@salesforce/command
Version:
Salesforce CLI base command class
225 lines (224 loc) • 8.31 kB
TypeScript
import { Optional } from '@salesforce/ts-types';
/**
* A table option configuration type that can be the TableOptions as defined by
* [oclif/cli-ux](https://github.com/oclif/cli-ux/blob/master/src/styled/table.ts) or a string array of table keys to be used as table headers
* for simple tables.
*
* @typedef {object} SfdxTableOptions
* @property {TableOptions | string[]} options
*/
/**
* A prompt option configuration as defined by
* [oclif/cli-ux](https://github.com/oclif/cli-ux/blob/master/src/prompt.ts).
*
* @typedef {object} IPromptOptions
* @property {string} prompt The prompt string displayed to the user.
* @property {'normal' | 'mask' | 'hide'} type `Normal` does not hide the user input, `mask` hides the user input after the user presses `ENTER`, and `hide` hides the user input as it is being typed.
*/
/**
* An action option configuration as defined by
* [oclif/cli-ux](https://github.com/oclif/cli-ux/blob/master/src/action/base.ts).
*
* @typedef {object} OclifActionOptions
* @property {boolean} stdout The option to display to stdout or not.
*/
import { Logger } from '@salesforce/core';
import { CliUx } from '@oclif/core';
import { Options as OclifActionOptions } from '@oclif/core/lib/cli-ux/action/base';
import { IPromptOptions } from '@oclif/core/lib/cli-ux';
/**
* @deprecated Use Ux from `@salesforce/sf-plugins-core` instead
* Utilities for interacting with terminal I/O.
*/
export declare class UX {
private logger;
/**
* Collection of warnings that can be accessed and manipulated later.
*
* @type {Set<string>}
*/
static warnings: Set<string>;
cli: typeof CliUx;
private isOutputEnabled;
/**
* Do not directly construct instances of this class -- use {@link UX.create} instead.
*/
constructor(logger: Logger, isOutputEnabled?: boolean, ux?: typeof CliUx);
/**
* Formats a deprecation warning for display to `stderr`, `stdout`, and/or logs.
*
* @param {DeprecationDefinition} def The definition for the deprecated object.
* @returns {string} The formatted deprecation message.
*/
static formatDeprecationWarning(def: DeprecationDefinition): string;
/**
* Create a `UX` instance.
*
* @returns {Promise<UX>} A `Promise` of the created `UX` instance.
*/
static create(): Promise<UX>;
/**
* Logs at `INFO` level and conditionally writes to `stdout` if stream output is enabled.
*
* @param {...any[]} args The messages or objects to log.
* @returns {UX}
*/
log(...args: string[]): UX;
/**
* Log JSON to stdout and to the log file with log level info.
*
* @param {object} obj The object to log -- must be serializable as JSON.
* @returns {UX}
* @throws {TypeError} If the object is not JSON-serializable.
*/
logJson(obj: Record<string, unknown>): UX;
/**
* Prompt the user for input.
*
* @param {string} name The string that the user sees when prompted for information.
* @param {IPromptOptions} options A prompt option configuration.
* @returns {Promise<string>} The user input to the prompt.
*/
prompt(name: string, options?: IPromptOptions): Promise<string>;
/**
* Prompt the user for confirmation.
*
* @param {string} message The message displayed to the user.
* @returns {Promise<boolean>} Returns `true` if the user inputs 'y' or 'yes', and `false` if the user inputs 'n' or 'no'.
*/
confirm(message: string): Promise<boolean>;
/**
* Start a spinner action after displaying the given message.
*
* @param {string} message The message displayed to the user.
* @param {string} status The status displayed to the user.
* @param {OclifActionOptions} opts The options to select whereas spinner will output to stderr or stdout.
*/
startSpinner(message: string, status?: string, opts?: OclifActionOptions): void;
/**
* Pause the spinner and call the given function.
*
* @param {function} fn The function to be called in the pause.
* @param {string} icon The string displayed to the user.
* @returns {T} The result returned by the passed in function.
*/
pauseSpinner<T>(fn: () => T, icon?: string): Optional<T>;
/**
* Update the spinner status.
*
* @param {string} status The message displayed to the user.
*/
setSpinnerStatus(status?: string): void;
/**
* Get the spinner status.
*
* @returns {Optional<string>}
*/
getSpinnerStatus(): Optional<string>;
/**
* Stop the spinner action.
*
* @param {string} message The message displayed to the user.
*/
stopSpinner(message?: string): void;
/**
* Logs a warning as `WARN` level and conditionally writes to `stderr` if the log
* level is `WARN` or above and stream output is enabled. The message is added
* to the static {@link UX.warnings} set if stream output is _not_ enabled, for later
* consumption and manipulation.
*
* @param {string} message The warning message to output.
* @returns {UX}
* @see UX.warnings
*/
warn(message: string): UX;
/**
* Logs an error at `ERROR` level and conditionally writes to `stderr` if stream
* output is enabled.
*
* @param {...any[]} args The errors to log.
* @returns {UX}
*/
error(...args: unknown[]): UX;
/**
* Logs an object as JSON at `ERROR` level and to `stderr`.
*
* @param {object} obj The error object to log -- must be serializable as JSON.
* @returns {UX}
* @throws {TypeError} If the object is not JSON-serializable.
*/
errorJson(obj: object): UX;
/**
* Logs at `INFO` level and conditionally writes to `stdout` in a table format if
* stream output is enabled.
*
* @param {object[]} rows The rows of data to be output in table format.
* @param columns Table column options
* @param {SfdxTableOptions} options The {@link SfdxTableOptions} to use for formatting.
* @returns {UX}
*/
table(rows: any[], columns?: TableColumns, options?: CliUx.Table.table.Options): UX;
/**
* Logs at `INFO` level and conditionally writes to `stdout` in a styled object format if
* stream output is enabled.
*
* @param {object} obj The object to be styled for stdout.
* @param {string[]} [keys] The object keys to be written to stdout.
* @returns {UX}
*/
styledObject(obj: object, keys?: string[]): UX;
/**
* Log at `INFO` level and conditionally write to `stdout` in styled JSON format if
* stream output is enabled.
*
* @param {object} obj The object to be styled for stdout.
* @returns {UX}
*/
styledJSON(obj: object): UX;
/**
* Logs at `INFO` level and conditionally writes to `stdout` in a styled header format if
* stream output is enabled.
*
* @param {string} header The header to be styled.
* @returns {UX}
*/
styledHeader(header: string): UX;
}
/**
* A table option configuration type. May be a detailed configuration, or
* more simply just a string array in the simple cases where table header values
* are the only desired config option.
*/
export type TableColumns = CliUx.Table.table.Columns<any> | string[];
/**
* A deprecation configuration type. A typical instance can pass `name`,
* `type`, and `version` for a standard message. Alternatively, the `messageOverride` can
* be used as a special case deprecated message. Used when defining a deprecation on a
* command or flag.
*/
export type Deprecation = {
to?: string;
message?: string;
} & ({
version: number | string;
} | {
messageOverride: string;
});
/**
*
* @deprecated use deprecation from oclif/core
*
* A deprecation warning message configuration type. A typical instance can pass `name`,
* `type`, and `version` for a standard message. Alternatively, the `messageOverride` can
* be used as a special case deprecated message. Used when formatting a deprecation message.
*/
export type DeprecationDefinition = {
to?: string;
message?: string;
} & ({
version: number | string;
name: string;
type: string;
} | {
messageOverride: string;
});