@gentleduck/error

中文文档
1.1.1发布于 2026/10/04MITTypeScriptESM + CJS零依赖近 30 天下载 2992

已打入,由注册人驱动的出错类别:品牌代码,JSON的秘密安全,以及一个构造或扔出包. 框架不可知,零依赖.

中文使用文档
文档目录9 节
  1. 安装
  2. 快开始
  3. 你得到的东西
  4. @Throws : 对拒绝驱动程序进行分类
  5. 为什么 Throws 代码是 Bare ,登记处没有代码
  6. 规则
  7. 其他司机
  8. 设计说明
  9. 许可证

@gentleduck/error

@ gentleduck/ 错误

已打入、登记驱动的错误类别:品牌编码、保密 toJSON,则a (原始内容存档于2019-09-21) (英语). Instruction-or-throw kid. 框架不可知、零运行时间依赖、无害环境管理+CJS.

麻省理工学院 - 说吧 更改日志 - 说吧 文档

npm downloads MIT


安装

npm install @gentleduck/error
# or
bun add @gentleduck/error

快开始

import { createErrorKit, detail, fault } from '@gentleduck/error'

// A registry: each code maps to a status. `detail<M>(status)` says the code also
// carries a `meta` of shape M; `fault(status)` marks a code a store/adapter can
// raise itself (vs. one only flow/validation logic raises). A plain `number` is
// a bare code with no required meta.
const USER_ERRORS = {
  USER_NOT_FOUND: detail<{ id: string }>(404),
  USER_EMAIL_TAKEN: detail<{ email: string }>(409),
  VALIDATION_FAILED: 400,
  STORE_UNAVAILABLE: fault(503),
}

const { fail, throwError, asError, hasErrorCode, metaOf } = createErrorKit('UserError', USER_ERRORS)

// Construct without throwing.
const err = fail('USER_NOT_FOUND', { id: 'u_123' })

// Throw directly. A code's declared shape is enforced at the call site: USER_NOT_FOUND's
// `id` can't be omitted, while a bare code like VALIDATION_FAILED takes no meta argument at all.
throwError('USER_EMAIL_TAKEN', { email: '[email protected]' })

// Wrap an unknown catch value. Already-typed instances pass through unchanged;
// anything else is wrapped under the given code with the original on `.cause`.
try {
  await store.get(id)
} catch (e) {
  throw asError(e, 'STORE_UNAVAILABLE')
}

// Narrow by code rather than `instanceof` — this also matches an instance built
// by a duplicated copy of the package (hoisting, or a dependency installed
// separately from its consumer).
if (hasErrorCode(err, 'USER_NOT_FOUND')) {
  metaOf(err, 'USER_NOT_FOUND').id // typed as string
}

你得到的东西

  • createErrorKit(name, registry) 新建错误类及其帮助者 。 每个电话 宣布自己的班级,从不共享, 所以两个工具箱的例子 从来没有满足对方的 instanceof 就像两个手写课不会那样.
  • fail 编号 : throwError 构造或扔出已键入实例; asError 编号 : rethrowError 关闭 a 一个 unknown catch 值,通过不变的已类型实例.
  • hasErrorCode 缩入 a code 属性代替 instanceof,所以它仍然承认 实例来自软件包复制的副本.
  • .toJSON() 返回时 { ok: false, error: { code, status, ...meta } } 每个密钥匹配 /secret|password|passphrase|plaintext|token|hash|salt|signature|credential|private|otp|recovery|apikey|api_key/i 在任何深度投放——安全直通电线. isSecretKey 财务报告和审定财务报表 scrubMeta 为: 单独导出,如果在其他地方需要同样的编辑.
  • .status 财务报告和审定财务报表 .statusCode (一个别名,以 Nest 的基础例外过滤器为名) 直接从登记簿上出来.
  • 赤色代码完全没有元形 —— 说 fail('SOME_BARE_CODE', { anything }) 是编译 错误而不是一个从未达到的默默接受值 .meta。其元档仅次于 接受 undefined,所以存在 总是选择 cause 在它拥有固定位置后 居住地点: fail('SOME_BARE_CODE', undefined, causeError)。 。 。 .
  • A 类 detail(status) 忘记了它 <M> 失败的方式相同 -没有 object没什么,所以.. 没有类型参数而宣布的注册条目也不能给出元,而不是 默地接受任何形状.
  • fail 编号 : throwError 选择 cause 元之后a —— 说 fail('USER_NOT_FOUND', { id }, driverError) ——仅在给定时才设置在实例上,所以省略的原因从未出现为: 'cause' in err。 。 。 .

@Throws: 对拒绝驱动程序进行分类

一个选择入选方法的装饰器, 将一个被拒绝的 Aync 方法的驱动程序出错( 或包裹) cause 连锁店)进入了这个工具箱的自有代码之一. 从专用子路径导入,所以它是唯一的 如果这就是你使用的全部, 或者直接从包根—— 两种决心 同一个代码 :

import { createThrows, POSTGRES_REFUSALS } from '@gentleduck/error/throws'
// or: import { createThrows, POSTGRES_REFUSALS } from '@gentleduck/error'

