koatty_logger/dist/index.d.ts

Logger for koatty.

/*!
* @Author: richen
* @Date: 2026-04-24 16:20:19
* @License: BSD (3-Clause)
* @Copyright (c) - <richenlin(at)gmail.com>
* @HomePage: https://koatty.org/
*/
import { transports } from 'winston';

export declare interface BatchConfig {
    enabled?: boolean;
    maxSize?: number;
    flushInterval?: number;
    maxWaitTime?: number;
}

export declare const DefaultLogger: Logger;

/**
 * Logger interface
 *
 * @export
 * @interface ILogger
 */
export declare interface ILogger {
    /**
     * log Debug
     *
     * @returns {*}
     * @memberof Logger
     */
    Debug(...args: any[]): void;
    /**
     * log Info
     *
     * @returns {*}
     * @memberof Logger
     */
    Info(...args: any[]): void;
    /**
     * log Warn
     *
     * @returns {*}
     * @memberof Logger
     */
    Warn(...args: any[]): void;
    /**
     * log Error
     *
     * @returns {*}
     * @memberof Logger
     */
    Error(...args: any[]): void;
    /**
     * log Fatal - for critical errors that cause application termination
     * Automatically exits the process after logging
     *
     * @returns {void}
     * @memberof Logger
     */
    Fatal(...args: any[]): void;
    /**
     * log Custom
     *
     * Logger.Log('msg')
     *
     * Logger.Log('name', 'msg')
     *
     * Logger.Log('name', 'msg1', 'msg2'...)
     *
     * @param {...any[]} args
     * @returns {*}
     * @memberof Logger
     */
    Log(...msg: any[]): void;
    Log(name: LogLevelType | string, ...msg: any[]): void;
    Log(name: LogLevelType | string, color: LogColor, ...msg: any[]): void;
    /**
     * Enable or disable logging
     * @param b - boolean flag
     */
    enable(b?: boolean): void;
    /**
     * Get current log level
     */
    getLevel(): LogLevelType;
    /**
     * Set log level
     * @param level - log level
     */
    setLevel(level: LogLevelType): void;
    /**
     * Get current log file path
     */
    getLogFilePath(): string;
    /**
     * Set log file path (with security validation)
     * @param f - file path
     */
    setLogFilePath(f: string): void;
    /**
     * Get sensitive fields
     */
    getSensFields(): Set<string>;
    /**
     * Add sensitive fields
     * @param fields - array of field names
     */
    setSensFields(fields: string[]): void;
    /**
     * Clear all sensitive fields
     */
    clearSensFields(): void;
    /**
     * Reset sensitive fields to specific list
     * @param fields - array of field names
     */
    resetSensFields(fields: string[]): void;
    /**
     * Destroy logger instance and release resources
     */
    destroy(): void;
    /**
     * Enable or disable batch writing
     * @param enabled - whether to enable batch writing
     */
    enableBatch(enabled?: boolean): void;
    /**
     * Set batch writing configuration
     * @param config - batch configuration
     */
    setBatchConfig(config: Partial<BatchConfig>): void;
    /**
     * Get current batch configuration
     */
    getBatchConfig(): BatchConfig;
    /**
     * Get batch writing status
     */
    getBatchStatus(): {
        enabled: boolean;
        bufferSize: number;
        maxSize?: number;
        timeSinceLastFlush: number;
    };
    /**
     * Flush batch buffer immediately
     */
    flushBatch(): Promise<void>;
}

/**
 * Minimal interface for property decorator manager (avoids depending on koatty_container).
 * Pass decoratorManager.property from koatty_container when calling registerLogDecorator.
 */
export declare interface IPropertyDecoratorManagerLike {
    registerWrapper(decoratorType: string, wrapperFunction: (originalDescriptor: PropertyDescriptor | undefined, config: any, propertyName: string, target: any) => PropertyDescriptor): void;
    registerDecorator(target: any, propertyKey: string | symbol, metadata: {
        wrapperTypes: string[];
        config?: any;
    }, originalDescriptor?: PropertyDescriptor): PropertyDescriptor;
}

/**
 * Property decorator: inject a logger instance.
 * - @Log() uses the global DefaultLogger.
 * - @Log(options) uses a dedicated Logger instance with the given options (cached per class+property).
 *
 * Supports both legacy and TC39 field decorator calling conventions.
 * Requires registerLogDecorator(decoratorManager.property) to be called first;
 * otherwise the decorator is a no-op so existing code is not broken.
 *
 * @param options - Optional LoggerOpt for a custom Logger instance
 * @example
 * ```ts
 * registerLogDecorator(decoratorManager.property);
 *
 * class UserController {
 *   \@Log()
 *   logger: any;
 *
 *   \@Log({ logLevel: 'debug' })
 *   debugLogger: any;
 * }
 * ```
 */
export declare function Log(options?: LoggerOpt): (...args: any[]) => void | PropertyDescriptor | ((init: any) => any);

export declare type LogColor = "white" | "blue" | "yellow" | "red";

export declare interface LogEntry {
    level: LogLevelType;
    name: string;
    args: any[];
    timestamp: number;
}

