@visulima/pail 3.2.0 → 3.2.2

package/dist/pail.browser.d.ts

@@ -0,0 +1,412 @@
+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: any[]): 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

@@ -0,0 +1,233 @@
+import InteractiveManager from "./interactive/interactive-manager.d.ts";
+import { PailBrowserImpl } from "./pail.d.ts";
+import type { MultiBarOptions, SingleBarOptions } from "./progress-bar.d.ts";
+import { MultiProgressBar, ProgressBar } from "./progress-bar.d.ts";
+import type { SpinnerOptions } from "./spinner.d.ts";
+import { MultiSpinner, Spinner } from "./spinner.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;
+    /**
+     * Creates a single progress bar.
+     * @param options Configuration options for the progress bar
+     * @returns A new ProgressBar instance
+     * @example
+     * ```typescript
+     * const logger = createPail({ interactive: true });
+     * const bar = logger.createProgressBar({
+     *   total: 100,
+     *   format: 'Downloading [{bar}] {percentage}% | ETA: {eta}s | {value}/{total}'
+     * });
+     *
+     * bar.start();
+     * // ... do work and update progress
+     * bar.update(50);
+     * bar.stop();
+     * ```
+     */
+    createProgressBar(options: SingleBarOptions): ProgressBar;
+    /**
+     * Creates a multi-bar progress manager for displaying multiple progress bars.
+     * @param options Configuration options for the multi-bar manager
+     * @returns A new MultiProgressBar instance
+     * @example
+     * ```typescript
+     * const logger = createPail({ interactive: true });
+     * const multiBar = logger.createMultiProgressBar();
+     *
+     * const bar1 = multiBar.create(100);
+     * const bar2 = multiBar.create(200);
+     *
+     * bar1.start();
+     * bar2.start();
+     * // ... update bars as needed
+     * multiBar.stop();
+     * ```
+     */
+    createMultiProgressBar(options?: MultiBarOptions): MultiProgressBar;
+    /**
+     * Creates a single spinner.
+     * @param options Configuration options for the spinner
+     * @returns A new Spinner instance
+     * @example
+     * ```typescript
+     * const logger = createPail({ interactive: true });
+     * const spinner = logger.createSpinner({ name: 'dots' });
+     * spinner.start('Loading...');
+     * // ... do work
+     * spinner.succeed('Done');
+     * ```
+     */
+    createSpinner(options?: SpinnerOptions): Spinner;
+    /**
+     * Creates a multi-spinner manager for displaying multiple spinners.
+     * @param options Configuration options for the multi-spinner manager
+     * @returns A new MultiSpinner instance
+     * @example
+     * ```typescript
+     * const logger = createPail({ interactive: true });
+     * const multiSpinner = logger.createMultiSpinner();
+     *
+     * const spinner1 = multiSpinner.create('Loading 1');
+     * const spinner2 = multiSpinner.create('Loading 2');
+     *
+     * spinner1.start();
+     * spinner2.start();
+     * // ... update spinners as needed
+     * multiSpinner.stop();
+     * ```
+     */
+    createMultiSpinner(options?: SpinnerOptions): MultiSpinner;
+    /**
+     * 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 {};