@visulima/pail 4.0.0-alpha.8 → 4.0.0

package/dist/progress-bar.js

@@ -1,404 +0,0 @@
-const CHAR_GRADIENTS = {
-  default: ["█", "▓", "▒", "░"],
-  rect: ["▬", "▮", "▯", "▭"]
-};
-const BAR_REGEX = /\[([^[\]]*)\]/u;
-const getBarChar = (char, style, complete = true) => {
-  if (char) {
-    return char;
-  }
-  switch (style) {
-    case "ascii": {
-      return complete ? "#" : "-";
-    }
-    case "filled": {
-      return complete ? "█" : " ";
-    }
-    case "rect": {
-      return complete ? "▬" : "▭";
-    }
-    case "shades_classic": {
-      return complete ? "█" : "░";
-    }
-    case "shades_grey": {
-      return complete ? "▓" : "░";
-    }
-    case "solid": {
-      return complete ? "█" : " ";
-    }
-    default: {
-      return complete ? "█" : "░";
-    }
-  }
-};
-const applyStyleToOptions = (options) => {
-  if (!options.style) {
-    return options;
-  }
-  const { style } = options;
-  const result = { ...options };
-  if (result.barCompleteChar === void 0) {
-    result.barCompleteChar = getBarChar(void 0, style, true);
-  }
-  if (result.barIncompleteChar === void 0) {
-    result.barIncompleteChar = getBarChar(void 0, style, false);
-  }
-  if (result.barGlue === void 0) {
-    result.barGlue = "";
-  }
-  return result;
-};
-class ProgressBar {
-  options;
-  current;
-  startTime;
-  interactiveManager;
-  isActive = false;
-  payload;
-  /**
-   * Creates a new progress bar instance.
-   * @param options Configuration options for the progress bar
-   * @param interactiveManager Optional interactive manager for rendering
-   * @param payload Optional initial payload data for format placeholders
-   */
-  constructor(options, interactiveManager, payload) {
-    const isCompleteArray = Array.isArray(options.barCompleteChar);
-    const isIncompleteArray = Array.isArray(options.barIncompleteChar);
-    const isGradientMode = isCompleteArray || isIncompleteArray;
-    const completeChar = isCompleteArray ? options.barCompleteChar : getBarChar(options.barCompleteChar, "shades_classic");
-    const incompleteChar = isIncompleteArray ? options.barIncompleteChar : getBarChar(options.barIncompleteChar, "shades_classic", false);
-    this.options = {
-      barCompleteChar: completeChar,
-      barIncompleteChar: incompleteChar,
-      current: 0,
-      fps: 10,
-      width: 40,
-      ...options
-    };
-    if (isGradientMode) {
-      if (!Array.isArray(this.options.barCompleteChar)) {
-        this.options.barCompleteChar = [this.options.barCompleteChar];
-      }
-      if (!Array.isArray(this.options.barIncompleteChar)) {
-        this.options.barIncompleteChar = [this.options.barIncompleteChar];
-      }
-    }
-    this.current = this.options.current ?? 0;
-    this.startTime = Date.now();
-    this.interactiveManager = interactiveManager;
-    this.payload = payload;
-  }
-  /**
-   * Updates the progress bar to a new value.
-   * @param current The current progress value
-   * @param payload Optional payload data to merge with existing data
-   */
-  update(current, payload) {
-    this.current = Math.min(current, this.options.total);
-    if (payload) {
-      this.payload = { ...this.payload, ...payload };
-    }
-    if (this.interactiveManager && this.isActive) {
-      const progressBar = this.render();
-      this.interactiveManager.update("stdout", [progressBar]);
-    }
-  }
-  /**
-   * Increments the progress bar by a specified step.
-   * @param step Amount to increment (default: 1)
-   * @param payload Optional payload data to merge with existing data
-   */
-  increment(step = 1, payload) {
-    this.update(this.current + step, payload);
-  }
-  /**
-   * Renders the progress bar as a formatted string.
-   * @returns Formatted progress bar string with all placeholders replaced
-   */
-  // eslint-disable-next-line sonarjs/cognitive-complexity
-  render() {
-    const total = this.options.total > 0 ? this.options.total : 1;
-    const width = Math.max(0, this.options.width ?? 40);
-    const percentage = Math.max(0, Math.min(100, Math.round(this.current / total * 100)));
-    const filled = Math.max(0, Math.min(width, Math.round(this.current / total * width)));
-    const empty = width - filled;
-    let bar;
-    if (Array.isArray(this.options.barCompleteChar) || Array.isArray(this.options.barIncompleteChar)) {
-      const completeChars = Array.isArray(this.options.barCompleteChar) ? this.options.barCompleteChar : void 0;
-      const incompleteChars = Array.isArray(this.options.barIncompleteChar) ? this.options.barIncompleteChar : void 0;
-      const completeChar = completeChars?.[completeChars.length - 1] ?? (typeof this.options.barCompleteChar === "string" ? this.options.barCompleteChar : "█");
-      const incompleteChar = incompleteChars?.[0] ?? (typeof this.options.barIncompleteChar === "string" ? this.options.barIncompleteChar : "░");
-      const completeLength = completeChars?.length ?? 1;
-      const progressRatio = this.current / total;
-      const totalSteps = width * completeLength;
-      const currentStep = Math.round(progressRatio * totalSteps);
-      const fractional = currentStep % completeLength;
-      let barContent = "";
-      for (let i = 0; i < width; i += 1) {
-        if (i < filled) {
-          const isGradientBoundary = i === filled - 1 && fractional > 0 && completeChars;
-          barContent += isGradientBoundary ? completeChars[Math.max(0, fractional - 1)] : completeChar;
-        } else {
-          barContent += incompleteChar;
-        }
-      }
-      bar = barContent;
-    } else {
-      const completeChar = typeof this.options.barCompleteChar === "string" ? this.options.barCompleteChar : "█";
-      const incompleteChar = typeof this.options.barIncompleteChar === "string" ? this.options.barIncompleteChar : "░";
-      bar = completeChar.repeat(filled) + incompleteChar.repeat(empty);
-    }
-    let format = this.options.format ?? "progress [{bar}] {percentage}% | ETA: {eta}s | {value}/{total}";
-    if (this.payload) {
-      for (const [k, v] of Object.entries(this.payload)) {
-        format = format.replaceAll(`{${k}}`, String(v));
-      }
-    }
-    const eta = this.calculateETA();
-    return format.replaceAll("{bar}", bar).replaceAll("{percentage}", String(percentage)).replaceAll("{value}", String(this.current)).replaceAll("{total}", String(this.options.total)).replaceAll("{eta}", String(eta));
-  }
-  /**
-   * Starts the progress bar.
-   * @param total Optional total value to set
-   * @param startValue Optional starting value
-   * @param payload Optional initial payload data
-   */
-  start(total, startValue, payload) {
-    if (total !== void 0) {
-      this.options.total = total;
-    }
-    if (startValue !== void 0) {
-      this.current = startValue;
-    }
-    this.startTime = Date.now();
-    this.isActive = true;
-    if (this.interactiveManager) {
-      this.interactiveManager.hook();
-      this.update(this.current, payload);
-    }
-  }
-  /**
-   * Stops the progress bar and cleanup.
-   */
-  stop() {
-    this.isActive = false;
-    if (this.interactiveManager) {
-      this.interactiveManager.unhook(false);
-    }
-  }
-  calculateETA() {
-    if (this.current === 0) {
-      return 0;
-    }
-    const elapsed = (Date.now() - this.startTime) / 1e3;
-    if (elapsed < 0.1) {
-      return 0;
-    }
-    const rate = this.current / elapsed;
-    const remaining = this.options.total - this.current;
-    return Math.round(remaining / rate);
-  }
-}
-class MultiBarInstance extends ProgressBar {
-  multiBar;
-  constructor(multiBar, options, payload) {
-    super(options, void 0, payload);
-    this.multiBar = multiBar;
-  }
-  update(current, payload) {
-    super.update(current, payload);
-    this.multiBar.renderAll();
-  }
-  getBarState() {
-    const completeChar = Array.isArray(this.options.barCompleteChar) ? this.options.barCompleteChar[this.options.barCompleteChar.length - 1] : getBarChar(this.options.barCompleteChar, this.options.style ?? "shades_classic", true);
-    return {
-      char: completeChar ?? "█",
-      current: this.current,
-      total: this.options.total
-    };
-  }
-}
-class MultiProgressBar {
-  bars = /* @__PURE__ */ new Map();
-  options;
-  interactiveManager;
-  isActive = false;
-  nextBarId = 0;
-  composite = false;
-  barColors = /* @__PURE__ */ new Map();
-  /**
-   * Creates a new multi progress bar manager.
-   * @param options Configuration options for the progress bars
-   * @param interactiveManager Optional interactive manager for rendering
-   */
-  constructor(options = {}, interactiveManager) {
-    this.options = {
-      barCompleteChar: getBarChar(void 0, "shades_classic"),
-      barIncompleteChar: getBarChar(void 0, "shades_classic", false),
-      composite: false,
-      format: "progress [{bar}] {percentage}% | ETA: {eta}s | {value}/{total}",
-      fps: 10,
-      ...options
-    };
-    this.composite = this.options.composite ?? false;
-    this.interactiveManager = interactiveManager;
-  }
-  /**
-   * Creates a new progress bar within this multi-bar manager.
-   * @param total Total value for the progress bar
-   * @param current Starting current value (default: 0)
-   * @param payload Optional initial payload data for format placeholders
-   * @returns The created progress bar instance
-   */
-  create(total, current = 0, payload) {
-    const barId = `bar_${this.nextBarId++}`;
-    const bar = new MultiBarInstance(
-      this,
-      {
-        barCompleteChar: this.options.barCompleteChar,
-        barIncompleteChar: this.options.barIncompleteChar,
-        current,
-        format: this.options.format,
-        fps: this.options.fps,
-        total,
-        width: 40
-      },
-      payload
-    );
-    this.bars.set(barId, bar);
-    if (!this.isActive && this.interactiveManager) {
-      this.interactiveManager.hook();
-      this.isActive = true;
-      this.renderAll();
-    }
-    return bar;
-  }
-  /**
-   * Removes a progress bar from the manager.
-   * @param bar The progress bar instance to remove
-   * @returns True if the bar was removed, false if not found
-   */
-  remove(bar) {
-    for (const [id, existingBar] of this.bars.entries()) {
-      if (existingBar === bar) {
-        this.bars.delete(id);
-        if (this.bars.size === 0) {
-          if (this.interactiveManager) {
-            this.interactiveManager.unhook(false);
-          }
-          this.isActive = false;
-        } else {
-          this.renderAll();
-        }
-        return true;
-      }
-    }
-    return false;
-  }
-  /**
-   * Renders all progress bars.
-   */
-  renderAll() {
-    if (!this.interactiveManager || !this.isActive) {
-      return;
-    }
-    const lines = [];
-    if (this.composite) {
-      const barsArray = [...this.bars.values()];
-      if (barsArray.length > 0) {
-        const compositeOutput = this.renderComposite(barsArray);
-        lines.push(compositeOutput);
-      }
-    } else {
-      for (const bar of this.bars.values()) {
-        lines.push(bar.render());
-      }
-    }
-    this.interactiveManager.update("stdout", lines);
-  }
-  /**
-   * Sets or removes a color function for a specific bar.
-   * @param bar The progress bar instance to color (must be from this MultiProgressBar)
-   * @param color Color function or undefined to remove color
-   */
-  setBarColor(bar, color) {
-    for (const instance of this.bars.values()) {
-      if (instance === bar) {
-        if (color) {
-          this.barColors.set(instance, color);
-        } else {
-          this.barColors.delete(instance);
-        }
-        break;
-      }
-    }
-  }
-  /**
-   * Stops all progress bars and cleanup.
-   */
-  // eslint-disable-next-line sonarjs/no-identical-functions
-  stop() {
-    this.isActive = false;
-    if (this.interactiveManager) {
-      this.interactiveManager.unhook(false);
-    }
-  }
-  renderComposite(bars) {
-    if (bars.length === 0) {
-      return "";
-    }
-    const firstBar = bars[0];
-    if (!firstBar) {
-      return "";
-    }
-    const output = firstBar.render();
-    const barMatch = output.match(BAR_REGEX);
-    if (!barMatch || !barMatch[1]) {
-      return output;
-    }
-    const width = barMatch[1].length;
-    const grid = Array.from({ length: width }, () => []);
-    bars.forEach((bar, index) => {
-      const state = bar.getBarState();
-      const filled = Math.round(state.current / state.total * width);
-      for (let i = 0; i < width; i += 1) {
-        if (i < filled) {
-          grid[i]?.push(index);
-        }
-      }
-    });
-    const composite = Array.from({ length: width }, (_, i) => this.getCompositeChar(bars, grid[i])).join("");
-    return output.replace(BAR_REGEX, `[${composite}]`);
-  }
-  getCompositeChar(bars, stack) {
-    if (!stack || stack.length === 0) {
-      const defaultBar = bars[0];
-      return defaultBar?.getBarState().char ?? "█";
-    }
-    const charGradient = CHAR_GRADIENTS[this.options.style === "rect" ? "rect" : "default"];
-    const char = charGradient?.[Math.min(stack.length - 1, charGradient.length - 1)] ?? "█";
-    let selectedBar;
-    let smallestPercent = 100;
-    for (const stackBarIndex of stack) {
-      const bar = bars[stackBarIndex];
-      if (!bar) {
-        continue;
-      }
-      const barState = bar.getBarState();
-      const barPercent = barState.current / barState.total * 100;
-      if (barPercent < smallestPercent || barPercent === smallestPercent && (selectedBar === void 0 || stackBarIndex > selectedBar)) {
-        smallestPercent = barPercent;
-        selectedBar = stackBarIndex;
-      }
-    }
-    const barIndex = selectedBar ?? stack[0];
-    const targetBar = bars[barIndex ?? 0];
-    if (!targetBar) {
-      return char;
-    }
-    const barColor = this.barColors.get(targetBar);
-    return barColor ? barColor(char) : char;
-  }
-}
-
-export { MultiBarInstance, MultiProgressBar, ProgressBar, applyStyleToOptions, getBarChar };

