`util.parseArgs` în Node.js

Criptografie și utilitare Node.js 16.17 / 18.3 (stabil din 20.0)

Citește opțiunile din linia de comandă (--port 8080, -v, --fara-culori) fără pachete ca yargs sau commander.

Sintaxă

import { parseArgs } from "node:util";
const { values, positionals } = parseArgs({
  args, options: { nume: { type: "string", short: "n", default: "..." } }, allowPositionals: true,
});

Ce face `util.parseArgs`

parseArgs analizează argumentele unui script după reguli obișnuite: --nume valoare, --nume=valoare, forme scurte (-n valoare, -v) și argumente fără nume (pozițiale). Implicit citește process.argv.slice(2); cu args îi dai tu tabloul.

În options descrii fiecare opțiune: type este "string" sau "boolean", short litera scurtă, multiple: true permite repetarea (primești un tablou), default valoarea implicită. Rezultatul are values (opțiunile) și positionals (restul).

Implicit, o opțiune necunoscută sau un argument pozițional neașteptat aruncă o eroare cu un mesaj clar; pozițiale permiți cu allowPositionals: true. Cu allowNegative: true (din 22.4 / 20.16) acceptă și forma --no-culori pentru opțiunile booleene.

Parametri

Parametru	Descriere
`args`	Tabloul de analizat (implicit argumentele procesului).
`options`	Descrierea opțiunilor: `type`, `short`, `multiple`, `default`.
`allowPositionals`	Permite argumente fără nume.
`strict`	Implicit `true`: erori pentru opțiuni necunoscute.
`allowNegative`	Acceptă `--no-x` pentru opțiunile booleene.

Ce returnează

Un obiect { values, positionals } (și tokens dacă ceri). values este un obiect fără prototip, afișat de console.log ca [Object: null prototype].

Exemple

Exemplul 1: Opțiuni lungi, scurte și pozițiale

În scriptul real nu dai args: sunt citite din linia de comandă. Aici le scriem explicit, ca în node raport.mjs vanzari.csv --oras Iași -v --luna 1 --luna 2.

import { parseArgs } from "node:util";

const { values, positionals } = parseArgs({
  args: ["vanzari.csv", "--oras", "Iași", "-v", "--luna", "1", "--luna", "2"],
  options: {
    oras: { type: "string", short: "o", default: "București" },
    verbose: { type: "boolean", short: "v", default: false },
    luna: { type: "string", multiple: true },
    format: { type: "string", default: "text" },
  },
  allowPositionals: true,
});

console.log(values);
console.log(positionals);

Rezultat

[Object: null prototype] {
  oras: 'Iași',
  verbose: true,
  luna: [ '1', '2' ],
  format: 'text'
}
[ 'vanzari.csv' ]

Exemplul 2: Opțiune necunoscută și forma –no-

import { parseArgs } from "node:util";

const optiuni = { culori: { type: "boolean", default: true } };

try {
  parseArgs({ args: ["--colori"], options: optiuni });
} catch (eroare) {
  console.log(eroare.code);
  console.log(eroare.message.split("\n")[0]);
}

const { values } = parseArgs({ args: ["--no-culori"], options: optiuni, allowNegative: true });
console.log(values);