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

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

از یک 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<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ها امکان مشاهده وضعیت اتصال و پیام‌های ورودی و خروجی را فراهم می‌کنند.

۵. بهبود DevTools

در نسخه 1.8.0 دو تب جدید به DevTools اضافه شده است:

  • WS برای WebSocket و WebTransport

  • Stream برای NDJSON

همچنین برای هر Connection یک Message Log در نظر گرفته شده تا بررسی و Debug کردن ارتباطات زنده ساده‌تر شود.

CLI نیز بهبود پیدا کرده است و دستور doctor می‌تواند استفاده مستقیم از new WebSocket و new EventSource را شناسایی کند.

۶. کاهش حجم Core در نسخه 2.0.0

یکی از مهم‌ترین تغییرات معماری نسخه 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ها همچنان قابلیت‌های قبلی خود را حفظ کرده‌اند.

۷. 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 <Message, Params, Send> // SSE / NDJSON <Message, Params>

۸. اصلاحات مهم در Streaming

در نسخه 2.0.0 چند مشکل مهم در چرخه اجرای NDJSON نیز برطرف شده است:

  • ارسال صحیح ReadableStream در Node.js با duplex: 'half'

  • اجرای onRequestError هنگام خطاهای شبکه

  • لغو فوری Stream هنگام Abort شدن در زمان Retry Delay

۹. مهاجرت از نسخه 1.7.1 به 2.0.0

برای ارتقا:

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

لینک‌های پروژه:

  • مستندات: https://mohamadgarmabi.github.io/tanstack-fetch/

  • GitHub: https://github.com/mohamadgarmabi/tanstack-fetch

  • npm: https://www.npmjs.com/package/tanstack-fetch

  • Release Notes: https://mohamadgarmabi.github.io/tanstack-fetch/blog/tanstack-fetch-2-0-0

این پروژه یک کتابخانه مستقل و Open Source است و محصول رسمی TanStack نیست.

خوشحال می‌شوم تجربه و نظرتان را درباره معماری جدید و قابلیت‌های نسخه 2.0.0 بدانم.

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