# @dotcom-tool-kit/validated 中文文档

规范地址：https://npmcn.com/package/%40dotcom-tool-kit/validated/

版本：2\.0\.0
npm 元数据更新时间：2025-10-31T09:24:16.086Z
中文译文更新时间：2026-11-13T01:45:37.227Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40dotcom-tool-kit/validated
原文对照：https://npmcn.com/package/%40dotcom-tool-kit/validated/?lang=original

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

- 包体积（解压后）：15.1 kB，10 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.x
- 运行依赖：1 个
- 首次发布：2024-04-30T14:55:14.511Z
- 最新版本发布：2025-10-31T09:24:15.884Z
- 近 30 天下载量：2605（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 0 个）

## 中文简介

错误为一等值的类型和函数

## 安装

```sh
npm install @dotcom-tool-kit/validated
```

也可以使用：`pnpm add @dotcom-tool-kit/validated`、`yarn add @dotcom-tool-kit/validated`、`bun add @dotcom-tool-kit/validated`

## README

# `@dotcom-tool-kit/validated`

错误为一等值的类型和函数

## 理由

在 Tool Kit 中,我们处理装入许多不同类型入口的插件(用于 `Task`s, (中文(简体) ), `Hook`(S等)并行进行。 这一过程可能会出错的各种点有:导入一个入门点,检查版本相容性,等等.

如果我们天真地使用例外抛出或承诺拒绝,工具箱会停止处理所发生的第一个问题;用户会固定它只会碰到下一个错误,这将令人沮丧. 我们想尽我们所能 收集所有错误 _一次_越迟越好.

我们 _能够_ 继续为此使用例外/拒绝,以及 `Promise.allSettled`然而,如果采用这种模式,将难以跟踪错误的数据流,很容易不小心忘记整理出一些错误,从而陷入一次扔出一个错误的同一问题.

相反,我们用明确的返回值模拟这些错误, `Validated<T>`。这种类型的联盟包括: `Valid<T>` 代表正确价值,以及 `Invalid` 这代表着一个清单的问题: `string` 说明理由。 通过使这个类型变得明确,我们清楚地标记了所有能够返回我们可能想要整理的错误的函数,并且使得不决定如何处理错误就无法使用这些值.

这个模式仿照了Go的 [使用多个返回值处理错误](https://go.dev/doc/tutorial/handle-errors)鲁斯的 [`Result<T, E>` 类型](https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html) 哈斯凯尔的 [`Either a b` 类型](https://hackage.haskell.org/package/base-4.19.0.0/docs/Data-Either.html)。 。 。 .

## 使用量

### 创建一个 `Validated`

`@dotcom-tool-kit/validated` 导出两个构造函数, `valid` 财务报告和审定财务报表 `invalid`。当值的状态已知时,使用这些来创建折叠器,例如:

```typescript
valid({ some: 'object' })

invalid([
    'list of problems'
])
```

### 使用 `Validated` 数值

`Validated` 对象有类似矩阵或承诺方法的方法,允许您用数值或出错的理由行事,而无需检查类型:

```typescript
validated.map(value => {
    /* do something with value */
    // `return` something else. replaces the value with this return value if valid, does nothing if invalid
})

validated.mapError(reasons => {
    /* do something with reasons */
    // `return` something else. replaces the reasons with this return value if invalid, does nothing if valid
})
```

### 从 a 提取值 `Validated`

`Validated` 有一个 `.unwrap` 方法,如果其值是有效的,则允许提取其值,如果无效,则可以抛出错误。 这个应该尽可能地被后期使用,当没有数值就无法再进一步时,如果无效则需要停止.

```typescript
validated.unwrap('something was invalid!')
```

### 组合数组 `Validated`

类似 `Promise.all`,如果您有多个 `Validated`s,您需要分组他们的价值观和理由(即您有 `Array<Validated<T>>` 而你却想要 `Validated<Array<T>>`),我们有 `reduceValidated`数字 :

```typescript
reduceValidated([
    validated1,
    validated2,
    validated3
])
```

这在工具箱中被使用, 例如, 我们同时装入多个插件 .

## 常见问题

### @dotcom-tool-kit/validated 是什么？

错误为一等值的类型和函数

### 如何安装 @dotcom-tool-kit/validated？

在项目目录运行 npm install @dotcom-tool-kit/validated，或使用 pnpm add / yarn add / bun add。

### @dotcom-tool-kit/validated 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dotcom-tool-kit\_\_validated 是否存在。

### @dotcom-tool-kit/validated 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @dotcom-tool-kit/validated 需要什么版本的 Node\.js？

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

### @dotcom-tool-kit/validated 可以商用吗？

@dotcom-tool-kit/validated 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dotcom-tool-kit/validated 的下载量有多少？

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

### @dotcom-tool-kit/validated 还在维护吗？

最新版本 2\.0\.0 发布于 2025/10/31（1 年前）；至今共发布 6 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/04/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。