@naturalcycles/db-lib 10.17.1 → 10.18.0

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

@@ -1,12 +1,12 @@
 import type { Transform } from 'node:stream';
 import type { JsonSchemaObject, JsonSchemaRootObject } from '@naturalcycles/js-lib/json-schema';
 import type { CommonLogger } from '@naturalcycles/js-lib/log';
-import type { AsyncIndexedMapper, BaseDBEntity, StringMap, UnixTimestampMillis, Unsaved } from '@naturalcycles/js-lib/types';
+import type { AsyncIndexedMapper, BaseDBEntity, NonNegativeInteger, StringMap, UnixTimestampMillis, Unsaved } from '@naturalcycles/js-lib/types';
 import { type ReadableTyped } from '@naturalcycles/nodejs-lib/stream';
 import type { CommonDBTransactionOptions, DBTransaction, RunQueryResult } from '../db.model.js';
 import type { DBQuery } from '../query/dbQuery.js';
 import { RunnableDBQuery } from '../query/dbQuery.js';
-import type { CommonDaoCfg, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoPatchByIdOptions, CommonDaoPatchOptions, CommonDaoReadOptions, CommonDaoSaveBatchOptions, CommonDaoSaveOptions, CommonDaoStreamDeleteOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions, CommonDaoStreamSaveOptions } from './common.dao.model.js';
+import type { CommonDaoCfg, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoPatchByIdOptions, CommonDaoPatchOptions, CommonDaoReadOptions, CommonDaoSaveBatchOptions, CommonDaoSaveOptions, CommonDaoStreamDeleteOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions, CommonDaoStreamSaveOptions, DaoWithId, DaoWithIds, DaoWithRows } from './common.dao.model.js';
 /**
  * Lowest common denominator API between supported Databases.
  *
@@ -167,6 +167,22 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
      * Proxy to this.cfg.db.ping
      */
     ping(): Promise<void>;
