@naturalcycles/nodejs-lib 15.82.1 → 15.84.0

package/dist/stream/stream.model.d.ts

@@ -24,9 +24,9 @@ export interface ReadableTyped<T = unknown> extends Readable {
     take: (limit: number, opt?: ReadableSignalOptions) => ReadableTyped<T>;
     drop: (limit: number, opt?: ReadableSignalOptions) => ReadableTyped<T>;
 }
-export interface WritableTyped<T> extends Writable {
+export interface WritableTyped<_T> extends Writable {
 }
-export interface TransformTyped<IN = unknown, OUT = unknown> extends Transform {
+export interface TransformTyped<_IN = unknown, _OUT = unknown> extends Transform {
 }
 export interface TransformOptions {
     /**

package/dist/validation/ajv/getAjv.js

@@ -1,5 +1,6 @@
 import { _isBetween, _lazyValue } from '@naturalcycles/js-lib';
-import { _mapObject, Set2 } from '@naturalcycles/js-lib/object';
+import { _assert } from '@naturalcycles/js-lib/error';
+import { _deepCopy, _mapObject, Set2 } from '@naturalcycles/js-lib/object';
 import { _substringAfterLast } from '@naturalcycles/js-lib/string';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import { validTLDs } from '../tlds.js';
@@ -165,7 +166,7 @@ export function createAjv(opt) {
                     }
                     idx++;
                 }
-                if (ctx?.parentData && ctx.parentDataProperty) {
+                if (ctx?.parentData && ctx.parentDataProperty !== undefined) {
                     ctx.parentData[ctx.parentDataProperty] = set;
                 }
                 return true;
@@ -215,7 +216,7 @@ export function createAjv(opt) {
                     ];
                     return false;
                 }
-                if (ctx?.parentData && ctx.parentDataProperty) {
+                if (ctx?.parentData && ctx.parentDataProperty !== undefined) {
                     ctx.parentData[ctx.parentDataProperty] = buffer;
                 }
                 return true;
@@ -258,7 +259,7 @@ export function createAjv(opt) {
                     return false;
                 }
             }
-            if (ctx?.parentData && ctx.parentDataProperty) {
+            if (ctx?.parentData && ctx.parentDataProperty !== undefined) {
                 ctx.parentData[ctx.parentDataProperty] = cleanData;
             }
             return true;
@@ -381,18 +382,17 @@ export function createAjv(opt) {
     });
     ajv.addKeyword({
         keyword: 'optionalValues',
-        type: ['string', 'number', 'boolean'],
+        type: ['string', 'number', 'boolean', 'null'],
         modifying: true,
         errors: false,
         schemaType: 'array',
         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.');
             if (!optionalValues.includes(data))
                 return true;
-            if (ctx?.parentData && ctx.parentDataProperty) {
-                delete ctx.parentData[ctx.parentDataProperty];
-            }
+            ctx.parentData[ctx.parentDataProperty] = undefined;
             return true;
         },
     });
@@ -417,7 +417,7 @@ export function createAjv(opt) {
             return validate;
         },
     });
-    // This and `maxProperties2` are added because Ajv validates the `min/maxProperties` before validating the properties.
+    // 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.
     // And Ajv would return `{}` as a successful validation.
@@ -434,7 +434,7 @@ export function createAjv(opt) {
         validate: function validate(minProperties, data, _schema, ctx) {
             if (typeof data !== 'object')
                 return true;
-            const numberOfProperties = Object.getOwnPropertyNames(data).length;
+            const numberOfProperties = Object.entries(data).filter(([, v]) => v !== undefined).length;
             const isValid = numberOfProperties >= minProperties;
             if (!isValid) {
                 ;
@@ -513,6 +513,53 @@ export function createAjv(opt) {
             return validate;
         },
     });
+    ajv.addKeyword({
+        keyword: 'anyOfThese',
+        modifying: true,
+        errors: true,
+        schemaType: 'array',
+        compile(schemas, _parentSchema, _it) {
+            const validators = schemas.map(schema => ajv.compile(schema));
+            function validate(data, ctx) {
+                let correctValidator;
+                let result = false;
+                let clonedData;
+                // Try each validator until we find one that works!
+                for (const validator of validators) {
+                    clonedData = isPrimitive(data) ? _deepCopy(data) : data;
+                    result = validator(clonedData);
+                    if (result) {
+                        correctValidator = validator;
+                        break;
+                    }
+                }
+                if (result && ctx?.parentData && ctx.parentDataProperty !== undefined) {
+                    // If we found a validator and the data is valid and we are validating a property inside an object,
+                    // then we can inject our result and be done with it.
+                    ctx.parentData[ctx.parentDataProperty] = clonedData;
+                }
+                else if (result) {
+                    // If we found a validator but we are not validating a property inside an object,
+                    // then we must re-run the validation so that the mutations caused by Ajv
+                    // will be done on the input data, not only on the clone.
+                    result = correctValidator(data);
+                }
+                else {
+                    // If we didn't find a fitting schema,
+                    // we add our own error.
+                    ;
+                    validate.errors = [
+                        {
+                            instancePath: ctx?.instancePath ?? '',
+                            message: `could not find a suitable schema to validate against`,
+                        },
+                    ];
+                }
+                return result;
+            }
+            return validate;
+        },
+    });
     return ajv;
 }
 const monthLengths = [0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
@@ -652,3 +699,6 @@ function isIsoMonthValid(s) {
     const month = (s.charCodeAt(5) - ZERO_CODE) * 10 + (s.charCodeAt(6) - ZERO_CODE);
     return _isBetween(year, 1900, 2500, '[]') && _isBetween(month, 1, 12, '[]');
 }
+function isPrimitive(data) {
+    return data !== null && typeof data === 'object';
+}

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

@@ -68,7 +68,7 @@ export declare const j: {
     oneOf<B extends readonly JsonSchemaAnyBuilder<any, any, boolean>[], IN = BuilderInUnion<B>, OUT = BuilderOutUnion<B>>(items: [...B]): JsonSchemaAnyBuilder<IN, OUT, false>;
     /**
      * Use only with primitive values, otherwise this function will throw to avoid bugs.
-     * To validate objects, use `anyOfBy`.
+     * To validate objects, use `anyOfBy` or `anyOfThese`.
      *
      * Our Ajv is configured to strip unexpected properties from objects,
      * and since Ajv is mutating the input, this means that it cannot
@@ -78,7 +78,28 @@ export declare const j: {
      * Use `oneOf` when schemas are mutually exclusive.
      */
     anyOf<B extends readonly JsonSchemaAnyBuilder<any, any, boolean>[], IN = BuilderInUnion<B>, OUT = BuilderOutUnion<B>>(items: [...B]): JsonSchemaAnyBuilder<IN, OUT, false>;
+    /**
+     * Pick validation schema for an object based on the value of a specific property.
+     *
+     * ```
+     * const schemaMap = {
+     *   true: successSchema,
+     *   false: errorSchema
+     * }
+     *
+     * const schema = j.anyOfBy('success', schemaMap)
+     * ```
+     */
     anyOfBy<P extends string, D extends Record<PropertyKey, JsonSchemaTerminal<any, any, any>>, IN = AnyOfByIn<D>, OUT = AnyOfByOut<D>>(propertyName: P, schemaDictionary: D): JsonSchemaAnyOfByBuilder<IN, OUT, P>;
+    /**
+     * Custom version of `anyOf` which - in contrast to the original function - does not mutate the input.
+     * This comes with a performance penalty, so do not use it where performance matters.
+     *
+     * ```
+     * const schema = j.anyOfThese([successSchema, errorSchema])
+     * ```
+     */
+    anyOfThese<B extends readonly JsonSchemaAnyBuilder<any, any, boolean>[], IN = BuilderInUnion<B>, OUT = BuilderOutUnion<B>>(items: [...B]): JsonSchemaAnyBuilder<IN, OUT, false>;
     and(): {
         silentBob: () => never;
     };
@@ -148,8 +169,13 @@ export declare class JsonSchemaStringBuilder<IN extends string | undefined = str
      *
      * 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?: string[]): JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true>;
+    optional<T extends readonly (string | null)[] | undefined = undefined>(optionalValues?: T): T extends readonly (infer U)[] ? null extends U ? JsonSchemaTerminal<IN | undefined, OUT | undefined, true> : JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true> : JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true>;
     regex(pattern: RegExp, opt?: JsonBuilderRuleOpt): this;
     pattern(pattern: string, opt?: JsonBuilderRuleOpt): this;
     minLength(minLength: number): this;
@@ -223,8 +249,13 @@ export declare class JsonSchemaNumberBuilder<IN extends number | undefined = num
      *
      * 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?: number[]): JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true>;
+    optional<T extends readonly (number | null)[] | undefined = undefined>(optionalValues?: T): T extends readonly (infer U)[] ? null extends U ? JsonSchemaTerminal<IN | undefined, OUT | undefined, true> : JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true> : JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true>;
     integer(): this;
     branded<B extends number>(): JsonSchemaNumberBuilder<B, B, Opt>;
     multipleOf(multipleOf: number): this;
@@ -369,6 +400,10 @@ export declare class JsonSchemaAnyOfByBuilder<IN, OUT, _P extends string = strin
     in: IN;
     constructor(propertyName: string, schemaDictionary: Record<PropertyKey, JsonSchemaTerminal<any, any, any>>);
 }
