@visulima/pail 4.0.0-alpha.2 → 4.0.0-alpha.21

package/dist/processor/opentelemetry-processor.js

@@ -1,52 +1 @@
-import { trace, context, isSpanContextValid } from '@opentelemetry/api';
-
-class OpenTelemetryProcessor {
-  /** Field name for trace ID */
-  #traceIdField;
-  /** Field name for span ID */
-  #spanIdField;
-  /** Field name for trace flags */
-  #traceFlagsField;
-  /** Optional field name to nest all trace fields under */
-  #traceFieldName;
-  /**
-   * Creates a new OpenTelemetryProcessor instance.
-   * @param options Configuration options for field names and nesting
-   */
-  constructor(options = {}) {
-    this.#traceIdField = options.traceIdFieldName || "trace_id";
-    this.#spanIdField = options.spanIdFieldName || "span_id";
-    this.#traceFlagsField = options.traceFlagsFieldName || "trace_flags";
-    this.#traceFieldName = options.traceFieldName;
-  }
-  /**
-   * Processes log metadata to add OpenTelemetry trace context.
-   *
-   * Extracts trace information from the active OpenTelemetry span and adds it
-   * to the log context. If no valid span is found, the metadata is returned unchanged.
-   * @param meta The log metadata to process
-   * @returns The processed metadata with trace context added
-   */
-  process(meta) {
-    const span = trace.getSpan(context.active());
-    if (!span) {
-      return meta;
-    }
-    const spanContext = span.spanContext();
-    if (!isSpanContextValid(spanContext)) {
-      return meta;
-    }
-    const fields = {
-      [this.#spanIdField]: spanContext.spanId,
-      [this.#traceFlagsField]: `0${spanContext.traceFlags.toString(16)}`,
-      [this.#traceIdField]: spanContext.traceId
-    };
-    const traceData = this.#traceFieldName ? {
-      [this.#traceFieldName]: fields
-    } : fields;
-    meta.context = [...meta.context || [], traceData];
-    return meta;
-  }
-}
-
-export { OpenTelemetryProcessor };
+import{trace as i,context as c,isSpanContextValid as n}from"@opentelemetry/api";class l{#s;#e;#r;#t;constructor(t={}){this.#s=t.traceIdFieldName??"trace_id",this.#e=t.spanIdFieldName??"span_id",this.#r=t.traceFlagsFieldName??"trace_flags",this.#t=t.traceFieldName}process(t){const e=i.getSpan(c.active());if(!e)return t;const s=e.spanContext();if(!n(s))return t;const r={[this.#e]:s.spanId,[this.#r]:`0${s.traceFlags.toString(16)}`,[this.#s]:s.traceId},a=this.#t?{[this.#t]:r}:r;return t.context=[...t.context??[],a],t}}export{l as OpenTelemetryProcessor};

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

@@ -1,44 +1,63 @@
-import type { RedactOptions, Rules } from "@visulima/redact";
-import type { Meta, Processor } from "../types.d.ts";
+import { M as Meta, P as Processor } from "../packem_shared/types.d-Ck_RSjLg.js";
+import '@visulima/colorize';
+import '@visulima/interactive-manager';
+type StringAnonymize = {
+  key: string;
+  pattern: RegExp | string;
+  replacement?: string;
+};
+type Anonymize = {
+  deep?: boolean;
+  key: string;
+  pattern?: RegExp | string;
+  replacement?: unknown;
+};
+type Rules = (Anonymize | StringAnonymize | number | string)[];
+type RedactOptions = {
+  exclude?: (number | string)[];
+  logger?: {
+    debug: (message?: unknown, ...optionalParameters: unknown[]) => void;
+  };
+};
 /**
- * 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
- * passwords, API keys, credit card numbers, and other PII.
- * @template L - The log level type
- * @example
- * ```typescript
- * import { createPail } from "@visulima/pail";
- * import RedactProcessor from "@visulima/pail/processor/redact";
- *
- * const logger = createPail({
- *   processors: [new RedactProcessor()]
- * });
- *
- * logger.info("User login", {
- *   username: "john",
- *   password: "secret123",  // Will be redacted
- *   apiKey: "sk-123456"    // Will be redacted
- * });
- * ```
- */
+* Redact Processor.
+*
+* A processor that redacts sensitive information from log messages and metadata.
+* 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
+* ```typescript
+* import { createPail } from "@visulima/pail";
+* import RedactProcessor from "@visulima/pail/processor/redact";
+*
+* const logger = createPail({
+*   processors: [new RedactProcessor()]
+* });
+*
+* logger.info("User login", {
+*   username: "john",
+*   password: "secret123",  // Will be redacted
+*   apiKey: "sk-123456"    // Will be redacted
+* });
+* ```
+*/
 declare class RedactProcessor<L extends string = string> implements Processor<L> {
-    #private;
-    /**
-     * Creates a new RedactProcessor instance.
-     * @param rules Custom redaction rules (uses standardRules if not provided)
-     * @param options Additional redaction options
-     */
-    constructor(rules?: Rules, options?: RedactOptions);
-    /**
-     * Processes log metadata to redact sensitive information.
-     *
-     * Applies redaction rules to the message, context, and error properties
-     * in the log metadata to prevent sensitive data from being logged.
-     * @param meta The log metadata to process
-     * @returns The processed metadata with sensitive data redacted
-     */
-    process(meta: Meta<L>): Meta<L>;
+  #private;
+  /**
+  * Creates a new RedactProcessor instance.
+  * @param rules Custom redaction rules (uses standardRules if not provided)
+  * @param options Additional redaction options
+  */
+  constructor(rules?: Rules, options?: RedactOptions);
+  /**
+  * Processes log metadata to redact sensitive information.
+  *
+  * Applies redaction rules to the message, context, and error properties
+  * in the log metadata to prevent sensitive data from being logged.
+  * @param meta The log metadata to process
+  * @returns The processed metadata with sensitive data redacted
+  */
+  process(meta: Meta<L>): Meta<L>;
 }
-export default RedactProcessor;
+export { RedactProcessor as default };

package/dist/processor/redact-processor.js

@@ -1,30 +1 @@
-import { redact, standardRules } from '@visulima/redact';
-
-class RedactProcessor {
-  /** The redact function configured with custom rules and options */
-  #redact;
-  /**
-   * Creates a new RedactProcessor instance.
-   * @param rules Custom redaction rules (uses standardRules if not provided)
-   * @param options Additional redaction options
-   */
-  constructor(rules, options) {
-    this.#redact = (input) => redact(input, rules || standardRules, options);
-  }
-  /**
-   * Processes log metadata to redact sensitive information.
-   *
-   * Applies redaction rules to the message, context, and error properties
-   * in the log metadata to prevent sensitive data from being logged.
-   * @param meta The log metadata to process
-   * @returns The processed metadata with sensitive data redacted
-   */
-  process(meta) {
-    meta.message = this.#redact(meta.message);
-    meta.context = this.#redact(meta.context);
-    meta.error = this.#redact(meta.error);
-    return meta;
-  }
-}
-
-export { RedactProcessor as default };
+import{redact as e,standardRules as a}from"@visulima/redact";class n{#t;constructor(t,s){const r=t??a;this.#t=o=>e(o,r,s)}process(t){return t.message=this.#t(t.message),t.context=this.#t(t.context),t.error=this.#t(t.error),t}}export{n as default};

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

@@ -0,0 +1,112 @@
+import { M as Meta, P as Processor } from "../packem_shared/types.d-Ck_RSjLg.js";
+import '@visulima/colorize';
+import '@visulima/interactive-manager';
+/**
+* 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 { type HeadSamplingConfig, type SamplingProcessorOptions, type TailSamplingCondition, SamplingProcessor as default };

package/dist/processor/sampling-processor.js

@@ -0,0 +1 @@
+class e{#r;#t;constructor(t={}){this.#r=t.head??{},this.#t=t.tail??[]}process(t){const r=t.type.level;return this.#s(r)&&!this.#e(t)?{...t,dropped:!0}:t}#s(t){const r=this.#r[t];return r===void 0?!1:r<=0?!0:r>=100?!1:Math.random()*100>=r}#e(t){for(let r=0;r<this.#t.length;r+=1)if(this.#t[r](t))return!0;return!1}}export{e as default};

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

@@ -1,46 +1,95 @@
-import type { Options as RfsOptions } from "rotating-file-stream";
-import type { AbstractJsonReporterOptions } from "../json/abstract-json-reporter.d.ts";
-import { AbstractJsonReporter } from "../json/abstract-json-reporter.d.ts";
-import RotatingFileStream from "./utils/rotating-file-stream.d.ts";
+import { Options } from 'rotating-file-stream';
+import { A as AbstractJsonReporterOptions, a as AbstractJsonReporter } from "../../packem_shared/abstract-json-reporter.d-Boj5w068.js";
+import 'safe-stable-stringify';
+import "../../packem_shared/types.d-Ck_RSjLg.js";
+import '@visulima/colorize';
+import '@visulima/interactive-manager';
 /**
- * Options for configuring the JsonFileReporter.
- */
-export type FileReporterOptions = AbstractJsonReporterOptions & RfsOptions & {
-    /** Path to the log file */
-    filePath: string;
-    /** Whether to write immediately to disk instead of buffering */
-    writeImmediately?: boolean;
+* 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?: Options);
+  /**
+  * 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;
+}
+/**
+* Options for configuring the JsonFileReporter.
+*/
+type FileReporterOptions = AbstractJsonReporterOptions & Options & {
+  /** Path to the log file */
+  filePath: string;
+  /** Whether to write immediately to disk instead of buffering */
+  writeImmediately?: boolean;
 };
 /**
- * JSON File Reporter.
- *
- * A reporter that writes structured JSON log entries to rotating files on disk.
- * Supports automatic file rotation based on size, time intervals, and compression.
- * @template L - The log level type
- * @example
- * ```typescript
- * const reporter = new JsonFileReporter({
- *   filePath: "/var/log/app.log",
- *   interval: "1d", // Rotate daily
- *   size: "10M",   // Rotate when file reaches 10MB
- *   compress: "gzip"
- * });
- *
- * logger.registerReporters([reporter]);
- * ```
- */
-export declare class JsonFileReporter<L extends string = string> extends AbstractJsonReporter<L> {
-    /** The rotating file stream instance */
-    protected stream: RotatingFileStream;
-    /**
-     * Creates a new JsonFileReporter instance.
-     * @param options Configuration options for file rotation and JSON formatting
-     */
-    constructor(options: FileReporterOptions);
-    /**
-     * Writes a JSON message to the rotating file stream.
-     * @param message The JSON-formatted log message to write
-     * @protected
-     */
-    protected _log(message: string): void;
+* JSON File Reporter.
+*
+* A reporter that writes structured JSON log entries to rotating files on disk.
+* Supports automatic file rotation based on size, time intervals, and compression.
+* @template L - The log level type
+* @example
+* ```typescript
+* const reporter = new JsonFileReporter({
+*   filePath: "/var/log/app.log",
+*   interval: "1d", // Rotate daily
+*   size: "10M",   // Rotate when file reaches 10MB
+*   compress: "gzip"
+* });
+*
+* logger.registerReporters([reporter]);
+* ```
+*/
+declare class JsonFileReporter<L extends string = string> extends AbstractJsonReporter<L> {
+  /** The rotating file stream instance */
+  protected stream: RotatingFileStream;
+  /**
+  * Creates a new JsonFileReporter instance.
+  * @param options Configuration options for file rotation and JSON formatting
+  */
+  constructor(options: FileReporterOptions);
+  /**
+  * Writes a JSON message to the rotating file stream.
+  * @param message The JSON-formatted log message to write
+  * @protected
+  */
+  protected override _log(message: string): void;
 }
+export { FileReporterOptions, JsonFileReporter };

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

@@ -1,136 +1,2 @@
-import { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-BaZ33PlE.js';
-
-class SafeStreamHandler {
-  #ready = true;
-  #stream;
-  #name;
-  constructor(stream, name) {
-    this.#stream = stream;
-    this.#name = name;
-  }
-  /**
-   * Writes `message` to the instance's internal stream.
-   * @param message Message to write
-   */
-  write(message) {
-    this.writeStream(message);
-  }
-  /**
-   * Calls `end` on this instance's internal stream
-   */
-  end(...arguments_) {
-    this.#stream.end(...arguments_);
-  }
-  get isReady() {
-    return this.#ready;
-  }
-  writeStream(message) {
-    if (!this.#ready) {
-      console.warn(`Stream busy: ${this.#name}. Write will be dropped: "${message}"`);
-      return;
-    }
-    this.#ready = false;
-    this.#stream.on("error", (error) => {
-      throw error;
-    });
-    this.#stream.on("drain", () => {
-      this.#ready = true;
-    });
-    this.#stream.on("finish", () => {
-      this.#ready = true;
-    });
-    this.#ready = this.#stream.write(message, () => {
-    });
-  }
-}
-
-class RotatingFileStream {
-  #filePath;
-  #immediate;
-  #stream;
-  #options;
-  #createRfsStream;
-  /**
-   * 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, writeImmediately = false, options = {}) {
-    this.#filePath = filePath;
-    this.#immediate = writeImmediately;
-    this.#options = options;
-    if (!this.#immediate) {
-      try {
-        this.#createRfsStream = require("rotating-file-stream").createStream;
-      } catch {
-        throw new Error("The 'rotating-file-stream' package is missing. Make sure to install the 'rotating-file-stream' package.");
-      }
-      this.#stream = this.#createRfsStream(this.#filePath, options);
-    }
-  }
-  /**
-   * 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) {
-    let fileStream = this.#stream;
-    if (this.#immediate) {
-      fileStream = this.#createRfsStream(this.#filePath, this.#options);
-    }
-    const stream = new SafeStreamHandler(fileStream, this.#filePath);
-    stream.write(message);
-    if (this.#immediate) {
-      stream.end();
-    }
-  }
-  /**
-   * 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() {
-    if (this.#stream !== void 0) {
-      this.#stream.end();
-    }
-  }
-}
-
-class JsonFileReporter extends AbstractJsonReporter {
-  /** The rotating file stream instance */
-  stream;
-  /**
-   * Creates a new JsonFileReporter instance.
-   * @param options Configuration options for file rotation and JSON formatting
-   */
-  constructor(options) {
-    super();
-    const { filePath, writeImmediately = false, ...rfsOptions } = options;
-    this.stream = new RotatingFileStream(filePath, writeImmediately, {
-      compress: "gzip",
-      // compress rotated files
-      interval: "1d",
-      // rotate daily
-      size: "10M",
-      // rotate every 10 MegaBytes written,
-      ...rfsOptions
-    });
-  }
-  /**
-   * Writes a JSON message to the rotating file stream.
-   * @param message The JSON-formatted log message to write
-   * @protected
-   */
-  // eslint-disable-next-line no-underscore-dangle
-  _log(message) {
-    this.stream.write(`${message}
-`);
-  }
-}
-
-export { JsonFileReporter };
+import{AbstractJsonReporter as a}from"../../packem_shared/AbstractJsonReporter-CF0KKdQS.js";class r{#t=!0;#s;#e;constructor(t,e){this.#s=t,this.#e=e,this.#s.on("error",s=>{throw s}),this.#s.on("drain",()=>{this.#t=!0}),this.#s.on("finish",()=>{this.#t=!0})}write(t){this.writeStream(t)}end(...t){this.#s.end(...t)}get isReady(){return this.#t}writeStream(t){if(!this.#t){console.warn(`Stream busy: ${this.#e}. Write will be dropped: "${t}"`);return}this.#t=!1,this.#t=this.#s.write(t,()=>{})}}class n{#t;#s;#e;#r;#i;#h;constructor(t,e=!1,s={}){this.#t=t,this.#s=e,this.#r=s;try{this.#i=require("rotating-file-stream").createStream}catch{throw new Error("The 'rotating-file-stream' package is missing. Make sure to install the 'rotating-file-stream' package.")}this.#s||(this.#e=this.#i(this.#t,s),this.#h=new r(this.#e,this.#t))}write(t){if(this.#s){const e=this.#i(this.#t,this.#r),s=new r(e,this.#t);s.write(t),s.end();return}this.#h.write(t)}end(){this.#e!==void 0&&this.#e.end()}}class c extends a{stream;constructor(t){super();const{filePath:e,writeImmediately:s=!1,...h}=t;this.stream=new n(e,s,{compress:"gzip",interval:"1d",size:"10M",...h})}_log(t){this.stream.write(`${t}
+`)}}export{c as JsonFileReporter};