@nextage/nx-frame-be 1.0.40 → 1.0.41

package/build/common/base/__test__/base.controller.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/common/base/__test__/base.controller.test.js

@@ -0,0 +1,63 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const base_controller_1 = require("../base.controller");
+const coded_entity_model_1 = require("../../models/coded-entity.model");
+/**
+ * SEAM TEST — BaseController.withTransaction (3.4.1)
+ *
+ * The test harness runs a STANDALONE mongodb-memory-server, which does NOT support
+ * multi-document transactions. This locks the graceful-degradation contract of the
+ * session seam: detection returns false, the callback runs WITHOUT a session, an
+ * already-present session is reused (nested), and the session-aware model ops keep
+ * working unchanged when no session is supplied (parity with pre-3.4.1 behaviour).
+ */
+// keep publishCRUDEvent inert (CRUDEvents is enabled on ceModel)
+jest.spyOn(coded_entity_model_1.CodedEntity.prototype, 'publishCRUDEvent').mockImplementation(() => { });
+class CeController extends base_controller_1.BaseController {
+}
+const ctrl = new CeController({ model: coded_entity_model_1.ceModel });
+describe('BaseController.withTransaction — session seam (standalone fallback)', () => {
+    it('reports no transaction support on a standalone deployment', () => __awaiter(void 0, void 0, void 0, function* () {
+        const supported = yield ctrl.supportsTransactions();
+        expect(supported).toBe(false);
+    }));
+    it('runs the callback WITHOUT a session when transactions are unsupported', () => __awaiter(void 0, void 0, void 0, function* () {
+        const seen = [];
+        const result = yield ctrl.withTransaction({ i18n: 'en' }, (ctx) => __awaiter(void 0, void 0, void 0, function* () {
+            seen.push(ctx);
+            return 'done';
+        }));
+        expect(result).toBe('done');
+        expect(seen).toHaveLength(1);
+        expect(seen[0].session).toBeUndefined(); // fallback injects no session
+        expect(seen[0].i18n).toBe('en'); // original context preserved
+    }));
+    it('reuses an existing session (nested call) without opening a new one', () => __awaiter(void 0, void 0, void 0, function* () {
+        const outerSession = { id: 'outer' };
+        const seen = [];
+        yield ctrl.withTransaction({ session: outerSession }, (ctx) => __awaiter(void 0, void 0, void 0, function* () {
+            seen.push(ctx);
+        }));
+        expect(seen[0].session).toBe(outerSession); // same session, not replaced
+    }));
+    it('create / update / remove still work when the context carries no session', () => __awaiter(void 0, void 0, void 0, function* () {
+        const ctx = {};
+        const created = yield coded_entity_model_1.ceModel.create({ code: 'C1', name: 'n1', data: { items: [] } }, ctx);
+        expect(created.id).toBeDefined();
+        const updated = yield coded_entity_model_1.ceModel.update(created.id, { name: 'n2' }, false, ctx);
+        expect(updated.name).toBe('n2');
+        const removed = yield coded_entity_model_1.ceModel.remove(created.id, ctx);
+        expect(removed).toBeTruthy();
+        const after = yield coded_entity_model_1.ceModel.get(created.id, ctx);
+        expect(after).toBeNull();
+    }));
+});

package/build/common/base/base.controller.d.ts

