@nextage/nx-frame-be 1.0.48 → 1.0.49

package/build/common/base/__test__/base.model.unset-paths.test.d.ts

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

package/build/common/base/__test__/base.model.unset-paths.test.js

@@ -0,0 +1,149 @@
+"use strict";
+/* ────────────────────────────────────────────────────────────────────────────
+ * BaseModel.update - the `unsetPaths` option
+ *
+ * An update payload can say two things about a property: absent means PRESERVE, and present
+ * means set it. It cannot say REMOVE IT - a property set to `undefined` does not survive the
+ * merge, because lodash skips undefined source values, and an absent key is preserved by
+ * design. `unsetPaths` is the third statement.
+ *
+ * WHAT THESE TESTS GUARD, beyond the option itself: that adding an optional argument did not
+ * disturb the two call shapes that already existed. The overloads are told apart by the TYPE
+ * of the third argument, and a check on the PRESENCE of the fourth - which is what the code
+ * did before - would leave the context empty as soon as options are passed, turning a scoped
+ * read and write into an unscoped one without any error.
+ * ──────────────────────────────────────────────────────────────────────────── */
+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());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const mongoose_1 = __importDefault(require("mongoose"));
+const base_model_1 = require("../base.model");
+const mongo_utils_1 = require("../mongo-utils");
+class UnsetEntity extends base_model_1.BaseModel {
+}
+const schema = {
+    code: { type: String, required: true },
+    name: { type: String, required: true },
+    note: { type: String }, // optional scalar: the unset target
+    data: { type: mongoose_1.default.SchemaTypes.Mixed }, // holds the dotted scalar path
+    // Declared because the audit only stamps what the schema declares: it is what lets the third
+    // case below prove that the CONTEXT was read as such and not mistaken for the options.
+    updatedBy: { type: String },
+    updatedAt: { type: Date }
+};
+const model = (0, mongo_utils_1.createModel)({
+    name: 'UnsetEntity',
+    modelName: 'UnsetEntity',
+    collection: 'unsetEntity',
+    classDef: UnsetEntity,
+    mergeSchema: false,
+    modelParams: { sort: { code: 1 } },
+    schema
+}, false);
+/** The document as MONGO holds it: the only place where "absent" and "null" tell apart. */
+const raw = (id) => mongoose_1.default.connection.db.collection('unsetEntity').findOne({ _id: new mongoose_1.default.Types.ObjectId(id) });
+const seed = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (attrs = {}) { return model.create(Object.assign({ code: 'C1', name: 'N1', note: 'to-remove', data: { keep: 'k', drop: 'd' } }, attrs), {}); });
+describe('BaseModel.update - legacy call shapes stay untouched', () => {
+    it('1. (id, item, context) keeps working and applies the payload', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield seed();
+        const updated = yield model.update(doc.id, { name: 'N2' }, {});
+        expect(updated.name).toEqual('N2');
+        expect(updated.code).toEqual('C1');
+        expect(updated.version).toEqual(doc.version + 1);
+    }));
+    it('2. (id, item, mergeItem, context) keeps working, and the merge still preserves', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield seed();
+        const updated = yield model.update(doc.id, { name: 'N2' }, true, {});
+        expect(updated.name).toEqual('N2');
+        expect(updated.note).toEqual('to-remove'); // absent from the payload: preserved
+    }));
+});
+describe('BaseModel.update - the context is not lost when options are passed', () => {
+    it('3. (id, item, context, options) reads the third argument as the CONTEXT', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield seed();
+        // The context carries a user here: were the third argument misread as options - the trap the
+        // dispatch had to avoid - the audit stamp would silently go missing.
+        const ctx = { user: { id: 'u-1' } };
+        const updated = yield model.update(doc.id, { name: 'N2' }, ctx, { unsetPaths: ['note'] });
+        expect(updated.name).toEqual('N2');
+        expect(updated.updatedBy).toEqual('u-1');
+        expect(yield raw(doc.id)).not.toHaveProperty('note');
+    }));
+    it('4. (id, item, mergeItem, context, options) works in the five-argument shape', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield seed();
+        const updated = yield model.update(doc.id, { name: 'N2' }, true, {}, { unsetPaths: ['note'] });
+        expect(updated.name).toEqual('N2');
+        expect(yield raw(doc.id)).not.toHaveProperty('note');
+    }));
+});
+describe('BaseModel.update - unsetPaths', () => {
+    it('5. mergeUpdate with an absent property preserves the persisted value', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield seed();
+        yield model.update(doc.id, { name: 'N2' }, true, {});
+        const after = yield raw(doc.id);
+        expect(after.note).toEqual('to-remove');
+    }));
+    it('6. mergeUpdate + unsetPaths REMOVES the key, it does not null it', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield seed();
+        yield model.update(doc.id, { name: 'N2' }, true, {}, { unsetPaths: ['note'] });
+        const after = yield raw(doc.id);
+        expect(after).not.toHaveProperty('note'); // the key is gone
+        expect(after.note).toBeUndefined(); // and not sitting there as null
+        expect(after.name).toEqual('N2');
+    }));
+    it('7. unsetting a path that is already absent is a no-op', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield seed({ note: undefined });
+        const before = yield raw(doc.id);
+        expect(before).not.toHaveProperty('note');
+        const updated = yield model.update(doc.id, {}, true, {}, { unsetPaths: ['note'] });
+        expect(yield raw(doc.id)).not.toHaveProperty('note');
+        expect(updated.code).toEqual('C1');
+    }));
+    it('8. sets one field and unsets another in the SAME update, with one version step', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield seed();
+        const updated = yield model.update(doc.id, { name: 'N2' }, true, {}, { unsetPaths: ['note'] });
+        const after = yield raw(doc.id);
+        expect(after.name).toEqual('N2');
+        expect(after).not.toHaveProperty('note');
+        expect(updated.version).toEqual(doc.version + 1); // one save, one version
+    }));
+    it('9. removes a DOTTED path to a scalar, leaving its siblings alone', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield seed();
+        yield model.update(doc.id, {}, true, {}, { unsetPaths: ['data.drop'] });
+        const after = yield raw(doc.id);
+        expect(after.data).toEqual({ keep: 'k' });
+    }));
+    it('10. re-applies the removal on the VersionError retry, without bypassing it', () => __awaiter(void 0, void 0, void 0, function* () {
+        const doc = yield seed();
+        // A concurrent writer bumps the version between the read and the save of the FIRST attempt:
+        // mongoose raises a VersionError, the loop re-reads and retries. The removal must reach the
+        // document read by the retry too - which is why it is applied inside the loop.
+        const original = model.get.bind(model);
+        let raced = false;
+        const spy = jest.spyOn(model, 'get').mockImplementation((...args) => __awaiter(void 0, void 0, void 0, function* () {
+            const found = yield original(...args);
+            if (!raced) {
+                raced = true;
+                yield mongoose_1.default.connection.db.collection('unsetEntity')
+                    .updateOne({ _id: new mongoose_1.default.Types.ObjectId(doc.id) }, { $inc: { version: 1 } });
+            }
+            return found;
+        }));
+        yield model.update(doc.id, { name: 'N2' }, true, {}, { unsetPaths: ['note'] });
+        expect(spy).toHaveBeenCalledTimes(2); // first attempt + retry
+        const after = yield raw(doc.id);
+        expect(after).not.toHaveProperty('note');
+        expect(after.name).toEqual('N2');
+        spy.mockRestore();
+    }));
+});

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

