@taicode/common-base 1.7.4 → 1.7.6

package/output/error/error.test.js

@@ -1,11 +1,11 @@
 import { describe, it, expect } from 'vitest';
-import { UserError, SystemError, UnknownError } from './error';
+import { UserError, SystemError } from './error';
 describe('UserError', () => {
     describe('constructor', () => {
         it('应该正确创建UserError实例', () => {
             const type = 'VALIDATION_ERROR';
             const message = '输入验证失败';
-            const error = new UserError(type, message);
+            const error = new UserError(type, undefined, message);
             expect(error).toBeInstanceOf(Error);
             expect(error).toBeInstanceOf(UserError);
             expect(error.name).toBe('UserError');
@@ -32,7 +32,7 @@ describe('UserError', () => {
         });
         it('应该在提供空字符串message时保持空字符串', () => {
             const type = 'VALIDATION_ERROR';
-            const error = new UserError(type, '');
+            const error = new UserError(type, {}, '');
             expect(error).toBeInstanceOf(Error);
             expect(error).toBeInstanceOf(UserError);
             expect(error.name).toBe('UserError');
@@ -43,34 +43,32 @@ describe('UserError', () => {
             const type = 'VALIDATION_ERROR';
             const message = '输入验证失败';
             const cause = new Error('原始错误');
-            const error = new UserError(type, message, { cause });
+            const error = new UserError(type, { cause }, message);
             expect(error.cause).toBe(cause);
         });
         it('应该支持ErrorOptions参数且message为可选', () => {
             const type = 'VALIDATION_ERROR';
             const cause = new Error('原始错误');
-            const error = new UserError(type, undefined, { cause });
+            const error = new UserError(type, { cause });
             expect(error.cause).toBe(cause);
             expect(error.message).toBe('');
         });
         it('应该正确设置错误堆栈信息', () => {
-            const error = new UserError('TEST_ERROR', '测试错误');
+            const error = new UserError('TEST_ERROR', undefined, '测试错误');
             expect(error.stack).toBeDefined();
             expect(error.stack).toContain('UserError');
         });
     });
     describe('is', () => {
         it('应该正确识别UserError实例', () => {
-            const error = new UserError('TEST_ERROR', '测试错误');
+            const error = new UserError('TEST_ERROR', undefined, '测试错误');
             expect(UserError.is(error)).toBe(true);
         });
         it('应该正确识别非UserError实例', () => {
             const regularError = new Error('普通错误');
-            const systemError = new SystemError('SYSTEM_ERROR', '系统错误');
-            const unknownError = new UnknownError('未知错误');
+            const systemError = new SystemError('SYSTEM_ERROR', undefined, '系统错误');
             expect(UserError.is(regularError)).toBe(false);
             expect(UserError.is(systemError)).toBe(false);
-            expect(UserError.is(unknownError)).toBe(false);
             expect(UserError.is(null)).toBe(false);
             expect(UserError.is(undefined)).toBe(false);
             expect(UserError.is('字符串')).toBe(false);
@@ -78,7 +76,7 @@ describe('UserError', () => {
             expect(UserError.is({})).toBe(false);
         });
         it('应该支持类型守卫功能', () => {
-            const error = new UserError('TEST_ERROR', '测试错误');
+            const error = new UserError('TEST_ERROR', undefined, '测试错误');
             if (UserError.is(error)) {
                 // 在类型守卫内部，error的类型应该被正确推断
                 expect(error.type).toBe('TEST_ERROR');
@@ -86,16 +84,27 @@ describe('UserError', () => {
                 expect(error.name).toBe('UserError');
             }
         });
+        it('在原型链丢失的情况下仍能通过品牌标记正确识别', () => {
+            const error = new UserError('TEST_ERROR', undefined, '测试错误');
+            // 模拟编译/序列化后原型链丢失的情况
+            const plainObj = Object.create(null);
+            Object.assign(plainObj, error);
+            // 手动复制品牌标记（Symbol.for 在不同模块实例中指向同一个 Symbol）
+            const brand = Symbol.for('@taicode/common/UserError');
+            Object.defineProperty(plainObj, brand, { value: true });
+            expect(plainObj instanceof UserError).toBe(false); // instanceof 失效
+            expect(UserError.is(plainObj)).toBe(true); // 品牌标记仍然有效
+        });
     });
     describe('继承行为', () => {
         it('应该正确继承Error的所有属性和方法', () => {
-            const error = new UserError('TEST_ERROR', '测试错误');
+            const error = new UserError('TEST_ERROR', undefined, '测试错误');
             expect(error.toString()).toContain('测试错误');
             expect(error.toString()).toContain('UserError');
             expect(error instanceof Error).toBe(true);
         });
         it('应该支持Error的标准用法', () => {
-            const error = new UserError('TEST_ERROR', '测试错误');
+            const error = new UserError('TEST_ERROR', undefined, '测试错误');
             try {
                 throw error;
             }
@@ -111,7 +120,7 @@ describe('SystemError', () => {
         it('应该正确创建SystemError实例', () => {
             const type = 'DATABASE_ERROR';
             const message = '数据库连接失败';
-            const error = new SystemError(type, message);
+            const error = new SystemError(type, undefined, message);
             expect(error).toBeInstanceOf(Error);
             expect(error).toBeInstanceOf(SystemError);
             expect(error.name).toBe('SystemError');
@@ -138,7 +147,7 @@ describe('SystemError', () => {
         });
         it('应该在提供空字符串message时保持空字符串', () => {
             const type = 'DATABASE_ERROR';
-            const error = new SystemError(type, '');
+            const error = new SystemError(type, {}, '');
             expect(error).toBeInstanceOf(Error);
             expect(error).toBeInstanceOf(SystemError);
             expect(error.name).toBe('SystemError');
@@ -149,34 +158,32 @@ describe('SystemError', () => {
             const type = 'NETWORK_ERROR';
             const message = '网络请求失败';
             const cause = new Error('连接超时');
-            const error = new SystemError(type, message, { cause });
+            const error = new SystemError(type, { cause }, message);
             expect(error.cause).toBe(cause);
         });
         it('应该支持ErrorOptions参数且message为可选', () => {
             const type = 'NETWORK_ERROR';
             const cause = new Error('连接超时');
-            const error = new SystemError(type, undefined, { cause });
+            const error = new SystemError(type, { cause });
             expect(error.cause).toBe(cause);
             expect(error.message).toBe('');
         });
         it('应该正确设置错误堆栈信息', () => {
-            const error = new SystemError('FILE_ERROR', '文件读取失败');
+            const error = new SystemError('FILE_ERROR', undefined, '文件读取失败');
             expect(error.stack).toBeDefined();
             expect(error.stack).toContain('SystemError');
         });
     });
     describe('is', () => {
         it('应该正确识别SystemError实例', () => {
-            const error = new SystemError('TEST_ERROR', '测试错误');
+            const error = new SystemError('TEST_ERROR', undefined, '测试错误');
             expect(SystemError.is(error)).toBe(true);
         });
         it('应该正确识别非SystemError实例', () => {
             const regularError = new Error('普通错误');
-            const userError = new UserError('USER_ERROR', '用户错误');
-            const unknownError = new UnknownError('未知错误');
+            const userError = new UserError('USER_ERROR', undefined, '用户错误');
             expect(SystemError.is(regularError)).toBe(false);
             expect(SystemError.is(userError)).toBe(false);
-            expect(SystemError.is(unknownError)).toBe(false);
             expect(SystemError.is(null)).toBe(false);
             expect(SystemError.is(undefined)).toBe(false);
             expect(SystemError.is('字符串')).toBe(false);
@@ -184,7 +191,7 @@ describe('SystemError', () => {
             expect(SystemError.is({})).toBe(false);
         });
         it('应该支持类型守卫功能', () => {
-            const error = new SystemError('DATABASE_ERROR', '数据库错误');
+            const error = new SystemError('DATABASE_ERROR', undefined, '数据库错误');
             if (SystemError.is(error)) {
                 // 在类型守卫内部，error的类型应该被正确推断
                 expect(error.type).toBe('DATABASE_ERROR');
@@ -192,16 +199,26 @@ describe('SystemError', () => {
                 expect(error.name).toBe('SystemError');
             }
         });
+        it('在原型链丢失的情况下仍能通过品牌标记正确识别', () => {
+            const error = new SystemError('TEST_ERROR', undefined, '测试错误');
+            // 模拟编译/序列化后原型链丢失的情况
+            const plainObj = Object.create(null);
+            Object.assign(plainObj, error);
+            const brand = Symbol.for('@taicode/common/SystemError');
+            Object.defineProperty(plainObj, brand, { value: true });
+            expect(plainObj instanceof SystemError).toBe(false); // instanceof 失效
+            expect(SystemError.is(plainObj)).toBe(true); // 品牌标记仍然有效
+        });
     });
     describe('继承行为', () => {
         it('应该正确继承Error的所有属性和方法', () => {
-            const error = new SystemError('TEST_ERROR', '测试错误');
+            const error = new SystemError('TEST_ERROR', undefined, '测试错误');
             expect(error.toString()).toContain('测试错误');
             expect(error.toString()).toContain('SystemError');
             expect(error instanceof Error).toBe(true);
         });
         it('应该支持Error的标准用法', () => {
-            const error = new SystemError('TEST_ERROR', '测试错误');
+            const error = new SystemError('TEST_ERROR', undefined, '测试错误');
             try {
                 throw error;
             }
@@ -212,99 +229,192 @@ describe('SystemError', () => {
         });
     });
 });
-describe('UnknownError', () => {
-    describe('constructor', () => {
-        it('应该正确创建UnknownError实例', () => {
-            const message = '发生了未知错误';
-            const error = new UnknownError(message);
-            expect(error).toBeInstanceOf(Error);
-            expect(error).toBeInstanceOf(UnknownError);
-            expect(error.name).toBe('UnknownError');
-            expect(error.message).toBe(message);
-        });
-        it('应该支持ErrorOptions参数', () => {
-            const message = '未知错误';
-            const cause = new Error('原始未知错误');
-            const error = new UnknownError(message, { cause });
-            expect(error.cause).toBe(cause);
-        });
-        it('应该正确设置错误堆栈信息', () => {
-            const error = new UnknownError('测试未知错误');
-            expect(error.stack).toBeDefined();
-            expect(error.stack).toContain('UnknownError');
-        });
-    });
-    describe('is', () => {
-        it('应该正确识别UnknownError实例', () => {
-            const error = new UnknownError('测试错误');
-            expect(UnknownError.is(error)).toBe(true);
-        });
-        it('应该正确识别非UnknownError实例', () => {
-            const regularError = new Error('普通错误');
-            const userError = new UserError('USER_ERROR', '用户错误');
-            const systemError = new SystemError('SYSTEM_ERROR', '系统错误');
-            expect(UnknownError.is(regularError)).toBe(false);
-            expect(UnknownError.is(userError)).toBe(false);
-            expect(UnknownError.is(systemError)).toBe(false);
-            expect(UnknownError.is(null)).toBe(false);
-            expect(UnknownError.is(undefined)).toBe(false);
-            expect(UnknownError.is('字符串')).toBe(false);
-            expect(UnknownError.is(123)).toBe(false);
-            expect(UnknownError.is({})).toBe(false);
-        });
-    });
-    describe('继承行为', () => {
-        it('应该正确继承Error的所有属性和方法', () => {
-            const error = new UnknownError('测试错误');
-            expect(error.toString()).toContain('测试错误');
-            expect(error instanceof Error).toBe(true);
-        });
-        it('应该支持Error的标准用法', () => {
-            const error = new UnknownError('测试错误');
-            try {
-                throw error;
-            }
-            catch (caught) {
-                expect(caught).toBe(error);
-                expect(caught).toBeInstanceOf(UnknownError);
-            }
-        });
-    });
-});
 describe('错误类型区分', () => {
-    it('三种错误类型应该是不同的类', () => {
-        const userError = new UserError('USER_ERROR', '用户错误');
-        const systemError = new SystemError('SYSTEM_ERROR', '系统错误');
-        const unknownError = new UnknownError('未知错误');
+    it('两种错误类型应该是不同的类', () => {
+        const userError = new UserError('USER_ERROR', undefined, '用户错误');
+        const systemError = new SystemError('SYSTEM_ERROR', undefined, '系统错误');
         // 每种错误只能被自己的类型检查函数识别
         expect(UserError.is(userError)).toBe(true);
         expect(SystemError.is(userError)).toBe(false);
-        expect(UnknownError.is(userError)).toBe(false);
         expect(UserError.is(systemError)).toBe(false);
         expect(SystemError.is(systemError)).toBe(true);
-        expect(UnknownError.is(systemError)).toBe(false);
-        expect(UserError.is(unknownError)).toBe(false);
-        expect(SystemError.is(unknownError)).toBe(false);
-        expect(UnknownError.is(unknownError)).toBe(true);
     });
     it('所有错误类型都应该是Error的实例', () => {
-        const userError = new UserError('USER_ERROR', '用户错误');
-        const systemError = new SystemError('SYSTEM_ERROR', '系统错误');
-        const unknownError = new UnknownError('未知错误');
+        const userError = new UserError('USER_ERROR', undefined, '用户错误');
+        const systemError = new SystemError('SYSTEM_ERROR', undefined, '系统错误');
         expect(userError instanceof Error).toBe(true);
         expect(systemError instanceof Error).toBe(true);
-        expect(unknownError instanceof Error).toBe(true);
+    });
+    it('define 创建的 BoundError 也能被基类 is 方法识别', () => {
+        const MyUserError = UserError.define({
+            'test': {}
+        });
+        const MySystemError = SystemError.define({
+            'test': {}
+        });
+        const userError = new MyUserError('test', { msg: 'hello' }, '测试');
+        const systemError = new MySystemError('test', { msg: 'world' }, '测试');
+        // 基类的 is 方法应该能识别 define 创建的子类实例
+        expect(UserError.is(userError)).toBe(true);
+        expect(SystemError.is(systemError)).toBe(true);
+        // 但不会互相匹配
+        expect(UserError.is(systemError)).toBe(false);
+        expect(SystemError.is(userError)).toBe(false);
     });
 });
 describe('泛型类型支持', () => {
     it('UserError应该支持字符串字面量类型', () => {
-        const error = new UserError('REQUIRED_FIELD', '字段必填');
+        const error = new UserError('REQUIRED_FIELD', {}, '字段必填');
         expect(error.type).toBe('REQUIRED_FIELD');
         expect(UserError.is(error)).toBe(true);
     });
     it('SystemError应该支持字符串字面量类型', () => {
-        const error = new SystemError('DATABASE_ERROR', '数据库连接失败');
+        const error = new SystemError('DATABASE_ERROR', {}, '数据库连接失败');
         expect(error.type).toBe('DATABASE_ERROR');
         expect(SystemError.is(error)).toBe(true);
     });
 });
+describe('define 工厂方法', () => {
+    describe('UserError.define', () => {
+        it('应该定义一个绑定了特定错误类型的 UserError 类', () => {
+            const MyUserError = UserError.define({
+                'validation-failed': {},
+                'permission-denied': {},
+                'not-found': {}
+            });
+            const error = new MyUserError('validation-failed', {
+                field: 'email',
+                value: 'invalid@'
+            }, '验证失败');
+            expect(error).toBeInstanceOf(Error);
+            expect(error.name).toBe('UserError');
+            expect(error.type).toBe('validation-failed');
+            expect(error.message).toBe('验证失败');
+            expect(error.context).toEqual({ field: 'email', value: 'invalid@' });
+        });
+        it('应该支持 is 类型守卫', () => {
+            const MyUserError = UserError.define({
+                'test-error': {}
+            });
+            const error = new MyUserError('test-error', { code: 123 }, '测试错误');
+            expect(MyUserError.is(error)).toBe(true);
+            expect(MyUserError.is(new Error('普通错误'))).toBe(false);
+            expect(MyUserError.is(null)).toBe(false);
+        });
+        it('应该支持多次调用 define 定义不同的错误类', () => {
+            const ValidationError = UserError.define({
+                'required': {},
+                'invalid': {}
+            });
+            const AuthError = UserError.define({
+                'unauthorized': {},
+                'forbidden': {}
+            });
+            const validationError = new ValidationError('required', { field: 'username' }, '必填字段');
+            const authError = new AuthError('unauthorized', { reason: 'token expired' }, '未授权');
+            expect(validationError.type).toBe('required');
+            expect(authError.type).toBe('unauthorized');
+            expect(ValidationError.is(validationError)).toBe(true);
+            expect(ValidationError.is(authError)).toBe(false); // 不同的类不会互相识别
+            expect(AuthError.is(authError)).toBe(true);
+            expect(AuthError.is(validationError)).toBe(false); // 不同的类不会互相识别
+        });
+        it('应该支持不传 context 参数', () => {
+            const MyUserError = UserError.define({
+                'simple-error': {}
+            });
+            const error = new MyUserError('simple-error', undefined, '简单错误');
+            expect(error.type).toBe('simple-error');
+            expect(error.message).toBe('简单错误');
+            expect(error.context).toBeUndefined();
+        });
+        it('应该支持不传 message 参数', () => {
+            const MyUserError = UserError.define({
+                'no-message': {}
+            });
+            const error = new MyUserError('no-message');
+            expect(error.type).toBe('no-message');
+            expect(error.message).toBe('');
+        });
+        it('应该暴露所有定义的错误类型', () => {
+            const MyUserError = UserError.define({
+                'validation-failed': {},
+                'permission-denied': {},
+                'not-found': {}
+            });
+            expect(MyUserError.types).toEqual(['validation-failed', 'permission-denied', 'not-found']);
+            expect(MyUserError.types).toHaveLength(3);
+        });
+    });
+    describe('SystemError.define', () => {
+        it('应该定义一个绑定了特定错误类型的 SystemError 类', () => {
+            const MySystemError = SystemError.define({
+                'database-error': {},
+                'network-error': {},
+                'service-unavailable': {}
+            });
+            const error = new MySystemError('database-error', {
+                query: 'SELECT * FROM users',
+                table: 'users'
+            }, '数据库错误');
+            expect(error).toBeInstanceOf(Error);
+            expect(error.name).toBe('SystemError');
+            expect(error.type).toBe('database-error');
+            expect(error.message).toBe('数据库错误');
+            expect(error.context).toEqual({ query: 'SELECT * FROM users', table: 'users' });
+        });
+        it('应该支持 is 类型守卫', () => {
+            const MySystemError = SystemError.define({
+                'test-error': {}
+            });
+            const error = new MySystemError('test-error', { code: 500 }, '测试错误');
+            expect(MySystemError.is(error)).toBe(true);
+            expect(MySystemError.is(new Error('普通错误'))).toBe(false);
+            expect(MySystemError.is(null)).toBe(false);
+        });
+        it('应该支持多次调用 define 定义不同的错误类', () => {
+            const DatabaseError = SystemError.define({
+                'connection-failed': {},
+                'query-timeout': {}
+            });
+            const NetworkError = SystemError.define({
+                'request-failed': {},
+                'timeout': {}
+            });
+            const dbError = new DatabaseError('connection-failed', { host: 'localhost', port: 5432 }, '连接失败');
+            const netError = new NetworkError('request-failed', { url: '/api/data', method: 'GET' }, '请求失败');
+            expect(dbError.type).toBe('connection-failed');
+            expect(netError.type).toBe('request-failed');
+            expect(DatabaseError.is(dbError)).toBe(true);
+            expect(DatabaseError.is(netError)).toBe(false); // 不同的类不会互相识别
+            expect(NetworkError.is(netError)).toBe(true);
+            expect(NetworkError.is(dbError)).toBe(false); // 不同的类不会互相识别
+        });
+        it('应该支持不传 context 参数', () => {
+            const MySystemError = SystemError.define({
+                'simple-error': {}
+            });
+            const error = new MySystemError('simple-error', undefined, '简单错误');
+            expect(error.type).toBe('simple-error');
+            expect(error.message).toBe('简单错误');
+            expect(error.context).toBeUndefined();
+        });
+        it('应该支持不传 message 参数', () => {
+            const MySystemError = SystemError.define({
+                'no-message': {}
+            });
+            const error = new MySystemError('no-message');
+            expect(error.type).toBe('no-message');
+            expect(error.message).toBe('');
+        });
+        it('应该暴露所有定义的错误类型', () => {
+            const MySystemError = SystemError.define({
+                'database-error': {},
+                'network-error': {},
+                'service-unavailable': {}
+            });
+            expect(MySystemError.types).toEqual(['database-error', 'network-error', 'service-unavailable']);
+            expect(MySystemError.types).toHaveLength(3);
+        });
+    });
+});

package/output/error/index.d.ts

@@ -1,2 +1,3 @@
-export { UserError, SystemError, UnknownError, UserErrorTypes, SystemErrorTypes, UserErrorType, SystemErrorType, UserErrorContext, SystemErrorContext } from './error';
+export { UserError, SystemError } from './error';
+export type { ErrorContext } from './error';
 //# sourceMappingURL=index.d.ts.map

package/output/error/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/error/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,WAAW,EACX,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/error/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,WAAW,EACZ,MAAM,SAAS,CAAA;AAEhB,YAAY,EACV,YAAY,EACb,MAAM,SAAS,CAAA"}

package/output/error/index.js

@@ -1 +1 @@
-export { UserError, SystemError, UnknownError } from './error';
+export { UserError, SystemError } from './error';

package/output/events/disposer.d.ts

@@ -0,0 +1,6 @@
+export declare class Disposer {
+    private cleanupFunctions;
+    addDisposer(cleanupFn: () => unknown): void;
+    dispose(): void;
+}
+//# sourceMappingURL=disposer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disposer.d.ts","sourceRoot":"","sources":["../../source/events/disposer.ts"],"names":[],"mappings":"AAAA,qBAAa,QAAQ;IACnB,OAAO,CAAC,gBAAgB,CAAyB;IAGjD,WAAW,CAAC,SAAS,EAAE,MAAM,OAAO,GAAG,IAAI;IAK3C,OAAO,IAAI,IAAI;CAUhB"}

package/output/events/disposer.js

@@ -0,0 +1,19 @@
+export class Disposer {
+    cleanupFunctions = [];
+    // 添加清理函数
+    addDisposer(cleanupFn) {
+        this.cleanupFunctions.push(cleanupFn);
+    }
+    // 执行所有清理函数
+    dispose() {
+        for (const cleanupFn of this.cleanupFunctions) {
+            try {
+                cleanupFn();
+            }
+            catch (error) {
+                console.error('Error during cleanup:', error);
+            }
+        }
+        this.cleanupFunctions = []; // 清空清理函数列表
+    }
+}

package/output/events/disposer.test.d.ts

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

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

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