@zhin.js/logger 0.1.0

package/lib/logger.d.ts

@@ -0,0 +1,273 @@
+import { WriteStream } from 'node:fs';
+/**
+ * 日志级别枚举
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    SILENT = 4
+}
+/**
+ * 日志级别名称映射
+ */
+export declare const LOG_LEVEL_NAMES: Record<LogLevel, string>;
+/**
+ * 日志级别颜色映射
+ */
+export declare const LOG_LEVEL_COLORS: Record<LogLevel, (text: string) => string>;
+/**
+ * 日志条目接口
+ */
+export interface LogEntry {
+    level: LogLevel;
+    name: string;
+    message: string;
+    timestamp: Date;
+    args: any[];
+    error?: Error;
+}
+/**
+ * 日志格式化器接口
+ */
+export interface LogFormatter {
+    format(entry: LogEntry): string;
+}
+/**
+ * 日志输出器接口
+ */
+export interface LogTransport {
+    write(formatted: string): void;
+}
+/**
+ * Transport安全选项
+ */
+export interface TransportSecurityOptions {
+    /** 是否移除ANSI转义序列 */
+    removeAnsi?: boolean;
+    /** 是否脱敏敏感信息 */
+    maskSensitive?: boolean;
+}
+/**
+ * 颜色函数类型
+ */
+export type ColorFunction = (text: string) => string;
+/**
+ * Logger 颜色配置选项
+ */
+export interface LoggerColorOptions {
+    /** 日志级别颜色映射（覆盖默认级别颜色） */
+    levelColors?: Partial<Record<LogLevel, ColorFunction>>;
+    /** Logger名称颜色（可以是单个颜色或颜色数组） */
+    nameColor?: ColorFunction | ColorFunction[];
+    /** 日期时间颜色 */
+    dateColor?: ColorFunction;
+}
+/**
+ * Logger 配置选项
+ */
+export interface LoggerOptions {
+    /** 日志级别 */
+    level?: LogLevel;
+    /** 自定义格式化器 */
+    formatter?: LogFormatter;
+    /** 输出器列表 */
+    transports?: LogTransport[];
+    /** 颜色配置 */
+    colors?: LoggerColorOptions;
+    /** 性能选项 */
+    performance?: {
+        /** 最大子Logger数量（默认1000） */
+        maxChildLoggers?: number;
+        /** 最大Timer数量（默认100） */
+        maxTimers?: number;
+    };
+}
+/**
+ * 默认格式化器 - 【date】【level】【name】：【message】
+ * 只负责格式化，不处理安全净化（由Transport处理）
+ */
+export declare class DefaultFormatter implements LogFormatter {
+    private nameColorMap;
+    private colorIndex;
+    private readonly maxCacheSize;
+    private levelColors;
+    private nameColors;
+    private dateColor;
+    constructor(colorOptions?: LoggerColorOptions);
+    private getNameColor;
+    format(entry: LogEntry): string;
+}
+/**
+ * 控制台输出器 - 开发友好，默认保留颜色和完整信息
+ */
+export declare class ConsoleTransport implements LogTransport {
+    private securityOptions?;
+    constructor(securityOptions?: TransportSecurityOptions | undefined);
+    write(formatted: string): void;
+}
+/**
+ * 文件输出器 - 生产安全，默认去除颜色和脱敏
+ */
+export declare class FileTransport implements LogTransport {
+    private stream;
+    private securityOptions?;
+    constructor(stream: WriteStream, securityOptions?: TransportSecurityOptions | undefined);
+    write(formatted: string): void;
+}
+/**
+ * 流输出器 - 可配置安全选项
+ */
+export declare class StreamTransport implements LogTransport {
+    private stream;
+    private securityOptions?;
+    constructor(stream: NodeJS.WritableStream, securityOptions?: TransportSecurityOptions | undefined);
+    write(formatted: string): void;
+}
+/**
+ * 性能计时器
+ */
+export interface Timer {
+    end(): void;
+}
+/**
+ * Logger 类 - 自管理子 Logger
+ */
+export declare class Logger {
+    #private;
+    private level;
+    private formatter;
+    private transports;
+    private timers;
+    private childLoggers;
+    private readonly maxChildLoggers;
+    private readonly maxTimers;
+    constructor(parent: Logger | null, name: string, options?: LoggerOptions);
+    get name(): string;
+    set name(name: string);
+    /**
+     * 设置日志级别
+     * @param level
+     * @param recursive 是否同时设置所有子 Logger 的级别
+     */
+    setLevel(level: LogLevel, recursive?: boolean): void;
+    /**
+     * 递归设置级别，带深度检查
+     */
+    private setLevelRecursive;
+    /**
+     * 获取当前日志级别
+     */
+    getLevel(): LogLevel;
+    /**
+     * 检查指定级别是否启用
+     */
+    isLevelEnabled(level: LogLevel): boolean;
+    /**
+     * 添加输出器
+     * @param transport
+     * @param recursive 是否同时添加到所有子 Logger
+     */
+    addTransport(transport: LogTransport, recursive?: boolean): void;
+    /**
+     * 移除输出器
+     * @param transport
+     * @param recursive 是否同时从所有子 Logger 移除
+     */
+    removeTransport(transport: LogTransport, recursive?: boolean): void;
+    /**
+     * 设置格式化器
+     * @param formatter
+     * @param recursive 是否同时设置所有子 Logger 的格式化器
+     */
+    setFormatter(formatter: LogFormatter, recursive?: boolean): void;
+    hasLogger(name: string): boolean;
+    /**
+     * 获取或创建子 Logger
+     * @param namespace 子命名空间
+     * @param options 可选配置，会覆盖从父级继承的配置
+     */
+    getLogger(namespace: string, options?: LoggerOptions): Logger;
+    /**
+     * 检查并清理过多的子Logger
+     */
+    private checkChildLoggerLimit;
+    setLogger(name: string, options?: LoggerOptions): Logger;
+    setOptions(options?: LoggerOptions): void;
+    /**
+     * 移除子 Logger
+     */
+    removeLogger(namespace: string): boolean;
+    /**
+     * 获取所有子 Logger 名称
+     */
+    getLoggerNames(): string[];
+    get parent(): Logger | null;
+    /**
+     * 检查是否为根 Logger
+     */
+    isRoot(): boolean;
+    /**
+     * 记录日志的通用方法
+     */
+    private log;
+    /**
+     * DEBUG 级别日志
+     */
+    debug(message: string, ...args: any[]): void;
+    /**
+     * INFO 级别日志
+     */
+    info(message: string, ...args: any[]): void;
+    /**
+     * SUCCESS 日志（INFO 级别，带绿色 ✓ 标记）
+     */
+    success(message: string, ...args: any[]): void;
+    /**
+     * WARN 级别日志
+     */
+    warn(message: string, ...args: any[]): void;
+    /**
+     * ERROR 级别日志
+     * 支持传入Error对象，会自动打印错误堆栈信息
+     * @param message 错误消息
+     * @param args 其他参数，如果第一个参数是Error对象，会使用其message并打印堆栈
+     */
+    error(message: string, ...args: any[]): void;
+    /**
+     * 开始性能计时
+     */
+    time(label: string): Timer;
+    /**
+     * 清理过期的Timer
+     */
+    private cleanupTimers;
+    /**
+     * 结束性能计时
+     */
+    timeEnd(label: string): void;
+    /**
+     * 条件日志
+     */
+    logIf(condition: boolean, level: LogLevel, message: string, ...args: any[]): void;
+    /**
+     * 获取 logger 名称
+     */
+    getName(): string;
+}
+declare const defaultLogger: Logger;
+export declare function getLogger(name: string, options?: LoggerOptions, parent?: Logger): Logger;
+export declare function setLogger(name: string, options?: LoggerOptions, parent?: Logger): Logger;
+export declare function setOptions(options?: LoggerOptions, logger?: Logger): void;
+export declare function addTransport(transport: LogTransport, logger?: Logger): void;
+export declare function removeTransport(transport: LogTransport, logger?: Logger): void;
+export declare function setFormatter(formatter: LogFormatter, logger?: Logger): void;
+export declare function setLevel(level: LogLevel, logger?: Logger): void;
+export declare function getLevel(logger?: Logger): LogLevel;
+export declare function isLevelEnabled(level: LogLevel, logger?: Logger): boolean;
+export declare function setName(name: string, logger?: Logger): string;
+export declare function getName(logger?: Logger): string;
+export declare function getLoggerNames(logger?: Logger): string[];
+export default defaultLogger;
+//# sourceMappingURL=logger.d.ts.map

package/lib/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}