type-flash 1.1.10 → 1.2.0

package/README.md

@@ -2,46 +2,55 @@
 
 # type-flash
 
-**JSON 智能生成 TypeScript 类型定义**
+**智能 TypeScript 类型生成器 · 零依赖 · 轻量 · 极速**
 
 [![npm version](https://img.shields.io/npm/v/type-flash.svg?style=flat-square)](https://www.npmjs.com/package/type-flash)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
 
-> **One line of code, types generated instantly.**
-> 一行代码，类型秒出。告别手写 Interface 的繁琐时代。
 
-[功能特性](#-功能特性) • [快速开始](#-快速开始) • [使用方式](#-使用方式) • [配置选项](#-配置选项) • [对比优势](#-对比优势)
+> 自动生成 TypeScript 类型定义，支持对象 / JSON / 接口返回，一行代码搞定，彻底告别手写类型的繁琐工作。
+
+[功能特性](#功能特性) • [快速开始](#快速开始) • [使用方式](#使用方式) • [配置选项](#配置选项) • [优势对比](#优势对比) • [常见问题](#常见问题)
 
 </div>
 
 ---
 
-## ✨ 功能特性
+## 功能特性
 
-### 🎯 核心能力
+type-flash 基于内置的类型推断算法，能够深度解析 JSON 数据结构，自动生成精准的 TypeScript 类型定义。
 
-- **🔍 智能类型推断** - 自动识别 string / number / boolean / null / undefined 等基础类型
-- **📦 嵌套对象支持** - 递归遍历深层结构，自动生成子接口定义
-- **🔗 联合类型推断** - 数组元素类型不同？自动合并为 `(string | number)[]`
-- **❓ 可选属性识别** - 数组中部分对象缺少某字段？自动标记为 `?` 可选
-- **🔄 结构等价去重** - 相同结构的对象复用同一类型，避免重复定义
-- **🔁 循环引用检测** - 智能检测并处理 JSON 中的循环引用
+| 能力 | 说明 | 示例 |
+|------|------|------|
+| **基础类型识别** | 自动识别 string / number / boolean / null / undefined / function 等多种类型 | `name: string` |
+| **嵌套对象推导** | 递归遍历深层嵌套结构，自动生成子接口定义，支持无限层级 | `profile: UserProfile` |
+| **联合类型合并** | 数组元素类型不一致时，自动合并为联合类型，保留完整类型信息 | `(string \| number)[]` |
+| **可选属性识别** | 智能分析数组中对象的字段出现频率，自动标记可选属性 | `desc?: string` |
+| **结构等价去重** | 基于结构等价性算法，相同结构的对象自动复用同一类型，避免重复定义 | 全局唯一类型 |
+| **循环引用检测** | 自动检测 JSON 数据中的循环引用，生成合法的 type alias 处理循环 | 安全无栈溢出 |
+| **函数类型支持** | 支持识别函数类型，正确输出 Function 类型声明 | `callback: Function` |
 
-### ⚡ 增强功能
+#### 灵活的输出控制
 
-- **🧬 泛型模式识别** - 智能识别分页结构 `{ list: T[], total: number }`，提取为 `PageResult<T>`
-- **🎨 多种输出风格** - 支持 `interface` 和 `type alias` 两种输出风格
-- **📏 灵活命名控制** - 支持 PascalCase / camelCase、前缀后缀、自定义类型名映射
+- **双风格输出**：支持 `interface` 和 `type alias` 两种输出风格，适配不同团队规范；
+- **命名风格切换**：支持 PascalCase / camelCase 两种命名风格，满足各种编码规范；
+- **前后缀自定义**：为所有生成的类型名添加统一前缀/后缀，如 `IUserDTO`；
+- **自定义类型名**：通过 `typeNameMap` 精确指定任意层级字段的类型名称；
+- **属性排序**：支持字母序 / 定义序两种属性排序方式；
 
-### 🛠️ 工程化支持
+#### 工程化能力
 
-- **💻 CLI 命令行工具** - 开箱即用的命令行工具，支持管道输入
-- **📦 双模块输出** - 同时提供 CommonJS 和 ESM 两种模块格式
-- **🔩 TypeScript 原生** - 纯 TypeScript 编写，类型定义开箱即用
+| 特性 | 说明 |
+|------|------|
+| **CLI 命令行** | 开箱即用的命令行工具，支持文件输入/输出、管道输入，轻松集成到工作流 |
+| **双模块输出** | 同时提供 CommonJS 和 ESM 两种模块格式，兼容 Node.js 和浏览器环境 |
+| **TypeScript 原生** | 纯 TypeScript 编写，类型定义开箱即用，支持 IDE 智能提示 |
+| **零依赖** | 运行时零第三方依赖，包体仅 ~10KB，轻量无负担 |
+| **高兼容性** | 支持 Node.js 14+，兼容所有主流 TypeScript 版本 |
 
 ---
 
-## 🚀 快速开始
+## 快速开始
 
 ### 安装
 
@@ -52,16 +61,16 @@ npm install type-flash --save-dev
 # yarn
 yarn add type-flash -D
 
-# pnpm
-pnpm add type-flash -D
+# 全局安装（使用 CLI）
+npm install -g type-flash
 ```
 
-### 一行代码上手
+### 使用
 
 ```typescript
 import { generate } from 'type-flash';
 
-const jsonData = {
+const data = {
   id: 1,
   name: 'Alice',
   email: 'alice@example.com',
@@ -69,11 +78,11 @@ const jsonData = {
     avatar: 'https://example.com/avatar.jpg',
     bio: 'Hello World',
   },
-  tags: ['admin', 'user'],
+  tags: ['admin', 'user', 88],
 };
 
-const result = generate(jsonData, { rootName: 'User' });
-console.log(result.code);
+const result = generate(data, { rootName: 'User' });
+console.log(result);
 ```
 
 **输出结果：**
@@ -83,13 +92,12 @@ console.log(result.code);
  * Generated by type-flash
  * Root type: User
  */
-
 export interface User {
   email: string;
   id: number;
   name: string;
   profile: UserProfile;
-  tags: string[];
+  tags: (string | number)[];
 }
 
 export interface UserProfile {
@@ -100,40 +108,42 @@ export interface UserProfile {
 
 ---
 
-## 📖 使用方式
+## 使用方式
 
 ### 1. 编程式 API
 
 #### 基础用法
 
 ```typescript
-import { generate, generateFromString } from 'type-flash';
+import { generate } from 'type-flash';
 
-// 从 JS 对象生成
-const result1 = generate({ name: 'foo', age: 25 }, { rootName: 'User' });
+const result = generate(data, GenerateOptions);
+```
 
-// 从 JSON 字符串生成
-const result2 = generateFromString('{"name": "foo"}', { rootName: 'User' });
+#### 基础示例
 
-// 获取生成的代码
-console.log(result1.code);
+```typescript
+import { generate, generateFromString } from 'type-flash';
+
+// 从 JS 对象生成，直接返回代码字符串
+const code1 = generate({ name: 'foo', age: 25 }, { rootName: 'User' });
 
-// 获取所有类型定义
-console.log(result1.types);
+// 从 JSON 字符串生成
+const code2 = generateFromString('{"name": "foo"}', { rootName: 'User' });
 ```
 
-#### 分页接口示例
+#### 分页数据示例
 
 ```typescript
 import { generate } from 'type-flash';
 
 const apiResponse = {
-  code: 0,
+  code: 200,
   message: 'success',
   data: {
     list: [
-      { id: 1, name: 'Alice', status: 'active' },
-      { id: 2, name: 'Bob', status: 'inactive' },
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' },
     ],
     total: 100,
     page: 1,
@@ -141,15 +151,14 @@ const apiResponse = {
   },
 };
 
-const result = generate(apiResponse, {
+const code = generate(apiResponse, {
   rootName: 'ApiResponse',
-  extractGenerics: true,
 });
 
-console.log(result.code);
+console.log(code);
 ```
 
-**输出：**
+输出：
 
 ```typescript
 export interface ApiResponse {
@@ -159,13 +168,13 @@ export interface ApiResponse {
 }
 
 export interface ApiResponseData {
-  list: PageResult<ListItem>;
+  list: ApiResponseDataListItem[];
   page: number;
   pageSize: number;
   total: number;
 }
 
-export interface ListItem {
+export interface ApiResponseDataListItem {
   id: number;
   name: string;
 }
@@ -175,34 +184,88 @@ export interface ListItem {
 
 #### 基础用法
 
+```json
+// user.json
+{
+  "id": 1,
+  "name": 'Alice',
+  "email": 'alice@example.com',
+  "profile": {
+    "avatar": 'https://example.com/avatar.jpg',
+    "bio": 'Hello World',
+  },
+  "tags": ['admin', 'user', 88],
+};
+```
+
 ```bash
-# 从文件生成，输出到控制台
-type-flash user.json
+# 读取文件并生成类型，输出到控制台
+type-flash -i user.json
 
 # 指定输出文件
-type-flash user.json -o user.types.ts
+type-flash -i user.json -o user.types.ts
 
 # 自定义根类型名
-type-flash user.json -n User
+type-flash -i user.json -n User
 
 # 使用 type 风格输出
-type-flash data.json --style type
+type-flash -i user.json -s type
 ```
 
-#### 高级用法
+#### 常用选项示例
 
 ```bash
-# 从标准输入读取（管道）
+# 严格空值模式（保留 null 为独立类型）
+type-flash -i user.json --strict-null
+
+# 添加类型前缀/后缀
+type-flash -i user.json --prefix I --suffix DTO -o user.ts
+
+# 不生成 export
+type-flash -i user.json --no-export
+
+# 4 空格缩进
+type-flash -i user.json --indent 4
+
+# camelCase 命名风格
+type-flash -i user.json --naming-style camelCase
+```
+
+#### 管道输入（标准输入）
+
+支持通过管道接收其他命令输出的数据，无需新建临时文件，方便接口调试与自动化脚本调用。
+
+> **适用场景**
+>
+> - 接口调试：拉取线上接口返回数据即时生成类型，省去存文件步骤；
+>
+> - 脚本集成：写自动化脚本时，串联多条命令，自动批量生成类型；
+>
+>
+
+**Linux / macOS / Git Bash：**
+```bash
+# 从接口直接生成类型
 curl https://api.example.com/users | type-flash -n UserList
 
-# 严格空值模式
-type-flash data.json --strict-null
+# 快速测试
+echo '{"name": "Alice", "age": 18}' | type-flash -n User
+
+# 从文件读取并管道
+cat data.json | type-flash -n User
+```
 
-# 添加类型前缀
-type-flash response.json --prefix I -o interfaces.ts
+**Windows PowerShell：**
+```powershell
+# 方式一：先保存到文件（推荐，最稳定）
+curl https://api.example.com/users -o temp.json
+type-flash -i temp.json -n UserList -o temp.ts
 
-# 不生成 export
-type-flash types.json --no-export
+# 方式二：用 curl.exe（需安装 Git 或原生 curl）
+curl.exe https://api.example.com/users | type-flash -n UserList
+
+# 方式三：PowerShell 原生方式
+(Invoke-RestMethod https://api.example.com/users | ConvertTo-Json -Depth 10) | type-flash -n UserList
 ```
 
 #### 所有 CLI 选项
@@ -210,120 +273,93 @@ type-flash types.json --no-export
 | 选项 | 说明 | 默认值 |
 |------|------|--------|
 | `-i, --input <file>` | 输入 JSON 文件路径 | - |
-| `-o, --output <file>` | 输出 TS 文件路径 | stdout |
+| `-o, --output <file>` | 输出 TS 文件路径 | 控制台输出 |
 | `-n, --name <name>` | 根类型名称 | `Root` |
 | `-s, --style <style>` | 输出风格: `interface` \| `type` | `interface` |
 | `--naming-style <s>` | 命名风格: `PascalCase` \| `camelCase` | `PascalCase` |
 | `--sort <order>` | 属性排序: `alpha` \| `definition` | `alpha` |
 | `--no-export` | 不添加 export 关键字 | - |
-| `--strict-null` | 严格空值模式 | - |
+| `--strict-null` | 严格空值模式（保留 null 类型） | - |
 | `--no-optional` | 不标记可选属性 | - |
-| `--no-generics` | 不提取泛型类型 | - |
 | `--indent <n>` | 缩进空格数 | `2` |
 | `--prefix <prefix>` | 类型名前缀 | - |
 | `--suffix <suffix>` | 类型名后缀 | - |
-| `-h, --help` | 显示帮助 | - |
+| `-h, --help` | 显示帮助信息 | - |
 | `-v, --version` | 显示版本号 | - |
 
 ---
 
-## ⚙️ 配置选项
-
-### GenerateOptions 完整配置
-
-```typescript
-interface GenerateOptions {
-  /** 根类型名称，默认 'Root' */
-  rootName?: string;
-  
-  /** 输出风格：interface 或 type，默认 'interface' */
-  outputStyle?: 'interface' | 'type';
-  
-  /** 命名风格：PascalCase 或 camelCase，默认 'PascalCase' */
-  namingStyle?: 'PascalCase' | 'camelCase';
-  
-  /** 属性排序方式，默认 'alpha' */
-  sortProperties?: 'alpha' | 'definition';
-  
-  /** 是否添加 export 语句，默认 true */
-  addExport?: boolean;
-  
-  /** 是否严格空值，默认 false */
-  strictNullChecks?: boolean;
-  
-  /** 是否标记可选属性，默认 true */
-  markOptional?: boolean;
-  
-  /** 是否提取泛型，默认 true */
-  extractGenerics?: boolean;
-  
-  /** 缩进空格数，默认 2 */
-  indentSize?: number;
-  
-  /** 自定义类型名映射 */
-  typeNameMap?: Record<string, string>;
-  
-  /** 类型名前缀 */
-  typePrefix?: string;
-  
-  /** 类型名后缀 */
-  typeSuffix?: string;
-}
-```
-
-### 配置示例
-
-#### 企业级 DTO 配置
-
-```typescript
-import { generate } from 'type-flash';
-
-const result = generate(jsonData, {
-  rootName: 'UserDTO',
-  outputStyle: 'interface',
-  namingStyle: 'PascalCase',
-  typePrefix: 'I',
-  typeSuffix: 'DTO',
-  addExport: true,
-  sortProperties: 'alpha',
-  extractGenerics: true,
-  strictNullChecks: true,
-  indentSize: 2,
-});
-```
+## 配置选项
+
+### GenerateOptions 完整配置表
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `rootName` | `string` | `'Root'` | 根类型名称 |
+| `outputStyle` | `'interface' \| 'type'` | `'interface'` | 输出风格，接口或类型别名 |
+| `namingStyle` | `'PascalCase' \| 'camelCase'` | `'PascalCase'` | 生成的类型名命名风格 |
+| `sortProperties` | `'alpha' \| 'definition'` | `'alpha'` | 属性排序方式，字母序或定义序 |
+| `addExport` | `boolean` | `true` | 是否添加 export 关键字 |
+| `strictNullChecks` | `boolean` | `false` | 是否启用严格空值模式，保留 null 为独立类型 |
+| `markOptional` | `boolean` | `true` | 是否自动标记可选属性 |
+| `indentSize` | `number` | `2` | 缩进空格数 |
+| `lineEnding` | `string` | `'\n'` | 行尾换行符 |
+| `typeNameMap` | `Record<string, string>` | `{}` | 自定义类型名映射，key 为字段路径 |
+| `typePrefix` | `string` | `''` | 所有类型名添加此前缀 |
+| `typeSuffix` | `string` | `''` | 所有类型名添加此后缀 |
 
 #### 自定义类型名映射
 
 ```typescript
-const result = generate(jsonData, {
+const code = generate(jsonData, {
   rootName: 'ApiResponse',
   typeNameMap: {
     'ApiResponse.data': 'ResponseData',
-    'ResponseData.list': 'UserItem',
+    'ApiResponse.data.list': 'UserItem',
+    'ApiResponse.data.list.extra': 'ExtraInfo',
   },
 });
 ```
 
+> 💡 **提示**：`typeNameMap` 的 key 格式为 `{根类型名}.{字段名}.{子字段名}...`，支持任意深度。
+
 ---
 
-## 🆚 对比优势
+## 优势对比
 
-### 与其他方案对比
 
-| 特性 | type-flash | json-schema-to-typescript | 在线转换工具 | quicktype |
-|------|--------|---------------------------|--------------|-----------|
-| **直接输入 JSON** | ✅ | ❌ 需要 JSON Schema | ✅ | ✅ |
-| **嵌套对象自动命名** | ✅ 智能命名 | ✅ | ⚠️ 简单命名 | ✅ |
-| **联合类型推断** | ✅ | ⚠️ 有限支持 | ❌ | ✅ |
-| **可选属性识别** | ✅ | ✅ | ❌ | ✅ |
-| **枚举自动提取** | ✅ | ⚠️ 需手动定义 | ❌ | ✅ |
-| **泛型模式识别** | ✅ | ❌ | ❌ | ❌ |
-| **结构等价去重** | ✅ | ⚠️ 有限 | ❌ | ✅ |
-| **循环引用处理** | ✅ | ✅ | ❌ | ✅ |
-| **CLI 命令行** | ✅ | ✅ | ❌ | ✅ |
-| **编程式 API** | ✅ | ✅ | ❌ | ✅ |
-| **零依赖** | ✅ | ❌ 依赖多 | - | ❌ 包体大 |
-| **体积大小** | ~10KB | ~100KB | - | ~500KB |
+| 特性 | type-flash | json-schema-to-typescript | 其它 |
+|------|-----------|---------------------------|--------------|
+| **直接输入 JSON** | ✅ | ❌ 需要 JSON Schema | ✅ |
+| **嵌套对象智能命名** | ✅ 上下文感知命名 | ⚠️ 简单拼接 | ⚠️ 简单命名 |
+| **联合类型推断** | ✅ 完整支持 | ⚠️ 有限支持 | ❌ |
+| **可选属性识别** | ✅ 频率分析 | ✅ | ❌ | ⚠️部分 |
+| **结构等价去重** | ✅ 精确算法 | ⚠️ 有限 | ⚠️部分 |
+| **循环引用处理** | ✅ 安全检测 | ✅ | ❌ |
+| **函数类型支持** | ✅ | ❌ | ❌ |
+| **CLI 命令行** | ✅ | ✅ | ❌ |
+| **编程式 API** | ✅ | ✅ | ❌ |
+| **零运行时依赖** | ✅ | ❌ 依赖多 | ❌ 包体大 |
+| **包体大小** | ~10KB | ~100KB | ~500KB |
+| **安装速度** | ⚡ 极快 | 🐢 较慢 | 🐢 慢 |
+
+---
+
+## 常见问题
+
+### Q: 生成的类型名为什么是 UserProfile 而不是 Profile？
+A: type-flash 默认会用父级类型名 + 字段名来生成子类型名，避免重名。如果想自定义类型名，可以使用 `typeNameMap` 配置。
+
+### Q: 为什么数组里的 null 被去掉了？
+A: 默认情况下 `strictNullChecks` 为 `false`，会自动移除 null 类型。如果需要保留 null，可以设置 `strictNullChecks: true`。
+
+### Q: 支持循环引用的 JSON 吗？
+A: 支持。type-flash 会自动检测循环引用并生成合法的 type alias，不会出现栈溢出。
+
+### Q: 可以在浏览器环境使用吗？
+A: 可以。type-flash 同时提供 ESM 格式，支持在浏览器和 Node.js 环境中使用。
+
+---
 
-**如果觉得好用，别忘了给个 ⭐ Star 支持一下！**
 
+**如果觉得好用，别忘了给个 ⭐ Star 支持一下喔~**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "type-flash",
-  "version": "1.1.10",
+  "version": "1.2.0",
   "description": "JSON 智能生成 TypeScript 类型定义 - 一键从 JSON 数据生成 Interface / Type 定义",
   "main": "dist/index.js",
   "module": "dist/index.mjs",