@naturalcycles/db-lib 8.46.1 → 8.48.0

package/src/common.db.ts

@@ -5,6 +5,7 @@ import {
   CommonDBOptions,
   CommonDBSaveOptions,
   CommonDBStreamOptions,
+  DBPatch,
   RunQueryResult,
 } from './db.model'
 import { DBQuery } from './query/dbQuery'
@@ -42,17 +43,6 @@ export interface CommonDB {
     opt?: CommonDBCreateOptions,
   ): Promise<void>
 
-  // GET
-  /**
-   * Order of items returned is not guaranteed to match order of ids.
-   * (Such limitation exists because Datastore doesn't support it).
-   */
-  getByIds<ROW extends ObjectWithId>(
-    table: string,
-    ids: ROW['id'][],
-    opt?: CommonDBOptions,
-  ): Promise<ROW[]>
-
   // QUERY
   /**
    * Order by 'id' is not supported by all implementations (for example, Datastore doesn't support it).
@@ -84,14 +74,32 @@ export interface CommonDB {
    * Returns number of deleted items.
    * Not supported by all implementations (e.g Datastore will always return same number as number of ids).
    */
-  deleteByIds<ROW extends ObjectWithId>(
-    table: string,
-    ids: ROW['id'][],
+  deleteByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBOptions): Promise<number>
+
+  /**
+   * Applies patch to the rows returned by the query.
+   *
+   * Example:
+   *
+   * UPDATE table SET A = B where $QUERY_CONDITION
+   *
+   * 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.
+   */
+  updateByQuery<ROW extends ObjectWithId>(
+    q: DBQuery<ROW>,
+    patch: DBPatch<ROW>,
     opt?: CommonDBOptions,
   ): Promise<number>
 
