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.