+export declare class JsonSchemaAnyOfTheseBuilder<IN, OUT, _P extends string = string> extends JsonSchemaAnyBuilder<AnyOfByInput<IN, _P> | IN, OUT, false> {
+    in: IN;
+    constructor(propertyName: string, schemaDictionary: Record<PropertyKey, JsonSchemaTerminal<any, any, any>>);
+}
 type EnumBaseType = 'string' | 'number' | 'other';
 export interface JsonSchema<IN = unknown, OUT = IN> {
     readonly in?: IN;
@@ -432,7 +467,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
         truncate?: number;
     };
     errorMessages?: StringMap<string>;
-    optionalValues?: (string | number | boolean)[];
+    optionalValues?: (string | number | boolean | null)[];
     keySchema?: JsonSchema;
     minProperties2?: number;
     exclusiveProperties?: (readonly string[])[];
@@ -440,10 +475,11 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
         propertyName: string;
         schemaDictionary: Record<string, JsonSchema>;
     };
+    anyOfThese?: JsonSchema[];
 }
 declare function object(props: AnyObject): never;
 declare function object<IN extends AnyObject>(props: {
-    [K in keyof Required<IN>]-?: JsonSchemaAnyBuilder<any, IN[K], any>;
+    [K in keyof Required<IN>]-?: JsonSchemaTerminal<any, IN[K], any>;
 }): JsonSchemaObjectBuilder<IN, IN, false>;
 declare function objectInfer<P extends Record<string, JsonSchemaAnyBuilder<any, any, any>>>(props: P): JsonSchemaObjectInferringBuilder<P, false>;
 declare function objectDbEntity(props: AnyObject): never;

