@naturalcycles/db-lib 9.20.0 → 9.22.0

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,23 +1,18 @@
-import { UnixTimestampNumber } from '@naturalcycles/js-lib'
+import { StringMap, UnixTimestampNumber } from '@naturalcycles/js-lib'
 import { ReadableTyped } from '@naturalcycles/nodejs-lib'
 import { CommonDBCreateOptions } from '../db.model'
 
-export type KeyValueDBTuple = [key: string, value: Buffer]
-
-export interface CommonKeyValueDBSaveBatchOptions {
-  /**
-   * If set (and if it's implemented by the driver) - will set expiry TTL for each key of the batch.
-   * E.g EXAT in Redis.
-   */
-  expireAt?: UnixTimestampNumber
-}
-
 /**
  * Common interface for Key-Value database implementations.
  *
  * @experimental
  */
 export interface CommonKeyValueDB {
+  /**
+   * Manifest of supported features.
+   */
+  support: CommonKeyValueDBSupport
+
   /**
    * Check that DB connection is working properly.
    */
@@ -51,11 +46,49 @@ 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]
+
+export interface CommonKeyValueDBSaveBatchOptions {
+  /**
+   * If set (and if it's implemented by the driver) - will set expiry TTL for each key of the batch.
+   * E.g EXAT in Redis.
+   */
+  expireAt?: UnixTimestampNumber
+}
+
+/**
+ * Manifest of supported features.
+ */
+export interface CommonKeyValueDBSupport {
+  count?: boolean
+  increment?: boolean
+}
+
+export const commonKeyValueDBFullSupport: CommonKeyValueDBSupport = {
+  count: true,
+  increment: true,
 }

package/src/kv/commonKeyValueDao.ts

@@ -8,7 +8,7 @@ import {
   KeyValueDBTuple,
 } from './commonKeyValueDB'
 
