@socketsecurity/lib 6.0.5 → 6.0.7

package/dist/logger/node.d.ts

@@ -1,23 +1,14 @@
 /**
- * @file Node-side `Logger` class — owns the per-instance state (parent, bound
- *   stream, indent buffers, theme), the symbol-prefixed semantic methods
- *   (`success`, `fail`, `info`, ...), and the chainable wrappers around the
- *   underlying `node:console` methods. The shared-default singleton lives in
- *   `./default`; this file exports only the class. Consumers should import
- *   `Logger` from `./logger` (auto-routed by the package.json `browser`
- *   condition); `./node` is the explicit Node entry, useful for tests pinning
- *   to one implementation. Console construction is deliberately lazy: the
- *   constructor only stashes its args in `_internal.privateConstructorArgs`;
- *   the actual `node:console` instance is built on first call to
- *   `#getConsole()`. This lets the logger be imported during early Node.js
- *   bootstrap before stdout is ready, avoiding `ERR_CONSOLE_WRITABLE_STREAM`.
- *   Free helpers live in sibling leaves (per `socket-lib`'s
- *   export-top-level-functions rule):
- *
- *   - color helpers — `./colors` (`applyColor`, `getYoctocolors`)
- *   - log symbols + symbol getters — `./symbols`
- *   - lazy console init + prototype mirror — `./console-init`
- *   - shared private state — `./_internal`
+ * @file Node-side `Logger` class — owns per-instance state (parent, bound
+ *   stream, indent buffers, theme) and exposes the public surface as thin
+ *   delegators over sibling free-function leaves. Console construction is lazy:
+ *   the constructor stashes its args in `_internal.privateConstructorArgs` and
+ *   the `node:console` instance is built on first `#getConsole()`, so the
+ *   logger can be imported during early Node.js bootstrap before stdout is
+ *   ready (avoiding `ERR_CONSOLE_WRITABLE_STREAM`). Method bodies live in the
+ *   leaves: `./console-methods`, `./semantic-methods`, `./indentation-methods`,
+ *   `./stream-methods`, `./console`, `./options`, `./symbols`,
+ *   `./symbols-builder`, `./_internal`.
  */
 import { incLogCallCountSymbol, lastWasBlankSymbol } from './symbols';
 import type { Task } from './types';
