@orkestrel/console 0.0.12 → 0.0.14

package/dist/src/core/index.js

@@ -1,5 +1,5 @@
+import { isArray, isError, isFunction, isInstance, isObject } from "@orkestrel/contract";
 import { Emitter } from "@orkestrel/emitter";
-import { isArray } from "@orkestrel/contract";
 //#region src/core/constants.ts
 /**
 * Maps each {@link Color} to its SGR foreground parameter — the 8 base colors at 30–37 and their
@@ -102,11 +102,11 @@ var ATTRIBUTES = Object.freeze([
 /** Holds the SGR RESET parameter (0) — terminates a styled run, clearing all colors and attributes. */
 var RESET_CODE = 0;
 /**
-* Holds the ESC control character (`U+001B`) that begins every ANSI escape sequence. Built
+* Holds the escape control character (`U+001B`) that begins every ANSI escape sequence. Built
 * with `String.fromCharCode` so no raw control character appears in source.
 */
 var ESC = String.fromCharCode(27);
-/** Holds the BEL control character (`U+0007`) that can terminate an OSC sequence. */
+/** Holds the bell control character (`U+0007`) that can terminate an OSC sequence. */
 var BEL = String.fromCharCode(7);
 /** Holds the Control Sequence Introducer (`ESC[`) that opens every SGR sequence. */
 var CSI = `[`;
@@ -171,9 +171,12 @@ var LEVEL_COLORS = Object.freeze({
 	error: "red"
 });
 /**
-* Sets the default bounded-retention cap for a {@link import('./types.js').LoggerInterface} — at
-* most this many recent records are kept (oldest dropped first). Retention is always bounded — the
-* oldest record is dropped after the cap is reached; a consumer overrides it through `options.limit`.
+* Sets the default bounded-retention cap for a {@link import('./types.js').LoggerInterface} —
+* `1000`, so at most that many recent records are kept and retention is always bounded.
+*
+* @remarks
+* The oldest record is dropped after the cap is reached; a consumer overrides the cap through
+* `options.limit`.
 */
 var DEFAULT_LOG_LIMIT = 1e3;
 /** Sets the default {@link LogLevel} threshold a logger gates at when none is supplied — `info`. */
@@ -191,9 +194,12 @@ var LOG_LEVELS = Object.freeze([
 ]);
 /**
 * Holds the complete {@link BorderChars} junction set for each {@link BorderStyle} — the standard
-* Unicode box-drawing glyphs at the four line weights. The renderers ({@link
-* import('./helpers.js').renderBox} / {@link import('./helpers.js').renderTable}) look the
-* style up here, so no glyph literal lives in a renderer. Deeply frozen.
+* Unicode box-drawing glyphs at each line weight, deeply frozen.
+*
+* @remarks
+* The renderers ({@link import('./helpers.js').renderBox} /
+* {@link import('./helpers.js').renderTable}) look the style up here, so no glyph literal lives in
+* a renderer.
 *
 * @remarks
 * `round` shares `single`'s edges and tees — only its corners differ (the rounded `╭╮╰╯`).
@@ -290,7 +296,7 @@ var STATUS_LEVELS = Object.freeze([
 * Sets the default visible column width for the width-aware renderers — the separator rule and a
 * {@link import('./helpers.js').renderBox} with no explicit `width`, and the reporter's
 * `section` rule. A sane terminal default (80 columns); a caller overrides it per-call or through
-* {@link import('./types.js').ReporterOptions}`.width`.
+* {@link import('./types.js').ReporterOptions.width}.
 */
 var DEFAULT_WIDTH = 80;
 /** Sets the default horizontal padding inside a box's edges ({@link import('./helpers.js').renderBox}) — one cell. */
