Class Kernel<Command>

The Ace kernel manages the registration and execution of commands.

The kernel is the main entry point of a console application, and is tailored for a standard CLI environment.

Example

const kernel = Kernel.create()

kernel.defineFlag('help', {
 type: 'boolean',
 alias: 'h',
 description: 'Display help for the given command. When no command is given display help for the list command'
})
kernel.on('help', async (command, $kernel, options) => {
  options.args.unshift(command.commandName)
  await new HelpCommand($kernel, options, kernel.ui, kernel.prompt).exec()
  return true
})

kernel.addLoader(new FsLoader('./commands'))

kernel.info.set('binary', 'node ace')
kernel.info.set('Framework version', '9.1')
kernel.info.set('App version', '1.1.1')

await kernel.handle(process.argv.slice(2))

Type Parameters

Command extends AbstractBaseCommand

Constructors

constructor

new Kernel<Command extends AbstractBaseCommand>(
defaultCommand: Command,
executor: ExecutorContract<Command>,
): Kernel<Command>
Create a new Kernel instance
Type Parameters
- Command extends AbstractBaseCommand
Parameters
- defaultCommand: Command
  The default command to run when no command is specified
- executor: ExecutorContract<Command>
  The executor for creating and running command instances
Returns Kernel<Command>
- Defined in src/kernel.ts:240

Properties

errorHandler

errorHandler: { render(error: unknown, kernel: Kernel<any>): Promise<any> } = ...

The error handler for rendering exceptions

`Static`commandExecutor

commandExecutor: ExecutorContract<typeof BaseCommand> = ...

The default executor for creating command instances and running them

`Static`defaultCommand

defaultCommand: typeof BaseCommand = ListCommand

The default command to use when creating kernel instance via static create method

`Optional`exitCode

exitCode?: number

The exit code for the kernel. The exit code is inferred from the main command when not set explicitly

ui

ui: {} = ...

The UI primitives to use within commands

prompt

prompt: Prompt = ...

Instance of prompt to display CLI prompts. We share a single instance with all the commands. This allows trapping prompts for commands executed internally

info

info: Map<string, AllowedInfoValues> = ...

CLI info map containing metadata about the application

Accessors

flags

get flags(): ({ name: string } & Flag)[]
List of global flags available across all commands

Returns ({ name: string } & Flag)[]
Example
```
kernel.flags // [{ name: 'help', type: 'boolean', ... }]
```
- Defined in src/kernel.ts:230

Methods

`Static`create

create(): Kernel<typeof BaseCommand>
Creates an instance of kernel with the default executor and default command

Returns Kernel<typeof BaseCommand>
Example
```
const kernel = Kernel.create()
```
- Defined in src/kernel.ts:110

on

on(option: string, callback: FlagListener<Command>): this
Listen for CLI options and execute an action. Only one listener can be defined per option.

The callbacks are only executed for the main command
Parameters
- option: string
- callback: FlagListener<Command>
Returns this
- Defined in src/kernel.ts:437

defineFlag

defineFlag(
    name: string,
    options: Partial<Flag> & {
        type: "string" | "number" | "boolean" | "array";
    },
): void
Define a global flag that is applicable for all commands
Parameters
- name: string
  The flag name
- options: Partial<Flag> & { type: "string" | "number" | "boolean" | "array" }
  Flag configuration options
Returns void
Example
```
kernel.defineFlag('verbose', { type: 'boolean', description: 'Enable verbose output' })
```
- Defined in src/kernel.ts:454

addLoader

addLoader(
    loader:
        | LoadersContract<Command>
        | (() => Promise<LoadersContract<Command>>),
): this
Register a commands loader. The commands will be collected by all loaders.

In case multiple loaders return a single command, the command from the most recent loader will be used.
Parameters
- loader: LoadersContract<Command> | (() => Promise<LoadersContract<Command>>)
  The loader instance or a function that returns a loader
