TypeScript va npm kutubxonalari: turlar qayerdan keladi — paket, @types yoki o'zingiz

Qisqacha: npm paketining turlari uch joydan keladi: paketning o'zidan (package.json dagi types yoki exports ichidagi "types"), @types/<nom> paketidan (DefinitelyTyped hamjamiyati yozgan) yoki o'zingiz yozgan declare module "<nom>" dan. Buni npm view <paket> types va npm view @types/<paket> version bilan bir daqiqada aniqlaysiz. @types versiyasi kutubxona versiyasiga mos bo'lishi kerak — eskirgan turlar to'g'ri kodni rad etadi yoki xato kodni o'tkazadi.

Bu darsda

• Paketda turlar bor-yo'qligini npm view bilan tekshirasiz va TS7016 xabaridagi maslahatni o'qiysiz.
• @types/* va DefinitelyTyped nima ekanini, versiyalar qanday mos kelishini tushuntirasiz.
• Turlarsiz paketga o'zingiz minimal declare module yozasiz — va declare module "x"; qisqa yozuvi nega xavfli ekanini bilasiz.
• Module augmentation bilan kutubxona turiga yangi metod qo'shasiz (dayjs plagini).
• types: [] (TypeScript 7 standarti) va @types paketlari qanday birga ishlashini bilasiz.

Oldin bilishingiz kerak: Declaration fayllari (.d.ts), Modullar TypeScript'da, npm'ga birinchi qadam.

1. Nega bu kerak?

O'tgan darsda o'z eski JS faylimizga .d.ts yozdik. Endi tashqi dunyo — npm. Haqiqiy loyihada kodning katta qismi boshqalar yozgan paketlar: sanalar, vaqt, matn bilan ishlash.

«Bahor» bron tizimiga uchta kichik paket kerak bo'ldi. Sardor ularni o'rnatdi (aniq versiyalar bilan, npm'ga birinchi qadam darsidagidek):

npm install --save-exact ms@2.1.3 latinize@2.0.0 dayjs@1.11.23

• ms — "2h" kabi matnni millisekundga aylantiradi (bron davomiyligi).
• latinize — "José Müller" → "Jose Muller": chet ellik mehmon ismini qidiruv uchun lotinlashtiradi.
• dayjs — sanalar bilan ishlash.

Birinchi npx tsc (kodda uchala import ham bor):

37-kutubxonalar/guests.ts(2,22): error TS7016: Could not find a declaration file for module 'latinize'. '…/node_modules/latinize/latinize.js' implicitly has an 'any' type.
  Try `npm i --save-dev @types/latinize` if it exists or add a new declaration (.d.ts) file containing `declare module 'latinize';`
37-kutubxonalar/guests.ts(3,16): error TS7016: Could not find a declaration file for module 'ms'. '…/node_modules/ms/index.js' implicitly has an 'any' type.
  Try `npm i --save-dev @types/ms` if it exists or add a new declaration (.d.ts) file containing `declare module 'ms';`

Tanish TS7016 (.d.ts darsidan), lekin endi ikkinchi qatori bor: "Agar mavjud bo'lsa, npm i --save-dev @types/latinize ni o'rnating yoki declare module 'latinize'; qatori bor .d.ts fayl qo'shing". dayjs uchun xato yo'q — u turlarini o'zi bilan olib keladi. Uch paket — uch xil holat. Bugun har birini ko'ramiz.

2. Uch manba

flowchart TD
  A["import x from 'paket'"] --> B{"Paketda types bormi?"}
  B -- "ha" --> C["1. Paketning o'z turlari"]
  B -- "yo'q" --> D{"@types/paket bormi?"}
  D -- "ha, versiya mos" --> E["2. npm i -D @types/paket"]
  D -- "yo'q yoki eski" --> F["3. O'zingiz: declare module"]

2.1 Paketning o'z turlari

TypeScript'da yozilgan yoki turlarini o'zi saqlaydigan paketlar .d.ts ni ichida olib keladi. tsc ularni package.json dagi ikki joydan topadi:

• types (yoki eski nomi typings) maydoni — "types": "index.d.ts".
• exports ichidagi "types" sharti — zamonaviy paketlarda, ESM va CommonJS uchun alohida.

Tekshirish uchun paketni o'rnatish shart emas — npm view registrdan o'qiydi. Bugun (2026-10-06) olingan haqiqiy natijalar:

npm view dayjs version types

version = '1.11.23'
types = 'index.d.ts'

date-fns da types maydoni yo'q, lekin exports da bor (npm view date-fns exports --json dan parcha):

{
  ".": {
    "import": {
      "types": "./index.d.ts",
      "default": "./index.js"
    },
    "require": {
      "types": "./index.d.cts",
      "default": "./index.cjs"
    }
  }
}

module: nodenext bilan tsc exports ni Node kabi o'qiydi: ESM importda — index.d.ts, require da — index.d.cts (Modullar TypeScript'da dagi .d.cts — CommonJS turlari). npmjs.com sahifasida bunday paket nomi yonida ko'k TS belgisi turadi.

2.2 @types/* — DefinitelyTyped

Ko'p mashhur paketlar JavaScript'da yozilgan va turlarini o'zi olib kelmaydi. Ular uchun DefinitelyTyped bor — GitHub'dagi ulkan hamjamiyat ombori (github.com/DefinitelyTyped/DefinitelyTyped). Undagi har bir papka npm'ga @types/<paket> nomi bilan chiqadi. @types/node ni Tur annotatsiyasi darsining mashqidan beri ishlatyapsiz — u ham shu yerdan.

(Hammasi npm view <paket> version bilan, 2026-10-06.) Qoida: @types versiyasining birinchi ikki raqami kutubxonaning birinchi ikki raqamiga mos bo'lishi kerak: ms 2.1 ↔ @types/ms 2.1, express 5 ↔ @types/express 5.0. Uchinchi raqam — turlarning o'z tuzatishlari, u farq qilishi tabiiy.

Jadvalning oxirgi qatoriga qarang: latinize — 2.0, @types/latinize esa — 0.2. Turlar eski versiya uchun yozilgan. Bu nimaga olib kelishini «Eskirgan @types» bo'limida ko'ramiz.

@types — --save-dev (devDependency) bilan o'rnatiladi: turlar faqat tsc ga kerak, ishlash paytida emas.

npm install --save-dev --save-exact @types/ms@2.1.0

Shundan keyin ms xatosi yo'qoladi. Endi turlar ishlaydi — va qiziq narsa ushlanadi:

e.ts(3,16): error TS2769: No overload matches this call.
  The last overload gave the following error.
    Argument of type '"2 soat"' is not assignable to parameter of type 'StringValue'.

ms("2 soat") — "hech bir overload mos emas: "2 soat" ni StringValue turiga berib bo'lmaydi". @types/ms da StringValue — template literal type: `${number}` + birlik ("h", "m", "Hours"…). O'zbekcha "soat" — birlik emas. JavaScript'da esa ms("2 soat") jim undefined qaytaradi (biz tekshirdik) — bron davomiyligi NaN bo'lib qolardi.

2.3 types: [] va @types — ziddiyat yo'q

tsconfig.json chuqur darsida ko'rdik: TypeScript 7 da types standart holatda []. Bu @types/ms ni o'chirib qo'yadimi? Yo'q. types faqat global turlarni boshqaradi — import qilinmasdan ko'rinadiganlarni (@types/node dagi process, Buffer). import ms from "ms" yozilganda tsc @types/ms ni modul sifatida o'zi topadi — types ro'yxatida bo'lmasa ham. Mashqlar papkamizda "types": ["node"] bor, @types/ms esa yo'q — va hammasi ishlaydi.

Tekshirib ko'ring: @types/date-fns paketi bor (2.6.3), lekin npm view uning deprecated maydonini ko'rsatadi: "This is a stub types definition. date-fns provides its own type definitions…". Uni o'rnatish kerakmi?

3. O'z e'loningiz: declare module "paket"

3.1 Eskirgan @types

latinize uchun @types/latinize@0.2.18 ni o'rnatib ko'rdik. tsc — toza. Lekin 2.0 versiyadagi yangi imkoniyat — ikkinchi parametr (o'z almashtirish jadvali) — rad etildi:

e.ts(4,31): error TS2554: Expected 1 arguments, but got 2.

"1 ta argument kutilgan edi, 2 ta berildi". latinize("Ñandú", { "Ñ": "NY" }) ishlash paytida to'g'ri ishlaydi (NYandú), turlar esa uni bilmaydi. Eskirgan @types ikki tomonlama xavfli: to'g'ri kodni rad etadi (bu holat) yoki o'chirilgan funksiyani "bor" deb ko'rsatadi (teskarisi — ishlash paytida TypeError).

Bunday holatda o'zingiz yozasiz. Faqat ishlatadigan qismini:

// 37-kutubxonalar/latinize.d.ts — latinize 2.0.0 uchun o'z e'lonimiz
// (@types/latinize 0.2.18 — eski 0.2 versiya uchun yozilgan)
declare module "latinize" {
  export default function latinize(
    str: string,
    characters?: Readonly<Record<string, string>>,
  ): string;
}

Bu — ambient modul e'loni: "latinize degan paket bor, uning standart eksporti — shunday funksiya". Fayl skript (yuqori darajada import/export yo'q) — .d.ts darsidagi declare module "*.svg" kabi. tsconfig.json ning include iga tushsa — yetarli.

Imzoni qayerdan oldik? Paketning README va manbasidan: node_modules/latinize/latinize.js da function latinize(str, characters = latinize.characters) va export default latinize. .d.ts — shu ikki qatorning tur tarjimasi.

3.2 TypeScript ushlamaydigan tuzoq: declare module "x";

TS7016 xabari eng tez yo'lni taklif qiladi — bitta qator:

// shims.d.ts
declare module "latinize";

Bu qisqa (shorthand) e'lon: "latinize bor, undan import qilingan hamma narsa — any". Xato yo'qoladi — lekin tekshiruv ham:

import latinize from "latinize";
const key = latinize.normalize("José");
console.log(key);

npx tsc — toza. Node esa:

TypeError: latinize.normalize is not a function

latinize da normalize yo'q — any hamma narsaga "ha" dedi. Qisqa e'lon TS7016 ni o'chiradi, xatolarni emas. Qoida: vaqtincha (ko'chish paytida) ishlatish mumkin, lekin TODO izohi bilan va tez orada haqiqiy imzolarga almashtiring. Bunday any qanday tarqalishini TypeScript best practices darsida ko'ramiz.

4. Module augmentation: kutubxona turini kengaytirish

4.1 dayjs plagini

dayjs'ning plagin tizimi bor: dayjs.extend(plagin) kutubxonaga yangi metod qo'shadi. «Bahor» SMS'larida sana o'zbekcha bo'lishi kerak — "6-oktabr". Metodni ishlash paytida qo'shish oson, lekin dayjs turlari uni bilmaydi. Module augmentation (modulni kengaytirish) — mavjud paketning turlariga o'z qismingizni qo'shish:

// 37-kutubxonalar/guests.ts (parcha)
import dayjs from "dayjs";
import type { PluginFunc } from "dayjs";

declare module "dayjs" {
  interface Dayjs {
    toUzbek(): string;
  }
}

const MONTHS = [
  "yanvar", "fevral", "mart", "aprel", "may", "iyun",
  "iyul", "avgust", "sentabr", "oktabr", "noyabr", "dekabr",
];

const uzbekDate: PluginFunc = (_options, DayjsClass) => {
  DayjsClass.prototype.toUzbek = function () {
    return `${this.date()}-${MONTHS[this.month()]}`;
  };
};
dayjs.extend(uzbekDate);
console.log(dayjs("2026-10-06").toUzbek()); // 6-oktabr

Uch qism:

O'tgan darsda declare module modul faylda TS2664 bergan edi — "mavjud modulni kengaytirish" deb tushunilgan, *.svg esa mavjud emas edi. Bu yerda aynan shu ma'no kerak: fayl modul (import bor), "dayjs" esa haqiqatan mavjud paket. Shuning uchun e'lon kengaytirish bo'ladi va dayjs'ning Dayjs interfeysi bilan birlashadi. const MONTHS qatorlari ixcham yozilgan — uzun ro'yxatni telefonda o'qish uchun.

4.2 Global turlarni kengaytirish va uning tuzog'i

Xuddi shu usul bilan standart turlarni ham kengaytirish mumkin — declare global ichida. Lekin turga qo'shish — kodga qo'shish emas:

declare global {
  interface Array<T> {
    last(): T | undefined;
  }
}
const prices = [35000, 28000];
console.log(prices.last());

tsc — xatosiz. Node esa:

TypeError: prices.last is not a function

Tur "last bor" dedi, uni hech kim yaratmadi. dayjs misolida dayjs.extend aynan shu ishni qilgan edi. Bu yerda ham amalga oshirish kerak:

declare global {
  interface Array<T> {
    last(): T | undefined;
  }
}
Object.defineProperty(Array.prototype, "last", {
  value: function <T>(this: T[]) {
    return this[this.length - 1];
  },
});
const prices = [35000, 28000];
console.log(prices.last()); // 28000

Ishladi — lekin bu usulni (standart obyektlarning prototipini o'zgartirish) ilova kodida qilmang: boshqa kutubxona ham last qo'shsa yoki kelajakda JavaScript'ning o'zida last paydo bo'lsa, to'qnashuv bo'ladi (JavaScript'ning mashhur tuzoqlari). Oddiy funksiya — last(prices) — xavfsizroq. Augmentation kutubxonaning rasmiy plagin tizimi bilan (dayjs kabi) ishlatiladi.

Mavjud xususiyat turini o'zgartirib bo'lmaydi:

declare global {
  interface Array<T> {
    length: string;
  }
}

Kompilyator:

TS2717: Subsequent property declarations must have the same type.  Property 'length' must be of type 'number', but here has type 'string'.

"Keyingi xususiyat e'lonlari bir xil turda bo'lishi kerak. length number bo'lishi kerak, bu yerda esa string". Declaration merging faqat qo'shadi — bor narsani o'zgartirmaydi.

5. Turlarni o'qish: node_modules ichiga qarash

Kutubxona turlari — eng aniq hujjat. VS Code'da import qilingan nom ustida F12 ("Go to Definition") — sizni .d.ts ga olib boradi: dayjs uchun node_modules/dayjs/index.d.ts, ms uchun node_modules/@types/ms/index.d.ts. Ikkinchisining boshi (izohlarsiz, telefon uchun qatorlarga bo'lingan):

declare function ms(
  value: number,
  options?: { long: boolean },
): string;

declare function ms(value: ms.StringValue): number;

Ikki overload: son bersangiz — satr (ms(7200000) → "2h"), satr bersangiz — son. StringValue esa birliklar ro'yxatidan yasalgan naqsh — Template literal types darsidagi texnika haqiqiy kutubxonada. Shu tarzda o'qish ikki narsaga yordam beradi: funksiya nimani qabul qilishini README'siz bilasiz va @types eskirganmi-yo'qmi — haqiqiy kod bilan solishtira olasiz (latinize dagi kabi).

.d.ts fayllar ichida ko'pincha conditional, mapped va rekursiv turlar uchraydi. Bu qismning oldingi darslari aynan shu o'qish uchun kerak edi: endi kutubxona turi "qora quti" emas.

6. Paket o'rnatilmagan bo'lsa

Saytdagi blok va yangi papka — node_modules siz:

import ms from "ms";
console.log(ms("2h"));

Kompilyator:

TS2307: Cannot find module 'ms' or its corresponding type declarations.

"ms moduli yoki uning tur e'lonlari topilmadi". TS7016 dan farqi: u yerda paket bor, turlari yo'q; bu yerda paketning o'zi yo'q. Tuzatish — npm install ms. (Saytdagi «Ishga tushir» tugmasi ham npm paketlarini yuklamaydi — bunday kodni o'z kompyuteringizda sinang.)

7. Ko'p uchraydigan xatolar

7.1 Turlarsiz paket

TS7016: Could not find a declaration file for module 'ms'. Tuzatish: npm view @types/ms version — bor bo'lsa va versiyasi mos bo'lsa, npm i -D @types/ms@<versiya>; yo'q bo'lsa — o'z declare module.

7.2 @types ni dependencies ga qo'yish

Ishlaydi, lekin foydalanuvchilarga keraksiz yuklanadi. Tuzatish: --save-dev. (Istisno — kutubxona yozayotgan bo'lsangiz va sizning .d.ts laringiz @types/... ga tayansa.)

7.3 Versiyasi mos kelmaydigan @types

TS2554: Expected 1 arguments, but got 2. — haqiqatda ishlaydigan chaqiruvga. Tuzatish: versiyalarni solishtiring; mos @types yo'q bo'lsa — o'z e'loningiz.

7.4 declare module "x"; bilan "tuzatish"

Hamma narsa any — TypeError ishlash paytida. Tuzatish: haqiqiy imzolar, hech bo'lmasa ishlatiladigan funksiyalar uchun.

7.5 Augmentation bor, amalga oshirish yo'q

TypeError: … is not a function. Tuzatish: turni kengaytirgan joyda ishlash paytidagi kodni ham qo'shing (plagin, extend).

8. Mashqlar

1-mashq (oson): Qaysi manba?

Har paket uchun turlar qayerdan keladi — paket (o'zida), dt (@types/*, DefinitelyTyped) yoki declare (o'zingiz yozasiz)? (Ma'lumotlar npm view dan, 2026-10-06.)

1. nanoid 6.0.2 — types = './index.d.ts':
2. pluralize 8.0.0 — types yo'q; @types/pluralize 0.0.33 bor, lekin 8.0 uchun emas:
3. qrcode 1.5.4 — types yo'q; @types/qrcode 1.5.6:

2-mashq (o'rta): ms bilan xavfsiz davomiylik

durationMinutes(text) — bron davomiyligini daqiqada qaytaradi: "90m" → 90. Parametr turini qanday yozasiz, toki durationMinutes("2 soat") tsc da to'xtasin?

import ms from "ms";

export function durationMinutes(text: ms.StringValue): number {
  return ms(text) / 60_000;
}

37-kutubxonalar/guests.ts(32,13): error TS2769: No overload matches this call.
  The last overload gave the following error.
    Argument of type 'string' is not assignable to parameter of type 'StringValue'.

3-mashq (qiyin): Amaliy tajriba — uch xil kutubxona

kurs/mashqlar/15/ da (umumiy package.json ga):

npm install --save-exact ms@2.1.3 latinize@2.0.0 dayjs@1.11.23
npm install --save-dev --save-exact @types/ms@2.1.0

37-kutubxonalar/ da:

• latinize.d.ts — «O'z e'loningiz» bo'limidagi fayl.
• guests.ts — searchKey(name) (lotinlashtirilgan, kichik harf, chetdagi bo'shliqsiz), durationMinutes(text) (2-mashq), bookingDay(isoDate) (dayjs + toUzbek plagini → "6-oktabr").
• guests.test.ts — har funksiyaga test.

Avval latinize.d.ts siz va @types/ms siz npx tsc --pretty false ni ishga tushiring — «Nega bu kerak?» bo'limidagi ikki TS7016. Keyin bittadan qo'shib, xatolar qanday yo'qolishini kuzating.

// 37-kutubxonalar/guests.ts — mehmonlar, bron va sanalar
import latinize from "latinize";
import ms from "ms";
import dayjs from "dayjs";
import type { PluginFunc } from "dayjs";

declare module "dayjs" {
  interface Dayjs {
    toUzbek(): string;
  }
}

const MONTHS = [
  "yanvar", "fevral", "mart", "aprel", "may", "iyun",
  "iyul", "avgust", "sentabr", "oktabr", "noyabr", "dekabr",
];

const uzbekDate: PluginFunc = (_options, DayjsClass) => {
  DayjsClass.prototype.toUzbek = function () {
    return `${this.date()}-${MONTHS[this.month()]}`;
  };
};
dayjs.extend(uzbekDate);

// "José Müller" → "jose muller": qidiruv uchun kalit
export function searchKey(name: string): string {
  return latinize(name).toLowerCase().trim();
}

// Bron davomiyligi: "90m" → 90 daqiqa
export function durationMinutes(text: ms.StringValue): number {
  return ms(text) / 60_000;
}

export function bookingDay(isoDate: string): string {
  return dayjs(isoDate).toUzbek();
}

// 37-kutubxonalar/guests.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { searchKey, durationMinutes, bookingDay } from "./guests.ts";

test("searchKey: urg'u belgilarsiz, kichik harf", () => {
  assert.equal(searchKey("José Müller "), "jose muller");
  assert.equal(searchKey("Dilshod"), "dilshod");
});

test("durationMinutes: ms satridan daqiqa", () => {
  assert.equal(durationMinutes("90m"), 90);
  assert.equal(durationMinutes("2h"), 120);
});

test("bookingDay: o'zbekcha sana", () => {
  assert.equal(bookingDay("2026-10-06"), "6-oktabr");
});

✔ searchKey: urg'u belgilarsiz, kichik harf (2.852ms)
✔ durationMinutes: ms satridan daqiqa (1.6286ms)
✔ bookingDay: o'zbekcha sana (3.9139ms)
ℹ tests 3
ℹ suites 0
ℹ pass 3
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 416.9837

git add 15/package.json 15/package-lock.json
git add 15/37-kutubxonalar 15/XATOLAR.md
git commit -m "15/37: kutubxona turlari — @types, declare module"

9. Real ishda

• Har yangi paketda birinchi savol: "turlari bormi?". npmjs.com'dagi belgi (ko'k TS — o'zida, oq-ko'k DT — @types da) yoki npm view. Turlari yo'q yoki eski paket — ko'pincha qo'llab-quvvatlanmayotgan paket belgisi: muqobilini qidirish vaqti.
• @types/node, @types/react — eng ko'p o'rnatiladigan @types paketlari. Ularning versiyasi Node va React versiyasiga mos tanlanadi (@types/node@24 — Node 24 uchun).
• Express (24-qism) — 5-versiyada ham turlarni o'zi olib kelmaydi: @types/express kerak. Express Request obyektiga req.user qo'shish — xuddi dayjs kabi module augmentation bilan qilinadi.
• DefinitelyTyped'ga hissa qo'shish — ochiq manbaga birinchi qadamlardan biri: eskirgan @types ni tuzatish (masalan, latinize uchun 2.0 turlari) — portfolio uchun yaxshi tajriba.
• Intervyu: "@types nima?", "Turlarsiz kutubxonani qanday ishlatasiz?", "Module augmentation nima?" — amaliy savollar.

Xulosa

• Turlar uch joydan: paketning o'zi (types / exports → "types"), @types/<nom> (DefinitelyTyped), o'z declare module. Tekshirish — npm view <paket> version types va npm view @types/<paket> version.
• @types versiyasining birinchi ikki raqami kutubxonaga mos bo'lsin; eskirgan turlar to'g'ri kodni rad etadi yoki xatoni o'tkazadi.
• @types — --save-dev. types: [] faqat globallarga ta'sir qiladi — import qilingan paketning @types i baribir topiladi.
• declare module "x"; — hammasi any: TS7016 yo'qoladi, tekshiruv ham.
• Module augmentation turga qo'shadi, kodga emas — amalga oshirishni (plagin) ham yozing.

Keyingi dars: Build: tsc, bundler'lar va tsgo — zamonaviy loyihada kim turlarni tekshiradi va kim JavaScript chiqaradi: tsc --noEmit, esbuild/SWC, project references va TypeScript 7.

Manbalar

• TypeScript Handbook: "Declaration Files — Consumption" va "Publishing" (types, exports) — typescriptlang.org/docs/handbook/declaration-files/consumption.html
• TypeScript Handbook: "Declaration Merging" (Module Augmentation, Global augmentation) — typescriptlang.org/docs/handbook/declaration-merging.html
• DefinitelyTyped — github.com/DefinitelyTyped/DefinitelyTyped
• npm hujjatlari: npm view — docs.npmjs.com/cli/commands/npm-view
• dayjs: "Plugin" — day.js.org/docs/en/plugin/plugin