neopg 0.0.1 → 1.0.1

package/README.md

@@ -0,0 +1,415 @@
+![](./images/neopg.png)
+
+# NeoPG
+
+### The Next Generation PostgreSQL ORM for Node.js
+
+**NeoPG** is a high-performance, zero-dependency ORM built directly on top of [postgres.js](https://github.com/porsager/postgres) — the fastest PostgreSQL client for Node.js.
+
+It bridges the gap between the developer experience (DX) of a chainable Query Builder and the raw performance of native SQL Template Literals.
+
+### [🪭 中文文档 ☯️](./README.cn.md)
+
+## 🚀 Key Features
+
+*   **Powered by [postgres.js](https://github.com/porsager/postgres)**: Inherits the incredible speed and stability of the fastest PG client.
+*   **Zero Dependencies**: The core driver is vendored and optimized internally. No heavy dependency tree.
+*   **Hybrid API**: Enjoy the ease of **Chainable/Fluent APIs** (like `.where().select()`) combined with the power of **Tagged Template Literals**.
+*   **Performance First**: Zero string concatenation logic. All queries are compiled into efficient fragments and executed natively.
+*   **Auto Schema Sync**: define your models in code, and NeoPG syncs the table structure, indices, and foreign keys automatically.
+*   **Type Smart**: Automatic type casting for aggregations (`sum`, `avg` returns numbers, not strings) and JSON handling.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install neopg
+```
+
+---
+
+## 🔌 Initialization
+
+### Connect to Database
+
+```javascript
+const NeoPG = require('neopg');
+
+const config = {
+  host: 'localhost',
+  port: 5432,
+  database: 'my_db',
+  user: 'postgres',
+  password: 'password',
+  max: 10,             // Connection pool size
+  idle_timeout: 30,    // Idle connection timeout in seconds
+  debug: false,        // Enable query logging
+  schema: 'public'     // Default schema
+};
+
+const db = new NeoPG(config);
+```
+
+### Close Connection
+
+```javascript
+await db.close()
+```
+
+---
+
+## 📝 Defining a Model
+
+Create a model file (e.g., `models/User.js`). Your class should extend `NeoPG.ModelChain`.
+
+```javascript
+const { ModelChain, dataTypes } = require('neopg')
+
+class User extends ModelChain {
+  static schema = {
+    tableName: 'users',
+    modelName: 'User', // Optional, defaults to tableName
+    primaryKey: 'id',
+    
+    // Auto-sync table structure based on this definition
+    column: {
+      id: { 
+        type: dataTypes.ID, // Auto-generates Snowflake-like ID 
+      },
+      username: { 
+        type: dataTypes.STRING(100), 
+        required: true 
+      },
+      email: { 
+        type: dataTypes.STRING(255), 
+        required: true 
+      },
+      age: { 
+        type: dataTypes.INT, 
+        default: 18 
+      },
+      meta: { 
+        type: dataTypes.JSONB 
+      },
+      created_at: {
+        type: dataTypes.BIGINT,
+        timestamp: 'insert' // Auto-fill on insert
+      },
+      updated_at: {
+        type: dataTypes.BIGINT,
+        timestamp: 'update' // Auto-fill on insert & update
+      }
+    },
+
+    // Indexes
+    index: ['email', 'age'],
+    unique: ['username']
+  }
+}
+
+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 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')
+
+// 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'
+  }
+})
+
+```
+
+### Syncing Database
+
+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 })
+
+console.log('Database synced!')
+```
+
+---
+
+## 🔍 Querying
+
+NeoPG provides a fluent, chainable API that feels natural to use.
+
+### Basic Find
+
+```javascript
+// Get all users
+const users = await db.model('User').find();
+
+// Select specific columns
+const users = await db.model('User')
+  .select('id, username')
+  .limit(10)
+  .find();
+
+// Get a single record
+const user = await db.model('User').where({ id: '123' }).get();
+
+// Pagination
+const page2 = await db.model('User').page(2, 20).find(); // Page 2, Size 20
+```
+
+### Chained Where
+
+```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();
+```
+
+### Complex Where with Template Literals
+
+This is where NeoPG shines. You can mix raw SQL fragments safely using the `sql` tag from the context.
+
+```javascript
+// db.sql is the native postgres instance
+const { sql } = db; 
+
+await db.model('User')
+  .where({ status: 'active' })
+  // Safe parameter injection via Template Literals
+  .where(sql`age > ${20} AND email LIKE ${'%@gmail.com'}`)
+  .find();
+```
+
+---
+
+## 📊 Aggregation
+
+NeoPG handles type casting automatically (e.g., converting PostgreSQL `count` string results to Javascript Numbers).
+
+```javascript
+// Count
+const total = await db.model('User').where({ age: 18 }).count();
+
+// Max / Min
+const maxAge = await db.model('User').max('age');
+
+// Sum / Avg (Returns Number, not String)
+const totalScore = await db.model('User').sum('score');
+const avgScore = await db.model('User').avg('score');
+
+// Group By
+const stats = await db.model('User')
+  .select('city, count(*) as num')
+  .group('city')
+  .find();
+```
+
+---
+
+## ✏️ Write Operations
+
+### Insert
+
+```javascript
+// Insert one
+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
+
+```javascript
+const updated = await db.model('User')
+  .where({ id: '123' })
+  .update({
+    age: 99,
+    meta: { role: 'admin' }
+  });
+```
+
+### Delete
+
+```javascript
+await db.model('User')
+  .where('age', '<', 10)
+  .delete();
+```
+
+### Returning Data
+
+By default, write operations might not return data depending on the driver optimization. You can enforce it:
+
+```javascript
+const deletedUsers = await db.model('User')
+  .where('status', 'banned')
+  .returning('id, username') // or returning('*')
+  .delete();
+```
+
+---
+
+## ⚡ Raw SQL (Template Literals)
+
+NeoPG exposes the full power of `postgres.js`. You don't need the ModelChain for everything.
+
+> 📚 **Reference**: Full documentation for the SQL tag can be found at the [postgres.js GitHub page](https://github.com/porsager/postgres).
+
+```javascript
+// Access the native driver
+const sql = db.sql;
+
+// Execute raw SQL safely
+const users = await sql`
+  SELECT * FROM users 
+  WHERE age > ${20}
+`;
+
+// Dynamic tables/columns using helper
+const table = 'users';
+const column = 'age';
+const result = await sql`
+  SELECT ${sql(column)} 
+  FROM ${sql(table)}
+`;
+```
+
+---
+
+## 🤝 Transactions
+
+NeoPG provides a unified transaction API. It supports nested transactions (Savepoints) automatically.
+
+### Using NeoPG Context (Recommended)
+
+```javascript
+// Start a transaction scope
+const result = await db.transaction(async (tx) => {
+  // 'tx' is a TransactionScope that mimics 'db'
+  
+  // 1. Write operation
+  const user = await tx.model('User').insert({ username: 'alice' });
+  
+  // 2. Read operation within transaction
+  const count = await tx.model('User').count();
+  
+  // 3. Throwing an error will automatically ROLLBACK
+  if (count > 100) {
+    throw new Error('Limit reached'); 
+  }
+  
+  return user;
+});
+// Automatically COMMITTED here if no error
+```
+
+### Using Raw Postgres Transaction
+
+```javascript
+await db.sql.begin(async (sql) => {
+  // sql is the transaction connection
+  await sql`INSERT INTO users (name) VALUES ('bob')`;
+});
+```
+
+---
+
+## License
+
+ISC
+
+
+![](./images/neopg-programming.jpeg)

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();