@naturalcycles/db-lib 8.55.1 → 8.56.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,38 @@ 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
      *
-     * 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.
+     */
+    savePatch(bm: Saved<BM>, patch: Partial<BM>, opt: CommonDaoSaveBatchOptions<DBM>): Promise<Saved<BM>>;
+    /**
+     * 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.
      */
-    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(id: ID, patch: Partial<BM>, opt?: CommonDaoSaveBatchOptions<DBM>): Promise<Saved<BM>>;
+    patchAsDBM(id: ID, patch: Partial<DBM>, opt?: CommonDaoSaveBatchOptions<DBM>): Promise<DBM>;
+    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,70 @@ 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);
+    }
+    /**
+     * 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.
+     */
+    async patch(id, patch, opt = {}) {
+        const bm = await this.getById(id, opt);
+        let patched;
+        if (bm) {
+            patched = {
+                ...bm,
+                ...patch,
+            };
+            if ((0, js_lib_1._deepJsonEquals)(bm, patched)) {
+                // Skipping the save operation, as data is the same
+                return bm;
+            }
+        }
+        else {
+            patched = this.create({ ...patch, id }, opt);
+        }
+        return await this.save(patched, 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);
+        const dbm = await this.getByIdAsDBM(id, opt);
+        let patched;
+        if (dbm) {
+            patched = {
+                ...dbm,
+                ...patch,
+            };
+            if ((0, js_lib_1._deepJsonEquals)(dbm, patched)) {
+                // Skipping the save operation, as data is the same
+                return dbm;
+            }
+        }
+        else {
+            patched = this.create({ ...patch, id }, opt);
+        }
+        return await this.saveAsDBM(patched, 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.56.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,6 +1,7 @@
 import { Transform } from 'node:stream'
 import {
   _assert,
+  _deepJsonEquals,
   _filterNullishValues,
   _filterUndefinedValues,
   _isTruthy,
@@ -57,6 +58,7 @@ import {
   CommonDaoHooks,
   CommonDaoLogLevel,
   CommonDaoOptions,
+  CommonDaoSaveBatchOptions,
   CommonDaoSaveOptions,
   CommonDaoStreamDeleteOptions,
   CommonDaoStreamForEachOptions,
@@ -697,7 +699,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 +717,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 +762,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 +809,94 @@ 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
+   *
+   * Similar to `save` with skipIfEquals.
+   * Similar to `patch`, but doesn't load the object from the Database.
+   */
+  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)
+  }
+
+  /**
+   * 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.
    */
-  async patch(id: ID, patch: Partial<BM>, opt: CommonDaoSaveOptions<DBM> = {}): Promise<Saved<BM>> {
-    return await this.save(
-      {
-        ...(await this.getByIdOrEmpty(id, patch, opt)),
+  async patch(
+    id: ID,
+    patch: Partial<BM>,
+    opt: CommonDaoSaveBatchOptions<DBM> = {},
+  ): Promise<Saved<BM>> {
+    const bm = await this.getById(id, opt)
+    let patched: Saved<BM>
+
+    if (bm) {
+      patched = {
+        ...bm,
         ...patch,
-      } as any,
-      opt,
-    )
+      }
+
+      if (_deepJsonEquals(bm, patched)) {
+        // Skipping the save operation, as data is the same
+        return bm
+      }
+    } else {
+      patched = this.create({ ...patch, id }, opt)
+    }
+
+    return await this.save(patched, 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)
+  async patchAsDBM(
+    id: ID,
+    patch: Partial<DBM>,
+    opt: CommonDaoSaveBatchOptions<DBM> = {},
+  ): Promise<DBM> {
+    const dbm = await this.getByIdAsDBM(id, opt)
+    let patched: DBM
 
-    return await this.saveAsDBM(
-      {
+    if (dbm) {
+      patched = {
         ...dbm,
         ...patch,
-      },
-      opt,
-    )
+      }
+
+      if (_deepJsonEquals(dbm, patched)) {
+        // Skipping the save operation, as data is the same
+        return dbm
+      }
+    } else {
+      patched = this.create({ ...patch, id } as Partial<BM>, opt) as any as DBM
+    }
+
+    return await this.saveAsDBM(patched, 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 +936,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 +987,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