Commander.js: Node CLI uchun sub-buyruqlar, opsiyalar va avtomatik yordam

Qisqacha: Commander — Node'dagi eng mashhur CLI kutubxonasi: program.command("kurs") sub-buyruq qo'shadi, .option("-f, --format <format>") bayroq, .action(...) esa bajariladigan funksiya. Yordam matni, --version, noma'lum buyruq uchun "Did you mean…?" va qiymat tekshiruvi tayyor keladi. Narxi bor: bizning o'lchovda import +32.5 ms va yordam matni inglizcha. valyuta ning 6 buyrug'i uchun util.parseArgs va oddiy if yetarli bo'ldi — Commander kanonga kirmadi, lekin katta CLI'da u vaqtni tejaydi.

Bu darsda

• valyuta buyruqlarini Commander bilan qayta yozasiz: command, argument, option, action.
• choices, requiredOption va o'z tekshiruv funksiyangiz bilan qiymatlarni tekshirasiz.
• Commander'ning exit kodlarini exitOverride bilan valyuta kelishuviga moslaysiz va undagi tartib tuzog'ini bilasiz.
• yargs, citty va cac'ni Commander bilan taqqoslaysiz.
• Kutubxona qo'shish qarorini o'lchov bilan qabul qilasiz.

Oldin bilishingiz kerak: Node'da CLI dastur anatomiyasi, util moduli, Semver va bog'liqliklar.

1. Nega bu kerak?

CLI anatomiyasi darsida valyuta ning "qo'lda" qurilganini ko'rdingiz: parseArgs bayroqlarni ajratadi, keyin if (birinchi === "kurs"), if (birinchi === "tarix") … zanjiri buyruqni tanlaydi, yordam matni — qo'lda yozilgan katta satr.

6 buyruqda bu yaxshi ishlaydi. Endi git ni tasavvur qiling: 150 dan ortiq buyruq, har birining o'z bayroqlari va o'z yordami (git commit --help). Qo'lda yozilsa — har yangi bayroq uchun uch joyni o'zgartirasiz: tahlil, tekshiruv, yordam matni. Bittasini unutsangiz, yordam yolg'on gapiradi.

Commander bu uchtasini bitta e'londan yasaydi. Bayroqni bir marta yozasiz — u tahlil ham qilinadi, tekshiriladi ham, yordamda ham chiqadi.

O'xshatish: to'y taklifnomasi. Har mehmonga qo'lda yozsangiz — 300 ta xat, har birida xato bo'lishi mumkin. Shablon bilan — bir marta matn, qolganini printer qiladi. Lekin 5 mehmon bo'lsa, printer sotib olish shart emas.

2. Birinchi Commander dasturi

2.1 O'rnatish va tuzilma

npm i commander@15.0.0

Biz %TEMP% dagi alohida papkaga o'rnatdik: 1 paket, 0.2 MB, bog'liqliksiz (kanon t51-kutubxona.txt; commander 15.0.0 — 2026-05-29). valyuta buyruqlarining Commander nusxasi:

#!/usr/bin/env node
// komanda.mjs — valyuta buyruqlarining Commander nusxasi (tajriba)
import { Command, Option } from "commander";

const program = new Command();

program
  .name("valyuta")
  .description("CBU valyuta kurslari terminalda")
  .version("1.0.0", "-v, --version");

program
  .command("kurs")
  .description("kurslar jadvali")
  .argument("[kodlar...]", "valyuta kodlari", ["USD"])
  .addOption(
    new Option("-f, --format <format>", "chiqish formati")
      .choices(["jadval", "json", "csv"])
      .default("jadval"),
  )
  .option("-s, --sana <sana>", "YYYY-MM-DD")
  .action((kodlar, bayroqlar) => {
    console.log("kurs:", kodlar, bayroqlar);
  });

