@chnak/zod-to-markdown 1.0.1 → 1.0.3

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cd D:/Date/20260321/zod-to-markdown && npm test)"
+    ]
+  }
+}

package/README.md

@@ -1,6 +1,6 @@
 # zod-to-markdown
 
-将 Zod schema 转换为 Markdown 文档的工具函数。
+将 Zod schema 转换为 Markdown 文档的工具函数，支持两种输出格式：树状列表和表格。
 
 ## 安装
 
@@ -13,7 +13,7 @@ npm install @chnak/zod-to-markdown
 ### ESM / TypeScript
 
 ```typescript
-import { zodSchemaToMarkdown } from '@chnak/zod-to-markdown';
+import { zodSchemaToMarkdown, zodSchemaToTable } from '@chnak/zod-to-markdown';
 import { z } from 'zod';
 
 const schema = z.object({
@@ -21,14 +21,19 @@ const schema = z.object({
   age: z.number(),
 });
 
+// 树状格式
 const markdown = zodSchemaToMarkdown(schema);
 console.log(markdown);
+
+// 表格格式
+const table = zodSchemaToTable(schema);
+console.log(table);
 ```
 
 ### CommonJS / Node.js
 
 ```javascript
-const { zodSchemaToMarkdown } = require('@chnak/zod-to-markdown');
+const { zodSchemaToMarkdown, zodSchemaToTable } = require('@chnak/zod-to-markdown');
 const { z } = require('zod');
 
 const schema = z.object({
@@ -37,11 +42,15 @@ const schema = z.object({
 });
 
 const markdown = zodSchemaToMarkdown(schema);
+const table = zodSchemaToTable(schema);
 console.log(markdown);
+console.log(table);
 ```
 
 ### 输出结果
 
+**树状格式 (`zodSchemaToMarkdown`)**：
+
 ```markdown
 - name
   - String
@@ -49,6 +58,15 @@ console.log(markdown);
   - Number
 ```
 
+**表格格式 (`zodSchemaToTable`)**：
+
+```markdown
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| name | String | - |
+| age | Number | - |
+```
+
 ## 支持的 Zod 类型
 
 ### 基础类型
