nodejs-store 2.3.0 → 2.5.0

package/src/executors/index.js

@@ -38,6 +38,43 @@ function _scalar(rows) {
   return typeof v === 'string' ? Number(v) : v;
 }
 
+/**
+ * 显式 checkout：返回 `{ conn, release }`；`release` 为 async 幂等函数。
+ *
+ * 池形态（pg Pool → `connect()` / mysql2 Pool → `getConnection()`）失败**直接上抛**，
+ * 禁「静默退回 driver 本体」——退回本体可能落到池上另一连接，使事务语义错乱；
+ * 单连接形态直用 driver，release 为 no-op。
+ * pg / mysql 执行器的显式事务句柄均以此为基础（禁第二套 checkout 路径）。
+ */
+async function openAcquire(driver) {
+  if (driver && typeof driver.connect === 'function') {
+    const conn = await driver.connect(); // pg Pool：失败直接上抛
+    let released = false;
+    return {
+      conn,
+      release: async () => {
+        if (released) return;
+        released = true;
+        // pg Client（connect() 返回自身）无 release()，属单连接形态
+        if (typeof conn.release === 'function') conn.release();
+      },
+    };
+  }
+  if (driver && typeof driver.getConnection === 'function') {
+    const conn = await driver.getConnection(); // mysql2 Pool：失败直接上抛
+    let released = false;
+    return {
+      conn,
+      release: async () => {
+        if (released) return;
+        released = true;
+        conn.release();
+      },
+    };
+  }
+  return { conn: driver, release: async () => {} }; // 单连接形态
+}
+
 /** 中立包络 → Mongo 驱动等价返回值 */
 function shapeResult(cmd, out) {
   switch (cmd.kind) {
@@ -62,4 +99,4 @@ function shapeResult(cmd, out) {
   }
 }
 
-module.exports = { createConnection, shapeResult, mongo, mysql, postgres, sqlite };
+module.exports = { createConnection, openAcquire, shapeResult, mongo, mysql, postgres, sqlite };

package/src/executors/mongo.js

@@ -11,6 +11,10 @@
  * 同时命中「值为 null」与「字段缺失」两类文档，而本 store 的三态契约（F-07/H-09）
  * 要求 `null` 只命中显式 null、`$exists:false` 才命中缺失 —— 这与 SQL 侧
  * `col IS NULL`（显式 null）语义对齐。运算对象（`$ne:null`/`$exists`/`$gt`…）不改写。
+ *
+ * Mongo session 事务：本模块只提供原语 `openTransaction`（`startSession` +
+ * `startTransaction`）与 `execMongo(..., session)` 透传；事务的编排（提交/回滚/
+ * 降级声明）由 datasource 层负责。Mongo **无** `SAVEPOINT` 原语，故不提供保存点系列。
  */
 
 /** 递归改写 filter：`field: null`（标量等值）→ `field: {$eq: null, $exists: true}`。 */
@@ -51,52 +55,96 @@ function _normPipeline(cmd) {
   }
 }
 
