@longzai-intelligence/error-core 0.0.1

package/README.md

@@ -0,0 +1,140 @@
+# @longzai-intelligence/error-core
+
+领域错误的核心异常类包，提供统一的错误处理机制。
+
+## 概述
+
+本包提供了领域驱动设计的核心异常类，包括：
+
+- **DomainError**: 领域错误抽象基类
+- **ValidationError**: 验证错误
+- **EntityNotFoundError**: 实体未找到错误
+- **RepositoryError**: 仓储操作错误
+- **PermissionDeniedError**: 权限拒绝错误
+- **BusinessRuleError**: 业务规则错误
+- **ConcurrencyError**: 并发冲突错误
+- **ConfigurationError**: 配置错误
+- **ExternalServiceError**: 外部服务错误
+- **DuplicateEntityError**: 实体重复错误
+- **AuthenticationError**: 认证错误
+- **NotFoundError**: 资源未找到错误
+
+## 安装
+
+```bash
+bun add @longzai-intelligence/error-core
+```
+
+## 核心概念
+
+### DomainError
+
+所有领域异常的抽象基类，提供统一的错误处理接口。
+
+特性：
+- 错误代码：用于程序化识别错误类型
+- 上下文信息：附加与错误相关的额外数据
+- JSON 序列化：支持日志记录和 API 响应
+
+### 错误分类
+
+| 错误类 | 用途 |
+|--------|------|
+| ValidationError | 输入验证失败、业务规则校验失败 |
+| EntityNotFoundError | 实体在数据库中不存在 |
+| RepositoryError | 数据库操作失败、持久化层错误 |
+| PermissionDeniedError | 权限不足、操作被拒绝 |
+| BusinessRuleError | 业务规则违反 |
+| ConcurrencyError | 并发冲突、乐观锁失败 |
+| ConfigurationError | 配置缺失或无效 |
+| ExternalServiceError | 外部服务调用失败 |
+| DuplicateEntityError | 实体已存在、唯一约束冲突 |
+| AuthenticationError | 认证失败、会话过期 |
+| NotFoundError | 通用资源未找到 |
+
+## 使用示例
+
+### 导入错误类
+
+```typescript
+import {
+  DomainError,
+  ValidationError,
+  EntityNotFoundError,
+  RepositoryError,
+  PermissionDeniedError,
+} from '@longzai-intelligence/error-core';
+```
+
+### 使用工厂函数
+
+```typescript
+import {
+  createValidationError,
+  createEntityNotFoundError,
+  createRepositoryError,
+  createPermissionDeniedError,
+} from '@longzai-intelligence/error-core';
+
+// 验证失败
+throw createValidationError('用户名格式不正确', 'username', username);
+
+// 实体不存在
+throw createEntityNotFoundError('用户', userId);
+
+// 仓储操作失败
+throw createRepositoryError('获取用户列表失败', error);
+
+// 权限不足
+throw createPermissionDeniedError('包', '发布');
+```
+
+### 自定义领域错误
+
+```typescript
+import { DomainError } from '@longzai-intelligence/error-core';
+
+class InsufficientBalanceError extends DomainError {
+  constructor(userId: string, balance: number, required: number) {
+    super(
+      `余额不足: 当前 ${balance}, 需要 ${required}`,
+      'INSUFFICIENT_BALANCE',
+      { userId, balance, required }
+    );
+  }
+}
+```
+
+### 错误序列化
+
+```typescript
+try {
+  // 业务操作
+} catch (error) {
+  if (error instanceof DomainError) {
+    console.log(error.toJSON());
+    // {
+    //   name: 'ValidationError',
+    //   code: 'VALIDATION_ERROR',
+    //   message: '用户名格式不正确',
+    //   context: { field: 'username', value: 'abc' },
+    //   stack: '...'
+    // }
+  }
+}
+```
+
+## 设计原则
+
+- **类型安全**: 所有错误类都继承自 DomainError 基类
+- **上下文丰富**: 错误携带详细的上下文信息
+- **可序列化**: 支持转换为 JSON 用于日志和 API 响应
+- **语义清晰**: 错误类名直接表达错误含义
+
+## 相关包
+
+- `@longzai-intelligence/error-utils`: 错误处理工具函数
+
+## 许可证
+
+UNLICENSED