-  deleteByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBOptions): Promise<number>
-
   // TRANSACTION
   /**
    * Should be implemented as a Transaction (best effort), which means that

package/src/commondao/common.dao.ts

@@ -40,6 +40,7 @@ import {
   DBDeleteByIdsOperation,
   DBModelType,
   DBOperation,
+  DBPatch,
   DBSaveBatchOperation,
   RunQueryResult,
 } from '../db.model'
@@ -133,14 +134,17 @@ export class CommonDao<
 
     if (opt.timeout) {
       // todo: possibly remove it after debugging is done
-      dbm = (
-        await pTimeout(() => this.cfg.db.getByIds<DBM>(table, [id]), {
+      dbm = await pTimeout(
+        async () => {
+          return (await this.cfg.db.runQuery(DBQuery.create<DBM>(table).filterEq('id', id))).rows[0]
+        },
+        {
           timeout: opt.timeout,
           name: `getById(${table})`,
-        })
-      )[0]
+        },
+      )
     } else {
-      dbm = (await this.cfg.db.getByIds<DBM>(table, [id]))[0]
+      dbm = (await this.cfg.db.runQuery(DBQuery.create<DBM>(table).filterEq('id', id))).rows[0]
     }
 
     const bm = opt.raw ? (dbm as any) : await this.dbmToBM(dbm, opt)
@@ -170,7 +174,7 @@ export class CommonDao<
     const op = `getByIdAsDBM(${id})`
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
-    let [dbm] = await this.cfg.db.getByIds<DBM>(table, [id])
+    let [dbm] = (await this.cfg.db.runQuery(DBQuery.create<DBM>(table).filterEq('id', id))).rows
     if (!opt.raw) {
       dbm = this.anyToDBM(dbm!, opt)
     }
@@ -185,7 +189,7 @@ export class CommonDao<
     const op = `getByIdAsTM(${id})`
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
-    const [dbm] = await this.cfg.db.getByIds<DBM>(table, [id])
+    const [dbm] = (await this.cfg.db.runQuery(DBQuery.create<DBM>(table).filterEq('id', id))).rows
     if (opt.raw) {
       this.logResult(started, op, dbm, table)
       return (dbm as any) || null
@@ -200,7 +204,7 @@ export class CommonDao<
     const op = `getByIds ${ids.length} id(s) (${_truncate(ids.slice(0, 10).join(', '), 50)})`
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
-    const dbms = await this.cfg.db.getByIds<DBM>(table, ids)
+    const dbms = (await this.cfg.db.runQuery(DBQuery.create<DBM>(table).filterIn('id', ids))).rows
     const bms = opt.raw ? (dbms as any) : await this.dbmsToBM(dbms, opt)
     this.logResult(started, op, bms, table)
     return bms
@@ -210,7 +214,7 @@ export class CommonDao<
     const op = `getByIdsAsDBM ${ids.length} id(s) (${_truncate(ids.slice(0, 10).join(', '), 50)})`
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
-    const dbms = await this.cfg.db.getByIds<DBM>(table, ids)
+    const dbms = (await this.cfg.db.runQuery(DBQuery.create<DBM>(table).filterIn('id', ids))).rows
     this.logResult(started, op, dbms, table)
     return dbms
   }
@@ -266,7 +270,8 @@ 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])
+    const existing = (await this.cfg.db.runQuery(DBQuery.create<DBM>(table).filterEq('id', dbm.id)))
+      .rows
     if (existing.length) {
       throw new AppError(DBLibError.NON_UNIQUE_ID, {
         table,
@@ -868,9 +873,9 @@ export class CommonDao<
     const op = `deleteById(${id})`
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
-    const ids = await this.cfg.db.deleteByIds(table, [id])
+    const count = await this.cfg.db.deleteByQuery(DBQuery.create(table).filterEq('id', id))
     this.logSaveResult(started, op, table)
-    return ids
+    return count
   }
 
   async deleteByIds(ids: ID[], opt: CommonDaoOptions = {}): Promise<number> {
@@ -879,9 +884,9 @@ export class CommonDao<
     const op = `deleteByIds(${ids.join(', ')})`
     const table = opt.table || this.cfg.table
     const started = this.logStarted(op, table)
-    const deletedIds = await this.cfg.db.deleteByIds(table, ids)
+    const count = await this.cfg.db.deleteByQuery(DBQuery.create(table).filterIn('id', ids))
     this.logSaveResult(started, op, table)
-    return deletedIds
+    return count
   }
 
   /**
@@ -911,7 +916,10 @@ export class CommonDao<
         transformBuffer<string>({ batchSize }),
         transformMap<string[], void>(
           async ids => {
-            deleted += await this.cfg.db.deleteByIds(q.table, ids, opt)
+            deleted += await this.cfg.db.deleteByQuery(
+              DBQuery.create(q.table).filterIn('id', ids),
+              opt,
+            )
           },
           {
             predicate: _passthroughPredicate,
@@ -934,6 +942,29 @@ export class CommonDao<
     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> {
+    return await this.updateByQuery(this.query().filterIn('id', ids), patch, opt)
+  }
+
+  async updateByQuery(
+    q: DBQuery<DBM>,
+    patch: DBPatch<DBM>,
+    opt: CommonDaoOptions = {},
+  ): Promise<number> {
+    this.requireWriteAccess()
+    this.requireObjectMutability(opt)
+    q.table = opt.table || q.table
+    const op = `updateByQuery(${q.pretty()})`
+    const started = this.logStarted(op, q.table)
+    const updated = await this.cfg.db.updateByQuery(q, patch, opt)
+    this.logSaveResult(started, op, q.table)
+    return updated
+  }
+
   // CONVERSIONS
 
   async dbmToBM(_dbm: undefined, opt?: CommonDaoOptions): Promise<undefined>

package/src/db.model.ts

@@ -76,3 +76,22 @@ export enum DBModelType {
   BM = 'BM',
   TM = 'TM',
 }
+
+/**
+ * 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 Partial<ObjectWithId>> = Partial<
+  Record<keyof ROW, ROW[keyof ROW] | DBIncrement>
+>

package/src/query/dbQuery.ts

@@ -5,9 +5,15 @@ import {
   _truncate,
   Saved,
   AnyObject,
+  _objectAssign,
 } from '@naturalcycles/js-lib'
 import { ReadableTyped } from '@naturalcycles/nodejs-lib'
-import { CommonDaoOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions } from '..'
+import {
+  CommonDaoOptions,
+  CommonDaoStreamForEachOptions,
+  CommonDaoStreamOptions,
+  DBPatch,
+} from '..'
 import { CommonDao } from '../commondao/common.dao'
 import { RunQueryResult } from '../db.model'
 
@@ -118,6 +124,11 @@ export class DBQuery<ROW extends ObjectWithId = AnyObjectWithId> {
     return this
   }
 
+  filterIn(name: keyof ROW, val: any[]): this {
+    this._filters.push({ name, op: 'in', val })
+    return this
+  }
+
   limit(limit: number): this {
     this._limitValue = limit
     return this
@@ -162,7 +173,7 @@ export class DBQuery<ROW extends ObjectWithId = AnyObjectWithId> {
   }
 
   clone(): DBQuery<ROW> {
-    return Object.assign(new DBQuery<ROW>(this.table), {
+    return _objectAssign(new DBQuery<ROW>(this.table), {
       _filters: [...this._filters],
       _limitValue: this._limitValue,
       _offsetValue: this._offsetValue,
@@ -269,6 +280,10 @@ 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 streamQueryForEach(
     mapper: AsyncMapper<Saved<BM>, void>,
     opt?: CommonDaoStreamForEachOptions<Saved<BM>>,

package/src/testing/daoTest.ts

@@ -1,6 +1,6 @@
 import { pDelay, _deepCopy, _pick, _sortBy, _omit, localTime } from '@naturalcycles/js-lib'
 import { readableToArray, transformNoOp } from '@naturalcycles/nodejs-lib'
-import { CommonDaoLogLevel } from '..'
+import { CommonDaoLogLevel, DBQuery } from '..'
 import { CommonDB } from '../common.db'
 import { CommonDao } from '../commondao/common.dao'
 import { CommonDBImplementationFeatures, CommonDBImplementationQuirks, expectMatch } from './dbTest'
@@ -75,9 +75,12 @@ export function runCommonDaoTest(
     // DELETE ALL initially
     test('deleteByIds test items', async () => {
       const rows = await dao.query().select(['id']).runQuery()
-      await db.deleteByIds(
-        TEST_TABLE,
-        rows.map(i => i.id),
+      await db.deleteByQuery(
+        DBQuery.create(TEST_TABLE).filter(
+          'id',
+          'in',
+          rows.map(r => r.id),
+        ),
       )
     })
 
@@ -156,7 +159,11 @@ export function runCommonDaoTest(
   // GET not empty
   test('getByIds all items', async () => {
     const rows = await dao.getByIds(items.map(i => i.id).concat('abcd'))
-    expectMatch(expectedItems, rows, quirks)
+    expectMatch(
+      expectedItems,
+      _sortBy(rows, r => r.id),
+      quirks,
+    )
   })
 
   // QUERY
@@ -258,11 +265,7 @@ export function runCommonDaoTest(
 
     test('cleanup', async () => {
       // CLEAN UP
-      const rows = await dao.query().select(['id']).runQuery()
-      await db.deleteByIds(
-        TEST_TABLE,
-        rows.map(i => i.id),
-      )
+      await dao.query().deleteByQuery()
     })
   }
 

package/src/testing/dbTest.ts

@@ -1,6 +1,7 @@
 import { pDelay, pMap, _filterObject, _pick, _sortBy } from '@naturalcycles/js-lib'
 import { readableToArray } from '@naturalcycles/nodejs-lib'
 import { CommonDB } from '../common.db'
+import { DBIncrement, DBPatch } from '../db.model'
 import { DBQuery } from '../query/dbQuery'
 import { DBTransaction } from '../transaction/dbTransaction'
 import {
@@ -25,6 +26,10 @@ export interface CommonDBImplementationFeatures {
   insert?: boolean
   update?: boolean
 
+  updateByQuery?: boolean
+
+  dbIncrement?: boolean
+
   createTable?: boolean
   tableSchemas?: boolean
 
@@ -87,6 +92,8 @@ export function runCommonDBTest(
     dbQuerySelectFields = true,
     insert = true,
     update = true,
+    updateByQuery = true,
+    dbIncrement = true,
     streaming = true,
     strongConsistency = true,
     bufferSupport = true,
@@ -122,9 +129,12 @@ export function runCommonDBTest(
     // DELETE ALL initially
     test('deleteByIds test items', async () => {
       const { rows } = await db.runQuery(queryAll().select(['id']))
-      await db.deleteByIds(
-        TEST_TABLE,
-        rows.map(i => i.id),
+      await db.runQuery(
+        queryAll().filter(
+          'id',
+          'in',
+          rows.map(i => i.id),
+        ),
       )
     })
 
@@ -138,17 +148,17 @@ export function runCommonDBTest(
 
   // GET empty
   test('getByIds(item1.id) should return empty', async () => {
-    const [item1Loaded] = await db.getByIds<TestItemDBM>(TEST_TABLE, [item1.id])
+    const [item1Loaded] = (await db.runQuery(queryAll().filterEq('id', item1.id))).rows
     // console.log(a)
     expect(item1Loaded).toBeUndefined()
   })
 
   test('getByIds([]) should return []', async () => {
-    expect(await db.getByIds(TEST_TABLE, [])).toEqual([])
+    expect((await db.runQuery(queryAll().filter('id', 'in', []))).rows).toEqual([])
   })
 
   test('getByIds(...) should return empty', async () => {
-    expect(await db.getByIds(TEST_TABLE, ['abc', 'abcd'])).toEqual([])
+    expect((await db.runQuery(queryAll().filter('id', 'in', ['abc', 'abcd']))).rows).toEqual([])
   })
 
   // SAVE
@@ -160,7 +170,7 @@ export function runCommonDBTest(
       }
       deepFreeze(item3)
       await db.saveBatch(TEST_TABLE, [item3])
-      const item3Loaded = (await db.getByIds<TestItemDBM>(TEST_TABLE, [item3.id]))[0]!
+      const item3Loaded = (await db.runQuery(queryAll().filterEq('id', item3.id))).rows[0]!
       expectMatch([item3], [item3Loaded], quirks)
       expect(item3Loaded.k2).toBeNull()
     })
@@ -177,7 +187,7 @@ export function runCommonDBTest(
       delete expected.k2
 
       await db.saveBatch(TEST_TABLE, [item3])
-      const item3Loaded = (await db.getByIds<TestItemDBM>(TEST_TABLE, [item3.id]))[0]!
+      const item3Loaded = (await db.runQuery(queryAll().filterEq('id', item3.id))).rows[0]!
       expectMatch([expected], [item3Loaded], quirks)
       expect(item3Loaded.k2).toBeUndefined()
       expect(Object.keys(item3Loaded)).not.toContain('k2')
@@ -212,8 +222,14 @@ export function runCommonDBTest(
 
   // GET not empty
   test('getByIds all items', async () => {
-    const rows = await db.getByIds<TestItemDBM>(TEST_TABLE, items.map(i => i.id).concat('abcd'))
-    expectMatch(items, rows, quirks)
+    const rows = (
+      await db.runQuery(queryAll().filter('id', 'in', items.map(i => i.id).concat('abcd')))
+    ).rows
+    expectMatch(
+      items,
+      _sortBy(rows, r => r.id),
+      quirks,
+    )
   })
 
   // QUERY
@@ -333,8 +349,8 @@ export function runCommonDBTest(
         b1,
       }
       await db.saveBatch(TEST_TABLE, [item])
-      const [loaded] = await db.getByIds<TestItemDBM>(TEST_TABLE, [item.id])
-      const b1Loaded = loaded!.b1!
+      const loaded = (await db.runQuery(queryAll().filterEq('id', item.id))).rows[0]!
+      const b1Loaded = loaded.b1!
       // console.log({
       //   b11: typeof b1,
       //   b12: typeof b1Loaded,
@@ -383,14 +399,61 @@ export function runCommonDBTest(
     })
   }
 
+  if (updateByQuery) {
+    test('updateByQuery simple', async () => {
+      // cleanup, reset initial data
+      await db.deleteByQuery(queryAll())
+      await db.saveBatch(TEST_TABLE, items)
+
+      const patch: DBPatch<TestItemDBM> = {
+        k3: 5,
+        k2: 'abc',
+      }
+
+      await db.updateByQuery(DBQuery.create<TestItemDBM>(TEST_TABLE).filterEq('even', true), patch)
+
+      const { rows } = await db.runQuery(queryAll())
+      const expected = items.map(r => {
+        if (r.even) {
+          return { ...r, ...patch }
+        }
+        return r
+      })
+      expectMatch(expected, rows, quirks)
+    })
+
+    if (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',
+        }
+
+        await db.updateByQuery(
+          DBQuery.create<TestItemDBM>(TEST_TABLE).filterEq('even', true),
+          patch,
+        )
+
+        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)
+      })
+    }
+  }
+
   if (querying) {
     test('cleanup', async () => {
       // CLEAN UP
-      const { rows } = await db.runQuery(queryAll().select(['id']))
-      await db.deleteByIds(
-        TEST_TABLE,
-        rows.map(i => i.id),
-      )
+      await db.deleteByQuery(queryAll())
     })
   }
 }

package/src/transaction/dbTransaction.util.ts

@@ -1,5 +1,6 @@
 import type { CommonDB } from '../common.db'
 import { CommonDBSaveOptions, DBOperation } from '../db.model'
+import { DBQuery } from '../query/dbQuery'
 import { DBTransaction } from './dbTransaction'
 
 /**
@@ -80,7 +81,10 @@ export async function commitDBTransactionSimple(
     if (op.type === 'saveBatch') {
       await db.saveBatch(op.table, op.rows, { ...op.opt, ...opt })
     } else if (op.type === 'deleteByIds') {
-      await db.deleteByIds(op.table, op.ids, { ...op.opt, ...opt })
+      await db.deleteByQuery(DBQuery.create(op.table).filter('id', 'in', op.ids), {
+        ...op.opt,
+        ...opt,
+      })
     } else {
       throw new Error(`DBOperation not supported: ${(op as any).type}`)
     }