@chnak/zod-to-markdown 1.0.2 → 1.0.4

package/README.md

@@ -1,177 +1,246 @@
-# zod-to-markdown
-
-将 Zod schema 转换为 Markdown 文档的工具函数。
-
-## 安装
-
-```bash
-npm install @chnak/zod-to-markdown
-```
-
-## 使用方法
-
-### ESM / TypeScript
-
-```typescript
-import { zodSchemaToMarkdown } 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);
-```
-
-### CommonJS / Node.js
-
-```javascript
-const { zodSchemaToMarkdown } = require('@chnak/zod-to-markdown');
-const { z } = require('zod');
-
-const schema = z.object({
-  name: z.string(),
-  age: z.number(),
-});
-
-const markdown = zodSchemaToMarkdown(schema);
-console.log(markdown);
-```
-
-### 输出结果
-
-```markdown
-- 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
-
-```typescript
-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));
-```
-
-输出：
-```markdown
-- id
-  - String
-- name
-  - String
-- email
-  - String
-- age
-  - Optional
-    - Number
-- role
-  - Enum: admin, user, guest
-- metadata
-  - Optional
-    - Record
-      Key:
-        - String
-      Value:
-        - Unknown
-```
-
-### 鉴别联合类型 (Discriminated Union)
-
-```typescript
-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));
-```
-
-输出：
-```markdown
-- DiscriminatedUnion (key: role)
-  - role
-    - Literal: "user"
-  - content
-    - String
-  |
-  - role
-    - Literal: "assistant"
-  - content
-    - String
-```
-
-### Transform 效果
-
-```typescript
-const transformedSchema = z.string().transform(val => val.length);
-
-console.log(zodSchemaToMarkdown(transformedSchema));
-```
-
-输出：
-```markdown
-- Effects (transform)
-  - String
-```
-
-## API
-
-### `zodSchemaToMarkdown(schema, indentLevel?)`
-
-| 参数 | 类型 | 说明 |
-|------|------|------|
-| `schema` | `z.ZodTypeAny` | 要转换的 Zod schema |
-| `indentLevel` | `number` | 初始缩进级别（默认: `0`） |
-
-返回转换后的 Markdown 字符串。
-
-## License
-
-MIT License
+# zod-to-markdown
+
+将 Zod schema 转换为 Markdown 文档的工具函数，支持两种输出格式：树状列表和表格。
+
+## 安装
+
+```bash
+npm install @chnak/zod-to-markdown
+```
+
+## 使用方法
+
+### ESM / TypeScript
+
+```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
+
+```javascript
+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`)**：
+
+```markdown
+- name
+  - String
+- age
+  - Number
+```
+
+**表格格式 (`zodSchemaToTable`)**：
+
+```markdown
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| 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
+
+```typescript
+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));
+```
+
+输出：
+```markdown
+- id
+  - String
+- name
+  - String
+- email
+  - String
+- age
+  - Optional
+    - Number
+- role
+  - Enum: admin, user, guest
+- metadata
+  - Optional
+    - Record
+      Key:
+        - String
+      Value:
+        - Unknown
+```
+
+### 鉴别联合类型 (Discriminated Union)
+
+```typescript
+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));
+```
+
+输出：
+```markdown
+- DiscriminatedUnion (key: role)
+  - role
+    - Literal: "user"
+  - content
+    - String
+  |
+  - role
+    - Literal: "assistant"
+  - content
+    - String
+```
+
+### Transform 效果
+
+```typescript
+const transformedSchema = z.string().transform(val => val.length);
+
+console.log(zodSchemaToMarkdown(transformedSchema));
+```
+
+输出：
+```markdown
+- Effects (transform)
+  - 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?)`
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `schema` | `z.ZodTypeAny` | 要转换的 Zod schema |
+| `indentLevel` | `number` | 初始缩进级别（默认: `0`） |
+
+返回树状格式的 Markdown 字符串。
+
+### `zodSchemaToTable(schema)`
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `schema` | `z.ZodTypeAny` | 要转换的 Zod schema（仅支持 ZodObject） |
+
+返回表格格式的 Markdown 字符串。非 ZodObject 类型会回退到树状格式。
+
+## License
+
+MIT License

package/examples/company-schema-table.md

@@ -2,17 +2,17 @@
 |------|------|------|
 | id | String | 公司ID |
 | name | String | 公司名称 |
-| departments[] | name | 部门名称 |
-| departments[] | employees[] | 员工ID |
-| departments[] | employees[] | 姓名 |
-| departments[] | employees[] | 职位 |
-| departments[] | employees[] | 技能 |
-| departments[] | employees[] | 邮箱 |
-| departments[] | employees[] | 电话 |
-| departments[] | location.street | 街道 |
-| departments[] | location.city | 城市 |
-| departments[] | location.country | 国家 |
-| departments[] | location.coordinates.lat | 纬度 |
-| departments[] | location.coordinates.lng | 经度 |
+| 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

@@ -1,60 +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');
+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');