@@ -307,9 +313,9 @@ var SEPARATOR_FILL = "─";
 */
 var SEPARATOR_TITLE_GAP = " ";
 /**
-* Sets the number of milliseconds at or above which {@link import('./helpers.js').formatDuration}
-* (and so `Reporter.timing`) switches from a `…ms` rendering to a `…s` (seconds, 2 d.p.)
-* rendering — exactly one second.
+* Sets the millisecond threshold at or above which {@link import('./helpers.js').formatDuration}
+* (and so `Reporter.timing`) switches from a `…ms` rendering to a `…s` (seconds, 2 d.p.) rendering
+* — `1000`, exactly one second.
 */
 var SECOND_MS = 1e3;
 /**
@@ -326,17 +332,20 @@ var CAPTURE_LEVELS = Object.freeze([
 	"debug"
 ]);
 /**
-* Sets the default bounded-buffer cap for a {@link import('./types.js').CaptureInterface} — at most this
-* many recent {@link CapturedMessage}s are retained per buffer (the total buffer and each by-level
-* bucket; oldest dropped first). Capture retention is always bounded so a long-running capture can
-* never grow without bound (the same retention precedent as {@link DEFAULT_LOG_LIMIT}); a consumer
-* overrides it through `options.limit`.
+* Sets the default bounded-buffer cap for a {@link import('./types.js').CaptureInterface} — `1000`,
+* so at most that many recent {@link CapturedMessage}s are retained per buffer (the total buffer
+* and each by-level bucket; oldest dropped first) and retention is always bounded.
+*
+* @remarks
+* A long-running capture can never grow without bound (the same retention precedent as
+* {@link DEFAULT_LOG_LIMIT}); a consumer overrides the cap through `options.limit`.
 */
 var DEFAULT_CAPTURE_LIMIT = 1e3;
 /**
 * Maps each {@link CaptureLevel} to its {@link LogLevel} for the optional sink forward — the projection the
 * Capture routes through when writing an intercepted call to a {@link
-* import('./types.js').SinkInterface} (`sink.write(text, CAPTURE_LEVEL_MAP[level])`). `warn` /
+* import('./types.js').SinkInterface}. `sink.write(text, CAPTURE_LEVEL_MAP[level])` is the call
+* this map backs. `warn` /
 * `error` / `debug` / `info` map to their matching {@link LogLevel}; `log` maps to `info` (a plain
 * console log is informational — the default stream), so a stream-aware sink routes `warn` / `error`
 * captures to the right stream. The source of truth for the capture-to-log projection.
@@ -349,11 +358,14 @@ var CAPTURE_LEVEL_MAP = Object.freeze({
 	debug: "debug"
 });
 /**
-* Holds the default spinner frame cycle a {@link import('./types.js').SpinnerInterface} advances through —
-* the ten braille-pattern glyphs (U+2800 block) that read as a smoothly rotating dot, the universal
-* terminal-spinner convention. Frozen; a consumer swaps the whole cycle through `options.frames`.
+* Holds the default spinner frame cycle a {@link import('./types.js').SpinnerInterface} advances
+* through — the braille-pattern glyphs (`⠋⠙⠹…`, the U+2800 block) that read as a smoothly rotating
+* dot.
 *
 * @remarks
+* The cycle is the universal terminal-spinner convention. Frozen; a consumer swaps the whole
+* cycle through `options.frames`.
+*
 * Braille glyphs are single visible cells, so every frame occupies one column — the spinner glyph
 * never shifts the message beside it as it advances. The source of truth for the default frame axis.
 */
