@rushstack/terminal 0.7.24 → 0.8.1

package/dist/terminal.d.ts

@@ -8,9 +8,37 @@
  * @packageDocumentation
  */
 
+/// <reference types="node" />
+
 import type { Brand } from '@rushstack/node-core-library';
-import type { ITerminal } from '@rushstack/node-core-library';
 import { NewlineKind } from '@rushstack/node-core-library';
+import { Writable } from 'stream';
+import { WritableOptions } from 'stream';
+
+/**
+ * Operations for working with text strings that contain
+ * {@link https://en.wikipedia.org/wiki/ANSI_escape_code | ANSI escape codes}.
+ * The most commonly used escape codes set the foreground/background color for console output.
+ * @public
+ */
+export declare class AnsiEscape {
+    private static readonly _csiRegExp;
+    private static readonly _sgrRegExp;
+    private static readonly _backslashNRegExp;
+    private static readonly _backslashRRegExp;
+    static getEscapeSequenceForAnsiCode(code: number): string;
+    /**
+     * Returns the input text with all ANSI escape codes removed.  For example, this is useful when saving
+     * colorized console output to a log file.
+     */
+    static removeCodes(text: string): string;
+    /**
+     * Replaces ANSI escape codes with human-readable tokens.  This is useful for unit tests
+     * that compare text strings in test assertions or snapshot files.
+     */
+    static formatForTests(text: string, options?: IAnsiEscapeConvertForTestsOptions): string;
+    private static _tryGetSgrFriendlyName;
+}
 
 /**
  * This class enables very basic {@link TerminalWritable.onWriteChunk} operations to be implemented
@@ -32,6 +60,82 @@ export declare class CallbackWritable extends TerminalWritable {
     protected onWriteChunk(chunk: ITerminalChunk): void;
 }
 
+/**
+ * The static functions on this class are used to produce colored text
+ * for use with a terminal that supports ANSI escape codes.
+ *
+ * Note that this API always generates color codes, regardless of whether
+ * the process's stdout is a TTY. The reason is that, in a complex program, the
+ * code that is generating strings often does not know were those strings will end
+ * up. In some cases, the same log message may get printed both to a shell
+ * that supports color AND to a log file that does not.
+ *
+ * @example
+ * ```ts
+ * console.log(Colorize.red('Red Text!'))
+ * terminal.writeLine(Colorize.green('Green Text!'), ' ', Colorize.blue('Blue Text!'));
+ *```
+ *
+ * @public
+ */
+export declare class Colorize {
+    static black(text: string): string;
+    static red(text: string): string;
+    static green(text: string): string;
+    static yellow(text: string): string;
+    static blue(text: string): string;
+    static magenta(text: string): string;
+    static cyan(text: string): string;
+    static white(text: string): string;
+    static gray(text: string): string;
+    static blackBackground(text: string): string;
+    static redBackground(text: string): string;
+    static greenBackground(text: string): string;
+    static yellowBackground(text: string): string;
+    static blueBackground(text: string): string;
+    static magentaBackground(text: string): string;
+    static cyanBackground(text: string): string;
+    static whiteBackground(text: string): string;
+    static grayBackground(text: string): string;
+    static bold(text: string): string;
+    static dim(text: string): string;
+    static underline(text: string): string;
+    static blink(text: string): string;
+    static invertColor(text: string): string;
+    static hidden(text: string): string;
+    private static _wrapTextInAnsiEscapeCodes;
+}
+
+/**
+ * Terminal provider that prints to STDOUT (for log- and verbose-level messages) and
+ * STDERR (for warning- and error-level messsages).
+ *
+ * @beta
+ */
+export declare class ConsoleTerminalProvider implements ITerminalProvider {
+    /**
+     * If true, verbose-level messages should be written to the console.
+     */
+    verboseEnabled: boolean;
+    /**
+     * If true, debug-level messages should be written to the console.
+     */
+    debugEnabled: boolean;
+    constructor(options?: Partial<IConsoleTerminalProviderOptions>);
+    /**
+     * {@inheritDoc ITerminalProvider.write}
+     */
+    write(data: string, severity: TerminalProviderSeverity): void;
+    /**
+     * {@inheritDoc ITerminalProvider.eolCharacter}
+     */
+    get eolCharacter(): string;
+    /**
+     * {@inheritDoc ITerminalProvider.supportsColor}
+     */
+    get supportsColor(): boolean;
+}
+
 /**
  * A sensible fallback column width for consoles.
  *
@@ -85,6 +189,17 @@ export declare class DiscardStdoutTransform extends TerminalTransform {
     protected onWriteChunk(chunk: ITerminalChunk): void;
 }
 
+/**
+ * Options for {@link AnsiEscape.formatForTests}.
+ * @public
+ */
+export declare interface IAnsiEscapeConvertForTestsOptions {
+    /**
+     * If true then `\n` will be replaced by `[n]`, and `\r` will be replaced by `[r]`.
+     */
+    encodeNewlines?: boolean;
+}
+
 /**
  * Constructor options for {@link CallbackWritable}.
  * @public
@@ -93,6 +208,24 @@ export declare interface ICallbackWritableOptions {
     onWriteChunk: (chunk: ITerminalChunk) => void;
 }
 
+/**
+ * Options to be provided to a {@link ConsoleTerminalProvider}
+ *
+ * @beta
+ */
+export declare interface IConsoleTerminalProviderOptions {
+    /**
+     * If true, print verbose logging messages.
+     */
+    verboseEnabled: boolean;
+    /**
+     * If true, print debug logging messages. Note that "verbose" and "debug" are considered
+     * separate message filters; if you want debug to imply verbose, it is up to your
+     * application code to enforce that.
+     */
+    debugEnabled: boolean;
+}
+
 /**
  * Constructor options for {@link DiscardStdoutTransform}
  *
@@ -101,6 +234,19 @@ export declare interface ICallbackWritableOptions {
 export declare interface IDiscardStdoutTransformOptions extends ITerminalTransformOptions {
 }
 
+/**
+ * Options for {@link PrefixProxyTerminalProvider}.
+ *
+ * @beta
+ */
+export declare interface IDynamicPrefixProxyTerminalProviderOptions extends IPrefixProxyTerminalProviderOptionsBase {
+    /**
+     * A function that returns the prefix that should be added to each line of output. This is useful
+     * for prefixing each line with a timestamp.
+     */
+    getPrefix: () => string;
+}
+
 /**
  * Constructor options for {@link NormalizeNewlinesTextRewriter}
  *
@@ -122,6 +268,21 @@ export declare interface INormalizeNewlinesTextRewriterOptions {
     ensureNewlineAtEnd?: boolean;
 }
 
+/**
+ * @beta
+ */
+export declare type IPrefixProxyTerminalProviderOptions = IStaticPrefixProxyTerminalProviderOptions | IDynamicPrefixProxyTerminalProviderOptions;
+
+/**
+ * @beta
+ */
+export declare interface IPrefixProxyTerminalProviderOptionsBase {
+    /**
+     * The {@link ITerminalProvider} that will be wrapped.
+     */
+    terminalProvider: ITerminalProvider;
+}
+
 /**
  * Constructor options for {@link SplitterTransform}.
  *
@@ -134,6 +295,18 @@ export declare interface ISplitterTransformOptions extends ITerminalWritableOpti
     destinations: TerminalWritable[];
 }
 
+/**
+ * Options for {@link PrefixProxyTerminalProvider}, with a static prefix.
+ *
+ * @beta
+ */
+export declare interface IStaticPrefixProxyTerminalProviderOptions extends IPrefixProxyTerminalProviderOptionsBase {
+    /**
+     * The prefix that should be added to each line of output.
+     */
+    prefix: string;
+}
+
 /**
  * Constructor options for {@link StderrLineTransform}
  * @beta
@@ -162,6 +335,85 @@ export declare interface IStdioSummarizerOptions {
     trailingLines?: number;
 }
 
+/**
+ * @beta
+ */
+export declare interface IStringBufferOutputOptions {
+    /**
+     * If set to true, special characters like \\n, \\r, and the \\u001b character
+     * in color control tokens will get normalized to [-n-], [-r-], and [-x-] respectively
+     *
+     * This option defaults to `true`
+     */
+    normalizeSpecialCharacters: boolean;
+}
+
+/**
+ * @beta
+ */
+export declare interface ITerminal {
+    /**
+     * Subscribe a new terminal provider.
+     */
+    registerProvider(provider: ITerminalProvider): void;
+    /**
+     * Unsubscribe a terminal provider. If the provider isn't subscribed, this function does nothing.
+     */
+    unregisterProvider(provider: ITerminalProvider): void;
+    /**
+     * Write a generic message to the terminal
+     */
+    write(...messageParts: TerminalWriteParameters): void;
+    /**
+     * Write a generic message to the terminal, followed by a newline
+     */
+    writeLine(...messageParts: TerminalWriteParameters): void;
+    /**
+     * Write a warning message to the console with yellow text.
+     *
+     * @remarks
+     * The yellow color takes precedence over any other foreground colors set.
+     */
+    writeWarning(...messageParts: TerminalWriteParameters): void;
+    /**
+     * Write a warning message to the console with yellow text, followed by a newline.
+     *
+     * @remarks
+     * The yellow color takes precedence over any other foreground colors set.
+     */
+    writeWarningLine(...messageParts: TerminalWriteParameters): void;
+    /**
+     * Write an error message to the console with red text.
+     *
+     * @remarks
+     * The red color takes precedence over any other foreground colors set.
+     */
+    writeError(...messageParts: TerminalWriteParameters): void;
+    /**
+     * Write an error message to the console with red text, followed by a newline.
+     *
+     * @remarks
+     * The red color takes precedence over any other foreground colors set.
+     */
+    writeErrorLine(...messageParts: TerminalWriteParameters): void;
+    /**
+     * Write a verbose-level message.
+     */
+    writeVerbose(...messageParts: TerminalWriteParameters): void;
+    /**
+     * Write a verbose-level message followed by a newline.
+     */
+    writeVerboseLine(...messageParts: TerminalWriteParameters): void;
+    /**
+     * Write a debug-level message.
+     */
+    writeDebug(...messageParts: TerminalWriteParameters): void;
+    /**
+     * Write a debug-level message followed by a newline.
+     */
+    writeDebugLine(...messageParts: TerminalWriteParameters): void;
+}
+
 /**
  * Represents a chunk of output that will ultimately be written to a {@link TerminalWritable}.
  *
@@ -193,6 +445,55 @@ export declare interface ITerminalChunk {
     text: string;
 }
 
+/**
+ * Implement the interface to create a terminal provider. Terminal providers
+ * can be registered to a {@link Terminal} instance to receive messages.
+ *
+ * @beta
+ */
+export declare interface ITerminalProvider {
+    /**
+     * This property should return true only if the terminal provider supports
+     * rendering console colors.
+     */
+    supportsColor: boolean;
+    /**
+     * This property should return the newline character the terminal provider
+     * expects.
+     */
+    eolCharacter: string;
+    /**
+     * This function gets called on every terminal provider upon every
+     * message function call on the terminal instance.
+     *
+     * @param data - The terminal message.
+     * @param severity - The message severity. Terminal providers can
+     * route different kinds of messages to different streams and may choose
+     * to ignore verbose or debug messages.
+     */
+    write(data: string, severity: TerminalProviderSeverity): void;
+}
+
+/**
+ * Options for {@link TerminalStreamWritable}.
+ *
+ * @beta
+ */
+export declare interface ITerminalStreamWritableOptions {
+    /**
+     * The {@link ITerminal} that the Writable will write to.
+     */
+    terminal: ITerminal;
+    /**
+     * The severity of the messages that will be written to the {@link ITerminal}.
+     */
+    severity: TerminalProviderSeverity;
+    /**
+     * Options for the underlying Writable.
+     */
+    writableOptions?: WritableOptions;
+}
+
 /**
  * Constructor options for {@link TerminalTransform}.
  *
@@ -237,6 +538,17 @@ export declare interface ITerminalWritableOptions {
     preventAutoclose?: boolean;
 }
 
+/**
+ * @beta
+ */
+export declare interface ITerminalWriteOptions {
+    /**
+     * If set to true, SGR parameters will not be replaced by the terminal
+     * standard (i.e. - red for errors, yellow for warnings).
+     */
+    doNotOverrideSgrCodes?: boolean;
+}
+
 /**
  * Constructor options for {@link TextRewriterTransform}.
  *
@@ -307,6 +619,26 @@ export declare class NormalizeNewlinesTextRewriter extends TextRewriter {
     close(unknownState: TextRewriterState): string;
 }
 
+/**
+ * Wraps an existing {@link ITerminalProvider} that prefixes each line of output with a specified
+ * prefix string.
+ *
+ * @beta
+ */
+export declare class PrefixProxyTerminalProvider implements ITerminalProvider {
+    private readonly _parentTerminalProvider;
+    private readonly _getPrefix;
+    private readonly _newlineRegex;
+    private _isOnNewline;
+    constructor(options: IPrefixProxyTerminalProviderOptions);
+    /** @override */
+    get supportsColor(): boolean;
+    /** @override */
+    get eolCharacter(): string;
+    /** @override */
+    write(data: string, severity: TerminalProviderSeverity): void;
+}
+
 /**
  * A collection of utilities for printing messages to the console.
  *
@@ -531,6 +863,117 @@ export declare class StdioWritable extends TerminalWritable {
     protected onWriteChunk(chunk: ITerminalChunk): void;
 }
 
+/**
+ * Terminal provider that stores written data in buffers separated by severity.
+ * This terminal provider is designed to be used when code that prints to a terminal
+ * is being unit tested.
+ *
+ * @beta
+ */
+export declare class StringBufferTerminalProvider implements ITerminalProvider {
+    private _standardBuffer;
+    private _verboseBuffer;
+    private _debugBuffer;
+    private _warningBuffer;
+    private _errorBuffer;
+    private _supportsColor;
+    constructor(supportsColor?: boolean);
+    /**
+     * {@inheritDoc ITerminalProvider.write}
+     */
+    write(data: string, severity: TerminalProviderSeverity): void;
+    /**
+     * {@inheritDoc ITerminalProvider.eolCharacter}
+     */
+    get eolCharacter(): string;
+    /**
+     * {@inheritDoc ITerminalProvider.supportsColor}
+     */
+    get supportsColor(): boolean;
+    /**
+     * Get everything that has been written at log-level severity.
+     */
+    getOutput(options?: IStringBufferOutputOptions): string;
+    /**
+     * Get everything that has been written at verbose-level severity.
+     */
+    getVerbose(options?: IStringBufferOutputOptions): string;
+    /**
+     * Get everything that has been written at debug-level severity.
+     */
+    getDebugOutput(options?: IStringBufferOutputOptions): string;
+    /**
+     * Get everything that has been written at error-level severity.
+     */
+    getErrorOutput(options?: IStringBufferOutputOptions): string;
+    /**
+     * Get everything that has been written at warning-level severity.
+     */
+    getWarningOutput(options?: IStringBufferOutputOptions): string;
+    private _normalizeOutput;
+}
+
+/**
+ * This class facilitates writing to a console.
+ *
+ * @beta
+ */
+export declare class Terminal implements ITerminal {
+    private _providers;
+    constructor(provider: ITerminalProvider);
+    /**
+     * {@inheritdoc ITerminal.registerProvider}
+     */
+    registerProvider(provider: ITerminalProvider): void;
+    /**
+     * {@inheritdoc ITerminal.unregisterProvider}
+     */
+    unregisterProvider(provider: ITerminalProvider): void;
+    /**
+     * {@inheritdoc ITerminal.write}
+     */
+    write(...messageParts: TerminalWriteParameters): void;
+    /**
+     * {@inheritdoc ITerminal.writeLine}
+     */
+    writeLine(...messageParts: TerminalWriteParameters): void;
+    /**
+     * {@inheritdoc ITerminal.writeWarning}
+     */
+    writeWarning(...messageParts: TerminalWriteParameters): void;
+    /**
+     * {@inheritdoc ITerminal.writeWarningLine}
+     */
+    writeWarningLine(...messageParts: TerminalWriteParameters): void;
+    /**
+     * {@inheritdoc ITerminal.writeError}
+     */
+    writeError(...messageParts: TerminalWriteParameters): void;
+    /**
+     * {@inheritdoc ITerminal.writeErrorLine}
+     */
+    writeErrorLine(...messageParts: TerminalWriteParameters): void;
+    /**
+     * {@inheritdoc ITerminal.writeVerbose}
+     */
+    writeVerbose(...messageParts: TerminalWriteParameters): void;
+    /**
+     * {@inheritdoc ITerminal.writeVerboseLine}
+     */
+    writeVerboseLine(...messageParts: TerminalWriteParameters): void;
+    /**
+     * {@inheritdoc ITerminal.writeDebug}
+     */
+    writeDebug(...messageParts: TerminalWriteParameters): void;
+    /**
+     * {@inheritdoc ITerminal.writeDebugLine}
+     */
+    writeDebugLine(...messageParts: TerminalWriteParameters): void;
+    private _writeSegmentsToProviders;
+    private _serializeLegacyColorableSequence;
+    private _normalizeWriteParameters;
+}
+
 /**
  * Specifies the kind of data represented by a {@link ITerminalChunk} object.
  * @public
@@ -546,6 +989,43 @@ export declare const enum TerminalChunkKind {
     Stderr = "E"
 }
 
+/**
+ * Similar to many popular logging packages, terminal providers support a range of message
+ * severities. These severities have built-in formatting defaults in the Terminal object
+ * (warnings are yellow, errors are red, etc.).
+ *
+ * Terminal providers may choose to suppress certain messages based on their severity,
+ * or to route some messages to other providers or not based on severity.
+ *
+ *   Severity  | Purpose
+ *   --------- | -------
+ *   error     | Build errors and fatal issues
+ *   warning   | Not necessarily fatal, but indicate a problem the user should fix
+ *   log       | Informational messages
+ *   verbose   | Additional information that may not always be necessary
+ *   debug     | Highest detail level, best used for troubleshooting information
+ *
+ * @beta
+ */
+export declare enum TerminalProviderSeverity {
+    log = 0,
+    warning = 1,
+    error = 2,
+    verbose = 3,
+    debug = 4
+}
+
+/**
+ * A adapter to allow writing to a provided terminal using Writable streams.
+ *
+ * @beta
+ */
+export declare class TerminalStreamWritable extends Writable {
+    private _writeMethod;
+    constructor(options: ITerminalStreamWritableOptions);
+    _write(chunk: string | Buffer | Uint8Array, encoding: string, callback: (error?: Error | null) => void): void;
+}
+
 /**
  * The abstract base class for {@link TerminalWritable} objects that receive an input,
  * transform it somehow, and then write the output to another `TerminalWritable`.
@@ -593,7 +1073,7 @@ export declare abstract class TerminalTransform extends TerminalWritable {
 /**
  * The abstract base class for objects that can present, route, or process text output for
  * a console application.  This output is typically prepared using
- * the {@link @rushstack/node-core-library#Terminal} API.
+ * the {@link Terminal} API.
  *
  * @remarks
  *
@@ -695,6 +1175,11 @@ export declare abstract class TerminalWritable {
     protected onClose(): void;
 }
 
+/**
+ * @beta
+ */
+export declare type TerminalWriteParameters = string[] | [...string[], ITerminalWriteOptions];
+
 /**
  * The abstract base class for operations that can be applied by {@link TextRewriterTransform}.
  *

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.40.1"
+      "packageVersion": "7.39.1"
     }
   ]
 }

package/lib/AnsiEscape.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Options for {@link AnsiEscape.formatForTests}.
+ * @public
+ */
+export interface IAnsiEscapeConvertForTestsOptions {
+    /**
+     * If true then `\n` will be replaced by `[n]`, and `\r` will be replaced by `[r]`.
+     */
+    encodeNewlines?: boolean;
+}
+/**
+ * Operations for working with text strings that contain
+ * {@link https://en.wikipedia.org/wiki/ANSI_escape_code | ANSI escape codes}.
+ * The most commonly used escape codes set the foreground/background color for console output.
+ * @public
+ */
+export declare class AnsiEscape {
+    private static readonly _csiRegExp;
+    private static readonly _sgrRegExp;
+    private static readonly _backslashNRegExp;
+    private static readonly _backslashRRegExp;
+    static getEscapeSequenceForAnsiCode(code: number): string;
+    /**
+     * Returns the input text with all ANSI escape codes removed.  For example, this is useful when saving
+     * colorized console output to a log file.
+     */
+    static removeCodes(text: string): string;
+    /**
+     * Replaces ANSI escape codes with human-readable tokens.  This is useful for unit tests
+     * that compare text strings in test assertions or snapshot files.
+     */
+    static formatForTests(text: string, options?: IAnsiEscapeConvertForTestsOptions): string;
+    private static _tryGetSgrFriendlyName;
+}
+//# sourceMappingURL=AnsiEscape.d.ts.map

package/lib/AnsiEscape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnsiEscape.d.ts","sourceRoot":"","sources":["../src/AnsiEscape.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,MAAM,WAAW,iCAAiC;IAChD;;OAEG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,UAAU;IAGrB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAA2D;IAI7F,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAwB;IAE1D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAiB;IAC1D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAiB;WAE5C,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIhE;;;OAGG;WACW,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAK/C;;;OAGG;WACW,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iCAAiC,GAAG,MAAM;IAiC/F,OAAO,CAAC,MAAM,CAAC,sBAAsB;CAsEtC"}