Series: TypeScript Basics Lesson 34

Overload signatures

TypeScript'da overload imzolari: literal parametr orqali callback type'ini bog'lash, JSDoc, mustaqil shartnomalar, implementation bilan moslik, ortiqcha overload'lar va interface/.d.ts dagi imzolar.

34-dars

Overload signatures

Overload imzolari (overload signatures) funksiyaning tashqi dunyo uchun "menyusi": qaysi argumentlar bilan chaqirish mumkin va har holatda nima qaytadi. Ayniqsa, bir parametrning qiymati boshqa parametrning type'ini belgilaganda foydali.

// ❌ Muammo: bitta umumiy imzo — handler qanday event olishini bilmaydi
function on(event: string, handler: (e: Event) => void): void {
  document.addEventListener(event, handler);
}

on("keydown", (e) => {
  console.log(e.key);
  // ❌ Property 'key' does not exist on type 'Event'.
});

on("clik", () => {}); // 🐛 imlo xatosi — TS indamaydi, event hech qachon ishlamaydi
// ✅ Yechim: har bir event nomi uchun alohida overload imzosi
function on(event: "click", handler: (e: MouseEvent) => void): void;
function on(event: "keydown", handler: (e: KeyboardEvent) => void): void;
function on(event: string, handler: (e: Event) => void): void {
  document.addEventListener(event, handler);
}

on("click", (e) => console.log(e.clientX)); // ✅ e: MouseEvent
on("keydown", (e) => console.log(e.key));   // ✅ e: KeyboardEvent
on("clik", () => {});
// ❌ No overload matches this call.
//      Overload 1 of 2, '(event: "click", handler: (e: MouseEvent) => void): void', gave the following error.
//        Argument of type '"clik"' is not assignable to parameter of type '"click"'.
//      Overload 2 of 2, '(event: "keydown", handler: (e: KeyboardEvent) => void): void', gave the following error.
//        Argument of type '"clik"' is not assignable to parameter of type '"keydown"'.

Literal type va callback typing overload imzolari orqali bir-biriga bog'landi.

Qanday ishlaydi?

1. Overload imzosi — tanasiz e'lon

Har bir imzo tanasiz yoziladi va ; bilan tugaydi. Uning har birini alohida JSDoc bilan hujjatlash mumkin — IDE qaysi imzo tanlanganini va uning izohini ko'rsatadi.

/** Sonni belgilangan aniqlikda formatlaydi */
function format(value: number, digits: number): string;
/** Sanani ISO formatda qaytaradi */
function format(value: Date): string;
function format(value: number | Date, digits?: number): string {
  return value instanceof Date ? value.toISOString() : value.toFixed(digits);
}

format(3.14159, 2); // tooltip: "Sonni belgilangan aniqlikda formatlaydi"
format(new Date()); // tooltip: "Sanani ISO formatda qaytaradi"

IDE'da format ustiga kursor olib borilganda (+1 overload) yozuvi chiqadi — bu qo'shimcha imzolar borligini bildiradi.

2. Har bir imzo — mustaqil shartnoma

Imzolar o'zaro aralashmaydi: bir imzodagi parametr boshqa imzodagi parametr bilan birga ishlatilmaydi.

format(new Date(), 2);
// ❌ No overload matches this call.
//      Overload 1 of 2, '(value: number, digits: number): string', gave the following error.
//        Argument of type 'Date' is not assignable to parameter of type 'number'.
//      Overload 2 of 2, '(value: Date): string', gave the following error.
//        Expected 1 arguments, but got 2.

Implementation digits? qabul qilsa ham, Date + digits kombinatsiyasi hech bir imzoda yo'q — demak, taqiqlangan. Overload imzolarining asosiy kuchi shu: ruxsat etilgan kombinatsiyalarni aniq sanab beradi.

3. Imzolar implementation bilan mos bo'lishi shart

Har bir overload imzosi implementation imzosiga "sig'ishi" kerak: parametrlar va qaytariladigan type implementation'dagilar bilan mos bo'lishi lozim.

function toText(value: string): string;
function toText(value: boolean): string;
// ❌ This overload signature is not compatible with its implementation signature.
function toText(value: string | number): string {
  return String(value);
}

boolean implementation'ning string | number parametriga to'g'ri kelmaydi. Qaytariladigan type ham xuddi shunday tekshiriladi.

