@naturalcycles/db-lib 8.36.1 → 8.38.0

package/dist/adapter/cachedb/cache.db.d.ts

@@ -24,7 +24,7 @@ export declare class CacheDB extends BaseCommonDB implements CommonDB {
     createTable<ROW extends ObjectWithId>(table: string, schema: JsonSchemaObject<ROW>, opt?: CacheDBCreateOptions): Promise<void>;
     getByIds<ROW extends ObjectWithId>(table: string, ids: ROW['id'][], opt?: CacheDBSaveOptions<ROW>): Promise<ROW[]>;
     deleteByIds<ROW extends ObjectWithId>(table: string, ids: ROW['id'][], opt?: CacheDBOptions): Promise<number>;
-    saveBatch<ROW extends ObjectWithId>(table: string, rows: ROW[], opt?: CacheDBSaveOptions<ROW>): Promise<void>;
+    saveBatch<ROW extends Partial<ObjectWithId>>(table: string, rows: ROW[], opt?: CacheDBSaveOptions<ROW>): Promise<void>;
     runQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CacheDBSaveOptions<ROW>): Promise<RunQueryResult<ROW>>;
     runQueryCount<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CacheDBOptions): Promise<number>;
     streamQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CacheDBStreamOptions): Readable;

package/dist/adapter/cachedb/cache.db.model.d.ts

@@ -47,7 +47,7 @@ export interface CacheDBOptions {
      */
     onlyCache?: boolean;
 }
