@naturalcycles/db-lib 9.5.0 → 9.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/db-lib",
   "scripts": {
-    "prepare": "husky install"
+    "prepare": "husky"
   },
   "dependencies": {
     "@naturalcycles/js-lib": "^14.116.0",
@@ -40,7 +40,7 @@
   "engines": {
     "node": ">=18.12"
   },
-  "version": "9.5.0",
+  "version": "9.7.0",
   "description": "Lowest Common Denominator API to supported Databases",
   "keywords": [
     "db",

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

@@ -47,17 +47,6 @@ export interface CommonDaoHooks<BM extends BaseDBEntity, DBM extends BaseDBEntit
    */
   beforeCreate: (bm: Partial<BM>) => Partial<BM>
 
-  /**
-   * Called when loading things "as DBM" and validation is not skipped.
-   * When loading things as BM/TM - other hooks get involved instead:
-   * - beforeDBMToBM
-   * - beforeBMToTM
-   *
-   * TODO: maybe rename those to `validateAs(model)`
-   * as it only validates "final state", not intermediate
-   */
-  beforeDBMValidate: (dbm: Partial<DBM>) => Partial<DBM>
-
   beforeDBMToBM: (dbm: DBM) => Partial<BM> | Promise<Partial<BM>>
   beforeBMToDBM: (bm: BM) => Partial<DBM> | Promise<Partial<DBM>>
 
@@ -136,7 +125,6 @@ export interface CommonDaoCfg<BM extends BaseDBEntity, DBM extends BaseDBEntity
   /**
    * Joi, AjvSchema or ZodSchema is supported.
    */
-  dbmSchema?: ObjectSchema<DBM> | AjvSchema<DBM> | ZodSchema<DBM>
   bmSchema?: ObjectSchema<BM> | AjvSchema<BM> | ZodSchema<BM>
 
   excludeFromIndexes?: (keyof DBM)[]
@@ -201,17 +189,6 @@ export interface CommonDaoCfg<BM extends BaseDBEntity, DBM extends BaseDBEntity
    */
   useUpdatedProperty?: boolean
 
-  /**
-   * Default is false.
-   * If true - will run `_filterNullishValues` inside `validateAndConvert` function
-   * (instead of `_filterUndefinedValues`).
-   * This was the old db-lib behavior.
-   * This option allows to keep backwards-compatible behavior.
-   *
-   * @deprecated
-   */
-  filterNullishValues?: boolean
-
   /**
    * Defaults to false.
    * If true - run patch operations (patch, patchById) in a Transaction.
@@ -242,16 +219,6 @@ export interface CommonDaoOptions extends CommonDBOptions {
    */
   skipConversion?: boolean
 
-  /**
-   * If true - will SKIP ANY transformation/processing, will return DB objects as they are. Will also skip created/updated/id
-   * generation.
-   *
-   * Useful for performance/streaming/pipelines.
-   *
-   * @default false
-   */
-  raw?: boolean
-
   /**
    * @default false
    */

package/src/commondao/common.dao.ts

@@ -1,8 +1,8 @@
 import { Transform } from 'node:stream'
 import {
   _assert,
+  _deepCopy,
   _deepJsonEquals,
-  _filterNullishValues,
   _filterUndefinedValues,
   _isTruthy,
   _objectAssignExact,
@@ -43,13 +43,7 @@ import {
   writableVoid,
 } from '@naturalcycles/nodejs-lib'
 import { DBLibError } from '../cnst'
-import {
-  CommonDBTransactionOptions,
-  DBModelType,
-  DBPatch,
-  DBTransaction,
-  RunQueryResult,
-} from '../db.model'
+import { CommonDBTransactionOptions, DBPatch, DBTransaction, RunQueryResult } from '../db.model'
 import { DBQuery, RunnableDBQuery } from '../query/dbQuery'
 import {
   CommonDaoCfg,
@@ -91,9 +85,6 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
       hooks: {
         parseNaturalId: () => ({}),
         beforeCreate: bm => bm as BM,
-        beforeDBMValidate: dbm => dbm,
-        beforeDBMToBM: dbm => dbm as any,
-        beforeBMToDBM: bm => bm as any,
         anonymize: dbm => dbm,
         onValidationError: err => err,
         ...cfg.hooks,
@@ -112,7 +103,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
     const bm = this.cfg.hooks!.beforeCreate!(part)
     // First assignIdCreatedUpdated, then validate!
     this.assignIdCreatedUpdated(bm, opt)
-    return this.validateAndConvert(bm, this.cfg.bmSchema, DBModelType.BM, opt)
+    return this.validateAndConvert(bm, this.cfg.bmSchema, opt)
   }
 
   // GET
@@ -125,11 +116,11 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
     const started = this.logStarted(op, table)
 
     let dbm = (await (opt.tx || this.cfg.db).getByIds<DBM>(table, [id]))[0]
-    if (dbm && !opt.raw && this.cfg.hooks!.afterLoad) {
+    if (dbm && this.cfg.hooks!.afterLoad) {
       dbm = (await this.cfg.hooks!.afterLoad(dbm)) || undefined
     }
 
-    const bm = opt.raw ? (dbm as any) : await this.dbmToBM(dbm, opt)
+    const bm = await this.dbmToBM(dbm, opt)
     this.logResult(started, op, bm, table)
     return bm || null
   }
@@ -141,18 +132,6 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
     return this.create({ ...part, id }, opt)
   }
 
-  async getByIdAsDBMOrEmpty(
-    id: string,
-    part: Partial<BM> = {},
-    opt?: CommonDaoOptions,
-  ): Promise<DBM> {
-    const dbm = await this.getByIdAsDBM(id, opt)
-    if (dbm) return dbm
-
-    const bm = this.create({ ...part, id }, opt)
-    return await this.bmToDBM(bm, opt)
-  }
-
   async getByIdAsDBM(id: undefined | null, opt?: CommonDaoOptions): Promise<null>
   async getByIdAsDBM(id?: string | null, opt?: CommonDaoOptions): Promise<DBM | null>
   async getByIdAsDBM(id?: string | null, opt: CommonDaoOptions = {}): Promise<DBM | null> {
@@ -161,13 +140,11 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
     let [dbm] = await (opt.tx || this.cfg.db).getByIds<DBM>(table, [id])
-    if (dbm && !opt.raw && this.cfg.hooks!.afterLoad) {
+    if (dbm && this.cfg.hooks!.afterLoad) {
       dbm = (await this.cfg.hooks!.afterLoad(dbm)) || undefined
     }
 
-    if (!opt.raw) {
-      dbm = this.anyToDBM(dbm!, opt)
-    }
+    dbm = this.anyToDBM(dbm!, opt)
     this.logResult(started, op, dbm, table)
     return dbm || null
   }
@@ -178,13 +155,13 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
     let dbms = await (opt.tx || this.cfg.db).getByIds<DBM>(table, ids)
-    if (!opt.raw && this.cfg.hooks!.afterLoad && dbms.length) {
+    if (this.cfg.hooks!.afterLoad && dbms.length) {
       dbms = (await pMap(dbms, async dbm => await this.cfg.hooks!.afterLoad!(dbm))).filter(
         _isTruthy,
       )
     }
 
-    const bms = opt.raw ? (dbms as any) : await this.dbmsToBM(dbms, opt)
+    const bms = await this.dbmsToBM(dbms, opt)
     this.logResult(started, op, bms, table)
     return bms
   }
@@ -195,7 +172,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
     let dbms = await (opt.tx || this.cfg.db).getByIds<DBM>(table, ids)
-    if (!opt.raw && this.cfg.hooks!.afterLoad && dbms.length) {
+    if (this.cfg.hooks!.afterLoad && dbms.length) {
       dbms = (await pMap(dbms, async dbm => await this.cfg.hooks!.afterLoad!(dbm))).filter(
         _isTruthy,
       )
@@ -318,13 +295,13 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
     const started = this.logStarted(op, q.table)
     let { rows, ...queryResult } = await this.cfg.db.runQuery<DBM>(q, opt)
     const partialQuery = !!q._selectedFieldNames
-    if (!opt.raw && this.cfg.hooks!.afterLoad && rows.length) {
+    if (this.cfg.hooks!.afterLoad && rows.length) {
       rows = (await pMap(rows, async dbm => await this.cfg.hooks!.afterLoad!(dbm))).filter(
         _isTruthy,
       )
     }
 
-    const bms = partialQuery || opt.raw ? (rows as any[]) : await this.dbmsToBM(rows, opt)
+    const bms = partialQuery ? (rows as any[]) : await this.dbmsToBM(rows, opt)
     this.logResult(started, op, bms, q.table)
     return {
       rows: bms,
@@ -345,14 +322,14 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
     const op = `runQueryAsDBM(${q.pretty()})`
     const started = this.logStarted(op, q.table)
     let { rows, ...queryResult } = await this.cfg.db.runQuery<DBM>(q, opt)
-    if (!opt.raw && this.cfg.hooks!.afterLoad && rows.length) {
+    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 || opt.raw ? rows : this.anyToDBMs(rows, opt)
+    const dbms = partialQuery ? rows : this.anyToDBMs(rows, opt)
     this.logResult(started, op, dbms, q.table)
     return { rows: dbms, ...queryResult }
   }
@@ -388,7 +365,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
       transformMap<DBM, BM>(
         async dbm => {
           count++
-          if (partialQuery || opt.raw) return dbm as any
+          if (partialQuery) return dbm as any
 
           if (this.cfg.hooks!.afterLoad) {
             dbm = (await this.cfg.hooks!.afterLoad(dbm))!
@@ -438,7 +415,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
       transformMap<any, DBM>(
         async dbm => {
           count++
-          if (partialQuery || opt.raw) return dbm
+          if (partialQuery) return dbm
 
           if (this.cfg.hooks!.afterLoad) {
             dbm = (await this.cfg.hooks!.afterLoad(dbm))!
@@ -480,7 +457,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
     const partialQuery = !!q._selectedFieldNames
 
     const stream = this.cfg.db.streamQuery<DBM>(q, opt)
-    if (partialQuery || opt.raw) return stream
+    if (partialQuery) return stream
 
     return stream
       .on('error', err => stream.emit('error', err))
@@ -518,7 +495,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
 
     const stream = this.cfg.db.streamQuery<DBM>(q, opt)
     const partialQuery = !!q._selectedFieldNames
-    if (partialQuery || opt.raw) return stream
+    if (partialQuery) return stream
 
     return (
       stream
@@ -627,51 +604,6 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
   }
 
   // SAVE
-  /**
-   * Mutates with id, created, updated
-   */
-  async save(bm: Unsaved<BM>, opt: CommonDaoSaveOptions<BM, DBM> = {}): Promise<BM> {
-    this.requireWriteAccess()
-
-    if (opt.skipIfEquals && _deepJsonEquals(bm, opt.skipIfEquals)) {
-      // Skipping the save operation
-      return bm as BM
-    }
-
-    const idWasGenerated = !bm.id && this.cfg.generateId
-    this.assignIdCreatedUpdated(bm, opt) // mutates
-    _typeCast<BM>(bm)
-    let dbm = await this.bmToDBM(bm, opt)
-
-    if (this.cfg.hooks!.beforeSave) {
-      dbm = (await this.cfg.hooks!.beforeSave(dbm))!
-      if (dbm === null) 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) {
-      bm.id = dbm.id
-    }
-
-    this.logSaveResult(started, op, table)
-    return bm
-  }
-
   /**
    * 1. Applies the patch
    * 2. If object is the same after patching - skips saving it
@@ -794,19 +726,62 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
     })
   }
 
-  async saveAsDBM(dbm: Unsaved<DBM>, opt: CommonDaoSaveBatchOptions<DBM> = {}): Promise<DBM> {
+  /**
+   * Mutates with id, created, updated
+   */
+  async save(bm: Unsaved<BM>, opt: CommonDaoSaveOptions<BM, DBM> = {}): Promise<BM> {
+    this.requireWriteAccess()
+
+    if (opt.skipIfEquals && _deepJsonEquals(bm, opt.skipIfEquals)) {
+      // Skipping the save operation
+      return bm as BM
+    }
+
+    const idWasGenerated = !bm.id && this.cfg.generateId
+    this.assignIdCreatedUpdated(bm, opt) // mutates
+    _typeCast<BM>(bm)
+    let dbm = await this.bmToDBM(bm, opt) // validates BM
+
+    if (this.cfg.hooks!.beforeSave) {
+      dbm = (await this.cfg.hooks!.beforeSave(dbm))!
+      if (dbm === null) 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) {
+      bm.id = dbm.id
+    }
+
+    this.logSaveResult(started, op, table)
+    return bm
+  }
+
+  async saveAsDBM(dbm: Unsaved<DBM>, opt: CommonDaoSaveOptions<BM, DBM> = {}): Promise<DBM> {
     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
-    let row = dbm as DBM
-    if (!opt.raw) {
-      const idWasGenerated = !dbm.id && this.cfg.generateId
-      this.assignIdCreatedUpdated(dbm, opt) // mutates
-      row = this.anyToDBM(dbm, opt)
-      if (opt.ensureUniqueId && idWasGenerated) await this.ensureUniqueId(table, row)
-    }
+    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' }
     }
@@ -885,12 +860,10 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
     if (!dbms.length) return []
     this.requireWriteAccess()
     const table = opt.table || this.cfg.table
-    let rows = dbms as DBM[]
-    if (!opt.raw) {
-      dbms.forEach(dbm => this.assignIdCreatedUpdated(dbm, opt)) // mutates
-      rows = this.anyToDBMs(dbms as DBM[], opt)
-      if (opt.ensureUniqueId) throw new AppError('ensureUniqueId is not supported in saveBatch')
-    }
+    dbms.forEach(dbm => this.assignIdCreatedUpdated(dbm, opt)) // mutates
+    let rows = this.anyToDBMs(dbms as DBM[], 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' }
     }
@@ -995,18 +968,9 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
   /**
    * @returns number of deleted items
    */
-  async deleteById(id: undefined | null, opt?: CommonDaoOptions): Promise<0>
-  async deleteById(id?: string | null, opt?: CommonDaoOptions): Promise<number>
   async deleteById(id?: string | null, opt: CommonDaoOptions = {}): Promise<number> {
     if (!id) return 0
-    this.requireWriteAccess()
-    this.requireObjectMutability(opt)
-    const op = `deleteById(${id})`
-    const table = opt.table || this.cfg.table
-    const started = this.logStarted(op, table)
-    const count = await this.cfg.db.deleteByIds(table, [id], opt)
-    this.logSaveResult(started, op, table)
-    return count
+    return await this.deleteByIds([id], opt)
   }
 
   async deleteByIds(ids: string[], opt: CommonDaoOptions = {}): Promise<number> {
@@ -1119,11 +1083,16 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
     }
 
     // DBM > BM
-    const bm = await this.cfg.hooks!.beforeDBMToBM!(dbm)
+    let bm: Partial<BM>
+    if (this.cfg.hooks!.beforeDBMToBM) {
+      bm = await this.cfg.hooks!.beforeDBMToBM(dbm)
+    } else {
+      bm = dbm as any
+    }
 
     // Validate/convert BM
 
-    return this.validateAndConvert(bm, this.cfg.bmSchema, DBModelType.BM, opt)
+    return this.validateAndConvert(bm, this.cfg.bmSchema, opt)
   }
 
   async dbmsToBM(dbms: DBM[], opt: CommonDaoOptions = {}): Promise<BM[]> {
@@ -1139,20 +1108,23 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
   async bmToDBM(bm?: BM, opt?: CommonDaoOptions): Promise<DBM | undefined> {
     if (bm === undefined) return
 
-    // optimization: no need to run the BM validation, since DBM will be validated anyway
-    // Validate/convert BM
-    // bm gets assigned to the new reference
-    // bm = this.validateAndConvert(bm, this.cfg.bmSchema, DBModelType.BM, opt)
-
     // should not do it on load, but only on save!
     // this.assignIdCreatedUpdated(bm, opt)
 
+    // bm gets assigned to the new reference
+    bm = this.validateAndConvert(bm, this.cfg.bmSchema, opt)
+
     // BM > DBM
-    const dbm = { ...(await this.cfg.hooks!.beforeBMToDBM!(bm)) }
+    let dbm: DBM
+    if (this.cfg.hooks!.beforeBMToDBM) {
+      dbm = { ...((await this.cfg.hooks!.beforeBMToDBM(bm!)) as DBM) }
+    } else {
+      dbm = bm as any
+    }
 
     // Validate/convert DBM
-
-    return this.validateAndConvert(dbm, this.cfg.dbmSchema, DBModelType.DBM, opt)
+    // return this.validateAndConvert(dbm, this.cfg.dbmSchema, DBModelType.DBM, opt)
+    return dbm
   }
 
   async bmsToDBM(bms: BM[], opt: CommonDaoOptions = {}): Promise<DBM[]> {
@@ -1170,12 +1142,15 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
 
     dbm = { ...dbm, ...this.cfg.hooks!.parseNaturalId!(dbm.id) }
 
+    // todo: is this the right place?
+    // todo: is anyToDBM even needed?
     if (opt.anonymize) {
       dbm = this.cfg.hooks!.anonymize!(dbm)
     }
 
     // Validate/convert DBM
-    return this.validateAndConvert(dbm, this.cfg.dbmSchema, DBModelType.DBM, opt)
+    // return this.validateAndConvert(dbm, this.cfg.dbmSchema, DBModelType.DBM, opt)
+    return dbm
   }
 
   anyToDBMs(entities: DBM[], opt: CommonDaoOptions = {}): DBM[] {
@@ -1191,12 +1166,8 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
   validateAndConvert<T>(
     obj: Partial<T>,
     schema: ObjectSchema<T> | AjvSchema<T> | ZodSchema<T> | undefined,
-    modelType?: DBModelType,
     opt: CommonDaoOptions = {},
   ): any {
-    // `raw` option completely bypasses any processing
-    if (opt.raw) return obj as any
-
     // Kirill 2021-10-18: I realized that there's little reason to keep removing null values
     // So, from now on we'll preserve them
     // "undefined" values, I believe, are/were not saved to/from DB anyway (due to e.g JSON.stringify removing them)
@@ -1206,16 +1177,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
     // obj = _filterNullishValues(obj as any)
     // We still filter `undefined` values here, because `beforeDBMToBM` can return undefined values
     // and they can be annoying with snapshot tests
-    if (this.cfg.filterNullishValues) {
-      obj = _filterNullishValues(obj)
-    } else {
-      obj = _filterUndefinedValues(obj)
-    }
-
-    // Pre-validation hooks
-    if (modelType === DBModelType.DBM) {
-      obj = this.cfg.hooks!.beforeDBMValidate!(obj as any) as T
-    }
+    obj = _filterUndefinedValues(obj)
 
     // Return as is if no schema is passed or if `skipConversion` is set
     if (!schema || opt.skipConversion) {
@@ -1224,7 +1186,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM> {
 
     // This will Convert and Validate
     const table = opt.table || this.cfg.table
-    const objectName = table + (modelType || '')
+    const objectName = table
 
     let error: JoiValidationError | AjvValidationError | ZodValidationError<T> | undefined
     let convertedValue: any
@@ -1413,9 +1375,9 @@ export class CommonDaoTransaction {
   async save<BM extends BaseDBEntity, DBM extends BaseDBEntity>(
     dao: CommonDao<BM, DBM>,
     bm: Unsaved<BM>,
-    opt?: CommonDaoSaveBatchOptions<DBM>,
+    opt?: CommonDaoSaveOptions<BM, DBM>,
   ): Promise<BM> {
-    return (await this.saveBatch(dao, [bm], opt))[0]!
+    return await dao.save(bm, { ...opt, tx: this.tx })
   }
 
   async saveBatch<BM extends BaseDBEntity, DBM extends BaseDBEntity>(
@@ -1426,6 +1388,24 @@ export class CommonDaoTransaction {
     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<BM extends BaseDBEntity, DBM extends BaseDBEntity>(
+    dao: CommonDao<BM, DBM>,
+    bm: BM,
+    patch: Partial<BM>,
+    opt?: CommonDaoSaveOptions<BM, DBM>,
+  ): Promise<BM> {
+    const skipIfEquals = _deepCopy(bm)
+    Object.assign(bm, patch)
+    return await dao.save(bm, { ...opt, skipIfEquals, tx: this.tx })
+  }
+
   async deleteById(
     dao: CommonDao<any>,
     id?: string | null,

package/src/testing/daoTest.ts

@@ -8,10 +8,9 @@ import { CommonDBImplementationQuirks, expectMatch } from './dbTest'
 import {
   createTestItemsBM,
   testItemBMSchema,
-  testItemDBMSchema,
   TEST_TABLE,
   createTestItemBM,
-  testItemDBMJsonSchema,
+  testItemBMJsonSchema,
 } from './test.model'
 import { TestItemBM } from '.'
 
@@ -20,7 +19,6 @@ export function runCommonDaoTest(db: CommonDB, quirks: CommonDBImplementationQui
   const dao = new CommonDao({
     table: TEST_TABLE,
     db,
-    dbmSchema: testItemDBMSchema,
     bmSchema: testItemBMSchema,
     logStarted: true,
     logLevel: CommonDaoLogLevel.DATA_FULL,
@@ -43,7 +41,7 @@ export function runCommonDaoTest(db: CommonDB, quirks: CommonDBImplementationQui
   // CREATE TABLE, DROP
   if (support.createTable) {
     test('createTable, dropIfExists=true', async () => {
-      await dao.createTable(testItemDBMJsonSchema, { dropIfExists: true })
+      await dao.createTable(testItemBMJsonSchema, { dropIfExists: true })
     })
   }
 

package/src/testing/dbTest.ts

@@ -7,8 +7,8 @@ import {
   createTestItemDBM,
   createTestItemsDBM,
   TEST_TABLE,
+  testItemBMJsonSchema,
   TestItemDBM,
-  testItemDBMJsonSchema,
 } from './test.model'
 import { deepFreeze } from './test.util'
 
@@ -42,7 +42,7 @@ export function runCommonDBTest(db: CommonDB, quirks: CommonDBImplementationQuir
   // CREATE TABLE, DROP
   if (support.createTable) {
     test('createTable, dropIfExists=true', async () => {
-      await db.createTable(TEST_TABLE, testItemDBMJsonSchema, { dropIfExists: true })
+      await db.createTable(TEST_TABLE, testItemBMJsonSchema, { dropIfExists: true })
     })
   }
 

package/src/testing/index.ts

@@ -10,8 +10,6 @@ import {
   testItemBMJsonSchema,
   testItemBMSchema,
   TestItemDBM,
-  testItemDBMJsonSchema,
-  testItemDBMSchema,
   TestItemTM,
   testItemTMSchema,
   TEST_TABLE,
@@ -25,11 +23,9 @@ export {
   createTestItemBM,
   createTestItemsDBM,
   createTestItemsBM,
-  testItemDBMSchema,
   testItemBMSchema,
   testItemTMSchema,
   testItemBMJsonSchema,
-  testItemDBMJsonSchema,
   runCommonDBTest,
   runCommonDaoTest,
   runCommonKeyValueDBTest,

package/src/testing/test.model.ts

@@ -35,14 +35,6 @@ export const testItemBMSchema = objectSchema<TestItemBM>({
   b1: binarySchema.optional(),
 }).concat(baseDBEntitySchema as any)
 
-export const testItemDBMSchema = objectSchema<TestItemDBM>({
-  k1: stringSchema,
-  k2: stringSchema.allow(null).optional(),
-  k3: numberSchema.optional(),
-  even: booleanSchema.optional(),
-  b1: binarySchema.optional(),
-}).concat(baseDBEntitySchema as any)
-
 export const testItemTMSchema = objectSchema<TestItemTM>({
   k1: stringSchema,
   even: booleanSchema.optional(),
@@ -63,20 +55,6 @@ export const testItemBMJsonSchema: JsonSchemaObject<TestItemBM> = jsonSchema
   .baseDBEntity()
   .build()
 
-export const testItemDBMJsonSchema: JsonSchemaObject<TestItemDBM> = jsonSchema
-  .rootObject<TestItemDBM>({
-    // todo: figure out how to not copy-paste these 3 fields
-    id: jsonSchema.string(),
-    created: jsonSchema.unixTimestamp(),
-    updated: jsonSchema.unixTimestamp(),
-    k1: jsonSchema.string(),
-    k2: jsonSchema.string().optional(),
-    k3: jsonSchema.number().optional(),
-    even: jsonSchema.boolean().optional(),
-    b1: jsonSchema.buffer().optional(),
-  })
-  .build()
-
 export function createTestItemDBM(num = 1): TestItemDBM {
   return {
     id: `id${num}`,