@naturalcycles/db-lib 8.36.1 → 8.37.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';
@@ -81,10 +81,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>>;
+    save(bm: Unsaved<BM>, opt?: CommonDaoSaveOptions<DBM>): Promise<Saved<BM>>;
     private ensureImmutableDontExist;
     private ensureUniqueId;
     private throwIfObjectExists;
@@ -99,7 +100,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.model.d.ts

@@ -165,7 +165,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/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,
@@ -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/package.json

@@ -42,7 +42,7 @@
   "engines": {
     "node": ">=14.15"
   },
-  "version": "8.36.1",
+  "version": "8.37.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

@@ -209,7 +209,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,
@@ -573,10 +574,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,11 +595,11 @@ 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])
@@ -702,11 +704,11 @@ 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(

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/dbTest.ts

@@ -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,
@@ -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'))