@visulima/pail 4.0.1 → 4.1.0

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

@@ -1,22 +1,21 @@
-import { M as Meta, P as Processor } from "../packem_shared/types.d-bWnqHJKL.js";
+import { M as Meta, P as Processor } from "../packem_shared/types.d-4ge_rME4.js";
 import '@visulima/colorize';
 import '@visulima/interactive-manager';
-import 'type-fest';
 /**
-* A censor function receives the original value being redacted plus the dot-path
-* identifier of where it was found, and returns the value to store in its place.
-*
-* Use it for partial masking — e.g. keep the last four digits of a card number, or
-* mask the local part of an email — instead of a static replacement string.
-* @example
-* ```ts
-* const keepLast4: Censor = (value) =>
-*     typeof value === "string" ? "****" + value.slice(-4) : value;
-* ```
-* @param value The original value matched by the rule.
-* @param path The dot-path of the matched key (e.g. `user.card`), or `undefined`
-* for matches that have no key path (string-anonymizer / array-index matches).
-*/
+ * A censor function receives the original value being redacted plus the dot-path
+ * identifier of where it was found, and returns the value to store in its place.
+ *
+ * Use it for partial masking — e.g. keep the last four digits of a card number, or
+ * mask the local part of an email — instead of a static replacement string.
+ * @example
+ * ```ts
+ * const keepLast4: Censor = (value) =>
+ *     typeof value === "string" ? "****" + value.slice(-4) : value;
+ * ```
+ * @param value The original value matched by the rule.
+ * @param path The dot-path of the matched key (e.g. `user.card`), or `undefined`
+ * for matches that have no key path (string-anonymizer / array-index matches).
+ */
 type Censor = (value: unknown, path: string | undefined) => unknown;
 type StringAnonymize = {
   key: string;
@@ -25,23 +24,23 @@ type StringAnonymize = {
 };
 type Anonymize = {
   /**
-  * When `true`, the rule is also applied to nested string values (NLP / regex based),
-  * not just to matching object keys.
-  */
+   * When `true`, the rule is also applied to nested string values (NLP / regex based),
+   * not just to matching object keys.
+   */
   deep?: boolean;
   /** The key (or wildcard pattern, or NLP type) to match. Case-insensitive. */
   key: string;
   /** Optional regular expression matched against nested string values. */
   pattern?: RegExp | string;
   /**
-  * When `true`, the matching key is deleted from the output object instead of being
-  * replaced with `replacement`. Ignored for array elements and string-anonymizer matches.
-  */
+   * When `true`, the matching key is deleted from the output object instead of being
+   * replaced with `replacement`. Ignored for array elements and string-anonymizer matches.
+   */
   remove?: boolean;
   /**
-  * The value (or {@link Censor} function) to put in place of a match. Defaults to
-  * the `<KEY>` placeholder when omitted.
-  */
+   * The value (or {@link Censor} function) to put in place of a match. Defaults to
+   * the `<KEY>` placeholder when omitted.
+   */
   replacement?: unknown;
 };
 type Rules = (Anonymize | StringAnonymize | number | string)[];
@@ -52,51 +51,44 @@ type RedactOptions = {
   };
 };
 /**
-* Credential / secret rules: API keys, AWS keys, bearer/JWT/Slack tokens, crypto wallets,
-* basic-auth strings, and the broad key-name rules (`auth`, `password`, `secret`, ...).
-*
-* These are the safest default rules — they target high-entropy or unambiguous shapes — and are
-* what most logger-scrubbing use cases need.
-*/
-/**
-* 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
-* });
-* ```
-*/
+ * 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
-  */
+   * 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
-  */
+   * 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 };

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

@@ -1,113 +1,112 @@
-import { M as Meta, P as Processor } from "../packem_shared/types.d-bWnqHJKL.js";
+import { M as Meta, P as Processor } from "../packem_shared/types.d-4ge_rME4.js";
 import '@visulima/colorize';
 import '@visulima/interactive-manager';