-export interface CommonKeyValueDaoCfg<T> {
+export interface CommonKeyValueDaoCfg<V> {
   db: CommonKeyValueDB
 
   table: string
@@ -35,9 +35,9 @@ export interface CommonKeyValueDaoCfg<T> {
   logStarted?: boolean
 
   hooks?: {
-    mapValueToBuffer?: (v: T) => Promise<Buffer>
-    mapBufferToValue?: (b: Buffer) => Promise<T>
-    beforeCreate?: (v: Partial<T>) => Partial<T>
+    mapValueToBuffer?: (v: V) => Promise<Buffer>
+    mapBufferToValue?: (b: Buffer) => Promise<V>
+    beforeCreate?: (v: Partial<V>) => Partial<V>
   }
 
   /**
@@ -203,8 +203,8 @@ export class CommonKeyValueDao<V, K extends string = string> {
     await this.cfg.db.deleteByIds(this.cfg.table, [id])
   }
 
-  streamIds(limit?: number): ReadableTyped<string> {
-    return this.cfg.db.streamIds(this.cfg.table, limit)
+  streamIds(limit?: number): ReadableTyped<K> {
+    return this.cfg.db.streamIds(this.cfg.table, limit) as ReadableTyped<K>
   }
 
   streamValues(limit?: number): ReadableTyped<V> {
@@ -236,10 +236,12 @@ export class CommonKeyValueDao<V, K extends string = string> {
       return this.cfg.db.streamEntries(this.cfg.table, limit) as ReadableTyped<KeyValueTuple<K, V>>
     }
 
-    return this.cfg.db.streamEntries(this.cfg.table, limit).flatMap(
+    return (
+      this.cfg.db.streamEntries(this.cfg.table, limit) as ReadableTyped<KeyValueTuple<K, Buffer>>
+    ).flatMap(
       async ([id, buf]) => {
         try {
-          return [[id as K, await mapBufferToValue(buf)]]
+          return [[id, await mapBufferToValue(buf)]]
         } catch (err) {
           this.cfg.logger.error(err)
           return [] // SKIP
@@ -251,6 +253,18 @@ export class CommonKeyValueDao<V, K extends string = string> {
     )
   }
 
+  async getAllKeys(limit?: number): Promise<K[]> {
+    return await this.streamIds(limit).toArray()
+  }
+
+  async getAllValues(limit?: number): Promise<V[]> {
+    return await this.streamValues(limit).toArray()
+  }
+
+  async getAllEntries(limit?: number): Promise<KeyValueTuple<K, V>[]> {
+    return await this.streamEntries(limit).toArray()
+  }
+
   /**
    * Increments the `id` field by the amount specified in `by`,
    * or by 1 if `by` is not specified.

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) {

package/src/testing/keyValueDBTest.ts

@@ -21,6 +21,8 @@ export function runCommonKeyValueDBTest(db: CommonKeyValueDB): void {
     await db.deleteByIds(TEST_TABLE, ids)
   })
 
+  const { support } = db
+
   test('ping', async () => {
     await db.ping()
   })
@@ -50,9 +52,11 @@ export function runCommonKeyValueDBTest(db: CommonKeyValueDB): void {
     expect(entries).toEqual(testEntries)
   })
 
-  test('count should be 3', async () => {
-    expect(await db.count(TEST_TABLE)).toBe(3)
-  })
+  if (support.count) {
+    test('count should be 3', async () => {
+      expect(await db.count(TEST_TABLE)).toBe(3)
+    })
+  }
 
   test('streamIds', async () => {
     const ids = await db.streamIds(TEST_TABLE).toArray()
@@ -100,18 +104,34 @@ export function runCommonKeyValueDBTest(db: CommonKeyValueDB): void {
     expect(results).toEqual([])
   })
 
-  test('increment on a non-existing field should set the value to 1', async () => {
-    const result = await db.increment(TEST_TABLE, 'nonExistingField')
-    expect(result).toBe(1)
-  })
-
-  test('increment on a existing field should increase the value by one', async () => {
-    const result = await db.increment(TEST_TABLE, 'nonExistingField')
-    expect(result).toBe(2)
-  })
-
-  test('increment should increase the value by the specified amount', async () => {
-    const result = await db.increment(TEST_TABLE, 'nonExistingField', 2)
-    expect(result).toBe(4)
-  })
+  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_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_TABLE, id)
+      expect(result).toBe(2)
+    })
+
+    test('increment should increase the value by the specified amount', async () => {
+      const result = await db.increment(TEST_TABLE, id, 2)
+      expect(result).toBe(4)
+    })
+
+    test('increment 2 ids at the same time', async () => {
+      const result = await db.incrementBatch(TEST_TABLE, {
+        [id]: 1,
+        [id2]: 2,
+      })
+      expect(result).toEqual({
+        [id]: 5,
+        [id2]: 2,
+      })
+    })
+  }
 }

package/src/testing/keyValueDaoTest.ts

@@ -20,6 +20,8 @@ export function runCommonKeyValueDaoTest(dao: CommonKeyValueDao<Buffer>): void {
     await dao.deleteByIds(ids)
   })
 
+  const { support } = dao.cfg.db
+
   test('ping', async () => {
     await dao.ping()
   })
@@ -91,18 +93,20 @@ export function runCommonKeyValueDaoTest(dao: CommonKeyValueDao<Buffer>): void {
     expect(results).toEqual([])
   })
 
-  test('increment on a non-existing field should set the value to 1', async () => {
-    const result = await dao.increment('nonExistingField')
-    expect(result).toBe(1)
-  })
+  if (support.increment) {
+    test('increment on a non-existing field should set the value to 1', async () => {
+      const result = await dao.increment('nonExistingField')
+      expect(result).toBe(1)
+    })
 
-  test('increment on a existing field should increase the value by one', async () => {
-    const result = await dao.increment('nonExistingField')
-    expect(result).toBe(2)
-  })
+    test('increment on a existing field should increase the value by one', async () => {
+      const result = await dao.increment('nonExistingField')
+      expect(result).toBe(2)
+    })
 
-  test('increment should increase the value by the specified amount', async () => {
-    const result = await dao.increment('nonExistingField', 2)
-    expect(result).toBe(4)
-  })
+    test('increment should increase the value by the specified amount', async () => {
+      const result = await dao.increment('nonExistingField', 2)
+      expect(result).toBe(4)
+    })
+  }
 }