neopg 0.0.1 → 1.0.1

package/lib/ModelChain.js

@@ -4,6 +4,18 @@ const makeId = require('./makeId.js')
 const makeTimestamp = require('./makeTimestamp.js')
 const TransactionScope = require('./TransactionScope.js')
 
+// [优化 1] 提取常量定义到类外部，提升性能
+const INT_TYPES = new Set([
+    'int', 'integer', 'smallint', 'bigint', 
+    'serial', 'bigserial', 'smallserial',
+    'int2', 'int4', 'int8'
+])
+
+const FLOAT_TYPES = new Set([
+    'float', 'double', 'numeric', 'decimal', 'real', 
+    'money', 'double precision', 'float4', 'float8'
+])
+
 /**
  * ModelChain - 链式查询构建器
  * 负责运行时的查询构建、SQL 拼装和结果处理。
@@ -30,6 +42,9 @@ class ModelChain {
     this._columns = null
     this._group = null
     this._lock = null
+    this._returning = null
+    this._joins = []
+    this._group = []
 
     // 内部状态标记
     this._isRaw = !!def.isRaw
@@ -163,6 +178,37 @@ class ModelChain {
     return this
   }
 
+  returning(cols) {
+    if (!cols) return this
+
+    if (typeof cols === 'string') {
+      // 支持 'id, name' 写法
+      this._returning = cols.split(',').map(s => s.trim()).filter(s => s)
+    } else if (Array.isArray(cols)) {
+      this._returning = cols
+    }
+
+    return this
+  }
+
+  // --- 构建 RETURNING 片段 ---
+  _buildReturning() {
+    // 如果没有设置 returning，默认不返回数据 (节省性能)
+    // 注意：这意味着默认 insert/update 返回的是 Result 对象(包含 count)，而不是行数据
+    if (!this._returning || this._returning.length === 0) {
+        return this.sql``
+    }
+
+    // 特殊处理 '*': 用户显式要求 returning('*')
+    // 如果直接用 this.sql(['*']) 会被转义为 "*"，导致错误
+    if (this._returning.length === 1 && this._returning[0] === '*') {
+        return this.sql`RETURNING *`
+    }
+
+    // 普通字段：利用 postgres.js 自动转义标识符
+    return this.sql`RETURNING ${this.sql(this._returning)}`
+  }
+
    // --- 辅助：构建 Where 片段 (修复 Bug 的核心) ---
   _buildWhere() {
     const len = this._conditions.length
@@ -208,18 +254,15 @@ class ModelChain {
     // 修复：使用新方法构建
     const w = this._buildWhere()
     const o = this._buildOrder()
+    const j = this._buildJoins()
+    const g = this._buildGroup()
 
     const l = this._limit ? this.sql`LIMIT ${this._limit}` : this.sql``
     const off = this._offset ? this.sql`OFFSET ${this._offset}` : this.sql``
     const lck = this._lock || this.sql``
     const ft = this.sql`${this.sql(this.schema)}.${t}`
     
-    return await this.sql`SELECT ${c} FROM ${ft} ${w} ${o} ${l} ${off} ${lck}`
-  }
-
-  // Thenable 接口
-  then(onFulfilled, onRejected) {
-    return this.find().then(onFulfilled, onRejected)
+    return await this.sql`SELECT ${c} FROM ${ft} ${j} ${w} ${g} ${o} ${l} ${off} ${lck}`
   }
 
   async get() {
@@ -229,12 +272,16 @@ class ModelChain {
   }
 
   async count() {
-    const t = this.sql(this.tableName); 
-    // 修复：使用新方法构建
+    const t = this.sql(this.tableName)
+
     const w = this._buildWhere()
     const ft = this.sql`${this.sql(this.schema)}.${t}`
+    const j = this._buildJoins()
     
-    const r = await this.sql`SELECT count(*) as total FROM ${ft} ${w}`
+    const r = await this.sql`SELECT count(*) as total FROM ${ft} ${j} ${w}`
+
+    if (r.length === 0) return 0
+
     return parseInt(r[0].total)
   }
 
@@ -248,9 +295,24 @@ class ModelChain {
     }
 
     const fullTable = this.sql`${this.sql(this.schema)}.${this.sql(this.tableName)}`
-    const result = await this.sql`INSERT INTO ${fullTable} ${this.sql(inputs)} RETURNING *`
 
-    if (!isArray && result.length > 0) return result[0]
+    // [修改] 动态构建 returning
+    const retFragment = this._buildReturning()
+
+    const result = await this.sql`INSERT INTO ${fullTable} ${this.sql(inputs)} ${retFragment}`
+
+    // 如果有 returning 数据，result 是数组（包含行）；否则 result 是 Result 对象（包含 count）
+    // 逻辑保持兼容：如果用户请求了数据，且是单条插入，返回对象；否则返回数组
+    if (this._returning && this._returning.length > 0) {
+        if (!isArray && result.length === 1) {
+          return result[0]
+        }
+
+        return result
+    }
+    
+    // 如果没有 returning，返回 postgres 原生结果 (包含 count 等信息)
+    // 测试发现如果没有returning则返回的是空数组
     return result
   }
 
@@ -264,7 +326,18 @@ class ModelChain {
     // 修复：使用新方法构建
     const whereFragment = this._buildWhere()
     
-    return await this.sql`UPDATE ${fullTable} SET ${this.sql(data)} ${whereFragment} RETURNING *`
+    // [修改] 动态构建 returning
+    const retFragment = this._buildReturning()
+    
+    const result = await this.sql`UPDATE ${fullTable} SET ${this.sql(data)} ${whereFragment} ${retFragment}`
+
+    if (this._returning && this._returning.length > 0) {
+        if (result.length === 1) return result[0]
+
+        return result
+    }
+
+    return result
   }
 
   async delete() {
@@ -273,14 +346,249 @@ class ModelChain {
     // 修复：使用新方法构建
     const whereFragment = this._buildWhere()
     
-    return await this.sql`DELETE FROM ${fullTable} ${whereFragment} RETURNING *`
+    const retFragment = this._buildReturning()
+      
+    return await this.sql`DELETE FROM ${fullTable} ${whereFragment} ${retFragment}`
   }
 
   async transaction(callback) {
-    return await this.sql.begin(async (trxSql) => {
+    return this.ctx.transaction(callback)
+    /* return await this.sql.begin(async (trxSql) => {
       const scope = new TransactionScope(this.ctx, trxSql)
       return await callback(scope)
-    })
+    }) */
+  }
+
+  begin(callback) {
+    return this.ctx.transaction(callback)
+  }
+
+   /**
+   * 内部通用 Join 添加器
+   * @param {string} type - 'INNER JOIN', 'LEFT JOIN', 'RIGHT JOIN'
+   * @param {string|Object} table - 表名 或 sql`fragment`
+   * @param {string|Object} on - 条件字符串 或 sql`fragment`
+   */
+  _addJoin(type, table, on) {
+    let tableFragment
+    let onFragment
+
+    // 1. 处理 Table
+    if (table.constructor && table.constructor.name === 'Query') {
+      tableFragment = table
+    } else {
+      // 默认作为当前 Schema 下的表名处理 "public"."table"
+      // 如果需要跨 Schema (e.g. "other.table")，请用户传入 sql`other.table`
+      tableFragment = this.sql(table)
+    }
+
+    // 2. 处理 ON 条件
+    if (on.constructor && on.constructor.name === 'Query') {
+      onFragment = on;
+    } else {
+      // 字符串情况，视为 Raw SQL (e.g. "u.id = p.uid")
+      // 因为 ON 条件通常包含操作符，无法简单参数化，必须 unsafe
+      onFragment = this.sql.unsafe(on);
+    }
+
+    // 3. 构建单个 Join 片段
+    // 格式: TYPE + table + ON + condition
+    const joinFragment = this.sql`${this.sql.unsafe(type)} ${tableFragment} ON ${onFragment}`
+    
+    this._joins.push(joinFragment)
+    return this
+  }
+
+  join(table, on) {
+    return this._addJoin('INNER JOIN', table, on)
+  }
+
+  innerJoin(table, on) {
+    return this._addJoin('INNER JOIN', table, on)
+  }
+
+  leftJoin(table, on) {
+    return this._addJoin('LEFT JOIN', table, on)
+  }
+
+  rightJoin(table, on) {
+    return this._addJoin('RIGHT JOIN', table, on)
+  }
+
+  fullJoin(table, on) {
+    return this._addJoin('FULL OUTER JOIN', table, on)
+  }
+
+  _buildJoins() {
+    const len = this._joins.length
+    if (len === 0) return this.sql``
+
+    // 只有一个 Join，直接返回
+    if (len === 1) {
+      return this._joins[0]
+    }
+
+    // 多个 Join，必须用空格连接，不能用逗号
+    // 采用“平铺数组”高性能方案
+    const parts = new Array(len * 2 - 1)
+    const SPACE = this.sql.unsafe(' ')
+
+    for (let i = 0; i < len; i++) {
+      parts[i * 2] = this._joins[i]
+      if (i < len - 1) {
+        parts[i * 2 + 1] = SPACE
+      }
+    }
+
+    return this.sql`${parts}`
+  }
+
+  /**
+   * 添加 Group By 条件
+   * .group('category_id')
+   * .group('category_id, type')
+   * .group(['id', 'name'])
+   */
+  group(arg) {
+    if (!arg) return this
+    
+    // 1. Fragment
+    if (arg.constructor && arg.constructor.name === 'Query') {
+      this._group.push(arg)
+      return this
+    }
+
+    // 2. Array
+    if (Array.isArray(arg)) {
+      arg.forEach(f => this.group(f))
+      return this
+    }
+
+    // 3. String
+    if (typeof arg === 'string') {
+      if (arg.includes(',')) {
+        // 'id, name' -> 拆分
+        arg.split(',').map(s => s.trim()).filter(s=>s).forEach(s => {
+          this._group.push(this.sql(s))
+        })
+      } else {
+        // 单个字段
+        this._group.push(this.sql(arg))
+      }
+    }
+
+    return this
+  }
+
+  // 构建 Group 片段
+  _buildGroup() {
+    if (this._group.length === 0) return this.sql``
+
+    // postgres.js 模板数组默认用逗号连接，正好符合 GROUP BY 语法
+    return this.sql`GROUP BY ${this._group}`
+  }
+
+  // --- 聚合函数 ---
+
+  async min(field) {
+    return this._aggregate('MIN', field)
+  }
+
+  async max(field) {
+    return this._aggregate('MAX', field)
+  }
+
+  async sum(field) {
+    return this._aggregate('SUM', field)
+  }
+
+  async avg(field) {
+    return this._aggregate('AVG', field)
+  }
+
+  /**
+   * 通用聚合执行器
+   * @param {string} func - MIN, MAX, SUM, AVG
+   * @param {string} field - 列名
+   */
+  async _aggregate(func, field) {
+    if (!field) throw new Error(`[NeoPG] ${func} requires a field name.`)
+
+    const t = this.sql(this.tableName)
+    const w = this._buildWhere()
+    const j = this._buildJoins()
+    const ft = this.sql`${this.sql(this.schema)}.${t}`
+
+    // 处理字段名 (可能是 'age' 也可能是 'users.age')
+    let colFragment;
+    if (field.constructor && field.constructor.name === 'Query') {
+        colFragment = field
+    } else {
+        colFragment = this.sql(field)
+    }
+    
+    // SELECT MIN(age) as val ...
+    const query = this.sql`
+        SELECT ${this.sql.unsafe(func)}(${colFragment}) as val 
+        FROM ${ft} ${j} ${w}
+    `
+
+    const result = await query
+    const val = result.length > 0 ? result[0].val : null
+
+    if (val === null) return null;
+
+    // 智能类型转换
+    return this._convertAggregateValue(val, field, func)
+  }
+
+  /**
+   * 智能转换聚合结果类型
+   * Postgres 对于 SUM/AVG/COUNT 经常返回字符串 (BigInt/Numeric)，我们需要转回 Number
+   */
+  _convertAggregateValue(val, field, func) {
+    // 1. AVG 始终是浮点数
+    if (func === 'AVG') {
+      return parseFloat(val)
+    }
+
+    // 如果是 Raw Fragment，无法推断类型，直接返回原值（通常是 String）
+    if (typeof field !== 'string') return val
+
+    // 2. 尝试从 ModelDef 获取列定义
+    // field 可能是 'age' 也可能是 'u.age' (别名暂不支持自动推断，这里只处理简单列名)
+    const colDef = this.def && this.def.columns ? this.def.columns[field] : null
+
+    // 如果不知道列定义，尝试尽力猜测
+    if (!colDef) {
+        // 如果 val 是字符串且长得像数字
+        if (typeof val === 'string' && !isNaN(val)) {
+            // SUM 默认为数字
+            if (func === 'SUM') return parseFloat(val)
+        }
+
+        return val
+    }
+
+    // 5. [优化] 精确类型匹配
+    // 处理 'numeric(10,2)' -> 'numeric'
+    // 处理 'integer' -> 'integer'
+    const rawType = colDef.type.toLowerCase()
+    const parenIndex = rawType.indexOf('(')
+    const baseType = parenIndex > 0 ? rawType.substring(0, parenIndex).trim() : rawType
+
+    // 整数匹配
+    if (INT_TYPES.has(baseType)) {
+      return parseInt(val, 10)
+    }
+
+    // 浮点数匹配
+    if (FLOAT_TYPES.has(baseType)) {
+      return parseFloat(val)
+    }
+
+    // 其他 (Date, String, Boolean) 原样返回
+    return val
   }
 
   // --- 内部辅助方法 ---

