@naturalcycles/db-lib 10.10.1 → 10.12.0

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

@@ -2,9 +2,6 @@ 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 { ZodType } from '@naturalcycles/js-lib/zod';
-import { AjvSchema } from '@naturalcycles/nodejs-lib/ajv';
-import { type ObjectSchema } from '@naturalcycles/nodejs-lib/joi';
 import type { ReadableTyped } from '@naturalcycles/nodejs-lib/stream';
 import type { CommonDBTransactionOptions, DBTransaction, RunQueryResult } from '../db.model.js';
 import type { DBQuery } from '../query/dbQuery.js';
@@ -163,8 +160,7 @@ export declare class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity
      * Does NOT mutate the object.
      * Validates (unless `skipValidation=true` passed).
      */
-    validateAndConvert<T>(obj: Partial<T>, schema: ObjectSchema<T> | AjvSchema<T> | ZodType<T> | undefined, op?: 'load' | 'save', // this is to skip validation if validateOnLoad/Save is false
-    opt?: CommonDaoOptions): any;
+    private validateAndConvert;
     getTableSchema(): Promise<JsonSchemaRootObject<DBM>>;
     createTable(schema: JsonSchemaObject<DBM>, opt?: CommonDaoCreateOptions): Promise<void>;
     /**

package/dist/commondao/common.dao.js

@@ -8,10 +8,7 @@ import { _deepCopy, _filterUndefinedValues, _objectAssignExact, } from '@natural
 import { pMap } from '@naturalcycles/js-lib/promise/pMap.js';
 import { _truncate } from '@naturalcycles/js-lib/string/string.util.js';
 import { _passthroughPredicate, _typeCast, SKIP } from '@naturalcycles/js-lib/types';
-import { ZodType, zSafeValidate } from '@naturalcycles/js-lib/zod';
 import { stringId } from '@naturalcycles/nodejs-lib';
-import { AjvSchema } from '@naturalcycles/nodejs-lib/ajv';
-import { getValidationResult, } from '@naturalcycles/nodejs-lib/joi';
 import { _pipeline, transformChunk, transformLogProgress, transformMap, transformNoOp, writableVoid, } from '@naturalcycles/nodejs-lib/stream';
 import { DBLibError } from '../cnst.js';
 import { RunnableDBQuery } from '../query/dbQuery.js';
@@ -57,7 +54,7 @@ export class CommonDao {
         const bm = this.cfg.hooks.beforeCreate(part);
         // First assignIdCreatedUpdated, then validate!
         this.assignIdCreatedUpdated(bm, opt);
-        return this.validateAndConvert(bm, this.cfg.bmSchema, undefined, opt);
+        return this.validateAndConvert(bm, undefined, opt);
     }
     // GET
     // overrides are disabled now, as they obfuscate errors when ID branded type is used
@@ -592,7 +589,7 @@ export class CommonDao {
             // We compare with convertedBM, to account for cases when some extra property is assigned to bm,
             // which should be removed post-validation, but it breaks the "equality check"
             // Post-validation the equality check should work as intended
-            const convertedBM = this.validateAndConvert(bm, this.cfg.bmSchema, 'save', opt);
+            const convertedBM = this.validateAndConvert(bm, 'save', opt);
             if (_deepJsonEquals(convertedBM, opt.skipIfEquals)) {
                 // Skipping the save operation
                 return bm;
@@ -901,7 +898,7 @@ export class CommonDao {
         // DBM > BM
         const bm = ((await this.cfg.hooks.beforeDBMToBM?.(dbm)) || dbm);
         // Validate/convert BM
-        return this.validateAndConvert(bm, this.cfg.bmSchema, 'load', opt);
+        return this.validateAndConvert(bm, 'load', opt);
     }
     async dbmsToBM(dbms, opt = {}) {
         return await pMap(dbms, async (dbm) => await this.dbmToBM(dbm, opt));
@@ -910,7 +907,7 @@ export class CommonDao {
         if (bm === undefined)
             return;
         // bm gets assigned to the new reference
-        bm = this.validateAndConvert(bm, this.cfg.bmSchema, 'save', opt);
+        bm = this.validateAndConvert(bm, 'save', opt);
         // BM > DBM
         return ((await this.cfg.hooks.beforeBMToDBM?.(bm)) || bm);
     }
@@ -941,58 +938,26 @@ export class CommonDao {
      * Does NOT mutate the object.
      * Validates (unless `skipValidation=true` passed).
      */