package/dist/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=class extends Error{constructor(e,t=`DOMAIN_ERROR`,n){super(e),this.code=t,this.context=n,this.name=`DomainError`}toJSON(){return{name:this.name,code:this.code,message:this.message,context:this.context,stack:this.stack}}},t=class extends e{constructor(e,t,n){super(e,`VALIDATION_ERROR`,{field:t,value:n}),this.field=t,this.value=n,this.name=`ValidationError`}},n=class extends e{constructor(e,t){super(`${e} 未找到: ${t}`,`ENTITY_NOT_FOUND`,{entityType:e,entityId:t}),this.entityType=e,this.entityId=t,this.name=`EntityNotFoundError`}},r=class extends e{constructor(e,t,n){super(e,`REPOSITORY_ERROR`,n),this.cause=t,this.name=`RepositoryError`}toJSON(){return{...super.toJSON(),cause:this.cause?.message}}},i=class extends e{constructor(e,t){super(`无权限执行操作: ${t} on ${e}`,`PERMISSION_DENIED`,{resource:e,action:t}),this.resource=e,this.action=t,this.name=`PermissionDeniedError`}},a=class extends e{constructor(e,t){super(e,`BUSINESS_RULE_ERROR`,{rule:t}),this.name=`BusinessRuleError`}},o=class extends e{constructor(e=`并发冲突，请重试`){super(e,`CONCURRENCY_ERROR`),this.name=`ConcurrencyError`}},s=class extends e{constructor(e,t){super(e,`CONFIGURATION_ERROR`,{key:t}),this.key=t,this.name=`ConfigurationError`}},c=class extends e{constructor(e,t,n){super(t,`EXTERNAL_SERVICE_ERROR`,{service:e}),this.service=e,this.name=`ExternalServiceError`,n&&(this.cause=n)}},l=class extends e{constructor(e,t){super(`${e} 已存在: ${t}`,`DUPLICATE_ENTITY`,{entityType:e,entityId:t}),this.entityType=e,this.entityId=t,this.name=`DuplicateEntityError`}},u=class extends e{constructor(e){super(e,`AUTHENTICATION_ERROR`),this.name=`AuthenticationError`}},d=class extends e{constructor(e){super(e,`NOT_FOUND`),this.name=`NotFoundError`}};function f(e,n,r){return new t(e,n,r)}function p(e,t){return new n(e,t)}function m(e,t){return new r(e,t)}function h(e,t){return new i(e,t)}function g(e,t){return new l(e,t)}function _(e){return new u(e)}function v(e){return new d(e)}exports.AuthenticationError=u,exports.BusinessRuleError=a,exports.ConcurrencyError=o,exports.ConfigurationError=s,exports.DomainError=e,exports.DuplicateEntityError=l,exports.EntityNotFoundError=n,exports.ExternalServiceError=c,exports.NotFoundError=d,exports.PermissionDeniedError=i,exports.RepositoryError=r,exports.ValidationError=t,exports.createAuthenticationError=_,exports.createDuplicateEntityError=g,exports.createEntityNotFoundError=p,exports.createNotFoundError=v,exports.createPermissionDeniedError=h,exports.createRepositoryError=m,exports.createValidationError=f;

package/dist/index.d.cts

@@ -0,0 +1,85 @@
+//#region src/domain.errors.d.ts
+declare abstract class DomainError extends Error {
+  readonly code: string;
+  readonly context?: Record<string, unknown> | undefined;
+  constructor(message: string, code?: string, context?: Record<string, unknown> | undefined);
+  toJSON(): object;
+}
+//#endregion
+//#region src/validation.errors.d.ts
+declare class ValidationError extends DomainError {
+  readonly field?: string | undefined;
+  readonly value?: unknown | undefined;
+  constructor(message: string, field?: string | undefined, value?: unknown | undefined);
+}
+//#endregion
+//#region src/entity-not-found.errors.d.ts
+declare class EntityNotFoundError extends DomainError {
+  readonly entityType: string;
+  readonly entityId: string;
+  constructor(entityType: string, entityId: string);
+}
+//#endregion
+//#region src/repository.errors.d.ts
+declare class RepositoryError extends DomainError {
+  readonly cause?: Error | undefined;
+  constructor(message: string, cause?: Error | undefined, context?: Record<string, unknown>);
+  toJSON(): object;
+}
+//#endregion
+//#region src/permission-denied.errors.d.ts
+declare class PermissionDeniedError extends DomainError {
+  readonly resource: string;
+  readonly action: string;
+  constructor(resource: string, action: string);
+}
+//#endregion
+//#region src/business-rule.errors.d.ts
+declare class BusinessRuleError extends DomainError {
+  constructor(message: string, rule?: string);
+}
+//#endregion
+//#region src/concurrency.errors.d.ts
+declare class ConcurrencyError extends DomainError {
+  constructor(message?: string);
+}
+//#endregion
+//#region src/configuration.errors.d.ts
+declare class ConfigurationError extends DomainError {
+  readonly key?: string | undefined;
+  constructor(message: string, key?: string | undefined);
+}
+//#endregion
+//#region src/external-service.errors.d.ts
+declare class ExternalServiceError extends DomainError {
+  readonly service: string;
+  constructor(service: string, message: string, cause?: Error);
+}
+//#endregion
+//#region src/duplicate-entity.errors.d.ts
+declare class DuplicateEntityError extends DomainError {
+  readonly entityType: string;
+  readonly entityId: string;
+  constructor(entityType: string, entityId: string);
+}
+//#endregion
+//#region src/authentication.errors.d.ts
+declare class AuthenticationError extends DomainError {
+  constructor(message: string);
+}
+//#endregion
+//#region src/not-found.errors.d.ts
+declare class NotFoundError extends DomainError {
+  constructor(message: string);
+}
+//#endregion
+//#region src/factories.d.ts
+declare function createValidationError(message: string, field?: string, value?: unknown): ValidationError;
+declare function createEntityNotFoundError(entityType: string, entityId: string): EntityNotFoundError;
+declare function createRepositoryError(message: string, cause?: Error): RepositoryError;
+declare function createPermissionDeniedError(resource: string, action: string): PermissionDeniedError;
+declare function createDuplicateEntityError(entityType: string, entityId: string): DuplicateEntityError;
+declare function createAuthenticationError(message: string): AuthenticationError;
+declare function createNotFoundError(message: string): NotFoundError;
+//#endregion
+export { AuthenticationError, BusinessRuleError, ConcurrencyError, ConfigurationError, DomainError, DuplicateEntityError, EntityNotFoundError, ExternalServiceError, NotFoundError, PermissionDeniedError, RepositoryError, ValidationError, createAuthenticationError, createDuplicateEntityError, createEntityNotFoundError, createNotFoundError, createPermissionDeniedError, createRepositoryError, createValidationError };

