@nextage/nx-frame-be 1.0.50 → 1.0.52

package/build/common/base/__test__/base.controller.deferred-events.test.d.ts

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

package/build/common/base/__test__/base.controller.deferred-events.test.js

@@ -0,0 +1,145 @@
+"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 constants_1 = require("../../constants");
+const constants_2 = require("../../constants");
+const base_controller_1 = require("../base.controller");
+const pubsub_manager_1 = require("../../manager/pubsub-manager");
+const enums_1 = require("../../enums");
+const coded_entity_model_1 = require("../../models/coded-entity.model");
+/**
+ * DEFERRED CRUD EMISSIONS - what a transaction is allowed to announce, and when.
+ *
+ * The harness runs a STANDALONE mongodb-memory-server, so the real transactional path cannot be
+ * reached here: `supportsTransactions()` answers false and `withTransaction` degrades. These are
+ * therefore UNIT tests of the queue itself - detection and the session are stubbed, and what is
+ * asserted is the contract the transactional path must keep:
+ *
+ *   nothing leaves before the commit · everything leaves after it · an abort leaves nothing ·
+ *   a retried transaction emits once · the subscriber never receives the session.
+ *
+ * The end-to-end proof, against a REAL replica set, lives in the consumer (D1).
+ */
+class CeController extends base_controller_1.BaseController {
+}
+const ctrl = new CeController({ model: coded_entity_model_1.ceModel });
+/** A session that records what was asked of it and never talks to a server. */
+function fakeSession(behaviour) {
+    let attempts = 0;
+    return {
+        ended: false,
+        attempts: () => attempts,
+        withTransaction: (fn) => __awaiter(this, void 0, void 0, function* () {
+            attempts++;
+            if (behaviour === 'abort') {
+                yield fn();
+                throw new Error('deliberate abort');
+            }
+            if (behaviour === 'retry-once' && attempts === 1) {
+                yield fn(); // first attempt does its work...
+                attempts++;
+                return fn(); // ...and is then re-run, as a transient error would cause
+            }
+            return fn();
+        }),
+        endSession: function () {
+            return __awaiter(this, void 0, void 0, function* () { this.ended = true; });
+        }
+    };
+}
+describe('withTransaction - emissions wait for the commit', () => {
+    let published;
+    let session;
+    beforeEach(() => {
+        published = [];
+        constants_1.APP.nxPubSub = {
+            publish: (key, data, context) => { published.push({ key, data, context }); }
+        };
+        jest.spyOn(ctrl, 'supportsTransactions').mockResolvedValue(true);
+    });
+    afterEach(() => jest.restoreAllMocks());
+    const startWith = (behaviour) => {
+        session = fakeSession(behaviour);
+        jest.spyOn(coded_entity_model_1.ceModel.mgModel, 'startSession').mockResolvedValue(session);
+    };
+    it('holds an emission back until the transaction has committed', () => __awaiter(void 0, void 0, void 0, function* () {
+        startWith('commit');
+        let seenDuring = -1;
+        yield ctrl.withTransaction({ i18n: 'en' }, (ctx) => __awaiter(void 0, void 0, void 0, function* () {
+            coded_entity_model_1.ceModel.publishCRUDEvent({ type: enums_1.ModelCrudEventType.create, data: { uid: 'x1', model: 'ce' } }, ctx);
+            seenDuring = published.length;
+        }));
+        expect(seenDuring).toBe(0); // nothing announced while the write is uncommitted
+        expect(published).toHaveLength(1); // and exactly one announcement after the commit
+        expect(published[0].key).toBe(constants_2.MODEL_CRUD_EVENT);
+        expect(published[0].data.data.uid).toBe('x1');
+    }));
+    it('hands the subscriber a context without the session and without the queue', () => __awaiter(void 0, void 0, void 0, function* () {
+        startWith('commit');
+        yield ctrl.withTransaction({ i18n: 'en' }, (ctx) => __awaiter(void 0, void 0, void 0, function* () {
+            expect(ctx.session).toBeDefined(); // the WRITE is in the transaction...
+            expect(ctx.deferredEvents).toBeDefined();
+            coded_entity_model_1.ceModel.publishCRUDEvent({ type: enums_1.ModelCrudEventType.create, data: { uid: 'x2', model: 'ce' } }, ctx);
+        }));
+        // ...but the SUBSCRIBER is not: it would be joining a transaction it cannot see the end of.
+        expect(published[0].context.session).toBeUndefined();
+        expect(published[0].context.deferredEvents).toBeUndefined();
+        expect(published[0].context.i18n).toBe('en'); // the rest of the context survives
+    }));
+    it('announces nothing when the transaction aborts', () => __awaiter(void 0, void 0, void 0, function* () {
+        startWith('abort');
+        yield expect(ctrl.withTransaction({}, (ctx) => __awaiter(void 0, void 0, void 0, function* () {
+            coded_entity_model_1.ceModel.publishCRUDEvent({ type: enums_1.ModelCrudEventType.create, data: { uid: 'x3', model: 'ce' } }, ctx);
+        }))).rejects.toThrow('deliberate abort');
+        expect(published).toHaveLength(0); // the write never happened: announcing it would be a lie
+    }));
+    it('announces once when the transaction is re-run on a transient error', () => __awaiter(void 0, void 0, void 0, function* () {
+        startWith('retry-once');
+        yield ctrl.withTransaction({}, (ctx) => __awaiter(void 0, void 0, void 0, function* () {
+            coded_entity_model_1.ceModel.publishCRUDEvent({ type: enums_1.ModelCrudEventType.create, data: { uid: 'x4', model: 'ce' } }, ctx);
+        }));
+        expect(session.attempts()).toBeGreaterThan(1); // the callback really did run twice
+        expect(published).toHaveLength(1); // and the queue kept only the last attempt
+    }));
+    it('publishes immediately - and without the session - when there is no transaction', () => __awaiter(void 0, void 0, void 0, function* () {
+        jest.spyOn(ctrl, 'supportsTransactions').mockResolvedValue(false);
+        const handMadeSession = { id: 'by-hand' };
+        coded_entity_model_1.ceModel.publishCRUDEvent({ type: enums_1.ModelCrudEventType.create, data: { uid: 'x5', model: 'ce' } }, { i18n: 'it', session: handMadeSession });
+        expect(published).toHaveLength(1);
+        expect(published[0].context.session).toBeUndefined();
+        expect(published[0].context.i18n).toBe('it');
+    }));
+});
+describe('PubSubManager - a failing subscriber cannot take the process down', () => {
+    it('handles the rejection of an async subscriber instead of leaving it unhandled', () => __awaiter(void 0, void 0, void 0, function* () {
+        const pubSub = new pubsub_manager_1.PubSubManager();
+        const seen = [];
+        const onUnhandled = (err) => seen.push(err);
+        process.on('unhandledRejection', onUnhandled);
+        const id = pubSub.subscribe('probe.key', () => __awaiter(void 0, void 0, void 0, function* () { throw new Error('subscriber failed'); }));
+        pubSub.publish('probe.key', { any: 'payload' }, {});
+        // Let the microtask queue run: an unhandled rejection would be reported by now.
+        yield new Promise(resolve => setImmediate(resolve));
+        yield new Promise(resolve => setImmediate(resolve));
+        process.off('unhandledRejection', onUnhandled);
+        expect(seen).toHaveLength(0);
+        pubSub.unsubscribe(id);
+    }));
+    it('really detaches the subscriber it registered', () => __awaiter(void 0, void 0, void 0, function* () {
+        const pubSub = new pubsub_manager_1.PubSubManager();
+        let calls = 0;
+        const id = pubSub.subscribe('probe.detach', () => { calls++; });
+        pubSub.publish('probe.detach', {}, {});
+        pubSub.unsubscribe(id);
+        pubSub.publish('probe.detach', {}, {});
+        expect(calls).toBe(1); // the second publish must not reach a detached subscriber
+    }));
+});

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

