@taicode/common-base 1.7.3 → 1.7.5

package/output/error/error.d.ts

@@ -1,85 +1,122 @@
 /**
  * 错误类型模块
- * key 为错误的类型
- * value 为错误的上下文类型
- * 错误的上下文可以帮助系统更好的理解和处理错误
- * 一般存放的是错误发生时的关键信息，例如请求的路径，参数等等
- * 输入错误时输入的字段信息，校验规则等等
- * 可以通过模块声明合并来定义全局错误类型：
  *
- * @example
- * ```typescript
- * declare module '@taicode/common-base/error' {
- *   interface UserErrorTypes {
- *     'validation-failed': { field?: string; value?: unknown; rule?: string }
- *     'permission-denied': { resource?: string; action?: string; userId?: string }
- *     'not-found': { id?: string; type?: string; query?: Record<string, unknown> }
- *   }
+ * 提供两种错误类型：
+ * - UserError: 用户可见的错误（如验证失败、权限不足等）
+ * - SystemError: 系统内部错误（如数据库错误、网络错误等）
  *
- *   interface SystemErrorTypes {
- *     'database-error': { query?: string; table?: string; operation?: string }
- *     'network-error': { url?: string; method?: string; status?: number }
- *     'service-unavailable': { service?: string; endpoint?: string; retryAfter?: number }
- *   }
- * }
+ * **错误类型命名规范**：推荐使用全大写、下划线分割的风格（如 `VALIDATION_FAILED`）
  *
- * // 然后可以这样使用：
- * const userError = new UserError('validation-failed', '邮箱格式无效', {
- *   field: 'email',
- *   value: 'invalid-email',
- *   rule: 'email-format'
+ * @example
+ * ```typescript
+ * // 1. 使用 define 方法定义类型安全的错误类
+ * const MyUserError = UserError.define({
+ *   'VALIDATION_FAILED': {} as { field?: string; value?: unknown },
+ *   'PERMISSION_DENIED': {} as { resource?: string; action?: string },
+ *   'NOT_FOUND': {} as { id?: string; type?: string }
  * })
- * // 或者省略 message，直接使用 type 作为消息
- * const userError2 = new UserError('validation-failed', undefined, {
+ *
+ * // type 会被自动推导和限制
+ * const error = new MyUserError('VALIDATION_FAILED', {
  *   field: 'email',
- *   value: 'invalid-email',
- *   rule: 'email-format'
- * })
- * const systemError = new SystemError('database-error', '数据库连接失败', {
- *   table: 'users',
- *   query: 'SELECT * FROM users',
- *   operation: 'select'
- * })
- * // 或者省略 message
- * const systemError2 = new SystemError('database-error', undefined, {
- *   table: 'users',
- *   query: 'SELECT * FROM users',
- *   operation: 'select'
- * })
+ *   value: 'invalid@'
+ * }, '验证失败')
+ *
+ * // 获取所有定义的错误类型
+ * console.log(MyUserError.types) // ['VALIDATION_FAILED', 'PERMISSION_DENIED', 'NOT_FOUND']
+ *
+ * // 2. 直接使用基础错误类
+ * const error2 = new UserError('CUSTOM_ERROR', undefined, '自定义错误')
+ * const error3 = new SystemError('DATABASE_ERROR', undefined, '数据库错误')
+ *
+ * // 3. 使用类型守卫检查错误
+ * if (MyUserError.is(error)) {
+ *   console.log(error.type, error.context)
+ * }
  * ```
  */