program
  .command("tarix")
  .description("kunlik kurslar oqimi")
  .argument("<kod>", "valyuta kodi")
  .requiredOption("--dan <sana>", "boshlanish sanasi")
  .option("--gacha <sana>", "tugash sanasi")
  .action((kod, bayroqlar) => {
    console.log("tarix:", kod, bayroqlar);
  });

program.parse();

nocheck — blok commander paketini talab qiladi, u natija oynasida ham, tekshiruv muhitida ham yo'q. Pastdagi hamma chiqish — biz Node 24.21.0 da ishga tushirgan haqiqiy natija.

2.2 Qismlar

Nimaga e'tibor bering: bitta e'lon — uch ish. .option("-s, --sana <sana>", "YYYY-MM-DD") tahlilga ham, yordam matniga ham kiradi.

2.3 Ishlatib ko'ramiz

$ node komanda.mjs kurs USD EUR -f csv
kurs: [ 'USD', 'EUR' ] { format: 'csv' }
[exit 0]
$ node komanda.mjs tarix EUR --dan 2026-10-01
tarix: EUR { dan: '2026-10-01' }
[exit 0]
$ node komanda.mjs -v
1.0.0
[exit 0]

action ga argumentlar e'lon tartibida keladi: kurs uchun kodlar massivi, tarix uchun kod satri. Bayroqlar — oxirgi argument, obyekt. sana berilmagani uchun obyektda umuman yo'q — parseArgs dagidek.

3. Avtomatik yordam

3.1 Ildiz va sub-buyruq yordami

$ node komanda.mjs --help
Usage: valyuta [options] [command]

CBU valyuta kurslari terminalda

Options:
  -v, --version               output the version number
  -h, --help                  display help for command

Commands:
  kurs [options] [kodlar...]  kurslar jadvali
  tarix [options] <kod>       kunlik kurslar oqimi
  help [command]              display help for command

$ node komanda.mjs kurs --help
Usage: valyuta kurs [options] [kodlar...]

kurslar jadvali

Arguments:
  kodlar                 valyuta kodlari (default: ["USD"])

Options:
  -f, --format <format>  chiqish formati (choices: "jadval", "json", "csv",
                         default: "jadval")
  -s, --sana <sana>      YYYY-MM-DD
  -h, --help             display help for command

Hech qanday yordam matni yozmadik — hammasi e'londan. choices va default ham avtomatik qo'shildi. help buyrug'i ham o'zi paydo bo'ldi: valyuta help kurs = valyuta kurs --help.

3.2 Narxi: aralash til

Diqqat bilan qarang: bizning tavsiflar o'zbekcha ("kurslar jadvali"), Commander'niki — inglizcha (Usage, Options, display help for command, default:). O'zbek foydalanuvchi uchun bu aralash matn. Uni tuzatish mumkin: helpOption("-h, --help", "shu yordam"), .configureHelp(...) va .helpInformation() ni qayta yozish. Lekin Usage:, Arguments: kabi sarlavhalarni o'zgartirish uchun yordam matni formatlovchisini to'liq almashtirish kerak bo'ladi. Natijada qo'lda yozilgan yordamga yaqin ish chiqadi.

valyuta ning qo'lda yozilgan yordami esa to'liq o'zbekcha va muhit o'zgaruvchilari bo'limi ham bor. Bu qarorning birinchi sababi.

4. Tekshiruv: choices, requiredOption, o'z funksiyangiz

4.1 Tayyor tekshiruvlar

$ node komanda.mjs kurs -f xml
error: option '-f, --format <format>' argument 'xml' is invalid. Allowed choices are jadval, json, csv.
[exit 1]
$ node komanda.mjs tarix EUR
error: required option '--dan <sana>' not specified
[exit 1]
$ node komanda.mjs kurss
error: unknown command 'kurss'
(Did you mean kurs?)
[exit 1]
$ node komanda.mjs kurs --bayroq
error: unknown option '--bayroq'
[exit 1]