-import 'type-fest';
 /**
-* 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
-* };
-* ```
-*/
+ * 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
-*/
+ * 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.
-*/
+ * 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 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 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,
-*       ],
-*     }),
-*   ],
-* });
-* ```
-*/
+ * 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
-  */
+   * 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
-  */
+   * 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/reporter/file/json-file-reporter.d.ts

@@ -1,59 +1,58 @@
 import { Options } from 'rotating-file-stream';
-import { A as AbstractJsonReporterOptions, a as AbstractJsonReporter } from "../../packem_shared/abstract-json-reporter.d-wfESoEa-.js";
+import { A as AbstractJsonReporterOptions, a as AbstractJsonReporter } from "../../packem_shared/abstract-json-reporter.d-B6NoO-hG.js";
 import "../../packem_shared/index.d-T71KjNAr.js";
-import 'type-fest';
-import "../../packem_shared/types.d-bWnqHJKL.js";
+import "../../packem_shared/types.d-4ge_rME4.js";
 import '@visulima/colorize';
 import '@visulima/interactive-manager';
 /**
-* 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"
-* });
-* ```
-*/
+ * 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
-  */
+   * 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
-  */
+   * 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.
-  */
+   * 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.
-*/
+ * Options for configuring the JsonFileReporter.
+ */
 type FileReporterOptions = AbstractJsonReporterOptions & Options & {
   /** Path to the log file */
   filePath: string;
@@ -61,53 +60,53 @@ type FileReporterOptions = AbstractJsonReporterOptions & Options & {
   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]);
-* ```
-*/
+ * 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
-  */
+   * Creates a new JsonFileReporter instance.
+   * @param options Configuration options for file rotation and JSON formatting
+   */
   constructor(options: FileReporterOptions);
   /**
-  * Closes the underlying rotating file stream.
-  *
-  * Ends the buffered stream so any queued writes are flushed to disk before the
-  * process exits. Without this the tail of the log can be lost on a short-lived
-  * process. After calling `close()` no further writes should be made (unless
-  * `writeImmediately` was enabled, in which case each write owns its own stream).
-  * @example
-  * ```typescript
-  * process.on("beforeExit", () => reporter.close());
-  * ```
-  */
+   * Closes the underlying rotating file stream.
+   *
+   * Ends the buffered stream so any queued writes are flushed to disk before the
+   * process exits. Without this the tail of the log can be lost on a short-lived
+   * process. After calling `close()` no further writes should be made (unless
+   * `writeImmediately` was enabled, in which case each write owns its own stream).
+   * @example
+   * ```typescript
+   * process.on("beforeExit", () => reporter.close());
+   * ```
+   */
   close(): void;
   /**
-  * Alias for {@link close} to match common transport `dispose` conventions.
-  */
+   * Alias for {@link close} to match common transport `dispose` conventions.
+   */
   dispose(): void;
   /**
-  * Writes a JSON message to the rotating file stream.
-  * @param message The JSON-formatted log message to write
-  * @protected
-  */
+   * 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,2 +1,2 @@
-import{AbstractJsonReporter as a}from"../../packem_shared/AbstractJsonReporter-w_bGGiD-.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 o{#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 o(e,s,{compress:"gzip",interval:"1d",size:"10M",...h})}close(){this.stream.end()}dispose(){this.close()}_log(t){this.stream.write(`${t}
+import{AbstractJsonReporter as a}from"../../packem_shared/AbstractJsonReporter-DxZwImm5.js";class h{#t=!0;#s;#e;#i;constructor(t,e,s){this.#s=t,this.#e=e,this.#i=s??((i,o)=>{console.error(`Stream error: ${o}. Writes will be dropped.`,i)}),this.#s.on("error",i=>{this.#t=!1,this.#i(i,this.#e)}),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;#i;#r;#h;constructor(t,e=!1,s={}){this.#t=t,this.#s=e,this.#i=s;try{this.#r=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.#r(this.#t,s),this.#h=new h(this.#e,this.#t))}write(t){if(this.#s){const e=this.#r(this.#t,this.#i),s=new h(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,...i}=t;this.stream=new n(e,s,{compress:"gzip",interval:"1d",size:"10M",...i})}close(){this.stream.end()}dispose(){this.close()}_log(t){this.stream.write(`${t}
 `)}}export{c as JsonFileReporter};