Seriya: TypeScript Basics Dars 89

Type-safe API client

TypeScript'da type-xavfsiz API client: barcha endpoint'larni bitta Api xaritasida tavsiflash, URL'dan avtomatik body va javob type'i, TS ushlaydigan xatolar va real vositalar.

89-dars

Type-safe API client

Barcha endpoint'larni bitta type xaritasida tavsiflaysiz: qaysi URL, qaysi metod, nima yuboriladi, nima qaytadi. Keyin client funksiyasi shu xaritadan foydalanadi va siz URL yozishingiz bilan TS body va javob type'ini o'zi biladi.

Oddiy fetchJson<User>(...) (85-dars) dan farqi: u yerda type'ni har safar qo'lda yozasiz va xato qilishingiz mumkin. Bu yerda type URL'dan avtomatik chiqadi.

1. Endpoint xaritasi

type User = { id: number; name: string; email: string };
type Product = { id: number; title: string; price: number };

type Api = {
  "GET /users": {
    response: User[];
  };
  "GET /users/:id": {
    params: { id: number };
    response: User;
  };
  "POST /users": {
    body: { name: string; email: string };
    response: User;
  };
  "GET /products": {
    query: { page?: number; search?: string };
    response: Product[];
  };
};

Butun API "shartnomasi" bitta joyda.

2. Client funksiyasi

type Route = keyof Api;

// endpointda bor maydonlarni majburiy qiladi
type Options<R extends Route> = Omit<Api[R], "response">;

async function api<R extends Route>(
  route: R,
  ...[options]: {} extends Options<R> ? [Options<R>?] : [Options<R>]
): Promise<Api[R]["response"]> {
  const [method, rawPath] = route.split(" ");
  const opts = (options ?? {}) as {
    params?: Record<string, unknown>;
    query?: Record<string, unknown>;
    body?: unknown;
  };

  // :id → 5
  let path = rawPath.replace(/:(\w+)/g, (_, key) => String(opts.params?.[key]));

  if (opts.query) {
    const qs = new URLSearchParams();
    for (const [k, v] of Object.entries(opts.query)) {
      if (v !== undefined) qs.set(k, String(v));
    }
    path += `?${qs}`;
  }

  return fetchJson(`/api${path}`, {
    method,
    headers: { "Content-Type": "application/json" },
    body: opts.body ? JSON.stringify(opts.body) : undefined,
  });
}

Bu kodni bir marta yozasiz. Murakkab qismi faqat shu yerda. Ishlatadigan TS vositalari — keyof (54-dars), indexed access Api[R]["response"] (56-dars), generic constraint R extends Route (52-dars) — oldingi darslardan tanish.

3. Ishlatish (asosiy foyda shu yerda)

const users = await api("GET /users");
// users: User[]  ← type'ni yozmadik, o'zi chiqdi

const user = await api("GET /users/:id", { params: { id: 5 } });
// user: User

const created = await api("POST /users", {
  body: { name: "Ali", email: "[email protected]" },
});

const products = await api("GET /products", { query: { search: "telefon" } });

TS ushlaydigan xatolar

api("GET /user");                               // ❌ bunday endpoint yo'q
api("GET /users/:id");                          // ❌ params berilmadi
api("GET /users/:id", { params: { id: "5" } }); // ❌ id number bo'lishi kerak
api("POST /users", { body: { name: "Ali" } });  // ❌ email yo'q
api("GET /products", { query: { sort: "x" } }); // ❌ sort query'da yo'q

Editor'da api(" yozsangiz, barcha endpoint'lar ro'yxati avtokomplit bo'lib chiqadi.

Real loyihada

Bu g'oyani tayyor holatda beradigan vositalar bor:

  • OpenAPI → TS generatorlar (openapi-typescript + openapi-fetch): backend Swagger'idan xaritani avtomatik yasaydi.
  • tRPC: backend va frontend ham TS bo'lsa, xarita umuman yozilmaydi.
  • Zod bilan birga ishlatilsa, javob runtime'da ham tekshiriladi.

Eslab qolish uchun

  • Hamma endpoint'lar bitta Api type'ida.
  • Client generic: R extends keyof Api.
  • Type URL'dan chiqadi, qo'lda <User> yozilmaydi.
  • Endpoint o'zgarsa, ishlatilgan hamma joyda xato chiqadi, hech narsa unutilmaydi.