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

package/dist/packem_shared/wide-event.d-B-t8ZnhI.d.ts

@@ -0,0 +1,704 @@
+import { stringify } from 'safe-stable-stringify';
+import { M as Meta, D as DefaultLogTypes, L as LiteralUnion, c as LoggerTypesConfig, P as Processor, E as ExtendedRfc5424LogLevels, d as Reporter, e as LoggerFunction, C as ConstructorOptions } from "./types.d-BeLumqgD.js";
+/**
+* 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>;
+};
+/**
+* A pail instance with dynamically generated log methods.
+* This is the minimal interface WideEvent needs from a pail logger.
+*/
+type PailLike<T extends string = string> = PailBrowserImpl<T> & Record<DefaultLogTypes | T, LoggerFunction>;
+/**
+* Makes all properties in T optional recursively.
+*/
+type DeepPartial<T> = { [K in keyof T]?: T[K] extends Record<string, unknown> ? DeepPartial<T[K]> : T[K] };
+/**
+* Severity levels for wide events.
+*/
+type WideEventLevel = "debug" | "error" | "info" | "warn";
+/**
+* An entry in the request lifecycle log.
+*/
+interface RequestLogEntry {
+  /**
+  * Additional structured context for this log entry.
+  */
+  context?: Record<string, unknown>;
+  /**
+  * Severity level of this entry.
+  */
+  level: WideEventLevel;
+  /**
+  * Human-readable message describing what happened.
+  */
+  message: string;
+  /**
+  * ISO 8601 timestamp of when this entry was recorded.
+  */
+  timestamp: string;
+}
+/**
+* Serialized error information included in the emitted wide event.
+*/
+interface SerializedError {
+  cause?: SerializedError;
+  data?: unknown;
+  message: string;
+  name: string;
+  stack?: string;
+  status?: number;
+}
+/**
+* Options for finishing a wide event with HTTP context.
+*/
+interface WideEventFinishOptions {
+  /**
+  * An error that occurred during the operation.
+  * Will be serialized and included in the emitted event.
+  */
+  error?: Error;
+  /**
+  * HTTP response status code.
+  */
+  status?: number;
+}
+/**
+* Options for creating a WideEvent instance.
+* @template T - Custom logger type names
+*/
+interface WideEventOptions<T extends string = string> {
+  /**
+  * Auto-emit the event when disposed via `Symbol.dispose`.
+  * Works with TC39 Explicit Resource Management (`using`).
+  * @default true
+  */
+  autoEmit?: boolean;
+  /**
+  * Event name identifying this wide event, e.g. "api.checkout", "worker.send-email".
+  */
+  name: string;
+  /**
+  * The pail logger instance to use for emission.
+  */
+  pail: PailLike<T>;
+  /**
+  * Service name for this event. Overrides any service name from pail's scope.
+  */
+  service?: string;
+  /**
+  * Base log type to use when emitting. Defaults to "info".
+  * The actual type may be escalated based on logged warnings/errors.
+  */
+  type?: DefaultLogTypes | T;
+}
+/**
+* A wide event logger that accumulates context incrementally and emits
+* a single comprehensive log event through pail.
+*
+* Instead of scattering multiple log calls throughout an operation,
+* use `set()` to build up context as information becomes available,
+* then emit once at the end. Lifecycle methods (`info()`, `warn()`, `error()`,
+* `debug()`) record timestamped entries in a `requestLogs` array and
+* automatically escalate the event's severity level.
+*
+* Implements `Disposable` for use with TC39 Explicit Resource Management.
+* @template TData - Shape of the accumulated event data
+* @template T - Custom logger type names from the pail instance
+* @example
+* ```typescript
+* // Manual finish
+* const ev = createWideEvent({ pail: logger, name: "api.checkout" });
+* ev.set({ user: { id: 1 } });
+* ev.info("Validated cart");
+* ev.set({ cart: { items: 3, total: 9999 } });
+* ev.finish({ status: 200 });
+*
+* // Auto-emit with Explicit Resource Management
+* using ev = createWideEvent({ pail: logger, name: "api.checkout" });
+* ev.set({ user: { id: 1 } });
+* // emits automatically when scope exits
+*
+* // Typed data shape
+* interface CheckoutData {
+*   user: { id: number; plan: string };
+*   cart: { items: number; total: number };
+* }
+* const ev = createWideEvent<CheckoutData>({ pail: logger, name: "api.checkout" });
+* ev.set({ user: { id: 1, plan: "pro" } }); // fully typed
+* ```
+*/
+declare class WideEvent<TData extends Record<string, unknown> = Record<string, unknown>, T extends string = string> implements Disposable {
+  readonly name: string;
+  private readonly autoEmit;
+  private data;
+  private emitted;
+  private attachedError?;
+  private level;
+  private readonly pail;
+  private readonly requestLogs;
+  private readonly service;
+  private readonly startTime;
+  private status;
+  private readonly timestamp;
+  private readonly _type;
+  constructor(options: WideEventOptions<T>);
+  /**
+  * Record a debug-level lifecycle log entry.
+  * Does not escalate the event level.
+  * @param message Description of what happened
+  * @param context Optional structured context
+  * @returns `this` for chaining
+  */
+  debug(message: string, context?: Record<string, unknown>): this;
+  /**
+  * Emit the wide event through the pail logger. Can only be called once;
+  * subsequent calls are no-ops.
+  *
+  * Automatically calculates duration, determines the log type based on
+  * the highest severity level reached, and serializes any attached error.
+  *
+  * Prefer `finish()` for HTTP request contexts where you have a status code.
+  * @param typeOverride Override the log type for this emission
+  */
+  emit(typeOverride?: DefaultLogTypes | T): void;
+  /**
+  * Record an error-level lifecycle log entry and attach the error.
+  * Escalates the event level to "error".
+  * @param message Description of what went wrong
+  * @param error The error that occurred
+  * @param context Optional structured context
+  * @returns `this` for chaining
+  */
+  error(message: string, error?: Error, context?: Record<string, unknown>): this;
+  /**
+  * Finish and emit the wide event with HTTP context.
+  * Sets the response status and optional error before emitting.
+  * @example
+  * ```typescript
+  * ev.finish({ status: 200 });
+  * ev.finish({ status: 500, error: new Error("DB timeout") });
+  * ```
+  * @param options Status code and/or error
+  */
+  finish(options?: WideEventFinishOptions): void;
+  /**
+  * Get a read-only snapshot of the accumulated data.
+  */
+  getData(): Readonly<TData>;
+  /**
+  * Get the current severity level of the event.
+  * The level auto-escalates as `warn()` or `error()` entries are added.
+  */
+  getLevel(): WideEventLevel;
+  /**
+  * Get a read-only copy of the request lifecycle log entries.
+  */
+  getRequestLogs(): ReadonlyArray<RequestLogEntry>;
+  /**
+  * Record an info-level lifecycle log entry.
+  * Does not escalate the event level.
+  * @param message Description of what happened
+  * @param context Optional structured context
+  * @returns `this` for chaining
+  */
+  info(message: string, context?: Record<string, unknown>): this;
+  /**
+  * Accumulate context into the wide event via deep merge.
+  * Call as many times as needed throughout the operation.
+  * @example
+  * ```typescript
+  * ev.set({ user: { id: 1 } });
+  * ev.set({ user: { plan: "pro" } });
+  * // data = { user: { id: 1, plan: "pro" } }
+  * ```
+  * @param data Partial data to merge into the event
+  * @returns `this` for chaining
+  */
+  set(data: DeepPartial<TData>): this;
+  /**
+  * Attach an error to the event. Automatically escalates the event
+  * level to "error".
+  * @param error The error to attach
+  * @returns `this` for chaining
+  */
+  setError(error: Error): this;
+  /**
+  * Set the HTTP response status code.
+  * @param status HTTP status code
+  * @returns `this` for chaining
+  */
+  setStatus(status: number): this;
+  /**
+  * Record a warn-level lifecycle log entry.
+  * Escalates the event level to "warn" (unless already "error").
+  * @param message Description of the warning
+  * @param context Optional structured context
+  * @returns `this` for chaining
+  */
+  warn(message: string, context?: Record<string, unknown>): this;
+  /**
+  * Disposable implementation. Auto-emits the event if `autoEmit` is true
+  * and the event hasn't been manually emitted yet.
+  *
+  * Enables usage with TC39 Explicit Resource Management:
+  * ```typescript
+  * using ev = createWideEvent({ pail: logger, name: "api.checkout" });
+  * ev.set({ user: { id: 1 } });
+  * // auto-emits here when scope exits
+  * ```
+  */
+  [Symbol.dispose](): void;
+  /**
+  * Add an entry to the request lifecycle log and escalate level if needed.
+  */
+  private addLogEntry;
+  /**
+  * Escalate the event level if the new level has higher severity.
+  */
+  private escalateLevel;
+}
+/**
+* Create a wide event logger that accumulates context and emits a single
+* comprehensive log event through pail.
+* @template TData - Shape of the accumulated event data
+* @template T - Custom logger type names from the pail instance
+* @param options Configuration options
+* @returns A new WideEvent instance
+* @example
+* ```typescript
+* import { createPail } from "@visulima/pail";
+* import { createWideEvent } from "@visulima/pail/wide-event";
+*
+* const logger = createPail();
+*
+* // In a request handler:
+* const ev = createWideEvent({ pail: logger, name: "api.checkout" });
+*
+* ev.set({ user: { id: 1, plan: "pro" } });
+* ev.info("Validated cart", { itemCount: 3 });
+* ev.set({ cart: { id: 42, items: 3, total: 9999 } });
+* ev.info("Payment processed");
+* ev.finish({ status: 200 });
+*
+* // Emits a single structured log:
+* // {
+* //   event: "api.checkout",
+* //   timestamp: "2025-01-24T10:23:45.612Z",
+* //   duration: "127ms",
+* //   duration_ms: 127,
+* //   status: 200,
+* //   user: { id: 1, plan: "pro" },
+* //   cart: { id: 42, items: 3, total: 9999 },
+* //   requestLogs: [
+* //     { level: "info", message: "Validated cart", timestamp: "...", context: { itemCount: 3 } },
+* //     { level: "info", message: "Payment processed", timestamp: "..." }
+* //   ]
+* // }
+* ```
+*/
+declare const createWideEvent: <TData extends Record<string, unknown> = Record<string, unknown>, T extends string = string>(options: WideEventOptions<T>) => WideEvent<TData, T>;
+export { PailBrowserImpl as P, RequestLogEntry as R, SerializedError as S, WideEvent as W, WideEventFinishOptions as a, WideEventLevel as b, WideEventOptions as c, createWideEvent as d };