console-toolkit 1.2.8 → 1.2.10

package/src/output/show.js

@@ -2,6 +2,12 @@ import process from 'node:process';
 import {matchCsiNoGroups} from '../strings.js';
 import Box from '../box.js';
 
+/** Logs a text container to the console via `console.log()`. Strips ANSI codes if colorDepth < 4.
+ * @param {import('../strings.js').StringsInput} s - Input convertible to a Box.
+ * @param {object} [options] - Options.
+ * @param {string} [options.endOfLineCommand='\x1B[m'] - ANSI command appended to each line.
+ * @param {number} [options.colorDepth=24] - Color depth (1 = no color, 4/8/24 = color).
+ */
 export const log = (s, {endOfLineCommand = '\x1B[m', colorDepth = 24} = {}) => {
   s = Box.make(s);
   if (colorDepth < 4) {
@@ -12,6 +18,13 @@ export const log = (s, {endOfLineCommand = '\x1B[m', colorDepth = 24} = {}) => {
   s.box.forEach(row => console.log(row + endOfLineCommand));
 };
 
+/** Writes a text container to a stream. Strips ANSI codes if colorDepth < 4.
+ * @param {import('../strings.js').StringsInput} s - Input convertible to a Box.
+ * @param {object} [options] - Options.
+ * @param {import('node:stream').Writable} [options.stream=process.stdout] - The output stream.
+ * @param {string} [options.endOfLineCommand='\x1B[m'] - ANSI command appended to each line.
+ * @param {number} [options.colorDepth] - Color depth. Auto-detected from stream if not specified.
+ */
 export const out = (s, {stream = process.stdout, endOfLineCommand = '\x1B[m', colorDepth} = {}) => {
   s = Box.make(s);
   if (typeof colorDepth != 'number' || isNaN(colorDepth)) colorDepth = stream.isTTY ? stream.getColorDepth() : 1;
@@ -23,17 +36,32 @@ export const out = (s, {stream = process.stdout, endOfLineCommand = '\x1B[m', co
   s.box.forEach(row => stream.write(row + endOfLineCommand + '\n'));
 };
 
+/** Convenience wrapper around a writable stream for formatted output.
+ * Auto-detects color depth from the stream.
+ */
 export class Out {
+  /**
+   * @param {import('node:stream').Writable} stream - The writable stream to wrap.
+   */
   constructor(stream) {
     this.stream = stream;
     this.colorDepth = stream.isTTY ? stream.getColorDepth() : 1;
   }
+  /** Writes a text container to the stream.
+   * @param {import('../strings.js').StringsInput} s - Input convertible to a Box.
+   * @param {object} [options] - Options.
+   * @param {string} [options.endOfLineCommand='\x1B[m'] - ANSI command appended to each line.
+   * @param {number} [options.colorDepth] - Color depth override.
+   */
   out(s, {endOfLineCommand = '\x1B[m', colorDepth} = {}) {
     if (typeof colorDepth != 'number' || isNaN(colorDepth)) colorDepth = this.colorDepth;
     return out(s, {stream: this.stream, endOfLineCommand, colorDepth});
   }
 }
 
+/** Logs a string with control characters visualized as hex escape sequences.
+ * @param {string} string - The string to debug.
+ */
 export const debug = string =>
   console.log(
     string.replace(/[\x00-\x1F]/g, m => '\\x' + m[0].charCodeAt(0).toString(16).padStart(2, '0').toUpperCase())

package/src/output/updater.d.ts

@@ -0,0 +1,114 @@
+import Writer from './writer.js';
+import {StringsInput} from '../strings.js';
+
+/** Options for `Updater` constructor. */
+export interface UpdaterOptions {
+  /** String written before the first frame. */
+  prologue?: string;
+  /** String written after the final frame. */
+  epilogue?: string;
+  /** String written before each frame. */
+  beforeFrame?: string;
+  /** String written after each frame. */
+  afterFrame?: string;
+  /** String prepended before each line. */
+  beforeLine?: string;
+  /** String appended after each line. */
+  afterLine?: string;
+  /** If true, omit the trailing newline on the last line. */
+  noLastNewLine?: boolean;
+}
+
+/** An object that can provide frames for the Updater. */
+export interface UpdaterTarget {
+  /** Current state string. */
+  state?: string;
+  /** Returns the current frame content.
+   * @returns Frame content (Box, string, or string array).
+   */
+  getFrame(...args: unknown[]): StringsInput;
+}
+
+/** Manages auto-refreshing console output for spinners, progress bars, etc. */
+export class Updater {
+  /** The updater function or target object. */
+  updater: ((state: string, ...args: unknown[]) => StringsInput) | UpdaterTarget;
+  /** The Writer instance used for output. */
+  writer: Writer;
+  /** String written before the first frame. */
+  prologue: string;
+  /** String written after the final frame. */
+  epilogue: string;
+  /** String written before each frame. */
+  beforeFrame: string;
+  /** String written after each frame. */
+  afterFrame: string;
+  /** String prepended before each line. */
+  beforeLine: string;
+  /** String appended after each line. */
+  afterLine: string;
+  /** If true, omit the trailing newline on the last line. */
+  noLastNewLine: boolean | undefined;
+  /** Height of the last written frame in rows. */
+  lastHeight: number;
+  /** Whether the updater has been finalized. */
+  isDone: boolean;
+  /** Whether this is the first frame. */
+  first: boolean;
+  /** Handle for the auto-refresh interval, or null. */
+  intervalHandle: ReturnType<typeof setInterval> | null;
+
+  /**
+   * @param updater - A function or UpdaterTarget that provides frames.
+   * @param options - Updater options.
+   * @param writer - Writer instance (default: new Writer).
+   */
+  constructor(
+    updater: ((state: string, ...args: unknown[]) => StringsInput) | UpdaterTarget,
+    options?: UpdaterOptions,
+    writer?: Writer
+  );
+
+  /** Whether auto-refreshing is active. */
+  readonly isRefreshing: boolean;
+
+  /** Starts auto-refreshing at the given interval.
+   * @param ms - Refresh interval in milliseconds (default: 100).
+   * @returns This Updater.
+   */
+  startRefreshing(ms?: number): this;
+  /** Stops auto-refreshing.
+   * @returns This Updater.
+   */
+  stopRefreshing(): this;
+  /** Resets the updater state.
+   * @returns This Updater.
+   */
+  reset(): this;
+
+  /** Gets the current frame from the updater.
+   * @param state - State string.
+   * @returns Frame content.
+   */
+  getFrame(state: string, ...args: unknown[]): StringsInput;
+  /** Writes a frame to the stream.
+   * @param state - State string.
+   * @returns A promise that resolves when the frame is written.
+   */
+  writeFrame(state: string, ...args: unknown[]): Promise<void>;
+  /** Finishes updating: writes the epilogue and stops refreshing.
+   * @returns A promise that resolves when done.
+   */
+  done(): Promise<void>;
+  /** Updates with a new state and writes the frame.
+   * @param state - State string.
+   * @returns A promise that resolves when the update is written.
+   */
+  update(state?: string, ...args: unknown[]): Promise<void>;
+  /** Writes the final frame with state 'finished' and calls `done()`.
+   * @returns A promise that resolves when done.
+   */
+  final(...args: unknown[]): Promise<void>;
+}
+
+export default Updater;

package/src/output/updater.js

@@ -1,13 +1,30 @@
-'use strict';
-
 import Writer from './writer.js';
 import {toStrings} from '../strings.js';
 import {cursorUp, setCommands} from '../ansi/csi.js';
 
 const RESET = setCommands([]);
 
+/** Manages continuously updating console output (spinners, progress bars, etc.).
+ * Handles refreshing frames, prologue/epilogue sequences, and interacts with a Writer instance.
+ */
 export class Updater {
-  constructor(updater, {prologue, epilogue, beforeFrame, afterFrame, beforeLine, afterLine, noLastNewLine} = {}, writer = new Writer()) {
+  /**
+   * @param {((state: string, ...args: unknown[]) => import('../strings.js').StringsInput)|{state?: string, getFrame: (...args: unknown[]) => import('../strings.js').StringsInput}} updater - A function `(state, ...args) => frame` or an object with `getFrame()`.
+   * @param {object} [options] - Options.
+   * @param {string} [options.prologue] - String written before the first frame.
+   * @param {string} [options.epilogue] - String written after the last frame.
+   * @param {string} [options.beforeFrame] - String written before each frame.
+   * @param {string} [options.afterFrame] - String written after each frame.
+   * @param {string} [options.beforeLine] - String prepended to each line.
+   * @param {string} [options.afterLine] - String appended to each line.
+   * @param {boolean} [options.noLastNewLine] - If true, omit the trailing newline of each frame.
+   * @param {import('./writer.js').default} [writer=new Writer()] - The Writer instance to use.
+   */
+  constructor(
+    updater,
+    {prologue, epilogue, beforeFrame, afterFrame, beforeLine, afterLine, noLastNewLine} = {},
+    writer = new Writer()
+  ) {
     this.updater = updater;
     this.writer = writer;
     this.prologue = prologue || RESET;
@@ -23,16 +40,24 @@ export class Updater {
     this.intervalHandle = null;
   }
 
+  /** Whether the updater is currently auto-refreshing. */
   get isRefreshing() {
     return this.intervalHandle !== null;
   }
 
+  /** Starts auto-refreshing at the given interval.
+   * @param {number} [ms=100] - Refresh interval in milliseconds.
+   * @returns {this}
+   */
   startRefreshing(ms = 100) {
     if (this.intervalHandle || this.isDone || !this.writer.isTTY) return this;
     this.intervalHandle = setInterval(this.update.bind(this), ms);
     return this;
   }
 
+  /** Stops auto-refreshing.
+   * @returns {this}
+   */
   stopRefreshing() {
     if (!this.intervalHandle) return this;
     clearInterval(this.intervalHandle);
@@ -40,6 +65,9 @@ export class Updater {
     return this;
   }
 
+  /** Resets the updater state, stopping any refresh and clearing the done flag.
+   * @returns {this}
+   */
   reset() {
     this.stopRefreshing();
     this.isDone = false;
@@ -47,6 +75,11 @@ export class Updater {
     return this;
   }
 
+  /** Gets a frame from the updater function or object.
+   * @param {string} state - The current state ('active', 'paused', 'finished', etc.).
+   * @param {...unknown} args - Additional arguments.
+   * @returns {import('../strings.js').StringsInput} The frame content.
+   */
   getFrame(state, ...args) {
     if (typeof this.updater == 'function') return this.updater(state, ...args);
     if (typeof this.updater?.getFrame == 'function') {
@@ -56,6 +89,11 @@ export class Updater {
     throw new TypeError('Updater must be a function or implement getFrame()');
   }
 
+  /** Writes a single frame to the output, handling cursor repositioning.
+   * @param {string} state - The current state.
+   * @param {...unknown} args - Additional arguments passed to `getFrame()`.
+   * @returns {Promise<void>}
+   */
   async writeFrame(state, ...args) {
     if (this.first) {
       this.prologue && (await this.writer.writeString(this.prologue));
@@ -70,10 +108,17 @@ export class Updater {
     this.lastHeight = frame.length;
     if (this.noLastNewLine) --this.lastHeight;
 
-    await this.writer.write(frame, {noLastNewLine: this.noLastNewLine, beforeLine: this.beforeLine, afterLine: this.afterLine});
+    await this.writer.write(frame, {
+      noLastNewLine: this.noLastNewLine,
+      beforeLine: this.beforeLine,
+      afterLine: this.afterLine
+    });
     this.afterFrame && (await this.writer.writeString(this.afterFrame));
   }
 
+  /** Marks the updater as done, stops refreshing, and writes the epilogue.
+   * @returns {Promise<void>}
+   */
   async done() {
     if (this.isDone) return;
     this.isDone = true;
@@ -81,11 +126,20 @@ export class Updater {
     this.epilogue && (await this.writer.writeString(this.epilogue));
   }
 
+  /** Updates the display with a new frame.
+   * @param {string} [state='active'] - The current state.
+   * @param {...unknown} args - Additional arguments passed to `getFrame()`.
+   * @returns {Promise<void>}
+   */
   async update(state = 'active', ...args) {
     if (this.isDone || !this.writer.isTTY) return;
     await this.writeFrame(state, ...args);
   }
 
+  /** Writes the final frame with state 'finished' and calls `done()`.
+   * @param {...unknown} args - Additional arguments passed to `getFrame()`.
+   * @returns {Promise<void>}
+   */
   async final(...args) {
     if (this.isDone) return;
     await this.writeFrame('finished', ...args);

package/src/output/writer.d.ts

@@ -0,0 +1,87 @@
+import {Writable} from 'node:stream';
+import {StringsInput} from '../strings.js';
+
+/** Options for `Writer.write()`. */
+export interface WriteOptions {
+  /** If true or 'save', keep cursor in the same column after writing. */
+  sameColumn?: boolean | 'save';
+  /** If true, omit the trailing newline on the last line. */
+  noLastNewLine?: boolean;
+  /** String prepended before each line. */
+  beforeLine?: string;
+  /** String appended after each line. */
+  afterLine?: string;
+}
+
+/** Manages writing to a stream with cursor manipulation and color depth awareness. */
+export class Writer {
+  /** The underlying writable stream. */
+  stream: Writable;
+  /** Forced color depth override, or undefined to auto-detect. */
+  forceColorDepth: number | undefined;
+
+  /**
+   * @param stream - Writable stream (default: stdout).
+   * @param forceColorDepth - Override color depth.
+   */
+  constructor(stream?: Writable, forceColorDepth?: number);
+
+  /** Whether the stream is a TTY. */
+  readonly isTTY: boolean;
+  /** Terminal width in columns. */
+  readonly columns: number;
+  /** Terminal height in rows. */
+  readonly rows: number;
+  /** Terminal dimensions. */
+  readonly size: {columns: number; rows: number};
+
+  /** Returns the color depth of the stream.
+   * @param env - Environment variables to check (default: `process.env`).
+   * @returns Color depth (1, 4, 8, or 24).
+   */
+  getColorDepth(env?: object): number;
+  /** Checks if the stream supports the given number of colors.
+   * @param count - Number of colors to check for.
+   * @param env - Environment variables to check.
+   * @returns True if supported.
+   */
+  hasColors(count?: number, env?: object): boolean;
+  hasColors(env?: object): boolean;
+
+  /** Clears the current line.
+   * @param dir - Direction: -1 left, 0 entire, 1 right.
+   * @returns Promise resolving when done.
+   */
+  clearLine(dir: number): Promise<boolean>;
+  /** Clears from cursor to end of screen.
+   * @returns Promise resolving when done.
+   */
+  clearScreenDown(): Promise<boolean>;
+
+  /** Moves cursor to absolute position.
+   * @param x - Column.
+   * @param y - Row (optional).
+   * @returns Promise resolving when done.
+   */
+  cursorTo(x: number, y?: number): Promise<boolean>;
+  /** Moves cursor relative to current position.
+   * @param dx - Columns.
+   * @param dy - Rows.
+   * @returns Promise resolving when done.
+   */
+  moveCursor(dx: number, dy: number): Promise<boolean>;
+
+  /** Writes a raw string to the stream.
+   * @param s - The string to write.
+   * @returns Promise resolving when done.
+   */
+  writeString(s: string): Promise<void>;
+  /** Writes a Box/string to the stream with optional cursor control.
+   * @param s - Input: Box, string, or string array.
+   * @param options - Write options.
+   * @returns Promise resolving when done.
+   */
+  write(s: StringsInput, options?: WriteOptions): Promise<void>;
+}
+
+export default Writer;

package/src/output/writer.js

@@ -1,5 +1,3 @@
-'use strict';
-
 import process from 'node:process';
 
 import {CURSOR_DOWN1, CURSOR_RESTORE_POS, CURSOR_SAVE_POS} from '../ansi/csi.js';
@@ -8,33 +6,57 @@ import {getLength, matchCsiNoGroups, matchCsiNoSgrNoGroups, toStrings} from '../
 const write = async (stream, chunk, encoding = 'utf8') =>
   new Promise((resolve, reject) => stream.write(chunk, encoding, error => (error ? reject(error) : resolve())));
 
+/** Abstracts writing to a stream (defaulting to `process.stdout`).
+ * Handles TTY capabilities, color depth, cursor manipulation, and ANSI stripping for non-TTY streams.
+ */
 export class Writer {
+  /**
+   * @param {import('node:stream').Writable} [stream=process.stdout] - The output stream.
+   * @param {number} [forceColorDepth] - Force a specific color depth instead of auto-detecting.
+   */
   constructor(stream = process.stdout, forceColorDepth) {
     this.stream = stream;
     this.forceColorDepth = forceColorDepth;
   }
 
+  /** Whether the stream is a TTY. */
   get isTTY() {
     return this.stream.isTTY;
   }
+  /** The number of columns in the terminal. */
   get columns() {
     return this.stream.columns;
   }
+  /** The number of rows in the terminal. */
   get rows() {
     return this.stream.rows;
   }
+  /** The terminal size as `{columns, rows}`. */
   get size() {
     const [columns, rows] = this.stream.getWindowSize?.() || [];
     return {columns, rows};
   }
+  /** Returns the color depth of the stream.
+   * @param {object} [env] - Environment variables to check (default: `process.env`).
+   * @returns {number} The color depth (1, 4, 8, or 24).
+   */
   getColorDepth(...args) {
     return this.forceColorDepth || this.stream.getColorDepth?.(...args);
   }
 
+  /** Checks if the stream supports the given number of colors.
+   * @param {number} [count] - Number of colors to check for.
+   * @param {object} [env] - Environment variables to check.
+   * @returns {boolean} True if supported.
+   */
   hasColors(...args) {
     return this.forceColorDepth ? args[0] <= Math.pow(2, this.forceColorDepth) : this.stream.hasColors?.(...args);
   }
 
+  /** Clears the current line.
+   * @param {number} dir - Direction: -1 = left, 0 = entire line, 1 = right.
+   * @returns {Promise<boolean>} True if the operation was supported.
+   */
   clearLine(dir) {
     return new Promise((resolve, reject) => {
       if (typeof this.stream.clearLine == 'function') {
@@ -44,6 +66,9 @@ export class Writer {
       }
     });
   }
+  /** Clears the screen from the cursor down.
+   * @returns {Promise<boolean>} True if the operation was supported.
+   */
   clearScreenDown() {
     return new Promise((resolve, reject) => {
       if (typeof this.stream.clearScreenDown == 'function') {
@@ -54,6 +79,11 @@ export class Writer {
     });
   }
 
+  /** Moves the cursor to an absolute position.
+   * @param {number} x - Column.
+   * @param {number} [y] - Row.
+   * @returns {Promise<boolean>} True if the operation was supported.
+   */
   cursorTo(x, y) {
     return new Promise((resolve, reject) => {
       if (typeof this.stream.cursorTo == 'function') {
@@ -63,6 +93,11 @@ export class Writer {
       }
     });
   }
+  /** Moves the cursor relative to its current position.
+   * @param {number} dx - Columns to move.
+   * @param {number} dy - Rows to move.
+   * @returns {Promise<boolean>} True if the operation was supported.
+   */
   moveCursor(dx, dy) {
     return new Promise((resolve, reject) => {
       if (typeof this.stream.moveCursor == 'function') {
@@ -73,6 +108,10 @@ export class Writer {
     });
   }
 
+  /** Writes a raw string to the stream, stripping ANSI codes for non-TTY streams.
+   * @param {string} s - The string to write.
+   * @returns {Promise<void>}
+   */
   async writeString(s) {
     s = String(s);
 
@@ -93,12 +132,23 @@ export class Writer {
     await write(this.stream, s.replace(matchCsiNoGroups, ''));
   }
 
+  /** Writes a text container to the stream.
+   * @param {import('../strings.js').StringsInput} s - Input convertible to strings.
+   * @param {object} [options] - Options.
+   * @param {boolean|'save'} [options.sameColumn] - If true or 'save', keep cursor in the same column between lines.
+   * @param {boolean} [options.noLastNewLine] - If true, omit the trailing newline.
+   * @param {string} [options.beforeLine=''] - String prepended to each line.
+   * @param {string} [options.afterLine=''] - String appended to each line.
+   * @returns {Promise<void>}
+   */
   async write(s, {sameColumn, noLastNewLine, beforeLine = '', afterLine = ''} = {}) {
     s = toStrings(s);
 
     if (!this.isTTY) {
       const matcher = this.forceColorDepth ? matchCsiNoSgrNoGroups : matchCsiNoGroups;
-      let lines = Array.from(s).map(line => beforeLine + line + afterLine).join('\n');
+      let lines = Array.from(s)
+        .map(line => beforeLine + line + afterLine)
+        .join('\n');
       if (!noLastNewLine) lines += '\n';
       matcher.lastIndex = 0;
       lines = lines.replace(matcher, '');
@@ -108,7 +158,7 @@ export class Writer {
 
     if (sameColumn === 'save') {
       for (const line of s) {
-        await write(this.stream, CURSOR_SAVE_POS + beforeLine + line + afterline + CURSOR_RESTORE_POS + CURSOR_DOWN1);
+        await write(this.stream, CURSOR_SAVE_POS + beforeLine + line + afterLine + CURSOR_RESTORE_POS + CURSOR_DOWN1);
       }
       return;
     }
@@ -123,7 +173,9 @@ export class Writer {
       return;
     }
 
-    let lines = Array.from(s).map(line => beforeLine + line + afterLine).join('\n');
+    let lines = Array.from(s)
+      .map(line => beforeLine + line + afterLine)
+      .join('\n');
     if (!noLastNewLine) lines += '\n';
     await write(this.stream, lines);
   }