+    id(id: string): DaoWithId;
+    ids(ids: string[]): DaoWithIds;
+    rows(rows: BM[]): DaoWithRows;
+    /**
+     * Very @experimental.
+     */
+    static multiGetById<T>(inputs: DaoWithId[], opt?: CommonDaoReadOptions): Promise<T>;
+    /**
+     * Very @experimental.
+     */
+    static multiGetByIds(inputs: DaoWithIds[], opt?: CommonDaoReadOptions): Promise<StringMap<unknown[]>>;
+    /**
+     * Very @experimental.
+     */
+    static multiDeleteByIds(inputs: DaoWithIds[], _opt?: CommonDaoOptions): Promise<NonNegativeInteger>;
+    static multiSaveBatch(inputs: DaoWithRows[], opt?: CommonDaoSaveBatchOptions<any>): Promise<void>;
     createTransaction(opt?: CommonDBTransactionOptions): Promise<CommonDaoTransaction>;
     runInTransaction<T = void>(fn: CommonDaoTransactionFn<T>, opt?: CommonDBTransactionOptions): Promise<T>;
     /**

package/dist/commondao/common.dao.js

@@ -981,6 +981,89 @@ export class CommonDao {
     async ping() {
         await this.cfg.db.ping();
     }
+    id(id) {
+        return {
+            dao: this,
+            id,
+        };
+    }
+    ids(ids) {
+        return {
+            dao: this,
+            ids,
+        };
+    }
+    rows(rows) {
+        return {
+            dao: this,
+            rows,
+        };
+    }
+    /**
+     * Very @experimental.
+     */
+    static async multiGetById(inputs, opt = {}) {
+        const inputs2 = inputs.map(input => ({
+            dao: input.dao,
+            ids: [input.id],
+        }));
+        const rowsByTable = await CommonDao.multiGetByIds(inputs2, opt);
+        const results = inputs.map(({ dao }) => {
+            const { table } = dao.cfg;
+            return rowsByTable[table]?.[0] || null;
+        });
+        return results;
+    }
+    /**
+     * Very @experimental.
+     */
+    static async multiGetByIds(inputs, opt = {}) {
+        if (!inputs.length)
+            return {};
+        const { db } = inputs[0].dao.cfg;
+        const idsByTable = {};
+        for (const { dao, ids } of inputs) {
+            const { table } = dao.cfg;
+            idsByTable[table] = ids;
+        }
+        // todo: support tx
+        const dbmsByTable = await db.multiGetByIds(idsByTable, opt);
+        const bmsByTable = {};
+        await pMap(inputs, async ({ dao }) => {
+            const { table } = dao.cfg;
+            let dbms = dbmsByTable[table] || [];
+            if (dao.cfg.hooks.afterLoad && dbms.length) {
+                dbms = (await pMap(dbms, async (dbm) => await dao.cfg.hooks.afterLoad(dbm))).filter(_isTruthy);
+            }
+            bmsByTable[table] = await dao.dbmsToBM(dbms, opt);
+        });
+        return bmsByTable;
+    }
+    /**
+     * Very @experimental.
+     */
+    static async multiDeleteByIds(inputs, _opt = {}) {
+        if (!inputs.length)
+            return 0;
+        const { db } = inputs[0].dao.cfg;
+        const idsByTable = {};
+        for (const { dao, ids } of inputs) {
+            idsByTable[dao.cfg.table] = ids;
+        }
+        return await db.multiDeleteByIds(idsByTable);
+    }
+    static async multiSaveBatch(inputs, opt = {}) {
+        if (!inputs.length)
+            return;
+        const { db } = inputs[0].dao.cfg;
+        const dbmsByTable = {};
+        await pMap(inputs, async ({ dao, rows }) => {
+            const { table } = dao.cfg;
+            rows.forEach(bm => dao.assignIdCreatedUpdated(bm, opt));
+            dbmsByTable[table] = await dao.bmsToDBM(rows, opt);
+        });
+        await db.multiSaveBatch(dbmsByTable);
+    }
     async createTransaction(opt) {
         const tx = await this.cfg.db.createTransaction(opt);
         return new CommonDaoTransaction(tx, this.cfg.logger);

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

@@ -1,10 +1,11 @@
 import type { ValidationFunction } from '@naturalcycles/js-lib';
 import type { AppError, ErrorMode } from '@naturalcycles/js-lib/error';
 import type { CommonLogger } from '@naturalcycles/js-lib/log';
-import type { BaseDBEntity, NumberOfMilliseconds, Promisable, UnixTimestamp } from '@naturalcycles/js-lib/types';
+import type { BaseDBEntity, ObjectWithId, Promisable, UnixTimestamp } from '@naturalcycles/js-lib/types';
 import type { TransformLogProgressOptions, TransformMapOptions } from '@naturalcycles/nodejs-lib/stream';
 import type { CommonDB } from '../commondb/common.db.js';
 import type { CommonDBCreateOptions, CommonDBOptions, CommonDBSaveOptions } from '../db.model.js';
+import type { CommonDao } from './common.dao.js';
 export interface CommonDaoHooks<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']> {
     /**
      * Allows to override the id generation function.
@@ -197,10 +198,7 @@ export interface CommonDaoIndex<DBM extends BaseDBEntity> {
      * Name of the property to index.
      */
     name: keyof DBM;
-    /**
-     * Defaults to ['asc']
-     */
-    order?: CommonDaoIndexOrder[];
+    order: CommonDaoIndexOrder[];
 }
 export type CommonDaoIndexOrder = 'asc' | 'desc' | 'array-contains';
 /**
@@ -335,8 +333,15 @@ export interface CommonDaoStreamOptions<IN> extends CommonDaoReadOptions, Transf
     chunkConcurrency?: number;
 }
 export type CommonDaoCreateOptions = CommonDBCreateOptions;
-export interface OnValidationTimeData {
-    tookMillis: NumberOfMilliseconds;
-    table: string;
-    obj: any;
+export interface DaoWithIds {
+    dao: CommonDao<any>;
+    ids: string[];
+}
+export interface DaoWithId {
+    dao: CommonDao<any>;
+    id: string;
+}
+export interface DaoWithRows<ROW extends ObjectWithId = ObjectWithId> {
+    dao: CommonDao<any>;
+    rows: ROW[];
 }

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

@@ -1,7 +1,7 @@
 import type { JsonSchemaObject, JsonSchemaRootObject } from '@naturalcycles/js-lib/json-schema';
 import type { ObjectWithId, StringMap } from '@naturalcycles/js-lib/types';
 import type { ReadableTyped } from '@naturalcycles/nodejs-lib/stream';
-import type { CommonDBOptions, CommonDBSaveOptions, CommonDBTransactionOptions, DBTransaction, DBTransactionFn, RunQueryResult } from '../db.model.js';
+import type { CommonDBOptions, CommonDBReadOptions, CommonDBSaveOptions, CommonDBTransactionOptions, DBTransaction, DBTransactionFn, RunQueryResult } from '../db.model.js';
 import type { DBQuery } from '../query/dbQuery.js';
 import type { CommonDB, CommonDBSupport } from './common.db.js';
 import { CommonDBType } from './common.db.js';
@@ -19,6 +19,7 @@ export declare class BaseCommonDB implements CommonDB {
     getByIds<ROW extends ObjectWithId>(_table: string, _ids: string[]): Promise<ROW[]>;
     deleteByQuery<ROW extends ObjectWithId>(_q: DBQuery<ROW>): Promise<number>;
     patchByQuery<ROW extends ObjectWithId>(_q: DBQuery<ROW>, _patch: Partial<ROW>, _opt?: CommonDBOptions): Promise<number>;
+    patchById<ROW extends ObjectWithId>(_table: string, _id: string, _patch: Partial<ROW>, _opt?: CommonDBOptions): Promise<void>;
     runQuery<ROW extends ObjectWithId>(_q: DBQuery<ROW>): Promise<RunQueryResult<ROW>>;
     runQueryCount<ROW extends ObjectWithId>(_q: DBQuery<ROW>): Promise<number>;
     saveBatch<ROW extends ObjectWithId>(_table: string, _rows: ROW[], _opt?: CommonDBSaveOptions<ROW>): Promise<void>;
@@ -27,4 +28,7 @@ export declare class BaseCommonDB implements CommonDB {
     runInTransaction(fn: DBTransactionFn, _opt?: CommonDBTransactionOptions): Promise<void>;
     createTransaction(_opt?: CommonDBTransactionOptions): Promise<DBTransaction>;
     incrementBatch(_table: string, _prop: string, _incrementMap: StringMap<number>, _opt?: CommonDBOptions): Promise<StringMap<number>>;
+    multiGetByIds<ROW extends ObjectWithId>(_map: StringMap<string[]>, _opt?: CommonDBReadOptions): Promise<StringMap<ROW[]>>;
+    multiSaveBatch<ROW extends ObjectWithId>(_map: StringMap<ROW[]>, _opt?: CommonDBSaveOptions<ROW>): Promise<void>;
+    multiDeleteByIds(_map: StringMap<string[]>, _opt?: CommonDBOptions): Promise<number>;
 }

package/dist/commondb/base.common.db.js

@@ -28,6 +28,9 @@ export class BaseCommonDB {
     async patchByQuery(_q, _patch, _opt) {
         throw new Error('patchByQuery is not implemented');
     }
+    async patchById(_table, _id, _patch, _opt) {
+        throw new Error('patchById is not implemented');
+    }
     async runQuery(_q) {
         throw new Error('runQuery is not implemented');
     }
@@ -54,4 +57,13 @@ export class BaseCommonDB {
     async incrementBatch(_table, _prop, _incrementMap, _opt) {
         throw new Error('incrementBatch is not implemented');
     }
+    async multiGetByIds(_map, _opt) {
+        throw new Error('multiGetByIds is not implemented');
+    }
+    async multiSaveBatch(_map, _opt) {
+        throw new Error('multiSaveBatch is not implemented');
+    }
+    async multiDeleteByIds(_map, _opt) {
+        throw new Error('multiDeleteByIds is not implemented');
+    }
 }

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

@@ -1,5 +1,5 @@
 import type { JsonSchemaObject, JsonSchemaRootObject } from '@naturalcycles/js-lib/json-schema';
-import type { ObjectWithId, StringMap } from '@naturalcycles/js-lib/types';
+import type { NonNegativeInteger, ObjectWithId, StringMap } from '@naturalcycles/js-lib/types';
 import type { ReadableTyped } from '@naturalcycles/nodejs-lib/stream';
 import type { CommonDBCreateOptions, CommonDBOptions, CommonDBReadOptions, CommonDBSaveOptions, CommonDBStreamOptions, CommonDBTransactionOptions, DBTransaction, DBTransactionFn, RunQueryResult } from '../db.model.js';
 import type { DBQuery } from '../query/dbQuery.js';
@@ -7,6 +7,10 @@ export declare enum CommonDBType {
     'document' = "document",
     'relational' = "relational"
 }
+/**
+ * A tuple that contains the table name and the id.
+ */
+export type CommonDBKey = [table: string, id: string];
 export interface CommonDB {
     /**
      * Relational databases are expected to return `null` for all missing properties.
@@ -44,26 +48,83 @@ export interface CommonDB {
      * (Such limitation exists because Datastore doesn't support it).
      */
     getByIds: <ROW extends ObjectWithId>(table: string, ids: string[], opt?: CommonDBReadOptions) => Promise<ROW[]>;
+    /**
+     * Get rows from multiple tables at once.
+     * Mimics the API of some NoSQL databases like Firestore.
+     *
+     * Takes `map`, which is a map from "table name" to an array of ids.
+     * Example:
+     * {
+     *   'TableOne': ['id1', 'id2'],
+     *   'TableTwo': ['id3'],
+     * }
+     *
+     * Returns a map with the same keys (table names) and arrays of rows as values.
+     * Even if some table is not found, it will return an empty array of results for that table.
+     *
+     * @experimental
+     */
+    multiGetByIds: <ROW extends ObjectWithId>(idsByTable: StringMap<string[]>, opt?: CommonDBReadOptions) => Promise<StringMap<ROW[]>>;
     /**
      * Order by 'id' is not supported by all implementations (for example, Datastore doesn't support it).
      */
     runQuery: <ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBReadOptions) => Promise<RunQueryResult<ROW>>;
