@naturalcycles/db-lib 8.55.0 → 8.56.0

package/dist/adapter/file/file.db.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileDB = void 0;
 const js_lib_1 = require("@naturalcycles/js-lib");
 const nodejs_lib_1 = require("@naturalcycles/nodejs-lib");
-const nodejs_lib_2 = require("@naturalcycles/nodejs-lib");
 const __1 = require("../..");
 /**
  * Provides barebone implementation for "whole file" based CommonDB.
@@ -195,7 +194,7 @@ class FileDB extends __1.BaseCommonDB {
     logFinished(started, op) {
         if (!this.cfg.logFinished)
             return;
-        this.cfg.logger?.log(`<< ${op} ${(0, nodejs_lib_2.dimGrey)(`in ${(0, js_lib_1._since)(started)}`)}`);
+        this.cfg.logger?.log(`<< ${op} ${(0, nodejs_lib_1.dimGrey)(`in ${(0, js_lib_1._since)(started)}`)}`);
     }
 }
 exports.FileDB = FileDB;

package/dist/adapter/file/localFile.persistence.plugin.js

@@ -3,8 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocalFilePersistencePlugin = void 0;
 const tslib_1 = require("tslib");
 const node_fs_1 = tslib_1.__importDefault(require("node:fs"));
-const node_stream_1 = require("node:stream");
 const promises_1 = tslib_1.__importDefault(require("node:fs/promises"));
+const node_stream_1 = require("node:stream");
 const node_zlib_1 = require("node:zlib");
 const js_lib_1 = require("@naturalcycles/js-lib");
 const nodejs_lib_1 = require("@naturalcycles/nodejs-lib");

package/dist/adapter/inmemory/inMemory.db.js

@@ -8,7 +8,6 @@ const node_stream_1 = require("node:stream");
 const node_zlib_1 = require("node:zlib");
 const js_lib_1 = require("@naturalcycles/js-lib");
 const nodejs_lib_1 = require("@naturalcycles/nodejs-lib");
-const nodejs_lib_2 = require("@naturalcycles/nodejs-lib");
 const __1 = require("../..");
 const dbQuery_1 = require("../../query/dbQuery");
 class InMemoryDB {
@@ -185,7 +184,7 @@ class InMemoryDB {
                 node_fs_1.default.createWriteStream(fname),
             ]);
         });
-        this.cfg.logger.log(`flushToDisk took ${(0, nodejs_lib_2.dimGrey)((0, js_lib_1._since)(started))} to save ${(0, nodejs_lib_2.yellow)(tables)} tables`);
+        this.cfg.logger.log(`flushToDisk took ${(0, nodejs_lib_1.dimGrey)((0, js_lib_1._since)(started))} to save ${(0, nodejs_lib_1.yellow)(tables)} tables`);
     }
     /**
      * Restores all tables (all namespaces) at once.
@@ -212,7 +211,7 @@ class InMemoryDB {
             ]);
             this.data[table] = (0, js_lib_1._by)(rows, r => r.id);
         });
-        this.cfg.logger.log(`restoreFromDisk took ${(0, nodejs_lib_2.dimGrey)((0, js_lib_1._since)(started))} to read ${(0, nodejs_lib_2.yellow)(files.length)} tables`);
+        this.cfg.logger.log(`restoreFromDisk took ${(0, nodejs_lib_1.dimGrey)((0, js_lib_1._since)(started))} to read ${(0, nodejs_lib_1.yellow)(files.length)} tables`);
     }
 }
 exports.InMemoryDB = InMemoryDB;

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/dist/pipeline/dbPipelineBackup.js

@@ -7,7 +7,6 @@ const promises_1 = tslib_1.__importDefault(require("node:fs/promises"));
 const node_zlib_1 = require("node:zlib");
 const js_lib_1 = require("@naturalcycles/js-lib");
 const nodejs_lib_1 = require("@naturalcycles/nodejs-lib");
-const nodejs_lib_2 = require("@naturalcycles/nodejs-lib");
 const index_1 = require("../index");
 /**
  * Pipeline from input stream(s) to a NDJSON file (optionally gzipped).
@@ -23,11 +22,11 @@ async function dbPipelineBackup(opt) {
     const strict = errorMode !== js_lib_1.ErrorMode.SUPPRESS;
     const gzip = opt.gzip !== false; // default to true
     let { tables } = opt;
-    const sinceUpdatedStr = sinceUpdated ? ' since ' + (0, nodejs_lib_2.grey)((0, js_lib_1.localTime)(sinceUpdated).toPretty()) : '';
-    console.log(`>> ${(0, nodejs_lib_2.dimWhite)('dbPipelineBackup')} started in ${(0, nodejs_lib_2.grey)(outputDirPath)}...${sinceUpdatedStr}`);
+    const sinceUpdatedStr = sinceUpdated ? ' since ' + (0, nodejs_lib_1.grey)((0, js_lib_1.localTime)(sinceUpdated).toPretty()) : '';
+    console.log(`>> ${(0, nodejs_lib_1.dimWhite)('dbPipelineBackup')} started in ${(0, nodejs_lib_1.grey)(outputDirPath)}...${sinceUpdatedStr}`);
     (0, nodejs_lib_1._ensureDirSync)(outputDirPath);
     tables ||= await db.getTables();
-    console.log(`${(0, nodejs_lib_2.yellow)(tables.length)} ${(0, nodejs_lib_2.boldWhite)('table(s)')}:\n` + tables.join('\n'));
+    console.log(`${(0, nodejs_lib_1.yellow)(tables.length)} ${(0, nodejs_lib_1.boldWhite)('table(s)')}:\n` + tables.join('\n'));
     const statsPerTable = {};
     await (0, js_lib_1.pMap)(tables, async (table) => {
         let q = index_1.DBQuery.create(table).limit(limit);
@@ -42,11 +41,11 @@ async function dbPipelineBackup(opt) {
         const started = Date.now();
         let rows = 0;
         (0, nodejs_lib_1._ensureFileSync)(filePath);
-        console.log(`>> ${(0, nodejs_lib_2.grey)(filePath)} started...`);
+        console.log(`>> ${(0, nodejs_lib_1.grey)(filePath)} started...`);
         if (emitSchemaFromDB) {
             const schema = await db.getTableSchema(table);
             await (0, nodejs_lib_1._writeJson)(schemaFilePath, schema, { spaces: 2 });
-            console.log(`>> ${(0, nodejs_lib_2.grey)(schemaFilePath)} saved (generated from DB)`);
+            console.log(`>> ${(0, nodejs_lib_1.grey)(schemaFilePath)} saved (generated from DB)`);
         }
         await (0, nodejs_lib_1._pipeline)([
             db.streamQuery(q),
@@ -74,7 +73,7 @@ async function dbPipelineBackup(opt) {
             rows,
             sizeBytes,
         });
-        console.log(`>> ${(0, nodejs_lib_2.grey)(filePath)}\n` + stats.toPretty());
+        console.log(`>> ${(0, nodejs_lib_1.grey)(filePath)}\n` + stats.toPretty());
         statsPerTable[table] = stats;
     }, { concurrency, errorMode });
     const statsTotal = nodejs_lib_1.NDJsonStats.createCombined(Object.values(statsPerTable));

package/dist/pipeline/dbPipelineCopy.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.dbPipelineCopy = void 0;
 const js_lib_1 = require("@naturalcycles/js-lib");
 const nodejs_lib_1 = require("@naturalcycles/nodejs-lib");
-const nodejs_lib_2 = require("@naturalcycles/nodejs-lib");
 const dbQuery_1 = require("../query/dbQuery");
 /**
  * Pipeline from input stream(s) to CommonDB .saveBatch().
@@ -14,10 +13,10 @@ const dbQuery_1 = require("../query/dbQuery");
 async function dbPipelineCopy(opt) {
     const { batchSize = 100, dbInput, dbOutput, concurrency = 16, limit = 0, sinceUpdated, mapperPerTable = {}, saveOptionsPerTable = {}, transformMapOptions, errorMode = js_lib_1.ErrorMode.SUPPRESS, } = opt;
     let { tables } = opt;
-    const sinceUpdatedStr = sinceUpdated ? ' since ' + (0, nodejs_lib_2.grey)((0, js_lib_1.localTime)(sinceUpdated).toPretty()) : '';
-    console.log(`>> ${(0, nodejs_lib_2.dimWhite)('dbPipelineCopy')} started...${sinceUpdatedStr}`);
+    const sinceUpdatedStr = sinceUpdated ? ' since ' + (0, nodejs_lib_1.grey)((0, js_lib_1.localTime)(sinceUpdated).toPretty()) : '';
+    console.log(`>> ${(0, nodejs_lib_1.dimWhite)('dbPipelineCopy')} started...${sinceUpdatedStr}`);
     tables ||= await dbInput.getTables();
-    console.log(`${(0, nodejs_lib_2.yellow)(tables.length)} ${(0, nodejs_lib_2.boldWhite)('table(s)')}:\n` + tables.join('\n'));
+    console.log(`${(0, nodejs_lib_1.yellow)(tables.length)} ${(0, nodejs_lib_1.boldWhite)('table(s)')}:\n` + tables.join('\n'));
     const statsPerTable = {};
     await (0, js_lib_1.pMap)(tables, async (table) => {
         let q = dbQuery_1.DBQuery.create(table).limit(limit);
@@ -53,7 +52,7 @@ async function dbPipelineCopy(opt) {
             rows,
             sizeBytes: 0, // n/a
         });
-        console.log(`>> ${(0, nodejs_lib_2.grey)(table)}\n` + stats.toPretty());
+        console.log(`>> ${(0, nodejs_lib_1.grey)(table)}\n` + stats.toPretty());
         statsPerTable[table] = stats;
     }, { concurrency, errorMode });
     const statsTotal = nodejs_lib_1.NDJsonStats.createCombined(Object.values(statsPerTable));

package/dist/pipeline/dbPipelineRestore.js

@@ -6,7 +6,6 @@ const node_fs_1 = tslib_1.__importDefault(require("node:fs"));
 const node_zlib_1 = require("node:zlib");
 const js_lib_1 = require("@naturalcycles/js-lib");
 const nodejs_lib_1 = require("@naturalcycles/nodejs-lib");
-const nodejs_lib_2 = require("@naturalcycles/nodejs-lib");
 /**
  * Pipeline from NDJSON files in a folder (optionally gzipped) to CommonDB.
  * Allows to define a mapper and a predicate to map/filter objects between input and output.
@@ -18,8 +17,8 @@ async function dbPipelineRestore(opt) {
     const { db, concurrency = 16, batchSize = 100, limit, sinceUpdated, inputDirPath, mapperPerTable = {}, saveOptionsPerTable = {}, transformMapOptions, errorMode = js_lib_1.ErrorMode.SUPPRESS, recreateTables = false, } = opt;
     const strict = errorMode !== js_lib_1.ErrorMode.SUPPRESS;
     const onlyTables = opt.tables && new Set(opt.tables);
-    const sinceUpdatedStr = sinceUpdated ? ' since ' + (0, nodejs_lib_2.grey)((0, js_lib_1.localTime)(sinceUpdated).toPretty()) : '';
-    console.log(`>> ${(0, nodejs_lib_2.dimWhite)('dbPipelineRestore')} started in ${(0, nodejs_lib_2.grey)(inputDirPath)}...${sinceUpdatedStr}`);
+    const sinceUpdatedStr = sinceUpdated ? ' since ' + (0, nodejs_lib_1.grey)((0, js_lib_1.localTime)(sinceUpdated).toPretty()) : '';
+    console.log(`>> ${(0, nodejs_lib_1.dimWhite)('dbPipelineRestore')} started in ${(0, nodejs_lib_1.grey)(inputDirPath)}...${sinceUpdatedStr}`);
     (0, nodejs_lib_1._ensureDirSync)(inputDirPath);
     const tablesToGzip = new Set();
     const sizeByTable = {};
@@ -46,7 +45,7 @@ async function dbPipelineRestore(opt) {
         sizeByTable[table] = node_fs_1.default.statSync(`${inputDirPath}/${f}`).size;
     });
     const sizeStrByTable = (0, js_lib_1._mapValues)(sizeByTable, (_k, b) => (0, js_lib_1._hb)(b));
-    console.log(`${(0, nodejs_lib_2.yellow)(tables.length)} ${(0, nodejs_lib_2.boldWhite)('table(s)')}:\n`, sizeStrByTable);
+    console.log(`${(0, nodejs_lib_1.yellow)(tables.length)} ${(0, nodejs_lib_1.boldWhite)('table(s)')}:\n`, sizeStrByTable);
     // const schemaByTable: Record<string, CommonSchema> = {}
     if (recreateTables) {
         await (0, js_lib_1.pMap)(tables, async (table) => {
@@ -66,7 +65,7 @@ async function dbPipelineRestore(opt) {
         const started = Date.now();
         let rows = 0;
         const sizeBytes = sizeByTable[table];
-        console.log(`<< ${(0, nodejs_lib_2.grey)(filePath)} ${(0, nodejs_lib_2.dimWhite)((0, js_lib_1._hb)(sizeBytes))} started...`);
+        console.log(`<< ${(0, nodejs_lib_1.grey)(filePath)} ${(0, nodejs_lib_1.dimWhite)((0, js_lib_1._hb)(sizeBytes))} started...`);
         await (0, nodejs_lib_1._pipeline)([
             node_fs_1.default.createReadStream(filePath),
             ...(gzip ? [(0, node_zlib_1.createUnzip)()] : []),
@@ -98,7 +97,7 @@ async function dbPipelineRestore(opt) {
             rows,
             sizeBytes,
         });
-        console.log(`<< ${(0, nodejs_lib_2.grey)(filePath)}\n` + stats.toPretty());
+        console.log(`<< ${(0, nodejs_lib_1.grey)(filePath)}\n` + stats.toPretty());
         statsPerTable[table] = stats;
     }, { concurrency, errorMode });
     const statsTotal = nodejs_lib_1.NDJsonStats.createCombined(Object.values(statsPerTable));

package/dist/testing/daoTest.js

@@ -205,7 +205,7 @@ function runCommonDaoTest(db, features = {}, quirks = {}) {
             // cleanup
             await dao.query().deleteByQuery();
             // Test that id, created, updated are created
-            const now = (0, js_lib_1.localTime)().unix();
+            const now = (0, js_lib_1.localTimeNow)().unix();
             await dao.runInTransaction([dao.tx.save((0, js_lib_1._omit)(item1, ['id', 'created', 'updated']))]);
             const loaded = await dao.query().runQuery();
             expect(loaded.length).toBe(1);

package/package.json

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

package/src/adapter/file/file.db.ts

@@ -17,8 +17,7 @@ import {
   _stringMapEntries,
   Saved,
 } from '@naturalcycles/js-lib'
-import { readableCreate, ReadableTyped } from '@naturalcycles/nodejs-lib'
-import { dimGrey } from '@naturalcycles/nodejs-lib'
+import { readableCreate, ReadableTyped, dimGrey } from '@naturalcycles/nodejs-lib'
 import { BaseCommonDB, DBSaveBatchOperation, queryInMemory } from '../..'
 import { CommonDB } from '../../common.db'
 import {

package/src/adapter/file/localFile.persistence.plugin.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs'
-import { Readable } from 'node:stream'
 import fsp from 'node:fs/promises'
+import { Readable } from 'node:stream'
 import { createGzip, createUnzip } from 'node:zlib'
 import { pMap, ObjectWithId } from '@naturalcycles/js-lib'
 import {

package/src/adapter/inmemory/inMemory.db.ts

@@ -27,8 +27,9 @@ import {
   _pipeline,
   _emptyDir,
   _ensureDir,
+  dimGrey,
+  yellow,
 } from '@naturalcycles/nodejs-lib'
-import { dimGrey, yellow } from '@naturalcycles/nodejs-lib'
 import { CommonDB, DBIncrement, DBPatch, DBTransaction, queryInMemory } from '../..'
 import {
   CommonDBCreateOptions,

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

package/src/model.util.ts

@@ -1,5 +1,5 @@
-import { stringId } from '@naturalcycles/nodejs-lib'
 import { CreatedUpdated, CreatedUpdatedId } from '@naturalcycles/js-lib'
+import { stringId } from '@naturalcycles/nodejs-lib'
 
 export function createdUpdatedFields(
   existingObject?: Partial<CreatedUpdated> | null,

package/src/pipeline/dbPipelineBackup.ts

@@ -22,8 +22,11 @@ import {
   _pathExistsSync,
   _ensureFileSync,
   _writeJson,
+  boldWhite,
+  dimWhite,
+  grey,
+  yellow,
 } from '@naturalcycles/nodejs-lib'
-import { boldWhite, dimWhite, grey, yellow } from '@naturalcycles/nodejs-lib'
 import { CommonDB } from '../common.db'
 import { DBQuery } from '../index'
 

package/src/pipeline/dbPipelineCopy.ts

@@ -9,8 +9,11 @@ import {
   transformTap,
   writableForEach,
   _pipeline,
+  boldWhite,
+  dimWhite,
+  grey,
+  yellow,
 } from '@naturalcycles/nodejs-lib'
-import { boldWhite, dimWhite, grey, yellow } from '@naturalcycles/nodejs-lib'
 import { CommonDB } from '../common.db'
 import { CommonDBSaveOptions } from '../db.model'
 import { DBQuery } from '../query/dbQuery'

package/src/pipeline/dbPipelineRestore.ts

@@ -27,8 +27,11 @@ import {
   _pipeline,
   _ensureDirSync,
   _readJson,
+  boldWhite,
+  dimWhite,
+  grey,
+  yellow,
 } from '@naturalcycles/nodejs-lib'
-import { boldWhite, dimWhite, grey, yellow } from '@naturalcycles/nodejs-lib'
 import { CommonDB } from '../common.db'
 import { CommonDBSaveOptions } from '../index'
 

package/src/testing/daoTest.ts

@@ -1,5 +1,5 @@
 import { Readable } from 'node:stream'
-import { pDelay, _deepCopy, _pick, _sortBy, _omit, localTime } from '@naturalcycles/js-lib'
+import { pDelay, _deepCopy, _pick, _sortBy, _omit, localTimeNow } from '@naturalcycles/js-lib'
 import { _pipeline, readableToArray, transformNoOp } from '@naturalcycles/nodejs-lib'
 import { CommonDaoLogLevel, DBQuery } from '..'
 import { CommonDB } from '../common.db'
@@ -289,7 +289,7 @@ export function runCommonDaoTest(
       await dao.query().deleteByQuery()
 
       // Test that id, created, updated are created
-      const now = localTime().unix()
+      const now = localTimeNow().unix()
       await dao.runInTransaction([dao.tx.save(_omit(item1, ['id', 'created', 'updated']))])
 
       const loaded = await dao.query().runQuery()

package/src/testing/keyValueDaoTest.ts

@@ -1,7 +1,7 @@
 import { _range, _sortBy } from '@naturalcycles/js-lib'
 import { readableToArray } from '@naturalcycles/nodejs-lib'
-import { CommonKeyValueDao } from '../kv/commonKeyValueDao'
 import { KeyValueDBTuple } from '../kv/commonKeyValueDB'
+import { CommonKeyValueDao } from '../kv/commonKeyValueDao'
 
 const testIds = _range(1, 4).map(n => `id${n}`)
 const testEntries: KeyValueDBTuple[] = testIds.map(id => [id, Buffer.from(`${id}value`)])