Kutubxona manba kodini o'qish: node_modules, .d.ts, testlar va GitHub

Qisqacha: Kutubxona qanday ishlashini bilish uchun uning kodini o'qish mumkin — u node_modules da, oddiy JavaScript. Tartib bor. package.json dagi exports qaysi fayl ishlashini aytadi, import.meta.resolve buni tasdiqlaydi. .d.ts nima va'da qilinganini ko'rsatadi, testlar — qanday holatlar kutilganini. GitHub'dagi repo esa izohlar va tarixni saqlaydi. nanoid ning 117 baytlik nanoid() funksiyasini shu yo'l bilan oxirigacha tushunamiz.

Bu darsda

• node_modules dagi paketni ochib, kirish nuqtasini exports va import.meta.resolve bilan topasiz.
• .d.ts dan va VS Code'ning "Go to Definition" dan foydalanasiz va ularning chegarasini bilasiz.
• Testlarni "ishlaydigan hujjat" sifatida o'qiysiz.
• npm'dagi kod va GitHub'dagi manba farqini (gitHead) tushunasiz.
• Kod o'qish strategiyasini notanish kutubxonaga qo'llaysiz.

Oldin bilishingiz kerak: Begona repoda orientatsiya, package.json IV: kirish nuqtalari, Declaration fayllari (.d.ts).

1. Nega bu kerak?

O'tgan darsda nanoid reposining ildizini o'qidik. Sardor endi bir savolga javob qidirmoqda: "nanoid() 21 ta belgini qanday yasaydi? Ular haqiqatan tasodifiymi? Brauzerda ham xuddi shunday ishlaydimi?"

README javob bermaydi — u "qanday ishlatish" haqida. Internetdagi maqolalar eskirgan bo'lishi mumkin. Eng ishonchli manba — kodning o'zi. U allaqachon kompyuteringizda: node_modules/nanoid/.

Ko'p boshlovchilar node_modules ni "qora quti" deb biladi — tegib bo'lmaydigan sehrli papka. Aslida u yerda xuddi siz yozgandek JavaScript fayllar turadi. Ularni o'qish — kasbiy o'sishning eng tez yo'llaridan biri: yaxshi kutubxonalar kodi — tayyor darslik. Shuningdek, xatoni topish uchun ham: "kutubxona xato qilyaptimi yoki men noto'g'ri ishlatyapmanmi?" degan savolga ko'pincha faqat kod javob beradi.

O'xshatish: yangi taomning ta'mini bilish uchun retseptni o'qiysiz, lekin tarkibini aniq bilish uchun oshxonaga kirib, oshpaz nima qo'shayotganini ko'rasiz.

2. Kirish nuqtasini topish

2.1 Papka ichida nima bor

Mashq loyihasi: kurs/mashqlar/16/47-manba-kod/ — npm i -E nanoid@6.0.2.

ls node_modules/nanoid

LICENSE
README.md
bin
index.browser.js
index.d.ts
index.js
nanoid.js
non-secure
package.json
url-alphabet

O'nta narsa, hammasi 14.7 KB (npm view nanoid@6.0.2 dist.unpackedSize → 14728). index.js va index.browser.js — ikkita! Qaysi biri ishlaydi?

2.2 exports javob beradi

Kirish nuqtalari darsidagi exports maydoni — paketning "qabulxonasi". nanoid/package.json dan:

{
  "exports": {
    ".": {
      "types": "./index.d.ts",
      "browser": "./index.browser.js",
      "react-native": "./index.browser.js",
      "default": "./index.js"
    },
    "./non-secure": {
      "types": "./non-secure/index.d.ts",
      "default": "./non-secure/index.js"
    },
    "./package.json": "./package.json"
  }
}

"." — import … from "nanoid". Ichida shartlar (conditions): TypeScript — types, brauzer bundler'i — browser, qolganlar (Node) — default. Taxmin qilmasdan, Node'dan so'raymiz:

node --input-type=module -e '
console.log(import.meta.resolve("nanoid"))'

file:///D:/kurs/mashqlar/16/47-manba-kod/node_modules/nanoid/index.js

import.meta.resolve — "bu importni qaysi faylga aylantirasan?" degan savol. Node uchun — index.js. Bu bir qatorlik buyruq har qanday paketda ishlaydi va taxminni fakt bilan almashtiradi.

2.3 exports — devor ham

