@naturalcycles/nodejs-lib 15.87.0 → 15.89.0

package/dist/validation/ajv/getAjv.js

@@ -389,7 +389,7 @@ export function createAjv(opt) {
         validate: function validate(optionalValues, data, _schema, ctx) {
             if (!optionalValues)
                 return true;
-            _assert(ctx?.parentData && ctx.parentDataProperty !== undefined, 'You should only use `optional([x, y, z]) on a property of an object, or on an element of an array due to Ajv mutation issues.');
+            _assert(ctx?.parentData && ctx.parentDataProperty !== undefined, 'You should only use `optional([x, y, z])` on a property of an object, or on an element of an array due to Ajv mutation issues.');
             if (!optionalValues.includes(data))
                 return true;
             ctx.parentData[ctx.parentDataProperty] = undefined;
@@ -578,11 +578,51 @@ export function createAjv(opt) {
         validate: function validate(numberOfDigits, data, _schema, ctx) {
             if (!numberOfDigits)
                 return true;
-            _assert(ctx?.parentData && ctx.parentDataProperty !== undefined, 'You should only use `precision(n) on a property of an object, or on an element of an array due to Ajv mutation issues.');
+            _assert(ctx?.parentData && ctx.parentDataProperty !== undefined, 'You should only use `precision(n)` on a property of an object, or on an element of an array due to Ajv mutation issues.');
             ctx.parentData[ctx.parentDataProperty] = _round(data, 10 ** (-1 * numberOfDigits));
             return true;
         },
     });
+    ajv.addKeyword({
+        keyword: 'customValidations',
+        modifying: false,
+        errors: true,
+        schemaType: 'array',
+        validate: function validate(customValidations, data, _schema, ctx) {
+            if (!customValidations?.length)
+                return true;
+            for (const validator of customValidations) {
+                const error = validator(data);
+                if (error) {
+                    ;
+                    validate.errors = [
+                        {
+                            instancePath: ctx?.instancePath ?? '',
+                            message: error,
+                        },
+                    ];
+                    return false;
+                }
+            }
+            return true;
+        },
+    });
+    ajv.addKeyword({
+        keyword: 'customConversions',
+        modifying: true,
+        errors: false,
+        schemaType: 'array',
+        validate: function validate(customConversions, data, _schema, ctx) {
+            if (!customConversions?.length)
+                return true;
+            _assert(ctx?.parentData && ctx.parentDataProperty !== undefined, 'You should only use `convert()` on a property of an object, or on an element of an array due to Ajv mutation issues.');
+            for (const converter of customConversions) {
+                data = converter(data);
+            }
+            ctx.parentData[ctx.parentDataProperty] = data;
+            return true;
+        },
+    });
     return ajv;
 }
 const monthLengths = [0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];

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

@@ -161,6 +161,24 @@ export declare class JsonSchemaAnyBuilder<IN, OUT, Opt> extends JsonSchemaTermin
      * Locks the given schema chain and no other modification can be done to it.
      */
     final(): JsonSchemaTerminal<IN, OUT, Opt>;
+    /**
+     *
+     * @param validator A validator function that returns an error message or undefined.
+     *
+     * You may add multiple custom validators and they will be executed in the order you added them.
+     */
+    custom<OUT2 = OUT>(validator: CustomValidatorFn): JsonSchemaAnyBuilder<IN, OUT2, Opt>;
+    /**
+     *
+     * @param converter A converter function that returns a new value.
+     *
+     * You may add multiple converters and they will be executed in the order you added them,
+     * each converter receiving the result from the previous one.
+     *
+     * This feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     */
+    convert<OUT2>(converter: CustomConverterFn<OUT2>): JsonSchemaAnyBuilder<IN, OUT2, Opt>;
 }
 export declare class JsonSchemaStringBuilder<IN extends string | undefined = string, OUT = IN, Opt extends boolean = false> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
     constructor();
