@taicode/common-base 1.2.0 → 1.4.0

package/output/logger/logger.test.js

@@ -1,33 +1,219 @@
 import { describe, it, expect, vi } from 'vitest';
-import { Logger } from './index';
+import { Logger } from './logger';
+import { DefaultLogFormatter } from './formatter';
+import { UserError, SystemError, UnknownError } from '../error';
+import { MemoryTransport } from './transport'; // 测试向后兼容性
 describe('Logger', () => {
     it('应该默认记录 info 及以上级别', () => {
-        const handler = vi.fn();
-        const logger = new Logger({ handler });
+        const print = vi.fn();
+        const logger = new Logger({ print });
         logger.debug('debug');
         logger.info('info');
         logger.warn('warn');
         logger.error('error');
-        expect(handler).not.toHaveBeenCalledWith('debug', 'debug');
-        expect(handler).toHaveBeenCalledWith('info', 'info');
-        expect(handler).toHaveBeenCalledWith('warn', 'warn');
-        expect(handler).toHaveBeenCalledWith('error', 'error');
+        expect(print).not.toHaveBeenCalledWith('debug', 'debug');
+        expect(print).toHaveBeenCalledWith('info', 'info');
+        expect(print).toHaveBeenCalledWith('warn', 'warn');
+        expect(print).toHaveBeenCalledWith('error', 'error');
     });
     it('应该遵守日志级别', () => {
-        const handler = vi.fn();
-        const logger = new Logger({ level: 'warn', handler });
+        const print = vi.fn();
+        const logger = new Logger({ level: 'warn', print });
         logger.info('info');
         logger.warn('warn');
         logger.error('error');
-        expect(handler).not.toHaveBeenCalledWith('info', 'info');
-        expect(handler).toHaveBeenCalledWith('warn', 'warn');
-        expect(handler).toHaveBeenCalledWith('error', 'error');
+        expect(print).not.toHaveBeenCalledWith('info', 'info');
+        expect(print).toHaveBeenCalledWith('warn', 'warn');
+        expect(print).toHaveBeenCalledWith('error', 'error');
     });
     it('应该允许自定义处理器', () => {
         const logs = [];
-        const handler = (level, ...args) => logs.push([level, ...args]);
-        const logger = new Logger({ handler });
+        const print = (level, ...args) => logs.push([level, ...args]);
+        const logger = new Logger({ print });
         logger.error('err', 123);
-        expect(logs).toContainEqual(['error', 'err', 123]);
+        expect(logs).toContainEqual(['error', 'err', "123"]);
+    });
+});
+describe('Logger 错误处理', () => {
+    it('应该正确格式化 UserError', () => {
+        const mockPrint = vi.fn();
+        const logger = new Logger({ print: mockPrint });
+        const userError = new UserError('validation-failed', '邮箱格式无效', {
+            field: 'email',
+            value: 'invalid-email',
+            rule: 'email-format'
+        });
+        logger.error('测试用户错误:', userError);
+        expect(mockPrint).toHaveBeenCalledWith('error', '测试用户错误:', expect.stringContaining('🚫 User Error [validation-failed]'));
+        expect(mockPrint).toHaveBeenCalledWith('error', '测试用户错误:', expect.stringContaining('邮箱格式无效'));
+    });
+    it('应该正确格式化 SystemError', () => {
+        const mockPrint = vi.fn();
+        const logger = new Logger({ print: mockPrint });
+        const systemError = new SystemError('database-error', '数据库连接失败', {
+            table: 'users',
+            query: 'SELECT * FROM users',
+            operation: 'select'
+        });
+        logger.error('测试系统错误:', systemError);
+        expect(mockPrint).toHaveBeenCalledWith('error', '测试系统错误:', expect.stringContaining('⚠️ System Error [database-error]'));
+        expect(mockPrint).toHaveBeenCalledWith('error', '测试系统错误:', expect.stringContaining('数据库连接失败'));
+    });
+    it('应该正确格式化 UnknownError', () => {
+        const mockPrint = vi.fn();
+        const logger = new Logger({ print: mockPrint });
+        const unknownError = new UnknownError('未知错误', {
+            cause: 'something went wrong'
+        });
+        logger.error('测试未知错误:', unknownError);
+        expect(mockPrint).toHaveBeenCalledWith('error', '测试未知错误:', expect.stringContaining('❓ Unknown Error'));
+        expect(mockPrint).toHaveBeenCalledWith('error', '测试未知错误:', expect.stringContaining('未知错误'));
+    });
+    it('应该正确格式化普通 Error', () => {
+        const mockPrint = vi.fn();
+        const logger = new Logger({ print: mockPrint });
+        const genericError = new Error('普通错误');
+        logger.error('测试普通错误:', genericError);
+        expect(mockPrint).toHaveBeenCalledWith('error', '测试普通错误:', expect.stringContaining('💥 Error'));
+        expect(mockPrint).toHaveBeenCalledWith('error', '测试普通错误:', expect.stringContaining('普通错误'));
+    });
+    it('应该支持自定义 LogFormatter 实例', () => {
+        const customFormatter = new DefaultLogFormatter({}, {
+            showStack: false,
+            useColors: false
+        });
+        const mockPrint = vi.fn();
+        const logger = new Logger({
+            print: mockPrint,
+            formatter: customFormatter
+        });
+        const error = new Error('测试错误');
+        logger.error(error);
+        const formattedError = mockPrint.mock.calls[0][1];
+        expect(formattedError).not.toContain('Stack:');
+        expect(formattedError).not.toContain('\x1b['); // ANSI color codes
+    });
+    it('应该支持自定义格式化选项', () => {
+        const customFormatter = new DefaultLogFormatter({}, {
+            showStack: false,
+            showContext: false,
+            useColors: false
+        });
+        const mockPrint = vi.fn();
+        const logger = new Logger({
+            print: mockPrint,
+            formatter: customFormatter
+        });
+        const userError = new UserError('test-error', '测试错误', { field: 'test' });
+        logger.error(userError);
+        const formattedError = mockPrint.mock.calls[0][1];
+        expect(formattedError).not.toContain('Stack:');
+        expect(formattedError).not.toContain('Context:');
+        expect(formattedError).not.toContain('\x1b['); // ANSI color codes
+    });
+});
+describe('Logger Transport 集成', () => {
+    it('应该支持 Transport 记录日志', () => {
+        const transport = new MemoryTransport();
+        const logger = new Logger({ transports: [transport] });
+        logger.info('测试消息', { data: 'value' });
+        const records = transport.getRecords();
+        expect(records).toHaveLength(1);
+        expect(records[0].level).toBe('info');
+        expect(records[0].args).toEqual(['测试消息', { data: 'value' }]);
+        expect(records[0].timestamp).toBeInstanceOf(Date);
+    });
+    it('应该支持多个 Transport', () => {
+        const transport1 = new MemoryTransport({ maxRecords: 10 });
+        const transport2 = new MemoryTransport({ maxRecords: 10 });
+        const logger = new Logger({ transports: [transport1, transport2] });
+        logger.error('错误消息');
+        expect(transport1.getRecords()).toHaveLength(1);
+        expect(transport2.getRecords()).toHaveLength(1);
+        expect(transport1.getRecords()[0].args).toEqual(['错误消息']);
+        expect(transport2.getRecords()[0].args).toEqual(['错误消息']);
+    });
+    it('应该支持动态添加和移除 Transport', () => {
+        const logger = new Logger();
+        const transport = new MemoryTransport();
+        // 添加 transport
+        logger.addTransport(transport);
+        logger.info('消息1');
+        expect(transport.getRecords()).toHaveLength(1);
+        // 移除 transport
+        logger.removeTransport('memory');
+        logger.info('消息2');
+        expect(transport.getRecords()).toHaveLength(1); // 应该还是1条
+    });
+    it('应该获取所有 Transport', () => {
+        const transport1 = new MemoryTransport();
+        const transport2 = new MemoryTransport();
+        const logger = new Logger({ transports: [transport1, transport2] });
+        const transports = logger.getTransports();
+        expect(transports).toHaveLength(2);
+        expect(transports[0].name).toBe('memory');
+        expect(transports[1].name).toBe('memory');
+    });
+    it('应该同时支持 Transport 和 print', () => {
+        const transport = new MemoryTransport();
+        const mockPrint = vi.fn();
+        const logger = new Logger({
+            transports: [transport],
+            print: mockPrint
+        });
+        logger.warn('警告消息');
+        // Transport 应该收到结构化数据
+        const records = transport.getRecords();
+        expect(records).toHaveLength(1);
+        expect(records[0].args).toEqual(['警告消息']);
+        // print 应该收到格式化的数据
+        expect(mockPrint).toHaveBeenCalledWith('warn', '警告消息');
+    });
+    it('应该处理 Transport 错误而不影响主程序', () => {
+        const faultyTransport = {
+            name: 'faulty',
+            log: () => { throw new Error('Transport 错误'); }
+        };
+        const logger = new Logger({ transports: [faultyTransport] });
+        // 不应该抛出错误
+        expect(() => {
+            logger.error('测试消息');
+        }).not.toThrow();
+    });
+    it('应该在没有 Transport 和 print 时使用默认输出', () => {
+        const consoleSpy = vi.spyOn(console, 'info').mockImplementation(() => { });
+        const logger = new Logger();
+        logger.info('默认输出测试');
+        expect(consoleSpy).toHaveBeenCalledWith('[INFO]', '默认输出测试');
+        consoleSpy.mockRestore();
+    });
+    it('应该关闭所有 Transport', async () => {
+        const mockClose1 = vi.fn();
+        const mockClose2 = vi.fn();
+        const transport1 = {
+            name: 'test1',
+            log: () => { },
+            close: mockClose1
+        };
+        const transport2 = {
+            name: 'test2',
+            log: () => { },
+            close: mockClose2
+        };
+        const logger = new Logger({ transports: [transport1, transport2] });
+        await logger.close();
+        expect(mockClose1).toHaveBeenCalled();
+        expect(mockClose2).toHaveBeenCalled();
+    });
+});
+describe('向后兼容性测试', () => {
+    it('Transport 类型别名应该正常工作', () => {
+        // 测试 Transport 类型别名是否可以正常使用
+        const transport = new MemoryTransport();
+        const logger = new Logger({ transports: [transport] });
+        logger.info('测试向后兼容性');
+        const records = transport.getRecords();
+        expect(records).toHaveLength(1);
+        expect(records[0].args).toEqual(['测试向后兼容性']);
     });
 });

