@naturalcycles/db-lib 10.18.0 → 10.19.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, NonNegativeInteger, StringMap, UnixTimestampMillis, Unsaved } from '@naturalcycles/js-lib/types';
+import { type AsyncIndexedMapper, type BaseDBEntity, type NonNegativeInteger, type StringMap, type UnixTimestampMillis, type 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, DaoWithId, DaoWithIds, DaoWithRows } from './common.dao.model.js';
+import type { CommonDaoCfg, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoPatchByIdOptions, CommonDaoPatchOptions, CommonDaoReadOptions, CommonDaoSaveBatchOptions, CommonDaoSaveOptions, CommonDaoStreamDeleteOptions, CommonDaoStreamForEachOptions, CommonDaoStreamOptions, CommonDaoStreamSaveOptions } from './common.dao.model.js';
 /**
  * Lowest common denominator API between supported Databases.
  *
@@ -14,7 +14,7 @@ import type { CommonDaoCfg, CommonDaoCreateOptions, CommonDaoOptions, CommonDaoP
  * BM = Backend model (optimized for API access)
  * TM = Transport model (optimized to be sent over the wire)
  */
-export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, ID = BM['id']> {
+export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, ID extends string = BM['id']> {
     cfg: CommonDaoCfg<BM, DBM, ID>;
     constructor(cfg: CommonDaoCfg<BM, DBM, ID>);
     create(part?: Partial<BM>, opt?: CommonDaoOptions): BM;
@@ -167,22 +167,26 @@ 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;
+    withId(id: ID): DaoWithId<typeof this>;
+    withIds(ids: ID[]): DaoWithIds<typeof this>;
+    toSave(input: BM | BM[]): DaoWithRows<typeof this>;
     /**
-     * Very @experimental.
-     */
-    static multiGetById<T>(inputs: DaoWithId[], opt?: CommonDaoReadOptions): Promise<T>;
-    /**
-     * Very @experimental.
+     * Load rows (by their ids) from Multiple tables at once.
+     * An optimized way to load data, minimizing DB round-trips.
+     *
+     * @experimental.
      */
-    static multiGetByIds(inputs: DaoWithIds[], opt?: CommonDaoReadOptions): Promise<StringMap<unknown[]>>;
+    static multiGet<MAP extends Record<string, DaoWithIds<AnyDao> | DaoWithId<AnyDao>>>(inputMap: MAP, opt?: CommonDaoReadOptions): Promise<{
+        [K in keyof MAP]: MAP[K] extends DaoWithIds<any> ? InferBM<MAP[K]['dao']>[] : InferBM<MAP[K]['dao']> | null;
+    }>;
+    private static prepareMultiGetIds;
+    private static multiGetMapByTableById;
+    private static prepareMultiGetOutput;
     /**
      * Very @experimental.
      */
-    static multiDeleteByIds(inputs: DaoWithIds[], _opt?: CommonDaoOptions): Promise<NonNegativeInteger>;
-    static multiSaveBatch(inputs: DaoWithRows[], opt?: CommonDaoSaveBatchOptions<any>): Promise<void>;
+    static multiDeleteByIds(inputs: DaoWithIds<any>[], _opt?: CommonDaoOptions): Promise<NonNegativeInteger>;
+    static multiSave(inputs: DaoWithRows<any>[], opt?: CommonDaoSaveBatchOptions<any>): Promise<void>;
     createTransaction(opt?: CommonDBTransactionOptions): Promise<CommonDaoTransaction>;
     runInTransaction<T = void>(fn: CommonDaoTransactionFn<T>, opt?: CommonDBTransactionOptions): Promise<T>;
     /**
@@ -218,8 +222,8 @@ export declare class CommonDaoTransaction {
      * Never throws.
      */
     rollback(): Promise<void>;
-    getById<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(dao: CommonDao<BM, DBM, ID>, id?: ID | null, opt?: CommonDaoReadOptions): Promise<BM | null>;
-    getByIds<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(dao: CommonDao<BM, DBM, ID>, ids: ID[], opt?: CommonDaoReadOptions): Promise<BM[]>;
+    getById<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID extends string = BM['id']>(dao: CommonDao<BM, DBM, ID>, id?: ID | null, opt?: CommonDaoReadOptions): Promise<BM | null>;
+    getByIds<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID extends string = BM['id']>(dao: CommonDao<BM, DBM, ID>, ids: ID[], opt?: CommonDaoReadOptions): Promise<BM[]>;
     save<BM extends BaseDBEntity, DBM extends BaseDBEntity>(dao: CommonDao<BM, DBM>, bm: Unsaved<BM>, opt?: CommonDaoSaveOptions<BM, DBM>): Promise<BM>;
     saveBatch<BM extends BaseDBEntity, DBM extends BaseDBEntity>(dao: CommonDao<BM, DBM>, bms: Unsaved<BM>[], opt?: CommonDaoSaveBatchOptions<DBM>): Promise<BM[]>;
     /**
@@ -229,7 +233,23 @@ export declare class CommonDaoTransaction {
      *
      * So, this method is a rather simple convenience "Object.assign and then save".
      */
-    patch<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(dao: CommonDao<BM, DBM, ID>, bm: BM, patch: Partial<BM>, opt?: CommonDaoSaveOptions<BM, DBM>): Promise<BM>;
-    deleteById<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(dao: CommonDao<BM, DBM, ID>, id?: ID | null, opt?: CommonDaoOptions): Promise<number>;
-    deleteByIds<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(dao: CommonDao<BM, DBM, ID>, ids: ID[], opt?: CommonDaoOptions): Promise<number>;
+    patch<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID extends string = BM['id']>(dao: CommonDao<BM, DBM, ID>, bm: BM, patch: Partial<BM>, opt?: CommonDaoSaveOptions<BM, DBM>): Promise<BM>;
+    deleteById<DAO extends AnyDao>(dao: DAO, id?: InferID<DAO> | null, opt?: CommonDaoOptions): Promise<number>;
+    deleteByIds<DAO extends AnyDao>(dao: DAO, ids: InferID<DAO>[], opt?: CommonDaoOptions): Promise<number>;
+}
+export interface DaoWithIds<DAO extends AnyDao> {
+    dao: DAO;
+    ids: string[];
+}
+export interface DaoWithId<DAO extends AnyDao> {
+    dao: DAO;
+    id: string;
+}
+export interface DaoWithRows<DAO extends AnyDao> {
+    dao: DAO;
+    rows: InferBM<DAO>[];
 }
+type InferBM<DAO> = DAO extends CommonDao<infer BM> ? BM : never;
+type InferID<DAO> = DAO extends CommonDao<any, any, infer ID> ? ID : never;
+export type AnyDao = CommonDao<any>;
+export {};

package/dist/commondao/common.dao.js

@@ -7,6 +7,7 @@ import { _deepJsonEquals } from '@naturalcycles/js-lib/object/deepEquals.js';
 import { _deepCopy, _filterUndefinedValues, _objectAssignExact, } from '@naturalcycles/js-lib/object/object.util.js';
 import { pMap } from '@naturalcycles/js-lib/promise/pMap.js';
 import { _truncate } from '@naturalcycles/js-lib/string/string.util.js';
+import { _stringMapEntries, _stringMapValues, } from '@naturalcycles/js-lib/types';
 import { _passthroughPredicate, _typeCast, SKIP } from '@naturalcycles/js-lib/types';
 import { stringId } from '@naturalcycles/nodejs-lib';
 import { transformFlatten } from '@naturalcycles/nodejs-lib/stream';
@@ -981,63 +982,96 @@ export class CommonDao {
     async ping() {
         await this.cfg.db.ping();
     }
-    id(id) {
+    withId(id) {
         return {
             dao: this,
             id,
         };
     }
-    ids(ids) {
+    withIds(ids) {
         return {
             dao: this,
             ids,
         };
     }
-    rows(rows) {
+    toSave(input) {
         return {
             dao: this,
-            rows,
+            rows: [input].flat(),
         };
     }
     /**
-     * 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.
+     * Load rows (by their ids) from Multiple tables at once.
+     * An optimized way to load data, minimizing DB round-trips.
+     *
+     * @experimental.
      */
-    static async multiGetByIds(inputs, opt = {}) {
-        if (!inputs.length)
+    static async multiGet(inputMap, opt = {}) {
+        const db = Object.values(inputMap)[0]?.dao.cfg.db;
+        if (!db) {
             return {};
-        const { db } = inputs[0].dao.cfg;
-        const idsByTable = {};
-        for (const { dao, ids } of inputs) {
-            const { table } = dao.cfg;
-            idsByTable[table] = ids;
         }
+        const idsByTable = CommonDao.prepareMultiGetIds(inputMap);
         // todo: support tx
-        const dbmsByTable = await db.multiGetByIds(idsByTable, opt);
-        const bmsByTable = {};
-        await pMap(inputs, async ({ dao }) => {
+        const dbmsByTable = await db.multiGet(idsByTable, opt);
+        const dbmByTableById = CommonDao.multiGetMapByTableById(dbmsByTable);
+        return (await CommonDao.prepareMultiGetOutput(inputMap, dbmByTableById, opt));
+    }
+    static prepareMultiGetIds(inputMap) {
+        const idSetByTable = {};
+        for (const input of _stringMapValues(inputMap)) {
+            const { table } = input.dao.cfg;
+            idSetByTable[table] ||= new Set();
+            if ('id' in input) {
+                // Singular
+                idSetByTable[table].add(input.id);
+            }
+            else {
+                // Plural
+                for (const id of input.ids) {
+                    idSetByTable[table].add(id);
+                }
+            }
+        }
+        const idsByTable = {};
+        for (const [table, idSet] of _stringMapEntries(idSetByTable)) {
+            idsByTable[table] = [...idSet];
+        }
+        return idsByTable;
+    }
+    static multiGetMapByTableById(dbmsByTable) {
+        // We create this "map of maps", to be able to track the results back to the input props
+        // This is needed to support:
+        // - having multiple props from the same table
+        const dbmByTableById = {};
+        for (const [table, dbms] of _stringMapEntries(dbmsByTable)) {
+            dbmByTableById[table] ||= {};
+            for (const dbm of dbms) {
+                dbmByTableById[table][dbm.id] = dbm;
+            }
+        }
+        return dbmByTableById;
+    }
+    static async prepareMultiGetOutput(inputMap, dbmByTableById, opt = {}) {
+        const bmsByProp = {};
+        // Loop over input props again, to produce the output of the same shape as requested
+        await pMap(_stringMapEntries(inputMap), async ([prop, input]) => {
+            const { dao } = input;
             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);
+            if ('id' in input) {
+                // Singular
+                const dbm = dbmByTableById[table][input.id];
+                bmsByProp[prop] = (await dao.dbmToBM(dbm, opt)) || null;
+            }
+            else {
+                // Plural
+                // We apply filtering, to be able to support multiple input props fetching from the same table.
+                // Without filtering - every prop will get ALL rows from that table.
+                const dbms = input.ids.map(id => dbmByTableById[table][id]).filter(_isTruthy);
+                bmsByProp[prop] = await dao.dbmsToBM(dbms, opt);
             }
-            bmsByTable[table] = await dao.dbmsToBM(dbms, opt);
         });
-        return bmsByTable;
+        return bmsByProp;
     }
     /**
      * Very @experimental.
@@ -1050,9 +1084,9 @@ export class CommonDao {
         for (const { dao, ids } of inputs) {
             idsByTable[dao.cfg.table] = ids;
         }
-        return await db.multiDeleteByIds(idsByTable);
+        return await db.multiDelete(idsByTable);
     }
-    static async multiSaveBatch(inputs, opt = {}) {
+    static async multiSave(inputs, opt = {}) {
         if (!inputs.length)
             return;
         const { db } = inputs[0].dao.cfg;
@@ -1062,7 +1096,7 @@ export class CommonDao {
             rows.forEach(bm => dao.assignIdCreatedUpdated(bm, opt));
             dbmsByTable[table] = await dao.bmsToDBM(rows, opt);
         });
-        await db.multiSaveBatch(dbmsByTable);
+        await db.multiSave(dbmsByTable);
     }
     async createTransaction(opt) {
         const tx = await this.cfg.db.createTransaction(opt);
@@ -1217,6 +1251,7 @@ export class CommonDaoTransaction {
         Object.assign(bm, patch);
         return await dao.save(bm, { ...opt, skipIfEquals, tx: this.tx });
     }
+    // todo: use AnyDao/Infer in other methods as well, if this works well
     async deleteById(dao, id, opt) {
         if (!id)
             return 0;

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

@@ -1,11 +1,10 @@
 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, ObjectWithId, Promisable, UnixTimestamp } from '@naturalcycles/js-lib/types';
+import type { BaseDBEntity, 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.
@@ -333,15 +332,3 @@ export interface CommonDaoStreamOptions<IN> extends CommonDaoReadOptions, Transf
     chunkConcurrency?: number;
 }
 export type CommonDaoCreateOptions = CommonDBCreateOptions;
-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

@@ -28,7 +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>;
+    multiGet<ROW extends ObjectWithId>(_map: StringMap<string[]>, _opt?: CommonDBReadOptions): Promise<StringMap<ROW[]>>;
+    multiSave<ROW extends ObjectWithId>(_map: StringMap<ROW[]>, _opt?: CommonDBSaveOptions<ROW>): Promise<void>;
+    multiDelete(_map: StringMap<string[]>, _opt?: CommonDBOptions): Promise<number>;
 }

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

@@ -57,13 +57,13 @@ export class BaseCommonDB {
     async incrementBatch(_table, _prop, _incrementMap, _opt) {
         throw new Error('incrementBatch is not implemented');
     }
-    async multiGetByIds(_map, _opt) {
+    async multiGet(_map, _opt) {
         throw new Error('multiGetByIds is not implemented');
     }
-    async multiSaveBatch(_map, _opt) {
+    async multiSave(_map, _opt) {
         throw new Error('multiSaveBatch is not implemented');
     }
-    async multiDeleteByIds(_map, _opt) {
+    async multiDelete(_map, _opt) {
         throw new Error('multiDeleteByIds is not implemented');
     }
 }

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

@@ -3,14 +3,6 @@ import type { NonNegativeInteger, ObjectWithId, StringMap } from '@naturalcycles
 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';
-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.
@@ -64,7 +56,7 @@ export interface CommonDB {
      *
      * @experimental
      */
-    multiGetByIds: <ROW extends ObjectWithId>(idsByTable: StringMap<string[]>, opt?: CommonDBReadOptions) => Promise<StringMap<ROW[]>>;
+    multiGet: <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).
      */
@@ -88,7 +80,7 @@ export interface CommonDB {
      *
      * @experimental
      */
-    multiSaveBatch: <ROW extends ObjectWithId>(rowsByTable: StringMap<ROW[]>, opt?: CommonDBSaveOptions<ROW>) => Promise<void>;
+    multiSave: <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.
@@ -119,7 +111,7 @@ export interface CommonDB {
      *
      * @experimental
      */
-    multiDeleteByIds: (idsByTable: StringMap<string[]>, opt?: CommonDBOptions) => Promise<NonNegativeInteger>;
+    multiDelete: (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).
@@ -172,6 +164,10 @@ export interface CommonDB {
      */
     incrementBatch: (table: string, prop: string, incrementMap: StringMap<number>, opt?: CommonDBOptions) => Promise<StringMap<number>>;
 }
+export declare enum CommonDBType {
+    'document' = "document",
+    'relational' = "relational"
+}
 /**
  * Manifest of supported features.
  */

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

@@ -50,13 +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[]>>;
+    multiGet<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>;
+    multiSave<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>;
+    multiDelete(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,7 +74,7 @@ export class InMemoryDB {
         this.data[table] ||= {};
         return ids.map(id => this.data[table][id]).filter(Boolean);
     }
-    async multiGetByIds(map, _opt = {}) {
+    async multiGet(map, _opt = {}) {
         const result = {};
         for (const [tableName, ids] of _stringMapEntries(map)) {
             const table = this.cfg.tablesPrefix + tableName;
@@ -104,7 +104,7 @@ export class InMemoryDB {
             this.data[table][r.id] = JSON.parse(JSON.stringify(r), bufferReviver);
         }
     }
-    async multiSaveBatch(map, opt = {}) {
+    async multiSave(map, opt = {}) {
         for (const [table, rows] of _stringMapEntries(map)) {
             await this.saveBatch(table, rows, opt);
         }
@@ -134,7 +134,7 @@ export class InMemoryDB {
         }
         return count;
     }
-    async multiDeleteByIds(map, _opt) {
+    async multiDelete(map, _opt) {
         let count = 0;
         for (const [table, ids] of _stringMapEntries(map)) {
             count += await this.deleteByIds(table, ids, _opt);

package/dist/query/dbQuery.d.ts

@@ -87,7 +87,7 @@ export declare class DBQuery<ROW extends ObjectWithId> {
 /**
  * DBQuery that has additional method to support Fluent API style.
  */
-export declare class RunnableDBQuery<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, ID = BM['id']> extends DBQuery<DBM> {
+export declare class RunnableDBQuery<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, ID extends string = BM['id']> extends DBQuery<DBM> {
     dao: CommonDao<BM, DBM, ID>;
     /**
      * Pass `table` to override table.

package/package.json

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

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

@@ -1,19 +1,13 @@
 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,
-  ObjectWithId,
-  Promisable,
-  UnixTimestamp,
-} from '@naturalcycles/js-lib/types'
+import type { BaseDBEntity, 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']> {
   /**
@@ -404,18 +398,3 @@ export interface CommonDaoStreamOptions<IN>
 }
 
 export type CommonDaoCreateOptions = CommonDBCreateOptions
-
-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

@@ -14,14 +14,16 @@ import {
 } from '@naturalcycles/js-lib/object/object.util.js'
 import { pMap } from '@naturalcycles/js-lib/promise/pMap.js'
 import { _truncate } from '@naturalcycles/js-lib/string/string.util.js'
-import type {
-  AsyncIndexedMapper,
-  BaseDBEntity,
-  NonNegativeInteger,
-  ObjectWithId,
-  StringMap,
-  UnixTimestampMillis,
-  Unsaved,
+import {
+  _stringMapEntries,
+  _stringMapValues,
+  type AsyncIndexedMapper,
+  type BaseDBEntity,
+  type NonNegativeInteger,
+  type ObjectWithId,
+  type StringMap,
+  type UnixTimestampMillis,
+  type Unsaved,
 } from '@naturalcycles/js-lib/types'
 import { _passthroughPredicate, _typeCast, SKIP } from '@naturalcycles/js-lib/types'
 import { stringId } from '@naturalcycles/nodejs-lib'
@@ -52,9 +54,6 @@ import type {
   CommonDaoStreamForEachOptions,
   CommonDaoStreamOptions,
   CommonDaoStreamSaveOptions,
-  DaoWithId,
-  DaoWithIds,
-  DaoWithRows,
 } from './common.dao.model.js'
 import { CommonDaoLogLevel } from './common.dao.model.js'
 
@@ -65,7 +64,11 @@ import { CommonDaoLogLevel } from './common.dao.model.js'
  * BM = Backend model (optimized for API access)
  * TM = Transport model (optimized to be sent over the wire)
  */
-export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, ID = BM['id']> {
+export class CommonDao<
+  BM extends BaseDBEntity,
+  DBM extends BaseDBEntity = BM,
+  ID extends string = BM['id'],
+> {
   constructor(public cfg: CommonDaoCfg<BM, DBM, ID>) {
     this.cfg = {
       logLevel: CommonDaoLogLevel.NONE,
@@ -1261,85 +1264,131 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     await this.cfg.db.ping()
   }
 
-  id(id: string): DaoWithId {
+  withId(id: ID): DaoWithId<typeof this> {
     return {
       dao: this,
       id,
     }
   }
 
-  ids(ids: string[]): DaoWithIds {
+  withIds(ids: ID[]): DaoWithIds<typeof this> {
     return {
       dao: this,
       ids,
     }
   }
 
-  rows(rows: BM[]): DaoWithRows {
+  toSave(input: BM | BM[]): DaoWithRows<typeof this> {
     return {
       dao: this,
-      rows,
+      rows: [input].flat() as any[],
     }
   }
 
   /**
-   * Very @experimental.
+   * Load rows (by their ids) from Multiple tables at once.
+   * An optimized way to load data, minimizing DB round-trips.
+   *
+   * @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
-    })
+  static async multiGet<MAP extends Record<string, DaoWithIds<AnyDao> | DaoWithId<AnyDao>>>(
+    inputMap: MAP,
+    opt: CommonDaoReadOptions = {},
+  ): Promise<{
+    [K in keyof MAP]: MAP[K] extends DaoWithIds<any>
+      ? InferBM<MAP[K]['dao']>[]
+      : InferBM<MAP[K]['dao']> | null
+  }> {
+    const db = Object.values(inputMap)[0]?.dao.cfg.db
+    if (!db) {
+      return {} as any
+    }
+
+    const idsByTable = CommonDao.prepareMultiGetIds(inputMap)
+
+    // todo: support tx
+    const dbmsByTable = await db.multiGet(idsByTable, opt)
+
+    const dbmByTableById = CommonDao.multiGetMapByTableById(dbmsByTable)
 
-    return results as T
+    return (await CommonDao.prepareMultiGetOutput(inputMap, dbmByTableById, opt)) as any
   }
 
-  /**
-   * Very @experimental.
-   */
-  static async multiGetByIds(
-    inputs: DaoWithIds[],
-    opt: CommonDaoReadOptions = {},
-  ): Promise<StringMap<unknown[]>> {
-    if (!inputs.length) return {}
-    const { db } = inputs[0]!.dao.cfg
+  private static prepareMultiGetIds(
+    inputMap: StringMap<DaoWithIds<AnyDao> | DaoWithId<AnyDao>>,
+  ): StringMap<string[]> {
+    const idSetByTable: StringMap<Set<string>> = {}
+
+    for (const input of _stringMapValues(inputMap)) {
+      const { table } = input.dao.cfg
+      idSetByTable[table] ||= new Set()
+      if ('id' in input) {
+        // Singular
+        idSetByTable[table].add(input.id)
+      } else {
+        // Plural
+        for (const id of input.ids) {
+          idSetByTable[table].add(id)
+        }
+      }
+    }
+
     const idsByTable: StringMap<string[]> = {}
-    for (const { dao, ids } of inputs) {
-      const { table } = dao.cfg
-      idsByTable[table] = ids
+    for (const [table, idSet] of _stringMapEntries(idSetByTable)) {
+      idsByTable[table] = [...idSet]
+    }
+    return idsByTable
+  }
+
+  private static multiGetMapByTableById(
+    dbmsByTable: StringMap<ObjectWithId[]>,
+  ): StringMap<StringMap<ObjectWithId>> {
+    // We create this "map of maps", to be able to track the results back to the input props
+    // This is needed to support:
+    // - having multiple props from the same table
+    const dbmByTableById: StringMap<StringMap<ObjectWithId>> = {}
+    for (const [table, dbms] of _stringMapEntries(dbmsByTable)) {
+      dbmByTableById[table] ||= {}
+      for (const dbm of dbms) {
+        dbmByTableById[table][dbm.id] = dbm
+      }
     }
 
-    // todo: support tx
-    const dbmsByTable = await db.multiGetByIds(idsByTable, opt)
-    const bmsByTable: StringMap<unknown[]> = {}
+    return dbmByTableById
+  }
 
-    await pMap(inputs, async ({ dao }) => {
-      const { table } = dao.cfg
-      let dbms = dbmsByTable[table] || []
+  private static async prepareMultiGetOutput(
+    inputMap: StringMap<DaoWithIds<AnyDao> | DaoWithId<AnyDao>>,
+    dbmByTableById: StringMap<StringMap<ObjectWithId>>,
+    opt: CommonDaoReadOptions = {},
+  ): Promise<StringMap<unknown>> {
+    const bmsByProp: StringMap<unknown> = {}
 
-      if (dao.cfg.hooks!.afterLoad && dbms.length) {
-        dbms = (await pMap(dbms, async dbm => await dao.cfg.hooks!.afterLoad!(dbm))).filter(
-          _isTruthy,
-        )
+    // Loop over input props again, to produce the output of the same shape as requested
+    await pMap(_stringMapEntries(inputMap), async ([prop, input]) => {
+      const { dao } = input
+      const { table } = dao.cfg
+      if ('id' in input) {
+        // Singular
+        const dbm = dbmByTableById[table]![input.id]
+        bmsByProp[prop] = (await dao.dbmToBM(dbm, opt)) || null
+      } else {
+        // Plural
+        // We apply filtering, to be able to support multiple input props fetching from the same table.
+        // Without filtering - every prop will get ALL rows from that table.
+        const dbms = input.ids.map(id => dbmByTableById[table]![id]).filter(_isTruthy)
+        bmsByProp[prop] = await dao.dbmsToBM(dbms, opt)
       }
-
-      bmsByTable[table] = await dao.dbmsToBM(dbms, opt)
     })
 
-    return bmsByTable
+    return bmsByProp as any
   }
 
   /**
    * Very @experimental.
    */
   static async multiDeleteByIds(
-    inputs: DaoWithIds[],
+    inputs: DaoWithIds<any>[],
     _opt: CommonDaoOptions = {},
   ): Promise<NonNegativeInteger> {
     if (!inputs.length) return 0
@@ -1349,11 +1398,11 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
       idsByTable[dao.cfg.table] = ids
     }
 
-    return await db.multiDeleteByIds(idsByTable)
+    return await db.multiDelete(idsByTable)
   }
 
-  static async multiSaveBatch(
-    inputs: DaoWithRows[],
+  static async multiSave(
+    inputs: DaoWithRows<any>[],
     opt: CommonDaoSaveBatchOptions<any> = {},
   ): Promise<void> {
     if (!inputs.length) return
@@ -1365,7 +1414,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
       dbmsByTable[table] = await dao.bmsToDBM(rows, opt)
     })
 
-    await db.multiSaveBatch(dbmsByTable)
+    await db.multiSave(dbmsByTable)
   }
 
   async createTransaction(opt?: CommonDBTransactionOptions): Promise<CommonDaoTransaction> {
@@ -1506,7 +1555,7 @@ export class CommonDaoTransaction {
     }
   }
 
-  async getById<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(
+  async getById<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID extends string = BM['id']>(
     dao: CommonDao<BM, DBM, ID>,
     id?: ID | null,
     opt?: CommonDaoReadOptions,
@@ -1514,7 +1563,7 @@ export class CommonDaoTransaction {
     return await dao.getById(id, { ...opt, tx: this.tx })
   }
 
-  async getByIds<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(
+  async getByIds<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID extends string = BM['id']>(
     dao: CommonDao<BM, DBM, ID>,
     ids: ID[],
     opt?: CommonDaoReadOptions,
@@ -1559,7 +1608,7 @@ export class CommonDaoTransaction {
    *
    * So, this method is a rather simple convenience "Object.assign and then save".
    */
-  async patch<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(
+  async patch<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID extends string = BM['id']>(
     dao: CommonDao<BM, DBM, ID>,
     bm: BM,
     patch: Partial<BM>,
@@ -1570,20 +1619,42 @@ export class CommonDaoTransaction {
     return await dao.save(bm, { ...opt, skipIfEquals, tx: this.tx })
   }
 
-  async deleteById<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(
-    dao: CommonDao<BM, DBM, ID>,
-    id?: ID | null,
+  // todo: use AnyDao/Infer in other methods as well, if this works well
+  async deleteById<DAO extends AnyDao>(
+    dao: DAO,
+    id?: InferID<DAO> | null,
     opt?: CommonDaoOptions,
   ): Promise<number> {
     if (!id) return 0
     return await this.deleteByIds(dao, [id], opt)
   }
 
-  async deleteByIds<BM extends BaseDBEntity, DBM extends BaseDBEntity, ID = BM['id']>(
-    dao: CommonDao<BM, DBM, ID>,
-    ids: ID[],
+  async deleteByIds<DAO extends AnyDao>(
+    dao: DAO,
+    ids: InferID<DAO>[],
     opt?: CommonDaoOptions,
   ): Promise<number> {
     return await dao.deleteByIds(ids, { ...opt, tx: this.tx })
   }
 }
+
+export interface DaoWithIds<DAO extends AnyDao> {
+  dao: DAO
+  ids: string[]
+}
+
+export interface DaoWithId<DAO extends AnyDao> {
+  dao: DAO
+  id: string
+}
+
+export interface DaoWithRows<DAO extends AnyDao> {
+  dao: DAO
+  rows: InferBM<DAO>[]
+}
+
+type InferBM<DAO> = DAO extends CommonDao<infer BM> ? BM : never
+// type InferDBM<DAO> = DAO extends CommonDao<any, infer DBM> ? DBM : never
+type InferID<DAO> = DAO extends CommonDao<any, any, infer ID> ? ID : never
+
+export type AnyDao = CommonDao<any>

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

@@ -113,21 +113,21 @@ export class BaseCommonDB implements CommonDB {
     throw new Error('incrementBatch is not implemented')
   }
 
-  async multiGetByIds<ROW extends ObjectWithId>(
+  async multiGet<ROW extends ObjectWithId>(
     _map: StringMap<string[]>,
     _opt?: CommonDBReadOptions,
   ): Promise<StringMap<ROW[]>> {
     throw new Error('multiGetByIds is not implemented')
   }
 
-  async multiSaveBatch<ROW extends ObjectWithId>(
+  async multiSave<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> {
+  async multiDelete(_map: StringMap<string[]>, _opt?: CommonDBOptions): Promise<number> {
     throw new Error('multiDeleteByIds is not implemented')
   }
 }

package/src/commondb/common.db.ts

@@ -14,16 +14,6 @@ import type {
 } from '../db.model.js'
 import type { DBQuery } from '../query/dbQuery.js'
 
-export 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.
@@ -93,7 +83,7 @@ export interface CommonDB {
    *
    * @experimental
    */
-  multiGetByIds: <ROW extends ObjectWithId>(
+  multiGet: <ROW extends ObjectWithId>(
     idsByTable: StringMap<string[]>,
     opt?: CommonDBReadOptions,
   ) => Promise<StringMap<ROW[]>>
@@ -140,7 +130,7 @@ export interface CommonDB {
    *
    * @experimental
    */
-  multiSaveBatch: <ROW extends ObjectWithId>(
+  multiSave: <ROW extends ObjectWithId>(
     rowsByTable: StringMap<ROW[]>,
     opt?: CommonDBSaveOptions<ROW>,
   ) => Promise<void>
@@ -183,7 +173,7 @@ export interface CommonDB {
    *
    * @experimental
    */
-  multiDeleteByIds: (
+  multiDelete: (
     idsByTable: StringMap<string[]>,
     opt?: CommonDBOptions,
   ) => Promise<NonNegativeInteger>
@@ -258,6 +248,11 @@ export interface CommonDB {
   ) => Promise<StringMap<number>>
 }
 
+export enum CommonDBType {
+  'document' = 'document',
+  'relational' = 'relational',
+}
+
 /**
  * Manifest of supported features.
  */

package/src/inmemory/inMemory.db.ts

@@ -145,7 +145,7 @@ export class InMemoryDB implements CommonDB {
     return ids.map(id => this.data[table]![id] as ROW).filter(Boolean)
   }
 
-  async multiGetByIds<ROW extends ObjectWithId>(
+  async multiGet<ROW extends ObjectWithId>(
     map: StringMap<string[]>,
     _opt: CommonDBOptions = {},
   ): Promise<StringMap<ROW[]>> {
@@ -192,7 +192,7 @@ export class InMemoryDB implements CommonDB {
     }
   }
 
-  async multiSaveBatch<ROW extends ObjectWithId>(
+  async multiSave<ROW extends ObjectWithId>(
     map: StringMap<ROW[]>,
     opt: CommonDBSaveOptions<ROW> = {},
   ): Promise<void> {
@@ -239,7 +239,7 @@ export class InMemoryDB implements CommonDB {
     return count
   }
 
-  async multiDeleteByIds(map: StringMap<string[]>, _opt?: CommonDBOptions): Promise<number> {
+  async multiDelete(map: StringMap<string[]>, _opt?: CommonDBOptions): Promise<number> {
     let count = 0
 
     for (const [table, ids] of _stringMapEntries(map)) {

package/src/query/dbQuery.ts

@@ -236,7 +236,7 @@ export class DBQuery<ROW extends ObjectWithId> {
 export class RunnableDBQuery<
   BM extends BaseDBEntity,
   DBM extends BaseDBEntity = BM,
-  ID = BM['id'],
+  ID extends string = BM['id'],
 > extends DBQuery<DBM> {
   /**
    * Pass `table` to override table.