@kwayteow/typeseer v0.5.1

🧩 TypeScript Mock 数据生成器

一个强大的 TypeScript Mock 数据生成工具，基于 JSON Schema，可以从 TypeScript 接口自动生成符合类型约束的模拟数据。

✨ 功能特点

• 🔄 从 TypeScript 接口自动生成 JSON Schema
• 🎭 基于 JSON Schema 生成符合类型约束的 Mock 数据
• ✅ 支持 TypeScript 类型验证（通过 JSON Schema 规范）
• 📏 支持丰富的验证规则（最小/最大值、模式匹配、格式等）
• 🔌 支持自定义验证关键字（如 autoIncrement、fake 等）
• 📁 支持通过文件夹组织生成的文件（schemas/mocks）
• 🛠️ 提供完整的 CLI 和 API 使用方式

📦 安装

# 使用 npm
npm install -g @kwayteow/typeseer
npm install @kwayteow/typeseer --save-dev

# 使用 yarn
yarn global add @kwayteow/typeseer
yarn add @kwayteow/typeseer --dev

# 使用 pnpm
pnpm add -g @kwayteow/typeseer
pnpm add @kwayteow/typeseer -D

💻 命令行使用

📐 生成 Schema

typeseer schema -f src/types.ts -s User -o user-schema.json

参数:

• -f, --file: TypeScript 文件路径（必填）
• -s, --symbol: 要生成 Schema 的类型名称（必填）
• -o, --output: 输出文件路径（可选，不提供则输出到控制台）

🎲 生成 Mock 数据

typeseer mock -s user-schema.json -o user-mock.json -c 5

参数:

• -s, --schema: JSON Schema 文件路径（必填）
• -o, --output: 输出文件路径（可选，不提供则输出到控制台）
• -c, --count: 生成数据条数（默认为 1）

🚀 一键生成

typeseer generate -f src/types.ts -s User -o ./output -c 5
# 使用文件夹组织生成的文件
typeseer generate -f src/types.ts -s User -o ./output -c 5 -u

参数:

• -f, --file: TypeScript 文件路径（必填）
• -s, --symbol: 要生成的类型名称（必填）
• -o, --output: 输出目录（默认为 ./output）
• -c, --count: 生成数据条数（默认为 1）
• -u, --use-folder: 使用文件夹组织生成的文件（将在输出目录下创建 schemas 和 mocks 文件夹）

🔌 API 使用

📐 生成 Schema

import { generateSchema } from "@kwayteow/typeseer";

// 从 TypeScript 文件生成 Schema
const schema = generateSchema("src/types.ts", "User");

// 从 TypeScript 文件生成 Schema 并保存到文件
generateSchema("src/types.ts", "User", "user-schema.json");

🎲 生成 Mock 数据

import { generateMock, generateMultipleMocks } from "@kwayteow/typeseer";

// 从 Schema 对象生成 Mock 数据
const schema = {
  /* JSON Schema 对象 */
};
const mockData = await generateMock(schema);

// 从 Schema 文件生成 Mock 数据
const mockData = await generateMock("user-schema.json");

// 生成多条 Mock 数据
const mockDataList = await generateMultipleMocks(schema, 5);

// 生成多条 Mock 数据并保存到文件
await generateMultipleMocks(schema, 5, "user-mocks.json");

📝 类型约束和验证规则

TypeSeer 支持通过 JSDoc 注解为 TypeScript 类型添加各种约束条件，这些约束会被转换为 JSON Schema，并在生成 Mock 数据时应用。

数值约束

interface Product {
  /**
   * @minimum 0
   * @maximum 1000
   */
  price: number;

  /**
   * @multipleOf 0.5
   */
  weight: number;

  /**
   * @exclusiveMinimum 0
   * @exclusiveMaximum 100
   */
  stock: number;

  /**
   * @enum {number} [0, 1, 2]
   */
  status: number;

  /**
   * @autoIncrement true
   * @initialOffset 1000
   */
  id: number;
}

字符串约束