-interface ErrorContext {
-    /** 导致此错误的原因，通常是另一个错误或异常 */
+/**
+ * 错误上下文接口
+ * 可以通过交叉类型扩展自定义属性
+ */
+export interface ErrorContext {
+    /** 导致此错误的原因 */
     cause?: unknown;
+    /** 允许扩展其他属性 */
+    [key: string]: unknown;
 }
-export interface UserErrorTypes {
-}
-export interface SystemErrorTypes {
-}
-export type UserErrorType = keyof UserErrorTypes extends never ? string : Extract<keyof UserErrorTypes, string>;
-export type SystemErrorType = keyof SystemErrorTypes extends never ? string : Extract<keyof SystemErrorTypes, string>;
-export type UserErrorContext<T extends string> = T extends keyof UserErrorTypes ? UserErrorTypes[T] & ErrorContext : ErrorContext;
-export type SystemErrorContext<T extends string> = T extends keyof SystemErrorTypes ? SystemErrorTypes[T] & ErrorContext : ErrorContext;
-/** 用户可见的错误 */
-export declare class UserError<T extends UserErrorType = UserErrorType> extends Error {
+/**
+ * 用户可见的错误
+ * 用于表示用户操作导致的错误，如验证失败、权限不足等
+ */
+export declare class UserError<T extends string = string> extends Error {
     type: T;
+    context?: ErrorContext | undefined;
     message: string;
-    context?: UserErrorContext<T> | undefined;
-    constructor(type: T, message?: string, context?: UserErrorContext<T> | undefined);
-    static is<T extends UserErrorType = UserErrorType>(error: unknown): error is UserError<T>;
+    constructor(type: T, context?: ErrorContext | undefined, message?: string);
+    static is<T extends string = string>(error: unknown): error is UserError<T>;
+    /**
+     * 定义一个绑定了特定错误类型的 UserError 类
+     * @param errorTypes 错误类型定义对象，key 为错误类型，value 为上下文类型
+     * @returns 返回绑定了特定类型的 UserError 类
+     */
+    static define<Types extends Record<string, ErrorContext>>(errorTypes: Types): {
+        new (type: Extract<keyof Types, string>, context?: Types[Extract<keyof Types, string>], message?: string): {
+            readonly type: Extract<keyof Types, string>;
+            readonly context?: Types[Extract<keyof Types, string>];
+            name: string;
+            message: string;
+            stack?: string;
+            cause?: unknown;
+        };
+        /** 获取所有定义的错误类型 */
+        readonly types: Extract<keyof Types, string>[];
+        is(error: unknown): error is {
+            readonly type: Extract<keyof Types, string>;
+            readonly context?: Types[Extract<keyof Types, string>];
+            name: string;
+            message: string;
+            stack?: string;
+            cause?: unknown;
+        };
+        isError(error: unknown): error is Error;
+    };
 }
-/** 系统错误 */
-export declare class SystemError<T extends SystemErrorType = SystemErrorType> extends Error {
+/**
+ * 系统内部错误
+ * 用于表示系统层面的错误，如数据库错误、网络错误等
+ */
+export declare class SystemError<T extends string = string> extends Error {
     type: T;
-    message: string;
-    context?: SystemErrorContext<T> | undefined;
-    constructor(type: T, message?: string, context?: SystemErrorContext<T> | undefined);
-    static is<T extends SystemErrorType = SystemErrorType>(error: unknown): error is SystemError<T>;
-}
-export declare class UnknownError extends Error {
     context?: ErrorContext | undefined;
-    constructor(message: string, context?: ErrorContext | undefined);
-    static is(error: unknown): error is UnknownError;
+    message: string;
+    constructor(type: T, context?: ErrorContext | undefined, message?: string);
+    static is<T extends string = string>(error: unknown): error is SystemError<T>;
+    /**
+     * 定义一个绑定了特定错误类型的 SystemError 类
+     * @param errorTypes 错误类型定义对象，key 为错误类型，value 为上下文类型
+     * @returns 返回绑定了特定类型的 SystemError 类
+     */
+    static define<Types extends Record<string, ErrorContext>>(errorTypes: Types): {
+        new (type: Extract<keyof Types, string>, context?: Types[Extract<keyof Types, string>], message?: string): {
+            readonly type: Extract<keyof Types, string>;
+            readonly context?: Types[Extract<keyof Types, string>];
+            name: string;
+            message: string;
+            stack?: string;
+            cause?: unknown;
+        };
+        /** 获取所有定义的错误类型 */
+        readonly types: Extract<keyof Types, string>[];
+        is(error: unknown): error is {
+            readonly type: Extract<keyof Types, string>;
+            readonly context?: Types[Extract<keyof Types, string>];
+            name: string;
+            message: string;
+            stack?: string;
+            cause?: unknown;
+        };
+        isError(error: unknown): error is Error;
+    };
 }
-export {};
 //# sourceMappingURL=error.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../source/error/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,UAAU,YAAY;IACpB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAID,MAAM,WAAW,cAAc;CAAG;AAClC,MAAM,WAAW,gBAAgB;CAAG;AAGpC,MAAM,MAAM,aAAa,GAAG,MAAM,cAAc,SAAS,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,cAAc,EAAE,MAAM,CAAC,CAAA;AAC/G,MAAM,MAAM,eAAe,GAAG,MAAM,gBAAgB,SAAS,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,gBAAgB,EAAE,MAAM,CAAC,CAAA;AAGrH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,cAAc,GAC3E,cAAc,CAAC,CAAC,CAAC,GAAG,YAAY,GAChC,YAAY,CAAA;AAEhB,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,MAAM,gBAAgB,GAC/E,gBAAgB,CAAC,CAAC,CAAC,GAAG,YAAY,GAClC,YAAY,CAAA;AAEhB,cAAc;AACd,qBAAa,SAAS,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,CAAE,SAAQ,KAAK;IACxD,IAAI,EAAE,CAAC;IAAS,OAAO,EAAE,MAAM;IAAc,OAAO,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC;gBAA1E,IAAI,EAAE,CAAC,EAAS,OAAO,GAAE,MAAW,EAAS,OAAO,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC,YAAA;IAK7F,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAAC,CAAC,CAAC;CAG1F;AAED,WAAW;AACX,qBAAa,WAAW,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,CAAE,SAAQ,KAAK;IAC9D,IAAI,EAAE,CAAC;IAAS,OAAO,EAAE,MAAM;IAAc,OAAO,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC;gBAA5E,IAAI,EAAE,CAAC,EAAS,OAAO,GAAE,MAAW,EAAS,OAAO,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,YAAA;IAK/F,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAAC,CAAC,CAAC;CAGhG;AAED,qBAAa,YAAa,SAAQ,KAAK;IACD,OAAO,CAAC,EAAE,YAAY;gBAA9C,OAAO,EAAE,MAAM,EAAS,OAAO,CAAC,EAAE,YAAY,YAAA;IAK1D,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY;CAGjD"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../source/error/error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,eAAe;IACf,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,eAAe;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;;GAGG;AACH,qBAAa,SAAS,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,KAAK;IAEpD,IAAI,EAAE,CAAC;IACP,OAAO,CAAC,EAAE,YAAY;IACtB,OAAO,EAAE,MAAM;gBAFf,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,YAAY,YAAA,EACtB,OAAO,GAAE,MAAW;IAM7B,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAAC,CAAC,CAAC;IAI3E;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,UAAU,EAAE,KAAK;2DAY3D,KAAK,8BAAW,YACjB,MAAM;;+BARS,KAAK,8BAAW;;;;;;QAE1C,kBAAkB;wBACiC,8BAAW;kBAa7C,OAAO,GAAG,KAAK;;+BAhBN,KAAK,8BAAW;;;;;SAgBQ;;;CAKvD;AAED;;;GAGG;AACH,qBAAa,WAAW,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,KAAK;IAEtD,IAAI,EAAE,CAAC;IACP,OAAO,CAAC,EAAE,YAAY;IACtB,OAAO,EAAE,MAAM;gBAFf,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE,YAAY,YAAA,EACtB,OAAO,GAAE,MAAW;IAM7B,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAAC,CAAC,CAAC;IAI7E;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,UAAU,EAAE,KAAK;2DAY3D,KAAK,8BAAW,YACjB,MAAM;;+BARS,KAAK,8BAAW;;;;;;QAE1C,kBAAkB;wBACiC,8BAAW;kBAa7C,OAAO,GAAG,KAAK;;+BAhBN,KAAK,8BAAW;;;;;SAgBU;;;CAKzD"}

package/output/error/error.js

@@ -1,93 +1,119 @@
 /**
  * 错误类型模块
- * key 为错误的类型
- * value 为错误的上下文类型
- * 错误的上下文可以帮助系统更好的理解和处理错误
- * 一般存放的是错误发生时的关键信息，例如请求的路径，参数等等
- * 输入错误时输入的字段信息，校验规则等等
- * 可以通过模块声明合并来定义全局错误类型：
  *
- * @example
- * ```typescript
- * declare module '@taicode/common-base/error' {
- *   interface UserErrorTypes {
- *     'validation-failed': { field?: string; value?: unknown; rule?: string }
- *     'permission-denied': { resource?: string; action?: string; userId?: string }
- *     'not-found': { id?: string; type?: string; query?: Record<string, unknown> }
- *   }
+ * 提供两种错误类型：
+ * - UserError: 用户可见的错误（如验证失败、权限不足等）
+ * - SystemError: 系统内部错误（如数据库错误、网络错误等）
  *
- *   interface SystemErrorTypes {
- *     'database-error': { query?: string; table?: string; operation?: string }
- *     'network-error': { url?: string; method?: string; status?: number }
- *     'service-unavailable': { service?: string; endpoint?: string; retryAfter?: number }
- *   }
- * }
+ * **错误类型命名规范**：推荐使用全大写、下划线分割的风格（如 `VALIDATION_FAILED`）
  *
- * // 然后可以这样使用：
- * const userError = new UserError('validation-failed', '邮箱格式无效', {
- *   field: 'email',
- *   value: 'invalid-email',
- *   rule: 'email-format'
+ * @example
+ * ```typescript
+ * // 1. 使用 define 方法定义类型安全的错误类
+ * const MyUserError = UserError.define({
+ *   'VALIDATION_FAILED': {} as { field?: string; value?: unknown },
+ *   'PERMISSION_DENIED': {} as { resource?: string; action?: string },
+ *   'NOT_FOUND': {} as { id?: string; type?: string }
  * })
- * // 或者省略 message，直接使用 type 作为消息
- * const userError2 = new UserError('validation-failed', undefined, {
+ *
+ * // type 会被自动推导和限制
+ * const error = new MyUserError('VALIDATION_FAILED', {
  *   field: 'email',
- *   value: 'invalid-email',
- *   rule: 'email-format'
- * })
- * const systemError = new SystemError('database-error', '数据库连接失败', {
- *   table: 'users',
- *   query: 'SELECT * FROM users',
- *   operation: 'select'
- * })
- * // 或者省略 message
- * const systemError2 = new SystemError('database-error', undefined, {
- *   table: 'users',
- *   query: 'SELECT * FROM users',
- *   operation: 'select'
- * })
+ *   value: 'invalid@'
+ * }, '验证失败')
+ *
+ * // 获取所有定义的错误类型
+ * console.log(MyUserError.types) // ['VALIDATION_FAILED', 'PERMISSION_DENIED', 'NOT_FOUND']
+ *
+ * // 2. 直接使用基础错误类
+ * const error2 = new UserError('CUSTOM_ERROR', undefined, '自定义错误')
+ * const error3 = new SystemError('DATABASE_ERROR', undefined, '数据库错误')
+ *
+ * // 3. 使用类型守卫检查错误
+ * if (MyUserError.is(error)) {
+ *   console.log(error.type, error.context)
+ * }
  * ```
  */
-/** 用户可见的错误 */
+/**
+ * 用户可见的错误
+ * 用于表示用户操作导致的错误，如验证失败、权限不足等
+ */
 export class UserError extends Error {
     type;
-    message;
     context;
-    constructor(type, message = '', context) {
+    message;
+    constructor(type, context, message = '') {
         super(message, context);
         this.type = type;
-        this.message = message;
         this.context = context;
+        this.message = message;
         this.name = 'UserError';
     }
     static is(error) {
         return error instanceof UserError;
     }
+    /**
+     * 定义一个绑定了特定错误类型的 UserError 类
+     * @param errorTypes 错误类型定义对象，key 为错误类型，value 为上下文类型
+     * @returns 返回绑定了特定类型的 UserError 类
+     */
+    static define(errorTypes) {
+        return class BoundUserError extends Error {
+            type;
+            context;
+            /** 获取所有定义的错误类型 */
+            static types = Object.keys(errorTypes);
+            constructor(type, context, message = '') {
+                super(message, context);
+                this.name = 'UserError';
+                this.type = type;
+                this.context = context;
+            }
+            static is(error) {
+                return error instanceof BoundUserError;
+            }
+        };
+    }
 }
-/** 系统错误 */
+/**
+ * 系统内部错误
+ * 用于表示系统层面的错误，如数据库错误、网络错误等
+ */
 export class SystemError extends Error {
     type;
-    message;
     context;
-    constructor(type, message = '', context) {
+    message;
+    constructor(type, context, message = '') {
         super(message, context);
         this.type = type;
-        this.message = message;
         this.context = context;
+        this.message = message;
         this.name = 'SystemError';
     }
     static is(error) {
         return error instanceof SystemError;
     }
-}
-export class UnknownError extends Error {
-    context;
-    constructor(message, context) {
-        super(message, context);
-        this.context = context;
-        this.name = 'UnknownError';
-    }
-    static is(error) {
-        return error instanceof UnknownError;
+    /**
+     * 定义一个绑定了特定错误类型的 SystemError 类
+     * @param errorTypes 错误类型定义对象，key 为错误类型，value 为上下文类型
+     * @returns 返回绑定了特定类型的 SystemError 类
+     */
+    static define(errorTypes) {
+        return class BoundSystemError extends Error {
+            type;
+            context;
+            /** 获取所有定义的错误类型 */
+            static types = Object.keys(errorTypes);
+            constructor(type, context, message = '') {
+                super(message, context);
+                this.name = 'SystemError';
+                this.type = type;
+                this.context = context;
+            }
+            static is(error) {
+                return error instanceof BoundSystemError;
+            }
+        };
     }
 }

package/output/error/error.test.d.ts

@@ -1,19 +1,2 @@
-declare module './error' {
-    interface UserErrorTypes {
-        VALIDATION_ERROR: unknown;
-        TEST_ERROR: unknown;
-        USER_ERROR: unknown;
-        REQUIRED_FIELD: unknown;
-        INVALID_FORMAT: unknown;
-        OUT_OF_RANGE: unknown;
-    }
-    interface SystemErrorTypes {
-        DATABASE_ERROR: unknown;
-        NETWORK_ERROR: unknown;
-        FILE_ERROR: unknown;
-        TEST_ERROR: unknown;
-        SYSTEM_ERROR: unknown;
-    }
-}
 export {};
 //# sourceMappingURL=error.test.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"error.test.d.ts","sourceRoot":"","sources":["../../source/error/error.test.ts"],"names":[],"mappings":"AAGA,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,gBAAgB,EAAE,OAAO,CAAA;QACzB,UAAU,EAAE,OAAO,CAAA;QACnB,UAAU,EAAE,OAAO,CAAA;QACnB,cAAc,EAAE,OAAO,CAAA;QACvB,cAAc,EAAE,OAAO,CAAA;QACvB,YAAY,EAAE,OAAO,CAAA;KACtB;IAED,UAAU,gBAAgB;QACxB,cAAc,EAAE,OAAO,CAAA;QACvB,aAAa,EAAE,OAAO,CAAA;QACtB,UAAU,EAAE,OAAO,CAAA;QACnB,UAAU,EAAE,OAAO,CAAA;QACnB,YAAY,EAAE,OAAO,CAAA;KACtB;CACF"}
+{"version":3,"file":"error.test.d.ts","sourceRoot":"","sources":["../../source/error/error.test.ts"],"names":[],"mappings":""}