-    runQueryCount: <ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBReadOptions) => Promise<number>;
+    runQueryCount: <ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBReadOptions) => Promise<NonNegativeInteger>;
     streamQuery: <ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBStreamOptions) => ReadableTyped<ROW>;
     /**
      * rows can have missing ids only if DB supports auto-generating them (like mysql auto_increment).
      */
     saveBatch: <ROW extends ObjectWithId>(table: string, rows: ROW[], opt?: CommonDBSaveOptions<ROW>) => Promise<void>;
     /**
+     * Save rows for multiple tables at once.
+     * Mimics the API of some NoSQL databases like Firestore.
+     *
+     * Takes `map`, which is a map from "table name" to an array of rows.
+     * Example:
+     * {
+     *  'TableOne': [{ id: 'id1', ... }, { id: 'id2', ... }],
+     *  'TableTwo': [{ id: 'id3', ... }],
+     * }
+     *
+     * @experimental
+     */
+    multiSaveBatch: <ROW extends ObjectWithId>(rowsByTable: StringMap<ROW[]>, opt?: CommonDBSaveOptions<ROW>) => Promise<void>;
+    /**
+     * Perform a partial update of a row by its id.
+     * Unlike save - doesn't require to first load the doc.
+     * Mimics the API of some NoSQL databases like Firestore.
+     *
+     * The object with given id has to exist, otherwise an error will be thrown.
+     *
+     * @experimental
+     */
+    patchById: <ROW extends ObjectWithId>(table: string, id: string, patch: Partial<ROW>, opt?: CommonDBOptions) => Promise<void>;
+    /**
+     * Returns number of deleted items.
+     * Not supported by all implementations (e.g Datastore will always return same number as number of ids).
+     */
+    deleteByIds: (table: string, ids: string[], opt?: CommonDBOptions) => Promise<NonNegativeInteger>;
+    /**
+     * Deletes rows from multiple tables at once.
+     * Mimics the API of some NoSQL databases like Firestore.
+     * Takes `map`, which is a map from "table name" to an array of ids to delete.
+     * Example:
+     * {
+     *  'TableOne': ['id1', 'id2'],
+     *  'TableTwo': ['id3'],
+     * }
+     *
      * Returns number of deleted items.
      * Not supported by all implementations (e.g Datastore will always return same number as number of ids).
+     *
+     * @experimental
      */
