# @amritk/generate-examples 中文文档

规范地址：https://npmcn.com/package/%40amritk/generate-examples/

版本：0\.8\.12
npm 元数据更新时间：2026-10-22T18:55:58.777Z
中文译文更新时间：2026-11-06T01:29:17.783Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40amritk/generate-examples
原文对照：https://npmcn.com/package/%40amritk/generate-examples/?lang=original
项目主页：https://github.com/amritk/mjst/tree/main/packages/generate-examples#readme
源码仓库：https://github.com/amritk/mjst

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

- 包体积（解压后）：106 kB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- peer 依赖：fast-check \>=3
- 首次发布：2026-05-29T18:57:09.534Z
- 最新版本发布：2026-10-22T18:55:58.390Z
- 近 30 天下载量：59176（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：40（近 12 个月 40 个）

## 中文简介

从 JSON Schemas 中生成快速检查仲裁和示例值.

## 安装

```sh
npm install @amritk/generate-examples
```

也可以使用：`pnpm add @amritk/generate-examples`、`yarn add @amritk/generate-examples`、`bun add @amritk/generate-examples`

## README

# @amritk/基因-实例

**用于从 JSON Schemas 生成快速检查仲裁和实例值的程序API .**

![status](https://img.shields.io/badge/status-pre--alpha-ef4444?style=flat-square)  ![version](https://img.shields.io/npm/v/@amritk/generate-examples?style=flat-square&logo=npm&logoColor=white&label=version&color=6366f1)  ![license](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)  ![JSON Schema](https://img.shields.io/badge/JSON%20Schema-2020--12-f97316?style=flat-square)  ![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white)  ![vibe coded](https://img.shields.io/badge/vibe-coded-a855f7?style=flat-square)

* * *

## 概览

`@amritk/generate-examples` 将 JSON Schema 变成 **测试数据**在 其他mjst发电机给你代码 _消耗量_ 运行时的数据(参数, 校验器、 类型 , 此选项通过将数据发送给 _练习_ 那个密码.

每个生成的文件导出 :

-   类型脚本 `type` 计划的定义
-   A 类 [`fast-check`](https://github.com/dubzzz/fast-check) 任意( a)`FooArbitrary`(中文(简体) ) 用于基于属性的测试的理想
-   具体、自成一体的例子价值(`fooExample`——理想的固定装置, 种子和文档

一个 `index.ts` 枪管再出口一切.

> \[注\] 生成的仲裁导入 `fast-check`,所以消费者需要安装 (单位:千美元)`npm i -D fast-check`) (中文(简体) ). 任意的,其策略使用关键字 否 `fc.*` 组合器自行抓取( e)`if`编号 :`then`编号 :`else`, (中文(简体) ), `not`专用 `oneOf`, (中文(简体) ), `contains`,以及显示对象的关键字—— `patternProperties`, (中文(简体) ), `propertyNames`, (中文(简体) ), `dependent*`, (中文(简体) ), `min`编号 :`maxProperties`进口 `@amritk/runtime-validators` 用于生成后验证过滤器;不需要此过滤器的文件不需要. 静态 `fooExample` 值没有运行时间依赖性.
> 
> `@amritk/runtime-validators` 是一个 `dependency` 这里不是同伴,因为 这台发电机是自己进口的 这解决了发电机,但 _没有_ 必然用于生成的文件——文件所在区域 **** 源树,所以 在 pnpm 的严格布局下或 Yarn PnP 它从您的项目解决,而不是从 这个包裹。 如果您的计划使用了其中的任何关键词, 请直接安装 (单位:千美元)`npm i @amritk/runtime-validators`) (中文(简体) ). 无法声明为对等点: Bun 拒绝同时列出的工作空间包,以及 `--frozen-lockfile` 失败 整个回放.

* * *

## 安装

```bash
npm install @amritk/generate-examples
# or
pnpm add @amritk/generate-examples
# or
yarn add @amritk/generate-examples
# or
bun add @amritk/generate-examples
```

* * *

## 使用量

```typescript
import { buildExampleSchema } from '@amritk/generate-examples'

const schema = {
  type: 'object',
  properties: {
    id: { type: 'string', format: 'uuid' },
    age: { type: 'integer', minimum: 0 },
  },
  required: ['id'],
} as const

const files = await buildExampleSchema(schema, 'User')
// → [{ filename: 'user.ts', content: '...' }, { filename: 'index.ts', content: '...' }]
```

生成的 `user.ts` 看起来像:

```typescript
import * as fc from 'fast-check'

export type User = { id: string; age?: number }

export const UserArbitrary: fc.Arbitrary<User> = fc.record(
  { "id": fc.uuid(), "age": fc.integer({ min: 0 }) },
  { requiredKeys: ["id"] },
)

export const userExample: User = { "id": "00000000-0000-0000-0000-000000000000", "age": 0 }
```

在属性测试中使用任意性 :

```typescript
import { test, fc } from '@fast-check/vitest'
import { UserArbitrary } from './generated'
import { parseUser } from './parsers'

test.prop([UserArbitrary])('parseUser round-trips any valid User', (user) => {
  expect(parseUser(user)).toEqual(user)
})
```

...或者抓住静态的例子作为固定:

```typescript
import { userExample } from './generated'

const res = await fetch('/users', { method: 'POST', body: JSON.stringify(userExample) })
```

* * *

## 低级 API

| 导出 | 说明 |
| :-- | :-- |
| `buildExampleSchema(schema, rootName, suffix?)` | 走着走着 `$ref` 图表并返回 a `GeneratedFile[]` (每个计划一个文件+一个 `index.ts`) (中文(简体) ). |
| `generateArbitrary(schema, typeName, suffix?, lazyRefFilenames?, rootSchema?)` | 返回 `export const …Arbitrary` 单一计划节点的来源. |
| `generateExampleConst(schema, typeName, rootSchema?)` | 返回 `export const …Example` 单一计划节点的来源. |
| `deriveExample(schema, rootSchema?)` | 返回一个混凝土, 计数系统验证的 JavaScript 值( 无代码生成) . |
| `serializeValue(value)` | 将衍生值序列化为 TypeScript 源表达式( 手) `Date`编号 :`bigint`) (中文(简体) ). |

* * *

## 支持的关键字

`type` 包括多种类型的工会,例如: `['string', 'null']` —— 说 (字符串/数字/整数/布尔/核/阵列/对象), `properties`, (中文(简体) ), `required`, (中文(简体) ), `additionalProperties`, (中文(简体) ), `items`, (中文(简体) ), `prefixItems`, (中文(简体) ), `minItems`编号 :`maxItems`, (中文(简体) ), `uniqueItems`, (中文(简体) ), `minLength`编号 :`maxLength`, (中文(简体) ), `pattern`, (中文(简体) ), `format`, (中文(简体) ), `minimum`编号 :`maximum`, (中文(简体) ), `exclusiveMinimum`编号 :`exclusiveMaximum`, (中文(简体) ), `multipleOf`, (中文(简体) ), `enum` (被兄弟们过滤) 限制), `const`, (中文(简体) ), `minProperties`编号 :`maxProperties`, (中文(简体) ), `patternProperties`, (中文(简体) ), `propertyNames`, (中文(简体) ), `dependentRequired`, (中文(简体) ), `dependentSchemas`, (中文(简体) ), `contains`, (中文(简体) ), `minContains`, (中文(简体) ), `allOf` (合并为一个计划), `oneOf`编号 :`anyOf`, (中文(简体) ), `if`编号 :`then`编号 :`else`, (中文(简体) ), `not`, (中文(简体) ), `$ref`,则 `x-mjst` 扩展 (单位:千美元)`Date`, (中文(简体) ), `bigint`) (中文(简体) ). `if`编号 :`then`编号 :`else`, (中文(简体) ), `not`,以及 `oneOf` 排他性是 通过验证生成的候选人以对抗计划及 重试/拒绝。 不支持的构造可降解为 `fc.anything()` 内 仲裁和仲裁 `null` 在静态示例中.

