# @diister/valibot-mock 中文文档

规范地址：https://npmcn.com/package/%40diister/valibot-mock/

版本：0\.1\.11
npm 元数据更新时间：2026-10-14T06:45:33.907Z
中文译文更新时间：2026-11-12T09:47:44.866Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：259 kB，38 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| ^22\.13\.0 \|\| ^23\.5\.0 \|\| \>=24\.0\.0
- 运行依赖：3 个
- peer 依赖：valibot ^1\.1\.0
- 首次发布：2026-09-08T23:14:28.821Z
- 最新版本发布：2026-10-14T06:45:33.527Z
- 近 30 天下载量：2631（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

从 Valibot 计划生成模拟数据

## 安装

```sh
npm install @diister/valibot-mock
```

也可以使用：`pnpm add @diister/valibot-mock`、`yarn add @diister/valibot-mock`、`bun add @diister/valibot-mock`

## README

# @ diist/ valibot- mock (英语)

> Valibot 计划模拟数据生成器

此软件包允许您从 [维利博特](https://valibot.dev/) 计划使用 [Faker.js (英语)](https://fakerjs.dev/) 创造现实价值.

## \* 特性

-   🎯 **自动生成**: 根据您的 Valibot 计划创建有效的数据
-   🌍 **多语种支助**: 使用Faker.js并配有当地语言支持
-   🔧 **可配置**: 自定义选项(种子、尝试、大小)
-   📦 **广泛的类型支持**: Valibot 类型(原始、对象、阵列、联盟等)的广泛支持
-   ⚡ **表演者**: 内置自动重试验证

## ++ 支持类型

### 初级类型

-   `string`, (中文(简体) ), `number`, (中文(简体) ), `boolean`, (中文(简体) ), `date`, (中文(简体) ), `bigint`
-   管道支持 : `minLength`, (中文(简体) ), `maxLength`, (中文(简体) ), `regex`, (中文(简体) ), `min`, (中文(简体) ), `max`, (中文(简体) ), `integer`, (中文(简体) ), `isoTimestamp`

### 收集类型

-   `array`, (中文(简体) ), `object`, (中文(简体) ), `record`, (中文(简体) ), `map`, (中文(简体) ), `set`, (中文(简体) ), `tuple`

### 选择类型

-   `union`, (中文(简体) ), `enum`, (中文(简体) ), `picklist`, (中文(简体) ), `literal`, (中文(简体) ), `variant`

### 修改类型

-   `optional`, (中文(简体) ), `nullable`, (中文(简体) ), `nullish`, (中文(简体) ), `nonNullable`, (中文(简体) ), `nonNullish`, (中文(简体) ), `nonOptional`
-   `brand` - 品牌/标记类型

### 特殊类型

-   `lazy`, (中文(简体) ), `intersect`, (中文(简体) ), `custom`, (中文(简体) ), `unknown`, (中文(简体) ), `any`
-   `null`, (中文(简体) ), `undefined`, (中文(简体) ), `void`, (中文(简体) ), `never`
-   `file`, (中文(简体) ), `blob`

## \* 安装

`valibot` 是一个 **同伴依赖**: 生成器读取并验证 所以它必须用你的valibot副本 而不是 捆了第二个.

```bash
# Bun / npm / pnpm / yarn
bun add @diister/valibot-mock valibot

# Deno
deno add jsr:@diister/valibot-mock npm:valibot
```

```ts
import { createMockGenerator } from "@diister/valibot-mock";
import * as v from "valibot";
```

发布到 npm 为 `@diister/valibot-mock` 并用同名JSR 两个带相同的代码。 Bun、Deno和Node.js的运行情况——节点地板是 `^20.19 || ^22.13 || ^23.5 || >=24`,从 `@faker-js/faker`。 。 。 .

## 使用量

### 基本实例

```ts
import * as v from "valibot";
import { createMockGenerator } from "@diister/valibot-mock";

const UserSchema = v.object({
  id: v.pipe(v.string(), v.regex(/^user:[A-Z0-9]{16}$/)),
  email: v.pipe(v.string(), v.email()),
  firstName: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(32))),
  lastName: v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(32))),
  age: v.pipe(v.number(), v.integer(), v.min(18), v.max(120)),
  status: v.enum(["active", "inactive", "pending"]),
  roles: v.array(v.string()),
  createdAt: v.pipe(v.string(), v.isoTimestamp())
});

const generator = createMockGenerator(UserSchema);

// Generate a single user
const mockUser = generator.generate();
console.log(mockUser);

// Generate multiple users
const mockUsers = generator.generateMany(5);
console.log(mockUsers);
```

### 高级使用

### 自定义数据生成方式 `fake()`

对于更现实的数据生成,你可以使用 `fake()` 用于提供自定义生成器的函数:

```typescript
import * as v from "valibot";
import { createMockGenerator, fake } from "@diister/valibot-mock";

const UserSchema = v.object({
  // Use fake() for custom realistic data generation
  firstName: v.pipe(
    v.string(),
    v.minLength(2),
    fake((faker, context) => {
      console.log(`Generating firstName at ${context.path}`);
      return faker.person.firstName();
    })
  ),
  lastName: v.pipe(
    v.string(),
    fake((faker) => faker.person.lastName())
  ),
  email: v.pipe(
    v.string(),
    v.email(),
    fake((faker) => faker.internet.email())
  ),
  // Fields without fake() use intelligent defaults
  age: v.pipe(
    v.number(),
    v.minValue(18),
    v.maxValue(80)
  ),
  bio: v.optional(v.pipe(
    v.string(),
    v.maxLength(500),
    fake((faker) => faker.person.bio())
  ))
});

const mockGenerator = createMockGenerator(UserSchema);
const userData = mockGenerator.generate();

// Output:
// {
//   firstName: "John",
//   lastName: "Doe", 
//   email: "john.doe@example.com",
//   age: 25.4,
//   bio: "Software engineer and coffee enthusiast"
// }
```

### 假生成器函数

这个 `fake()` 函数接受具有两个参数的生成器函数:

```typescript
fake((faker, context) => {
  // faker: Faker.js instance with full API
  // context: { path: string } - current field path for debugging
  return faker.datatype.uuid();
})
```

### 与本地支持合并

```ts
import { createMockGenerator, locales } from "@diister/valibot-mock";

const generator = createMockGenerator(UserSchema, {
  faker: { 
    locale: [locales.fr], 
    seed: 42 
  },
  maxAttempts: 15, // Number of attempts to generate a valid value
  defaultArrayMaxLength: 5, // Max size for arrays by default
  defaultStringMaxLength: 100 // Max size for strings by default
});
```

## • API

### `createMockGenerator<T>(schema, options?)`

为给定的计划创建模拟生成器.

#### 参数

-   `schema`: 要使用的 Valibot 计划
-   `options?`配置选项

#### 选项

```ts
interface MockGeneratorOptions {
  faker?: {
    locale?: LocaleDefinition | LocaleDefinition[];  // use the exported locales
    seed?: number;                   // Seed for reproducible results
    randomizer?: Randomizer;
  };
  maxAttempts?: number;             // Max attempts per value (default: 100)
  maxRegexAttempts?: number;        // Max draws for a regex-backed string (default: 50)
  defaultArrayMaxLength?: number;   // Max array size (default: 10)
  defaultStringMaxLength?: number;  // Max string size (default: 20)

  // Realistic values for recognised field names — see "Semantic field names".
  // `false` disables the tier; a record extends or overrides the built-in table.
  semantics?: Record<string, SemanticGenerator> | false;

  // Caller-side hook consulted at every node — see "The resolve hook".
  resolve?: (node: ResolveNode) => unknown;
}
```

#### 回返

A 类 `MockGenerator` 带有方法的对象 :

-   `generate()`: 生成单一值
-   `generateMany(count)`: 生成多个值

世代相会分三级,依此顺序: `resolve`,则 `fake()` 依附在计划上 `semantics`。 。 。 .

#### 失败

当无法产生有效值时, `generate()` 丢出一个 `MockGenerationError` (出口)携带节点 `path`页:1 `schemaType` 和,对于一个regex后背弦,它的 `pattern`。没什么 打印到控制台上.

从图案中取出一个正则后置的字符串,并附带其限定词 以便结果符合 `maxLength` (有记录的重复,例如: `/^\/(?:[^/]+\/)*$/` (包括中文) 每个图画都与图案对照 `maxRegexAttempts` 绘制全部错失( 环绕或另一个构造 ) 生成器不能遵守),或者当模式无法适应时 `maxLength` 毕竟, 生成失败,而不是重试整个值。 给这样的 字段 a `fake()` 或者从 `resolve`。 。 。 .

### 这个 `resolve` 钩子

`resolve` 要求每个节点在任何深度, 并排在两个 `fake()` 财务报告和审定财务报表 语义. 返回时 `SKIP` 降低节点,让正常的一代继续; 任何其它东西都被当成值, 验证像一个生成的值 未访问子树 .

```ts
import { createMockGenerator, SKIP } from "@diister/valibot-mock";

const gen = createMockGenerator(OrderSchema, {
  resolve: (node) => (node.path === "customer.id" ? "cus_fixed" : SKIP),
});
```

`node.path` 与根位分隔(`""` )并包含数组 指数,例如:. `"items.0.sku"`。 。 。 .

### 语义字段名称

普通字符串在识别时会从其字段名生成,所以 `firstname` 条目生成名称而不是随机字符。 键是 已恢复正常 `first_name`, (中文(简体) ), `First-Name` 财务报告和审定财务报表 `firstName` 全部匹配 `firstname`。 。 。 .

```ts
import {
  createMockGenerator,
  DEFAULT_SEMANTICS,
  normalizeSemanticKey,
} from "@diister/valibot-mock";

normalizeSemanticKey("First-Name"); // "firstname"
Object.keys(DEFAULT_SEMANTICS);     // the built-in table

// Extend or override it; pass `false` to switch the tier off entirely.
createMockGenerator(schema, {
  semantics: { sku: (faker) => faker.string.alphanumeric(8).toUpperCase() },
});
```

### `fake(generatorFn)`

为更现实的模拟数据创建自定义数据生成器.

#### 参数

-   `generatorFn`函数 `(faker, context) => any`
    -   `faker`页:1
    -   `context`对象为 `path` 当前字段位置的属性

#### 示例

```typescript
fake((faker, context) => {
  // Use any Faker.js method
  return faker.person.firstName();
})
```

### 导出的地方

```ts
import { locales } from "@diister/valibot-mock";

// Available locales
locales.en    // English
locales.fr    // French
locales.de    // German
locales.es    // Spanish
locales.it    // Italian
locales.ja    // Japanese
locales.ko    // Korean
locales.pt    // Portuguese
locales.ru    // Russian
locales.zh    // Chinese
// ... and many more
```

## 发展

这个软件包正在积极开发中。 API可能会在1.0版本之前进化.

## 许可证

麻省理工学院

## 常见问题

### @diister/valibot-mock 是什么？

从 Valibot 计划生成模拟数据

### 如何安装 @diister/valibot-mock？

在项目目录运行 npm install @diister/valibot-mock，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：valibot（^1\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @diister/valibot-mock 支持 TypeScript 吗？

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

### @diister/valibot-mock 支持 ESM 还是 CommonJS？

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

### @diister/valibot-mock 需要什么版本的 Node\.js？

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

### @diister/valibot-mock 可以商用吗？

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

### @diister/valibot-mock 的下载量有多少？

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

### @diister/valibot-mock 还在维护吗？

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