@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/logger/logger.d.ts

@@ -0,0 +1,405 @@
+/**
+ * @file The `Logger` class + the shared-default `getDefaultLogger()` accessor —
+ *   the public class surface for `logger/*`. Owns the per-instance state
+ *   (parent, bound stream, indent buffers, theme), the symbol-prefixed semantic
+ *   methods (`success`, `fail`, `info`, ...), the chainable wrappers around the
+ *   underlying `Console` methods, AND the module-singleton accessor for the
+ *   shared default instance. 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`
+ */
+import { incLogCallCountSymbol, lastWasBlankSymbol } from './symbols';
+import type { Task } from './types';
+/**
+ * Enhanced console logger with indentation, colored symbols, and stream
+ * management.
+ */
+export declare class Logger {
+    #private;
+    /**
+     * Static reference to log symbols for convenience.
+     */
+    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.
+     *
+     * @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.
+     *
+     * @param name - The name of the task.
+     *
+     * @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.
+     *
+     * @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;
+}
+/**
+ * Get the default logger instance. Lazily creates the logger to avoid circular
+ * dependencies during module initialization. Reuses the same instance across
+ * calls.
+ *
+ * Construction is lazy so that importing this module during early Node.js
+ * bootstrap doesn't try to resolve `node:console` before stdout is ready
+ * (mirrors the lazy `Console` init inside `Logger` itself).
+ *
+ * @returns Shared default logger instance
+ */
+export declare function getDefaultLogger(): Logger;