@@ -225,6 +243,18 @@ export interface JsonSchemaStringEmailOptions {
 }
 export declare class JsonSchemaIsoDateBuilder<Opt extends boolean = false> extends JsonSchemaAnyBuilder<string | IsoDate, IsoDate, Opt> {
     constructor();
+    /**
+     * @param optionalValues List of values that should be considered/converted as `undefined`.
+     *
+     * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     *
+     * Make sure this `optional()` call is at the end of your call chain.
+     *
+     * When `null` is included in optionalValues, the return type becomes `JsonSchemaTerminal`
+     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
+     */
+    optional<T extends readonly null[] | undefined = undefined>(optionalValues?: T): T extends readonly null[] ? JsonSchemaTerminal<string | IsoDate | undefined, IsoDate | undefined, true> : JsonSchemaIsoDateBuilder<true>;
     before(date: string): this;
     sameOrBefore(date: string): this;
     after(date: string): this;
@@ -520,6 +550,8 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
     };
     anyOfThese?: JsonSchema[];
     precision?: number;
+    customValidations?: CustomValidatorFn[];
+    customConversions?: CustomConverterFn<any>[];
 }
 declare function object(props: AnyObject): never;
 declare function object<IN extends AnyObject>(props: {
@@ -618,4 +650,6 @@ type TupleIn<T extends readonly JsonSchemaAnyBuilder<any, any, any>[]> = {
 type TupleOut<T extends readonly JsonSchemaAnyBuilder<any, any, any>[]> = {
     [K in keyof T]: T[K] extends JsonSchemaAnyBuilder<any, infer O, any> ? O : never;
 };
+export type CustomValidatorFn = (v: any) => string | undefined;
+export type CustomConverterFn<OUT> = (v: any) => OUT;
 export {};

package/dist/validation/ajv/jsonSchemaBuilder.js

@@ -3,7 +3,7 @@
 import { _isUndefined, _numberEnumValues, _stringEnumValues, getEnumType, } from '@naturalcycles/js-lib';
 import { _uniq } from '@naturalcycles/js-lib/array';
 import { _assert } from '@naturalcycles/js-lib/error';
-import { _deepCopy, _sortObject } from '@naturalcycles/js-lib/object';
+import { _sortObject } from '@naturalcycles/js-lib/object';
 import { _objectAssign, _typeCast, JWT_REGEX, } from '@naturalcycles/js-lib/types';
 import { BASE64URL_REGEX, COUNTRY_CODE_REGEX, CURRENCY_REGEX, IPV4_REGEX, IPV6_REGEX, LANGUAGE_TAG_REGEX, SEMVER_REGEX, SLUG_REGEX, URL_REGEX, UUID_REGEX, } from '../regexes.js';
 import { TIMEZONES } from '../timezones.js';
@@ -223,13 +223,13 @@ export class JsonSchemaTerminal {
      */
     build() {
         _assert(!(this.schema.optionalField && this.schema.default !== undefined), '.optional() and .default() should not be used together - the default value makes .optional() redundant and causes incorrect type inference');
-        const jsonSchema = _sortObject(JSON.parse(JSON.stringify(this.schema)), JSON_SCHEMA_ORDER);
+        const jsonSchema = _sortObject(deepCopyPreservingFunctions(this.schema), JSON_SCHEMA_ORDER);
         delete jsonSchema.optionalField;
         return jsonSchema;
     }
     clone() {
         const cloned = Object.create(Object.getPrototypeOf(this));
-        cloned.schema = _deepCopy(this.schema);
+        cloned.schema = deepCopyPreservingFunctions(this.schema);
         return cloned;
     }
     cloneAndUpdateSchema(schema) {
@@ -318,6 +318,34 @@ export class JsonSchemaAnyBuilder extends JsonSchemaTerminal {
     final() {
         return new JsonSchemaTerminal(this.schema);
     }
+    /**
+     *
+     * @param validator A validator function that returns an error message or undefined.
+     *
+     * You may add multiple custom validators and they will be executed in the order you added them.
+     */
+    custom(validator) {
+        const { customValidations = [] } = this.schema;
+        return this.cloneAndUpdateSchema({
+            customValidations: [...customValidations, validator],
+        });
+    }
+    /**
+     *
+     * @param converter A converter function that returns a new value.
+     *
+     * You may add multiple converters and they will be executed in the order you added them,
+     * each converter receiving the result from the previous one.
+     *
+     * This feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     */
+    convert(converter) {
+        const { customConversions = [] } = this.schema;
+        return this.cloneAndUpdateSchema({
+            customConversions: [...customConversions, converter],
+        });
+    }
 }
 export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
     constructor() {
@@ -480,6 +508,31 @@ export class JsonSchemaIsoDateBuilder extends JsonSchemaAnyBuilder {
             IsoDate: {},
         });
     }
+    /**
+     * @param optionalValues List of values that should be considered/converted as `undefined`.
+     *
+     * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     *
+     * Make sure this `optional()` call is at the end of your call chain.
+     *
+     * When `null` is included in optionalValues, the return type becomes `JsonSchemaTerminal`
+     * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
+     */
+    optional(optionalValues) {
+        if (!optionalValues) {
+            return super.optional();
+        }
+        _typeCast(optionalValues);
+        const newBuilder = new JsonSchemaTerminal({
+            anyOf: [
+                { type: 'null', optionalValues },
+                this.cloneAndUpdateSchema({ optionalField: true }).build(),
+            ],
+            optionalField: true,
+        });
+        return newBuilder;
+    }
     before(date) {
         return this.cloneAndUpdateSchema({ IsoDate: { before: date } });
     }
@@ -729,7 +782,7 @@ export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
     }
     extend(props) {
         const newBuilder = new JsonSchemaObjectBuilder();
-        _objectAssign(newBuilder.schema, _deepCopy(this.schema));
+        _objectAssign(newBuilder.schema, deepCopyPreservingFunctions(this.schema));
         const incomingSchemaBuilder = new JsonSchemaObjectBuilder(props);
         mergeJsonSchemaObjects(newBuilder.schema, incomingSchemaBuilder.schema);
         _objectAssign(newBuilder.schema, { hasIsOfTypeCheck: false });
@@ -838,7 +891,7 @@ export class JsonSchemaObjectInferringBuilder extends JsonSchemaAnyBuilder {
     }
     extend(props) {
         const newBuilder = new JsonSchemaObjectInferringBuilder();
-        _objectAssign(newBuilder.schema, _deepCopy(this.schema));
+        _objectAssign(newBuilder.schema, deepCopyPreservingFunctions(this.schema));
         const incomingSchemaBuilder = new JsonSchemaObjectInferringBuilder(props);
         mergeJsonSchemaObjects(newBuilder.schema, incomingSchemaBuilder.schema);
         // This extend function is not type-safe as it is inferring,
@@ -1057,3 +1110,22 @@ function hasNoObjectSchemas(schema) {
     }
     return false;
 }
+/**
+ * Deep copy that preserves functions in customValidations/customConversions.
+ * Unlike structuredClone, this handles function references (which only exist in those two properties).
+ */
+function deepCopyPreservingFunctions(obj) {
+    if (obj === null || typeof obj !== 'object')
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(deepCopyPreservingFunctions);
+    const copy = {};
+    for (const key of Object.keys(obj)) {
+        const value = obj[key];
+        copy[key] =
+            (key === 'customValidations' || key === 'customConversions') && Array.isArray(value)
+                ? [...value]
+                : deepCopyPreservingFunctions(value);
+    }
+    return copy;
+}

package/package.json

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

package/src/validation/ajv/getAjv.ts

@@ -6,6 +6,8 @@ import type { AnyObject } from '@naturalcycles/js-lib/types'
 import { Ajv2020, type Options, type ValidateFunction } from 'ajv/dist/2020.js'
 import { validTLDs } from '../tlds.js'
 import type {
+  CustomConverterFn,
+  CustomValidatorFn,
   JsonSchemaIsoDateOptions,
   JsonSchemaIsoMonthOptions,
   JsonSchemaStringEmailOptions,
@@ -450,7 +452,7 @@ export function createAjv(opt?: Options): Ajv2020 {
 
       _assert(
         ctx?.parentData && ctx.parentDataProperty !== undefined,
-        'You should only use `optional([x, y, z]) on a property of an object, or on an element of an array due to Ajv mutation issues.',
+        'You should only use `optional([x, y, z])` on a property of an object, or on an element of an array due to Ajv mutation issues.',
       )
 
       if (!optionalValues.includes(data)) return true
@@ -660,7 +662,7 @@ export function createAjv(opt?: Options): Ajv2020 {
 
       _assert(
         ctx?.parentData && ctx.parentDataProperty !== undefined,
-        'You should only use `precision(n) on a property of an object, or on an element of an array due to Ajv mutation issues.',
+        'You should only use `precision(n)` on a property of an object, or on an element of an array due to Ajv mutation issues.',
       )
 
       ctx.parentData[ctx.parentDataProperty] = _round(data, 10 ** (-1 * numberOfDigits))
@@ -669,6 +671,59 @@ export function createAjv(opt?: Options): Ajv2020 {
     },
   })
 
+  ajv.addKeyword({
+    keyword: 'customValidations',
+    modifying: false,
+    errors: true,
+    schemaType: 'array',
+    validate: function validate(customValidations: CustomValidatorFn[], data: any, _schema, ctx) {
+      if (!customValidations?.length) return true
+
+      for (const validator of customValidations) {
+        const error = validator(data)
+        if (error) {
+          ;(validate as any).errors = [
+            {
+              instancePath: ctx?.instancePath ?? '',
+              message: error,
+            },
+          ]
+          return false
+        }
+      }
+
+      return true
+    },
+  })
+
+  ajv.addKeyword({
+    keyword: 'customConversions',
+    modifying: true,
+    errors: false,
+    schemaType: 'array',
+    validate: function validate(
+      customConversions: CustomConverterFn<any>[],
+      data: any,
+      _schema,
+      ctx,
+    ) {
+      if (!customConversions?.length) return true
+
+      _assert(
+        ctx?.parentData && ctx.parentDataProperty !== undefined,
+        'You should only use `convert()` on a property of an object, or on an element of an array due to Ajv mutation issues.',
+      )
+
+      for (const converter of customConversions) {
+        data = converter(data)
+      }
+
+      ctx.parentData[ctx.parentDataProperty] = data
+
+      return true
+    },
+  })
+
   return ajv
 }
 

package/src/validation/ajv/jsonSchemaBuilder.ts

@@ -10,7 +10,7 @@ import {
 import { _uniq } from '@naturalcycles/js-lib/array'
 import { _assert } from '@naturalcycles/js-lib/error'
 import type { Set2 } from '@naturalcycles/js-lib/object'
-import { _deepCopy, _sortObject } from '@naturalcycles/js-lib/object'
+import { _sortObject } from '@naturalcycles/js-lib/object'
 import {
   _objectAssign,
   _typeCast,
@@ -338,7 +338,7 @@ export class JsonSchemaTerminal<IN, OUT, Opt> {
     )
 
     const jsonSchema = _sortObject(
-      JSON.parse(JSON.stringify(this.schema)),
+      deepCopyPreservingFunctions(this.schema) as AnyObject,
       JSON_SCHEMA_ORDER,
     ) as JsonSchema<IN, OUT>
 
@@ -349,7 +349,7 @@ export class JsonSchemaTerminal<IN, OUT, Opt> {
 
   clone(): this {
     const cloned = Object.create(Object.getPrototypeOf(this))
-    cloned.schema = _deepCopy(this.schema)
+    cloned.schema = deepCopyPreservingFunctions(this.schema)
     return cloned
   }
 
@@ -455,6 +455,36 @@ export class JsonSchemaAnyBuilder<IN, OUT, Opt> extends JsonSchemaTerminal<IN, O
   final(): JsonSchemaTerminal<IN, OUT, Opt> {
     return new JsonSchemaTerminal<IN, OUT, Opt>(this.schema)
   }
+
+  /**
+   *
+   * @param validator A validator function that returns an error message or undefined.
+   *
+   * You may add multiple custom validators and they will be executed in the order you added them.
+   */
+  custom<OUT2 = OUT>(validator: CustomValidatorFn): JsonSchemaAnyBuilder<IN, OUT2, Opt> {
+    const { customValidations = [] } = this.schema
+    return this.cloneAndUpdateSchema({
+      customValidations: [...customValidations, validator],
+    }) as unknown as JsonSchemaAnyBuilder<IN, OUT2, Opt>
+  }
+
+  /**
+   *
+   * @param converter A converter function that returns a new value.
+   *
+   * You may add multiple converters and they will be executed in the order you added them,
+   * each converter receiving the result from the previous one.
+   *
+   * This feature only works when the current schema is nested in an object or array schema,
+   * due to how mutability works in Ajv.
+   */
+  convert<OUT2>(converter: CustomConverterFn<OUT2>): JsonSchemaAnyBuilder<IN, OUT2, Opt> {
+    const { customConversions = [] } = this.schema
+    return this.cloneAndUpdateSchema({
+      customConversions: [...customConversions, converter],
+    }) as unknown as JsonSchemaAnyBuilder<IN, OUT2, Opt>
+  }
 }
 
 export class JsonSchemaStringBuilder<
@@ -673,6 +703,43 @@ export class JsonSchemaIsoDateBuilder<Opt extends boolean = false> extends JsonS
     })
   }
 
+  /**
+   * @param optionalValues List of values that should be considered/converted as `undefined`.
+   *
+   * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
+   * due to how mutability works in Ajv.
+   *
+   * Make sure this `optional()` call is at the end of your call chain.
+   *
+   * When `null` is included in optionalValues, the return type becomes `JsonSchemaTerminal`
+   * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
+   */
+  override optional<T extends readonly null[] | undefined = undefined>(
+    optionalValues?: T,
+  ): T extends readonly null[]
+    ? JsonSchemaTerminal<string | IsoDate | undefined, IsoDate | undefined, true>
+    : JsonSchemaIsoDateBuilder<true> {
+    if (!optionalValues) {
+      return super.optional() as any
+    }
+
+    _typeCast<null[]>(optionalValues)
+
+    const newBuilder = new JsonSchemaTerminal<
+      string | IsoDate | undefined,
+      IsoDate | undefined,
+      true
+    >({
+      anyOf: [
+        { type: 'null', optionalValues },
+        this.cloneAndUpdateSchema({ optionalField: true }).build(),
+      ],
+      optionalField: true,
+    })
+
+    return newBuilder as any
+  }
+
   before(date: string): this {
     return this.cloneAndUpdateSchema({ IsoDate: { before: date } })
   }
@@ -1051,7 +1118,7 @@ export class JsonSchemaObjectBuilder<
     false
   > {
     const newBuilder = new JsonSchemaObjectBuilder()
-    _objectAssign(newBuilder.schema, _deepCopy(this.schema))
+    _objectAssign(newBuilder.schema, deepCopyPreservingFunctions(this.schema))
 
     const incomingSchemaBuilder = new JsonSchemaObjectBuilder(props)
     mergeJsonSchemaObjects(newBuilder.schema as any, incomingSchemaBuilder.schema as any)
@@ -1305,7 +1372,7 @@ export class JsonSchemaObjectInferringBuilder<
     Opt
   > {
     const newBuilder = new JsonSchemaObjectInferringBuilder<PROPS, Opt>()
-    _objectAssign(newBuilder.schema, _deepCopy(this.schema))
+    _objectAssign(newBuilder.schema, deepCopyPreservingFunctions(this.schema))
 
     const incomingSchemaBuilder = new JsonSchemaObjectInferringBuilder<NEW_PROPS, false>(props)
     mergeJsonSchemaObjects(newBuilder.schema as any, incomingSchemaBuilder.schema as any)
@@ -1587,6 +1654,8 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
   }
   anyOfThese?: JsonSchema[]
   precision?: number
+  customValidations?: CustomValidatorFn[]
+  customConversions?: CustomConverterFn<any>[]
 }
 
 function object(props: AnyObject): never
@@ -1893,3 +1962,25 @@ type TupleIn<T extends readonly JsonSchemaAnyBuilder<any, any, any>[]> = {
 type TupleOut<T extends readonly JsonSchemaAnyBuilder<any, any, any>[]> = {
   [K in keyof T]: T[K] extends JsonSchemaAnyBuilder<any, infer O, any> ? O : never
 }
+
+export type CustomValidatorFn = (v: any) => string | undefined
+export type CustomConverterFn<OUT> = (v: any) => OUT
+
+/**
+ * Deep copy that preserves functions in customValidations/customConversions.
+ * Unlike structuredClone, this handles function references (which only exist in those two properties).
+ */
+function deepCopyPreservingFunctions<T>(obj: T): T {
+  if (obj === null || typeof obj !== 'object') return obj
+  if (Array.isArray(obj)) return obj.map(deepCopyPreservingFunctions) as T
+  const copy = {} as T
+  for (const key of Object.keys(obj)) {
+    const value = (obj as any)[key]
+    // customValidations/customConversions are arrays of functions - shallow copy the array
+    ;(copy as any)[key] =
+      (key === 'customValidations' || key === 'customConversions') && Array.isArray(value)
+        ? [...value]
+        : deepCopyPreservingFunctions(value)
+  }
+  return copy
+}