Config fayl formatlari: YAML, TOML, JSON5, INI va cosmiconfig, convict

Qisqacha: JSON izohni qo'llamaydi — shuning uchun config uchun JSON5, YAML, TOML, INI ham ishlatiladi. Har birining tuzog'i bor: YAML'ning eski 1.1 versiyasida NO — false, 010 — 8; 1.2 da 1.10 — 1.1 soniga aylanadi. TOML turlari qat'iy, INI'da hamma narsa satr. Vositalar: cosmiconfig — ".toolrc, tool.config.js yoki package.json dagi kalitni top" (ESLint, Prettier uslubi), convict — sxemali config, c12 va rc — boshqa yondashuvlar. Ularni ko'pincha o'zingiz yozmaysiz — begona loyihada o'qiysiz. vazifalar-api hech birini ishlatmaydi.

Bu darsda

• Bitta sozlamani JSON, JSON5, YAML, TOML va INI'da yozib, farqlarini ayta olasiz.
• YAML'ning NO, 010, 12:30, 1.10 tuzoqlarini bilasiz.
• cosmiconfig qaysi fayllarni qaysi tartibda qidirishini va sukut chegarasini tushuntira olasiz.
• convict, rc, c12, .env.vault nima ekanini taniysiz.
• Loyiha ildizidagi config fayllarni (.npmrc, .nvmrc, .editorconfig) o'qiy olasiz.

Oldin bilishingiz kerak: node-config, Env validatsiyasi va tipli config, Platforma va kutubxona config fayllari.

1. Nega bu kerak?

Begona repo'ni klonladingiz. Ildizda: .npmrc, .nvmrc, .editorconfig, .prettierrc.yaml, docker-compose.yml, fly.toml, config/default.json5, .env.vault. Sakkizta fayl — beshta format. Ularning hech birini siz yozmagansiz, lekin loyiha ishlashi uchun ularni tushunishingiz kerak.

16-qismda frontend asboblarining config fayllarini ko'rgansiz. Bu dars backend va umumiy tomonni yopadi: formatlarning o'zi va "config qayerdan o'qiladi" degan savolga javob beradigan kutubxonalar.

O'xshatish: turli mamlakatlarning elektr rozetkalari. Tok bir xil, vilkalar har xil. Sayohatchi har rozetka uchun yangi elektr stansiya qurmaydi — u faqat qaysi adapter kerakligini biladi.

2. Bitta sozlama — beshta format

2.1 JSON va izoh muammosi

JSON — ma'lumot almashish formati, odam yozadigan config uchun yaratilmagan. Eng katta noqulaylik — izoh yo'q:

const config = '{ "port": 3000, // izoh\n }';
try {
  JSON.parse(config);
} catch (x) {
  console.log(x.name);
  console.log(x.message);
}

Konsolda:

SyntaxError
Expected double-quoted property name in JSON at position 16 (line 1 column 17)

"16-pozitsiyada qo'shtirnoqli xususiyat nomi kutilgan edi" — JSON uchun // belgisi xususiyat nomi emas. Oxirgi vergul (3000,) ham xuddi shunday xato beradi. Shu sababli tsconfig.json aslida JSON emas, JSONC (izohli JSON) — TypeScript uni o'zi o'qiydi.

2.2 Biz sinadik: besh format, bitta natija

Bir xil sozlamani besh formatda yozib, o'z tahlilchilari bilan o'qidik (json5 2.2.3, yaml 2.9.1, smol-toml 1.9.1, ini 7.0.0; Node 24.21.0):

Natija:

JSON : {"port":3000,"cors":["http://localhost:5173"]}
JSON5: {"port":3000,"cors":["http://localhost:5173"]}
YAML : {"port":3000,"cors":["http://localhost:5173"]}
TOML : {"port":3000,"cors":["http://localhost:5173"]}
INI  : {"port":"3000","server":{"host":"127.0.0.1"}}

To'rtta format bir xil obyekt berdi. INI esa "port": "3000" — satr. INI'da tur yo'q: hamma qiymat matn, [server] — bo'lim (obyektning ichki kaliti). Uni o'qigandan keyin har qiymatni o'zingiz aylantirasiz — env darsidagi process.env bilan bir xil holat.

3. YAML: eng ko'p ishlatiladigan va eng ko'p aldaydigan

3.1 Tuzoqlarni o'lchadik

