@naturalcycles/db-lib 10.18.0 → 10.20.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 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 { CommonDBTransactionOptions, 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';
+import { CommonDaoTransaction } from './commonDaoTransaction.js';
 /**
  * Lowest common denominator API between supported Databases.
  *
@@ -14,27 +14,18 @@ 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;
-    getById(id?: ID | null, opt?: CommonDaoReadOptions): Promise<BM | null>;
+    requireById(id: ID, opt?: CommonDaoReadOptions): Promise<BM>;
+    requireByIdAsDBM(id: ID, opt?: CommonDaoReadOptions): Promise<DBM>;
     getByIdOrEmpty(id: ID, part?: Partial<BM>, opt?: CommonDaoReadOptions): Promise<BM>;
+    getById(id?: ID | null, opt?: CommonDaoReadOptions): Promise<BM | null>;
     getByIdAsDBM(id?: ID | null, opt?: CommonDaoReadOptions): Promise<DBM | null>;
     getByIds(ids: ID[], opt?: CommonDaoReadOptions): Promise<BM[]>;
     getByIdsAsDBM(ids: ID[], opt?: CommonDaoReadOptions): Promise<DBM[]>;
-    requireById(id: ID, opt?: CommonDaoReadOptions): Promise<BM>;
-    requireByIdAsDBM(id: ID, opt?: CommonDaoReadOptions): Promise<DBM>;
-    private throwRequiredError;
-    /**
-     * Throws if readOnly is true
-     */
-    private requireWriteAccess;
-    /**
-     * Throws if readOnly is true
-     */
-    private requireObjectMutability;
-    private ensureUniqueId;
+    private loadByIds;
     getBy(by: keyof DBM, value: any, limit?: number, opt?: CommonDaoReadOptions): Promise<BM[]>;
     getOneBy(by: keyof DBM, value: any, opt?: CommonDaoReadOptions): Promise<BM | null>;
     getAll(opt?: CommonDaoReadOptions): Promise<BM[]>;
@@ -75,9 +66,8 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
     streamQueryIdsForEach(q: DBQuery<DBM>, mapper: AsyncIndexedMapper<ID, void>, opt?: CommonDaoStreamForEachOptions<ID>): Promise<void>;
     /**
      * Mutates!
-     * "Returns", just to have a type of "Saved"
      */
-    assignIdCreatedUpdated<T extends BaseDBEntity>(obj: Partial<T>, opt?: CommonDaoOptions): T;
+    assignIdCreatedUpdated<T extends BaseDBEntity>(obj: Partial<T>, opt?: CommonDaoOptions): void;
     /**
      * Convenience method to replace 3 operations (loading+patching+saving) with one:
      *
@@ -110,6 +100,7 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
     saveAsDBM(dbm: Unsaved<DBM>, opt?: CommonDaoSaveOptions<BM, DBM>): Promise<DBM>;
     saveBatch(bms: Unsaved<BM>[], opt?: CommonDaoSaveBatchOptions<DBM>): Promise<BM[]>;
     saveBatchAsDBM(dbms: Unsaved<DBM>[], opt?: CommonDaoSaveBatchOptions<DBM>): Promise<DBM[]>;
+    private prepareSaveOptions;
     /**
      * "Streaming" is implemented by buffering incoming rows into **batches**
      * (of size opt.chunkSize, which defaults to 500),
@@ -142,19 +133,19 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
      * @experimental
      */
     incrementBatch(prop: keyof DBM, incrementMap: StringMap<number>, opt?: CommonDaoOptions): Promise<StringMap<number>>;
-    dbmToBM(_dbm: undefined, opt?: CommonDaoOptions): Promise<undefined>;
+    dbmToBM(_dbm: undefined, opt?: CommonDaoOptions): Promise<null>;
     dbmToBM(_dbm?: DBM, opt?: CommonDaoOptions): Promise<BM>;
     dbmsToBM(dbms: DBM[], opt?: CommonDaoOptions): Promise<BM[]>;
     /**
      * Mutates object with properties: id, created, updated.
      * Returns DBM (new reference).
      */
-    bmToDBM(bm: undefined, opt?: CommonDaoOptions): Promise<undefined>;
+    bmToDBM(bm: undefined, opt?: CommonDaoOptions): Promise<null>;
     bmToDBM(bm?: BM, opt?: CommonDaoOptions): Promise<DBM>;
     bmsToDBM(bms: BM[], opt?: CommonDaoOptions): Promise<DBM[]>;
-    anyToDBM(dbm: undefined, opt?: CommonDaoOptions): undefined;
+    anyToDBM(dbm: undefined, opt?: CommonDaoOptions): null;
     anyToDBM(dbm?: any, opt?: CommonDaoOptions): DBM;
-    anyToDBMs(entities: DBM[], opt?: CommonDaoOptions): DBM[];
+    anyToDBMs(rows: DBM[], opt?: CommonDaoOptions): DBM[];
     /**
      * Returns *converted value* (NOT the same reference).
      * Does NOT mutate the object.
@@ -167,32 +158,42 @@ 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>;
+    withId(id: ID): DaoWithId<typeof this>;
+    withIds(ids: ID[]): DaoWithIds<typeof this>;
+    withRows(rows: BM[]): DaoWithRows<typeof this>;
+    withRow(row: BM, opt?: DaoWithRowOptions<BM>): DaoWithRow<typeof this>;
     /**
-     * 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> | DaoWithRow<any>)[], opt?: CommonDaoSaveBatchOptions<any>): Promise<void>;
     createTransaction(opt?: CommonDBTransactionOptions): Promise<CommonDaoTransaction>;
     runInTransaction<T = void>(fn: CommonDaoTransactionFn<T>, opt?: CommonDBTransactionOptions): Promise<T>;
+    private ensureRequired;
+    /**
+     * Throws if readOnly is true
+     */
+    private requireWriteAccess;
+    /**
+     * Throws if readOnly is true
+     */
+    private requireObjectMutability;
     /**
      * Throws if query uses a property that is in `excludeFromIndexes` list.
      */
     private validateQueryIndexes;
-    protected logResult(started: UnixTimestampMillis, op: string, res: any, table: string): void;
-    protected logSaveResult(started: UnixTimestampMillis, op: string, table: string): void;
-    protected logStarted(op: string, table: string, force?: boolean): UnixTimestampMillis;
-    protected logSaveStarted(op: string, items: any, table: string): UnixTimestampMillis;
 }
 /**
  * Transaction is committed when the function returns resolved Promise (aka "returns normally").
@@ -200,36 +201,28 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
  * Transaction is rolled back when the function returns rejected Promise (aka "throws").
  */
 export type CommonDaoTransactionFn<T = void> = (tx: CommonDaoTransaction) => Promise<T>;
