@visulima/pail 4.0.0-alpha.11 → 4.0.0-alpha.13

package/dist/index.browser.d.ts

@@ -1,49 +1,559 @@
-import type { PailBrowserType } from "./pail.d.ts";
-import type { ConstructorOptions } from "./types.d.ts";
+import { stringify } from 'safe-stable-stringify';
+import { LiteralUnion } from 'type-fest';
+import { C as ConstructorOptions, M as Meta, D as DefaultLogTypes, L as LoggerTypesConfig, P as Processor, E as ExtendedRfc5424LogLevels, b as Reporter, c as LoggerFunction } from "./packem_shared/types.d-C51XNfQz.js";
+export { type d as DefaultLoggerTypes, type e as LoggerConfiguration, type a as LoggerTypesAwareReporter, type f as StreamAwareReporter } from "./packem_shared/types.d-C51XNfQz.js";
+import '@visulima/colorize';
+import '@visulima/interactive-manager';
 /**
- * Creates a new Pail logger instance configured for browser environments.
- *
- * This factory function creates a browser-compatible logger with default processors
- * and reporters suitable for client-side logging.
- * @template T - Custom logger types
- * @template L - Log level types
- * @param options Configuration options for the logger
- * @returns A new PailBrowser instance
- * @example
- * ```typescript
- * import { createPail } from "@visulima/pail";
- *
- * const logger = createPail({
- *   logLevel: "debug",
- *   types: {
- *     custom: {
- *       color: "blue",
- *       label: "CUSTOM",
- *       logLevel: "info"
- *     }
- *   }
- * });
- *
- * logger.info("Hello world!");
- * logger.custom("Custom message");
- * ```
- */
-export declare const createPail: <T extends string = string, L extends string = string>(options?: ConstructorOptions<T, L>) => PailBrowserType<T, L>;
+* Pail Browser Implementation.
+*
+* A comprehensive logging library for browser environments with support for
+* multiple log levels, custom types, processors, reporters, and advanced features
+* like throttling, scoping, timers, and counters.
+* @template T - Custom logger types (string union)
+* @template L - Log level types (string union)
+* @example
+* ```typescript
+* const logger = new PailBrowserImpl({
+*   logLevel: "debug",
+*   types: {
+*     http: { color: "blue", label: "HTTP", logLevel: "info" }
+*   },
+*   reporters: [new JsonReporter()]
+* });
+*
+* logger.info("Application started");
+* logger.http("GET /api/users 200");
+* logger.error("Something went wrong", error);
+* ```
+*/
+declare class PailBrowserImpl<T extends string = string, L extends string = string> {
+  #private;
+  protected timersMap: Map<string, number>;
+  protected countMap: Map<string, number>;
+  protected seqTimers: Set<string>;
+  protected readonly lastLog: {
+    count?: number;
+    object?: Meta<L>;
+    time?: Date;
+    timeout?: ReturnType<typeof setTimeout>;
+  };
+  protected readonly logLevels: Record<string, number>;
+  protected disabled: boolean;
+  protected paused: boolean;
+  protected messageQueue: {
+    messageObject: any[];
+    raw: boolean;
+    type: LiteralUnion<DefaultLogTypes, T>;
+  }[];
+  protected scopeName: string[];
+  protected readonly types: LoggerTypesConfig<LiteralUnion<DefaultLogTypes, T>, L>;
+  protected readonly longestLabel: string;
+  protected readonly processors: Set<Processor<L>>;
+  protected readonly generalLogLevel: LiteralUnion<ExtendedRfc5424LogLevels, L>;
+  protected reporters: Set<Reporter<L>>;
+  protected readonly throttle: number;
+  protected readonly throttleMin: number;
+  protected readonly stringify: typeof stringify;
+  protected groups: string[];
+  protected readonly startTimerMessage: string;
+  protected readonly endTimerMessage: string;
+  protected rawReporter: Reporter<L>;
+  protected force: Record<string, LoggerFunction>;
+  /**
+  * Creates a new Pail browser logger instance.
+  *
+  * Initializes the logger with the provided configuration options,
+  * setting up reporters, processors, log levels, and other internal state.
+  * @param options Configuration options for the logger
+  */
+  constructor(options: ConstructorOptions<T, L>);
+  /**
+  * Wraps the global console methods to redirect them through the logger.
+  *
+  * This method replaces console methods (log, info, warn, error, etc.) with
+  * calls to the corresponding logger methods. The original console methods
+  * are backed up and can be restored using restoreConsole().
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.wrapConsole();
+  *
+  * console.log("This will go through the logger");
+  * console.error("This too!");
+  *
+  * logger.restoreConsole(); // Restore original console methods
+  * ```
+  */
+  wrapConsole(): void;
+  /**
+  * Restores the original global console methods.
+  *
+  * This method restores the console methods that were backed up by wrapConsole().
+  * After calling this, console methods will work as they did before wrapping.
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.wrapConsole();
+  *
+  * // Console methods are now wrapped
+  * logger.restoreConsole();
+  * // Console methods are restored to original behavior
+  * ```
+  */
+  restoreConsole(): void;
+  /**
+  * Wraps uncaught exception and unhandled rejection handlers.
+  *
+  * This method sets up global error handlers that will log uncaught exceptions
+  * and unhandled promise rejections through the logger. This is useful for
+  * capturing and logging application crashes.
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.wrapException();
+  *
+  * // Now uncaught errors will be logged
+  * throw new Error("This will be logged");
+  * ```
+  */
+  wrapException(): void;
+  /**
+  * Disables all logging output.
+  *
+  * When disabled, all log calls will be silently ignored and no output
+  * will be produced by any reporters. This can be useful for temporarily
+  * suppressing log output in production or during testing.
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.disable();
+  * logger.info("This won't be logged"); // Silent
+  * logger.enable();
+  * logger.info("This will be logged"); // Output produced
+  * ```
+  */
+  disable(): void;
+  /**
+  * Enables logging output.
+  *
+  * Re-enables logging after it has been disabled. All subsequent log calls
+  * will produce output according to the configured reporters.
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.disable();
+  * logger.info("This won't be logged");
+  * logger.enable(); // Re-enable logging
+  * logger.info("This will be logged");
+  * ```
+  */
+  enable(): void;
+  /**
+  * Checks if logging is currently enabled.
+  *
+  * Returns true if logging is enabled and false if it has been disabled.
+  * @returns True if logging is enabled, false if disabled
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * console.log(logger.isEnabled()); // true
+  * logger.disable();
+  * console.log(logger.isEnabled()); // false
+  * ```
+  */
+  isEnabled(): boolean;
+  /**
+  * Pauses logging and starts queuing messages.
+  *
+  * When paused, all log calls will be queued instead of being output immediately.
+  * The queued messages will be processed when resume() is called. This is useful
+  * for temporarily buffering log output during critical operations.
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.pause();
+  * logger.info("This will be queued"); // Queued, not output yet
+  * logger.warn("This too"); // Also queued
+  * logger.resume(); // Now both messages are output
+  * ```
+  */
+  pause(): void;
+  /**
+  * Resumes logging and flushes all queued messages.
+  *
+  * Processes all messages that were queued during the pause period and
+  * resumes normal logging behavior. Messages are output in the order
+  * they were originally called.
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.pause();
+  * logger.info("Message 1"); // Queued
+  * logger.info("Message 2"); // Queued
+  * logger.resume(); // Both messages are now output in order
+  * logger.info("Message 3"); // Output immediately
+  * ```
+  */
+  resume(): void;
+  /**
+  * Creates a scoped logger instance.
+  *
+  * Returns a new logger instance that inherits all configuration but adds
+  * the specified scope names to all log messages. This is useful for
+  * categorizing logs by component, module, or feature.
+  * @template N - The new custom logger type names
+  * @param name Scope names to apply to all log messages
+  * @returns A new scoped logger instance
+  * @throws {Error} If no scope name is provided
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * const scopedLogger = logger.scope("auth", "login");
+  * scopedLogger.info("User logged in"); // Will include scope: ["auth", "login"]
+  * ```
+  */
+  scope<N extends string = T>(...name: string[]): PailBrowserType<N, L>;
+  /**
+  * Removes the current scope from the logger.
+  *
+  * Clears all scope names that were set by previous scope() calls.
+  * After calling this, log messages will no longer include scope information.
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * const scopedLogger = logger.scope("auth");
+  * scopedLogger.info("Scoped message"); // Has scope
+  * scopedLogger.unscope();
+  * scopedLogger.info("Unscoped message"); // No scope
+  * ```
+  */
+  unscope(): void;
+  /**
+  * Creates a child logger that inherits settings from the parent.
+  *
+  * Returns a new logger instance that inherits all configuration from the parent
+  * (reporters, processors, types, log levels, throttle settings, etc.) while allowing
+  * you to override only what you need. Child loggers are independent instances with
+  * their own state (timers, counters, etc.).
+  * @template N - The new custom logger type names
+  * @template LC - The new log level types
+  * @param options Configuration options to override or extend parent settings
+  * @returns A new child logger instance
+  * @example
+  * ```typescript
+  * const parent = createPail({
+  *   logLevel: "info",
+  *   types: { http: { label: "HTTP", logLevel: "info" } },
+  *   reporters: [new PrettyReporter()],
+  * });
+  *
+  * // Child inherits parent settings but overrides log level
+  * const child = parent.child({ logLevel: "debug" });
+  * child.info("This will be logged"); // Uses debug level from child
+  * child.http("GET /api 200"); // Inherits http type from parent
+  *
+  * // Child can add new types
+  * const childWithNewType = parent.child({
+  *   types: { db: { label: "DB", logLevel: "info" } },
+  * });
+  * childWithNewType.db("Query executed"); // New type available
+  * ```
+  */
+  child<N extends string = T, LC extends string = L>(options?: Partial<ConstructorOptions<N, LC>>): PailBrowserType<N, LC>;
+  /**
+  * Starts a timer with the specified label.
+  *
+  * Records the current timestamp and associates it with the given label.
+  * Multiple timers can be active simultaneously with different labels.
+  * @param label The timer label (defaults to "default")
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.time("operation");
+  * // ... some operation ...
+  * logger.timeEnd("operation"); // Logs: "Timer run for: X ms"
+  * ```
+  */
+  time(label?: string): void;
+  /**
+  * Logs the current elapsed time for a timer without stopping it.
+  *
+  * Calculates and logs the time elapsed since the timer was started,
+  * but keeps the timer running. If no label is provided, uses the
+  * most recently started timer.
+  * @param label The timer label (uses last timer if not specified)
+  * @param data Additional data to include in the log message
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.time("task");
+  * // ... some work ...
+  * logger.timeLog("task"); // Logs current elapsed time
+  * // ... more work ...
+  * logger.timeEnd("task"); // Logs final time and stops timer
+  * ```
+  */
+  timeLog(label?: string, ...data: unknown[]): void;
+  /**
+  * Stops a timer and logs the final elapsed time.
+  *
+  * Calculates the total time elapsed since the timer was started,
+  * logs the result, and removes the timer. If no label is provided,
+  * uses the most recently started timer.
+  * @param label The timer label (uses last timer if not specified)
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.time("operation");
+  * // ... perform operation ...
+  * logger.timeEnd("operation"); // Logs: "Timer run for: X ms"
+  * ```
+  */
+  timeEnd(label?: string): void;
+  /**
+  * Starts a log group with the specified label.
+  *
+  * Groups related log messages together. In browser environments,
+  * this uses the native console.group() functionality. In other
+  * environments, it tracks group nesting internally.
+  * @param label The group label (defaults to "console.group")
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.group("Database Operations");
+  * logger.info("Connecting to database");
+  * logger.info("Running migration");
+  * logger.groupEnd(); // End the group
+  * ```
+  */
+  group(label?: string): void;
+  /**
+  * Ends the current log group.
+  *
+  * Closes the most recently opened log group. In browser environments,
+  * this uses the native console.groupEnd() functionality.
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.group("Processing");
+  * logger.info("Step 1");
+  * logger.info("Step 2");
+  * logger.groupEnd(); // Closes the "Processing" group
+  * ```
+  */
+  groupEnd(): void;
+  /**
+  * Increments and logs a counter with the specified label.
+  *
+  * Maintains an internal counter for each label and logs the current count
+  * each time it's called. Useful for tracking how many times certain
+  * code paths are executed.
+  * @param label The counter label (defaults to "default")
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.count("requests"); // Logs: "requests: 1"
+  * logger.count("requests"); // Logs: "requests: 2"
+  * logger.count("errors");   // Logs: "errors: 1"
+  * ```
+  */
+  count(label?: string): void;
+  /**
+  * Resets a counter to zero.
+  *
+  * Removes the counter with the specified label, effectively resetting
+  * it to zero. If the counter doesn't exist, logs a warning.
+  * @param label The counter label to reset (defaults to "default")
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.count("requests"); // Logs: "requests: 1"
+  * logger.countReset("requests"); // Resets counter
+  * logger.count("requests"); // Logs: "requests: 1" (starts over)
+  * ```
+  */
+  countReset(label?: string): void;
+  /**
+  * Clears the console output.
+  *
+  * Calls the native console.clear() method to clear all output from
+  * the console. This is a convenience method that wraps the native
+  * console.clear() functionality.
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.info("Some message");
+  * logger.clear(); // Clears the console
+  * ```
+  */
+  clear(): void;
+  /**
+  * Logs a raw message bypassing normal processing.
+  *
+  * Sends a message directly to the raw reporter without going through
+  * the normal logging pipeline (processors, throttling, etc.). This is
+  * useful for logging that needs to bypass all formatting and processing.
+  * @param message The raw message to log
+  * @param arguments_ Additional arguments to include
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.raw("Direct message", { data: "value" });
+  * ```
+  */
+  raw(message: string, ...arguments_: unknown[]): void;
+  protected extendReporter(reporter: Reporter<L>): Reporter<L>;
+  protected registerReporters(reporters: Reporter<L>[]): void;
+  protected registerProcessors(processors: Processor<L>[]): void;
+  protected logger(type: LiteralUnion<DefaultLogTypes, T>, raw: boolean, force: boolean, ...messageObject: unknown[]): void;
+}
+type PailBrowserType<T extends string = string, L extends string = string> = Console & (new <TC extends string = string, LC extends string = string>(options?: ConstructorOptions<TC, LC>) => PailBrowserType<TC, LC>) & PailBrowserImpl<T, L> & Record<DefaultLogTypes, LoggerFunction> & Record<T, LoggerFunction> & {
+  force: Record<DefaultLogTypes, LoggerFunction> & Record<T, LoggerFunction>;
+};
 /**
- * Default Pail logger instance for browser environments.
- *
- * A pre-configured logger instance ready for immediate use in browser environments.
- * Uses default configuration with JSON reporter and message formatter processor.
- * @example
- * ```typescript
- * import { pail } from "@visulima/pail";
- *
- * pail.info("Application started");
- * pail.error("Something went wrong", new Error("Test error"));
- * ```
- */
-export declare const pail: PailBrowserType;
-export type { PailErrorOptions } from "./error.d.ts";
-export { createPailError, PailError } from "./error.d.ts";
-export type { PailBrowserType as Pail } from "./pail.d.ts";
-export type { ConstructorOptions, DefaultLoggerTypes, DefaultLogTypes, ExtendedRfc5424LogLevels, LoggerConfiguration, LoggerFunction, LoggerTypesAwareReporter, LoggerTypesConfig, Processor, Reporter, StreamAwareReporter, } from "./types.d.ts";
+* Options for creating a PailError.
+*
+* Extends standard error properties with self-documenting fields
+* that provide actionable context for debugging, particularly useful
+* for AI-assisted log analysis.
+*/
+interface PailErrorOptions {
+  /** The root cause of this error */
+  cause?: unknown;
+  /** A suggested resolution or steps to fix the issue */
+  fix?: string;
+  /** A link to relevant documentation or issue tracker */
+  link?: string;
+  /** The error message */
+  message: string;
+  /** HTTP status code associated with this error */
+  status?: number;
+  /** An explanation of what caused the failure */
+  why?: string;
+}
+/**
+* Self-documenting error class for structured logging.
+*
+* Inspired by evlog's structured error approach, PailError extends the native
+* Error class with additional fields that make log entries immediately actionable:
+* - `why`: Explains what caused the failure
+* - `fix`: Suggests how to resolve the issue
+* - `link`: Points to relevant documentation
+* - `status`: HTTP status code for request-related errors
+*
+* These fields are preserved through the logging pipeline and displayed by reporters,
+* making it easier for both humans and AI agents to understand and resolve issues.
+* @example
+* ```typescript
+* import { PailError, createPailError } from "@visulima/pail/error";
+*
+* // Using the class directly
+* throw new PailError({
+*   message: "Payment processing failed",
+*   status: 402,
+*   why: "The customer's card was declined by the payment provider",
+*   fix: "Retry with a different payment method or contact the card issuer",
+*   link: "https://docs.example.com/payments/declined",
+* });
+*
+* // Using the factory function
+* throw createPailError("Connection timeout");
+*
+* // With full options
+* throw createPailError({
+*   message: "Database connection failed",
+*   why: "Connection pool exhausted after 30s timeout",
+*   fix: "Increase pool size or check for connection leaks",
+* });
+* ```
+*/
+declare class PailError extends Error {
+  /** HTTP status code (defaults to 500) */
+  readonly status: number;
+  /** Explanation of what caused the failure */
+  readonly why: string | undefined;
+  /** Suggested resolution steps */
+  readonly fix: string | undefined;
+  /** Link to relevant documentation */
+  readonly link: string | undefined;
+  constructor(options: PailErrorOptions | string);
+  /**
+  * Converts the error to a JSON-serializable object.
+  *
+  * Includes all self-documenting fields in the output for structured logging.
+  * @returns A plain object representation of the error
+  */
+  toJSON(): Record<string, unknown>;
+  /**
+  * Returns a formatted string representation including self-documenting fields.
+  * @returns Formatted error string with why/fix/link context
+  */
+  override toString(): string;
+}
+/**
+* Factory function for creating PailError instances.
+*
+* A convenient shorthand for creating PailError objects. Accepts either
+* a string message or a full PailErrorOptions object.
+* @param options Error message string or PailErrorOptions object
+* @returns A new PailError instance
+* @example
+* ```typescript
+* import { createPailError } from "@visulima/pail/error";
+*
+* throw createPailError("Something went wrong");
+*
+* throw createPailError({
+*   message: "Auth failed",
+*   status: 401,
+*   why: "Token expired",
+*   fix: "Refresh the authentication token",
+* });
+* ```
+*/
+declare const createPailError: (options: PailErrorOptions | string) => PailError;
+/**
+* Creates a new Pail logger instance configured for browser environments.
+*
+* This factory function creates a browser-compatible logger with default processors
+* and reporters suitable for client-side logging.
+* @template T - Custom logger types
+* @template L - Log level types
+* @param options Configuration options for the logger
+* @returns A new PailBrowser instance
+* @example
+* ```typescript
+* import { createPail } from "@visulima/pail";
+*
+* const logger = createPail({
+*   logLevel: "debug",
+*   types: {
+*     custom: {
+*       color: "blue",
+*       label: "CUSTOM",
+*       logLevel: "info"
+*     }
+*   }
+* });
+*
+* logger.info("Hello world!");
+* logger.custom("Custom message");
+* ```
+*/
+declare const createPail: <T extends string = string, L extends string = string>(options?: ConstructorOptions<T, L>) => PailBrowserType<T, L>;
+/**
+* Default Pail logger instance for browser environments.
+*
+* A pre-configured logger instance ready for immediate use in browser environments.
+* Uses default configuration with JSON reporter and message formatter processor.
+* @example
+* ```typescript
+* import { pail } from "@visulima/pail";
+*
+* pail.info("Application started");
+* pail.error("Something went wrong", new Error("Test error"));
+* ```
+*/
+declare const pail: PailBrowserType;
+export { type ConstructorOptions, type DefaultLogTypes, type ExtendedRfc5424LogLevels, type LoggerFunction, type LoggerTypesConfig, type PailBrowserType as Pail, PailError, type PailErrorOptions, type Processor, type Reporter, createPail, createPailError, pail };