Ismail-elkorchi/argv-flags

argv-flags

Turn argv into trustworthy typed options on Node, Deno, and Bun.

argv-flags compiles a small option definition into a reusable parser. It handles flags, decoded values, short clusters, positional arguments, and -- with immutable results and structured diagnostics. Its focused parser API fits CLI applications, reusable libraries, and command routers.

Install

npm install argv-flags
bun add argv-flags
deno add jsr:@ismail-elkorchi/argv-flags

Use

import { createParser, value } from "argv-flags";

const parser = createParser({
  source: { type: "string", flags: ["-s", "--source"], required: true },
  retries: {
    type: value.integer({ minimum: 0 }),
    flags: ["-r", "--retries"],
    default: 2,
  },
  color: {
    type: value.choice(["auto", "always", "never"]),
    flags: ["--color"],

implicitValue: "auto", }, verbose: { type: "boolean", flags: ["-v", "--verbose"], falseFlags: ["--no-verbose"], }, include: { type: "string", flags: ["-I", "--include"], multiple: true }, quiet: { type: "count", flags: ["-q"] }, });

const result = parser.parse();

if (result.success) { console.log(result.values); console.log(result.positionals); console.log(result.afterDoubleDash); } else { console.error(result.issues); process.exitCode = 2; }

`parse()` reads the current runtime's argv. Use
`parser.parse({ argv: ["--source", "input.txt"] })` for an explicit vector.
Definitions and parse settings are closed objects: misspelled or unsupported
properties fail in TypeScript and at runtime.

Libraries that compose definitions dynamically can type their assembled record
as `OptionDefinitionMap` and compile it with `createParserFromMap()`. Direct
callers should prefer `createParser()` because it preserves option-specific
value inference and rejects extra fields through variables. Composition
libraries can extend the exported scalar, multiple, boolean, and count
definition types with their own presentation metadata instead of reproducing

Composition libraries can call parser.scan() to classify recognized option spans, ordinary arguments, unknown flags, and the exact -- location without decoding values or applying defaults. parse() and scan() use the same grammar implementation. Each occurrence has a state discriminant for boolean, count, explicit, implicit, missing, or unexpected values.

ValueParser is a public structural interface. A value parser created by a compatible second installation, bundle, or npm/JSR copy can be used in a definition compiled by another copy. Implementations must remain synchronous and expose their operations as data properties, not accessors. They must validate and snapshot values according to that interface. Advertised raw choices must be unique and must parse successfully.

Grammar

• Long values use --name value, --name=value, or --name=.
• Short values use -n value, -nvalue, or -n=value.
• Boolean and count flags can be clustered: -vvq.
• A value-taking short flag owns the rest of its cluster: -abofile gives

file to -o after processing -a and -b.

• A required separate value may begin with -; only the exact element --

interrupts it.