-/** Command JSON → MongoDB 原生驱动调用 */
-async function execMongo(db, cmd) {
+/** Mongo 连接的 client：db 实例取 .client；MongoClient 返回自身 */
+function _clientOf(connection) {
+  if (connection && typeof connection.db === 'function' && typeof connection.collection !== 'function') {
+    return connection; // MongoClient
+  }
+  return (connection && connection.client) || null; // Db.client
+}
+
+/** 合并 session 到 options（session 为空时返回原 options 语义，零回归） */
+function _opts(session, base) {
+  const o = base ? { ...base } : {};
+  if (session) o.session = session;
+  return o;
+}
+
+/**
+ * Mongo 事务句柄：startSession + startTransaction
+ *   - commit/rollback 幂等；release 结束 session；
+ *   - 无保存点原语（Mongo 不支持 SAVEPOINT），嵌套由 datasource 层降级声明。
+ */
+async function openTransaction(connection) {
+  const client = _clientOf(connection);
+  const session = client.startSession();
+  session.startTransaction();
+  let closed = false;
+  return {
+    session,
+    async commit() {
+      if (closed) return;
+      closed = true;
+      await session.commitTransaction();
+    },
+    async rollback() {
+      if (closed) return;
+      closed = true;
+      await session.abortTransaction();
+    },
+    async release() {
+      await session.endSession();
+    },
+  };
+}
+
+/** Command JSON → MongoDB 原生驱动调用（session 非空时全部操作携带该 session） */
+async function execMongo(db, cmd, session) {
   const coll = db.collection(cmd.collection);
   switch (cmd.kind) {
     case 'find': {
       _normFilter(cmd);
-      const opts = cmd.projection ? { projection: cmd.projection } : undefined;
+      const opts = _opts(session, cmd.projection ? { projection: cmd.projection } : undefined);
       return coll.find(cmd.filter, opts).toArray();
     }
     case 'aggregate':
+      // cmd.options 为原生聚合透传项（executeNative 注入；GQL 路径无此键，零回归）
       _normPipeline(cmd);
-      return coll.aggregate(cmd.pipeline).toArray();
+      return coll.aggregate(cmd.pipeline, _opts(session, cmd.options)).toArray();
     case 'countDocuments':
       _normFilter(cmd);
-      return coll.countDocuments(cmd.filter);
+      return coll.countDocuments(cmd.filter, _opts(session));
     case 'findOne': {
       _normFilter(cmd);
-      const opts = cmd.projection ? { projection: cmd.projection } : undefined;
+      const opts = _opts(session, cmd.projection ? { projection: cmd.projection } : undefined);
       return coll.findOne(cmd.filter, opts);
     }
     case 'insertOne':
-      await coll.insertOne(cmd.doc);
+      await coll.insertOne(cmd.doc, _opts(session));
       return cmd.doc;
     case 'insertMany':
       if (cmd.upsertById) {
         // 归档幂等（core planArchiveDocs）：按 _id 逐条覆盖 —— 「归档成功但删除失败」
         // 的重试不再因 _id 冲突整批失败。SQL 侧由 dialect 的 ON CONFLICT/REPLACE 承接。
         for (const doc of cmd.docs) {
-          await coll.replaceOne({ _id: doc._id }, doc, { upsert: true });
+          await coll.replaceOne({ _id: doc._id }, doc, _opts(session, { upsert: true }));
         }
         return { insertedCount: cmd.docs.length };
       }
-      await coll.insertMany(cmd.docs);
+      await coll.insertMany(cmd.docs, _opts(session));
       return { insertedCount: cmd.docs.length };
     case 'findOneAndUpdate':
       _normFilter(cmd);
-      return coll.findOneAndUpdate(cmd.filter, cmd.update, cmd.options);
+      return coll.findOneAndUpdate(cmd.filter, cmd.update, _opts(session, cmd.options));
     case 'updateMany':
       _normFilter(cmd);
-      return coll.updateMany(cmd.filter, cmd.update);
+      return coll.updateMany(cmd.filter, cmd.update, _opts(session));
     case 'deleteMany':
       _normFilter(cmd);
-      return coll.deleteMany(cmd.filter);
+      return coll.deleteMany(cmd.filter, _opts(session));
     default:
       throw new Error(`未支持的命令: ${cmd.kind}`);
   }
 }
 
-module.exports = { execMongo };
+module.exports = { execMongo, openTransaction };

package/src/executors/mysql.js

@@ -42,32 +42,67 @@ function create(driver, _options = {}) {
     return { docs, rows, affectedRows };
   }
 
+  /**
+   * 显式事务句柄：池 checkout 专用连接（失败直接上抛，无静默兜底）
+   * + beginTransaction + 幂等 commit/rollback；release 归还连接（单连接为 no-op）。
+   */
+  async function openTransaction() {
+    const { openAcquire } = require('./index'); // 延迟导入：避免与 index 的循环依赖
+    const { conn, release } = await openAcquire(driver);
+    await conn.beginTransaction();
+    let closed = false;
+    return {
+      exec: (plan) => runStmts(conn, plan),
+      async savepoint(name) {
+        /* 保存点（嵌套事务用）；name 由 Host 生成（sp_<n>），非用户输入。
+           MySQL 预备语句协议不支持 SAVEPOINT → 必须走 conn.query */
+        await conn.query(`SAVEPOINT ${name}`);
+      },
+      async releaseSavepoint(name) {
+        await conn.query(`RELEASE SAVEPOINT ${name}`);
+      },
+      async rollbackToSavepoint(name) {
+        await conn.query(`ROLLBACK TO SAVEPOINT ${name}`);
+      },
+      async commit() {
+        if (closed) return;
+        closed = true;
+        await conn.commit();
+      },
+      async rollback() {
+        if (closed) return;
+        closed = true;
+        await conn.rollback();
+      },
+      release,
+    };
+  }
+
+  /** 事务执行：基于 openTransaction（无第二套事务路径），任一失败整体回滚；
+   *  body(exec, tx) 第二参数为事务句柄（供上层读保存点原语），可选——旧单参写法继续可用 */
+  async function withTransaction(body) {
+    const tx = await openTransaction();
+    try {
+      const out = await body(tx.exec, tx);
+      await tx.commit();
+      return out;
+    } catch (e) {
+      try {
+        await tx.rollback();
+      } catch (_) {
+        /* rollback 失败不掩盖原始错误 */
+      }
+      throw e;
+    } finally {
+      await tx.release();
+    }
+  }
+
   return {
     kind: 'mysql',
     exec: (plan) => runStmts(driver, plan),
-    /**
-     * 事务执行：body(executeOnTx) 的所有 plan 落在同一连接同一事务内，
-     * 成功 commit / 失败 rollback。池自动取专用连接（结束归还）。
-     */
-    async withTransaction(body) {
-      const conn =
-        typeof driver.getConnection === 'function' ? await driver.getConnection() : driver;
-      try {
-        await conn.beginTransaction();
-        const out = await body((plan) => runStmts(conn, plan));
-        await conn.commit();
-        return out;
-      } catch (e) {
-        try {
-          await conn.rollback();
-        } catch (_) {
-          /* rollback 失败不掩盖原始错误 */
-        }
-        throw e;
-      } finally {
-        if (conn !== driver && typeof conn.release === 'function') conn.release();
-      }
-    },
+    withTransaction,
+    openTransaction,
   };
 }
 

