The Parser module provides utilities for parsing command-line arguments (argv) and environment variables against Zod schemas, with automatic type coercion and validation.
Functions
parse
Parses raw argv tokens against Zod schemas for positional arguments and named options.
The command-line arguments to parse (e.g., process.argv.slice(2))
Configuration for parsing, including schemas for args and options
An object containing parsed args and options
Usage: Basic Parsing
import { z } from 'zod'
import { parse } from 'incur'
const argsSchema = z.object({
source: z.string(),
destination: z.string()
})
const optionsSchema = z.object({
verbose: z.boolean().default(false),
force: z.boolean().default(false)
})
const { args, options } = parse(
['input.txt', 'output.txt', '--verbose'],
{ args: argsSchema, options: optionsSchema }
)
// args: { source: 'input.txt', destination: 'output.txt' }
// options: { verbose: true, force: false }
Usage: Flag Aliases
import { z } from 'zod'
import { parse } from 'incur'
const optionsSchema = z.object({
verbose: z.boolean().default(false),
output: z.string().optional()
})
const { options } = parse(
['-v', '-o', 'result.json'],
{
options: optionsSchema,
alias: { verbose: 'v', output: 'o' }
}
)
// options: { verbose: true, output: 'result.json' }
Usage: Stacked Boolean Flags
import { z } from 'zod'
import { parse } from 'incur'
const optionsSchema = z.object({
verbose: z.boolean().default(false),
force: z.boolean().default(false),
recursive: z.boolean().default(false)
})
const { options } = parse(
['-vfr'],
{
options: optionsSchema,
alias: { verbose: 'v', force: 'f', recursive: 'r' }
}
)
// options: { verbose: true, force: true, recursive: true }
Usage: Array Options
import { z } from 'zod'
import { parse } from 'incur'
const optionsSchema = z.object({
include: z.array(z.string()).default([])
})
const { options } = parse(
['--include', 'src', '--include', 'lib', '--include', 'tests'],
{ options: optionsSchema }
)
// options: { include: ['src', 'lib', 'tests'] }
Usage: Kebab-case to camelCase
import { z } from 'zod'
import { parse } from 'incur'
const optionsSchema = z.object({
dryRun: z.boolean().default(false),
maxRetries: z.number().default(3)
})
const { options } = parse(
['--dry-run', '--max-retries', '5'],
{ options: optionsSchema }
)
// options: { dryRun: true, maxRetries: 5 }
Usage: Boolean Negation
import { z } from 'zod'
import { parse } from 'incur'
const optionsSchema = z.object({
colors: z.boolean().default(true)
})
const { options } = parse(
['--no-colors'],
{ options: optionsSchema }
)
// options: { colors: false }
Usage: Equals Syntax
import { z } from 'zod'
import { parse } from 'incur'
const optionsSchema = z.object({
config: z.string().optional(),
port: z.number().default(3000)
})
const { options } = parse(
['--config=/path/to/config.json', '--port=8080'],
{ options: optionsSchema }
)
// options: { config: '/path/to/config.json', port: 8080 }
parseEnv
Parses environment variables against a Zod schema with automatic type coercion.
The Zod schema defining expected environment variables
source
Record<string, string | undefined>
The environment variable source. Defaults to process.env (Node.js) or Deno.env (Deno).
The parsed and validated environment variables
Usage: Basic Environment Parsing
import { z } from 'zod'
import { parseEnv } from 'incur'
const envSchema = z.object({
NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
PORT: z.number().default(3000),
DATABASE_URL: z.string(),
ENABLE_LOGGING: z.boolean().default(false)
})
const env = parseEnv(envSchema)
// Reads from process.env and coerces types:
// PORT: '3000' -> 3000 (number)
// ENABLE_LOGGING: 'true' -> true (boolean)
Usage: Custom Environment Source
import { z } from 'zod'
import { parseEnv } from 'incur'
const envSchema = z.object({
API_KEY: z.string(),
TIMEOUT: z.number().default(5000)
})
const customEnv = {
API_KEY: 'secret-key',
TIMEOUT: '10000'
}
const env = parseEnv(envSchema, customEnv)
// env: { API_KEY: 'secret-key', TIMEOUT: 10000 }
Usage: Boolean Coercion
import { z } from 'zod'
import { parseEnv } from 'incur'
const envSchema = z.object({
DEBUG: z.boolean().default(false),
VERBOSE: z.boolean().default(false)
})
// Boolean coercion:
// 'true' or '1' -> true
// anything else -> false
const env = parseEnv(envSchema, {
DEBUG: 'true',
VERBOSE: '1'
})
// env: { DEBUG: true, VERBOSE: true }
Types
parse.Options
Configuration options for the parse() function.
args
z.ZodObject<any> | undefined
Zod schema for positional arguments. Keys define the order of arguments.
options
z.ZodObject<any> | undefined
Zod schema for named options/flags.
alias
Record<string, string> | undefined
Map of option names to single-character aliases (e.g., { verbose: 'v' }).
parse.ReturnType
The return type of the parse() function, providing type-safe access to parsed arguments and options.
Parsed positional arguments, typed according to the schema. Empty object if no schema provided.
Parsed named options, typed according to the schema. Empty object if no schema provided.
Error Handling
The parser throws specific error types for different failure scenarios:
ParseError: Thrown when argument parsing fails (e.g., unknown flags, missing values, invalid syntax)ValidationError: Thrown when values fail Zod schema validation
import { z } from 'zod'
import { parse, ParseError, ValidationError } from 'incur'
try {
const { args } = parse(
['--unknown-flag'],
{ options: z.object({ verbose: z.boolean() }) }
)
} catch (err) {
if (err instanceof ParseError) {
console.error('Parse error:', err.message)
// Parse error: Unknown flag: --unknown-flag
} else if (err instanceof ValidationError) {
console.error('Validation error:', err.fieldErrors)
}
}