package/dist/index.d.mts

@@ -0,0 +1,85 @@
+//#region src/domain.errors.d.ts
+declare abstract class DomainError extends Error {
+  readonly code: string;
+  readonly context?: Record<string, unknown> | undefined;
+  constructor(message: string, code?: string, context?: Record<string, unknown> | undefined);
+  toJSON(): object;
+}
+//#endregion
+//#region src/validation.errors.d.ts
+declare class ValidationError extends DomainError {
+  readonly field?: string | undefined;
+  readonly value?: unknown | undefined;
+  constructor(message: string, field?: string | undefined, value?: unknown | undefined);
+}
+//#endregion
+//#region src/entity-not-found.errors.d.ts
+declare class EntityNotFoundError extends DomainError {
+  readonly entityType: string;
+  readonly entityId: string;
+  constructor(entityType: string, entityId: string);
+}
+//#endregion
+//#region src/repository.errors.d.ts
+declare class RepositoryError extends DomainError {
+  readonly cause?: Error | undefined;
+  constructor(message: string, cause?: Error | undefined, context?: Record<string, unknown>);
+  toJSON(): object;
+}
+//#endregion
+//#region src/permission-denied.errors.d.ts
+declare class PermissionDeniedError extends DomainError {
+  readonly resource: string;
+  readonly action: string;
+  constructor(resource: string, action: string);
+}
+//#endregion
+//#region src/business-rule.errors.d.ts
+declare class BusinessRuleError extends DomainError {
+  constructor(message: string, rule?: string);
+}
+//#endregion
+//#region src/concurrency.errors.d.ts
+declare class ConcurrencyError extends DomainError {
+  constructor(message?: string);
+}
+//#endregion
+//#region src/configuration.errors.d.ts
+declare class ConfigurationError extends DomainError {
+  readonly key?: string | undefined;
+  constructor(message: string, key?: string | undefined);
+}
+//#endregion
+//#region src/external-service.errors.d.ts
+declare class ExternalServiceError extends DomainError {
+  readonly service: string;
+  constructor(service: string, message: string, cause?: Error);
+}
+//#endregion
+//#region src/duplicate-entity.errors.d.ts
+declare class DuplicateEntityError extends DomainError {
+  readonly entityType: string;
+  readonly entityId: string;
+  constructor(entityType: string, entityId: string);
+}
+//#endregion
+//#region src/authentication.errors.d.ts
+declare class AuthenticationError extends DomainError {
+  constructor(message: string);
+}
+//#endregion
+//#region src/not-found.errors.d.ts
+declare class NotFoundError extends DomainError {
+  constructor(message: string);
+}
+//#endregion
+//#region src/factories.d.ts
+declare function createValidationError(message: string, field?: string, value?: unknown): ValidationError;
+declare function createEntityNotFoundError(entityType: string, entityId: string): EntityNotFoundError;
+declare function createRepositoryError(message: string, cause?: Error): RepositoryError;
+declare function createPermissionDeniedError(resource: string, action: string): PermissionDeniedError;
+declare function createDuplicateEntityError(entityType: string, entityId: string): DuplicateEntityError;
+declare function createAuthenticationError(message: string): AuthenticationError;
+declare function createNotFoundError(message: string): NotFoundError;
+//#endregion
+export { AuthenticationError, BusinessRuleError, ConcurrencyError, ConfigurationError, DomainError, DuplicateEntityError, EntityNotFoundError, ExternalServiceError, NotFoundError, PermissionDeniedError, RepositoryError, ValidationError, createAuthenticationError, createDuplicateEntityError, createEntityNotFoundError, createNotFoundError, createPermissionDeniedError, createRepositoryError, createValidationError };

