Types Reference

Complete reference of all types exported from @crustjs/core.

Command Types

`CommandNode`

Internal representation of a single node in the command tree. Built by the Crust builder class; exported for downstream packages.

interface CommandNode {
  meta: CommandMeta;
  localFlags: FlagsDef;
  effectiveFlags: FlagsDef;
  args: ArgsDef | undefined;
  subCommands: Record<string, CommandNode>;
  plugins: CrustPlugin[];
  preRun?: (ctx: unknown) => void | Promise<void>;
  run?: (ctx: unknown) => void | Promise<void>;
  postRun?: (ctx: unknown) => void | Promise<void>;
}

localFlags — Flags defined directly on this command via .flags()
effectiveFlags — Inherited flags merged with local flags (used by the parser and help plugin)
plugins — Plugins registered via .use()

`CrustCommandContext<A, F>`

Runtime context passed to preRun, run, and postRun hooks on the Crust builder:

interface CrustCommandContext<A extends ArgsDef, F extends FlagsDef> {
  args: InferArgs<A>;       // Resolved positional arguments
  flags: InferFlags<F>;     // Resolved flags
  rawArgs: string[];         // Arguments after `--`
  command: CommandNode;      // The resolved command node
}

`CommandMeta`

Metadata describing a command:

interface CommandMeta {
  name: string;          // Command name (required)
  description?: string;  // Help text description
  usage?: string;        // Custom usage string
}

Argument Types

`ArgDef`

Defines a single positional argument. Discriminated union by type for type-safe defaults:

type ArgDef = StringArgDef | NumberArgDef | BooleanArgDef;

Each variant constrains default to match its type. Boolean toggle fields (required, variadic) only accept true:

// String variant (Number and Boolean follow the same shape)
interface StringArgDef {
  name: string;          // Argument name
  type: "string";        // Type discriminant
  description?: string;  // Help text
  default?: string;      // Default value (type-safe)
  required?: true;       // Error if missing
  variadic?: true;       // Collect remaining into array
}

`ArgsDef`

Ordered tuple of argument definitions:

type ArgsDef = readonly ArgDef[];

Flag Types

`FlagDef`

Defines a single named flag. Discriminated union by type and multiple:

type FlagDef =
  | StringFlagDef | NumberFlagDef | BooleanFlagDef           // single-value
  | StringMultiFlagDef | NumberMultiFlagDef | BooleanMultiFlagDef; // multi-value

Single-value variants use multiple?: never (field absent); multi-value variants require multiple: true:

// Single-value string flag
interface StringFlagDef {
  type: "string";              // Type discriminant
  description?: string;        // Help text
  default?: string;            // Default value (type-safe)
  required?: true;             // Error if missing
  short?: string;              // Single-character short form (-x)
  aliases?: string[];          // Additional aliases (single-char or long)
  multiple?: never;            // Absent for single-value flags
  inherit?: true;              // Inherited by subcommands
}

// Multi-value string flag
interface StringMultiFlagDef {
  type: "string";              // Type discriminant
  description?: string;        // Help text
  default?: string[];          // Default array value (type-safe)
  required?: true;             // Error if missing
  short?: string;              // Single-character short form (-x)
  aliases?: string[];          // Additional aliases (single-char or long)
  multiple: true;              // Collect repeated values into array
  inherit?: true;              // Inherited by subcommands
}
// Number and boolean variants follow the same pattern

Boolean toggle fields (required, multiple, inherit) only accept true — passing false is a type error.

`FlagsDef`

Record mapping flag names to definitions:

type FlagsDef = Record<string, FlagDef>;

Flag Inheritance Types

`InheritableFlags<F>`

Picks only the flags from F that have inherit: true:

type InheritableFlags<F extends FlagsDef> = {
  [K in keyof F as F[K] extends { inherit: true } ? K : never]: F[K];
};

`MergeFlags<Parent, Local>`

Merges parent flags with local flags, where local keys override parent keys:

type MergeFlags<Parent extends FlagsDef, Local extends FlagsDef> =
  Omit<Parent, keyof Local> & Local;

`EffectiveFlags<Inherited, Local>`

Computes the effective flags for a command by filtering inherited flags (only those with inherit: true) and merging with local flags:

type EffectiveFlags<Inherited extends FlagsDef, Local extends FlagsDef> =
  MergeFlags<InheritableFlags<Inherited>, Local>;

This is the type-level counterpart of the runtime computeEffectiveFlags() function.

