@naturalcycles/db-lib 8.46.1 → 8.47.0

package/dist/adapter/cachedb/cache.db.d.ts

@@ -3,7 +3,7 @@ import { Readable } from 'node:stream';
 import { JsonSchemaObject, JsonSchemaRootObject, ObjectWithId } from '@naturalcycles/js-lib';
 import { BaseCommonDB } from '../../base.common.db';
 import { CommonDB } from '../../common.db';
-import { CommonDBOptions, RunQueryResult } from '../../db.model';
+import { CommonDBOptions, DBPatch, RunQueryResult } from '../../db.model';
 import { DBQuery } from '../../query/dbQuery';
 import { DBTransaction } from '../../transaction/dbTransaction';
 import { CacheDBCfg, CacheDBCreateOptions, CacheDBOptions, CacheDBSaveOptions, CacheDBStreamOptions } from './cache.db.model';
@@ -30,5 +30,6 @@ export declare class CacheDB extends BaseCommonDB implements CommonDB {
     runQueryCount<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CacheDBOptions): Promise<number>;
     streamQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CacheDBStreamOptions): Readable;
     deleteByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CacheDBOptions): Promise<number>;
+    updateByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, patch: DBPatch<ROW>, opt?: CacheDBOptions): Promise<number>;
     commitTransaction(tx: DBTransaction, opt?: CommonDBOptions): Promise<void>;
 }

package/dist/adapter/cachedb/cache.db.js

@@ -195,6 +195,18 @@ class CacheDB extends base_common_db_1.BaseCommonDB {
         }
         return deletedIds;
     }
