neopg 1.0.0 → 2.0.0

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,130 @@ 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('数据库结构已同步！')
+```
+
+---
+
+### 📂 自动加载模型
+
+NeoPG 支持扫描指定目录并自动注册所有模型，无需手动逐个引入。
+
+**加载规则：**
+*   仅加载 `.js` 和 `.mjs` 后缀的文件。
+*   **忽略**以 `_` 开头的文件（可用作目录内的共享工具或基类）。
+*   **忽略**以 `!` 开头的文件（可用作临时禁用的模型）。
+
+```javascript
+const db = new NeoPG(config)
+
+// 自动加载 ./models 目录下的所有模型
+// 注意：这是一个异步方法，因为它兼容 ESM (.mjs) 的动态导入
+await db.loadModels('./models')
+
+// 加载完成后即可同步或使用
+await db.sync()
 ```
 
 ---
@@ -160,16 +261,13 @@ const page2 = await db.model('User').page(2, 20).find(); // 第 2 页，每页 2
 
 ```javascript
 await db.model('User')
-  // 对象风格 (自动处理 AND)
   .where({ 
     age: 18, 
     status: 'active' 
   })
-  // 操作符风格
   .where('create_time', '>', 1600000000)
-  // SQL 片段风格 (强大且灵活！)
   .where('id IS NOT NULL')
-  .find();
+  .find()
 ```
 
 ### 结合模板字符串的复杂查询
@@ -180,9 +278,9 @@ await db.model('User')
 // db.sql 是原生的 postgres 实例
 const { sql } = db; 
 
+// 通过模板字符串安全地注入参数
 await db.model('User')
   .where({ status: 'active' })
-  // 通过模板字符串安全地注入参数
   .where(sql`age > ${20} AND email LIKE ${'%@gmail.com'}`)
   .find();
 ```

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,130 @@ 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
+
+Sync the table structure to the database based on registered models.
 
-// 2. Sync Table Structure (DDL)
+```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!')
+```
+
+---
+
+### 📂 Auto-loading Models
+
+Instead of manually importing and defining each model, you can load all models from a directory.
+
+**Rules:**
+*   Only `.js` and `.mjs` files are loaded.
+*   Files starting with `_` are ignored (useful for utils/helpers).
+*   Files starting with `!` are ignored (useful for disabled models).
+
+```javascript
+const db = new NeoPG(config)
+
+// Load all models from the './models' directory
+// This is asynchronous because it supports .mjs dynamic imports
+await db.loadModels('./models')
+
+// Now you can sync and use them
+await db.sync()
 ```
 
 ---
@@ -159,16 +260,13 @@ const page2 = await db.model('User').page(2, 20).find(); // Page 2, Size 20
 
 ```javascript
 await db.model('User')
-  // Object style (AND logic)
   .where({ 
     age: 18, 
     status: 'active' 
   })
-  // Operator style
   .where('create_time', '>', 1600000000)
-  // SQL Fragment style (Powerful!)
   .where('id IS NOT NULL')
-  .find();
+  .find()
 ```
 
 ### Complex Where with Template Literals
@@ -221,14 +319,14 @@ const stats = await db.model('User')
 const newUser = await db.model('User').insert({
   username: 'neo',
   email: 'neo@matrix.com'
-});
+})
 // ID and Timestamps are automatically generated if configured in Schema
 
 // Insert multiple (Batch)
 await db.model('User').insert([
   { username: 'a' }, 
   { username: 'b' }
-]);
+])
 ```
 
 ### Update
@@ -305,16 +403,15 @@ const result = await db.transaction(async (tx) => {
   const user = await tx.model('User').insert({ username: 'alice' });
   
   // 2. Read operation within transaction
-  const count = await tx.model('User').count();
+  const count = await tx.model('User').count()
   
   // 3. Throwing an error will automatically ROLLBACK
   if (count > 100) {
-    throw new Error('Limit reached'); 
+    throw new Error('Limit reached')
   }
   
-  return user;
-});
-// Automatically COMMITTED here if no error
+  return user
+})
 ```
 
 ### Using Raw Postgres Transaction