package/output/logger/transport.d.ts

@@ -0,0 +1,124 @@
+/**
+ * LogTransport 抽象接口和实现
+ * LogTransport 负责处理和存储结构化的日志数据
+ */
+import type { LogLevel } from './logger';
+/**
+ * 日志记录接口
+ * 包含完整的结构化日志信息
+ */
+export interface LogRecord {
+    /** 日志级别 */
+    level: LogLevel;
+    /** 时间戳 */
+    timestamp: Date;
+    /** 原始参数数组 */
+    args: any[];
+    /** 可选的附加元数据 */
+    metadata?: Record<string, any>;
+}
+/**
+ * LogTransport 抽象接口
+ * 负责处理结构化日志数据的存储和管理
+ */
+export interface LogTransport {
+    /** LogTransport 名称 */
+    readonly name: string;
+    /** 最低日志级别 */
+    level?: LogLevel;
+    /** 是否启用 */
+    enabled?: boolean;
+    /**
+     * 处理日志记录
+     * @param record 结构化的日志记录
+     */
+    log(record: LogRecord): void | Promise<void>;
+    /**
+     * 关闭 LogTransport，清理资源
+     */
+    close?(): void | Promise<void>;
+}
+/**
+ * 内存 LogTransport 配置选项
+ */
+export interface MemoryTransportOptions {
+    /** 最大存储的日志条数 */
+    maxRecords?: number;
+    /** 最低日志级别 */
+    level?: LogLevel;
+    /** 是否启用 */
+    enabled?: boolean;
+}
+/**
+ * 内存中的日志条目
+ */
+export interface MemoryLogEntry extends LogRecord {
+    /** 唯一标识符 */
+    id: string;
+}
+/**
+ * 内存 LogTransport 实现
+ * 将结构化日志数据存储在内存中，支持查询和分析
+ * 使用RingCache实现高效的FIFO行为
+ */
+export declare class MemoryTransport implements LogTransport {
+    readonly name: string;
+    level?: LogLevel;
+    enabled: boolean;
+    private cache;
+    private static readonly LOG_LEVELS;
+    constructor(options?: MemoryTransportOptions);
+    /**
+     * 检查是否应该处理此级别的日志
+     */
+    private shouldLog;
+    log(record: LogRecord): void;
+    /**
+     * 获取所有日志记录
+     */
+    getRecords(): readonly MemoryLogEntry[];
+    /**
+     * 根据级别获取日志记录
+     */
+    getRecordsByLevel(level: LogLevel): MemoryLogEntry[];
+    /**
+     * 根据时间范围获取日志记录
+     */
+    getRecordsByTimeRange(start: Date, end: Date): MemoryLogEntry[];
+    /**
+     * 搜索日志记录
+     * @param predicate 搜索条件函数
+     */
+    searchRecords(predicate: (record: MemoryLogEntry) => boolean): MemoryLogEntry[];
+    /**
+     * 根据参数内容搜索
+     * @param searchText 搜索文本
+     */
+    searchByContent(searchText: string): MemoryLogEntry[];
+    /**
+     * 获取最近的 N 条记录
+     */
+    getRecentRecords(count: number): MemoryLogEntry[];
+    /**
+     * 获取统计信息
+     */
+    getStats(): {
+        total: number;
+        byLevel: Record<LogLevel, number>;
+        oldestTimestamp?: Date;
+        newestTimestamp?: Date;
+    };
+    /**
+     * 清空所有记录
+     */
+    clear(): void;
+    /**
+     * 导出为 JSON 格式
+     */
+    exportToJSON(): string;
+    /**
+     * 关闭 LogTransport
+     */
+    close(): void;
+}
+//# sourceMappingURL=transport.d.ts.map

