koatty_logger/dist/index.d.ts

Logger for koatty.

/*!
* @Author: richen
* @Date: 2025-06-02 17:42: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 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>;
}

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 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" | "warning" | "error";

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

export { }