CommandBuilder
Immutable command schema builder.
The type parameters F (flags), A (args), and C (context) are phantom types that accumulate builder types as .flag(), .arg(), .derive(), and .middleware() are chained. The .action() handler receives fully typed ActionParams<F, A, C>.
C defaults to Record<string, never>, making ctx property access a type error until derive or middleware extends it.
- Import:
@kjanat/dreamcli - Export kind: class
- Declared in:
src/core/schema/command.ts - Source link:
packages/dreamcli/src/core/schema/command.ts:801
Signatures
class CommandBuilder<F extends Record<string, FlagBuilder<FlagConfig>>, A extends Record<string, ArgBuilder<ArgConfig>>, C extends Record<string, unknown>> {}Members
Constructors
constructor
constructor();Properties
_args
Phantom brand for accumulated arg builder types. No runtime value.
_args: CommandBuilder.A;_ctx
Phantom brand for accumulated context type. No runtime value.
_ctx: CommandBuilder.C;_executionSteps
Execution steps in registration order.
Distinct from schema.middleware: middleware handlers remain in schema for backward compatibility, while derives stay command-local and builder- scoped so future shared/global middleware can compose cleanly.
_executionSteps: readonly ExecutionStep[];_flags
Phantom brand for accumulated flag builder types. No runtime value.
_flags: CommandBuilder.F;_subcommands
Nested sub-command builders (type-erased for heterogeneous storage).
Stored separately from schema.commands because builders carry action handlers and phantom types needed by eraseCommand() in the CLI layer. schema.commands holds pure CommandSchema[] for help/completion.
_subcommands: readonly AnyCommandBuilder[];handler
The action handler, if registered (type-erased for covariance).
handler: ErasedActionHandler | undefined;schema
Runtime schema descriptor.
schema: CommandSchema;Methods
action
action(handler: ActionHandler<CommandBuilder.F, CommandBuilder.A, CommandBuilder.C>): CommandBuilder<CommandBuilder.F, CommandBuilder.A, CommandBuilder.C>;alias
alias(name: string): CommandBuilder<CommandBuilder.F, CommandBuilder.A, CommandBuilder.C>;arg
arg<N extends string, B extends ArgBuilder<ArgConfig>>(name: N & Exclude<N, keyof CommandBuilder.A>, builder: B): CommandBuilder<CommandBuilder.F, CommandBuilder.A & Record<N, B>, CommandBuilder.C>;command
command<F2 extends Record<string, FlagBuilder<FlagConfig>>, A2 extends Record<string, ArgBuilder<ArgConfig>>, C2 extends Record<string, unknown>>(sub: CommandBuilder<F2, A2, C2>): CommandBuilder<CommandBuilder.F, CommandBuilder.A, CommandBuilder.C>;derive
derive<Output extends Record<string, unknown> | undefined>(handler: DeriveHandler<CommandBuilder.F, CommandBuilder.A, CommandBuilder.C, Output>): CommandBuilder<CommandBuilder.F, CommandBuilder.A, WidenDerivedContext<CommandBuilder.C, Output>>;description
description(text: string): CommandBuilder<CommandBuilder.F, CommandBuilder.A, CommandBuilder.C>;example
example(cmd: string, description?: string): CommandBuilder<CommandBuilder.F, CommandBuilder.A, CommandBuilder.C>;flag
flag<N extends string, B extends FlagBuilder<FlagConfig>>(name: N & Exclude<N, keyof CommandBuilder.F>, builder: B): CommandBuilder<CommandBuilder.F & Record<N, B>, CommandBuilder.A, CommandBuilder.C>;hidden
hidden(): CommandBuilder<CommandBuilder.F, CommandBuilder.A, CommandBuilder.C>;interactive
interactive(resolver: InteractiveResolver<CommandBuilder.F>): CommandBuilder<CommandBuilder.F, CommandBuilder.A, CommandBuilder.C>;middleware
middleware<Output extends Record<string, unknown>>(m: Middleware<Output>): CommandBuilder<CommandBuilder.F, CommandBuilder.A, WidenContext<CommandBuilder.C, Output>>;Examples
const deploy = command('deploy')
.description('Deploy to an environment')
.arg('target', arg.string().describe('Deploy target'))
.flag('force', flag.boolean().alias('f'))
.flag('region', flag.enum(['us', 'eu', 'ap']))
.action(async ({ args, flags, out }) => {
// args.target: string
// flags.force: boolean
// flags.region: 'us' | 'eu' | 'ap' | undefined
out.log(`Deploying ${args.target}...`);
});