package/lib/NeoPG.js

@@ -33,8 +33,9 @@ class NeoPG {
 
   // --- 注册 ---
 
-  add(input) {
-    let ModelClass;
+  add(input, is_reset=false) {
+    let ModelClass
+
     if (typeof input === 'function') {
       ModelClass = input
     } else {
@@ -42,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
@@ -54,6 +61,14 @@ class NeoPG {
     return this
   }
 
+  define(model) {
+    return this.add(model)
+  }
+
+  set(model) {
+    return this.add(model, true)
+  }
+
   // --- 事务 ---
   async transaction(callback) {
     return await this.driver.begin(async (trxSql) => {
@@ -62,6 +77,10 @@ class NeoPG {
     })
   }
 
+  begin(callback) {
+    return this.transaction(callback)
+  }
+
   // --- 同步 ---
   async sync(options = {}) {
     if (!options || typeof options !== 'object') {
@@ -75,6 +94,45 @@ class NeoPG {
     }
   }
 
+  /**
+   * 监听 Postgres 消息通道
+   * @param {string} channel - 通道名称
+   * @param {Function} callback - (payload) => {}
+   * @returns {Object} 包含 unlisten 方法的对象
+   */
+  async listen(channel, callback) {
+    // postgres.js 的 listen 返回一个 Promise<void>
+    // 但它内部会维持连接。我们需要提供一种方式来取消监听。
+    // postgres.js v3 使用 sql.listen(channel, cb) 并返回一个 state 对象用于 close
+    const listener = await this.sql.listen(channel, (payload) => {
+      // 可以在这里统一处理 JSON 解析等
+      try {
+        const data = JSON.parse(payload)
+        callback(data)
+      } catch (e) {
+        // 无法解析则返回原始字符串
+        callback(payload)
+      }
+    })
+
+    return {
+      // 返回一个句柄用于取消监听
+      close: () => listener.unlisten() 
+    }
+  }
+
+  /**
+   * 发送通知
+   * @param {string} channel 
+   * @param {string|Object} payload 
+   */
+  async notify(channel, payload) {
+    const data = typeof payload === 'object' ? JSON.stringify(payload) : payload
+
+    // 使用 sql.notify 是最高效的
+    await this.sql.notify(channel, data)
+  }
+
   async close() {
     await this.driver.end()
   }

package/lib/SchemaSync.js

@@ -47,6 +47,18 @@ class SchemaSync {
     const tableName = def.tableName;
     const curTableName = `${schema}.${tableName}`;
 
+    // [递归锁初始化] 记录本次同步过程中已经处理过的 Model，防止死循环
+    if (!options.syncedModels) {
+        options.syncedModels = new Set();
+    }
+
+    // 如果该表在本次递归链中已经同步过，则跳过
+    if (options.syncedModels.has(def.modelName)) {
+        return; 
+    }
+    // 标记当前表已开始同步
+    options.syncedModels.add(def.modelName);
+
     if (debug) console.log(`检测数据表 ${tableName} 的column...`);
 
     // 0. 检查列定义的合法性 (移植自 _checkFixColumn)
@@ -76,7 +88,7 @@ class SchemaSync {
       // 同步索引、约束、外键
       await this.syncIndex(sql, def, schema, curTableName, debug);
       await this.syncUnique(sql, def, schema, curTableName, debug);
-      await this.syncReferences(sql, def, schema, curTableName, schemaOid, debug, ctx);
+      await this.syncReferences(sql, def, schema, curTableName, schemaOid, debug, ctx, options);
       return;
     }
 
@@ -84,7 +96,7 @@ class SchemaSync {
     // 获取现有列信息
     const cols = await sql`
       SELECT column_name, data_type, column_default, character_maximum_length, 
-             numeric_precision, numeric_scale, is_nullable
+             numeric_precision, numeric_scale, is_nullable, is_generated
       FROM information_schema.columns 
       WHERE table_name = ${tableName} 
       AND table_schema = ${schema} 
@@ -103,7 +115,7 @@ class SchemaSync {
     await this.syncIndex(sql, def, schema, curTableName, debug);
     await this.syncUnique(sql, def, schema, curTableName, debug);
     await this.autoRemoveIndex(sql, def, schema, tableName, debug);
-    await this.syncReferences(sql, def, schema, curTableName, schemaOid, debug, ctx);
+    await this.syncReferences(sql, def, schema, curTableName, schemaOid, debug, ctx, options);
 
     if (debug) console.log(` - 表结构同步完成 (${tableName}) - `);
   }
@@ -263,12 +275,31 @@ class SchemaSync {
 
     // 7. Drop Not Exist (Force Mode)
     if (dropNotExistCol) {
-      for (let k in inf) {
-        if (!def.columns[k] && !renameTable[k]) {
-           await sql.unsafe(`ALTER TABLE ${curTableName} DROP COLUMN ${this.fmtColName(k)}`);
+      for (let dbColName in inf) {
+        // 如果代码中没定义，且不是刚改名的
+        if (!def.columns[dbColName] && !renameTable[dbColName]) {
+           
+           const dbCol = inf[dbColName];
+
+           // [核心逻辑] 如果是数据库层面的虚拟列 (is_generated == 'ALWAYS')，豁免，不删除
+           if (dbCol.is_generated === 'ALWAYS') {
+             if (debug) console.log(`[NeoPG] Ignoring DB-only generated column: ${dbColName}`);
+             continue;
+           }
+
+           // [额外建议] 如果是 identity 列 (自增列的一种新形式)，通常也建议豁免，防止误删
+           // if (dbCol.is_identity === 'YES') continue; 
+
+           if (debug) console.log(`Deleting unused column: ${dbColName}`);
+           await sql.unsafe(`ALTER TABLE ${curTableName} DROP COLUMN ${this.fmtColName(dbColName)}`);
         }
       }
     }
+      /* for (let k in inf) {
+        if (!def.columns[k] && !renameTable[k]) {
+           await sql.unsafe(`ALTER TABLE ${curTableName} DROP COLUMN ${this.fmtColName(k)}`);
+        }
+      } */
   }
 
   // --- 索引同步 ---
@@ -370,7 +401,7 @@ class SchemaSync {
   }
 
   // --- 外键同步 ---
-  static async syncReferences(sql, def, schema, curTableName, schemaOid, debug, ctx) {
+  static async syncReferences(sql, def, schema, curTableName, schemaOid, debug, ctx, options) {
       // 1. 收集定义中的外键
       // 格式: { fkName: "xxx", createSql: "..." }
       let targetFKs = new Map();
@@ -382,27 +413,32 @@ class SchemaSync {
 
           // 解析 ref: "ModelName:colName"
           const [refModelName, refColName] = this._parseRef(col.ref, k);
+
+          // 查找被引用的 Model 定义
+          // 假设 ctx.registry.get 返回 { Class, def }
+          const targetModelItem = ctx.registry.get(refModelName);
           
-          // 加载目标模型 (这里需要通过 ctx (NeoPG实例) 获取其他模型)
-          // 假设 ctx.registry.get(refModelName) 能拿到
-          // 或者如果是文件路径，尝试 require
-          
-          // 为了简化复刻，这里假设我们能拿到目标表名
-          // 在原逻辑中是 require 文件，这里建议 NeoPG 注册机制解决
-          // 这里做一个适配：
           let targetTableName = '';
-          if (ctx.registry && ctx.registry.get(refModelName)) {
-             targetTableName = ctx.registry.get(refModelName).def.tableName;
+
+          if (targetModelItem) {
+              targetTableName = targetModelItem.def.tableName;
+              // --- [关键] 递归同步 ---
+              // 在创建外键之前，确保目标表已经存在且结构最新
+              if (debug) console.log(`[Recursive Sync] Triggered by FK: ${def.modelName} -> ${refModelName}`);
+
+              await this.execute(sql, targetModelItem.def, ctx, options);
           } else {
-             // 尝试作为表名直接使用 (Fallback)
-             targetTableName = refModelName.toLowerCase(); 
+              // 目标模型未注册，可能是直接引用的表名 (Fallback)
+              if (debug) console.warn(`[NeoPG] Referenced model '${refModelName}' not found in registry. Using as table name.`);
+              targetTableName = refModelName.toLowerCase();
           }
 
-          // 构建外键名
+          // 准备外键 SQL
           const fkName = `${def.tableName}_${k}_fkey`;
           
           // 构建 REFERENCES 子句
           let refSql = `REFERENCES ${schema}.${targetTableName} (${refColName})`;
+
           if (col.refActionUpdate) refSql += ` ON UPDATE ${col.refActionUpdate}`;
           else refSql += ` ON UPDATE CASCADE`; // 默认
 
@@ -497,14 +533,15 @@ class SchemaSync {
 
   static _parseRef(refstr, curColumn) {
       if (refstr.includes(':')) {
-          const parts = refstr.split(':');
+          const parts = refstr.split(':')
           // 处理 Model:col 格式，取最后一部分做 col，前面做 Model
-          const col = parts.pop();
-          const model = parts.join(':');
-          return [model, col];
+          const col = parts.pop()
+          const model = parts.join(':')
+          return [model, col]
       }
-      return [refstr, curColumn];
+
+      return [refstr, curColumn]
   }
 }
 
-module.exports = SchemaSync;
+module.exports = SchemaSync

package/lib/TransactionScope.js

@@ -24,6 +24,10 @@ class TransactionScope {
       return await callback(new TransactionScope(this.parent, sp))
     })
   }
+
+  begin(callback) {
+    return this.transaction(callback)
+  }
 }
 
 module.exports = TransactionScope

package/package.json

@@ -1,16 +1,26 @@
 {
   "name": "neopg",
-  "version": "0.0.1",
+  "version": "1.0.1",
   "description": "orm for postgres",
   "keywords": [
+    "neopg",
+    "NeoPG",
+    "pg",
+    "neo",
+    "pgorm",
+    "psqlorm",
     "postgres",
     "orm",
-    "database"
+    "database",
+    "postgres.js"
   ],
   "homepage": "https://github.com/master-genius/neopg#readme",
   "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"