@black-flag/core / index
- Arguments
- ChildConfiguration
- Configuration
- ConfigurationHooks
- ConfigureArguments
- ConfigureErrorHandlingEpilogue
- ConfigureExecutionContext
- ConfigureExecutionEpilogue
- ConfigureExecutionPrologue
- ImportedConfigurationModule
- NullArguments
- ParentConfiguration
- RootConfiguration
Ƭ Arguments<CustomCliArguments, CustomExecutionContext>: _Arguments<FrameworkArguments<CustomExecutionContext> & CustomCliArguments>
Represents the parsed CLI arguments, plus _ and $0, any (hidden)
arguments/properties specific to Black Flag, and an indexer falling back to
unknown for unrecognized arguments.
| Name | Type |
|---|---|
CustomCliArguments |
extends Record<string, unknown> = Record<string, unknown> |
CustomExecutionContext |
extends ExecutionContext = ExecutionContext |
Ƭ ChildConfiguration<CustomCliArguments, CustomExecutionContext>: Partial<Configuration<CustomCliArguments, CustomExecutionContext>>
A partial extension to the Configuration interface for child configurations. This type was designed for use in external ESM/CJS module files that will eventually get imported via auto-discovery.
| Name | Type |
|---|---|
CustomCliArguments |
extends Record<string, unknown> = Record<string, unknown> |
CustomExecutionContext |
extends ExecutionContext = ExecutionContext |
Ƭ Configuration<CustomCliArguments, CustomExecutionContext>: Object
A replacement for the CommandModule type that comes with yargs.
Auto-discovered configuration modules must implement this interface or a
subtype of this interface.
| Name | Type |
|---|---|
CustomCliArguments |
extends Record<string, unknown> = Record<string, unknown> |
CustomExecutionContext |
extends ExecutionContext = ExecutionContext |
| Name | Type | Description |
|---|---|---|
aliases |
string[] |
An array of command aliases as interpreted by yargs. WARNING: positional arguments ARE NOT ALLOWED HERE and including them will lead to strange behavior! If you want to add positional arguments, export Configuration.command instead. Note: when a command file is interpreted as a RootConfiguration, aliases is effectively ignored. Default ts [] |
builder |
{ [key: string]: _Options; } | (blackFlag: Omit<EffectorProgram<CustomCliArguments, CustomExecutionContext>, "parseAsync" | "fail" | "command" | "command_deferred" | "command_finalize_deferred">, helpOrVersionSet: boolean, argv?: Arguments<CustomCliArguments, CustomExecutionContext>) => void | EffectorProgram<CustomCliArguments, CustomExecutionContext> | { [key: string]: _Options; } | _Program |
An object containing yargs options configuration or a function that will receive the current Black Flag program. Unlike with vanilla yargs, you do not need to return anything at all; "returning" undefined/void is equivalent. If you return something other than the blackFlag parameter, such as an object of options, it will be passed to yargs::options for you. Note 1: if builder is a function, it cannot be async or return a promise due to a yargs bug present at time of writing. However, a Configuration module can export an async function, so hoist any async logic out of the builder function to work around this bug for now. Note 2: if positional arguments are given and your command accepts them (i.e. provided via Configuration.command and configured via yargs::positional), they are only accessible from argv?._ (builder's third parameter). This is because positional arguments, while fully supported by Black Flag, are parsed and validated after builder is first invoked and so aren't available until a little later. Default ts {} |
command |
"$0" | `$0 ${string}` |
The command as interpreted by yargs. May contain positional arguments. It is usually unnecessary to change or use this property if you're not using positional arguments. If you want to change your command's name, use Configuration.name. If you want to change the usage text, use Configuration.usage. Default ts "$0" |
deprecated |
string | boolean |
If truthy, the command will be considered "deprecated" by yargs. If deprecated is a string, it will additionally be treated as a deprecation message that will appear alongside the command in help text. Default ts false |
description |
string | false |
The description for the command in help text. If false, the command will be considered "hidden" by yargs. Default ts "" |
handler |
(argv: Arguments<CustomCliArguments, CustomExecutionContext>) => Promisable<void> |
- |
name |
string |
The name of the command. Any spaces will be replaced with hyphens. Including a character that yargs does not consider valid for a command name will result in an error. Defaults to the filename containing the configuration, excluding its extension, or the directory name (with spaces replaced) if the filename without extension is "index". |
usage |
string |
Set a usage message shown at the top of the command's help text. Several replacements are made to the usage string before it is output. In order: - $000 will be replaced by the entire command itself (including full canonical name and parameters). - $1 will be replaced by the description of the command. - $0 will be replaced with the full canonical name of the command. Default ts "Usage: $000\n\n$1" |
Ƭ ConfigurationHooks: Object
An object containing zero or more configuration hooks. See each hook type definition for details.
| Name | Type | Description |
|---|---|---|
configureArguments? |
ConfigureArguments |
This function is called once towards the beginning of the execution of PreExecutionContext::execute and should return a process.argv-like array. This is where yargs middleware and other argument pre-processing can be implemented. |
configureErrorHandlingEpilogue? |
ConfigureErrorHandlingEpilogue |
This function is called once at the very end of the error handling process after an error has occurred. Note that this function is always called whenever there is an error, regardless of which other functions have already been called. The only exceptions to this are if (1) the error occurs within configureErrorHandlingEpilogue itself or (2) the error is an instance of GracefulEarlyExitError. This function is also called even after yargs internally handles and reports an argument parsing/validation error. |
configureExecutionContext? |
ConfigureExecutionContext |
This function is called once towards the beginning of the execution of configureProgram and should return what will become the global ExecutionContext singleton. Note that any errors thrown this early in the initialization process will be thrown as-is and will NOT trigger ConfigureErrorHandlingEpilogue. |
configureExecutionEpilogue? |
ConfigureExecutionEpilogue |
This function is called once after CLI argument parsing completes and either (1) handler execution succeeds or (2) a GracefulEarlyExitError is thrown. The value returned by this function is used as the return value of the PreExecutionContext::execute method. This function will not be called when yargs argument validation fails. This function is the complement of ConfigureExecutionPrologue. |
configureExecutionPrologue? |
ConfigureExecutionPrologue |
This function is called once towards the end of the execution of configureProgram, after all commands have been discovered but before any have been executed, and should apply any final configurations to the programs that constitute the command line interface. All commands and sub-commands known to Black Flag are available in the ExecutionContext.commands map, which can be accessed from the context parameter or from the Arguments object returned by Program::parseAsync et al. This function is the complement of ConfigureExecutionEpilogue. Note that any errors thrown this early in the initialization process will be thrown as-is and will NOT trigger ConfigureErrorHandlingEpilogue. |
Ƭ ConfigureArguments<CustomContext>: (rawArgv: typeof process.argv, context: CustomContext) => Promisable<typeof process.argv>
This function is called once towards the beginning of the execution of
PreExecutionContext::execute and should return a process.argv-like array.
This is where yargs middleware and other argument pre-processing can be implemented.
| Name | Type |
|---|---|
CustomContext |
extends ExecutionContext = ExecutionContext |
▸ (rawArgv, context): Promisable<typeof process.argv>
| Name | Type |
|---|---|
rawArgv |
typeof process.argv |
context |
CustomContext |
Promisable<typeof process.argv>
Ƭ ConfigureErrorHandlingEpilogue<CustomContext>: (meta: { error: unknown ; exitCode: number ; message: string }, argv: Omit<Partial<Arguments>, typeof $executionContext> & { [$executionContext]: ExecutionContext }, context: CustomContext) => Promisable<void>
This function is called once at the very end of the error handling process after an error has occurred.
Note that this function is always called whenever there is an error,
regardless of which other functions have already been called. The only
exceptions to this are if (1) the error occurs within
configureErrorHandlingEpilogue itself or (2) the error is an instance of
GracefulEarlyExitError.
This function is also called even after yargs internally handles and reports an argument parsing/validation error.
| Name | Type |
|---|---|
CustomContext |
extends ExecutionContext = ExecutionContext |
▸ (meta, argv, context): Promisable<void>
| Name | Type |
|---|---|
meta |
Object |
meta.error |
unknown |
meta.exitCode |
number |
meta.message |
string |
argv |
Omit<Partial<Arguments>, typeof $executionContext> & { [$executionContext]: ExecutionContext } |
context |
CustomContext |
Promisable<void>
Ƭ ConfigureExecutionContext<CustomContext>: (context: ExecutionContext) => Promisable<CustomContext>
This function is called once towards the beginning of the execution of
configureProgram and should return what will become the global
ExecutionContext singleton.
Note that any errors thrown this early in the initialization process will be thrown as-is and will NOT trigger ConfigureErrorHandlingEpilogue.
| Name | Type |
|---|---|
CustomContext |
extends ExecutionContext = ExecutionContext |
▸ (context): Promisable<CustomContext>
| Name | Type |
|---|---|
context |
ExecutionContext |
Promisable<CustomContext>
Ƭ ConfigureExecutionEpilogue<CustomContext>: (argv: Arguments, context: CustomContext) => Promisable<Arguments>
This function is called once after CLI argument parsing completes and either
(1) handler execution succeeds or (2) a GracefulEarlyExitError is thrown.
The value returned by this function is used as the return value of the
PreExecutionContext::execute method. This function will not be called
when yargs argument validation fails.
This function is the complement of ConfigureExecutionPrologue.
| Name | Type |
|---|---|
CustomContext |
extends ExecutionContext = ExecutionContext |
▸ (argv, context): Promisable<Arguments>
| Name | Type |
|---|---|
argv |
Arguments |
context |
CustomContext |
Promisable<Arguments>
Ƭ ConfigureExecutionPrologue<CustomContext>: (rootPrograms: Programs, context: CustomContext) => Promisable<void>
This function is called once towards the end of the execution of
configureProgram, after all commands have been discovered but before any
have been executed, and should apply any final configurations to the programs
that constitute the command line interface.
All commands and sub-commands known to Black Flag are available in the
ExecutionContext.commands map, which can be accessed from the
context parameter or from the Arguments object returned by
Program::parseAsync et al.
This function is the complement of ConfigureExecutionEpilogue.
Note that any errors thrown this early in the initialization process will be thrown as-is and will NOT trigger ConfigureErrorHandlingEpilogue.
| Name | Type |
|---|---|
CustomContext |
extends ExecutionContext = ExecutionContext |
▸ (rootPrograms, context): Promisable<void>
| Name | Type |
|---|---|
rootPrograms |
Programs |
context |
CustomContext |
Promisable<void>
Ƭ ImportedConfigurationModule<CustomCliArguments, CustomExecutionContext>: (context: ExecutionContext) => Promisable<Partial<RootConfiguration<CustomCliArguments, CustomExecutionContext> | ParentConfiguration<CustomCliArguments, CustomExecutionContext> | ChildConfiguration<CustomCliArguments, CustomExecutionContext>>> | Partial<RootConfiguration<CustomCliArguments, CustomExecutionContext> | ParentConfiguration<CustomCliArguments, CustomExecutionContext> | ChildConfiguration<CustomCliArguments, CustomExecutionContext>> & { default?: ImportedConfigurationModule<CustomCliArguments, CustomExecutionContext> }
Represents a Configuration object imported from a CJS/ESM module external to the CLI framework (e.g. importing an auto-discovered config module from a file).
| Name | Type |
|---|---|
CustomCliArguments |
extends Record<string, unknown> = Record<string, unknown> |
CustomExecutionContext |
extends ExecutionContext = ExecutionContext |
Ƭ NullArguments<CustomExecutionContext>: { $0: "<NullArguments: no parse result available due to exception>" ; _: [] } & FrameworkArguments<CustomExecutionContext>
Represents an empty or "null" Arguments object devoid of useful data.
This result type is fed to certain configuration hooks and returned by
various Arguments-returning functions when an exceptional event prevents
yargs from returning a real Arguments parse result.
| Name | Type |
|---|---|
CustomExecutionContext |
extends ExecutionContext = ExecutionContext |
Ƭ ParentConfiguration<CustomCliArguments, CustomExecutionContext>: Partial<Configuration<CustomCliArguments, CustomExecutionContext>>
A partial extension to the Configuration interface for non-root parent configurations. This type was designed for use in external ESM/CJS module files that will eventually get imported via auto-discovery.
| Name | Type |
|---|---|
CustomCliArguments |
extends Record<string, unknown> = Record<string, unknown> |
CustomExecutionContext |
extends ExecutionContext = ExecutionContext |
Ƭ RootConfiguration<CustomCliArguments, CustomExecutionContext>: Partial<ParentConfiguration<CustomCliArguments, CustomExecutionContext>>
A partial extension to the Configuration interface for root configurations. This type was designed for use in external ESM/CJS module files that will eventually get imported via auto-discovery.
| Name | Type |
|---|---|
CustomCliArguments |
extends Record<string, unknown> = Record<string, unknown> |
CustomExecutionContext |
extends ExecutionContext = ExecutionContext |
• Const $executionContext: typeof $executionContext
A symbol allowing access to the ExecutionContext object "hidden" within
each Arguments instance.
▸ configureProgram<CustomContext>(commandModulePath, configurationHooks?): Promise<PreExecutionContext>
Create and return a PreExecutionContext containing fully-configured Program instances and an Executor entry point function.
Command auto-discovery will occur at commandModulePath. An exception will
occur if no commands are loadable from the given commandModulePath.
This function throws whenever an exception occurs, making it not ideal as an entry point for a CLI. See runProgram for a wrapper function that handles exceptions and sets the exit code for you.
| Name | Type |
|---|---|
CustomContext |
extends ExecutionContext = ExecutionContext |
| Name | Type | Description |
|---|---|---|
commandModulePath |
string |
Command auto-discovery will occur at commandModulePath. An exception will occur if no commands are loadable from the given commandModulePath. 'file://...'-style URLs are also accepted. |
configurationHooks? |
Promisable<ConfigurationHooks> |
- |
Promise<PreExecutionContext>
▸ isCliError(parameter): parameter is CliError
Type guard for CliError.
| Name | Type |
|---|---|
parameter |
unknown |
parameter is CliError
▸ isGracefulEarlyExitError(parameter): parameter is GracefulEarlyExitError
Type guard for GracefulEarlyExitError.
| Name | Type |
|---|---|
parameter |
unknown |
parameter is GracefulEarlyExitError
▸ runProgram<CustomCliArguments>(...args): Promise<NullArguments | Arguments<CustomCliArguments> | undefined>
Invokes the dynamically imported
configureProgram(commandModulePath).execute() function.
This function is suitable for a CLI entry point since it will never throw
or reject no matter what. Instead, when an error is caught,
process.exitCode is set to the appropriate value and either NullArguments
(only if GracefulEarlyExitError was thrown) or undefined is returned.
Note: It is always safe to invoke this form of runProgram as many times as
desired.
| Name | Type |
|---|---|
CustomCliArguments |
extends Record<string, unknown> = Record<string, unknown> |
| Name | Type |
|---|---|
...args |
[commandModulePath: string] |
Promise<NullArguments | Arguments<CustomCliArguments> | undefined>
NullArguments if GracefulEarlyExitError is thrown, undefined
if any other error occurs, or Arguments otherwise.
▸ runProgram<CustomCliArguments>(...args): Promise<NullArguments | Arguments<CustomCliArguments> | undefined>
Invokes the dynamically imported configureProgram(commandModulePath, configurationHooks).execute() function.
This function is suitable for a CLI entry point since it will never throw
or reject no matter what. Instead, when an error is caught,
process.exitCode is set to the appropriate value and either NullArguments
(only if GracefulEarlyExitError was thrown) or undefined is returned.
Note: It is always safe to invoke this form of runProgram as many times as
desired.
| Name | Type |
|---|---|
CustomCliArguments |
extends Record<string, unknown> = Record<string, unknown> |
| Name | Type |
|---|---|
...args |
[commandModulePath: string, configurationHooks: Promisable<ConfigurationHooks>] |
Promise<NullArguments | Arguments<CustomCliArguments> | undefined>
NullArguments if GracefulEarlyExitError is thrown, undefined
if any other error occurs, or Arguments otherwise.
▸ runProgram<CustomCliArguments>(...args): Promise<NullArguments | Arguments<CustomCliArguments> | undefined>
Invokes the preExecutionContext.execute() function.
WARNING: reusing the same preExecutionContext with multiple invocations
of runProgram will cause successive invocations to fail. This is because
yargs does not support calling yargs::parseAsync more than once. If this is
unacceptable, do not pass runProgram a preExecutionContext property.
This function is suitable for a CLI entry point since it will never throw
or reject no matter what. Instead, when an error is caught,
process.exitCode is set to the appropriate value and either NullArguments
(only if GracefulEarlyExitError was thrown) or undefined is returned.
| Name | Type |
|---|---|
CustomCliArguments |
extends Record<string, unknown> = Record<string, unknown> |
| Name | Type |
|---|---|
...args |
[commandModulePath: string, preExecutionContext: Promisable<PreExecutionContext>] |
Promise<NullArguments | Arguments<CustomCliArguments> | undefined>
NullArguments if GracefulEarlyExitError is thrown, undefined
if any other error occurs, or Arguments otherwise.
▸ runProgram<CustomCliArguments>(...args): Promise<NullArguments | Arguments<CustomCliArguments>>
Invokes the dynamically imported
configureProgram(commandModulePath).execute(argv) function. If argv is a
string, argv = argv.split(' ') is applied first.
This function is suitable for a CLI entry point since it will never throw
or reject no matter what. Instead, when an error is caught,
process.exitCode is set to the appropriate value and either NullArguments
(only if GracefulEarlyExitError was thrown) or undefined is returned.
Note: It is always safe to invoke this form of runProgram as many times as
desired.
| Name | Type |
|---|---|
CustomCliArguments |
extends Record<string, unknown> = Record<string, unknown> |
| Name | Type |
|---|---|
...args |
[commandModulePath: string, argv: string | string[]] |
Promise<NullArguments | Arguments<CustomCliArguments>>
NullArguments if GracefulEarlyExitError is thrown, undefined
if any other error occurs, or Arguments otherwise.
▸ runProgram<CustomCliArguments>(...args): Promise<NullArguments | Arguments<CustomCliArguments>>
Invokes the dynamically imported configureProgram(commandModulePath, configurationHooks).execute(argv) function. If argv is a string, argv = argv.split(' ') is applied first.
This function is suitable for a CLI entry point since it will never throw
or reject no matter what. Instead, when an error is caught,
process.exitCode is set to the appropriate value and either NullArguments
(only if GracefulEarlyExitError was thrown) or undefined is returned.
Note: It is always safe to invoke this form of runProgram as many times as
desired.
| Name | Type |
|---|---|
CustomCliArguments |
extends Record<string, unknown> = Record<string, unknown> |
| Name | Type |
|---|---|
...args |
[commandModulePath: string, argv: string | string[], configurationHooks: Promisable<ConfigurationHooks>] |
Promise<NullArguments | Arguments<CustomCliArguments>>
NullArguments if GracefulEarlyExitError is thrown, undefined
if any other error occurs, or Arguments otherwise.
▸ runProgram<CustomCliArguments>(...args): Promise<NullArguments | Arguments<CustomCliArguments>>
Invokes the preExecutionContext.execute(argv) function. If argv is a
string, argv = argv.split(' ') is applied first.
WARNING: reusing the same preExecutionContext with multiple invocations
of runProgram will cause successive invocations to fail. This is because
yargs does not support calling yargs::parseAsync more than once. If this is
unacceptable, do not pass runProgram a preExecutionContext property.
This function is suitable for a CLI entry point since it will never throw
or reject no matter what. Instead, when an error is caught,
process.exitCode is set to the appropriate value and either NullArguments
(only if GracefulEarlyExitError was thrown) or undefined is returned.
| Name | Type |
|---|---|
CustomCliArguments |
extends Record<string, unknown> = Record<string, unknown> |
| Name | Type |
|---|---|
...args |
[commandModulePath: string, argv: string | string[], preExecutionContext: Promisable<PreExecutionContext>] |
Promise<NullArguments | Arguments<CustomCliArguments>>
NullArguments if GracefulEarlyExitError is thrown, undefined
if any other error occurs, or Arguments otherwise.