@naturalcycles/nodejs-lib 15.86.0 → 15.88.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;
@@ -417,6 +417,15 @@ export function createAjv(opt) {
             return validate;
         },
     });
+    // Validates that the value is undefined. Used in record/stringMap with optional value schemas
+    // to allow undefined values in patternProperties via anyOf.
+    ajv.addKeyword({
+        keyword: 'isUndefined',
+        modifying: false,
+        errors: false,
+        schemaType: 'boolean',
+        validate: (_schema, data) => data === undefined,
+    });
     // This is added because Ajv validates the `min/maxProperties` before validating the properties.
     // So, in case of `minProperties(1)` and `{ foo: 'bar' }` Ajv will let it pass, even
     // if the property validation would strip `foo` from the data.
@@ -569,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();
@@ -511,6 +529,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
     errorMessages?: StringMap<string>;
     optionalValues?: (string | number | boolean | null)[];
     keySchema?: JsonSchema;
+    isUndefined?: true;
     minProperties2?: number;
     exclusiveProperties?: (readonly string[])[];
     anyOfBy?: {
@@ -519,6 +538,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: {
@@ -617,4 +638,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';
@@ -32,11 +32,15 @@ export const j = {
             return j.object({}).allowAdditionalProperties();
         },
         stringMap(schema) {
+            const isValueOptional = schema.getSchema().optionalField;
             const builtSchema = schema.build();
+            const finalValueSchema = isValueOptional
+                ? { anyOf: [{ isUndefined: true }, builtSchema] }
+                : builtSchema;
             return new JsonSchemaObjectBuilder({}, {
                 hasIsOfTypeCheck: false,
                 patternProperties: {
-                    '^.+$': builtSchema,
+                    '^.+$': finalValueSchema,
                 },
             });
         },
@@ -219,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) {
@@ -314,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() {
@@ -725,7 +757,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 });
@@ -834,7 +866,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,
@@ -979,12 +1011,19 @@ function objectDbEntity(props) {
 }
 function record(keySchema, valueSchema) {
     const keyJsonSchema = keySchema.build();
+    // Check if value schema is optional before build() strips the optionalField flag
+    const isValueOptional = valueSchema.getSchema()
+        .optionalField;
     const valueJsonSchema = valueSchema.build();
+    // When value schema is optional, wrap in anyOf to allow undefined values
+    const finalValueSchema = isValueOptional
+        ? { anyOf: [{ isUndefined: true }, valueJsonSchema] }
+        : valueJsonSchema;
     return new JsonSchemaObjectBuilder([], {
         hasIsOfTypeCheck: false,
         keySchema: keyJsonSchema,
         patternProperties: {
-            ['^.*$']: valueJsonSchema,
+            ['^.*$']: finalValueSchema,
         },
     });
 }
@@ -1046,3 +1085,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.86.0",
+  "version": "15.88.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
@@ -486,6 +488,16 @@ export function createAjv(opt?: Options): Ajv2020 {
     },
   })
 
+  // Validates that the value is undefined. Used in record/stringMap with optional value schemas
+  // to allow undefined values in patternProperties via anyOf.
+  ajv.addKeyword({
+    keyword: 'isUndefined',
+    modifying: false,
+    errors: false,
+    schemaType: 'boolean',
+    validate: (_schema: boolean, data: unknown) => data === undefined,
+  })
+
   // This is added because Ajv validates the `min/maxProperties` before validating the properties.
   // So, in case of `minProperties(1)` and `{ foo: 'bar' }` Ajv will let it pass, even
   // if the property validation would strip `foo` from the data.
@@ -650,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))
@@ -659,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,
@@ -80,14 +80,18 @@ export const j = {
     stringMap<S extends JsonSchemaTerminal<any, any, any>>(
       schema: S,
     ): JsonSchemaObjectBuilder<StringMap<SchemaIn<S>>, StringMap<SchemaOut<S>>> {
+      const isValueOptional = schema.getSchema().optionalField
       const builtSchema = schema.build()
+      const finalValueSchema: JsonSchema = isValueOptional
+        ? { anyOf: [{ isUndefined: true }, builtSchema] }
+        : builtSchema
 
       return new JsonSchemaObjectBuilder<StringMap<SchemaIn<S>>, StringMap<SchemaOut<S>>>(
         {},
         {
           hasIsOfTypeCheck: false,
           patternProperties: {
-            '^.+$': builtSchema,
+            '^.+$': finalValueSchema,
           },
         },
       )
@@ -334,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>
 
@@ -345,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
   }
 
@@ -451,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<
@@ -1047,7 +1081,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)
@@ -1301,7 +1335,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)
@@ -1574,6 +1608,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
   errorMessages?: StringMap<string>
   optionalValues?: (string | number | boolean | null)[]
   keySchema?: JsonSchema
+  isUndefined?: true
   minProperties2?: number
   exclusiveProperties?: (readonly string[])[]
   anyOfBy?: {
@@ -1582,6 +1617,8 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
   }
   anyOfThese?: JsonSchema[]
   precision?: number
+  customValidations?: CustomValidatorFn[]
+  customConversions?: CustomConverterFn<any>[]
 }
 
 function object(props: AnyObject): never
@@ -1648,8 +1685,16 @@ function record<
   false
 > {
   const keyJsonSchema = keySchema.build()
+  // Check if value schema is optional before build() strips the optionalField flag
+  const isValueOptional = (valueSchema as JsonSchemaTerminal<any, any, any>).getSchema()
+    .optionalField
   const valueJsonSchema = valueSchema.build()
 
+  // When value schema is optional, wrap in anyOf to allow undefined values
+  const finalValueSchema: JsonSchema = isValueOptional
+    ? { anyOf: [{ isUndefined: true }, valueJsonSchema] }
+    : valueJsonSchema
+
   return new JsonSchemaObjectBuilder<
     Opt extends true
       ? Partial<Record<SchemaIn<KS>, SchemaIn<VS>>>
@@ -1662,7 +1707,7 @@ function record<
     hasIsOfTypeCheck: false,
     keySchema: keyJsonSchema,
     patternProperties: {
-      ['^.*$']: valueJsonSchema,
+      ['^.*$']: finalValueSchema,
     },
   })
 }
@@ -1880,3 +1925,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
+}