وقتی با 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 یک typed Fetch client است که API آن با نحوهی استفاده از TanStack Query هماهنگ شده است.
هدف پروژه این نیست که یک Axios دیگر بسازد.
ایده سادهتر است:
اگر TanStack Query یک لایه برای مدیریت server state است، tanstack-fetch باید یک لایهی کوچک و قابل پیشبینی برای HTTP باشد.
مدل ذهنی پروژه بسیار ساده است:
TanStack Query │ ▼ tanstack-fetch │ ▼ fetch() │ ▼ API
خود 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 روی چند اصل ساده ساخته شده است.
در موفقیت، چیزی که میخواهیم معمولاً خود data است:
const user = await api.get<User>('/users/1')
نه:
const response = await api.get('/users/1') response.data
اگر 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 هم طبیعی باقی میماند.
TanStack Query هنگام cancellation، signal در اختیار queryFn قرار میدهد:
useQuery({ queryKey: ['users'], queryFn: ({ signal }) => api.get('/users', { signal, }), })
tanstack-fetch این signal را به fetch منتقل میکند.
پس cancellation توسط Query و HTTP client با هم کار میکنند.
یکی از مهمترین اهداف tanstack-fetch این است که TypeScript فقط تزئینی نباشد.
مثلاً:
type User = { id: string name: string email: string } const user = await api.get<User>('/users/123')
حالا:
user.name user.email
کاملاً typed هستند.
یکی از قابلیتهای جالب نسخههای اخیر، typed path parameters است.
مثلاً:
api.get('/users/:id', { params: { id: userId, }, })
TypeScript از مسیر متوجه میشود که id لازم است.
برای مثال:
api.get('/users/:id', { params: {}, })
میتواند به عنوان استفادهی نادرست شناسایی شود.
این قابلیت برای APIهای بزرگ که endpointهای زیادی دارند، جلوی بخشی از خطاهای runtime را میگیرد.
یکی از مهمترین تفاوتهای 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 یکی از قسمتهایی است که HTTP client باید بتواند آن را مدیریت کند.
مثلاً:
const api = createFetch({ baseUrl: API_URL, getToken: () => accessToken, })
درخواستها میتوانند به شکل متمرکز token دریافت کنند.
در نتیجه لازم نیست در هر request بنویسیم:
headers: { Authorization: `Bearer ${token}`, }
در نسخه 1.3.0 قابلیت مهمی اضافه شده است:
createRefreshTokenInterceptor
این interceptor میتواند دو سناریو را مدیریت کند.
اگر token نزدیک expiration باشد:
Token │ ├───────────────┬───────────────┤ ↑ refresh threshold
قبل از request، token refresh میشود.
اگر token هنوز از دید client معتبر باشد اما server پاسخ بدهد:
401 Unauthorized
interceptor میتواند:
401 ↓ refresh token ↓ retry original request
را انجام دهد.
اما قسمت مهمتر اینجاست.
فرض کنید ۱۰ 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 اهمیت زیادی دارد.
tanstack-fetch یک سیستم interceptor دارد که اجازه میدهد رفتار request را بدون آلوده کردن feature code تغییر دهیم.
به جای اینکه در تکتک Queryها بنویسیم:
if (response.status === 401) { ... }
میتوانیم رفتار را در HTTP layer قرار دهیم.
ساختار ذهنی:
Request │ ▼ Interceptor │ ▼ fetch │ ▼ Response │ ▼ Interceptor │ ▼ Application
این separation برای پروژههای بزرگتر بسیار مهم است.
در پروژههای واقعی همهی 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 در یک محل مشخص قرار بگیرد.
یکی دیگر از قابلیتها، کار با Retry-After است.
وقتی server میگوید:
429 Too Many Requests Retry-After: 10
client میتواند بفهمد که چه مدت باید صبر کند.
وجود parseRetryAfter باعث میشود این رفتار در HTTP layer قابل مدیریت باشد.
این موضوع مخصوصاً برای APIهایی که rate limit دارند اهمیت دارد.
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
tanstack-fetch فقط برای browser طراحی نشده است.
در applicationهایی که SSR دارند، استفاده از abstractionی که بیش از حد به:
window localStorage document
وابسته باشد، مشکلساز میشود.
به همین دلیل HTTP core پروژه تلاش میکند environment-agnostic باقی بماند.
این موضوع استفاده از آن را در معماریهایی مثل:
Next.js Remix Node.js Edge
سادهتر میکند.
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
کاربرد دارد.
در سیستمهای streaming، قطع شدن connection مسئلهی مهمی است.
اگر client وسط stream disconnect شود، ideally نباید همیشه از ابتدا شروع کند.
پشتیبانی از resume در SSE میتواند کمک کند client از نقطهی قبلی ادامه دهد.
این قابلیت مخصوصاً برای streamهای طولانیتر اهمیت دارد.
Upload نیز یکی از قابلیتهای optional در ecosystem پروژه است.
در applicationهای واقعی ممکن است نیاز داشته باشیم:
JSON FormData File Blob Multipart
را ارسال کنیم.
داشتن API یکپارچه برای transport باعث میشود feature code کمتر درگیر جزئیات fetch شود.
tanstack-fetch فقط محدود به REST نیست.
برای tRPC نیز entry point جداگانه در نظر گرفته شده است.
ایده این است که transport layer بتواند در معماریهای مختلف استفاده شود، بدون اینکه HTTP core مجبور شود تمام قابلیتها را به صورت monolithic داخل خودش قرار دهد.
در کنار HTTP core، helperهایی برای React نیز وجود دارند.
اما یک تصمیم معماری مهم این است که همهچیز در core قرار نگیرد.
به جای یک package بسیار بزرگ:
tanstack-fetch ├── React ├── SSE ├── Upload ├── SSR ├── tRPC └── ...
قابلیتها تا حد امکان به صورت entry pointهای جداگانه در دسترس هستند.
این به کاهش حجم bundle و سادهتر شدن dependency graph کمک میکند.
یکی از اهداف پروژه کوچک نگه داشتن HTTP core است.
HTTP core تقریباً 3.5 KB gzip است.
یعنی اگر فقط یک Fetch client ساده میخواهید، مجبور نیستید تمام قابلیتهای ecosystem را وارد bundle کنید.
در سادهترین حالت:
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 را مدیریت کند.
یکی از مهمترین 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های بزرگ تفاوت قابل توجهی ایجاد میکند.
هدف 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 خودش HTTP client نیست.
وظیفهی آن چیزهایی مثل:
caching
synchronization
invalidation
refetching
stale state
mutations
server state
است.
اما برای اجرای request باید یک queryFn داشته باشیم.
اینجا tanstack-fetch وارد میشود.
Application │ ▼ TanStack Query │ ▼ tanstack-fetch │ ▼ Fetch │ ▼ API
هر لایه یک مسئولیت مشخص دارد.
اگر پروژهی شما این 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 تمرکز اصلی روی 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 پروژهی شما مناسب است یا نه.
tanstack-fetch — Typed Fetch for TanStack Query.