neopg 1.0.0 → 1.0.1

package/README.cn.md

@@ -64,7 +64,7 @@ await db.close();
 创建一个模型文件（例如 `models/User.js`）。您的类应当继承自 `NeoPG.ModelChain`。
 
 ```javascript
-const { ModelChain, dataTypes } = require('neopg');
+const { ModelChain, dataTypes } = require('neopg')
 
 class User extends ModelChain {
   static schema = {
@@ -106,29 +106,108 @@ class User extends ModelChain {
     index: ['email', 'age'],
     // 唯一索引定义
     unique: ['username']
-  };
+  }
 }
 
-module.exports = User;
+module.exports = User
+```
+
+## 🛠 CLI 模型生成器
+
+NeoPG 内置了一个 CLI 工具，可以快速生成带有样板代码的模型文件。
+
+### 用法
+
+通过 `npx` 直接运行（无需全局安装）：
+
+```bash
+npx neopg-model [选项] [模型名称...]
+```
+
+### 选项
+
+*   `--dir=<path>`: 指定输出目录（默认：`./model`）。
+
+### 示例
+
+**1. 基础生成**
+```bash
+npx neopg-model user
+# 创建文件: ./model/user.js
+# 类名: User
+# 表名: user
+```
+
+**2. 命名规范（连字符处理）**
+输入带连字符的名称，NeoPG 会自动将类名转换为 **大驼峰（CamelCase）**，将表名转换为 **下划线（snake_case）**。
+
+```bash
+npx neopg-model user-log
+# 创建文件: ./model/user-log.js
+# 类名: UserLog
+# 表名: user_log
+```
+
+**3. 批量生成与自定义目录**
+```bash
+npx neopg-model --dir=./src/models product order-item
+# 创建:
+#   ./src/models/product.js
+#   ./src/models/order-item.js
+```
+
+**4. ES Modules (.mjs)**
+如果在名称后加上 `.mjs` 后缀，将生成 ESM 语法（`export default`）的文件。
+```bash
+npx neopg-model config.mjs
 ```
 
 ---
 
 ## ⚙️ 注册与同步
 
-初始化 NeoPG 并注册您的模型。您还可以将表结构定义同步到数据库中。
+初始化 NeoPG 并注册您的模型。您可以使用类（Class）或配置对象（Object）来定义模型。
+
+### 注册模型
+
+NeoPG 提供了三种注册方法以应对不同场景：
+
+*   **`define(model)`**：标准注册方法。如果同名模型已存在，会抛出错误（`modelName conflict`），防止意外覆盖。
+*   **`add(model)`**：同 `define`，行为一致。
+*   **`set(model)`**：**强制覆盖/重置**。如果模型已存在，则更新其定义。适用于热重载或动态 Schema 场景。
 
 ```javascript
-const User = require('./models/User');
+const User = require('./models/User')
+
+// 1. 标准注册 (安全模式)
+// 如果 'User' 已经被注册过，此处会报错
+db.define(User)
+
+// 2. 强制覆盖 (重置模式)
+// 即使 'User' 已存在，也会使用新的定义覆盖它
+db.set(User)
+
+// 3. 使用纯对象注册 (快速原型)
+db.define({
+  tableName: 'logs',
+  column: {
+    message: 'string',
+    level: 'int'
+  }
+})
 
-// 1. 注册模型
-db.define(User);
+```
+
+### 同步数据库
 
-// 2. 同步表结构 (DDL)
+根据已注册的模型同步数据库表结构。
+
+```javascript
+// 同步表结构 (DDL)
 // options: { force: true } 开启强制模式，会删除 Schema 中未定义的字段，请谨慎使用
-await db.sync({ force: false }); 
+await db.sync({ force: false })
 
-console.log('数据库结构已同步！');
+console.log('数据库结构已同步！')
 ```
 
 ---

package/README.md

@@ -54,7 +54,7 @@ const db = new NeoPG(config);
 ### Close Connection
 
 ```javascript
-await db.close();
+await db.close()
 ```
 
 ---
@@ -64,7 +64,7 @@ await db.close();
 Create a model file (e.g., `models/User.js`). Your class should extend `NeoPG.ModelChain`.
 
 ```javascript
-const { ModelChain, dataTypes } = require('neopg');
+const { ModelChain, dataTypes } = require('neopg')
 
 class User extends ModelChain {
   static schema = {
@@ -105,29 +105,108 @@ class User extends ModelChain {
     // Indexes
     index: ['email', 'age'],
     unique: ['username']
-  };
+  }
 }
 
-module.exports = User;
+module.exports = User
+```
+
+## 🛠 CLI Model Generator
+
+NeoPG includes a built-in CLI tool to quickly generate model files with boilerplate code.
+
+### Usage
+
+Run via `npx` (no global installation required):
+
+```bash
+npx neopg-model [options] [model_names...]
+```
+
+### Options
+
+*   `--dir=<path>`: Specify the output directory (default: `./model`).
+
+### Examples
+
+**1. Basic Generation**
+```bash
+npx neopg-model user
+# Creates: ./model/user.js
+# Class: User
+# Table: user
+```
+
+**2. Naming Convention (Hyphenated)**
+NeoPG automatically converts hyphenated names to **CamelCase** for the class and **snake_case** for the table.
+
+```bash
+npx neopg-model user-log
+# Creates: ./model/user-log.js
+# Class: UserLog
+# Table: user_log
+```
+
+**3. Multiple Models & Custom Directory**
+```bash
+npx neopg-model --dir=./src/models product order-item
+# Creates:
+#   ./src/models/product.js
+#   ./src/models/order-item.js
+```
+
+**4. ES Modules (.mjs)**
+If you suffix the name with `.mjs`, it generates ESM syntax (`export default`).
+```bash
+npx neopg-model config.mjs
 ```
 
 ---
 
 ## ⚙️ Registration & Sync
 