package/dist/index.mjs

@@ -0,0 +1 @@
+var e=class extends Error{constructor(e,t=`DOMAIN_ERROR`,n){super(e),this.code=t,this.context=n,this.name=`DomainError`}toJSON(){return{name:this.name,code:this.code,message:this.message,context:this.context,stack:this.stack}}},t=class extends e{constructor(e,t,n){super(e,`VALIDATION_ERROR`,{field:t,value:n}),this.field=t,this.value=n,this.name=`ValidationError`}},n=class extends e{constructor(e,t){super(`${e} 未找到: ${t}`,`ENTITY_NOT_FOUND`,{entityType:e,entityId:t}),this.entityType=e,this.entityId=t,this.name=`EntityNotFoundError`}},r=class extends e{constructor(e,t,n){super(e,`REPOSITORY_ERROR`,n),this.cause=t,this.name=`RepositoryError`}toJSON(){return{...super.toJSON(),cause:this.cause?.message}}},i=class extends e{constructor(e,t){super(`无权限执行操作: ${t} on ${e}`,`PERMISSION_DENIED`,{resource:e,action:t}),this.resource=e,this.action=t,this.name=`PermissionDeniedError`}},a=class extends e{constructor(e,t){super(e,`BUSINESS_RULE_ERROR`,{rule:t}),this.name=`BusinessRuleError`}},o=class extends e{constructor(e=`并发冲突，请重试`){super(e,`CONCURRENCY_ERROR`),this.name=`ConcurrencyError`}},s=class extends e{constructor(e,t){super(e,`CONFIGURATION_ERROR`,{key:t}),this.key=t,this.name=`ConfigurationError`}},c=class extends e{constructor(e,t,n){super(t,`EXTERNAL_SERVICE_ERROR`,{service:e}),this.service=e,this.name=`ExternalServiceError`,n&&(this.cause=n)}},l=class extends e{constructor(e,t){super(`${e} 已存在: ${t}`,`DUPLICATE_ENTITY`,{entityType:e,entityId:t}),this.entityType=e,this.entityId=t,this.name=`DuplicateEntityError`}},u=class extends e{constructor(e){super(e,`AUTHENTICATION_ERROR`),this.name=`AuthenticationError`}},d=class extends e{constructor(e){super(e,`NOT_FOUND`),this.name=`NotFoundError`}};function f(e,n,r){return new t(e,n,r)}function p(e,t){return new n(e,t)}function m(e,t){return new r(e,t)}function h(e,t){return new i(e,t)}function g(e,t){return new l(e,t)}function _(e){return new u(e)}function v(e){return new d(e)}export{u as AuthenticationError,a as BusinessRuleError,o as ConcurrencyError,s as ConfigurationError,e as DomainError,l as DuplicateEntityError,n as EntityNotFoundError,c as ExternalServiceError,d as NotFoundError,i as PermissionDeniedError,r as RepositoryError,t as ValidationError,_ as createAuthenticationError,g as createDuplicateEntityError,p as createEntityNotFoundError,v as createNotFoundError,h as createPermissionDeniedError,m as createRepositoryError,f as createValidationError};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@longzai-intelligence/error-core",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.mts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "build:prod": "NODE_ENV=production tsdown",
+    "prepublishOnly": "bun run build:prod",
+    "dev": "tsdown --watch",
+    "clean": "rimraf dist tsconfig/.cache",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "bun run typecheck:app && bun run typecheck:node && bun run typecheck:test",
+    "typecheck:app": "tsc --noEmit -p tsconfig/app.json",
+    "typecheck:node": "tsc --noEmit -p tsconfig/node.json",
+    "typecheck:test": "tsc --noEmit -p tsconfig/test.json",
+    "upgrade-deps": "ncu -u"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.11",
+    "@types/node": "^25.5.2",
+    "eslint": "^10.2.0",
+    "rimraf": "^6.1.3",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.3",
+    "@longzai-intelligence/eslint-preset-library": "0.0.5",
+    "@longzai-intelligence/vitest-config": "0.0.4",
+    "@longzai-intelligence/typescript-config": "0.0.2",
+    "tsdown": "^0.21.7",
+    "@longzai-intelligence/tsdown-config": "0.0.1"
+  },
+  "keywords": [
+    "error",
+    "core",
+    "domain",
+    "typescript"
+  ],
+  "license": "UNLICENSED",
+  "module": "./dist/index.mjs"
+}