ویرگول
ورودثبت نام
garmabi.mohammad73
garmabi.mohammad73Senior Software Engineer با تمرکز بر Frontend، React و TypeScript. علاقه‌مند به Software Architecture، System Design، Open Source و ساخت ابزارهای ساده و مقیاس‌پذیر.
garmabi.mohammad73
garmabi.mohammad73
خواندن ۹ دقیقه·۲ ماه پیش

tanstack-fetch؛ یک Fetch Client تایپ‌شده برای TanStack Query

وقتی با React و TanStack Query کار می‌کنیم، بخش زیادی از کدهای پروژه در نهایت به API request ختم می‌شوند.

چیزی شبیه این:

const { data } = useQuery({ queryKey: ['users'], queryFn: ({ signal }) => fetch('/api/users', { signal, }).then((res) => res.json()), })

در نگاه اول ساده است.

اما با بزرگ‌تر شدن پروژه، خیلی سریع به این مشکلات می‌رسیم:

  • مدیریت خطا

  • TypeScript

  • Authentication

  • Refresh Token

  • Retry

  • AbortSignal

  • SSR

  • SSE

  • Upload

  • Interceptors

  • Path Parameters

  • Error Handling

  • تفاوت رفتار GET و Mutation

  • و در نهایت یک مجموعه wrapper دور fetch

اینجاست که tanstack-fetch شکل گرفت.


tanstack-fetch چیست؟

tanstack-fetch یک typed Fetch client است که API آن با نحوه‌ی استفاده از TanStack Query هماهنگ شده است.

هدف پروژه این نیست که یک Axios دیگر بسازد.

ایده ساده‌تر است:

اگر TanStack Query یک لایه برای مدیریت server state است، tanstack-fetch باید یک لایه‌ی کوچک و قابل پیش‌بینی برای HTTP باشد.

مدل ذهنی پروژه بسیار ساده است:

TanStack Query │ ▼ tanstack-fetch │ ▼ fetch() │ ▼ API

چرا یک Fetch Client جدید؟

خود fetch عالی است.

اما API خام آن چند مشکل دارد.

مثلاً:

const response = await fetch('/users') if (!response.ok) { throw new Error('Request failed') } const data = await response.json()

تقریباً در هر پروژه‌ای دوباره همین کد را می‌نویسیم.

حالا Authentication را اضافه کنیم:

const response = await fetch('/users', { headers: { Authorization: `Bearer ${token}`, }, })

بعد:

401 ↓ refresh token ↓ retry

بعد:

429 ↓ Retry-After ↓ wait ↓ retry

بعد:

AbortSignal SSR SSE Upload Interceptors

در نهایت یک HTTP abstraction ساخته‌ایم؛ فقط بدون اینکه از ابتدا طراحی شده باشد.

tanstack-fetch تلاش می‌کند این لایه را کوچک، typed و قابل ترکیب نگه دارد.


فلسفه‌ی اصلی

tanstack-fetch روی چند اصل ساده ساخته شده است.

1. Data in, data out

در موفقیت، چیزی که می‌خواهیم معمولاً خود data است:

const user = await api.get<User>('/users/1')

نه:

const response = await api.get('/users/1') response.data

2. HTTP error باید واقعاً Error باشد

اگر API پاسخ 4xx یا 5xx بدهد، request نباید مثل یک موفقیت رفتار کند.

tanstack-fetch از FetchError استفاده می‌کند:

try { await api.get('/users') } catch (error) { if (error instanceof FetchError) { console.log(error.status) } }

در نتیجه error handling در TanStack Query هم طبیعی باقی می‌ماند.


3. AbortSignal از ابتدا first-class است

TanStack Query هنگام cancellation، signal در اختیار queryFn قرار می‌دهد:

useQuery({ queryKey: ['users'], queryFn: ({ signal }) => api.get('/users', { signal, }), })

tanstack-fetch این signal را به fetch منتقل می‌کند.

پس cancellation توسط Query و HTTP client با هم کار می‌کنند.