-    validateAndConvert(obj, schema, op, // this is to skip validation if validateOnLoad/Save is false
+    validateAndConvert(input, op, // this is to skip validation if validateOnLoad/Save is false
     opt = {}) {
-        // Kirill 2021-10-18: I realized that there's little reason to keep removing null values
-        // So, from now on we'll preserve them
-        // "undefined" values, I believe, are/were not saved to/from DB anyway (due to e.g JSON.stringify removing them)
-        // But let's keep watching it!
-        //
-        // Filter null and undefined values
-        // obj = _filterNullishValues(obj as any)
         // We still filter `undefined` values here, because `beforeDBMToBM` can return undefined values
         // and they can be annoying with snapshot tests
-        obj = _filterUndefinedValues(obj);
+        input = _filterUndefinedValues(input);
         // Return as is if no schema is passed or if `skipConversion` is set
-        if ((!schema && !this.cfg.validateBM) ||
+        if (!this.cfg.validateBM ||
             opt.skipValidation ||
             (op === 'load' && !this.cfg.validateOnLoad) ||
             (op === 'save' && !this.cfg.validateOnSave)) {
-            return obj;
-        }
-        // This will Convert and Validate
-        const table = opt.table || this.cfg.table;
-        const objectName = table;
-        let error;
-        let convertedValue;
-        if (this.cfg.validateBM) {
-            const [err, value] = this.cfg.validateBM(obj, {
-                inputName: table,
-            });
-            error = err;
-            convertedValue = value;
-        }
-        else if (schema instanceof ZodType) {
-            // Zod schema
-            const [err, value] = zSafeValidate(obj, schema);
-            error = err;
-            convertedValue = value;
+            return input;
         }
-        else if (schema instanceof AjvSchema) {
-            // Ajv schema
-            const [err, value] = schema.getValidationResult(obj, {
-                objectName,
-            });
-            error = err;
-            convertedValue = value;
-        }
-        else {
-            // Joi
-            const [err, value] = getValidationResult(obj, schema, objectName);
-            error = err;
-            convertedValue = value;
-        }
-        // If we care about validation and there's an error
+        const inputName = opt.table || this.cfg.table;
+        const [error, convertedValue] = this.cfg.validateBM(input, {
+            // Passing `mutateInput` through allows to do opt-in mutation
+            // for individual operations, e.g `someDao.save(myObj, { mutateInput: true })`,
+            // while still keeping safe non-mutating behavior by default
+            mutateInput: opt.mutateInput,
+            inputName,
+        });
         if (error) {
             const processedError = this.cfg.hooks.onValidationError(error);
             if (processedError)

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

@@ -1,10 +1,7 @@
 import type { ValidationFunction } from '@naturalcycles/js-lib';
-import type { ErrorMode } from '@naturalcycles/js-lib/error';
+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 { ZodType, ZodValidationError } from '@naturalcycles/js-lib/zod';
-import type { AjvSchema, AjvValidationError } from '@naturalcycles/nodejs-lib/ajv';
-import type { JoiValidationError, ObjectSchema } from '@naturalcycles/nodejs-lib/joi';
 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';
@@ -79,7 +76,7 @@ export interface CommonDaoHooks<BM extends BaseDBEntity, DBM extends BaseDBEntit
      * Return original `err` to pass the error through (will be thrown in CommonDao).
      * Return modified/new `Error` if needed.
      */
-    onValidationError: (err: JoiValidationError | AjvValidationError | ZodValidationError) => Error | false;
+    onValidationError: (err: AppError) => Error | false;
 }
 export declare enum CommonDaoLogLevel {
     /**
@@ -102,17 +99,11 @@ export declare enum CommonDaoLogLevel {
 export interface CommonDaoCfg<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, ID = BM['id']> {
     db: CommonDB;
     table: string;
-    /**
-     * Joi, AjvSchema or ZodSchema is supported.
-     */
-    bmSchema?: ObjectSchema<BM> | AjvSchema<BM> | ZodType<BM>;
     /**
      * Experimental alternative to bmSchema.
      * "Bring your own validation function".
      * It removes the knowledge from CommonDao about the validation library used
      * and abstracts it away.
-     *
-     * @experimental
      */
     validateBM?: ValidationFunction<BM, any>;
     excludeFromIndexes?: (keyof DBM)[];
@@ -190,10 +181,22 @@ export interface CommonDaoOptions extends CommonDBOptions {
     /**
      * Defaults to false.
      *
-     * If set to true - will disable validation (and conversion).
-     * One possible use case of doing this is - performance (as validation/conversion takes time, especially with Joi).
+     * If set to true - will disable validation.
+     * One possible use case of doing this is - performance (as validation/transformation takes time, especially with Joi).
      */
     skipValidation?: boolean;
+    /**
+     * Default to false.
+     *
+     * False ensures that the input is not mutated by the Validation function (`validateBM`).
+     *
+     * True ensures the opposite - that the Validation function will mutate the input object
+     * if it needs to apply transformations, such as:
+     * - stripping unknown properties
+     * - converting types (e.g. string to number)
+     * - applying transformations (which as string trim, toLowerCase, etc)
+     */
+    mutateInput?: boolean;
     /**
      * @default false
      */

package/dist/testing/commonDaoTest.js

@@ -2,6 +2,7 @@ import { Readable } from 'node:stream';
 import { _sortBy } from '@naturalcycles/js-lib/array/array.util.js';
 import { localTime } from '@naturalcycles/js-lib/datetime/localTime.js';
 import { _deepCopy, _filterObject, _omit, _pick } from '@naturalcycles/js-lib/object';
+import { getJoiValidationFunction } from '@naturalcycles/nodejs-lib/joi';
 import { _pipeline } from '@naturalcycles/nodejs-lib/stream';
 import { CommonDao } from '../commondao/common.dao.js';
 import { CommonDaoLogLevel } from '../commondao/common.dao.model.js';
@@ -14,7 +15,7 @@ export async function runCommonDaoTest(db, quirks = {}) {
     const dao = new CommonDao({
         table: TEST_TABLE,
         db,
-        bmSchema: testItemBMSchema,
+        validateBM: getJoiValidationFunction(testItemBMSchema),
         logStarted: true,
         logLevel: CommonDaoLogLevel.DATA_FULL,
     });

package/package.json

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

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

@@ -1,5 +1,5 @@
 import type { ValidationFunction } from '@naturalcycles/js-lib'
-import type { ErrorMode } from '@naturalcycles/js-lib/error'
+import type { AppError, ErrorMode } from '@naturalcycles/js-lib/error'
 import type { CommonLogger } from '@naturalcycles/js-lib/log'
 import type {
   BaseDBEntity,
@@ -7,9 +7,6 @@ import type {
   Promisable,
   UnixTimestamp,
 } from '@naturalcycles/js-lib/types'
-import type { ZodType, ZodValidationError } from '@naturalcycles/js-lib/zod'
-import type { AjvSchema, AjvValidationError } from '@naturalcycles/nodejs-lib/ajv'
-import type { JoiValidationError, ObjectSchema } from '@naturalcycles/nodejs-lib/joi'
 import type {
   TransformLogProgressOptions,
   TransformMapOptions,
@@ -96,9 +93,7 @@ export interface CommonDaoHooks<BM extends BaseDBEntity, DBM extends BaseDBEntit
    * Return original `err` to pass the error through (will be thrown in CommonDao).
    * Return modified/new `Error` if needed.
    */
-  onValidationError: (
-    err: JoiValidationError | AjvValidationError | ZodValidationError,
-  ) => Error | false
+  onValidationError: (err: AppError) => Error | false
 }
 
 export enum CommonDaoLogLevel {
@@ -128,18 +123,11 @@ export interface CommonDaoCfg<
   db: CommonDB
   table: string
 
-  /**
-   * Joi, AjvSchema or ZodSchema is supported.
-   */
-  bmSchema?: ObjectSchema<BM> | AjvSchema<BM> | ZodType<BM>
-
   /**
    * Experimental alternative to bmSchema.
    * "Bring your own validation function".
    * It removes the knowledge from CommonDao about the validation library used
    * and abstracts it away.
-   *
-   * @experimental
    */
   validateBM?: ValidationFunction<BM, any>
 
@@ -233,11 +221,24 @@ export interface CommonDaoOptions extends CommonDBOptions {
   /**
    * Defaults to false.
    *
-   * If set to true - will disable validation (and conversion).
-   * One possible use case of doing this is - performance (as validation/conversion takes time, especially with Joi).
+   * If set to true - will disable validation.
+   * One possible use case of doing this is - performance (as validation/transformation takes time, especially with Joi).
    */
   skipValidation?: boolean
 
+  /**
+   * Default to false.
+   *
+   * False ensures that the input is not mutated by the Validation function (`validateBM`).
+   *
+   * True ensures the opposite - that the Validation function will mutate the input object
+   * if it needs to apply transformations, such as:
+   * - stripping unknown properties
+   * - converting types (e.g. string to number)
+   * - applying transformations (which as string trim, toLowerCase, etc)
+   */
+  mutateInput?: boolean
+
   /**
    * @default false
    */

package/src/commondao/common.dao.ts

@@ -23,15 +23,7 @@ import type {
   Unsaved,
 } from '@naturalcycles/js-lib/types'
 import { _passthroughPredicate, _typeCast, SKIP } from '@naturalcycles/js-lib/types'
-import type { ZodValidationError } from '@naturalcycles/js-lib/zod'
-import { ZodType, zSafeValidate } from '@naturalcycles/js-lib/zod'
 import { stringId } from '@naturalcycles/nodejs-lib'
-import { AjvSchema, type AjvValidationError } from '@naturalcycles/nodejs-lib/ajv'
-import {
-  getValidationResult,
-  type JoiValidationError,
-  type ObjectSchema,
-} from '@naturalcycles/nodejs-lib/joi'
 import type { ReadableTyped } from '@naturalcycles/nodejs-lib/stream'
 import {
   _pipeline,
@@ -102,7 +94,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     const bm = this.cfg.hooks!.beforeCreate!(part)
     // First assignIdCreatedUpdated, then validate!
     this.assignIdCreatedUpdated(bm, opt)
-    return this.validateAndConvert(bm, this.cfg.bmSchema, undefined, opt)
+    return this.validateAndConvert(bm, undefined, opt)
   }
 
   // GET
@@ -767,7 +759,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
       // We compare with convertedBM, to account for cases when some extra property is assigned to bm,
       // which should be removed post-validation, but it breaks the "equality check"
       // Post-validation the equality check should work as intended
-      const convertedBM = this.validateAndConvert(bm as Partial<BM>, this.cfg.bmSchema, 'save', opt)
+      const convertedBM = this.validateAndConvert(bm as Partial<BM>, 'save', opt)
       if (_deepJsonEquals(convertedBM, opt.skipIfEquals)) {
         // Skipping the save operation
         return bm as BM
@@ -1150,7 +1142,7 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     const bm = ((await this.cfg.hooks!.beforeDBMToBM?.(dbm)) || dbm) as Partial<BM>
 
     // Validate/convert BM
-    return this.validateAndConvert(bm, this.cfg.bmSchema, 'load', opt)
+    return this.validateAndConvert(bm, 'load', opt)
   }
 
   async dbmsToBM(dbms: DBM[], opt: CommonDaoOptions = {}): Promise<BM[]> {
@@ -1167,10 +1159,10 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
     if (bm === undefined) return
 
     // bm gets assigned to the new reference
-    bm = this.validateAndConvert(bm, this.cfg.bmSchema, 'save', opt)
+    bm = this.validateAndConvert(bm, 'save', opt)
 
     // BM > DBM
-    return ((await this.cfg.hooks!.beforeBMToDBM?.(bm!)) || bm) as DBM
+    return ((await this.cfg.hooks!.beforeBMToDBM?.(bm)) || bm) as DBM
   }
 
   async bmsToDBM(bms: BM[], opt: CommonDaoOptions = {}): Promise<DBM[]> {
@@ -1208,69 +1200,37 @@ export class CommonDao<BM extends BaseDBEntity, DBM extends BaseDBEntity = BM, I
    * Does NOT mutate the object.
    * Validates (unless `skipValidation=true` passed).
    */
-  validateAndConvert<T>(
-    obj: Partial<T>,
-    schema: ObjectSchema<T> | AjvSchema<T> | ZodType<T> | undefined,
+  private validateAndConvert(
+    input: Partial<BM>,
     op?: 'load' | 'save', // this is to skip validation if validateOnLoad/Save is false
     opt: CommonDaoOptions = {},
-  ): any {
-    // Kirill 2021-10-18: I realized that there's little reason to keep removing null values
-    // So, from now on we'll preserve them
-    // "undefined" values, I believe, are/were not saved to/from DB anyway (due to e.g JSON.stringify removing them)
-    // But let's keep watching it!
-    //
-    // Filter null and undefined values
-    // obj = _filterNullishValues(obj as any)
+  ): BM {
     // We still filter `undefined` values here, because `beforeDBMToBM` can return undefined values
     // and they can be annoying with snapshot tests
-    obj = _filterUndefinedValues(obj)
+    input = _filterUndefinedValues(input)
 
     // Return as is if no schema is passed or if `skipConversion` is set
     if (
-      (!schema && !this.cfg.validateBM) ||
+      !this.cfg.validateBM ||
       opt.skipValidation ||
       (op === 'load' && !this.cfg.validateOnLoad) ||
       (op === 'save' && !this.cfg.validateOnSave)
     ) {
-      return obj
+      return input as BM
     }
 
-    // This will Convert and Validate
-    const table = opt.table || this.cfg.table
-    const objectName = table
+    const inputName = opt.table || this.cfg.table
 
-    let error: JoiValidationError | AjvValidationError | ZodValidationError | null | undefined
-    let convertedValue: any
-
-    if (this.cfg.validateBM) {
-      const [err, value] = this.cfg.validateBM(obj as any as BM, {
-        inputName: table,
-      })
-      error = err
-      convertedValue = value
-    } else if (schema instanceof ZodType) {
-      // Zod schema
-      const [err, value] = zSafeValidate(obj as T, schema)
-      error = err
-      convertedValue = value
-    } else if (schema instanceof AjvSchema) {
-      // Ajv schema
-      const [err, value] = schema.getValidationResult(obj as T, {
-        objectName,
-      })
-      error = err
-      convertedValue = value
-    } else {
-      // Joi
-      const [err, value] = getValidationResult(obj, schema, objectName)
-      error = err
-      convertedValue = value
-    }
+    const [error, convertedValue] = this.cfg.validateBM(input as BM, {
+      // Passing `mutateInput` through allows to do opt-in mutation
+      // for individual operations, e.g `someDao.save(myObj, { mutateInput: true })`,
+      // while still keeping safe non-mutating behavior by default
+      mutateInput: opt.mutateInput,
+      inputName,
+    })
 
-    // If we care about validation and there's an error
     if (error) {
       const processedError = this.cfg.hooks!.onValidationError!(error)
-
       if (processedError) throw processedError
     }
 

package/src/testing/commonDaoTest.ts

@@ -2,6 +2,7 @@ import { Readable } from 'node:stream'
 import { _sortBy } from '@naturalcycles/js-lib/array/array.util.js'
 import { localTime } from '@naturalcycles/js-lib/datetime/localTime.js'
 import { _deepCopy, _filterObject, _omit, _pick } from '@naturalcycles/js-lib/object'
+import { getJoiValidationFunction } from '@naturalcycles/nodejs-lib/joi'
 import { _pipeline } from '@naturalcycles/nodejs-lib/stream'
 import { CommonDao } from '../commondao/common.dao.js'
 import { CommonDaoLogLevel } from '../commondao/common.dao.model.js'
@@ -28,7 +29,7 @@ export async function runCommonDaoTest(
   const dao = new CommonDao({
     table: TEST_TABLE,
     db,
-    bmSchema: testItemBMSchema,
+    validateBM: getJoiValidationFunction(testItemBMSchema),
     logStarted: true,
     logLevel: CommonDaoLogLevel.DATA_FULL,
   })