zod-to-markdown

将 Zod schema 转换为 Markdown 文档的工具函数，支持两种输出格式：树状列表和表格。

安装

npm install @chnak/zod-to-markdown

使用方法

ESM / TypeScript

import { zodSchemaToMarkdown, zodSchemaToTable } from '@chnak/zod-to-markdown';
import { z } from 'zod';

const schema = z.object({
  name: z.string(),
  age: z.number(),
});

// 树状格式
const markdown = zodSchemaToMarkdown(schema);
console.log(markdown);

// 表格格式
const table = zodSchemaToTable(schema);
console.log(table);

CommonJS / Node.js

const { zodSchemaToMarkdown, zodSchemaToTable } = require('@chnak/zod-to-markdown');
const { z } = require('zod');

const schema = z.object({
  name: z.string(),
  age: z.number(),
});

const markdown = zodSchemaToMarkdown(schema);
const table = zodSchemaToTable(schema);
console.log(markdown);
console.log(table);

输出结果

树状格式 (zodSchemaToMarkdown)：

- name
  - String
- age
  - Number

表格格式 (zodSchemaToTable)：

| 字段 | 类型 | 描述 |
|------|------|------|
| name | String | - |
| age | Number | - |

支持的 Zod 类型

基础类型

• ZodObject - 对象 schema，包含嵌套属性
• ZodArray - 数组 schema，包含元素类型
• ZodString - 字符串，可选 minLength/maxLength
• ZodNumber - 数字，可选 minValue/maxValue
• ZodBoolean - 布尔类型
• ZodEnum - 枚举值
• ZodBigInt - BigInt 类型
• ZodDate - Date 类型

工具类型

• ZodOptional - 可选属性
• ZodNullable - 可为空属性
• ZodDefault - 默认值
• ZodEffects - transform/coerce 效果

高级类型

• ZodUnion - 联合类型
• ZodDiscriminatedUnion - 带鉴别键的联合类型
• ZodIntersection - 交叉类型
• ZodRecord - Record（字典）类型
• ZodTuple - 元组类型

特殊类型

• ZodLiteral - 字面量值（如 "hello", 1, true）
• ZodNaN - NaN 类型
• ZodNever - Never 类型
• ZodUnknown - Unknown 类型
• ZodVoid - Void 类型

示例

复杂 Schema

import { z } from 'zod';

const userSchema = z.object({
  id: z.string().uuid(),
  name: z.string(),
  email: z.string().email(),
  age: z.number().optional(),
  role: z.enum(['admin', 'user', 'guest']),
  metadata: z.record(z.string(), z.unknown()).optional(),
});

console.log(zodSchemaToMarkdown(userSchema));

输出：

- id
  - String
- name
  - String
- email
  - String
- age
  - Optional
    - Number
- role
  - Enum: admin, user, guest
- metadata
  - Optional
    - Record
      Key:
        - String
      Value:
        - Unknown

鉴别联合类型 (Discriminated Union)

const messageSchema = z.discriminatedUnion('role', [
  z.object({ role: z.literal('user'), content: z.string() }),
  z.object({ role: z.literal('assistant'), content: z.string() }),
]);

console.log(zodSchemaToMarkdown(messageSchema));

输出：

- DiscriminatedUnion (key: role)
  - role
    - Literal: "user"
  - content
    - String
  |
  - role
    - Literal: "assistant"
  - content
    - String

Transform 效果

const transformedSchema = z.string().transform(val => val.length);

console.log(zodSchemaToMarkdown(transformedSchema));

输出：

- Effects (transform)
  - String

表格格式示例

import { z } from 'zod';

const userSchema = z.object({
  id: z.string().uuid().describe('用户ID'),
  name: z.string().describe('姓名'),
  profile: z.object({
    bio: z.string().describe('个人简介'),
    avatar: z.string().describe('头像URL'),
  }).describe('用户资料'),
  tags: z.array(z.string()).describe('标签'),
  skills: z.record(z.string(), z.number()).describe('技能评分'),
});

console.log(zodSchemaToTable(userSchema));

输出：

| 字段 | 类型 | 描述 |
|------|------|------|
| id | String | 用户ID |
| name | String | 姓名 |
| profile.bio | String | 个人简介 |
| profile.avatar | String | 头像URL |
| tags[] | Array<String> | 标签 |
| skills | Record<String, Number> | 技能评分 |

路径格式说明

表格格式使用点 . 和 [] 表示嵌套结构：

| 格式 | 含义 | 示例 | |------|------|------| | field | 普通字段 | name | | parent.child | 对象嵌套 | profile.bio | | field[] | 数组 | tags[] | | array[].field | 对象数组的字段 | users[].name | | a[].b[].c | 多层嵌套 | departments[].employees[].name |

API

zodSchemaToMarkdown(schema, indentLevel?)

| 参数 | 类型 | 说明 | |------|------|------| | schema | z.ZodTypeAny | 要转换的 Zod schema | | indentLevel | number | 初始缩进级别（默认: 0） |

返回树状格式的 Markdown 字符串。

zodSchemaToTable(schema)

| 参数 | 类型 | 说明 | |------|------|------| | schema | z.ZodTypeAny | 要转换的 Zod schema（仅支持 ZodObject） |

返回表格格式的 Markdown 字符串。非 ZodObject 类型会回退到树状格式。

License

MIT License