YAML'da qo'shtirnoq shart emas — qulay, lekin tahlilchi qiymat turini o'zi taxmin qiladi. YAML'ning ikki versiyasi bor: eski 1.1 (2005) va yangi 1.2 (2009). Ular taxminni turlicha qiladi. Biz yaml 2.9.1 da bitta matnni ikki versiya qoidasi bilan o'qidik:

tasdiq: no
mamlakat: NO
versiya: 1.10
pochta: 010
vaqt: 12:30

Ikki qatorni maydonma-maydon solishtiring — qaysi qiymat yozilganidek qoldi, qaysi biri boshqa narsaga aylandi:

YAML 1.2 (sukut): {"tasdiq":"no","mamlakat":"NO","versiya":1.1,"pochta":10,"vaqt":"12:30"}
YAML 1.1 rejimi:  {"tasdiq":false,"mamlakat":false,"versiya":1.1,"pochta":8,"vaqt":750}

Nima bo'ldi? 1.2 da no va NO satr bo'lib qoldi, 1.1 da esa ikkalasi false. 010 va 12:30 ham 1.1 da boshqa songa aylandi. 1.10 esa ikkala versiyada 1.1 soni. Har biri haqiqiy muammoga olib kelgan:

Oxirgi qator — YAML 1.2 da ham bor tuzoq. versiya: 1.10 ni satr deb o'ylaysiz, YAML esa uni o'nli kasr deb o'qiydi.

Qoida bitta: matn bo'lishi kerak bo'lgan har qiymatni qo'shtirnoqqa oling — versiya: "1.10", mamlakat: "NO", pochta: "010". Ba'zi tahlilchilar hali ham 1.1 qoidalari bilan o'qiydi (masalan, Python'ning mashhur PyYAML kutubxonasi). Faylingizni qaysi vosita va qaysi versiya bilan o'qishini har doim bilmaysiz — shuning uchun taxmin qilmang, qo'shtirnoq qo'ying.

3.2 Chekinish — sintaksis

YAML'da tuzilma bo'shliqlar bilan beriladi. Bitta ortiqcha bo'shliq:

a:
  b: 1
   c: 2

chekinish xatosi: Nested mappings are not allowed in compact mappings at line 2, column 6:

Yaxshi holat — xato aniq chiqdi. Yomon holat — bo'shliq boshqa joyda bo'lsa, fayl yaroqli qoladi, lekin kalit boshqa obyektga tushadi. Tab belgisi umuman taqiqlangan. Muharrirda YAML uchun bo'shliqlarni ko'rsatishni yoqing.

Tekshirib ko'ring: GitHub Actions faylida on: kaliti bor. YAML 1.1 tahlilchisi uni qanday o'qishi mumkin?

4. TOML: qat'iy turlar

TOML (Tom's Obvious Minimal Language) — YAML'ning taxminlariga javob: har qiymat turi sintaksisdan aniq.

sana = 2026-10-24
port = 3000
xabar = "3000"

sana turi: TomlDate true
{"sana":"2026-10-24","port":3000,"xabar":"3000"}

3000 — son, "3000" — satr; taxmin yo'q. Sana — alohida tur (smol-toml'da Date ning bolasi TomlDate). Kamchiligi: chuqur ichma-ich tuzilmalar ([server.tls.sertifikat]) noqulay. Shuning uchun TOML ko'pincha tekis yoki ikki darajali sozlamalar uchun.

5. Vositalar

5.1 cosmiconfig: "config qayerda?"

ESLint, Prettier, Stylelint, Babel — hammasi bir savolga javob beradi: foydalanuvchi sozlamani qaysi faylga yozgan? .prettierrc, .prettierrc.json, .prettierrc.yaml, prettier.config.js yoki package.json dagi "prettier" kaliti? cosmiconfig shu qidiruvni tayyor qiladi.

Biz cosmiconfig@10.0.1 ni sinadik. Tuzilma: loyiha/ papkasi, ichida src/ papkasi. loyiha/ da ikkala fayl bor: package.json da "vazifalar": { "port": 1111 }, yonida .vazifalarrc.yaml (port: 2222). Qidiruvni bir marta src/ dan, bir marta loyiha/ ning o'zidan boshladik:

import { cosmiconfig } from "cosmiconfig";
const qidiruvchi = cosmiconfig("vazifalar");
const r = await qidiruvchi.search(papka);
// r.filepath, r.config

Har qatorda: qayerdan qidirildi, qaysi sozlama bilan, nima topildi:

src dan, sukut: null
src dan, project: …\loyiha\package.json {"port":1111}
loyiha dan, sukut: …\loyiha\package.json {"port":1111}

Nima bo'ldi? src/ dan sukut bilan — hech narsa (null), garchi config bir papka yuqorida tursa ham. project bilan — topdi. Ikkala topilmada ham .vazifalarrc.yaml (2222) emas, package.json (1111) yutdi. Nega — diagramma va keyingi ikki band tushuntiradi.

flowchart TD
  S["search(papka)"] --> P{"package.json da<br/>'vazifalar' kaliti?"}
  P -- ha --> T[topildi — to'xta]
  P -- yo'q --> R{".vazifalarrc,<br/>.vazifalarrc.yaml …?"}
  R -- ha --> T
  R -- yo'q --> C{"vazifalar.config.js …?"}
  C -- ha --> T
  C -- yo'q --> Q{"searchStrategy"}
  Q -- none --> N[null]
  Q -- project --> U[ota papkaga o'tib qayta]
  U --> P

Diagrammada ikki narsaga qarang: birinchi topilgan joyda qidiruv to'xtaydi, va yuqoriga chiqish faqat searchStrategy ruxsat bersa bo'ladi.

Ikki topilma:

• Tartib: ikkala fayl bo'lsa, package.json dagi kalit yutdi. cosmiconfig searchPlaces ro'yxatini tartib bilan tekshiradi va birinchi topilganda to'xtaydi — birlashtirmaydi (node-config'dan farqi).
• Sukut chegarasi: src/ dan qidirganda — null! cosmiconfig 9 dan beri sukut searchStrategy: "none" — faqat berilgan papkaning o'zi. Yuqoriga (ota papkalarga) qidirish uchun searchStrategy: "project" (birinchi package.json gacha) yoki "global". Eski qo'llanmalarda "o'zi yuqoriga qidiradi" deyilgan — 8-versiyagacha shunday edi.

5.2 convict: sxemali config

Mozilla yaratgan convict — har kalit uchun doc, format, default, env:

const c = convict({
  port: { doc: "Server porti", format: "port",
    default: 3000, env: "PORT" },
  saqlash: { doc: "Ombor", format: ["xotira", "fayl"],
    default: "xotira", env: "SAQLASH" },
});
c.validate({ allowed: "strict" });

convict@6.2.5, PORT=yuz SAQLASH=mongo bilan:

validate: port: ports must be within range 0 - 65535 | saqlash: must be one of the possible values: ["xotira","fayl"]: value was "mongo"

Node-config'dan farqli — tekshiradi va hamma xatoni birdan beradi. Lekin ikkinchi xabarda value was "mongo" — qiymat xabarda, tipli config darsidagi envalid kabi. doc maydoni — sozlamalar hujjati sxemaning o'zida. Zod'dan oldingi davrning yaxshi yechimi; bugun Zod + o'z config.ts xuddi shu ishni bajaradi.

5.3 rc va c12

• rc — juda eski (npm o'zi ham uzoq yillar shunga o'xshash usulni ishlatgan): rc("ilova") — .ilovarc ni joriy papkadan, uy papkasidan, /etc dan va --buyruq-satri argumentlaridan yig'adi, ilova_ prefiksli env'larni ham oladi. Eski CLI vositalarida uchraydi. Kanon faqat ro'yxatda ko'rgan, biz ham o'rnatmadik.
• c12 — UnJS ekotizimidan (Nuxt, Nitro): .config/, *.config.ts, .rc fayllar, extends (boshqa config'dan meros), env bo'yicha qatlamlar. Kanon tekshiruvi (2026-10-24): barqaror versiya — 3.3.4; 4.0.0 hali release candidate (rc) — production uchun kutish kerak.

Bog'liqlik sonlari — kanon npm view natijasi.

Tekshirib ko'ring: Siz CLI vosita yozyapsiz (24-qismdagi valyuta kabi) va foydalanuvchi sozlamani package.json ga ham, alohida faylga ham yozishi mumkin bo'lsin. Qaysi vosita mos?

6. Loyiha ildizidagi config fayllar

Bular — ilovaning emas, asboblarning sozlamalari:

.npmrc alohida e'tiborga loyiq: unda token bo'lishi mumkin (//registry.npmjs.org/:_authToken=…). Loyiha .npmrc si git'ga tushadi — tokenni u yerga emas, uy papkangizdagi ~/.npmrc ga yoki env'ga (${NPM_TOKEN}) yozing.

vazifalar-api da bulardan faqat tsconfig.json va eslint.config.js bor. engines.node >=24 — package.json da (.nvmrc qo'shish — kichik, foydali qadam; 2-mashq).

7. Feature config va .env.vault

7.1 Feature config

Ba'zi sozlamalar muhitga emas, biznesga bog'liq: "yangi eksport formati — faqat 10 % foydalanuvchiga". Bular — feature flag'lar. Ularni env'da saqlash noqulay (o'zgartirish = qayta deploy). Odatda alohida JSON fayl yoki xizmatda (Unleash, LaunchDarkly) yashaydi va ishlash paytida yangilanadi. Frontend tomoni 21-qismda bo'lgan, backend tomoni — 31-qismda.

7.2 .env.vault — xabardor bo'ling

dotenv mualliflarining g'oyasi: .env ni shifrlab, .env.vault sifatida git'ga qo'yish; ochish kaliti (DOTENV_KEY) — serverda env'da. Keyinroq ular shu g'oyani dotenvx vositasiga ko'chirgan. Biz buni sinamadik. Bilish kerak bo'lgan narsa: shifrlangan sir git'da baribir sir — kalit sizib chiqsa, tarixdagi hamma versiya ochiladi. Sirlarni boshqarishning to'liq manzarasi — keyingi darsda.

8. API qadami: tajriba (holat 40, 4-qism)

Bu dars vazifalar-api ga kod qo'shmaydi: kanon qarori — env + Zod, qo'shimcha config vositasi yo'q. Hali commit qilmang.

O'zingiz takrorlang — loyihadan tashqarida:

mkdir format-tajriba && cd format-tajriba
npm init -y
npm i --save-exact yaml@2.9.1 smol-toml@1.9.1 json5@2.2.3

yaml.mjs:

import YAML from "yaml";
const matn = "mamlakat: NO\npochta: 010\nversiya: 1.10\n";
console.log(YAML.parse(matn));
console.log(YAML.parse(matn, { version: "1.1" }));

Ikkala chiqishni solishtiring — «YAML» bo'limidagi jadval bilan bir xil bo'lishi kerak.

9. Ko'p uchraydigan xatolar

10. Mashqlar

Yechimlar kurs/mashqlar/25/38-config-formatlar/ da.

1-mashq (oson): formatni taniyng

• [server] ↵ port = 3000 — (yoki TOML)
• server: ↵ port: 3000 —
• { server: { port: 3000, }, } —
• 24 (bitta qator, .nvmrc) — Node versiyasi

2-mashq (o'rta): mini INI o'quvchi

iniOqi(matn) yozing: ; va # bilan boshlangan qatorlar — izoh; [nom] — bo'lim; kalit = qiymat — joriy bo'limga. Qiymat satr bo'lib qolsin (INI'dagidek). .editorconfig parchasini o'qing.

function iniOqi(matn) {
  const natija = {};
  let bolim = natija;
  for (const xom of matn.split(/\r?\n/)) {
    const q = xom.trim();
    if (q === "" || q.startsWith(";") || q.startsWith("#")) continue;
    const b = /^\[(.+)\]$/.exec(q);
    if (b) {
      bolim = natija[b[1]] = {};
      continue;
    }
    const i = q.indexOf("=");
    if (i === -1) continue;
    bolim[q.slice(0, i).trim()] = q.slice(i + 1).trim();
  }
  return natija;
}

const editorconfig = [
  "root = true",
  "",
  "[*]",
  "indent_size = 2",
  "end_of_line = lf",
  "; izoh",
  "[*.md]",
  "trim_trailing_whitespace = false",
].join("\n");
console.log(iniOqi(editorconfig));

{
  root: 'true',
  '*': { indent_size: '2', end_of_line: 'lf' },
  '*.md': { trim_trailing_whitespace: 'false' }
}

3-mashq (qiyin): YAML "xavfli" qiymatlar detektori

YAML faylidagi kalit: qiymat qatorlarini ko'rib chiqadigan xavfliQiymatlar(matn) yozing (to'liq YAML tahlilchisi emas — oddiy qatorlar yetarli). Qo'shtirnoqsiz qiymat quyidagilardan biri bo'lsa, ogohlantirsin: yes/no/on/off/y/n (katta-kichik harfsiz), bosh nolli son (010), HH:MM, nuqtali son oxiri 0 bilan (1.10).

const QOIDALAR = [
  [/^(yes|no|on|off|y|n)$/i, "YAML 1.1 da mantiqiy qiymat"],
  [/^0\d+$/, "bosh nol yo'qoladi (1.1 da sakkizlik)"],
  [/^\d{1,2}:\d{2}$/, "1.1 da 60 lik son"],
  [/^\d+\.\d*0$/, "son bo'lib, oxirgi 0 yo'qoladi"],
];

function xavfliQiymatlar(matn) {
  const natija = [];
  matn.split("\n").forEach((qator, i) => {
    const m = /^\s*([\w-]+):\s+(.+?)\s*$/.exec(qator);
    if (!m) return;
    const qiymat = m[2];
    if (/^["']/.test(qiymat)) return; // qo'shtirnoqda — xavfsiz
    for (const [re, sabab] of QOIDALAR) {
      if (re.test(qiymat)) {
        natija.push(`${i + 1}-qator ${m[1]}: ${qiymat} — ${sabab}`);
      }
    }
  });
  return natija;
}

const yaml = [
  "mamlakat: NO",
  "pochta: 010",
  "boshlanish: 12:30",
  "versiya: 1.10",
  'tuzatilgan: "1.10"',
  "port: 3000",
].join("\n");
for (const x of xavfliQiymatlar(yaml)) console.log(x);

1-qator mamlakat: NO — YAML 1.1 da mantiqiy qiymat
2-qator pochta: 010 — bosh nol yo'qoladi (1.1 da sakkizlik)
3-qator boshlanish: 12:30 — 1.1 da 60 lik son
4-qator versiya: 1.10 — son bo'lib, oxirgi 0 yo'qoladi

4-mashq: API qadami

«API qadami» bo'limidagi tajribani loyihadan tashqarida bajaring. Qo'shimcha: vazifalar-api ildiziga .nvmrc (24) qo'shish kerakmi? package.json dagi engines.node bilan farqini yozing. Commit yo'q.

11. Real ishda

• DevOps fayllari deyarli hammasi YAML: Docker Compose (33-qism), GitHub Actions (34-qism), Kubernetes. YAML tuzoqlarini bilish — kunlik ehtiyoj.
• O'z CLI yoki kutubxonangizga config kerak bo'lsa — cosmiconfig (yoki c12); ilova (server) uchun — env + sxema.
• Intervyu savollari: "YAML va JSON farqi?", "Nega tsconfig.json da izoh yozsa bo'ladi?", "Norway problem nima?"

Xulosa

• JSON'da izoh yo'q → JSON5/JSONC; YAML qulay, lekin turni taxmin qiladi; TOML — qat'iy turlar; INI — hamma narsa satr.
• YAML: matn bo'lishi kerak qiymatni qo'shtirnoqqa oling ("NO", "010", "1.10", "12:30").
• cosmiconfig — faylni qidiradi, birinchisida to'xtaydi; v9+ da sukut faqat joriy papka.
• convict — sxema va doc bilan; rc — eski CLI'lar; c12 — UnJS, 4.0 hali rc.
• .npmrc da token — git'ga emas; .env.vault/dotenvx — shifrlangan sir ham sir.

Keyingi dars: Sirlarni boshqarish — git tarixiga tushgan kalit nega o'chirish bilan yo'qolmaydi, rotatsiya, sir omborlari va sizib chiqqanda qadamlar.

Manbalar

• YAML 1.2.2 spetsifikatsiyasi (Core Schema): https://yaml.org/spec/1.2.2/ ; yaml paketi (version opsiyasi): https://eemeli.org/yaml/
• TOML v1.0.0: https://toml.io/en/v1.0.0 ; JSON5: https://json5.org/
• cosmiconfig (searchStrategy, v9 o'zgarishi): https://github.com/cosmiconfig/cosmiconfig
• convict: https://github.com/mozilla/node-convict ; c12: https://github.com/unjs/c12 ; rc: https://github.com/dominictarr/rc ; dotenvx: https://dotenvx.com
• Kanon: natijalar/tajriba/t36-config.txt (#38 — npm view versiyalari va bog'liqliklar soni). Format tahlili (json5 2.2.3, yaml 2.9.1, smol-toml 1.9.1, ini 7.0.0), cosmiconfig 10.0.1 qidiruvi va convict 6.2.5 validatsiyasi — biz ishga tushirdik (Node 24.21.0, Windows 11).