نوشته های garmabi.mohammad73

انتشار tanstack-fetch 2.1.0؛ لغو واقعی در retry، رفرش توکن امن‌تر و پارامترهای آرایه‌ای

garmabi.mohammad73 — Sat, 07 Nov 2026 12:50:32 +0330

نسخه اصلی این مطلب (انگلیسی): mohamadgarmabi.github.io/tanstack-fetch/blog/tanstack-fetch-2-1-0نسخه 2.1.0 کتابخانه tanstack-fetch یک نسخه با محوریت رفع باگ است و هیچ تغییر ناسازگاری (breaking change) ندارد. با ارتقا این‌ها را می‌گیرید:لغو یعنی لغو: اگر درخواست در حین تأخیرِ بین تلاش‌ها (retry delay) لغو شود، بلافاصله reject می‌شود.دونقطه در مسیر: مسیری مثل /models/gemini:generateContent دیگر پارامتری به اسم generateContent نمی‌خواهد.فقط یک رفرش برای هر چرخش توکن: یک 401 دیررس دیگر رفرش دوم را شروع نمی‌کند.مقادیر آرایه‌ای در query، گزینه‌های parseAs: 'arrayBuffer' | 'stream' و entry جدید tanstack-fetch/full.ارتقاnpm install tanstack-fetch@2.1.0باگ‌های رفع‌شدهلغو درخواست در حین تأخیر retryوقتی سرور Retry-After: 5 برمی‌گرداند (یا هر backoff دیگری)، درخواست HTTP حتی بعد از abort شدن signal کل زمان تأخیر را صبر می‌کرد. TanStack Query موقع unmount و تغییر queryKey درخواست را abort می‌کند، پس query چند ثانیه در حالت pending می‌ماند. حالا تأخیر به signal گوش می‌دهد و بلافاصله با AbortError رد می‌شود و تلاش بعدی هم ارسال نمی‌شود.useQuery({ queryKey: ['report', id], // unmount during a 5s Retry-After → rejects now, no second fetch queryFn: ({ signal }) => api.get('/reports/:id', { params: { id }, signal }), })دونقطه داخل یک بخش از مسیرحالا :name فقط وقتی در ابتدای یک بخش از مسیر بیاید پارامتر مسیر حساب می‌شود؛ هم در زمان اجرا و هم در تایپ‌ها:await api.post('/v1/models/gemini:generateContent', { body }) // literal path, no params await api.get('/users/:id', { params: { id: 1 } }) // → /users/1قبلاً فراخوانی اول با خطای missing path param "generateContent" شکست می‌خورد و TypeScript هم همین پارامتر را می‌خواست.رفرش توکن: بدون رفرش دوم برای 401 دیررسinterceptor از قبل یک رفرش در جریان را بین چند 401 موازی به اشتراک می‌گذاشت. اما درخواستی که با توکن قدیمی ارسال شده بود و 401اش بعد از تمام شدن رفرش می‌رسید، یک رفرش جدید شروع می‌کرد. با refresh tokenهای چرخشی (rotating)، این فراخوانی دوم می‌تواند نشستی را که اولی تازه ساخته باطل کند.حالا interceptor می‌داند هر درخواست بعد از کدام رفرش ارسال شده است. یک 401 دیررس فقط درخواست را با توکن جدید دوباره می‌فرستد:A ──(old token)──────────────────────► 401 → retry with new token ✓ B ──(old token)──► 401 → refresh() ✓ → retry ✓ refresh() called onceحالت برعکس هم درست شده است. درخواستی که به دلیل دیگری retry شده بود (مثلاً یک 502 از طریق retry-idempotent) و بعد 401 می‌گرفت، رفرش را رد می‌کرد، چون شرط بررسی attempt > 0 بود. حالا هر درخواست حداکثر یک بار رفرش می‌کند و این به ازای هر فراخوانی ردیابی می‌شود، پس چرخه 401 → refresh → 401 همچنان نمی‌تواند حلقه بسازد.این قابلیت با یک context.meta.state جدید کار می‌کند؛ یک object ساده که بین همه تلاش‌های یک درخواست مشترک است. interceptorهای خودتان هم می‌توانند از آن برای flagهای مخصوص هر فراخوانی استفاده کنند.بدنه‌های stream دیگر retry نمی‌شوندبدنه از نوع ReadableStream در تلاش اول مصرف می‌شود، بنابراین retry قبلاً با یک TypeError گیج‌کننده درباره «locked stream» شکست می‌خورد. حالا درخواست‌هایی که بدنه stream دارند، به جای retry، خطای واقعی (مثلاً FetchError با وضعیت 503) را برمی‌گردانند.قابلیت‌های جدیدمقادیر آرایه‌ای در queryawait api.get('/users', { query: { ids: [1, 2], role: 'admin' } }) // → /users?ids=1&ids=2&role=adminQueryParams حالا آرایه‌ای از string | number | boolean را می‌پذیرد و هر آیتم به صورت یک key=value جدا اضافه می‌شود. مقادیر null و undefined همچنان نادیده گرفته می‌شوند.گزینه parseAs: 'arrayBuffer' | 'stream'const bytes = await api.get('/files/:id', { params: { id }, parseAs: 'arrayBuffer' }) const body = await api.get>('/export', { parseAs: 'stream' })حالت 'stream' خودِ response.body را بدون خواندن برمی‌گرداند.entry جدید tanstack-fetch/fullکلاینت کامل HTTP (میان‌برهای option، تابع upload() و رویدادهای progress) قبلاً فقط زیر tanstack-fetch/sse بود که اگر از SSE استفاده نمی‌کنید عجیب به نظر می‌رسد. tanstack-fetch/full همان build با یک اسم واضح‌تر است و /sse هم مثل قبل کار می‌کند.import { createFetch } from 'tanstack-fetch/full'تایپ‌های درست برای CommonJSحالا require('tanstack-fetch') به جای .d.ts نسخه ESM، به declarationهای .d.cts resolve می‌شود؛ بنابراین پروژه‌های TypeScript که با module: node16 یا nodenext و CJS کار می‌کنند تایپ‌های درست را می‌گیرند. CI هم حالا همه entryها را با publint و @arethetypeswrong/cli بررسی می‌کند و تست‌ها را روی Node 20، 22 و 24 اجرا می‌کند.حجم باندل (gzip)tanstack-fetch: از 3.57KB به 3.68KBtanstack-fetch/sse: از 6.33KB به 6.43KBtanstack-fetch/live: از 8.75KB به 8.84KBtanstack-fetch/plugins: از 1.13KB به 1.22KBیعنی حدود ۱۰۰ بایت برای همه این اصلاحات.نکتهtimeoutها و abortها با TimeoutError / AbortError خودِ پلتفرم reject می‌شوند، نه با FetchError. این همیشه همین‌طور بوده و حالا در README هم ذکر شده است. برای بررسی‌شان از isAbortError(error) استفاده کنید. (مستندات Errors)بیشتر بخوانید: آموزش refresh token · گزینه‌های درخواست · Changelog · مخزن GitHub

انتشار tanstack-fetch 2.0.0؛ هسته‌ای سبک‌تر، پشتیبانی از WebSocket و WebTransport و استریم Type-safe

garmabi.mohammad73 — Sat, 31 Oct 2026 12:00:06 +0330

از یک HTTP Client سبک تا یک لایه ارتباطی یکپارچه برای اپلیکیشن‌های مدرن TypeScriptنسخه 2.0.0 کتابخانه tanstack-fetch منتشر شد.این نسخه صرفاً یک آپدیت معمولی نیست؛ در فاصله نسخه 1.7.1 تا 2.0.0، معماری کتابخانه تغییرات مهمی داشته و قابلیت‌های جدیدی برای ارتباطات Real-time و Streaming به آن اضافه شده است.مهم‌ترین تغییرات این نسخه عبارت‌اند از:کاهش حجم Core از 5.14KB به 3.57KB فشرده‌شده با gzipاضافه شدن WebSocketاضافه شدن WebTransportپشتیبانی از NDJSON Streamingیکپارچه‌سازی معماری HTTP و Live Transportبهبود DevTools برای بررسی ارتباطات زندهپشتیبانی کامل‌تر از Type-safe Params در APIهای زندهانتقال Authentication و Status Handling به Interceptorهادر این مقاله تغییرات نسخه‌های 1.8.0 و 2.0.0 را بررسی می‌کنیم.۱. پشتیبانی از WebSocketیکی از مهم‌ترین قابلیت‌های نسخه 1.8.0 اضافه شدن متد api.ws() است.در بسیاری از اپلیکیشن‌ها، HTTP به‌تنهایی کافی نیست. برای ساخت چت، داشبوردهای زنده، ابزارهای همکاری و سیستم‌های Real-time به ارتباط دوطرفه و پایدار نیاز داریم.حالا می‌توانیم از همان معماری کلاینت برای WebSocket استفاده کنیم:const socket = api.ws< Message, { roomId: string }, SendMessage >('/rooms/:roomId', { params: { roomId: 'general' }, }) socket.onMessage((message) => { console.log(message) }) socket.send({ text: 'Hello!', })قابلیت‌های مهم:اتصال مجدد خودکار با Exponential Backoffدریافت توکن جدید هنگام Reconnectصف ارسال پیام تا زمان برقراری اتصالپشتیبانی از AbortSignalپردازش پیام‌های JSONمدیریت Lifecycle اتصالهمچنین نحوه ارسال اطلاعات احراز هویت با توجه به محدودیت‌های محیط اجرا طراحی شده است؛ در مرورگر، توکن به‌صورت پیش‌فرض داخل URL قرار نمی‌گیرد.۲. پشتیبانی از WebTransportدر کنار WebSocket، قابلیت WebTransport نیز اضافه شده است.WebTransport مبتنی بر HTTP/3 است و امکان استفاده از Datagram و سایر الگوهای ارتباطی را فراهم می‌کند.const connection = api.transport('/live', { // WebTransport options })این قابلیت از تنظیماتی مانند serverCertificateHashes و پیاده‌سازی سفارشی از طریق createWebTransport پشتیبانی می‌کند.۳. پشتیبانی از NDJSON Streamingقابلیت مهم دیگر api.stream() است.در پاسخ‌های JSON معمولی، معمولاً باید منتظر دریافت کل پاسخ بمانیم؛ اما با NDJSON سرور می‌تواند داده‌ها را به‌صورت تدریجی ارسال کند.const stream = api.stream('/events', { method: 'POST', body: { prompt: 'Hello', }, }) for await (const message of stream) { console.log(message) }این قابلیت شامل موارد زیر است:پشتیبانی از متدهای مختلف HTTPپشتیبانی از Request Bodyاستفاده از Interceptorهای مشترکRetry و مدیریت خطاRefresh Tokenلغو درخواست با AbortSignalسازگاری با streamedQuery در TanStack Query۴. معماری یکپارچه برای ارتباطات زندهدر نسخه 1.8.0 یک Entry Point جدید معرفی شد:import { createFetch } from 'tanstack-fetch/live'این ماژول شامل متدهای زیر است:api.sse()api.ws()api.transport()api.stream()به این ترتیب، برای استفاده از HTTP، SSE، WebSocket و NDJSON نیازی به پیاده‌سازی چند معماری کاملاً جداگانه نداریم.همچنین Hookهای جدیدی برای Interceptorها اضافه شده‌اند:onLiveOpenonLiveMessageonLiveCloseاین Hookها امکان مشاهده وضعیت اتصال و پیام‌های ورودی و خروجی را فراهم می‌کنند.۵. بهبود DevToolsدر نسخه 1.8.0 دو تب جدید به DevTools اضافه شده است:WS برای WebSocket و WebTransportStream برای NDJSONهمچنین برای هر Connection یک Message Log در نظر گرفته شده تا بررسی و Debug کردن ارتباطات زنده ساده‌تر شود.CLI نیز بهبود پیدا کرده است و دستور doctor می‌تواند استفاده مستقیم از new WebSocket و new EventSource را شناسایی کند.۶. کاهش حجم Core در نسخه 2.0.0یکی از مهم‌ترین تغییرات معماری نسخه 2.0.0 کاهش حجم Core است.5.14KB → 3.57KB gzipیعنی تقریباً ۳۰ درصد کاهش حجم.در این نسخه، Core فقط روی مسئولیت‌های اصلی HTTP متمرکز شده است:مدیریت Base URLHeadersTimeoutInterceptorsFetch implementationCredentialsRetry configurationقابلیت‌هایی مانند Authentication و Status Handling از Core خارج شده‌اند و از طریق Interceptorهای مستقل استفاده می‌شوند.برای مثال:import { createFetch } from 'tanstack-fetch' import { createAuthInterceptor, createStatusInterceptor, } from 'tanstack-fetch/plugins' const api = createFetch({ baseUrl: '/api', interceptors: [ createAuthInterceptor({ getToken, }), createStatusInterceptor({ 401: handleUnauthorized, '5xx': handleServerError, }), ], })این تغییر باعث می‌شود قابلیت‌های اختیاری به‌جای قرار گرفتن در هسته اصلی، به‌صورت مستقل و ترکیب‌پذیر استفاده شوند.نکته مهم: این تغییر به معنای حذف کامل قابلیت Upload نیست. ماژول‌های tanstack-fetch/sse، /live، /trpc و Framework Providerها همچنان قابلیت‌های قبلی خود را حفظ کرده‌اند.۷. Type-safe Params برای APIهای Liveدر نسخه 2.0.0، تایپ پارامترهای مسیر به APIهای زنده نیز گسترش پیدا کرده است.پیش از این، HTTP از قابلیت Type-safe Params برخوردار بود، اما APIهای Live از همین سطح استنتاج تایپ پشتیبانی نمی‌کردند.حالا می‌توانیم بنویسیم:const socket = api.ws< Message, { roomId: number } >( '/rooms/:roomId', { params: { roomId: 42, }, }, )این قابلیت در موارد زیر در دسترس است:api.sse()api.ws()api.transport()api.stream()useSse()useWs()همچنین برای React، Vue، Solid، Svelte و Angular در نظر گرفته شده است.ترتیب Genericها نیز یکپارچه‌تر شده است:// WebSocket // SSE / NDJSON ۸. اصلاحات مهم در Streamingدر نسخه 2.0.0 چند مشکل مهم در چرخه اجرای NDJSON نیز برطرف شده است:ارسال صحیح ReadableStream در Node.js با duplex: 'half'اجرای onRequestError هنگام خطاهای شبکهلغو فوری Stream هنگام Abort شدن در زمان Retry Delay۹. مهاجرت از نسخه 1.7.1 به 2.0.0برای ارتقا:npm install tanstack-fetch@2.0.0چند نکته مهم در Migration وجود دارد:۱. تنظیمات getToken و Status Handlerها را به Interceptor منتقل کنید.۲. اگر از upload() در Core استفاده می‌کردید، Entry Point مربوط به tanstack-fetch/sse را بررسی کنید.۳. ترتیب Genericهای WebSocket را به ساختار جدید تغییر دهید.۴. اگر از api.stream() استفاده می‌کنید، حتماً مدیریت AbortSignal و Retry را بررسی کنید.جمع‌بندیهدف tanstack-fetch ساخت یک Axios دیگر نیست.ایده اصلی این پروژه فراهم کردن یک لایه ارتباطی سبک، Type-safe و قابل ترکیب است که در کنار TanStack Query به‌خوبی کار کند.HTTP، SSE، WebSocket، WebTransport و NDJSON روش‌های مختلفی برای ارتباط با سرور هستند؛ اما نباید برای هرکدام مجبور باشیم معماری مستقلی برای Authentication، مدیریت خطا، Retry و Observability بسازیم.در نسخه 2.0.0، Core کوچک‌تر شده، معماری ماژولارتر شده و پشتیبانی از ارتباطات زنده توسعه پیدا کرده است.نصب:npm install tanstack-fetchلینک‌های پروژه:مستندات: https://mohamadgarmabi.github.io/tanstack-fetch/GitHub: https://github.com/mohamadgarmabi/tanstack-fetchnpm: https://www.npmjs.com/package/tanstack-fetchRelease Notes: https://mohamadgarmabi.github.io/tanstack-fetch/blog/tanstack-fetch-2-0-0این پروژه یک کتابخانه مستقل و Open Source است و محصول رسمی TanStack نیست.خوشحال می‌شوم تجربه و نظرتان را درباره معماری جدید و قابلیت‌های نسخه 2.0.0 بدانم.

چطور در React درخواستهای API را کنترل کنیم؟ آموزش TanStack Pacer در کنار TanStack Query

garmabi.mohammad73 — Wed, 28 Oct 2026 10:55:29 +0330

اگر اپلیکیشن React شما درخواستهای API زیادی ارسال میکند، همیشه مشکل از HTTP Client نیست. گاهی مشکل اصلی این است که درخواستها چه زمانی و با چه فاصلهای اجرا میشوند.چند مثال آشنا:با هر بار تایپ کاربر در Search یک درخواست ارسال میشود.هنگام ویرایش متن، چند درخواست Autosave همزمان اجرا میشوند.هنگام اسکرول، محاسبات و بررسیهای تکراری انجام میشوند.با انتخاب تعداد زیادی فایل، همه آپلودها همزمان شروع میشوند.هر رویداد Analytics یک درخواست مستقل ایجاد میکند.در این مقاله، شش الگوی کاربردی را با استفاده از سه کتابخانه بررسی میکنیم:TanStack Pacer: کنترل زمان اجرا و تعداد دفعات اجرای عملیاتTanStack Query: مدیریت Server State، کش و چرخه عمر درخواستهاtanstack-fetch: مدیریت درخواستهای HTTP و خطاهای تایپشدهمن Mohammad Garmabi، سازنده کتابخانه tanstack-fetch هستم. این کتابخانه یک پروژه مستقل جامعه توسعهدهندگان است و پروژه رسمی تیم TanStack نیست.۱. نصب کتابخانهها و ساخت HTTP Clientابتدا پکیجهای موردنیاز را نصب میکنیم:npm install @tanstack/react-pacer @tanstack/react-query tanstack-fetchسپس یک Client مشترک میسازیم:// src/lib/api.ts import { createFetch } from 'tanstack-fetch' export const api = createFetch({ baseUrl: import.meta.env.VITE_API_URL, timeoutMs: 10_000, })در این معماری، هر کتابخانه مسئولیت مشخصی دارد. Pacer زمان اجرای عملیات را کنترل میکند، Query مسئول کش و وضعیت دادههاست و tanstack-fetch ارتباط HTTP را مدیریت میکند.نمونههای این مقاله بر اساس API نسخههای موردنظر نوشته شدهاند. پیش از استفاده در پروژه واقعی، امضای متدها را با نسخه نصبشده و مستندات فعلی بررسی کنید.۲. پیادهسازی Search با Debounceفرض کنید کاربر عبارت tanstack را جستوجو میکند. اگر با هر کاراکتر یک درخواست بفرستیم، تعداد زیادی درخواست غیرضروری ایجاد میشود.با Debounce میتوانیم صبر کنیم تا کاربر برای مدت کوتاهی تایپ را متوقف کند.import { useState } from 'react' import { useDebouncedValue } from '@tanstack/react-pacer' import { keepPreviousData, useQuery } from '@tanstack/react-query' import { api } from '~/lib/api' type User = { id: number name: string email: string } export function SearchUsers() { const [search, setSearch] = useState('') const [debouncedSearch] = useDebouncedValue(search, { wait: 300, }) const query = useQuery({ queryKey: ['users', 'search', debouncedSearch], queryFn: ({ signal }) => api.get('/users', { query: { q: debouncedSearch }, signal, }), enabled: debouncedSearch.trim().length >= 2, placeholderData: keepPreviousData, staleTime: 30_000, }) return ( <> setSearch(event.target.value)} placeholder="جستوجوی کاربران" /> {query.isFetching && در حال جستوجو...} {query.data?.map((user) => (

{user.name}

))} ) }چند نکته مهم در این پیادهسازی وجود دارد:مقدار Input بلافاصله تغییر میکند و تایپ کاربر کند نمیشود.فقط مقدار debouncedSearch وارد queryKey میشود.هر عبارت جستوجو میتواند کش مستقل خودش را داشته باشد.با keepPreviousData، نتایج قبلی هنگام بارگذاری نتایج جدید باقی میمانند.با مصرف signal در queryFn، درخواستهای قبلی امکان لغو شدن دارند.نکته: بهتر است خود queryFn را با یک تابع Debounce معمولی Wrap نکنید. مقدار ورودی به queryKey را Debounce کنید تا قرارداد Promise مورد انتظار TanStack Query حفظ شود.۳. Autosave با قابلیت لغو درخواستدر قابلیت Autosave، هدف این است که بعد از توقف تایپ، آخرین نسخه متن ذخیره شود. اما فقط تأخیر انداختن درخواست کافی نیست؛ باید به درخواستهایی که قبلاً شروع شدهاند هم توجه کنیم.یک جریان مناسب شامل این مراحل است:۱. بعد از توقف تایپ، عملیات ذخیره اجرا شود.۲. درخواست PATCH همراه با AbortSignal ارسال شود.۳. در صورت کنار گذاشتن تغییرات، عملیات در انتظار لغو شود و درخواست در حال اجرا نیز در صورت امکان Abort شود.۴. پس از دریافت پاسخ موفق، کش TanStack Query بهروز شود.برای مدیریت زمانبندی عملیات غیرهمزمان میتوان از useAsyncDebouncer در TanStack Pacer استفاده کرد و AbortSignal را به درخواست tanstack-fetch داد.با این حال، یک نکته مهم را نباید فراموش کنیم: لغو درخواست در مرورگر لزوماً به معنی لغو پردازش آن در سرور نیست. اگر صحت داده اهمیت زیادی دارد، بهتر است از مکانیزمهایی مانند Version Check یا Optimistic Concurrency در سمت سرور هم استفاده کنیم.۴. کنترل Infinite Scroll با Throttleرویدادهای Scroll میتوانند در هر ثانیه چندین بار اجرا شوند. اگر در هر رویداد موقعیت اسکرول را بررسی کنیم، محاسبات تکراری خواهیم داشت.با Throttle میتوانیم تعداد دفعات اجرای Callback را محدود کنیم:const = useThrottledCallback( (element: HTMLElement) => { const nearBottom = element.scrollTop + element.clientHeight > element.scrollHeight - 600 if (nearBottom && hasNextPage && !isFetchingNextPage) { void fetchNextPage() } }, { wait: 200 }, )در این مثال، تابع در هر بازه زمانی حداکثر با محدودیت تعریفشده اجرا میشود. TanStack Query همچنان مسئول مدیریت صفحهها و وضعیت درخواست است.برای بعضی رابطهای کاربری، استفاده از IntersectionObserver و یک عنصر مشخص در انتهای لیست نیز انتخاب مناسبی است.۵. Rate Limiting برای جلوگیری از درخواستهای بیشازحدفرض کنید یک API موقعیتیابی، حداکثر پنج درخواست در ثانیه را مجاز میداند. میتوانیم پیش از ارسال درخواست، تعداد عملیات را در سمت کلاینت کنترل کنیم.const limiter = useAsyncRateLimiter( (address: string) => api.get('/geocode', { query: { address }, }), { limit: 5, window: 1_000, windowType: 'sliding', onReject: (_args, rateLimiter) => { const seconds = Math.ceil( rateLimiter.getMsUntilNextWindow() / 1000, ) toast(`لطفاً ${seconds} ثانیه دیگر تلاش کنید`) }, }, )این روش به کاهش درخواستهای غیرضروری و ارائه بازخورد سریع به کاربر کمک میکند.اما Rate Limiting سمت کلاینت، محدودیت امنیتی یا سراسری نیست. کاربر میتواند از تب یا دستگاه دیگری درخواست بفرستد. بنابراین سرور باید محدودیت واقعی را اعمال کند.برای پاسخ HTTP با کد 429 Too Many Requests نیز میتوان سیاست Retry را در لایه Transport تعریف کرد و در صورت پشتیبانی نسخه نصبشده، مقدار Retry-After را در نظر گرفت.۶. مدیریت آپلودهای همزمان با Queueفرض کنید کاربر ۲۰۰ تصویر را برای آپلود انتخاب کرده است. شروع همزمان تمام درخواستها میتواند فشار زیادی به مرورگر، شبکه و سرور وارد کند.با Queue میتوان تعداد درخواستهای فعال را محدود کرد:const queue = useAsyncQueuer( (job: UploadJob) => api.upload('/photos', { file: job.file, fields: { albumId: job.albumId }, }), { concurrency: 3, wait: 100, onSuccess: (_photo, job) => queryClient.invalidateQueries({ queryKey: ['albums', job.albumId, 'photos'], }), : (error, job) => console.error(`Upload failed: ${job.file.name}`, error), }, )در این مثال، حداکثر سه آپلود بهصورت همزمان فعال هستند و سایر فایلها در صف باقی میمانند.این ساختار میتواند پایهای برای امکانات زیر باشد:نمایش درصد پیشرفت آپلودهاتوقف و ادامه صفاولویتبندی فایلهامدیریت خطای هر فایل بهصورت مستقلبه محدود کردن حجم کار همزمان، Backpressure گفته میشود؛ یعنی بهجای شروع تمام عملیات، نرخ ورود کار به سیستم را کنترل میکنیم.۷. Batch کردن رویدادهای Analyticsفرض کنید در یک صفحه تعداد زیادی رویداد ثبت میشود. ارسال یک درخواست HTTP برای هر رویداد، سربار غیرضروری ایجاد میکند.با Batcher میتوان چند رویداد را در یک درخواست ارسال کرد:const batcher = useAsyncBatcher( (events: TrackEvent[]) => api.post('/events', { body: { events } }), { maxSize: 20, wait: 2_000, : (error, batch) => console.warn(`Batch of ${batch.length} events failed`, error), }, ) batcher.addItem({ name: 'button_clicked', at: Date.now(), props: { page: '/dashboard' }, })در این مثال، رویدادها با رسیدن به سقف تعیینشده یا بر اساس زمانبندی Batcher ارسال میشوند.برای استفاده در محیط Production باید درباره Retry، جلوگیری از ثبت تکراری رویدادها و ارسال رویدادهای باقیمانده هنگام مخفی شدن صفحه نیز تصمیم بگیریم.۸. یک اشتباه رایج: Retry در چند لایهTanStack Query، Pacer و HTTP Client ممکن است هرکدام امکان Retry داشته باشند.اگر هر سه لایه بهصورت مستقل یک عملیات را Retry کنند، یک درخواست ناموفق میتواند به تعداد زیادی درخواست تبدیل شود.بهتر است مسئولیتها را تفکیک کنیم:لایه HTTP: رفتارهای وابسته به وضعیت پاسخ مانند 429 و Retry-AfterTanStack Query: سیاست Retry برای QueryهاTanStack Pacer: Retry برای کارهای صفبندیشده یا Batchهایی که مسئولیت آنها در جای دیگری مدیریت نمیشودبرای مثال، میتوان در Query از Retry کردن بیشتر خطاهای سمت کلاینت جلوگیری کرد:import { isFetchError } from 'tanstack-fetch' retry: (count, error) => !(isFetchError(error) && error.status < 500) && count < 3این صرفاً یک سیاست نمونه است و باید با رفتار واقعی API شما تطبیق داده شود.۹. کدام ابزار را انتخاب کنیم؟نیازابزارجستوجو و فیلترهاuseDebouncedValueAutosaveuseAsyncDebouncerرویدادهای Scroll و ResizeuseThrottledCallbackمحدودیت تعداد درخواستهاuseAsyncRateLimiterآپلود گروهیuseAsyncQueuerتجمیع رویدادهای AnalyticsuseAsyncBatcherبرای جزئیات API و گزینههای هر ابزار، مستندات TanStack Pacer را بررسی کنید.جمعبندیبرای ساخت یک لایه ارتباطی قابل نگهداری در React، بهتر است مسئولیتها را از هم جدا کنیم:TanStack Pacer مشخص میکند عملیات چه زمانی اجرا شود.TanStack Query وضعیت دادههای سمت سرور، کش و چرخه عمر Queryها را مدیریت میکند.tanstack-fetch مسئول ارسال درخواستهای HTTP و مدیریت رفتارهای لایه Transport است.این تفکیک باعث میشود کنترل درخواستها، کش، لغو عملیات و مدیریت خطاها سادهتر و قابلفهمتر باشد.لینکهای بیشترمستندات TanStack Pacerمستندات TanStack Queryمستندات tanstack-fetchنویسنده: Mohammad Garmabi، سازنده tanstack-fetch؛ یک کتابخانه مستقل HTTP Client برای اکوسیستم فرانتاند.

