از یک 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 را بررسی میکنیم.
یکی از مهمترین قابلیتهای نسخه 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 قرار نمیگیرد.
در کنار WebSocket، قابلیت WebTransport نیز اضافه شده است.
WebTransport مبتنی بر HTTP/3 است و امکان استفاده از Datagram و سایر الگوهای ارتباطی را فراهم میکند.
const connection = api.transport('/live', { // WebTransport options })
این قابلیت از تنظیماتی مانند serverCertificateHashes و پیادهسازی سفارشی از طریق createWebTransport پشتیبانی میکند.
قابلیت مهم دیگر api.stream() است.
در پاسخهای JSON معمولی، معمولاً باید منتظر دریافت کل پاسخ بمانیم؛ اما با NDJSON سرور میتواند دادهها را بهصورت تدریجی ارسال کند.
const stream = api.stream<Message>('/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ها اضافه شدهاند:
onLiveOpen
onLiveMessage
onLiveClose
این Hookها امکان مشاهده وضعیت اتصال و پیامهای ورودی و خروجی را فراهم میکنند.
در نسخه 1.8.0 دو تب جدید به DevTools اضافه شده است:
WS برای WebSocket و WebTransport
Stream برای NDJSON
همچنین برای هر Connection یک Message Log در نظر گرفته شده تا بررسی و Debug کردن ارتباطات زنده سادهتر شود.
CLI نیز بهبود پیدا کرده است و دستور doctor میتواند استفاده مستقیم از new WebSocket و new EventSource را شناسایی کند.
یکی از مهمترین تغییرات معماری نسخه 2.0.0 کاهش حجم Core است.
<escape>5.14KB → 3.57KB gzip</escape>
یعنی تقریباً ۳۰ درصد کاهش حجم.
در این نسخه، Core فقط روی مسئولیتهای اصلی HTTP متمرکز شده است:
مدیریت Base URL
Headers
Timeout
Interceptors
Fetch implementation
Credentials
Retry 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ها همچنان قابلیتهای قبلی خود را حفظ کردهاند.
در نسخه 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 <Message, Params, Send> // SSE / NDJSON <Message, Params>
در نسخه 2.0.0 چند مشکل مهم در چرخه اجرای NDJSON نیز برطرف شده است:
ارسال صحیح ReadableStream در Node.js با duplex: 'half'
اجرای onRequestError هنگام خطاهای شبکه
لغو فوری Stream هنگام Abort شدن در زمان Retry Delay
برای ارتقا:
npm install [email protected]
چند نکته مهم در 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
لینکهای پروژه:
این پروژه یک کتابخانه مستقل و Open Source است و محصول رسمی TanStack نیست.
خوشحال میشوم تجربه و نظرتان را درباره معماری جدید و قابلیتهای نسخه 2.0.0 بدانم.