@collective-intelligence/schema-codegen

中文文档
0.3.2发布于 2026/11/15TypeScriptES Module零依赖近 30 天下载 1962

从2020-12 Draft JSON Schema文档到TypeScript, Zod和Effect Schema源的纯生成器.

中文使用文档
文档目录6 节
  1. 生成模块
  2. 文件头
  3. 权力和要求
  4. 关键词
  5. 目标限制
  6. 检查

@collective-intelligence/schema-codegen

从2020-12 Draft JSON Schema文档到TypeScript源的纯生成器. 它没有运行时间依赖。 它没有IO文件,也没有CLI. 呼叫通过 文档并写入返回的文本。 这个 ci package codegen 命令 @collective-intelligence/cli 是一揽子声明的呼叫者;参见 CLI 读取。 。 。 .

目标:

  • types: 普通类型脚本类型.
  • zod: Zod schemas和推断出的类型.
  • effect数字 : effect/Schema 计划与类型.

生成模块

软件包导出 generateSchemaModule 及其类型。 功能是纯的 永远不要扔。 它返回一个目标文件的源文本 .

import { generateSchemaModule } from "@collective-intelligence/schema-codegen"

const result = generateSchemaModule({
  target: "zod",
  header: { packageFqn: "acme.billing", packageVersion: "1.0.0" },
  schemas: [
    {
      name: "acme.billing.invoice#input",
      document: { type: "object", properties: { id: { type: "string" } } },
      fidelity: "exact"
    }
  ]
})

if (result.errors === undefined) {
  // Write result.source to <out>/acme.billing/zod.ts. result.warnings is data.
}
  • SchemaInput.name 实值 <component fqn>#<slot label>创建生成器 从中导出名称: PascalCase 组件 fqn 没有软件包 fqn,然后是PascalCase插槽标签。 出口按构成部分分类 fqn, (中文(简体) ), 然后是插槽标签。 没有名字 #<slot label>名称 目标文件和两个具有一个导出名的策略是 错误 (reserved_name, (中文(简体) ), invalid_name, (中文(简体) ), name_clash) (中文(简体) ). 这个 zod 文件使用 z, (中文(简体) ), RegExp 财务报告和审定财务报表 Infinity; 数据 effect 文件使用 Schema, (中文(简体) ), RegExp 财务报告和审定财务报表 Infinity编辑 types 文件保留名称。 这是用来保存姓名的 $defs 条目.
  • SchemaInput.fidelity 实值 exact 或者说 structuralA级 structural 计划可以 运行时比JSON Schema更严格 每个 structural 计划给出一个 structural_fidelity 警告 警告他们.
  • GenerateResult 实值 { source, warnings } 或者说 { errors }。一次运行收集 每一个错误,每个有代码, 计划名称, 一个JSON指针和 关键词( e)null 当没有任何一个关键词有错的时候.
  • Warning.kind 实值 structural_fidelity, (中文(简体) ), dropped_keyword, (中文(简体) ), format_annotation_only 或者说 closed_object_unenforced。 。 。 .
  • 输出为字节稳定. 同样的输入给出了相同的文字: 无时间戳, 工具版本或散列。 图书馆不叫论坛.

文件头

每个文件都以 // 注释头. 标题为目标命名 软件包 fqn 和软件包版本, 并说计划不是 运行时间验证权限. 后面是一行空白线 这个 effect 标题 再来一行关于多余的键.

// @generated
// Target: zod
// Package: acme.billing
// Version: 1.0.0
// Generated schemas are a convenience and not runtime validation authority.
// The backend host validates.

这个 @generated 在主注释中标记是 CLI 如何识别文件 以便它覆盖.

权力和要求

所生之相为方便. 后端主机验证; 生成 文件从不替换。 计划描述了钢丝形状:编码为JSON, 未解码运行时间值 .

  • zod 产出需求 zod 4.4 或后来. 用这个 z.xor 页:1 oneOf。 。 。 .
  • effect 产出需求 effect/Schema。 。 。 .
  • types 输出没有导入 .

关键词

支持的关键字 :

  • 类型和值: type, (中文(简体) ), enum, (中文(简体) ), const。 。 。 .
  • 字符串 : minLength, (中文(简体) ), maxLength, (中文(简体) ), pattern, (中文(简体) ), format。 。 。 .
  • 数量 : minimum, (中文(简体) ), maximum, (中文(简体) ), exclusiveMinimum, (中文(简体) ), exclusiveMaximum, (中文(简体) ), multipleOf。 。 。 .
  • 对象 : properties, (中文(简体) ), required, (中文(简体) ), additionalProperties, (中文(简体) ), minProperties, (中文(简体) ), maxProperties。 。 。 .
  • 矩阵 : items, (中文(简体) ), prefixItems, (中文(简体) ), minItems, (中文(简体) ), maxItems, (中文(简体) ), uniqueItems。 。 。 .
  • 组成: anyOf, (中文(简体) ), oneOf, (中文(简体) ), allOf。 。 。 .
  • 参考文献:当地 $ref 改为 $defs 输入同一文档和根 $defsA级 $defs 条目成为不导出的地方声明.
  • 说明: title, (中文(简体) ), description, (中文(简体) ), default, (中文(简体) ), examples, (中文(简体) ), deprecated, (中文(简体) ), readOnly, (中文(简体) ), writeOnly。 。 。 .
  • 已忽略 : $schema, (中文(简体) ), $id, (中文(简体) ), $anchor, (中文(简体) ), $comment, (中文(简体) ), $vocabulary 和每个 开始的关键字 x-。 。 。 .

