@visulima/pail 3.1.0 → 3.2.1

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

@@ -1,21 +1,54 @@
-import { P as Processor, M as Meta } from '../../packem_shared/types-DVzG8TWL.js';
-import '@visulima/colorize';
-import 'type-fest';
-import '../../interactive/index.js';
-
+import type { Meta, Processor } from "../../types.d.ts";
+/**
+ * Global namespace extension for caller file metadata.
+ *
+ * Extends the VisulimaPail.CustomMeta interface to include file information
+ * that will be added by the CallerProcessor.
+ */
 declare global {
     namespace VisulimaPail {
         interface CustomMeta<L> {
+            /** File information where the log was called from */
             file: {
+                /** Column number in the source file */
                 column: number | undefined;
+                /** Line number in the source file */
                 line: number | undefined;
+                /** Name/path of the source file */
                 name: string | undefined;
             } | undefined;
         }
     }
 }
+/**
+ * Caller Processor.
+ *
+ * A processor that adds file location information to log metadata.
+ * Uses stack trace analysis to determine the file, line, and column
+ * where the log call originated from.
+ * @template L - The log level type
+ * @example
+ * ```typescript
+ * import { createPail } from "@visulima/pail";
+ * import CallerProcessor from "@visulima/pail/processor/caller";
+ *
+ * const logger = createPail({
+ *   processors: [new CallerProcessor()]
+ * });
+ *
+ * logger.info("This log will include file location info");
+ * // Result includes: file: { name: "...", line: 123, column: 45 }
+ * ```
+ */
 declare class CallerProcessor<L extends string = string> implements Processor<L> {
+    /**
+     * Processes log metadata to add caller file information.
+     *
+     * Analyzes the call stack to determine the file location where the log
+     * was called from and adds this information to the metadata.
+     * @param meta The log metadata to process
+     * @returns The processed metadata with file location information added
+     */
     process(meta: Meta<L>): Meta<L>;
 }
-
-export { CallerProcessor as default };
+export default CallerProcessor;

package/dist/processor/caller/caller-processor.js

@@ -1 +1,59 @@
-var u=Object.defineProperty;var n=(a,e)=>u(a,"name",{value:e,configurable:!0});var m=Object.defineProperty,o=n((a,e)=>m(a,"name",{value:e,configurable:!0}),"u");const c=o(()=>{const a=Error.prepareStackTrace;try{let e=[];Error.prepareStackTrace=(i,r)=>{const t=r.slice(1);return e=t,t};const l=e.reduce((i,r)=>(r.isNative()||r.getFileName()?.includes("pail/dist")||i.push({columnNumber:r.getColumnNumber(),fileName:r.getFileName()??void 0,lineNumber:r.getLineNumber()}),i),[])[0];return l?{columnNumber:l.columnNumber??void 0,fileName:l.fileName,lineNumber:l.lineNumber??void 0}:{fileName:"anonymous",lineNumber:void 0}}finally{Error.prepareStackTrace=a}},"getCallerFilename");var s=Object.defineProperty,N=n((a,e)=>s(a,"name",{value:e,configurable:!0}),"r");class f{static{n(this,"a")}static{N(this,"CallerProcessor")}process(e){const{columnNumber:l,fileName:i,lineNumber:r}=c();return e.file={column:l,line:r,name:i},e}}export{f as default};
+const getCallerFilename = () => {
+  const errorStack = Error.prepareStackTrace;
+  try {
+    let result = [];
+    Error.prepareStackTrace = (_error, stack) => {
+      const callSitesWithoutCurrent = stack.slice(1);
+      result = callSitesWithoutCurrent;
+      return callSitesWithoutCurrent;
+    };
+    const callers = result.reduce((accumulator, x) => {
+      if (x.isNative() || x.getFileName()?.includes("pail/dist")) {
+        return accumulator;
+      }
+      accumulator.push({
+        columnNumber: x.getColumnNumber(),
+        fileName: x.getFileName() ?? void 0,
+        lineNumber: x.getLineNumber()
+      });
+      return accumulator;
+    }, []);
+    const firstExternalFilePath = callers[0];
+    if (firstExternalFilePath) {
+      return {
+        columnNumber: firstExternalFilePath.columnNumber ?? void 0,
+        fileName: firstExternalFilePath.fileName,
+        lineNumber: firstExternalFilePath.lineNumber ?? void 0
+      };
+    }
+    return {
+      fileName: "anonymous",
+      lineNumber: void 0
+    };
+  } finally {
+    Error.prepareStackTrace = errorStack;
+  }
+};
+
+class CallerProcessor {
+  /**
+   * Processes log metadata to add caller file information.
+   *
+   * Analyzes the call stack to determine the file location where the log
+   * was called from and adds this information to the metadata.
+   * @param meta The log metadata to process
+   * @returns The processed metadata with file location information added
+   */
+  // eslint-disable-next-line class-methods-use-this
+  process(meta) {
+    const { columnNumber, fileName, lineNumber } = getCallerFilename();
+    meta.file = {
+      column: columnNumber,
+      line: lineNumber,
+      name: fileName
+    };
+    return meta;
+  }
+}
+
+export { CallerProcessor as default };

