args.ts

Declarations
#

10 declarations

Args
#

Args import type {Args} from '@fuzdev/fuz_util/args.js';

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>

`[key: string]`

type ArgValue

args_extract_aliases
#

args.ts view source

(schema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>): ArgsAliasesResult import {args_extract_aliases} from '@fuzdev/fuz_util/args.js';

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

args_parse
#

args.ts view source

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

import {args_parse} from '@fuzdev/fuz_util/args.js';

Validates parsed CLI args against a zod schema.

Handles CLI-specific concerns before validation:

Validates schema (cached) - returns error if alias conflicts exist
Expands aliases defined in schema .meta({aliases: ['v']})
Strips alias keys (required for strictObject schemas)
Validates with zod
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>

z.ZodSafeParseResult with expanded/synced data on success

generics

args_parse<TOutput extends Record<string, ArgValue> = Args>

`TOutput`

constraint Record<string, ArgValue>

default Args

args_serialize
#

args.ts view source

(args: Args, schema?: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>> | undefined): string[] import {args_serialize} from '@fuzdev/fuz_util/args.js';

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`

type Args

`schema?`

optional zod schema to extract aliases for short form preference

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

optional

returns

string[]

args_validate_schema
#

args.ts view source

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

import {args_validate_schema} from '@fuzdev/fuz_util/args.js';

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 import type {ArgsAliasesResult} from '@fuzdev/fuz_util/args.js';

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 import type {ArgSchema} from '@fuzdev/fuz_util/args.js';

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 import {argv_parse} from '@fuzdev/fuz_util/args.js';

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 import type {ArgValue} from '@fuzdev/fuz_util/args.js';

Value types supported in CLI arguments.

ParsedArgs
#

args.ts view source

ParsedArgs import type {ParsedArgs} from '@fuzdev/fuz_util/args.js';

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

inheritance

extends: Args

`_`

type Array<string>