# @empyria/common 中文文档

规范地址：https://npmcn.com/package/%40empyria/common/

版本：0\.3\.18
npm 元数据更新时间：2026-10-31T23:34:25.730Z
中文译文更新时间：2026-11-01T02:51:59.652Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40empyria/common
原文对照：https://npmcn.com/package/%40empyria/common/?lang=original
项目主页：https://github.com/empyria-nano/common#readme
源码仓库：https://github.com/empyria-nano/common

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

- 包体积（解压后）：81.7 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=26
- 运行依赖：4 个
- 首次发布：2026-08-16T15:34:24.438Z
- 最新版本发布：2026-10-31T23:34:25.573Z
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

共享后端为Empyria的好东西

## 安装

```sh
npm install @empyria/common
```

也可以使用：`pnpm add @empyria/common`、`yarn add @empyria/common`、`bun add @empyria/common`

## README

# @empyria /常见

中的高级组件的共享后端服务 **Empyria**纳米服务 主要建立在Bun上的框架：环境变量模式，错误定义， Codogram （SMS/ totp风格的挑战代码）和Ata (JSON模式构建块和 验证)。

## 要求

-   包子 `>=1.4.0` 或node . js `>=26`
-   简单的ESM，没有构建步骤，没有TypeScript

这两个要求都来自 [@empyria /分类](https://github.com/imrefazekas/empyria-classification)， 这个包依赖于哪个，哪个使用本机 `Temporal` 人人享有全球 日期/时间处理。

## 安装

```bash
bun add @empyria/common
```

## 使用

```js
import { createEnv, BaseErrors, generateCodogram, validate, string } from '@empyria/common'

const envSchema = createEnv({ API_KEY: string() })

throw new BaseErrors.EntityInvalid({ type: 'User', id: 42 })

const pin = generateCodogram('PIN')
```

所有的东西都是从包根目录通过 [index.js](https://npmcn.com/package/%40empyria/common/index.js)。个人 模块下 `lib/` 如果只需要一个，也可以直接导入：

```js
import { defineSchema } from '@empyria/common/lib/Ata.js'
```

## 模块

| 模块 | 目的 |
| --- | --- |
| [index.js](https://npmcn.com/package/%40empyria/common/index.js) | 包入口点；重新导出下面的每个模块以及分子元助手(`moleculerMeta`， `moleculerEmpyriaMeta`)和工作流ID助手(`workflowName`， `workflowId`， `identifyWorkflow`）。 |
| [lib / Errors.js](https://npmcn.com/package/%40empyria/common/lib/Errors.js) | `EmpyriaError`, `ErrorCreator` 工厂, `BaseErrors` - Empyria的预构建模板错误目录。 |
| [lib / js](https://npmcn.com/package/%40empyria/common/lib/Env.js) | `createEnv` -从empyria范围内的默认值构建服务的环境变量JSON模式；通过 `{ closed: true }` 拒绝未声明的变量并绑定 `{ coerceTypes, removeAdditional }` 到模式。 |
| [lib / Ata.js](https://npmcn.com/package/%40empyria/common/lib/Ata.js) | JSON模式构建块(`string`， `number`， `integer`， `bool`， `enumType`， `constant`， `nullable`， `array`， `discriminated`， `email`， `isoDateTime`，…)和验证抛出(`defineSchema`， `createValidator`， `validate`)、转换意图别名(`parse`， `createParser`)，或非投掷/结构化(`createChecker`， `checkSchema`，现在返回解析后的结果 `data`) -建立在 [ata-validator](https://www.npmjs.com/package/ata-validator)． 看到 _模式建筑商_ 和 _验证选项_ 下面。 |
| [lib / Codogram.js](https://npmcn.com/package/%40empyria/common/lib/Codogram.js) | `generateCodogram` -一次性挑战码（PIN，字母数字，字母）用于SMS/ totp风格的验证流程。 |
| [lib / Defaulter.js](https://npmcn.com/package/%40empyria/common/lib/Defaulter.js) | `defaultsFromSchema` -为JSON模式构建一个完全填充的默认对象。 |

每个导出的函数都直接用JSDoc记录在其源文件中——悬停 VSCode或Zed中的函数显示其参数和返回类型，不需要任何额外的内容 工具，因为两个编辑器都从plain读取JSDoc `.js` 自动文件。

测试在 [测试/](https://npmcn.com/package/%40empyria/common/test/)，每个模块一个文件，与 `lib/` 来源。

## 验证选项

`createValidator` / `validate` / `parse` / `createChecker` / `checkSchema` 向前 [`ata-validator`的选项](https://www.npmjs.com/package/ata-validator) 到底层 `Validator`。选项分为三层， **最后赢了**：

1.  **图书馆违约** - - - - - - `setAtaDefaults({ ... })`，在启动时调用一次 deployment-wide政策; `getAtaDefaults()` 把它读回来， `setAtaDefaults()` 清除它。
2.  **schema-bound** - - - - - - `defineSchema(map, { validation: { ... } })` 将选项存储在 不可枚举键，因此模式具有自己的解析策略(`schemaOptions(schema)` 读取)。该模式仍然作为普通JSON模式进行序列化和比较。
3.  **按** - - - `options` 上述任意函数的参数。

`formats` 合并一层深，用 `EMPYRIA_FORMATS` 总是在下面。

| 选项 | 它的作用（与Empyria相关） |
| --- | --- |
| `coerceTypes` | `"4040"` → `4040` 前验证。的原因 `env.js` 文件工作-每 `process.env` Value为字符串。 |
| `useDefaults` | 从他们的模式中填充缺失的道具 `default`. **默认开启**;每一个 `string()/number()/bool()/enumType()` 发出一个。 |
| `removeAdditional` | 模式未覆盖的条带键。仅与 `additionalProperties: false` (即。 `defineSchema({ strict: true })`）。 |
| `assertFormat` | 是否 `format` 不匹配是一种硬错误。默认为开启。 |
| `abortEarly` | 在第一个错误处停止，跳过浓缩。对于仅限判决的热路径(与 `createChecker`而不是投掷路径)。 |
| `richErrors` | 保持 `ATA####` 代码/ doc url /提示 `renderPretty` 消费。默认为开启；让它开着。 |
| `verbose` | 添加 `parentSchema` 每个错误（ajv's） `verbose`）。 |
| `formats` | 自定义 `format` 跳棋。 `EMPYRIA_FORMATS` （`empyria-email`， `empyria-password`， `empyria-ipv4`， `empyria-ipv6`)自动折叠。 |

**返回值/突变。** `createValidator` ＆ `validate` 返回 `ata-validator`的 `result.data` -与输入对象相同，除非 `coerceTypes` / `removeAdditional` / `useDefaults` 应用。这些传球也是 **就地改变输入对象**，所以给他们一个 当调用者必须保持其输入的原始状态(如 `env.js` 文件与 `{ ...process.env }`）。 `parse` / `createParser` 呼叫站点的行为别名有哪些 意图是转化而不仅仅是断言。 `createChecker` / `checkSchema` 现在也 返回 `data` (成功的解析值， `undefined` 失败)。

## 模式建筑商

每个返回一个普通的JSON模式片段；将它们组合在一起 `defineSchema(map, opts)`.

| 建设者 | 生产 |
| --- | --- |
| `bool(default?)` | `{ type: 'boolean' }` |
| `string(default?, minLength | { minLength, maxLength, pattern, format, description })` | `{ type: 'string', … }` |
| `number(default?, { min, max, exclusiveMin, exclusiveMax, multipleOf, description })` | `{ type: 'number', … }` |
| `integer(default?, …)` | `{ type: 'integer', … }` -用于端口/计数；拒绝 `3.5` |
| `enumType(list, default?, { type, description })` | `{ enum, type? }` |
| `constant(value, { description })` | `{ const: value }` |
| `nullable(schema)` | `type: [t, 'null']`，或者 `{ anyOf: [schema, { type: 'null' }] }` |
| `array(items?, { minItems, maxItems, uniqueItems, default, description })` | `{ type: 'array', … }` |
| `email() / password() / ip4() / ip6()` | `{ type: 'string', format: 'empyria-*' }` (见 `EMPYRIA_FORMATS`） |
| `isoDateTime() / isoDate() / isoTime() / duration() / uri() / uuid()` | `{ type: 'string', format: … }` （ata内置格式） |
| `logLevel() / nodeEnv() / tmpFile() / logFile()` | 域预设 |
| `discriminated(prop, { value: schema, … }, { description })` | JSON模式 **v1** `propertyDependencies` —物体的形状取决于 `prop`的价值 |

### 方言

`defineSchema(map, { dialect: 'v1' \| '2020-12' \| 'draft-07' \| <uri> })` 邮票 `$schema` （`ata-validator` 读它来挑选方言)。 `setDefaultDialect('v1')` / `getDefaultDialect()` 为每个调用设置一个进程范围的默认值 `dialect` 覆盖。V1与2020-12的区别只在于 `$dynamicRef` 作用域和解锁 `propertyDependencies`； `discriminated()` 适用于任何 方言（ata支持关键字作为扩展），但是 `dialect: 'v1'` 使它特别合法。

`defineSchema(map, { strict: 'unevaluated' })` 集合 `unevaluatedProperties: false` 而 离开 `additionalProperties` 开放-严格的可组合形式，用于模式的本意 `allOf`结合。

## 脚本

```bash
bun run format       # check formatting (oxfmt)
bun run format:fix   # apply formatting
bun run lint         # lint (oxlint)
bun run lint:fix     # lint and fix
bun run test         # run tests with coverage
```

## 许可证

MIT©Imre Fazekas

## 常见问题

### @empyria/common 是什么？

共享后端为Empyria的好东西

### 如何安装 @empyria/common？

在项目目录运行 npm install @empyria/common，或使用 pnpm add / yarn add / bun add。

### @empyria/common 支持 TypeScript 吗？

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

### @empyria/common 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @empyria/common 需要什么版本的 Node\.js？

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

### @empyria/common 可以商用吗？

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

### @empyria/common 还在维护吗？

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