Returns this
Example
```
kernel.addLoader(new FsLoader('./commands'))
kernel.addLoader(() => import('./lazy-loader').then(m => new m.LazyLoader()))
```
- Defined in src/kernel.ts:479

addAlias

addAlias(alias: string, command: string): this
Register alias for a command name
Parameters
- alias: string
  The alias name
- command: string
  The command name (can include arguments)
Returns this
Example
```
kernel.addAlias('m', 'make:model')
kernel.addAlias('migrate:fresh', 'migration:rollback --to=0 && migration:run')
```
- Defined in src/kernel.ts:500

hasCommand

hasCommand(commandName: string): boolean
Check if a command or an alias is registered with kernel
Parameters
- commandName: string
Returns boolean
- Defined in src/kernel.ts:517

getState

getState(): "booted" | "idle" | "running" | "completed"
Get the current state of the kernel.

Returns "booted" | "idle" | "running" | "completed"
- Defined in src/kernel.ts:525

getCommands

getCommands(): CommandMetaData[]
Returns a flat list of commands metadata registered with the kernel. The list is sorted alphabetically by the command name.

Returns CommandMetaData[]
- Defined in src/kernel.ts:533

getNamespaceCommands

getNamespaceCommands(namespace?: string): CommandMetaData[]
Get a list of commands for a specific namespace. All non-namespaces commands will be returned if no namespace is defined.
Parameters
- Optionalnamespace: string
Returns CommandMetaData[]
- Defined in src/kernel.ts:543

getCommand

getCommand(commandName: string): null | CommandMetaData
Returns the command metadata by its name. Returns null when the command is missing.
Parameters
- commandName: string
Returns null | CommandMetaData
- Defined in src/kernel.ts:564

getDefaultCommand

getDefaultCommand(): Command
Returns a reference for the default command. The return value is the default command constructor

Returns Command
- Defined in src/kernel.ts:572

getMainCommand

getMainCommand(): undefined | InstanceType<Command>
Returns reference to the main command

Returns undefined | InstanceType<Command>
- Defined in src/kernel.ts:579

getAliases

getAliases(): string[]
Returns an array of aliases registered.
- Call getCommandAliases method to get aliases for a given command
- Call getAliasCommand to get the command or a given alias
Returns string[]
- Defined in src/kernel.ts:589

getAliasCommand

getAliasCommand(alias: string): null | CommandMetaData
Returns the command metata for a given alias. Returns null if alias is not recognized.
Parameters
- alias: string
Returns null | CommandMetaData
- Defined in src/kernel.ts:597

getCommandAliases

getCommandAliases(commandName: string): string[]
Returns an array of aliases for a given command
Parameters
- commandName: string
Returns string[]
- Defined in src/kernel.ts:609

getNamespaces

getNamespaces(): string[]
Returns a list of namespaces. The list is sorted alphabetically by the namespace name

Returns string[]
- Defined in src/kernel.ts:621

getCommandSuggestions

getCommandSuggestions(keyword: string): string[]
Returns an array of command and aliases name suggestions for a given keyword.
Parameters
- keyword: string
Returns string[]
- Defined in src/kernel.ts:629

getNamespaceSuggestions

getNamespaceSuggestions(keyword: string): string[]
Returns an array of namespaces suggestions for a given keyword.
Parameters
- keyword: string
Returns string[]
- Defined in src/kernel.ts:657

finding

finding(callback: FindingHookHandler): Kernel<Command>
Listen for the event before we begin the process of finding the command.
Parameters
- callback: FindingHookHandler
Returns Kernel<Command>
- Defined in src/kernel.ts:676

loading

loading(callback: LoadingHookHandler): Kernel<Command>
Listen for the event when importing the command
Parameters
- callback: LoadingHookHandler
Returns Kernel<Command>
- Defined in src/kernel.ts:684

loaded

loaded(callback: LoadedHookHandler<Command>): Kernel<Command>
Listen for the event when the command has been imported
Parameters
- callback: LoadedHookHandler<Command>
Returns Kernel<Command>
- Defined in src/kernel.ts:692