package/dist/processor/caller/get-caller-filename.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Gets the file location information of the caller.
+ *
+ * Uses Node.js stack trace API to analyze the call stack and determine
+ * the file, line, and column where this function was called from.
+ * Filters out internal pail files and native code.
+ * @returns Object containing file location information
+ * @example
+ * ```typescript
+ * const location = getCallerFilename();
+ * console.log(location);
+ * // { fileName: "/path/to/file.js", lineNumber: 42, columnNumber: 10 }
+ * ```
+ */
+declare const getCallerFilename: () => {
+    /** Column number where the call originated */
+    columnNumber?: number;
+    /** File name/path where the call originated */
+    fileName: string | undefined;
+    /** Line number where the call originated */
+    lineNumber?: number;
+};
+export default getCallerFilename;

package/dist/processor/message-formatter-processor.d.ts

@@ -1,17 +1,52 @@
-import { h as StringifyAwareProcessor, M as Meta } from '../packem_shared/types-DVzG8TWL.js';
-import '@visulima/colorize';
-import 'type-fest';
-import '../interactive/index.js';
-
-type FormatterFunction = (argument: any) => string;
-
+import type { FormatterFunction } from "@visulima/fmt";
+import type { Meta, StringifyAwareProcessor } from "../types.d.ts";
+/**
+ * Message Formatter Processor.
+ *
+ * A processor that formats log messages using the {@link https://www.visulima.com/docs/package/fmt|@visulima/fmt} library.
+ * Supports custom formatters, string interpolation, and complex object formatting.
+ * Processes both the main message and contextual data.
+ * @template L - The log level type
+ * @example
+ * ```typescript
+ * import { createPail } from "@visulima/pail";
+ * import MessageFormatterProcessor from "@visulima/pail/processor/message-formatter";
+ *
+ * const logger = createPail({
+ *   processors: [new MessageFormatterProcessor({
+ *     formatters: {
+ *       user: (value) => `[USER:${value.id}]`
+ *     }
+ *   })]
+ * });
+ *
+ * logger.info("User {user} logged in", { user: { id: 123 } });
+ * // Output: "User [USER:123] logged in"
+ * ```
+ */
 declare class MessageFormatterProcessor<L extends string = string> implements StringifyAwareProcessor<L> {
     #private;
+    /**
+     * Creates a new MessageFormatterProcessor instance.
+     * @param options Configuration options
+     * @param options.formatters Custom formatters for message interpolation
+     */
     constructor(options?: {
         formatters?: Record<string, FormatterFunction>;
     });
+    /**
+     * Sets the stringify function for object serialization.
+     * @param function_ The stringify function to use for serializing objects
+     */
     setStringify(function_: any): void;
+    /**
+     * Processes log metadata to format messages.
+     *
+     * Applies string interpolation and custom formatters to the message
+     * and contextual data in the log metadata.
+     * @param meta The log metadata to process
+     * @returns The processed metadata with formatted messages
+     */
     process(meta: Meta<L>): Meta<L>;
 }