package/output/logger/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../source/logger/transport.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAGxC;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,WAAW;IACX,KAAK,EAAE,QAAQ,CAAA;IACf,UAAU;IACV,SAAS,EAAE,IAAI,CAAA;IACf,aAAa;IACb,IAAI,EAAE,GAAG,EAAE,CAAA;IACX,eAAe;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,aAAa;IACb,KAAK,CAAC,EAAE,QAAQ,CAAA;IAEhB,WAAW;IACX,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB;;;OAGG;IACH,GAAG,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE5C;;OAEG;IACH,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,gBAAgB;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,aAAa;IACb,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,WAAW;IACX,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,YAAY;IACZ,EAAE,EAAE,MAAM,CAAA;CACX;AAED;;;;GAIG;AACH,qBAAa,eAAgB,YAAW,YAAY;IAClD,SAAgB,IAAI,EAAE,MAAM,CAAY;IACjC,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,OAAO,EAAE,OAAO,CAAQ;IAE/B,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAkD;gBAExE,OAAO,GAAE,sBAA2B;IAQhD;;OAEG;IACH,OAAO,CAAC,SAAS;IAeV,GAAG,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAQnC;;OAEG;IACI,UAAU,IAAI,SAAS,cAAc,EAAE;IAO9C;;OAEG;IACI,iBAAiB,CAAC,KAAK,EAAE,QAAQ,GAAG,cAAc,EAAE;IAQ3D;;OAEG;IACI,qBAAqB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,cAAc,EAAE;IAQtE;;;OAGG;IACI,aAAa,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,OAAO,GAAG,cAAc,EAAE;IAItF;;;OAGG;IACI,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,EAAE;IAsB5D;;OAEG;IACI,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE;IAOxD;;OAEG;IACI,QAAQ,IAAI;QACjB,KAAK,EAAE,MAAM,CAAA;QACb,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;QACjC,eAAe,CAAC,EAAE,IAAI,CAAA;QACtB,eAAe,CAAC,EAAE,IAAI,CAAA;KACvB;IA4BD;;OAEG;IACI,KAAK,IAAI,IAAI;IAIpB;;OAEG;IACI,YAAY,IAAI,MAAM;IAI7B;;OAEG;IACI,KAAK,IAAI,IAAI;CAGrB"}

