@black-flag/core • Docs
@black-flag/core / index / CliError
Represents a CLI-specific error with suggested exit code and other
properties. As CliError
has built-in support for cause chaining, this class
can be used as a simple wrapper around other errors.
AppError
NonNullable
<CliErrorOptions
>
new CliError(
reason
,options
?):CliError
Represents a CLI-specific error, optionally with suggested exit code and other context.
• reason: string
| Error
• options?: CliErrorOptions
AppError.constructor
new CliError(
reason
,options
,message
,superOptions
):CliError
This constructor syntax is used by subclasses when calling this constructor
via super
.
• reason: string
| Error
• options: CliErrorOptions
• message: string
• superOptions: ErrorOptions
AppError.constructor
[$type]:
string
[]
optional
cause:unknown
NonNullable.cause
AppError.cause
node_modules/typescript/lib/lib.es2022.error.d.ts:24
dangerouslyFatal:
boolean
=false
This option is similar in intent to yargs's exitProcess()
function,
except applied more granularly.
Normally, runProgram never throws and never calls process.exit
,
instead setting process.exitCode
when an error occurs.
However, it is at times prudent to kill Node.js as soon as possible after
error handling happens. For example: the execa library struggles to abort
concurrent subcommand promises in a timely manner, and doesn't prevent them
from dumping output to stdout even after Black Flag has finished executing.
To work around this, we can set dangerouslyFatal
to true
, forcing Black
Flag to call process.exit
immediately after error handling completes.
More generally, enabling dangerouslyFatal
is a quick way to get rid of
strange behavior that can happen when your microtask queue isn't empty
(i.e. the event loop still has work to do) by the time Black Flag's error
handling code completes. However, doing this without proper consideration
of why you still have hanging promises and/or other microtasks adding
work to the event loop can lead to faulty/glitchy/flaky software and
heisenbugs. You will also have to specially handle process.exit
when
running unit/integration tests and executing command handlers within other
command handlers. Tread carefully.
NonNullable.dangerouslyFatal
message:
string
AppError.message
node_modules/typescript/lib/lib.es5.d.ts:1077
name:
string
AppError.name
node_modules/typescript/lib/lib.es5.d.ts:1076
showHelp:
boolean
=false
If true
, help text will be sent to stderr before this exception finishes
bubbling. Where the exception is thrown will determine which instance is
responsible for error text generation.
false
NonNullable.showHelp
optional
stack:string
AppError.stack
node_modules/typescript/lib/lib.es5.d.ts:1078
suggestedExitCode:
FrameworkExitCode
=FrameworkExitCode.DefaultError
The exit code that will be returned when the application exits, given nothing else goes wrong in the interim.
FrameworkExitCode.DefaultError
NonNullable.suggestedExitCode
static
optional
prepareStackTrace: (err
,stackTraces
) =>any
Optional override for formatting stack traces
• err: Error
• stackTraces: CallSite
[]
any
https://v8.dev/docs/stack-trace-api#customizing-stack-traces
AppError.prepareStackTrace
node_modules/@types/node/globals.d.ts:28
static
stackTraceLimit:number
AppError.stackTraceLimit
node_modules/@types/node/globals.d.ts:30
static
captureStackTrace(targetObject
,constructorOpt
?):void
Create .stack property on a target object
• targetObject: object
• constructorOpt?: Function
void
AppError.captureStackTrace
node_modules/@types/node/globals.d.ts:21