@@ -32,369 +23,56 @@ export declare class Logger {
      */
     static LOG_SYMBOLS: Record<string, string>;
     /**
-     * Creates a new Logger instance.
-     *
-     * When called without arguments, creates a logger using the default
-     * `process.stdout` and `process.stderr` streams. Can accept custom console
-     * constructor arguments for advanced use cases.
+     * Creates a new Logger. With no args it uses the default `process.stdout` /
+     * `process.stderr`; an options object customizes stream / theme. See
+     * {@link parseLoggerOptions}.
      *
      * @param args - Optional console constructor arguments.
      */
     constructor(...args: unknown[]);
-    /**
-     * Gets a logger instance bound exclusively to stderr.
-     *
-     * All logging operations on this instance will write to stderr only.
-     * Indentation is tracked separately from stdout. The instance is cached and
-     * reused on subsequent accesses.
-     *
-     * @returns A logger instance bound to stderr
-     */
     get stderr(): Logger;
-    /**
-     * Gets a logger instance bound exclusively to stdout.
-     *
-     * All logging operations on this instance will write to stdout only.
-     * Indentation is tracked separately from stderr. The instance is cached and
-     * reused on subsequent accesses.
-     *
-     * @returns A logger instance bound to stdout
-     */
     get stdout(): Logger;
-    /**
-     * Gets the total number of log calls made on this logger instance.
-     *
-     * Tracks all logging method calls including `log()`, `error()`, `warn()`,
-     * `success()`, `fail()`, etc. Useful for testing and monitoring logging
-     * activity.
-     *
-     * @returns The number of times logging methods have been called
-     */
     get logCallCount(): number;
-    /**
-     * Increments the internal log call counter.
-     *
-     * This is called automatically by logging methods and should not be called
-     * directly in normal usage.
-     */
     [incLogCallCountSymbol](): this;
-    /**
-     * Sets whether the last logged line was blank.
-     *
-     * Used internally to track blank lines and prevent duplicate spacing. This is
-     * called automatically by logging methods.
-     *
-     * @param value - Whether the last line was blank.
-     * @param stream - Optional stream to update (defaults to both streams if not
-     *   bound, or target stream if bound)
-     */
     [lastWasBlankSymbol](value: unknown, stream?: 'stderr' | 'stdout'): this;
-    /**
-     * Logs an assertion failure message if the value is falsy.
-     *
-     * Works like `console.assert()` but returns the logger for chaining. If the
-     * value is truthy, nothing is logged. If falsy, logs an error message with an
-     * assertion failure.
-     *
-     * @param value - The value to test.
-     * @param message - Optional message and additional arguments to log.
-     */
     assert(value: unknown, ...message: unknown[]): this;
-    /**
-     * Clears the current line in the terminal.
-     *
-     * Moves the cursor to the beginning of the line and clears all content. Works
-     * in both TTY and non-TTY environments. Useful for clearing progress
-     * indicators created with `progress()`.
-     *
-     * The stream to clear (stderr or stdout) depends on whether the logger is
-     * stream-bound.
-     */
     clearLine(): this;
-    /**
-     * Clears the visible terminal screen.
-     *
-     * Only available on the main logger instance, not on stream-bound instances
-     * (`.stderr` or `.stdout`). Resets the log call count and blank line tracking
-     * if the output is a TTY.
-     *
-     * @throws {Error} If called on a stream-bound logger instance
-     */
     clearVisible(): this;
-    /**
-     * Increments and logs a counter for the given label.
-     *
-     * Each unique label maintains its own counter. Works like `console.count()`.
-     *
-     * @default 'default'
-     *
-     * @param label - Optional label for the counter.
-     */
     count(label?: string | undefined): this;
     /**
-     * Creates a task that logs start and completion messages automatically.
-     *
-     * Returns a task object with a `run()` method that executes the provided
-     * function and logs "Starting task: {name}" before execution and "Completed
-     * task: {name}" after completion.
+     * Creates a task whose `run()` logs "Starting task: {name}" before running
+     * the provided function and "Completed task: {name}" after.
      *
      * @param name - The name of the task.
      *
-     * @returns A task object with a `run()` method
+     * @returns A task object with a `run()` method.
      */
     createTask(name: string): Task;
-    /**
-     * Decreases the indentation level by removing spaces from the prefix.
-     *
-     * When called on the main logger, affects both stderr and stdout indentation.
-     * When called on a stream-bound logger (`.stderr` or `.stdout`), affects only
-     * that stream's indentation.
-     *
-     * @default 2
-     */
     dedent(spaces?: number): this;
-    /**
-     * Displays an object's properties in a formatted way.
-     *
-     * Works like `console.dir()` with customizable options for depth, colors,
-     * etc. Useful for inspecting complex objects.
-     *
-     * @param obj - The object to display.
-     * @param options - Optional formatting options (Node.js inspect options)
-     */
     dir(obj: unknown, options?: unknown | undefined): this;
-    /**
-     * Displays data as XML/HTML in a formatted way.
-     *
-     * Works like `console.dirxml()`. In Node.js, behaves the same as `dir()`.
-     *
-     * @param data - The data to display.
-     */
     dirxml(...data: unknown[]): this;
-    /**
-     * Logs a completion message with a success symbol (alias for `success()`).
-     *
-     * Provides semantic clarity when marking something as "done". Does NOT
-     * automatically clear the current line - call `clearLine()` first if needed
-     * after using `progress()`.
-     */
     done(...args: unknown[]): this;
-    /**
-     * Logs an error message to stderr.
-     *
-     * Automatically applies current indentation. All arguments are formatted and
-     * logged like `console.error()`.
-     */
     error(...args: unknown[]): this;
-    /**
-     * Logs a newline to stderr only if the last line wasn't already blank.
-     *
-     * Prevents multiple consecutive blank lines. Useful for adding spacing
-     * between sections without creating excessive whitespace.
-     */
     errorNewline(): this;
-    /**
-     * Logs a failure message with a red colored fail symbol.
-     *
-     * Automatically prefixes the message with `LOG_SYMBOLS.fail` (red ✖). Always
-     * outputs to stderr. If the message starts with an existing symbol, it will
-     * be stripped and replaced.
-     */
     fail(...args: unknown[]): this;
-    /**
-     * Starts a new indented log group.
-     *
-     * If a label is provided, it's logged before increasing indentation. Groups
-     * can be nested. Each group increases indentation by the `kGroupIndentWidth`
-     * (default 2 spaces). Call `groupEnd()` to close.
-     *
-     * @param label - Optional label to display before the group.
-     */
     group(...label: unknown[]): this;
-    /**
-     * Starts a new collapsed log group (alias for `group()`).
-     *
-     * In browser consoles, this creates a collapsed group. In Node.js, it behaves
-     * identically to `group()`.
-     *
-     * @param label - Optional label to display before the group.
-     */
     groupCollapsed(...label: unknown[]): this;
-    /**
-     * Ends the current log group and decreases indentation.
-     *
-     * Must be called once for each `group()` or `groupCollapsed()` call to
-     * properly close the group and restore indentation.
-     */
     groupEnd(): this;
-    /**
-     * Increases the indentation level by adding spaces to the prefix.
-     *
-     * When called on the main logger, affects both stderr and stdout indentation.
-     * When called on a stream-bound logger (`.stderr` or `.stdout`), affects only
-     * that stream's indentation. Maximum indentation is 1000 spaces.
-     *
-     * @default 2
-     */
     indent(spaces?: number): this;
-    /**
-     * Logs an informational message with a blue colored info symbol.
-     *
-     * Automatically prefixes the message with `LOG_SYMBOLS.info` (blue ℹ). Always
-     * outputs to stderr. If the message starts with an existing symbol, it will
-     * be stripped and replaced.
-     */
     info(...args: unknown[]): this;
-    /**
-     * Logs a message to stdout.
-     *
-     * Automatically applies current indentation. All arguments are formatted and
-     * logged like `console.log()`. This is the primary method for standard
-     * output.
-     */
     log(...args: unknown[]): this;
-    /**
-     * Logs a newline to stdout only if the last line wasn't already blank.
-     *
-     * Prevents multiple consecutive blank lines. Useful for adding spacing
-     * between sections without creating excessive whitespace.
-     */
     logNewline(): this;
-    /**
-     * Shows a progress indicator that can be cleared with `clearLine()`.
-     *
-     * Displays a simple status message with a '∴' prefix. Does not include
-     * animation or spinner. Intended to be cleared once the operation completes.
-     * The output stream (stderr or stdout) depends on whether the logger is
-     * stream-bound.
-     *
-     * Always clears the current line before writing so calling `progress(...)`
-     * twice in a row redraws cleanly, and any partially-flushed prior output on
-     * the same row gets overwritten. TTY path uses `cursorTo(0) + clearLine(0)`;
-     * non-TTY path falls back to `\r\x1b[K` (which still works in CI logs).
-     *
-     * @param text - The progress message to display.
-     */
     progress(text: string): this;
-    /**
-     * Resets all indentation to zero.
-     *
-     * When called on the main logger, resets both stderr and stdout indentation.
-     * When called on a stream-bound logger (`.stderr` or `.stdout`), resets only
-     * that stream's indentation.
-     */
     resetIndent(): this;
-    /**
-     * Logs a skip message with a cyan colored skip symbol.
-     *
-     * Automatically prefixes the message with `LOG_SYMBOLS.skip` (cyan ↻). Always
-     * outputs to stderr. If the message starts with an existing symbol, it will
-     * be stripped and replaced.
-     */
     skip(...args: unknown[]): this;
-    /**
-     * Logs a main step message with a cyan arrow symbol and blank line before it.
-     *
-     * Automatically prefixes the message with `LOG_SYMBOLS.step` (cyan →) and
-     * adds a blank line before the message unless the last line was already
-     * blank. Useful for marking major steps in a process with clear visual
-     * separation. Always outputs to stdout. If the message starts with an
-     * existing symbol, it will be stripped and replaced.
-     *
-     * @param msg - The step message to log.
-     * @param extras - Additional arguments to log.
-     */
     step(msg: string, ...extras: unknown[]): this;
-    /**
-     * Logs an indented substep message (stateless).
-     *
-     * Adds a 2-space indent to the message without affecting the logger's
-     * indentation state. Useful for showing sub-items under a main step.
-     *
-     * @param msg - The substep message to log.
-     * @param extras - Additional arguments to log.
-     */
     substep(msg: string, ...extras: unknown[]): this;
-    /**
-     * Logs a success message with a green colored success symbol.
-     *
-     * Automatically prefixes the message with `LOG_SYMBOLS.success` (green ✔).
-     * Always outputs to stderr. If the message starts with an existing symbol, it
-     * will be stripped and replaced.
-     */
     success(...args: unknown[]): this;
-    /**
-     * Displays data in a table format.
-     *
-     * Works like `console.table()`. Accepts arrays of objects or objects with
-     * nested objects. Optionally specify which properties to include in the
-     * table.
-     *
-     * @param tabularData - The data to display as a table.
-     * @param properties - Optional array of property names to include.
-     */
     table(tabularData: unknown, properties?: readonly string[] | undefined): this;
-    /**
-     * Starts a timer for measuring elapsed time.
-     *
-     * Creates a timer with the given label. Use `timeEnd()` with the same label
-     * to stop the timer and log the elapsed time, or use `timeLog()` to check the
-     * time without stopping the timer.
-     *
-     * @default 'default'
-     *
-     * @param label - Optional label for the timer.
-     */
     time(label?: string | undefined): this;
-    /**
-     * Ends a timer and logs the elapsed time.
-     *
-     * Logs the duration since `console.time()` or `logger.time()` was called with
-     * the same label. The timer is stopped and removed.
-     *
-     * @default 'default'
-     *
-     * @param label - Optional label for the timer.
-     */
     timeEnd(label?: string | undefined): this;
-    /**
-     * Logs the current value of a timer without stopping it.
-     *
-     * Logs the duration since `console.time()` was called with the same label,
-     * but keeps the timer running. Can include additional data to log alongside
-     * the time.
-     *
-     * @default 'default'
-     *
-     * @param label - Optional label for the timer.
-     * @param data - Additional data to log with the time.
-     */
     timeLog(label?: string | undefined, ...data: unknown[]): this;
-    /**
-     * Logs a stack trace to the console.
-     *
-     * Works like `console.trace()`. Shows the call stack leading to where this
-     * method was called. Useful for debugging.
-     *
-     * @param message - Optional message to display with the trace.
-     * @param args - Additional arguments to log.
-     */
     trace(message?: unknown | undefined, ...args: unknown[]): this;
-    /**
-     * Logs a warning message with a yellow colored warning symbol.
-     *
-     * Automatically prefixes the message with `LOG_SYMBOLS.warn` (yellow ⚠).
-     * Always outputs to stderr. If the message starts with an existing symbol, it
-     * will be stripped and replaced.
-     */
     warn(...args: unknown[]): this;
-    /**
-     * Writes text directly to stdout without a newline or indentation.
-     *
-     * Useful for progress indicators or custom formatting where you need
-     * low-level control. Does not apply any indentation or formatting.
-     *
-     * @param text - The text to write.
-     */
     write(text: string): this;
 }