Class Context<TOptions>

The context for a command execution.

The Context serves as the orchestrator for the entire command lifecycle. It is responsible for initializing the CLI environment, resolving commands, parsing options, and managing execution flow. It ensures that all aspects of the CLI are prepared and ready before any action is taken, establishing a predictable and stable execution environment.

Philosophy:

Immutable Configuration: Once the context is prepared, its configuration should not change. This immutability guarantees consistency throughout the CLI's operation and avoids side effects that could arise from dynamic changes in the environment.
Explicit Lifecycle Management: By clearly defining lifecycle hooks and preparation stages, Context offers explicit control over the command execution process, allowing for extensibility and customization without sacrificing predictability.
Separation of Concerns: Context focuses on the setup and execution environment, while State manages the actual progression and state changes during command execution. This separation ensures that each module only handles its designated responsibilities, making the system easier to maintain and extend.
Fail-fast Philosophy: The context should catch and handle errors as early as possible (during the preparation phase), ensuring that execution only proceeds when all systems are nominal. The exception to this rule is option validation, which is performed dynamically when options are accessed during execution. This is done to give command handlers the ability to gracefully handle missing or invalid options and potentially prompt the user for the missing information.

Scope:

Plugin Initialization: Loading and preparing all plugins for the execution cycle.
Command Resolution: Determining the sequence of command modules to be executed based on the input string.
Option Parsing: Interpreting command-line arguments and flags into a structured format for consumption by commands.
Execution Readiness: Ensuring that the context has been fully prepared before allowing the execution to proceed.
Error Management: Providing a centralized mechanism for error handling during the preparation and execution phases.
Exit Management: Providing a centralized mechanism for exiting the CLI.

Type Parameters

TOptions extends OptionsConfig = OptionsConfig

Index

Accessors

commandQueue

get commandQueue(): ResolvedCommand[]
Returns ResolvedCommand[]
- Defined in packages/cli/src/core/context.ts:224

options

get options(): TOptions
Returns TOptions
- Defined in packages/cli/src/core/context.ts:217

optionValues

get optionValues(): {
    [key: string]: | undefined
    | string
    | number
    | boolean
    | string[]
    | number[]
    | false[]
    | true[];
}
Returns {
    [key: string]:
        | undefined
        | string
        | number
        | boolean
        | string[]
        | number[]
        | false[]
        | true[];
}
- Defined in packages/cli/src/core/context.ts:231

result

get result(): unknown
Returns unknown
- Defined in packages/cli/src/core/context.ts:238

Constructors

constructor

new Context<TOptions extends OptionsConfig = OptionsConfig>(
__namedParameters: ContextParams<TOptions>,
): Context<TOptions>
Type Parameters
- TOptions extends OptionsConfig = OptionsConfig
Parameters
- __namedParameters: ContextParams<TOptions>
Returns Context<TOptions>
- Defined in packages/cli/src/core/context.ts:173

Methods

`Readonly`enqueueCommand

enqueueCommand(resolvedCommands: ResolvedCommand[]): void
Append to the list of resolved commands to be executed.
Parameters
- resolvedCommands: ResolvedCommand[]
Returns void
- Defined in packages/cli/src/core/context.ts:319

`Readonly`execute

execute(initialData?: any): Promise<any>
Execute the context's command string.

This function will override the context's result with the result of the final command in the chain each time it is called.
Parameters
- OptionalinitialData: any
  Optional data to be passed to the first command in the chain.
Returns Promise<any>
- Defined in packages/cli/src/core/context.ts:414

`Readonly`exit

exit(code?: number, message?: any): Promise<void>
Exit the CLI with an optional exit code and message.
Parameters
- code: number = 0
  The exit code. Defaults to 0.
- Optionalmessage: any
  The message to be displayed before exiting.
Returns Promise<void>
- Defined in packages/cli/src/core/context.ts:496

`Readonly`parseCommand

parseCommand(
commandString?: string,
optionsConfig?: OptionsConfig,
): ParsedCommand | Promise<ParsedCommand>
Parse a command string into a structured object using the configured parseFn and the context's options config.

This function has no side effects and is simply a wrapper around the configured parseFn and options config.
Parameters
- commandString: string = ...
  The command string to be parsed. Defaults to the context's command string.
- optionsConfig: OptionsConfig = ...
  Additional options config to be merged with the context's options config.
Returns ParsedCommand | Promise<ParsedCommand>
A ParsedCommand object containing the parsed command tokens and option values.
- Defined in packages/cli/src/core/context.ts:366

prepare