-
-export { MessageFormatterProcessor as default };
+export default MessageFormatterProcessor;

package/dist/processor/message-formatter-processor.js

@@ -1 +1,67 @@
-var f=Object.defineProperty;var n=(o,t)=>f(o,"name",{value:t,configurable:!0});import{G as c}from"../packem_shared/index-D9hWq9ka.js";var y=Object.defineProperty,a=n((o,t)=>y(o,"name",{value:t,configurable:!0}),"s");class p{static{n(this,"p")}static{a(this,"MessageFormatterProcessor")}#t;#e;constructor(t={}){this.#e=t.formatters}setStringify(t){this.#t=t}process(t){const e=c({formatters:this.#e,stringify:a(s=>{const r=this.#t(s);return r===void 0?(console.warn(`Unable to stringify value of type ${typeof s}`,s),"undefined"):r},"stringify")});return t.message!==void 0&&(t.message=this.#s(e,t.message,t.context??[])),t}#s(t,e,s=[]){if(typeof e=="string")return t(e,s);if(typeof e=="object"&&e!==null)for(const r in e){const i=e[r];(typeof i=="string"||Array.isArray(i)||typeof i=="object")&&(e[r]=this.#s(t,i,s))}return e}}export{p as default};
+import { b as build } from '../packem_shared/index-BomQ3E6J.js';
+
+class MessageFormatterProcessor {
+  /** Custom stringify function for object serialization */
+  #stringify;
+  /** Custom formatters for message interpolation */
+  #formatters;
+  /**
+   * Creates a new MessageFormatterProcessor instance.
+   * @param options Configuration options
+   * @param options.formatters Custom formatters for message interpolation
+   */
+  constructor(options = {}) {
+    this.#formatters = options.formatters;
+  }
+  /**
+   * Sets the stringify function for object serialization.
+   * @param function_ The stringify function to use for serializing objects
+   */
+  // eslint-disable-next-line , @typescript-eslint/no-explicit-any
+  setStringify(function_) {
+    this.#stringify = function_;
+  }
+  /**
+   * Processes log metadata to format messages.
+   *
+   * Applies string interpolation and custom formatters to the message
+   * and contextual data in the log metadata.
+   * @param meta The log metadata to process
+   * @returns The processed metadata with formatted messages
+   */
+  process(meta) {
+    const formatter = build({
+      formatters: this.#formatters});
+    if (meta.message !== void 0) {
+      meta.message = this.#format(formatter, meta.message, meta.context ?? []);
+    }
+    return meta;
+  }
+  /**
+   * Recursively formats data using the formatter.
+   *
+   * Applies string interpolation and formatting to strings, arrays, and objects.
+   * @param formatter The formatter function to use
+   * @param data The data to format (string, array, or object)
+   * @param arguments_ Additional arguments for formatting
+   * @returns The formatted data
+   * @private
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  #format(formatter, data, arguments_ = []) {
+    if (typeof data === "string") {
+      return formatter(data, arguments_);
+    }
+    if (typeof data === "object" && data !== null) {
+      for (const index in data) {
+        const value = data[index];
+        if (typeof value === "string" || Array.isArray(value) || typeof value === "object") {
+          data[index] = this.#format(formatter, value, arguments_);
+        }
+      }
+    }
+    return data;
+  }
+}
+
+export { MessageFormatterProcessor as default };

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

@@ -0,0 +1,70 @@
+import type { Meta, Processor } from "../types.d.ts";
+/**
+ * Configuration options for the OpenTelemetry processor.
+ */
+export interface OpenTelemetryProcessorOptions {
+    /**
+     * Field name for the span ID. Defaults to 'span_id'
+     */
+    spanIdFieldName?: string;
+    /**
+     * If specified, all trace fields will be nested under this key
+     */
+    traceFieldName?: string;
+    /**
+     * Field name for the trace flags. Defaults to 'trace_flags'
+     */
+    traceFlagsFieldName?: string;
+    /**
+     * Field name for the trace ID. Defaults to 'trace_id'
+     */
+    traceIdFieldName?: string;
+}
+/**
+ * OpenTelemetry Processor.
+ *
+ * A processor that adds OpenTelemetry trace context to log metadata.
+ * Extracts trace ID, span ID, and trace flags from the active OpenTelemetry span
+ * and adds them to the log context for distributed tracing correlation.
+ * @template L - The log level type
+ * @example
+ * ```typescript
+ * import { createPail } from "@visulima/pail";
+ * import { OpenTelemetryProcessor } from "@visulima/pail/processor/opentelemetry";
+ *
+ * const logger = createPail({
+ *   processors: [new OpenTelemetryProcessor()]
+ * });
+ *
+ * logger.info("Processing request");
+ * // Context includes: { trace_id: "...", span_id: "...", trace_flags: "01" }
+ * ```
+ * @example
+ * ```typescript
+ * // With custom field names
+ * const logger = createPail({
+ *   processors: [new OpenTelemetryProcessor({
+ *     traceFieldName: "trace",
+ *     traceIdFieldName: "traceId",
+ *     spanIdFieldName: "spanId"
+ *   })]
+ * });
+ * ```
+ */
+export declare class OpenTelemetryProcessor<L extends string = string> implements Processor<L> {
+    #private;
+    /**
+     * Creates a new OpenTelemetryProcessor instance.
+     * @param options Configuration options for field names and nesting
+     */
+    constructor(options?: OpenTelemetryProcessorOptions);
+    /**
+     * 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: Meta<L>): Meta<L>;
+}

package/dist/processor/opentelemetry-processor.js

@@ -0,0 +1,52 @@
+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 };

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

@@ -1,13 +1,44 @@
-import { Rules, RedactOptions } from '@visulima/redact';
-import { P as Processor, M as Meta } from '../packem_shared/types-DVzG8TWL.js';
-import '@visulima/colorize';
-import 'type-fest';
-import '../interactive/index.js';
-
+import type { RedactOptions, Rules } from "@visulima/redact";
+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
+ * 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>;
 }
-
-export { RedactProcessor as default };
+export default RedactProcessor;

package/dist/processor/redact-processor.js

@@ -1 +1,30 @@
-var o=Object.defineProperty;var s=(t,r)=>o(t,"name",{value:r,configurable:!0});import{redact as c,standardRules as i}from"@visulima/redact";var n=Object.defineProperty,u=s((t,r)=>n(t,"name",{value:r,configurable:!0}),"r");class l{static{s(this,"a")}static{u(this,"RedactProcessor")}#r;constructor(r,e){this.#r=a=>c(a,r||i,e)}process(r){return r.message=this.#r(r.message),r.context=this.#r(r.context),r.error=this.#r(r.error),r}}export{l as default};
+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 };

package/dist/progress-bar.d.ts

@@ -1,7 +1,6 @@
-import { InteractiveManager } from './interactive/index.js';
-
-type ProgressBarStyle = "shades_classic" | "shades_grey" | "rect" | "filled" | "solid" | "ascii" | "custom";
-interface ProgressBarOptions {
+import type InteractiveManager from "./interactive/interactive-manager.d.ts";
+export type ProgressBarStyle = "shades_classic" | "shades_grey" | "rect" | "filled" | "solid" | "ascii" | "custom";
+export interface ProgressBarOptions {
     barCompleteChar?: string | string[];
     barGlue?: string;
     barIncompleteChar?: string | string[];
@@ -12,10 +11,10 @@ interface ProgressBarOptions {
     total: number;
     width?: number;
 }
-interface SingleBarOptions extends ProgressBarOptions {
+export interface SingleBarOptions extends ProgressBarOptions {
     format?: string;
 }
-interface MultiBarOptions {
+export interface MultiBarOptions {
     barCompleteChar?: string | string[];
     barGlue?: string;
     barIncompleteChar?: string | string[];
@@ -24,27 +23,63 @@ interface MultiBarOptions {
     fps?: number;
     style?: ProgressBarStyle;
 }
-interface ProgressBarPayload {
+export interface ProgressBarPayload {
     [key: string]: string | number | boolean;
 }
-declare const getBarChar: (char: string | undefined, style: ProgressBarStyle, complete?: boolean) => string;
-declare const applyStyleToOptions: <T extends ProgressBarOptions | MultiBarOptions>(options: T) => T;
-declare class ProgressBar {
+/**
+ * Gets the appropriate bar character based on style and completion state.
+ * @param char Custom character override
+ * @param style Progress bar style to use
+ * @param complete Whether to get completed or incomplete character
+ * @returns The appropriate character for the given style
+ */
+export declare const getBarChar: (char: string | undefined, style: ProgressBarStyle, complete?: boolean) => string;
+export declare const applyStyleToOptions: <T extends ProgressBarOptions | MultiBarOptions>(options: T) => T;
+export declare class ProgressBar {
     protected options: ProgressBarOptions;
     protected current: number;
     private startTime;
     private interactiveManager?;
     private isActive;
     private 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: ProgressBarOptions, interactiveManager?: InteractiveManager, payload?: ProgressBarPayload);
+    /**
+     * 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: number, payload?: ProgressBarPayload): void;
+    /**
+     * 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?: number, payload?: ProgressBarPayload): void;
+    /**
+     * Renders the progress bar as a formatted string.
+     * @returns Formatted progress bar string with all placeholders replaced
+     */
     render(): string;
+    /**
+     * Starts the progress bar.
+     * @param total Optional total value to set
+     * @param startValue Optional starting value
+     * @param payload Optional initial payload data
+     */
     start(total?: number, startValue?: number, payload?: ProgressBarPayload): void;
+    /**
+     * Stops the progress bar and cleanup.
+     */
     stop(): void;
     private calculateETA;
 }
-declare class MultiBarInstance extends ProgressBar {
+export declare class MultiBarInstance extends ProgressBar {
     private multiBar;
     constructor(multiBar: MultiProgressBar, options: ProgressBarOptions, payload?: ProgressBarPayload);
     update(current: number, payload?: ProgressBarPayload): void;
@@ -54,7 +89,7 @@ declare class MultiBarInstance extends ProgressBar {
         total: number;
     };
 }
-declare class MultiProgressBar {
+export declare class MultiProgressBar {
     private bars;
     private options;
     private interactiveManager?;
@@ -62,15 +97,40 @@ declare class MultiProgressBar {
     private nextBarId;
     private composite;
     private barColors;
+    /**
+     * Creates a new multi progress bar manager.
+     * @param options Configuration options for the progress bars
+     * @param interactiveManager Optional interactive manager for rendering
+     */
     constructor(options?: MultiBarOptions, 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: number, current?: number, payload?: ProgressBarPayload): ProgressBar;
+    /**
+     * 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: ProgressBar): boolean;
+    /**
+     * Renders all progress bars.
+     */
     renderAll(): void;
+    /**
+     * 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: MultiBarInstance, color: ((text: string) => string) | undefined): void;
+    /**
+     * Stops all progress bars and cleanup.
+     */
     stop(): void;
     private renderComposite;
     private getCompositeChar;
 }
-
-export { MultiBarInstance, MultiProgressBar, ProgressBar, applyStyleToOptions, getBarChar };
-export type { MultiBarOptions, ProgressBarOptions, ProgressBarPayload, ProgressBarStyle, SingleBarOptions };