Class Context<TOptions>

The command lifecycle manager.

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

Accessors

options parsedOptions resolvedCommands result

Constructors

constructor

Methods

addOptions execute exit parseCommand prepare resolveCommand throw prepare

Properties

client commandsDir commandString hooks plugins

Accessors

options

parsedOptions

  • get parsedOptions(): {}

  • The parsed option values for the command.

    Returns {}

    resolvedCommands

    result

    • get result(): unknown

    • The result of the most recent execution.

      Returns unknown

    Constructors

    constructor

    Methods

    ReadonlyaddOptions

    • addOptions(options): void

    • Append additional options to the context's 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

    Readonlyexecute

    • execute(initialData?): Promise<void>

    • 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<void>

    Readonlyexit

    • exit(code?, message?): 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>

    ReadonlyparseCommand

    • parseCommand(commandString?, optionsConfig?): MaybePromise<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.

      Parameters

      • commandString: string = ...

        The command string to be parsed. Defaults to the context's command string.

      • OptionaloptionsConfig: OptionsConfig

        Additional options config to be merged with the context's options config.

      Returns MaybePromise<ParsedCommand>

      A ParsedCommand object containing the parsed command tokens and option values.

    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.

    ReadonlyresolveCommand

    • resolveCommand(commandString?, commandsDir?): Promise<ResolvedCommand>

    • Resolve a command string into a list of imported command modules 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 Promise<ResolvedCommand>

      A ResolvedCommand object.

    Readonlythrow

    • throw(error): 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>

    Staticprepare

    Properties

    Readonlyclient

    client: Client

    The standard streams client.

    ReadonlycommandsDir

    commandsDir: string

    The path to the directory containing command modules.

    ReadonlycommandString

    commandString: string

    The command string to be executed.

    Readonlyhooks

    hooks: HooksEmitter<Hooks>

    The hooks emitter.

    Readonlyplugins

    plugins: Record<string, {
        description?: string;
        meta?: Record<string, any>;
        name: string;
        version: string;
    } & {
        isReady: boolean;
    }>

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

    Settings

    Member Visibility

    On This Page

    Accessors
    Constructors
    Methods
    Properties