@socketsecurity/lib 1.0.4 → 1.1.0

package/dist/spinner.js

@@ -294,31 +294,51 @@ function Spinner(options) {
         super.text = this.#buildDisplayText();
       }
       /**
-       * Show a debug message without stopping the spinner (only if debug mode enabled).
+       * Show a debug message (ℹ) without stopping the spinner.
+       * Only displays if debug mode is enabled via environment variable.
        * Outputs to stderr and continues spinning.
+       *
+       * @param text - Debug message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
        */
-      debug(...args) {
+      debug(text, ...extras) {
         const { isDebug } = require("./debug.js");
         if (isDebug()) {
-          return this.#showStatusAndKeepSpinning("info", args);
+          return this.#showStatusAndKeepSpinning("info", [text, ...extras]);
         }
         return this;
       }
       /**
-       * Show a debug message and stop the spinner (only if debug mode enabled).
+       * Show a debug message (ℹ) and stop the spinner.
+       * Only displays if debug mode is enabled via environment variable.
        * Auto-clears the spinner line before displaying the message.
+       *
+       * @param text - Debug message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
        */
-      debugAndStop(...args) {
+      debugAndStop(text, ...extras) {
         const { isDebug } = require("./debug.js");
         if (isDebug()) {
-          return this.#apply("info", args);
+          return this.#apply("info", [text, ...extras]);
         }
         return this;
       }
       /**
-       * Decrease indentation level.
-       * Pass 0 to reset indentation to zero.
-       * @param spaces - Number of spaces to remove (default: 2)
+       * Decrease indentation level by removing spaces from the left.
+       * Pass 0 to reset indentation to zero completely.
+       *
+       * @param spaces - Number of spaces to remove
+       * @returns This spinner for chaining
+       * @default spaces=2
+       *
+       * @example
+       * ```ts
+       * spinner.dedent()    // Remove 2 spaces
+       * spinner.dedent(4)   // Remove 4 spaces
+       * spinner.dedent(0)   // Reset to zero indentation
+       * ```
        */
       dedent(spaces) {
         if (spaces === 0) {
@@ -332,40 +352,68 @@ function Spinner(options) {
         return this;
       }
       /**
-       * Alias for success() (shorter name).
-       * DESIGN DECISION: Unlike yocto-spinner, our done() does NOT stop the spinner.
-       * Use doneAndStop() if you want to stop the spinner.
+       * Show a done/success message (✓) without stopping the spinner.
+       * Alias for `success()` with a shorter name.
+       *
+       * DESIGN DECISION: Unlike yocto-spinner, our `done()` does NOT stop the spinner.
+       * Use `doneAndStop()` if you want to stop the spinner.
+       *
+       * @param text - Message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
        */
-      done(...args) {
-        return this.#showStatusAndKeepSpinning("success", args);
+      done(text, ...extras) {
+        return this.#showStatusAndKeepSpinning("success", [text, ...extras]);
       }
       /**
-       * Show a done message and stop the spinner.
+       * Show a done/success message (✓) and stop the spinner.
        * Auto-clears the spinner line before displaying the success message.
+       *
+       * @param text - Message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
        */
-      doneAndStop(...args) {
-        return this.#apply("success", args);
+      doneAndStop(text, ...extras) {
+        return this.#apply("success", [text, ...extras]);
       }
       /**
-       * Show a failure message without stopping the spinner.
-       * DESIGN DECISION: Unlike yocto-spinner, our fail() does NOT stop the spinner.
+       * Show a failure message (✗) without stopping the spinner.
+       * DESIGN DECISION: Unlike yocto-spinner, our `fail()` does NOT stop the spinner.
        * This allows displaying errors while continuing to spin.
-       * Use failAndStop() if you want to stop the spinner.
+       * Use `failAndStop()` if you want to stop the spinner.
+       *
+       * @param text - Error message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
        */
-      fail(...args) {
-        return this.#showStatusAndKeepSpinning("fail", args);
+      fail(text, ...extras) {
+        return this.#showStatusAndKeepSpinning("fail", [text, ...extras]);
       }
       /**
-       * Show a failure message and stop the spinner.
+       * Show a failure message (✗) and stop the spinner.
        * Auto-clears the spinner line before displaying the error message.
+       *
+       * @param text - Error message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
        */
-      failAndStop(...args) {
-        return this.#apply("error", args);
+      failAndStop(text, ...extras) {
+        return this.#apply("error", [text, ...extras]);
       }
       /**
-       * Increase indentation level.
-       * Pass 0 to reset indentation to zero.
-       * @param spaces - Number of spaces to add (default: 2)
+       * Increase indentation level by adding spaces to the left.
+       * Pass 0 to reset indentation to zero completely.
+       *
+       * @param spaces - Number of spaces to add
+       * @returns This spinner for chaining
+       * @default spaces=2
+       *
+       * @example
+       * ```ts
+       * spinner.indent()    // Add 2 spaces
+       * spinner.indent(4)   // Add 4 spaces
+       * spinner.indent(0)   // Reset to zero indentation
+       * ```
        */
       indent(spaces) {
         if (spaces === 0) {
@@ -378,22 +426,33 @@ function Spinner(options) {
         return this;
       }
       /**
-       * Show an info message without stopping the spinner.
+       * Show an info message (ℹ) without stopping the spinner.
        * Outputs to stderr and continues spinning.
+       *
+       * @param text - Info message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
        */
-      info(...args) {
-        return this.#showStatusAndKeepSpinning("info", args);
+      info(text, ...extras) {
+        return this.#showStatusAndKeepSpinning("info", [text, ...extras]);
       }
       /**
-       * Show an info message and stop the spinner.
+       * Show an info message (ℹ) and stop the spinner.
        * Auto-clears the spinner line before displaying the message.
+       *
+       * @param text - Info message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
        */
-      infoAndStop(...args) {
-        return this.#apply("info", args);
+      infoAndStop(text, ...extras) {
+        return this.#apply("info", [text, ...extras]);
       }
       /**
        * Log a message to stdout without stopping the spinner.
-       * Unlike other methods, this outputs to stdout for data logging.
+       * Unlike other status methods, this outputs to stdout for data logging.
+       *
+       * @param args - Values to log to stdout
+       * @returns This spinner for chaining
        */
       log(...args) {
         const { logger } = require("./logger.js");
@@ -401,18 +460,30 @@ function Spinner(options) {
         return this;
       }
       /**
-       * Log a message and stop the spinner.
+       * Log a message to stdout and stop the spinner.
        * Auto-clears the spinner line before displaying the message.
+       *
+       * @param text - Message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
        */
-      logAndStop(...args) {
-        return this.#apply("stop", args);
+      logAndStop(text, ...extras) {
+        return this.#apply("stop", [text, ...extras]);
       }
       /**
        * Update progress information displayed with the spinner.
        * Shows a progress bar with percentage and optional unit label.
+       *
        * @param current - Current progress value
-       * @param total - Total progress value
+       * @param total - Total/maximum progress value
        * @param unit - Optional unit label (e.g., 'files', 'items')
+       * @returns This spinner for chaining
+       *
+       * @example
+       * ```ts
+       * spinner.progress(5, 10)            // "███████░░░░░░░░░░░░░ 50% (5/10)"
+       * spinner.progress(7, 20, 'files')   // "███████░░░░░░░░░░░░░ 35% (7/20 files)"
+       * ```
        */
       progress = (current, total, unit) => {
         this.#progress = {
@@ -427,7 +498,18 @@ function Spinner(options) {
       /**
        * Increment progress by a specified amount.
        * Updates the progress bar displayed with the spinner.
-       * @param amount - Amount to increment (default: 1)
+       * Clamps the result between 0 and the total value.
+       *
+       * @param amount - Amount to increment by
+       * @returns This spinner for chaining
+       * @default amount=1
+       *
+       * @example
+       * ```ts
+       * spinner.progress(0, 10, 'files')
+       * spinner.progressStep()    // Progress: 1/10
+       * spinner.progressStep(3)   // Progress: 4/10
+       * ```
        */
       progressStep(amount = 1) {
         if (this.#progress) {
@@ -444,8 +526,17 @@ function Spinner(options) {
       }
       /**
        * Start the spinner animation with optional text.
-       * Begins displaying the animated spinner.
+       * Begins displaying the animated spinner on stderr.
+       *
        * @param text - Optional text to display with the spinner
+       * @returns This spinner for chaining
+       *
+       * @example
+       * ```ts
+       * spinner.start('Loading…')
+       * // Later:
+       * spinner.successAndStop('Done!')
+       * ```
        */
       start(...args) {
         if (args.length) {
@@ -464,27 +555,47 @@ function Spinner(options) {
       /**
        * Log a main step message to stderr without stopping the spinner.
        * Adds a blank line before the message for visual separation.
-       * Aligns with logger.step() to use stderr for status messages.
+       * Aligns with `logger.step()` to use stderr for status messages.
+       *
+       * @param text - Step message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       *
+       * @example
+       * ```ts
+       * spinner.step('Building application')
+       * spinner.substep('Compiling TypeScript')
+       * spinner.substep('Bundling assets')
+       * ```
        */
-      step(...args) {
-        const text = args[0];
+      step(text, ...extras) {
         const { logger } = require("./logger.js");
         if (typeof text === "string") {
           logger.error("");
-          logger.error(text, ...args.slice(1));
+          logger.error(text, ...extras);
         }
         return this;
       }
       /**
        * Log an indented substep message to stderr without stopping the spinner.
        * Adds 2-space indentation to the message.
-       * Aligns with logger.substep() to use stderr for status messages.
+       * Aligns with `logger.substep()` to use stderr for status messages.
+       *
+       * @param text - Substep message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
+       *
+       * @example
+       * ```ts
+       * spinner.step('Building application')
+       * spinner.substep('Compiling TypeScript')
+       * spinner.substep('Bundling assets')
+       * ```
        */
-      substep(...args) {
-        const text = args[0];
+      substep(text, ...extras) {
         if (typeof text === "string") {
           const { logger } = require("./logger.js");
-          logger.error(`  ${text}`, ...args.slice(1));
+          logger.error(`  ${text}`, ...extras);
         }
         return this;
       }
@@ -492,7 +603,18 @@ function Spinner(options) {
        * Stop the spinner animation and clear internal state.
        * Auto-clears the spinner line via yocto-spinner.stop().
        * Resets progress, shimmer, and text state.
+       *
        * @param text - Optional final text to display after stopping
+       * @returns This spinner for chaining
+       *
+       * @example
+       * ```ts
+       * spinner.start('Processing…')
+       * // Do work
+       * spinner.stop() // Just stop, no message
+       * // or
+       * spinner.stop('Finished processing')
+       * ```
        */
       stop(...args) {
         this.#baseText = "";
@@ -506,20 +628,28 @@ function Spinner(options) {
         return result;
       }
       /**
-       * Show a success message without stopping the spinner.
-       * DESIGN DECISION: Unlike yocto-spinner, our success() does NOT stop the spinner.
+       * Show a success message (✓) without stopping the spinner.
+       * DESIGN DECISION: Unlike yocto-spinner, our `success()` does NOT stop the spinner.
        * This allows displaying success messages while continuing to spin for multi-step operations.
-       * Use successAndStop() if you want to stop the spinner.
+       * Use `successAndStop()` if you want to stop the spinner.
+       *
+       * @param text - Success message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
        */
-      success(...args) {
-        return this.#showStatusAndKeepSpinning("success", args);
+      success(text, ...extras) {
+        return this.#showStatusAndKeepSpinning("success", [text, ...extras]);
       }
       /**
-       * Show a success message and stop the spinner.
+       * Show a success message (✓) and stop the spinner.
        * Auto-clears the spinner line before displaying the success message.
+       *
+       * @param text - Success message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
        */
-      successAndStop(...args) {
-        return this.#apply("success", args);
+      successAndStop(text, ...extras) {
+        return this.#apply("success", [text, ...extras]);
       }
       text(value) {
         if (arguments.length === 0) {
@@ -530,18 +660,26 @@ function Spinner(options) {
         return this;
       }
       /**
-       * Show a warning message without stopping the spinner.
+       * Show a warning message (⚠) without stopping the spinner.
        * Outputs to stderr and continues spinning.
+       *
+       * @param text - Warning message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
        */
-      warn(...args) {
-        return this.#showStatusAndKeepSpinning("warn", args);
+      warn(text, ...extras) {
+        return this.#showStatusAndKeepSpinning("warn", [text, ...extras]);
       }
       /**
-       * Show a warning message and stop the spinner.
+       * Show a warning message (⚠) and stop the spinner.
        * Auto-clears the spinner line before displaying the warning message.
+       *
+       * @param text - Warning message to display
+       * @param extras - Additional values to log
+       * @returns This spinner for chaining
        */
-      warnAndStop(...args) {
-        return this.#apply("warning", args);
+      warnAndStop(text, ...extras) {
+        return this.#apply("warning", [text, ...extras]);
       }
       /**
        * Toggle shimmer effect or update shimmer configuration.