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

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

import { TypedEventEmitter } from '@nowarajs/typed-event-emitter';
import type { LoggerEvent } from './events/loggerEvents';
import type { BodiesIntersection } from './types/bodiesIntersection';
import type { LoggerStrategy } from './types/loggerStrategy';
import type { StrategyMap } from './types/strategyMap';
/**
 * Logger provides a flexible, type-safe logging system that allows multiple strategies for log output.
 * The logger uses a transform stream to process log entries and execute the logging strategies.
 *
 * Logger extends the TypedEventEmitter class to emit typed events when an error occurs or when the logger ends.
 * The logger can log messages with different levels: error, warn, info, debug, and log.
 *
 * @template TStrategies - The map of strategy names to LoggerStrategy types.
 */
export declare class Logger<TStrategies extends StrategyMap = {}> extends TypedEventEmitter<LoggerEvent> {
    /**
     * The map of strategies.
     */
    private readonly _strategies;
    /**
     * The transform stream for processing log entries.
     */
    private readonly _logStream;
    /**
     * The queue of pending log entries.
     */
    private readonly _pendingLogs;
    /**
     * The maximum number of pending logs.
     * @defaultValue 10_000
     */
    private readonly _maxPendingLogs;
    /**
     * Flag to indicate if the logger is currently writing logs.
     */
    private _isWriting;
    /**
     * Construct a Logger.
     *
     * @template TStrategies - The map of strategy names to LoggerStrategy types.
     *
     * @param strategies - Initial strategies map.
     *
     * @param maxPendingLogs - Maximum number of logs in the queue (default: 10_000)
     */
    constructor(strategies?: TStrategies, maxPendingLogs?: number);
    /**
     * Register a new logging strategy.
     *
     * @template Key - The name of the strategy.
     * @template Strategy - The strategy type.
     *
     * @param name - The name of the strategy.
     * @param strategy - The strategy to add. It must implement {@link LoggerStrategy}.
     *
     * @throws ({@link BaseError}) - If the strategy is already added.
     *
     * @returns A new Logger instance with the added strategy.
     */
    registerStrategy<Key extends string, Strategy extends LoggerStrategy>(name: Key, strategy: Strategy): Logger<TStrategies & Record<Key, Strategy>>;
    /**
     * Unregister a logging strategy.
     *
     * @template Key - The name of the strategy.
     *
     * @param name - The name of the strategy to remove.
     *
     * @throws ({@link BaseError}) - If the strategy is not found.
     *
     * @returns A new Logger instance without the removed strategy.
     */
    unregisterStrategy<Key extends keyof TStrategies>(name: Key): Logger<Omit<TStrategies, Key>>;
    /**
     * Register multiple strategies at once.
     *
     * @template TNew - The new strategies to add.
     *
     * @param strategies - An array of tuples where each tuple contains the strategy name and the strategy instance.
     *
     * @throws ({@link BaseError}) - If any strategy is already added.
     *
     * @returns A new Logger instance with the added strategies.
     */
    registerStrategies<TNew extends [string, LoggerStrategy][] = [string, LoggerStrategy][]>(strategies: TNew): Logger<TStrategies & {
        [K in TNew[number][0]]: Extract<TNew[number], [K, LoggerStrategy]>[1];
    }>;
    /**
     * Unregister multiple strategies at once.
     *
     * @template Keys - The names of the strategies to remove.
     *
     * @param names - An array of strategy names to remove.
     *
     * @throws ({@link BaseError}) - If any strategy is not found.
     *
     * @returns A new Logger instance without the removed strategies.
     */
    unregisterStrategies<Keys extends Extract<keyof TStrategies, string>>(names: Keys[]): Logger<Omit<TStrategies, Keys>>;
    /**
     * Remove all strategies.
     *
     * @returns A new Logger instance without any strategies.
     */
    clearStrategies(): Logger;
    /**
     * Log an error message.
     *
     * @template SNames - The names of the strategies to use.
     *
     * @param object - The object to log.
     * @param strategiesNames - The names of the strategies to use. If not provided, all strategies will be used.
     *
     * @throws ({@link BaseError}) - If no strategy is added.
     */
    error<SNames extends (keyof TStrategies)[] = (keyof TStrategies)[]>(object: BodiesIntersection<TStrategies, SNames[number]>, strategiesNames?: SNames): void;
    /**
     * Log a warning message.
     *
     * @template SNames - The names of the strategies to use.
     *
     * @param object - The object to log.
     * @param strategiesNames - The names of the strategies to use. If not provided, all strategies will be used.
     *
     * @throws ({@link BaseError}) - If no strategy is added.
     */
    warn<SNames extends (keyof TStrategies)[] = (keyof TStrategies)[]>(object: BodiesIntersection<TStrategies, SNames[number]>, strategiesNames?: SNames): void;
    /**
     * Log an info message.
     *
     * @template SNames - The names of the strategies to use.
     *
     * @param object - The object to log.
     * @param strategiesNames - The names of the strategies to use. If not provided, all strategies will be used.
     *
     * @throws ({@link BaseError}) - If no strategy is added.
     */
    info<SNames extends (keyof TStrategies)[] = (keyof TStrategies)[]>(object: BodiesIntersection<TStrategies, SNames[number]>, strategiesNames?: SNames): void;
    /**
     * Log a debug message.
     *
     * @template SNames - The names of the strategies to use.
     *
     * @param object - The object to log.
     * @param strategiesNames - The names of the strategies to use. If not provided, all strategies will be used.
     *
     * @throws ({@link BaseError}) - If no strategy is added.
     */
    debug<SNames extends (keyof TStrategies)[] = (keyof TStrategies)[]>(object: BodiesIntersection<TStrategies, SNames[number]>, strategiesNames?: SNames): void;
    /**
     * Log a generic message.
     *
     * @template SNames - The names of the strategies to use.
     *
     * @param object - The object to log.
     * @param strategiesNames - The names of the strategies to use. If not provided, all strategies will be used.
     *
     * @throws ({@link BaseError}) - If no strategy is added.
     */
    log<SNames extends (keyof TStrategies)[] = (keyof TStrategies)[]>(object: BodiesIntersection<TStrategies, SNames[number]>, strategiesNames?: SNames): void;
    /**
     * Internal: execute all strategies for a log event.
     *
     * @template TLogObject - The type of the log object.
     *
     * @param level - The log level.
     * @param date - The date of the log event.
     * @param object - The object to log.
     * @param strategiesNames - The names of the strategies to use. If not provided, all strategies will be used.
     *
     * @throws ({@link BaseError}) - If a strategy throws.
     */
    private _executeStrategies;
    /**
     * Internal: queue a log event and start writing if not already.
     *
     * @template TLogObject - The type of the log object.
     *
     * @param level - The log level.
     * @param object - The object to log.
     * @param strategiesNames - The names of the strategies to use. If not provided, all strategies will be used.
     *
     * @throws ({@link BaseError}) - If no strategy is added.
     */
    private _out;
    /**
     * Internal: process the log queue and emit 'end' when done.
     */
    private _writeLog;
}