{"_id":"@aiweik/tableforge","name":"@aiweik/tableforge","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@aiweik/tableforge","version":"1.0.0","description":"A powerful MySQL table builder for Node.js with method chaining and complete data type support","main":"index.js","scripts":{"test":"node test/table-builder.test.js","example:basic":"node examples/basic-example.js","example:advanced":"node examples/advanced-example.js"},"keywords":["mysql","table-builder","database","schema","migration","mysql2","builder","sql","nodejs","tableforge"],"author":{"name":"Aiweik","email":"aiweik@example.com"},"license":"ISC","type":"commonjs","dependencies":{"mysql2":"^3.15.3"},"engines":{"node":">=14.0.0"},"repository":{"type":"git","url":"git+https://github.com/aiweik/tableforge.git"},"bugs":{"url":"https://github.com/aiweik/tableforge/issues"},"homepage":"https://github.com/aiweik/tableforge#readme","_id":"@aiweik/tableforge@1.0.0","_nodeVersion":"22.20.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-Dt0QhScuHCsOuFuvJau3XItwNIVuMFW5Tam5w2aedBTaLWwp/+Ek1gu2CEunbxfCiRH6TQF98je7y1ySn2KwLg==","shasum":"c85fb1c98e020981c82da9e1194d4766f91dda5c","tarball":"https://registry.npmjs.org/@aiweik/tableforge/-/tableforge-1.0.0.tgz","fileCount":7,"unpackedSize":42115,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDSvxto6qyhYvgj+0Trw+vfLum/J94oBt9hCw2jISTn3AiEAi3SEWC//8sUyPWBv53UKvLALgmNQcyfl5IDbZCATxUo="}]},"_npmUser":{"name":"aiweik","email":"1533458582@qq.com"},"directories":{},"maintainers":[{"name":"aiweik","email":"1533458582@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tableforge_1.0.0_1763829838606_0.1774771157244528"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-22T16:43:58.528Z","1.0.0":"2025-11-22T16:43:58.808Z","modified":"2025-11-22T16:43:59.097Z"},"maintainers":[{"name":"aiweik","email":"1533458582@qq.com"}],"description":"A powerful MySQL table builder for Node.js with method chaining and complete data type support","homepage":"https://github.com/aiweik/tableforge#readme","keywords":["mysql","table-builder","database","schema","migration","mysql2","builder","sql","nodejs","tableforge"],"repository":{"type":"git","url":"git+https://github.com/aiweik/tableforge.git"},"author":{"name":"Aiweik","email":"aiweik@example.com"},"bugs":{"url":"https://github.com/aiweik/tableforge/issues"},"license":"ISC","readme":"# TableForge - MySQL 表构建器\r\n\r\n[![NPM Version](https://img.shields.io/npm/v/@aiweik/tableforge.svg)](https://www.npmjs.com/package/@aiweik/tableforge)\r\n[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)\r\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org/)\r\n\r\n基于 Node.js + mysql2 实现的纯 JavaScript 动态建表工具，支持完整的 MySQL 数据类型、字段约束与链式调用。\r\n\r\n## ✨ 特性\r\n\r\n- 🚀 **链式调用** - 流畅的 API 设计，支持方法链式调用\r\n- 🎯 **类型安全** - 完整的 MySQL 数据类型支持，参数化配置\r\n- 🔧 **灵活配置** - 支持字段约束、索引、表选项等完整配置\r\n- 📝 **SQL 调试** - 提供 `toSQL()` 方法查看生成的 SQL 语句\r\n- 🛡️ **防护措施** - 字段名自动转义，防止 SQL 注入\r\n- 📦 **零依赖** - 仅依赖 mysql2，轻量级设计\r\n\r\n## 📦 安装\r\n\r\n```bash\r\nnpm install @aiweik/tableforge mysql2\r\n```\r\n\r\n## 🚀 快速开始\r\n\r\n```javascript\r\nconst TableBuilder = require('@aiweik/tableforge');\r\n\r\n// 创建数据库连接配置\r\nconst dbConfig = {\r\n    host: 'localhost',\r\n    user: 'root',\r\n    password: '123456',\r\n    database: 'myapp'\r\n};\r\n\r\n(async () => {\r\n    // 创建用户表\r\n    const usersTable = new TableBuilder('users', dbConfig);\r\n    \r\n    await usersTable\r\n        .addField('id', 'BIGINT', {\r\n            primaryKey: true,\r\n            autoIncrement: true,\r\n            notNull: true\r\n        })\r\n        .addField('username', 'VARCHAR(50)', {\r\n            notNull: true,\r\n            unique: true,\r\n            comment: '用户名'\r\n        })\r\n        .addField('email', 'VARCHAR(255)', {\r\n            notNull: true,\r\n            unique: true\r\n        })\r\n        .addField('status', \"ENUM('active', 'inactive')\", {\r\n            default: \"'active'\",\r\n            comment: '用户状态'\r\n        })\r\n        .addField('created_at', 'TIMESTAMP', {\r\n            default: 'CURRENT_TIMESTAMP'\r\n        })\r\n        .engine('InnoDB')\r\n        .charset('utf8mb4')\r\n        .create();\r\n\r\n    console.log('✅ 用户表创建成功！');\r\n})();\r\n```\r\n\r\n## 📋 核心模块\r\n\r\n### TableBuilder 类\r\n\r\n#### 构造函数\r\n\r\n```javascript\r\nnew TableBuilder(tableName, connectionConfig)\r\n```\r\n\r\n- `tableName` (string): 表名\r\n- `connectionConfig` (object): mysql2 连接配置\r\n\r\n#### 核心方法\r\n\r\n| 方法 | 参数 | 说明 | 返回值 |\r\n|------|------|------|--------|\r\n| `addField(name, type, options)` | 字段名, 类型, 选项 | 添加字段定义 | TableBuilder |\r\n| `addIndex(fields, options)` | 字段/字段数组, 选项 | 添加普通索引 | TableBuilder |\r\n| `addUniqueIndex(fields, options)` | 字段/字段数组, 选项 | 添加唯一索引 | TableBuilder |\r\n| `addFullTextIndex(fields, options)` | 字段/字段数组, 选项 | 添加全文索引 | TableBuilder |\r\n| `engine(name)` | 引擎名称 | 设置存储引擎 | TableBuilder |\r\n| `charset(name)` | 字符集名称 | 设置字符集 | TableBuilder |\r\n| `collation(name)` | 排序规则名称 | 设置排序规则 | TableBuilder |\r\n| `comment(text)` | 注释文本 | 设置表注释 | TableBuilder |\r\n| `ifNotExists(bool)` | 布尔值 | 是否添加 IF NOT EXISTS | TableBuilder |\r\n| `create()` | 无 | 执行建表操作 | Promise |\r\n| `toSQL()` | 无 | 获取生成的 SQL | string |\r\n| `exists()` | 无 | 检查表是否存在 | Promise<boolean> |\r\n| `drop()` | 无 | 删除表 | Promise |\r\n\r\n#### 字段选项 (options)\r\n\r\n```javascript\r\n{\r\n    primaryKey: false,      // 是否主键\r\n    autoIncrement: false,   // 是否自增\r\n    notNull: false,        // 是否非空\r\n    default: undefined,    // 默认值\r\n    unique: false,         // 是否唯一\r\n    unsigned: false,       // 是否无符号\r\n    zerofill: false,       // 是否零填充\r\n    comment: null          // 字段注释\r\n}\r\n```\r\n\r\n#### 索引选项 (options)\r\n\r\n```javascript\r\n{\r\n    name: 'idx_name',      // 索引名称\r\n    using: 'BTREE',        // 索引类型 (BTREE/HASH)\r\n    comment: '索引注释'    // 索引注释\r\n}\r\n```\r\n\r\n## 🎨 数据类型支持\r\n\r\n### 数值类型\r\n\r\n```javascript\r\nconst TableBuilder = require('@aiweik/tableforge');\r\n\r\n// 整数类型\r\n'TINYINT(3)'     // -128 ~ 127\r\n'SMALLINT(5)'    // -32768 ~ 32767\r\n'MEDIUMINT(8)'   // -8388608 ~ 8388607\r\n'INT(10)'        // 标准整数\r\n'BIGINT(20)'     // 大整数\r\n\r\n// 浮点类型\r\n'FLOAT(7,2)'     // 单精度浮点\r\n'DOUBLE(15,4)'   // 双精度浮点\r\n'DECIMAL(10,2)'  // 精确小数（推荐用于金额）\r\n\r\n// 位类型\r\n'BIT(8)'         // 位字段\r\n```\r\n\r\n### 日期时间类型\r\n\r\n```javascript\r\n'DATE'              // YYYY-MM-DD\r\n'TIME(3)'           // HH:MM:SS[.ffffff]\r\n'DATETIME(6)'       // 日期+时间\r\n'TIMESTAMP(3)'      // 时间戳（自动时区转换）\r\n'YEAR'              // 四位年份\r\n```\r\n\r\n### 字符串类型\r\n\r\n```javascript\r\n'CHAR(10)'          // 固定长度字符串\r\n'VARCHAR(255)'      // 可变长字符串\r\n'TINYTEXT'          // 短文本 (255 字节)\r\n'TEXT'              // 文本 (64KB)\r\n'MEDIUMTEXT'        // 中等文本 (16MB)\r\n'LONGTEXT'          // 长文本 (4GB)\r\n```\r\n\r\n### 特殊类型\r\n\r\n```javascript\r\n'JSON'              // JSON 文档 (MySQL 5.7+)\r\n'ENUM(\"a\",\"b\",\"c\")' // 枚举（单选）\r\n'SET(\"x\",\"y\",\"z\")'  // 集合（多选）\r\n'POINT'             // 空间点\r\n'GEOMETRY'          // 几何图形\r\n```\r\n\r\n## 💡 高级用法示例\r\n\r\n### 复杂表创建\r\n\r\n```javascript\r\nconst ordersTable = new TableBuilder('orders', dbConfig);\r\n\r\nawait ordersTable\r\n    // 订单基础信息\r\n    .addField('id', 'BIGINT', {\r\n        primaryKey: true,\r\n        autoIncrement: true,\r\n        notNull: true,\r\n        unsigned: true\r\n    })\r\n    .addField('order_no', 'VARCHAR(32)', {\r\n        notNull: true,\r\n        unique: true,\r\n        comment: '订单唯一编号'\r\n    })\r\n    .addField('user_id', 'BIGINT', {\r\n        notNull: true,\r\n        unsigned: true,\r\n        comment: '用户ID'\r\n    })\r\n    .addField('total_amount', 'DECIMAL(12,2)', {\r\n        notNull: true,\r\n        unsigned: true,\r\n        comment: '订单总金额'\r\n    })\r\n    // 订单状态\r\n    .addField('status', \"ENUM('pending','paid','shipped','delivered','cancelled')\", {\r\n        notNull: true,\r\n        default: \"'pending'\",\r\n        comment: '订单状态'\r\n    })\r\n    // 地址和标签\r\n    .addField('shipping_address', 'JSON', {\r\n        comment: '收货地址JSON'\r\n    })\r\n    .addField('tags', \"SET('urgent','gift','fragile','express')\", {\r\n        comment: '订单标签'\r\n    })\r\n    // 时间字段\r\n    .addField('created_at', 'DATETIME(3)', {\r\n        notNull: true,\r\n        default: 'CURRENT_TIMESTAMP(3)'\r\n    })\r\n    // 添加索引\r\n    .addIndex('user_id', {\r\n        name: 'idx_user_id',\r\n        comment: '用户ID索引'\r\n    })\r\n    .addIndex(['status', 'created_at'], {\r\n        name: 'idx_status_date'\r\n    })\r\n    .addFullTextIndex(['shipping_address'], {\r\n        name: 'ft_address'\r\n    })\r\n    // 表选项\r\n    .engine('InnoDB')\r\n    .charset('utf8mb4')\r\n    .collation('utf8mb4_unicode_ci')\r\n    .comment('订单信息表')\r\n    .create();\r\n```\r\n\r\n### 调试和预览\r\n\r\n```javascript\r\nconst table = new TableBuilder('debug_table', dbConfig);\r\n\r\n// 添加字段...\r\ntable.addField('id', 'BIGINT', { primaryKey: true });\r\n\r\n// 预览生成的 SQL\r\nconsole.log('生成的SQL:');\r\nconsole.log(table.toSQL());\r\n\r\n// 检查表是否存在\r\nconst exists = await table.exists();\r\nconsole.log('表是否存在:', exists);\r\n\r\n// 仅在表不存在时创建\r\nif (!exists) {\r\n    await table.create();\r\n}\r\n```\r\n\r\n### 错误处理\r\n\r\n```javascript\r\ntry {\r\n    const table = new TableBuilder('users', dbConfig);\r\n    await table\r\n        .addField('id', 'BIGINT', { primaryKey: true })\r\n        .create();\r\n    console.log('✅ 表创建成功');\r\n} catch (error) {\r\n    if (error.message.includes('already exists')) {\r\n        console.log('⚠️ 表已存在');\r\n    } else {\r\n        console.error('❌ 创建失败:', error.message);\r\n    }\r\n}\r\n```\r\n\r\n## ⚠️ 重要注意事项\r\n\r\n### 默认值处理\r\n\r\n```javascript\r\n// 字符串默认值需要加引号\r\ndefault: \"'active'\"    \r\n// 数字直接传值\r\ndefault: 0             \r\n// SQL 函数作为字符串\r\ndefault: 'CURRENT_TIMESTAMP'\r\n```\r\n\r\n### 主键约束\r\n\r\n- 自增字段必须是整数类型\r\n- 自增字段自动成为主键\r\n- 支持多字段联合主键\r\n\r\n### 安全性\r\n\r\n- 字段名自动使用反引号转义\r\n- ENUM/SET 值自动转义单引号\r\n- 默认值由用户控制，请勿直接拼接用户输入\r\n\r\n### 生产环境建议\r\n\r\n- 适用于开发、测试或轻量级脚本\r\n- 生产环境推荐使用专业迁移工具：\r\n  - [Knex.js](https://knexjs.org/)\r\n  - [Sequelize CLI](https://sequelize.org/docs/v6/other-topics/migrations/)\r\n  - [TypeORM Migrations](https://typeorm.io/migrations)\r\n\r\n## 🧪 测试\r\n\r\n```bash\r\n# 运行测试示例\r\nnode examples/basic-example.js\r\n\r\n# 运行高级示例\r\nnode examples/advanced-example.js\r\n```\r\n\r\n## 📁 项目结构\r\n\r\n```\r\nTableForge/\r\n├── lib/\r\n│   ├── TableBuilder.js      # 表构建器核心类\r\n│   └── types.js            # MySQL 类型常量（可选）\r\n├── examples/\r\n│   ├── basic-example.js    # 基础用法示例\r\n│   └── advanced-example.js # 高级用法示例\r\n├── test/\r\n│   └── table-builder.test.js # 单元测试\r\n├── index.js                # 主入口文件\r\n├── package.json           # 项目配置\r\n├── README.md             # 中文文档\r\n└── README_EN.md          # 英文文档\r\n```\r\n\r\n## 🔗 相关链接\r\n\r\n- [NPM 包地址](https://www.npmjs.com/package/@aiweik/tableforge)\r\n- [MySQL 官方文档](https://dev.mysql.com/doc/)\r\n- [mysql2 驱动文档](https://github.com/sidorares/node-mysql2)\r\n\r\n## 📄 许可证\r\n\r\n[ISC License](LICENSE)\r\n\r\n## 🤝 贡献\r\n\r\n欢迎提交 Issue 和 Pull Request！\r\n\r\n---\r\n\r\n**TableForge** - 让 MySQL 表构建变得简单优雅 ✨","readmeFilename":"README.md","_rev":"1-ebd75236fa084f917777d214821ebb93"}