@@ -370,35 +382,43 @@ var SPINNER_FRAMES = Object.freeze([
 	"⠏"
 ]);
 /**
-* Sets the default timer period in milliseconds between a {@link import('./types.js').SpinnerInterface}'s
-* frames — the `setInterval` interval `start()` arms. Eighty milliseconds (≈12.5 frames/second) is
-* the conventional spinner cadence: fast enough to read as motion, slow enough not to thrash a
-* terminal. A consumer overrides it through `options.interval`.
+* Sets the default timer period between a {@link import('./types.js').SpinnerInterface}'s frames —
+* the `setInterval` interval `start()` arms, `80` ms (≈12.5 frames/second).
+*
+* @remarks
+* That is the conventional spinner cadence: fast enough to read as motion, slow enough not to
+* thrash a terminal. A consumer overrides it through `options.interval`.
 */
 var DEFAULT_SPINNER_INTERVAL = 80;
 /**
-* Holds the default filled-cell glyph {@link import('./helpers.js').renderBar} draws the completed run of a
-* progress bar with — the full block `█` (U+2588). A single visible cell; a consumer overrides it
-* through {@link import('./types.js').BarOptions}`.fill`.
+* Holds the default filled-cell glyph {@link import('./helpers.js').renderBar} draws the completed
+* run of a progress bar with — the full block `█` (U+2588). A single visible cell; a consumer
+* overrides it through {@link import('./types.js').BarOptions.fill}.
 */
 var BAR_FILL = "█";
 /**
-* Holds the default empty-cell glyph {@link import('./helpers.js').renderBar} draws the remaining run of a
-* progress bar with — the light-shade block `░` (U+2591). A single visible cell; a consumer overrides
-* it through {@link import('./types.js').BarOptions}`.empty`.
+* Holds the default empty-cell glyph {@link import('./helpers.js').renderBar} draws the remaining
+* run of a progress bar with — the light-shade block `░` (U+2591). A single visible cell; a
+* consumer overrides it through {@link import('./types.js').BarOptions.empty}.
 */
 var BAR_EMPTY = "░";
 /**
-* Sets the default visible cell count of a progress-bar track — the glyph run {@link
-* import('./helpers.js').renderBar} fills (and a {@link import('./types.js').ProgressInterface} sizes
-* its bar to). Thirty cells is a compact, terminal-friendly default; a consumer overrides it through
-* `options.width`. Distinct from {@link DEFAULT_WIDTH} (the renderers' 80-column line width) — a bar
-* track is one inline element, not a full-width rule.
+* Sets the default visible cell count of a progress-bar track — the glyph run
+* {@link import('./helpers.js').renderBar} fills, and the width a
+* {@link import('./types.js').ProgressInterface} sizes its bar to. `30` cells.
+*
+* @remarks
+* Thirty cells is a compact, terminal-friendly default; a consumer overrides it through
+* `options.width`. It is distinct from {@link DEFAULT_WIDTH} (the renderers' 80-column line
+* width) — a bar track is one inline element, not a full-width rule.
 */
 var DEFAULT_BAR_WIDTH = 30;
 /**
-* Holds the default {@link Theme} — every role bound to its default {@link Style}, deeply frozen.
-* The base {@link import('./factories.js').createTheme} merges over, and the theme every
+* Holds the default {@link Theme} — every role bound to its default {@link Style}, assembled from
+* {@link LEVEL_COLORS}, {@link STATUS_ICONS}, and {@link STATUS_COLORS} and deeply frozen.
+*
+* @remarks
+* It is the base {@link import('./factories.js').createTheme} merges over, and the theme every
 * entity uses when none is supplied.
 *
 * @remarks
@@ -467,12 +487,12 @@ var DEFAULT_THEME = Object.freeze({
 //#endregion
 //#region src/core/errors.ts
 /**
-* Represents an error thrown by the console layer.
+* Carries a {@link ConsoleErrorCode} and an optional `context` bag — the error the console layer
+* throws for an internal invariant violated at a defensive guard.
 *
 * @remarks
-* Carries a {@link ConsoleErrorCode} and an optional `context` bag. Thrown for: an
-* internal invariant violated at a defensive, structurally-unreachable guard
-* (`INVARIANT`).
+* `INVARIANT` is the code for a guard that is structurally unreachable, so a `catch` branches on
+* `error.code` rather than parsing the message.
 */
 var ConsoleError = class extends Error {
 	code;
@@ -485,7 +505,7 @@ var ConsoleError = class extends Error {
 	}
 };
 /**
-* Narrows an unknown caught value to a {@link ConsoleError}.
+* Narrows an unknown caught value to a {@link ConsoleError} — the guard a `catch` branches on.
 *
 * @param value - The value to test (typically a `catch` binding)
 * @returns True if `value` is a {@link ConsoleError}; false otherwise
@@ -500,7 +520,7 @@ var ConsoleError = class extends Error {
 * ```
 */
 function isConsoleError(value) {
-	return value instanceof ConsoleError;
+	return isInstance(value, ConsoleError);
 }
 //#endregion
 //#region src/core/helpers.ts