package/dist/reporter/file/utils/rotating-file-stream.d.ts

@@ -1,48 +0,0 @@
-import type { Options as RfsOptions } from "rotating-file-stream";
-/**
- * Rotating File Stream.
- *
- * A wrapper for the `rotating-file-stream` module that provides optional immediate
- * writing to disk by creating and closing a new stream on each write operation.
- * This is useful for ensuring log messages are written immediately rather than buffered.
- * @example
- * ```typescript
- * // Buffered writing (default)
- * const bufferedStream = new RotatingFileStream("/var/log/app.log", false, {
- *   interval: "1d",
- *   size: "10M"
- * });
- *
- * // Immediate writing
- * const immediateStream = new RotatingFileStream("/var/log/app.log", true, {
- *   interval: "1d"
- * });
- * ```
- */
-declare class RotatingFileStream {
-    #private;
-    /**
-     * Creates a new RotatingFileStream instance.
-     * @param filePath Path to the log file
-     * @param writeImmediately Whether to write immediately or buffer writes
-     * @param options Options for the rotating file stream
-     * @throws {Error} If the 'rotating-file-stream' package is not installed
-     */
-    constructor(filePath: string, writeImmediately?: boolean, options?: RfsOptions);
-    /**
-     * Writes a message to the rotating file stream.
-     *
-     * If writeImmediately was set to true in the constructor, a new stream
-     * is created for each write operation. Otherwise, uses the buffered stream.
-     * @param message The message to write to the file
-     */
-    write(message: string): void;
-    /**
-     * Ends the rotating file stream.
-     *
-     * Closes the underlying stream. When `writeImmediately` is not `true`,
-     * calling `write` after calling this method will throw an error.
-     */
-    end(): void;
-}
-export default RotatingFileStream;