+    async updateByQuery(q, patch, opt = {}) {
+        let updated;
+        if (!opt.onlyCache && !this.cfg.onlyCache) {
+            updated = await this.cfg.downstreamDB.updateByQuery(q, patch, opt);
+        }
+        if (!opt.skipCache && !this.cfg.skipCache) {
+            const cacheResult = this.cfg.cacheDB.updateByQuery(q, patch, opt);
+            if (this.cfg.awaitCache)
+                updated ??= await cacheResult;
+        }
+        return updated || 0;
+    }
     async commitTransaction(tx, opt) {
         await this.cfg.downstreamDB.commitTransaction(tx, opt);
         await this.cfg.cacheDB.commitTransaction(tx, opt);

package/dist/adapter/inmemory/inMemory.db.d.ts

@@ -1,6 +1,6 @@
 import { JsonSchemaObject, StringMap, JsonSchemaRootObject, ObjectWithId, CommonLogger } from '@naturalcycles/js-lib';
 import { ReadableTyped } from '@naturalcycles/nodejs-lib';
-import { CommonDB, DBTransaction } from '../..';
+import { CommonDB, DBPatch, DBTransaction } from '../..';
 import { CommonDBCreateOptions, CommonDBOptions, CommonDBSaveOptions, RunQueryResult } from '../../db.model';
 import { DBQuery } from '../../query/dbQuery';
 export interface InMemoryDBCfg {
@@ -56,6 +56,7 @@ export declare class InMemoryDB implements CommonDB {
     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>;
+    updateByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, patch: DBPatch<ROW>): Promise<number>;
     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?: CommonDBOptions): ReadableTyped<ROW>;

package/dist/adapter/inmemory/inMemory.db.js

@@ -94,14 +94,14 @@ class InMemoryDB {
     async deleteByIds(_table, ids, _opt) {
         const table = this.cfg.tablesPrefix + _table;
         this.data[table] ||= {};
-        return ids
-            .map(id => {
-            const exists = !!this.data[table][id];
+        let count = 0;
+        ids.forEach(id => {
+            if (!this.data[table][id])
+                return;
             delete this.data[table][id];
-            if (exists)
-                return id;
-        })
-            .filter(Boolean).length;
+            count++;
+        });
+        return count;
     }
     async deleteByQuery(q, _opt) {
         const table = this.cfg.tablesPrefix + q.table;
@@ -109,6 +109,24 @@ class InMemoryDB {
         const ids = rows.map(r => r.id);
         return await this.deleteByIds(q.table, ids);
     }
+    async updateByQuery(q, patch) {
+        const patchEntries = Object.entries(patch);
+        if (!patchEntries.length)
+            return 0;
+        const table = this.cfg.tablesPrefix + q.table;
+        const rows = (0, __1.queryInMemory)(q, Object.values(this.data[table] || {}));
+        rows.forEach((row) => {
+            patchEntries.forEach(([k, v]) => {
+                if (v instanceof __1.DBIncrement) {
+                    row[k] = (row[k] || 0) + v.amount;
+                }
+                else {
+                    row[k] = v;
+                }
+            });
+        });
+        return rows.length;
+    }
     async runQuery(q, _opt) {
         const table = this.cfg.tablesPrefix + q.table;
         return { rows: (0, __1.queryInMemory)(q, Object.values(this.data[table] || {})) };
@@ -147,9 +165,7 @@ class InMemoryDB {
      * Flushes all tables (all namespaces) at once.
      */
     async flushToDisk() {
-        if (!this.cfg.persistenceEnabled) {
-            throw new Error('flushToDisk() called but persistenceEnabled=false');
-        }
+        (0, js_lib_1._assert)(this.cfg.persistenceEnabled, 'flushToDisk() called but persistenceEnabled=false');
         const { persistentStoragePath, persistZip } = this.cfg;
         const started = Date.now();
         await fs.emptyDir(persistentStoragePath);
@@ -175,9 +191,7 @@ class InMemoryDB {
      * Restores all tables (all namespaces) at once.
      */
     async restoreFromDisk() {
-        if (!this.cfg.persistentStoragePath) {
-            throw new Error('restoreFromDisk() called but persistenceEnabled=false');
-        }
+        (0, js_lib_1._assert)(this.cfg.persistenceEnabled, 'restoreFromDisk() called but persistenceEnabled=false');
         const { persistentStoragePath } = this.cfg;
         const started = Date.now();
         await fs.ensureDir(persistentStoragePath);

package/dist/adapter/inmemory/queryInMemory.js

@@ -17,6 +17,10 @@ const FILTER_FNS = {
 // Important: q.table is not used in this function, so tablesPrefix is not needed.
 // But should be careful here..
 function queryInMemory(q, rows = []) {
+    // .ids
+    if (q._ids?.length) {
+        rows = rows.filter(r => q._ids.includes(r.id));
+    }
     // .filter
     // eslint-disable-next-line unicorn/no-array-reduce
     rows = q._filters.reduce((rows, filter) => {

package/dist/base.common.db.d.ts

@@ -1,7 +1,7 @@
 import { JsonSchemaObject, JsonSchemaRootObject, ObjectWithId } from '@naturalcycles/js-lib';
 import { ReadableTyped } from '@naturalcycles/nodejs-lib';
 import { CommonDB } from './common.db';
-import { CommonDBOptions, CommonDBSaveOptions, RunQueryResult } from './db.model';
+import { CommonDBOptions, CommonDBSaveOptions, DBPatch, RunQueryResult } from './db.model';
 import { DBQuery } from './query/dbQuery';
 import { DBTransaction } from './transaction/dbTransaction';
 /**
@@ -12,14 +12,15 @@ export declare class BaseCommonDB implements CommonDB {
     ping(): Promise<void>;
     getTables(): Promise<string[]>;
     getTableSchema<ROW extends ObjectWithId>(table: string): Promise<JsonSchemaRootObject<ROW>>;
-    createTable<ROW extends ObjectWithId>(_table: string, _schema: JsonSchemaObject<ROW>): Promise<void>;
-    deleteByIds<ROW extends ObjectWithId>(_table: string, _ids: ROW['id'][]): Promise<number>;
-    deleteByQuery<ROW extends ObjectWithId>(_q: DBQuery<ROW>): Promise<number>;
-    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 Partial<ObjectWithId>>(_table: string, _rows: ROW[], _opt?: CommonDBSaveOptions<ROW>): Promise<void>;
-    streamQuery<ROW extends ObjectWithId>(_q: DBQuery<ROW>): ReadableTyped<ROW>;
+    createTable<ROW extends ObjectWithId>(table: string, schema: JsonSchemaObject<ROW>): Promise<void>;
+    deleteByIds<ROW extends ObjectWithId>(table: string, ids: ROW['id'][]): Promise<number>;
+    deleteByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>): Promise<number>;
+    updateByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, patch: DBPatch<ROW>, opt?: CommonDBOptions): Promise<number>;
+    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 Partial<ObjectWithId>>(table: string, rows: ROW[], opt?: CommonDBSaveOptions<ROW>): Promise<void>;
+    streamQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>): ReadableTyped<ROW>;
     /**
      * Naive implementation.
      * Doesn't support rollback on error, hence doesn't pass dbTest.

package/dist/base.common.db.js

@@ -1,45 +1,47 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseCommonDB = void 0;
-const node_stream_1 = require("node:stream");
-const dbTransaction_util_1 = require("./transaction/dbTransaction.util");
+/* eslint-disable unused-imports/no-unused-vars */
 /**
  * No-op implementation of CommonDB interface.
  * To be extended by actual implementations.
  */
 class BaseCommonDB {
-    async ping() { }
+    async ping() {
+        throw new Error('ping is not implemented');
+    }
     async getTables() {
-        return [];
+        throw new Error('getTables is not implemented');
     }
     async getTableSchema(table) {
-        return {
-            $id: `${table}.schema.json`,
-            type: 'object',
-            additionalProperties: true,
-            properties: {},
-            required: [],
-        };
+        throw new Error('getTableSchema is not implemented');
+    }
+    async createTable(table, schema) {
+        throw new Error('createTable is not implemented');
+    }
+    async deleteByIds(table, ids) {
+        throw new Error('deleteByIds is not implemented');
+    }
+    async deleteByQuery(q) {
+        throw new Error('deleteByQuery is not implemented');
     }
-    async createTable(_table, _schema) { }
-    async deleteByIds(_table, _ids) {
-        return 0;
+    async updateByQuery(q, patch, opt) {
+        throw new Error('updateByQuery is not implemented');
     }
-    async deleteByQuery(_q) {
-        return 0;
+    async getByIds(table, ids) {
+        throw new Error('getByIds is not implemented');
     }
-    async getByIds(_table, _ids) {
-        return [];
+    async runQuery(q) {
+        throw new Error('runQuery is not implemented');
     }
-    async runQuery(_q) {
-        return { rows: [] };
+    async runQueryCount(q) {
+        throw new Error('runQueryCount is not implemented');
     }
-    async runQueryCount(_q) {
-        return 0;
+    async saveBatch(table, rows, opt) {
+        throw new Error('saveBatch is not implemented');
     }
-    async saveBatch(_table, _rows, _opt) { }
-    streamQuery(_q) {
-        return node_stream_1.Readable.from([]);
+    streamQuery(q) {
+        throw new Error('streamQuery is not implemented');
     }
     /**
      * Naive implementation.
@@ -47,7 +49,7 @@ class BaseCommonDB {
      * To be extended.
      */
     async commitTransaction(tx, opt) {
-        await (0, dbTransaction_util_1.commitDBTransactionSimple)(this, tx, opt);
+        throw new Error('commitTransaction is not implemented');
     }
 }
 exports.BaseCommonDB = BaseCommonDB;

package/dist/common.db.d.ts

@@ -1,6 +1,6 @@
 import { JsonSchemaObject, JsonSchemaRootObject, ObjectWithId } from '@naturalcycles/js-lib';
 import { ReadableTyped } from '@naturalcycles/nodejs-lib';
-import { CommonDBCreateOptions, CommonDBOptions, CommonDBSaveOptions, CommonDBStreamOptions, RunQueryResult } from './db.model';
+import { CommonDBCreateOptions, CommonDBOptions, CommonDBSaveOptions, CommonDBStreamOptions, DBPatch, RunQueryResult } from './db.model';
 import { DBQuery } from './query/dbQuery';
 import { DBTransaction } from './transaction/dbTransaction';
 export interface CommonDB {
@@ -48,6 +48,25 @@ export interface CommonDB {
      */
     deleteByIds<ROW extends ObjectWithId>(table: string, ids: ROW['id'][], opt?: CommonDBOptions): Promise<number>;
     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>;
     /**
      * Should be implemented as a Transaction (best effort), which means that
      * either ALL or NONE of the operations should be applied.

package/dist/commondao/common.dao.d.ts

@@ -1,6 +1,6 @@
 import { AnyObject, AsyncMapper, JsonSchemaObject, JsonSchemaRootObject, ObjectWithId, Saved, Unsaved } from '@naturalcycles/js-lib';
 import { AjvSchema, ObjectSchemaTyped, ReadableTyped } from '@naturalcycles/nodejs-lib';
-import { DBDeleteByIdsOperation, DBModelType, DBOperation, DBSaveBatchOperation, RunQueryResult } from '../db.model';
+import { DBDeleteByIdsOperation, DBModelType, DBOperation, DBPatch, DBSaveBatchOperation, RunQueryResult } from '../db.model';
 import { DBQuery, RunnableDBQuery } from '../query/dbQuery';
 import { CommonDaoCfg, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoSaveOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions } from './common.dao.model';
 /**
@@ -120,6 +120,9 @@ export declare class CommonDao<BM extends Partial<ObjectWithId<ID>>, DBM extends
     deleteByQuery(q: DBQuery<DBM>, opt?: CommonDaoStreamForEachOptions<DBM> & {
         stream?: boolean;
     }): Promise<number>;
+    updateById(id: ID, patch: DBPatch<DBM>, opt?: CommonDaoOptions): Promise<number>;
+    updateByIds(ids: ID[], patch: DBPatch<DBM>, opt?: CommonDaoOptions): Promise<number>;
+    updateByQuery(q: DBQuery<DBM>, patch: DBPatch<DBM>, opt?: CommonDaoOptions): Promise<number>;
     dbmToBM(_dbm: undefined, opt?: CommonDaoOptions): Promise<undefined>;
     dbmToBM(_dbm?: DBM, opt?: CommonDaoOptions): Promise<Saved<BM>>;
     dbmsToBM(dbms: DBM[], opt?: CommonDaoOptions): Promise<Saved<BM>[]>;

package/dist/commondao/common.dao.js

@@ -711,6 +711,22 @@ class CommonDao {
         this.logSaveResult(started, op, q.table);
         return deleted;
     }
+    async updateById(id, patch, opt = {}) {
+        return await this.updateByQuery(this.query().byId(id), patch, opt);
+    }
+    async updateByIds(ids, patch, opt = {}) {
+        return await this.updateByQuery(this.query().byIds(ids), patch, opt);
+    }
+    async updateByQuery(q, patch, opt = {}) {
+        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;
+    }
     async dbmToBM(_dbm, opt = {}) {
         if (!_dbm)
             return;

package/dist/db.model.d.ts

@@ -62,3 +62,16 @@ export declare 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 declare class DBIncrement {
+    amount: number;
+    private constructor();
+    static of(amount: number): DBIncrement;
+}
+export type DBPatch<ROW extends Partial<ObjectWithId>> = Partial<Record<keyof ROW, ROW[keyof ROW] | DBIncrement>>;

package/dist/db.model.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DBModelType = exports.DBRelation = void 0;
+exports.DBIncrement = exports.DBModelType = exports.DBRelation = void 0;
 var DBRelation;
 (function (DBRelation) {
     DBRelation["ONE_TO_ONE"] = "ONE_TO_ONE";
@@ -12,3 +12,19 @@ var DBModelType;
     DBModelType["BM"] = "BM";
     DBModelType["TM"] = "TM";
 })(DBModelType = exports.DBModelType || (exports.DBModelType = {}));
+/**
+ * Allows to construct a query similar to:
+ *
+ * UPDATE table SET A = A + 1
+ *
+ * In this case DBIncement.of(1) will be needed.
+ */
+class DBIncrement {
+    constructor(amount) {
+        this.amount = amount;
+    }
+    static of(amount) {
+        return new DBIncrement(amount);
+    }
+}
+exports.DBIncrement = DBIncrement;

package/dist/query/dbQuery.d.ts

@@ -1,6 +1,6 @@
 import { AnyObjectWithId, ObjectWithId, AsyncMapper, Saved, AnyObject } 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';
 /**
@@ -66,6 +66,7 @@ export declare class DBQuery<ROW extends ObjectWithId = AnyObjectWithId> {
     _selectedFieldNames?: (keyof ROW)[];
     _groupByFieldNames?: (keyof ROW)[];
     _distinct: boolean;
+    _ids?: ROW['id'][];
     filter(name: keyof ROW, op: DBQueryFilterOperator, val: any): this;
     filterEq(name: keyof ROW, val: any): this;
     limit(limit: number): this;
@@ -76,6 +77,20 @@ export declare class DBQuery<ROW extends ObjectWithId = AnyObjectWithId> {
     distinct(distinct?: boolean): this;
     startCursor(startCursor?: string): this;
     endCursor(endCursor?: string): this;
+    /**
+     * Allows to query by ids (one or many).
+     * Similar to:
+     * SELECT * FROM table where id in (a, b, c)
+     * or (if only 1 id is passed)
+     * SELECT * FROM table where id = a
+     */
+    byIds(ids: ROW['id'][]): this;
+    /**
+     * Allows to query by id.
+     * Similar to:
+     * SELECT * FROM table where id = a
+     */
+    byId(id: ROW['id']): this;
     clone(): DBQuery<ROW>;
     pretty(): string;
     prettyConditions(): string[];
@@ -97,6 +112,7 @@ export declare class RunnableDBQuery<BM extends Partial<ObjectWithId<ID>>, DBM e
     runQueryExtendedAsDBM(opt?: CommonDaoOptions): Promise<RunQueryResult<DBM>>;
     runQueryExtendedAsTM(opt?: CommonDaoOptions): Promise<RunQueryResult<TM>>;
     runQueryCount(opt?: CommonDaoOptions): Promise<number>;
+    updateByQuery(patch: DBPatch<DBM>, opt?: CommonDaoOptions): Promise<number>;
     streamQueryForEach(mapper: AsyncMapper<Saved<BM>, void>, opt?: CommonDaoStreamForEachOptions<Saved<BM>>): Promise<void>;
     streamQueryAsDBMForEach(mapper: AsyncMapper<DBM, void>, opt?: CommonDaoStreamForEachOptions<DBM>): Promise<void>;
     streamQuery(opt?: CommonDaoStreamOptions): ReadableTyped<Saved<BM>>;

package/dist/query/dbQuery.js

@@ -85,8 +85,28 @@ class DBQuery {
         this._endCursor = endCursor;
         return this;
     }
+    /**
+     * Allows to query by ids (one or many).
+     * Similar to:
+     * SELECT * FROM table where id in (a, b, c)
+     * or (if only 1 id is passed)
+     * SELECT * FROM table where id = a
+     */
+    byIds(ids) {
+        this._ids = ids;
+        return this;
+    }
+    /**
+     * Allows to query by id.
+     * Similar to:
+     * SELECT * FROM table where id = a
+     */
+    byId(id) {
+        this._ids = [id];
+        return this;
+    }
     clone() {
-        return Object.assign(new DBQuery(this.table), {
+        return (0, js_lib_1._objectAssign)(new DBQuery(this.table), {
             _filters: [...this._filters],
             _limitValue: this._limitValue,
             _offsetValue: this._offsetValue,
@@ -96,6 +116,7 @@ class DBQuery {
             _distinct: this._distinct,
             _startCursor: this._startCursor,
             _endCursor: this._endCursor,
+            _ids: this._ids,
         });
     }
     pretty() {
@@ -109,6 +130,14 @@ class DBQuery {
         if (this._selectedFieldNames) {
             tokens.push(`select${this._distinct ? ' distinct' : ''}(${this._selectedFieldNames.join(',')})`);
         }
+        if (this._ids?.length) {
+            if (this._ids.length === 1) {
+                tokens.push(`id=${this._ids[0]}`);
+            }
+            else {
+                tokens.push(`ids in (${this._ids.join(',')})`);
+            }
+        }
         tokens.push(...this._filters.map(f => `${f.name}${f.op}${f.val}`), ...this._orders.map(o => `order by ${o.name}${o.descending ? ' desc' : ''}`));
         if (this._groupByFieldNames) {
             tokens.push(`groupBy(${this._groupByFieldNames.join(',')})`);
@@ -164,6 +193,9 @@ class RunnableDBQuery extends DBQuery {
     async runQueryCount(opt) {
         return await this.dao.runQueryCount(this, opt);
     }
+    async updateByQuery(patch, opt) {
+        return await this.dao.updateByQuery(this, patch, opt);
+    }
     async streamQueryForEach(mapper, opt) {
         await this.dao.streamQueryForEach(this, mapper, opt);
     }

package/dist/testing/dbTest.d.ts

@@ -10,6 +10,8 @@ export interface CommonDBImplementationFeatures {
     dbQuerySelectFields?: boolean;
     insert?: boolean;
     update?: boolean;
+    updateByQuery?: boolean;
+    dbIncrement?: boolean;
     createTable?: boolean;
     tableSchemas?: boolean;
     /**

package/dist/testing/dbTest.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.expectMatch = exports.runCommonDBTest = void 0;
 const js_lib_1 = require("@naturalcycles/js-lib");
 const nodejs_lib_1 = require("@naturalcycles/nodejs-lib");
+const db_model_1 = require("../db.model");
 const dbQuery_1 = require("../query/dbQuery");
 const dbTransaction_1 = require("../transaction/dbTransaction");
 const test_model_1 = require("./test.model");
@@ -13,7 +14,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, insert = true, update = true, streaming = true, strongConsistency = true, bufferSupport = true, nullValues = true, documentDB = true, transactions = true, } = features;
+    dbQueryOrder = true, dbQuerySelectFields = true, insert = true, update = true, updateByQuery = true, dbIncrement = true, streaming = true, strongConsistency = true, bufferSupport = true, nullValues = true, documentDB = true, transactions = true, } = features;
     // const {
     // allowExtraPropertiesInResponse,
     // allowBooleansAsUndefined,
@@ -245,6 +246,47 @@ function runCommonDBTest(db, features = {}, quirks = {}) {
             expectMatch(expected, rows, quirks);
         });
     }
+    if (updateByQuery) {
+        // todo: query by ids (same as getByIds)
+        test('updateByQuery simple', async () => {
+            // cleanup, reset initial data
+            await db.deleteByQuery(queryAll());
+            await db.saveBatch(test_model_1.TEST_TABLE, items);
+            const patch = {
+                k3: 5,
+                k2: 'abc',
+            };
+            await db.updateByQuery(dbQuery_1.DBQuery.create(test_model_1.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_model_1.TEST_TABLE, items);
+                const patch = {
+                    k3: db_model_1.DBIncrement.of(1),
+                    k2: 'abcd',
+                };
+                await db.updateByQuery(dbQuery_1.DBQuery.create(test_model_1.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

package/package.json

@@ -41,7 +41,7 @@
   "engines": {
     "node": ">=14.15"
   },
-  "version": "8.46.1",
+  "version": "8.47.0",
   "description": "Lowest Common Denominator API to supported Databases",
   "keywords": [
     "db",

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

@@ -7,7 +7,7 @@ import {
 } from '@naturalcycles/js-lib'
 import { BaseCommonDB } from '../../base.common.db'
 import { CommonDB } from '../../common.db'
-import { CommonDBOptions, RunQueryResult } from '../../db.model'
+import { CommonDBOptions, DBPatch, RunQueryResult } from '../../db.model'
 import { DBQuery } from '../../query/dbQuery'
 import { DBTransaction } from '../../transaction/dbTransaction'
 import {
@@ -294,6 +294,25 @@ export class CacheDB extends BaseCommonDB implements CommonDB {
     return deletedIds
   }
 
+  override async updateByQuery<ROW extends ObjectWithId>(
+    q: DBQuery<ROW>,
+    patch: DBPatch<ROW>,
+    opt: CacheDBOptions = {},
+  ): Promise<number> {
+    let updated: number | undefined
+
+    if (!opt.onlyCache && !this.cfg.onlyCache) {
+      updated = await this.cfg.downstreamDB.updateByQuery(q, patch, opt)
+    }
+
+    if (!opt.skipCache && !this.cfg.skipCache) {
+      const cacheResult = this.cfg.cacheDB.updateByQuery(q, patch, opt)
+      if (this.cfg.awaitCache) updated ??= await cacheResult
+    }
+
+    return updated || 0
+  }
+
   override async commitTransaction(tx: DBTransaction, opt?: CommonDBOptions): Promise<void> {
     await this.cfg.downstreamDB.commitTransaction(tx, opt)
     await this.cfg.cacheDB.commitTransaction(tx, opt)

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

@@ -13,6 +13,7 @@ import {
   _stringMapValues,
   CommonLogger,
   _deepCopy,
+  _assert,
 } from '@naturalcycles/js-lib'
 import {
   bufferReviver,
@@ -25,7 +26,7 @@ import {
 } from '@naturalcycles/nodejs-lib'
 import { dimGrey, yellow } from '@naturalcycles/nodejs-lib/dist/colors'
 import * as fs from 'fs-extra'
-import { CommonDB, DBTransaction, queryInMemory } from '../..'
+import { CommonDB, DBIncrement, DBPatch, DBTransaction, queryInMemory } from '../..'
 import {
   CommonDBCreateOptions,
   CommonDBOptions,
@@ -149,7 +150,7 @@ export class InMemoryDB implements CommonDB {
   ): Promise<ROW[]> {
     const table = this.cfg.tablesPrefix + _table
     this.data[table] ||= {}
-    return ids.map(id => this.data[table]![id]).filter(Boolean) as ROW[]
+    return ids.map(id => this.data[table]![id] as ROW).filter(Boolean)
   }
 
   async saveBatch<ROW extends Partial<ObjectWithId>>(
@@ -190,14 +191,13 @@ export class InMemoryDB implements CommonDB {
   ): Promise<number> {
     const table = this.cfg.tablesPrefix + _table
     this.data[table] ||= {}
-
-    return ids
-      .map(id => {
-        const exists = !!this.data[table]![id]
-        delete this.data[table]![id]
-        if (exists) return id
-      })
-      .filter(Boolean).length
+    let count = 0
+    ids.forEach(id => {
+      if (!this.data[table]![id]) return
+      delete this.data[table]![id]
+      count++
+    })
+    return count
   }
 
   async deleteByQuery<ROW extends ObjectWithId>(
@@ -210,6 +210,28 @@ export class InMemoryDB implements CommonDB {
     return await this.deleteByIds(q.table, ids)
   }
 
+  async updateByQuery<ROW extends ObjectWithId>(
+    q: DBQuery<ROW>,
+    patch: DBPatch<ROW>,
+  ): Promise<number> {
+    const patchEntries = Object.entries(patch)
+    if (!patchEntries.length) 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
+        }
+      })
+    })
+
+    return rows.length
+  }
+
   async runQuery<ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
     _opt?: CommonDBOptions,
@@ -260,9 +282,7 @@ export class InMemoryDB implements CommonDB {
    * Flushes all tables (all namespaces) at once.
    */
   async flushToDisk(): Promise<void> {
-    if (!this.cfg.persistenceEnabled) {
-      throw new Error('flushToDisk() called but persistenceEnabled=false')
-    }
+    _assert(this.cfg.persistenceEnabled, 'flushToDisk() called but persistenceEnabled=false')
     const { persistentStoragePath, persistZip } = this.cfg
 
     const started = Date.now()
@@ -297,9 +317,7 @@ export class InMemoryDB implements CommonDB {
    * Restores all tables (all namespaces) at once.
    */
   async restoreFromDisk(): Promise<void> {
-    if (!this.cfg.persistentStoragePath) {
-      throw new Error('restoreFromDisk() called but persistenceEnabled=false')
-    }
+    _assert(this.cfg.persistenceEnabled, 'restoreFromDisk() called but persistenceEnabled=false')
     const { persistentStoragePath } = this.cfg
 
     const started = Date.now()

package/src/adapter/inmemory/queryInMemory.ts

@@ -19,6 +19,11 @@ const FILTER_FNS: Record<DBQueryFilterOperator, FilterFn> = {
 // Important: q.table is not used in this function, so tablesPrefix is not needed.
 // But should be careful here..
 export function queryInMemory<ROW extends ObjectWithId>(q: DBQuery<ROW>, rows: ROW[] = []): ROW[] {
+  // .ids
+  if (q._ids?.length) {
+    rows = rows.filter(r => q._ids!.includes(r.id))
+  }
+
   // .filter
   // eslint-disable-next-line unicorn/no-array-reduce
   rows = q._filters.reduce((rows, filter) => {

package/src/base.common.db.ts

@@ -1,68 +1,76 @@
-import { Readable } from 'node:stream'
 import { JsonSchemaObject, JsonSchemaRootObject, ObjectWithId } from '@naturalcycles/js-lib'
 import { ReadableTyped } from '@naturalcycles/nodejs-lib'
 import { CommonDB } from './common.db'
-import { CommonDBOptions, CommonDBSaveOptions, RunQueryResult } from './db.model'
+import { CommonDBOptions, CommonDBSaveOptions, DBPatch, RunQueryResult } from './db.model'
 import { DBQuery } from './query/dbQuery'
 import { DBTransaction } from './transaction/dbTransaction'
-import { commitDBTransactionSimple } from './transaction/dbTransaction.util'
+
+/* eslint-disable unused-imports/no-unused-vars */
 
 /**
  * No-op implementation of CommonDB interface.
  * To be extended by actual implementations.
  */
 export class BaseCommonDB implements CommonDB {
-  async ping(): Promise<void> {}
+  async ping(): Promise<void> {
+    throw new Error('ping is not implemented')
+  }
 
   async getTables(): Promise<string[]> {
-    return []
+    throw new Error('getTables is not implemented')
   }
 
   async getTableSchema<ROW extends ObjectWithId>(
     table: string,
   ): Promise<JsonSchemaRootObject<ROW>> {
-    return {
-      $id: `${table}.schema.json`,
-      type: 'object',
-      additionalProperties: true,
-      properties: {} as any,
-      required: [],
-    }
+    throw new Error('getTableSchema is not implemented')
   }
 
   async createTable<ROW extends ObjectWithId>(
-    _table: string,
-    _schema: JsonSchemaObject<ROW>,
-  ): Promise<void> {}
+    table: string,
+    schema: JsonSchemaObject<ROW>,
+  ): Promise<void> {
+    throw new Error('createTable is not implemented')
+  }
 
-  async deleteByIds<ROW extends ObjectWithId>(_table: string, _ids: ROW['id'][]): Promise<number> {
-    return 0
+  async deleteByIds<ROW extends ObjectWithId>(table: string, ids: ROW['id'][]): Promise<number> {
+    throw new Error('deleteByIds is not implemented')
   }
 
-  async deleteByQuery<ROW extends ObjectWithId>(_q: DBQuery<ROW>): Promise<number> {
-    return 0
+  async deleteByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>): Promise<number> {
+    throw new Error('deleteByQuery is not implemented')
   }
 
-  async getByIds<ROW extends ObjectWithId>(_table: string, _ids: ROW['id'][]): Promise<ROW[]> {
-    return []
+  async updateByQuery<ROW extends ObjectWithId>(
+    q: DBQuery<ROW>,
+    patch: DBPatch<ROW>,
+    opt?: CommonDBOptions,
+  ): Promise<number> {
+    throw new Error('updateByQuery is not implemented')
   }
 
-  async runQuery<ROW extends ObjectWithId>(_q: DBQuery<ROW>): Promise<RunQueryResult<ROW>> {
-    return { rows: [] }
+  async getByIds<ROW extends ObjectWithId>(table: string, ids: ROW['id'][]): Promise<ROW[]> {
+    throw new Error('getByIds is not implemented')
   }
 
-  async runQueryCount<ROW extends ObjectWithId>(_q: DBQuery<ROW>): Promise<number> {
-    return 0
+  async runQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>): Promise<RunQueryResult<ROW>> {
+    throw new Error('runQuery is not implemented')
+  }
+
+  async runQueryCount<ROW extends ObjectWithId>(q: DBQuery<ROW>): Promise<number> {
+    throw new Error('runQueryCount is not implemented')
   }
 
   async saveBatch<ROW extends Partial<ObjectWithId>>(
-    _table: string,
-    _rows: ROW[],
-    _opt?: CommonDBSaveOptions<ROW>,
-  ): Promise<void> {}
+    table: string,
+    rows: ROW[],
+    opt?: CommonDBSaveOptions<ROW>,
+  ): Promise<void> {
+    throw new Error('saveBatch is not implemented')
+  }
 
-  streamQuery<ROW extends ObjectWithId>(_q: DBQuery<ROW>): ReadableTyped<ROW> {
-    return Readable.from([])
+  streamQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>): ReadableTyped<ROW> {
+    throw new Error('streamQuery is not implemented')
   }
 
   /**
@@ -71,6 +79,6 @@ export class BaseCommonDB implements CommonDB {
    * To be extended.
    */
   async commitTransaction(tx: DBTransaction, opt?: CommonDBOptions): Promise<void> {
-    await commitDBTransactionSimple(this, tx, opt)
+    throw new Error('commitTransaction is not implemented')
   }
 }

package/src/common.db.ts

@@ -5,6 +5,7 @@ import {
   CommonDBOptions,
   CommonDBSaveOptions,
   CommonDBStreamOptions,
+  DBPatch,
   RunQueryResult,
 } from './db.model'
 import { DBQuery } from './query/dbQuery'
@@ -92,6 +93,30 @@ export interface CommonDB {
 
   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>
+
   // 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'
@@ -934,6 +935,29 @@ export class CommonDao<
     return deleted
   }
 
+  async updateById(id: ID, patch: DBPatch<DBM>, opt: CommonDaoOptions = {}): Promise<number> {
+    return await this.updateByQuery(this.query().byId(id), patch, opt)
+  }
+
+  async updateByIds(ids: ID[], patch: DBPatch<DBM>, opt: CommonDaoOptions = {}): Promise<number> {
+    return await this.updateByQuery(this.query().byIds(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'
 
@@ -107,6 +113,7 @@ export class DBQuery<ROW extends ObjectWithId = AnyObjectWithId> {
   _selectedFieldNames?: (keyof ROW)[]
   _groupByFieldNames?: (keyof ROW)[]
   _distinct = false
+  _ids?: ROW['id'][]
 
   filter(name: keyof ROW, op: DBQueryFilterOperator, val: any): this {
     this._filters.push({ name, op, val })
@@ -161,8 +168,30 @@ export class DBQuery<ROW extends ObjectWithId = AnyObjectWithId> {
     return this
   }
 
+  /**
+   * Allows to query by ids (one or many).
+   * Similar to:
+   * SELECT * FROM table where id in (a, b, c)
+   * or (if only 1 id is passed)
+   * SELECT * FROM table where id = a
+   */
+  byIds(ids: ROW['id'][]): this {
+    this._ids = ids
+    return this
+  }
+
+  /**
+   * Allows to query by id.
+   * Similar to:
+   * SELECT * FROM table where id = a
+   */
+  byId(id: ROW['id']): this {
+    this._ids = [id]
+    return this
+  }
+
   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,
@@ -172,6 +201,7 @@ export class DBQuery<ROW extends ObjectWithId = AnyObjectWithId> {
       _distinct: this._distinct,
       _startCursor: this._startCursor,
       _endCursor: this._endCursor,
+      _ids: this._ids,
     })
   }
 
@@ -192,6 +222,14 @@ export class DBQuery<ROW extends ObjectWithId = AnyObjectWithId> {
       )
     }
 
+    if (this._ids?.length) {
+      if (this._ids.length === 1) {
+        tokens.push(`id=${this._ids[0]}`)
+      } else {
+        tokens.push(`ids in (${this._ids.join(',')})`)
+      }
+    }
+
     tokens.push(
       ...this._filters.map(f => `${f.name as string}${f.op}${f.val}`),
       ...this._orders.map(o => `order by ${o.name as string}${o.descending ? ' desc' : ''}`),
@@ -269,6 +307,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/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,
@@ -383,6 +390,58 @@ export function runCommonDBTest(
     })
   }
 
+  if (updateByQuery) {
+    // todo: query by ids (same as getByIds)
+    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