@@ -146,8 +146,33 @@ export declare abstract class BaseController<TAttrs, TDoc extends BaseMongoDoc,
      *  - `session.withTransaction` may re-run `fn` on transient errors, so `fn` MUST
      *    keep non-DB side effects (e.g. publishing) OUTSIDE the transaction.
      *
+     * DEFERRED EMISSIONS. A CRUD publication asked for INSIDE the transaction is held back and
+     * released only after the commit. Without this the subscribers were handed a context carrying
+     * the live session, their work was never awaited by the caller, and whatever they had in
+     * flight met that session the moment `withTransaction` committed and `endSession` closed it -
+     * a rejection nobody was listening for, which is an uncaught rejection and, with the usual
+     * process handler, a shutdown. Queueing also makes the emission mean what it says: an event
+     * announcing a write that the database has not yet accepted is a lie the subscribers cannot
+     * detect, and on an abort it would announce a write that never happened.
+     *
      * @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>;
+    /**
+     * Releases the emissions a committed transaction held back.
+     *
+     * Two properties, both deliberate:
+     *
+     *  - the subscribers are handed a context WITHOUT the session (and without the queue). The
+     *    transaction is over; a subscriber that joined it would be writing into a session that is
+     *    about to be closed, which is the failure this whole mechanism removes;
+     *  - a subscriber that throws SYNCHRONOUSLY cannot stop the flush or fail the caller's write,
+     *    which has already committed. It is logged and the remaining emissions still go out. An
+     *    asynchronous rejection is guarded one level down, where the subscriber is invoked
+     *    (`PubSubManager.subscribe`), because that is the only place that can see the promise.
+     *
+     * @param deferred the queue opened for the transaction that has just committed
+     */
+    private flushDeferredEvents;
 }

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