package/dist/validation/ajv/jsonSchemaBuilder.js

@@ -4,7 +4,7 @@ import { _isUndefined, _numberEnumValues, _stringEnumValues, getEnumType, } from
 import { _uniq } from '@naturalcycles/js-lib/array';
 import { _assert } from '@naturalcycles/js-lib/error';
 import { _deepCopy, _sortObject } from '@naturalcycles/js-lib/object';
-import { _objectAssign, JWT_REGEX, } from '@naturalcycles/js-lib/types';
+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';
 import { isEveryItemNumber, isEveryItemPrimitive, isEveryItemString, JSON_SCHEMA_ORDER, mergeJsonSchemaObjects, } from './jsonSchemaBuilder.util.js';
@@ -133,7 +133,7 @@ export const j = {
     },
     /**
      * Use only with primitive values, otherwise this function will throw to avoid bugs.
-     * To validate objects, use `anyOfBy`.
+     * To validate objects, use `anyOfBy` or `anyOfThese`.
      *
      * Our Ajv is configured to strip unexpected properties from objects,
      * and since Ajv is mutating the input, this means that it cannot
@@ -149,9 +149,34 @@ export const j = {
             anyOf: schemas,
         });
     },
+    /**
+     * Pick validation schema for an object based on the value of a specific property.
+     *
+     * ```
+     * const schemaMap = {
+     *   true: successSchema,
+     *   false: errorSchema
+     * }
+     *
+     * const schema = j.anyOfBy('success', schemaMap)
+     * ```
+     */
     anyOfBy(propertyName, schemaDictionary) {
         return new JsonSchemaAnyOfByBuilder(propertyName, schemaDictionary);
     },