package/dist/reporter/http/utils/compression.d.ts

@@ -1,7 +0,0 @@
-/**
- * Compresses data using gzip compression.
- * @param data The data to compress as a string
- * @returns A Promise that resolves to the compressed data as Uint8Array
- */
-declare const compressData: (data: string) => Promise<Uint8Array>;
-export default compressData;

package/dist/reporter/http/utils/log-size-error.d.ts

@@ -1,30 +0,0 @@
-/**
- * Error thrown when a log entry exceeds the maximum allowed size.
- */
-declare class LogSizeError extends Error {
-    /**
-     * The log entry data that caused the error
-     */
-    readonly logData: Record<string, unknown>;
-    /**
-     * The actual size of the log entry in bytes
-     */
-    readonly actualSize: number;
-    /**
-     * The maximum allowed size in bytes
-     */
-    readonly maxSize: number;
-    /**
-     * Creates a new LogSizeError instance.
-     * @param message Descriptive error message explaining the size violation
-     * @param logData The log entry data that caused the error
-     * @param actualSize Size of the log entry in bytes
-     * @param maxSize Maximum allowed size in bytes
-     * @example
-     * ```typescript
-     * throw new LogSizeError("Log too large", logData, 2000000, 1000000);
-     * ```
-     */
-    constructor(message: string, logData: Record<string, unknown>, actualSize: number, maxSize: number);
-}
-export default LogSizeError;

