aws-cdk
Version:
CDK Toolkit, the command line tool for CDK apps
205 lines (204 loc) • 6.77 kB
TypeScript
export type IoMessageCodeCategory = 'TOOLKIT' | 'SDK' | 'ASSETS';
export type IoCodeLevel = 'E' | 'W' | 'I';
export type IoMessageSpecificCode<L extends IoCodeLevel> = `CDK_${IoMessageCodeCategory}_${L}${number}${number}${number}${number}`;
export type IoMessageCode = IoMessageSpecificCode<IoCodeLevel>;
/**
* Basic message structure for toolkit notifications.
* Messages are emitted by the toolkit and handled by the IoHost.
*/
export interface IoMessage<T> {
/**
* The time the message was emitted.
*/
readonly time: Date;
/**
* The log level of the message.
*/
readonly level: IoMessageLevel;
/**
* The action that triggered the message.
*/
readonly action: ToolkitAction;
/**
* A short message code uniquely identifying a message type using the format CDK_[CATEGORY]_[E/W/I][000-999].
*
* The level indicator follows these rules:
* - 'E' for error level messages
* - 'W' for warning level messages
* - 'I' for info/debug/trace level messages
*
* Codes ending in 000 are generic messages, while codes ending in 001-999 are specific to a particular message.
* The following are examples of valid and invalid message codes:
* ```ts
* 'CDK_ASSETS_I000' // valid: generic assets info message
* 'CDK_TOOLKIT_E002' // valid: specific toolkit error message
* 'CDK_SDK_W023' // valid: specific sdk warning message
* ```
*/
readonly code: IoMessageCode;
/**
* The message text.
*/
readonly message: string;
/**
* If true, the message will be written to stdout
* regardless of any other parameters.
*
* @default false
*/
readonly forceStdout?: boolean;
/**
* The data attached to the message.
*/
readonly data?: T;
}
export interface IoRequest<T, U> extends IoMessage<T> {
/**
* The default response that will be used if no data is returned.
*/
readonly defaultResponse: U;
}
export type IoMessageLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
export declare const levelPriority: Record<IoMessageLevel, number>;
/**
* The current action being performed by the CLI. 'none' represents the absence of an action.
*/
export type ToolkitAction = 'bootstrap' | 'synth' | 'list' | 'diff' | 'deploy' | 'rollback' | 'watch' | 'destroy' | 'context' | 'docs' | 'doctor' | 'gc' | 'import' | 'metadata' | 'notices' | 'init' | 'migrate' | 'version';
export interface IIoHost {
/**
* Notifies the host of a message.
* The caller waits until the notification completes.
*/
notify<T>(msg: IoMessage<T>): Promise<void>;
/**
* Notifies the host of a message that requires a response.
*
* If the host does not return a response the suggested
* default response from the input message will be used.
*/
requestResponse<T, U>(msg: IoRequest<T, U>): Promise<U>;
}
export interface CliIoHostProps {
/**
* The initial Toolkit action the hosts starts with.
*
* @default 'none'
*/
readonly currentAction?: ToolkitAction;
/**
* Determines the verbosity of the output.
*
* The CliIoHost will still receive all messages and requests,
* but only the messages included in this level will be printed.
*
* @default 'info'
*/
readonly logLevel?: IoMessageLevel;
/**
* Overrides the automatic TTY detection.
*
* When TTY is disabled, the CLI will have no interactions or color.
*
* @default - determined from the current process
*/
readonly isTTY?: boolean;
/**
* Whether the CliIoHost is running in CI mode.
*
* In CI mode, all non-error output goes to stdout instead of stderr.
* Set to false in the CliIoHost constructor it will be overwritten if the CLI CI argument is passed
*
* @default - determined from the environment, specifically based on `process.env.CI`
*/
readonly isCI?: boolean;
}
/**
* A simple IO host for the CLI that writes messages to the console.
*/
export declare class CliIoHost implements IIoHost {
/**
* Returns the singleton instance
*/
static instance(props?: CliIoHostProps, forceNew?: boolean): CliIoHost;
/**
* Singleton instance of the CliIoHost
*/
private static _instance;
private _currentAction;
private _isCI;
private _isTTY;
private _logLevel;
private _internalIoHost?;
private constructor();
/**
* Returns the singleton instance
*/
registerIoHost(ioHost: IIoHost): void;
/**
* The current action being performed by the CLI.
*/
get currentAction(): ToolkitAction;
/**
* Sets the current action being performed by the CLI.
*
* @param action The action being performed by the CLI.
*/
set currentAction(action: ToolkitAction);
/**
* Whether the host can use interactions and message styling.
*/
get isTTY(): boolean;
/**
* Set TTY mode, i.e can the host use interactions and message styling.
*
* @param value set TTY mode
*/
set isTTY(value: boolean);
/**
* Whether the CliIoHost is running in CI mode. In CI mode, all non-error output goes to stdout instead of stderr.
*/
get isCI(): boolean;
/**
* Set the CI mode. In CI mode, all non-error output goes to stdout instead of stderr.
* @param value set the CI mode
*/
set isCI(value: boolean);
/**
* The current threshold. Messages with a lower priority level will be ignored.
*/
get logLevel(): IoMessageLevel;
/**
* Sets the current threshold. Messages with a lower priority level will be ignored.
* @param level The new log level threshold
*/
set logLevel(level: IoMessageLevel);
/**
* Notifies the host of a message.
* The caller waits until the notification completes.
*/
notify<T>(msg: IoMessage<T>): Promise<void>;
/**
* Determines which output stream to use based on log level and configuration.
*/
private stream;
/**
* Notifies the host of a message that requires a response.
*
* If the host does not return a response the suggested
* default response from the input message will be used.
*/
requestResponse<T, U>(msg: IoRequest<T, U>): Promise<U>;
/**
* Formats a message for console output with optional color support
*/
private formatMessage;
/**
* Formats date to HH:MM:SS
*/
private formatTime;
}
/**
* Returns true if the current process is running in a CI environment
* @returns true if the current process is running in a CI environment
*/
export declare function isCI(): boolean;