@visulima/pail 3.2.0 → 3.2.2

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

@@ -1,21 +1,54 @@
-import { P as Processor, M as Meta } from '../../packem_shared/types-D3ycu8-x.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/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-D3ycu8-x.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

@@ -17,7 +17,7 @@ class MessageFormatterProcessor {
    * Sets the stringify function for object serialization.
    * @param function_ The stringify function to use for serializing objects
    */
-  // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
+  // eslint-disable-next-line , @typescript-eslint/no-explicit-any
   setStringify(function_) {
     this.#stringify = function_;
   }

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

@@ -1,19 +1,70 @@
-import { P as Processor, M as Meta } from '../packem_shared/types-D3ycu8-x.js';
-import '@visulima/colorize';
-import 'type-fest';
-import '../interactive/index.js';
-
-interface OpenTelemetryProcessorOptions {
+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;
 }
-declare class OpenTelemetryProcessor<L extends string = string> implements Processor<L> {
+/**
+ * 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>;
 }
-
-export { OpenTelemetryProcessor };
-export type { OpenTelemetryProcessorOptions };

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-D3ycu8-x.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/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 };

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

@@ -1,27 +1,46 @@
-import { Options } from 'rotating-file-stream';
-import { a as AbstractJsonReporterOptions, A as AbstractJsonReporter } from '../../packem_shared/abstract-json-reporter-DiyVyU0j.js';
-import '../../packem_shared/index.d-oxZvg_y7.js';
-import 'type-fest';
-import '../../packem_shared/types-D3ycu8-x.js';
-import '@visulima/colorize';
-import '../../interactive/index.js';
-
-declare class RotatingFileStream {
-    #private;
-    constructor(filePath: string, writeImmediately?: boolean, options?: Options);
-    write(message: string): void;
-    end(): void;
-}
-
-type FileReporterOptions = AbstractJsonReporterOptions & Options & {
+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";
+/**
+ * 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;
 };
-declare class JsonFileReporter<L extends string = string> extends AbstractJsonReporter<L> {
+/**
+ * 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;
 }
-
-export { JsonFileReporter };
-export type { FileReporterOptions };

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

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