-    deleteByIds: (table: string, ids: string[], opt?: CommonDBOptions) => Promise<number>;
+    multiDeleteByIds: (idsByTable: StringMap<string[]>, opt?: CommonDBOptions) => Promise<NonNegativeInteger>;
     /**
      * Returns number of deleted items.
      * Not supported by all implementations (e.g Datastore will always return same number as number of ids).
      */
-    deleteByQuery: <ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBOptions) => Promise<number>;
+    deleteByQuery: <ROW extends ObjectWithId>(q: DBQuery<ROW>, opt?: CommonDBOptions) => Promise<NonNegativeInteger>;
     /**
      * Applies patch to all the rows that are matched by the query.
      *
@@ -123,6 +184,7 @@ export interface CommonDBSupport {
     insertSaveMethod?: boolean;
     updateSaveMethod?: boolean;
     patchByQuery?: boolean;
+    patchById?: boolean;
     increment?: boolean;
     createTable?: boolean;
     tableSchemas?: boolean;
@@ -131,5 +193,6 @@ export interface CommonDBSupport {
     nullValues?: boolean;
     transactions?: boolean;
     timeMachine?: boolean;
+    multiTableOperations?: boolean;
 }
-export declare const commonDBFullSupport: CommonDBSupport;
+export declare const commonDBFullSupport: Required<CommonDBSupport>;

package/dist/commondb/common.db.js

@@ -12,6 +12,7 @@ export const commonDBFullSupport = {
     insertSaveMethod: true,
     updateSaveMethod: true,
     patchByQuery: true,
+    patchById: true,
     increment: true,
     createTable: true,
     tableSchemas: true,
@@ -20,4 +21,5 @@ export const commonDBFullSupport = {
     nullValues: true,
     transactions: true,
     timeMachine: true,
+    multiTableOperations: true,
 };

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

@@ -50,9 +50,13 @@ export declare class InMemoryDB implements CommonDB {
     getTableSchema<ROW extends ObjectWithId>(_table: string): Promise<JsonSchemaRootObject<ROW>>;
     createTable<ROW extends ObjectWithId>(_table: string, _schema: JsonSchemaObject<ROW>, opt?: CommonDBCreateOptions): Promise<void>;
     getByIds<ROW extends ObjectWithId>(_table: string, ids: string[], _opt?: CommonDBOptions): Promise<ROW[]>;
+    multiGetByIds<ROW extends ObjectWithId>(map: StringMap<string[]>, _opt?: CommonDBOptions): Promise<StringMap<ROW[]>>;
     saveBatch<ROW extends ObjectWithId>(_table: string, rows: ROW[], opt?: CommonDBSaveOptions<ROW>): Promise<void>;
+    multiSaveBatch<ROW extends ObjectWithId>(map: StringMap<ROW[]>, opt?: CommonDBSaveOptions<ROW>): Promise<void>;
+    patchById<ROW extends ObjectWithId>(_table: string, id: string, patch: Partial<ROW>, _opt?: CommonDBOptions): Promise<void>;
     deleteByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, _opt?: CommonDBOptions): Promise<number>;
     deleteByIds(_table: string, ids: string[], _opt?: CommonDBOptions): Promise<number>;
+    multiDeleteByIds(map: StringMap<string[]>, _opt?: CommonDBOptions): Promise<number>;
     patchByQuery<ROW extends ObjectWithId>(q: DBQuery<ROW>, patch: Partial<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>;

package/dist/inmemory/inMemory.db.js

@@ -74,18 +74,28 @@ export class InMemoryDB {
         this.data[table] ||= {};
         return ids.map(id => this.data[table][id]).filter(Boolean);
     }
+    async multiGetByIds(map, _opt = {}) {
+        const result = {};
+        for (const [tableName, ids] of _stringMapEntries(map)) {
+            const table = this.cfg.tablesPrefix + tableName;
+            result[table] = ids.map(id => this.data[table]?.[id]).filter(Boolean);
+        }
+        return result;
+    }
     async saveBatch(_table, rows, opt = {}) {
         const table = this.cfg.tablesPrefix + _table;
         this.data[table] ||= {};
+        const isInsert = opt.saveMethod === 'insert';
+        const isUpdate = opt.saveMethod === 'update';
         for (const r of rows) {
             if (!r.id) {
                 this.cfg.logger.warn({ rows });
                 throw new Error(`InMemoryDB doesn't support id auto-generation in saveBatch, row without id was given`);
             }
-            if (opt.saveMethod === 'insert' && this.data[table][r.id]) {
+            if (isInsert && this.data[table][r.id]) {
                 throw new Error(`InMemoryDB: INSERT failed, entity exists: ${table}.${r.id}`);
             }
-            if (opt.saveMethod === 'update' && !this.data[table][r.id]) {
+            if (isUpdate && !this.data[table][r.id]) {
                 throw new Error(`InMemoryDB: UPDATE failed, entity doesn't exist: ${table}.${r.id}`);
             }
             // JSON parse/stringify (deep clone) is to:
@@ -94,6 +104,16 @@ export class InMemoryDB {
             this.data[table][r.id] = JSON.parse(JSON.stringify(r), bufferReviver);
         }
     }
+    async multiSaveBatch(map, opt = {}) {
+        for (const [table, rows] of _stringMapEntries(map)) {
+            await this.saveBatch(table, rows, opt);
+        }
+    }
+    async patchById(_table, id, patch, _opt) {
+        const table = this.cfg.tablesPrefix + _table;
+        _assert(!this.data[table]?.[id], `InMemoryDB: patchById failed, entity doesn't exist: ${table}.${id}`);
+        Object.assign(this.data[table][id], patch);
+    }
     async deleteByQuery(q, _opt) {
         const table = this.cfg.tablesPrefix + q.table;
         if (!this.data[table])
@@ -114,6 +134,13 @@ export class InMemoryDB {
         }
         return count;
     }
+    async multiDeleteByIds(map, _opt) {
+        let count = 0;
+        for (const [table, ids] of _stringMapEntries(map)) {
+            count += await this.deleteByIds(table, ids, _opt);
+        }
+        return count;
+    }
     async patchByQuery(q, patch) {
         if (_isEmptyObject(patch))
             return 0;

package/dist/testing/test.model.d.ts

@@ -2,6 +2,7 @@ import type { JsonSchemaObject } from '@naturalcycles/js-lib/json-schema';
 import type { BaseDBEntity } from '@naturalcycles/js-lib/types';
 import { type ObjectSchema } from '@naturalcycles/nodejs-lib/joi';
 export declare const TEST_TABLE = "TEST_TABLE";
+export declare const TEST_TABLE_2 = "TEST_TABLE_2";
 export interface TestItemBM extends BaseDBEntity {
     k1: string;
     k2?: string | null;

package/dist/testing/test.model.js

@@ -3,6 +3,7 @@ import { j } from '@naturalcycles/js-lib/json-schema';
 import { baseDBEntitySchema, binarySchema, booleanSchema, numberSchema, objectSchema, stringSchema, } from '@naturalcycles/nodejs-lib/joi';
 const MOCK_TS_2018_06_21 = 1529539200;
 export const TEST_TABLE = 'TEST_TABLE';
+export const TEST_TABLE_2 = 'TEST_TABLE_2';
 export const testItemBMSchema = objectSchema({
     k1: stringSchema,
     k2: stringSchema.allow(null).optional(),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/db-lib",
   "type": "module",
-  "version": "10.17.1",
+  "version": "10.18.0",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@naturalcycles/nodejs-lib": "^15"

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

@@ -3,7 +3,7 @@ import type { AppError, ErrorMode } from '@naturalcycles/js-lib/error'
 import type { CommonLogger } from '@naturalcycles/js-lib/log'
 import type {
   BaseDBEntity,
-  NumberOfMilliseconds,
+  ObjectWithId,
   Promisable,
   UnixTimestamp,
 } from '@naturalcycles/js-lib/types'
@@ -13,6 +13,7 @@ import type {
 } from '@naturalcycles/nodejs-lib/stream'
 import type { CommonDB } from '../commondb/common.db.js'
 import type { CommonDBCreateOptions, CommonDBOptions, CommonDBSaveOptions } from '../db.model.js'
+import type { CommonDao } from './common.dao.js'
 
 export interface CommonDaoHooks<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']> {
   /**
@@ -239,10 +240,7 @@ export interface CommonDaoIndex<DBM extends BaseDBEntity> {
    * Name of the property to index.
    */
   name: keyof DBM
