console-toolkit 1.2.8 → 1.2.10

package/src/charts/columns/plain.d.ts

@@ -0,0 +1,32 @@
+import {ChartDatum, ChartDataInput} from '../utils.js';
+import {SgrState} from '../../ansi/sgr-state.js';
+import {StackedColumnChartOptions} from './draw-stacked.js';
+
+/** Options for plain column charts. */
+export interface PlainColumnOptions extends StackedColumnChartOptions {
+  /** Size of each rectangle in characters. */
+  rectSize?: number;
+  /** Initial SGR state. */
+  initState?: SgrState | string | null;
+  /** If true, reverse the drawing direction. */
+  reverse?: boolean;
+}
+
+/** Draws a single stacked column using plain symbols.
+ * @param data - Chart data items.
+ * @param width - Available width.
+ * @param maxValue - Maximum value.
+ * @param options - Options.
+ * @returns Array of strings for the column.
+ */
+export function drawColumn(data: ChartDatum[], width: number, maxValue: number, options?: PlainColumnOptions): string[];
+
+/** Draws a complete plain stacked column chart.
+ * @param values - Chart data.
+ * @param width - Available width.
+ * @param options - Options.
+ * @returns Array of strings representing the chart.
+ */
+export function drawChart(values: ChartDataInput, width: number, options?: PlainColumnOptions): string[];
+
+export default drawChart;

package/src/charts/columns/plain.js

@@ -11,6 +11,13 @@ 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 || {},
@@ -34,6 +41,12 @@ 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.d.ts

@@ -0,0 +1,6 @@
+import {ChartTheme} from '../utils.js';
+
+/** The default chart theme with standard colors. */
+export const chartTheme: ChartTheme;
+
+export default chartTheme;

package/src/charts/themes/default.js

@@ -3,6 +3,7 @@ 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.d.ts

@@ -0,0 +1,6 @@
+import {ChartDatum} from '../utils.js';
+
+/** Rainbow chart theme with reversed spectrum colors. */
+export const chartTheme: ChartDatum[];
+
+export default chartTheme;

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

@@ -1,5 +1,6 @@
-import rainbow from "./rainbow.js";
+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.d.ts

@@ -0,0 +1,6 @@
+import {ChartDatum} from '../utils.js';
+
+/** Rainbow chart theme with spectrum colors. */
+export const chartTheme: ChartDatum[];
+
+export default chartTheme;

package/src/charts/themes/rainbow.js

@@ -3,6 +3,7 @@ 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.d.ts

@@ -0,0 +1,79 @@
+import {SgrState} from '../ansi/sgr-state.js';
+
+/** Converts a foreground color state to a background color state.
+ * @param state - The SGR state with foreground color.
+ * @returns An object with the background property.
+ */
+export function makeBgFromFg(state: SgrState): {background: string | string[] | null};
+/** Converts a background color state to a foreground color state.
+ * @param state - The SGR state with background color.
+ * @returns An object with the foreground property.
+ */
+export function makeFgFromBg(state: SgrState): {foreground: string | string[] | null};
+
+/** Sums the values in a data series.
+ * @param series - Array of data items with optional `value` properties.
+ * @returns The sum of all values.
+ */
+export function sumValues(series: {value?: number}[]): number;
+
+/** A single data point in a chart. */
+export interface ChartDatum {
+  /** The numeric value. */
+  value: number;
+  /** SGR state for the color fill. */
+  colorState?: SgrState;
+  /** Character used for the bar/column fill. */
+  symbol?: string;
+  /** SGR state for the item. */
+  state?: SgrState;
+  /** Text label for the item. */
+  label?: string;
+  /** Additional custom properties. */
+  [key: string]: unknown;
+}
+
+/** Input type for chart data: each series can be a number, a ChartDatum, or an array of either. */
+export type ChartDataInput = (number | ChartDatum | (number | ChartDatum)[])[];
+
+/** Context object passed to custom `drawItem` callbacks. */
+export interface DrawItemInfo {
+  /** Index of the current datum within the series. */
+  index: number;
+  /** The full data series. */
+  data: ChartDatum[];
+  /** Allocated sizes per datum. */
+  sizes: number[];
+  /** Maximum value for scaling. */
+  maxValue: number;
+  /** Available width in characters. */
+  width: number;
+}
+
+/** A chart theme: an array of ChartDatum defaults with an optional `empty` style. */
+export type ChartTheme = ChartDatum[] & {empty?: {symbol?: string; state?: SgrState | null; colorState?: SgrState}};
+
+/** Normalizes chart data, merging with default and custom themes.
+ * @param data - Raw chart data (numbers, ChartDatum objects, or arrays thereof).
+ * @param theme - Default theme to merge with.
+ * @returns Normalized 2D array of ChartDatum.
+ */
+export function normalizeData(
+  data: (number | ChartDatum | (number | ChartDatum)[])[],
+  theme: ChartDatum[]
+): ChartDatum[][];
+
+/** Allocates pixel/character sizes to data values proportionally.
+ * @param data - Array of chart data items.
+ * @param maxValue - Maximum value for scaling.
+ * @param size - Total available size in characters.
+ * @returns Array of allocated sizes.
+ */
+export function allocateSizes(data: ChartDatum[], maxValue: number, size: number): number[];
+
+/** Calculates the integer size needed for a fractional value.
+ * @param value - The fractional value.
+ * @param drawEmptyBorder - If true, add space for an empty border.
+ * @returns The integer size.
+ */
+export function getFracSize(value: number, drawEmptyBorder?: boolean): number;

