@socketsecurity/lib 5.19.0 → 5.19.1

package/dist/stdio/clear.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Terminal clearing and cursor utilities.
+ * Provides functions for clearing lines, screens, and managing cursor position.
+ */
+/**
+ * Clear the current line in the terminal.
+ * Uses native TTY methods when available, falls back to ANSI escape codes.
+ * Uses native TTY methods when available and falls back to `\r\x1b[K` ANSI
+ * escapes on non-TTY streams.
+ *
+ * ANSI Sequences:
+ * - `\r`: Carriage return (move to line start)
+ * - `\x1b[K`: Clear from cursor to end of line
+ *
+ * @param stream - Output stream to clear (defaults to `process.stdout`)
+ * @default stream process.stdout
+ *
+ * @example
+ * ```ts
+ * clearLine() // Clear current line on stdout
+ * clearLine(process.stderr) // Clear on stderr
+ * ```
+ */
+export declare function clearLine(stream?: NodeJS.WriteStream): void;
+/**
+ * Clear multiple lines above the current cursor position.
+ * Useful for clearing multi-line output like progress bars or status messages.
+ *
+ * ANSI Sequences:
+ * - `\x1b[1A`: Move cursor up one line
+ * - `\x1b[2K`: Erase entire line
+ *
+ * @param count - Number of lines to clear
+ * @param stream - Output stream to clear
+ * @default stream process.stdout
+ *
+ * @example
+ * ```ts
+ * console.log('Line 1')
+ * console.log('Line 2')
+ * console.log('Line 3')
+ * clearLines(2) // Clears lines 2 and 3
+ * ```
+ */
+export declare function clearLines(count: number, stream?: NodeJS.WriteStream): void;
+/**
+ * Clear the entire screen and reset cursor to top-left.
+ * Only works in TTY environments.
+ *
+ * ANSI Sequence:
+ * - `\x1bc`: Full reset (clear screen and move cursor home)
+ *
+ * @param stream - Output stream to clear
+ * @default stream process.stdout
+ *
+ * @example
+ * ```ts
+ * clearScreen() // Clear entire terminal
+ * ```
+ */
+export declare function clearScreen(stream?: NodeJS.WriteStream): void;
+/**
+ * Clear the visible terminal screen.
+ * Alias for `clearScreen()`.
+ *
+ * @param stream - Output stream to clear
+ * @default stream process.stdout
+ *
+ * @example
+ * ```ts
+ * clearVisible() // Same as clearScreen()
+ * ```
+ */
+export declare function clearVisible(stream?: NodeJS.WriteStream): void;
+/**
+ * Move cursor to the beginning of the current line.
+ * Uses native TTY methods when available, falls back to carriage return.
+ *
+ * @param stream - Output stream to manipulate
+ * @default stream process.stdout
+ *
+ * @example
+ * ```ts
+ * process.stdout.write('Some text...')
+ * cursorToStart()
+ * process.stdout.write('New text') // Overwrites from start
+ * ```
+ */
+export declare function cursorToStart(stream?: NodeJS.WriteStream): void;
+/**
+ * Hide the terminal cursor.
+ * Useful for cleaner output during animations or progress indicators.
+ *
+ * ANSI Sequence:
+ * - `\x1b[?25l`: DECTCEM hide cursor
+ *
+ * @param stream - Output stream to manipulate
+ * @default stream process.stdout
+ *
+ * @example
+ * ```ts
+ * hideCursor()
+ * // ... show animation
+ * showCursor()
+ * ```
+ */
+export declare function hideCursor(stream?: NodeJS.WriteStream): void;
+/**
+ * Restore cursor to previously saved position.
+ * Must be called after `saveCursor()`.
+ *
+ * ANSI Sequence:
+ * - `\x1b8`: DECRC restore cursor
+ *
+ * @param stream - Output stream to manipulate
+ * @default stream process.stdout
+ *
+ * @example
+ * ```ts
+ * saveCursor()
+ * console.log('Temporary text')
+ * restoreCursor()
+ * console.log('Back at saved position')
+ * ```
+ */
+export declare function restoreCursor(stream?: NodeJS.WriteStream): void;
+/**
+ * Save the current cursor position.
+ * Can be restored later with `restoreCursor()`.
+ *
+ * ANSI Sequence:
+ * - `\x1b7`: DECSC save cursor
+ *
+ * @param stream - Output stream to manipulate
+ * @default stream process.stdout
+ *
+ * @example
+ * ```ts
+ * saveCursor()
+ * console.log('Temporary text')
+ * restoreCursor()
+ * console.log('Back at saved position')
+ * ```
+ */
+export declare function saveCursor(stream?: NodeJS.WriteStream): void;
+/**
+ * Show the terminal cursor.
+ * Should be called after `hideCursor()` to restore normal cursor visibility.
+ *
+ * ANSI Sequence:
+ * - `\x1b[?25h`: DECTCEM show cursor
+ *
+ * @param stream - Output stream to manipulate
+ * @default stream process.stdout
+ *
+ * @example
+ * ```ts
+ * hideCursor()
+ * // ... show animation
+ * showCursor()
+ * ```
+ */
+export declare function showCursor(stream?: NodeJS.WriteStream): void;