@@ -8,8 +8,20 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseController = void 0;
+const constants_1 = require("../constants");
 /**
  * Merges the options the PARSE decided with the ones the CALLER asked for, leaving both untouched.
  *
@@ -226,23 +238,42 @@ class BaseController {
      *  - `session.withTransaction` may re-run `fn` on transient errors, so `fn` MUST
      *    keep non-DB side effects (e.g. publishing) OUTSIDE the transaction.
      *
+     * DEFERRED EMISSIONS. A CRUD publication asked for INSIDE the transaction is held back and
+     * released only after the commit. Without this the subscribers were handed a context carrying
+     * the live session, their work was never awaited by the caller, and whatever they had in
+     * flight met that session the moment `withTransaction` committed and `endSession` closed it -
+     * a rejection nobody was listening for, which is an uncaught rejection and, with the usual
+     * process handler, a shutdown. Queueing also makes the emission mean what it says: an event
+     * announcing a write that the database has not yet accepted is a lie the subscribers cannot
+     * detect, and on an abort it would announce a write that never happened.
+     *
      * @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)
+            // already inside a transaction → reuse it (nested call, no new session). The queue of the
+            // OUTER call travels with the context, so an inner emission is released by the outer commit.
             if (context === null || context === void 0 ? void 0 : context.session)
                 return fn(context);
-            // standalone deployment → no atomicity available, run as today
+            // standalone deployment → no atomicity available, run as today. Nothing to wait for either:
+            // with no transaction there is no commit to defer to, so emissions leave immediately.
             if (!(yield this.supportsTransactions()))
                 return fn(context);
             const session = yield this.model.mgModel.startSession();
+            const deferred = [];
             try {
                 let result;
                 yield session.withTransaction(() => __awaiter(this, void 0, void 0, function* () {
-                    result = yield fn(Object.assign(Object.assign({}, context), { session }));
+                    // `withTransaction` MAY RE-RUN this callback on a transient error. Anything queued by a
+                    // previous attempt belongs to a transaction that did not commit, so it is dropped here
+                    // rather than emitted twice.
+                    deferred.length = 0;
+                    result = yield fn(Object.assign(Object.assign({}, context), { session, deferredEvents: deferred }));
                 }));
+                // Committed, and only now. An abort never reaches this line: the throw propagates and the
+                // queue is discarded with the stack, which is exactly the intended behaviour.
+                this.flushDeferredEvents(deferred);
                 return result;
             }
             finally {
@@ -250,5 +281,33 @@ class BaseController {
             }
         });
     }
+    /**
+     * Releases the emissions a committed transaction held back.
+     *
+     * Two properties, both deliberate:
+     *
+     *  - the subscribers are handed a context WITHOUT the session (and without the queue). The
+     *    transaction is over; a subscriber that joined it would be writing into a session that is
+     *    about to be closed, which is the failure this whole mechanism removes;
+     *  - a subscriber that throws SYNCHRONOUSLY cannot stop the flush or fail the caller's write,
+     *    which has already committed. It is logged and the remaining emissions still go out. An
+     *    asynchronous rejection is guarded one level down, where the subscriber is invoked
+     *    (`PubSubManager.subscribe`), because that is the only place that can see the promise.
+     *
+     * @param deferred the queue opened for the transaction that has just committed
+     */
+    flushDeferredEvents(deferred) {
+        var _a, _b;
+        for (const ev of deferred) {
+            const _c = ev.context, { session, deferredEvents } = _c, ctx = __rest(_c, ["session", "deferredEvents"]);
+            try {
+                (_a = constants_1.APP.nxPubSub) === null || _a === void 0 ? void 0 : _a.publish(ev.key, ev.data, ctx);
+            }
+            catch (err) {
+                (_b = constants_1.APP.logger) === null || _b === void 0 ? void 0 : _b.error(`Deferred event [${ev.key}] failed to publish after commit: ${err}`);
+            }
+        }
+        deferred.length = 0;
+    }
 }
 exports.BaseController = BaseController;

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