-Initialize NeoPG and register your models. You can also sync the table structure to the database.
+Initialize NeoPG and register your models. You can define models using classes or configuration objects.
+
+### Registering Models
+
+NeoPG provides three methods for registration:
+
+*   **`define(model)`**: The standard method. Throws an error if a model with the same name already exists.
+*   **`add(model)`**: Alias for `define`.
+*   **`set(model)`**: **Overwrites** the existing model if the name conflicts. Useful for hot-reloading or dynamic schema updates.
 
 ```javascript
-const User = require('./models/User');
+const User = require('./models/User')
+
+// 1. Standard Registration (Safe)
+// Will throw error: "[NeoPG] modelName conflict: User" if registered twice
+db.define(User)
+
+// 2. Force Overwrite (Reset)
+// Updates the definition for 'User' even if it exists
+db.set(User)
+
+// 3. Register using a plain object (Quick prototype)
+db.define({
+  tableName: 'logs',
+  column: {
+    message: 'string',
+    level: 'int'
+  }
+})
 
-// 1. Register Model
-db.define(User);
+```
+
+### Syncing Database
 
-// 2. Sync Table Structure (DDL)
+Sync the table structure to the database based on registered models.
+
+```javascript
+// Sync Table Structure (DDL)
 // options: { force: true } will drop columns not defined in schema
-await db.sync({ force: false }); 
+await db.sync({ force: false })
 
-console.log('Database synced!');
+console.log('Database synced!')
 ```
 
 ---