بازطراحی سایت tanstack-fetch؛ تجربه‌ای بهتر برای توسعه‌دهنده‌ها 🚀

garmabi.mohammad73 — Wed, 21 Oct 2026 11:55:31 +0330

سایت پروژه متن‌باز tanstack-fetch رو بازطراحی کردم.هدفم این بود که معرفی پروژه و دسترسی به مستندات، تجربه ساده‌تر و مرتب‌تری داشته باشه.ایده اصلی این کتابخانه، تکمیل تجربه کار با TanStack Query هست؛ به این شکل که مدیریت Server State در TanStack Query باقی می‌مونه و مسئولیت ارتباط HTTP و مدیریت درخواست‌ها به tanstack-fetch سپرده می‌شه.اگر با React، TypeScript و TanStack Query کار می‌کنید، خوشحال می‌شم نگاهی به نسخه جدید سایت بندازید و نظرتون رو بگید.🔗 مشاهده سایت:https://mohamadgarmabi.github.io/tanstack-fetch/بازخوردها و مشارکت شما می‌تونه به بهتر شدن این پروژه متن‌باز کمک کنه.

انتشار tanstack-fetch 1.7.1؛ رفع باگ‌های مهم در URL، Timeout، بدنه‌های باینری و مدیریت خطا

garmabi.mohammad73 — Sun, 18 Oct 2026 11:21:08 +0330

