@taicode/common-base 3.8.0 → 4.0.0-beta.10

package/output/disposer/disposer.d.ts

@@ -1,7 +1,25 @@
 type CleanupFunction = () => unknown | Promise<unknown>;
+/**
+ * 清理失败时的日志出口（结构性类型）。
+ *
+ * 既兼容 base 全局 logger 的可变参形式 `(...args: unknown[])`，
+ * 也兼容 pino 的 `log.error(obj, msg)`；调用方传入应用自己的 logger 后，
+ * 失败日志就不会落进 console，而是进应用日志流。
+ */
+export interface DisposerLogSink {
+    error(payload: unknown, message?: string): void;
+}
+export interface DisposerOptions {
+    /** 失败日志出口；不传则回退到 base 全局 logger */
+    log?: DisposerLogSink;
+    /** 日志标签，用于区分是哪个阶段的 disposer（缺省 `disposer`） */
+    label?: string;
+}
 export declare class Disposer {
+    private readonly opts;
     private cleanupFunctions;
-    addDisposer(cleanupFn: CleanupFunction): void;
+    constructor(opts?: DisposerOptions);
+    add(cleanupFn: CleanupFunction): void;
     dispose(): Promise<void>;
 }
 export {};

package/output/disposer/disposer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"disposer.d.ts","sourceRoot":"","sources":["../../source/disposer/disposer.ts"],"names":[],"mappings":"AAEA,KAAK,eAAe,GAAG,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAEvD,qBAAa,QAAQ;IACnB,OAAO,CAAC,gBAAgB,CAAwB;IAGhD,WAAW,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI;IAKvC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAY/B"}
+{"version":3,"file":"disposer.d.ts","sourceRoot":"","sources":["../../source/disposer/disposer.ts"],"names":[],"mappings":"AAEA,KAAK,eAAe,GAAG,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAEvD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAChD;AAED,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,GAAG,CAAC,EAAE,eAAe,CAAA;IACrB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,qBAAa,QAAQ;IAGP,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,gBAAgB,CAAwB;gBAEnB,IAAI,GAAE,eAAoB;IAGvD,GAAG,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI;IAK/B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAgB/B"}

package/output/disposer/disposer.js