静态实例包括: `format` `@amritk/runtime-validators` 知道该如何 检查 : `email`, (中文(简体) ), `idn-email`, (中文(简体) ), `date`, (中文(简体) ), `date-time`, (中文(简体) ), `time`, (中文(简体) ), `duration`, (中文(简体) ), `uuid`, (中文(简体) ), `uri`, (中文(简体) ), `iri`, (中文(简体) ), `uri-reference`, (中文(简体) ), `iri-reference`, (中文(简体) ), `uri-template`, (中文(简体) ), `json-pointer`, (中文(简体) ), `relative-json-pointer`, (中文(简体) ), `hostname`, (中文(简体) ), `idn-hostname`, (中文(简体) ), `ipv4`, (中文(简体) ), `ipv6`, (中文(简体) ), `regex`, (中文(简体) ), 加上 OpenAPI 代码 `url`。未识别 `format` 倒计时 `"string"`。 。 。 .

* * *

## 已知限制

每个 `fooExample` 在书写之前,将依据自己的计划加以验证。 何时 值不能满足它仍然发射的图谋——所以模块总是 编译——但生成器打印 a `console.warn` 命名类型。 到达 `FooArbitrary` 在这种情况下:任意性带有运行时间验证过滤器 ,并在静态值不能时保持正确.

其价值不足有三个原因:

-   **计划没有实例.** `{ pattern: '^ab$', minLength: 5 }`, (中文(简体) ), `uniqueItems` 以布尔表示 `minItems: 3`页:1 `required` 键 `additionalProperties: false` 禁止,或 `oneOf` 他们的分行 每一个价值 两次匹配。 没有任何正确的信息发出;警告指向 计划 不是发电机.
-   **所行所行所行所行所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出所出.** `pattern` 由一个样本 最好的递归 - 贵族行走 regex, 所以看看周围和 回溯引用回溯到 `"string"`; 未识别 `format` 做同样的.
-   **约束比任何固定的要大.** 衍生的字符串、 数组或 对象停止以 10,000 个字符 / 元素 / 密钥生长, 因此文档 请求 `minLength: 50000000` 生成一个上限值和一个警告,而不是 a 50 MB 字节. `FooArbitrary` 仍然尊重真正的约束.

几个值得了解的形状,每个形状都保留生成的文件 编译而非更正:

-   一个计划需要一把钥匙 它的 **生成类型从未声明** —— 说 `required` 命名缺少的东西 `properties`页:1 `dependentRequired` 编号 : `dependentSchemas` 扶养,或a `minProperties` 填充对象为无 索引签名。 此示例保留了密钥( 缺少其方案 ) 要求是断开的数据),并作为 `… as Foo`,因为一个赤裸的物体 含有多余属性的字元无法编译 .
-   作者 `examples[0]` (或,当没有 `examples`,则 `default`)为 使用过的 **只有它满足了自己的计划**。提示不会 (单位:千美元)`{ type: 'string', default: 42 }` 常见于其字段类型 页:1 衍生值, 因为生成的类型遵循了图谋并拒绝 直接的暗示. `const` 永远是荣誉:类型是康斯特自己的 字面类型,所以两者不能有分歧.
-   一个 **不满足范围** (单位:千美元)`minLength: 10, maxLength: 2`) 倒塌在其上 上面的束缚在任意。 每个界限 `fc.*` 组合者称 `min <= max` 抛出 _导入_,从而将所有其它出口 与它并列的文件。 整数范围也仅限于快速检查本身 32-位范围,和长度/计算范围到非负整数.
-   A 类 **递归定义的** 样板必须停下来,然后停下来 `null`,不可更改的类型不承认,因此排放为 `… as unknown as Node`。 。 。 . `NodeArbitrary` 将重现通过 `fc.letrec` 并且不需要这样的逃脱.
-   A 类 `pattern` 这是 **无效的 JavaScript regex**,或者使用前视线 或往后看,倒入平地 `fc.string()`。 。 。 . `fc.stringMatching` 编译 模块范围的图案,不能从一个断言中产生,因此荣誉 它会把文件扔到无法使用的地方 而不是那个 随意松开.
-   **巢穴深于400级** 以错误命名限制. 建造一个任意的,每个图级需要几个堆栈框架,所以更深 文档耗尽了堆栈——盖子将它变成一个信息,说些什么 错了.

两种形状无法生成, 任意性会重试 永远,如果你的样本。 两者都是没有实例的诡计 和例子 警告说:

-   A 类 `pattern` 所需长度的字符串无法匹配 (单位:千美元)`{ pattern: '^[a-z]{2}$', minLength: 5 }`) (中文(简体) ). 可爱但狭小的配对 (单位:千美元)`{ pattern: '^[a-f0-9]+$', minLength: 32, maxLength: 32 }`)对于 同样的原因 -- `fc.stringMatching` 很少按准确的长度降落.
-   A 类 `minLength`编号 :`minItems` 如此之大,所以无法建立如此大小的值.

还有一个缺口不是这个包的关闭:a `$ref` 无处解决 文档按其名称键入(`Nope`)但从未进口,因为它是 从未作为文件生成 。 任意贬低为: `fc.anything()`不过 键入时仍为它命名,因此文件不编译。 同样的 `{ "type": [] }`, (中文(简体) ), 类型为 `export type Foo = ;`两者来自 `@amritk/helpers/generate-type-definition`。 。 。 .

> \[TIP\] 实例 `$ref` 以数值表示内含,所以定义图宽度 扇出出出出相相相应大字. 成本在产出中 大小,而不是生成时间——每个定义每文档产生一次.

* * *

## 许可证

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

## 常见问题

### @amritk/generate-examples 是什么？

从 JSON Schemas 中生成快速检查仲裁和示例值\.

### 如何安装 @amritk/generate-examples？

在项目目录运行 npm install @amritk/generate-examples，或使用 pnpm add / yarn add / bun add。

### @amritk/generate-examples 支持 TypeScript 吗？

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

### @amritk/generate-examples 支持 ESM 还是 CommonJS？

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

### @amritk/generate-examples 需要什么版本的 Node\.js？

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

### @amritk/generate-examples 可以商用吗？

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

### @amritk/generate-examples 的下载量有多少？

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

### @amritk/generate-examples 还在维护吗？

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