package/dist/stdio/clear.js

@@ -0,0 +1,96 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var clear_exports = {};
+__export(clear_exports, {
+  clearLine: () => clearLine,
+  clearLines: () => clearLines,
+  clearScreen: () => clearScreen,
+  clearVisible: () => clearVisible,
+  cursorToStart: () => cursorToStart,
+  hideCursor: () => hideCursor,
+  restoreCursor: () => restoreCursor,
+  saveCursor: () => saveCursor,
+  showCursor: () => showCursor
+});
+module.exports = __toCommonJS(clear_exports);
+var import_node_process = __toESM(require("node:process"));
+function clearLine(stream = import_node_process.default.stdout) {
+  if (stream.isTTY) {
+    stream.cursorTo(0);
+    stream.clearLine(0);
+  } else {
+    stream.write("\r\x1B[K");
+  }
+}
+function clearLines(count, stream = import_node_process.default.stdout) {
+  for (let i = 0; i < count; i++) {
+    stream.write("\x1B[1A\x1B[2K");
+  }
+}
+function clearScreen(stream = import_node_process.default.stdout) {
+  if (stream.isTTY) {
+    stream.write("\x1Bc");
+  }
+}
+function clearVisible(stream = import_node_process.default.stdout) {
+  clearScreen(stream);
+}
+function cursorToStart(stream = import_node_process.default.stdout) {
+  if (stream.isTTY) {
+    stream.cursorTo(0);
+  } else {
+    stream.write("\r");
+  }
+}
+function hideCursor(stream = import_node_process.default.stdout) {
+  stream.write("\x1B[?25l");
+}
+function restoreCursor(stream = import_node_process.default.stdout) {
+  stream.write("\x1B8");
+}
+function saveCursor(stream = import_node_process.default.stdout) {
+  stream.write("\x1B7");
+}
+function showCursor(stream = import_node_process.default.stdout) {
+  stream.write("\x1B[?25h");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearLine,
+  clearLines,
+  clearScreen,
+  clearVisible,
+  cursorToStart,
+  hideCursor,
+  restoreCursor,
+  saveCursor,
+  showCursor
+});