/**
 * Logger
 *
 * @class Logger
 */
export declare class Logger implements ILogger {
    /**
     * Creates an instance of Logger.
     * @param {LoggerOpt} [opt]
     * @memberof Logger
     */
    constructor(opt?: LoggerOpt);
    /**
     * enable
     */
    enable(b?: boolean): void;
    /**
     * getLevel
     */
    getLevel(): LogLevelType;
    /**
     * setLevel
     */
    setLevel(level: LogLevelType): void;
    /**
     * getLogFilePath
     */
    getLogFilePath(): string;
    /**
     * setLogFile
     */
    setLogFilePath(f: string): void;
    /**
     * getSensFields
     */
    getSensFields(): Set<string>;
    /**
     * setSensFields
     */
    setSensFields(fields: string[]): void;
    /**
     * clearSensFields - 清理敏感字段，防止内存泄漏
     */
    clearSensFields(): void;
    /**
     * resetSensFields - 重置敏感字段为指定列表
     */
    resetSensFields(fields: string[]): void;
    /**
     * destroy - 销毁Logger实例，释放资源
     */
    destroy(): void;
    /**
     * enableBatch - 启用/禁用批量写入
     */
    enableBatch(enabled?: boolean): void;
    /**
     * setBatchConfig - 设置批量写入配置
     */
    setBatchConfig(config: Partial<BatchConfig>): void;
    /**
     * getBatchConfig - 获取批量写入配置
     */
    getBatchConfig(): BatchConfig;
    /**
     * getBatchStatus - 获取批量写入状态
     */
    getBatchStatus(): {
        enabled: boolean;
        bufferSize: number;
        maxSize: number;
        timeSinceLastFlush: number;
    };
    /**
     * flushBatch - 立即刷新批量写入缓冲区
     */
    flushBatch(): Promise<void>;
    /**
     * startBatchTimer - 启动批量写入定时器
     */
    /**
     * stopBatchTimer - 停止批量写入定时器
     */
    /**
     * addToBuffer - 添加日志到缓冲区
     */
    /**
     * writeLogEntry - 写入单个日志条目
     */
    /**
     * sanitizeInput - 过滤危险字符，防止日志注入
     */
    /**
     * validateLogPath - 验证日志路径安全性
     */
    /**
     * log Debug
     *
     * @returns {*}
     * @memberof Logger
     */
    Debug(...args: any[]): void;
    /**
     * debug
     */
    debug(...args: any[]): void;
    /**
     * log Info
     *
     * @returns {*}
     * @memberof Logger
     */
    Info(...args: any[]): void;
    /**
     * info
     */
    info(...args: any[]): void;
    /**
     * log Warn
     *
     * @returns {*}
     * @memberof Logger
     */
    Warn(...args: any[]): void;
    /**
     * warn
     */
    warn(...args: any[]): void;
    /**
     * log Error
     *
     * @returns {*}
     * @memberof Logger
     */
    Error(...args: any[]): void;
    /**
     * error
     */
    error(...args: any[]): void;
    /**
     * log Fatal - for critical errors that cause application termination
     * Automatically exits the process after logging
     *
     * @returns {*}
     * @memberof Logger
     */
    Fatal(...args: any[]): void;
    /**
     * fatal
     */
    fatal(...args: any[]): void;
    /**
     * log Log
     *
     * Logger.Log('msg')
     *
     * Logger.Log('name', 'msg')
     *
     * Logger.Log('name', 'msg1', 'msg2'...)
     *
     * @param {...any[]} args
     * @returns {*}
     * @memberof Logger
     */
    Log(name: LogLevelType | string, ...args: any[]): void;
    /**
     * log
     */
    log(name: LogLevelType | string, ...args: any[]): void;
    /**
     * print console
     *
     * @private
     * @param {LogLevelType} level
     * @param {string} name
     * @param {any[]|string} args
     * @memberof Logger
     */
    /**
     * writeLogAsync - 异步写入单个日志条目
     */
    /**
     * 格式化
     *
     * @private
     * @param {string} level
     * @param {string} label
     * @param {string} timestamp
     * @param {any[]|string} args
     * @returns {string}
     * @memberof Logger
     */
    /**
     * createLogger
     * @returns
     */
}

export declare interface LoggerOpt {
    logLevel?: LogLevelType;
    logFilePath?: string;
    sensFields?: Set<string>;
    batchConfig?: BatchConfig;
}

export declare type LogLevelType = "debug" | "info" | "warn" | "error";

export declare interface LogTrans {
    Console?: transports.ConsoleTransportInstance;
    File?: any;
}

/**
 * Register the "Log" decorator with koatty-container's property manager.
 * Call once at app startup, e.g. registerLogDecorator(decoratorManager.property).
 *
 * @param propertyManager - PropertyDecoratorManager from decoratorManager.property
 */
export declare function registerLogDecorator(propertyManager: IPropertyDecoratorManagerLike): void;

/**
 * Unregister the stored property manager (e.g. for tests).
 */
export declare function unregisterLogDecorator(): void;

export { }