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 commandString commandsDir 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

    Readonly addOptions

    • 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

    Readonly execute

    • 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

      • Optional initialData: any

        Optional data to be passed to the first command in the chain.

      Returns Promise<void>

    Readonly exit

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

      • Optional message: any

        The message to be displayed before exiting.

      Returns Promise<void>

    Readonly parseCommand

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

      • Optional optionsConfig: 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.

    Readonly 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.

    Readonly resolveCommand

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

    Readonly throw

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

    Static prepare

    Properties

    Readonly client

    client: Client

    The standard streams client.

    Readonly commandString

    commandString: string

    The command string to be executed.

    Readonly commandsDir

    commandsDir: string

    The path to the directory containing command modules.

    Readonly hooks

    hooks: HooksEmitter

    The hooks emitter.

    Readonly plugins

    plugins: Record<string, PluginInfo & {
        isReady: boolean;
    }>

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

    Settings

    Member Visibility

    Theme

    On This Page

    optionsparsedOptionsresolvedCommandsresultconstructoraddOptionsexecuteexitparseCommandprepareresolveCommandthrowprepareclientcommandStringcommandsDirhooksplugins