制约关键字需要 type。 。 。 . minLength, (中文(简体) ), pattern, (中文(简体) ), format,数字 范围, properties, (中文(简体) ), required, (中文(简体) ), additionalProperties, (中文(简体) ), minProperties, (中文(简体) ), maxProperties, (中文(简体) ), items, (中文(简体) ), prefixItems, (中文(简体) ), minItems, (中文(简体) ), maxItems 财务报告和审定财务报表 uniqueItems 仅约束它们自己类型的值,所以没有 type 也接受所有其他价值,没有目标可以这么说. 这个 生成器不猜测类型: 每个关键字运行失败 unsupported_keyword_combination,以及 keyword 这是限制。 这个 内 allOf, (中文(简体) ), anyOf 财务报告和审定财务报表 oneOf 成员 $defs 条目.

一个名字在 required 那个 properties 不申报为财产 additionalProperties 描述:任何值,或 additionalProperties 计划 与 additionalProperties: false 没有物体可以满足它,所以它 失败 unsupported_keyword_combination (单位:千美元)required+additionalProperties(中文(简体) ) 地点 required 输入.

prefixItems 描述存在和不存在的立场. 仅需以下职位 minItems; 后期位置为可选 tuple 元素 ([A, B?]) (中文(简体) ). 位于或超出的职位 maxItems 不存在, 财务报告和审定财务报表 items 最后一个被丢弃之后.

这些关键字无法运行, 因为生成器无法表达它们 : contains, (中文(简体) ), dependentRequired, (中文(简体) ), if, (中文(简体) ), then, (中文(简体) ), else, (中文(简体) ), not, (中文(简体) ), patternProperties, (中文(简体) ), unevaluatedItems, (中文(简体) ), unevaluatedProperties, (中文(简体) ), $dynamicRef, (中文(简体) ), $defs 根下方,一个远程 $ref,递归 $ref,以及 (单位:千美元) $ref 这并不意味着 $defs 输入。 任何其它关键字 不从 x- 是一个 unknown_keyword 错误。 发电机从来没有 降解一个形状,改变计划接受的内容.

仅删除一个在目标中没有等效的验证关键字。 留下来 用作记念和警告dropped_keyword 或者说 format_annotation_only) (中文(简体) ).

目标限制

  • types: 类型不能检查值。 验证关键字( E)minLength, (中文(简体) ), maxLength, (中文(简体) ), pattern, (中文(简体) ), format,数字界限、财产和物品 计数, uniqueItems成为JSDoc标签并给予 dropped_keyword 警告! 警告你们.
  • zod: 对象 additionalProperties: false 为: z.strictObject。一个 无属性和无属性的对象 additionalProperties 这是公开的纪录, 和其他目标一样. format 被选中 date-time, (中文(简体) ), email, (中文(简体) ), uuid 财务报告和审定财务报表 uri; 任何其他 格式保持为 .meta 数据和给予 format_annotation_only。 。 。 . uniqueItems, (中文(简体) ), minProperties 财务报告和审定财务报表 maxProperties 保持不变 .meta 数据及数据 给 dropped_keyword。 。 。 .
  • effect数字 : Schema.Struct 没有关闭对象. additionalProperties: false 未执行并给出 closed_object_unenforced 每个对象发出警告; 仅以解码选项拒绝多余的密钥 onExcessProperty: "error"。仅限 format: uuid 是格式检查;任何其他 格式保留为注释并给出 format_annotation_only对象 已经宣布了密钥,没有额外的计划 无法计算它的密钥,所以 minProperties 财务报告和审定财务报表 maxProperties 留作说明并给予 dropped_keyword。 。 。 . allOf 只合并纯对象; 其他成员 (单位:千美元)allof_not_plain_objects,也用于 $ref 成员名单 以不同方式申报一项财产(allof_property_conflict),失败 运行。 一个未合并的计划对象的关键词, 例如 a $ref 限制或限制 type 与 oneOf失败 unsupported_keyword_combination; 其编号 keyword 列出与 +。 。 。 .

检查

bun test tests/package-contract.test.ts
bun run type-check
bun run build
bun run test:pack

版本与发布记录

@collective-intelligence/schema-codegen 共发布 20 个版本,首次发布于 2026/10/28;过去 12 个月发布了 20 个版本。

版本发布日期距今
0.3.2latest2026/11/15今天
0.3.12026/11/15今天
0.3.02026/11/141 天前
0.2.322026/11/141 天前
0.1.312026/11/142 天前
0.1.302026/11/142 天前

关于 @collective-intelligence/schema-codegen 的常见问题

@collective-intelligence/schema-codegen 是什么?

从2020-12 Draft JSON Schema文档到TypeScript, Zod和Effect Schema源的纯生成器.

如何安装 @collective-intelligence/schema-codegen?

在项目目录运行 npm install @collective-intelligence/schema-codegen,或使用 pnpm add / yarn add / bun add。

@collective-intelligence/schema-codegen 支持 TypeScript 吗?

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

@collective-intelligence/schema-codegen 支持 ESM 还是 CommonJS?

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

@collective-intelligence/schema-codegen 可以商用吗?

@collective-intelligence/schema-codegen 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@collective-intelligence/schema-codegen 的下载量有多少?

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

@collective-intelligence/schema-codegen 还在维护吗?

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