package/src/executors/postgres.js

@@ -32,44 +32,66 @@ function create(driver, _options = {}) {
     return { docs, rows, affectedRows };
   }
 
+  /**
+   * 显式事务句柄：池 checkout 专用 client（失败直接上抛，无静默兜底）
+   * + BEGIN + 幂等 commit/rollback；release 归还连接（单连接为 no-op）。
+   */
+  async function openTransaction() {
+    const { openAcquire } = require('./index'); // 延迟导入：避免与 index 的循环依赖
+    const { conn, release } = await openAcquire(driver);
+    await conn.query('BEGIN');
+    let closed = false;
+    return {
+      exec: (plan) => runStmts(conn, plan),
+      async savepoint(name) {
+        /* 保存点（嵌套事务用）；name 由 Host 生成（sp_<n>），非用户输入 */
+        await conn.query(`SAVEPOINT ${name}`);
+      },
+      async releaseSavepoint(name) {
+        await conn.query(`RELEASE SAVEPOINT ${name}`);
+      },
+      async rollbackToSavepoint(name) {
+        await conn.query(`ROLLBACK TO SAVEPOINT ${name}`);
+      },
+      async commit() {
+        if (closed) return;
+        closed = true;
+        await conn.query('COMMIT');
+      },
+      async rollback() {
+        if (closed) return;
+        closed = true;
+        await conn.query('ROLLBACK');
+      },
+      release,
+    };
+  }
+
+  /** 事务执行：基于 openTransaction（无第二套事务路径），任一失败整体回滚；
+   *  body(exec, tx) 第二参数为事务句柄（供上层读保存点原语），可选——旧单参写法继续可用 */
+  async function withTransaction(body) {
+    const tx = await openTransaction();
+    try {
+      const out = await body(tx.exec, tx);
+      await tx.commit();
+      return out;
+    } catch (e) {
+      try {
+        await tx.rollback();
+      } catch (_) {
+        /* rollback 失败不掩盖原始错误 */
+      }
+      throw e;
+    } finally {
+      await tx.release();
+    }
+  }
+
   return {
     kind: 'postgres',
     exec: (plan) => runStmts(driver, plan),
-    /**
-     * 事务执行：显式 BEGIN/COMMIT/ROLLBACK 包住 body 的全部 plan。
-     * Pool 自动 checkout 专用 client（`release()` 归还）；Client 直连直接用。
-     */
-    async withTransaction(body) {
-      let conn = driver;
-      let release = null;
-      if (typeof driver.connect === 'function') {
-        try {
-          const c = await driver.connect();
-          // Pool.connect() → 专用 Client（带 release）；Client.connect() → 自身
-          if (c && typeof c.query === 'function') {
-            conn = c;
-            if (c !== driver && typeof c.release === 'function') release = () => c.release();
-          }
-        } catch (_) {
-          /* checkout 失败退回 driver 本体，事务语义由 BEGIN/COMMIT 保证 */
-        }
-      }
-      try {
-        await conn.query('BEGIN');
-        const out = await body((plan) => runStmts(conn, plan));
-        await conn.query('COMMIT');
-        return out;
-      } catch (e) {
-        try {
-          await conn.query('ROLLBACK');
-        } catch (_) {
-          /* rollback 失败不掩盖原始错误 */
-        }
-        throw e;
-      } finally {
-        if (release) release();
-      }
-    },
+    withTransaction,
+    openTransaction,
   };
 }
 

