@nowarajs/logger/dist/logger.d.ts

Type-safe logging library for Bun with advanced TypeScript body intersection, modular sink pattern, transform streams, and immutable API design.

import { TypedEventEmitter } from '@nowarajs/typed-event-emitter';
import type { LoggerEvent } from './events/logger-events';
import type { LoggerOptions } from './types/logger-options';
import type { LoggerSink } from './types/logger-sink';
import type { SinkBodiesIntersection } from './types/sink-bodies-intersection';
import type { SinkMap } from './types/sink-map';
export declare class Logger<TSinks extends SinkMap = {}> extends TypedEventEmitter<LoggerEvent> {
    /**
     * Map of registered sinks (logging destinations)
     */
    private readonly _sinks;
    /**
     * List of registered sink keys for quick access
     */
    private readonly _sinkKeys;
    /**
     * Worker instance handling log processing
     */
    private readonly _worker;
    /**
     * Maximum number of pending log messages allowed in the queue
     */
    private readonly _maxPendingLogs;
    /**
     * Maximum number of messages in flight to the worker
     */
    private readonly _maxMessagesInFlight;
    /**
     * Number of logs to batch before sending to worker
     */
    private readonly _batchSize;
    /**
     * Timeout in milliseconds before flushing incomplete batch
     */
    private readonly _batchTimeout;
    /**
     * Whether to auto flush and close on process exit
     */
    private readonly _autoEnd;
    /**
     * Whether to flush before process exit
     */
    private readonly _flushOnBeforeExit;
    /**
     * Queue of pending log messages
     */
    private readonly _pendingLogs;
    /**
     * Number of log messages currently being processed by the worker
     */
    private _messagesInFlight;
    /**
     * Timer for batching log messages
     */
    private _batchTimer;
    /**
     * Whether the logger is currently writing log messages to the worker
     */
    private _isWriting;
    /**
     * Resolvers for flush promises
     */
    private readonly _flushResolvers;
    /**
     * Resolver for the close promise
     */
    private _closeResolver;
    /**
     * Resolver for backpressure when maxMessagesInFlight is reached
     */
    private _backpressureResolver;
    /**
     * Handle the exit event
     */
    private readonly _handleExit;
    /**
     * Handle the worker close event
     */
    private readonly _handleWorkerClose;
    /**
     * Creates a new Logger instance with the specified options.
     *
     * @param options - Configuration options for the logger
     */
    constructor(options?: LoggerOptions);
    /**
     * Registers a new sink (logging destination) with the logger.
     *
     * @param sinkName - The name of the sink
     * @param sinkConstructor - The sink class constructor
     * @param sinkArgs - The sink constructor arguments
     *
     * @returns The logger instance with new type (for chaining)
     */
    registerSink<TSinkName extends string, TSink extends LoggerSink, TSinkArgs extends unknown[]>(sinkName: TSinkName, sinkConstructor: new (...args: TSinkArgs) => TSink, ...sinkArgs: TSinkArgs): Logger<TSinks & Record<TSinkName, new (...args: TSinkArgs) => TSink>>;
    /**
     * Logs a message at the ERROR level to the specified sinks.
     *
     * @param object - The log message object
     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
     */
    error<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
    /**
     * Logs a message at the WARN level to the specified sinks.
     *
     * @param object - The log message object
     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
     */
    warn<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
    /**
     * Logs a message at the INFO level to the specified sinks.
     *
     * @param object - The log message object
     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
     */
    info<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
    /**
     * Logs a message at the DEBUG level to the specified sinks.
     *
     * @param object - The log message object
     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
     */
    debug<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
    /**
     * Logs a message at the TRACE level to the specified sinks.
     *
     * @param object - The log message object
     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
     */
    log<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
    /**
     * Flushes all pending logs and waits for them to be processed.
     */
    flush(): Promise<void>;
    /**
     * Closes the logger, flushes pending logs, and releases resources.
     */
    close(): Promise<void>;
    /**
     * Enqueues a log message to be processed by the worker.
     *
     * @param level - The log level
     * @param object - The log message object
     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
     */
    private _enqueue;
    /**
     * Triggers processing of pending logs.
     */
    private _triggerProcessing;
    /**
     * Processes pending log messages by sending them to the worker in batches.
     */
    private _processPendingLogs;
    /**
     * Releases a batch by decrementing the in-flight counter and resolving backpressure if needed.
     */
    private _releaseBatch;
    /**
     * Sets up message handling for the worker.
     */
    private _setupWorkerMessages;
    /**
     * Sets up automatic flushing and closing of the logger on process exit.
     */
    private _setupAutoEnd;
    /**
     * Handles the beforeExit event.
     */
    private readonly _handleBeforeExit;
}