@naturalcycles/db-lib 9.21.0 → 9.22.0

package/dist/testing/keyValueDBTest.js

@@ -86,17 +86,29 @@ function runCommonKeyValueDBTest(db) {
         expect(results).toEqual([]);
     });
     if (support.increment) {
+        const id = 'nonExistingField';
+        const id2 = 'nonExistingField2';
         test('increment on a non-existing field should set the value to 1', async () => {
-            const result = await db.increment(test_model_1.TEST_TABLE, 'nonExistingField');
+            const result = await db.increment(test_model_1.TEST_TABLE, id);
             expect(result).toBe(1);
         });
         test('increment on a existing field should increase the value by one', async () => {
-            const result = await db.increment(test_model_1.TEST_TABLE, 'nonExistingField');
+            const result = await db.increment(test_model_1.TEST_TABLE, id);
             expect(result).toBe(2);
         });
         test('increment should increase the value by the specified amount', async () => {
-            const result = await db.increment(test_model_1.TEST_TABLE, 'nonExistingField', 2);
+            const result = await db.increment(test_model_1.TEST_TABLE, id, 2);
             expect(result).toBe(4);
         });
+        test('increment 2 ids at the same time', async () => {
+            const result = await db.incrementBatch(test_model_1.TEST_TABLE, {
+                [id]: 1,
+                [id2]: 2,
+            });
+            expect(result).toEqual({
+                [id]: 5,
+                [id2]: 2,
+            });
+        });
     }
 }

package/package.json

@@ -45,7 +45,7 @@
   "engines": {
     "node": ">=20.13"
   },