در نسخه‌ی 1.7.1 از tanstack-fetch روی چند مشکل در مسیر اصلی ارسال درخواست تمرکز کرده‌ام؛ مواردی که شاید در مثال‌های ساده دیده نشوند، اما در پروژه‌های واقعی، SSR و محیط‌های Node.js می‌توانند دردسرساز شوند.این نسخه API جدیدی اضافه نمی‌کند. هدف آن قابل‌پیش‌بینی‌تر کردن رفتار درخواست‌ها و اصلاح چند edge case مهم است.برای نصب:npm install tanstack-fetch@1.7.1۱. تشخیص اشتباه پارامترهای مسیر در URL اصلاح شدقبلاً matcher پارامترهای مسیر، کل URL را بررسی می‌کرد. در نتیجه ممکن بود :8080 در آدرس http://localhost:8080 یا مقداری مثل 10:30 در query string به‌اشتباه پارامتر مسیر در نظر گرفته شود.در نسخه‌ی جدید فقط pathname برای پیدا کردن پارامترهایی مثل :id یا {id} بررسی می‌شود و scheme، host، port، query string و hash دست‌نخورده باقی می‌مانند.await api.get( 'http://localhost:8080/users/:id?at=10:30', { params: { id: '1' } }, ) // → http://localhost:8080/users/1?at=10:30این اصلاح به‌خصوص در سناریوهای SSR که درخواست به یک origin محلی ارسال می‌شود کاربرد دارد.۲. Timeout دیگر با خطای معمول شبکه اشتباه گرفته نمی‌شوددر نسخه‌های قبلی، تمام شدن زمان درخواست با NETWORK_ERROR گزارش می‌شد. در نتیجه تشخیص timeout از قطع شدن اتصال سخت بود و ممکن بود منطق retry سفارشی آن را مثل یک خطای شبکه در نظر بگیرد.حالا timeout با TimeoutError رد می‌شود و تابع isAbortError() آن را تشخیص می‌دهد:import { isAbortError, isFetchError } from 'tanstack-fetch' try { await api.get('/report', { timeoutMs: 5_000 }) } catch (error) { if (isAbortError(error)) { if ((error as Error).name === 'TimeoutError') { // نمایش پیام اختصاصی برای تمام شدن زمان درخواست } } else if (isFetchError(error)) { // مدیریت خطاهای HTTP یا شبکه } }به این ترتیب می‌توان timeout را از cancellation ناشی از کاربر یا TanStack Query جدا کرد.۳. تایمرهای Timeout پس از پایان درخواست پاک می‌شوندپیش از این، ممکن بود تایمر timeout حتی بعد از موفق شدن درخواست تا پایان مدت تعیین‌شده فعال بماند. در Node.js، SSR و محیط‌های serverless این موضوع می‌توانست باعث زنده ماندن غیرضروری process یا انباشته شدن تایمرها زیر بار شود.در نسخه‌ی 1.7.1 تایمر پس از پایان هر تلاش پاک می‌شود و در Node.js نیز به‌تنهایی مانع پایان process نخواهد شد.۴. بدنه‌های باینری و Stream به‌صورت صحیح ارسال می‌شوندقبلاً ممکن بود Uint8Array به‌جای ارسال بایت‌های خام، به JSON تبدیل شود؛ چیزی شبیه:{"0":1,"1":2,"2":3}اکنون ArrayBuffer، typed arrayها، DataView و ReadableStream به شکل مناسب خود ارسال می‌شوند.برای stream body نیز گزینه‌ی duplex: 'half' تنظیم می‌شود تا با Fetch در Node.js سازگار باشد. آبجکت‌های معمولی JavaScript همچنان به JSON تبدیل می‌شوند.۵. خطاهای HTTP وضعیت واقعی پاسخ را حفظ می‌کنندگاهی یک gateway یا proxy پاسخ 502 را همراه با صفحه‌ی HTML برمی‌گرداند، حتی اگر content-type آن JSON باشد.قبلاً خطای parse می‌توانست پیش از اجرای interceptorها رخ دهد؛ در نتیجه status واقعی HTTP در دسترس منطق مدیریت خطا قرار نمی‌گرفت.در نسخه‌ی جدید، پاسخ non-2xx با JSON نامعتبر همچنان status واقعی خود را حفظ می‌کند. کد خطا HTTP_ERROR است، متن خام پاسخ در error.body قرار می‌گیرد و interceptorهای onResponseError اجرا می‌شوند.try { await api.get('/gateway') } catch (error) { if (isFetchError(error)) { error.status // 502 error.code // 'HTTP_ERROR' error.body // متن خام پاسخ gateway } }خطای PARSE_ERROR اکنون برای JSON نامعتبر در پاسخ‌های موفق 2xx استفاده می‌شود.نکته مهم هنگام ارتقاتنها تغییر رفتاری مهم این نسخه مربوط به timeout است:اگر با error.code === 'NETWORK_ERROR' timeout را تشخیص می‌دادید، منطق خود را به isAbortError(error) تغییر دهید و در صورت نیاز error.name === 'TimeoutError' را بررسی کنید.timeoutها دیگر از onRequestError عبور نمی‌کنند. اگر retry سفارشی شما فقط در این interceptor پیاده‌سازی شده، باید محل اجرای retry را بازبینی کنید.می‌توانید TimeoutError را در محل فراخوانی مدیریت کنید یا از قابلیت retry در TanStack Query استفاده کنید.جمع‌بندینسخه‌ی 1.7.1 بیشتر از آن‌که روی قابلیت‌های جدید تمرکز کند، روی رفتار درست در شرایط واقعی تمرکز دارد: URLهای دارای port و query، timeout، پاک‌سازی منابع، ارسال داده‌های باینری و حفظ اطلاعات خطاهای HTTP.نصب نسخه‌ی جدید:npm install tanstack-fetch@1.7.1مشاهده توضیحات کامل انتشار:https://mohamadgarmabi.github.io/tanstack-fetch/blog/tanstack-fetch-1-7-1tanstack-fetch یک پروژه‌ی مستقل برای مدیریت لایه‌ی HTTP در کنار ابزارهایی مانند TanStack Query است و پکیج رسمی TanStack نیست.— محمد گرمابی