-/**
- * Transaction context.
- * Has similar API than CommonDao, but all operations are performed in the context of the transaction.
- */
-export declare class CommonDaoTransaction {
-    tx: DBTransaction;
-    private logger;
-    constructor(tx: DBTransaction, logger: CommonLogger);
-    /**
-     * Commits the underlying DBTransaction.
-     * May throw.
-     */
-    commit(): Promise<void>;
-    /**
-     * Perform a graceful rollback without throwing/re-throwing any error.
-     * 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[]>;
-    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[]>;
-    /**
-     * DaoTransaction.patch does not load from DB.
-     * It assumes the bm was previously loaded in the same Transaction, hence could not be
-     * concurrently modified. Hence it's safe to not sync with DB.
-     *
-     * 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>;
+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>[];
+}
+export interface DaoWithRow<DAO extends AnyDao> {
+    dao: DAO;
+    row: InferBM<DAO>;
+    opt?: DaoWithRowOptions<InferBM<DAO>>;
+}
+interface DaoWithRowOptions<BM extends BaseDBEntity> {
+    skipIfEquals?: BM;
 }
+export type InferBM<DAO> = DAO extends CommonDao<infer BM> ? BM : never;
+export type InferDBM<DAO> = DAO extends CommonDao<any, infer DBM> ? DBM : never;
+export type InferID<DAO> = DAO extends CommonDao<any, any, infer ID> ? ID : never;
+export type AnyDao = CommonDao<any>;
+export {};