@@ -85,11 +85,10 @@ export declare class BaseModel<TAttrs, TDoc extends BaseMongoDoc, TMongoModel ex
     aggregateNativeFiltered(pipeline: mongoose.PipelineStage[], params: FilterParams | undefined, context: NxContext): Promise<mongoose.mongo.AggregationCursor<any> | null>;
     /**
      *
-     * @param {*} pipeline
-     * @param {*} params
-     * @param {*} context
+     * @param pipeline
+     * @param options
      */
-    aggregateNative(pipeline: mongoose.PipelineStage[]): mongoose.mongo.AggregationCursor<any>;
+    aggregateNative(pipeline: mongoose.PipelineStage[], options?: mongoose.mongo.AggregateOptions): mongoose.mongo.AggregationCursor<any>;
     /**
      * Simple Find wrapper
      * @param {*} params
@@ -442,9 +441,19 @@ export declare class BaseModel<TAttrs, TDoc extends BaseMongoDoc, TMongoModel ex
      */
     bulkRemove(ids: string, context: NxContext): Promise<TDoc[]>;
     /**
+     * Announce a CRUD write to the in-process subscribers.
      *
-     * @param {*} evt
-     * @param {*} context
+     * WHEN A TRANSACTION IS OPEN THE EMISSION IS QUEUED, not published: the context carries the
+     * queue that `BaseController.withTransaction` opened, and the flush happens after the commit.
+     * Publishing here would announce a write the database has not accepted yet, and would hand the
+     * subscribers a live session that the caller is about to close.
+     *
+     * OUTSIDE a transaction the emission goes out immediately, as it always has - but the session,
+     * if the caller put one on the context by hand, is REMOVED first. A subscriber must never join
+     * a transaction whose lifetime it does not control and whose end it cannot see.
+     *
+     * @param evt     the CRUD event to announce
+     * @param context the context of the write; decides whether this waits for a commit
      */
     publishCRUDEvent(evt: CrudItemEvent, context?: NxContext): void;
     /**

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

@@ -175,12 +175,11 @@ class BaseModel extends events_1.EventEmitter {
     }
     /**
      *
-     * @param {*} pipeline
-     * @param {*} params
-     * @param {*} context
+     * @param pipeline
+     * @param options
      */
-    aggregateNative(pipeline) {
-        return this.mgModel.collection.aggregate(pipeline, { allowDiskUse: true });
+    aggregateNative(pipeline, options = {}) {
+        return this.mgModel.collection.aggregate(pipeline, Object.assign({ allowDiskUse: true }, options));
     }
     /**
      * Simple Find wrapper
@@ -928,9 +927,19 @@ class BaseModel extends events_1.EventEmitter {
         return Promise.all(promises);
     }
     /**
+     * Announce a CRUD write to the in-process subscribers.
      *
-     * @param {*} evt
-     * @param {*} context
+     * WHEN A TRANSACTION IS OPEN THE EMISSION IS QUEUED, not published: the context carries the
+     * queue that `BaseController.withTransaction` opened, and the flush happens after the commit.
+     * Publishing here would announce a write the database has not accepted yet, and would hand the
+     * subscribers a live session that the caller is about to close.
+     *
+     * OUTSIDE a transaction the emission goes out immediately, as it always has - but the session,
+     * if the caller put one on the context by hand, is REMOVED first. A subscriber must never join
+     * a transaction whose lifetime it does not control and whose end it cannot see.
+     *
+     * @param evt     the CRUD event to announce
+     * @param context the context of the write; decides whether this waits for a commit
      */
     publishCRUDEvent(evt, context = {}) {
         var _a;
@@ -938,7 +947,12 @@ class BaseModel extends events_1.EventEmitter {
             return;
         if (context === null || context === void 0 ? void 0 : context.evtType)
             evt.type = context.evtType;
-        (_a = constants_1.APP.nxPubSub) === null || _a === void 0 ? void 0 : _a.publish(constants_1.MODEL_CRUD_EVENT, evt, context);
+        if (context === null || context === void 0 ? void 0 : context.deferredEvents) {
+            context.deferredEvents.push({ key: constants_1.MODEL_CRUD_EVENT, data: evt, context });
+            return;
+        }
+        const { session, deferredEvents } = context, ctx = __rest(context, ["session", "deferredEvents"]);
+        (_a = constants_1.APP.nxPubSub) === null || _a === void 0 ? void 0 : _a.publish(constants_1.MODEL_CRUD_EVENT, evt, ctx);
     }
     /**
      *

package/build/common/interfaces.d.ts

@@ -12,6 +12,26 @@ export interface NxContext {
     res?: Response;
     i18n?: string;
     session?: ClientSession;
+    /**
+     * Emissions held back until the transaction that produced them has COMMITTED.
+     *
+     * Opened by `BaseController.withTransaction` on the child context and, from there, carried
+     * down to every model op. Its presence is the signal that a publication must wait: see
+     * `BaseModel.publishCRUDEvent`. It is transport-agnostic bookkeeping, not application data,
+     * and it never reaches a subscriber - the flush strips it along with the session.
+     */
+    deferredEvents?: DeferredEvent[];
+}
+/**
+ * One publication, captured at the moment it was asked for and released after the commit.
+ *
+ * The context is kept as it was so the subscriber still sees the user, the language and the
+ * rest of it; only `session` and `deferredEvents` are removed on the way out.
+ */
+export interface DeferredEvent {
+    key: string;
+    data: any;
+    context: NxContext;
 }
 export interface NxJwtData extends NxObject {
     rls?: string[];

package/build/common/manager/pubsub-manager.d.ts

@@ -1,9 +1,20 @@
 import { NxContext } from '../interfaces';
 export declare class PubSubManager {
     /**
+     * Register `method` for `key`.
      *
-     * @param {*} key
-     * @param {*} method
+     * THE SUBSCRIBER IS WRAPPED, for one reason: `EventEmitter.emit` calls a listener and throws
+     * its return value away. An async subscriber therefore leaves a promise nobody holds, and if
+     * it rejects the process sees an unhandled rejection - which, with the usual process-level
+     * handler, takes the service down over a failure in one listener. The wrapper is the only
+     * place that can see that promise, so it is the only place the rejection can be handled.
+     *
+     * A failing subscriber is logged and the publication continues: a publisher never learns that
+     * a listener failed, and must not, because the write it announced has already happened.
+     *
+     * @param key    the event name
+     * @param method the subscriber; ignored when it is not a function
+     * @returns the subscription id, to be passed back to `unsubscribe`
      */
     subscribe(key: string, method: Function): string;
     /**

package/build/common/manager/pubsub-manager.js

@@ -2,21 +2,49 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PubSubManager = void 0;
 const events_1 = require("events");
+const constants_1 = require("../constants");
 const utils_1 = require("../utils");
 const subs = {};
 const eventsEmitter = new events_1.EventEmitter();
 class PubSubManager {
     /**
+     * Register `method` for `key`.
      *
-     * @param {*} key
-     * @param {*} method
+     * THE SUBSCRIBER IS WRAPPED, for one reason: `EventEmitter.emit` calls a listener and throws
+     * its return value away. An async subscriber therefore leaves a promise nobody holds, and if
+     * it rejects the process sees an unhandled rejection - which, with the usual process-level
+     * handler, takes the service down over a failure in one listener. The wrapper is the only
+     * place that can see that promise, so it is the only place the rejection can be handled.
+     *
+     * A failing subscriber is logged and the publication continues: a publisher never learns that
+     * a listener failed, and must not, because the write it announced has already happened.
+     *
+     * @param key    the event name
+     * @param method the subscriber; ignored when it is not a function
+     * @returns the subscription id, to be passed back to `unsubscribe`
      */
     subscribe(key, method) {
         if (!(0, utils_1.isFunction)(method))
             return '';
         const id = (0, utils_1.uuid)();
-        subs[id] = { key, method };
-        eventsEmitter.on(key, (data, context) => method(data, context));
+        const guarded = (data, context) => {
+            var _a;
+            try {
+                const result = method(data, context);
+                if (result && typeof result.then === 'function')
+                    result.catch((err) => {
+                        var _a;
+                        (_a = constants_1.APP.logger) === null || _a === void 0 ? void 0 : _a.error(`Subscriber of [${key}] rejected: ${err}`);
+                    });
+            }
+            catch (err) {
+                (_a = constants_1.APP.logger) === null || _a === void 0 ? void 0 : _a.error(`Subscriber of [${key}] threw: ${err}`);
+            }
+        };
+        // The GUARDED function is what gets registered, so it is also what `unsubscribe` must
+        // remove: `off` compares by reference and would not find the original `method`.
+        subs[id] = { key, method, guarded };
+        eventsEmitter.on(key, guarded);
         return id;
     }
     /**
@@ -32,7 +60,7 @@ class PubSubManager {
      * @param {*} id
      */
     unsubscribe(id) {
-        eventsEmitter.off(subs[id].key, subs[id].method);
+        eventsEmitter.off(subs[id].key, subs[id].guarded);
     }
 }
 exports.PubSubManager = PubSubManager;

package/package.json

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