Inference Types

`InferArgs<A>`

Maps an ArgsDef tuple to resolved arg types:

type InferArgs<A> = A extends ArgsDef ? /* resolved types */ : Record<string, never>;

Resolution rules:

Definition	Inferred Type
`{ type: "string" }`	`string \| undefined`
`{ type: "string", required: true }`	`string`
`{ type: "string", default: "hi" }`	`string`
`{ type: "number" }`	`number \| undefined`
`{ type: "number", default: 3000 }`	`number`
`{ type: "string", variadic: true }`	`string[]`

`InferFlags<F>`

Maps a FlagsDef record to resolved flag types:

type InferFlags<F> = F extends FlagsDef ? /* resolved types */ : Record<string, never>;

Resolution rules:

Definition	Inferred Type
`{ type: "string" }`	`string \| undefined`
`{ type: "string", required: true }`	`string`
`{ type: "string", default: "hi" }`	`string`
`{ type: "boolean" }`	`boolean \| undefined`
`{ type: "string", multiple: true }`	`string[] \| undefined`
`{ type: "string", multiple: true, required: true }`	`string[]`

Parse Types

`ParseResult<A, F>`

Output of parseArgs:

interface ParseResult<A extends ArgsDef, F extends FlagsDef> {
  args: InferArgs<A>;     // Resolved positional arguments
  flags: InferFlags<F>;   // Resolved flags
  rawArgs: string[];       // Arguments after `--`
}

Routing Types

`CommandRoute`

Output of resolveCommand:

interface CommandRoute {
  command: CommandNode;    // The resolved command
  argv: string[];           // Remaining argv
  commandPath: string[];    // Full command path
}

Plugin Types

`CrustPlugin`

The plugin interface:

interface CrustPlugin {
  name?: string;
  setup?: (context: SetupContext, actions: SetupActions) => void | Promise<void>;
  middleware?: PluginMiddleware;
}

`SetupContext`

Context available during plugin setup:

interface SetupContext {
  readonly argv: readonly string[];
  readonly rootCommand: CommandNode;
  readonly state: PluginState;
}

`SetupActions`

Actions available during plugin setup:

interface SetupActions {
  addFlag(command: CommandNode, name: string, def: FlagDef): void;
  addSubCommand(parent: CommandNode, name: string, command: CommandNode): void;
}

addFlag — inject a flag into a command's effectiveFlags object (localFlags is unchanged). If the command already has a flag with the same name, the plugin's flag overrides it. crust build emits a warning when this happens.
addSubCommand — inject a subcommand into a command's subCommands record. If the parent already has a subcommand with the same name (user-defined), the call is skipped — user definitions always take priority. crust build emits a warning when this happens.

`MiddlewareContext`

Context available during middleware execution:

interface MiddlewareContext {
  readonly argv: readonly string[];
  readonly rootCommand: CommandNode;
  readonly state: PluginState;
  route: Readonly<CommandRoute> | null;
  input: ParseResult | null;
}

`PluginMiddleware`

Middleware function type:

type PluginMiddleware = (
  context: MiddlewareContext,
  next: () => Promise<void>,
) => void | Promise<void>;

Other Types

`ValueType`

Supported type literals for args and flags:

type ValueType = "string" | "number" | "boolean";

Compile-Time Validation Types

`ValidateVariadicArgs<A>`

Per-arg validation used by .args(). Enforces that only the last positional argument can use variadic: true.

type ValidateVariadicArgs<A extends readonly object[]> = /* ... */;
// On error, the offending arg gets a branded property:
// { readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic" }

`ValidateFlagAliases<F>`

Per-flag validation used by .flags(). Enforces that aliases do not collide with other flag names or aliases.

type ValidateFlagAliases<F extends Record<string, unknown>> = /* ... */;
// On error, the offending flag gets a branded property:
// { readonly FIX_ALIAS_COLLISION: `Alias "${...}" collides with another flag name or alias` }

`ValidateNoPrefixedFlags<F>`

Per-flag validation used by .flags(). Reserves the no- prefix for boolean negation by rejecting flag names and aliases that start with no-.

type ValidateNoPrefixedFlags<F extends Record<string, unknown>> = /* ... */;
// On error, the offending flag gets a branded property:
// { readonly FIX_NO_PREFIX: `Flag name "${...}" must not start with "no-"; ...` }
// or
// { readonly FIX_NO_PREFIX: `Alias "${...}" must not start with "no-"; ...` }

On this page