package/dist/stdio/progress.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Progress bar utilities for CLI applications.
+ * Provides various progress indicators including bars, percentages, and spinners.
+ */
+export interface ProgressBarOptions {
+    /**
+     * Width of the progress bar in characters.
+     * @default 40
+     */
+    width?: number | undefined;
+    /**
+     * Format template for progress bar display.
+     * Available tokens: `:bar`, `:percent`, `:current`, `:total`, `:elapsed`, `:eta`.
+     * Custom tokens can be passed via the `tokens` parameter in `update()` or `tick()`.
+     * @default ':bar :percent :current/:total'
+     * @example
+     * ```ts
+     * format: ':bar :percent :current/:total :eta'
+     * ```
+     */
+    format?: string | undefined;
+    /**
+     * Character(s) to use for completed portion of bar.
+     * @default '█'
+     */
+    complete?: string | undefined;
+    /**
+     * Character(s) to use for incomplete portion of bar.
+     * @default '░'
+     */
+    incomplete?: string | undefined;
+    /**
+     * Character(s) to use for the head of the progress bar.
+     * @default ''
+     */
+    head?: string | undefined;
+    /**
+     * Clear the progress bar when complete.
+     * @default false
+     */
+    clear?: boolean | undefined;
+    /**
+     * Minimum time between renders in milliseconds.
+     * ~60fps = 16ms throttle.
+     * @default 16
+     */
+    renderThrottle?: number | undefined;
+    /**
+     * Stream to write progress bar output to.
+     * @default process.stderr
+     */
+    stream?: NodeJS.WriteStream | undefined;
+    /**
+     * Color to apply to the completed portion of the bar.
+     * @default 'cyan'
+     */
+    color?: 'cyan' | 'green' | 'yellow' | 'blue' | 'magenta' | undefined;
+}
+export declare class ProgressBar {
+    private current;
+    private total;
+    private startTime;
+    private lastRender;
+    private stream;
+    private options;
+    private terminated;
+    private lastDrawnWidth;
+    /**
+     * Create a new progress bar instance.
+     *
+     * @param total - Total number of units for the progress bar
+     * @param options - Configuration options for the progress bar
+     *
+     * @example
+     * ```ts
+     * const bar = new ProgressBar(100, {
+     *   width: 50,
+     *   format: ':bar :percent :current/:total :eta',
+     *   color: 'green'
+     * })
+     * ```
+     */
+    constructor(total: number, options?: ProgressBarOptions);
+    /**
+     * Update progress to a specific value and redraw the bar.
+     * Updates are throttled to prevent excessive rendering (default ~60fps).
+     *
+     * @param current - Current progress value (will be clamped to total)
+     * @param tokens - Optional custom tokens to replace in format string
+     *
+     * @example
+     * ```ts
+     * bar.update(50)
+     * bar.update(75, { status: 'Processing...' })
+     * ```
+     */
+    update(current: number, tokens?: Record<string, unknown>): void;
+    /**
+     * Increment progress by a specified amount.
+     * Convenience method for `update(current + amount)`.
+     *
+     * @param amount - Amount to increment by
+     * @param tokens - Optional custom tokens to replace in format string
+     * @default amount 1
+     *
+     * @example
+     * ```ts
+     * bar.tick() // Increment by 1
+     * bar.tick(5) // Increment by 5
+     * bar.tick(1, { file: 'data.json' })
+     * ```
+     */
+    tick(amount?: number, tokens?: Record<string, unknown>): void;
+    /**
+     * Render the progress bar.
+     */
+    private render;
+    /**
+     * Clear the current line.
+     */
+    private clearLine;
+    /**
+     * Format time in seconds to human readable.
+     */
+    private formatTime;
+    /**
+     * Terminate the progress bar and optionally clear it.
+     * Called automatically when progress reaches 100%.
+     * If `clear` option is true, removes the bar from terminal.
+     * Otherwise, moves to next line to preserve the final state.
+     */
+    terminate(): void;
+}
+/**
+ * Create a simple progress indicator without a graphical bar.
+ * Returns a formatted string showing progress as percentage and fraction.
+ *
+ * @param current - Current progress value
+ * @param total - Total progress value
+ * @param label - Optional label prefix
+ * @returns Formatted progress indicator string
+ *
+ * @example
+ * ```ts
+ * createProgressIndicator(50, 100)
+ * // Returns: '[50%] 50/100'
+ *
+ * createProgressIndicator(3, 10, 'Files')
+ * // Returns: 'Files: [30%] 3/10'
+ * ```
+ */
+export declare function createProgressIndicator(current: number, total: number, label?: string | undefined): string;

package/dist/stdio/progress.js