TypeScript First

یکی از مهم‌ترین اهداف tanstack-fetch این است که TypeScript فقط تزئینی نباشد.

مثلاً:

type User = { id: string name: string email: string } const user = await api.get<User>('/users/123')

حالا:

user.name user.email

کاملاً typed هستند.


Path Parameters

یکی از قابلیت‌های جالب نسخه‌های اخیر، typed path parameters است.

مثلاً:

api.get('/users/:id', { params: { id: userId, }, })

TypeScript از مسیر متوجه می‌شود که id لازم است.

برای مثال:

api.get('/users/:id', { params: {}, })

می‌تواند به عنوان استفاده‌ی نادرست شناسایی شود.

این قابلیت برای APIهای بزرگ که endpointهای زیادی دارند، جلوی بخشی از خطاهای runtime را می‌گیرد.


TanStack Query Integration

یکی از مهم‌ترین تفاوت‌های tanstack-fetch این است که API آن برای استفاده مستقیم در queryFn طراحی شده است.

const api = createFetch({ baseUrl: 'https://api.example.com', }) const usersQuery = useQuery({ queryKey: ['users'], queryFn: ({ signal }) => api.get<User[]>('/users', { signal, }), })

هیچ adapter خاصی لازم نیست.

نه:

response.data

و نه:

queryFn: async () => { const response = await axios.get(...) return response.data }

فقط:

api.get(...)

Authentication

Authentication یکی از قسمت‌هایی است که HTTP client باید بتواند آن را مدیریت کند.

مثلاً:

const api = createFetch({ baseUrl: API_URL, getToken: () => accessToken, })

درخواست‌ها می‌توانند به شکل متمرکز token دریافت کنند.

در نتیجه لازم نیست در هر request بنویسیم:

headers: { Authorization: `Bearer ${token}`, }

Refresh Token

در نسخه 1.3.0 قابلیت مهمی اضافه شده است:

createRefreshTokenInterceptor

این interceptor می‌تواند دو سناریو را مدیریت کند.

قبل از expiry

اگر token نزدیک expiration باشد:

Token │ ├───────────────┬───────────────┤ ↑ refresh threshold

قبل از request، token refresh می‌شود.


بعد از 401

اگر token هنوز از دید client معتبر باشد اما server پاسخ بدهد:

401 Unauthorized

interceptor می‌تواند:

401 ↓ refresh token ↓ retry original request

را انجام دهد.


Single-Flight Refresh

اما قسمت مهم‌تر اینجاست.

فرض کنید ۱۰ Query هم‌زمان 401 دریافت کنند.

پیاده‌سازی ساده ممکن است این کار را انجام دهد:

Request 1 → refresh Request 2 → refresh Request 3 → refresh Request 4 → refresh ... Request 10 → refresh

که اصلاً مطلوب نیست.

tanstack-fetch می‌تواند refresh را به صورت single-flight هماهنگ کند:

Request 1 ──┐ Request 2 ──┤ Request 3 ──┤ Request 4 ──┤ Request 5 ──┼──→ ONE refresh Request 6 ──┤ Request 7 ──┤ Request 8 ──┤ Request 9 ──┤ Request 10 ─┘ │ ▼ retry all

یعنی چند request منتظر همان refresh operation می‌مانند.

این موضوع برای applicationهای concurrent اهمیت زیادی دارد.


Interceptors

tanstack-fetch یک سیستم interceptor دارد که اجازه می‌دهد رفتار request را بدون آلوده کردن feature code تغییر دهیم.

به جای اینکه در تک‌تک Queryها بنویسیم:

if (response.status === 401) { ... }

می‌توانیم رفتار را در HTTP layer قرار دهیم.

ساختار ذهنی:

Request │ ▼ Interceptor │ ▼ fetch │ ▼ Response │ ▼ Interceptor │ ▼ Application

این separation برای پروژه‌های بزرگ‌تر بسیار مهم است.


HTTP Error Handling

در پروژه‌های واقعی همه‌ی errorها یکسان نیستند.