prepare(): Promise<void>
Prepare the context for execution.
1. Initialize plugins
2. Resolve the command string into a list of imported command modules
3. Parse the command string with the final options config from plugins and commands
4. Mark the context as ready
Returns Promise<void>
Remarks
This method is idempotent.
- Defined in packages/cli/src/core/context.ts:276

preparePlugins

preparePlugins(): Promise<void>
Prepare the plugins for execution by calling their initialization functions, if defined.

Returns Promise<void>
Remarks
This method is idempotent. It will only call the initialization functions of plugins that have not been marked as ready.
- Defined in packages/cli/src/core/context.ts:251

`Readonly`resolveCommand

resolveCommand(
commandString?: string,
commandsDir?: string,
): MaybePromise<ResolvedCommand>
Resolve the first command module from a command string using the configured resolveFn and parseFn.

This function has no side effects and is simply a wrapper around the configured resolveFn and parseFn.
Parameters
- commandString: string = ...
  The command string to be resolved. Defaults to the context's command string.
- commandsDir: string = ...
  The path to the directory containing command modules. Defaults to the context's commands directory.
Returns MaybePromise<ResolvedCommand>
A ResolvedCommand object.
- Defined in packages/cli/src/core/context.ts:341

`Readonly`setOptions

setOptions(options: OptionsConfig): void
Set the options config for the context, merging it with the existing options config. Typically, this is done by plugins during initialization.
Parameters
- options: OptionsConfig
  The options config to be merged with the context's options config.
Returns void
- Defined in packages/cli/src/core/context.ts:308

`Readonly`setOptionValues

setOptionValues(
    optionValues: {
        [key: string]:
            | undefined
            | string
            | number
            | boolean
            | string[]
            | number[]
            | false[]
            | true[];
    },
): void
Parameters
- optionValues: {
      [key: string]:
          | undefined
          | string
          | number
          | boolean
          | string[]
          | number[]
          | false[]
          | true[];
  }
Returns void
- Defined in packages/cli/src/core/context.ts:312

`Readonly`throw

throw(error: unknown): Promise<void>
Throw an error, allowing hooks to modify the error or ignore it.
Parameters
- error: unknown
  The error to be thrown.
Returns Promise<void>
- Defined in packages/cli/src/core/context.ts:474

`Static`prepare

prepare(options: ContextParams): Promise<Context<OptionsConfig>>
Create a new Context instance and automatically prep it for execution.
Parameters
- options: ContextParams
Returns Promise<Context<OptionsConfig>>
- Defined in packages/cli/src/core/context.ts:206

Properties

`Readonly`client

client: Client

The client instance used for logging and user interaction.

`Readonly`commandsDir

commandsDir: string

`Readonly`commandString

commandString: string

`Readonly`hooks

hooks: HookRegistry

The hooks emitter.

`Readonly`plugins

plugins: {
    [name: string]: { description?: string; name: string; version?: string } & PluginMetaOption<
        AnyObject,
    > & { isReady: boolean };
}

Metadata about the plugins that will be used during preparation and execution.

Class Context<TOptions>

Type Parameters

Index

Accessors

Constructors

Methods

Properties

Accessors

commandQueue

Returns ResolvedCommand[]

options

Returns TOptions

optionValues

Returns { [key: string]: | undefined | string | number | boolean | string[] | number[] | false[] | true[];}

result

Returns unknown

Constructors

constructor

Type Parameters

Parameters

Returns Context<TOptions>

Methods

ReadonlyenqueueCommand

Parameters

Returns void

Readonlyexecute

Parameters

Returns Promise<any>

Readonlyexit

Parameters

Returns Promise<void>

ReadonlyparseCommand

Parameters

Returns ParsedCommand | Promise<ParsedCommand>

prepare

Returns Promise<void>

Remarks

preparePlugins

Returns Promise<void>

Remarks

ReadonlyresolveCommand

Parameters

Returns MaybePromise<ResolvedCommand>

ReadonlysetOptions

Parameters

Returns void

ReadonlysetOptionValues

Parameters

Returns void

Readonlythrow

Parameters

Returns Promise<void>

Staticprepare

Parameters

Returns Promise<Context<OptionsConfig>>

Properties

Readonlyclient

ReadonlycommandsDir

ReadonlycommandString

Readonlyhooks

Readonlyplugins

Settings

On This Page

Returns {
[key: string]:
| undefined
| string
| number
| boolean
| string[]
| number[]
| false[]
| true[];
}

`Readonly`enqueueCommand

`Readonly`execute

`Readonly`exit

`Readonly`parseCommand

`Readonly`resolveCommand

`Readonly`setOptions

`Readonly`setOptionValues

`Readonly`throw

`Static`prepare

`Readonly`client

`Readonly`commandsDir

`Readonly`commandString

`Readonly`hooks

`Readonly`plugins