bananass-utils-console 0.8.0 → 0.9.0

package/build/logger.js

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Console logger.
+ * @module bananass-utils-console/logger
+ */
+// --------------------------------------------------------------------------------
+// Import
+// --------------------------------------------------------------------------------
+import { styleText } from 'node:util';
+// --------------------------------------------------------------------------------
+// Class
+// --------------------------------------------------------------------------------
+class Logger {
+    // ------------------------------------------------------------------------------
+    // Private Properties
+    // ------------------------------------------------------------------------------
+    #debug;
+    #quiet;
+    #textPrefix;
+    #textPrefixDefault = '>';
+    #lastMethodCalled = 'log';
+    #undeclaredValue = Symbol('undeclared-value');
+    constructor(options = {}) {
+        this.#debug = options.debug ?? false;
+        this.#quiet = options.quiet ?? false;
+        this.#textPrefix =
+            typeof options.textPrefix === 'boolean'
+                ? options.textPrefix
+                    ? this.#textPrefixDefault
+                    : this.#undeclaredValue
+                : (options.textPrefix ?? this.#textPrefixDefault);
+    }
+    // ------------------------------------------------------------------------------
+    // Public Methods
+    // ------------------------------------------------------------------------------
+    /**
+     * Log a message or executes a callback.
+     *
+     * The first parameter can be a message or a callback function.
+     * - If it's a function, it's invoked with subsequent arguments.
+     * - Otherwise, the message (with a configured text prefix) and additional arguments are logged.
+     *
+     * Behavior based on `quiet` option:
+     * - `quiet === true`: output X
+     * - `quiet === false`: output O
+     *
+     * @param params The message or callback function, followed by any additional arguments.
+     * @returns The current `Logger` instance for chaining.
+     */
+    log(...params) {
+        const textOrCallback = typeof params[0] !== 'undefined' // Same with default parameter implemetation using `arguments`
+            ? params[0]
+            : params.length > 0
+                ? undefined
+                : this.#undeclaredValue;
+        const args = params.slice(1);
+        this.#lastMethodCalled = 'log';
+        if (this.#quiet)
+            return this;
+        if (typeof textOrCallback === 'function') {
+            textOrCallback(...args);
+        }
+        else {
+            // eslint-disable-next-line no-console -- Needed for logging.
+            console.log(...[this.#textPrefix, textOrCallback, ...args].filter(arg => arg !== this.#undeclaredValue));
+        }
+        return this;
+    }
+    /**
+     * Log a message or executes a callback in debug mode.
+     *
+     * The first parameter can be a message or a callback function.
+     * - If it's a function, it's invoked with subsequent arguments.
+     * - Otherwise, the message (with a configured text prefix) and additional arguments are logged in debug mode.
+     *
+     * Behavior based on `debug` and `quiet` options:
+     * - `quiet === true`: output X
+     * - `quiet === false && debug === true`: output O
+     * - `quiet === false && debug === false`: output X
+     *
+     * @param params The message or callback function, followed by any additional arguments.
+     * @returns The current `Logger` instance for chaining.
+     */
+    debug(...params) {
+        const textOrCallback = typeof params[0] !== 'undefined'
+            ? params[0]
+            : params.length > 0
+                ? undefined
+                : this.#undeclaredValue;
+        const args = params.slice(1);
+        this.#lastMethodCalled = 'debug';
+        if (this.#quiet)
+            return this;
+        if (!this.#debug)
+            return this;
+        if (typeof textOrCallback === 'function') {
+            textOrCallback(...args);
+        }
+        else {
+            // eslint-disable-next-line no-console -- Needed for logging.
+            console.log(...[this.#textPrefix, textOrCallback, ...args]
+                .filter(arg => arg !== this.#undeclaredValue)
+                .map(arg => (typeof arg === 'string' ? styleText('gray', arg) : arg)));
+        }
+        return this;
+    }
+    /**
+     * Ends the current line by logging an empty line using the last method called.
+     *
+     * This method temporarily sets the text prefix to an undeclared value,
+     * then invokes either `log()` or `debug()` depending on the previously method called.
+     * After logging, it restores the original text prefix.
+     *
+     * @returns The current `Logger` instance for chaining.
+     */
+    eol() {
+        const prevTextPrefix = this.#textPrefix;
+        this.#textPrefix = this.#undeclaredValue;
+        if (this.#lastMethodCalled === 'log') {
+            this.log();
+        }
+        else {
+            this.debug();
+        }
+        this.#textPrefix = prevTextPrefix;
+        return this;
+    }
+    // ------------------------------------------------------------------------------
+    // Getters and Setters
+    // ------------------------------------------------------------------------------
+    /**
+     * Get the last method called.
+     * @returns {'log' | 'debug'}
+     */
+    get lastMethodCalled() {
+        return this.#lastMethodCalled;
+    }
+}
+// --------------------------------------------------------------------------------
+// Export
+// --------------------------------------------------------------------------------
+/**
+ * Create a new `Logger` instance.
+ *
+ * @param options The logger options.
+ * @returns A new `Logger` instance.
+ *
+ * @example
+ * import createLogger from 'bananass-utils-console/logger';
+ *
+ * const logger = createLogger({
+ *   debug: false,
+ *   quiet: false,
+ *   textPrefix: '>',
+ * })
+ *
+ * logger
+ *   .log('Hello, log!');
+ *   .debug('Hello, debug!');
+ *   .eol();
+ */
+export default function createLogger(options) {
+    return new Logger(options);
+}

package/build/{spinner/spinner.d.ts → spinner.d.ts}

@@ -1,101 +1,57 @@
 /**
- * Create a new spinner instance.
- *
- * @param {Options} [options]
- * @returns {Spinner} A new spinner instance.
- *
- * @example
- * import createSpinner from 'bananass-utils-console/spinner';
- *
- * const spinner = createSpinner({
- *   text: 'Loading…'
- *   color: 'yellow',
- *   stream: process.stderr,
- *   spinner: {
- *     frames: ['-', '\\', '|', '/'],
- *     interval: 100,
- *   },
- * }).start();
- *
- * setTimeout(() => {
- *   spinner.success('Success!');
- * }, 2000);
+ * @fileoverview Console spinner.
+ * @module bananass-utils-console/spinner
+ * @license MIT Portions of this code were borrowed from [`yocto-spinner`](https://github.com/sindresorhus/yocto-spinner).
  */
-export default function createSpinner(options?: Options): Spinner;
-export type ForegroundColors = "black" | "blackBright" | "blue" | "blueBright" | "cyan" | "cyanBright" | "gray" | "green" | "greenBright" | "grey" | "magenta" | "magentaBright" | "red" | "redBright" | "white" | "whiteBright" | "yellow" | "yellowBright";
-export type SpinnerStyle = {
-    frames: string[];
-    interval: number;
-};
+import type { WriteStream } from 'node:tty';
+import { type SpinnerStyle } from './icons.ts';
+type ForegroundColors = 'black' | 'blackBright' | 'blue' | 'blueBright' | 'cyan' | 'cyanBright' | 'gray' | 'green' | 'greenBright' | 'grey' | 'magenta' | 'magentaBright' | 'red' | 'redBright' | 'white' | 'whiteBright' | 'yellow' | 'yellowBright';
 /**
  * Spinner options.
  */
-export type Options = {
+interface Options {
     /**
-     * Text to display next to the spinner. (default: `''`)
+     * Text to display next to the spinner.
+     * @default ''
      */
     text?: string | undefined;
     /**
-     * The color of the spinner. (default: `'yellow'`)
+     * The color of the spinner.
+     * @default 'yellow'
      */
     color?: ForegroundColors | undefined;
     /**
-     * The stream to which the spinner is written. (default: `process.stderr`)
+     * The stream to which the spinner is written.
+     * @default process.stderr
      */
-    stream?: NodeJS.WriteStream | undefined;
+    stream?: WriteStream | undefined;
     /**
-     * Whether the spinner should be interactive. (default: Auto-detected)
+     * Whether the spinner should be interactive.
+     * @default Auto-detected
      */
     isInteractive?: boolean | undefined;
     /**
      * Customize the spinner animation with a custom set of frames and interval.
      *
-     * ```
+     * Pass in any spinner from [`cli-spinners`](https://github.com/sindresorhus/cli-spinners).
+     *
+     * @example
      * {
-     * frames: ['-', '\\', '|', '/'],
-     * interval: 100,
+     *    frames: ['-', '\\', '|', '/'],
+     *    interval: 100,
      * }
-     * ```
-     *
-     * Pass in any spinner from [`cli-spinners`](https://github.com/sindresorhus/cli-spinners).
      */
     spinner?: SpinnerStyle | undefined;
-};
-/**
- * @typedef {"black"|"blackBright"|"blue"|"blueBright"|"cyan"|"cyanBright"|"gray"|"green"|"greenBright"|"grey"|"magenta"|"magentaBright"|"red"|"redBright"|"white"|"whiteBright"|"yellow"|"yellowBright"} ForegroundColors
- */
-/**
- * @typedef {object} SpinnerStyle
- * @property {string[]} frames
- * @property {number} interval
- */
-/**
- * @typedef {object} Options Spinner options.
- * @property {string | undefined} [text] Text to display next to the spinner. (default: `''`)
- * @property {ForegroundColors | undefined} [color] The color of the spinner. (default: `'yellow'`)
- * @property {NodeJS.WriteStream | undefined} [stream] The stream to which the spinner is written. (default: `process.stderr`)
- * @property {boolean | undefined} [isInteractive] Whether the spinner should be interactive. (default: Auto-detected)
- * @property {SpinnerStyle | undefined} [spinner]
- * Customize the spinner animation with a custom set of frames and interval.
- *
- * ```
- * {
- *    frames: ['-', '\\', '|', '/'],
- *    interval: 100,
- * }
- * ```
- *
- * Pass in any spinner from [`cli-spinners`](https://github.com/sindresorhus/cli-spinners).
- */
+}
 declare class Spinner {
-    /** @param {Options} options */
+    #private;
     constructor(options?: Options);
     /**
      * Starts the spinner.
      *
      * Optionally, updates the text.
      *
-     * @param {string} [text] The text to display next to the spinner.
+     * @param text The text to display next to the spinner.
      * @returns The spinner instance.
      */
     start(text?: string): this;
@@ -104,35 +60,35 @@ declare class Spinner {
      *
      * Optionally displays a final message.
      *
-     * @param {string} [finalText] The final text to display after stopping the spinner.
+     * @param finalText The final text to display after stopping the spinner.
      * @returns The spinner instance.
      */
     stop(finalText?: string): this;
     /**
      * Stops the spinner and displays a success symbol with the message.
      *
-     * @param {string} [text] The success message to display.
+     * @param text The success message to display.
      * @returns The spinner instance.
      */
     success(text?: string): this;
     /**
      * Stops the spinner and displays an error symbol with the message.
      *
-     * @param {string} [text] The error message to display.
+     * @param text The error message to display.
      * @returns The spinner instance.
      */
     error(text?: string): this;
     /**
      * Stops the spinner and displays a warning symbol with the message.
      *
-     * @param {string} [text] The warning message to display.
+     * @param text The warning message to display.
      * @returns The spinner instance.
      */
     warning(text?: string): this;
     /**
      * Stops the spinner and displays an info symbol with the message.
      *
-     * @param {string} [text] The info message to display.
+     * @param text The info message to display.
      * @returns The spinner instance.
      */
     info(text?: string): this;
@@ -148,26 +104,49 @@ declare class Spinner {
      * @example
      * spinner.text = 'New text';
      */
-    set text(value: string);
+    get text(): string;
     /**
      * Change the text displayed next to the spinner.
      *
      * @example
      * spinner.text = 'New text';
      */
-    get text(): string;
+    set text(value: string);
     /**
      * Change the spinner color.
      */
-    set color(value: ForegroundColors);
+    get color(): ForegroundColors;
     /**
      * Change the spinner color.
      */
-    get color(): ForegroundColors;
+    set color(value: ForegroundColors);
     /**
      * Returns whether the spinner is currently spinning.
      */
     get isSpinning(): boolean;
-    #private;
 }
+/**
+ * Create a new spinner instance.
+ *
+ * @param options The spinner options.
+ * @returns A new spinner instance.
+ *
+ * @example
+ * import createSpinner from 'bananass-utils-console/spinner';
+ *
+ * const spinner = createSpinner({
+ *   text: 'Loading…'
+ *   color: 'yellow',
+ *   stream: process.stderr,
+ *   spinner: {
+ *     frames: ['-', '\\', '|', '/'],
+ *     interval: 100,
+ *   },
+ * }).start();
+ *
+ * setTimeout(() => {
+ *   spinner.success('Success!');
+ * }, 2000);
+ */
+export default function createSpinner(options?: Options): Spinner;
 export {};

package/build/spinner.js

@@ -0,0 +1,277 @@
+/**
+ * @fileoverview Console spinner.
+ * @module bananass-utils-console/spinner
+ * @license MIT Portions of this code were borrowed from [`yocto-spinner`](https://github.com/sindresorhus/yocto-spinner).
+ */
+// --------------------------------------------------------------------------------
+// Import
+// --------------------------------------------------------------------------------
+import { styleText } from 'node:util';
+import { successIcon, errorIcon, warningIcon, infoIcon, defaultSpinner, } from "./icons.js";
+import isInteractive from "./is-interactive.js";
+// --------------------------------------------------------------------------------
+// Class
+// --------------------------------------------------------------------------------
+class Spinner {
+    // ------------------------------------------------------------------------------
+    // Private Properties
+    // ------------------------------------------------------------------------------
+    #frames;
+    #interval;
+    #currentFrame = -1;
+    #timer = undefined;
+    #text;
+    #stream;
+    #color;
+    #lines = 0;
+    #isInteractive;
+    #exitHandlerBound;
+    #lastSpinnerFrameTime = 0;
+    constructor(options = {}) {
+        const spinner = options.spinner ?? defaultSpinner;
+        this.#frames = spinner.frames;
+        this.#interval = spinner.interval;
+        this.#text = options.text ?? '';
+        this.#stream = options.stream ?? process.stderr;
+        this.#color = options.color ?? 'yellow';
+        this.#isInteractive = options.isInteractive ?? isInteractive(this.#stream);
+        this.#exitHandlerBound = this.#exitHandler.bind(this);
+    }
+    // ------------------------------------------------------------------------------
+    // Private Methods
+    // ------------------------------------------------------------------------------
+    #symbolStop(symbol, text = this.#text) {
+        return this.stop(`${symbol} ${text}`);
+    }
+    #render() {
+        const currentTime = Date.now();
+        // Ensure we only update the spinner frame at the wanted interval, even if the render method is called more often.
+        if (this.#currentFrame === -1 ||
+            currentTime - this.#lastSpinnerFrameTime >= this.#interval) {
+            this.#currentFrame = (this.#currentFrame + 1) % this.#frames.length;
+            this.#lastSpinnerFrameTime = currentTime;
+        }
+        const color = this.#color ?? 'yellow';
+        const frame = this.#frames[this.#currentFrame];
+        let string = `${styleText(color, frame)} ${this.#text}`;
+        if (!this.#isInteractive) {
+            string += '\n';
+        }
+        this.clear();
+        this.#write(string);
+        if (this.#isInteractive) {
+            this.#lines = this.#lineCount(string);
+        }
+    }
+    #write(text) {
+        this.#stream.write(text);
+    }
+    #lineCount(text) {
+        const width = this.#stream.columns ?? 80;
+        const lines = text.split('\n');
+        let lineCount = 0;
+        for (const line of lines) {
+            lineCount += Math.max(1, Math.ceil(line.length / width));
+        }
+        return lineCount;
+    }
+    #hideCursor() {
+        if (this.#isInteractive) {
+            this.#write('\u001B[?25l');
+        }
+    }
+    #showCursor() {
+        if (this.#isInteractive) {
+            this.#write('\u001B[?25h');
+        }
+    }
+    #subscribeToProcessEvents() {
+        process.once('SIGINT', this.#exitHandlerBound);
+        process.once('SIGTERM', this.#exitHandlerBound);
+    }
+    #unsubscribeFromProcessEvents() {
+        process.off('SIGINT', this.#exitHandlerBound);
+        process.off('SIGTERM', this.#exitHandlerBound);
+    }
+    #exitHandler(signal) {
+        if (this.isSpinning) {
+            this.stop();
+        }
+        // SIGINT: 128 + 2, SIGTERM: 128 + 15
+        const exitCode = signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 1;
+        process.exit(exitCode);
+    }
+    // ------------------------------------------------------------------------------
+    // Public Methods
+    // ------------------------------------------------------------------------------
+    /**
+     * Starts the spinner.
+     *
+     * Optionally, updates the text.
+     *
+     * @param text The text to display next to the spinner.
+     * @returns The spinner instance.
+     */
+    start(text) {
+        if (text) {
+            this.#text = text;
+        }
+        if (this.isSpinning) {
+            return this;
+        }
+        this.#hideCursor();
+        this.#render();
+        this.#subscribeToProcessEvents();
+        this.#timer = setInterval(() => {
+            this.#render();
+        }, this.#interval);
+        return this;
+    }
+    /**
+     * Stops the spinner.
+     *
+     * Optionally displays a final message.
+     *
+     * @param finalText The final text to display after stopping the spinner.
+     * @returns The spinner instance.
+     */
+    stop(finalText) {
+        if (!this.isSpinning) {
+            return this;
+        }
+        clearInterval(this.#timer);
+        this.#timer = undefined;
+        this.#showCursor();
+        this.clear();
+        this.#unsubscribeFromProcessEvents();
+        if (finalText) {
+            this.#stream.write(`${finalText}\n`);
+        }
+        return this;
+    }
+    /**
+     * Stops the spinner and displays a success symbol with the message.
+     *
+     * @param text The success message to display.
+     * @returns The spinner instance.
+     */
+    success(text) {
+        return this.#symbolStop(successIcon, text);
+    }
+    /**
+     * Stops the spinner and displays an error symbol with the message.
+     *
+     * @param text The error message to display.
+     * @returns The spinner instance.
+     */
+    error(text) {
+        return this.#symbolStop(errorIcon, text);
+    }
+    /**
+     * Stops the spinner and displays a warning symbol with the message.
+     *
+     * @param text The warning message to display.
+     * @returns The spinner instance.
+     */
+    warning(text) {
+        return this.#symbolStop(warningIcon, text);
+    }
+    /**
+     * Stops the spinner and displays an info symbol with the message.
+     *
+     * @param text The info message to display.
+     * @returns The spinner instance.
+     */
+    info(text) {
+        return this.#symbolStop(infoIcon, text);
+    }
+    /**
+     * Clears the spinner.
+     *
+     * @returns The spinner instance.
+     */
+    clear() {
+        if (!this.#isInteractive) {
+            return this;
+        }
+        this.#stream.cursorTo(0);
+        for (let index = 0; index < this.#lines; index++) {
+            if (index > 0) {
+                this.#stream.moveCursor(0, -1);
+            }
+            this.#stream.clearLine(1);
+        }
+        this.#lines = 0;
+        return this;
+    }
+    // ------------------------------------------------------------------------------
+    // Getters and Setters
+    // ------------------------------------------------------------------------------
+    /**
+     * Change the text displayed next to the spinner.
+     *
+     * @example
+     * spinner.text = 'New text';
+     */
+    get text() {
+        return this.#text;
+    }
+    /**
+     * Change the text displayed next to the spinner.
+     *
+     * @example
+     * spinner.text = 'New text';
+     */
+    set text(value) {
+        this.#text = value ?? '';
+        this.#render();
+    }
+    /**
+     * Change the spinner color.
+     */
+    get color() {
+        return this.#color;
+    }
+    /**
+     * Change the spinner color.
+     */
+    set color(value) {
+        this.#color = value;
+        this.#render();
+    }
+    /**
+     * Returns whether the spinner is currently spinning.
+     */
+    get isSpinning() {
+        return this.#timer !== undefined;
+    }
+}
+// --------------------------------------------------------------------------------
+// Export
+// --------------------------------------------------------------------------------
+/**
+ * Create a new spinner instance.
+ *
+ * @param options The spinner options.
+ * @returns A new spinner instance.
+ *
+ * @example
+ * import createSpinner from 'bananass-utils-console/spinner';
+ *
+ * const spinner = createSpinner({
+ *   text: 'Loading…'
+ *   color: 'yellow',
+ *   stream: process.stderr,
+ *   spinner: {
+ *     frames: ['-', '\\', '|', '/'],
+ *     interval: 100,
+ *   },
+ * }).start();
+ *
+ * setTimeout(() => {
+ *   spinner.success('Success!');
+ * }, 2000);
+ */
+export default function createSpinner(options) {
+    return new Spinner(options);
+}