package/src/charts/utils.js

@@ -1,24 +1,41 @@
 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
     : Array.isArray(state.foreground)
-    ? [Commands.BG_EXTENDED_COLOR, ...state.foreground.slice(1)]
-    : Number(state.foreground) + 10
+      ? [Commands.BG_EXTENDED_COLOR, ...state.foreground.slice(1)]
+      : 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
     : Array.isArray(state.background)
-    ? [Commands.EXTENDED_COLOR, ...state.background.slice(1)]
-    : Number(state.background) - 10
+      ? [Commands.EXTENDED_COLOR, ...state.background.slice(1)]
+      : 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];
@@ -31,6 +48,12 @@ 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);
@@ -65,6 +88,11 @@ 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.d.ts

@@ -0,0 +1,16 @@
+import Box from './box.js';
+
+/** Draws a block with fractional width using 1/8th Unicode block characters.
+ * @param realWidth - Fractional width (e.g., 3.5 for 3.5 columns).
+ * @param height - Height in rows.
+ * @param drawEmptyBorder - If true, add an empty border column when the fractional part is close to 0 but not exactly 0.
+ * @returns A Box containing the drawn block.
+ */
+export function drawRealWidthBlock(realWidth: number, height: number, drawEmptyBorder?: boolean): Box;
+/** Draws a block with fractional height using 1/8th Unicode block characters.
+ * @param width - Width in columns.
+ * @param realHeight - Fractional height (e.g., 3.5 for 3.5 rows).
+ * @param drawEmptyBorder - If true, add an empty border row when the fractional part is close to 0 but not exactly 0.
+ * @returns A Box containing the drawn block.
+ */
+export function drawRealHeightBlock(width: number, realHeight: number, drawEmptyBorder?: boolean): Box;

package/src/draw-block-frac.js

@@ -1,6 +1,13 @@
 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));
@@ -15,6 +22,13 @@ 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.d.ts

@@ -0,0 +1,53 @@
+import Box from './box.js';
+import {LineTheme} from './themes/utils.js';
+
+/** Options for `drawBlock()` and `drawFrame()`. */
+export interface DrawBlockOptions {
+  /** Sub-theme for the top border (defaults to `hTheme`, then `theme`, then `1`). */
+  top?: number;
+  /** Sub-theme for the bottom border (defaults to `hTheme`, then `theme`, then `1`). */
+  bottom?: number;
+  /** Sub-theme for the left border (defaults to `vTheme`, then `theme`, then `1`). */
+  left?: number;
+  /** Sub-theme for the right border (defaults to `vTheme`, then `theme`, then `1`). */
+  right?: number;
+  /** Sub-theme for vertical borders (left and right). Defaults to `theme`, then `1`. */
+  vTheme?: number;
+  /** Sub-theme for horizontal borders (top and bottom). Defaults to `theme`, then `1`. */
+  hTheme?: number;
+  /** Sub-theme for all borders (default: `1`). */
+  theme?: number;
+  /** Fill character for the interior. `drawBlock()` defaults to the theme's `f` property or space; `drawFrame()` defaults to space. */
+  symbol?: string;
+}
+
+/** 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 width - Interior width in columns.
+ * @param height - Interior height in rows.
+ * @param blockTheme - Block theme object defining border characters.
+ * @param options - Drawing options.
+ * @returns A Box containing the drawn block.
+ * @see {@link https://github.com/uhop/console-toolkit/wiki/Module:-draw-block}
+ */
+export function drawBlock(
+  width: number,
+  height: number,
+  blockTheme: LineTheme,
+  options?: DrawBlockOptions
+): Box;
+/** Draws a rectangular frame using a block theme. Same as `drawBlock()` but defaults the interior fill to space if `symbol` is not specified.
+ * @param width - Interior width in columns.
+ * @param height - Interior height in rows.
+ * @param blockTheme - Block theme object defining border characters.
+ * @param options - Drawing options.
+ * @returns A Box containing the drawn frame.
+ */
+export function drawFrame(
+  width: number,
+  height: number,
+  blockTheme: LineTheme,
+  options?: DrawBlockOptions
+): Box;
+
+export default drawBlock;

package/src/draw-block.js

@@ -11,6 +11,23 @@ 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,
@@ -47,9 +64,16 @@ 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);
-}
+};
 
 export default drawBlock;

package/src/meta.d.ts