مثلاً:

401 → Authentication 403 → Authorization 404 → Resource not found 429 → Rate limiting 4xx → Client error 5xx → Server error

tanstack-fetch برای این سناریوها handlerهایی ارائه می‌کند.

مثلاً:

createFetch({ onUnauthorized: () => { // logout }, onTooManyRequests: (error) => { // handle rate limit }, onClientError: (error) => { // common 4xx handling }, })

این باعث می‌شود policy مربوط به HTTP در یک محل مشخص قرار بگیرد.


Rate Limiting

یکی دیگر از قابلیت‌ها، کار با Retry-After است.

وقتی server می‌گوید:

429 Too Many Requests Retry-After: 10

client می‌تواند بفهمد که چه مدت باید صبر کند.

وجود parseRetryAfter باعث می‌شود این رفتار در HTTP layer قابل مدیریت باشد.

این موضوع مخصوصاً برای APIهایی که rate limit دارند اهمیت دارد.


Retry

Retry باید با دقت انجام شود.

برای همه‌ی requestها retry کردن لزوماً درست نیست.

مثلاً retry کردن یک GET معمولاً با retry کردن یک mutation یکسان نیست.

HTTP client باید اطلاعات کافی را در اختیار application قرار دهد تا retry policy قابل کنترل باشد.

این موضوع در کنار TanStack Query اهمیت بیشتری پیدا می‌کند، چون خود Query نیز مکانیزم retry دارد.

بنابراین بهتر است مسئولیت‌ها مشخص باشند:

TanStack Query │ ├── Query retry ├── Cache ├── Refetch └── Server state │ ▼ tanstack-fetch │ ├── HTTP ├── Auth ├── Interceptors └── Transport errors

SSR Support

tanstack-fetch فقط برای browser طراحی نشده است.

در applicationهایی که SSR دارند، استفاده از abstractionی که بیش از حد به:

window localStorage document

وابسته باشد، مشکل‌ساز می‌شود.

به همین دلیل HTTP core پروژه تلاش می‌کند environment-agnostic باقی بماند.

این موضوع استفاده از آن را در معماری‌هایی مثل:

Next.js Remix Node.js Edge

ساده‌تر می‌کند.


SSE

SSE یا Server-Sent Events برای دریافت stream از server استفاده می‌شود.

مثلاً:

Server │ ├── event ├── event ├── event ├── event └── event ↓ Client

tanstack-fetch برای SSE نیز قابلیت‌های مربوط به streaming را ارائه می‌کند.

این موضوع برای:

  • live updates

  • notifications

  • dashboards

  • AI responses

  • realtime-ish applications

کاربرد دارد.


SSE Resume

در سیستم‌های streaming، قطع شدن connection مسئله‌ی مهمی است.

اگر client وسط stream disconnect شود، ideally نباید همیشه از ابتدا شروع کند.

پشتیبانی از resume در SSE می‌تواند کمک کند client از نقطه‌ی قبلی ادامه دهد.

این قابلیت مخصوصاً برای streamهای طولانی‌تر اهمیت دارد.


Upload

Upload نیز یکی از قابلیت‌های optional در ecosystem پروژه است.

در applicationهای واقعی ممکن است نیاز داشته باشیم:

JSON FormData File Blob Multipart

را ارسال کنیم.

داشتن API یکپارچه برای transport باعث می‌شود feature code کمتر درگیر جزئیات fetch شود.


tRPC

tanstack-fetch فقط محدود به REST نیست.

برای tRPC نیز entry point جداگانه در نظر گرفته شده است.

ایده این است که transport layer بتواند در معماری‌های مختلف استفاده شود، بدون اینکه HTTP core مجبور شود تمام قابلیت‌ها را به صورت monolithic داخل خودش قرار دهد.


React Helpers

در کنار HTTP core، helperهایی برای React نیز وجود دارند.

اما یک تصمیم معماری مهم این است که همه‌چیز در core قرار نگیرد.

به جای یک package بسیار بزرگ:

tanstack-fetch ├── React ├── SSE ├── Upload ├── SSR ├── tRPC └── ...

قابلیت‌ها تا حد امکان به صورت entry pointهای جداگانه در دسترس هستند.

این به کاهش حجم bundle و ساده‌تر شدن dependency graph کمک می‌کند.


حجم Core

یکی از اهداف پروژه کوچک نگه داشتن HTTP core است.

HTTP core تقریباً 3.5 KB gzip است.

یعنی اگر فقط یک Fetch client ساده می‌خواهید، مجبور نیستید تمام قابلیت‌های ecosystem را وارد bundle کنید.


API ساده

در ساده‌ترین حالت:

import { createFetch } from 'tanstack-fetch' const api = createFetch({ baseUrl: 'https://api.example.com', }) const users = await api.get<User[]>('/users')

POST:

const user = await api.post<User>('/users', { body: { name: 'Mohammad', email: '[email protected]', }, })

PUT:

await api.put('/users/123', { body: { name: 'Mohammad', }, })

DELETE:

await api.delete('/users/123')

و در تمام این موارد TypeScript می‌تواند type response را مدیریت کند.


AbortSignal

یکی از مهم‌ترین integrationها با TanStack Query:

useQuery({ queryKey: ['users'], queryFn: ({ signal }) => api.get('/users', { signal, }), })

وقتی Query عملیات را cancel کند، AbortSignal به request منتقل می‌شود.

یعنی:

TanStack Query │ │ AbortSignal ▼ tanstack-fetch │ ▼ fetch() │ ▼ API

این integration کوچک است، اما در applicationهای بزرگ تفاوت قابل توجهی ایجاد می‌کند.


چرا Axios نه؟

هدف tanstack-fetch این نیست که بگوید Axios بد است.

Axios یک HTTP client mature و بسیار پرکاربرد است.

اما اگر پروژه‌ای از:

React + TanStack Query + TypeScript + native Fetch

استفاده می‌کند، ممکن است یک abstraction سبک‌تر و نزدیک‌تر به Fetch مناسب‌تر باشد.

مقایسه‌ی mental model:

Axios Query ↓ Axios adapter ↓ Axios response ↓ response.data

در tanstack-fetch:

Query ↓ tanstack-fetch ↓ data

هر دو رویکرد معتبرند؛ مسئله این است که abstraction باید با architecture پروژه هماهنگ باشد.


چرا این پروژه برای TanStack Query ساخته شده؟

TanStack Query خودش HTTP client نیست.

وظیفه‌ی آن چیزهایی مثل:

  • caching

  • synchronization

  • invalidation

  • refetching

  • stale state

  • mutations

  • server state

است.

اما برای اجرای request باید یک queryFn داشته باشیم.

اینجا tanstack-fetch وارد می‌شود.

Application │ ▼ TanStack Query │ ▼ tanstack-fetch │ ▼ Fetch │ ▼ API

هر لایه یک مسئولیت مشخص دارد.


چه زمانی tanstack-fetch مناسب است؟

اگر پروژه‌ی شما این stack را دارد:

React TypeScript TanStack Query REST API Fetch

tanstack-fetch می‌تواند یک گزینه باشد.

خصوصاً اگر نیاز دارید:

  • API client typed داشته باشید

  • error handling متمرکز داشته باشید

  • Authentication را متمرکز کنید

  • Refresh Token داشته باشید

  • request cancellation داشته باشید

  • path parameters typed باشند

  • SSR داشته باشید

  • SSE استفاده کنید

  • interceptor داشته باشید

  • بدون Axios adapter با TanStack Query کار کنید


چه زمانی شاید به آن نیاز نداشته باشید؟

اگر پروژه فقط چند request ساده دارد:

fetch('/api/users') fetch('/api/posts')

احتمالاً خود fetch کافی است.

هدف tanstack-fetch اضافه کردن abstraction صرفاً برای abstraction نیست.

وقتی complexity ایجاد می‌شود، abstraction باید complexity را کم کند، نه اینکه خودش تبدیل به complexity جدید شود.


معماری کلی

اگر بخواهیم کل قابلیت‌ها را در یک تصویر ذهنی قرار دهیم:

Application │ ▼ TanStack Query │ ┌─────────┴─────────┐ │ │ ▼ ▼ Query / Mutation React │ ▼ tanstack-fetch │ ┌───────────┼───────────┐ │ │ │ ▼ ▼ ▼ Auth Interceptors Errors │ │ │ └───────────┼───────────┘ │ ┌─────────┼─────────┐ │ │ │ ▼ ▼ ▼ Fetch SSE Upload │ ▼ API

نصب

npm install tanstack-fetch

اگر از TanStack Query استفاده می‌کنید:

npm install tanstack-fetch @tanstack/react-query

یک مثال واقعی

یک application فرضی داریم:

React │ ├── Users ├── Orders ├── Dashboard └── Notifications │ ▼ TanStack Query │ ▼ tanstack-fetch │ ├── Authentication ├── Refresh Token ├── Error Handling ├── Retry └── SSE │ ▼ Backend

در featureهای مختلف دیگر لازم نیست این منطق تکرار شود.

مثلاً:

export const getUsers = (signal?: AbortSignal) => api.get<User[]>('/users', { signal, })

و:

export const getOrders = (signal?: AbortSignal) => api.get<Order[]>('/orders', { signal, })

سپس:

useQuery({ queryKey: ['users'], queryFn: ({ signal }) => getUsers(signal), })

کد feature ساده باقی می‌ماند.


نسخه 1.3.0

در نسخه 1.3.0 تمرکز اصلی روی authentication و refresh token بوده است.

مهم‌ترین قابلیت:

createRefreshTokenInterceptor()

با دو مسیر:

BEFORE Token نزدیک expiry ↓ refresh ↓ request

و:

AFTER 401 ↓ refresh ↓ retry

به همراه:

Single-flight

یعنی چند request هم‌زمان باعث چند refresh request نمی‌شوند.


مسیر پروژه

tanstack-fetch یک پروژه‌ی Open Source است و هدفش این است که یک abstraction کوچک و composable برای Fetch و TanStack Query ارائه کند.

چند اصل پروژه برای من مهم هستند:

Simple over clever.

Typed over implicit.

Composable over monolithic.

و مهم‌تر از همه:

یک abstraction خوب باید پیچیدگی را از application بگیرد، نه اینکه پیچیدگی جدیدی به آن اضافه کند.


نتیجه

fetch به تنهایی ابزار قدرتمندی است.

TanStack Query هم مدیریت server state را بسیار خوب انجام می‌دهد.

اما بین این دو یک فضای کوچک وجود دارد:

Query ↓ HTTP

tanstack-fetch تلاش می‌کند این فاصله را پر کند.

نه با یک framework بزرگ.

نه با یک abstraction پیچیده.

بلکه با یک Fetch client typed و قابل ترکیب که برای سناریوهای واقعی مثل:

  • Authentication

  • Refresh Token

  • Single-flight

  • Interceptors

  • HTTP Errors

  • Retry

  • Rate Limiting

  • AbortSignal

  • SSR

  • SSE

  • Upload

  • Typed Path Parameters

ساخته شده است.

اگر از TanStack Query استفاده می‌کنید، می‌توانید tanstack-fetch را امتحان کنید و ببینید آیا این مدل برای architecture پروژه‌ی شما مناسب است یا نه.

Links

  • npm

  • Documentation

  • GitHub

  • Refresh Token Recipe

  • Changelog


tanstack-fetch — Typed Fetch for TanStack Query.

reactfetchaxios
۱
۰
garmabi.mohammad73
garmabi.mohammad73
Senior Software Engineer با تمرکز بر Frontend، React و TypeScript. علاقه‌مند به Software Architecture، System Design، Open Source و ساخت ابزارهای ساده و مقیاس‌پذیر.
شاید از این پست‌ها خوشتان بیاید