@naturalcycles/db-lib 10.19.0 → 10.20.0

package/dist/commondao/common.dao.js

@@ -1,20 +1,18 @@
 import { _isTruthy } from '@naturalcycles/js-lib';
 import { _uniqBy } from '@naturalcycles/js-lib/array/array.util.js';
 import { localTime } from '@naturalcycles/js-lib/datetime/localTime.js';
-import { _since } from '@naturalcycles/js-lib/datetime/time.util.js';
-import { _assert, AppError, ErrorMode } from '@naturalcycles/js-lib/error';
+import { _assert, ErrorMode } from '@naturalcycles/js-lib/error';
 import { _deepJsonEquals } from '@naturalcycles/js-lib/object/deepEquals.js';
-import { _deepCopy, _filterUndefinedValues, _objectAssignExact, } from '@naturalcycles/js-lib/object/object.util.js';
+import { _filterUndefinedValues, _objectAssignExact, } from '@naturalcycles/js-lib/object/object.util.js';
 import { pMap } from '@naturalcycles/js-lib/promise/pMap.js';
-import { _truncate } from '@naturalcycles/js-lib/string/string.util.js';
 import { _stringMapEntries, _stringMapValues, } from '@naturalcycles/js-lib/types';
 import { _passthroughPredicate, _typeCast, SKIP } from '@naturalcycles/js-lib/types';
 import { stringId } from '@naturalcycles/nodejs-lib';
-import { transformFlatten } from '@naturalcycles/nodejs-lib/stream';
+import { transformFlatten, transformMapSync, } from '@naturalcycles/nodejs-lib/stream';
 import { _pipeline, transformChunk, transformLogProgress, transformMap, transformNoOp, writableVoid, } from '@naturalcycles/nodejs-lib/stream';
 import { DBLibError } from '../cnst.js';
 import { RunnableDBQuery } from '../query/dbQuery.js';
