console-toolkit 1.2.15 → 1.3.0

package/src/charts/columns/plain.js

@@ -11,13 +11,6 @@ import defaultTheme from '../themes/default.js';
 
 const defaultSymbol = hBlocks8th[7];
 
-/** Draws a single stacked column using plain symbols.
- * @param {object[]} data - Normalized data series.
- * @param {number} width - Total height.
- * @param {number} maxValue - Maximum value for scaling.
- * @param {object} [options] - Options including `reverse`, `rectSize`, `initState`, `theme`.
- * @returns {string[]} The drawn column lines.
- */
 export const drawColumn = (data, width, maxValue, options = {}) => {
   const {reverse, rectSize = 1, initState = {}, theme = defaultTheme} = options,
     {symbol = ' ', state = null, colorState} = theme?.empty || {},
@@ -41,12 +34,6 @@ export const drawColumn = (data, width, maxValue, options = {}) => {
   return result.map(line => optimize(line));
 };
 
-/** Draws a complete plain stacked column chart.
- * @param {any[]} values - Chart data.
- * @param {number} width - Available height.
- * @param {object} [options] - Options.
- * @returns {string[]} Array of strings representing the chart.
- */
 export const drawChart = drawStackedChart(drawColumn);
 
 export default drawChart;

package/src/charts/themes/default.js

@@ -3,7 +3,6 @@ import style from '../../style.js';
 
 const seriesColors = 'cyan,magenta,blue,yellow,green,red'.split(',');
 
-/** The default chart theme with standard colors. */
 export const chartTheme = [
   ...seriesColors.map(name => ({colorState: style['bright' + capitalize(name)].getState()})),
   ...seriesColors.map(name => ({colorState: style[name].getState()}))

package/src/charts/themes/rainbow-reversed.js

@@ -1,6 +1,5 @@
 import rainbow from './rainbow.js';
 
-/** Rainbow chart theme with reversed spectrum colors. */
 export const chartTheme = rainbow.slice().reverse();
 
 export default chartTheme;

package/src/charts/themes/rainbow.js

@@ -3,7 +3,6 @@ import style from '../../style.js';
 // red, orange, yellow, green, blue, indigo, violet
 const colors = [0xff0000, 0xffa500, 0xffff00, 0x008000, 0x0000ff, 0x4b0082, 0xee82ee];
 
-/** Rainbow chart theme with spectrum colors. */
 export const chartTheme = colors.map(color => ({colorState: style.hex(color).getState()}));
 
 export default chartTheme;

package/src/charts/utils.js

@@ -1,10 +1,6 @@
 import {Commands} from '../ansi/sgr.js';
 import defaultTheme from './themes/default.js';
 
-/** Converts a foreground color state to a background color state.
- * @param {object} state - SGR state with a `foreground` property.
- * @returns {object} State with a `background` property.
- */
 export const makeBgFromFg = state => ({
   background: !state.foreground
     ? null
@@ -13,10 +9,6 @@ export const makeBgFromFg = state => ({
       : Number(state.foreground) + 10
 });
 
-/** Converts a background color state to a foreground color state.
- * @param {object} state - SGR state with a `background` property.
- * @returns {object} State with a `foreground` property.
- */
 export const makeFgFromBg = state => ({
   foreground: !state.background
     ? null
@@ -25,17 +17,8 @@ export const makeFgFromBg = state => ({
       : Number(state.background) - 10
 });
 
-/** Sums the values in a data series.
- * @param {{value?: number}[]} series
- * @returns {number}
- */
 export const sumValues = series => series.reduce((acc, datum) => acc + (datum?.value || 0), 0);
 
-/** Normalizes chart data, merging with default and custom themes.
- * @param {(number|object|Array)[]} data - Raw chart data.
- * @param {object[]} theme - Theme array for series styling.
- * @returns {object[][]} Normalized data.
- */
 export const normalizeData = (data, theme) =>
   data.map(series => {
     if (!Array.isArray(series)) series = [series];
@@ -48,12 +31,6 @@ export const normalizeData = (data, theme) =>
     });
   });
 
-/** Allocates pixel/character sizes to data values proportionally.
- * @param {{value?: number}[]} data - Data series.
- * @param {number} maxValue - Maximum value (-1 for auto).
- * @param {number} size - Total available size.
- * @returns {number[]} Allocated sizes per datum plus one extra for remainder.
- */
 export const allocateSizes = (data, maxValue, size) => {
   const values = data.map((datum, index) => ({value: datum?.value || 0, index})),
     seriesValue = values.reduce((acc, datum) => acc + datum.value, 0);
@@ -61,6 +38,8 @@ export const allocateSizes = (data, maxValue, size) => {
   if (maxValue < 0) {
     maxValue = seriesValue;
     if (!maxValue) maxValue = 1;
+  } else if (!maxValue) {
+    maxValue = 1;
   }
   if (seriesValue < maxValue) {
     values.push({value: maxValue - seriesValue, index: -1}); // add an empty bin
@@ -88,11 +67,6 @@ export const allocateSizes = (data, maxValue, size) => {
   return sizes;
 };
 
-/** Calculates the integer size needed for a fractional value.
- * @param {number} value - The fractional value.
- * @param {boolean} [drawEmptyBorder] - Whether to draw a border for empty fractional parts.
- * @returns {number} The integer size.
- */
 export const getFracSize = (value, drawEmptyBorder) => {
   const intValue = Math.floor(value),
     hasFrac = value - intValue > 0,

package/src/draw-block-frac.js

@@ -1,13 +1,6 @@
 import {fullBlock, hBlocks8th, vBlocks8th} from './symbols.js';
 import Box from './box.js';
 
-/** Draws a block with a fractional width using 1/8th Unicode block characters.
- * The integer part is filled with full blocks; the fractional part appears on the right.
- * @param {number} realWidth - The real width (float). Fractional part is interpreted in 1/8th steps.
- * @param {number} height - The integer height of the block.
- * @param {boolean} [drawEmptyBorder=false] - If true, add an empty border column when the fractional part is close to 0 but not exactly 0.
- * @returns {import('./box.js').Box} A Box containing the drawn block.
- */
 export const drawRealWidthBlock = (realWidth, height, drawEmptyBorder) => {
   realWidth = Math.max(0, realWidth);
   height = Math.max(0, Math.floor(height));
@@ -22,13 +15,6 @@ export const drawRealWidthBlock = (realWidth, height, drawEmptyBorder) => {
   return new Box(new Array(height).fill(line), true);
 };
 
-/** Draws a block with a fractional height using 1/8th Unicode block characters.
- * The integer part is filled with full blocks; the fractional part appears on the top.
- * @param {number} width - The integer width of the block.
- * @param {number} realHeight - The real height (float). Fractional part is interpreted in 1/8th steps.
- * @param {boolean} [drawEmptyBorder=false] - If true, add an empty border row when the fractional part is close to 0 but not exactly 0.
- * @returns {import('./box.js').Box} A Box containing the drawn block.
- */
 export const drawRealHeightBlock = (width, realHeight, drawEmptyBorder) => {
   width = Math.max(0, Math.floor(width));
   realHeight = Math.max(0, realHeight);

package/src/draw-block.js

@@ -11,23 +11,6 @@ const T = 1,
   LB = getIndex(L, B),
   RB = getIndex(R, B);
 
-/** Draws a filled rectangular block using a block theme.
- * The interior is filled with a symbol from the theme's `f` property, or space by default.
- * @param {number} width - Interior width in columns.
- * @param {number} height - Interior height in rows.
- * @param {object} blockTheme - Block theme object defining border characters.
- * @param {object} [options] - Drawing options.
- * @param {number} [options.top] - Sub-theme for the top border (defaults to `hTheme`, then `theme`, then `1`).
- * @param {number} [options.bottom] - Sub-theme for the bottom border (defaults to `hTheme`, then `theme`, then `1`).
- * @param {number} [options.left] - Sub-theme for the left border (defaults to `vTheme`, then `theme`, then `1`).
- * @param {number} [options.right] - Sub-theme for the right border (defaults to `vTheme`, then `theme`, then `1`).
- * @param {number} [options.vTheme] - Sub-theme for vertical borders (left and right). Defaults to `theme`, then `1`.
- * @param {number} [options.hTheme] - Sub-theme for horizontal borders (top and bottom). Defaults to `theme`, then `1`.
- * @param {number} [options.theme] - Sub-theme for all borders (default: `1`).
- * @param {string} [options.symbol] - Fill character for the interior. Defaults to the theme's `f` property or space.
- * @returns {import('./box.js').Box} A Box containing the drawn block.
- * @see {@link https://github.com/uhop/console-toolkit/wiki/Module:-draw-block}
- */
 export const drawBlock = (
   width,
   height,
@@ -64,13 +47,6 @@ export const drawBlock = (
   );
 };
 
-/** Draws a rectangular frame using a block theme. Same as `drawBlock()` but defaults the interior fill to space if `symbol` is not specified.
- * @param {number} width - Interior width in columns.
- * @param {number} height - Interior height in rows.
- * @param {object} blockTheme - Block theme object defining border characters.
- * @param {object} [options] - Drawing options (same as `drawBlock()`).
- * @returns {import('./box.js').Box} A Box containing the drawn frame.
- */
 export const drawFrame = (width, height, blockTheme, options) => {
   if (!options?.symbol) options = {...options, symbol: ' '};
   return drawBlock(width, height, blockTheme, options);

package/src/meta.js

@@ -1,90 +1,31 @@
-/** Capitalizes the first letter of a string and lowercases the rest.
- * @param {string} name - The string to capitalize.
- * @returns {string} The capitalized string.
- */
 export const capitalize = name => (name ? name[0].toUpperCase() + name.substring(1).toLowerCase() : name);
 
-/** Converts an array of name parts to camelCase.
- * @param {string[]} names - The name parts.
- * @returns {string} The camelCase string.
- */
 export const toCamelCase = names =>
   names.map((name, index) => (index ? capitalize(name) : name.toLowerCase())).join('');
-/** Splits a camelCase string into an array of name parts.
- * @param {string} name - The camelCase string.
- * @returns {string[]} The name parts.
- */
 export const fromCamelCase = name => name.split(/(?=[A-Z])/g);
 
-/** Converts an array of name parts to PascalCase.
- * @param {string[]} names - The name parts.
- * @returns {string} The PascalCase string.
- */
 export const toPascalCase = names => names.map(name => capitalize(name)).join('');
-/** Splits a PascalCase string into an array of name parts.
- * @param {string} name - The PascalCase string.
- * @returns {string[]} The name parts.
- */
 export const fromPascalCase = name => name.split(/(?=[A-Z])/g);
 
-/** Converts an array of name parts to ALL_CAPS_SNAKE_CASE.
- * @param {string[]} names - The name parts.
- * @returns {string} The ALL_CAPS_SNAKE_CASE string.
- */
 export const toAllCapsSnakeCase = names => names.map(name => name.toUpperCase()).join('_');
-/** Converts an array of name parts to snake_case.
- * @param {string[]} names - The name parts.
- * @returns {string} The snake_case string.
- */
 export const toSnakeCase = names => names.map(name => name.toLowerCase()).join('_');
-/** Splits a snake_case string into an array of name parts.
- * @param {string} name - The snake_case string.
- * @returns {string[]} The name parts.
- */
 export const fromSnakeCase = name => name.split('_');
 
-/** Converts an array of name parts to kebab-case.
- * @param {string[]} names - The name parts.
- * @returns {string} The kebab-case string.
- */
 export const toKebabCase = names => names.map(name => name.toLowerCase()).join('-');
-/** Splits a kebab-case string into an array of name parts.
- * @param {string} name - The kebab-case string.
- * @returns {string[]} The name parts.
- */
 export const fromKebabCase = name => name.split('-');
 
-/** Adds a getter property to a class prototype or object.
- * @param {Function|object} Class - The class or object to add the getter to.
- * @param {string} name - The property name.
- * @param {Function} getter - The getter function.
- * @param {boolean} [force] - If true, overwrite existing properties.
- * @returns {object} The modified prototype or object.
- */
 export const addGetter = (Class, name, getter, force) => {
   const object = Class.prototype || Class;
   if (!force && object.hasOwnProperty(name)) return object;
   return Object.defineProperty(object, name, {configurable: true, enumerable: true, get: getter});
 };
 
-/** Adds multiple getter properties to a class prototype or object.
- * @param {Function|object} Class - The class or object to add getters to.
- * @param {Record<string, Function>} getters - An object mapping property names to getter functions.
- * @param {boolean} [force] - If true, overwrite existing properties.
- */
 export const addGetters = (Class, getters, force) => {
   for (const [name, value] of Object.entries(getters)) {
     addGetter(Class, name, value, force);
   }
 };
 
-/** Adds an alias property that mirrors an existing property descriptor.
- * @param {Function|object} Class - The class or object to add the alias to.
- * @param {string} name - The new alias name.
- * @param {string} oldName - The existing property name to alias.
- * @param {boolean} [force] - If true, overwrite existing properties.
- * @returns {object} The modified prototype or object.
- */
 export const addAlias = (Class, name, oldName, force) => {
   const object = Class.prototype || Class;
   if (!force && object.hasOwnProperty(name)) return object;
@@ -93,11 +34,6 @@ export const addAlias = (Class, name, oldName, force) => {
   return Object.defineProperty(object, name, descriptor);
 };
 
-/** Adds multiple alias properties to a class prototype or object.
- * @param {Function|object} Class - The class or object to add aliases to.
- * @param {Record<string, string>} aliases - An object mapping new names to existing property names.
- * @param {boolean} [force] - If true, overwrite existing properties.
- */
 export const addAliases = (Class, aliases, force) => {
   for (const [name, oldName] of Object.entries(aliases)) {
     addAlias(Class, name, oldName, force);

package/src/output/show.d.ts

@@ -19,18 +19,23 @@ export interface OutOptions {
   colorDepth?: number;
 }
 
-/** Logs a text container to the console via `console.log()`. Strips ANSI codes if colorDepth < 4.
+/** Logs a text container via `console.log()`. Defaults to passing ANSI through (colorDepth = 24).
+ * Use this when you know your terminal supports the colors you're emitting.
+ * Strips ANSI when colorDepth < 4.
  * @param s - Input: Box, string, string array, or object with `toStrings()`.
  * @param options - Log options.
  */
 export function log(s: StringsInput, options?: LogOptions): void;
-/** Writes a text container to a stream (default: stdout).
+/** Writes a text container to any writable stream (default: stdout).
+ * Auto-detects colorDepth from `stream.isTTY` and `stream.getColorDepth()` when omitted.
+ * Strips ANSI when colorDepth < 4.
  * @param s - Input: Box, string, string array, or object with `toStrings()`.
  * @param options - Output options.
  */
 export function out(s: StringsInput, options?: OutOptions): void;
 
-/** Wraps a writable stream for outputting styled text. */
+/** Wraps a writable stream for outputting styled text. Caches `colorDepth` once at construction
+ * to avoid per-call detection — useful for tight write loops to the same stream. */
 export class Out {
   /** The underlying writable stream. */
   stream: Writable;

package/src/output/show.js

@@ -2,66 +2,35 @@ 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} = {}) => {
+const writeRows = (s, endOfLineCommand, colorDepth, write) => {
   s = Box.make(s);
   if (colorDepth < 4) {
     matchCsiNoGroups.lastIndex = 0;
-    s.box.forEach(row => console.log((row + endOfLineCommand).replace(matchCsiNoGroups, '')));
+    s.box.forEach(row => write((row + endOfLineCommand).replace(matchCsiNoGroups, '')));
     return;
   }
-  s.box.forEach(row => console.log(row + endOfLineCommand));
+  s.box.forEach(row => write(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 log = (s, {endOfLineCommand = '\x1B[m', colorDepth = 24} = {}) =>
+  writeRows(s, endOfLineCommand, colorDepth, row => console.log(row));
+
 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;
-  if (colorDepth < 4) {
-    matchCsiNoGroups.lastIndex = 0;
-    s.box.forEach(row => stream.write((row + endOfLineCommand).replace(matchCsiNoGroups, '') + '\n'));
-    return;
-  }
-  s.box.forEach(row => stream.write(row + endOfLineCommand + '\n'));
+  writeRows(s, endOfLineCommand, colorDepth, row => stream.write(row + '\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

@@ -19,14 +19,19 @@ export interface UpdaterOptions {
   noLastNewLine?: boolean;
 }
 
-/** An object that can provide frames for the Updater. */
+/** An object that can provide frames for the Updater. Prefer implementing `nextFrame()`
+ * (advance + return) for spinners and progress bars; `getFrame()` is the read-only fallback. */
 export interface UpdaterTarget {
   /** Current state string. */
   state?: string;
-  /** Returns the current frame content.
+  /** Returns the next frame content (advance + return). Preferred entry point for spinners.
    * @returns Frame content (Box, string, or string array).
    */
-  getFrame(...args: unknown[]): StringsInput;
+  nextFrame?(...args: unknown[]): StringsInput;
+  /** Returns the current frame content. Used as fallback when `nextFrame()` is not implemented.
+   * @returns Frame content (Box, string, or string array).
+   */
+  getFrame?(...args: unknown[]): StringsInput;
 }
 
 /** Manages auto-refreshing console output for spinners, progress bars, etc. */

package/src/output/updater.js

@@ -4,22 +4,7 @@ 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 {
-  /**
-   * @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} = {},
@@ -40,24 +25,16 @@ 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);
@@ -65,9 +42,6 @@ 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;
@@ -75,25 +49,16 @@ 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') {
+    if (this.updater) {
       this.updater.state = state;
-      return this.updater.getFrame(...args);
+      if (typeof this.updater.nextFrame == 'function') return this.updater.nextFrame(...args);
+      if (typeof this.updater.getFrame == 'function') return this.updater.getFrame(...args);
     }
-    throw new TypeError('Updater must be a function or implement getFrame()');
+    throw new TypeError('Updater must be a function or implement nextFrame()/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));
@@ -116,9 +81,6 @@ export class Updater {
     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;
@@ -126,20 +88,11 @@ 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.js

@@ -6,59 +6,35 @@ 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) {
     if (!this.forceColorDepth) return this.stream.hasColors?.(...args);
     const count = typeof args[0] == 'number' ? args[0] : 2;
     return count <= Math.pow(2, this.forceColorDepth);
   }
 
-  /** 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') {
@@ -68,9 +44,6 @@ 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') {
@@ -81,11 +54,6 @@ 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') {
@@ -95,11 +63,6 @@ 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') {
@@ -110,10 +73,6 @@ 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);
 
@@ -134,15 +93,6 @@ 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);
 
@@ -175,9 +125,7 @@ export class Writer {
       return;
     }
 
-    let lines = Array.from(s)
-      .map(line => beforeLine + line + afterLine)
-      .join('\n');
+    let lines = s.map(line => beforeLine + line + afterLine).join('\n');
     if (!noLastNewLine) lines += '\n';
     await write(this.stream, lines);
   }