@@ -161,6 +179,49 @@ console.log(zodSchemaToMarkdown(transformedSchema));
   - String
 ```
 
+### 表格格式示例
+
+```typescript
+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));
+```
+
+输出：
+```markdown
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| 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?)`
@@ -170,7 +231,15 @@ console.log(zodSchemaToMarkdown(transformedSchema));
 | `schema` | `z.ZodTypeAny` | 要转换的 Zod schema |
 | `indentLevel` | `number` | 初始缩进级别（默认: `0`） |
 
-返回转换后的 Markdown 字符串。
+返回树状格式的 Markdown 字符串。
+
+### `zodSchemaToTable(schema)`
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `schema` | `z.ZodTypeAny` | 要转换的 Zod schema（仅支持 ZodObject） |
+
+返回表格格式的 Markdown 字符串。非 ZodObject 类型会回退到树状格式。
 
 ## License
 

package/examples/company-schema-table.md

@@ -0,0 +1,18 @@
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| id | String | 公司ID |
+| name | String | 公司名称 |
+| departments[].name | String | 部门名称 |
+| departments[].employees[].id | String | 员工ID |
+| departments[].employees[].name | String | 姓名 |
+| departments[].employees[].title | String | 职位 |
+| departments[].employees[].skills[] | Array<String> | 技能 |
+| departments[].employees[].contact.email | String | 邮箱 |
+| departments[].employees[].contact.phone | Optional<String> | 电话 |
+| departments[].location.street | String | 街道 |
+| departments[].location.city | String | 城市 |
+| departments[].location.country | String | 国家 |
+| departments[].location.coordinates.lat | Number | 纬度 |
+| departments[].location.coordinates.lng | Number | 经度 |
+| foundedYear | Number | 成立年份 |
+| tags[] | Array<String> | 标签 |

package/examples/complex-schema-table.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { zodSchemaToTable } from '../src/index';
+import * as fs from 'fs';
+
+// 多层嵌套 Schema 示例
+
+// 第一层：坐标
+const coordinatesSchema = z.object({
+  lat: z.number().describe('纬度'),
+  lng: z.number().describe('经度'),
+}).describe('地理坐标');
+
+// 第二层：地址
+const addressSchema = z.object({
+  street: z.string().describe('街道'),
+  city: z.string().describe('城市'),
+  country: z.string().describe('国家'),
+  coordinates: coordinatesSchema.describe('坐标'),
+}).describe('地址');
+
+// 爱好
+const hobbySchema = z.object({
+  name: z.string().describe('爱好名称'),
+  level: z.enum(['beginner', 'intermediate', 'advanced']).describe('等级'),
+  equipment: z.array(z.object({
+    name: z.string().describe('装备名称'),
+    brand: z.string().optional().describe('品牌'),
+  })).optional().describe('相关装备'),
+}).describe('爱好');
+
+// 主要 Schema
+const companySchema = z.object({
+  id: z.string().uuid().describe('公司ID'),
+  name: z.string().describe('公司名称'),
+  departments: z.array(z.object({
+    name: z.string().describe('部门名称'),
+    employees: z.array(z.object({
+      id: z.string().describe('员工ID'),
+      name: z.string().describe('姓名'),
+      title: z.string().describe('职位'),
+      skills: z.array(z.string()).describe('技能'),
+      contact: z.object({
+        email: z.string().describe('邮箱'),
+        phone: z.string().optional().describe('电话'),
+      }).describe('联系方式'),
+    })).describe('员工列表'),
+    location: addressSchema.describe('部门地址'),
+  })).describe('部门列表'),
+  foundedYear: z.number().describe('成立年份'),
+  tags: z.array(z.string()).describe('标签'),
+}).describe('公司');
+
+const markdown = zodSchemaToTable(companySchema);
+
+console.log('## Company Schema 文档 (多层级嵌套)\n');
+console.log(markdown);
+
+// 保存到文件
+fs.writeFileSync('examples/company-schema-table.md', markdown);
+console.log('\n已保存到 examples/company-schema-table.md');

package/examples/nested-object-example.md

@@ -0,0 +1,11 @@
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| id | String | 用户ID |
+| name | String | 姓名 |
+| profile.bio | String | 个人简介 |
+| profile.avatar | String | 头像URL |
+| profile.age | Number | 年龄 |
+| settings.theme | Enum(light | dark) | 主题 |
+| settings.language | String | 语言 |
+| settings.notifications.email | Boolean | 邮件通知 |
+| settings.notifications.push | Boolean | 推送通知 |

package/examples/nested-object-example.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { zodSchemaToTable } from '../src/index';
+import * as fs from 'fs';
+
+// 纯对象嵌套示例
+const coordinatesSchema = z.object({
+  lat: z.number().describe('纬度'),
+  lng: z.number().describe('经度'),
+});
+
+const addressSchema = z.object({
+  street: z.string().describe('街道'),
+  city: z.string().describe('城市'),
+  country: z.string().describe('国家'),
+  coordinates: coordinatesSchema.describe('坐标'),
+});
+
+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'),
+    age: z.number().describe('年龄'),
+  }).describe('用户资料'),
+  settings: z.object({
+    theme: z.enum(['light', 'dark']).describe('主题'),
+    language: z.string().describe('语言'),
+    notifications: z.object({
+      email: z.boolean().describe('邮件通知'),
+      push: z.boolean().describe('推送通知'),
+    }).describe('通知设置'),
+  }).describe('设置'),
+});
+
+const markdown = zodSchemaToTable(userSchema);
+
+console.log('## User Schema (Object 嵌套)\n');
+console.log(markdown);
+
+fs.writeFileSync('examples/nested-object-example.md', markdown);
+console.log('已保存到 examples/nested-object-example.md');

package/lib/index.d.ts

@@ -1,2 +1,8 @@
 import { z } from "zod";
+/**
+ * 将 Zod schema 转换为表格形式的 Markdown
+ * @param schema - 要转换的 Zod schema
+ * @returns 表格形式的 Markdown 字符串
+ */
+export declare function zodSchemaToTable(schema: z.ZodTypeAny): string;
 export declare function zodSchemaToMarkdown(schema: z.ZodTypeAny, indentLevel?: number): string;

package/lib/index.js

@@ -1,7 +1,213 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.zodSchemaToMarkdown = void 0;
+exports.zodSchemaToMarkdown = exports.zodSchemaToTable = void 0;
 const zod_1 = require("zod");
+/**
+ * 将 Zod schema 转换为表格形式的 Markdown
+ * @param schema - 要转换的 Zod schema
+ * @returns 表格形式的 Markdown 字符串
+ */
+function zodSchemaToTable(schema) {
+    if (!(schema instanceof zod_1.z.ZodObject)) {
+        return zodSchemaToMarkdown(schema);
+    }
+    // 收集所有嵌套字段
+    const fields = [];
+    collectFields(schema, '', fields);
+    // 表头
+    const rows = [];
+    rows.push('| 字段 | 类型 | 描述 |');
+    rows.push('|------|------|------|');
+    fields.forEach(({ path, type, description }) => {
+        rows.push(`| ${path} | ${type} | ${description} |`);
+    });
+    return rows.join('\n') + '\n';
+}
+exports.zodSchemaToTable = zodSchemaToTable;
+/**
+ * 递归收集所有嵌套字段
+ */
+function collectFields(schema, prefix, fields) {
+    // 处理 Optional - 包装类型
+    if (schema instanceof zod_1.z.ZodOptional) {
+        const innerType = getTypeString(schema.unwrap());
+        // 对于简单类型直接包装
+        if (schema.unwrap() instanceof zod_1.z.ZodObject || schema.unwrap() instanceof zod_1.z.ZodArray) {
+            collectFields(schema.unwrap(), prefix, fields);
+        }
+        else {
+            fields.push({
+                path: prefix,
+                type: `Optional<${innerType}>`,
+                description: schema.description || '-',
+            });
+        }
+        return;
+    }
+    // 处理 Nullable - 包装类型
+    if (schema instanceof zod_1.z.ZodNullable) {
+        const innerType = getTypeString(schema.unwrap());
+        if (schema.unwrap() instanceof zod_1.z.ZodObject || schema.unwrap() instanceof zod_1.z.ZodArray) {
+            collectFields(schema.unwrap(), prefix, fields);
+        }
+        else {
+            fields.push({
+                path: prefix,
+                type: `Nullable<${innerType}>`,
+                description: schema.description || '-',
+            });
+        }
+        return;
+    }
+    // 处理 Default
+    if (schema instanceof zod_1.z.ZodDefault) {
+        collectFields(schema.removeDefault(), prefix, fields);
+        return;
+    }
+    // 处理 Array - 收集元素类型
+    if (schema instanceof zod_1.z.ZodArray) {
+        const element = schema.element;
+        // 如果是对象数组，展开其字段
+        if (element instanceof zod_1.z.ZodObject) {
+            const innerFields = [];
+            collectFields(element, '', innerFields);
+            innerFields.forEach(field => {
+                const fieldPath = field.path || 'value';
+                fields.push({
+                    path: `${prefix}[].${fieldPath}`,
+                    type: field.type,
+                    description: field.description,
+                });
+            });
+        }
+        else {
+            // 非对象数组，保持原样
+            fields.push({
+                path: `${prefix}[]`,
+                type: getTypeString(schema),
+                description: schema.description || '-',
+            });
+        }
+        return;
+    }
+    // 处理 ZodObject - 递归展开
+    if (schema instanceof zod_1.z.ZodObject) {
+        const shape = schema.shape;
+        Object.keys(shape).forEach(key => {
+            const subSchema = shape[key];
+            const newPath = prefix ? `${prefix}.${key}` : key;
+            collectFields(subSchema, newPath, fields);
+        });
+        return;
+    }
+    // 处理 Record
+    if (schema instanceof zod_1.z.ZodRecord) {
+        fields.push({
+            path: prefix,
+            type: `Record<${getTypeString(schema.keySchema)}, ${getTypeString(schema.valueSchema)}>`,
+            description: schema.description || '-',
+        });
+        return;
+    }
+    // 处理 Tuple
+    if (schema instanceof zod_1.z.ZodTuple) {
+        const items = schema.items.map((item) => getTypeString(item)).join(', ');
+        fields.push({
+            path: prefix,
+            type: `Tuple(${items})`,
+            description: schema.description || '-',
+        });
+        return;
+    }
+    // 其他类型直接添加
+    fields.push({
+        path: prefix,
+        type: getTypeString(schema),
+        description: schema.description || '-',
+    });
+}
+/**
+ * 获取类型的字符串描述
+ */
+function getTypeString(schema) {
+    if (schema instanceof zod_1.z.ZodOptional) {
+        return `Optional<${getTypeString(schema.unwrap())}>`;
+    }
+    if (schema instanceof zod_1.z.ZodNullable) {
+        return `Nullable<${getTypeString(schema.unwrap())}>`;
+    }
+    if (schema instanceof zod_1.z.ZodDefault) {
+        return `Default<${getTypeString(schema.removeDefault())}>`;
+    }
+    if (schema instanceof zod_1.z.ZodArray) {
+        return `Array<${getTypeString(schema.element)}>`;
+    }
+    if (schema instanceof zod_1.z.ZodString) {
+        let result = 'String';
+        if (schema.minLength !== null || schema.maxLength !== null) {
+            const constraints = [];
+            if (schema.minLength !== null)
+                constraints.push(`min: ${schema.minLength}`);
+            if (schema.maxLength !== null)
+                constraints.push(`max: ${schema.maxLength}`);
+            result += ` (${constraints.join(', ')})`;
+        }
+        return result;
+    }
+    if (schema instanceof zod_1.z.ZodNumber) {
+        let result = 'Number';
+        if (schema.minValue !== null || schema.maxValue !== null) {
+            const constraints = [];
+            if (schema.minValue !== null)
+                constraints.push(`min: ${schema.minValue}`);
+            if (schema.maxValue !== null)
+                constraints.push(`max: ${schema.maxValue}`);
+            result += ` (${constraints.join(', ')})`;
+        }
+        return result;
+    }
+    if (schema instanceof zod_1.z.ZodEnum) {
+        return `Enum(${schema.options.join(' | ')})`;
+    }
+    if (schema instanceof zod_1.z.ZodLiteral) {
+        return `Literal(${JSON.stringify(schema.value)})`;
+    }
+    if (schema instanceof zod_1.z.ZodBoolean)
+        return 'Boolean';
+    if (schema instanceof zod_1.z.ZodBigInt)
+        return 'BigInt';
+    if (schema instanceof zod_1.z.ZodDate)
+        return 'Date';
+    if (schema instanceof zod_1.z.ZodNaN)
+        return 'NaN';
+    if (schema instanceof zod_1.z.ZodNever)
+        return 'Never';
+    if (schema instanceof zod_1.z.ZodUnknown)
+        return 'Unknown';
+    if (schema instanceof zod_1.z.ZodVoid)
+        return 'Void';
+    if (schema instanceof zod_1.z.ZodRecord) {
+        return `Record<${getTypeString(schema.keySchema)}, ${getTypeString(schema.valueSchema)}>`;
+    }
+    if (schema instanceof zod_1.z.ZodTuple) {
+        const items = schema.items.map((item) => getTypeString(item)).join(', ');
+        return `Tuple(${items})`;
+    }
+    if (schema instanceof zod_1.z.ZodUnion) {
+        const options = schema.options.map((opt) => getTypeString(opt)).join(' | ');
+        return `Union(${options})`;
+    }
+    if (schema instanceof zod_1.z.ZodDiscriminatedUnion) {
+        return `DiscriminatedUnion(${schema.discriminator})`;
+    }
+    if (schema instanceof zod_1.z.ZodIntersection) {
+        return 'Intersection';
+    }
+    if (schema instanceof zod_1.z.ZodEffects) {
+        return `Effects(${schema._def.effect.type})`;
+    }
+    return schema.constructor.name;
+}
 function zodSchemaToMarkdown(schema, indentLevel = 0) {
     let markdown = "";
     const indent = "  ".repeat(indentLevel);

package/lib/index.test.js

@@ -131,3 +131,81 @@ describe('zodSchemaToMarkdown', () => {
         expect((0, index_1.zodSchemaToMarkdown)(schema)).toBe(expected);
     });
 });
+describe('zodSchemaToTable', () => {
+    it('should convert a simple object schema to table', () => {
+        const schema = zod_1.z.object({
+            name: zod_1.z.string(),
+            age: zod_1.z.number(),
+        });
+        const expected = `| 字段 | 类型 | 描述 |
+|------|------|------|
+| name | String | - |
+| age | Number | - |
+`;
+        expect((0, index_1.zodSchemaToTable)(schema)).toBe(expected);
+    });
+    it('should convert object schema with optional and nullable to table', () => {
+        const schema = zod_1.z.object({
+            name: zod_1.z.string().optional(),
+            email: zod_1.z.string().nullable(),
+        });
+        const expected = `| 字段 | 类型 | 描述 |
+|------|------|------|
+| name | Optional<String> | - |
+| email | Nullable<String> | - |
+`;
+        expect((0, index_1.zodSchemaToTable)(schema)).toBe(expected);
+    });
+    it('should convert object schema with enum to table', () => {
+        const schema = zod_1.z.object({
+            role: zod_1.z.enum(['admin', 'user', 'guest']),
+        });
+        const expected = `| 字段 | 类型 | 描述 |
+|------|------|------|
+| role | Enum(admin | user | guest) | - |
+`;
+        expect((0, index_1.zodSchemaToTable)(schema)).toBe(expected);
+    });
+    it('should convert object schema with array to table', () => {
+        const schema = zod_1.z.object({
+            tags: zod_1.z.array(zod_1.z.string()),
+            scores: zod_1.z.array(zod_1.z.number()),
+        });
+        const expected = `| 字段 | 类型 | 描述 |
+|------|------|------|
+| tags[] | Array<String> | - |
+| scores[] | Array<Number> | - |
+`;
+        expect((0, index_1.zodSchemaToTable)(schema)).toBe(expected);
+    });
+    it('should convert object schema with description to table', () => {
+        const schema = zod_1.z.object({
+            name: zod_1.z.string().describe('用户名称'),
+            age: zod_1.z.number().describe('用户年龄'),
+        });
+        const expected = `| 字段 | 类型 | 描述 |
+|------|------|------|
+| name | String | 用户名称 |
+| age | Number | 用户年龄 |
+`;
+        expect((0, index_1.zodSchemaToTable)(schema)).toBe(expected);
+    });
+    it('should convert object schema with literal to table', () => {
+        const schema = zod_1.z.object({
+            status: zod_1.z.literal('active'),
+            count: zod_1.z.literal(1),
+        });
+        const expected = `| 字段 | 类型 | 描述 |
+|------|------|------|
+| status | Literal("active") | - |
+| count | Literal(1) | - |
+`;
+        expect((0, index_1.zodSchemaToTable)(schema)).toBe(expected);
+    });
+    it('should fallback to markdown for non-object schema', () => {
+        const schema = zod_1.z.string();
+        const expected = `- String
+`;
+        expect((0, index_1.zodSchemaToTable)(schema)).toBe(expected);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chnak/zod-to-markdown",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "A utility function to convert Zod schemas to Markdown documentation",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",