package/dist/reporter/http/utils/retry.d.ts

@@ -1,27 +0,0 @@
-/**
- * Sends an HTTP request with retry logic and rate limiting support.
- * @param url The URL to send the request to
- * @param method The HTTP method to use
- * @param headers Request headers
- * @param body The request body (string or Uint8Array)
- * @param maxRetries Maximum number of retry attempts
- * @param retryDelay Base delay between retries in milliseconds
- * @param respectRateLimit Whether to respect rate limiting (429 responses)
- * @param onDebugRequestResponse Optional callback for debugging requests/responses
- * @param onError Optional callback for error handling
- */
-declare const sendWithRetry: (url: string, method: string, headers: Record<string, string>, body: string | Uint8Array, maxRetries: number, retryDelay: number, respectRateLimit: boolean, onDebugRequestResponse?: (requestResponse: {
-    req: {
-        body: string | Uint8Array;
-        headers: Record<string, string>;
-        method: string;
-        url: string;
-    };
-    res: {
-        body: string;
-        headers: Record<string, string>;
-        status: number;
-        statusText: string;
-    };
-}) => void, onError?: (error: Error) => void) => Promise<void>;
-export default sendWithRetry;

package/dist/reporter/json/abstract-json-reporter.d.ts

@@ -1,61 +0,0 @@
-import type { stringify } from "safe-stable-stringify";
-import type { LiteralUnion } from "type-fest";
-import type { ExtendedRfc5424LogLevels, ReadonlyMeta, StringifyAwareReporter } from "../../types.d.ts";
-/**
- * Options for configuring JSON reporters.
- */
-export type AbstractJsonReporterOptions = {
-    /** Error serialization options */
-    error: Partial<{
-        /** Properties to exclude from error serialization */
-        exclude?: string[];
-        /** Maximum depth for error object serialization */
-        maxDepth?: number;
-        /** Whether to use toJSON methods during serialization */
-        useToJSON?: boolean;
-    }>;
-};
-/**
- * Abstract JSON Reporter.
- *
- * Base class for JSON-based reporters that provides common functionality
- * for serializing log metadata to JSON format. Handles error serialization,
- * context processing, and provides a template method for actual output.
- * @template L - The log level type
- * @example
- * ```typescript
- * class CustomJsonReporter extends AbstractJsonReporter {
- *   protected _log(message: string): void {
- *     console.log(message);
- *   }
- * }
- * ```
- */
-export declare abstract class AbstractJsonReporter<L extends string = string> implements StringifyAwareReporter<L> {
-    /** Custom stringify function for object serialization */
-    protected stringify: typeof stringify | undefined;
-    /** Error serialization options */
-    protected errorOptions: AbstractJsonReporterOptions["error"];
-    /**
-     * Creates a new AbstractJsonReporter instance.
-     * @param options Configuration options for JSON formatting and error handling
-     */
-    constructor(options?: Partial<AbstractJsonReporterOptions>);
-    /**
-     * Sets a custom stringify function for object serialization.
-     * @param function_ The stringify function to use for serialization
-     */
-    setStringify(function_: any): void;
-    log(meta: ReadonlyMeta<L>): void;
-    /**
-     * Template method for outputting the JSON log message.
-     *
-     * Subclasses must implement this method to define how the JSON message
-     * is actually written (to console, file, network, etc.).
-     * @param message The JSON-formatted log message
-     * @param logLevel The log level of the message
-     * @protected
-     * @abstract
-     */
-    protected abstract _log(message: string, logLevel: LiteralUnion<ExtendedRfc5424LogLevels, L>): void;
-}