4. Ortiqcha overload'lardan qochish

Faqat oxirgi parametr bor-yo'qligi yoki bitta parametr type'i bilan farq qiladigan imzolar keraksiz murakkablik qo'shadi.

// ❌ Faqat oxirgi parametr bilan farq qiladi
function greet(name: string): string;
function greet(name: string, title: string): string;
function greet(name: string, title?: string): string {
  return title ? `${title} ${name}` : name;
}

// ✅ Optional parametr yetarli
function greet2(name: string, title?: string): string {
  return title ? `${title} ${name}` : name;
}

// ❌ Faqat bitta parametr type'i farq qiladi, qaytish bir xil
declare function getId(user: { id: number }): number;
declare function getId(user: { userId: number }): number;

// ✅ Union parametr yetarli (12-dars)
function getId2(user: { id: number } | { userId: number }): number {
  return "id" in user ? user.id : user.userId;
}
Imzolar o'rtasidagi farq Overload kerakmi?
Faqat oxirgi parametr bor/yo'q ❌ optional parametr
Bitta parametr type'i, qaytish bir xil ❌ union
Qaytish type'i argumentga bog'liq ✅ ha
Bir parametr boshqasining type'ini belgilaydi ✅ ha
Argumentlar soni turlicha, ma'nosi boshqa ✅ ha

5. Interface, type va declaration fayllardagi imzolar

Overload imzolari faqat function e'lonlarida emas, method va call signature sifatida ham yoziladi. Bu holda implementation umuman yo'q — faqat imzolar bor.

interface Settings {
  get(key: "theme"): "light" | "dark";
  get(key: "fontSize"): number;
  get(key: "language"): string;
}

declare const settings: Settings;

const t = settings.get("theme");    // t: "light" | "dark"
const f = settings.get("fontSize"); // f: number

Kutubxonalarning .d.ts fayllarida overload'lar aynan shunday — tanasiz imzolar ro'yxati sifatida yoziladi:

declare function parseValue(input: string): number;
declare function parseValue(input: string[]): number[];

Bunday "kalit → type" bog'lanishlari ko'payganda, imzolar o'rniga mapped type va generic ishlatiladi (keyof + generics) — bitta imzo barcha kalitlarni qamrab oladi.

Eng ko'p uchraydigan xato

Yangi overload imzosini qo'shib, implementation'ni kengaytirishni unutish. Funksiya avval ikki holatni qo'llab-quvvatlagan. Yangi talab chiqadi va dasturchi faqat yangi imzo qo'shadi:

function createId(prefix: string): string;
function createId(num: number): string;
function createId(parts: string[]): string; // yangi qo'shildi
// ❌ This overload signature is not compatible with its implementation signature.
function createId(input: string | number): string {
  return `id-${input}`;
}

Nega bunday bo'ladi? Overload imzolari va implementation alohida yoziladi, shuning uchun ularni sinxron saqlash oson unutiladi. TS har bir imzo implementation'ga sig'ishini talab qiladi: string[] esa string | number ichida yo'q.

Xatoni tezda yo'qotish uchun implementation parametri kengaytiriladi — lekin bu yarim yechim:

function createId(input: string | number | string[]): string {
  return `id-${input}`; // 🐛 TS jim, lekin ["a","b"] → "id-a,b"
}

TS faqat imzolar mosligini tekshiradi, yangi holat tanada to'g'ri ishlanganini emas.

// ✅ Yechim: implementation'ni kengaytiramiz VA yangi holatni alohida ishlaymiz
function createId(prefix: string): string;
function createId(num: number): string;
function createId(parts: string[]): string;
function createId(input: string | number | string[]): string {
  if (Array.isArray(input)) {
    return `id-${input.join("-")}`; // yangi holat
  }
  return `id-${input}`;
}

createId(["user", "42"]); // "id-user-42" ✅

Yangi imzo qo'shganingizda doim ikki joyni tekshiring: implementation imzosi va implementation tanasidagi narrowing.

Esda tuting: har bir overload imzosi — va'da; yangi va'da qo'shilganda uni bajaradigan kod ham implementation'ga qo'shilishi kerak, aks holda TS faqat imzolarni tekshirib, mantiqiy xatoni o'tkazib yuboradi.