type-flash 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lebron_shi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,358 @@
+<div align="center">
+
+# type-gen
+
+**JSON 智能生成 TypeScript 类型定义**
+
+[![npm version](https://img.shields.io/npm/v/type-gen.svg?style=flat-square)](https://www.npmjs.com/package/type-gen)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE)
+
+> **One line of code, types generated instantly.**
+> 一行代码，类型秒出。告别手写 Interface 的繁琐时代。
+
+[功能特性](#-功能特性) • [快速开始](#-快速开始) • [使用方式](#-使用方式) • [配置选项](#-配置选项) • [对比优势](#-对比优势)
+
+</div>
+
+---
+
+## ✨ 功能特性
+
+### 🎯 核心能力
+
+- **🔍 智能类型推断** - 自动识别 string / number / boolean / null / undefined 等基础类型
+- **📦 嵌套对象支持** - 递归遍历深层结构，自动生成子接口定义
+- **🔗 联合类型推断** - 数组元素类型不同？自动合并为 `(string | number)[]`
+- **❓ 可选属性识别** - 数组中部分对象缺少某字段？自动标记为 `?` 可选
+- **🔄 结构等价去重** - 相同结构的对象复用同一类型，避免重复定义
+- **🔁 循环引用检测** - 智能检测并处理 JSON 中的循环引用
+
+### ⚡ 增强功能
+
+- **📑 枚举自动提取** - 字符串字段取值有限时，自动提取为 `enum` 枚举类型
+- **🧬 泛型模式识别** - 智能识别分页结构 `{ list: T[], total: number }`，提取为 `PageResult<T>`
+- **📝 JSDoc 注释生成** - 根据字段名猜测含义，自动生成文档注释
+- **🎨 多种输出风格** - 支持 `interface` 和 `type alias` 两种输出风格
+- **📏 灵活命名控制** - 支持 PascalCase / camelCase、前缀后缀、自定义类型名映射
+
+### 🛠️ 工程化支持
+
+- **💻 CLI 命令行工具** - 开箱即用的命令行工具，支持管道输入
+- **📦 双模块输出** - 同时提供 CommonJS 和 ESM 两种模块格式
+- **🔩 TypeScript 原生** - 纯 TypeScript 编写，类型定义开箱即用
+- **🧪 完整测试覆盖** - Jest 单元测试，确保核心功能稳定可靠
+
+---
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+# npm
+npm install type-gen --save-dev
+
+# yarn
+yarn add type-gen -D
+
+# pnpm
+pnpm add type-gen -D
+```
+
+### 一行代码上手
+
+```typescript
+import { generate } from 'type-gen';
+
+const jsonData = {
+  id: 1,
+  name: 'Alice',
+  email: 'alice@example.com',
+  profile: {
+    avatar: 'https://example.com/avatar.jpg',
+    bio: 'Hello World',
+  },
+  tags: ['admin', 'user'],
+};
+
+const result = generate(jsonData, { rootName: 'User' });
+console.log(result.code);
+```
+
+**输出结果：**
+
+```typescript
+/**
+ * Generated by type-gen
+ * Root type: User
+ */
+
+export interface User {
+  email: string;
+  id: number;
+  name: string;
+  profile: UserProfile;
+  tags: string[];
+}
+
+export interface UserProfile {
+  avatar: string;
+  bio: string;
+}
+```
+
+---
+
+## 📖 使用方式
+
+### 1. 编程式 API
+
+#### 基础用法
+
+```typescript
+import { generate, generateFromString } from 'type-gen';
+
+// 从 JS 对象生成
+const result1 = generate({ name: 'foo', age: 25 }, { rootName: 'User' });
+
+// 从 JSON 字符串生成
+const result2 = generateFromString('{"name": "foo"}', { rootName: 'User' });
+
+// 获取生成的代码
+console.log(result1.code);
+
+// 获取所有类型定义
+console.log(result1.types);
+```
+
+#### 分页接口示例
+
+```typescript
+import { generate } from 'type-gen';
+
+const apiResponse = {
+  code: 0,
+  message: 'success',
+  data: {
+    list: [
+      { id: 1, name: 'Alice', status: 'active' },
+      { id: 2, name: 'Bob', status: 'inactive' },
+    ],
+    total: 100,
+    page: 1,
+    pageSize: 10,
+  },
+};
+
+const result = generate(apiResponse, {
+  rootName: 'ApiResponse',
+  extractEnums: true,
+  extractGenerics: true,
+});
+
+console.log(result.code);
+```
+
+**输出：**
+
+```typescript
+export interface ApiResponse {
+  code: number;
+  data: ApiResponseData;
+  message: string;
+}
+
+export interface ApiResponseData {
+  list: PageResult<ListItem>;
+  page: number;
+  pageSize: number;
+  total: number;
+}
+
+export interface ListItem {
+  id: number;
+  name: string;
+  status: StatusEnum;
+}
+
+export enum StatusEnum {
+  ACTIVE = 'active',
+  INACTIVE = 'inactive',
+}
+```
+
+### 2. CLI 命令行
+
+#### 基础用法
+
+```bash
+# 从文件生成，输出到控制台
+type-gen user.json
+
+# 指定输出文件
+type-gen user.json -o user.types.ts
+
+# 自定义根类型名
+type-gen user.json -n User
+
+# 使用 type 风格输出
+type-gen data.json --style type
+```
+
+#### 高级用法
+
+```bash
+# 从标准输入读取（管道）
+curl https://api.example.com/users | type-gen -n UserList
+
+# 生成带注释的类型定义
+type-gen api.json --comments -o api-types.ts
+
+# 严格空值模式
+type-gen data.json --strict-null
+
+# 添加类型前缀
+type-gen response.json --prefix I -o interfaces.ts
+
+# 不生成 export
+type-gen types.json --no-export
+```
+
+#### 所有 CLI 选项
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `-i, --input <file>` | 输入 JSON 文件路径 | - |
+| `-o, --output <file>` | 输出 TS 文件路径 | stdout |
+| `-n, --name <name>` | 根类型名称 | `Root` |
+| `-s, --style <style>` | 输出风格: `interface` \| `type` | `interface` |
+| `--naming-style <s>` | 命名风格: `PascalCase` \| `camelCase` | `PascalCase` |
+| `--sort <order>` | 属性排序: `alpha` \| `definition` | `alpha` |
+| `--no-export` | 不添加 export 关键字 | - |
+| `--comments` | 生成 JSDoc 注释 | - |
+| `--strict-null` | 严格空值模式 | - |
+| `--no-optional` | 不标记可选属性 | - |
+| `--no-enums` | 不提取枚举类型 | - |
+| `--enum-threshold <n>` | 枚举提取阈值 | `5` |
+| `--no-generics` | 不提取泛型类型 | - |
+| `--indent <n>` | 缩进空格数 | `2` |
+| `--prefix <prefix>` | 类型名前缀 | - |
+| `--suffix <suffix>` | 类型名后缀 | - |
+| `-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;
+  
+  /** 是否生成 JSDoc 注释，默认 false */
+  addComments?: boolean;
+  
+  /** 是否严格空值，默认 false */
+  strictNullChecks?: boolean;
+  
+  /** 是否标记可选属性，默认 true */
+  markOptional?: boolean;
+  
+  /** 是否提取枚举类型，默认 true */
+  extractEnums?: boolean;
+  
+  /** 枚举提取阈值，默认 5 */
+  enumThreshold?: number;
+  
+  /** 是否提取泛型，默认 true */
+  extractGenerics?: boolean;
+  
+  /** 缩进空格数，默认 2 */
+  indentSize?: number;
+  
+  /** 自定义类型名映射 */
+  typeNameMap?: Record<string, string>;
+  
+  /** 类型名前缀 */
+  typePrefix?: string;
+  
+  /** 类型名后缀 */
+  typeSuffix?: string;
+}
+```
+
+### 配置示例
+
+#### 企业级 DTO 配置
+
+```typescript
+import { generate } from 'type-gen';
+
+const result = generate(jsonData, {
+  rootName: 'UserDTO',
+  outputStyle: 'interface',
+  namingStyle: 'PascalCase',
+  typePrefix: 'I',
+  typeSuffix: 'DTO',
+  addExport: true,
+  addComments: true,
+  sortProperties: 'alpha',
+  extractEnums: true,
+  enumThreshold: 8,
+  extractGenerics: true,
+  strictNullChecks: true,
+  indentSize: 2,
+});
+```
+
+#### 自定义类型名映射
+
+```typescript
+const result = generate(jsonData, {
+  rootName: 'ApiResponse',
+  typeNameMap: {
+    'ApiResponse.data': 'ResponseData',
+    'ResponseData.list': 'UserItem',
+  },
+});
+```
+
+---
+
+## 🆚 对比优势
+
+### 与其他方案对比
+
+| 特性 | type-gen | json-schema-to-typescript | 在线转换工具 | quicktype |
+|------|--------|---------------------------|--------------|-----------|
+| **直接输入 JSON** | ✅ | ❌ 需要 JSON Schema | ✅ | ✅ |
+| **嵌套对象自动命名** | ✅ 智能命名 | ✅ | ⚠️ 简单命名 | ✅ |
+| **联合类型推断** | ✅ | ⚠️ 有限支持 | ❌ | ✅ |
+| **可选属性识别** | ✅ | ✅ | ❌ | ✅ |
+| **枚举自动提取** | ✅ | ⚠️ 需手动定义 | ❌ | ✅ |
+| **泛型模式识别** | ✅ | ❌ | ❌ | ❌ |
+| **结构等价去重** | ✅ | ⚠️ 有限 | ❌ | ✅ |
+| **循环引用处理** | ✅ | ✅ | ❌ | ✅ |
+| **JSDoc 注释生成** | ✅ | ✅ | ❌ | ✅ |
+| **CLI 命令行** | ✅ | ✅ | ❌ | ✅ |
+| **编程式 API** | ✅ | ✅ | ❌ | ✅ |
+| **零依赖** | ✅ | ❌ 依赖多 | - | ❌ 包体大 |
+| **体积大小** | ~10KB | ~100KB | - | ~500KB |
+
+**如果觉得好用，别忘了给个 ⭐ Star 支持一下！**
+

package/bin/type-gen.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+/**
+ * type-gen CLI - 命令行工具
+ * 
+ * 用法：
+ *   type-gen <input.json> [options]
+ *   type-gen -i input.json -o output.ts
+ *   cat data.json | type-gen
+ * 
+ * 示例：
+ *   type-gen user.json -n User
+ *   type-gen api.json --style type --no-export
+ *   curl https://api.example.com/users | type-gen -n UserList
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// 解析命令行参数
+function parseArgs(argv) {
+  const args = {
+    input: null,
+    output: null,
+    rootName: 'Root',
+    outputStyle: 'interface',
+    namingStyle: 'PascalCase',
+    sortProperties: 'alpha',
+    addExport: true,
+    addComments: false,
+    strictNullChecks: false,
+    markOptional: true,
+    extractEnums: true,
+    enumThreshold: 5,
+    extractGenerics: true,
+    indentSize: 2,
+    typePrefix: '',
+    typeSuffix: '',
+    help: false,
+    version: false,
+  };
+
+  let i = 2; // 跳过 node 和脚本路径
+  while (i < argv.length) {
+    const arg = argv[i];
+
+    switch (arg) {
+      case '-h':
+      case '--help':
+        args.help = true;
+        break;
+
+      case '-v':
+      case '--version':
+        args.version = true;
+        break;
+
+      case '-i':
+      case '--input':
+        args.input = argv[++i];
+        break;
+
+      case '-o':
+      case '--output':
+        args.output = argv[++i];
+        break;
+
+      case '-n':
+      case '--name':
+      case '--root-name':
+        args.rootName = argv[++i];
+        break;
+
+      case '-s':
+      case '--style':
+        args.outputStyle = argv[++i];
+        break;
+
+      case '--naming-style':
+        args.namingStyle = argv[++i];
+        break;
+
+      case '--sort':
+        args.sortProperties = argv[++i];
+        break;
+
+      case '--no-export':
+        args.addExport = false;
+        break;
+
+      case '--comments':
+        args.addComments = true;
+        break;
+
+      case '--strict-null':
+        args.strictNullChecks = true;
+        break;
+
+      case '--no-optional':
+        args.markOptional = false;
+        break;
+
+      case '--no-enums':
+        args.extractEnums = false;
+        break;
+
+      case '--enum-threshold':
+        args.enumThreshold = parseInt(argv[++i], 10);
+        break;
+
+      case '--no-generics':
+        args.extractGenerics = false;
+        break;
+
+      case '--indent':
+        args.indentSize = parseInt(argv[++i], 10);
+        break;
+
+      case '--prefix':
+        args.typePrefix = argv[++i];
+        break;
+
+      case '--suffix':
+        args.typeSuffix = argv[++i];
+        break;
+
+      default:
+        // 第一个非选项参数作为输入文件
+        if (!args.input && !arg.startsWith('-')) {
+          args.input = arg;
+        }
+        break;
+    }
+
+    i++;
+  }
+
+  return args;
+}
+
+// 显示帮助信息
+function showHelp() {
+  console.log(`
+type-gen - JSON 智能生成 TypeScript 类型定义
+
+用法:
+  type-gen <input.json> [options]
+  type-gen -i input.json -o output.ts
+  cat data.json | type-gen
+
+选项:
+  -i, --input <file>        输入 JSON 文件路径
+  -o, --output <file>       输出 TypeScript 文件路径（默认输出到 stdout）
+  -n, --name <name>         根类型名称（默认: Root）
+  -s, --style <style>       输出风格: interface | type（默认: interface）
+      --naming-style <s>    命名风格: PascalCase | camelCase（默认: PascalCase）
+      --sort <order>        属性排序: alpha | definition（默认: alpha）
+      --no-export           不添加 export 关键字
+      --comments            生成 JSDoc 注释
+      --strict-null         严格空值模式（保留 null 类型）
+      --no-optional         不标记可选属性
+      --no-enums            不提取枚举类型
+      --enum-threshold <n>  枚举提取阈值（默认: 5）
+      --no-generics         不提取泛型类型
+      --indent <n>          缩进空格数（默认: 2）
+      --prefix <prefix>     类型名前缀
+      --suffix <suffix>     类型名后缀
+  -h, --help                显示帮助信息
+  -v, --version             显示版本号
+
+示例:
+  # 从文件生成
+  type-gen user.json -n User -o user.ts
+
+  # 使用 type 风格输出
+  type-gen data.json --style type
+
+  # 从标准输入读取
+  curl https://api.example.com/data | type-gen -n ApiResponse
+
+  # 带前缀和注释
+  type-gen api.json --prefix Api --comments -o api-types.ts
+`);
+}
+
+// 显示版本号
+function showVersion() {
+  try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    console.log(`type-gen v${pkg.version}`);
+  } catch (e) {
+    console.log('type-gen (unknown version)');
+  }
+}
+
+// 读取输入
+async function readInput(inputPath) {
+  if (inputPath) {
+    // 从文件读取
+    const fullPath = path.resolve(inputPath);
+    if (!fs.existsSync(fullPath)) {
+      console.error(`错误: 文件不存在: ${fullPath}`);
+      process.exit(1);
+    }
+    return fs.readFileSync(fullPath, 'utf-8');
+  }
+
+  // 从标准输入读取
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+
+    process.stdin.on('data', chunk => {
+      data += chunk;
+    });
+
+    process.stdin.on('end', () => {
+      resolve(data);
+    });
+
+    process.stdin.on('error', reject);
+
+    // 检查是否有输入
+    setTimeout(() => {
+      if (!data) {
+        console.error('错误: 未提供输入数据。请指定输入文件或通过管道传入 JSON。');
+        console.error('使用 --help 查看帮助信息。');
+        process.exit(1);
+      }
+    }, 100);
+  });
+}
+
+// 主函数
+async function main() {
+  const args = parseArgs(process.argv);
+
+  if (args.help) {
+    showHelp();
+    return;
+  }
+
+  if (args.version) {
+    showVersion();
+    return;
+  }
+
+  try {
+    // 读取输入
+    const jsonStr = await readInput(args.input);
+
+    // 解析 JSON
+    let jsonData;
+    try {
+      jsonData = JSON.parse(jsonStr);
+    } catch (e) {
+      console.error(`错误: JSON 解析失败 - ${e.message}`);
+      process.exit(1);
+    }
+
+    // 动态导入生成函数
+    const { generate } = require('../dist/index.js');
+
+    // 生成类型
+    const result = generate(jsonData, {
+      rootName: args.rootName,
+      outputStyle: args.outputStyle,
+      namingStyle: args.namingStyle,
+      sortProperties: args.sortProperties,
+      addExport: args.addExport,
+      addComments: args.addComments,
+      strictNullChecks: args.strictNullChecks,
+      markOptional: args.markOptional,
+      extractEnums: args.extractEnums,
+      enumThreshold: args.enumThreshold,
+      extractGenerics: args.extractGenerics,
+      indentSize: args.indentSize,
+      typePrefix: args.typePrefix,
+      typeSuffix: args.typeSuffix,
+    });
+
+    // 输出结果
+    if (args.output) {
+      const outputPath = path.resolve(args.output);
+      fs.writeFileSync(outputPath, result.code, 'utf-8');
+      console.log(`✓ 已生成: ${outputPath}`);
+      console.log(`  共生成 ${result.types.length} 个类型定义`);
+    } else {
+      console.log(result.code);
+    }
+  } catch (e) {
+    console.error(`错误: ${e.message}`);
+    if (process.env.DEBUG) {
+      console.error(e.stack);
+    }
+    process.exit(1);
+  }
+}
+
+main();