index.browser.js ni Node'da to'g'ridan-to'g'ri import qilib ko'ramiz:

node --input-type=module -e '
import { nanoid } from "nanoid/index.browser.js"'

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './index.browser.js' is not defined by "exports" in D:\kurs\mashqlar\16\47-manba-kod\node_modules\nanoid\package.json imported from D:\kurs\mashqlar\16\47-manba-kod\[eval1]

"./index.browser.js yo'li exports da yo'q". exports faqat ruxsat etilgan eshiklarni ochadi — paketning ichki fayllari "yopiq". O'qish uchun esa nisbiy yo'l bilan to'g'ridan-to'g'ri ochish mumkin: await import("./node_modules/nanoid/index.browser.js") — mashqlarda shunday qilamiz. Real kodda bunday qilmang: ichki fayl keyingi versiyada yo'qolishi mumkin.

3. Kodni o'qish: nanoid() qanday ishlaydi

3.1 Brauzer versiyasi — eng qisqasi

Kichikdan boshlaymiz. index.browser.js dagi nanoid:

export let nanoid = (size = 21) => {
  var id = ''
  var bytes = crypto.getRandomValues(new Uint8Array((size |= 0)))
  while (size--) {
    id += urlAlphabet[bytes[size] & 63]
  }
  return id
}

Qatorma-qator:

Asosiy hiyla — & 63. 63 ikkilikda 111111 — oltita bir. Bitli "VA" (&) baytning faqat oxirgi 6 bitini qoldiradi:

const urlAlphabet =
  "57X6y3wQZNzYjJB2L_10pxbackgroundhimselfUTF-8DEMOGRAPHICSVqvt4KW9";

console.log(urlAlphabet.length); // 64
console.log((63).toString(2)); // 111111
console.log(200 & 63); // 8
console.log(urlAlphabet[200 & 63]); // Z

256 ta bayt qiymati 64 ta belgiga teng taqsimlanadi: har belgiga aynan 4 ta bayt (256 ÷ 64 = 4). Hech bir belgi boshqasidan ko'proq chiqmaydi — ID haqiqatan tasodifiy. Bitli amallar — Bitwise operatorlar darsida.

3.2 G'alati alifbo

urlAlphabet — 57X6y3wQZNzYjJB2L_10pxbackgroundhimselfUTF-8DEMOGRAPHICSVqvt4KW9. Ichida inglizcha so'zlar: background, himself, UTF-8, DEMOGRAPHICS! Nega? npm'dagi faylda izoh yo'q. Bunday savollarga javob — reponing asl manbasida (keyingi bo'lim).

3.3 Node versiyasi — uzunroq

index.js (Node) dagi nanoid boshqacha: export const nanoid = customAlphabet(urlAlphabet). customAlphabet 50 qatorga yaqin va ichida yangi g'oya — pool (havza): tasodifiy baytlarni bittalab emas, katta bo'lak qilib oladi va keyingi chaqiruvlarda shu zaxiradan beradi. Ba'zi qatorlar:

const POOL_MAX = GET_RANDOM_LIMIT / 2
…
if (poolOffset + size > pool.length) {
  let target = Math.max(poolNext, size)
  poolNext = Math.min(target * 16, POOL_MAX)
  let buffer = Buffer.allocUnsafe(target)

Zaxira tugasa — 16 baravar kattaroq yangisi olinadi (eng ko'pi 32 768 bayt). Bu — README'dagi "50% faster than native crypto.randomUUID()" va'dasining sababi: tizimdan tasodif so'rash qimmat, kam so'rash tezroq. Buffer — Node'ning baytlar massivi; brauzerda u yo'q, shuning uchun brauzer versiyasi boshqa fayl.

Bu bo'limni to'liq tushunish shart emas. Muhimi — strategiya: avval qisqa versiyani o'qib, g'oyani tushunish, keyin murakkabini.

Tekshirib ko'ring: nanoid(5) brauzer versiyasida nechta tasodifiy bayt so'raydi va nega size-- teskari tartibda yuradi?

3.4 O'qish yetmasa — kuzatish

Havza haqidagi gapimiz — hozircha kodni o'qishdan chiqargan taxmin. Uni tekshirishning eng oddiy yo'li: node_modules dagi faylga vaqtincha console.log qo'yish. Bu sizning kompyuteringizdagi nusxa — boshqa hech kimga ta'sir qilmaydi. node_modules/nanoid/index.js dagi let target = … qatoridan keyin:

console.log("[nanoid] havza to'ldirildi:", target, "bayt")

Sinov fayli havza.js:

import { nanoid } from "nanoid";

for (let i = 1; i <= 4; i++) {
  console.log(i, nanoid());
}

node havza.js

[nanoid] havza to'ldirildi: 21 bayt
1 16HAPjPowr6xxPhvKpss_
[nanoid] havza to'ldirildi: 336 bayt
2 alI8egljI6zUcWKJVu2eT
3 T5IT5FfAxCRDocYcXlxPm
4 ORXHGfZnG27dx7302llwx

Taxmin tasdiqlandi va aniqlashdi. Birinchi chaqiruv faqat 21 bayt oldi — kerakli miqdorni. Ikkinchisi 16 baravar ko'p — 336 bayt — va keyingi ikki ID shu zaxiradan, tizimga murojaatsiz chiqdi. 30 marta chaqirsak, uchinchi to'ldirish 5 376 bayt bo'ladi (yana ×16). ID'lar sizda boshqacha — ular tasodifiy.

Tajribadan keyin asl holatga qaytarish shart:

npm ci

added 16 packages, and audited 17 packages in 1s

npm ci node_modules ni lock-fayldan qayta quradi — console.log qatori yo'qoldi (Lock-fayllar va npm ci). Bu usulni faqat o'rganish va xato qidirish uchun ishlating. Kutubxonani doimiy o'zgartirish kerak bo'lsa — boshqa yo'llar bor (patch-package).

Diqqat: node_modules dagi o'zgarishni unutib qoldirsangiz, keyingi kun "nega terminalda g'alati yozuvlar chiqyapti?" deb hayron bo'lasiz. Tajribani tugatgach, darhol npm ci.

4. npm'dagi kod va GitHub'dagi manba

4.1 Izohlar qayerda

Repodagi url-alphabet/index.js (o'tgan darsdagi commit):

// This alphabet uses `A-Za-z0-9_-` symbols.
// The order of characters is optimized for better brotli compression.
// Same as in non-secure/index.js
//
// References to the brotli default dictionary:
// `DEMOGRAPHICS`, `UTF-8`, `himself`, `background`, and `10px`
export let urlAlphabet =
  '57X6y3wQZNzYjJB2L_10pxbackgroundhimselfUTF-8DEMOGRAPHICSVqvt4KW9'

Javob: brotli siqish algoritmining ichki lug'atida bu so'zlar bor (bundle tahlili dagi gzip va brotli). Alifbo shunday tartiblanganki, siqilgan fayl kichikroq chiqadi. Hammasi 117 bayt uchun.

Nega npm'dagi faylda bu izoh yo'q? Reponing .github/workflows/release.yml ida ai/clean-npm-project qadami bor, sozlamasi clean-comments: true: nashrdan oldin izohlar olib tashlanadi. Natija: repodagi index.js — 177 qator, npm'dagisi — 125 qator. Kod bir xil, izohlar — faqat GitHub'da.

4.2 gitHead — aynan qaysi commit

npm har versiyani qaysi commitdan chiqarilganini eslab qoladi:

npm view nanoid@6.0.2 gitHead repository.url

gitHead = '3167e108865702c0539d8e552365ed840ac9d8d9'
repository.url = 'git+https://github.com/ai/nanoid.git'

github.com/ai/nanoid/tree/3167e108… — sizdagi 6.0.2 ning aynan manbasi. main branch'da kod allaqachon o'zgargan bo'lishi mumkin — eski versiyaning xatosini qidirsangiz, main emas, gitHead ni oching. Bu Kod arxeologiyasi darsidagi git log -S bilan birga ishlaydigan qurol.

Tekshirib ko'ring: Malika loyihasida nanoid 5.1.0. U GitHub'da main branch'dagi index.js ni o'qidi va o'z loyihasidagi xulqni shu kod bilan tushuntirdi. Xulosa ishonchlimi?

4.3 GitHub code search

GitHub'ning qidiruvi (github.com saytidagi qidiruv maydoni, akkaunt bilan kirgan holda) butun repo bo'yicha ishlaydi. Foydali shablonlar:

Xato xabarini qidirish — eng tez yo'l: xabar matni kodda deyarli doim aynan shunday yozilgan.

5. .d.ts va "Go to Definition"

5.1 .d.ts — va'da

index.d.ts dagi nanoid e'loni:

/**
 * Generate secure URL-friendly unique ID.
 *
 * By default, the ID will have 21 symbols to have a collision
 * probability similar to UUID v4.
 * …
 * @param size Size of the ID. The default size is 21.
 * @typeparam Type The ID type to replace `string` with some opaque
 *   type.
 * @returns A random string.
 */
export function nanoid<Type extends string>(size?: number): Type

Declaration fayllari darsidan bilasiz: bu — shartnoma, kod emas. JSDoc izohlari VS Code'da sichqoncha ostida ko'rinadi. Va <Type extends string> — branded types uchun eshik: nanoid<UserId>().

5.2 "Go to Definition" — tuzoq

VS Code'da nanoid ustida F12 ("Go to Definition") bossangiz, index.js emas, index.d.ts ochiladi. TypeScript faqat turlarni biladi. Haqiqiy kodga borish uchun boshqa buyruq bor: sichqonchaning o'ng tugmasi → "Go to Source Definition" (TypeScript 4.7 dan). U .d.ts ni chetlab, .js faylni ochadi.

6. Testlar — ishlaydigan hujjat

6.1 Testdan qoida o'qish

Reponing test/index.test.js ida:

test('throws on negative or too big ID length', () => {
  throws(() => {
    nanoid(2147483648)
  }, /Wrong ID size|Invalid typed array length/)
  throws(() => {
    nanoid(-10)
  }, /Wrong ID size|Invalid typed array length/)
  …
})

Testning nomi — qoida: "manfiy yoki juda katta uzunlikda xato tashlaydi". throws — assert dagi "xato tashlashi kerak" tekshiruvi. Kutilgan xabar esa ikkita: Wrong ID size yoki Invalid typed array length. Nega ikkita? Tekshiramiz:

node --input-type=module -e '
import { nanoid } from "nanoid";
try { nanoid(-1) } catch (e) {
  console.log(`${e.name}: ${e.message}`)
}'

RangeError: Wrong ID size

Brauzer faylini to'g'ridan-to'g'ri ochib:

RangeError: Invalid typed array length: -1

Node versiyasi o'zi tekshiradi (if (size < 0) throw new RangeError('Wrong ID size')), brauzer versiyasida tekshiruv yo'q — xatoni new Uint8Array(-1) ning o'zi beradi. 117 baytda tekshiruvga joy yo'q. Test ikkala variantni ham qabul qiladi — va bu farqni kodni o'qimay turib ochib berdi.

6.2 Strategiya

flowchart LR
  P["exports"] --> R["import.meta.resolve"]
  R --> S["qisqa versiya:<br/>asosiy g'oya"]
  S --> T["testlar:<br/>qoidalar va chegaralar"]
  T --> G["GitHub:<br/>izoh, gitHead, tarix"]
  G --> D[".d.ts:<br/>va'da va hujjat"]

1. Kirish nuqtasi — exports, keyin import.meta.resolve bilan tasdiq.
2. Eng qisqa yo'l — avval oddiy variant (brauzer, non-secure), keyin murakkabi.
3. Testlar — chegaraviy holatlar ro'yxati; test nomlari — qoidalar.
4. Asl manba — izohlar, gitHead dagi commit, git log.
5. .d.ts — nima va'da qilingani; amalga oshirilishi bilan solishtiring.

Tekshirib ko'ring: Vite bilan yig'ilgan saytda nanoid ning qaysi fayli ishlaydi? Qanday isbotlaysiz?

7. Ko'p uchraydigan xatolar

Yana bir tuzoq — minifikatsiya qilingan paket (dist/index.min.js). Uni o'qib bo'lmaydi: exports da boshqa (.mjs, src/) fayl bormi qarang yoki GitHub'dagi manbaga o'ting. Source map bo'lsa, DevTools asl kodni ko'rsatadi.

8. Mashqlar

Mashq papkasi: kurs/mashqlar/16/47-manba-kod/ — npm init -y, npm pkg set type=module, npm i -E nanoid@6.0.2.

1-mashq (oson): qaysi fayl?

import.meta.resolve bilan toping: "nanoid" → [:nanoid/index.js], "nanoid/non-secure" → [:nanoid/non-secure/index.js].

node --input-type=module -e '
console.log(import.meta.resolve("nanoid/non-secure"))'

file:///D:/kurs/mashqlar/16/47-manba-kod/node_modules/nanoid/non-secure/index.js

2-mashq (o'rta): non-secure ni o'qing

node_modules/nanoid/non-secure/index.js ni oching. Savollar: tasodif qayerdan olinadi? Nega bu versiya "secure emas"? Qachon ishlatsa bo'ladi?

export let nanoid = (size = 21) => {
  let id = ''
  let i = size | 0
  while (i-- > 0) {
    id += urlAlphabet[(Math.random() * 64) | 0]
  }
  return id
}

3-mashq (o'rta): nega % xavfli

Repodagi customRandom izohi aytadi: 17 belgili alifboda bayt % 17 ba'zi belgilarni "ko'proq" chiqaradi. Buni o'zingiz sanang: 0 dan 255 gacha har bayt uchun alphabet[bayt % 17] va har belgi necha marta tushganini chiqaring.

// egrilik.mjs — bayt % 17: har belgiga nechta bayt tushadi
const alphabet = "0123456789abcdefg"; // 17 ta belgi
const counts = new Map();
for (let byte = 0; byte < 256; byte++) {
  const symbol = alphabet[byte % alphabet.length];
  counts.set(symbol, (counts.get(symbol) ?? 0) + 1);
}
console.log([...counts].map(([s, n]) => `${s}:${n}`).join(" "));
const cutoff = 256 - (256 % alphabet.length);
console.log("safeByteCutoff:", cutoff);

0:16 1:15 2:15 3:15 4:15 5:15 6:15 7:15 8:15 9:15 a:15 b:15 c:15 d:15 e:15 f:15 g:15
safeByteCutoff: 255

4-mashq (qiyin): Vite qaysi faylni oldi?

Shu papkada npm i -D -E vite@8.3.3, index.html (<script type="module" src="/main.js">) va main.js:

import { nanoid } from "nanoid";
document.title = nanoid();

npx vite build. Natijadagi JS faylda qaysi versiya kodi borligini isbotlang. Yordam: grep -o "allocUnsafe\|&63\|getRandomValues" dist/assets/index-*.js (grep -o — faqat topilgan bo'lakni chiqaradi).

dist/assets/index-Dc-3RjTk.js  0.86 kB │ gzip: 0.53 kB

9. Real ishda

• Xato tergovi — "kutubxona xatosimi?" savoliga javob: kodni oching, testlarni qidiring, gitHead dagi versiyani GitHub'da ko'ring. Ko'pincha javob — sizning ishlatishingizda.
• Issue yozishdan oldin — kodni o'qib, xato qatorini ko'rsatsangiz, muallif tezroq javob beradi (Fork va upstream).
• O'rganish — nanoid, picocolors, ms kabi kichik paketlar — mukammal kod namunasi. Har hafta bitta paketni o'qish odati katta foyda beradi.
• Intervyu: "Kutubxona qanday ishlashini qanday bilasiz?", "exports dagi shartlar nima?", "Math.random va crypto.getRandomValues farqi?".

Xulosa

• node_modules — oddiy JavaScript; kirish nuqtasi exports da, import.meta.resolve — aniq javob.
• exports shartlari: Node — default (index.js), brauzer bundler'i — browser (index.browser.js); ichki fayllar yopiq (ERR_PACKAGE_PATH_NOT_EXPORTED).
• Avval qisqa versiya: nanoid() = getRandomValues + & 63 + 64 belgili alifbo (teng taqsimot).
• npm'dagi kod izohsiz bo'lishi mumkin — asl manba gitHead dagi commitda; GitHub code search xato matnini tez topadi.
• .d.ts — va'da; F12 o'rniga "Go to Source Definition"; testlar — chegaraviy holatlar hujjati.

Keyingi dars: Ishlatilmagan kod va bog'liqliklarni topish: knip — vazifalar da hech kim ishlatmayotgan eksportlarni knip topadi; 15-qismda yozgan ApiKlient turimiz ham ro'yxatda bo'ladi.

Manbalar

• nanoid: npm (6.0.2), manba 6.0.2 — gitHead, repo, commit c0d01e3
• Node.js: import.meta.resolve, Conditional exports
• MDN: Crypto.getRandomValues()
• GitHub: Understanding GitHub Code Search syntax
• TypeScript 4.7: Go to Source Definition