# @gentleduck/error 中文文档

规范地址：https://npmcn.com/package/%40gentleduck/error/

版本：1\.1\.1
npm 元数据更新时间：2026-10-04T06:29:39.156Z
中文译文更新时间：2026-11-16T04:12:40.501Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gentleduck/error
原文对照：https://npmcn.com/package/%40gentleduck/error/?lang=original
项目主页：https://gentleduck.org/duck-error
源码仓库：https://github.com/gentleeduck/duck-error

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：138 kB，30 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- peer 依赖：typescript \>=5\.0\.0
- 首次发布：2026-09-25T11:34:09.086Z
- 最新版本发布：2026-10-04T06:29:38.804Z
- 近 30 天下载量：2992（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

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

## 安装

```sh
npm install @gentleduck/error
```

也可以使用：`pnpm add @gentleduck/error`、`yarn add @gentleduck/error`、`bun add @gentleduck/error`

## README

![@gentleduck/error](https://npmcn.com/package/%40gentleduck/error/public/logo-dark.svg)

# @ gentleduck/ 错误

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

[麻省理工学院](https://npmcn.com/package/%40gentleduck/error/LICENSE) - 说吧 [更改日志](https://npmcn.com/package/%40gentleduck/error/CHANGELOG.md) - 说吧 [文档](https://gentleduck.org/duck-error)

[![npm](https://img.shields.io/npm/v/@gentleduck/error.svg)](https://www.npmjs.com/package/@gentleduck/error) [![downloads](https://img.shields.io/npm/dm/@gentleduck/error.svg)](https://www.npmjs.com/package/@gentleduck/error) [![MIT](https://img.shields.io/npm/l/@gentleduck/error.svg)](https://npmcn.com/package/%40gentleduck/error/LICENSE)

* * *

## 安装

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

## 快开始

```typescript
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: 'a@b.com' })

// 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` 连锁店)进入了这个工具箱的自有代码之一. 从专用子路径导入,所以它是唯一的 如果这就是你使用的全部, 或者直接从包根—— 两种决心 同一个代码 :

```typescript
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上,所以它 由应用框架组成 它最有可能坐在一起.

```typescript
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>()` 换句话说.

### 规则

```typescript
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` 条目,而不仅仅是再出口的名称——只导入子路径 从来没有拉到任何东西 捆绑者不会已经树摇 从包根.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40gentleduck/error/LICENSE)

## 常见问题

### @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 和提交记录判断。