@@ -0,0 +1,217 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var progress_exports = {};
+__export(progress_exports, {
+  ProgressBar: () => ProgressBar,
+  createProgressIndicator: () => createProgressIndicator
+});
+module.exports = __toCommonJS(progress_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_yoctocolors_cjs = __toESM(require("../external/yoctocolors-cjs"));
+var import_strings = require("../strings");
+class ProgressBar {
+  current = 0;
+  total;
+  startTime;
+  lastRender = 0;
+  stream;
+  options;
+  terminated = false;
+  lastDrawnWidth = 0;
+  /**
+   * Create a new progress bar instance.
+   *
+   * @param total - Total number of units for the progress bar
+   * @param options - Configuration options for the progress bar
+   *
+   * @example
+   * ```ts
+   * const bar = new ProgressBar(100, {
+   *   width: 50,
+   *   format: ':bar :percent :current/:total :eta',
+   *   color: 'green'
+   * })
+   * ```
+   */
+  constructor(total, options) {
+    this.total = total;
+    this.startTime = Date.now();
+    this.stream = options?.stream || import_node_process.default.stderr;
+    this.options = {
+      width: 40,
+      format: ":bar :percent :current/:total",
+      complete: "\u2588",
+      incomplete: "\u2591",
+      head: "",
+      clear: false,
+      // ~60fps.
+      renderThrottle: 16,
+      stream: this.stream,
+      color: "cyan",
+      ...options
+    };
+  }
+  /**
+   * Update progress to a specific value and redraw the bar.
+   * Updates are throttled to prevent excessive rendering (default ~60fps).
+   *
+   * @param current - Current progress value (will be clamped to total)
+   * @param tokens - Optional custom tokens to replace in format string
+   *
+   * @example
+   * ```ts
+   * bar.update(50)
+   * bar.update(75, { status: 'Processing...' })
+   * ```
+   */
+  update(current, tokens) {
+    if (this.terminated) {
+      return;
+    }
+    this.current = Math.min(current, this.total);
+    const now = Date.now();
+    if (now - this.lastRender < (this.options.renderThrottle ?? 16) && this.current < this.total) {
+      return;
+    }
+    this.lastRender = now;
+    this.render(tokens);
+    if (this.current >= this.total) {
+      this.terminate();
+    }
+  }
+  /**
+   * Increment progress by a specified amount.
+   * Convenience method for `update(current + amount)`.
+   *
+   * @param amount - Amount to increment by
+   * @param tokens - Optional custom tokens to replace in format string
+   * @default amount 1
+   *
+   * @example
+   * ```ts
+   * bar.tick() // Increment by 1
+   * bar.tick(5) // Increment by 5
+   * bar.tick(1, { file: 'data.json' })
+   * ```
+   */
+  tick(amount = 1, tokens) {
+    this.update(this.current + amount, tokens);
+  }
+  /**
+   * Render the progress bar.
+   */
+  render(tokens) {
+    const colorName = this.options.color ?? "cyan";
+    const colorFn = import_yoctocolors_cjs.default[colorName] || ((s) => s);
+    const percent = this.total === 0 ? 0 : Math.floor(this.current / this.total * 100);
+    const elapsed = Date.now() - this.startTime;
+    const eta = this.current === 0 ? 0 : elapsed / this.current * (this.total - this.current);
+    const availableWidth = this.options.width ?? 40;
+    const filledWidth = this.total === 0 ? 0 : Math.min(
+      availableWidth,
+      Math.floor(this.current / this.total * availableWidth)
+    );
+    const emptyWidth = Math.max(0, availableWidth - filledWidth);
+    const filled = (0, import_strings.repeatString)(this.options.complete ?? "\u2588", filledWidth);
+    const empty = (0, import_strings.repeatString)(this.options.incomplete ?? "\u2591", emptyWidth);
+    const bar = colorFn(filled) + empty;
+    let output = this.options.format ?? ":bar :percent :current/:total";
+    output = output.replace(":bar", bar);
+    output = output.replace(":percent", `${percent}%`);
+    output = output.replace(":current", String(this.current));
+    output = output.replace(":total", String(this.total));
+    output = output.replace(":elapsed", this.formatTime(elapsed));
+    output = output.replace(":eta", this.formatTime(eta));
+    if (tokens) {
+      for (const [key, value] of Object.entries(tokens)) {
+        output = output.replace(`:${key}`, String(value));
+      }
+    }
+    this.clearLine();
+    this.stream.write(output);
+    this.lastDrawnWidth = (0, import_strings.stripAnsi)(output).length;
+  }
+  /**
+   * Clear the current line.
+   */
+  clearLine() {
+    if (this.stream.isTTY) {
+      this.stream.cursorTo(0);
+      this.stream.clearLine(0);
+    } else if (this.lastDrawnWidth > 0) {
+      this.stream.write(`\r${(0, import_strings.repeatString)(" ", this.lastDrawnWidth)}\r`);
+    }
+  }
+  /**
+   * Format time in seconds to human readable.
+   */
+  formatTime(ms) {
+    const seconds = Math.round(ms / 1e3);
+    if (seconds < 60) {
+      return `${seconds}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = seconds % 60;
+    return `${minutes}m${remainingSeconds}s`;
+  }
+  /**
+   * Terminate the progress bar and optionally clear it.
+   * Called automatically when progress reaches 100%.
+   * If `clear` option is true, removes the bar from terminal.
+   * Otherwise, moves to next line to preserve the final state.
+   */
+  terminate() {
+    if (this.terminated) {
+      return;
+    }
+    this.terminated = true;
+    if (this.options.clear) {
+      this.clearLine();
+    } else {
+      this.stream.write("\n");
+    }
+  }
+}
+function createProgressIndicator(current, total, label) {
+  const percent = total === 0 ? 0 : Math.floor(current / total * 100);
+  const progress = `${current}/${total}`;
+  let output = "";
+  if (label) {
+    output += `${label}: `;
+  }
+  output += `${import_yoctocolors_cjs.default.cyan(`[${percent}%]`)} ${progress}`;
+  return output;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ProgressBar,
+  createProgressIndicator
+});