@nextage/nx-frame-be 1.0.40 → 1.0.42

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/graphql/__test__/registry.test.d.ts

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

package/build/common/graphql/__test__/registry.test.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const coded_entity_controller_1 = require("../../models/coded-entity.controller");
+const loader_1 = require("../loader");
+const registry_1 = require("../registry");
+/**
+ * `SchemaRegistry` defers `generateSchema`/`loadSchema` until `apply`, so module
+ * LOADING is decoupled from schema MUTATION. These tests assert the deferral,
+ * the single-shot application and the reset semantics used for test isolation.
+ */
+describe('SchemaRegistry', () => {
+    afterEach(() => registry_1.schemaRegistry.reset());
+    it('starts empty', () => {
+        expect(registry_1.schemaRegistry.count).toBe(0);
+    });
+    it('defers registerSchema until apply', () => {
+        const marker = 'registryProbeField: String';
+        registry_1.schemaRegistry.registerSchema({ typeDefs: { query: marker } });
+        // registration is recorded but NOT yet folded into mainSchema
+        expect(registry_1.schemaRegistry.count).toBe(1);
+        expect(loader_1.mainSchema.typeDefs.query).not.toContain('registryProbeField');
+        registry_1.schemaRegistry.apply();
+        expect(loader_1.mainSchema.typeDefs.query).toContain('registryProbeField');
+    });
+    it('defers register (controller) until apply', () => {
+        const params = {
+            fields: { type: 'id: String', query: 'code: String', input: 'code: String' }
+        };
+        registry_1.schemaRegistry.register(coded_entity_controller_1.ceCtrl, params);
+        // the CRUD query name is generated by generateSchema at apply time only
+        expect(registry_1.schemaRegistry.count).toBe(1);
+        expect(loader_1.mainSchema.typeDefs.query).not.toContain('codedEntityList');
+        registry_1.schemaRegistry.apply();
+        expect(loader_1.mainSchema.typeDefs.query).toContain('codedEntityList');
+    });
+    it('reset clears every registration', () => {
+        registry_1.schemaRegistry.registerSchema({ typeDefs: { query: 'a: String' } });
+        registry_1.schemaRegistry.registerSchema({ typeDefs: { query: 'b: String' } });
+        expect(registry_1.schemaRegistry.count).toBe(2);
+        registry_1.schemaRegistry.reset();
+        expect(registry_1.schemaRegistry.count).toBe(0);
+    });
+    it('exposes a class for isolated instances', () => {
+        const local = new registry_1.SchemaRegistry();
+        local.registerSchema({ typeDefs: { query: 'c: String' } });
+        expect(local.count).toBe(1);
+        expect(registry_1.schemaRegistry.count).toBe(0);
+    });
+});

package/build/common/graphql/index.d.ts

@@ -1,4 +1,5 @@
 export * from './directives';
 export * from './loader';
 export * from './generator';
+export * from './registry';
 export * from './utils';

package/build/common/graphql/index.js

@@ -17,5 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./directives"), exports);
 __exportStar(require("./loader"), exports);
 __exportStar(require("./generator"), exports);
+__exportStar(require("./registry"), exports);
 __exportStar(require("./utils"), exports);
 //export * from './scalars';

package/build/common/graphql/registry.d.ts

@@ -0,0 +1,47 @@
+import { BaseController } from '../base/base.controller';
+import { NxGraphQLSchemaData, NxGraphQLSchemaExtension } from './interfaces';
+/**
+ * Deferred GraphQL schema-assembly registry.
+ *
+ * Historically every nx-app GraphQL leaf mutated the global `mainSchema` at
+ * import time by calling `generateSchema`/`loadSchema` as a module side-effect.
+ * That coupled module LOADING (which files get imported, and in what order) with
+ * schema MUTATION, and left the registered set invisible and non-resettable.
+ *
+ * With this registry a leaf instead REGISTERS its module — a controller plus a
+ * schema extension, or a raw typeDefs/resolvers block — deferring the actual
+ * `generateSchema`/`loadSchema` call. The bootstrap `graphql` phase discovers and
+ * imports the leaves (which call {@link register}/{@link registerSchema}) and then
+ * calls {@link apply} ONCE to fold every module into `mainSchema`.
+ *
+ * Benefits: loading is order-independent (filesystem discovery), mutation is a
+ * single explicit logged step, and the registered set is inspectable ({@link count})
+ * and resettable ({@link reset}) for test isolation.
+ */
+export declare class SchemaRegistry {
+    private deferred;
+    /**
+     * Register a controller-backed module. Mirrors {@link generateSchema}'s
+     * signature verbatim; the call is deferred until {@link apply}.
+     */
+    register<T extends BaseController<any, any, any>>(controller: T, schema?: NxGraphQLSchemaExtension, mergeCodedEntity?: boolean, readOnly?: boolean): void;
+    /**
+     * Register a raw typeDefs/resolvers block (no controller). Mirrors
+     * {@link loadSchema}; the call is deferred until {@link apply}.
+     */
+    registerSchema(data: NxGraphQLSchemaData): void;
+    /**
+     * Fold every registered module into the global `mainSchema`. Call ONCE from
+     * the bootstrap `graphql` phase, after all leaves have been imported.
+     */
+    apply(): void;
+    /** Clear all registrations (test isolation). */
+    reset(): void;
+    /** Number of modules registered so far. */
+    get count(): number;
+}
+/**
+ * Process-wide GraphQL schema registry singleton. nx-app leaves import this and
+ * call `register`/`registerSchema`; the bootstrap `graphql` phase calls `apply`.
+ */
+export declare const schemaRegistry: SchemaRegistry;

package/build/common/graphql/registry.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schemaRegistry = exports.SchemaRegistry = void 0;
+const constants_1 = require("../constants");
+const generator_1 = require("./generator");
+const loader_1 = require("./loader");
+/**
+ * Deferred GraphQL schema-assembly registry.
+ *
+ * Historically every nx-app GraphQL leaf mutated the global `mainSchema` at
+ * import time by calling `generateSchema`/`loadSchema` as a module side-effect.
+ * That coupled module LOADING (which files get imported, and in what order) with
+ * schema MUTATION, and left the registered set invisible and non-resettable.
+ *
+ * With this registry a leaf instead REGISTERS its module — a controller plus a
+ * schema extension, or a raw typeDefs/resolvers block — deferring the actual
+ * `generateSchema`/`loadSchema` call. The bootstrap `graphql` phase discovers and
+ * imports the leaves (which call {@link register}/{@link registerSchema}) and then
+ * calls {@link apply} ONCE to fold every module into `mainSchema`.
+ *
+ * Benefits: loading is order-independent (filesystem discovery), mutation is a
+ * single explicit logged step, and the registered set is inspectable ({@link count})
+ * and resettable ({@link reset}) for test isolation.
+ */
+class SchemaRegistry {
+    constructor() {
+        this.deferred = [];
+    }
+    /**
+     * Register a controller-backed module. Mirrors {@link generateSchema}'s
+     * signature verbatim; the call is deferred until {@link apply}.
+     */
+    register(controller, schema = {}, mergeCodedEntity = false, readOnly = false) {
+        this.deferred.push(() => (0, generator_1.generateSchema)(controller, schema, mergeCodedEntity, readOnly));
+    }
+    /**
+     * Register a raw typeDefs/resolvers block (no controller). Mirrors
+     * {@link loadSchema}; the call is deferred until {@link apply}.
+     */
+    registerSchema(data) {
+        this.deferred.push(() => (0, loader_1.loadSchema)(data));
+    }
+    /**
+     * Fold every registered module into the global `mainSchema`. Call ONCE from
+     * the bootstrap `graphql` phase, after all leaves have been imported.
+     */
+    apply() {
+        this.deferred.forEach(run => run());
+        constants_1.APP.logger.info(`🧩 GraphQL registry: applied ${this.deferred.length} schema module(s)`);
+    }
+    /** Clear all registrations (test isolation). */
+    reset() {
+        this.deferred = [];
+    }
+    /** Number of modules registered so far. */
+    get count() {
+        return this.deferred.length;
+    }
+}
+exports.SchemaRegistry = SchemaRegistry;
+/**
+ * Process-wide GraphQL schema registry singleton. nx-app leaves import this and
+ * call `register`/`registerSchema`; the bootstrap `graphql` phase calls `apply`.
+ */
+exports.schemaRegistry = new SchemaRegistry();

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.42",
   "description": "",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",