package/output/logger/transport.js

@@ -0,0 +1,153 @@
+import { RingCache } from '../ring-cache';
+/**
+ * 内存 LogTransport 实现
+ * 将结构化日志数据存储在内存中，支持查询和分析
+ * 使用RingCache实现高效的FIFO行为
+ */
+export class MemoryTransport {
+    name = 'memory';
+    level;
+    enabled = true;
+    cache;
+    static LOG_LEVELS = ['debug', 'info', 'warn', 'error'];
+    constructor(options = {}) {
+        this.level = options.level;
+        this.enabled = options.enabled ?? true;
+        this.cache = new RingCache({
+            capacity: options.maxRecords ?? 1000
+        });
+    }
+    /**
+     * 检查是否应该处理此级别的日志
+     */
+    shouldLog(level) {
+        if (!this.enabled) {
+            return false;
+        }
+        if (!this.level) {
+            return true;
+        }
+        const currentIndex = MemoryTransport.LOG_LEVELS.indexOf(level);
+        const minIndex = MemoryTransport.LOG_LEVELS.indexOf(this.level);
+        return currentIndex >= minIndex;
+    }
+    log(record) {
+        if (!this.shouldLog(record.level)) {
+            return;
+        }
+        this.cache.add(record);
+    }
+    /**
+     * 获取所有日志记录
+     */
+    getRecords() {
+        return this.cache.getAll().map(entry => ({
+            ...entry.data,
+            id: entry.id
+        }));
+    }
+    /**
+     * 根据级别获取日志记录
+     */
+    getRecordsByLevel(level) {
+        return this.cache.search(entry => entry.data.level === level)
+            .map(entry => ({
+            ...entry.data,
+            id: entry.id
+        }));
+    }
+    /**
+     * 根据时间范围获取日志记录
+     */
+    getRecordsByTimeRange(start, end) {
+        return this.cache.getByTimeRange(start, end)
+            .map(entry => ({
+            ...entry.data,
+            id: entry.id
+        }));
+    }
+    /**
+     * 搜索日志记录
+     * @param predicate 搜索条件函数
+     */
+    searchRecords(predicate) {
+        return this.getRecords().filter(predicate);
+    }
+    /**
+     * 根据参数内容搜索
+     * @param searchText 搜索文本
+     */
+    searchByContent(searchText) {
+        const lowerSearchText = searchText.toLowerCase();
+        return this.cache.search(entry => entry.data.args.some(arg => {
+            if (typeof arg === 'string') {
+                return arg.toLowerCase().includes(lowerSearchText);
+            }
+            if (typeof arg === 'object' && arg !== null) {
+                try {
+                    return JSON.stringify(arg).toLowerCase().includes(lowerSearchText);
+                }
+                catch {
+                    return false;
+                }
+            }
+            return false;
+        })).map(entry => ({
+            ...entry.data,
+            id: entry.id
+        }));
+    }
+    /**
+     * 获取最近的 N 条记录
+     */
+    getRecentRecords(count) {
+        return this.cache.getRecent(count).map(entry => ({
+            ...entry.data,
+            id: entry.id
+        }));
+    }
+    /**
+     * 获取统计信息
+     */
+    getStats() {
+        const cacheStats = this.cache.getStats();
+        const all = this.cache.getAll();
+        const stats = {
+            total: cacheStats.size,
+            byLevel: {
+                debug: 0,
+                info: 0,
+                warn: 0,
+                error: 0
+            },
+            oldestTimestamp: cacheStats.oldestTimestamp,
+            newestTimestamp: cacheStats.newestTimestamp
+        };
+        if (all.length === 0) {
+            return stats;
+        }
+        // 统计各级别数量
+        all.forEach(entry => {
+            stats.byLevel[entry.data.level]++;
+        });
+        return stats;
+    }
+    /**
+     * 清空所有记录
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * 导出为 JSON 格式
+     */
+    exportToJSON() {
+        return JSON.stringify(this.getRecords(), null, 2);
+    }
+    /**
+     * 关闭 LogTransport
+     */
+    close() {
+        this.clear();
+    }
+}

package/output/logger/transport.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transport.test.d.ts.map

package/output/logger/transport.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.test.d.ts","sourceRoot":"","sources":["../../source/logger/transport.test.ts"],"names":[],"mappings":""}