package/src/executors/sqlite.js

@@ -49,26 +49,57 @@ function create(db, _options = {}) {
     return { docs, rows, affectedRows };
   }
 
-  return {
-    kind: 'sqlite',
-    exec: runStmts,
-    /** 事务执行：显式 BEGIN/COMMIT/ROLLBACK（better-sqlite3 默认 autocommit，显式开事务安全） */
-    async withTransaction(body) {
-      db.exec('BEGIN');
-      try {
-        const out = await body(runStmts);
+  /** 显式事务句柄：BEGIN + 幂等 commit/rollback；release 为 no-op（单连接不归还） */
+  async function openTransaction() {
+    db.exec('BEGIN');
+    let closed = false;
+    return {
+      exec: runStmts,
+      async savepoint(name) {
+        /* 保存点（嵌套事务用）；name 由 Host 生成（sp_<n>），非用户输入 */
+        db.exec(`SAVEPOINT ${name}`);
+      },
+      async releaseSavepoint(name) {
+        db.exec(`RELEASE SAVEPOINT ${name}`);
+      },
+      async rollbackToSavepoint(name) {
+        db.exec(`ROLLBACK TO SAVEPOINT ${name}`);
+      },
+      async commit() {
+        if (closed) return;
+        closed = true;
         db.exec('COMMIT');
-        return out;
-      } catch (e) {
-        try {
-          db.exec('ROLLBACK');
-        } catch (_) {
-          /* rollback 失败不掩盖原始错误 */
-        }
-        throw e;
+      },
+      async rollback() {
+        if (closed) return;
+        closed = true;
+        db.exec('ROLLBACK');
+      },
+      async release() {},
+    };
+  }
+
+  /** 事务执行：基于 openTransaction（无第二套事务路径），任一失败整体回滚；
+   *  body(exec, tx) 第二参数为事务句柄（供上层读保存点原语），可选——旧单参写法继续可用 */
+  async function withTransaction(body) {
+    const tx = await openTransaction();
+    try {
+      const out = await body(tx.exec, tx);
+      await tx.commit();
+      return out;
+    } catch (e) {
+      try {
+        await tx.rollback();
+      } catch (_) {
+        /* rollback 失败不掩盖原始错误 */
       }
-    },
-  };
+      throw e;
+    } finally {
+      await tx.release();
+    }
+  }
+
+  return { kind: 'sqlite', exec: runStmts, withTransaction, openTransaction };
 }
 
 module.exports = { create };

package/src/index.js

@@ -25,6 +25,7 @@ const { AsyncLocalStorage } = require('node:async_hooks');
 
 const crud = require('./crud');
 const datasource = require('./datasource');
+const { Session, NonAtomicWriteError } = require('./datasource');
 const ddl = require('./ddl');
 const executors = require('./executors');
 const feedback = require('./feedback');
