@naturalcycles/db-lib 8.51.1 → 8.53.0

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

@@ -1,4 +1,4 @@
-import { AnyObject, AsyncMapper, JsonSchemaObject, JsonSchemaRootObject, ObjectWithId, Saved, Unsaved, ZodSchema } from '@naturalcycles/js-lib';
+import { AnyObject, AsyncMapper, JsonSchemaObject, JsonSchemaRootObject, ObjectWithId, Promisable, Saved, Unsaved, ZodSchema } from '@naturalcycles/js-lib';
 import { AjvSchema, ObjectSchemaTyped, ReadableTyped } from '@naturalcycles/nodejs-lib';
 import { DBDeleteByIdsOperation, DBModelType, DBOperation, DBPatch, DBSaveBatchOperation, RunQueryResult } from '../db.model';
 import { DBQuery, RunnableDBQuery } from '../query/dbQuery';
@@ -85,9 +85,9 @@ export declare class CommonDao<BM extends Partial<ObjectWithId<ID>>, DBM extends
     assignIdCreatedUpdated(obj: Unsaved<BM>, opt?: CommonDaoOptions): Saved<BM>;
     tx: {
         save: (bm: Unsaved<BM>, opt?: CommonDaoSaveOptions<DBM>) => Promise<DBSaveBatchOperation>;
-        saveBatch: (bms: Unsaved<BM>[], opt?: CommonDaoSaveOptions<DBM>) => Promise<DBSaveBatchOperation>;
-        deleteByIds: (ids: ID[], opt?: CommonDaoOptions) => Promise<DBDeleteByIdsOperation>;
-        deleteById: (id: ID, opt?: CommonDaoOptions) => Promise<DBDeleteByIdsOperation>;
+        saveBatch: (bms: Unsaved<BM>[], opt?: CommonDaoSaveOptions<DBM>) => Promise<DBSaveBatchOperation | undefined>;
+        deleteByIds: (ids: ID[], opt?: CommonDaoOptions) => Promise<DBDeleteByIdsOperation | undefined>;
+        deleteById: (id: ID | null | undefined, opt?: CommonDaoOptions) => Promise<DBDeleteByIdsOperation | undefined>;
     };
     /**
      * Mutates with id, created, updated
@@ -139,9 +139,6 @@ export declare class CommonDao<BM extends Partial<ObjectWithId<ID>>, DBM extends
     bmToTM(bm: undefined, opt?: CommonDaoOptions): TM | undefined;
     bmToTM(bm?: Saved<BM>, opt?: CommonDaoOptions): TM;
     bmsToTM(bms: Saved<BM>[], opt?: CommonDaoOptions): TM[];
-    tmToBM(tm: undefined, opt?: CommonDaoOptions): undefined;
-    tmToBM(tm?: TM, opt?: CommonDaoOptions): BM;
-    tmsToBM(tms: TM[], opt?: CommonDaoOptions): BM[];
     /**
      * Returns *converted value*.
      * Validates (unless `skipValidation=true` passed).
@@ -155,7 +152,7 @@ export declare class CommonDao<BM extends Partial<ObjectWithId<ID>>, DBM extends
      * Proxy to this.cfg.db.ping
      */
     ping(): Promise<void>;
-    runInTransaction(ops: Promise<DBOperation>[]): Promise<void>;
+    runInTransaction(ops: Promisable<DBOperation | undefined>[]): Promise<void>;
     protected logResult(started: number, op: string, res: any, table: string): void;
     protected logSaveResult(started: number, op: string, table: string): void;
     protected logStarted(op: string, table: string, force?: boolean): number;

package/dist/commondao/common.dao.js