package/bin/neopg-model.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const process = require('node:process');
+
+// JS 关键字列表，防止类名冲突
+const JS_KEYWORDS = new Set([
+  'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 
+  'do', 'else', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 
+  'in', 'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 
+  'try', 'typeof', 'var', 'void', 'while', 'with', 'yield', 'let', 'static', 'enum', 'await', 
+  'implements', 'interface', 'package', 'private', 'protected', 'public', 'arguments', 'eval'
+]);
+
+// 帮助信息
+function showHelp() {
+  console.log(`
+Usage: neopg-model [options] [name1] [name2] ...
+
+Options:
+  --dir=<path>    指定模型文件保存目录 (默认: ./model)
+
+Example:
+  neopg-model user-log order_info
+  neopg-model --dir=./src/models Product
+  `);
+}
+
+// 解析参数
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const config = {
+    dir: './model',
+    names: []
+  };
+
+  if (args.length === 0) {
+    showHelp();
+    process.exit(0);
+  }
+
+  for (const arg of args) {
+    if (arg.startsWith('--dir=')) {
+      config.dir = arg.split('=')[1];
+    } else if (!arg.startsWith('-')) {
+      config.names.push(arg);
+    }
+  }
+
+  return config;
+}
+
+// 验证名称合法性: 字母开头，只允许字母、数字、_、-
+function isValidName(name) {
+  return /^[a-zA-Z][a-zA-Z0-9_-]*$/.test(name);
+}
+
+// 处理命名规则
+function processName(inputName) {
+  // 1. 移除扩展名，但记录是否是 .mjs
+  let isMjs = inputName.endsWith('.mjs');
+  const cleanName = inputName.replace(/(\.js|\.mjs)$/, '');
+
+  // 2. 验证合法性
+  if (!isValidName(cleanName)) {
+    console.error(`\x1b[31m[Error]\x1b[0m 名称 "${inputName}" 不合法。必须以字母开头，只能包含字母、数字、下划线和连字符。`);
+    return null;
+  }
+
+  // 3. 生成 tableName: 全小写，- 替换为 _
+  const tableName = cleanName.toLowerCase().replace(/-/g, '_');
+
+  // 4. 生成 modelName:
+  //    - 去掉 '-'
+  //    - '-' 后面的字母大写 (驼峰)
+  //    - '_' 保留，_ 后面的字母不做特殊处理
+  //    - 首字母大写
+  const parts = cleanName.split('-');
+  const modelName = parts.map((p, index) => {
+    // 每一部分的首字母大写
+    return p.charAt(0).toUpperCase() + p.slice(1);
+  }).join(''); // 直接连接，去掉了 -
+
+  // 检查关键字
+  if (JS_KEYWORDS.has(modelName)) {
+    console.warn(`\x1b[33m[Warning]\x1b[0m 生成的类名 "${modelName}" 是 JavaScript 关键字，建议修改名称。`);
+  }
+
+  return {
+    raw: cleanName,
+    isMjs,
+    tableName,
+    modelName
+  };
+}
+
+// 生成 CommonJS 模板
+function generateCJS(info) {
+  return `'use strict'\n\nconst { dataTypes, ModelChain } = require('neopg')
+
+class ${info.modelName} extends ModelChain {
+  static schema = {
+    tableName: '${info.tableName}',
+    modelName: '${info.modelName}',
+    primaryKey: 'id',
+    column: {
+      id: {
+        type: dataTypes.ID
+      },
+      name: {
+        type: dataTypes.STRING(30),
+        default: ''
+      }
+    },
+    index: [],
+    unique: []
+  }
+}
+
+module.exports = ${info.modelName}
+`;
+}
+
+// 生成 ESM 模板
+function generateESM(info) {
+  return `'use strict'\n\nimport { dataTypes, ModelChain } from 'neopg'
+
+class ${info.modelName} extends ModelChain {
+  static schema = {
+    tableName: '${info.tableName}',
+    modelName: '${info.modelName}',
+    primaryKey: 'id',
+    column: {
+      id: {
+        type: dataTypes.ID
+      },
+      name: {
+        type: dataTypes.STRING(30),
+        default: ''
+      }
+    },
+    index: [],
+    unique: []
+  }
+}
+
+export default ${info.modelName}
+`;
+}
+
+// 主逻辑
+function main() {
+  const config = parseArgs();
+  
+  // 1. 确保目录存在
+  const targetDir = path.resolve(process.cwd(), config.dir);
+  if (!fs.existsSync(targetDir)) {
+    try {
+      fs.mkdirSync(targetDir, { recursive: true });
+      console.log(`\x1b[32m[Info]\x1b[0m 创建目录: ${config.dir}`);
+    } catch (err) {
+      console.error(`\x1b[31m[Error]\x1b[0m 无法创建目录 ${targetDir}: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  if (config.names.length === 0) {
+    console.error('\x1b[31m[Error]\x1b[0m 未指定模型名称。');
+    process.exit(1);
+  }
+
+  for (const name of config.names) {
+    const info = processName(name);
+    if (!info) continue;
+
+    const ext = info.isMjs ? '.mjs' : '.js';
+    const fileName = info.raw + ext;
+    const filePath = path.join(targetDir, fileName);
+
+    // 检查冲突：
+    // 1. 检查完全同名的文件
+    if (fs.existsSync(filePath)) {
+      console.error(`\x1b[31m[Skip]\x1b[0m 文件已存在: ${fileName}`);
+      continue;
+    }
+
+    // 2. 检查 ModelName 命名的文件 (可选，防止 user.js 和 User.js 在某些系统混淆)
+    const modelNamePath = path.join(targetDir, info.modelName + ext);
+    if (fs.existsSync(modelNamePath) && modelNamePath.toLowerCase() !== filePath.toLowerCase()) {
+       console.warn(`\x1b[33m[Warning]\x1b[0m 存在同类名文件: ${info.modelName}${ext}，可能会导致混淆。`);
+    }
+
+    const content = info.isMjs ? generateESM(info) : generateCJS(info);
+
+    try {
+      fs.writeFileSync(filePath, content, 'utf8');
+      console.log(`\x1b[32m[Success]\x1b[0m 已创建模型: ${path.join(config.dir, fileName)} (Table: ${info.tableName}, Class: ${info.modelName})`);
+    } catch (err) {
+      console.error(`\x1b[31m[Error]\x1b[0m 写入文件失败 ${fileName}: ${err.message}`);
+    }
+  }
+}
+
+main();

package/lib/NeoPG.js

@@ -33,7 +33,7 @@ class NeoPG {
 
   // --- 注册 ---
 
-  add(input) {
+  add(input, is_reset=false) {
     let ModelClass
 
     if (typeof input === 'function') {
@@ -43,10 +43,16 @@ class NeoPG {
     }
 
     const rawSchema = ModelClass.schema
+
     if (!rawSchema) throw new Error(`[NeoPG] Missing static schema for ${ModelClass.name}`)
 
     const def = new ModelDef(rawSchema)
 
+    //已经存在又不是更新，则报错
+    if (!is_reset && this.registry.has(def.modelName)) {
+      throw new Error(`[NeoPG] modelName conflict: ${def.modelName}`)
+    }
+
     this.registry.set(def.modelName, {
       Class: ModelClass,
       def: def
@@ -59,6 +65,10 @@ class NeoPG {
     return this.add(model)
   }
 
+  set(model) {
+    return this.add(model, true)
+  }
+
   // --- 事务 ---
   async transaction(callback) {
     return await this.driver.begin(async (trxSql) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neopg",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "orm for postgres",
   "keywords": [
     "neopg",
@@ -18,6 +18,9 @@
   "bugs": {
     "url": "https://github.com/master-genius/neopg/issues"
   },
+  "bin": {
+    "neopg-model": "./bin/neopg-model.js"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/master-genius/neopg.git"