@chihqiang/sql-quicktype 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 chihqiang
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,451 @@
+# sql-quicktype
+
+将原始 SQL DDL 转换为结构化、类型化的数据库 Schema 中间表示（IR），可直接在代码中使用和分析。
+
+## 功能特性
+
+- **SQL 解析器**：支持解析 MySQL、PostgreSQL、SQLite、SQL Server 等多种数据库方言的 DDL 语句
+- **多语言代码生成**：支持生成 TypeScript、Go、GORM、XORM 等多种语言的类型定义
+- **灵活的数据源**：支持从 SQL 字符串或数据库连接生成代码
+- **类型安全**：生成的代码包含完整的类型信息，提高代码安全性
+- **注释保留**：自动保留表和列的注释信息
+- **CLI 工具**：提供命令行工具，方便快速生成代码
+- **自定义类型解析器**：支持注入自定义的类型解析器，灵活处理特殊的 SQL 类型
+- **类型属性支持**：支持整数类型的显示宽度、浮点数类型的精度和小数位数
+- **现代化 API**：使用异步 API，支持动态模块导入
+- **自动命名空间**：Go/GORM/XORM 语言自动使用默认命名空间 `models`
+
+## 安装
+
+```bash
+pnpm add @chihqiang/sql-quicktype
+```
+
+## 使用方法
+
+### CLI 使用
+
+#### 从 SQL 字符串生成代码
+
+```bash
+# 生成 GORM 代码（默认）
+sql-quicktype sql -s "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255));"
+
+# 生成 TypeScript 代码
+sql-quicktype sql -s "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255));" -l typescript -o ./output
+
+# 生成 XORM 代码
+sql-quicktype sql -s "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255));" -l xorm -o ./output
+
+# 生成 Go 代码
+sql-quicktype sql -s "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255));" -l go -o ./output
+```
+
+#### 从数据库连接生成代码
+
+```bash
+# 从MySQL数据库生成代码（每个表生成单独的文件）
+sql-quicktype db -h localhost -P 3306 -u user -p password -d dbname -l typescript -o ./output
+```
+
+#### 高级选项
+
+```bash
+# 指定数据库方言
+sql-quicktype sql -s "CREATE TABLE users (id INT PRIMARY KEY);" -x postgres
+
+# 指定命名空间/包名
+sql-quicktype sql -s "CREATE TABLE users (id INT PRIMARY KEY);" -n models
+
+# 为每个表生成单独的文件（仅 sql 命令支持）
+sql-quicktype sql -s "CREATE TABLE users (id INT PRIMARY KEY);" -m multi -o ./output
+
+# 指定数据库名称
+sql-quicktype sql -s "CREATE TABLE users (id INT PRIMARY KEY);" --db-name my_database
+```
+
+### 编程 API 使用
+
+#### 基本用法
+
+```typescript
+import { parseSQL, GeneratorFactory } from '@chihqiang/sql-quicktype';
+
+// 解析 SQL
+const sql = `
+  CREATE TABLE users (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    name VARCHAR(255) NOT NULL,
+    email VARCHAR(255) UNIQUE,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+  ) COMMENT '用户表';
+`;
+
+const dbSchema = parseSQL(sql, { dialect: 'mysql', dbName: 'my_database' });
+
+// 生成 TypeScript 代码
+const generator = await GeneratorFactory.createGenerator('typescript');
+const code = generator.generateDatabase(dbSchema);
+console.log(code);
+```
+
+#### 生成不同语言的代码
+
+```typescript
+// TypeScript
+const tsGenerator = await GeneratorFactory.createGenerator('typescript');
+const tsCode = tsGenerator.generateDatabase(dbSchema);
+
+// Go
+const goGenerator = await GeneratorFactory.createGenerator('go');
+const goCode = goGenerator.generateDatabase(dbSchema);
+
+// GORM
+const gormGenerator = await GeneratorFactory.createGenerator('gorm');
+const gormCode = gormGenerator.generateDatabase(dbSchema);
+
+// XORM
+const xormGenerator = await GeneratorFactory.createGenerator('xorm');
+const xormCode = xormGenerator.generateDatabase(dbSchema);
+```
+
+#### 生成单个表的代码
+
+```typescript
+const generator = await GeneratorFactory.createGenerator('typescript');
+const tableCode = generator.generateTable(dbSchema.tables[0]);
+console.log(tableCode);
+```
+
+#### 使用自定义选项
+
+```typescript
+const generator = await GeneratorFactory.createGenerator('gorm', {
+  language: 'gorm',
+  namespace: 'models',
+  generateComments: true
+});
+
+const code = generator.generateDatabase(dbSchema);
+```
+
+#### 使用自定义类型解析器
+
+```typescript
+import { parseSQL, TypeResolver } from '@chihqiang/sql-quicktype';
+
+// 定义自定义类型解析器
+class CustomTypeResolver implements TypeResolver {
+  resolve(def: { dataType: string; length?: number | number[]; scale?: number; }) {
+    const dt = def.dataType.toLowerCase();
+    
+    // 自定义处理 'decimal' 类型
+    if (dt === 'decimal') {
+      return {
+        kind: 'decimal' as const,
+        precision: 19,
+        scale: 4
+      };
+    }
+    
+    // 对于其他类型，返回 null，让默认解析器处理
+    return null;
+  }
+}
+
+// 解析 SQL，传递自定义类型解析器
+const dbSchema = parseSQL(sql, {
+  dialect: 'mysql',
+  dbName: 'test_db',
+  typeResolvers: [new CustomTypeResolver()]
+});
+```
+
+#### 从文件读取 SQL
+
+```typescript
+import { ReaderFactory } from '@chihqiang/sql-quicktype';
+
+// 从文件读取
+const fileReader = ReaderFactory.createReader({
+  type: 'file',
+  source: './schema.sql'
+});
+const sql = await fileReader.read();
+
+// 从字符串读取
+const stringReader = ReaderFactory.createReader({
+  type: 'string',
+  source: 'CREATE TABLE users (id INT PRIMARY KEY);'
+});
+const sql = await stringReader.read();
+```
+
+#### 使用 generateCode 函数
+
+```typescript
+import { generateCode } from '@chihqiang/sql-quicktype';
+
+// 定义 SQL
+const sql = `
+  CREATE TABLE users (
+    id INT PRIMARY KEY AUTO_INCREMENT,
+    name VARCHAR(255) NOT NULL,
+    email VARCHAR(255) UNIQUE,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+  ) COMMENT '用户表';
+`;
+
+// 生成 TypeScript 代码
+const tsCode = await generateCode(sql, {
+  language: 'typescript',
+  namespace: 'models',
+  dialect: 'mysql',
+  dbName: 'my_database'
+});
+console.log(tsCode);
+
+// 生成 GORM 代码
+const gormCode = await generateCode(sql, {
+  language: 'gorm',
+  namespace: 'models',
+  dialect: 'mysql',
+  dbName: 'my_database'
+});
+console.log(gormCode);
+```
+
+## 支持的 SQL 类型
+
+### 基本类型
+
+| SQL 类型 | TypeScript | Go | 说明 |
+|---------|-----------|-----|------|
+| INT | number | int | 整数 |
+| BIGINT | number | int64 | 大整数 |
+| FLOAT | number | float32 | 浮点数 |
+| DOUBLE | number | float64 | 双精度浮点数 |
+| DECIMAL | number | float64 | 精确小数 |
+| VARCHAR | string | string | 可变长度字符串 |
+| TEXT | string | string | 文本 |
+| LONGTEXT | string | string | 长文本 |
+| BOOLEAN | boolean | bool | 布尔值 |
+| DATE | Date | string | 日期 |
+| DATETIME | Date | string | 日期时间 |
+| TIMESTAMP | Date | string | 时间戳 |
+| JSON | unknown | string | JSON 数据 |
+| ENUM | string literal union | string | 枚举 |
+
+### 特殊类型
+
+- **BLOB**：映射为 text/string
+- **TIME**：映射为 text/string
+- **YEAR**：映射为 int
+- **TINYINT**：长度为 1 时映射为 boolean，否则为 int
+- **SMALLINT**：映射为 int
+- **MEDIUMINT**：映射为 int
+
+## CLI 选项
+
+### sql 命令选项
+
+从 SQL 字符串生成代码。
+
+| 选项 | 简写 | 说明 | 默认值 |
+|------|------|------|--------|
+| --sql | -s | SQL 字符串（必需） | - |
+| --output | -o | 输出目录 | ./output |
+| --language | -l | 目标语言（go/gorm/typescript/xorm） | gorm |
+| --mode | -m | 输出模式（single/multi） | single |
+| --namespace | -n | 命名空间/包名（go/gorm/xorm 默认：models） | - |
+| --dialect | -x | SQL 方言（mysql/postgres/sqlite/sqlserver） | mysql |
+| --db-name | - | 数据库名称 | my_database |
+
+### db 命令选项
+
+从数据库连接生成代码（每个表生成单独的文件）。
+
+| 选项 | 简写 | 说明 | 默认值 |
+|------|------|------|--------|
+| --host | -h | MySQL数据库主机 | 127.0.0.1 |
+| --port | -P | MySQL数据库端口 | 3306 |
+| --user | -u | MySQL数据库用户名 | root |
+| --password | -p | MySQL数据库密码 | 空字符串 |
+| --database | -d | MySQL数据库名称 | test |
+| --output | -o | 输出目录 | ./output |
+| --language | -l | 目标语言（go/gorm/typescript/xorm） | gorm |
+| --namespace | -n | 命名空间/包名（go/gorm/xorm 默认：models） | - |
+| --dialect | -x | SQL 方言（mysql/postgres/sqlite/sqlserver） | mysql |
+| --db-name | - | 数据库名称 | my_database |
+
+## API 文档
+
+### parseSQL(sql, options)
+
+将 SQL 字符串解析为数据库 Schema。
+
+**参数：**
+
+- `sql` (string): SQL 字符串
+- `options` (SQLParserOptions): 解析器选项
+  - `dialect` (string): 数据库方言（mysql、postgres、sqlite、sqlserver）
+  - `dbName` (string): 数据库名称
+  - `strictMode` (boolean): 是否启用严格模式（默认：false）
+  - `ignoreComments` (boolean): 是否忽略注释（默认：false）
+  - `parseForeignKeys` (boolean): 是否解析外键约束（默认：true）
+  - `parseIndexes` (boolean): 是否解析索引（默认：true）
+  - `typeResolvers` (TypeResolver[]): 自定义类型解析器数组
+
+**返回值：**
+
+- `DatabaseSchema`: 数据库 Schema 对象
+
+### TypeResolver 接口
+
+自定义类型解析器接口，用于扩展默认的类型解析逻辑。
+
+**方法：**
+
+- `resolve(def)`: 解析 SQL 类型定义为 SQLType
+  - `def` (object): 列定义对象
+    - `dataType` (string): SQL 数据类型
+    - `length` (number | number[]): 长度信息
+    - `scale` (number): 小数位数
+    - `unsigned` (boolean): 是否无符号
+    - `generated` (boolean): 是否为生成列
+  - **返回值** (SQLType | null): 解析后的 SQLType 对象，返回 null 则使用默认解析器
+
+### generateCode(sql, options)
+
+从 SQL 模式生成指定语言的代码。
+
+**参数：**
+
+- `sql` (string): SQL 模式字符串
+- `options` (object): 生成选项
+  - `language` (string): 目标语言（typescript、go、gorm、xorm）
+  - `namespace` (string): 命名空间/包名（可选）
+  - `dialect` (string): SQL 方言（可选，默认：mysql）
+  - `dbName` (string): 数据库名称（可选，默认：my_database）
+
+**返回值：**
+
+- `Promise<string>`: 生成的代码字符串
+
+### GeneratorFactory.createGenerator(language, options)
+
+创建语言生成器实例。
+
+**参数：**
+
+- `language` (string): 目标语言（typescript、go、gorm、xorm）
+- `options` (Options): 生成器选项
+  - `language` (string): 目标语言
+  - `generateComments` (boolean): 是否生成注释
+  - `namespace` (string): 命名空间/包名
+
+**返回值：**
+
+- `Promise<AGenerator>`: 生成器实例的 Promise
+
+### ReaderFactory.createReader(options)
+
+创建读取器实例。
+
+**参数：**
+
+- `options` (ReaderOptions): 读取器选项
+  - `type` (string): 读取器类型（string、file）
+  - `source` (string): 数据源
+
+**返回值：**
+
+- `Reader`: 读取器实例
+
+## 示例
+
+### 示例 1：生成 TypeScript 接口
+
+输入 SQL：
+
+```sql
+CREATE TABLE users (
+  id INT PRIMARY KEY AUTO_INCREMENT,
+  name VARCHAR(255) NOT NULL COMMENT '用户名',
+  email VARCHAR(255) UNIQUE COMMENT '用户邮箱',
+  age INT COMMENT '用户年龄',
+  is_active BOOLEAN DEFAULT TRUE COMMENT '是否激活',
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间'
+) COMMENT '用户表';
+```
+
+输出 TypeScript：
+
+```typescript
+// Database: my_database
+// Dialect: mysql
+
+// users 表结构
+export interface Users {
+  id?: number
+  name: string; // 用户名
+  email: string; // 用户邮箱
+  age?: number; // 用户年龄
+  isActive?: boolean; // 是否激活
+  createdAt?: Date; // 创建时间
+}
+```
+
+### 示例 2：生成 GORM 模型
+
+输入 SQL：
+
+```sql
+CREATE TABLE users (
+  id INT PRIMARY KEY AUTO_INCREMENT,
+  name VARCHAR(255) NOT NULL,
+  email VARCHAR(255) UNIQUE
+);
+```
+
+输出 GORM：
+
+```go
+package models
+
+type Users struct {
+  ID    int    `gorm:"column:id;primaryKey;autoIncrement"`
+  Name  string `gorm:"column:name;not null"`
+  Email string `gorm:"column:email;unique"`
+}
+```
+
+### 示例 3：生成 XORM 模型
+
+输入 SQL：
+
+```sql
+CREATE TABLE users (
+  id INT PRIMARY KEY AUTO_INCREMENT,
+  name VARCHAR(255) NOT NULL
+);
+```
+
+输出 XORM：
+
+```go
+package models
+
+type Users struct {
+  ID   int    `xorm:"'id' pk autoincr"`
+  Name string `xorm:"'name' notnull"`
+}
+```
+
+## 贡献
+
+欢迎提交 [Issue](https://github.com/chihqiang/sql-quicktype/issues) 和 [Pull Request](https://github.com/chihqiang/sql-quicktype/pulls)！
+
+## 许可证
+
+[Apache-2.0](https://github.com/chihqiang/sql-quicktype/blob/main/LICENSE)