-export interface CacheDBSaveOptions<ROW extends ObjectWithId> extends CacheDBOptions, CommonDBSaveOptions<ROW> {
+export interface CacheDBSaveOptions<ROW extends Partial<ObjectWithId>> extends CacheDBOptions, CommonDBSaveOptions<ROW> {
 }
 export interface CacheDBStreamOptions extends CacheDBOptions, CommonDBStreamOptions {
 }

package/dist/adapter/file/file.db.d.ts

@@ -22,7 +22,7 @@ export declare class FileDB extends BaseCommonDB implements CommonDB {
     ping(): Promise<void>;
     getTables(): Promise<string[]>;
     getByIds<ROW extends ObjectWithId>(table: string, ids: ROW['id'][], _opt?: CommonDBOptions): Promise<ROW[]>;
-    saveBatch<ROW extends ObjectWithId>(table: string, rows: ROW[], _opt?: CommonDBSaveOptions<ROW>): Promise<void>;
+    saveBatch<ROW extends Partial<ObjectWithId>>(table: string, rows: ROW[], _opt?: CommonDBSaveOptions<ROW>): Promise<void>;
     /**
      * Implementation is optimized for loading/saving _whole files_.
      */

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

@@ -46,6 +46,7 @@ class FileDB extends __1.BaseCommonDB {
         // 2. Merge with new data (using ids)
         let saved = 0;
         rows.forEach(r => {
+            (0, js_lib_1._assert)(r.id, 'FileDB: row.id is required');
             if (!(0, js_lib_1._deepEquals)(byId[r.id], r)) {
                 byId[r.id] = r;
                 saved++;

package/dist/adapter/inmemory/inMemory.db.d.ts

@@ -53,7 +53,7 @@ export declare class InMemoryDB implements CommonDB {
     getTableSchema<ROW extends ObjectWithId>(_table: string): Promise<JsonSchemaRootObject<ROW>>;
     createTable<ROW extends ObjectWithId>(_table: string, _schema: JsonSchemaObject<ROW>, opt?: CommonDBCreateOptions): Promise<void>;
     getByIds<ROW extends ObjectWithId>(_table: string, ids: ROW['id'][], _opt?: CommonDBOptions): Promise<ROW[]>;
-    saveBatch<ROW extends ObjectWithId>(_table: string, rows: ROW[], _opt?: CommonDBSaveOptions<ROW>): Promise<void>;
+    saveBatch<ROW extends Partial<ObjectWithId>>(_table: string, rows: ROW[], opt?: CommonDBSaveOptions<ROW>): Promise<void>;
     deleteByIds<ROW extends ObjectWithId>(_table: string, ids: ROW['id'][], _opt?: CommonDBOptions): Promise<number>;
     deleteByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, _opt?: CommonDBOptions): Promise<number>;
     runQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, _opt?: CommonDBOptions): Promise<RunQueryResult<ROW>>;

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

@@ -73,25 +73,25 @@ class InMemoryDB {
         (_a = this.data)[table] || (_a[table] = {});
         return ids.map(id => this.data[table][id]).filter(Boolean);
     }
-    async saveBatch(_table, rows, _opt) {
+    async saveBatch(_table, rows, opt = {}) {
         var _a;
         const table = this.cfg.tablesPrefix + _table;
         (_a = this.data)[table] || (_a[table] = {});
         rows.forEach(r => {
             if (!r.id) {
                 this.cfg.logger?.warn({ rows });
-                throw new Error(`InMemoryDB: id doesn't exist for row`);
+                throw new Error(`InMemoryDB doesn't support id auto-generation in saveBatch, row without id was given`);
+            }
+            if (opt.saveMethod === 'insert' && this.data[table][r.id]) {
+                throw new Error(`InMemoryDB: INSERT failed, entity exists: ${table}.${r.id}`);
+            }
+            if (opt.saveMethod === 'update' && !this.data[table][r.id]) {
+                throw new Error(`InMemoryDB: UPDATE failed, entity doesn't exist: ${table}.${r.id}`);
             }
             // JSON parse/stringify (deep clone) is to:
             // 1. Not store values "by reference" (avoid mutation bugs)
             // 2. Simulate real DB that would do something like that in a transport layer anyway
             this.data[table][r.id] = JSON.parse(JSON.stringify(r), nodejs_lib_1.bufferReviver);
-            // special treatment for Buffers (assign them raw, without JSON parse/stringify)
-            // Object.entries(r).forEach(([k, v]) => {
-            //   if (Buffer.isBuffer(v)) {
-            //     this.data[table]![r.id]![k] = v
-            //   }
-            // })
         });
     }
     async deleteByIds(_table, ids, _opt) {

package/dist/base.common.db.d.ts

@@ -18,7 +18,7 @@ export declare class BaseCommonDB implements CommonDB {
     getByIds<ROW extends ObjectWithId>(_table: string, _ids: ROW['id'][]): Promise<ROW[]>;
     runQuery<ROW extends ObjectWithId>(_q: DBQuery<ROW>): Promise<RunQueryResult<ROW>>;
     runQueryCount<ROW extends ObjectWithId>(_q: DBQuery<ROW>): Promise<number>;
-    saveBatch<ROW extends ObjectWithId>(_table: string, _rows: ROW[], _opt?: CommonDBSaveOptions<ROW>): Promise<void>;
+    saveBatch<ROW extends Partial<ObjectWithId>>(_table: string, _rows: ROW[], _opt?: CommonDBSaveOptions<ROW>): Promise<void>;
     streamQuery<ROW extends ObjectWithId>(_q: DBQuery<ROW>): ReadableTyped<ROW>;
     /**
      * Naive implementation.

package/dist/common.db.d.ts

@@ -38,7 +38,10 @@ export interface CommonDB {
     runQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBOptions): Promise<RunQueryResult<ROW>>;
     runQueryCount<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBOptions): Promise<number>;
     streamQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBStreamOptions): ReadableTyped<ROW>;
-    saveBatch<ROW extends ObjectWithId>(table: string, rows: ROW[], opt?: CommonDBSaveOptions<ROW>): Promise<void>;
+    /**
+     * rows can have missing ids only if DB supports auto-generating them (like mysql auto_increment).
+     */
+    saveBatch<ROW extends Partial<ObjectWithId>>(table: string, rows: ROW[], opt?: CommonDBSaveOptions<ROW>): Promise<void>;
     /**
      * Returns number of deleted items.
      * Not supported by all implementations (e.g Datastore will always return same number as number of ids).

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

@@ -1,4 +1,4 @@
-import { AsyncMapper, JsonSchemaObject, JsonSchemaRootObject, ObjectWithId, Saved } from '@naturalcycles/js-lib';
+import { AsyncMapper, JsonSchemaObject, JsonSchemaRootObject, ObjectWithId, Saved, Unsaved } from '@naturalcycles/js-lib';
 import { AjvSchema, ObjectSchemaTyped, ReadableTyped } from '@naturalcycles/nodejs-lib';
 import { DBModelType, RunQueryResult } from '../db.model';
 import { DBQuery, RunnableDBQuery } from '../query/dbQuery';
@@ -35,6 +35,7 @@ export declare class CommonDao<BM extends Partial<ObjectWithId<ID>>, DBM extends
      * Throws if readOnly is true
      */
     private requireObjectMutability;
+    private ensureUniqueId;
     getBy(by: keyof DBM, value: any, limit?: number, opt?: CommonDaoOptions): Promise<Saved<BM>[]>;
     getOneBy(by: keyof DBM, value: any, opt?: CommonDaoOptions): Promise<Saved<BM> | null>;
     getAll(opt?: CommonDaoOptions): Promise<Saved<BM>[]>;
@@ -81,13 +82,11 @@ export declare class CommonDao<BM extends Partial<ObjectWithId<ID>>, DBM extends
      */
     assignIdCreatedUpdated(obj: DBM, opt?: CommonDaoOptions): DBM;
     assignIdCreatedUpdated(obj: BM, opt?: CommonDaoOptions): Saved<BM>;
+    assignIdCreatedUpdated(obj: Unsaved<BM>, opt?: CommonDaoOptions): Saved<BM>;
     /**
      * Mutates with id, created, updated
      */
-    save(bm: BM, opt?: CommonDaoSaveOptions<DBM>): Promise<Saved<BM>>;
-    private ensureImmutableDontExist;
-    private ensureUniqueId;
-    private throwIfObjectExists;
+    save(bm: Unsaved<BM>, opt?: CommonDaoSaveOptions<DBM>): Promise<Saved<BM>>;
     /**
      * Loads the row by id.
      * Creates the row (via this.create()) if it doesn't exist
@@ -99,7 +98,7 @@ export declare class CommonDao<BM extends Partial<ObjectWithId<ID>>, DBM extends
     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: BM[], opt?: CommonDaoSaveOptions<DBM>): Promise<Saved<BM>[]>;
+    saveBatch(bms: Unsaved<BM>[], opt?: CommonDaoSaveOptions<DBM>): Promise<Saved<BM>[]>;
     saveBatchAsDBM(dbms: DBM[], opt?: CommonDaoSaveOptions<DBM>): Promise<DBM[]>;
     /**
      * @returns number of deleted items

package/dist/commondao/common.dao.js

@@ -175,14 +175,25 @@ class CommonDao {
     /**
      * Throws if readOnly is true
      */
-    requireObjectMutability() {
-        if (this.cfg.immutable) {
+    requireObjectMutability(opt) {
+        if (this.cfg.immutable && !opt.allowMutability) {
             throw new js_lib_1.AppError(cnst_1.DBLibError.OBJECT_IS_IMMUTABLE, {
                 code: cnst_1.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 js_lib_1.AppError(cnst_1.DBLibError.NON_UNIQUE_ID, {
+                table,
+                code: cnst_1.DBLibError.NON_UNIQUE_ID,
+                ids: existing.map(i => i.id),
+            });
+        }
+    }
     async getBy(by, value, limit = 0, opt) {
         return await this.query().filterEq(by, value).limit(limit).runQuery(opt);
     }
@@ -445,8 +456,9 @@ class CommonDao {
         const table = opt.table || this.cfg.table;
         if (opt.ensureUniqueId && idWasGenerated)
             await this.ensureUniqueId(table, dbm);
-        if (this.cfg.immutable)
-            await this.ensureImmutableDontExist(table, [dbm.id]);
+        if (this.cfg.immutable && !opt.allowMutability) {
+            opt.saveMethod || (opt.saveMethod = 'insert');
+        }
         const op = `save(${dbm.id})`;
         const started = this.logSaveStarted(op, bm, table);
         await this.cfg.db.saveBatch(table, [dbm], {
@@ -456,30 +468,6 @@ class CommonDao {
         this.logSaveResult(started, op, table);
         return bm;
     }
-    async ensureImmutableDontExist(table, ids) {
-        await this.throwIfObjectExists(table, ids, [
-            cnst_1.DBLibError.OBJECT_IS_IMMUTABLE,
-            {
-                code: cnst_1.DBLibError.OBJECT_IS_IMMUTABLE,
-                table,
-            },
-        ]);
-    }
-    async ensureUniqueId(table, dbm) {
-        // todo: retry N times
-        await this.throwIfObjectExists(table, [dbm.id], [
-            cnst_1.DBLibError.OBJECT_IS_IMMUTABLE,
-            {
-                code: cnst_1.DBLibError.OBJECT_IS_IMMUTABLE,
-                table,
-            },
-        ]);
-    }
-    async throwIfObjectExists(table, ids, errorMeta) {
-        const existing = await this.cfg.db.getByIds(table, ids);
-        if (existing.length > 0)
-            throw new js_lib_1.AppError(errorMeta[0], { ...errorMeta[1], ids: existing.map(i => i.id) });
-    }
     /**
      * Loads the row by id.
      * Creates the row (via this.create()) if it doesn't exist
@@ -513,8 +501,9 @@ class CommonDao {
             dbm = this.anyToDBM(dbm, opt);
             if (opt.ensureUniqueId && idWasGenerated)
                 await this.ensureUniqueId(table, dbm);
-            if (this.cfg.immutable)
-                await this.ensureImmutableDontExist(table, [dbm.id]);
+        }
+        if (this.cfg.immutable && !opt.allowMutability) {
+            opt.saveMethod || (opt.saveMethod = 'insert');
         }
         const op = `saveAsDBM(${dbm.id})`;
         const started = this.logSaveStarted(op, dbm, table);
@@ -532,8 +521,9 @@ class CommonDao {
         const dbms = await this.bmsToDBM(bms, opt);
         if (opt.ensureUniqueId)
             throw new js_lib_1.AppError('ensureUniqueId is not supported in saveBatch');
-        if (this.cfg.immutable)
-            await this.ensureImmutableDontExist(table, dbms.map(dbm => dbm.id));
+        if (this.cfg.immutable && !opt.allowMutability) {
+            opt.saveMethod || (opt.saveMethod = 'insert');
+        }
         const op = `saveBatch ${dbms.length} row(s) (${(0, js_lib_1._truncate)(dbms
             .slice(0, 10)
             .map(bm => bm.id)
@@ -554,8 +544,9 @@ class CommonDao {
             dbms = this.anyToDBMs(dbms, opt);
             if (opt.ensureUniqueId)
                 throw new js_lib_1.AppError('ensureUniqueId is not supported in saveBatch');
-            if (this.cfg.immutable)
-                await this.ensureImmutableDontExist(table, dbms.map(dbm => dbm.id));
+        }
+        if (this.cfg.immutable && !opt.allowMutability) {
+            opt.saveMethod || (opt.saveMethod = 'insert');
         }
         const op = `saveBatchAsDBM ${dbms.length} row(s) (${(0, js_lib_1._truncate)(dbms
             .slice(0, 10)
@@ -573,8 +564,7 @@ class CommonDao {
         if (!id)
             return 0;
         this.requireWriteAccess();
-        if (!opt.allowMutability)
-            this.requireObjectMutability();
+        this.requireObjectMutability(opt);
         const op = `deleteById(${id})`;
         const table = opt.table || this.cfg.table;
         const started = this.logStarted(op, table);
@@ -584,8 +574,7 @@ class CommonDao {
     }
     async deleteByIds(ids, opt = {}) {
         this.requireWriteAccess();
-        if (!opt.allowMutability)
-            this.requireObjectMutability();
+        this.requireObjectMutability(opt);
         const op = `deleteByIds(${ids.join(', ')})`;
         const table = opt.table || this.cfg.table;
         const started = this.logStarted(op, table);
@@ -600,8 +589,7 @@ class CommonDao {
      */
     async deleteByQuery(q, opt = {}) {
         this.requireWriteAccess();
-        if (!opt.allowMutability)
-            this.requireObjectMutability();
+        this.requireObjectMutability(opt);
         q.table = opt.table || q.table;
         const op = `deleteByQuery(${q.pretty()})`;
         const started = this.logStarted(op, q.table);

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

@@ -49,17 +49,18 @@ export interface CommonDaoCfg<BM extends Partial<ObjectWithId<ID>>, DBM extends
     tmSchema?: ObjectSchemaTyped<TM> | AjvSchema<TM>;
     excludeFromIndexes?: (keyof DBM)[];
     /**
-     * @default to false
-     * Set to true to limit DB writing:
-     * * Will throw an error if an object with matching ID already exists during save().
-     * * saveBatch, delete*() and patch() will throw.
+     * Defaults to false.
+     * Setting it to true will set saveMethod to `insert` for save/saveBatch, which will
+     * fail for rows that already exist in the DB (if CommonDB implementation supports it).
      *
-     * Although deletion is possible by passing (opt.overrideImmutability === true)
+     * `delete*` and `patch` will throw.
+     *
+     * You can still override saveMethod, or set opt.allowMutability to allow deletion.
      */
     immutable?: boolean;
     /**
-     * @default to false
-     * Set to true to limit DB writing (will throw an error is such case).
+     * Defaults to false.
+     * Set to true to limit DB writing (will throw an error in such case).
      */
     readOnly?: boolean;
     /**
@@ -165,7 +166,7 @@ export interface CommonDaoOptions extends CommonDBOptions {
 /**
  * All properties default to undefined.
  */
-export interface CommonDaoSaveOptions<DBM extends ObjectWithId> extends CommonDaoOptions, CommonDBSaveOptions<DBM> {
+export interface CommonDaoSaveOptions<DBM extends Partial<ObjectWithId>> extends CommonDaoOptions, CommonDBSaveOptions<DBM> {
     /**
      * @default false
      *

package/dist/db.model.d.ts

@@ -1,11 +1,24 @@
 import { AnyObjectWithId, ObjectWithId } from '@naturalcycles/js-lib';
+/**
+ * Similar to SQL INSERT, UPDATE.
+ * Insert will fail if row already exists.
+ * Update will fail if row is missing.
+ * Upsert will auto-detect and use Insert or Update to not fail.
+ *
+ * Default is Upsert.
+ */
+export declare type CommonDBSaveMethod = 'upsert' | 'insert' | 'update';
 export interface CommonDBOptions {
 }
 /**
  * All properties default to undefined.
  */
-export interface CommonDBSaveOptions<ROW extends ObjectWithId = AnyObjectWithId> extends CommonDBOptions {
+export interface CommonDBSaveOptions<ROW extends Partial<ObjectWithId> = AnyObjectWithId> extends CommonDBOptions {
     excludeFromIndexes?: (keyof ROW)[];
+    /**
+     * Default is `upsert`
+     */
+    saveMethod?: CommonDBSaveMethod;
 }
 export declare type CommonDBStreamOptions = CommonDBOptions;
 export interface CommonDBCreateOptions extends CommonDBOptions {

package/dist/index.d.ts

@@ -6,7 +6,7 @@ import { DBLibError } from './cnst';
 import { CommonDB } from './common.db';
 import { CommonDao } from './commondao/common.dao';
 import { CommonDaoCfg, CommonDaoCreateOptions, CommonDaoLogLevel, CommonDaoOptions, CommonDaoSaveOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions, CommonDaoHooks } from './commondao/common.dao.model';
-import { CommonDBCreateOptions, CommonDBOptions, CommonDBSaveOptions, CommonDBStreamOptions, DBDeleteByIdsOperation, DBModelType, DBOperation, DBRelation, DBSaveBatchOperation, RunQueryResult } from './db.model';
+import { CommonDBCreateOptions, CommonDBOptions, CommonDBSaveMethod, CommonDBSaveOptions, CommonDBStreamOptions, DBDeleteByIdsOperation, DBModelType, DBOperation, DBRelation, DBSaveBatchOperation, RunQueryResult } from './db.model';
 import { CommonKeyValueDao, CommonKeyValueDaoCfg } from './kv/commonKeyValueDao';
 import { CommonKeyValueDB, KeyValueDBTuple } from './kv/commonKeyValueDB';
 import { createdUpdatedFields, createdUpdatedIdFields, deserializeJsonField, serializeJsonField } from './model.util';
@@ -17,5 +17,5 @@ import { DBQuery, DBQueryFilter, DBQueryFilterOperator, dbQueryFilterOperatorVal
 import { DBTransaction, RunnableDBTransaction } from './transaction/dbTransaction';
 import { commitDBTransactionSimple, mergeDBOperations } from './transaction/dbTransaction.util';
 export * from './kv/commonKeyValueDaoMemoCache';
-export type { DBQueryFilterOperator, DBQueryFilter, DBQueryOrder, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoSaveOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions, CommonDaoHooks, CommonDBOptions, CommonDBSaveOptions, CommonDBStreamOptions, CommonDBCreateOptions, CommonDB, RunQueryResult, CommonDaoCfg, InMemoryDBCfg, InMemoryKeyValueDBCfg, DBPipelineBackupOptions, DBPipelineRestoreOptions, DBPipelineCopyOptions, DBOperation, DBSaveBatchOperation, DBDeleteByIdsOperation, CommonKeyValueDB, CommonKeyValueDaoCfg, KeyValueDBTuple, };
+export type { DBQueryFilterOperator, DBQueryFilter, DBQueryOrder, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoSaveOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions, CommonDaoHooks, CommonDBOptions, CommonDBSaveOptions, CommonDBSaveMethod, CommonDBStreamOptions, CommonDBCreateOptions, CommonDB, RunQueryResult, CommonDaoCfg, InMemoryDBCfg, InMemoryKeyValueDBCfg, DBPipelineBackupOptions, DBPipelineRestoreOptions, DBPipelineCopyOptions, DBOperation, DBSaveBatchOperation, DBDeleteByIdsOperation, CommonKeyValueDB, CommonKeyValueDaoCfg, KeyValueDBTuple, };
 export { DBQuery, dbQueryFilterOperatorValues, RunnableDBQuery, CommonDaoLogLevel, DBRelation, DBModelType, CommonDao, createdUpdatedFields, createdUpdatedIdFields, InMemoryDB, InMemoryKeyValueDB, queryInMemory, serializeJsonField, deserializeJsonField, dbPipelineBackup, dbPipelineRestore, dbPipelineCopy, DBLibError, BaseCommonDB, DBTransaction, RunnableDBTransaction, mergeDBOperations, commitDBTransactionSimple, CommonKeyValueDao, };

package/dist/testing/daoTest.js

@@ -7,7 +7,6 @@ const __1 = require("..");
 const common_dao_1 = require("../commondao/common.dao");
 const dbTest_1 = require("./dbTest");
 const test_model_1 = require("./test.model");
-const _1 = require(".");
 function runCommonDaoTest(db, features = {}, quirks = {}) {
     const dao = new common_dao_1.CommonDao({
         table: test_model_1.TEST_TABLE,
@@ -42,7 +41,7 @@ function runCommonDaoTest(db, features = {}, quirks = {}) {
     // CREATE TABLE, DROP
     if (createTable) {
         test('createTable, dropIfExists=true', async () => {
-            await dao.createTable((0, _1.getTestItemSchema)(), { dropIfExists: true });
+            await dao.createTable(test_model_1.testItemDBMJsonSchema.build(), { dropIfExists: true });
         });
     }
     if (querying) {

package/dist/testing/dbTest.d.ts

@@ -8,6 +8,8 @@ export interface CommonDBImplementationFeatures {
     dbQueryFilterIn?: boolean;
     dbQueryOrder?: boolean;
     dbQuerySelectFields?: boolean;
+    insert?: boolean;
+    update?: boolean;
     createTable?: boolean;
     tableSchemas?: boolean;
     /**

package/dist/testing/dbTest.js

@@ -12,7 +12,7 @@ const test_util_1 = require("./test.util");
 function runCommonDBTest(db, features = {}, quirks = {}) {
     const { querying = true, tableSchemas = true, createTable = true, dbQueryFilter = true, 
     // dbQueryFilterIn = true,
-    dbQueryOrder = true, dbQuerySelectFields = true, streaming = true, strongConsistency = true, bufferSupport = true, nullValues = true, documentDB = true, } = features;
+    dbQueryOrder = true, dbQuerySelectFields = true, insert = true, update = true, streaming = true, strongConsistency = true, bufferSupport = true, nullValues = true, documentDB = true, } = features;
     // const {
     // allowExtraPropertiesInResponse,
     // allowBooleansAsUndefined,
@@ -28,7 +28,7 @@ function runCommonDBTest(db, features = {}, quirks = {}) {
     // CREATE TABLE, DROP
     if (createTable) {
         test('createTable, dropIfExists=true', async () => {
-            await db.createTable(test_model_1.TEST_TABLE, (0, test_model_1.getTestItemSchema)(), { dropIfExists: true });
+            await db.createTable(test_model_1.TEST_TABLE, test_model_1.testItemDBMJsonSchema.build(), { dropIfExists: true });
         });
     }
     if (querying) {
@@ -87,9 +87,24 @@ function runCommonDBTest(db, features = {}, quirks = {}) {
             expect(Object.keys(item3Loaded)).not.toContain('k2');
         });
     }
+    if (update) {
+        test('saveBatch UPDATE method should throw', async () => {
+            await expect(db.saveBatch(test_model_1.TEST_TABLE, items, { saveMethod: 'update' })).rejects.toThrow();
+        });
+    }
     test('saveBatch test items', async () => {
         await db.saveBatch(test_model_1.TEST_TABLE, items);
     });
+    if (insert) {
+        test('saveBatch INSERT method should throw', async () => {
+            await expect(db.saveBatch(test_model_1.TEST_TABLE, items, { saveMethod: 'insert' })).rejects.toThrow();
+        });
+    }
+    if (update) {
+        test('saveBatch UPDATE method should pass', async () => {
+            await db.saveBatch(test_model_1.TEST_TABLE, items, { saveMethod: 'update' });
+        });
+    }
     // GET not empty
     test('getByIds all items', async () => {
         const rows = await db.getByIds(test_model_1.TEST_TABLE, items.map(i => i.id).concat('abcd'));

package/dist/testing/index.d.ts

@@ -1,6 +1,6 @@
 import { runCommonDaoTest } from './daoTest';
 import { CommonDBImplementationFeatures, CommonDBImplementationQuirks, runCommonDBTest } from './dbTest';
 import { runCommonKeyValueDBTest } from './keyValueDBTest';
-import { createTestItemBM, createTestItemDBM, createTestItemsBM, createTestItemsDBM, getTestItemSchema, TestItemBM, testItemBMSchema, TestItemDBM, testItemDBMSchema, TestItemTM, testItemTMSchema, TEST_TABLE } from './test.model';
+import { createTestItemBM, createTestItemDBM, createTestItemsBM, createTestItemsDBM, TestItemBM, testItemBMJsonSchema, testItemBMSchema, TestItemDBM, testItemDBMJsonSchema, testItemDBMSchema, TestItemTM, testItemTMSchema, TEST_TABLE } from './test.model';
 export type { TestItemDBM, TestItemBM, TestItemTM, CommonDBImplementationFeatures, CommonDBImplementationQuirks, };
-export { TEST_TABLE, createTestItemDBM, createTestItemBM, createTestItemsDBM, createTestItemsBM, testItemDBMSchema, testItemBMSchema, testItemTMSchema, getTestItemSchema, runCommonDBTest, runCommonDaoTest, runCommonKeyValueDBTest, };
+export { TEST_TABLE, createTestItemDBM, createTestItemBM, createTestItemsDBM, createTestItemsBM, testItemDBMSchema, testItemBMSchema, testItemTMSchema, testItemBMJsonSchema, testItemDBMJsonSchema, runCommonDBTest, runCommonDaoTest, runCommonKeyValueDBTest, };

package/dist/testing/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runCommonKeyValueDBTest = exports.runCommonDaoTest = exports.runCommonDBTest = exports.getTestItemSchema = exports.testItemTMSchema = exports.testItemBMSchema = exports.testItemDBMSchema = exports.createTestItemsBM = exports.createTestItemsDBM = exports.createTestItemBM = exports.createTestItemDBM = exports.TEST_TABLE = void 0;
+exports.runCommonKeyValueDBTest = exports.runCommonDaoTest = exports.runCommonDBTest = exports.testItemDBMJsonSchema = exports.testItemBMJsonSchema = exports.testItemTMSchema = exports.testItemBMSchema = exports.testItemDBMSchema = exports.createTestItemsBM = exports.createTestItemsDBM = exports.createTestItemBM = exports.createTestItemDBM = exports.TEST_TABLE = void 0;
 const daoTest_1 = require("./daoTest");
 Object.defineProperty(exports, "runCommonDaoTest", { enumerable: true, get: function () { return daoTest_1.runCommonDaoTest; } });
 const dbTest_1 = require("./dbTest");
@@ -12,8 +12,9 @@ Object.defineProperty(exports, "createTestItemBM", { enumerable: true, get: func
 Object.defineProperty(exports, "createTestItemDBM", { enumerable: true, get: function () { return test_model_1.createTestItemDBM; } });
 Object.defineProperty(exports, "createTestItemsBM", { enumerable: true, get: function () { return test_model_1.createTestItemsBM; } });
 Object.defineProperty(exports, "createTestItemsDBM", { enumerable: true, get: function () { return test_model_1.createTestItemsDBM; } });
-Object.defineProperty(exports, "getTestItemSchema", { enumerable: true, get: function () { return test_model_1.getTestItemSchema; } });
+Object.defineProperty(exports, "testItemBMJsonSchema", { enumerable: true, get: function () { return test_model_1.testItemBMJsonSchema; } });
 Object.defineProperty(exports, "testItemBMSchema", { enumerable: true, get: function () { return test_model_1.testItemBMSchema; } });
+Object.defineProperty(exports, "testItemDBMJsonSchema", { enumerable: true, get: function () { return test_model_1.testItemDBMJsonSchema; } });
 Object.defineProperty(exports, "testItemDBMSchema", { enumerable: true, get: function () { return test_model_1.testItemDBMSchema; } });
 Object.defineProperty(exports, "testItemTMSchema", { enumerable: true, get: function () { return test_model_1.testItemTMSchema; } });
 Object.defineProperty(exports, "TEST_TABLE", { enumerable: true, get: function () { return test_model_1.TEST_TABLE; } });

package/dist/testing/test.model.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="node" />
-import { JsonSchemaObject, BaseDBEntity, Saved } from '@naturalcycles/js-lib';
+import { BaseDBEntity, Saved } from '@naturalcycles/js-lib';
 export declare const TEST_TABLE = "TEST_TABLE";
 export interface TestItemBM extends BaseDBEntity {
     k1: string;
@@ -23,4 +23,3 @@ export declare function createTestItemDBM(num?: number): TestItemDBM;
 export declare function createTestItemBM(num?: number): Saved<TestItemBM>;
 export declare function createTestItemsDBM(count?: number): TestItemDBM[];
 export declare function createTestItemsBM(count?: number): Saved<TestItemBM>[];
-export declare function getTestItemSchema(): JsonSchemaObject<TestItemDBM>;

package/dist/testing/test.model.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTestItemSchema = exports.createTestItemsBM = exports.createTestItemsDBM = exports.createTestItemBM = exports.createTestItemDBM = exports.testItemDBMJsonSchema = exports.testItemBMJsonSchema = exports.testItemTMSchema = exports.testItemDBMSchema = exports.testItemBMSchema = exports.TEST_TABLE = void 0;
+exports.createTestItemsBM = exports.createTestItemsDBM = exports.createTestItemBM = exports.createTestItemDBM = exports.testItemDBMJsonSchema = exports.testItemBMJsonSchema = exports.testItemTMSchema = exports.testItemDBMSchema = exports.testItemBMSchema = exports.TEST_TABLE = void 0;
 const js_lib_1 = require("@naturalcycles/js-lib");
 const nodejs_lib_1 = require("@naturalcycles/nodejs-lib");
 const MOCK_TS_2018_06_21 = 1529539200;
@@ -67,19 +67,3 @@ function createTestItemsBM(count = 1) {
     return (0, js_lib_1._range)(1, count + 1).map(num => createTestItemBM(num));
 }
 exports.createTestItemsBM = createTestItemsBM;
-const testItemJsonSchema = js_lib_1.jsonSchema
-    .object({
-    id: js_lib_1.jsonSchema.string(),
-    k1: js_lib_1.jsonSchema.string(),
-    k2: js_lib_1.jsonSchema.string(),
-    k3: js_lib_1.jsonSchema.number(),
-    even: js_lib_1.jsonSchema.boolean(),
-    created: js_lib_1.jsonSchema.unixTimestamp(),
-    updated: js_lib_1.jsonSchema.unixTimestamp(),
-})
-    .build();
-function getTestItemSchema() {
-    // return CommonSchemaGenerator.generateFromRows({ table: TEST_TABLE }, createTestItemsDBM())
-    return testItemJsonSchema;
-}
-exports.getTestItemSchema = getTestItemSchema;

package/package.json

@@ -42,7 +42,7 @@
   "engines": {
     "node": ">=14.15"
   },
-  "version": "8.36.1",
+  "version": "8.38.0",
   "description": "Lowest Common Denominator API to supported Databases",
   "keywords": [
     "db",

package/src/adapter/cachedb/cache.db.model.ts

@@ -57,7 +57,7 @@ export interface CacheDBOptions {
   onlyCache?: boolean
 }
 
-export interface CacheDBSaveOptions<ROW extends ObjectWithId>
+export interface CacheDBSaveOptions<ROW extends Partial<ObjectWithId>>
   extends CacheDBOptions,
     CommonDBSaveOptions<ROW> {}
 

package/src/adapter/cachedb/cache.db.ts

@@ -146,7 +146,7 @@ export class CacheDB extends BaseCommonDB implements CommonDB {
     return deletedIds
   }
 
-  override async saveBatch<ROW extends ObjectWithId>(
+  override async saveBatch<ROW extends Partial<ObjectWithId>>(
     table: string,
     rows: ROW[],
     opt: CacheDBSaveOptions<ROW> = {},

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

@@ -13,6 +13,7 @@ import {
   _filterUndefinedValues,
   ObjectWithId,
   AnyObjectWithId,
+  _assert,
 } from '@naturalcycles/js-lib'
 import { readableCreate, ReadableTyped } from '@naturalcycles/nodejs-lib'
 import { dimGrey } from '@naturalcycles/nodejs-lib/dist/colors'
@@ -71,7 +72,7 @@ export class FileDB extends BaseCommonDB implements CommonDB {
     return ids.map(id => byId[id]!).filter(Boolean)
   }
 
-  override async saveBatch<ROW extends ObjectWithId>(
+  override async saveBatch<ROW extends Partial<ObjectWithId>>(
     table: string,
     rows: ROW[],
     _opt?: CommonDBSaveOptions<ROW>,
@@ -79,13 +80,15 @@ export class FileDB extends BaseCommonDB implements CommonDB {
     if (!rows.length) return // save some api calls
 
     // 1. Load the whole file
-    const byId = _by(await this.loadFile<ROW>(table), r => r.id)
+    const byId = _by(await this.loadFile<ROW & ObjectWithId>(table), r => r.id)
 
     // 2. Merge with new data (using ids)
     let saved = 0
     rows.forEach(r => {
+      _assert(r.id, 'FileDB: row.id is required')
+
       if (!_deepEquals(byId[r.id], r)) {
-        byId[r.id] = r
+        byId[r.id] = r as any
         saved++
       }
     })

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

@@ -151,10 +151,10 @@ export class InMemoryDB implements CommonDB {
     return ids.map(id => this.data[table]![id]).filter(Boolean) as ROW[]
   }
 
-  async saveBatch<ROW extends ObjectWithId>(
+  async saveBatch<ROW extends Partial<ObjectWithId>>(
     _table: string,
     rows: ROW[],
-    _opt?: CommonDBSaveOptions<ROW>,
+    opt: CommonDBSaveOptions<ROW> = {},
   ): Promise<void> {
     const table = this.cfg.tablesPrefix + _table
     this.data[table] ||= {}
@@ -162,20 +162,23 @@ export class InMemoryDB implements CommonDB {
     rows.forEach(r => {
       if (!r.id) {
         this.cfg.logger?.warn({ rows })
-        throw new Error(`InMemoryDB: id doesn't exist for row`)
+        throw new Error(
+          `InMemoryDB doesn't support id auto-generation in saveBatch, row without id was given`,
+        )
+      }
+
+      if (opt.saveMethod === 'insert' && this.data[table]![r.id]) {
+        throw new Error(`InMemoryDB: INSERT failed, entity exists: ${table}.${r.id}`)
+      }
+
+      if (opt.saveMethod === 'update' && !this.data[table]![r.id]) {
+        throw new Error(`InMemoryDB: UPDATE failed, entity doesn't exist: ${table}.${r.id}`)
       }
 
       // JSON parse/stringify (deep clone) is to:
       // 1. Not store values "by reference" (avoid mutation bugs)
       // 2. Simulate real DB that would do something like that in a transport layer anyway
       this.data[table]![r.id] = JSON.parse(JSON.stringify(r), bufferReviver)
-
-      // special treatment for Buffers (assign them raw, without JSON parse/stringify)
-      // Object.entries(r).forEach(([k, v]) => {
-      //   if (Buffer.isBuffer(v)) {
-      //     this.data[table]![r.id]![k] = v
-      //   }
-      // })
     })
   }
 

package/src/base.common.db.ts

@@ -55,7 +55,7 @@ export class BaseCommonDB implements CommonDB {
     return 0
   }
 
-  async saveBatch<ROW extends ObjectWithId>(
+  async saveBatch<ROW extends Partial<ObjectWithId>>(
     _table: string,
     _rows: ROW[],
     _opt?: CommonDBSaveOptions<ROW>,

package/src/common.db.ts

@@ -70,7 +70,10 @@ export interface CommonDB {
   ): ReadableTyped<ROW>
 
   // SAVE
-  saveBatch<ROW extends ObjectWithId>(
+  /**
+   * rows can have missing ids only if DB supports auto-generating them (like mysql auto_increment).
+   */
+  saveBatch<ROW extends Partial<ObjectWithId>>(
     table: string,
     rows: ROW[],
     opt?: CommonDBSaveOptions<ROW>,

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

@@ -73,18 +73,19 @@ export interface CommonDaoCfg<
   excludeFromIndexes?: (keyof DBM)[]
 
   /**
-   * @default to false
-   * Set to true to limit DB writing:
-   * * Will throw an error if an object with matching ID already exists during save().
-   * * saveBatch, delete*() and patch() will throw.
+   * Defaults to false.
+   * Setting it to true will set saveMethod to `insert` for save/saveBatch, which will
+   * fail for rows that already exist in the DB (if CommonDB implementation supports it).
    *
-   * Although deletion is possible by passing (opt.overrideImmutability === true)
+   * `delete*` and `patch` will throw.
+   *
+   * You can still override saveMethod, or set opt.allowMutability to allow deletion.
    */
   immutable?: boolean
 
   /**
-   * @default to false
-   * Set to true to limit DB writing (will throw an error is such case).
+   * Defaults to false.
+   * Set to true to limit DB writing (will throw an error in such case).
    */
   readOnly?: boolean
 
@@ -209,7 +210,7 @@ export interface CommonDaoOptions extends CommonDBOptions {
 /**
  * All properties default to undefined.
  */
-export interface CommonDaoSaveOptions<DBM extends ObjectWithId>
+export interface CommonDaoSaveOptions<DBM extends Partial<ObjectWithId>>
   extends CommonDaoOptions,
     CommonDBSaveOptions<DBM> {
   /**

package/src/commondao/common.dao.ts

@@ -15,6 +15,7 @@ import {
   pMap,
   pTimeout,
   Saved,
+  Unsaved,
 } from '@naturalcycles/js-lib'
 import {
   _pipeline,
@@ -244,8 +245,8 @@ export class CommonDao<
   /**
    * Throws if readOnly is true
    */
-  private requireObjectMutability(): void {
-    if (this.cfg.immutable) {
+  private requireObjectMutability(opt: CommonDaoOptions): void {
+    if (this.cfg.immutable && !opt.allowMutability) {
       throw new AppError(DBLibError.OBJECT_IS_IMMUTABLE, {
         code: DBLibError.OBJECT_IS_IMMUTABLE,
         table: this.cfg.table,
@@ -253,6 +254,18 @@ export class CommonDao<
     }
   }
 
+  private async ensureUniqueId(table: string, dbm: DBM): Promise<void> {
+    // todo: retry N times
+    const existing = await this.cfg.db.getByIds<DBM>(table, [dbm.id])
+    if (existing.length) {
+      throw new AppError(DBLibError.NON_UNIQUE_ID, {
+        table,
+        code: DBLibError.NON_UNIQUE_ID,
+        ids: existing.map(i => i.id),
+      })
+    }
+  }
+
   async getBy(by: keyof DBM, value: any, limit = 0, opt?: CommonDaoOptions): Promise<Saved<BM>[]> {
     return await this.query().filterEq(by, value).limit(limit).runQuery(opt)
   }
@@ -573,10 +586,11 @@ export class CommonDao<
    */
   assignIdCreatedUpdated(obj: DBM, opt?: CommonDaoOptions): DBM
   assignIdCreatedUpdated(obj: BM, opt?: CommonDaoOptions): Saved<BM>
-  assignIdCreatedUpdated(obj: DBM | BM, opt: CommonDaoOptions = {}): DBM | Saved<BM> {
+  assignIdCreatedUpdated(obj: Unsaved<BM>, opt?: CommonDaoOptions): Saved<BM>
+  assignIdCreatedUpdated(obj: DBM | BM | Unsaved<BM>, opt: CommonDaoOptions = {}): DBM | Saved<BM> {
     const now = Math.floor(Date.now() / 1000)
 
-    obj.id ||= this.cfg.hooks!.createId?.(obj)
+    obj.id ||= this.cfg.hooks!.createId?.(obj as BM)
 
     if (this.cfg.created) {
       obj['created'] ||= obj['updated'] || now
@@ -593,14 +607,16 @@ export class CommonDao<
   /**
    * Mutates with id, created, updated
    */
-  async save(bm: BM, opt: CommonDaoSaveOptions<DBM> = {}): Promise<Saved<BM>> {
+  async save(bm: Unsaved<BM>, opt: CommonDaoSaveOptions<DBM> = {}): Promise<Saved<BM>> {
     this.requireWriteAccess()
     const idWasGenerated = !bm.id
     this.assignIdCreatedUpdated(bm, opt) // mutates
-    const dbm = await this.bmToDBM(bm, opt)
+    const dbm = await this.bmToDBM(bm as BM, opt)
     const table = opt.table || this.cfg.table
     if (opt.ensureUniqueId && idWasGenerated) await this.ensureUniqueId(table, dbm)
-    if (this.cfg.immutable) await this.ensureImmutableDontExist(table, [dbm.id])
+    if (this.cfg.immutable && !opt.allowMutability) {
+      opt.saveMethod ||= 'insert'
+    }
     const op = `save(${dbm.id})`
     const started = this.logSaveStarted(op, bm, table)
     await this.cfg.db.saveBatch(table, [dbm], {
@@ -612,41 +628,6 @@ export class CommonDao<
     return bm as any
   }
 
-  private async ensureImmutableDontExist(table: string, ids: ID[]): Promise<void> {
-    await this.throwIfObjectExists(table, ids, [
-      DBLibError.OBJECT_IS_IMMUTABLE,
-      {
-        code: DBLibError.OBJECT_IS_IMMUTABLE,
-        table,
-      },
-    ])
-  }
-
-  private async ensureUniqueId(table: string, dbm: DBM): Promise<void> {
-    // todo: retry N times
-    await this.throwIfObjectExists(
-      table,
-      [dbm.id],
-      [
-        DBLibError.OBJECT_IS_IMMUTABLE,
-        {
-          code: DBLibError.OBJECT_IS_IMMUTABLE,
-          table,
-        },
-      ],
-    )
-  }
-
-  private async throwIfObjectExists(
-    table: string,
-    ids: ID[],
-    errorMeta: [DBLibError, any],
-  ): Promise<void> {
-    const existing = await this.cfg.db.getByIds<DBM>(table, ids)
-    if (existing.length > 0)
-      throw new AppError(errorMeta[0], { ...errorMeta[1], ids: existing.map(i => i.id) })
-  }
-
   /**
    * Loads the row by id.
    * Creates the row (via this.create()) if it doesn't exist
@@ -690,7 +671,9 @@ export class CommonDao<
       this.assignIdCreatedUpdated(dbm, opt) // mutates
       dbm = this.anyToDBM(dbm, opt)
       if (opt.ensureUniqueId && idWasGenerated) await this.ensureUniqueId(table, dbm)
-      if (this.cfg.immutable) await this.ensureImmutableDontExist(table, [dbm.id])
+    }
+    if (this.cfg.immutable && !opt.allowMutability) {
+      opt.saveMethod ||= 'insert'
     }
     const op = `saveAsDBM(${dbm.id})`
     const started = this.logSaveStarted(op, dbm, table)
@@ -702,17 +685,15 @@ export class CommonDao<
     return dbm
   }
 
-  async saveBatch(bms: BM[], opt: CommonDaoSaveOptions<DBM> = {}): Promise<Saved<BM>[]> {
+  async saveBatch(bms: Unsaved<BM>[], opt: CommonDaoSaveOptions<DBM> = {}): Promise<Saved<BM>[]> {
     this.requireWriteAccess()
     const table = opt.table || this.cfg.table
     bms.forEach(bm => this.assignIdCreatedUpdated(bm, opt))
-    const dbms = await this.bmsToDBM(bms, opt)
+    const dbms = await this.bmsToDBM(bms as BM[], opt)
     if (opt.ensureUniqueId) throw new AppError('ensureUniqueId is not supported in saveBatch')
-    if (this.cfg.immutable)
-      await this.ensureImmutableDontExist(
-        table,
-        dbms.map(dbm => dbm.id),
-      )
+    if (this.cfg.immutable && !opt.allowMutability) {
+      opt.saveMethod ||= 'insert'
+    }
 
     const op = `saveBatch ${dbms.length} row(s) (${_truncate(
       dbms
@@ -740,11 +721,9 @@ export class CommonDao<
       dbms.forEach(dbm => this.assignIdCreatedUpdated(dbm, opt)) // mutates
       dbms = this.anyToDBMs(dbms, opt)
       if (opt.ensureUniqueId) throw new AppError('ensureUniqueId is not supported in saveBatch')
-      if (this.cfg.immutable)
-        await this.ensureImmutableDontExist(
-          table,
-          dbms.map(dbm => dbm.id),
-        )
+    }
+    if (this.cfg.immutable && !opt.allowMutability) {
+      opt.saveMethod ||= 'insert'
     }
     const op = `saveBatchAsDBM ${dbms.length} row(s) (${_truncate(
       dbms
@@ -773,7 +752,7 @@ export class CommonDao<
   async deleteById(id?: ID, opt: CommonDaoOptions = {}): Promise<number> {
     if (!id) return 0
     this.requireWriteAccess()
-    if (!opt.allowMutability) this.requireObjectMutability()
+    this.requireObjectMutability(opt)
     const op = `deleteById(${id})`
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
@@ -784,7 +763,7 @@ export class CommonDao<
 
   async deleteByIds(ids: ID[], opt: CommonDaoOptions = {}): Promise<number> {
     this.requireWriteAccess()
-    if (!opt.allowMutability) this.requireObjectMutability()
+    this.requireObjectMutability(opt)
     const op = `deleteByIds(${ids.join(', ')})`
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
@@ -803,7 +782,7 @@ export class CommonDao<
     opt: CommonDaoStreamForEachOptions<DBM> & { stream?: boolean } = {},
   ): Promise<number> {
     this.requireWriteAccess()
-    if (!opt.allowMutability) this.requireObjectMutability()
+    this.requireObjectMutability(opt)
     q.table = opt.table || q.table
     const op = `deleteByQuery(${q.pretty()})`
     const started = this.logStarted(op, q.table)

package/src/db.model.ts

@@ -1,14 +1,29 @@
 import { AnyObjectWithId, ObjectWithId } from '@naturalcycles/js-lib'
 
+/**
+ * Similar to SQL INSERT, UPDATE.
+ * Insert will fail if row already exists.
+ * Update will fail if row is missing.
+ * Upsert will auto-detect and use Insert or Update to not fail.
+ *
+ * Default is Upsert.
+ */
+export type CommonDBSaveMethod = 'upsert' | 'insert' | 'update'
+
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface CommonDBOptions {}
 
 /**
  * All properties default to undefined.
  */
-export interface CommonDBSaveOptions<ROW extends ObjectWithId = AnyObjectWithId>
+export interface CommonDBSaveOptions<ROW extends Partial<ObjectWithId> = AnyObjectWithId>
   extends CommonDBOptions {
   excludeFromIndexes?: (keyof ROW)[]
+
+  /**
+   * Default is `upsert`
+   */
+  saveMethod?: CommonDBSaveMethod
 }
 
 export type CommonDBStreamOptions = CommonDBOptions

package/src/index.ts

@@ -18,6 +18,7 @@ import {
 import {
   CommonDBCreateOptions,
   CommonDBOptions,
+  CommonDBSaveMethod,
   CommonDBSaveOptions,
   CommonDBStreamOptions,
   DBDeleteByIdsOperation,
@@ -62,6 +63,7 @@ export type {
   CommonDaoHooks,
   CommonDBOptions,
   CommonDBSaveOptions,
+  CommonDBSaveMethod,
   CommonDBStreamOptions,
   CommonDBCreateOptions,
   CommonDB,

package/src/testing/daoTest.ts

@@ -11,8 +11,9 @@ import {
   testItemTMSchema,
   TEST_TABLE,
   createTestItemBM,
+  testItemDBMJsonSchema,
 } from './test.model'
-import { getTestItemSchema, TestItemBM } from '.'
+import { TestItemBM } from '.'
 
 export function runCommonDaoTest(
   db: CommonDB,
@@ -65,7 +66,7 @@ export function runCommonDaoTest(
   // CREATE TABLE, DROP
   if (createTable) {
     test('createTable, dropIfExists=true', async () => {
-      await dao.createTable(getTestItemSchema(), { dropIfExists: true })
+      await dao.createTable(testItemDBMJsonSchema.build(), { dropIfExists: true })
     })
   }
 

package/src/testing/dbTest.ts

@@ -5,9 +5,9 @@ import { DBQuery } from '../query/dbQuery'
 import {
   createTestItemDBM,
   createTestItemsDBM,
-  getTestItemSchema,
   TestItemDBM,
   TEST_TABLE,
+  testItemDBMJsonSchema,
 } from './test.model'
 import { deepFreeze } from './test.util'
 
@@ -21,6 +21,8 @@ export interface CommonDBImplementationFeatures {
   dbQueryFilterIn?: boolean
   dbQueryOrder?: boolean
   dbQuerySelectFields?: boolean
+  insert?: boolean
+  update?: boolean
 
   createTable?: boolean
   tableSchemas?: boolean
@@ -80,6 +82,8 @@ export function runCommonDBTest(
     // dbQueryFilterIn = true,
     dbQueryOrder = true,
     dbQuerySelectFields = true,
+    insert = true,
+    update = true,
     streaming = true,
     strongConsistency = true,
     bufferSupport = true,
@@ -106,7 +110,7 @@ export function runCommonDBTest(
   // CREATE TABLE, DROP
   if (createTable) {
     test('createTable, dropIfExists=true', async () => {
-      await db.createTable(TEST_TABLE, getTestItemSchema(), { dropIfExists: true })
+      await db.createTable(TEST_TABLE, testItemDBMJsonSchema.build(), { dropIfExists: true })
     })
   }
 
@@ -176,10 +180,28 @@ export function runCommonDBTest(
     })
   }
 
+  if (update) {
+    test('saveBatch UPDATE method should throw', async () => {
+      await expect(db.saveBatch(TEST_TABLE, items, { saveMethod: 'update' })).rejects.toThrow()
+    })
+  }
+
   test('saveBatch test items', async () => {
     await db.saveBatch(TEST_TABLE, items)
   })
 
+  if (insert) {
+    test('saveBatch INSERT method should throw', async () => {
+      await expect(db.saveBatch(TEST_TABLE, items, { saveMethod: 'insert' })).rejects.toThrow()
+    })
+  }
+
+  if (update) {
+    test('saveBatch UPDATE method should pass', async () => {
+      await db.saveBatch(TEST_TABLE, items, { saveMethod: 'update' })
+    })
+  }
+
   // GET not empty
   test('getByIds all items', async () => {
     const rows = await db.getByIds<TestItemDBM>(TEST_TABLE, items.map(i => i.id).concat('abcd'))

package/src/testing/index.ts

@@ -10,10 +10,11 @@ import {
   createTestItemDBM,
   createTestItemsBM,
   createTestItemsDBM,
-  getTestItemSchema,
   TestItemBM,
+  testItemBMJsonSchema,
   testItemBMSchema,
   TestItemDBM,
+  testItemDBMJsonSchema,
   testItemDBMSchema,
   TestItemTM,
   testItemTMSchema,
@@ -37,7 +38,8 @@ export {
   testItemDBMSchema,
   testItemBMSchema,
   testItemTMSchema,
-  getTestItemSchema,
+  testItemBMJsonSchema,
+  testItemDBMJsonSchema,
   runCommonDBTest,
   runCommonDaoTest,
   runCommonKeyValueDBTest,

package/src/testing/test.model.ts

@@ -1,4 +1,4 @@
-import { jsonSchema, JsonSchemaObject, _range, BaseDBEntity, Saved } from '@naturalcycles/js-lib'
+import { jsonSchema, _range, BaseDBEntity, Saved } from '@naturalcycles/js-lib'
 import {
   baseDBEntitySchema,
   binarySchema,
@@ -94,20 +94,3 @@ export function createTestItemsDBM(count = 1): TestItemDBM[] {
 export function createTestItemsBM(count = 1): Saved<TestItemBM>[] {
   return _range(1, count + 1).map(num => createTestItemBM(num))
 }
-
-const testItemJsonSchema = jsonSchema
-  .object<TestItemDBM>({
-    id: jsonSchema.string(),
-    k1: jsonSchema.string(),
-    k2: jsonSchema.string(),
-    k3: jsonSchema.number(),
-    even: jsonSchema.boolean(),
-    created: jsonSchema.unixTimestamp(),
-    updated: jsonSchema.unixTimestamp(),
-  })
-  .build()
-
-export function getTestItemSchema(): JsonSchemaObject<TestItemDBM> {
-  // return CommonSchemaGenerator.generateFromRows({ table: TEST_TABLE }, createTestItemsDBM())
-  return testItemJsonSchema
-}