@visulima/cerebro 3.0.0-alpha.9 → 3.0.1

package/dist/logger/create-pail-logger.d.ts

@@ -1,8 +1,770 @@
-import type { ConstructorOptions, PailServerType } from "@visulima/pail";
-/**
- * Create a Pail logger.
- * @param options Optional configuration options for the logger
- * @returns A configured Pail logger instance
- */
-declare const createPailLogger: (options?: Partial<ConstructorOptions<string, string>>) => PailServerType<string, string>;
-export default createPailLogger;
+import { InteractiveManager } from '@visulima/interactive-manager';
+import { LiteralUnion, Primitive } from 'type-fest';
+import { AnsiColors } from '@visulima/colorize';
+/**
+* Global namespace for extending Pail's metadata interface.
+*
+* This global declaration allows other packages and applications to extend
+* the Meta interface with custom properties by declaring additional properties
+* in the VisulimaPail.CustomMeta interface.
+* @example
+* ```typescript
+* declare global {
+*   namespace VisulimaPail {
+*     interface CustomMeta<L> {
+*       userId?: string;
+*       requestId?: string;
+*     }
+*   }
+* }
+* ```
+*/
+declare global {
+  namespace VisulimaPail {
+    interface CustomMeta<L> {}
+  }
+}
+/**
+* Metadata object containing all information about a log entry.
+*
+* This interface defines the structure of metadata that is passed to reporters
+* and processors. It contains all the contextual information about a log message
+* including the message itself, timing information, error details, and more.
+* @template L - The log level type
+*/
+interface Meta<L> extends VisulimaPail.CustomMeta<L> {
+  badge: string | undefined;
+  context: any[] | undefined;
+  date: Date | string;
+  error: Error | undefined;
+  groups: string[];
+  label: string | undefined;
+  message: Primitive | ReadonlyArray<unknown> | Record<PropertyKey, unknown>;
+  prefix: string | undefined;
+  repeated?: number;
+  scope: string[] | undefined;
+  suffix: string | undefined;
+  traceError: Error | undefined;
+  type: {
+    level: ExtendedRfc5424LogLevels | L;
+    name: string;
+  };
+}
+/**
+* Extended RFC 5424 Log Levels.
+*
+* Standard syslog severity levels as defined in RFC 5424, plus additional
+* levels commonly used in modern applications. Each level has a numeric
+* priority where lower numbers indicate higher severity.
+* @see https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1
+*/
+type ExtendedRfc5424LogLevels = "alert" | "critical" | "debug" | "emergency" | "error" | "informational" | "notice" | "trace" | "warning";
+/**
+* Default Log Types.
+*
+* Predefined semantic log types that provide meaningful categorization
+* for different kinds of log messages. Each type has associated styling
+* and log level configuration.
+*/
+type DefaultLogTypes = "alert" | "await" | "complete" | "critical" | "debug" | "emergency" | "error" | "info" | "log" | "notice" | "pending" | "start" | "stop" | "success" | "trace" | "wait" | "warn" | "warning" | "watch";
+/**
+* Logger Function Type.
+*
+* Represents a logging function that can accept either a structured Message object
+* or multiple arguments in the traditional console.log style.
+*/
+interface LoggerFunction {
+  (message: Message): void;
+  (...message: any[]): void;
+}
+/**
+* Logger Configuration.
+*
+* Configuration object that defines how a specific logger type should behave,
+* including its visual appearance and log level.
+* @template L - The log level type
+*/
+interface LoggerConfiguration<L extends string> {
+  badge?: string;
+  color?: AnsiColors;
+  label: string;
+  logLevel: LiteralUnion<ExtendedRfc5424LogLevels, L>;
+}
+/**
+* Logger Types Configuration.
+*
+* A record mapping logger type names to their configurations.
+* @template T - Custom logger type names
+* @template L - Log level types
+*/
+type LoggerTypesConfig<T extends string, L extends string> = Record<T, Partial<LoggerConfiguration<L>>>;
+/**
+* Default Logger Types Configuration.
+*
+* A complete mapping of all default log types to their full configurations.
+* @template L - Log level types
+*/
+
+/**
+* Read-only Metadata.
+*
+* Immutable version of the Meta interface for use in reporters.
+* @template L - The log level type
+*/
+type ReadonlyMeta<L extends string> = Readonly<Meta<L>>;
+/**
+* Reporter Interface.
+*
+* Base interface for all reporters. Reporters are responsible for
+* outputting log messages to various destinations (console, files, etc.).
+* @template L - The log level type
+*/
+interface Reporter<L extends string> {
+  log: (meta: ReadonlyMeta<L>) => void;
+}
+/**
+* Stream-Aware Reporter Interface.
+*
+* Extends Reporter with the ability to work with Node.js streams.
+* Used for server-side reporters that need to write to stdout/stderr.
+* @template L - The log level type
+*/
+
+/**
+* Processor Interface.
+*
+* Base interface for all processors. Processors can modify or enhance
+* log metadata before it reaches reporters.
+* @template L - The log level type
+*/
+interface Processor<L extends string> {
+  /** Process the log metadata */
+  process: (meta: Meta<L>) => Meta<L>;
+}
+interface ConstructorOptions<T extends string, L extends string> {
+  disabled?: boolean;
+  logLevel?: LiteralUnion<ExtendedRfc5424LogLevels, L>;
+  logLevels?: Partial<Record<ExtendedRfc5424LogLevels, number>> & Record<L, number>;
+  messages?: {
+    timerEnd?: string;
+    timerStart?: string;
+  };
+  processors?: Processor<L>[];
+  rawReporter?: Reporter<L>;
+  reporters?: Reporter<L>[];
+  scope?: string[] | string;
+  throttle?: number;
+  throttleMin?: number;
+  types?: LoggerTypesConfig<T, L> & Partial<LoggerTypesConfig<DefaultLogTypes, L>>;
+}
+interface ServerConstructorOptions<T extends string, L extends string> extends ConstructorOptions<T, L> {
+  interactive?: boolean;
+  stderr: NodeJS.WriteStream;
+  stdout: NodeJS.WriteStream;
+}
+type Message = {
+  context?: any[];
+  message: any;
+  prefix?: string;
+  suffix?: string;
+};
+type Replacer = (number | string)[] | null | undefined | ((key: string, value: unknown) => string | number | boolean | null | object);
+declare function stringify(value: undefined | symbol | ((...args: unknown[]) => unknown), replacer?: Replacer, space?: string | number): undefined;
+declare function stringify(value: string | number | unknown[] | null | boolean | object, replacer?: Replacer, space?: string | number): string;
+declare function stringify(value: unknown, replacer?: ((key: string, value: unknown) => unknown) | (number | string)[] | null | undefined, space?: string | number): string | undefined;
+declare namespace stringify {
+  export function configure(options: StringifyOptions): typeof stringify;
+}
+interface StringifyOptions {
+  bigint?: boolean;
+  circularValue?: string | null | TypeErrorConstructor | ErrorConstructor;
+  deterministic?: boolean | ((a: string, b: string) => number);
+  maximumBreadth?: number;
+  maximumDepth?: number;
+  strict?: boolean;
+}
+/**
+* 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 readonly lastLog: {
+    count?: number;
+    object?: Meta<L>;
+    signature?: string;
+    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;
+  /**
+  * Removes the global exception/rejection handlers installed by {@link wrapException}.
+  *
+  * Counterpart to `wrapException()` (mirrors `wrapConsole()`/`restoreConsole()`).
+  * Safe to call when no handlers are installed.
+  * @example
+  * ```typescript
+  * const logger = createPail();
+  * logger.wrapException();
+  * // ... later ...
+  * logger.restoreException(); // global handlers removed
+  * ```
+  */
+  restoreException(): 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>;
+};
+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>);
+  override 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
+  * ```
+  */
+  override 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
+  * ```
+  */
+  override clear(): void;
+  protected override extendReporter(reporter: Reporter<L>): Reporter<L>;
+}
+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>;
+};
+/**
+* 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.
+*/
+/**
+* Create a Pail logger.
+* @param options Optional configuration options for the logger
+* @returns A configured Pail logger instance
+*/
+declare const createPailLogger: (options?: Partial<ConstructorOptions<string, string>>) => PailServerType;
+export { createPailLogger as default };