要求数 experimentalDecorators: true 在你身边 tsconfig.json —— 说 @Throws 使用遗产 装饰签名 (target, key, descriptor),同一个NestJS和TypeorM上,所以它 由应用框架组成 它最有可能坐在一起.

import { createErrorKit, detail } from '@gentleduck/error'
import { createThrows, POSTGRES_REFUSALS } from '@gentleduck/error/throws'

const USERS_ERRORS = {
  USERS_QUERY_FAILED: 500,
  USERS_EMAIL_TAKEN: 409,
  USERS_NOT_FOUND: 404,
  USERS_ORG_NOT_FOUND: detail<{ orgId: string }>(404), // has required meta - see below
} as const satisfies Record<string, number>

const kit = createErrorKit('UsersError', USERS_ERRORS)

// Module-wide rules: every method below inherits this unless it declares its own for the same kind.
const { Throws } = createThrows(kit, POSTGRES_REFUSALS, { duplicate: 'USERS_EMAIL_TAKEN' })

class Users {
  @Throws('USERS_QUERY_FAILED', { missing: 'USERS_NOT_FOUND' })
  async create(email: string) {
    // Whatever this throws:
    //  - already one of this kit's errors, or any other kit's - passes through unchanged
    //  - a driver error whose SQLSTATE classifies as 'duplicate' or 'missing' - becomes
    //    USERS_EMAIL_TAKEN / USERS_NOT_FOUND, original error on `.cause`
    //  - anything else - becomes USERS_QUERY_FAILED, original error on `.cause`
  }
}

为什么 Throws代码是 Bare,登记处没有代码

装潢师只有一次 cause 提供它提出的代码—— 从来没有给过一个呼叫者, 因为当一个司机拒绝查询时,没有呼叫者. USERS_ORG_NOT_FOUND 上文 需求 { orgId: string }流出的一切无法产生,所以传递给 Throws 或一个 Rules 条目是一个编译错误,而不是在运行时用空元构建的代码 . 给一个 Throws- 可达到的代码为普通状态或只可选状态 detail<M>() 换句话说.

规则

type Rules<C> = {
  conflict?: C | Record<string, C>
  duplicate?: C | Record<string, C>
  invalid?: C | Record<string, C>
  missing?: C | Record<string, C>
  timeout?: C | Record<string, C>
  rename?: Record<string, C>
}
  • 5个拒绝者中每个都按一个代码或按驱动器限制键的表格排序 名称为 '*' 作为包罗万象的.. { duplicate: { users_email_key: 'USERS_EMAIL_TAKEN', '*': 'USERS_QUERY_FAILED' } }。 。 。 .
  • rename 匹配已丢出的错误 .message 给一个共同的帮助者 抛出平地 Error 带有可识别消息而不是驱动程序错误.
  • 采用的方法规则 Throws(code, rules) 覆盖模块规则从 createThrows 百分比 拒绝类型; 既不是声明, 也不属于装饰者本身 code。 。 。 .
  • 分类行走 .cause 链条,因为 ORM 通常将驱动程序错误包在一个 只包含查询、其参数和原件 cause。 。 。 .

其他司机

POSTGRES_REFUSALS 将 Postgres SQLSTATEs 映射到五种拒绝类型. createThrows第二届 参数只是 Record<string, Refusal> - 通过自己的桌子(MySQL/SQLite错误,联署材料) driver's own code strings),以同样的方式对不同的源进行分类.

设计说明

  • 零运行时间依赖, sideEffects: false,与 platform: 'neutral' - 这里没有 假设节点、浏览器或任何其他主机.
  • 无害环境管理和普通JS两种船舶exports 地图为 import编号 :require 条件,每个条件 拥有 .d.ts编号 :.d.cts),对照节点10,节点16和捆绑模块分辨率进行校验.
  • 品牌类型Carries, (中文(简体) ), Fault)是平淡而有弦键的地产品牌,而不是 unique symbol ——从消费包本身的申报产出中安全引用.
  • ./throws 这是它自己的 tsdown 条目,而不仅仅是再出口的名称——只导入子路径 从来没有拉到任何东西 捆绑者不会已经树摇 从包根.

许可证

麻省理工学院

版本与发布记录

@gentleduck/error 共发布 3 个版本,首次发布于 2026/09/25;过去 12 个月发布了 3 个版本。

版本发布日期距今
1.1.1latest2026/10/041 个月前
1.1.02026/09/271 个月前
1.0.02026/09/251 个月前

关于 @gentleduck/error 的常见问题

@gentleduck/error 是什么?

已打入,由注册人驱动的出错类别:品牌代码,JSON的秘密安全,以及一个构造或扔出包. 框架不可知,零依赖.

如何安装 @gentleduck/error?

在项目目录运行 npm install @gentleduck/error,或使用 pnpm add / yarn add / bun add。

@gentleduck/error 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gentleduck/error 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gentleduck/error 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gentleduck/error 可以商用吗?

@gentleduck/error 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gentleduck/error 的下载量有多少?

根据 npm 官方下载统计,@gentleduck/error 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,992 次,日均约 100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gentleduck/error 还在维护吗?

最新版本 1.1.1 发布于 2026/10/04(1 个月前);至今共发布 3 个版本,其中过去 12 个月发布了 3 个;首次发布于 2026/09/25。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。