+    /**
+     * Custom version of `anyOf` which - in contrast to the original function - does not mutate the input.
+     * This comes with a performance penalty, so do not use it where performance matters.
+     *
+     * ```
+     * const schema = j.anyOfThese([successSchema, errorSchema])
+     * ```
+     */
+    anyOfThese(items) {
+        return new JsonSchemaAnyBuilder({
+            anyOfThese: items.map(b => b.build()),
+        });
+    },
     and() {
         return {
             silentBob: () => {
@@ -301,17 +326,33 @@ export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
      *
      * 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();
         }
-        const newBuilder = new JsonSchemaStringBuilder().optional();
+        _typeCast(optionalValues);
+        let newBuilder = new JsonSchemaStringBuilder().optional();
         const alternativesSchema = j.enum(optionalValues);
         Object.assign(newBuilder.getSchema(), {
             anyOf: [this.build(), alternativesSchema.build()],
             optionalValues,
         });
+        // When `null` is specified, we want `null` to be stripped and the value to become `undefined`,
+        // so we must allow `null` values to be parsed by Ajv,
+        // but the typing should not reflect that.
+        // We also cannot accept more rules attached, since we're not building a StringSchema anymore.
+        if (optionalValues.includes(null)) {
+            newBuilder = new JsonSchemaTerminal({
+                anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
+                optionalField: true,
+            });
+        }
         return newBuilder;
     }
     regex(pattern, opt) {
@@ -477,17 +518,33 @@ export class JsonSchemaNumberBuilder extends JsonSchemaAnyBuilder {
      *
      * 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();
         }
-        const newBuilder = new JsonSchemaNumberBuilder().optional();
+        _typeCast(optionalValues);
+        let newBuilder = new JsonSchemaNumberBuilder().optional();
         const alternativesSchema = j.enum(optionalValues);
         Object.assign(newBuilder.getSchema(), {
             anyOf: [this.build(), alternativesSchema.build()],
             optionalValues,
         });
+        // When `null` is specified, we want `null` to be stripped and the value to become `undefined`,
+        // so we must allow `null` values to be parsed by Ajv,
+        // but the typing should not reflect that.
+        // We also cannot accept more rules attached, since we're not building a NumberSchema anymore.
+        if (optionalValues.includes(null)) {
+            newBuilder = new JsonSchemaTerminal({
+                anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
+                optionalField: true,
+            });
+        }
         return newBuilder;
     }
     integer() {
@@ -837,6 +894,22 @@ export class JsonSchemaAnyOfByBuilder extends JsonSchemaAnyBuilder {
         });
     }
 }
+export class JsonSchemaAnyOfTheseBuilder extends JsonSchemaAnyBuilder {
+    constructor(propertyName, schemaDictionary) {
+        const builtSchemaDictionary = {};
+        for (const [key, schema] of Object.entries(schemaDictionary)) {
+            builtSchemaDictionary[key] = schema.build();
+        }
+        super({
+            type: 'object',
+            hasIsOfTypeCheck: true,
+            anyOfBy: {
+                propertyName,
+                schemaDictionary: builtSchemaDictionary,
+            },
+        });
+    }
+}
 function object(props) {
     return new JsonSchemaObjectBuilder(props);
 }

package/package.json

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

package/src/stream/stream.model.ts

@@ -50,9 +50,11 @@ export interface ReadableTyped<T = unknown> extends Readable {
 }
 
 // oxlint-disable no-unused-vars
-export interface WritableTyped<T> extends Writable {}
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface WritableTyped<_T> extends Writable {}
 
