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

نسخه 1.6.1 پکیج tanstack-fetch منتشر شد.

تمرکز اصلی این نسخه روی بهبود Type Safety در URL Parameters است؛ به‌خصوص زمانی که API شما مسیرهایی مانند /users/:id یا /users/{id} دارد.

در این نسخه، دیگر لازم نیست برای تعریف مسیرهای API یک Route Map جداگانه ایجاد کنید.

چه چیزی تغییر کرده؟

در نسخه 1.6.0، یک Route Map با createFetch<Routes>() معرفی شده بود.

در نسخه 1.6.1 این رویکرد حذف شده و به‌جای آن، params مستقیماً در کنار Type مربوط به Response تعریف می‌شود.

مثلاً:

type User = {
  id: string
  name: string
}

type Params = {
  id: number
}

await api.get<User, Params>('/users/:id', {
  params: { id },
})

حالا TypeScript می‌تواند بررسی کند که:

• پارامتر id واقعاً در مسیر وجود داشته باشد.

• params شامل کلید موردنیاز مسیر باشد.

• نوع پارامتر صحیح باشد.

• پارامتر اضافی که در URL وجود ندارد استفاده نشود.

برای مثال، این کد خطا خواهد داشت:

await api.get<User, Params>('/users/:id', {
  params: {},
})

یا:

await api.get<User, { userId: number }>('/users/:id', {
  params: { userId: 1 },
})

چون :id در مسیر وجود دارد و userId با آن مطابقت ندارد.

Type-safe Body برای POST، PUT و PATCH

در متدهای write نیز امکان مشخص کردن Type مربوط به body اضافه شده است.

مثلاً:

await api.post<User, NoParams, { name: string }>('/users', {
  body: {
    name: 'Ada',
  },
})

یا برای یک مسیر دارای parameter:

await api.put<User, Params, { name: string }>('/users/:id', {
  params: {
    id,
  },
  body: {
    name: 'Ada',
  },
})

این الگو برای POST، PUT، PATCH و request قابل استفاده است و در DELETE و upload نیز همین مدل type-safe برای params در دسترس است.

چرا دو یا سه Generic؟

این بخش به یک محدودیت TypeScript برمی‌گردد.

وقتی فقط Response Type را مشخص می‌کنیم:

api.get<User>('/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<Routes>()حذف Route Mapparams نسبتاً آزادparams کاملاً type-safeتعریف مسیرها در Route MapType پارامتر کنار Response—Type-safe Body برای write methods

ارتقا به نسخه جدید

اگر از نسخه‌های قبلی استفاده می‌کنید:

npm install [email protected]

نسخه 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 را بدانم.