‏Ky: کلاینت HTTP کوچیک بر پایهٔ Fetch

Ky یه کلاینت HTTP کوچیک از sindresorhus هست که روی Fetch API ساخته شده و هیچ وابستگی‌ای نداره. تو مرورگرهای مدرن، Node.js، Bun و Deno کار می‌کنه. ایده‌ش ساده‌ست: همون fetch، ولی با یه API تمیزتر و کلی قابلیت که معمولاً خودت باید دستی بنویسی.

مثال اصلی README نشون می‌ده چقدر کد کم می‌شه. با Ky یه درخواست POST با بدنهٔ JSON و خوندن جواب، یه خطه:

import ky from 'ky';

const json = await ky.post('https://example.com', {json: {foo: true}}).json();

همین کار با fetch خالی یعنی خودت JSON.stringify کنی، هدر content-type بذاری، response.ok رو چک کنی و یه کلاس خطا بسازی. مزیت‌های اصلی نسبت به fetch: شورتکات برای متدها مثل ky.post()، خطا دادن روی وضعیت‌های غیر 2xx با HTTPError، ری‌ترای خودکار، تایم‌اوت، نمایش پیشرفت آپلود و دانلود، گزینهٔ baseUrl، ساختن instance با تنظیمات پیش‌فرض و هوک‌ها. می‌تونی مستقیم ky.get(input).json() بزنی و Ky هدر Accept مناسب رو هم خودش تنظیم می‌کنه.

تو TypeScript هم خروجی .json() به‌صورت پیش‌فرض unknown هست، نه any. یعنی تا تایپ ندی، کامپایلر نمی‌ذاره بی‌حساب‌وکتاب ازش استفاده کنی. پاسخ رو می‌شه با یه validator سازگار با Standard Schema (یعنی استاندارد مشترکی که Zod و Valibot پیاده‌ش کردن) اعتبارسنجی کرد. اگه داده با schema جور نباشه، SchemaValidationError پرتاب می‌شه.

سیستم ری‌ترای خیلی کامله. به‌صورت پیش‌فرض ۲ بار دوباره تلاش می‌کنه، فقط برای متدهایی مثل get، put، head و delete، و برای کدهای 408، 413، 429، 500، 502، 503 و 504. تأخیر بین تلاش‌ها نمایی بالا می‌ره و اگه سرور هدر Retry-After بفرسته، Ky بهش احترام می‌ذاره. گزینهٔ jitter هم یه کم تصادفی‌بودن به تأخیر اضافه می‌کنه تا همهٔ کلاینت‌ها با هم به سرور هجوم نبرن.

برای کنترل بیشتر، shouldRetry تصمیم می‌گیره که اصلاً دوباره تلاش بشه یا نه و از چک‌های پیش‌فرض اولویت داره. ولی هوک beforeRetry بعد از قطعی شدن تلاش دوباره صدا زده می‌شه و برای تغییر درخواسته. گزینه‌های baseUrl و prefix هم فرق دارن: baseUrl طبق استاندارد URL رو resolve می‌کنه، ولی prefix قبل از resolve شدن به اول input چسبونده می‌شه.

نکات کلیدی:

• Ky بدون وابستگی‌ه و روی مرورگر، Node.js، Bun و Deno کار می‌کنه.
• وضعیت‌های غیر 2xx خودکار HTTPError پرتاب می‌کنن.
• ری‌ترای پیش‌فرض: ۲ بار، برای کدهای 408، 413، 429، 500، 502، 503 و 504.
• خروجی .json() تو TypeScript به‌صورت پیش‌فرض unknown هست، نه any.
• اعتبارسنجی پاسخ با Standard Schema (مثل Zod 3.24 به بالا) پشتیبانی می‌شه.