@empyria /常见
中的高级组件的共享后端服务 Empyria纳米服务 主要建立在Bun上的框架：环境变量模式，错误定义， Codogram （SMS/ totp风格的挑战代码）和Ata (JSON模式构建块和 验证)。
要求
- 包子
>=1.4.0或node . js>=26 - 简单的ESM，没有构建步骤，没有TypeScript
这两个要求都来自 @empyria /分类，
这个包依赖于哪个，哪个使用本机 Temporal 人人享有全球
日期/时间处理。
安装
bun add @empyria/common
使用
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。个人
模块下 lib/ 如果只需要一个，也可以直接导入：
import { defineSchema } from '@empyria/common/lib/Ata.js'
模块
| 模块 | 目的 |
|---|---|
| index.js | 包入口点；重新导出下面的每个模块以及分子元助手(moleculerMeta， moleculerEmpyriaMeta)和工作流ID助手(workflowName， workflowId， identifyWorkflow）。 |
| lib / Errors.js | EmpyriaError, ErrorCreator 工厂, BaseErrors - Empyria的预构建模板错误目录。 |
| lib / js | createEnv -从empyria范围内的默认值构建服务的环境变量JSON模式；通过 { closed: true } 拒绝未声明的变量并绑定 { coerceTypes, removeAdditional } 到模式。 |
| 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． 看到 模式建筑商 和 验证选项 下面。 |
| lib / Codogram.js | generateCodogram -一次性挑战码（PIN，字母数字，字母）用于SMS/ totp风格的验证流程。 |
| lib / Defaulter.js | defaultsFromSchema -为JSON模式构建一个完全填充的默认对象。 |
每个导出的函数都直接用JSDoc记录在其源文件中——悬停
VSCode或Zed中的函数显示其参数和返回类型，不需要任何额外的内容
工具，因为两个编辑器都从plain读取JSDoc .js 自动文件。
测试在 测试/，每个模块一个文件，与 lib/ 来源。
验证选项
createValidator / validate / parse / createChecker / checkSchema 向前
ata-validator的选项 到底层
Validator。选项分为三层， 最后赢了：
- 图书馆违约 - - - - - -
setAtaDefaults({ ... })，在启动时调用一次 deployment-wide政策;getAtaDefaults()把它读回来，setAtaDefaults()清除它。 - schema-bound - - - - - -
defineSchema(map, { validation: { ... } })将选项存储在 不可枚举键，因此模式具有自己的解析策略(schemaOptions(schema)读取)。该模式仍然作为普通JSON模式进行序列化和比较。 - 按 - - -
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结合。
脚本
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