TanStack Start 1.0 + tanstack-fetch: 6 Real-World Data Fetching Patterns

garmabi.mohammad73 — Wed, 14 Oct 2026 14:59:41 +0330

TanStack Start is officially stable. If you have been waiting for the 1.0 release before building a production application, now is a good time to explore the framework.But getting a full-stack React application running is only the first step. The more interesting engineering decisions come later:Where should an API request run: in a route loader, on the server, or in the browser?How do you avoid fetching the same data twice?How should server-side rendering handle cookies and authorization?How do mutations update the existing Query cache?What happens when an API returns an HTTP error?How can a page combine REST data with live server-sent events?In this tutorial, we'll explore these scenarios using TanStack Start, TanStack Router, TanStack Query, and tanstack-fetch.I'm the creator of tanstack-fetch, an HTTP client designed to work with TanStack Query's server-state model. It is an independent community package, not an official TanStack project.1. Start with the right mental modelThese libraries solve different problems:TanStack Start provides the full-stack application framework, including server rendering and server functions.TanStack Router coordinates routes, navigation, search parameters, and loaders.TanStack Query manages server-state caching, freshness, mutations, and background updates.tanstack-fetch handles HTTP requests, typed responses and errors, and reusable request behavior.The important distinction is that an HTTP client and a server-state manager should not compete for the same responsibilities.TanStack Query owns the cache. The HTTP client executes requests.Install the core dependencies:npm install tanstack-fetch @tanstack/react-queryFollow the current TanStack Start and Router documentation for the framework-specific setup and SSR integration:TanStack Start documentationtanstack-fetch documentation2. Pattern one: Fetch data directlyNot every request needs a complicated abstraction.For a simple client-side request, create a reusable API client:// src/lib/api.ts import { createFetch } from 'tanstack-fetch' export const api = createFetch({ baseUrl: '/api', })Then use it in a component or a query function:import { useQuery } from '@tanstack/react-query' import { api } from '~/lib/api' type User = { id: string name: string } export function Users() { const usersQuery = useQuery({ queryKey: ['users'], queryFn: ({ signal }) => api.get('/users', { signal }), }) if (usersQuery.isPending) { return

Loading users...

} if (usersQuery.isError) { return

Could not load users.

} return (

{user.name}

) }Three details matter here:The response is typed as User[].The query function passes Query's AbortSignal to the HTTP client.HTTP failures should reject the query so Query can represent them through its error state.Passing the signal also allows an obsolete request to be cancelled when appropriate.When to use this pattern: Client-side widgets, independent requests, and pages that do not need route-level preloading.3. Pattern two: Share route loaders and Query cacheThis is where TanStack Router and TanStack Query become particularly useful together.A common implementation fetches data in a loader, then makes another request when the component mounts. Another implementation stores loader data separately from Query's cache.Both approaches can be valid, but they introduce extra synchronization work when the same resource is used across routes or components.Instead, define reusable query options:// src/queries/users.ts import { queryOptions } from '@tanstack/react-query' import { api } from '~/lib/api' export const usersQueryOptions = queryOptions({ queryKey: ['users'], queryFn: ({ signal }) => api.get('/users', { signal }), staleTime: 30_000, })Use the same options in the route loader and component:import { createFileRoute } from '@tanstack/react-router' import { useQuery } from '@tanstack/react-query' import { usersQueryOptions } from '~/queries/users' export const Route = createFileRoute('/users')({ loader: ({ context }) => context.queryClient.ensureQueryData( usersQueryOptions, ), component: UsersPage, }) function UsersPage() { const { data: users } = useQuery(usersQueryOptions) return (

