args.ts

Declarations
#

10 declarations

Args
#

Args

CLI arguments container.
Positional arguments stored in _, named flags/options as string keys.
Produced by argv_parse or external parsers (mri, minimist, etc.).

`_`

type Array<string>

args_extract_aliases
#

args.ts view source

(schema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>): ArgsAliasesResult

Extracts alias mappings and canonical keys from a zod schema's metadata.
Useful for consumers building custom tooling (help generators, conflict detection, etc.).
Results are cached per schema (WeakMap).
Note: Returns copies of the cached data to prevent mutation of internal cache.

`schema`

Zod object schema with optional .meta({aliases}) on fields

type ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

returns

ArgsAliasesResult

Object with aliases map and canonical_keys set

args_parse
#

args.ts view source

<TOutput extends Record<string, ArgValue> = Args>(unparsed_args: Args, schema: ZodType<TOutput, unknown, $ZodTypeInternals<TOutput, unknown>>): ZodSafeParseResult<...>

Validates parsed CLI args against a zod schema.
Handles CLI-specific concerns before validation:
1. Validates schema (cached) - returns error if alias conflicts exist
2. Expands aliases defined in schema .meta({aliases: ['v']})
3. Strips alias keys (required for strictObject schemas)
4. Validates with zod
5. After validation, syncs no- prefixed boolean flags with their base keys
Schema analysis is cached per schema (WeakMap) for performance.

`unparsed_args`

Args object from CLI parser (mri, minimist, etc.)

type Args

`schema`

Zod object schema with optional alias metadata

type ZodType<TOutput, unknown, $ZodTypeInternals<TOutput, unknown>>

returns

ZodSafeParseResult<TOutput>

Zod SafeParseResult with expanded/synced data on success

args_serialize
#

args.ts view source

(args: Args, schema?: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> | undefined): string[]

Serializes Args to CLI string array for subprocess forwarding.
Handles CLI conventions:
- Positionals first, then flags
- Single-char keys get single dash, multi-char get double dash
- Boolean true becomes bare flag, false is skipped
- undefined values are skipped
- no- prefixed keys skipped when base key is truthy (avoid contradiction)
- When schema provided, extracts aliases and prefers shortest form
Schema analysis is cached per schema (WeakMap) for performance.

`args`

Args object to serialize

type Args

`schema?`

Optional zod schema to extract aliases for short form preference

type ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> | undefined

optional

returns

string[]

Array of CLI argument strings

args_validate_schema
#

args.ts view source

(schema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>): { success: true; } | { success: false; error: ZodError<unknown>; }

Validates a zod schema for CLI arg usage.
Checks for:
- Alias conflicts with canonical keys
- Duplicate aliases across different keys
Results are cached per schema (WeakMap). Safe to call multiple times.

`schema`

Zod object schema with optional alias metadata

type ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

returns

{ success: true; } | { success: false; error: ZodError<unknown>; }

Validation result with success flag and optional error

ArgsAliasesResult
#

args.ts view source

ArgsAliasesResult

Result of alias extraction from a schema.
Includes canonical keys for downstream conflict detection.

`aliases`

type Map<string, string>

`canonical_keys`

type Set<string>

ArgSchema
#

args.ts view source

ArgSchema

Schema description for help text generation.
Not used by args_parse/args_serialize directly - provided for consumers
building CLI help output.

`type`

type string

`default`

type ArgValue

`description`

type string

argv_parse
#

args.ts view source

(argv: string[]): ParsedArgs

Parses raw CLI argv array into an Args object.
A lightweight, dependency-free alternative to mri/minimist with compatible behavior.
Features:
- --flag → {flag: true}
- --flag value → {flag: 'value'} or {flag: 123} (numeric coercion)
- --flag=value → equals syntax
- --flag= → {flag: ''} (empty string, differs from mri which returns true)
- -f → {f: true} (short flag)
- -f value → {f: 'value'}
- -abc → {a: true, b: true, c: true} (combined short flags)
- -abc value → {a: true, b: true, c: 'value'} (last flag gets value)
- --no-flag → {flag: false} (negation prefix)
- -- → stops flag parsing, rest become positionals
- Positionals collected in _ array
- Repeated flags become arrays
Intentional differences from mri:
- --flag= returns '' (mri returns true)
- --flag= next returns {flag: '', _: ['next']} (mri takes next as the value)
- ---flag returns {'-flag': true} (mri strips all dashes)
- ['--flag', ''] preserves '' (mri coerces to 0)
- --__proto__ works as a normal key (mri silently fails)
The returned object uses Object.create(null) to prevent prototype pollution
and allow any key name including __proto__ and constructor.

`argv`

Raw argument array (typically process.argv.slice(2))

type string[]

returns

ParsedArgs

Parsed Args object with guaranteed _ array (null prototype)

ArgValue
#

args.ts view source

ArgValue

Value types supported in CLI arguments.

ParsedArgs
#

args.ts view source

ParsedArgs

Parsed CLI arguments with guaranteed positionals array.
Returned by argv_parse which always initializes _.

inheritance

extends:

Args

`_`

type Array<string>