executing

executing(
callback: ExecutingHookHandler<InstanceType<Command>>,
): Kernel<Command>
Listen for the event before we start to execute the command.
Parameters
- callback: ExecutingHookHandler<InstanceType<Command>>
Returns Kernel<Command>
- Defined in src/kernel.ts:700

executed

executed(callback: ExecutedHookHandler<InstanceType<Command>>): Kernel<Command>
Listen for the event after the command has been executed
Parameters
- callback: ExecutedHookHandler<InstanceType<Command>>
Returns Kernel<Command>
- Defined in src/kernel.ts:708

boot

boot(): Promise<void>
Loads commands from all the registered loaders. The "addLoader" method must be called before calling the "load" method.

Returns Promise<void>
- Defined in src/kernel.ts:717

find

find<T extends AbstractBaseCommand>(commandName: string): Promise<T>
Find a command by its name
Type Parameters
- T extends AbstractBaseCommand
Parameters
- commandName: string
Returns Promise<T>
- Defined in src/kernel.ts:774

exec

exec<T extends AbstractBaseCommand>(
commandName: string,
argv: string[],
): Promise<InstanceType<T>>
Execute a command. The second argument is an array of command-line arguments (without the command name)
Type Parameters
- T extends AbstractBaseCommand
Parameters
- commandName: string
  The name of the command to execute
- argv: string[]
  Array of command-line arguments
Returns Promise<InstanceType<T>>
Example
```
await kernel.exec('make:model', ['User', '--migration'])
```
- Defined in src/kernel.ts:815

create

create<T extends AbstractBaseCommand>(
command: T,
argv: string | string[],
): Promise<InstanceType<T>>
Creates a command instance by parsing and validating the command-line arguments
Type Parameters
- T extends AbstractBaseCommand
Parameters
- command: T
  The command class to instantiate
- argv: string | string[]
  Command-line arguments as string or array
Returns Promise<InstanceType<T>>
Example
```
const commandInstance = await kernel.create(MyCommand, ['--verbose', 'arg1'])
```
- Defined in src/kernel.ts:846

handle

handle(argv: string[]): Promise<void>
Handle process argv and execute the command. Calling this method makes kernel own the process and register SIGNAL listeners
Parameters
- argv: string[]
  Array of command-line arguments from process.argv
Returns Promise<void>
Example
```
await kernel.handle(process.argv.slice(2))
```
- Defined in src/kernel.ts:868

shortcircuit

shortcircuit(): boolean
A named function that returns true. To be used by flag listeners

Returns boolean
- Defined in src/kernel.ts:914

Class Kernel<Command>

Example

Type Parameters

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns Kernel<Command>

Properties

errorHandler

StaticcommandExecutor

StaticdefaultCommand

OptionalexitCode

ui

prompt

info

Accessors

flags

Returns ({ name: string } & Flag)[]

Example

Methods

Staticcreate

Returns Kernel<typeof BaseCommand>

Example

on

Parameters

Returns this

defineFlag

Parameters

Returns void

Example

addLoader

Parameters

Returns this

Example

addAlias

Parameters

Returns this

Example

hasCommand

Parameters

Returns boolean

getState

Returns "booted" | "idle" | "running" | "completed"

getCommands

Returns CommandMetaData[]

getNamespaceCommands

Parameters

Returns CommandMetaData[]

getCommand

Parameters

Returns null | CommandMetaData

getDefaultCommand

Returns Command

getMainCommand

Returns undefined | InstanceType<Command>

getAliases

Returns string[]

getAliasCommand

Parameters

Returns null | CommandMetaData

getCommandAliases

Parameters

Returns string[]

getNamespaces

Returns string[]

getCommandSuggestions

Parameters

Returns string[]

getNamespaceSuggestions

Parameters

Returns string[]

finding

Parameters

Returns Kernel<Command>

`Static`commandExecutor

`Static`defaultCommand

`Optional`exitCode

`Static`create