@@ -146,21 +147,87 @@ class Store {
    * fn 内 executeRaw / CRUD 均落到该源的事务连接（commit/rollback 一体）；
    * Mongo 源或执行器未实现 withTransaction 时按原样执行（跨源无法原子），
    * 绝不静默假装已事务化。单源场景 source 传 'default'。
+   *
+   * 同源嵌套 transaction 会开保存点（内层失败只回滚本层）；句柄无保存点原语时
+   * 降级并入外层并发 nested_savepoint_unsupported。
    */
   async transaction(source, fn) {
     return datasource.runInTransaction(source, fn);
   }
 
   /**
-   * 在指定 SQL 源执行原生 SQL（事务内可用；占位符按各后端原生风格）
+   * 会话（工作单元）：回调式，退出统一提交 / 异常统一回滚
+   *
+   * 用法:
+   *   await store.session(async (s) => {
+   *     await s.insert('Order', { ... });
+   *     await s.update('Account', cond, { ... });
+   *   });
+   *
+   * 约束：同一会话内写命令只允许落在**单一数据源**；跨源写退出时抛
+   * NonAtomicWriteError（先全部回滚，绝不提交半截）。
    *
-   * mysql/sqlite 用 `?`，postgres 用 `$1..$n`；仅支持 SQL 源（Mongo 源抛 RawSqlError）。
-   * isWrite=false 取行（rows），true 取影响行数（affectedRows）。对齐 py-store store.execute_raw。
+   * 嵌套：内层会话作为嵌套作用域在已有事务上开保存点，内层失败只回滚本层
+   * （生命周期仍交外层）。
    */
-  async executeRaw(source, sql, params, isWrite) {
+  async session(fn) {
+    if (typeof fn !== 'function') {
+      throw new TypeError('store.session(fn) 需要回调函数：await store.session(async (s) => { ... })');
+    }
+    const s = new Session();
+    const parent = datasource.currentSession();
+    if (parent !== null) {
+      // 嵌套：生命周期交外层；本层作为嵌套作用域（保存点隔离，失败只回滚本层）
+      s.bindOuter(parent);
+      const scope = parent.pushScope();
+      try {
+        const out = await fn(s);
+        await parent.popScope(scope, false);
+        return out;
+      } catch (err) {
+        await parent.popScope(scope, true);
+        throw err;
+      }
+    }
+    return datasource.runWithSession(s, async () => {
+      try {
+        const out = await fn(s);
+        await s.exit(null);
+        return out;
+      } catch (err) {
+        await s.exit(err);
+        throw err;
+      }
+    });
+  }
+
+  /**
+   * 在指定 SQL 源执行原生 SQL（事务内可用；编译由 core rawStmtCompile 完成）
+   *
+   * 两档参数风格：位置档（params 为数组/null）→ SQL 原样透传，占位符为各后端
+   * 原生风格（mysql/sqlite 用 `?`，postgres 用 `$1..$n`）；命名档（params 为对象）
+   * → SQL 文本中的 `:name` 编译为方言占位符（同名复用、跳过 `::` cast / 引号 /
+   * 注释边界；缺名 / 多余名显式报错）。isWrite 缺省时按 SQL 首词推断（读白名单外
+   * 一律按写——安全方向）。仅支持 SQL 源（Mongo 源抛 RawSqlError）。
+   * 对齐 py-store store.execute_raw。
+   */
+  async executeRaw(source, sql, params = null, isWrite = null) {
     return datasource.executeRaw(source, sql, params, isWrite);
   }
 
+  /**
+   * 在指定 Mongo 源执行原生聚合管道（事务内可用；对标 SQL 侧 executeRaw）
+   *
+   * pipeline 为原生聚合管道（数组），options 为驱动原生透传项（allowDiskUse /
+   * batchSize / hint / maxTimeMS…，宿主不做白名单）。事务 / 会话作用域内自动透传
+   * session（由事务强制接管，options.session 不可覆盖）；统一按读路径解析，
+   * $merge / $out 写管道请自行开事务。仅支持 Mongo 源（SQL 源抛 NativeCommandError
+   * 并指引 executeRaw）。返回 { rows }。对齐 py-store store.execute_native。
+   */
+  async executeNative(source, collection, pipeline = [], options = null) {
+    return datasource.executeNative(source, collection, pipeline, options);
+  }
+
   /** 从已注册 schema def 生成指定后端 DDL 文本（纯函数，不连库、不回写；铁律 6） */
   generateDdl(backend, names) {
     return ddl.generate(backend, names);
@@ -240,6 +307,8 @@ Store.prototype.PermissionError = permission.PermissionError;
 Store.prototype.ProfileViolation = crud.ProfileViolation;
 /** 原生 SQL 入口错误（实例可被 store.RawSqlError 捕获） */
 Store.prototype.RawSqlError = datasource.RawSqlError;
+/** 原生 Mongo 命令入口错误（实例可被 store.NativeCommandError 捕获） */
+Store.prototype.NativeCommandError = datasource.NativeCommandError;
 
 const store = new Store();
 
@@ -331,10 +400,13 @@ module.exports = {
   store,
   Store,
   text2query,
+  Session,
+  NonAtomicWriteError,
   PermissionError: permission.PermissionError,
   ProfileViolation: crud.ProfileViolation,
   PushdownUnsupportedError: datasource.PushdownUnsupportedError,
   RawSqlError: datasource.RawSqlError,
+  NativeCommandError: datasource.NativeCommandError,
   datasource,
   ddl,
   schema,