@@ -1,20 +1,28 @@
 import { logger } from '../logger/index.js';
 export class Disposer {
+    opts;
     cleanupFunctions = [];
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
     // 添加清理函数
-    addDisposer(cleanupFn) {
+    add(cleanupFn) {
         this.cleanupFunctions.push(cleanupFn);
     }
-    // 执行所有清理函数
+    // 执行所有清理函数（LIFO：后注册的先执行）
     async dispose() {
         const cleanupFunctions = this.cleanupFunctions;
         this.cleanupFunctions = [];
-        for (const cleanupFn of cleanupFunctions) {
+        // 后创建的东西依赖先创建的，必须**后**销毁：逆注册序执行
+        for (const cleanupFn of [...cleanupFunctions].reverse()) {
             try {
                 await cleanupFn();
             }
             catch (error) {
-                logger.error('Error during cleanup:', error);
+                // 单个清理失败不阻断后续，也不向调用方抛出
+                const label = this.opts.label ?? 'disposer';
+                const sink = this.opts.log ?? logger;
+                sink.error({ error }, `[${label}] cleanup failed`);
             }
         }
     }

package/output/disposer/disposer.test.js

@@ -6,20 +6,20 @@ describe('Disposer', () => {
     beforeEach(() => {
         disposer = new Disposer();
     });
-    describe('addDisposer', () => {
+    describe('add', () => {
         it('应该能够添加清理函数', () => {
             const cleanupFn = vi.fn();
             expect(() => {
-                disposer.addDisposer(cleanupFn);
+                disposer.add(cleanupFn);
             }).not.toThrow();
         });
         it('应该能够添加多个清理函数', async () => {
             const cleanupFn1 = vi.fn();
             const cleanupFn2 = vi.fn();
             const cleanupFn3 = vi.fn();
-            disposer.addDisposer(cleanupFn1);
-            disposer.addDisposer(cleanupFn2);
-            disposer.addDisposer(cleanupFn3);
+            disposer.add(cleanupFn1);
+            disposer.add(cleanupFn2);
+            disposer.add(cleanupFn3);
             await disposer.dispose();
             expect(cleanupFn1).toHaveBeenCalledOnce();
             expect(cleanupFn2).toHaveBeenCalledOnce();
@@ -30,10 +30,10 @@ describe('Disposer', () => {
             const stringFn = vi.fn(() => 'cleanup result');
             const numberFn = vi.fn(() => 42);
             const promiseFn = vi.fn(() => Promise.resolve('async cleanup'));
-            disposer.addDisposer(voidFn);
-            disposer.addDisposer(stringFn);
-            disposer.addDisposer(numberFn);
-            disposer.addDisposer(promiseFn);
+            disposer.add(voidFn);
+            disposer.add(stringFn);
+            disposer.add(numberFn);
+            disposer.add(promiseFn);
             await disposer.dispose();
             expect(voidFn).toHaveBeenCalled();
             expect(stringFn).toHaveBeenCalled();
@@ -46,38 +46,39 @@ describe('Disposer', () => {
             const cleanupFn1 = vi.fn();
             const cleanupFn2 = vi.fn();
             const cleanupFn3 = vi.fn();
-            disposer.addDisposer(cleanupFn1);
-            disposer.addDisposer(cleanupFn2);
-            disposer.addDisposer(cleanupFn3);
+            disposer.add(cleanupFn1);
+            disposer.add(cleanupFn2);
+            disposer.add(cleanupFn3);
             await disposer.dispose();
             expect(cleanupFn1).toHaveBeenCalledOnce();
             expect(cleanupFn2).toHaveBeenCalledOnce();
             expect(cleanupFn3).toHaveBeenCalledOnce();
         });
-        it('应该按添加顺序执行清理函数', async () => {
+        it('应该按添加顺序的**逆序**（LIFO）执行清理函数', async () => {
             const executionOrder = [];
-            disposer.addDisposer(() => executionOrder.push(1));
-            disposer.addDisposer(() => executionOrder.push(2));
-            disposer.addDisposer(() => executionOrder.push(3));
+            disposer.add(() => executionOrder.push(1));
+            disposer.add(() => executionOrder.push(2));
+            disposer.add(() => executionOrder.push(3));
             await disposer.dispose();
-            expect(executionOrder).toEqual([1, 2, 3]);
+            // 后创建的东西依赖先创建的，必须后销毁
+            expect(executionOrder).toEqual([3, 2, 1]);
         });
-        it('应该按添加顺序执行异步清理函数', async () => {
+        it('应该按添加顺序的**逆序**（LIFO）执行异步清理函数', async () => {
             const executionOrder = [];
-            disposer.addDisposer(async () => {
+            disposer.add(async () => {
                 await Promise.resolve();
                 executionOrder.push(1);
             });
-            disposer.addDisposer(async () => {
+            disposer.add(async () => {
                 await Promise.resolve();
                 executionOrder.push(2);
             });
-            disposer.addDisposer(async () => {
+            disposer.add(async () => {
                 await Promise.resolve();
                 executionOrder.push(3);
             });
             await disposer.dispose();
-            expect(executionOrder).toEqual([1, 2, 3]);
+            expect(executionOrder).toEqual([3, 2, 1]);
         });
         it('应该处理清理函数中的错误', async () => {
             const workingFn1 = vi.fn();
@@ -87,9 +88,9 @@ describe('Disposer', () => {
             const workingFn2 = vi.fn();
             // 模拟 logger.error
             const loggerErrorSpy = vi.spyOn(logger, 'error').mockImplementation(() => { });
-            disposer.addDisposer(workingFn1);
-            disposer.addDisposer(errorFn);
-            disposer.addDisposer(workingFn2);
+            disposer.add(workingFn1);
+            disposer.add(errorFn);
+            disposer.add(workingFn2);
             // dispose 不应该抛出错误
             await expect(disposer.dispose()).resolves.toBeUndefined();
             // 所有函数都应该被调用
@@ -97,12 +98,12 @@ describe('Disposer', () => {
             expect(errorFn).toHaveBeenCalled();
             expect(workingFn2).toHaveBeenCalled();
             // 错误应该被记录
-            expect(loggerErrorSpy).toHaveBeenCalledWith('Error during cleanup:', expect.any(Error));
+            expect(loggerErrorSpy).toHaveBeenCalledWith({ error: expect.any(Error) }, '[disposer] cleanup failed');
             loggerErrorSpy.mockRestore();
         });
         it('应该在执行后清空清理函数列表', async () => {
             const cleanupFn = vi.fn();
-            disposer.addDisposer(cleanupFn);
+            disposer.add(cleanupFn);
             await disposer.dispose();
             expect(cleanupFn).toHaveBeenCalledOnce();
             // 再次调用 dispose 不应该执行任何函数
@@ -112,9 +113,9 @@ describe('Disposer', () => {
         it('应该能够在清空后重新添加清理函数', async () => {
             const firstCleanup = vi.fn();
             const secondCleanup = vi.fn();
-            disposer.addDisposer(firstCleanup);
+            disposer.add(firstCleanup);
             await disposer.dispose();
-            disposer.addDisposer(secondCleanup);
+            disposer.add(secondCleanup);
             await disposer.dispose();
             expect(firstCleanup).toHaveBeenCalledOnce();
             expect(secondCleanup).toHaveBeenCalledOnce();
@@ -124,19 +125,67 @@ describe('Disposer', () => {
         });
         it('应该能够多次调用 dispose', async () => {
             const cleanupFn = vi.fn();
-            disposer.addDisposer(cleanupFn);
+            disposer.add(cleanupFn);
             await disposer.dispose();
             await disposer.dispose();
             await disposer.dispose();
             expect(cleanupFn).toHaveBeenCalledOnce();
         });
     });
+    describe('日志注入', () => {
+        it('应该在传入 log 时使用注入的日志出口，不再走 base logger', async () => {
+            const loggerErrorSpy = vi.spyOn(logger, 'error').mockImplementation(() => { });
+            const logError = vi.fn();
+            const error = new Error('Injected log error');
+            const injected = new Disposer({ log: { error: logError }, label: 'resources' });
+            injected.add(() => {
+                throw error;
+            });
+            await expect(injected.dispose()).resolves.toBeUndefined();
+            expect(logError).toHaveBeenCalledOnce();
+            expect(logError).toHaveBeenCalledWith({ error }, '[resources] cleanup failed');
+            expect(loggerErrorSpy).not.toHaveBeenCalled();
+            loggerErrorSpy.mockRestore();
+        });
+        it('标签应该出现在消息里（注入 log 且自定义 label）', async () => {
+            const logError = vi.fn();
+            const injected = new Disposer({ log: { error: logError }, label: 'middlewares' });
+            injected.add(() => {
+                throw new Error('boom');
+            });
+            await injected.dispose();
+            expect(logError).toHaveBeenCalledWith({ error: expect.any(Error) }, '[middlewares] cleanup failed');
+        });
+        it('未传 log 时应该回退到 base logger', async () => {
+            const loggerErrorSpy = vi.spyOn(logger, 'error').mockImplementation(() => { });
+            const error = new Error('Fallback error');
+            const noLog = new Disposer({ label: 'routers' });
+            noLog.add(() => {
+                throw error;
+            });
+            await noLog.dispose();
+            expect(loggerErrorSpy).toHaveBeenCalledWith({ error }, '[routers] cleanup failed');
+            loggerErrorSpy.mockRestore();
+        });
+        it('传入 log 时单个失败仍不阻断后续，且全部走注入出口', async () => {
+            const logError = vi.fn();
+            const first = vi.fn();
+            const injected = new Disposer({ log: { error: logError }, label: 'services' });
+            injected.add(first);
+            injected.add(() => {
+                throw new Error('boom');
+            });
+            await injected.dispose();
+            expect(first).toHaveBeenCalledOnce();
+            expect(logError).toHaveBeenCalledOnce();
+        });
+    });
     describe('实际使用场景', () => {
         it('应该能够清理事件监听器', async () => {
             const removeEventListener = vi.fn();
             const unsubscribe = vi.fn();
-            disposer.addDisposer(removeEventListener);
-            disposer.addDisposer(unsubscribe);
+            disposer.add(removeEventListener);
+            disposer.add(unsubscribe);
             await disposer.dispose();
             expect(removeEventListener).toHaveBeenCalled();
             expect(unsubscribe).toHaveBeenCalled();
@@ -144,8 +193,8 @@ describe('Disposer', () => {
         it('应该能够清理定时器', async () => {
             const clearTimeout = vi.fn();
             const clearInterval = vi.fn();
-            disposer.addDisposer(() => clearTimeout(123));
-            disposer.addDisposer(() => clearInterval(456));
+            disposer.add(() => clearTimeout(123));
+            disposer.add(() => clearInterval(456));
             await disposer.dispose();
             expect(clearTimeout).toHaveBeenCalledWith(123);
             expect(clearInterval).toHaveBeenCalledWith(456);
@@ -153,8 +202,8 @@ describe('Disposer', () => {
         it('应该能够清理资源连接', async () => {
             const closeConnection = vi.fn();
             const releaseResource = vi.fn();
-            disposer.addDisposer(() => closeConnection());
-            disposer.addDisposer(() => releaseResource());
+            disposer.add(() => closeConnection());
+            disposer.add(() => releaseResource());
             await disposer.dispose();
             expect(closeConnection).toHaveBeenCalled();
             expect(releaseResource).toHaveBeenCalled();
@@ -167,9 +216,9 @@ describe('Disposer', () => {
             };
             const offFunction1 = mockEventEmitter.on('event1', vi.fn());
             const offFunction2 = mockEventEmitter.on('event2', vi.fn());
-            disposer.addDisposer(offFunction1);
-            disposer.addDisposer(offFunction2);
-            disposer.addDisposer(() => mockEventEmitter.cleanup());
+            disposer.add(offFunction1);
+            disposer.add(offFunction2);
+            disposer.add(() => mockEventEmitter.cleanup());
             await disposer.dispose();
             expect(offFunction1).toHaveBeenCalled();
             expect(offFunction2).toHaveBeenCalled();
@@ -180,22 +229,22 @@ describe('Disposer', () => {
         it('应该捕获并记录同步错误', async () => {
             const loggerErrorSpy = vi.spyOn(logger, 'error').mockImplementation(() => { });
             const error = new Error('Sync error');
-            disposer.addDisposer(() => {
+            disposer.add(() => {
                 throw error;
             });
             await disposer.dispose();
-            expect(loggerErrorSpy).toHaveBeenCalledWith('Error during cleanup:', error);
+            expect(loggerErrorSpy).toHaveBeenCalledWith({ error }, '[disposer] cleanup failed');
             loggerErrorSpy.mockRestore();
         });
         it('应该处理不同类型的错误', async () => {
             const loggerErrorSpy = vi.spyOn(logger, 'error').mockImplementation(() => { });
-            disposer.addDisposer(() => {
+            disposer.add(() => {
                 throw new TypeError('Type error');
             });
-            disposer.addDisposer(() => {
+            disposer.add(() => {
                 throw 'String error';
             });
-            disposer.addDisposer(() => {
+            disposer.add(() => {
                 throw { message: 'Object error' };
             });
             await disposer.dispose();
@@ -205,11 +254,11 @@ describe('Disposer', () => {
         it('应该捕获并记录异步错误', async () => {
             const loggerErrorSpy = vi.spyOn(logger, 'error').mockImplementation(() => { });
             const asyncError = new Error('Async error');
-            disposer.addDisposer(async () => {
+            disposer.add(async () => {
                 throw asyncError;
             });
             await disposer.dispose();
-            expect(loggerErrorSpy).toHaveBeenCalledWith('Error during cleanup:', asyncError);
+            expect(loggerErrorSpy).toHaveBeenCalledWith({ error: asyncError }, '[disposer] cleanup failed');
             loggerErrorSpy.mockRestore();
         });
     });

package/output/object/object.d.ts

@@ -2,6 +2,4 @@
  * 递归合并对象，只针对对象类型的属性进行合并，其他类型后者覆盖前者
  */
 export declare function objectMerge<T extends object>(target: T, ...rest: Partial<T>[]): T;
-export declare function ObjectKeys<T extends object>(obj: T): (keyof T)[];
-export declare function ObjectValues<T extends object>(obj: T): T[keyof T][];
 //# sourceMappingURL=object.d.ts.map

package/output/object/object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../../source/object/object.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAqBjF;AAED,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,CAEhE;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAEnE"}
+{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../../source/object/object.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAqBjF"}

package/output/object/object.js

@@ -22,9 +22,3 @@ export function objectMerge(target, ...rest) {
     }
     return target;
 }
-export function ObjectKeys(obj) {
-    return Object.keys(obj);
-}
-export function ObjectValues(obj) {
-    return Object.values(obj);
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taicode/common-base",
-  "version": "3.8.0",
+  "version": "4.0.0-beta.10",
   "author": "Alain",
   "license": "ISC",
   "description": "",
@@ -39,7 +39,7 @@
     "test:ci": "vitest run",
     "lint": "eslint && tsc --noEmit",
     "typecheck": "tsc --noEmit",
-    "build": "tsc -p tsconfig.json",
+    "build": "rm -rf output && tsc -p tsconfig.json",
     "dev": "tsc -p tsconfig.json --watch"
   }
 }