@@ -0,0 +1,84 @@
+/** Capitalizes the first letter of a string and lowercases the rest.
+ * @param name - The string to capitalize.
+ * @returns The capitalized string.
+ */
+export function capitalize(name: string): string;
+
+/** Converts an array of name parts to camelCase.
+ * @param names - Name parts.
+ * @returns The camelCase string.
+ */
+export function toCamelCase(names: string[]): string;
+/** Splits a camelCase string into an array of name parts.
+ * @param name - The camelCase string.
+ * @returns Array of name parts.
+ */
+export function fromCamelCase(name: string): string[];
+
+/** Converts an array of name parts to PascalCase.
+ * @param names - Name parts.
+ * @returns The PascalCase string.
+ */
+export function toPascalCase(names: string[]): string;
+/** Splits a PascalCase string into an array of name parts.
+ * @param name - The PascalCase string.
+ * @returns Array of name parts.
+ */
+export function fromPascalCase(name: string): string[];
+
+/** Converts an array of name parts to ALL_CAPS_SNAKE_CASE.
+ * @param names - Name parts.
+ * @returns The ALL_CAPS_SNAKE_CASE string.
+ */
+export function toAllCapsSnakeCase(names: string[]): string;
+/** Converts an array of name parts to snake_case.
+ * @param names - Name parts.
+ * @returns The snake_case string.
+ */
+export function toSnakeCase(names: string[]): string;
+/** Splits a snake_case string into an array of name parts.
+ * @param name - The snake_case string.
+ * @returns Array of name parts.
+ */
+export function fromSnakeCase(name: string): string[];
+
+/** Converts an array of name parts to kebab-case.
+ * @param names - Name parts.
+ * @returns The kebab-case string.
+ */
+export function toKebabCase(names: string[]): string;
+/** Splits a kebab-case string into an array of name parts.
+ * @param name - The kebab-case string.
+ * @returns Array of name parts.
+ */
+export function fromKebabCase(name: string): string[];
+
+/** Adds a getter property to a class prototype or object.
+ * @param Class - The class or object to modify.
+ * @param name - Property name.
+ * @param getter - Getter function.
+ * @param force - If true, overwrite existing properties.
+ * @returns The modified class/object.
+ */
+export function addGetter<T>(Class: T, name: string, getter: () => unknown, force?: boolean): T;
+/** Adds multiple getter properties to a class prototype or object.
+ * @param Class - The class or object to modify.
+ * @param getters - Map of property names to getter functions.
+ * @param force - If true, overwrite existing properties.
+ */
+export function addGetters<T>(Class: T, getters: Record<string, () => unknown>, force?: boolean): void;
+
+/** Adds an alias property that mirrors an existing property descriptor.
+ * @param Class - The class or object to modify.
+ * @param name - New property name.
+ * @param oldName - Existing property name to alias.
+ * @param force - If true, overwrite existing properties.
+ * @returns The modified class/object.
+ */
+export function addAlias<T>(Class: T, name: string, oldName: string, force?: boolean): T;
+/** Adds multiple alias properties to a class prototype or object.
+ * @param Class - The class or object to modify.
+ * @param aliases - Map of new names to existing names.
+ * @param force - If true, overwrite existing properties.
+ */
+export function addAliases<T>(Class: T, aliases: Record<string, string>, force?: boolean): void;

package/src/meta.js

@@ -1,31 +1,90 @@
+/** 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;
@@ -34,6 +93,11 @@ 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

@@ -0,0 +1,55 @@
+import {Writable} from 'node:stream';
+import {StringsInput} from '../strings.js';
+
+/** Options for `log()`. */
+export interface LogOptions {
+  /** ANSI command appended at the end of each line. */
+  endOfLineCommand?: string;
+  /** Color depth (1, 4, 8, or 24). If < 4, ANSI codes are stripped. */
+  colorDepth?: number;
+}
+
+/** Options for `out()`. */
+export interface OutOptions {
+  /** Writable stream to output to (default: stdout). */
+  stream?: Writable;
+  /** ANSI command appended at the end of each line. */
+  endOfLineCommand?: string;
+  /** Color depth (1, 4, 8, or 24). If < 4, ANSI codes are stripped. */
+  colorDepth?: number;
+}
+
+/** Logs a text container to the console via `console.log()`. Strips ANSI codes if 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).
+ * @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. */
+export class Out {
+  /** The underlying writable stream. */
+  stream: Writable;
+  /** The detected or configured color depth. */
+  colorDepth: number;
+
+  /**
+   * @param stream - The writable stream to wrap.
+   */
+  constructor(stream: Writable);
+
+  /** Writes a text container to the stream.
+   * @param s - Input: Box, string, string array, or object with `toStrings()`.
+   * @param options - Output options.
+   */
+  out(s: StringsInput, options?: {endOfLineCommand?: string; colorDepth?: number}): void;
+}
+
+/** Logs a string with non-printable characters visualized as hex escape sequences via `console.log()`.
+ * @param string - The string to debug.
+ */
+export function debug(string: string): void;