package/dist/reporter/json/json-reporter.browser.d.ts

@@ -1,40 +0,0 @@
-import type { LiteralUnion } from "type-fest";
-import type { ExtendedRfc5424LogLevels } from "../../types.d.ts";
-import type { AbstractJsonReporterOptions } from "./abstract-json-reporter.d.ts";
-import { AbstractJsonReporter } from "./abstract-json-reporter.d.ts";
-/**
- * Browser JSON Reporter.
- *
- * A JSON reporter for browser environments that outputs structured log data
- * to the browser console. Uses appropriate console methods based on log level.
- * @template L - The log level type
- * @example
- * ```typescript
- * import { createPail } from "@visulima/pail";
- *
- * const logger = createPail({
- *   reporters: [new JsonReporter()]
- * });
- *
- * logger.info("Application started", { version: "1.0.0" });
- * // Outputs: {"level":"info","message":"Application started","context":[{"version":"1.0.0"}],...}
- * ```
- */
-declare class JsonReporter<L extends string = string> extends AbstractJsonReporter<L> {
-    /**
-     * Creates a new Browser JSON Reporter instance.
-     * @param options Configuration options for JSON formatting
-     */
-    constructor(options?: Partial<AbstractJsonReporterOptions>);
-    /**
-     * Outputs the JSON message to the browser console.
-     *
-     * Uses the appropriate console method based on the log level
-     * (console.log, console.error, console.warn, etc.).
-     * @param message The JSON-formatted log message
-     * @param logLevel The log level determining which console method to use
-     * @protected
-     */
-    protected _log(message: string, logLevel: LiteralUnion<ExtendedRfc5424LogLevels, L>): void;
-}
-export default JsonReporter;