-  "version": "9.21.0",
+  "version": "9.22.0",
   "description": "Lowest Common Denominator API to supported Databases",
   "keywords": [
     "db",

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

@@ -9,7 +9,7 @@ import {
 import { ReadableTyped } from '@naturalcycles/nodejs-lib'
 import { BaseCommonDB } from '../../base.common.db'
 import { CommonDB, commonDBFullSupport, CommonDBSupport } from '../../common.db'
-import { DBPatch, RunQueryResult } from '../../db.model'
+import { RunQueryResult } from '../../db.model'
 import { DBQuery } from '../../query/dbQuery'
 import {
   CacheDBCfg,
@@ -29,6 +29,7 @@ export class CacheDB extends BaseCommonDB implements CommonDB {
   override support: CommonDBSupport = {
     ...commonDBFullSupport,
     transactions: false,
+    increment: false,
   }
 
   constructor(cfg: CacheDBCfg) {
@@ -271,19 +272,19 @@ export class CacheDB extends BaseCommonDB implements CommonDB {
     return deletedIds
   }
 
-  override async updateByQuery<ROW extends ObjectWithId>(
+  override async patchByQuery<ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
-    patch: DBPatch<ROW>,
+    patch: Partial<ROW>,
     opt: CacheDBOptions = {},
   ): Promise<number> {
     let updated: number | undefined
 
     if (!opt.onlyCache && !this.cfg.onlyCache) {
-      updated = await this.cfg.downstreamDB.updateByQuery(q, patch, opt)
+      updated = await this.cfg.downstreamDB.patchByQuery(q, patch, opt)
     }
 
     if (!opt.skipCache && !this.cfg.skipCache) {
-      const cacheResult = this.cfg.cacheDB.updateByQuery(q, patch, opt)
+      const cacheResult = this.cfg.cacheDB.patchByQuery(q, patch, opt)
       if (this.cfg.awaitCache) updated ??= await cacheResult
     }
 

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

@@ -45,9 +45,10 @@ export class FileDB extends BaseCommonDB implements CommonDB {
     bufferValues: false, // todo: implement
     insertSaveMethod: false,
     updateSaveMethod: false,
-    updateByQuery: false,
+    patchByQuery: false,
     createTable: false,
     transactions: false, // todo
+    increment: false,
   }
 
   constructor(cfg: FileDBCfg) {

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

@@ -3,9 +3,12 @@ import {
   _assert,
   _by,
   _deepCopy,
+  _isEmptyObject,
   _since,
   _sortObjectDeep,
+  _stringMapEntries,
   _stringMapValues,
+  AnyObjectWithId,
   CommonLogger,
   generateJsonSchemaFromData,
   JsonSchemaObject,
@@ -27,9 +30,7 @@ import {
   commonDBFullSupport,
   CommonDBTransactionOptions,
   CommonDBType,
-  DBIncrement,
   DBOperation,
-  DBPatch,
   DBTransactionFn,
   queryInMemory,
 } from '../..'
@@ -113,7 +114,7 @@ export class InMemoryDB implements CommonDB {
   cfg: InMemoryDBCfg
 
   // data[table][id] > {id: 'a', created: ... }
-  data: StringMap<StringMap<ObjectWithId>> = {}
+  data: StringMap<StringMap<AnyObjectWithId>> = {}
 
   /**
    * Returns internal "Data snapshot".
@@ -233,25 +234,14 @@ export class InMemoryDB implements CommonDB {
     return count
   }
 
-  async updateByQuery<ROW extends ObjectWithId>(
+  async patchByQuery<ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
-    patch: DBPatch<ROW>,
+    patch: Partial<ROW>,
   ): Promise<number> {
-    const patchEntries = Object.entries(patch)
-    if (!patchEntries.length) return 0
-
+    if (_isEmptyObject(patch)) return 0
     const table = this.cfg.tablesPrefix + q.table
     const rows = queryInMemory(q, Object.values(this.data[table] || {}) as ROW[])
-    rows.forEach((row: any) => {
-      patchEntries.forEach(([k, v]) => {
-        if (v instanceof DBIncrement) {
-          row[k] = (row[k] || 0) + v.amount
-        } else {
-          row[k] = v
-        }
-      })
-    })
-
+    rows.forEach(row => Object.assign(row, patch))
     return rows.length
   }
 
@@ -294,6 +284,27 @@ export class InMemoryDB implements CommonDB {
     }
   }
 
+  async incrementBatch(
+    table: string,
+    prop: string,
+    incrementMap: StringMap<number>,
+    _opt?: CommonDBOptions,
+  ): Promise<StringMap<number>> {
+    const tbl = this.cfg.tablesPrefix + table
+    this.data[tbl] ||= {}
+
+    const result: StringMap<number> = {}
+
+    for (const [id, by] of _stringMapEntries(incrementMap)) {
+      this.data[tbl][id] ||= { id }
+      const newValue = ((this.data[tbl][id][prop] as number) || 0) + by
+      this.data[tbl][id][prop] = newValue
+      result[id] = newValue
+    }
+
+    return result
+  }
+
   /**
    * Flushes all tables (all namespaces) at once.
    */

package/src/adapter/inmemory/inMemoryKeyValueDB.ts

@@ -1,5 +1,5 @@
 import { Readable } from 'node:stream'
-import { StringMap } from '@naturalcycles/js-lib'
+import { _stringMapEntries, StringMap } from '@naturalcycles/js-lib'
 import { ReadableTyped } from '@naturalcycles/nodejs-lib'
 import { CommonDBCreateOptions } from '../../db.model'
 import {
@@ -29,6 +29,7 @@ export class InMemoryKeyValueDB implements CommonKeyValueDB {
     ids.forEach(id => delete this.data[table]![id])
   }
 
+  // todo: but should we work with Tuples or Objects?
   async getByIds(table: string, ids: string[]): Promise<KeyValueDBTuple[]> {
     this.data[table] ||= {}
     return ids.map(id => [id, this.data[table]![id]!] as KeyValueDBTuple).filter(e => e[1])
@@ -65,4 +66,19 @@ export class InMemoryKeyValueDB implements CommonKeyValueDB {
 
     return newValue
   }
+
+  async incrementBatch(table: string, incrementMap: StringMap<number>): Promise<StringMap<number>> {
+    this.data[table] ||= {}
+
+    const result: StringMap<number> = {}
+
+    for (const [id, by] of _stringMapEntries(incrementMap)) {
+      const newValue = parseInt(this.data[table][id]?.toString() || '0') + by
+      // todo: but should this.data store Buffer or number for incremented values?
+      this.data[table][id] = Buffer.from(String(newValue))
+      result[id] = newValue
+    }
+
+    return result
+  }
 }

package/src/base.common.db.ts

@@ -1,11 +1,15 @@
-import { JsonSchemaObject, JsonSchemaRootObject, ObjectWithId } from '@naturalcycles/js-lib'
+import {
+  JsonSchemaObject,
+  JsonSchemaRootObject,
+  ObjectWithId,
+  StringMap,
+} from '@naturalcycles/js-lib'
 import { ReadableTyped } from '@naturalcycles/nodejs-lib'
 import { CommonDB, CommonDBSupport, CommonDBType } from './common.db'
 import {
   CommonDBOptions,
   CommonDBSaveOptions,
   CommonDBTransactionOptions,
-  DBPatch,
   DBTransactionFn,
   RunQueryResult,
 } from './db.model'
@@ -50,12 +54,12 @@ export class BaseCommonDB implements CommonDB {
     throw new Error('deleteByQuery is not implemented')
   }
 
-  async updateByQuery<ROW extends ObjectWithId>(
+  async patchByQuery<ROW extends ObjectWithId>(
     _q: DBQuery<ROW>,
-    _patch: DBPatch<ROW>,
+    _patch: Partial<ROW>,
     _opt?: CommonDBOptions,
   ): Promise<number> {
-    throw new Error('updateByQuery is not implemented')
+    throw new Error('patchByQuery is not implemented')
   }
 
   async runQuery<ROW extends ObjectWithId>(_q: DBQuery<ROW>): Promise<RunQueryResult<ROW>> {
@@ -87,4 +91,13 @@ export class BaseCommonDB implements CommonDB {
     await fn(tx)
     // there's no try/catch and rollback, as there's nothing to rollback
   }
+
+  async incrementBatch(
+    _table: string,
+    _prop: string,
+    _incrementMap: StringMap<number>,
+    _opt?: CommonDBOptions,
+  ): Promise<StringMap<number>> {
+    throw new Error('incrementBatch is not implemented')
+  }
 }

package/src/common.db.ts

@@ -1,4 +1,9 @@
-import { JsonSchemaObject, JsonSchemaRootObject, ObjectWithId } from '@naturalcycles/js-lib'
+import {
+  JsonSchemaObject,
+  JsonSchemaRootObject,
+  ObjectWithId,
+  StringMap,
+} from '@naturalcycles/js-lib'
 import type { ReadableTyped } from '@naturalcycles/nodejs-lib'
 import {
   CommonDBCreateOptions,
@@ -6,7 +11,6 @@ import {
   CommonDBSaveOptions,
   CommonDBStreamOptions,
   CommonDBTransactionOptions,
-  DBPatch,
   DBTransactionFn,
   RunQueryResult,
 } from './db.model'
@@ -116,7 +120,7 @@ export interface CommonDB {
   ) => Promise<number>
 
   /**
-   * Applies patch to the rows returned by the query.
+   * Applies patch to all the rows that are matched by the query.
    *
    * Example:
    *
@@ -124,18 +128,11 @@ export interface CommonDB {
    *
    * patch would be { A: 'B' } for that query.
    *
-   * Supports "increment query", example:
-   *
-   * UPDATE table SET A = A + 1
-   *
-   * In that case patch would look like:
-   * { A: DBIncrement(1) }
-   *
-   * Returns number of rows affected.
+   * Returns the number of rows affected.
    */
-  updateByQuery: <ROW extends ObjectWithId>(
+  patchByQuery: <ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
-    patch: DBPatch<ROW>,
+    patch: Partial<ROW>,
     opt?: CommonDBOptions,
   ) => Promise<number>
 
@@ -152,6 +149,28 @@ export interface CommonDB {
    * unless specified as readOnly in CommonDBTransactionOptions.
    */
   runInTransaction: (fn: DBTransactionFn, opt?: CommonDBTransactionOptions) => Promise<void>
+
+  /**
+   * Increments a value of a property by a given amount.
+   * This is a batch operation, so it allows to increment multiple rows at once.
+   *
+   * - table - the table to apply operations on
+   * - prop - name of the property to increment (in each of the rows passed)
+   * - incrementMap - map from id to increment value
+   *
+   * Example of incrementMap:
+   * { rowId1: 2, rowId2: 3 }
+   *
+   * Returns the incrementMap with the same keys and updated values.
+   *
+   * @experimental
+   */
+  incrementBatch: (
+    table: string,
+    prop: string,
+    incrementMap: StringMap<number>,
+    opt?: CommonDBOptions,
+  ) => Promise<StringMap<number>>
 }
 
 /**
@@ -165,8 +184,8 @@ export interface CommonDBSupport {
   dbQuerySelectFields?: boolean
   insertSaveMethod?: boolean
   updateSaveMethod?: boolean
-  updateByQuery?: boolean
-  dbIncrement?: boolean
+  patchByQuery?: boolean
+  increment?: boolean
   createTable?: boolean
   tableSchemas?: boolean
   streaming?: boolean
@@ -183,8 +202,8 @@ export const commonDBFullSupport: CommonDBSupport = {
   dbQuerySelectFields: true,
   insertSaveMethod: true,
   updateSaveMethod: true,
-  updateByQuery: true,
-  dbIncrement: true,
+  patchByQuery: true,
+  increment: true,
   createTable: true,
   tableSchemas: true,
   streaming: true,

package/src/commondao/common.dao.ts

@@ -22,6 +22,7 @@ import {
   ObjectWithId,
   pMap,
   SKIP,
+  StringMap,
   UnixTimestampMillisNumber,
   Unsaved,
   ZodSchema,
@@ -44,7 +45,7 @@ import {
   writableVoid,
 } from '@naturalcycles/nodejs-lib'
 import { DBLibError } from '../cnst'
-import { CommonDBTransactionOptions, DBPatch, DBTransaction, RunQueryResult } from '../db.model'
+import { CommonDBTransactionOptions, DBTransaction, RunQueryResult } from '../db.model'
 import { DBQuery, RunnableDBQuery } from '../query/dbQuery'
 import {
   CommonDaoCfg,
@@ -1068,31 +1069,65 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     return deleted
   }
 
-  async updateById(id: ID, patch: DBPatch<DBM>, opt: CommonDaoOptions = {}): Promise<number> {
-    return await this.updateByQuery(this.query().filterEq('id', id), patch, opt)
-  }
-
-  async updateByIds(ids: ID[], patch: DBPatch<DBM>, opt: CommonDaoOptions = {}): Promise<number> {
+  async patchByIds(ids: ID[], patch: Partial<DBM>, opt: CommonDaoOptions = {}): Promise<number> {
     if (!ids.length) return 0
-    return await this.updateByQuery(this.query().filterIn('id', ids), patch, opt)
+    return await this.patchByQuery(this.query().filterIn('id', ids), patch, opt)
   }
 
-  async updateByQuery(
+  async patchByQuery(
     q: DBQuery<DBM>,
-    patch: DBPatch<DBM>,
+    patch: Partial<DBM>,
     opt: CommonDaoOptions = {},
   ): Promise<number> {
     this.validateQueryIndexes(q) // throws if query uses `excludeFromIndexes` property
     this.requireWriteAccess()
     this.requireObjectMutability(opt)
     q.table = opt.table || q.table
-    const op = `updateByQuery(${q.pretty()})`
+    const op = `patchByQuery(${q.pretty()})`
     const started = this.logStarted(op, q.table)
-    const updated = await this.cfg.db.updateByQuery(q, patch, opt)
+    const updated = await this.cfg.db.patchByQuery(q, patch, opt)
     this.logSaveResult(started, op, q.table)
     return updated
   }
 
+  /**
+   * Caveat: it doesn't update created/updated props.
+   *
+   * @experimental
+   */
+  async increment(prop: keyof DBM, id: ID, by = 1, opt: CommonDaoOptions = {}): Promise<number> {
+    this.requireWriteAccess()
+    this.requireObjectMutability(opt)
+    const { table } = this.cfg
+    const op = `increment`
+    const started = this.logStarted(op, table)
+    const result = await this.cfg.db.incrementBatch(table, prop as string, {
+      [id as string]: by,
+    })
+    this.logSaveResult(started, op, table)
+    return result[id as string]!
+  }
+
+  /**
+   * Caveat: it doesn't update created/updated props.
+   *
+   * @experimental
+   */
+  async incrementBatch(
+    prop: keyof DBM,
+    incrementMap: StringMap<number>,
+    opt: CommonDaoOptions = {},
+  ): Promise<StringMap<number>> {
+    this.requireWriteAccess()
+    this.requireObjectMutability(opt)
+    const { table } = this.cfg
+    const op = `incrementBatch`
+    const started = this.logStarted(op, table)
+    const result = await this.cfg.db.incrementBatch(table, prop as string, incrementMap)
+    this.logSaveResult(started, op, table)
+    return result
+  }
+
   // CONVERSIONS
 
   async dbmToBM(_dbm: undefined, opt?: CommonDaoOptions): Promise<undefined>

package/src/db.model.ts

@@ -113,22 +113,3 @@ export enum DBModelType {
   DBM = 'DBM',
   BM = 'BM',
 }
-
-/**
- * Allows to construct a query similar to:
- *
- * UPDATE table SET A = A + 1
- *
- * In this case DBIncement.of(1) will be needed.
- */
-export class DBIncrement {
-  private constructor(public amount: number) {}
-
-  static of(amount: number): DBIncrement {
-    return new DBIncrement(amount)
-  }
-}
-
-export type DBPatch<ROW extends ObjectWithId> = Partial<
-  Record<keyof ROW, ROW[keyof ROW] | DBIncrement>
->

package/src/kv/commonKeyValueDB.ts

@@ -1,4 +1,4 @@
-import { UnixTimestampNumber } from '@naturalcycles/js-lib'
+import { StringMap, UnixTimestampNumber } from '@naturalcycles/js-lib'
 import { ReadableTyped } from '@naturalcycles/nodejs-lib'
 import { CommonDBCreateOptions } from '../db.model'
 
@@ -46,13 +46,28 @@ export interface CommonKeyValueDB {
   count: (table: string) => Promise<number>
 
   /**
-   *
    * Increments the value of a key in a table by a given amount.
    * Default increment is 1 when `by` is not provided.
    *
    * Returns the new value.
+   *
+   * @experimental
    */
   increment: (table: string, id: string, by?: number) => Promise<number>
+
+  /**
+   * Perform a batch of Increment operations.
+   * Given incrementMap, increment each key of it by the given amount (value of the map).
+   *
+   * Example:
+   * { key1: 2, key2: 3 }
+   * would increment `key1` by 2, and `key2` by 3.
+   *
+   * Returns the incrementMap with the same keys and updated values.
+   *
+   * @experimental
+   */
+  incrementBatch: (table: string, incrementMap: StringMap<number>) => Promise<StringMap<number>>
 }
 
 export type KeyValueDBTuple = [key: string, value: Buffer]

package/src/query/dbQuery.ts

@@ -11,7 +11,6 @@ import {
   CommonDaoStreamDeleteOptions,
   CommonDaoStreamForEachOptions,
   CommonDaoStreamOptions,
-  DBPatch,
 } from '..'
 import { CommonDao } from '../commondao/common.dao'
 import { RunQueryResult } from '../db.model'
@@ -276,8 +275,8 @@ export class RunnableDBQuery<
     return await this.dao.runQueryCount(this, opt)
   }
 
-  async updateByQuery(patch: DBPatch<DBM>, opt?: CommonDaoOptions): Promise<number> {
-    return await this.dao.updateByQuery(this, patch, opt)
+  async patchByQuery(patch: Partial<DBM>, opt?: CommonDaoOptions): Promise<number> {
+    return await this.dao.patchByQuery(this, patch, opt)
   }
 
   async streamQueryForEach(

package/src/testing/daoTest.ts

@@ -129,6 +129,34 @@ export function runCommonDaoTest(db: CommonDB, quirks: CommonDBImplementationQui
     expectMatch(expectedItems, itemsSaved, quirks)
   })
 
+  if (support.increment) {
+    test('increment', async () => {
+      await dao.incrementBatch('k3', { id1: 1, id2: 2 })
+      let rows = await dao.query().runQuery()
+      rows = _sortBy(rows, r => r.id)
+      const expected = expectedItems.map(r => {
+        if (r.id === 'id1') {
+          return {
+            ...r,
+            k3: r.k3! + 1,
+          }
+        }
+        if (r.id === 'id2') {
+          return {
+            ...r,
+            k3: r.k3! + 2,
+          }
+        }
+        return r
+      })
+      expectMatch(expected, rows, quirks)
+
+      // reset the changes
+      await dao.increment('k3', 'id1', -1)
+      await dao.increment('k3', 'id2', -2)
+    })
+  }
+
   // GET not empty
   test('getByIds all items', async () => {
     const rows = await dao.getByIds(items.map(i => i.id).concat('abcd'))

package/src/testing/dbTest.ts

@@ -1,6 +1,5 @@
 import { _deepFreeze, _filterObject, _pick, _sortBy, pMap } from '@naturalcycles/js-lib'
 import { CommonDB, CommonDBType } from '../common.db'
-import { DBIncrement, DBPatch } from '../db.model'
 import { DBQuery } from '../query/dbQuery'
 import {
   createTestItemDBM,
@@ -317,18 +316,18 @@ export function runCommonDBTest(db: CommonDB, quirks: CommonDBImplementationQuir
     })
   }
 
-  if (support.updateByQuery) {
-    test('updateByQuery simple', async () => {
+  if (support.patchByQuery) {
+    test('patchByQuery', async () => {
       // cleanup, reset initial data
       await db.deleteByQuery(queryAll())
       await db.saveBatch(TEST_TABLE, items)
 
-      const patch: DBPatch<TestItemDBM> = {
+      const patch: Partial<TestItemDBM> = {
         k3: 5,
         k2: 'abc',
       }
 
-      await db.updateByQuery(DBQuery.create<TestItemDBM>(TEST_TABLE).filterEq('even', true), patch)
+      await db.patchByQuery(DBQuery.create<TestItemDBM>(TEST_TABLE).filterEq('even', true), patch)
 
       const { rows } = await db.runQuery(queryAll())
       const expected = items.map(r => {
@@ -339,33 +338,28 @@ export function runCommonDBTest(db: CommonDB, quirks: CommonDBImplementationQuir
       })
       expectMatch(expected, rows, quirks)
     })
+  }
 
-    if (support.dbIncrement) {
-      test('updateByQuery DBIncrement', async () => {
-        // cleanup, reset initial data
-        await db.deleteByQuery(queryAll())
-        await db.saveBatch(TEST_TABLE, items)
-
-        const patch: DBPatch<TestItemDBM> = {
-          k3: DBIncrement.of(1),
-          k2: 'abcd',
-        }
+  if (support.increment) {
+    test('incrementBatch', async () => {
+      // cleanup, reset initial data
+      await db.deleteByQuery(queryAll())
+      await db.saveBatch(TEST_TABLE, items)
 
-        await db.updateByQuery(
-          DBQuery.create<TestItemDBM>(TEST_TABLE).filterEq('even', true),
-          patch,
-        )
+      await db.incrementBatch(TEST_TABLE, 'k3', { id1: 1, id2: 2 })
 
-        const { rows } = await db.runQuery(queryAll())
-        const expected = items.map(r => {
-          if (r.even) {
-            return { ...r, ...patch, k3: (r.k3 || 0) + 1 }
-          }
-          return r
-        })
-        expectMatch(expected, rows, quirks)
+      const { rows } = await db.runQuery(queryAll())
+      const expected = items.map(r => {
+        if (r.id === 'id1') {
+          return { ...r, k3: 2 }
+        }
+        if (r.id === 'id2') {
+          return { ...r, k3: 4 }
+        }
+        return r
       })
-    }
+      expectMatch(expected, rows, quirks)
+    })
   }
 
   if (support.queries) {