@socketsecurity/lib 1.0.5 → 1.1.0

package/dist/logger.js

@@ -135,6 +135,14 @@ const incLogCallCountSymbol = Symbol.for("logger.logCallCount++");
 const kGroupIndentationWidthSymbol = consoleSymbols.find((s) => s.label === "kGroupIndentWidth") ?? Symbol("kGroupIndentWidth");
 const lastWasBlankSymbol = Symbol.for("logger.lastWasBlank");
 class Logger {
+  /**
+   * Static reference to log symbols for convenience.
+   *
+   * @example
+   * ```typescript
+   * console.log(`${Logger.LOG_SYMBOLS.success} Done`)
+   * ```
+   */
   static LOG_SYMBOLS = LOG_SYMBOLS;
   #parent;
   #boundStream;
@@ -146,6 +154,27 @@ class Logger {
   #logCallCount = 0;
   #constructorArgs;
   #options;
+  /**
+   * 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
+   *
+   * @example
+   * ```typescript
+   * // Default logger
+   * const logger = new Logger()
+   *
+   * // Custom streams (advanced)
+   * const customLogger = new Logger({
+   *   stdout: customWritableStream,
+   *   stderr: customErrorStream
+   * })
+   * ```
+   */
   constructor(...args) {
     this.#constructorArgs = args;
     const options = args["0"];
@@ -168,8 +197,25 @@ class Logger {
     }
   }
   /**
-   * Get a logger instance bound to stderr.
-   * All operations on this instance will use stderr.
+   * 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
+   *
+   * @example
+   * ```typescript
+   * // Write errors to stderr
+   * logger.stderr.error('Configuration invalid')
+   * logger.stderr.warn('Using fallback settings')
+   *
+   * // Indent only affects stderr
+   * logger.stderr.indent()
+   * logger.stderr.error('Nested error details')
+   * logger.stderr.dedent()
+   * ```
    */
   get stderr() {
     if (!this.#stderrLogger) {
@@ -182,8 +228,25 @@ class Logger {
     return this.#stderrLogger;
   }
   /**
-   * Get a logger instance bound to stdout.
-   * All operations on this instance will use stdout.
+   * 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
+   *
+   * @example
+   * ```typescript
+   * // Write normal output to stdout
+   * logger.stdout.log('Processing started')
+   * logger.stdout.log('Items processed: 42')
+   *
+   * // Indent only affects stdout
+   * logger.stdout.indent()
+   * logger.stdout.log('Detailed output')
+   * logger.stdout.dedent()
+   * ```
    */
   get stdout() {
     if (!this.#stdoutLogger) {
@@ -283,27 +346,65 @@ class Logger {
     return this;
   }
   /**
-   * Get the current log call count.
+   * 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
+   *
+   * @example
+   * ```typescript
+   * logger.log('Message 1')
+   * logger.error('Message 2')
+   * console.log(logger.logCallCount) // 2
+   * ```
    */
   get logCallCount() {
     return this.#logCallCount;
   }
   /**
-   * Increment the log call count.
+   * Increments the internal log call counter.
+   *
+   * This is called automatically by logging methods and should not
+   * be called directly in normal usage.
+   *
+   * @returns The logger instance for chaining
    */
   [incLogCallCountSymbol]() {
     this.#logCallCount += 1;
     return this;
   }
   /**
-   * Set whether the last logged line was blank.
+   * 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
+   * @returns The logger instance for chaining
    */
   [lastWasBlankSymbol](value) {
     this.#lastWasBlank = !!value;
     return this;
   }
   /**
-   * Log an assertion.
+   * 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
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.assert(true, 'This will not log')
+   * logger.assert(false, 'Assertion failed: value is false')
+   * logger.assert(items.length > 0, 'No items found')
+   * ```
    */
   assert(value, ...message) {
     const con = privateConsole.get(this);
@@ -312,8 +413,23 @@ class Logger {
     return value ? this : this[incLogCallCountSymbol]();
   }
   /**
-   * Clear the visible terminal screen.
-   * Only available on the main logger instance.
+   * 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.
+   *
+   * @returns The logger instance for chaining
+   * @throws {Error} If called on a stream-bound logger instance
+   *
+   * @example
+   * ```typescript
+   * logger.log('Some output')
+   * logger.clearVisible()  // Screen is now clear
+   *
+   * // Error: Can't call on stream-bound instance
+   * logger.stderr.clearVisible()  // throws
+   * ```
    */
   clearVisible() {
     if (this.#boundStream) {
@@ -331,7 +447,21 @@ class Logger {
     return this;
   }
   /**
-   * Log a count for the given label.
+   * Increments and logs a counter for the given label.
+   *
+   * Each unique label maintains its own counter. Works like `console.count()`.
+   *
+   * @param label - Optional label for the counter
+   * @default 'default'
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.count('requests')  // requests: 1
+   * logger.count('requests')  // requests: 2
+   * logger.count('errors')    // errors: 1
+   * logger.count()            // default: 1
+   * ```
    */
   count(label) {
     const con = privateConsole.get(this);
@@ -340,7 +470,26 @@ class Logger {
     return this[incLogCallCountSymbol]();
   }
   /**
-   * Create a task with a given name.
+   * 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
+   *
+   * @example
+   * ```typescript
+   * const task = logger.createTask('Database Migration')
+   * const result = task.run(() => {
+   *   // Logs: "Starting task: Database Migration"
+   *   migrateDatabase()
+   *   return 'success'
+   *   // Logs: "Completed task: Database Migration"
+   * })
+   * console.log(result)  // 'success'
+   * ```
    */
   createTask(name) {
     return {
@@ -353,9 +502,33 @@ class Logger {
     };
   }
   /**
-   * Decrease indentation level.
-   * If called on main logger, affects both streams.
-   * If called on stream-bound logger, affects only that stream.
+   * 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.
+   *
+   * @param spaces - Number of spaces to remove from indentation
+   * @default 2
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.indent()
+   * logger.log('Indented')
+   * logger.dedent()
+   * logger.log('Back to normal')
+   *
+   * // Remove custom amount
+   * logger.indent(4)
+   * logger.log('Four spaces')
+   * logger.dedent(4)
+   *
+   * // Stream-specific dedent
+   * logger.stdout.indent()
+   * logger.stdout.log('Indented stdout')
+   * logger.stdout.dedent()
+   * ```
    */
   dedent(spaces = 2) {
     if (this.#boundStream) {
@@ -370,7 +543,22 @@ class Logger {
     return this;
   }
   /**
-   * Display an object's properties.
+   * 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)
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * const obj = { a: 1, b: { c: 2, d: { e: 3 } } }
+   * logger.dir(obj)
+   * logger.dir(obj, { depth: 1 })  // Limit nesting depth
+   * logger.dir(obj, { colors: true })  // Enable colors
+   * ```
    */
   dir(obj, options) {
     const con = privateConsole.get(this);
@@ -379,7 +567,18 @@ class Logger {
     return this[incLogCallCountSymbol]();
   }
   /**
-   * Display data as XML.
+   * 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
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.dirxml(document.body)  // In browser environments
+   * logger.dirxml(xmlObject)       // In Node.js
+   * ```
    */
   dirxml(...data) {
     const con = privateConsole.get(this);
@@ -388,25 +587,87 @@ class Logger {
     return this[incLogCallCountSymbol]();
   }
   /**
-   * Log an error message.
+   * Logs an error message to stderr.
+   *
+   * Automatically applies current indentation. All arguments are formatted
+   * and logged like `console.error()`.
+   *
+   * @param args - Message and additional arguments to log
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.error('Build failed')
+   * logger.error('Error code:', 500)
+   * logger.error('Details:', { message: 'Not found' })
+   * ```
    */
   error(...args) {
     return this.#apply("error", args);
   }
   /**
-   * Log a newline to stderr if last line wasn't blank.
+   * 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.
+   *
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.error('Error message')
+   * logger.errorNewline()  // Adds blank line
+   * logger.errorNewline()  // Does nothing (already blank)
+   * logger.error('Next section')
+   * ```
    */
   errorNewline() {
     return this.#lastWasBlank ? this : this.error("");
   }
   /**
-   * Log a failure message with symbol.
+   * 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.
+   *
+   * @param args - Message and additional arguments to log
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.fail('Build failed')
+   * logger.fail('Test suite failed:', { passed: 5, failed: 3 })
+   * ```
    */
   fail(...args) {
     return this.#symbolApply("fail", args);
   }
   /**
-   * Start a new log group.
+   * 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
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.group('Processing files:')
+   * logger.log('file1.js')
+   * logger.log('file2.js')
+   * logger.groupEnd()
+   *
+   * // Nested groups
+   * logger.group('Outer')
+   * logger.log('Outer content')
+   * logger.group('Inner')
+   * logger.log('Inner content')
+   * logger.groupEnd()
+   * logger.groupEnd()
+   * ```
    */
   group(...label) {
     const { length } = label;
@@ -422,7 +683,20 @@ class Logger {
     return this;
   }
   /**
-   * Start a new collapsed log group (alias for group).
+   * 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
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.groupCollapsed('Details')
+   * logger.log('Hidden by default in browsers')
+   * logger.groupEnd()
+   * ```
    */
   // groupCollapsed is an alias of group.
   // https://nodejs.org/api/console.html#consolegroupcollapsed
@@ -430,16 +704,54 @@ class Logger {
     return ReflectApply(this.group, this, label);
   }
   /**
-   * End the current log group.
+   * 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.
+   *
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.group('Group 1')
+   * logger.log('Content')
+   * logger.groupEnd()  // Closes 'Group 1'
+   * ```
    */
   groupEnd() {
     this.dedent(this[kGroupIndentationWidthSymbol]);
     return this;
   }
   /**
-   * Increase indentation level.
-   * If called on main logger, affects both streams.
-   * If called on stream-bound logger, affects only that stream.
+   * 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.
+   *
+   * @param spaces - Number of spaces to add to indentation
+   * @default 2
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.log('Level 0')
+   * logger.indent()
+   * logger.log('Level 1')
+   * logger.indent()
+   * logger.log('Level 2')
+   * logger.dedent()
+   * logger.dedent()
+   *
+   * // Custom indent amount
+   * logger.indent(4)
+   * logger.log('Indented 4 spaces')
+   * logger.dedent(4)
+   *
+   * // Stream-specific indent
+   * logger.stdout.indent()
+   * logger.stdout.log('Only stdout is indented')
+   * ```
    */
   indent(spaces = 2) {
     const spacesToAdd = " ".repeat(Math.min(spaces, maxIndentation));
@@ -455,27 +767,86 @@ class Logger {
     return this;
   }
   /**
-   * Log an info message with symbol.
+   * 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.
+   *
+   * @param args - Message and additional arguments to log
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.info('Starting build process')
+   * logger.info('Configuration loaded:', config)
+   * logger.info('Using cache directory:', cacheDir)
+   * ```
    */
   info(...args) {
     return this.#symbolApply("info", args);
   }
   /**
-   * Log a message.
+   * 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.
+   *
+   * @param args - Message and additional arguments to log
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.log('Processing complete')
+   * logger.log('Items processed:', 42)
+   * logger.log('Results:', { success: true, count: 10 })
+   *
+   * // Method chaining
+   * logger.log('Step 1').log('Step 2').log('Step 3')
+   * ```
    */
   log(...args) {
     return this.#apply("log", args);
   }
   /**
-   * Log a newline to stdout if last line wasn't blank.
+   * 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.
+   *
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.log('Section 1')
+   * logger.logNewline()  // Adds blank line
+   * logger.logNewline()  // Does nothing (already blank)
+   * logger.log('Section 2')
+   * ```
    */
   logNewline() {
     return this.#lastWasBlank ? this : this.log("");
   }
   /**
-   * Reset indentation to zero.
-   * If called on main logger, resets both streams.
-   * If called on stream-bound logger, resets only that stream.
+   * 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.
+   *
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.indent().indent().indent()
+   * logger.log('Very indented')
+   * logger.resetIndent()
+   * logger.log('Back to zero indentation')
+   *
+   * // Reset only stdout
+   * logger.stdout.resetIndent()
+   * ```
    */
   resetIndent() {
     if (this.#boundStream) {
@@ -487,7 +858,30 @@ class Logger {
     return this;
   }
   /**
-   * Log a main step with blank line before (stateless).
+   * Logs a main step message with a blank line before it (stateless).
+   *
+   * Automatically 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.
+   *
+   * @param msg - The step message to log
+   * @param extras - Additional arguments to log
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.step('Building project')
+   * logger.log('Compiling TypeScript...')
+   * logger.step('Running tests')
+   * logger.log('Running test suite...')
+   * // Output:
+   * // [blank line]
+   * // Building project
+   * // Compiling TypeScript...
+   * // [blank line]
+   * // Running tests
+   * // Running test suite...
+   * ```
    */
   step(msg, ...extras) {
     if (!this.#lastWasBlank) {
@@ -496,27 +890,104 @@ class Logger {
     return this.log(msg, ...extras);
   }
   /**
-   * Log an indented substep (stateless).
+   * 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
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.log('Installing dependencies:')
+   * logger.substep('Installing react')
+   * logger.substep('Installing typescript')
+   * logger.substep('Installing eslint')
+   * // Output:
+   * // Installing dependencies:
+   * //   Installing react
+   * //   Installing typescript
+   * //   Installing eslint
+   * ```
    */
   substep(msg, ...extras) {
     const indentedMsg = `  ${msg}`;
     return this.log(indentedMsg, ...extras);
   }
   /**
-   * Log a success message with symbol.
+   * 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.
+   *
+   * @param args - Message and additional arguments to log
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.success('Build completed')
+   * logger.success('Tests passed:', { total: 42, passed: 42 })
+   * logger.success('Deployment successful')
+   * ```
    */
   success(...args) {
     return this.#symbolApply("success", args);
   }
   /**
-   * Log a done message (alias for success).
-   * Does NOT auto-clear. Call clearLine() first if needed after progress().
+   * 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()`.
+   *
+   * @param args - Message and additional arguments to log
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.done('Task completed')
+   *
+   * // After progress indicator
+   * logger.progress('Processing...')
+   * // ... do work ...
+   * logger.clearLine()
+   * logger.done('Processing complete')
+   * ```
    */
   done(...args) {
     return this.#symbolApply("success", args);
   }
   /**
-   * Display data in a table format.
+   * 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
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * // Array of objects
+   * logger.table([
+   *   { name: 'Alice', age: 30 },
+   *   { name: 'Bob', age: 25 }
+   * ])
+   *
+   * // Specify properties to show
+   * logger.table(users, ['name', 'email'])
+   *
+   * // Object with nested objects
+   * logger.table({
+   *   user1: { name: 'Alice', age: 30 },
+   *   user2: { name: 'Bob', age: 25 }
+   * })
+   * ```
    */
   table(tabularData, properties) {
     const con = privateConsole.get(this);
@@ -525,7 +996,27 @@ class Logger {
     return this[incLogCallCountSymbol]();
   }
   /**
-   * End a timer and log the elapsed time.
+   * Ends a timer and logs the elapsed time.
+   *
+   * Logs the duration since `console.time()` was called with the same
+   * label. The timer is stopped and removed.
+   *
+   * @param label - Optional label for the timer
+   * @default 'default'
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * console.time('operation')
+   * // ... do work ...
+   * logger.timeEnd('operation')
+   * // Logs: "operation: 123.456ms"
+   *
+   * console.time()
+   * // ... do work ...
+   * logger.timeEnd()
+   * // Logs: "default: 123.456ms"
+   * ```
    */
   timeEnd(label) {
     const con = privateConsole.get(this);
@@ -534,7 +1025,28 @@ class Logger {
     return this[incLogCallCountSymbol]();
   }
   /**
-   * Log the current timer value.
+   * 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.
+   *
+   * @param label - Optional label for the timer
+   * @param data - Additional data to log with the time
+   * @default 'default'
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * console.time('process')
+   * // ... partial work ...
+   * logger.timeLog('process', 'Checkpoint 1')
+   * // Logs: "process: 123.456ms Checkpoint 1"
+   * // ... more work ...
+   * logger.timeLog('process', 'Checkpoint 2')
+   * // Logs: "process: 234.567ms Checkpoint 2"
+   * console.timeEnd('process')
+   * ```
    */
   timeLog(label, ...data) {
     const con = privateConsole.get(this);
@@ -543,7 +1055,24 @@ class Logger {
     return this[incLogCallCountSymbol]();
   }
   /**
-   * Log a stack trace.
+   * 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
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * function debugFunction() {
+   *   logger.trace('Debug point reached')
+   * }
+   *
+   * logger.trace('Trace from here')
+   * logger.trace('Error context:', { userId: 123 })
+   * ```
    */
   trace(message, ...args) {
     const con = privateConsole.get(this);
@@ -552,13 +1081,45 @@ class Logger {
     return this[incLogCallCountSymbol]();
   }
   /**
-   * Log a warning message with symbol.
+   * 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.
+   *
+   * @param args - Message and additional arguments to log
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.warn('Deprecated API used')
+   * logger.warn('Low memory:', { available: '100MB' })
+   * logger.warn('Missing optional configuration')
+   * ```
    */
   warn(...args) {
     return this.#symbolApply("warn", args);
   }
   /**
-   * Write to stdout without a newline or indentation.
+   * 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
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.write('Processing... ')
+   * // ... do work ...
+   * logger.write('done\n')
+   *
+   * // Build a line incrementally
+   * logger.write('Step 1')
+   * logger.write('... Step 2')
+   * logger.write('... Step 3\n')
+   * ```
    */
   write(text) {
     const con = privateConsole.get(this);
@@ -567,8 +1128,29 @@ class Logger {
     return this;
   }
   /**
-   * Show a progress indicator (can be cleared with clearLine).
-   * Simple status message without spinner animation.
+   * 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
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.progress('Processing files...')
+   * // ... do work ...
+   * logger.clearLine()
+   * logger.success('Files processed')
+   *
+   * // Stream-specific progress
+   * logger.stdout.progress('Loading...')
+   * // ... do work ...
+   * logger.stdout.clearLine()
+   * logger.stdout.log('Done')
+   * ```
    */
   progress(text) {
     const con = privateConsole.get(this);
@@ -579,7 +1161,32 @@ class Logger {
     return this;
   }
   /**
-   * Clear the current line.
+   * 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.
+   *
+   * @returns The logger instance for chaining
+   *
+   * @example
+   * ```typescript
+   * logger.progress('Loading...')
+   * // ... do work ...
+   * logger.clearLine()
+   * logger.success('Loaded')
+   *
+   * // Clear multiple progress updates
+   * for (const file of files) {
+   *   logger.progress(`Processing ${file}`)
+   *   processFile(file)
+   *   logger.clearLine()
+   * }
+   * logger.success('All files processed')
+   * ```
    */
   clearLine() {
     const con = privateConsole.get(this);