@@ -526,7 +546,8 @@ function strip(text) {
 }
 /**
 * Removes every non-printing C0 control character from `text` except `\t` / `\n` / `\r`
-* (meaningful whitespace), plus DEL — returning the sanitized string.
+* (meaningful whitespace), plus DEL — a separate pass from {@link strip}, so `width` stays
+* untouched.
 *
 * @remarks
 * Deliberately separate from {@link strip} (ANSI-escape removal only, so `width` /
@@ -569,7 +590,8 @@ function width(text) {
 	return [...strip(text)].length;
 }
 /**
-* Snapshots and deeply freezes one {@link Style} value.
+* Snapshots and deeply freezes one {@link Style} value, including an independent frozen copy of
+* its `attributes`.
 *
 * @param style - The caller-owned style to snapshot
 * @returns A frozen style record with an independently frozen attributes list
@@ -740,9 +762,9 @@ function formatDuration(ms) {
 	return ms < 1e3 ? `${ms}ms` : `${(ms / SECOND_MS).toFixed(2)}s`;
 }
 /**
-* Colors `text` through `styler`, or returns it verbatim when `styler` is `undefined` — the
-* single optional-styling primitive every renderer applies to its border / title / connector
-* glyphs (the one styler seam, shared, never re-hand-rolled per renderer).
+* Colors `text` through `styler` and an optional by-value {@link Style}, or returns it verbatim
+* when `styler` is `undefined` — the single optional-styling primitive every renderer applies to
+* its border / title / connector glyphs.
 *
 * @remarks
 * The renderers all take an optional `styler`: present ⇒ glyphs are colored, absent ⇒ plain.
@@ -927,8 +949,8 @@ function renderTable(options) {
 	].join("\n");
 }
 /**
-* Renders a nested {@link TreeNode} tree with box-drawing connectors. Pure: same
-* {@link TreeOptions} → same string.
+* Renders a nested {@link TreeNode} tree whose connectors derive from the chosen `border` set.
+* Pure: same {@link TreeOptions} → same string.
 *
 * @remarks
 * The `root` label is the unindented first line; its descendants are drawn beneath it with
@@ -957,10 +979,14 @@ function renderTree(options) {
 	})].join("\n");
 }
 /**
-* Renders the connector-prefixed lines for a {@link TreeNode} list — the recursive core
-* behind {@link renderTree}. Each child is drawn as `prefix` + its connector (`├─ ` for
-* any but the last, `└─ ` for the last) + its label, with its own descendants recursed
-* beneath under the carried guide (`│  ` under a non-last node, `   ` under the last).
+* Renders the connector-prefixed lines for a {@link TreeNode} list — the recursive core behind
+* {@link renderTree}, whose third options argument requires `border` and groups the optional
+* `styler` and `style`.
+*
+* @remarks
+* Each child is drawn as `prefix` + its connector (`├─ ` for any but the last, `└─ ` for the
+* last) + its label, with its own descendants recursed beneath under the carried guide (`│  `
+* under a non-last node, `   ` under the last).
 *
 * @remarks
 * A centralized, exported recursion branch so it is directly testable and
@@ -1023,12 +1049,12 @@ function renderTreeChildren(nodes, prefix, options) {
 * ```
 */
 function stringifyValue(value) {
-	if (value instanceof Error) return `${value.name}: ${value.message}`;
-	if (value === null || typeof value !== "object") return String(value);
+	if (isError(value)) return `${value.name}: ${value.message}`;
+	if (!isObject(value)) return String(value);
 	const seen = /* @__PURE__ */ new WeakSet();
 	try {
 		return JSON.stringify(value, (_key, nested) => {
-			if (nested !== null && typeof nested === "object") {
+			if (isObject(nested)) {
 				if (seen.has(nested)) return "[Circular]";
 				seen.add(nested);
 			}
@@ -1062,12 +1088,15 @@ function formatArgs(args) {
 }
 /**
 * Renders a determinate progress bar string — a filled / empty glyph track followed by the percentage
-* and the `(current/total)` count (`█████░░░░░ 50% (5/10)`). Pure: same {@link BarOptions} →
-* same string. The animation-layer sibling of the `render*` renderers (box / table / tree /
-* separator), shared so a {@link import('./types.js').ProgressInterface} and any direct caller draw
-* the one bar — never a second, hand-rolled one.
+* and the `(current/total)` count (`█████░░░░░ 50% (5/10)`). Pure and width-aware: same
+* {@link BarOptions} → same string.
 *
 * @remarks
+* It is the animation-layer sibling of the `render*` renderers (box / table / tree / separator),
+* shared so a {@link import('./types.js').ProgressInterface} and any direct caller draw the one
+* bar — never a second,
+* hand-rolled one.
+*
 * - **Fill fraction, clamped.** The filled cell count is `round((current / total) · width)` with
 *   `current` clamped to `[0, total]`, so an overrun never over-fills and a negative never under-fills.
 *   A `total <= 0` renders a full track (there is nothing to fill toward — the work is trivially done).
@@ -1102,12 +1131,13 @@ function renderBar(options) {
 //#region src/core/renderers/ANSIRenderer.ts
 /**
 * Implements the cross-environment default {@link RendererInterface} — renders style data as ANSI
-* SGR escape codes, exactly as `Scheduler` is the `setTimeout` default for its seam. It
-* is the single styling output the whole console / terminal system uses in a terminal;
-* the browser `%c` / CSS renderer implements the same contract over
-* the same {@link Style}, so retargeting changes the renderer, never the style model.
+* SGR escape codes, stateless and event-free.
 *
 * @remarks
+* It is the single styling output the whole console / terminal system uses in a terminal; the
+* browser `%c` / CSS renderer implements the same contract over the same {@link Style}, so
+* retargeting changes the renderer, never the style model.
+*
 * - **Style is data in, SGR string out.** It reads the style's `foreground` /
 *   `background` / `attributes` and emits one `ESC[…m` sequence whose parameters are the
 *   mapped SGR numbers (foreground 30–37 / 90–97, background 40–47 / 100–107, attributes
@@ -1143,7 +1173,8 @@ var ANSIRenderer = class {
 //#endregion
 //#region src/core/Retention.ts
 /**
-* Implements the bounded, level-keyed retention engine both captures buffer through — one capped total buffer
+* Implements the bounded, level-keyed retention engine the console and process captures buffer
+* through — one capped total buffer
 * plus one capped bucket per level, generic over the record type each capture carries.
 *
 * @remarks
@@ -1431,7 +1462,7 @@ var Styler = class Styler {
 		return this.#attribute(attribute).surface;
 	}
 	#isSurface(value) {
-		return typeof value === "function" && "style" in value && "enabled" in value && "render" in value && "red" in value && "bold" in value;
+		return isFunction(value) && "style" in value && "enabled" in value && "render" in value && "red" in value && "bold" in value;
 	}
 	#foreground(color) {
 		return new Styler(this.#renderer, this.#enabled, Object.freeze({
@@ -1450,10 +1481,13 @@ var Styler = class Styler {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Creates the fluent, composable {@link StylerInterface} — the consumer-facing styling
-* API. It builds a {@link import('./types.js').Style} under the hood and renders it
-* through a {@link import('./types.js').RendererInterface} (the ANSI default), so
-* `styler.red.bold('hi')` yields styled text. Chains are immutable, so a base styler is freely reusable.
+* Creates the fluent, composable {@link StylerInterface} — ANSI by default, retargeted by a
+* `renderer` and stripped of color by `enabled: false`.
+*
+* @remarks
+* It builds a {@link import('./types.js').Style} under the hood and renders it through a
+* {@link import('./types.js').RendererInterface}, so `styler.red.bold('hi')` yields styled text.
+* Chains are immutable, so a base styler is freely reusable.
 *
 * @param options - See {@link StylerOptions}
 * @returns A base {@link StylerInterface}
@@ -1900,12 +1934,14 @@ var Reporter = class {
 /**
 * Implements a self-driving, observable activity spinner — a glyph cycle that advances on a
 * periodic timer, writing each `\r` + frame line to its {@link SinkInterface} and emitting it on
-* `frame`. The leading `\r` is what an overwrite-capable sink (the TTY sink) redraws on; a plain
-* sink degrades to a fresh, non-overwriting line — the line-overwrite is the sink's job, never
-* the spinner's. Universal — `setInterval` + the one {@link StylerInterface} + the one
-* {@link SinkInterface}, no `node:*`, no `process.stdout`.
+* `frame`. The timer is always cleared on an outcome, so the spinner is leak-free.
 *
 * @remarks
+* The leading `\r` is what an overwrite-capable sink (the TTY sink) redraws on; a plain sink
+* degrades to a fresh, non-overwriting line — the line-overwrite is the sink's job, never the
+* spinner's. Universal — `setInterval` + the one {@link StylerInterface} + the one
+* {@link SinkInterface}, no `node:*`, no `process.stdout`.
+*
 * - **Self-driving but deterministically testable.** `start()` arms a `setInterval` that calls
 *   {@link tick} each `interval`; each {@link tick} builds the styled `glyph + message` line for the
 *   current frame, emits it on `frame`, writes `'\r' + line` to the sink, then advances the frame
@@ -2016,13 +2052,16 @@ var Spinner = class {
 //#region src/core/Progress.ts
 /**
 * Implements an update-driven, observable progress bar — {@link update} recomputes the bar through
-* {@link renderBar}, writes `\r` + bar to its {@link SinkInterface}, and emits the `{ current, total }`
-* on `update`. The leading `\r` is what an overwrite-capable sink (the TTY sink) redraws on; a
-* plain sink degrades to a fresh, non-overwriting line — the line-overwrite is the sink's job.
-* Universal — the one {@link StylerInterface} + the one {@link SinkInterface}, no `node:*`, no
-* `process.stdout`. No self-timer (unlike {@link import('./Spinner.js').Spinner}) — the caller drives it.
+* {@link renderBar}, writes `\r` + bar to its {@link SinkInterface}, and emits the `{ current,
+* total }` on `update`. No self-timer, unlike {@link import('./Spinner.js').Spinner} — the caller
+* drives it.
 *
 * @remarks
+* The leading `\r` is what an overwrite-capable sink (the TTY sink) redraws on; a plain sink
+* degrades to a fresh, non-overwriting line — the line-overwrite is the sink's job. Universal —
+* the one {@link StylerInterface} + the one {@link SinkInterface}, no `node:*`, no
+* `process.stdout`.
+*
 * - **Update-driven.** Each {@link update} clamps `current` to `[0, total]`, renders the bar (filled
 *   to `current / total`, with the trailing `percent (current/total)` + message) through {@link renderBar},
 *   emits `update`, and writes `'\r' + bar`. Progress advances only when the caller reports it.