@@ -323,7 +420,7 @@ const result = await db.transaction(async (tx) => {
 await db.sql.begin(async (sql) => {
   // sql is the transaction connection
   await sql`INSERT INTO users (name) VALUES ('bob')`;
-});
+})
 ```
 
 ---

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

@@ -7,6 +7,10 @@ const TransactionScope = require('./TransactionScope.js')
 const ModelChain = require('./ModelChain.js')
 const dataTypes = require('./dataTypes.js')
 
+const path = require('node:path')
+const fs = require('node:fs')
+const { pathToFileURL } = require('node:url')
+
 class NeoPG {
   constructor(config) {
     this.driver = postgres(config)
@@ -33,7 +37,7 @@ class NeoPG {
 
   // --- 注册 ---
 
-  add(input) {
+  add(input, is_reset=false) {
     let ModelClass
 
     if (typeof input === 'function') {
@@ -43,10 +47,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 +69,10 @@ class NeoPG {
     return this.add(model)
   }
 
+  set(model) {
+    return this.add(model, true)
+  }
+
   // --- 事务 ---
   async transaction(callback) {
     return await this.driver.begin(async (trxSql) => {
@@ -126,6 +140,64 @@ class NeoPG {
   async close() {
     await this.driver.end()
   }
+
+  /**
+   * 自动加载指定目录下的模型文件
+   * 规则：
+   * 1. 只加载 .js 和 .mjs 文件
+   * 2. 跳过以 '_' 开头的文件 (视为内部共享模块)
+   * 3. 跳过以 '!' 开头的文件 (视为保留或禁用文件)
+   * 
+   * @param {string} dirPath - 目录路径 (相对 process.cwd() 或绝对路径)
+   */
+  async loadModels(dirPath) {
+    // 解析绝对路径
+    const absPath = path.isAbsolute(dirPath) 
+      ? dirPath 
+      : path.resolve(process.cwd(), dirPath)
+
+    if (!fs.existsSync(absPath)) {
+      throw new Error(`[NeoPG] Models directory not found: ${absPath}`)
+    }
+
+    const files = fs.readdirSync(absPath)
+
+    for (const file of files) {
+      // 过滤规则
+      if (file.startsWith('_') || file.startsWith('!')) continue
+      
+      const ext = path.extname(file)
+
+      if (ext !== '.js' && ext !== '.mjs') continue
+
+      const fullFilePath = path.join(absPath, file)
+      let modelExport
+
+      try {
+        if (ext === '.mjs') {
+          // 处理 ESM 动态导入
+          // Windows 下 import() 需要 file:// 协议路径
+          const fileUrl = pathToFileURL(fullFilePath).href
+          const imported = await import(fileUrl)
+          modelExport = imported.default
+        } else {
+          // 处理 CommonJS
+          modelExport = require(fullFilePath)
+        }
+
+        // 注册模型 (如果导出为空或不是合法对象/类，add 方法内部会抛错或处理)
+        if (modelExport) {
+          this.add(modelExport)
+        }
+      } catch (err) {
+        console.error(`[NeoPG] Failed to load model: ${file}`)
+        throw err
+      }
+    }
+
+    return this
+  }
+
 }
 
 NeoPG.dataTypes = dataTypes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neopg",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "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"

package/test/test-db.js

@@ -154,12 +154,21 @@ db.add(User);
                 {
                   username: 'Neo',
                   email: '123@w.com',
+                  sex: 1,
                   level: Math.floor((Math.random() * 105))
                 },
                 {
                   username: 'PG',
                   email: '1234@w.com',
+                  sex: 2,
                   level: Math.floor((Math.random() * 100))
+                },
+
+                {
+                  username: 'NPG',
+                  email: '1235@w.com',
+                  sex: 3,
+                  level: 3
                 }
             ])
     )
@@ -179,6 +188,12 @@ db.add(User);
     let result = await tx.model('User').where(tx.sql`level > 10`).returning('*').update(data)
     console.log(result)
 
+    let sex = 3
+    console.log(
+      'test condition or',
+      await tx.model('User').where(tx.sql`(sex = ${sex} or level > 10)`).select(['id', 'level', 'username', 'sex']).find()
+    )
+
     console.log(
       'test avg',
       await tx.model('User').avg('level')