Tarjimalar: "xml noto'g'ri, ruxsat etilganlar — jadval, json, csv"; "majburiy --dan bayrog'i berilmagan"; "noma'lum buyruq kurss. kurs ni nazarda tutdingizmi?". Oxirgisi — yoqimli qulaylik: Commander o'xshash nomni o'zi topadi. valyuta da bu yo'q.

4.2 O'z tekshiruv funksiyangiz

Sana formatini tekshirish uchun bayroqqa funksiya beriladi. U qiymatni qaytaradi yoki InvalidArgumentError tashlaydi:

import { Command, InvalidArgumentError } from "commander";

function sananiTekshir(qiymat) {
  if (!/^\d{4}-\d{2}-\d{2}$/.test(qiymat)) {
    const xabar = "YYYY-MM-DD ko'rinishida bo'lsin.";
    throw new InvalidArgumentError(xabar);
  }
  return qiymat;
}

const program = new Command("valyuta");
program
  .command("kurs")
  .argument("[kodlar...]", "valyuta kodlari")
  .option("-s, --sana <sana>", "YYYY-MM-DD", sananiTekshir)
  .action((kodlar, b) => console.log(kodlar, b));
program.parse(["kurs", "USD", "-s", "ertaga"], { from: "user" });

parse(massiv, { from: "user" }) — process.argv o'rniga berilgan massivni o'qiydi (node va skript yo'lisiz). Testlar uchun qulay. Biz ishga tushirdik:

error: option '-s, --sana <sana>' argument 'ertaga' is invalid. YYYY-MM-DD ko'rinishida bo'lsin.
[exit 1]

"2026-10-01" bilan esa — [ 'USD' ] { sana: '2026-10-01' }. Xabarning bizning qismi o'zbekcha, Commander qo'shgani — inglizcha.

Tekshirib ko'ring: .argument("<kod>") va .argument("[kod]") ning farqi nima? tarix uchun qaysi biri to'g'ri?

5. Exit kodlar: Commander va valyuta kelishuvi

5.1 Muammo: hammasi 1

Yuqoridagi xatolarning hammasi [exit 1]. CLI anatomiyasi darsidagi kelishuvda foydalanuvchi xatosi — 2, 1 esa ish vaqtidagi xato. Commander ularni ajratmaydi. Yana bir narsa: argumentsiz chaqiruv yordamni stderr'ga chiqarib, 1 bilan tugaydi.

5.2 exitOverride va biz topgan tartib tuzog'i

Commander'da chiqishni o'zgartirish uchun exitOverride(fn) bor: Commander process.exit o'rniga sizning funksiyangizni chaqiradi. Birinchi urinishimiz — uni fayl oxirida, parse() dan oldin qo'shish:

program.showHelpAfterError("(yordam: valyuta --help)");
program.exitOverride((xato) => {
  process.exit(xato.exitCode === 1 ? 2 : xato.exitCode);
});
program.parse();

Natija kutilmagan bo'ldi:

$ node komanda2.mjs kurs -f xml
error: option '-f, --format <format>' argument 'xml' is invalid. Allowed choices are jadval, json, csv.
[exit 1]

Kod o'zgarmadi va yordam eslatmasi ham chiqmadi. Sabab — Commander hujjatida: bu sozlamalar keyin yaratilgan sub-buyruqlarga meros bo'ladi. kurs buyrug'i esa allaqachon yaratilgan edi — u eski sozlama bilan qoldi. Ildiz buyrug'i (--help, -v) yangi qoidaga bo'ysundi, kurs — yo'q.

To'g'ri tartib — sozlamalar new Command() dan darhol keyin, buyruqlardan oldin:

const program = new Command();

// sozlamalar keyin qo'shilgan buyruqlarga meros bo'ladi —
// shuning uchun buyruqlardan OLDIN
program.showHelpAfterError("(yordam: valyuta --help)");
program.exitOverride((xato) => {
  process.exit(xato.exitCode === 1 ? 2 : xato.exitCode);
});

$ node komanda3.mjs kurs -f xml
error: option '-f, --format <format>' argument 'xml' is invalid. Allowed choices are jadval, json, csv.
(yordam: valyuta --help)
[exit 2]
$ node komanda3.mjs tarix EUR
error: required option '--dan <sana>' not specified
(yordam: valyuta --help)
[exit 2]

--help hamon 0 (Commander undagi exitCode ni 0 beradi), argumentsiz chaqiruv — 2. Endi Commander nusxasi valyuta kelishuviga mos.

Saboq umumiy: kutubxonaning "zanjirli" API'sida tartib ma'no beradi. Bu tuzoq jim — xato xabari yo'q, faqat exit kod boshqa. Uni ushlash uchun exit kodni testda tekshirish kerak, ko'z bilan emas.

Tekshirib ko'ring: exitOverride ichida xato.exitCode === 1 ? 2 : xato.exitCode yozdik. Nega shunchaki process.exit(2) emas?

6. Boshqa kutubxonalar

6.1 Taqqoslash

Birinchi ikki qator — kanon o'lchovi (t51-kutubxona.txt). citty va cac versiyalari — npm view (2026-10-23), biz ularni o'rnatmadik va o'lchamadik.

Qisqacha xarakter:

• yargs — Commander'dan "og'irroq": tayyor qobiq to'ldirishi (completion), konfiguratsiya fayllari, middleware. Katta korporativ CLI'larda uchraydi.
• citty — buyruqni oddiy obyekt sifatida yozasiz (defineCommand({ meta, args, run })). TypeScript bilan yaxshi turlar beradi. Nuxt CLI shunda yozilgan.
• cac — minimal; Vite CLI'si hozir ham shu kutubxonada (npm view vite, 2026-10-23: cac ^7.1.0).

TypeScript'da Commander'ning action argumentlari aniq turlanishi uchun @commander-js/extra-typings paketi bor (hujjat bo'yicha; biz ishlatmadik).

6.2 Narx: import vaqti

CLI uchun eng muhim narx — sovuq start (Node.js nima darsidagi 73 ms pastki chegara). Kanon har kutubxona importini alohida o'lchadi (15 jarayon, mediana, bo'sh jarayonga nisbatan):

Nimaga qarang: valyuta --help hozir ~95 ms. Commander bilan ~127 ms, yargs bilan ~190 ms bo'lardi. Inson uchun 30 ms sezilmaydi. Lekin CLI ko'pincha skriptda yuzlab marta chaqiriladi: 1000 chaqiruvda Commander 32 soniya qo'shadi.

7. Qachon kutubxona, qachon parseArgs

flowchart TD
  A["Yangi CLI"] --> B{"Buyruqlar soni?"}
  B -- "1–6" --> C["util.parseArgs + if"]
  B -- "ko'p, ichma-ich" --> D{"Yordam tili?"}
  D -- "inglizcha mos" --> E["Commander"]
  D -- "to'liq o'zbekcha" --> F["parseArgs + o'z yordami yoki Commander + o'z formatlovchisi"]
  C --> G["Bog'liqlik 0, tez start"]

Bu — bitta to'g'ri javobli savol emas. valyuta uchun hal qiluvchi uch narsa bo'ldi: 6 buyruq, prod bog'liqlik 0 maqsadi (Ta'minot zanjiri xavfsizligi — har bog'liqlik xavf ham) va o'zbekcha yordam.

8. CLI qadami: holat yo'q — Commander o'lchab rad etildi

Kanon qarori (QADAMLAR.md #51, t51-kutubxona.txt): Commander kirmadi. Sabablar: parseArgs + 6 buyruqli if zanjiri yetarli; Commander sovuq startni ~95 dan ~127 ms ga oshirardi; avtomatik yordam inglizcha — o'zbekcha uchun baribir qo'lda. Bu darsdagi Commander nusxasi (komanda.mjs) — tajriba, valyuta reposiga kirmaydi.

Holat 52 commiti — keyingi darsda. Commit qilmang.

9. Ko'p uchraydigan xatolar

9.1 Sozlamani buyruqlardan keyin yozish

exitOverride, showHelpAfterError, configureOutput — buyruqlar yaratilishidan oldin. Aks holda sub-buyruqlar eski xulqda qoladi (biz yuqorida ko'rdik: exit 1 o'rniga 2 kutilgan edi).

9.2 action argumentlari tartibi

.argument("<kod>")
.option("--dan <sana>")
.action((bayroqlar, kod) => { /* ❌ teskari */ })

action ga avval argumentlar (e'lon tartibida), keyin bayroqlar obyekti, oxirida buyruqning o'zi keladi. Teskari yozilsa, bayroqlar da "EUR" satri bo'ladi va bayroqlar.dan — undefined.

9.3 Qiymatli bayroqda <> ni unutish

.option("-f, --format") — bu boolean bayroq: -f csv da format: true, csv esa pozitsion argument bo'lib ketadi. Qiymat kerak bo'lsa — .option("-f, --format <format>").

9.4 parse() ni unutish

Hamma e'lon yozildi, lekin dastur hech narsa qilmaydi va xato ham bermaydi. Oxirida program.parse() (asinxron action lar uchun — await program.parseAsync()).

9.5 process.exit ni action ichida

action ichida process.exit(1) — chiqish yo'qolishi mumkin (CLI anatomiyasi). process.exitCode = 1 yoki xato tashlab, uni bir joyda ushlang.

10. Mashqlar

Mashqlar kurs/mashqlar/24/51-commander/ da.

1-mashq (oson): e'londan yordamgacha

Commander e'lonini o'qing va savollarga javob bering:

program
  .command("tarix")
  .argument("<kod>")
  .requiredOption("--dan <sana>")
  .option("--gacha <sana>")
  .option("--gzip");

1. valyuta tarix (kodsiz) — xato bormi?
2. valyuta tarix EUR --gacha 2026-10-20 — xato bormi?
3. --gzip qiymat oladimi?
4. valyuta tarix EUR --dan 2026-10-01 da action ga keladigan bayroqlar obyekti qanday?

2-mashq (o'rta): kichik buyruq dispetcheri

Commander'ning asosiy g'oyasini kutubxonasiz qayta yarating. Sizga buyruqlar obyekti kerak. Undagi har kalit — buyruq nomi, qiymati — { tavsif, bajar(args) }. ishgaTushir(argv) funksiyasi birinchi so'z bo'yicha buyruqni topsin va bajar ga qolgan so'zlarni bersin. bajar exit kod qaytaradi. Buyruq berilmasa yoki help bo'lsa, buyruqlar ro'yxati chiqsin (exit 2 yoki 0). Noma'lum buyruqda eng o'xshash nom taklif qilinsin. O'xshashlik oddiy: bir xil harfdan boshlanadigan va uzunligi 1 ga farq qiladigan nom. Yordam: Object.entries (Obyekt bo'ylab yurish).

const buyruqlar = {
  kurs: {
    tavsif: "kurslar jadvali",
    bajar: (args) => {
      console.log("kurs:", args.join(" ") || "USD");
      return 0;
    },
  },
  tarix: {
    tavsif: "kunlik kurslar",
    bajar: (args) => {
      if (args.length === 0) {
        console.log("Xato: valyuta kodi kerak");
        return 2;
      }
      console.log("tarix:", args[0]);
      return 0;
    },
  },
};

function yordamniChiqar() {
  console.log("Buyruqlar:");
  for (const [nom, b] of Object.entries(buyruqlar)) {
    console.log(`  ${nom.padEnd(6)} ${b.tavsif}`);
  }
}

function oxshashNom(nom) {
  return Object.keys(buyruqlar).find(
    (b) => b[0] === nom[0] && Math.abs(b.length - nom.length) <= 1,
  );
}

function ishgaTushir([nom, ...args]) {
  if (nom === undefined || nom === "help") {
    yordamniChiqar();
    return nom === "help" ? 0 : 2;
  }
  const b = buyruqlar[nom];
  if (b) return b.bajar(args);
  const taklif = oxshashNom(nom);
  console.log(`Xato: noma'lum buyruq '${nom}'`);
  if (taklif) console.log(`Balki: ${taklif}?`);
  return 2;
}

console.log("kod", ishgaTushir(["kurs", "EUR"]));
console.log("kod", ishgaTushir(["tarix"]));
console.log("kod", ishgaTushir(["kurss"]));
console.log("kod", ishgaTushir([]));

kurs: EUR
kod 0
Xato: valyuta kodi kerak
kod 2
Xato: noma'lum buyruq 'kurss'
Balki: kurs?
kod 2
Buyruqlar:
  kurs   kurslar jadvali
  tarix  kunlik kurslar
kod 2

3-mashq (qiyin): valyuta ni Commander bilan (tajriba)

valyuta loyihangizdan nusxa oling (alohida papka) va src/cli.ts dagi argumentlar + if zanjirini Commander'ga o'tkazing: kurs, tarix, kesh, joylar, tahlil, interaktiv buyruqlari, umumiy bayroqlar (--offline, --rangsiz) ildizda. Exit kodlarni exitOverride bilan 2 ga moslang. Keyin ikki versiyani solishtiring: npm test natijasi va node dist/bin.js --help sovuq starti (har biri 10 marta, mediana).

11. Real ishda

• Commander'da yozilganlar: create-react-app (tarixiy), @vue/cli, nest (NestJS CLI), Svelte'ning sv CLI'si. npm statistikasiga ko'ra commander bir haftada ~314 million marta yuklab olingan (2026-10-12…18). Uni bilish — boshqalarning CLI kodini o'qiy olish.
• Monorepo asboblari: Nx, Turborepo — buyruqlar ko'p, bayroqlar ichma-ich. Ularda yargs/Commander kabi kutubxona majburiy.
• Kod sharhi: "Bog'liqlik qo'shamizmi?" — har PR'da so'raladigan savol. Javob — o'lchov: hajm, import vaqti, bog'liqliklar soni, yangilanish tezligi. Bu darsdagi jadval — aynan shunday sharh.
• Intervyu: "CLI uchun qaysi kutubxona?" degan savolga yaxshi javob "Commander" emas, "buyruqlar soniga, tilga va start vaqtiga qarab; kichik bo'lsa — util.parseArgs".

Xulosa

• Commander: command → argument → option → action → parse; bitta e'lon tahlil, tekshiruv va yordamni beradi.
• choices, requiredOption, o'z funksiyasi + InvalidArgumentError — tayyor tekshiruvlar; "Did you mean" bonusi.
• Commander foydalanuvchi xatolarida exit 1 beradi; exitOverride bilan 2 qilish mumkin, lekin faqat buyruqlardan oldin yozilsa.
• Narx: +32.5 ms import (yargs +97.6 ms), inglizcha yordam sarlavhalari.
• valyuta — 6 buyruq, bog'liqlik 0, o'zbekcha yordam: parseArgs tanlandi; Commander — tajriba.

Keyingi dars: Interaktiv CLI: savollar, ranglar, spinner — clack, inquirer, ora va styleText ni o'lchaymiz, quvurda qanday buzilishini ko'ramiz va valyuta ga 20 qatorlik o'z jarayon ko'rsatkichini qo'shamiz.

Manbalar

• Commander.js — README va hujjat: https://github.com/tj/commander.js
• yargs: https://yargs.js.org
• citty (UnJS): https://github.com/unjs/citty
• cac: https://github.com/cacjs/cac
• npm — commander paketi: https://www.npmjs.com/package/commander
• npm yuklab olish statistikasi (2026-10-12…18): https://api.npmjs.org/downloads/point/last-week/commander ; bog'liqliklar — npm view vite devDependencies.cac, npm view @nestjs/cli dependencies.commander, npm view sv devDependencies (2026-10-23)