@@ -2,6 +2,7 @@ import mongoose from 'mongoose';
 import { NxContext, NxObject } from '../interfaces';
 import { BaseModel } from './base.model';
 import { ArrayItemParams, BaseMongoDoc } from './base.interfaces';
+import { UpdateOptions } from './base.interfaces';
 import { FilterParams, QueryPagination } from './base.interfaces';
 export declare abstract class BaseController<TAttrs, TDoc extends BaseMongoDoc, T extends BaseModel<TAttrs, TDoc, any>> {
     model: T;
@@ -77,7 +78,7 @@ export declare abstract class BaseController<TAttrs, TDoc extends BaseMongoDoc,
      * @param context
      * @returns
      */
-    update(id: string, item: TAttrs, context: NxContext): Promise<TDoc>;
+    update(id: string, item: TAttrs, context: NxContext, options?: UpdateOptions): Promise<TDoc>;
     /**
      *
      * @param id

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

@@ -112,10 +112,12 @@ class BaseController {
      * @param context
      * @returns
      */
-    update(id, item, context) {
+    update(id, item, context, options) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.parseUpdateItem(id, item, context);
-            return this.model.update(id, item, this.mergeUpdate, context);
+            // The options belong to THIS update and are handed over untouched: the controller does not
+            // read them and does not interpret them.
+            return this.model.update(id, item, this.mergeUpdate, context, options);
         });
     }
     /**

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

@@ -33,6 +33,30 @@ export interface QueryPagination {
     limit?: number;
     sort?: NxObject;
 }
+/**
+ * Options of a SINGLE update, describing the mutation and not the operation context - which is
+ * why they travel as an argument and never inside `NxContext`: a context is reused across calls,
+ * and an option that outlived its own update would silently apply to the next one.
+ */
+export interface UpdateOptions {
+    /**
+     * Paths to REMOVE from the document.
+     *
+     * WHY IT CANNOT BE EXPRESSED BY THE PAYLOAD. An absent property means PRESERVE, and a property
+     * set to `undefined` does not survive the merge - lodash skips undefined source values - so
+     * neither of the two can ask for a removal. This option is the third statement: remove it.
+     *
+     * The paths are applied AFTER the merge, on the same hydrated document and inside the SAME
+     * `save()`: same session, same versioning, same VersionError retry, and no second write.
+     *
+     * CONTRACT, deliberately conservative in this first form: TOP-LEVEL paths and DOTTED paths to
+     * SCALAR fields. Arrays and positional paths are out of scope and untested.
+     *
+     * A path that is already absent is a no-op, and a path the schema declares `required` fails
+     * the ordinary mongoose validation on save: no bypass is introduced here.
+     */
+    unsetPaths?: string[];
+}
 export interface ArrayItemParams {
     arrayPath: string;
     item: NxObject;

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

@@ -5,6 +5,7 @@ import { BaseMongoDoc, BaseMongoModel } from './base.interfaces';
 import { ArrayItemParams, ChangeStreamData } from './base.interfaces';
 import { CrudItemEvent, FilterParams } from './base.interfaces';
 import { QueryPagination } from './base.interfaces';
+import { UpdateOptions } from './base.interfaces';
 import { ModelData } from './mongo.types';
 export declare class BaseModel<TAttrs, TDoc extends BaseMongoDoc, TMongoModel extends BaseMongoModel<TAttrs, TDoc>> extends EventEmitter {
     name: string;
@@ -288,8 +289,8 @@ export declare class BaseModel<TAttrs, TDoc extends BaseMongoDoc, TMongoModel ex
      * @param {*} callback
      */
     insertManyNative(items: mongoose.mongo.OptionalId<Document>[], options: mongoose.mongo.BulkWriteOptions): Promise<mongoose.mongo.InsertManyResult<mongoose.mongo.BSON.Document>>;
-    update(id: string, item: TAttrs, context: NxContext): Promise<TDoc>;
-    update(id: string, item: TAttrs, mergeItem: boolean, context: NxContext): Promise<TDoc>;
+    update(id: string, item: TAttrs, context: NxContext, options?: UpdateOptions): Promise<TDoc>;
+    update(id: string, item: TAttrs, mergeItem: boolean, context: NxContext, options?: UpdateOptions): Promise<TDoc>;
     /**
      * Update document using mongodb generic method
      *

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

@@ -574,18 +574,18 @@ class BaseModel extends events_1.EventEmitter {
      *
      * @param {*} id
      * @param {*} item
+     * @param {*} options optional per-update options, currently `unsetPaths`
      */
-    update(id, item, param3, param4) {
+    update(id, item, param3, param4, param5) {
         return __awaiter(this, void 0, void 0, function* () {
-            let mergeItem = false;
-            let context = {};
-            if (!param4) {
-                context = param3;
-            }
-            else if (typeof param3 === 'boolean') {
-                mergeItem = param3;
-                context = param4;
-            }
+            var _a, _b, _c;
+            // The overloads are told apart by the TYPE of the third argument, never by the presence of the
+            // fourth: the optional options object makes the fourth argument present in both forms, and a
+            // check on its presence would leave `context` empty - an unscoped read and write, in silence.
+            const byMerge = typeof param3 === 'boolean';
+            const mergeItem = byMerge ? param3 : false;
+            const context = ((_a = (byMerge ? param4 : param3)) !== null && _a !== void 0 ? _a : {});
+            const options = ((_b = (byMerge ? param5 : param4)) !== null && _b !== void 0 ? _b : {});
             item = yield this.beforeUpdate(item, context);
             //const res = await this.mgModel.findByIdAndUpdate(id, { $set: item }, { new: true });
             //const itemDoc = this.mgModel.build(Object.assign({ id, item }));
@@ -611,6 +611,12 @@ class BaseModel extends events_1.EventEmitter {
                     });
                 }
                 itemDoc.set(toApply);
+                // Explicit removals, AFTER the merge and on the same hydrated document: mongoose turns a
+                // path set to `undefined` into a real removal at save time, so this needs no second write
+                // and keeps the session, the versioning and the retry of this very loop. Applied INSIDE the
+                // loop on purpose: a retry re-reads the document, and the removals must reach that one too.
+                for (const path of (_c = options.unsetPaths) !== null && _c !== void 0 ? _c : [])
+                    itemDoc.set(path, undefined);
                 try {
                     res = yield itemDoc.save({ session: context === null || context === void 0 ? void 0 : context.session });
                     break;

package/build/common/index.d.ts

@@ -6,6 +6,7 @@ export * from './interfaces';
 export * from './types';
 export * from './manager';
 export * from './utils';
+export type { UpdateOptions } from './base/base.interfaces';
 export * from './base/tenancy';
 export * from './base/audit';
 export * from './express';

package/package.json

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