Parser

Parse command-line arguments and environment variables with Zod schema validation

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.

argv · string[] · required

The command-line arguments to parse (e.g., process.argv.slice(2))

options · parse.Options

Configuration for parsing, including schemas for args and options

return · parse.ReturnType

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.

schema · z.ZodObject<any> · required

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).

return · z.output<env>

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.

args · z.output<args> | {}

Parsed positional arguments, typed according to the schema. Empty object if no schema provided.

options · z.output<options> | {}

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)
  }
}