@visulima/cerebro 3.0.0-alpha.2 → 3.0.0-alpha.21

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

@@ -1,8 +1,779 @@
-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 { stringify } from 'safe-stable-stringify';
+import { AnsiColors } from '@visulima/colorize';
+/**
+Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+
+@category Type
+*/
+type Primitive = null | undefined | string | number | boolean | symbol | bigint;
+/**
+Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
+
+Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
+
+This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as it's not needed anymore.
+
+@example
+```
+import type {LiteralUnion} from 'type-fest';
+
+// Before
+
+type Pet = 'dog' | 'cat' | string;
+
+const petWithoutAutocomplete: Pet = '';
+// Start typing in your TypeScript-enabled IDE.
+// You **will not** get auto-completion for `dog` and `cat` literals.
+
+// After
+
+type Pet2 = LiteralUnion<'dog' | 'cat', string>;
+
+const petWithAutoComplete: Pet2 = '';
+// You **will** get auto-completion for `dog` and `cat` literals.
+```
+
+@category Type
+*/
+type LiteralUnion<LiteralType, BaseType extends Primitive> = LiteralType | (BaseType & Record<never, never>);
+/**
+* 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;
+};
+/**
+* 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>;
+};
+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 };