-export interface TransformTyped<IN = unknown, OUT = unknown> extends Transform {}
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export interface TransformTyped<_IN = unknown, _OUT = unknown> extends Transform {}
 // oxlint-enable
 
 export interface TransformOptions {

package/src/validation/ajv/getAjv.ts

@@ -1,5 +1,6 @@
 import { _isBetween, _lazyValue } from '@naturalcycles/js-lib'
-import { _mapObject, Set2 } from '@naturalcycles/js-lib/object'
+import { _assert } from '@naturalcycles/js-lib/error'
+import { _deepCopy, _mapObject, Set2 } from '@naturalcycles/js-lib/object'
 import { _substringAfterLast } from '@naturalcycles/js-lib/string'
 import type { AnyObject } from '@naturalcycles/js-lib/types'
 import { Ajv2020, type Options, type ValidateFunction } from 'ajv/dist/2020.js'
@@ -195,7 +196,7 @@ export function createAjv(opt?: Options): Ajv2020 {
           idx++
         }
 
-        if (ctx?.parentData && ctx.parentDataProperty) {
+        if (ctx?.parentData && ctx.parentDataProperty !== undefined) {
           ctx.parentData[ctx.parentDataProperty] = set
         }
 
@@ -248,7 +249,7 @@ export function createAjv(opt?: Options): Ajv2020 {
           return false
         }
 
-        if (ctx?.parentData && ctx.parentDataProperty) {
+        if (ctx?.parentData && ctx.parentDataProperty !== undefined) {
           ctx.parentData[ctx.parentDataProperty] = buffer
         }
 
@@ -297,7 +298,7 @@ export function createAjv(opt?: Options): Ajv2020 {
         }
       }
 
-      if (ctx?.parentData && ctx.parentDataProperty) {
+      if (ctx?.parentData && ctx.parentDataProperty !== undefined) {
         ctx.parentData[ctx.parentDataProperty] = cleanData
       }
 
@@ -435,7 +436,7 @@ export function createAjv(opt?: Options): Ajv2020 {
 
   ajv.addKeyword({
     keyword: 'optionalValues',
-    type: ['string', 'number', 'boolean'],
+    type: ['string', 'number', 'boolean', 'null'],
     modifying: true,
     errors: false,
     schemaType: 'array',
@@ -447,11 +448,14 @@ export function createAjv(opt?: Options): Ajv2020 {
     ) {
       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.',
+      )
+
       if (!optionalValues.includes(data)) return true
 
-      if (ctx?.parentData && ctx.parentDataProperty) {
-        delete ctx.parentData[ctx.parentDataProperty]
-      }
+      ctx.parentData[ctx.parentDataProperty] = undefined
 
       return true
     },
@@ -482,7 +486,7 @@ export function createAjv(opt?: Options): Ajv2020 {
     },
   })
 
-  // This and `maxProperties2` are added because Ajv validates the `min/maxProperties` before validating the properties.
+  // 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.
   // And Ajv would return `{}` as a successful validation.
@@ -499,7 +503,7 @@ export function createAjv(opt?: Options): Ajv2020 {
     validate: function validate(minProperties: number, data: AnyObject, _schema, ctx) {
       if (typeof data !== 'object') return true
 
-      const numberOfProperties = Object.getOwnPropertyNames(data).length
+      const numberOfProperties = Object.entries(data).filter(([, v]) => v !== undefined).length
       const isValid = numberOfProperties >= minProperties
       if (!isValid) {
         ;(validate as any).errors = [
@@ -585,6 +589,56 @@ export function createAjv(opt?: Options): Ajv2020 {
     },
   })
 
+  ajv.addKeyword({
+    keyword: 'anyOfThese',
+    modifying: true,
+    errors: true,
+    schemaType: 'array',
+    compile(schemas: JsonSchemaTerminal<any, any, any>[], _parentSchema, _it) {
+      const validators = schemas.map(schema => ajv.compile(schema))
+
+      function validate(data: AnyObject, ctx: any): boolean {
+        let correctValidator: ValidateFunction<unknown> | undefined
+        let result = false
+        let clonedData: any
+
+        // Try each validator until we find one that works!
+        for (const validator of validators) {
+          clonedData = isPrimitive(data) ? _deepCopy(data) : data
+          result = validator(clonedData)
+          if (result) {
+            correctValidator = validator
+            break
+          }
+        }
+
+        if (result && ctx?.parentData && ctx.parentDataProperty !== undefined) {
+          // If we found a validator and the data is valid and we are validating a property inside an object,
+          // then we can inject our result and be done with it.
+          ctx.parentData[ctx.parentDataProperty] = clonedData
+        } else if (result) {
+          // If we found a validator but we are not validating a property inside an object,
+          // then we must re-run the validation so that the mutations caused by Ajv
+          // will be done on the input data, not only on the clone.
+          result = correctValidator!(data)
+        } else {
+          // If we didn't find a fitting schema,
+          // we add our own error.
+          ;(validate as any).errors = [
+            {
+              instancePath: ctx?.instancePath ?? '',
+              message: `could not find a suitable schema to validate against`,
+            },
+          ]
+        }
+
+        return result
+      }
+
+      return validate
+    },
+  })
+
   return ajv
 }
 
@@ -728,3 +782,7 @@ function isIsoMonthValid(s: string): boolean {
 
   return _isBetween(year, 1900, 2500, '[]') && _isBetween(month, 1, 12, '[]')
 }
+
+function isPrimitive(data: any): boolean {
+  return data !== null && typeof data === 'object'
+}

package/src/validation/ajv/jsonSchemaBuilder.ts

@@ -13,6 +13,7 @@ import type { Set2 } from '@naturalcycles/js-lib/object'
 import { _deepCopy, _sortObject } from '@naturalcycles/js-lib/object'
 import {
   _objectAssign,
+  _typeCast,
   type AnyObject,
   type BaseDBEntity,
   type IANATimezone,
@@ -217,7 +218,7 @@ export const j = {
 
   /**
    * Use only with primitive values, otherwise this function will throw to avoid bugs.
-   * To validate objects, use `anyOfBy`.
+   * To validate objects, use `anyOfBy` or `anyOfThese`.
    *
    * Our Ajv is configured to strip unexpected properties from objects,
    * and since Ajv is mutating the input, this means that it cannot
@@ -242,6 +243,18 @@ export const j = {
     })
   },
 
+  /**
+   * Pick validation schema for an object based on the value of a specific property.
+   *
+   * ```
+   * const schemaMap = {
+   *   true: successSchema,
+   *   false: errorSchema
+   * }
+   *
+   * const schema = j.anyOfBy('success', schemaMap)
+   * ```
+   */
   anyOfBy<
     P extends string,
     D extends Record<PropertyKey, JsonSchemaTerminal<any, any, any>>,
@@ -251,6 +264,24 @@ export const j = {
     return new JsonSchemaAnyOfByBuilder<IN, OUT, P>(propertyName, schemaDictionary)
   },
 
+  /**
+   * Custom version of `anyOf` which - in contrast to the original function - does not mutate the input.
+   * This comes with a performance penalty, so do not use it where performance matters.
+   *
+   * ```
+   * const schema = j.anyOfThese([successSchema, errorSchema])
+   * ```
+   */
+  anyOfThese<
+    B extends readonly JsonSchemaAnyBuilder<any, any, boolean>[],
+    IN = BuilderInUnion<B>,
+    OUT = BuilderOutUnion<B>,
+  >(items: [...B]): JsonSchemaAnyBuilder<IN, OUT, false> {
+    return new JsonSchemaAnyBuilder<IN, OUT, false>({
+      anyOfThese: items.map(b => b.build()),
+    })
+  },
+
   and() {
     return {
       silentBob: () => {
@@ -438,26 +469,45 @@ export class JsonSchemaStringBuilder<
    *
    * 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(
-    optionalValues?: string[],
-  ): JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true> {
+  override optional<T extends readonly (string | null)[] | undefined = undefined>(
+    optionalValues?: T,
+  ): T extends readonly (infer U)[]
+    ? null extends U
+      ? JsonSchemaTerminal<IN | undefined, OUT | undefined, true>
+      : JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true>
+    : JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true> {
     if (!optionalValues) {
-      return super.optional() as unknown as JsonSchemaStringBuilder<
-        IN | undefined,
-        OUT | undefined,
-        true
-      >
+      return super.optional() as any
     }
 
-    const newBuilder = new JsonSchemaStringBuilder<IN, OUT, Opt>().optional()
+    _typeCast<(string | null)[]>(optionalValues)
+
+    let newBuilder: JsonSchemaTerminal<IN | undefined, OUT | undefined, true> =
+      new JsonSchemaStringBuilder<IN, OUT, Opt>().optional()
     const alternativesSchema = j.enum(optionalValues)
     Object.assign(newBuilder.getSchema(), {
       anyOf: [this.build(), alternativesSchema.build()],
       optionalValues,
     })
 
-    return newBuilder
+    // When `null` is specified, we want `null` to be stripped and the value to become `undefined`,
+    // so we must allow `null` values to be parsed by Ajv,
+    // but the typing should not reflect that.
+    // We also cannot accept more rules attached, since we're not building a StringSchema anymore.
+    if (optionalValues.includes(null)) {
+      newBuilder = new JsonSchemaTerminal({
+        anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
+        optionalField: true,
+      })
+    }
+
+    return newBuilder as any
   }
 
   regex(pattern: RegExp, opt?: JsonBuilderRuleOpt): this {
@@ -686,27 +736,45 @@ export class JsonSchemaNumberBuilder<
    *
    * 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(
-    optionalValues?: number[],
-  ): JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true> {
+  override optional<T extends readonly (number | null)[] | undefined = undefined>(
+    optionalValues?: T,
+  ): T extends readonly (infer U)[]
+    ? null extends U
+      ? JsonSchemaTerminal<IN | undefined, OUT | undefined, true>
+      : JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true>
+    : JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true> {
     if (!optionalValues) {
-      return super.optional() as unknown as JsonSchemaNumberBuilder<
-        IN | undefined,
-        OUT | undefined,
-        true
-      >
+      return super.optional() as any
     }
 
-    const newBuilder = new JsonSchemaNumberBuilder<IN, OUT, Opt>().optional()
+    _typeCast<(number | null)[]>(optionalValues)
+
+    let newBuilder: JsonSchemaTerminal<IN | undefined, OUT | undefined, true> =
+      new JsonSchemaNumberBuilder<IN, OUT, Opt>().optional()
     const alternativesSchema = j.enum(optionalValues)
     Object.assign(newBuilder.getSchema(), {
       anyOf: [this.build(), alternativesSchema.build()],
       optionalValues,
     })
 
-    return newBuilder
+    // When `null` is specified, we want `null` to be stripped and the value to become `undefined`,
+    // so we must allow `null` values to be parsed by Ajv,
+    // but the typing should not reflect that.
+    // We also cannot accept more rules attached, since we're not building a NumberSchema anymore.
+    if (optionalValues.includes(null)) {
+      newBuilder = new JsonSchemaTerminal({
+        anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
+        optionalField: true,
+      })
+    }
+
+    return newBuilder as any
   }
 
   integer(): this {
@@ -1267,6 +1335,34 @@ export class JsonSchemaAnyOfByBuilder<
   }
 }
 
+export class JsonSchemaAnyOfTheseBuilder<
+  IN,
+  OUT,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  _P extends string = string,
+> extends JsonSchemaAnyBuilder<AnyOfByInput<IN, _P> | IN, OUT, false> {
+  declare in: IN
+
+  constructor(
+    propertyName: string,
+    schemaDictionary: Record<PropertyKey, JsonSchemaTerminal<any, any, any>>,
+  ) {
+    const builtSchemaDictionary: Record<string, JsonSchema> = {}
+    for (const [key, schema] of Object.entries(schemaDictionary)) {
+      builtSchemaDictionary[key] = schema.build()
+    }
+
+    super({
+      type: 'object',
+      hasIsOfTypeCheck: true,
+      anyOfBy: {
+        propertyName,
+        schemaDictionary: builtSchemaDictionary,
+      },
+    })
+  }
+}
+
 type EnumBaseType = 'string' | 'number' | 'other'
 
 export interface JsonSchema<IN = unknown, OUT = IN> {
@@ -1342,7 +1438,7 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
   instanceof?: string | string[]
   transform?: { trim?: true; toLowerCase?: true; toUpperCase?: true; truncate?: number }
   errorMessages?: StringMap<string>
-  optionalValues?: (string | number | boolean)[]
+  optionalValues?: (string | number | boolean | null)[]
   keySchema?: JsonSchema
   minProperties2?: number
   exclusiveProperties?: (readonly string[])[]
@@ -1350,15 +1446,16 @@ export interface JsonSchema<IN = unknown, OUT = IN> {
     propertyName: string
     schemaDictionary: Record<string, JsonSchema>
   }
+  anyOfThese?: JsonSchema[]
 }
 
 function object(props: AnyObject): never
 function object<IN extends AnyObject>(props: {
-  [K in keyof Required<IN>]-?: JsonSchemaAnyBuilder<any, IN[K], any>
+  [K in keyof Required<IN>]-?: JsonSchemaTerminal<any, IN[K], any>
 }): JsonSchemaObjectBuilder<IN, IN, false>
 
 function object<IN extends AnyObject>(props: {
-  [key in keyof IN]: JsonSchemaAnyBuilder<any, IN[key], any>
+  [key in keyof IN]: JsonSchemaTerminal<any, IN[key], any>
 }): JsonSchemaObjectBuilder<IN, IN, false> {
   return new JsonSchemaObjectBuilder<IN, IN, false>(props)
 }