{user.name}

) }The router must expose the appropriate queryClient through its typed context, and the application must configure the Query provider and, when using SSR, the appropriate Router–Query integration.The result is a shared contract:The loader can ensure that data is available before the route renders.The component reads from the same Query cache.Other components can reuse the same query options.Query controls freshness and subsequent refetching.This does not mean a network request can never happen again. A stale query, invalidation, or an explicit refetch can legitimately trigger one. The goal is to avoid unnecessary duplicate fetching and separate caches.When to use this pattern: Lists, detail pages, nested routes, dashboards, and resources shared across multiple components.4. Pattern three: Handle SSR and authenticated requestsServer-side rendering introduces a different problem: the server does not automatically inherit the browser's request context when it calls an external API.If an upstream API requires the incoming request's cookies or authorization headers, the HTTP client needs an explicit server-side strategy.tanstack-fetch supports an ssr-forward plugin for forwarding request context.A server-aware client can be configured like this:// Illustrative server-side setup import { createFetch } from 'tanstack-fetch' export const createServerApi = ( apiOrigin: string, cookie: string | undefined, ) => createFetch({ baseUrl: `${apiOrigin}/api`, source: 'ssr', plugins: ['ssr-forward'], incoming: () => ({ cookie }), })This example illustrates the configuration pattern. Obtain the cookie from the actual incoming request using the relevant TanStack Start server API, and create the client in the request's server-side execution context.For a real application:Use an absolute API origin on the server.Read credentials from the incoming request, not from a global variable.Never expose private environment variables or server-only credentials to the browser.Avoid sharing user-specific API clients or Query caches across SSR requests.Forward only the headers that the upstream service actually needs.A server-side request may also need to preserve an authorization header or request ID. Those should be forwarded deliberately rather than copying every incoming header.When to use this pattern: Personalized SSR pages, authenticated dashboards, and applications whose API uses cookie-based sessions.5. Pattern four: Mutations and cache invalidationFetching data is only half of a data layer. The other half is keeping the UI consistent after writes.Suppose an application creates a user. The mutation should use the same HTTP client and invalidate the query that represents the user list.import { useMutation, useQueryClient, } from '@tanstack/react-query' import { api } from '~/lib/api' type CreateUserInput = { name: string } type User = { id: string name: string } export function CreateUserButton() { const queryClient = useQueryClient() const createUser = useMutation({ mutationFn: (input: CreateUserInput) => api.post('/users', { body: input }), onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'], }), }) return ( createUser.mutate({ name: 'New user' }) } > {createUser.isPending ? 'Creating...' : 'Create user'} ) }The example assumes the application has already configured the appropriate Query provider.Invalidation marks matching cached queries as stale and allows active queries to refetch according to Query's behavior. It does not blindly replace every cached copy of the data.For more responsive interfaces, optimistic updates may be appropriate. However, they need a rollback strategy when the mutation fails and careful handling when concurrent updates are possible.When to use this pattern: Forms, CRUD screens, admin panels, and any UI where a write affects previously fetched data.6. Pattern five: Centralize HTTP errors and authentication behaviorHTTP errors should have predictable semantics across the application.A 401 Unauthorized response might indicate that a session has expired. A 403 Forbidden response generally means that the caller is authenticated but lacks permission. A 404 means the resource was not found.These conditions should not all trigger the same recovery action.A reusable HTTP client gives you a place to configure error handling and interceptors instead of repeating that logic in every query function.For example, a refresh-token interceptor can coordinate token refresh and retry eligible failed requests:import { createFetch } from 'tanstack-fetch' import { createRefreshTokenInterceptor, } from 'tanstack-fetch/plugins' const api = createFetch({ baseUrl: '/api', }) api.use( 'refresh-token', createRefreshTokenInterceptor({ refresh: async () => { // Refresh the session using your authentication flow. // Store updated credentials according to your // application's security model. }, }), )The refresh implementation is application-specific. It must actually obtain and persist or update the new credential before a retry can succeed.A production implementation should also consider:Concurrent requests that fail while a refresh is in progress.Refresh failure and session expiry.Avoiding recursive refresh requests.Which HTTP methods are safe to retry.Cross-tab session changes.Whether credentials are stored in secure, HttpOnly cookies or another appropriate mechanism.Do not redirect to login on every error. In particular, a 403 should not automatically trigger logout, and a 404 should not be treated as an expired session.When to use this pattern: Applications with authentication, protected APIs, consistent error handling, and several features that share the same backend.7. Pattern six: Combine REST queries with live SSE updatesSome pages need both an initial snapshot and a stream of updates.Examples include notifications, order tracking, live dashboards, and operational monitoring.A useful architecture is:Load the initial resource through REST or another regular API.Use TanStack Query to cache and manage that resource.Open a server-sent events connection in the browser.Update the cache when an event arrives, or invalidate the relevant query when the event is incomplete.tanstack-fetch provides SSE support through its tanstack-fetch/sse integration.The exact event handling depends on the shape of your API. For a complete entity update, you may be able to update the cache directly:queryClient.setQueryData( ['order', orderId], updatedOrder, )If the event only tells you that an order changed, invalidating the query is usually safer:queryClient.invalidateQueries({ queryKey: ['order', orderId], })An SSE reconnect does not prove that no events were missed. If you need reliable recovery, design the protocol around event IDs, replay or resume support, and a strategy for reconciling the current snapshot.For authenticated streams, verify how credentials are transported. The browser's native EventSource API does not provide a general option for setting arbitrary authorization headers; a fetch-based SSE client can be useful when those headers are required.When to use this pattern: Live dashboards, event-driven interfaces, and pages where server state changes without a user action.8. What about Server Functions?TanStack Start Server Functions are useful for server-only logic that your own application invokes across the client/server boundary.For example, they can wrap a database operation or access server-only environment variables.They are not interchangeable with a generic HTTP client.Use a Server Function when the operation belongs to the application's server logic. Use an HTTP client when communicating with a REST API or another HTTP service. Use Server Routes when you need endpoints intended to be called externally or across origins.If you combine Server Functions with TanStack Query, keep validation, authorization, and cache invalidation explicit. The server boundary does not remove the need for security checks.9. A practical project structureOne possible structure is:src/ lib/ api.ts queries/ users.ts orders.ts routes/ users.tsx orders.$orderId.tsx components/ create-user-button.tsxThe exact folders are less important than keeping responsibilities clear:lib/api.ts owns reusable HTTP configuration.queries/ owns shared query keys, options, and request functions.routes/ owns navigation and route-level data requirements.components/ owns UI behavior and presentation.For SSR, keep request-specific clients and caches scoped to the request. Do not turn a convenience singleton into a cross-user data leak.10. How should you choose?RequirementRecommended approachSimple browser requestcreateFetch + useQueryRoute-level preloadingqueryOptions + ensureQueryDataAuthenticated SSRRequest-scoped client + ssr-forwardWrites and stale cached datauseMutation + invalidationShared HTTP error policyClient configuration and pluginsLive server updatesSSE + Query cacheServer-only application logicTanStack Start Server FunctionsPublic HTTP endpointServer Routes or a dedicated APIYou do not need to adopt every pattern at once. Start with one API client and shared query options. Add SSR forwarding, mutation strategies, and live updates only when the application needs them.Final thoughtsTanStack Start 1.0 makes this a good moment to evaluate a full-stack React architecture, but a stable framework does not automatically give you a maintainable data layer.The important part is choosing clear boundaries: Router coordinates navigation, Query owns server-state caching, the HTTP client owns transport concerns, and the server owns privileged operations.That's the problem space tanstack-fetch is designed to address. It is not a replacement for TanStack Query or TanStack Start; it is an option for standardizing HTTP behavior alongside them.Explore the project:tanstack-fetch documentationTanStack Start documentationTanStack Query integration guideIf you're building with TanStack Start, which part of the data layer has required the most work in your project: SSR, authentication, caching, or real-time updates?

آموزش Angular و tanstack-fetch؛ ساخت HTTP Client تایپ‌سیف با TypeScript

garmabi.mohammad73 — Mon, 12 Oct 2026 10:02:51 +0330

توضیحات مقاله: در این آموزش یاد می‌گیریم چطور با tanstack-fetch، Angular Dependency Injection و TanStack Query یک لایه‌ی API قابل‌استفاده‌ی مجدد، تایپ‌سیف و پشتیبان از لغو درخواست بسازیم.در پروژه‌های Angular معمولاً کار با API با چند درخواست ساده شروع می‌شود؛ اما با بزرگ‌تر شدن پروژه، مدیریت درخواست‌ها، خطاها، تایپ پاسخ‌ها و لغو درخواست‌ها می‌تواند به یک چالش تبدیل شود.اگر هر کامپوننت منطق درخواست HTTP خودش را داشته باشد، نگهداری و یکپارچه‌سازی رفتارها دشوارتر خواهد شد.در این مقاله، یک روش برای جداسازی لایه‌ی HTTP از مدیریت وضعیت سرور را با استفاده از tanstack-fetch، Angular و TanStack Query بررسی می‌کنیم.tanstack-fetch چیست؟tanstack-fetch یک HTTP client مستقل مبتنی بر TypeScript است که برای استفاده در کنار الگوی برنامه‌نویسی TanStack Query طراحی شده است.مسئولیت ابزارها را می‌توان این‌طور تقسیم کرد:tanstack-fetch: ارسال درخواست HTTP و مدیریت خطاهای مرتبط با کلاینت.TanStack Query: مدیریت چرخه‌ی عمر query و کش داده‌های سمت سرور.Angular: مدیریت کامپوننت‌ها و Dependency Injection.این پروژه توسط Mohammad Garmabi توسعه داده شده و یک پکیج رسمی از تیم TanStack نیست.۱. نصب پکیج‌هاابتدا پکیج‌های موردنیاز را نصب می‌کنیم:npm install tanstack-fetch npm install @tanstack/angular-query-experimentalاین نمونه بر اساس API ارائه‌شده در مستندات Angular پروژه نوشته شده است. پیش از استفاده در محیط production، سازگاری نسخه‌های نصب‌شده را بررسی کنید.۲. ساخت HTTP Client مشترکبهتر است تنظیمات API را در یک محل مشخص نگه داریم:// api.ts import { createFetch } from 'tanstack-fetch'; export interface User { id: number; name: string; email: string; } export const api = createFetch({ baseUrl: 'https://jsonplaceholder.typicode.com', });در این مثال از یک API آزمایشی استفاده می‌کنیم. در پروژه‌ی واقعی می‌توانید آدرس API خودتان را قرار دهید.۳. اتصال به Angular Dependency Injectionحالا client را به providerهای برنامه اضافه می‌کنیم:import { bootstrapApplication } from '@angular/platform-browser'; import { provideFetchClient } from 'tanstack-fetch/angular'; import { api } from './api'; import { UsersComponent } from './users.component'; bootstrapApplication(UsersComponent, { providers: [ provideFetchClient({ client: api }), ], });پس از این مرحله، می‌توانیم در context معتبر Angular از injectFetch() برای دریافت client استفاده کنیم.۴. دریافت داده با TanStack Queryدر مثال زیر، فهرست کاربران را دریافت می‌کنیم و وضعیت درخواست را در رابط کاربری نمایش می‌دهیم.import { Component } from '@angular/core'; import { injectQuery } from '@tanstack/angular-query-experimental'; import { injectFetch } from 'tanstack-fetch/angular'; import { isFetchError } from 'tanstack-fetch'; import { User } from './api'; @Component({ selector: 'app-users', standalone: true, template: ` @if (users.isPending()) {