@@ -34,6 +34,8 @@ class CommonDao {
                 };
             },
             saveBatch: async (bms, opt = {}) => {
+                if (!bms.length)
+                    return;
                 const rows = (await this.saveBatch(bms, { ...opt, tx: true }));
                 return {
                     type: 'saveBatch',
@@ -46,6 +48,8 @@ class CommonDao {
                 };
             },
             deleteByIds: async (ids, opt = {}) => {
+                if (!ids.length)
+                    return;
                 return {
                     type: 'deleteByIds',
                     table: this.cfg.table,
@@ -54,6 +58,8 @@ class CommonDao {
                 };
             },
             deleteById: async (id, opt = {}) => {
+                if (!id)
+                    return;
                 return {
                     type: 'deleteByIds',
                     table: this.cfg.table,
@@ -80,7 +86,6 @@ class CommonDao {
                 beforeDBMValidate: dbm => dbm,
                 beforeDBMToBM: dbm => dbm,
                 beforeBMToDBM: bm => bm,
-                beforeTMToBM: tm => tm,
                 beforeBMToTM: bm => bm,
                 anonymize: dbm => dbm,
                 onValidationError: err => err,
@@ -784,22 +789,6 @@ class CommonDao {
         // try/catch?
         return bms.map(bm => this.bmToTM(bm, opt));
     }
-    tmToBM(tm, opt = {}) {
-        if (!tm)
-            return;
-        // optimization: 1 validation is enough
-        // Validate/convert TM
-        // bm gets assigned to the new reference
-        // tm = this.validateAndConvert(tm, this.cfg.tmSchema, DBModelType.TM, opt)
-        // TM > BM
-        const bm = this.cfg.hooks.beforeTMToBM(tm);
-        // Validate/convert BM
-        return this.validateAndConvert(bm, this.cfg.bmSchema, db_model_1.DBModelType.BM, opt);
-    }
-    tmsToBM(tms, opt = {}) {
-        // try/catch?
-        return tms.map(tm => this.tmToBM(tm, opt));
-    }
     /**
      * Returns *converted value*.
      * Validates (unless `skipValidation=true` passed).
@@ -879,9 +868,9 @@ class CommonDao {
         await this.cfg.db.ping();
     }
     async runInTransaction(ops) {
-        if (!ops.length)
+        const resolvedOps = (await Promise.all(ops)).filter(js_lib_1._isTruthy);
+        if (!resolvedOps.length)
             return;
-        const resolvedOps = await Promise.all(ops);
         await this.cfg.db.commitTransaction(dbTransaction_1.DBTransaction.create(resolvedOps));
     }
     logResult(started, op, res, table) {

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

@@ -3,19 +3,53 @@ import { AjvSchema, AjvValidationError, JoiValidationError, ObjectSchemaTyped, T
 import { CommonDB } from '../common.db';
 import { CommonDBCreateOptions, CommonDBOptions, CommonDBSaveOptions } from '../db.model';
 export interface CommonDaoHooks<BM extends Partial<ObjectWithId<ID>>, DBM extends ObjectWithId<ID>, TM, ID extends string | number> {
+    /**
+     * Allows to override the id generation function.
+     * By default it uses `stringId` from nodejs-lib
+     * (which uses lowercase alphanumberic alphabet and the size of 16).
+     */
     createRandomId: () => ID;
     /**
      * createNaturalId hook is called (tried) first.
      * If it doesn't exist - createRandomId is called.
      */
     createNaturalId: (obj: DBM | BM) => ID;
+    /**
+     * It's a counter-part of `createNaturalId`.
+     * Allows to provide a parser function to parse "natural id" into
+     * DBM components (e.g accountId and some other property that is part of the id).
+     */
     parseNaturalId: (id: ID) => Partial<DBM>;
+    /**
+     * It is called only on `dao.create` method.
+     * Dao.create method is called in:
+     *
+     * - getByIdOrEmpty, getByIdAsDBMOrEmpty
+     * - patch, patchAsDBM
+     */
     beforeCreate: (bm: Partial<BM>) => Partial<BM>;
+    /**
+     * Called when loading things "as DBM" and validation is not skipped.
+     * When loading things like BM/TM - other hooks get involved instead:
+     * - beforeDBMToBM
+     * - beforeBMToTM
+     *
+     * TODO: maybe rename those to `validateAs(model)`
+     * as it only validates "final state", not intermediate
+     */
     beforeDBMValidate: (dbm: Partial<DBM>) => Partial<DBM>;
     beforeDBMToBM: (dbm: DBM) => Partial<BM> | Promise<Partial<BM>>;
     beforeBMToDBM: (bm: BM) => Partial<DBM> | Promise<Partial<DBM>>;
-    beforeTMToBM: (tm: TM) => Partial<BM>;
     beforeBMToTM: (bm: BM) => Partial<TM>;
+    /**
+     * Called in:
+     * - dbmToBM (applied before DBM becomes BM)
+     * - anyToDBM
+     *
+     * Hook only allows to apply anonymization to DBM (not to BM).
+     * It still applies to BM "transitively", during dbmToBM
+     * (e.g after loaded from the Database).
+     */
     anonymize: (dbm: DBM) => DBM;
     /**
      * If hook is defined - allows to prevent or modify the error thrown.

package/package.json

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

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

@@ -23,19 +23,59 @@ export interface CommonDaoHooks<
   TM,
   ID extends string | number,
 > {
+  /**
+   * Allows to override the id generation function.
+   * By default it uses `stringId` from nodejs-lib
+   * (which uses lowercase alphanumberic alphabet and the size of 16).
+   */
   createRandomId: () => ID
+
   /**
    * createNaturalId hook is called (tried) first.
    * If it doesn't exist - createRandomId is called.
    */
   createNaturalId: (obj: DBM | BM) => ID
+
+  /**
+   * It's a counter-part of `createNaturalId`.
+   * Allows to provide a parser function to parse "natural id" into
+   * DBM components (e.g accountId and some other property that is part of the id).
+   */
   parseNaturalId: (id: ID) => Partial<DBM>
+
+  /**
+   * It is called only on `dao.create` method.
+   * Dao.create method is called in:
+   *
+   * - getByIdOrEmpty, getByIdAsDBMOrEmpty
+   * - patch, patchAsDBM
+   */
   beforeCreate: (bm: Partial<BM>) => Partial<BM>
+
+  /**
+   * Called when loading things "as DBM" and validation is not skipped.
+   * When loading things like BM/TM - other hooks get involved instead:
+   * - beforeDBMToBM
+   * - beforeBMToTM
+   *
+   * TODO: maybe rename those to `validateAs(model)`
+   * as it only validates "final state", not intermediate
+   */
   beforeDBMValidate: (dbm: Partial<DBM>) => Partial<DBM>
+
   beforeDBMToBM: (dbm: DBM) => Partial<BM> | Promise<Partial<BM>>
   beforeBMToDBM: (bm: BM) => Partial<DBM> | Promise<Partial<DBM>>
-  beforeTMToBM: (tm: TM) => Partial<BM>
   beforeBMToTM: (bm: BM) => Partial<TM>
+
+  /**
+   * Called in:
+   * - dbmToBM (applied before DBM becomes BM)
+   * - anyToDBM
+   *
+   * Hook only allows to apply anonymization to DBM (not to BM).
+   * It still applies to BM "transitively", during dbmToBM
+   * (e.g after loaded from the Database).
+   */
   anonymize: (dbm: DBM) => DBM
 
   /**

package/src/commondao/common.dao.ts

@@ -2,6 +2,7 @@ import {
   _assert,
   _filterNullishValues,
   _filterUndefinedValues,
+  _isTruthy,
   _passthroughPredicate,
   _since,
   _truncate,
@@ -14,6 +15,7 @@ import {
   JsonSchemaRootObject,
   ObjectWithId,
   pMap,
+  Promisable,
   Saved,
   Unsaved,
   ZodSchema,
@@ -93,7 +95,6 @@ export class CommonDao<
         beforeDBMValidate: dbm => dbm,
         beforeDBMToBM: dbm => dbm as any,
         beforeBMToDBM: bm => bm as any,
-        beforeTMToBM: tm => tm as any,
         beforeBMToTM: bm => bm as any,
         anonymize: dbm => dbm,
         onValidationError: err => err,
@@ -633,7 +634,8 @@ export class CommonDao<
     saveBatch: async (
       bms: Unsaved<BM>[],
       opt: CommonDaoSaveOptions<DBM> = {},
-    ): Promise<DBSaveBatchOperation> => {
+    ): Promise<DBSaveBatchOperation | undefined> => {
+      if (!bms.length) return
       const rows: DBM[] = (await this.saveBatch(bms, { ...opt, tx: true })) as any
 
       return {
@@ -646,7 +648,11 @@ export class CommonDao<
         },
       }
     },
-    deleteByIds: async (ids: ID[], opt: CommonDaoOptions = {}): Promise<DBDeleteByIdsOperation> => {
+    deleteByIds: async (
+      ids: ID[],
+      opt: CommonDaoOptions = {},
+    ): Promise<DBDeleteByIdsOperation | undefined> => {
+      if (!ids.length) return
       return {
         type: 'deleteByIds',
         table: this.cfg.table,
@@ -654,7 +660,11 @@ export class CommonDao<
         opt,
       }
     },
-    deleteById: async (id: ID, opt: CommonDaoOptions = {}): Promise<DBDeleteByIdsOperation> => {
+    deleteById: async (
+      id: ID | null | undefined,
+      opt: CommonDaoOptions = {},
+    ): Promise<DBDeleteByIdsOperation | undefined> => {
+      if (!id) return
       return {
         type: 'deleteByIds',
         table: this.cfg.table,
@@ -1050,28 +1060,6 @@ export class CommonDao<
     return bms.map(bm => this.bmToTM(bm, opt))
   }
 
-  tmToBM(tm: undefined, opt?: CommonDaoOptions): undefined
-  tmToBM(tm?: TM, opt?: CommonDaoOptions): BM
-  tmToBM(tm?: TM, opt: CommonDaoOptions = {}): BM | undefined {
-    if (!tm) return
-
-    // optimization: 1 validation is enough
-    // Validate/convert TM
-    // bm gets assigned to the new reference
-    // tm = this.validateAndConvert(tm, this.cfg.tmSchema, DBModelType.TM, opt)
-
-    // TM > BM
-    const bm = this.cfg.hooks!.beforeTMToBM!(tm) as BM
-
-    // Validate/convert BM
-    return this.validateAndConvert<BM>(bm, this.cfg.bmSchema, DBModelType.BM, opt)
-  }
-
-  tmsToBM(tms: TM[], opt: CommonDaoOptions = {}): BM[] {
-    // try/catch?
-    return tms.map(tm => this.tmToBM(tm, opt))
-  }
-
   /**
    * Returns *converted value*.
    * Validates (unless `skipValidation=true` passed).
@@ -1164,10 +1152,9 @@ export class CommonDao<
     await this.cfg.db.ping()
   }
 
-  async runInTransaction(ops: Promise<DBOperation>[]): Promise<void> {
-    if (!ops.length) return
-
-    const resolvedOps = await Promise.all(ops)
+  async runInTransaction(ops: Promisable<DBOperation | undefined>[]): Promise<void> {
+    const resolvedOps = (await Promise.all(ops)).filter(_isTruthy)
+    if (!resolvedOps.length) return
 
     await this.cfg.db.commitTransaction(DBTransaction.create(resolvedOps))
   }

package/src/db.model.ts

@@ -10,7 +10,6 @@ import { ObjectWithId } from '@naturalcycles/js-lib'
  */
 export type CommonDBSaveMethod = 'upsert' | 'insert' | 'update'
 
-// eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface CommonDBOptions {}
 
 /**