package/dist/reporter/json/json-reporter.server.d.ts

@@ -1,50 +0,0 @@
-import type { LiteralUnion } from "type-fest";
-import type { ExtendedRfc5424LogLevels, StreamAwareReporter } from "../../types.d.ts";
-import type { AbstractJsonReporterOptions } from "./abstract-json-reporter.d.ts";
-import { AbstractJsonReporter } from "./abstract-json-reporter.d.ts";
-/**
- * Server JSON Reporter.
- *
- * A JSON reporter for Node.js server environments that outputs structured log data
- * to stdout/stderr streams. Routes error-level logs to stderr and others to stdout.
- * @template L - The log level type
- * @example
- * ```typescript
- * import { createPail } from "@visulima/pail";
- *
- * const logger = createPail({
- *   reporters: [new JsonReporter()]
- * });
- *
- * logger.info("Server started", { port: 3000 });
- * logger.error("Database connection failed", error);
- * ```
- */
-declare class JsonReporter<L extends string = string> extends AbstractJsonReporter<L> implements StreamAwareReporter<L> {
-    #private;
-    /**
-     * Creates a new Server JSON Reporter instance.
-     * @param options Configuration options for JSON formatting
-     */
-    constructor(options?: Partial<AbstractJsonReporterOptions>);
-    /**
-     * Sets the stdout stream for the reporter.
-     * @param stdout_ The writable stream to use for stdout output
-     */
-    setStdout(stdout_: NodeJS.WriteStream): void;
-    /**
-     * Sets the stderr stream for the reporter.
-     * @param stderr_ The writable stream to use for stderr output
-     */
-    setStderr(stderr_: NodeJS.WriteStream): void;
-    /**
-     * Outputs the JSON message to the appropriate stream.
-     *
-     * Routes error and warning level messages to stderr, others to stdout.
-     * @param message The JSON-formatted log message
-     * @param logLevel The log level determining which stream to use
-     * @protected
-     */
-    protected _log(message: string, logLevel: LiteralUnion<ExtendedRfc5424LogLevels, L>): void;
-}
-export default JsonReporter;