interface User {
  /**
   * @minLength 3
   * @maxLength 50
   */
  username: string;

  /**
   * @pattern ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
   */
  email: string;

  /**
   * @format date
   */
  birthdate: string;

  /**
   * @enum {string} ["admin", "user", "guest"]
   */
  role: string;

  /**
   * @fake {{name.firstName}}
   */
  firstName: string;

  /**
   * @format uuid
   */
  id: string;
}

数组约束

interface Post {
  /**
   * @minItems 1
   * @maxItems 10
   * @uniqueItems true
   */
  tags: string[];
}

对象约束

/**
 * @additionalProperties false
 */
interface Config {
  // 只允许定义的属性，不允许额外属性
  name: string;
  version: string;
}

自定义描述和默认值

interface Settings {
  /**
   * @description "用户首选主题"
   * @default "light"
   */
  theme: string;
}

自定义模拟数据

可以使用 @fake 标记生成特定模拟数据（基于 faker.js）：

interface User {
  /**
   * @fake {{name.firstName}}
   */
  firstName: string;

  /**
   * @fake {{internet.email}}
   */
  email: string;

  /**
   * @fake {{phone.phoneNumber}}
   */
  phone: string;
}

支持的格式

使用 @format 可以生成符合特定格式的数据：

interface Document {
  /**
   * @format uuid
   */
  id: string;

  /**
   * @format email
   */
  contactEmail: string;

  /**
   * @format date
   */
  createdAt: string;

  /**
   * @format date-time
   */
  updatedAt: string;

  /**
   * @format ipv4
   */
  serverIp: string;
}

自增 ID 支持

可以使用 @autoIncrement 和 @initialOffset 生成自增 ID：

interface Record {
  /**
   * @autoIncrement true
   * @initialOffset 1000
   */
  id: number;

  /**
   * @type integer
   * @autoIncrement true
   * @initialOffset 1
   */
  sequence: number;
}

🔧 高级配置

TypeSeer 提供了一些高级配置选项，可以通过 API 使用：

import { generateSchema, tjsDefaultSettings } from "@kwayteow/typeseer";

// 自定义 TypeScript JSON Schema 设置
const customSettings = {
  ...tjsDefaultSettings,
  required: false, // 不强制要求所有属性
  validationKeywords: [
    ...tjsDefaultSettings.validationKeywords,
    "customKeyword", // 添加自定义关键字
  ],
};

// 使用自定义设置生成 Schema
const schema = generateSchema(
  "src/types.ts",
  "User",
  undefined,
  customSettings
);

JSON Schema Faker 配置

TypeSeer 内部使用 JSON Schema Faker 生成 Mock 数据，默认配置如下：

JSONSchemaFaker.option({
  // 总是为可选字段生成数据，即使该字段是可选的
  alwaysFakeOptionals: true,
  // 如果 schema 中定义了默认值，优先使用默认值而不是生成随机值
  useDefaultValue: true,
  // 当遇到 schema 中的引用($ref)找不到时，忽略错误继续执行
  ignoreMissingRefs: true,
  // 生成数组类型数据时的最大长度
  maxItems: 5,
  // 生成数组类型数据时的最小长度
  minItems: 1,
});

更多约束规则请参考：

• JSON Schema 规范
• typescript-json-schema 文档
• JSON Schema Faker 文档

📂 推荐的项目结构

project/
├── src/
│   ├── types/        # TypeScript 类型定义
│   ├── schemas/      # 生成的 JSON Schema
│   └── mocks/        # 生成的 Mock 数据
├── ...

这种组织方式有助于保持项目结构清晰，特别是在处理多种类型和模型时。

🧪 测试

本项目使用 Vitest 进行单元测试。

pnpm test
# 或
npm run test

🛠️ 依赖

• typescript-json-schema
• json-schema-faker
• commander

🤝 贡献

欢迎贡献代码、报告问题或提出改进建议！请遵循以下步骤：

1. Fork 仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'feat: 添加某个功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

📜 许可证

MIT