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

package/dist/pail.browser.d.ts

@@ -1,412 +0,0 @@
-import type { stringify } from "safe-stable-stringify";
-import type { LiteralUnion } from "type-fest";
-import type { ConstructorOptions, DefaultLogTypes, ExtendedRfc5424LogLevels, LoggerFunction, LoggerTypesConfig, Meta, Processor, Reporter } from "./types.d.ts";
-/**
- * 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);
- * ```
- */
-export 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;
-}
-export 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>;
-};
-export type PailConstructor<T extends string = string, L extends string = string> = new (options?: ConstructorOptions<T, L>) => PailBrowserType<T, L>;
-export declare const PailBrowser: PailBrowserType;

package/dist/pail.server.d.ts

@@ -1,158 +0,0 @@
-import { InteractiveManager } from "@visulima/interactive-manager";
-import { PailBrowserImpl } from "./pail.d.ts";
-import type { ConstructorOptions, DefaultLogTypes, LoggerFunction, Reporter, ServerConstructorOptions } from "./types.d.ts";
-declare class PailServerImpl<T extends string = string, L extends string = string> extends PailBrowserImpl<T, L> {
-    #private;
-    readonly options: ServerConstructorOptions<T, L>;
-    protected readonly stdout: NodeJS.WriteStream;
-    protected readonly stderr: NodeJS.WriteStream;
-    protected interactiveManager: InteractiveManager | undefined;
-    protected readonly interactive: boolean;
-    /**
-     * Creates a new Pail server logger instance.
-     *
-     * Initializes the server-compatible logger with streams, interactive support,
-     * and server-specific configuration options.
-     * @param options Server-specific configuration options
-     */
-    constructor(options: ServerConstructorOptions<T, L>);
-    scope<N extends string = T>(...name: string[]): PailServerType<N, L>;
-    /**
-     * 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>> & Partial<Pick<ServerConstructorOptions<N, LC>, "interactive" | "stderr" | "stdout">>): PailServerType<N, LC>;
-    /**
-     * Gets the interactive manager instance if interactive mode is enabled.
-     *
-     * Returns the InteractiveManager instance that handles interactive terminal
-     * features like progress bars and dynamic updates. Only available when
-     * interactive mode is enabled in the constructor options.
-     * @returns The interactive manager instance, or undefined if not in interactive mode
-     * @example
-     * ```typescript
-     * const logger = createPail({ interactive: true });
-     * const manager = logger.getInteractiveManager();
-     * if (manager) {
-     *   manager.hook();
-     *   // Use interactive features
-     *   manager.unhook();
-     * }
-     * ```
-     */
-    getInteractiveManager(): InteractiveManager | undefined;
-    /**
-     * Wraps stdout and stderr streams to redirect them through the logger.
-     *
-     * Intercepts writes to process.stdout and process.stderr, redirecting them
-     * through the logger instead of writing directly to the streams. This allows
-     * all output to be processed by the logging pipeline.
-     * @example
-     * ```typescript
-     * const logger = createPail();
-     * logger.wrapStd();
-     *
-     * console.log("This goes through logger");
-     * process.stdout.write("This too");
-     *
-     * logger.restoreStd(); // Restore original streams
-     * ```
-     */
-    wrapStd(): void;
-    /**
-     * Restores the original stdout and stderr streams.
-     *
-     * Removes the stream wrapping that was applied by wrapStd(),
-     * restoring the original stream write methods.
-     * @example
-     * ```typescript
-     * const logger = createPail();
-     * logger.wrapStd();
-     * // Streams are wrapped
-     * logger.restoreStd();
-     * // Streams are restored to original behavior
-     * ```
-     */
-    restoreStd(): void;
-    /**
-     * Wraps all output sources (console and streams).
-     *
-     * Convenience method that calls both wrapConsole() and wrapStd()
-     * to redirect all output through the logger.
-     * @example
-     * ```typescript
-     * const logger = createPail();
-     * logger.wrapAll(); // Wraps console and streams
-     *
-     * // All output now goes through logger
-     * console.log("Console output");
-     * process.stdout.write("Stream output");
-     *
-     * logger.restoreAll(); // Restore everything
-     * ```
-     */
-    wrapAll(): void;
-    /**
-     * Restores all wrapped output sources.
-     *
-     * Convenience method that calls both restoreConsole() and restoreStd()
-     * to restore all original output behavior.
-     * @example
-     * ```typescript
-     * const logger = createPail();
-     * logger.wrapAll();
-     * // All output is wrapped
-     * logger.restoreAll();
-     * // All output sources are restored
-     * ```
-     */
-    restoreAll(): void;
-    /**
-     * Clears the terminal screen.
-     *
-     * Sends ANSI escape sequences to clear the terminal screen and move
-     * the cursor to the top-left position. This overrides the browser
-     * implementation to work with terminal streams.
-     * @example
-     * ```typescript
-     * const logger = createPail();
-     * logger.info("Some output");
-     * logger.clear(); // Clears the terminal screen
-     * ```
-     */
-    clear(): void;
-    protected extendReporter(reporter: Reporter<L>): Reporter<L>;
-}
-export type PailServerType<T extends string = string, L extends string = string> = Console & (new <TC extends string = string, LC extends string = string>(options?: ServerConstructorOptions<TC, LC>) => PailServerType<TC, LC>) & PailServerImpl<T, L> & Record<DefaultLogTypes, LoggerFunction> & Record<T, LoggerFunction> & {
-    force: Record<DefaultLogTypes, LoggerFunction> & Record<T, LoggerFunction>;
-};
-export type PailConstructor<T extends string = string, L extends string = string> = new (options?: ServerConstructorOptions<T, L>) => PailServerType<T, L>;
-export declare const PailServer: PailServerType;
-export {};

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

@@ -1,23 +0,0 @@
-/**
- * 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/reporter/file/utils/rotating-file-stream.d.ts

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

package/dist/reporter/http/utils/compression.d.ts

@@ -1,7 +0,0 @@
-/**
- * Compresses data using gzip compression.
- * @param data The data to compress as a string
- * @returns A Promise that resolves to the compressed data as Uint8Array
- */
-declare const compressData: (data: string) => Promise<Uint8Array>;
-export default compressData;

package/dist/reporter/http/utils/log-size-error.d.ts

@@ -1,30 +0,0 @@
-/**
- * Error thrown when a log entry exceeds the maximum allowed size.
- */
-declare class LogSizeError extends Error {
-    /**
-     * The log entry data that caused the error
-     */
-    readonly logData: Record<string, unknown>;
-    /**
-     * The actual size of the log entry in bytes
-     */
-    readonly actualSize: number;
-    /**
-     * The maximum allowed size in bytes
-     */
-    readonly maxSize: number;
-    /**
-     * Creates a new LogSizeError instance.
-     * @param message Descriptive error message explaining the size violation
-     * @param logData The log entry data that caused the error
-     * @param actualSize Size of the log entry in bytes
-     * @param maxSize Maximum allowed size in bytes
-     * @example
-     * ```typescript
-     * throw new LogSizeError("Log too large", logData, 2000000, 1000000);
-     * ```
-     */
-    constructor(message: string, logData: Record<string, unknown>, actualSize: number, maxSize: number);
-}
-export default LogSizeError;