nodejs-store 2.4.0 → 2.6.0

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,