-import { CommonDaoLogLevel } from './common.dao.model.js';
+import { CommonDaoTransaction } from './commonDaoTransaction.js';
 /**
  * Lowest common denominator API between supported Databases.
  *
@@ -27,7 +25,6 @@ export class CommonDao {
     constructor(cfg) {
         this.cfg = cfg;
         this.cfg = {
-            logLevel: CommonDaoLogLevel.NONE,
             generateId: true,
             assignGeneratedIds: false,
             useCreatedProperty: true,
@@ -59,22 +56,13 @@ export class CommonDao {
         return this.validateAndConvert(bm, undefined, opt);
     }
     // GET
-    // overrides are disabled now, as they obfuscate errors when ID branded type is used
-    // async getById(id: undefined | null, opt?: CommonDaoOptions): Promise<null>
-    // async getById(id?: ID | null, opt?: CommonDaoOptions): Promise<BM | null>
-    async getById(id, opt = {}) {
-        if (!id)
-            return null;
-        const op = `getById(${id})`;
-        const table = opt.table || this.cfg.table;
-        const started = this.logStarted(op, table);
-        let dbm = (await (opt.tx || this.cfg.db).getByIds(table, [id], opt))[0];
-        if (dbm && this.cfg.hooks.afterLoad) {
-            dbm = (await this.cfg.hooks.afterLoad(dbm)) || undefined;
-        }
-        const bm = await this.dbmToBM(dbm, opt);
-        this.logResult(started, op, bm, table);
-        return bm || null;
+    async requireById(id, opt = {}) {
+        const bm = await this.getById(id, opt);
+        return this.ensureRequired(bm, id, opt);
+    }
+    async requireByIdAsDBM(id, opt = {}) {
+        const dbm = await this.getByIdAsDBM(id, opt);
+        return this.ensureRequired(dbm, id, opt);
     }
     async getByIdOrEmpty(id, part = {}, opt) {
         const bm = await this.getById(id, opt);
@@ -82,99 +70,32 @@ export class CommonDao {
             return bm;
         return this.create({ ...part, id }, opt);
     }
-    // async getByIdAsDBM(id: undefined | null, opt?: CommonDaoOptions): Promise<null>
-    // async getByIdAsDBM(id?: ID | null, opt?: CommonDaoOptions): Promise<DBM | null>
+    async getById(id, opt = {}) {
+        if (!id)
+            return null;
+        const [dbm] = await this.loadByIds([id], opt);
+        return await this.dbmToBM(dbm, opt);
+    }
     async getByIdAsDBM(id, opt = {}) {
         if (!id)
             return null;
-        const op = `getByIdAsDBM(${id})`;
-        const table = opt.table || this.cfg.table;
-        const started = this.logStarted(op, table);
-        let [dbm] = await (opt.tx || this.cfg.db).getByIds(table, [id], opt);
-        if (dbm && this.cfg.hooks.afterLoad) {
-            dbm = (await this.cfg.hooks.afterLoad(dbm)) || undefined;
-        }
-        dbm = this.anyToDBM(dbm, opt);
-        this.logResult(started, op, dbm, table);
-        return dbm || null;
+        const [row] = await this.loadByIds([id], opt);
+        return this.anyToDBM(row, opt) || null;
     }
     async getByIds(ids, opt = {}) {
-        if (!ids.length)
-            return [];
-        const op = `getByIds ${ids.length} id(s) (${_truncate(ids.slice(0, 10).join(', '), 50)})`;
-        const table = opt.table || this.cfg.table;
-        const started = this.logStarted(op, table);
-        let dbms = await (opt.tx || this.cfg.db).getByIds(table, ids, opt);
-        if (this.cfg.hooks.afterLoad && dbms.length) {
-            dbms = (await pMap(dbms, async (dbm) => await this.cfg.hooks.afterLoad(dbm))).filter(_isTruthy);
-        }
-        const bms = await this.dbmsToBM(dbms, opt);
-        this.logResult(started, op, bms, table);
-        return bms;
+        const dbms = await this.loadByIds(ids, opt);
+        return await this.dbmsToBM(dbms, opt);
     }
     async getByIdsAsDBM(ids, opt = {}) {
+        const rows = await this.loadByIds(ids, opt);
+        return this.anyToDBMs(rows);
+    }
+    // DRY private method
+    async loadByIds(ids, opt = {}) {
         if (!ids.length)
             return [];
-        const op = `getByIdsAsDBM ${ids.length} id(s) (${_truncate(ids.slice(0, 10).join(', '), 50)})`;
-        const table = opt.table || this.cfg.table;
-        const started = this.logStarted(op, table);
-        let dbms = await (opt.tx || this.cfg.db).getByIds(table, ids, opt);
-        if (this.cfg.hooks.afterLoad && dbms.length) {
-            dbms = (await pMap(dbms, async (dbm) => await this.cfg.hooks.afterLoad(dbm))).filter(_isTruthy);
-        }
-        this.logResult(started, op, dbms, table);
-        return dbms;
-    }
-    async requireById(id, opt = {}) {
-        const r = await this.getById(id, opt);
-        if (!r) {
-            this.throwRequiredError(id, opt);
-        }
-        return r;
-    }
-    async requireByIdAsDBM(id, opt = {}) {
-        const r = await this.getByIdAsDBM(id, opt);
-        if (!r) {
-            this.throwRequiredError(id, opt);
-        }
-        return r;
-    }
-    throwRequiredError(id, opt) {
         const table = opt.table || this.cfg.table;
-        throw new AppError(`DB row required, but not found in ${table}`, {
-            table,
-            id,
-        });
-    }
-    /**
-     * Throws if readOnly is true
-     */
-    requireWriteAccess() {
-        if (this.cfg.readOnly) {
-            throw new AppError(DBLibError.DAO_IS_READ_ONLY, {
-                table: this.cfg.table,
-            });
-        }
-    }
-    /**
-     * Throws if readOnly is true
-     */
-    requireObjectMutability(opt) {
-        if (this.cfg.immutable && !opt.allowMutability) {
-            throw new AppError(DBLibError.OBJECT_IS_IMMUTABLE, {
-                table: this.cfg.table,
-            });
-        }
-    }
-    async ensureUniqueId(table, dbm) {
-        // todo: retry N times
-        const existing = await this.cfg.db.getByIds(table, [dbm.id]);
-        if (existing.length) {
-            throw new AppError(DBLibError.NON_UNIQUE_ID, {
-                table,
-                ids: existing.map(i => i.id),
-            });
-        }
+        return await (opt.tx || this.cfg.db).getByIds(table, ids, opt);
     }
     async getBy(by, value, limit = 0, opt) {
         return await this.query().filterEq(by, value).limit(limit).runQuery(opt);
@@ -215,15 +136,9 @@ export class CommonDao {
     async runQueryExtended(q, opt = {}) {
         this.validateQueryIndexes(q); // throws if query uses `excludeFromIndexes` property
         q.table = opt.table || q.table;
-        const op = `runQuery(${q.pretty()})`;
-        const started = this.logStarted(op, q.table);
-        let { rows, ...queryResult } = await this.cfg.db.runQuery(q, opt);
-        const partialQuery = !!q._selectedFieldNames;
-        if (this.cfg.hooks.afterLoad && rows.length) {
-            rows = (await pMap(rows, async (dbm) => await this.cfg.hooks.afterLoad(dbm))).filter(_isTruthy);
-        }
-        const bms = partialQuery ? rows : await this.dbmsToBM(rows, opt);
-        this.logResult(started, op, bms, q.table);
+        const { rows, ...queryResult } = await this.cfg.db.runQuery(q, opt);
+        const isPartialQuery = !!q._selectedFieldNames;
+        const bms = isPartialQuery ? rows : await this.dbmsToBM(rows, opt);
         return {
             rows: bms,
             ...queryResult,
@@ -236,48 +151,27 @@ export class CommonDao {
     async runQueryExtendedAsDBM(q, opt = {}) {
         this.validateQueryIndexes(q); // throws if query uses `excludeFromIndexes` property
         q.table = opt.table || q.table;
-        const op = `runQueryAsDBM(${q.pretty()})`;
-        const started = this.logStarted(op, q.table);
-        let { rows, ...queryResult } = await this.cfg.db.runQuery(q, opt);
-        if (this.cfg.hooks.afterLoad && rows.length) {
-            rows = (await pMap(rows, async (dbm) => await this.cfg.hooks.afterLoad(dbm))).filter(_isTruthy);
-        }
-        const partialQuery = !!q._selectedFieldNames;
-        const dbms = partialQuery ? rows : this.anyToDBMs(rows, opt);
-        this.logResult(started, op, dbms, q.table);
+        const { rows, ...queryResult } = await this.cfg.db.runQuery(q, opt);
+        const isPartialQuery = !!q._selectedFieldNames;
+        const dbms = isPartialQuery ? rows : this.anyToDBMs(rows, opt);
         return { rows: dbms, ...queryResult };
     }
     async runQueryCount(q, opt = {}) {
         this.validateQueryIndexes(q); // throws if query uses `excludeFromIndexes` property
         q.table = opt.table || q.table;
-        const op = `runQueryCount(${q.pretty()})`;
-        const started = this.logStarted(op, q.table);
-        const count = await this.cfg.db.runQueryCount(q, opt);
-        if (this.cfg.logLevel >= CommonDaoLogLevel.OPERATIONS) {
-            this.cfg.logger?.log(`<< ${q.table}.${op}: ${count} row(s) in ${_since(started)}`);
-        }
-        return count;
+        return await this.cfg.db.runQueryCount(q, opt);
     }
     async streamQueryForEach(q, mapper, opt = {}) {
         this.validateQueryIndexes(q); // throws if query uses `excludeFromIndexes` property
         q.table = opt.table || q.table;
         opt.skipValidation = opt.skipValidation !== false; // default true
         opt.errorMode ||= ErrorMode.SUPPRESS;
-        const partialQuery = !!q._selectedFieldNames;
-        const op = `streamQueryForEach(${q.pretty()})`;
-        const started = this.logStarted(op, q.table, true);
-        let count = 0;
+        const isPartialQuery = !!q._selectedFieldNames;
         await _pipeline([
             this.cfg.db.streamQuery(q, opt),
             transformMap(async (dbm) => {
-                count++;
-                if (partialQuery)
+                if (isPartialQuery)
                     return dbm;
-                if (this.cfg.hooks.afterLoad) {
-                    dbm = (await this.cfg.hooks.afterLoad(dbm));
-                    if (dbm === null)
-                        return SKIP;
-                }
                 return await this.dbmToBM(dbm, opt);
             }, {
                 errorMode: opt.errorMode,
@@ -293,30 +187,18 @@ export class CommonDao {
             }),
             writableVoid(),
         ]);
-        if (this.cfg.logLevel >= CommonDaoLogLevel.OPERATIONS) {
-            this.cfg.logger?.log(`<< ${q.table}.${op}: ${count} row(s) in ${_since(started)}`);
-        }
     }
     async streamQueryAsDBMForEach(q, mapper, opt = {}) {
         this.validateQueryIndexes(q); // throws if query uses `excludeFromIndexes` property
         q.table = opt.table || q.table;
         opt.skipValidation = opt.skipValidation !== false; // default true
         opt.errorMode ||= ErrorMode.SUPPRESS;
-        const partialQuery = !!q._selectedFieldNames;
-        const op = `streamQueryAsDBMForEach(${q.pretty()})`;
-        const started = this.logStarted(op, q.table, true);
-        let count = 0;
+        const isPartialQuery = !!q._selectedFieldNames;
         await _pipeline([
             this.cfg.db.streamQuery(q, opt),
-            transformMap(async (dbm) => {
-                count++;
-                if (partialQuery)
+            transformMapSync(dbm => {
+                if (isPartialQuery)
                     return dbm;
-                if (this.cfg.hooks.afterLoad) {
-                    dbm = (await this.cfg.hooks.afterLoad(dbm));
-                    if (dbm === null)
-                        return SKIP;
-                }
                 return this.anyToDBM(dbm, opt);
             }, {
                 errorMode: opt.errorMode,
@@ -332,9 +214,6 @@ export class CommonDao {
             }),
             writableVoid(),
         ]);
-        if (this.cfg.logLevel >= CommonDaoLogLevel.OPERATIONS) {
-            this.cfg.logger?.log(`<< ${q.table}.${op}: ${count} row(s) in ${_since(started)}`);
-        }
     }
     /**
      * Stream as Readable, to be able to .pipe() it further with support of backpressure.
@@ -344,19 +223,14 @@ export class CommonDao {
         q.table = opt.table || q.table;
         opt.skipValidation = opt.skipValidation !== false; // default true
         opt.errorMode ||= ErrorMode.SUPPRESS;
-        const partialQuery = !!q._selectedFieldNames;
+        const isPartialQuery = !!q._selectedFieldNames;
         const stream = this.cfg.db.streamQuery(q, opt);
-        if (partialQuery)
+        if (isPartialQuery)
             return stream;
         return (stream
             // the commented out line was causing RangeError: Maximum call stack size exceeded
             // .on('error', err => stream.emit('error', err))
-            .pipe(transformMap(async (dbm) => {
-            if (this.cfg.hooks.afterLoad) {
-                dbm = (await this.cfg.hooks.afterLoad(dbm));
-                if (dbm === null)
-                    return SKIP;
-            }
+            .pipe(transformMapSync(dbm => {
             return this.anyToDBM(dbm, opt);
         }, {
             errorMode: opt.errorMode,
@@ -377,16 +251,11 @@ export class CommonDao {
         opt.skipValidation = opt.skipValidation !== false; // default true
         opt.errorMode ||= ErrorMode.SUPPRESS;
         const stream = this.cfg.db.streamQuery(q, opt);
-        const partialQuery = !!q._selectedFieldNames;
-        if (partialQuery)
+        const isPartialQuery = !!q._selectedFieldNames;
+        if (isPartialQuery)
             return stream;
         // This almost works, but hard to implement `errorMode: THROW_AGGREGATED` in this case
         // return stream.flatMap(async (dbm: DBM) => {
-        //   if (this.cfg.hooks!.afterLoad) {
-        //     dbm = (await this.cfg.hooks!.afterLoad(dbm))!
-        //     if (dbm === null) return [] // SKIP
-        //   }
-        //
         //   return [await this.dbmToBM(dbm, opt)] satisfies BM[]
         // }, {
         //   concurrency: 16,
@@ -398,11 +267,6 @@ export class CommonDao {
             // the commented out line was causing RangeError: Maximum call stack size exceeded
             // .on('error', err => stream.emit('error', err))
             .pipe(transformMap(async (dbm) => {
-            if (this.cfg.hooks.afterLoad) {
-                dbm = (await this.cfg.hooks.afterLoad(dbm));
-                if (dbm === null)
-                    return SKIP;
-            }
             return await this.dbmToBM(dbm, opt);
         }, {
             errorMode: opt.errorMode,
@@ -442,14 +306,8 @@ export class CommonDao {
         this.validateQueryIndexes(q); // throws if query uses `excludeFromIndexes` property
         q.table = opt.table || q.table;
         opt.errorMode ||= ErrorMode.SUPPRESS;
-        const op = `streamQueryIdsForEach(${q.pretty()})`;
-        const started = this.logStarted(op, q.table, true);
-        let count = 0;
         await _pipeline([
-            this.cfg.db.streamQuery(q.select(['id']), opt).map(r => {
-                count++;
-                return r.id;
-            }),
+            this.cfg.db.streamQuery(q.select(['id']), opt).map(r => r.id),
             transformMap(mapper, {
                 ...opt,
                 predicate: _passthroughPredicate,
@@ -461,13 +319,9 @@ export class CommonDao {
             }),
             writableVoid(),
         ]);
-        if (this.cfg.logLevel >= CommonDaoLogLevel.OPERATIONS) {
-            this.cfg.logger?.log(`<< ${q.table}.${op}: ${count} id(s) in ${_since(started)}`);
-        }
     }
     /**
      * Mutates!
-     * "Returns", just to have a type of "Saved"
      */
     assignIdCreatedUpdated(obj, opt = {}) {
         const now = localTime.nowUnix();
@@ -481,7 +335,6 @@ export class CommonDao {
             obj.id ||= (this.cfg.hooks.createNaturalId?.(obj) ||
                 this.cfg.hooks.createRandomId());
         }
-        return obj;
     }
     // SAVE
     /**
@@ -599,7 +452,6 @@ export class CommonDao {
                 return bm;
             }
         }
-        const idWasGenerated = !bm.id && this.cfg.generateId;
         this.assignIdCreatedUpdated(bm, opt); // mutates
         _typeCast(bm);
         let dbm = await this.bmToDBM(bm, opt); // validates BM
@@ -609,125 +461,76 @@ export class CommonDao {
                 return bm;
         }
         const table = opt.table || this.cfg.table;
-        if (opt.ensureUniqueId && idWasGenerated)
-            await this.ensureUniqueId(table, dbm);
-        if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
-            opt = { ...opt, saveMethod: 'insert' };
-        }
-        const op = `save(${dbm.id})`;
-        const started = this.logSaveStarted(op, bm, table);
-        const { excludeFromIndexes } = this.cfg;
-        const assignGeneratedIds = opt.assignGeneratedIds || this.cfg.assignGeneratedIds;
-        await (opt.tx || this.cfg.db).saveBatch(table, [dbm], {
-            excludeFromIndexes,
-            assignGeneratedIds,
-            ...opt,
-        });
-        if (assignGeneratedIds) {
+        const saveOptions = this.prepareSaveOptions(opt);
+        await (opt.tx || this.cfg.db).saveBatch(table, [dbm], saveOptions);
+        if (saveOptions.assignGeneratedIds) {
             bm.id = dbm.id;
         }
-        this.logSaveResult(started, op, table);
         return bm;
     }
     async saveAsDBM(dbm, opt = {}) {
         this.requireWriteAccess();
-        const table = opt.table || this.cfg.table;
-        // assigning id in case it misses the id
-        // will override/set `updated` field, unless opts.preserveUpdated is set
-        const idWasGenerated = !dbm.id && this.cfg.generateId;
         this.assignIdCreatedUpdated(dbm, opt); // mutates
         let row = this.anyToDBM(dbm, opt);
-        if (opt.ensureUniqueId && idWasGenerated)
-            await this.ensureUniqueId(table, row);
-        if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
-            opt = { ...opt, saveMethod: 'insert' };
-        }
-        const op = `saveAsDBM(${row.id})`;
-        const started = this.logSaveStarted(op, row, table);
-        const { excludeFromIndexes } = this.cfg;
-        const assignGeneratedIds = opt.assignGeneratedIds || this.cfg.assignGeneratedIds;
         if (this.cfg.hooks.beforeSave) {
             row = (await this.cfg.hooks.beforeSave(row));
             if (row === null)
                 return dbm;
         }
-        await (opt.tx || this.cfg.db).saveBatch(table, [row], {
-            excludeFromIndexes,
-            assignGeneratedIds,
-            ...opt,
-        });
-        if (assignGeneratedIds) {
+        const table = opt.table || this.cfg.table;
+        const saveOptions = this.prepareSaveOptions(opt);
+        await (opt.tx || this.cfg.db).saveBatch(table, [row], saveOptions);
+        if (saveOptions.assignGeneratedIds) {
             dbm.id = row.id;
         }
-        this.logSaveResult(started, op, table);
         return row;
     }
     async saveBatch(bms, opt = {}) {
         if (!bms.length)
             return [];
         this.requireWriteAccess();
-        const table = opt.table || this.cfg.table;
         bms.forEach(bm => this.assignIdCreatedUpdated(bm, opt));
         let dbms = await this.bmsToDBM(bms, opt);
         if (this.cfg.hooks.beforeSave && dbms.length) {
             dbms = (await pMap(dbms, async (dbm) => await this.cfg.hooks.beforeSave(dbm))).filter(_isTruthy);
         }
-        if (opt.ensureUniqueId)
-            throw new AppError('ensureUniqueId is not supported in saveBatch');
-        if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
-            opt = { ...opt, saveMethod: 'insert' };
-        }
-        const op = `saveBatch ${dbms.length} row(s) (${_truncate(dbms
-            .slice(0, 10)
-            .map(bm => bm.id)
-            .join(', '), 50)})`;
-        const started = this.logSaveStarted(op, bms, table);
-        const { excludeFromIndexes } = this.cfg;
-        const assignGeneratedIds = opt.assignGeneratedIds || this.cfg.assignGeneratedIds;
-        await (opt.tx || this.cfg.db).saveBatch(table, dbms, {
-            excludeFromIndexes,
-            assignGeneratedIds,
-            ...opt,
-        });
-        if (assignGeneratedIds) {
+        const table = opt.table || this.cfg.table;
+        const saveOptions = this.prepareSaveOptions(opt);
+        await (opt.tx || this.cfg.db).saveBatch(table, dbms, saveOptions);
+        if (saveOptions.assignGeneratedIds) {
             dbms.forEach((dbm, i) => (bms[i].id = dbm.id));
         }
-        this.logSaveResult(started, op, table);
         return bms;
     }
     async saveBatchAsDBM(dbms, opt = {}) {
         if (!dbms.length)
             return [];
         this.requireWriteAccess();
-        const table = opt.table || this.cfg.table;
-        dbms.forEach(dbm => this.assignIdCreatedUpdated(dbm, opt)); // mutates
+        dbms.forEach(dbm => this.assignIdCreatedUpdated(dbm, opt));
         let rows = this.anyToDBMs(dbms, opt);
-        if (opt.ensureUniqueId)
-            throw new AppError('ensureUniqueId is not supported in saveBatch');
-        if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
-            opt = { ...opt, saveMethod: 'insert' };
-        }
-        const op = `saveBatchAsDBM ${rows.length} row(s) (${_truncate(rows
-            .slice(0, 10)
-            .map(bm => bm.id)
-            .join(', '), 50)})`;
-        const started = this.logSaveStarted(op, rows, table);
-        const { excludeFromIndexes } = this.cfg;
-        const assignGeneratedIds = opt.assignGeneratedIds || this.cfg.assignGeneratedIds;
         if (this.cfg.hooks.beforeSave && rows.length) {
             rows = (await pMap(rows, async (row) => await this.cfg.hooks.beforeSave(row))).filter(_isTruthy);
         }
-        await (opt.tx || this.cfg.db).saveBatch(table, rows, {
-            excludeFromIndexes,
-            assignGeneratedIds,
-            ...opt,
-        });
-        if (assignGeneratedIds) {
+        const table = opt.table || this.cfg.table;
+        const saveOptions = this.prepareSaveOptions(opt);
+        await (opt.tx || this.cfg.db).saveBatch(table, rows, saveOptions);
+        if (saveOptions.assignGeneratedIds) {
             rows.forEach((row, i) => (dbms[i].id = row.id));
         }
-        this.logSaveResult(started, op, table);
         return rows;
     }
+    prepareSaveOptions(opt) {
+        let { saveMethod, assignGeneratedIds = this.cfg.assignGeneratedIds, excludeFromIndexes = this.cfg.excludeFromIndexes, } = opt;
+        if (this.cfg.immutable && !opt.allowMutability && !opt.saveMethod) {
+            saveMethod = 'insert';
+        }
+        return {
+            ...opt,
+            excludeFromIndexes,
+            saveMethod,
+            assignGeneratedIds,
+        };
+    }
     /**
      * "Streaming" is implemented by buffering incoming rows into **batches**
      * (of size opt.chunkSize, which defaults to 500),
@@ -793,12 +596,8 @@ export class CommonDao {
             return 0;
         this.requireWriteAccess();
         this.requireObjectMutability(opt);
-        const op = `deleteByIds(${ids.join(', ')})`;
         const table = opt.table || this.cfg.table;
-        const started = this.logStarted(op, table);
-        const count = await (opt.tx || this.cfg.db).deleteByIds(table, ids, opt);
-        this.logSaveResult(started, op, table);
-        return count;
+        return await (opt.tx || this.cfg.db).deleteByIds(table, ids, opt);
     }
     /**
      * Pass `chunkSize: number` (e.g 500) option to use Streaming: it will Stream the query, chunk by 500, and execute
@@ -810,8 +609,6 @@ export class CommonDao {
         this.requireWriteAccess();
         this.requireObjectMutability(opt);
         q.table = opt.table || q.table;
-        const op = `deleteByQuery(${q.pretty()})`;
-        const started = this.logStarted(op, q.table);
         let deleted = 0;
         if (opt.chunkSize) {
             const { chunkSize, chunkConcurrency = 8 } = opt;
@@ -839,7 +636,6 @@ export class CommonDao {
         else {
             deleted = await this.cfg.db.deleteByQuery(q, opt);
         }
-        this.logSaveResult(started, op, q.table);
         return deleted;
     }
     async patchByIds(ids, patch, opt = {}) {
@@ -852,11 +648,7 @@ export class CommonDao {
         this.requireWriteAccess();
         this.requireObjectMutability(opt);
         q.table = opt.table || q.table;
-        const op = `patchByQuery(${q.pretty()})`;
-        const started = this.logStarted(op, q.table);
-        const updated = await this.cfg.db.patchByQuery(q, patch, opt);
-        this.logSaveResult(started, op, q.table);
-        return updated;
+        return await this.cfg.db.patchByQuery(q, patch, opt);
     }
     /**
      * Caveat: it doesn't update created/updated props.
@@ -867,12 +659,9 @@ export class CommonDao {
         this.requireWriteAccess();
         this.requireObjectMutability(opt);
         const { table } = this.cfg;
-        const op = `increment`;
-        const started = this.logStarted(op, table);
         const result = await this.cfg.db.incrementBatch(table, prop, {
             [id]: by,
         });
-        this.logSaveResult(started, op, table);
         return result[id];
     }
     /**
@@ -884,15 +673,11 @@ export class CommonDao {
         this.requireWriteAccess();
         this.requireObjectMutability(opt);
         const { table } = this.cfg;
-        const op = `incrementBatch`;
-        const started = this.logStarted(op, table);
-        const result = await this.cfg.db.incrementBatch(table, prop, incrementMap);
-        this.logSaveResult(started, op, table);
-        return result;
+        return await this.cfg.db.incrementBatch(table, prop, incrementMap);
     }
     async dbmToBM(_dbm, opt = {}) {
         if (!_dbm)
-            return;
+            return null;
         // optimization: no need to run full joi DBM validation, cause BM validation will be run
         // const dbm = this.anyToDBM(_dbm, opt)
         let dbm = { ..._dbm, ...this.cfg.hooks.parseNaturalId(_dbm.id) };
@@ -909,7 +694,7 @@ export class CommonDao {
     }
     async bmToDBM(bm, opt) {
         if (bm === undefined)
-            return;
+            return null;
         // bm gets assigned to the new reference
         bm = this.validateAndConvert(bm, 'save', opt);
         // BM > DBM
@@ -921,7 +706,7 @@ export class CommonDao {
     }
     anyToDBM(dbm, opt = {}) {
         if (!dbm)
-            return;
+            return null;
         // this shouldn't be happening on load! but should on save!
         // this.assignIdCreatedUpdated(dbm, opt)
         dbm = { ...dbm, ...this.cfg.hooks.parseNaturalId(dbm.id) };
@@ -934,8 +719,8 @@ export class CommonDao {
         // return this.validateAndConvert(dbm, this.cfg.dbmSchema, DBModelType.DBM, opt)
         return dbm;
     }
-    anyToDBMs(entities, opt = {}) {
-        return entities.map(entity => this.anyToDBM(entity, opt));
+    anyToDBMs(rows, opt = {}) {
+        return rows.map(entity => this.anyToDBM(entity, opt));
     }
     /**
      * Returns *converted value* (NOT the same reference).
@@ -994,10 +779,17 @@ export class CommonDao {
             ids,
         };
     }
-    toSave(input) {
+    withRows(rows) {
+        return {
+            dao: this,
+            rows: rows,
+        };
+    }
+    withRow(row, opt) {
         return {
             dao: this,
-            rows: [input].flat(),
+            row: row,
+            opt: opt,
         };
     }
     /**
@@ -1091,10 +883,31 @@ export class CommonDao {
             return;
         const { db } = inputs[0].dao.cfg;
         const dbmsByTable = {};
-        await pMap(inputs, async ({ dao, rows }) => {
+        await pMap(inputs, async (input) => {
+            const { dao } = input;
             const { table } = dao.cfg;
-            rows.forEach(bm => dao.assignIdCreatedUpdated(bm, opt));
-            dbmsByTable[table] = await dao.bmsToDBM(rows, opt);
+            dbmsByTable[table] ||= [];
+            if ('row' in input) {
+                // Singular
+                const { row } = input;
+                if (input.opt?.skipIfEquals) {
+                    // We compare with convertedBM, to account for cases when some extra property is assigned to bm,
+                    // which should be removed post-validation, but it breaks the "equality check"
+                    // Post-validation the equality check should work as intended
+                    const convertedBM = dao.validateAndConvert(row, 'save', opt);
+                    if (_deepJsonEquals(convertedBM, input.opt.skipIfEquals)) {
+                        // Skipping the save operation
+                        return;
+                    }
+                }
+                dao.assignIdCreatedUpdated(row, opt);
+                dbmsByTable[table].push(await dao.bmToDBM(row, opt));
+            }
+            else {
+                // Plural
+                input.rows.forEach(bm => dao.assignIdCreatedUpdated(bm, opt));
+                dbmsByTable[table].push(...(await dao.bmsToDBM(input.rows, opt)));
+            }
         });
         await db.multiSave(dbmsByTable);
     }
@@ -1116,6 +929,30 @@ export class CommonDao {
         }, opt);
         return r;
     }
+    ensureRequired(row, id, opt) {
+        const table = opt.table || this.cfg.table;
+        _assert(row, `DB row required, but not found in ${table}`, {
+            table,
+            id,
+        });
+        return row; // pass-through
+    }
+    /**
+     * Throws if readOnly is true
+     */
+    requireWriteAccess() {
+        _assert(!this.cfg.readOnly, DBLibError.DAO_IS_READ_ONLY, {
+            table: this.cfg.table,
+        });
+    }
+    /**
+     * Throws if readOnly is true
+     */
+    requireObjectMutability(opt) {
+        _assert(!this.cfg.immutable || opt.allowMutability, DBLibError.OBJECT_IS_IMMUTABLE, {
+            table: this.cfg.table,
+        });
+    }
     /**
      * Throws if query uses a property that is in `excludeFromIndexes` list.
      */
@@ -1129,135 +966,4 @@ export class CommonDao {
             });
         }
     }
-    logResult(started, op, res, table) {
-        if (!this.cfg.logLevel)
-            return;
-        let logRes;
-        const args = [];
-        if (Array.isArray(res)) {
-            logRes = `${res.length} row(s)`;
-            if (res.length && this.cfg.logLevel >= CommonDaoLogLevel.DATA_FULL) {
-                args.push('\n', ...res.slice(0, 10)); // max 10 items
-            }
-        }
-        else if (res) {
-            logRes = `1 row`;
-            if (this.cfg.logLevel >= CommonDaoLogLevel.DATA_SINGLE) {
-                args.push('\n', res);
-            }
-        }
-        else {
-            logRes = `undefined`;
-        }
-        this.cfg.logger?.log(`<< ${table}.${op}: ${logRes} in ${_since(started)}`, ...args);
-    }
-    logSaveResult(started, op, table) {
-        if (!this.cfg.logLevel)
-            return;
-        this.cfg.logger?.log(`<< ${table}.${op} in ${_since(started)}`);
-    }
-    logStarted(op, table, force = false) {
-        if (this.cfg.logStarted || force) {
-            this.cfg.logger?.log(`>> ${table}.${op}`);
-        }
-        return localTime.nowUnixMillis();
-    }
-    logSaveStarted(op, items, table) {
-        if (this.cfg.logStarted) {
-            const args = [`>> ${table}.${op}`];
-            if (Array.isArray(items)) {
-                if (items.length && this.cfg.logLevel >= CommonDaoLogLevel.DATA_FULL) {
-                    args.push('\n', ...items.slice(0, 10));
-                }
-                else {
-                    args.push(`${items.length} row(s)`);
-                }
-            }
-            else {
-                if (this.cfg.logLevel >= CommonDaoLogLevel.DATA_SINGLE) {
-                    args.push(items);
-                }
-            }
-            this.cfg.logger?.log(...args);
-        }
-        return localTime.nowUnixMillis();
-    }
-}
-/**
- * Transaction context.
- * Has similar API than CommonDao, but all operations are performed in the context of the transaction.
- */
-export class CommonDaoTransaction {
-    tx;
-    logger;
-    constructor(tx, logger) {
-        this.tx = tx;
-        this.logger = logger;
-    }
-    /**
-     * Commits the underlying DBTransaction.
-     * May throw.
-     */
-    async commit() {
-        await this.tx.commit();
-    }
-    /**
-     * Perform a graceful rollback without throwing/re-throwing any error.
-     * Never throws.
-     */
-    async rollback() {
-        try {
-            await this.tx.rollback();
-        }
-        catch (err) {
-            // graceful rollback without re-throw
-            this.logger.error(err);
-        }
-    }
-    async getById(dao, id, opt) {
-        return await dao.getById(id, { ...opt, tx: this.tx });
-    }
-    async getByIds(dao, ids, opt) {
-        return await dao.getByIds(ids, { ...opt, tx: this.tx });
-    }
-    // todo: Queries inside Transaction are not supported yet
-    // async runQuery<BM extends PartialObjectWithId, DBM extends ObjectWithId>(
-    //   dao: CommonDao<BM, DBM, any>,
-    //   q: DBQuery<DBM>,
-    //   opt?: CommonDaoOptions,
-    // ): Promise<BM[]> {
-    //   try {
-    //     return await dao.runQuery(q, { ...opt, tx: this.tx })
-    //   } catch (err) {
-    //     await this.rollback()
-    //     throw err
-    //   }
-    // }
-    async save(dao, bm, opt) {
-        return await dao.save(bm, { ...opt, tx: this.tx });
-    }
-    async saveBatch(dao, bms, opt) {
-        return await dao.saveBatch(bms, { ...opt, tx: this.tx });
-    }
-    /**
-     * DaoTransaction.patch does not load from DB.
-     * It assumes the bm was previously loaded in the same Transaction, hence could not be
-     * concurrently modified. Hence it's safe to not sync with DB.
-     *
-     * So, this method is a rather simple convenience "Object.assign and then save".
-     */
-    async patch(dao, bm, patch, opt) {
-        const skipIfEquals = _deepCopy(bm);
-        Object.assign(bm, patch);
-        return await dao.save(bm, { ...opt, skipIfEquals, tx: this.tx });
-    }
-    // todo: use AnyDao/Infer in other methods as well, if this works well
-    async deleteById(dao, id, opt) {
-        if (!id)
-            return 0;
-        return await this.deleteByIds(dao, [id], opt);
-    }
-    async deleteByIds(dao, ids, opt) {
-        return await dao.deleteByIds(ids, { ...opt, tx: this.tx });
-    }
 }