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

در نسخه‌ی 1.7.1 از tanstack-fetch روی چند مشکل در مسیر اصلی ارسال درخواست تمرکز کرده‌ام؛ مواردی که شاید در مثال‌های ساده دیده نشوند، اما در پروژه‌های واقعی، SSR و محیط‌های Node.js می‌توانند دردسرساز شوند.

این نسخه API جدیدی اضافه نمی‌کند. هدف آن قابل‌پیش‌بینی‌تر کردن رفتار درخواست‌ها و اصلاح چند edge case مهم است.

برای نصب:

npm install [email protected]

۱. تشخیص اشتباه پارامترهای مسیر در 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 [email protected]

مشاهده توضیحات کامل انتشار:

https://mohamadgarmabi.github.io/tanstack-fetch/blog/tanstack-fetch-1-7-1

tanstack-fetch یک پروژه‌ی مستقل برای مدیریت لایه‌ی HTTP در کنار ابزارهایی مانند TanStack Query است و پکیج رسمی TanStack نیست.

— محمد گرمابی