در حال دریافت اطلاعات...

} @else if (users.isError()) {

} @else {

{{ user.name }} - {{ user.email }}

} `, }) export class UsersComponent { private readonly api = injectFetch(); readonly users = injectQuery(() => ({ queryKey: ['users'], queryFn: ({ signal }: { signal: AbortSignal }) => this.api.get('/users', { signal }), })); errorLabel(): string { const error = this.users.error(); return isFetchError(error) ? `خطای HTTP ${error.status}: ${error.message}` : 'دریافت اطلاعات ناموفق بود'; } }این معماری چه مزایایی دارد؟۱. تایپ‌سیف بودن پاسخ‌هابا استفاده از get نوع داده‌ی موردانتظار را مشخص می‌کنیم. این کار به خوانایی کد و تشخیص خطاهای تایپی کمک می‌کند؛ البته صحت واقعی داده‌های دریافتی از سرور را به‌تنهایی تضمین نمی‌کند.۲. استفاده از Dependency Injectionبه‌جای ساختن client در هر کامپوننت، از یک نمونه‌ی پیکربندی‌شده استفاده می‌کنیم.۳. لغو درخواست با AbortSignalسیگنال دریافتی از TanStack Query را به درخواست HTTP منتقل می‌کنیم:queryFn: ({ signal }: { signal: AbortSignal }) => this.api.get('/users', { signal })این اتصال اجازه می‌دهد درخواست در صورت لغو شدن توسط چرخه‌ی عمر query، عملیات لغو را دریافت کند؛ مشروط به اینکه HTTP client سیگنال را به درخواست زیرین منتقل کند.۴. جداسازی مدیریت خطاتابع isFetchError() کمک می‌کند خطاهای مربوط به HTTP client را از خطاهای دیگر متمایز کنیم و پیام مناسب‌تری به کاربر نمایش دهیم.۵. جداسازی HTTP از مدیریت وضعیت سرورTanStack Query مسئول کش و چرخه‌ی عمر query است، درحالی‌که tanstack-fetch درخواست HTTP را انجام می‌دهد. این تفکیک از ترکیب شدن مسئولیت‌های متفاوت در یک کامپوننت جلوگیری می‌کند.آیا همیشه باید از یک HTTP Client جداگانه استفاده کنیم؟خیر. Angular ابزار داخلی HttpClient را هم در اختیار توسعه‌دهندگان قرار می‌دهد و برای بسیاری از پروژه‌ها کاملاً کافی است.استفاده از یک client جداگانه زمانی ارزشمند است که به قراردادهای مشترک برای درخواست‌ها، تایپ پاسخ‌ها، مدیریت خطا یا یکپارچگی بیشتر با ابزارهای مدیریت server state نیاز داشته باشید.هدف، پیچیده‌تر کردن معماری نیست؛ هدف این است که هر لایه مسئولیت مشخصی داشته باشد.جمع‌بندیبا ترکیب Angular Dependency Injection، tanstack-fetch و TanStack Query می‌توان یک لایه‌ی API ساخت که درخواست‌های تایپ‌سیف را با مدیریت وضعیت سرور و امکان انتقال سیگنال لغو هماهنگ می‌کند.اگر می‌خواهید جزئیات API و مثال‌های بیشتر را ببینید، مستندات پروژه در دسترس است:راهنمای Angular در tanstack-fetchمخزن GitHub پروژهنویسنده: Mohammad Garmabi، توسعه‌دهنده‌ی نرم‌افزار و سازنده‌ی پروژه‌ی متن‌باز tanstack-fetch.

انتشار tanstack-fetch 1.7.0؛ آداپترهای Solid، Angular و Svelte + دستور Doctor

garmabi.mohammad73 — Fri, 09 Oct 2026 18:07:20 +0330

در نسخه 1.7.0 کتابخانه tanstack-fetch، پشتیبانی از فریم‌ورک‌های بیشتری اضافه شده است. این نسخه شامل آداپترهای Solid، Angular و Svelte، ابزار بررسی سلامت پروژه (Doctor)، بهبود ابزار مهاجرت، نمایش پیشرفت دانلود و فیلتر فریم‌ورک در مستندات است.اگر از TanStack Query استفاده می‌کنید، تابع queryFn باید سه اصل مهم را رعایت کند:داده را برگرداند، نه آبجکت خام Response.در صورت بروز خطا، آن را با throw اعلام کند تا وضعیت isError به‌درستی کار کند.از AbortSignal پشتیبانی کند تا درخواست‌ها در صورت نیاز لغو شوند.tanstack-fetch با همین رویکرد طراحی شده است: ساده‌سازی لایه HTTP و هماهنگی بهتر آن با الگوی استفاده از TanStack Query.توجه: tanstack-fetch یک پروژه مستقل و غیررسمی است و ارتباطی با تیم رسمی TanStack ندارد.آداپترهای جدیددر نسخه 1.7.0، آداپترهای Solid، Svelte و Angular اضافه شده‌اند تا بتوان از قابلیت‌های کتابخانه در این فریم‌ورک‌ها استفاده کرد.Solidمسیر ایمپورت:tanstack-fetch/solidAPIهای اصلی:FetchProvideruseFetchuseSseSvelteمسیر ایمپورت:tanstack-fetch/svelteAPIهای اصلی:setFetchClientuseFetchuseSseAngularمسیر ایمپورت:tanstack-fetch/angularAPIهای اصلی:provideFetchClientinjectFetchuseSseمدیریت وضعیت اتصال SSE نیز از یک الگوی یکسان پیروی می‌کند:connecting، connected، disconnected و errorاین وضعیت‌ها کمک می‌کنند شرایط اتصال و خطاهای ارتباطی را در برنامه بهتر مدیریت کنید.مستندات آداپتر Solid:https://mohamadgarmabi.github.io/tanstack-fetch/guide/solidابزار Doctor برای بررسی سلامت پروژهیکی از قابلیت‌های جدید این نسخه، دستور doctor است.با اجرای این دستور، می‌توانید وضعیت استفاده از کلاینت‌های HTTP و برخی مشکلات احتمالی مهاجرت را در پروژه بررسی کنید.برای اجرا:npx tanstack-fetch doctor --dir ./src این ابزار موارد زیر را بررسی می‌کند:وجود پکیج‌های قدیمی مانند Axios، ky و ofetchتعداد استفاده از createFetchایمپورت‌های باقی‌مانده از کتابخانه‌های قبلیتوابع queryFn که احتمالاً signal را به درخواست منتقل نمی‌کنندهدف این است که پیش از تکمیل مهاجرت، مشکلات احتمالی را شناسایی کنید و بررسی کد را سریع‌تر انجام دهید.بهبود دستور Migrateابزار مهاجرت حالا اسکفولدهای بیشتری برای فریم‌ورک‌های مختلف ارائه می‌دهد.برای مهاجرت از Axios به Solid:npx tanstack-fetch migrate --from axios --framework solid --write برای مهاجرت از Axios به Angular:npx tanstack-fetch migrate --from axios --framework angular --write برای مهاجرت از Fetch به Svelte:npx tanstack-fetch migrate --from fetch --framework svelte --write برای مهاجرت از Fetch به SvelteKit:npx tanstack-fetch migrate --from fetch --framework sveltekit --write این دستورها با هدف کمک به شروع مهاجرت و ایجاد ساختار مناسب برای فریم‌ورک مقصد ارائه شده‌اند. بعد از اجرا، کد تولیدشده را بررسی کنید و بخش‌هایی را که به منطق اختصاصی پروژه وابسته‌اند، به‌صورت دستی اصلاح کنید.راهنمای مهاجرت:https://mohamadgarmabi.github.io/tanstack-fetch/guide/migrateنمایش پیشرفت دانلود فایلقابلیت جدید onDownloadProgress امکان مشاهده پیشرفت دانلود را فراهم می‌کند.برای مثال، هنگام دانلود یک فایل PDF:await api.get('/files/report.pdf', { parseAs: 'blob', onDownloadProgress: ({ progress, loaded, total }) => { console.log(progress, loaded, total) }, }) در این مثال:progress میزان پیشرفت دانلود را نشان می‌دهد.loaded حجم دریافت‌شده را مشخص می‌کند.total حجم کل فایل را، در صورت در دسترس بودن، نشان می‌دهد.این قابلیت برای نمایش نوار پیشرفت دانلود فایل‌ها و بهبود تجربه کاربری مفید است.راهنمای آپلود و دانلود:https://mohamadgarmabi.github.io/tanstack-fetch/guide/uploadنصب یا ارتقا به نسخه 1.7.0برای نصب نسخه جدید، دستور زیر را اجرا کنید:npm install tanstack-fetch@1.7.0لینک‌های پروژهوبلاگ نسخه 1.7.0: https://mohamadgarmabi.github.io/tanstack-fetch/blog/tanstack-fetch-1-7-0راهنمای مهاجرت: https://mohamadgarmabi.github.io/tanstack-fetch/guide/migrateراهنمای آپلود و دانلود: https://mohamadgarmabi.github.io/tanstack-fetch/guide/uploadمستندات Solid: https://mohamadgarmabi.github.io/tanstack-fetch/guide/solidصفحه npm: https://www.npmjs.com/package/tanstack-fetchمخزن GitHub: https://github.com/mohamadgarmabi/tanstack-fetchنسخه 1.7.0 با هدف گسترش پشتیبانی از فریم‌ورک‌ها، ساده‌تر کردن مهاجرت و فراهم کردن ابزارهای بهتر برای بررسی و مدیریت درخواست‌های HTTP منتشر شده است.

tanstack-fetch در برابر ky و Axios؛ کدام HTTP Client برای React و TanStack Query مناسب‌تر است؟

garmabi.mohammad73 — Wed, 07 Oct 2026 13:15:15 +0330

اگر با React کار می‌کنید، احتمالاً بارها بین fetch، Axios، ky یا HTTP Clientهای دیگر انتخاب کرده‌اید.اما وقتی TanStack Query وارد معماری پروژه می‌شود، یک سؤال مهم‌تر مطرح می‌شود:آیا HTTP Client ما واقعاً با مدل کاری TanStack Query هماهنگ است؟همین سؤال یکی از دلایلی بود که من tanstack-fetch را ساختم.هدف tanstack-fetch این نیست که صرفاً یک HTTP Client دیگر باشد.ایده اصلی این است:TanStack Query مسئول Server State باشد و tanstack-fetch مسئول HTTP Transport.مشکل کجاست؟TanStack Query برای queryFn یک مدل بسیار ساده دارد.queryFn باید:داده را برگردانددر صورت خطا exception ایجاد کنداز AbortSignal پشتیبانی کندمثلاً با Fetch خام:useQuery({ queryKey: ['users'], queryFn: ({ signal }) => fetch('/api/users', { signal }).then(res => res.json()), }) در پروژه واقعی، اما HTTP Client معمولاً مسئولیت‌های بیشتری پیدا می‌کند:AuthenticationToken RefreshInterceptorError HandlingSSRSSERetryType SafetyRequest Cancellationاینجاست که Axios یا ky وارد می‌شوند.Axios چه مشکلی دارد؟استفاده از Axios در TanStack Query کاملاً ممکن است:queryFn: async ({ signal }) => { const { data } = await axios.get('/users', { signal, }) return data } اما یک تبدیل اضافه داریم:Axios Response ↓ response.data ↓ TanStack Query این تبدیل کوچک به‌تنهایی مشکل بزرگی نیست.اما در یک پروژه بزرگ، ممکن است صدها بار تکرار شود.ky چطور؟ky نسبت به Axios سبک‌تر و نزدیک‌تر به Fetch است:queryFn: ({ signal }) => ky.get('/users', { signal }).json() اما همچنان باید Response را به داده تبدیل کنیم:Fetch Response ↓ .json() ↓ TanStack Query این API کاملاً قابل قبول است و ky برای بسیاری از پروژه‌ها انتخاب خوبی است.اما اگر TanStack Query بخش اصلی Server State پروژه باشد، می‌توان سؤال دیگری مطرح کرد:آیا می‌توان HTTP Client را مستقیماً با مدل TanStack Query هماهنگ کرد؟tanstack-fetchایده tanstack-fetch دقیقاً همین است.مثلاً:const api = createFetch({ baseUrl: 'https://api.example.com', }) و بعد:useQuery({ queryKey: ['users'], queryFn: ({ signal }) => api.get('/users', { signal }), }) نتیجه مستقیماً داده است:User[] بنابراین خبری از این موارد نیست:response.data یا:response.json() خطاهای HTTP نیز از طریق FetchError مدیریت می‌شوند.معماری پیشنهادیهدف این نیست که tanstack-fetch جای TanStack Query را بگیرد.برعکس، هر کدام مسئولیت مشخص خودشان را دارند:┌─────────────────────────┐ │ React UI │ ├─────────────────────────┤ │ TanStack Query │ │ │ │ Server State │ │ Cache │ │ Retry │ │ Refetch │ │ Mutations │ ├─────────────────────────┤ │ tanstack-fetch │ │ │ │ HTTP Transport │ │ Type Safety │ │ Authentication │ │ Token Refresh │ │ Interceptors │ │ SSE │ ├─────────────────────────┤ │ Fetch │ └─────────────────────────┘ به این شکل، هر لایه یک مسئولیت مشخص دارد.Token Refresh و درخواست‌های همزمانیکی از مشکلات رایج در اپلیکیشن‌های واقعی، Refresh Token است.فرض کنید چند درخواست تقریباً همزمان با 401 مواجه شوند.بدون هماهنگی ممکن است اتفاقی شبیه این رخ دهد:Request A → 401 → refresh Request B → 401 → refresh Request C → 401 → refresh Request D → 401 → refresh در حالی که چیزی که معمولاً می‌خواهیم این است:Request A → 401 ─┐ Request B → 401 ─┤ Request C → 401 ─┼→ یک refresh → retry Request D → 401 ─┘ tanstack-fetch برای این سناریو یک Refresh Token Interceptor با الگوی single-flight دارد.همچنین امکان Refresh قبل از منقضی شدن Token و Refresh واکنشی بعد از اولین 401 را فراهم می‌کند.SSR و SSEدر اپلیکیشن‌های مدرن React، HTTP Request فقط به Browser محدود نیست.در محیط‌هایی مثل Next.js ممکن است با مواردی مثل:SSRCookie ForwardingServer-side RequestAuthenticationSSERequest Cancellationمواجه شویم.بنابراین HTTP Client باید بتواند این سناریوها را نیز پوشش دهد.tanstack-fetch برای مواردی مانند SSR Cookie Forwarding، Authenticated SSE و SSE Resume قابلیت‌هایی ارائه می‌کند.مقایسه tanstack-fetch، ky و Axiosتمرکز روی TanStack Querytanstack-fetch:پشتیبانی و طراحی‌شده با تمرکز روی TanStack Queryky:تمرکز مستقیمی روی TanStack Query نداردAxios:تمرکز مستقیمی روی TanStack Query نداردمبتنی بر Fetchtanstack-fetch:بلهky:بلهAxios:خیرTyped Errortanstack-fetch:بله، با FetchErrorky:بله، با HTTPErrorAxios:بله، با AxiosErrorAbortSignaltanstack-fetch:پشتیبانی می‌کندky:پشتیبانی می‌کندAxios:پشتیبانی می‌کندToken Refreshtanstack-fetch:Built-inky:نیاز به پیاده‌سازی سفارشی داردAxios:نیاز به پیاده‌سازی سفارشی داردSingle-flight Refreshtanstack-fetch:پشتیبانی می‌کندky:نیاز به پیاده‌سازی سفارشی داردAxios:نیاز به پیاده‌سازی سفارشی داردSSRtanstack-fetch:First-class supportky:نیاز به پیاده‌سازی دستیAxios:نیاز به پیاده‌سازی دستیSSEtanstack-fetch:پشتیبانی می‌کندky:نیاز به پیاده‌سازی سفارشی داردAxios:نیاز به پیاده‌سازی سفارشی دارداکوسیستمtanstack-fetch:جدیدky:بالغAxios:بسیار بالغالبته این جدول به این معنی نیست که یک کتابخانه برای همه پروژه‌ها مناسب‌تر است.هر کدام مسئله متفاوتی را هدف قرار می‌دهند.چه زمانی tanstack-fetch انتخاب مناسبی است؟اگر:از TanStack Query استفاده می‌کنیدمی‌خواهید queryFn ساده‌تر شودType Safety برایتان مهم استToken Refresh داریدبا SSR کار می‌کنیدبه SSE نیاز داریدپروژه جدیدی شروع کرده‌ایدیا قصد مهاجرت از Axios، ky، ofetch یا Fetch را داریدtanstack-fetch می‌تواند گزینه‌ای باشد که ارزش بررسی دارد.چه زمانی ky بهتر است؟اگر فقط یک Fetch Wrapper سبک و ساده می‌خواهید و وابستگی خاصی به TanStack Query ندارید، ky می‌تواند انتخاب مناسبی باشد.چه زمانی Axios را نگه داریم؟اگر یک پروژه بزرگ با Axios دارید و:Interceptorهای پیچیده داریداکوسیستم بزرگی حول Axios ساخته‌ایدتیم شما تجربه زیادی با Axios داردو هزینه Migration بیشتر از مزایای آن استدلیلی وجود ندارد صرفاً به خاطر یک معماری جدید همه چیز را Rewrite کنید.مشکل واقعی: Migrationانتخاب HTTP Client جدید معمولاً سخت‌ترین قسمت ماجرا نیست.Migration سخت‌تر است.در یک پروژه واقعی ممکن است این موارد همزمان وجود داشته باشند:axios.get(...) axios.post(...) fetch(...) ky.get(...) در صدها فایل مختلف.به همین دلیل tanstack-fetch یک Migration CLI نیز دارد.این CLI می‌تواند به شناسایی HTTP Call Siteهای موجود کمک کند و مسیر مهاجرت از:Axios ky ofetch Fetch به معماری سازگارتر با TanStack Query را ساده‌تر کند.هدف این نیست که کل پروژه را یک‌باره Rewrite کنید.هدف، Incremental Migration است.آیا باید Axios را کنار بگذاریم؟لزوماً نه.اگر پروژه شما با Axios به‌خوبی کار می‌کند، احتمالاً نیازی به Rewrite کردن آن ندارید.سؤال جالب‌تر این است:وقتی TanStack Query مرکز Server State پروژه ماست، چرا HTTP Client باید باعث شود در هر queryFn یک لایه Adapter اضافی داشته باشیم؟tanstack-fetch دقیقاً برای پاسخ دادن به همین سؤال ساخته شده است.جمع‌بندیAxios یک HTTP Client بسیار بالغ و قدرتمند است.ky یک Fetch Wrapper سبک و تمیز است.tanstack-fetch رویکرد متفاوتی دارد:HTTP Layer را با Mental Model تان‌استک Query هماهنگ می‌کند.در نتیجه معماری می‌تواند به شکل زیر باشد:TanStack Query ↓ Server State tanstack-fetch ↓ HTTP Transport Fetch ↓ Network Primitive اگر پروژه جدیدی با React و TanStack Query شروع می‌کنید، این مدل معماری ارزش بررسی دارد.و اگر پروژه فعلی شما با Axios یا ky نوشته شده، لازم نیست همه چیز را یک‌باره تغییر دهید.می‌توانید با چند API شروع کنید، چند queryFn را مهاجرت دهید و بعد Developer Experience و هزینه نگهداری را مقایسه کنید.tanstack-fetch یک پروژه Open Source است و پروژه رسمی TanStack نیست.

مهاجرت از Axios، Ky، Ofetch یا Fetch به tanstack-fetch با یک دستور

garmabi.mohammad73 — Mon, 05 Oct 2026 12:34:23 +0330

یک کلاینت HTTP مناسب TanStack Query، به‌همراه CLI برای پیدا کردن call siteها و اسکفولد React، Vue، Nuxt و Next.jsاگر از TanStack Query استفاده می‌کنید، queryFn عملاً از شما سه چیز می‌خواهد:دیتا برگرداند، نه Response خامروی خطا throw کند تا isError و error handling درست کار کنندAbortSignal را رعایت کند تا cancellation درخواست‌ها درست انجام شودبیشتر HTTP Clientها دقیقاً برای این مدل طراحی نشده‌اند. معمولاً باید res.data را باز کنید، روی Response متد .json() را صدا بزنید یا حواستان باشد signal را به درخواست منتقل کنید.tanstack-fetch برای همین مدل ذهنی ساخته شده است: یک HTTP client تایپ‌شده که با الگوی استفاده از TanStack Query هماهنگ است.در نسخه 1.6.2 یک CLI برای migration اضافه شده که می‌تواند axios، ky، ofetch و fetch را اسکن کند، الگوهای امن را rewrite کند و برای React، Vue، Nuxt و Next.js فایل‌های اولیه را scaffold کند.نکته: tanstack-fetch یک پروژه رسمی TanStack نیست و هیچ وابستگی رسمی به تیم TanStack ندارد؛ فقط API و mental model آن با هدف هماهنگی با اکوسیستم TanStack طراحی شده است.مستندات:راهنمای Migration · بلاگ · npmقبلqueryFn: async ({ signal }) => { const res = await axios.get('/users', { signal, params: { page: 1 } }) return res.data } بعدimport { createFetch } from 'tanstack-fetch' const api = createFetch({ baseUrl: 'https://api.example.com' }) queryFn: ({ signal }) => api.get('/users', { signal, query: { page: 1 } }) یک کلاینت، دیتای مستقیم، FetchError تایپ‌شده و پشتیبانی از AbortSignal از ابتدا.CLI Migrationابتدا پکیج را نصب کنید:npm install tanstack-fetch بعد می‌توانید migration را به‌صورت dry run اجرا کنید:npx tanstack-fetch migrate --from axios --dir ./src npx tanstack-fetch migrate --from all --dir ./src یا migration و scaffold را هم‌زمان انجام دهید:npx tanstack-fetch migrate \ --from axios \ --framework react \ --dir ./src \ --write npx tanstack-fetch migrate \ --from ofetch \ --framework nuxt \ --write npx tanstack-fetch migrate \ --from fetch \ --framework nextjs \ --write فلگ‌هافلگمعنی--fromaxios | ky | ofetch | fetch | all--frameworkreact | vue | nuxt | nextjs--provider / --no-providerفقط React؛ با یا بدون FetchProvider--writerewrite امن + scaffold--write عمداً محافظه‌کار است.الگوهای شناخته‌شده و امن rewrite می‌شوند؛ اما مواردی مثل پارامترهای پیچیده query، interceptorها یا منطق res.ok ممکن است فقط گزارش شوند تا خودتان آن‌ها را بررسی و اصلاح کنید.بنابراین بعد از migration حتماً گزارش CLI را مرور کنید.نگاشت سریع APIازبهaxios.create({ baseURL })createFetch({ baseUrl })res.dataخود api.get دیتا را برمی‌گرداند.json()خود api.get دیتا را برمی‌گرداندparams در AxiosquerysearchParams در KyqueryisAxiosErrorisFetchErrorدر مورد fetch خام، migration بیشتر گزارش‌محور است.CLI محل‌هایی مثل:fetch(...) و:res.ok را پیدا می‌کند و گزارش می‌دهد تا بتوانید آن بخش را متناسب با منطق پروژه خودتان بازنویسی کنید.اسکفولد برای فریم‌ورک‌های مختلفCLI می‌تواند بر اساس فریم‌ورک شما ساختار اولیه را هم ایجاد کند:فریم‌ورکخروجیReactapi.ts + queries/users.ts + Provider اختیاریVueapi.ts + pluginNuxtapi + plugin + useApiNext.jsclient + api.server.ts با cookie و ssr-forwardReact و FetchProviderدر React، اگر migration را با --write اجرا کنید، CLI می‌تواند درباره استفاده از FetchProvider از شما سؤال کند:Use FetchProvider for React? [y/N] پیش‌فرض N است؛ یعنی بدون Provider.در این حالت می‌توانید client را مستقیماً به queryها پاس بدهید:client: api اگر نمی‌خواهید CLI سؤال بپرسد، می‌توانید صریحاً یکی از این دو فلگ را استفاده کنید:--provider یا:--no-provider چرا tanstack-fetch؟هدف اصلی این پروژه ساده است: HTTP layer باید با مدل استفاده از TanStack Query هماهنگ باشد.چند قابلیت مهم:مناسب برای استفاده مستقیم در queryFn و mutationFnخطاهای تایپ‌شده با اطلاعاتی مثل status و bodyhandlerهای قابل تنظیم برای status codeهای مختلف، از جمله 401 تا 429refresh token و جلوگیری از refreshهای هم‌زمانپشتیبانی از SSR و forwarding کوکیSSE با Authorization و قابلیت resumeپشتیبانی از AbortSignalهسته HTTP حدود 4.8KB gzipاگر می‌خواهید تفاوت آن با Axios، Ky، Ofetch و Fetch را دقیق‌تر ببینید:مقایسه کامل HTTP Clientهاامتحان کنیداگر می‌خواهید ابتدا ببینید پروژه شما چه چیزهایی برای migration دارد، بدون تغییر فایل‌ها شروع کنید:npx tanstack-fetch migrate \ --from all \ --dir ./src و اگر آماده rewrite و scaffold هستید:npx tanstack-fetch migrate \ --from all \ --framework react \ --write \ --no-provider لینک‌هاسایت tanstack-fetchبلاگ نسخه 1.6.2راهنمای MigrationGitHubnpmاگر روی یک پروژه واقعی این CLI را اجرا کردید، خوشحال می‌شوم بدانم چه migrationهایی را درست تشخیص داد، چه چیزهایی را از دست داد و کجا نیاز به اصلاح دستی داشت.همین بازخوردها می‌توانند مشخص کنند که transformerهای نسخه‌های بعدی باید روی چه الگوهایی تمرکز کنند.

tanstack-fetch 1.6.1؛ تایپ‌گذاری Path Params در API

garmabi.mohammad73 — Sat, 03 Oct 2026 10:42:04 +0330

tanstack-fetch 1.6.1 (params typed)نسخه 1.6.1 پکیج tanstack-fetch منتشر شد.تمرکز اصلی این نسخه روی بهبود Type Safety در URL Parameters است؛ به‌خصوص زمانی که API شما مسیرهایی مانند /users/:id یا /users/{id} دارد.در این نسخه، دیگر لازم نیست برای تعریف مسیرهای API یک Route Map جداگانه ایجاد کنید.چه چیزی تغییر کرده؟در نسخه 1.6.0، یک Route Map با createFetch() معرفی شده بود.در نسخه 1.6.1 این رویکرد حذف شده و به‌جای آن، params مستقیماً در کنار Type مربوط به Response تعریف می‌شود.مثلاً:type User = { id: string name: string } type Params = { id: number } await api.get('/users/:id', { params: { id }, }) حالا TypeScript می‌تواند بررسی کند که:پارامتر id واقعاً در مسیر وجود داشته باشد.params شامل کلید موردنیاز مسیر باشد.نوع پارامتر صحیح باشد.پارامتر اضافی که در URL وجود ندارد استفاده نشود.برای مثال، این کد خطا خواهد داشت:await api.get('/users/:id', { params: {}, }) یا:await api.get('/users/:id', { params: { userId: 1 }, }) چون :id در مسیر وجود دارد و userId با آن مطابقت ندارد.Type-safe Body برای POST، PUT و PATCHدر متدهای write نیز امکان مشخص کردن Type مربوط به body اضافه شده است.مثلاً:await api.post('/users', { body: { name: 'Ada', }, }) یا برای یک مسیر دارای parameter:await api.put('/users/:id', { params: { id, }, body: { name: 'Ada', }, }) این الگو برای POST، PUT، PATCH و request قابل استفاده است و در DELETE و upload نیز همین مدل type-safe برای params در دسترس است.چرا دو یا سه Generic؟این بخش به یک محدودیت TypeScript برمی‌گردد.وقتی فقط Response Type را مشخص می‌کنیم:api.get('/users/:id') TypeScript ممکن است literal بودن مسیر را از دست بدهد و در نتیجه بررسی :id دیگر به شکل مورد انتظار انجام نشود.به همین دلیل در نسخه 1.6.1 می‌توانیم Typeهای مختلف را جداگانه مشخص کنیم:api.get< User, // Response { id: number } // Params >('/users/:id', { params: { id }, }) و در متدهایی که Body دارند:api.post< User, // Response NoParams, // Params { name: string } // Body >('/users', { body: { name: 'Ada', }, }) تفاوت 1.6.0 و 1.6.1نسخه 1.6.0نسخه 1.6.1Route Map با createFetch()حذف Route Mapparams نسبتاً آزادparams کاملاً type-safeتعریف مسیرها در Route MapType پارامتر کنار Response—Type-safe Body برای write methodsارتقا به نسخه جدیداگر از نسخه‌های قبلی استفاده می‌کنید:npm install tanstack-fetch@1.6.1 نسخه 1.6.1 بیشتر از اینکه یک تغییر ظاهری در API باشد، روی یک مسئله مهم تمرکز دارد:هرچه بیشتر بتوانیم قرارداد API را در زمان توسعه توسط TypeScript بررسی کنیم، خطاهای runtime کمتری خواهیم داشت.این نسخه تلاش می‌کند همین موضوع را برای URL parameters و request body ساده‌تر و صریح‌تر کند.پروژه tanstack-fetch یک HTTP client تایپ‌شده بر پایه Fetch API است که برای استفاده در پروژه‌های TypeScript و در کنار TanStack Query طراحی شده است.tanstack-fetch یک پروژه مستقل است و پکیج رسمی TanStack نیست.اگر از tanstack-fetch استفاده می‌کنید، خوشحال می‌شوم تجربه‌تان درباره طراحی API و Type Safety را بدانم.

tanstack-fetch 1.5.0؛ پشتیبانی از Vue 3 و Nuxt

garmabi.mohammad73 — Thu, 01 Oct 2026 17:30:55 +0330

tanstack-fetch 1.5.0؛ پشتیبانی از Vue 3 و Nuxtنسخه 1.5.0 از tanstack-fetch منتشر شد.در این نسخه، پشتیبانی رسمی از Vue 3 و Nuxt اضافه شده است؛ با همان مدل ذهنیای که کاربران TanStack Query به آن عادت دارند:در حالت موفق، داده را برگرداندر خطای HTTP، یک FetchError پرتاب کنAbortSignal را به درخواست منتقل کنهدف tanstack-fetch این است که یک HTTP client کوچک، typed و قابل استفاده در کنار TanStack Query باشد؛ بدون اینکه خودش نقش data-fetching library را بازی کند.نکته: tanstack-fetch یک پکیج رسمی TanStack نیست. این پروژه مستقل است و با الهام از مدل ذهنی TanStack Query طراحی شده است.در نسخه 1.5.0 چه چیزی اضافه شده؟مهمترین تغییر این نسخه، اضافه شدن helperهای رسمی برای Vue 3 و Nuxt است.ExportکاربردcreateFetchPluginنصب کلاینت با app.use یا استفاده در NuxtprovideFetchClientProvide کردن کلاینت در کامپوننت والدuseFetchدریافت کلاینت مشترک از injectuseSseاتصال به SSE و مدیریت وضعیت streamیکی از نکات مهم این طراحی این است که helperهای Vue باعث نمیشوند هستهی HTTP بزرگتر و پیچیدهتر شود.هستهی HTTP در حدود 4.81KB gzip است و قابلیتهایی مثل SSE، پلاگینها، React، Vue، tRPC و DevTools به صورت جداگانه قابل import هستند.useFetch قرار نیست HTTP Request بزنداگر با Nuxt کار کرده باشید، احتمالاً اسم useFetch برایتان آشناست.اما useFetch در tanstack-fetch/vue با useFetch خود Nuxt یک تفاوت اساسی دارد.این helper فقط کلاینتی را که قبلاً provide شده دریافت میکند:import { useFetch as useFetchClient } from 'tanstack-fetch/vue'بنابراین:const api = useFetch()به معنی ارسال یک HTTP request نیست.در واقع api همان instance مربوط به createFetch است که از طریق Vue inject دریافت شده است.این تفکیک باعث میشود مسئولیتها مشخص باقی بمانند:createFetch → مدیریت HTTPuseFetch → دسترسی به clientTanStack Query → مدیریت server stateuseSse → مدیریت SSEاستفاده در Vue 3ابتدا یک client ایجاد میکنیم:import { createFetch } from 'tanstack-fetch' import { createFetchPlugin, useFetch } from 'tanstack-fetch/vue' const api = createFetch({ baseUrl: import.meta.env.VITE_API_URL, getToken: () => localStorage.getItem('access_token'), }) createApp(App) .use(createFetchPlugin({ client: api })) .mount('#app')حالا در component میتوانیم همان client را دریافت کنیم: