@naturalcycles/db-lib 8.55.1 → 8.57.0

package/dist/commondao/common.dao.d.ts

@@ -4,7 +4,7 @@ import { AnyObject, AsyncMapper, JsonSchemaObject, JsonSchemaRootObject, ObjectW
 import { AjvSchema, ObjectSchema, ReadableTyped } from '@naturalcycles/nodejs-lib';
 import { DBDeleteByIdsOperation, DBModelType, DBOperation, DBPatch, DBSaveBatchOperation, RunQueryResult } from '../db.model';
 import { DBQuery, RunnableDBQuery } from '../query/dbQuery';
-import { CommonDaoCfg, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoSaveOptions, CommonDaoStreamDeleteOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions, CommonDaoStreamSaveOptions } from './common.dao.model';
+import { CommonDaoCfg, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoSaveBatchOptions, CommonDaoSaveOptions, CommonDaoStreamDeleteOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions, CommonDaoStreamSaveOptions } from './common.dao.model';
 /**
  * Lowest common denominator API between supported Databases.
  *
@@ -86,28 +86,44 @@ export declare class CommonDao<BM extends Partial<ObjectWithId<ID>>, DBM extends
     assignIdCreatedUpdated(obj: BM, opt?: CommonDaoOptions): Saved<BM>;
     assignIdCreatedUpdated(obj: Unsaved<BM>, opt?: CommonDaoOptions): Saved<BM>;
     tx: {
-        save: (bm: Unsaved<BM>, opt?: CommonDaoSaveOptions<DBM>) => Promise<DBSaveBatchOperation | undefined>;
-        saveBatch: (bms: Unsaved<BM>[], opt?: CommonDaoSaveOptions<DBM>) => Promise<DBSaveBatchOperation | undefined>;
+        save: (bm: Unsaved<BM>, opt?: CommonDaoSaveBatchOptions<DBM>) => Promise<DBSaveBatchOperation | undefined>;
+        saveBatch: (bms: Unsaved<BM>[], opt?: CommonDaoSaveBatchOptions<DBM>) => Promise<DBSaveBatchOperation | undefined>;
         deleteByIds: (ids: ID[], opt?: CommonDaoOptions) => Promise<DBDeleteByIdsOperation | undefined>;
         deleteById: (id: ID | null | undefined, opt?: CommonDaoOptions) => Promise<DBDeleteByIdsOperation | undefined>;
     };
     /**
      * Mutates with id, created, updated
      */
-    save(bm: Unsaved<BM>, opt?: CommonDaoSaveOptions<DBM>): Promise<Saved<BM>>;
+    save(bm: Unsaved<BM>, opt?: CommonDaoSaveOptions<BM, DBM>): Promise<Saved<BM>>;
     /**
-     * Loads the row by id.
-     * Creates the row (via this.create()) if it doesn't exist
-     * (this will cause a validation error if Patch has not enough data for the row to be valid).
-     * Saves (as fast as possible) with the Patch applied.
+     * 1. Applies the patch
+     * 2. If object is the same after patching - skips saving it
+     * 3. Otherwise - saves the patched object and returns it
+     *
+     * Similar to `save` with skipIfEquals.
+     * Similar to `patch`, but doesn't load the object from the Database.
+     */
+    savePatch(bm: Saved<BM>, patch: Partial<BM>, opt: CommonDaoSaveBatchOptions<DBM>): Promise<Saved<BM>>;
+    /**
+     * Convenience method to replace 3 operations (loading+patching+saving) with one:
      *
-     * Convenience method to replace 3 operations (loading+patching+saving) with one.
+     * 1. Loads the row by id.
+     * 1.1 Creates the row (via this.create()) if it doesn't exist
+     * (this will cause a validation error if Patch has not enough data for the row to be valid).
+     * 2. Applies the patch on top of loaded data.
+     * 3. Saves (as fast as possible since the read) with the Patch applied, but only if the data has changed.
+     */
+    patchById(id: ID, patch: Partial<BM>, opt?: CommonDaoSaveBatchOptions<DBM>): Promise<Saved<BM>>;
+    /**
+     * Same as patchById, but takes the whole object as input.
+     * This "whole object" is mutated with the patch and returned.
+     * Otherwise, similar behavior as patchById.
+     * It still loads the row from the DB.
      */
-    patch(id: ID, patch: Partial<BM>, opt?: CommonDaoSaveOptions<DBM>): Promise<Saved<BM>>;
-    patchAsDBM(id: ID, patch: Partial<DBM>, opt?: CommonDaoSaveOptions<DBM>): Promise<DBM>;
-    saveAsDBM(dbm: DBM, opt?: CommonDaoSaveOptions<DBM>): Promise<DBM>;
-    saveBatch(bms: Unsaved<BM>[], opt?: CommonDaoSaveOptions<DBM>): Promise<Saved<BM>[]>;
-    saveBatchAsDBM(dbms: DBM[], opt?: CommonDaoSaveOptions<DBM>): Promise<DBM[]>;
+    patch(bm: Saved<BM>, patch: Partial<BM>, opt?: CommonDaoSaveBatchOptions<DBM>): Promise<Saved<BM>>;
+    saveAsDBM(dbm: DBM, opt?: CommonDaoSaveBatchOptions<DBM>): Promise<DBM>;
+    saveBatch(bms: Unsaved<BM>[], opt?: CommonDaoSaveBatchOptions<DBM>): Promise<Saved<BM>[]>;
+    saveBatchAsDBM(dbms: DBM[], opt?: CommonDaoSaveBatchOptions<DBM>): Promise<DBM[]>;
     /**
      * "Streaming" is implemented by buffering incoming rows into **batches**
      * (of size opt.batchSize, which defaults to 500),

package/dist/commondao/common.dao.js

@@ -555,6 +555,10 @@ class CommonDao {
      */
     async save(bm, opt = {}) {
         this.requireWriteAccess();
+        if (opt.skipIfEquals && (0, js_lib_1._deepJsonEquals)(bm, opt.skipIfEquals)) {
+            // Skipping the save operation
+            return bm;
+        }
         const idWasGenerated = !bm.id && this.cfg.createId;
         this.assignIdCreatedUpdated(bm, opt); // mutates
         let dbm = await this.bmToDBM(bm, opt);
@@ -589,26 +593,74 @@ class CommonDao {
         return bm;
     }
     /**
-     * Loads the row by id.
-     * Creates the row (via this.create()) if it doesn't exist
-     * (this will cause a validation error if Patch has not enough data for the row to be valid).
-     * Saves (as fast as possible) with the Patch applied.
+     * 1. Applies the patch
+     * 2. If object is the same after patching - skips saving it
+     * 3. Otherwise - saves the patched object and returns it
      *
-     * Convenience method to replace 3 operations (loading+patching+saving) with one.
+     * Similar to `save` with skipIfEquals.
+     * Similar to `patch`, but doesn't load the object from the Database.
      */
-    async patch(id, patch, opt = {}) {
-        return await this.save({
-            ...(await this.getByIdOrEmpty(id, patch, opt)),
+    async savePatch(bm, patch, opt) {
+        const patched = {
+            ...bm,
             ...patch,
-        }, opt);
+        };
+        if ((0, js_lib_1._deepJsonEquals)(bm, patched)) {
+            // Skipping the save operation, as data is the same
+            return bm;
+        }
+        // Actually apply the patch by mutating the original object (by design)
+        Object.assign(bm, patch);
+        return await this.save(bm, opt);
     }
-    async patchAsDBM(id, patch, opt = {}) {
-        const dbm = (await this.getByIdAsDBM(id, opt)) ||
-            this.create({ ...patch, id }, opt);
-        return await this.saveAsDBM({
-            ...dbm,
-            ...patch,
-        }, opt);
+    /**
+     * Convenience method to replace 3 operations (loading+patching+saving) with one:
+     *
+     * 1. Loads the row by id.
+     * 1.1 Creates the row (via this.create()) if it doesn't exist
+     * (this will cause a validation error if Patch has not enough data for the row to be valid).
+     * 2. Applies the patch on top of loaded data.
+     * 3. Saves (as fast as possible since the read) with the Patch applied, but only if the data has changed.
+     */
+    async patchById(id, patch, opt = {}) {
+        let patched;
+        const loaded = await this.getById(id, opt);
+        if (loaded) {
+            patched = { ...loaded, ...patch };
+            if ((0, js_lib_1._deepJsonEquals)(loaded, patched)) {
+                // Skipping the save operation, as data is the same
+                return patched;
+            }
+        }
+        else {
+            patched = this.create({ ...patch, id }, opt);
+        }
+        return await this.save(patched, opt);
+    }
+    /**
+     * Same as patchById, but takes the whole object as input.
+     * This "whole object" is mutated with the patch and returned.
+     * Otherwise, similar behavior as patchById.
+     * It still loads the row from the DB.
+     */
+    async patch(bm, patch, opt = {}) {
+        (0, js_lib_1._assert)(bm.id, 'patch argument object should have an id', {
+            bm,
+        });
+        const loaded = await this.getById(bm.id, opt);
+        if (loaded) {
+            Object.assign(loaded, patch);
+            if ((0, js_lib_1._deepJsonEquals)(loaded, bm)) {
+                // Skipping the save operation, as data is the same
+                return bm;
+            }
+            // Make `bm` exactly the same as `loaded`
+            (0, js_lib_1._objectAssignExact)(bm, loaded);
+        }
+        else {
+            Object.assign(bm, patch);
+        }
+        return await this.save(bm, opt);
     }
     async saveAsDBM(dbm, opt = {}) {
         this.requireWriteAccess();

package/dist/commondao/common.dao.model.d.ts

@@ -237,10 +237,21 @@ export interface CommonDaoOptions extends CommonDBOptions {
      */
     tx?: boolean;
 }
+export interface CommonDaoSaveOptions<BM extends Partial<ObjectWithId>, DBM extends ObjectWithId> extends CommonDaoSaveBatchOptions<DBM> {
+    /**
+     * If provided - a check will be made.
+     * If the object for saving equals to the object passed to `skipIfEquals` - save operation will be skipped.
+     *
+     * Equality is checked with _deepJsonEquals (aka "deep equals after JSON.stringify/parse", which removes keys with undefined values).
+     *
+     * It's supposed to be used to prevent "unnecessary saves", when data is not changed.
+     */
+    skipIfEquals?: BM;
+}
 /**
  * All properties default to undefined.
  */
-export interface CommonDaoSaveOptions<DBM extends ObjectWithId> extends CommonDaoOptions, CommonDBSaveOptions<DBM> {
+export interface CommonDaoSaveBatchOptions<DBM extends ObjectWithId> extends CommonDaoOptions, CommonDBSaveOptions<DBM> {
     /**
      * @default false
      *
@@ -254,7 +265,7 @@ export interface CommonDaoSaveOptions<DBM extends ObjectWithId> extends CommonDa
 }
 export interface CommonDaoStreamDeleteOptions<DBM extends ObjectWithId> extends CommonDaoStreamOptions<DBM> {
 }
-export interface CommonDaoStreamSaveOptions<DBM extends ObjectWithId> extends CommonDaoSaveOptions<DBM>, CommonDaoStreamOptions<DBM> {
+export interface CommonDaoStreamSaveOptions<DBM extends ObjectWithId> extends CommonDaoSaveBatchOptions<DBM>, CommonDaoStreamOptions<DBM> {
 }
 export interface CommonDaoStreamForEachOptions<IN> extends CommonDaoStreamOptions<IN>, TransformMapOptions<IN, any> {
 }

package/package.json

@@ -40,7 +40,7 @@
   "engines": {
     "node": ">=18.12"
   },
-  "version": "8.55.1",
+  "version": "8.57.0",
   "description": "Lowest Common Denominator API to supported Databases",
   "keywords": [
     "db",

package/src/commondao/common.dao.model.ts

@@ -298,10 +298,23 @@ export interface CommonDaoOptions extends CommonDBOptions {
   tx?: boolean
 }
 
+export interface CommonDaoSaveOptions<BM extends Partial<ObjectWithId>, DBM extends ObjectWithId>
+  extends CommonDaoSaveBatchOptions<DBM> {
+  /**
+   * If provided - a check will be made.
+   * If the object for saving equals to the object passed to `skipIfEquals` - save operation will be skipped.
+   *
+   * Equality is checked with _deepJsonEquals (aka "deep equals after JSON.stringify/parse", which removes keys with undefined values).
+   *
+   * It's supposed to be used to prevent "unnecessary saves", when data is not changed.
+   */
+  skipIfEquals?: BM
+}
+
 /**
  * All properties default to undefined.
  */
-export interface CommonDaoSaveOptions<DBM extends ObjectWithId>
+export interface CommonDaoSaveBatchOptions<DBM extends ObjectWithId>
   extends CommonDaoOptions,
     CommonDBSaveOptions<DBM> {
   /**
@@ -320,7 +333,7 @@ export interface CommonDaoStreamDeleteOptions<DBM extends ObjectWithId>
   extends CommonDaoStreamOptions<DBM> {}
 
 export interface CommonDaoStreamSaveOptions<DBM extends ObjectWithId>
-  extends CommonDaoSaveOptions<DBM>,
+  extends CommonDaoSaveBatchOptions<DBM>,
     CommonDaoStreamOptions<DBM> {}
 
 export interface CommonDaoStreamForEachOptions<IN>

package/src/commondao/common.dao.ts

@@ -1,9 +1,11 @@
 import { Transform } from 'node:stream'
 import {
   _assert,
+  _deepJsonEquals,
   _filterNullishValues,
   _filterUndefinedValues,
   _isTruthy,
+  _objectAssignExact,
   _passthroughPredicate,
   _since,
   _truncate,
@@ -57,6 +59,7 @@ import {
   CommonDaoHooks,
   CommonDaoLogLevel,
   CommonDaoOptions,
+  CommonDaoSaveBatchOptions,
   CommonDaoSaveOptions,
   CommonDaoStreamDeleteOptions,
   CommonDaoStreamForEachOptions,
@@ -697,7 +700,7 @@ export class CommonDao<
   tx = {
     save: async (
       bm: Unsaved<BM>,
-      opt: CommonDaoSaveOptions<DBM> = {},
+      opt: CommonDaoSaveBatchOptions<DBM> = {},
     ): Promise<DBSaveBatchOperation | undefined> => {
       // .save actually returns DBM (not BM) when it detects `opt.tx === true`
       const row: DBM | null = (await this.save(bm, { ...opt, tx: true })) as any
@@ -715,7 +718,7 @@ export class CommonDao<
     },
     saveBatch: async (
       bms: Unsaved<BM>[],
-      opt: CommonDaoSaveOptions<DBM> = {},
+      opt: CommonDaoSaveBatchOptions<DBM> = {},
     ): Promise<DBSaveBatchOperation | undefined> => {
       const rows: DBM[] = (await this.saveBatch(bms, { ...opt, tx: true })) as any
       if (!rows.length) return
@@ -760,8 +763,14 @@ export class CommonDao<
   /**
    * Mutates with id, created, updated
    */
-  async save(bm: Unsaved<BM>, opt: CommonDaoSaveOptions<DBM> = {}): Promise<Saved<BM>> {
+  async save(bm: Unsaved<BM>, opt: CommonDaoSaveOptions<BM, DBM> = {}): Promise<Saved<BM>> {
     this.requireWriteAccess()
+
+    if (opt.skipIfEquals && _deepJsonEquals(bm, opt.skipIfEquals)) {
+      // Skipping the save operation
+      return bm as Saved<BM>
+    }
+
     const idWasGenerated = !bm.id && this.cfg.createId
     this.assignIdCreatedUpdated(bm, opt) // mutates
     let dbm = await this.bmToDBM(bm as BM, opt)
@@ -801,38 +810,100 @@ export class CommonDao<
   }
 
   /**
-   * Loads the row by id.
-   * Creates the row (via this.create()) if it doesn't exist
-   * (this will cause a validation error if Patch has not enough data for the row to be valid).
-   * Saves (as fast as possible) with the Patch applied.
+   * 1. Applies the patch
+   * 2. If object is the same after patching - skips saving it
+   * 3. Otherwise - saves the patched object and returns it
    *
-   * Convenience method to replace 3 operations (loading+patching+saving) with one.
+   * Similar to `save` with skipIfEquals.
+   * Similar to `patch`, but doesn't load the object from the Database.
    */
-  async patch(id: ID, patch: Partial<BM>, opt: CommonDaoSaveOptions<DBM> = {}): Promise<Saved<BM>> {
-    return await this.save(
-      {
-        ...(await this.getByIdOrEmpty(id, patch, opt)),
-        ...patch,
-      } as any,
-      opt,
-    )
+  async savePatch(
+    bm: Saved<BM>,
+    patch: Partial<BM>,
+    opt: CommonDaoSaveBatchOptions<DBM>,
+  ): Promise<Saved<BM>> {
+    const patched: Saved<BM> = {
+      ...bm,
+      ...patch,
+    }
+
+    if (_deepJsonEquals(bm, patched)) {
+      // Skipping the save operation, as data is the same
+      return bm
+    }
+
+    // Actually apply the patch by mutating the original object (by design)
+    Object.assign(bm, patch)
+
+    return await this.save(bm, opt)
   }
 
-  async patchAsDBM(id: ID, patch: Partial<DBM>, opt: CommonDaoSaveOptions<DBM> = {}): Promise<DBM> {
-    const dbm =
-      (await this.getByIdAsDBM(id, opt)) ||
-      (this.create({ ...patch, id } as Partial<BM>, opt) as any as DBM)
+  /**
+   * Convenience method to replace 3 operations (loading+patching+saving) with one:
+   *
+   * 1. Loads the row by id.
+   * 1.1 Creates the row (via this.create()) if it doesn't exist
+   * (this will cause a validation error if Patch has not enough data for the row to be valid).
+   * 2. Applies the patch on top of loaded data.
+   * 3. Saves (as fast as possible since the read) with the Patch applied, but only if the data has changed.
+   */
+  async patchById(
+    id: ID,
+    patch: Partial<BM>,
+    opt: CommonDaoSaveBatchOptions<DBM> = {},
+  ): Promise<Saved<BM>> {
+    let patched: Saved<BM>
+    const loaded = await this.getById(id, opt)
+
+    if (loaded) {
+      patched = { ...loaded, ...patch }
+
+      if (_deepJsonEquals(loaded, patched)) {
+        // Skipping the save operation, as data is the same
+        return patched
+      }
+    } else {
+      patched = this.create({ ...patch, id }, opt)
+    }
 
-    return await this.saveAsDBM(
-      {
-        ...dbm,
-        ...patch,
-      },
-      opt,
-    )
+    return await this.save(patched, opt)
+  }
+
+  /**
+   * Same as patchById, but takes the whole object as input.
+   * This "whole object" is mutated with the patch and returned.
+   * Otherwise, similar behavior as patchById.
+   * It still loads the row from the DB.
+   */
+  async patch(
+    bm: Saved<BM>,
+    patch: Partial<BM>,
+    opt: CommonDaoSaveBatchOptions<DBM> = {},
+  ): Promise<Saved<BM>> {
+    _assert(bm.id, 'patch argument object should have an id', {
+      bm,
+    })
+
+    const loaded = await this.getById(bm.id, opt)
+
+    if (loaded) {
+      Object.assign(loaded, patch)
+
+      if (_deepJsonEquals(loaded, bm)) {
+        // Skipping the save operation, as data is the same
+        return bm
+      }
+
+      // Make `bm` exactly the same as `loaded`
+      _objectAssignExact(bm, loaded)
+    } else {
+      Object.assign(bm, patch)
+    }
+
+    return await this.save(bm, opt)
   }
 
-  async saveAsDBM(dbm: DBM, opt: CommonDaoSaveOptions<DBM> = {}): Promise<DBM> {
+  async saveAsDBM(dbm: DBM, opt: CommonDaoSaveBatchOptions<DBM> = {}): Promise<DBM> {
     this.requireWriteAccess()
     const table = opt.table || this.cfg.table
 
@@ -872,7 +943,10 @@ export class CommonDao<
     return row
   }
 
-  async saveBatch(bms: Unsaved<BM>[], opt: CommonDaoSaveOptions<DBM> = {}): Promise<Saved<BM>[]> {
+  async saveBatch(
+    bms: Unsaved<BM>[],
+    opt: CommonDaoSaveBatchOptions<DBM> = {},
+  ): Promise<Saved<BM>[]> {
     if (!bms.length) return []
     this.requireWriteAccess()
     const table = opt.table || this.cfg.table
@@ -920,7 +994,7 @@ export class CommonDao<
     return bms as any[]
   }
 
-  async saveBatchAsDBM(dbms: DBM[], opt: CommonDaoSaveOptions<DBM> = {}): Promise<DBM[]> {
+  async saveBatchAsDBM(dbms: DBM[], opt: CommonDaoSaveBatchOptions<DBM> = {}): Promise<DBM[]> {
     if (!dbms.length) return []
     this.requireWriteAccess()
     const table = opt.table || this.cfg.table