@naturalcycles/nodejs-lib 15.12.0 → 15.14.0

package/dist/validation/ajv/ajvSchema.d.ts

@@ -5,12 +5,19 @@ import type { Ajv } from 'ajv';
 import { AjvValidationError } from './ajvValidationError.js';
 export interface AjvValidationOptions {
     /**
-     * Defaults to false.
+     * Defaults to true,
+     * because that's how AJV works by default,
+     * and what gives it performance advantage.
+     * (Because we have found that deep-clone is surprisingly slow,
+     * nearly as slow as Joi validation).
      *
      * If set to true - AJV will mutate the input in case it needs to apply transformations
      * (strip unknown properties, convert types, etc).
      *
-     * If false - it will deep-clone the input to prevent its mutation. Will return the cloned/mutated object.
+     * If false - it will deep-clone (using JSON.stringify+parse) the input to prevent its mutation.
+     * Will return the cloned/mutated object.
+     * Please note that JSON.stringify+parse has side-effects,
+     * e.g it will transform Buffer into a weird object.
      */
     mutateInput?: boolean;
     inputName?: string;
@@ -57,6 +64,9 @@ export declare class AjvSchema<T = unknown> {
      * correctly for some reason.
      */
     static create<T>(schema: JsonSchemaBuilder<T> | JsonSchema<T> | AjvSchema<T>, cfg?: Partial<AjvSchemaCfg>): AjvSchema<T>;
+    /**
+     * @experimental
+     */
     static createFromZod<T>(zodSchema: ZodType<T>, cfg?: Partial<AjvSchemaCfg>): AjvSchema<T>;
     readonly cfg: AjvSchemaCfg;
     /**

package/dist/validation/ajv/ajvSchema.js

@@ -1,6 +1,6 @@
 import { _isObject, _lazyValue, } from '@naturalcycles/js-lib';
 import { JsonSchemaAnyBuilder } from '@naturalcycles/js-lib/json-schema';
-import { _filterNullishValues } from '@naturalcycles/js-lib/object';
+import { _deepCopy, _filterNullishValues } from '@naturalcycles/js-lib/object';
 import { _substringBefore } from '@naturalcycles/js-lib/string';
 import { z } from '@naturalcycles/js-lib/zod';
 import { _inspect } from '../../string/inspect.js';
@@ -51,6 +51,9 @@ export class AjvSchema {
         }
         return new AjvSchema(schema, cfg);
     }
+    /**
+     * @experimental
+     */
     static createFromZod(zodSchema, cfg) {
         const jsonSchema = z.toJSONSchema(zodSchema, { target: 'draft-7' });
         return new AjvSchema(jsonSchema, cfg);
@@ -71,12 +74,16 @@ export class AjvSchema {
         return output;
     }
     isValid(input, opt) {
+        // todo: we can make it both fast and non-mutating by using Ajv
+        // with "removeAdditional" and "useDefaults" disabled.
         const [err] = this.getValidationResult(input, opt);
         return !err;
     }
     getValidationResult(input, opt = {}) {
         const fn = this.getAJVValidateFunction();
-        const item = opt.mutateInput || typeof input !== 'object' ? input : structuredClone(input);
+        const item = opt.mutateInput !== false || typeof input !== 'object'
+            ? input // mutate
+            : _deepCopy(input); // not mutate
         const valid = fn(item); // mutates item
         if (valid)
             return [null, item];
@@ -87,6 +94,8 @@ export class AjvSchema {
             dataVar,
             separator,
         });
+        // Note: if we mutated the input already, e.g stripped unknown properties,
+        // the error message Input would contain already mutated object print, such as Input: {}
         const inputStringified = _inspect(input, { maxLen: 4000 });
         message = [message, 'Input: ' + inputStringified].join(separator);
         const err = new AjvValidationError(message, _filterNullishValues({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/nodejs-lib",
   "type": "module",
-  "version": "15.12.0",
+  "version": "15.14.0",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@types/js-yaml": "^4",

package/src/validation/ajv/ajvSchema.ts

@@ -6,7 +6,7 @@ import {
 } from '@naturalcycles/js-lib'
 import type { JsonSchema, JsonSchemaBuilder } from '@naturalcycles/js-lib/json-schema'
 import { JsonSchemaAnyBuilder } from '@naturalcycles/js-lib/json-schema'
-import { _filterNullishValues } from '@naturalcycles/js-lib/object'
+import { _deepCopy, _filterNullishValues } from '@naturalcycles/js-lib/object'
 import { _substringBefore } from '@naturalcycles/js-lib/string'
 import { z, type ZodType } from '@naturalcycles/js-lib/zod'
 import type { Ajv } from 'ajv'
@@ -16,12 +16,19 @@ import { getAjv } from './getAjv.js'
 
 export interface AjvValidationOptions {
   /**
-   * Defaults to false.
+   * Defaults to true,
+   * because that's how AJV works by default,
+   * and what gives it performance advantage.
+   * (Because we have found that deep-clone is surprisingly slow,
+   * nearly as slow as Joi validation).
    *
    * If set to true - AJV will mutate the input in case it needs to apply transformations
    * (strip unknown properties, convert types, etc).
    *
-   * If false - it will deep-clone the input to prevent its mutation. Will return the cloned/mutated object.
+   * If false - it will deep-clone (using JSON.stringify+parse) the input to prevent its mutation.
+   * Will return the cloned/mutated object.
+   * Please note that JSON.stringify+parse has side-effects,
+   * e.g it will transform Buffer into a weird object.
    */
   mutateInput?: boolean
   inputName?: string
@@ -108,6 +115,9 @@ export class AjvSchema<T = unknown> {
     return new AjvSchema<T>(schema as JsonSchema<T>, cfg)
   }
 
+  /**
+   * @experimental
+   */
   static createFromZod<T>(zodSchema: ZodType<T>, cfg?: Partial<AjvSchemaCfg>): AjvSchema<T> {
     const jsonSchema = z.toJSONSchema(zodSchema, { target: 'draft-7' })
     return new AjvSchema<T>(jsonSchema as JsonSchema<T>, cfg)
@@ -130,6 +140,8 @@ export class AjvSchema<T = unknown> {
   }
 
   isValid(input: T, opt?: AjvValidationOptions): boolean {
+    // todo: we can make it both fast and non-mutating by using Ajv
+    // with "removeAdditional" and "useDefaults" disabled.
     const [err] = this.getValidationResult(input, opt)
     return !err
   }
@@ -140,7 +152,10 @@ export class AjvSchema<T = unknown> {
   ): ValidationFunctionResult<T, AjvValidationError> {
     const fn = this.getAJVValidateFunction()
 
-    const item = opt.mutateInput || typeof input !== 'object' ? input : structuredClone(input)
+    const item =
+      opt.mutateInput !== false || typeof input !== 'object'
+        ? input // mutate
+        : _deepCopy(input) // not mutate
 
     const valid = fn(item) // mutates item
     if (valid) return [null, item]
@@ -158,6 +173,8 @@ export class AjvSchema<T = unknown> {
       separator,
     })
 
+    // Note: if we mutated the input already, e.g stripped unknown properties,
+    // the error message Input would contain already mutated object print, such as Input: {}
     const inputStringified = _inspect(input, { maxLen: 4000 })
     message = [message, 'Input: ' + inputStringified].join(separator)