-  /**
-   * Defaults to ['asc']
-   */
-  order?: CommonDaoIndexOrder[]
+  order: CommonDaoIndexOrder[]
 }
 
 export type CommonDaoIndexOrder = 'asc' | 'desc' | 'array-contains'
@@ -407,8 +405,17 @@ export interface CommonDaoStreamOptions<IN>
 
 export type CommonDaoCreateOptions = CommonDBCreateOptions
 
-export interface OnValidationTimeData {
-  tookMillis: NumberOfMilliseconds
-  table: string
-  obj: any
+export interface DaoWithIds {
+  dao: CommonDao<any>
+  ids: string[]
+}
+
+export interface DaoWithId {
+  dao: CommonDao<any>
+  id: string
+}
+
+export interface DaoWithRows<ROW extends ObjectWithId = ObjectWithId> {
+  dao: CommonDao<any>
+  rows: ROW[]
 }

package/src/commondao/common.dao.ts

@@ -17,6 +17,7 @@ import { _truncate } from '@naturalcycles/js-lib/string/string.util.js'
 import type {
   AsyncIndexedMapper,
   BaseDBEntity,
+  NonNegativeInteger,
   ObjectWithId,
   StringMap,
   UnixTimestampMillis,
@@ -51,6 +52,9 @@ import type {
   CommonDaoStreamForEachOptions,
   CommonDaoStreamOptions,
   CommonDaoStreamSaveOptions,
+  DaoWithId,
+  DaoWithIds,
+  DaoWithRows,
 } from './common.dao.model.js'
 import { CommonDaoLogLevel } from './common.dao.model.js'
 
@@ -1257,6 +1261,113 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     await this.cfg.db.ping()
   }
 
+  id(id: string): DaoWithId {
+    return {
+      dao: this,
+      id,
+    }
+  }
+
+  ids(ids: string[]): DaoWithIds {
+    return {
+      dao: this,
+      ids,
+    }
+  }
+
+  rows(rows: BM[]): DaoWithRows {
+    return {
+      dao: this,
+      rows,
+    }
+  }
+
+  /**
+   * Very @experimental.
+   */
+  static async multiGetById<T>(inputs: DaoWithId[], opt: CommonDaoReadOptions = {}): Promise<T> {
+    const inputs2 = inputs.map(input => ({
+      dao: input.dao,
+      ids: [input.id],
+    }))
+
+    const rowsByTable = await CommonDao.multiGetByIds(inputs2, opt)
+    const results: any[] = inputs.map(({ dao }) => {
+      const { table } = dao.cfg
+      return rowsByTable[table]?.[0] || null
+    })
+
+    return results as T
+  }
+
+  /**
+   * Very @experimental.
+   */
+  static async multiGetByIds(
+    inputs: DaoWithIds[],
+    opt: CommonDaoReadOptions = {},
+  ): Promise<StringMap<unknown[]>> {
+    if (!inputs.length) return {}
+    const { db } = inputs[0]!.dao.cfg
+    const idsByTable: StringMap<string[]> = {}
+    for (const { dao, ids } of inputs) {
+      const { table } = dao.cfg
+      idsByTable[table] = ids
+    }
+
+    // todo: support tx
+    const dbmsByTable = await db.multiGetByIds(idsByTable, opt)
+    const bmsByTable: StringMap<unknown[]> = {}
+
+    await pMap(inputs, async ({ dao }) => {
+      const { table } = dao.cfg
+      let dbms = dbmsByTable[table] || []
+
+      if (dao.cfg.hooks!.afterLoad && dbms.length) {
+        dbms = (await pMap(dbms, async dbm => await dao.cfg.hooks!.afterLoad!(dbm))).filter(
+          _isTruthy,
+        )
+      }
+
+      bmsByTable[table] = await dao.dbmsToBM(dbms, opt)
+    })
+
+    return bmsByTable
+  }
+
+  /**
+   * Very @experimental.
+   */
+  static async multiDeleteByIds(
+    inputs: DaoWithIds[],
+    _opt: CommonDaoOptions = {},
+  ): Promise<NonNegativeInteger> {
+    if (!inputs.length) return 0
+    const { db } = inputs[0]!.dao.cfg
+    const idsByTable: StringMap<string[]> = {}
+    for (const { dao, ids } of inputs) {
+      idsByTable[dao.cfg.table] = ids
+    }
+
+    return await db.multiDeleteByIds(idsByTable)
+  }
+
+  static async multiSaveBatch(
+    inputs: DaoWithRows[],
+    opt: CommonDaoSaveBatchOptions<any> = {},
+  ): Promise<void> {
+    if (!inputs.length) return
+    const { db } = inputs[0]!.dao.cfg
+    const dbmsByTable: StringMap<any[]> = {}
+    await pMap(inputs, async ({ dao, rows }) => {
+      const { table } = dao.cfg
+      rows.forEach(bm => dao.assignIdCreatedUpdated(bm, opt))
+      dbmsByTable[table] = await dao.bmsToDBM(rows, opt)
+    })
+
+    await db.multiSaveBatch(dbmsByTable)
+  }
+
   async createTransaction(opt?: CommonDBTransactionOptions): Promise<CommonDaoTransaction> {
     const tx = await this.cfg.db.createTransaction(opt)
     return new CommonDaoTransaction(tx, this.cfg.logger!)

package/src/commondb/base.common.db.ts

@@ -3,6 +3,7 @@ import type { ObjectWithId, StringMap } from '@naturalcycles/js-lib/types'
 import type { ReadableTyped } from '@naturalcycles/nodejs-lib/stream'
 import type {
   CommonDBOptions,
+  CommonDBReadOptions,
   CommonDBSaveOptions,
   CommonDBTransactionOptions,
   DBTransaction,
@@ -60,6 +61,15 @@ export class BaseCommonDB implements CommonDB {
     throw new Error('patchByQuery is not implemented')
   }
 
+  async patchById<ROW extends ObjectWithId>(
+    _table: string,
+    _id: string,
+    _patch: Partial<ROW>,
+    _opt?: CommonDBOptions,
+  ): Promise<void> {
+    throw new Error('patchById is not implemented')
+  }
+
   async runQuery<ROW extends ObjectWithId>(_q: DBQuery<ROW>): Promise<RunQueryResult<ROW>> {
     throw new Error('runQuery is not implemented')
   }
@@ -102,4 +112,22 @@ export class BaseCommonDB implements CommonDB {
   ): Promise<StringMap<number>> {
     throw new Error('incrementBatch is not implemented')
   }
+
+  async multiGetByIds<ROW extends ObjectWithId>(
+    _map: StringMap<string[]>,
+    _opt?: CommonDBReadOptions,
+  ): Promise<StringMap<ROW[]>> {
+    throw new Error('multiGetByIds is not implemented')
+  }
+
+  async multiSaveBatch<ROW extends ObjectWithId>(
+    _map: StringMap<ROW[]>,
+    _opt?: CommonDBSaveOptions<ROW>,
+  ): Promise<void> {
+    throw new Error('multiSaveBatch is not implemented')
+  }
+
+  async multiDeleteByIds(_map: StringMap<string[]>, _opt?: CommonDBOptions): Promise<number> {
+    throw new Error('multiDeleteByIds is not implemented')
+  }
 }

package/src/commondb/common.db.ts

@@ -1,5 +1,5 @@
 import type { JsonSchemaObject, JsonSchemaRootObject } from '@naturalcycles/js-lib/json-schema'
-import type { ObjectWithId, StringMap } from '@naturalcycles/js-lib/types'
+import type { NonNegativeInteger, ObjectWithId, StringMap } from '@naturalcycles/js-lib/types'
 import type { ReadableTyped } from '@naturalcycles/nodejs-lib/stream'
 import type {
   CommonDBCreateOptions,
@@ -19,6 +19,11 @@ export enum CommonDBType {
   'relational' = 'relational',
 }
 
+/**
+ * A tuple that contains the table name and the id.
+ */
+export type CommonDBKey = [table: string, id: string]
+
 export interface CommonDB {
   /**
    * Relational databases are expected to return `null` for all missing properties.
@@ -72,6 +77,27 @@ export interface CommonDB {
     opt?: CommonDBReadOptions,
   ) => Promise<ROW[]>
 
+  /**
+   * Get rows from multiple tables at once.
+   * Mimics the API of some NoSQL databases like Firestore.
+   *
+   * Takes `map`, which is a map from "table name" to an array of ids.
+   * Example:
+   * {
+   *   'TableOne': ['id1', 'id2'],
+   *   'TableTwo': ['id3'],
+   * }
+   *
+   * Returns a map with the same keys (table names) and arrays of rows as values.
+   * Even if some table is not found, it will return an empty array of results for that table.
+   *
+   * @experimental
+   */
+  multiGetByIds: <ROW extends ObjectWithId>(
+    idsByTable: StringMap<string[]>,
+    opt?: CommonDBReadOptions,
+  ) => Promise<StringMap<ROW[]>>
+
   // QUERY
   /**
    * Order by 'id' is not supported by all implementations (for example, Datastore doesn't support it).
@@ -84,7 +110,7 @@ export interface CommonDB {
   runQueryCount: <ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
     opt?: CommonDBReadOptions,
-  ) => Promise<number>
+  ) => Promise<NonNegativeInteger>
 
   streamQuery: <ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
@@ -101,12 +127,66 @@ export interface CommonDB {
     opt?: CommonDBSaveOptions<ROW>,
   ) => Promise<void>
 
+  /**
+   * Save rows for multiple tables at once.
+   * Mimics the API of some NoSQL databases like Firestore.
+   *
+   * Takes `map`, which is a map from "table name" to an array of rows.
+   * Example:
+   * {
+   *  'TableOne': [{ id: 'id1', ... }, { id: 'id2', ... }],
+   *  'TableTwo': [{ id: 'id3', ... }],
+   * }
+   *
+   * @experimental
+   */
+  multiSaveBatch: <ROW extends ObjectWithId>(
+    rowsByTable: StringMap<ROW[]>,
+    opt?: CommonDBSaveOptions<ROW>,
+  ) => Promise<void>
+
+  /**
+   * Perform a partial update of a row by its id.
+   * Unlike save - doesn't require to first load the doc.
+   * Mimics the API of some NoSQL databases like Firestore.
+   *
+   * The object with given id has to exist, otherwise an error will be thrown.
+   *
+   * @experimental
+   */
+  patchById: <ROW extends ObjectWithId>(
+    table: string,
+    id: string,
+    patch: Partial<ROW>,
+    opt?: CommonDBOptions,
+  ) => Promise<void>
+
   // DELETE
   /**
    * Returns number of deleted items.
    * Not supported by all implementations (e.g Datastore will always return same number as number of ids).
    */
-  deleteByIds: (table: string, ids: string[], opt?: CommonDBOptions) => Promise<number>
+  deleteByIds: (table: string, ids: string[], opt?: CommonDBOptions) => Promise<NonNegativeInteger>
+
+  /**
+   * Deletes rows from multiple tables at once.
+   * Mimics the API of some NoSQL databases like Firestore.
+   * Takes `map`, which is a map from "table name" to an array of ids to delete.
+   * Example:
+   * {
+   *  'TableOne': ['id1', 'id2'],
+   *  'TableTwo': ['id3'],
+   * }
+   *
+   * Returns number of deleted items.
+   * Not supported by all implementations (e.g Datastore will always return same number as number of ids).
+   *
+   * @experimental
+   */
+  multiDeleteByIds: (
+    idsByTable: StringMap<string[]>,
+    opt?: CommonDBOptions,
+  ) => Promise<NonNegativeInteger>
 
   /**
    * Returns number of deleted items.
@@ -115,7 +195,7 @@ export interface CommonDB {
   deleteByQuery: <ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
     opt?: CommonDBOptions,
-  ) => Promise<number>
+  ) => Promise<NonNegativeInteger>
 
   /**
    * Applies patch to all the rows that are matched by the query.
@@ -190,6 +270,7 @@ export interface CommonDBSupport {
   insertSaveMethod?: boolean
   updateSaveMethod?: boolean
   patchByQuery?: boolean
+  patchById?: boolean
   increment?: boolean
   createTable?: boolean
   tableSchemas?: boolean
@@ -198,9 +279,10 @@ export interface CommonDBSupport {
   nullValues?: boolean
   transactions?: boolean
   timeMachine?: boolean
+  multiTableOperations?: boolean
 }
 
-export const commonDBFullSupport: CommonDBSupport = {
+export const commonDBFullSupport: Required<CommonDBSupport> = {
   queries: true,
   dbQueryFilter: true,
   dbQueryFilterIn: true,
@@ -209,6 +291,7 @@ export const commonDBFullSupport: CommonDBSupport = {
   insertSaveMethod: true,
   updateSaveMethod: true,
   patchByQuery: true,
+  patchById: true,
   increment: true,
   createTable: true,
   tableSchemas: true,
@@ -217,4 +300,5 @@ export const commonDBFullSupport: CommonDBSupport = {
   nullValues: true,
   transactions: true,
   timeMachine: true,
+  multiTableOperations: true,
 }

package/src/inmemory/inMemory.db.ts

@@ -145,6 +145,20 @@ export class InMemoryDB implements CommonDB {
     return ids.map(id => this.data[table]![id] as ROW).filter(Boolean)
   }
 
+  async multiGetByIds<ROW extends ObjectWithId>(
+    map: StringMap<string[]>,
+    _opt: CommonDBOptions = {},
+  ): Promise<StringMap<ROW[]>> {
+    const result: StringMap<ROW[]> = {}
+
+    for (const [tableName, ids] of _stringMapEntries(map)) {
+      const table = this.cfg.tablesPrefix + tableName
+      result[table] = ids.map(id => this.data[table]?.[id] as ROW).filter(Boolean)
+    }
+
+    return result
+  }
+
   async saveBatch<ROW extends ObjectWithId>(
     _table: string,
     rows: ROW[],
@@ -152,6 +166,8 @@ export class InMemoryDB implements CommonDB {
   ): Promise<void> {
     const table = this.cfg.tablesPrefix + _table
     this.data[table] ||= {}
+    const isInsert = opt.saveMethod === 'insert'
+    const isUpdate = opt.saveMethod === 'update'
 
     for (const r of rows) {
       if (!r.id) {
@@ -161,11 +177,11 @@ export class InMemoryDB implements CommonDB {
         )
       }
 
-      if (opt.saveMethod === 'insert' && this.data[table][r.id]) {
+      if (isInsert && this.data[table][r.id]) {
         throw new Error(`InMemoryDB: INSERT failed, entity exists: ${table}.${r.id}`)
       }
 
-      if (opt.saveMethod === 'update' && !this.data[table][r.id]) {
+      if (isUpdate && !this.data[table][r.id]) {
         throw new Error(`InMemoryDB: UPDATE failed, entity doesn't exist: ${table}.${r.id}`)
       }
 
@@ -176,6 +192,29 @@ export class InMemoryDB implements CommonDB {
     }
   }
 
+  async multiSaveBatch<ROW extends ObjectWithId>(
+    map: StringMap<ROW[]>,
+    opt: CommonDBSaveOptions<ROW> = {},
+  ): Promise<void> {
+    for (const [table, rows] of _stringMapEntries(map)) {
+      await this.saveBatch(table, rows, opt)
+    }
+  }
+
+  async patchById<ROW extends ObjectWithId>(
+    _table: string,
+    id: string,
+    patch: Partial<ROW>,
+    _opt?: CommonDBOptions,
+  ): Promise<void> {
+    const table = this.cfg.tablesPrefix + _table
+    _assert(
+      !this.data[table]?.[id],
+      `InMemoryDB: patchById failed, entity doesn't exist: ${table}.${id}`,
+    )
+    Object.assign(this.data[table]![id]!, patch)
+  }
+
   async deleteByQuery<ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
     _opt?: CommonDBOptions,
@@ -200,6 +239,16 @@ export class InMemoryDB implements CommonDB {
     return count
   }
 
+  async multiDeleteByIds(map: StringMap<string[]>, _opt?: CommonDBOptions): Promise<number> {
+    let count = 0
+
+    for (const [table, ids] of _stringMapEntries(map)) {
+      count += await this.deleteByIds(table, ids, _opt)
+    }
+
+    return count
+  }
+
   async patchByQuery<ROW extends ObjectWithId>(
     q: DBQuery<ROW>,
     patch: Partial<ROW>,

package/src/testing/test.model.ts

@@ -15,6 +15,7 @@ import {
 const MOCK_TS_2018_06_21 = 1529539200 as UnixTimestamp
 
 export const TEST_TABLE = 'TEST_TABLE'
+export const TEST_TABLE_2 = 'TEST_TABLE_2'
 
 export interface TestItemBM extends BaseDBEntity {
   k1: string