Execution API Reference

The Execution layer handles command routing, argument parsing, validation, middleware execution, and handler invocation.

Functions

executeCli(options)

Executes a CLI with the provided arguments. This function:

• Resolves the command from the argument list
• Executes the command
• Handles errors
• Calls onDestroy hooks for all plugins

Note: deprecation warnings are typically provided via plugins (e.g. the standard library deprecationPlugin).

Parameters:

• options: ExecuteCliOptions - Execution options

Returns: Promise<void>

Example:

import { executeCli } from "cheloni";

await executeCli({
  cli,
  args: process.argv.slice(2) // optional, defaults to process.argv.slice(2)
});

executeCommand(options)

Executes a command with the provided arguments. This function:

• Parses arguments
• Executes middleware
• Validates options and positional arguments
• Executes bequeath option handlers
• Calls onBeforeCommandExecution hooks
• Executes the command handler
• Calls onAfterCommandExecution hooks

Note: plugin hook failures (e.g. onInit, onBeforeCommandExecution, onError throwing) are wrapped as plugin errors and routed directly to cli.onError to avoid error-handler plugin loops.

Parameters:

• options: ExecuteCommandOptions - Command execution options

Returns: Promise<void>

Example:

import { executeCommand } from "cheloni";

await executeCommand({
  command,
  args: ["--verbose", "file.txt"],
  cli
});

parseArgs(args, aliasMap?)

Parses command-line arguments into positional arguments and options.

Parameters:

• args: string[] - The argument array
• aliasMap?: Record<string, string[]> - Optional alias map

Returns: { positional: string[], options: Record<string, any> }

Example:

import { parseArgs } from "cheloni";

const { positional, options } = parseArgs(
  ["--verbose", "file.txt"],
  { verbose: ["v"] }
);
// positional: ["file.txt"]
// options: { verbose: true }

extractPositionalValue(schema, args, index)

Extracts a positional value from the argument array at the specified index.

Parameters:

• schema: z.ZodTypeAny | undefined - The positional schema
• args: string[] - The argument array
• index: number - The index to extract

Returns: any

Example:

import { extractPositionalValue } from "cheloni";
import { z } from "zod";

const value = extractPositionalValue(
  z.string(),
  ["file.txt", "other.txt"],
  0
);
// value: "file.txt"

handleError(options)

Handles command execution errors, formatting them appropriately.

Parameters:

• options: { error: unknown, command: Command } - Error handling options

Returns: void

Example:

import { handleError } from "cheloni";

try {
  await executeCommand({ command, args, cli });
} catch (error) {
  handleError({ error, command });
}

Types

ExecuteCliOptions

interface ExecuteCliOptions {
  cli: Cli;
  args?: string[];
}

ExecuteCommandOptions

interface ExecuteCommandOptions {
  args: string[];
  command: Command;
  cli: Cli;
}

Error Classes

InvalidSchemaError

Base class for schema validation errors.

class InvalidSchemaError extends Error {
  readonly issues: ReadonlyArray<z.core.$ZodIssue>;
  
  constructor(message: string, issues: ReadonlyArray<z.core.$ZodIssue>);
}

InvalidOptionsError

Thrown when options validation fails.

class InvalidOptionsError extends InvalidSchemaError {
  constructor(message: string, issues: ReadonlyArray<z.core.$ZodIssue>);
}

InvalidOptionError

Thrown when a single option validation fails.

class InvalidOptionError extends InvalidSchemaError {
  constructor(message: string, issues: ReadonlyArray<z.core.$ZodIssue>);
}

InvalidPositionalError

Thrown when positional argument validation fails.

class InvalidPositionalError extends InvalidSchemaError {
  constructor(message: string, issues: ReadonlyArray<z.core.$ZodIssue>);
}

Execution Flow

1. Argument Parsing - Parse raw arguments into positional and options (alias map applied first)
2. Plugin Hooks (Pre) - Call onBeforeCommandExecution hooks (unvalidated parsed args; runs before middleware)
3. Middleware Execution - Execute the matched command’s middleware chain only; context from next({ ctx }) is merged
4. Extraneous Options - Enforce throwOnExtrageousOptions policy against the command schema and bequeath names
5. Bequeath Option Handlers - Execute bequeath option handlers when flags are present (may short-circuit)
6. Positional Validation - Extract and validate positional arguments with Zod
7. Option Schema Validation - Validate command options with Zod
8. Handler Execution - Execute the command handler
9. Plugin Hooks (Post) - Call onAfterCommandExecution hooks in a finally block (always runs, even on error)

Hook Execution Order

onBeforeCommandExecution runs once per invocation, immediately after parse and before middleware and validation. onAfterCommandExecution runs in finally after the handler attempt.

For both hooks, plugins run in the same order: global plugins (from cli.plugins, in registration order), then command-level plugins from the matched command’s definition (in definition order).