@visulima/pail 3.2.2 → 4.0.0-alpha.10

package/dist/processor/redact-processor.d.ts

@@ -4,7 +4,7 @@ import type { Meta, Processor } from "../types.d.ts";
  * Redact Processor.
  *
  * A processor that redacts sensitive information from log messages and metadata.
- * Uses the {@link https://www.visulima.com/docs/package/redact|@visulima/redact} library to identify and mask sensitive data like
+ * Uses the {@link https://visulima.com/packages/redact/|@visulima/redact} library to identify and mask sensitive data like
  * passwords, API keys, credit card numbers, and other PII.
  * @template L - The log level type
  * @example

package/dist/processor/redact-processor.js

@@ -9,7 +9,8 @@ class RedactProcessor {
    * @param options Additional redaction options
    */
   constructor(rules, options) {
-    this.#redact = (input) => redact(input, rules || standardRules, options);
+    const effectiveRules = rules ?? standardRules;
+    this.#redact = (input) => redact(input, effectiveRules, options);
   }
   /**
    * Processes log metadata to redact sensitive information.

package/dist/processor/sampling-processor.d.ts

@@ -0,0 +1,111 @@
+import type { Meta, Processor } from "../types.d.ts";
+/**
+ * Head sampling configuration.
+ *
+ * Controls random sampling rates per log level. Each key is a log level name
+ * and the value is the percentage (0-100) of logs at that level to keep.
+ * Levels not listed default to 100 (keep all).
+ * @example
+ * ```typescript
+ * const headSampling: HeadSamplingConfig = {
+ *   debug: 0,      // Drop all debug logs
+ *   informational: 10,  // Keep 10% of info logs
+ *   warning: 50,   // Keep 50% of warning logs
+ *   error: 100,    // Keep all error logs
+ * };
+ * ```
+ */
+type HeadSamplingConfig = Partial<Record<string, number>>;
+/**
+ * Tail sampling condition function.
+ *
+ * A function that receives the log metadata and returns true if the log
+ * should be force-kept regardless of head sampling. This allows keeping
+ * important logs based on their content (e.g., errors, slow operations).
+ * @template L - The log level type
+ */
+type TailSamplingCondition<L extends string = string> = (meta: Readonly<Meta<L>>) => boolean;
+/**
+ * Sampling processor configuration options.
+ */
+interface SamplingProcessorOptions<L extends string = string> {
+    /**
+     * Head sampling rates per log level.
+     *
+     * A map of log level to sampling percentage (0-100).
+     * Levels not specified default to 100 (keep all).
+     * Set to 0 to drop all logs at that level.
+     */
+    head?: HeadSamplingConfig;
+    /**
+     * Tail sampling conditions.
+     *
+     * An array of condition functions that can force-keep a log entry
+     * even if it was dropped by head sampling. If any condition returns true,
+     * the log is kept.
+     */
+    tail?: TailSamplingCondition<L>[];
+}
+/**
+ * Sampling Processor.
+ *
+ * Inspired by evlog's production sampling strategy, this processor implements
+ * both head sampling (random per-level) and tail sampling (force-keep based
+ * on conditions) to control log volume in production environments.
+ *
+ * **Head sampling** randomly drops a percentage of logs per level. This is
+ * evaluated first and provides broad volume control.
+ *
+ * **Tail sampling** can override head sampling to force-keep important logs
+ * based on their content. For example, you might drop 90% of info logs but
+ * force-keep any that contain error information or relate to slow operations.
+ *
+ * When a log is dropped by sampling, the processor sets a `__dropped: true`
+ * boolean flag on the meta object. Reporters should check for this flag and
+ * skip entries where `__dropped` is `true`.
+ * @template L - The log level type
+ * @example
+ * ```typescript
+ * import { createPail } from "@visulima/pail";
+ * import SamplingProcessor from "@visulima/pail/processor/sampling";
+ *
+ * const logger = createPail({
+ *   processors: [
+ *     new SamplingProcessor({
+ *       head: {
+ *         debug: 0,         // Drop all debug logs
+ *         informational: 10, // Keep 10% of info logs
+ *         warning: 50,      // Keep 50% of warnings
+ *         error: 100,       // Keep all errors
+ *       },
+ *       tail: [
+ *         // Force-keep logs with errors regardless of head sampling
+ *         (meta) => meta.error !== undefined,
+ *         // Force-keep logs from critical scopes
+ *         (meta) => meta.scope?.includes("payment") ?? false,
+ *       ],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare class SamplingProcessor<L extends string = string> implements Processor<L> {
+    #private;
+    /**
+     * Creates a new SamplingProcessor instance.
+     * @param options Sampling configuration options
+     */
+    constructor(options?: SamplingProcessorOptions<L>);
+    /**
+     * Processes log metadata to apply sampling rules.
+     *
+     * First evaluates head sampling (random per-level), then checks tail
+     * sampling conditions. If a log is dropped, the meta is marked with
+     * `__dropped: true` so reporters can skip it.
+     * @param meta The log metadata to process
+     * @returns The processed metadata, potentially marked as dropped
+     */
+    process(meta: Meta<L>): Meta<L>;
+}
+export default SamplingProcessor;
+export type { HeadSamplingConfig, SamplingProcessorOptions, TailSamplingCondition };

package/dist/processor/sampling-processor.js

@@ -0,0 +1,59 @@
+class SamplingProcessor {
+  #headRates;
+  #tailConditions;
+  /**
+   * Creates a new SamplingProcessor instance.
+   * @param options Sampling configuration options
+   */
+  constructor(options = {}) {
+    this.#headRates = options.head ?? {};
+    this.#tailConditions = options.tail ?? [];
+  }
+  /**
+   * Processes log metadata to apply sampling rules.
+   *
+   * First evaluates head sampling (random per-level), then checks tail
+   * sampling conditions. If a log is dropped, the meta is marked with
+   * `__dropped: true` so reporters can skip it.
+   * @param meta The log metadata to process
+   * @returns The processed metadata, potentially marked as dropped
+   */
+  process(meta) {
+    const level = meta.type.level;
+    if (this.#shouldDrop(level) && !this.#shouldForceKeep(meta)) {
+      return { ...meta, dropped: true };
+    }
+    return meta;
+  }
+  /**
+   * Evaluates head sampling for the given log level.
+   * @returns true if the log should be dropped
+   */
+  #shouldDrop(level) {
+    const rate = this.#headRates[level];
+    if (rate === void 0) {
+      return false;
+    }
+    if (rate <= 0) {
+      return true;
+    }
+    if (rate >= 100) {
+      return false;
+    }
+    return Math.random() * 100 >= rate;
+  }
+  /**
+   * Evaluates tail sampling conditions.
+   * @returns true if any condition forces keeping the log
+   */
+  #shouldForceKeep(meta) {
+    for (let i = 0; i < this.#tailConditions.length; i += 1) {
+      if (this.#tailConditions[i](meta)) {
+        return true;
+      }
+    }
+    return false;
+  }
+}
+
+export { SamplingProcessor as default };

