@taicode/common-base 4.0.0-beta.2 → 4.0.0-beta.4

package/output/disposer/disposer.d.ts

@@ -1,6 +1,24 @@
 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;
+    constructor(opts?: DisposerOptions);
     add(cleanupFn: CleanupFunction): void;
     dispose(): Promise<void>;
 }

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,GAAG,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI;IAK/B,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;
+    }
     // 添加清理函数
     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

@@ -54,15 +54,16 @@ describe('Disposer', () => {
             expect(cleanupFn2).toHaveBeenCalledOnce();
             expect(cleanupFn3).toHaveBeenCalledOnce();
         });
-        it('应该按添加顺序执行清理函数', async () => {
+        it('应该按添加顺序的**逆序**（LIFO）执行清理函数', async () => {
             const executionOrder = [];
             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.add(async () => {
                 await Promise.resolve();
@@ -77,7 +78,7 @@ describe('Disposer', () => {
                 executionOrder.push(3);
             });
             await disposer.dispose();
-            expect(executionOrder).toEqual([1, 2, 3]);
+            expect(executionOrder).toEqual([3, 2, 1]);
         });
         it('应该处理清理函数中的错误', async () => {
             const workingFn1 = vi.fn();
@@ -97,7 +98,7 @@ 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 () => {
@@ -131,6 +132,54 @@ describe('Disposer', () => {
             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();
@@ -184,7 +233,7 @@ describe('Disposer', () => {
                 throw error;
             });
             await disposer.dispose();
-            expect(loggerErrorSpy).toHaveBeenCalledWith('Error during cleanup:', error);
+            expect(loggerErrorSpy).toHaveBeenCalledWith({ error }, '[disposer] cleanup failed');
             loggerErrorSpy.mockRestore();
         });
         it('应该处理不同类型的错误', async () => {
@@ -209,7 +258,7 @@ describe('Disposer', () => {
                 throw asyncError;
             });
             await disposer.dispose();
-            expect(loggerErrorSpy).toHaveBeenCalledWith('Error during cleanup:', asyncError);
+            expect(loggerErrorSpy).toHaveBeenCalledWith({ error: asyncError }, '[disposer] cleanup failed');
             loggerErrorSpy.mockRestore();
         });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taicode/common-base",
-  "version": "4.0.0-beta.2",
+  "version": "4.0.0-beta.4",
   "author": "Alain",
   "license": "ISC",
   "description": "",
@@ -20,6 +20,15 @@
       "default": "./output/*/index.js"
     }
   },
+  "scripts": {
+    "test": "vitest run",
+    "test:ci": "vitest run",
+    "lint": "eslint && tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf output && tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
   "files": [
     "output"
   ],
@@ -33,13 +42,5 @@
     "mobx": "^6.15.0",
     "typescript-eslint": "^8.56.1",
     "vitest": "^3.2.4"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "test:ci": "vitest run",
-    "lint": "eslint && tsc --noEmit",
-    "typecheck": "tsc --noEmit",
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsc -p tsconfig.json --watch"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 TaicodeLabs
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.