@@ -6,6 +6,8 @@ import { FilterParams, QueryPagination } from './base.interfaces';
 export declare abstract class BaseController<TAttrs, TDoc extends BaseMongoDoc, T extends BaseModel<TAttrs, TDoc, any>> {
     model: T;
     mergeUpdate: boolean;
+    /** Memoised transaction-capability of the deployment (see `supportsTransactions`). */
+    private static txnSupport?;
     constructor({ model, mergeUpdate }: {
         model: T;
         mergeUpdate?: boolean;
@@ -118,4 +120,27 @@ export declare abstract class BaseController<TAttrs, TDoc extends BaseMongoDoc,
      * @returns
      */
     removeArrayItem(id: string, params: ArrayItemParams, options: mongoose.QueryOptions<Document> | undefined, context: NxContext): Promise<TDoc | null>;
+    /**
+     * Whether the current deployment supports multi-document transactions (replica set
+     * or sharded cluster). A standalone mongod (e.g. local dev, in-memory tests) does
+     * NOT. Detected once per process via the `hello` admin command and memoised, so
+     * `withTransaction` can degrade gracefully instead of throwing at runtime.
+     */
+    protected supportsTransactions(): Promise<boolean>;
+    /**
+     * Run `fn` inside a Mongo transaction when the deployment supports it, injecting
+     * the session into a CHILD context so every session-aware model op (create /
+     * update / remove) joins the same atomic unit.
+     *
+     * Degradation & safety:
+     *  - if `context.session` is already set, the call is NESTED → reuse it (no new txn);
+     *  - if transactions are unsupported (standalone) → run `fn(context)` WITHOUT a
+     *    session, i.e. exactly the current non-atomic behaviour (graceful fallback);
+     *  - `session.withTransaction` may re-run `fn` on transient errors, so `fn` MUST
+     *    keep non-DB side effects (e.g. publishing) OUTSIDE the transaction.
+     *
+     * @param context caller context (may already carry a session)
+     * @param fn      work to run; receives the context to pass down to model ops
+     */
+    withTransaction<R>(context: NxContext, fn: (ctx: NxContext) => Promise<R>): Promise<R>;
 }

package/build/common/base/base.controller.js

@@ -170,5 +170,63 @@ class BaseController {
     removeArrayItem(id, params, options = { new: true }, context) {
         return this.model.removeArrayItem(id, params, options, context);
     }
+    /**
+     * Whether the current deployment supports multi-document transactions (replica set
+     * or sharded cluster). A standalone mongod (e.g. local dev, in-memory tests) does
+     * NOT. Detected once per process via the `hello` admin command and memoised, so
+     * `withTransaction` can degrade gracefully instead of throwing at runtime.
+     */
+    supportsTransactions() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (BaseController.txnSupport !== undefined)
+                return BaseController.txnSupport;
+            try {
+                const conn = this.model.mgModel.db;
+                const info = yield conn.db.admin().command({ hello: 1 });
+                // `setName` => replica set member; `msg: 'isdbgrid'` => mongos (sharded).
+                BaseController.txnSupport = !!info.setName || info.msg === 'isdbgrid';
+            }
+            catch (_a) {
+                BaseController.txnSupport = false;
+            }
+            return BaseController.txnSupport;
+        });
+    }
+    /**
+     * Run `fn` inside a Mongo transaction when the deployment supports it, injecting
+     * the session into a CHILD context so every session-aware model op (create /
+     * update / remove) joins the same atomic unit.
+     *
+     * Degradation & safety:
+     *  - if `context.session` is already set, the call is NESTED → reuse it (no new txn);
+     *  - if transactions are unsupported (standalone) → run `fn(context)` WITHOUT a
+     *    session, i.e. exactly the current non-atomic behaviour (graceful fallback);
+     *  - `session.withTransaction` may re-run `fn` on transient errors, so `fn` MUST
+     *    keep non-DB side effects (e.g. publishing) OUTSIDE the transaction.
+     *
+     * @param context caller context (may already carry a session)
+     * @param fn      work to run; receives the context to pass down to model ops
+     */
+    withTransaction(context, fn) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // already inside a transaction → reuse it (nested call, no new session)
+            if (context === null || context === void 0 ? void 0 : context.session)
+                return fn(context);
+            // standalone deployment → no atomicity available, run as today
+            if (!(yield this.supportsTransactions()))
+                return fn(context);
+            const session = yield this.model.mgModel.startSession();
+            try {
+                let result;
+                yield session.withTransaction(() => __awaiter(this, void 0, void 0, function* () {
+                    result = yield fn(Object.assign(Object.assign({}, context), { session }));
+                }));
+                return result;
+            }
+            finally {
+                yield session.endSession();
+            }
+        });
+    }
 }
 exports.BaseController = BaseController;

package/build/common/base/base.model.js

@@ -215,7 +215,7 @@ class BaseModel extends events_1.EventEmitter {
                 return null;
             const filter = { _id: (0, mongo_utils_1.toObjectId)(id) };
             yield this.beforeGet(filter, context);
-            return this.mgModel.findOne(filter);
+            return this.mgModel.findOne(filter, null, { session: context === null || context === void 0 ? void 0 : context.session });
         });
     }
     /**
@@ -403,7 +403,7 @@ class BaseModel extends events_1.EventEmitter {
         return __awaiter(this, void 0, void 0, function* () {
             item = yield this.beforeCreate(item, context);
             const itemDoc = this.mgModel.build(item);
-            const res = yield itemDoc.save(); //await this.mgModel.create(item);
+            const res = yield itemDoc.save({ session: context === null || context === void 0 ? void 0 : context.session }); //await this.mgModel.create(item);
             if (context)
                 context.evtItem = res;
             this.publishCRUDEvent({ type: enums_1.ModelCrudEventType.create, data: { uid: res.id, model: this.name } }, context);
@@ -480,7 +480,7 @@ class BaseModel extends events_1.EventEmitter {
                 }
                 itemDoc.set(toApply);
                 try {
-                    res = yield itemDoc.save();
+                    res = yield itemDoc.save({ session: context === null || context === void 0 ? void 0 : context.session });
                     break;
                 }
                 catch (err) {
@@ -737,7 +737,7 @@ class BaseModel extends events_1.EventEmitter {
             if (!id)
                 throw new Error('missing id');
             id = yield this.beforeRemove(id, context);
-            const res = yield this.mgModel.findByIdAndDelete(id);
+            const res = yield this.mgModel.findByIdAndDelete(id, { session: context === null || context === void 0 ? void 0 : context.session });
             this.publishCRUDEvent({ type: enums_1.ModelCrudEventType.remove, data: { uid: id, model: this.name } }, context);
             return this.afterRemove(res, context);
         });

package/build/common/interfaces.d.ts

@@ -1,4 +1,5 @@
 import { Response } from 'express';
+import type { ClientSession } from 'mongoose';
 import { ModelCrudEventType, AuthIssuer } from './enums';
 export interface NxContext {
     access?: string;
@@ -10,6 +11,7 @@ export interface NxContext {
     remoteAddress?: string;
     res?: Response;
     i18n?: string;
+    session?: ClientSession;
 }
 export interface NxJwtData extends NxObject {
     rls?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextage/nx-frame-be",
-  "version": "1.0.40",
+  "version": "1.0.41",
   "description": "",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",