package/dist/progress-bar.d.ts

@@ -1,5 +1,5 @@
 import type InteractiveManager from "./interactive/interactive-manager.d.ts";
-export type ProgressBarStyle = "shades_classic" | "shades_grey" | "rect" | "filled" | "solid" | "ascii" | "custom";
+export type ProgressBarStyle = "shades_classic" | "shades_grey" | "rect" | "filled" | "solid" | "ascii" | "braille" | "custom";
 export interface ProgressBarOptions {
     barCompleteChar?: string | string[];
     barGlue?: string;
@@ -7,6 +7,9 @@ export interface ProgressBarOptions {
     current?: number;
     format?: string;
     fps?: number;
+    peak?: number;
+    peakChar?: string;
+    roundedCaps?: boolean;
     style?: ProgressBarStyle;
     total: number;
     width?: number;
@@ -55,6 +58,11 @@ export declare class ProgressBar {
      * @param payload Optional payload data to merge with existing data
      */
     update(current: number, payload?: ProgressBarPayload): void;
+    /**
+     * Sets the peak marker position.
+     * @param peak The peak value (in the same scale as total)
+     */
+    setPeak(peak: number): void;
     /**
      * Increments the progress bar by a specified step.
      * @param step Amount to increment (default: 1)
@@ -77,6 +85,7 @@ export declare class ProgressBar {
      * Stops the progress bar and cleanup.
      */
     stop(): void;
+    private calculatePeakPosition;
     private calculateETA;
 }
 export declare class MultiBarInstance extends ProgressBar {

package/dist/progress-bar.js

@@ -1,7 +1,12 @@
 const CHAR_GRADIENTS = {
+  braille: ["⣿", "⡷", "⢾", "⠤"],
   default: ["█", "▓", "▒", "░"],
   rect: ["▬", "▮", "▯", "▭"]
 };
+const BRAILLE_FULL = "⣿";
+const BRAILLE_CAP_LEFT = "⢾";
+const BRAILLE_CAP_RIGHT = "⡷";
+const BRAILLE_EMPTY = "⠤";
 const BAR_REGEX = /\[([^[\]]*)\]/u;
 const getBarChar = (char, style, complete = true) => {
   if (char) {
@@ -11,6 +16,9 @@ const getBarChar = (char, style, complete = true) => {
     case "ascii": {
       return complete ? "#" : "-";
     }
+    case "braille": {
+      return complete ? BRAILLE_FULL : BRAILLE_EMPTY;
+    }
     case "filled": {
       return complete ? "█" : " ";
     }
@@ -37,15 +45,9 @@ const applyStyleToOptions = (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 = "";
-  }
+  result.barCompleteChar ??= getBarChar(void 0, style, true);
+  result.barIncompleteChar ??= getBarChar(void 0, style, false);
+  result.barGlue ??= "";
   return result;
 };
 class ProgressBar {
@@ -65,8 +67,9 @@ class ProgressBar {
     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);
+    const effectiveStyle = options.style ?? "shades_classic";
+    const completeChar = isCompleteArray ? options.barCompleteChar : getBarChar(options.barCompleteChar, effectiveStyle);
+    const incompleteChar = isIncompleteArray ? options.barIncompleteChar : getBarChar(options.barIncompleteChar, effectiveStyle, false);
     this.options = {
       barCompleteChar: completeChar,
       barIncompleteChar: incompleteChar,
@@ -103,6 +106,13 @@ class ProgressBar {
       this.interactiveManager.update("stdout", [progressBar]);
     }
   }
+  /**
+   * Sets the peak marker position.
+   * @param peak The peak value (in the same scale as total)
+   */
+  setPeak(peak) {
+    this.options.peak = peak;
+  }
   /**
    * Increments the progress bar by a specified step.
    * @param step Amount to increment (default: 1)
@@ -123,6 +133,7 @@ class ProgressBar {
     const filled = Math.max(0, Math.min(width, Math.round(this.current / total * width)));
     const empty = width - filled;
     let bar;
+    const useCaps = this.options.roundedCaps === true || this.options.roundedCaps === void 0 && this.options.style === "braille";
     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;
@@ -137,7 +148,7 @@ class ProgressBar {
       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;
+          barContent += isGradientBoundary ? completeChars[Math.max(0, fractional - 1)] ?? completeChar : completeChar;
         } else {
           barContent += incompleteChar;
         }
@@ -146,11 +157,35 @@ class ProgressBar {
     } 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);
+      const peakPos = this.calculatePeakPosition(width, total, filled);
+      const peakChar = this.options.peakChar ?? completeChar;
+      if (peakPos === void 0) {
+        bar = completeChar.repeat(filled) + incompleteChar.repeat(empty);
+      } else {
+        let barContent = "";
+        for (let i = 0; i < width; i += 1) {
+          if (i === peakPos) {
+            barContent += peakChar;
+          } else if (i < filled) {
+            barContent += completeChar;
+          } else {
+            barContent += incompleteChar;
+          }
+        }
+        bar = barContent;
+      }
+    }
+    if (useCaps && width >= 2) {
+      const chars = [...bar];
+      chars[0] = BRAILLE_CAP_LEFT;
+      chars[chars.length - 1] = BRAILLE_CAP_RIGHT;
+      bar = chars.join("");
     }
     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)) {
+      const entries = Object.entries(this.payload);
+      for (let i = 0; i < entries.length; i += 1) {
+        const [k, v] = entries[i];
         format = format.replaceAll(`{${k}}`, String(v));
       }
     }
@@ -186,6 +221,17 @@ class ProgressBar {
       this.interactiveManager.unhook(false);
     }
   }
+  calculatePeakPosition(width, total, filled) {
+    const { peak } = this.options;
+    if (peak === void 0 || peak <= 0) {
+      return void 0;
+    }
+    let peakPos = Math.max(0, Math.min(width - 1, Math.floor(peak / total * width)));
+    if (peakPos < filled - 1) {
+      peakPos = filled - 1;
+    }
+    return peakPos;
+  }
   calculateETA() {
     if (this.current === 0) {
       return 0;
@@ -210,7 +256,7 @@ class MultiBarInstance extends ProgressBar {
     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);
+    const completeChar = Array.isArray(this.options.barCompleteChar) ? this.options.barCompleteChar.at(-1) : getBarChar(this.options.barCompleteChar, this.options.style ?? "shades_classic", true);
     return {
       char: completeChar ?? "█",
       current: this.current,
@@ -251,7 +297,7 @@ class MultiProgressBar {
    * @returns The created progress bar instance
    */
   create(total, current = 0, payload) {
-    const barId = `bar_${this.nextBarId++}`;
+    const barId = `bar_${String(this.nextBarId++)}`;
     const bar = new MultiBarInstance(
       this,
       {
@@ -352,8 +398,8 @@ class MultiProgressBar {
       return "";
     }
     const output = firstBar.render();
-    const barMatch = output.match(BAR_REGEX);
-    if (!barMatch || !barMatch[1]) {
+    const barMatch = BAR_REGEX.exec(output);
+    if (!barMatch?.[1]) {
       return output;
     }
     const width = barMatch[1].length;
@@ -375,11 +421,20 @@ class MultiProgressBar {
       const defaultBar = bars[0];
       return defaultBar?.getBarState().char ?? "█";
     }
-    const charGradient = CHAR_GRADIENTS[this.options.style === "rect" ? "rect" : "default"];
+    let gradientKey;
+    if (this.options.style === "rect") {
+      gradientKey = "rect";
+    } else if (this.options.style === "braille") {
+      gradientKey = "braille";
+    } else {
+      gradientKey = "default";
+    }
+    const charGradient = CHAR_GRADIENTS[gradientKey];
     const char = charGradient?.[Math.min(stack.length - 1, charGradient.length - 1)] ?? "█";
     let selectedBar;
     let smallestPercent = 100;
-    for (const stackBarIndex of stack) {
+    for (let j = 0; j < stack.length; j += 1) {
+      const stackBarIndex = stack[j];
       const bar = bars[stackBarIndex];
       if (!bar) {
         continue;

package/dist/reporter/file/json-file-reporter.js

@@ -1,4 +1,4 @@
-import { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-intFdT_A.js';
+import { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-CjtVgHbU.js';
 
 class SafeStreamHandler {
   #ready = true;

package/dist/reporter/http/abstract-http-reporter.js

@@ -20,7 +20,7 @@ const __cjs_getBuiltinModule = (module) => {
 const {
   Buffer
 } = __cjs_getBuiltinModule("node:buffer");
-import { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-intFdT_A.js';
+import { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-CjtVgHbU.js';
 const {
   gzipSync
 } = __cjs_getBuiltinModule("node:zlib");
@@ -33,24 +33,25 @@ const compressData = async (data) => {
     const reader = stream.readable.getReader();
     const encoder = new TextEncoder();
     const chunks = [];
-    writer.write(encoder.encode(data));
-    writer.close();
+    await writer.write(encoder.encode(data));
+    await writer.close();
     let done = false;
     while (!done) {
-      const result2 = await reader.read();
-      done = result2.done ?? false;
-      if (result2.value) {
-        chunks.push(result2.value);
+      const result = await reader.read();
+      done = result.done;
+      if (result.value) {
+        chunks.push(result.value);
       }
     }
     const totalLength = chunks.reduce((accumulator, chunk) => accumulator + chunk.length, 0);
-    const result = new Uint8Array(totalLength);
+    const resultBuffer = new Uint8Array(totalLength);
     let offset = 0;
-    for (const chunk of chunks) {
-      result.set(chunk, offset);
+    for (let i = 0; i < chunks.length; i += 1) {
+      const chunk = chunks[i];
+      resultBuffer.set(chunk, offset);
       offset += chunk.length;
     }
-    return result;
+    return resultBuffer;
   }
   return gzipSync(data);
 };
@@ -125,7 +126,7 @@ const processResponse = async (response, url, method, headers, body, onDebugRequ
     return false;
   }
   if (response.status < 500 && response.status !== 429) {
-    const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
+    const error = new Error(`HTTP ${String(response.status)}: ${response.statusText}`);
     if (onError) {
       onError(error);
     }
@@ -185,7 +186,7 @@ const sendWithRetry = async (url, method, headers, body, maxRetries, retryDelay,
         continue;
       }
       if (!response.ok) {
-        const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
+        const error = new Error(`HTTP ${String(response.status)}: ${response.statusText}`);
         if (onError) {
           onError(error);
         }
@@ -298,7 +299,7 @@ class AbstractHttpReporter extends AbstractJsonReporter {
       const logEntrySize = this.edgeCompat || typeof TextEncoder === "undefined" ? Buffer.byteLength(payload, "utf8") : new TextEncoder().encode(payload).length;
       if (logEntrySize > this.maxLogSize) {
         const error = new LogSizeError(
-          `Log entry exceeds maximum size of ${this.maxLogSize} bytes. Size: ${logEntrySize} bytes`,
+          `Log entry exceeds maximum size of ${String(this.maxLogSize)} bytes. Size: ${String(logEntrySize)} bytes`,
           { data: payloadTemplate.data, logLevel: logLevelString, message: messageString },
           logEntrySize,
           this.maxLogSize
@@ -330,17 +331,15 @@ class AbstractHttpReporter extends AbstractJsonReporter {
     const payloadSizeWithEntry = this.currentBatchSize + logEntrySize + this.batchSendDelimiter.length;
     const payloadSizeThreshold = this.maxPayloadSize * 0.9;
     if (payloadSizeWithEntry > payloadSizeThreshold && this.batchQueue.length > 0) {
-      this.processBatch();
+      void this.processBatch();
     }
     this.batchQueue.push(payload);
     this.currentBatchSize += logEntrySize + this.batchSendDelimiter.length;
-    if (!this.batchTimeout) {
-      this.batchTimeout = setTimeout(() => {
-        this.processBatch();
-      }, this.batchSendTimeout);
-    }
+    this.batchTimeout ??= setTimeout(() => {
+      void this.processBatch();
+    }, this.batchSendTimeout);
     if (this.batchQueue.length >= this.batchSize) {
-      this.processBatch();
+      void this.processBatch();
     }
   }
   /**
@@ -371,7 +370,7 @@ class AbstractHttpReporter extends AbstractJsonReporter {
     } finally {
       this.isProcessingBatch = false;
       if (this.batchQueue.length > 0) {
-        this.processBatch();
+        void this.processBatch();
       }
     }
   }
@@ -404,9 +403,7 @@ class AbstractHttpReporter extends AbstractJsonReporter {
    */
   async sendPayload(payload, contentType) {
     const headers = typeof this.headers === "function" ? this.headers() : { ...this.headers };
-    if (!headers["content-type"]) {
-      headers["content-type"] = contentType ?? this.contentType;
-    }
+    headers["content-type"] ??= contentType ?? this.contentType;
     let finalPayload = payload;
     if (this.compression && !this.edgeCompat) {
       try {
@@ -414,7 +411,7 @@ class AbstractHttpReporter extends AbstractJsonReporter {
         headers["content-encoding"] = "gzip";
       } catch (error) {
         if (this.onError) {
-          this.onError(new Error(`Compression failed: ${error}`));
+          this.onError(new Error(`Compression failed: ${String(error)}`));
         }
       }
     }