@naturalcycles/nodejs-lib 15.93.0 → 15.95.0

package/dist/validation/ajv/{ajvSchema.js → jSchema.js}

@@ -1,6 +1,6 @@
 /* eslint-disable id-denylist */
 // oxlint-disable max-lines
-import { _isObject, _isUndefined, _lazyValue, _numberEnumValues, _stringEnumValues, getEnumType, } from '@naturalcycles/js-lib';
+import { _isObject, _isUndefined, _numberEnumValues, _stringEnumValues, getEnumType, } from '@naturalcycles/js-lib';
 import { _uniq } from '@naturalcycles/js-lib/array';
 import { _assert, _try } from '@naturalcycles/js-lib/error';
 import { _deepCopy, _filterNullishValues, _sortObject } from '@naturalcycles/js-lib/object';
@@ -12,314 +12,23 @@ import { TIMEZONES } from '../timezones.js';
 import { AjvValidationError } from './ajvValidationError.js';
 import { getAjv } from './getAjv.js';
 import { isEveryItemNumber, isEveryItemPrimitive, isEveryItemString, JSON_SCHEMA_ORDER, mergeJsonSchemaObjects, } from './jsonSchemaBuilder.util.js';
-// ==== AJV =====
-/**
- * On creation - compiles ajv validation function.
- * Provides convenient methods, error reporting, etc.
- */
-export class AjvSchema {
-    schema;
-    constructor(schema, cfg = {}) {
-        this.schema = schema;
-        this.cfg = {
-            lazy: false,
-            ...cfg,
-            ajv: cfg.ajv || getAjv(),
-            // Auto-detecting "InputName" from $id of the schema (e.g "Address.schema.json")
-            inputName: cfg.inputName || (schema.$id ? _substringBefore(schema.$id, '.') : undefined),
-        };
-        if (!cfg.lazy) {
-            this.getAJVValidateFunction(); // compile eagerly
-        }
-    }
-    /**
-     * Shortcut for AjvSchema.create(schema, { lazy: true })
-     */
-    static createLazy(schema, cfg) {
-        return AjvSchema.create(schema, {
-            lazy: true,
-            ...cfg,
-        });
-    }
-    /**
-     * Conveniently allows to pass either JsonSchema or JsonSchemaBuilder, or existing AjvSchema.
-     * If it's already an AjvSchema - it'll just return it without any processing.
-     * If it's a Builder - will call `build` before proceeding.
-     * Otherwise - will construct AjvSchema instance ready to be used.
-     *
-     * Implementation note: JsonSchemaBuilder goes first in the union type, otherwise TypeScript fails to infer <T> type
-     * correctly for some reason.
-     */
-    static create(schema, cfg) {
-        if (schema instanceof AjvSchema)
-            return schema;
-        if (AjvSchema.isSchemaWithCachedAjvSchema(schema)) {
-            return AjvSchema.requireCachedAjvSchema(schema);
-        }
-        let jsonSchema;
-        if (AjvSchema.isJsonSchemaBuilder(schema)) {
-            // oxlint-disable typescript-eslint(no-unnecessary-type-assertion)
-            jsonSchema = schema.build();
-            AjvSchema.requireValidJsonSchema(jsonSchema);
-        }
-        else {
-            jsonSchema = schema;
-        }
-        // This is our own helper which marks a schema as optional
-        // in case it is going to be used in an object schema,
-        // where we need to mark the given property as not-required.
-        // But once all compilation is done, the presence of this field
-        // really upsets Ajv.
-        delete jsonSchema.optionalField;
-        const ajvSchema = new AjvSchema(jsonSchema, cfg);
-        AjvSchema.cacheAjvSchema(schema, ajvSchema);
-        return ajvSchema;
-    }
-    static isJsonSchemaBuilder(schema) {
-        return schema instanceof JsonSchemaTerminal;
-    }
-    cfg;
-    /**
-     * It returns the original object just for convenience.
-     * Reminder: Ajv will MUTATE your object under 2 circumstances:
-     * 1. `useDefaults` option (enabled by default!), which will set missing/empty values that have `default` set in the schema.
-     * 2. `coerceTypes` (false by default).
-     *
-     * Returned object is always the same object (`===`) that was passed, so it is returned just for convenience.
-     */
-    validate(input, opt = {}) {
-        const [err, output] = this.getValidationResult(input, opt);
-        if (err)
-            throw err;
-        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 !== false || typeof input !== 'object'
-            ? input // mutate
-            : _deepCopy(input); // not mutate
-        let valid = fn(item); // mutates item, but not input
-        _typeCast(item);
-        let output = item;
-        if (valid && this.schema.postValidation) {
-            const [err, result] = _try(() => this.schema.postValidation(output));
-            if (err) {
-                valid = false;
-                fn.errors = [
-                    {
-                        instancePath: '',
-                        message: err.message,
-                    },
-                ];
-            }
-            else {
-                output = result;
-            }
-        }
-        if (valid)
-            return [null, output];
-        const errors = fn.errors;
-        const { inputId = _isObject(input) ? input['id'] : undefined, inputName = this.cfg.inputName || 'Object', } = opt;
-        const dataVar = [inputName, inputId].filter(Boolean).join('.');
-        this.applyImprovementsOnErrorMessages(errors);
-        let message = this.cfg.ajv.errorsText(errors, {
-            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: {}
-        // Unless `getOriginalInput` function is provided - then it will be used to preserve the Input pureness.
-        const inputStringified = _inspect(opt.getOriginalInput?.() || input, { maxLen: 4000 });
-        message = [message, 'Input: ' + inputStringified].join(separator);
-        const err = new AjvValidationError(message, _filterNullishValues({
-            errors,
-            inputName,
-            inputId,
-        }));
-        return [err, output];
-    }
-    getValidationFunction() {
-        return (input, opt) => {
-            return this.getValidationResult(input, {
-                mutateInput: opt?.mutateInput,
-                inputName: opt?.inputName,
-                inputId: opt?.inputId,
-            });
-        };
-    }
-    static isSchemaWithCachedAjvSchema(schema) {
-        return !!schema?.[HIDDEN_AJV_SCHEMA];
-    }
-    static cacheAjvSchema(schema, ajvSchema) {
-        return Object.assign(schema, { [HIDDEN_AJV_SCHEMA]: ajvSchema });
-    }
-    static requireCachedAjvSchema(schema) {
-        return schema[HIDDEN_AJV_SCHEMA];
-    }
-    getAJVValidateFunction = _lazyValue(() => this.cfg.ajv.compile(this.schema));
-    static requireValidJsonSchema(schema) {
-        // For object schemas we require that it is type checked against an external type, e.g.:
-        // interface Foo { name: string }
-        // const schema = j.object({ name: j.string() }).ofType<Foo>()
-        _assert(schema.type !== 'object' || schema.hasIsOfTypeCheck, 'The schema must be type checked against a type or interface, using the `.isOfType()` helper in `j`.');
-    }
-    applyImprovementsOnErrorMessages(errors) {
-        if (!errors)
-            return;
-        this.filterNullableAnyOfErrors(errors);
-        const { errorMessages } = this.schema;
-        for (const error of errors) {
-            const errorMessage = this.getErrorMessageForInstancePath(this.schema, error.instancePath, error.keyword);
-            if (errorMessage) {
-                error.message = errorMessage;
-            }
-            else if (errorMessages?.[error.keyword]) {
-                error.message = errorMessages[error.keyword];
-            }
-            else {
-                const unwrapped = unwrapNullableAnyOf(this.schema);
-                if (unwrapped?.errorMessages?.[error.keyword]) {
-                    error.message = unwrapped.errorMessages[error.keyword];
-                }
-            }
-            error.instancePath = error.instancePath.replaceAll(/\/(\d+)/g, `[$1]`).replaceAll('/', '.');
-        }
-    }
-    /**
-     * Filters out noisy errors produced by nullable anyOf patterns.
-     * When `nullable()` wraps a schema in `anyOf: [realSchema, { type: 'null' }]`,
-     * AJV produces "must be null" and "must match a schema in anyOf" errors
-     * that are confusing. This method splices them out, keeping only the real errors.
-     */
-    filterNullableAnyOfErrors(errors) {
-        // Collect exact schemaPaths to remove (anyOf aggregates) and prefixes (null branches)
-        const exactPaths = [];
-        const nullBranchPrefixes = [];
-        for (const error of errors) {
-            if (error.keyword !== 'anyOf')
-                continue;
-            const parentSchema = this.resolveSchemaPath(error.schemaPath);
-            if (!parentSchema)
-                continue;
-            const nullIndex = unwrapNullableAnyOfIndex(parentSchema);
-            if (nullIndex === -1)
-                continue;
-            exactPaths.push(error.schemaPath); // e.g. "#/anyOf"
-            const anyOfBase = error.schemaPath.slice(0, -'anyOf'.length);
-            nullBranchPrefixes.push(`${anyOfBase}anyOf/${nullIndex}/`); // e.g. "#/anyOf/1/"
-        }
-        if (!exactPaths.length)
-            return;
-        for (let i = errors.length - 1; i >= 0; i--) {
-            const sp = errors[i].schemaPath;
-            if (exactPaths.includes(sp) || nullBranchPrefixes.some(p => sp.startsWith(p))) {
-                errors.splice(i, 1);
-            }
-        }
-    }
-    /**
-     * Navigates the schema tree using an AJV schemaPath (e.g. "#/properties/foo/anyOf")
-     * and returns the parent schema containing the last keyword.
-     */
-    resolveSchemaPath(schemaPath) {
-        // schemaPath looks like "#/properties/foo/anyOf" or "#/anyOf"
-        // We want the schema that contains the final keyword (e.g. "anyOf")
-        const segments = schemaPath.replace(/^#\//, '').split('/');
-        // Remove the last segment (the keyword itself, e.g. "anyOf")
-        segments.pop();
-        let current = this.schema;
-        for (const segment of segments) {
-            if (!current || typeof current !== 'object')
-                return undefined;
-            current = current[segment];
-        }
-        return current;
-    }
-    getErrorMessageForInstancePath(schema, instancePath, keyword) {
-        if (!schema || !instancePath)
-            return undefined;
-        const segments = instancePath.split('/').filter(Boolean);
-        return this.traverseSchemaPath(schema, segments, keyword);
-    }
-    traverseSchemaPath(schema, segments, keyword) {
-        if (!segments.length)
-            return undefined;
-        const [currentSegment, ...remainingSegments] = segments;
-        const nextSchema = this.getChildSchema(schema, currentSegment);
-        if (!nextSchema)
-            return undefined;
-        if (nextSchema.errorMessages?.[keyword]) {
-            return nextSchema.errorMessages[keyword];
-        }
-        // Check through nullable wrapper
-        const unwrapped = unwrapNullableAnyOf(nextSchema);
-        if (unwrapped?.errorMessages?.[keyword]) {
-            return unwrapped.errorMessages[keyword];
-        }
-        if (remainingSegments.length) {
-            return this.traverseSchemaPath(nextSchema, remainingSegments, keyword);
-        }
-        return undefined;
-    }
-    getChildSchema(schema, segment) {
-        if (!segment)
-            return undefined;
-        // Unwrap nullable anyOf to find properties/items through nullable wrappers
-        const effectiveSchema = unwrapNullableAnyOf(schema) ?? schema;
-        if (/^\d+$/.test(segment) && effectiveSchema.items) {
-            return this.getArrayItemSchema(effectiveSchema, segment);
-        }
-        return this.getObjectPropertySchema(effectiveSchema, segment);
-    }
-    getArrayItemSchema(schema, indexSegment) {
-        if (!schema.items)
-            return undefined;
-        if (Array.isArray(schema.items)) {
-            return schema.items[Number(indexSegment)];
-        }
-        return schema.items;
-    }
-    getObjectPropertySchema(schema, segment) {
-        return schema.properties?.[segment];
-    }
-}
-function unwrapNullableAnyOf(schema) {
-    const nullIndex = unwrapNullableAnyOfIndex(schema);
-    if (nullIndex === -1)
-        return undefined;
-    return schema.anyOf[1 - nullIndex];
-}
-function unwrapNullableAnyOfIndex(schema) {
-    if (schema.anyOf?.length !== 2)
-        return -1;
-    const nullIndex = schema.anyOf.findIndex(s => s.type === 'null');
-    return nullIndex;
-}
-const separator = '\n';
-export const HIDDEN_AJV_SCHEMA = Symbol('HIDDEN_AJV_SCHEMA');
-// ===== JsonSchemaBuilders ===== //
+// ==== j (factory object) ====
 export const j = {
     /**
      * Matches literally any value - equivalent to TypeScript's `any` type.
      * Use sparingly, as it bypasses type validation entirely.
      */
     any() {
-        return new JsonSchemaAnyBuilder({});
+        return new JBuilder({});
     },
     string() {
-        return new JsonSchemaStringBuilder();
+        return new JString();
     },
     number() {
-        return new JsonSchemaNumberBuilder();
+        return new JNumber();
     },
     boolean() {
-        return new JsonSchemaBooleanBuilder();
+        return new JBoolean();
     },
     object: Object.assign(object, {
         dbEntity: objectDbEntity,
@@ -333,7 +42,7 @@ export const j = {
             const finalValueSchema = isValueOptional
                 ? { anyOf: [{ isUndefined: true }, builtSchema] }
                 : builtSchema;
-            return new JsonSchemaObjectBuilder({}, {
+            return new JObject({}, {
                 hasIsOfTypeCheck: false,
                 patternProperties: {
                     '^.+$': finalValueSchema,
@@ -376,16 +85,18 @@ export const j = {
         withRegexKeys,
     }),
     array(itemSchema) {
-        return new JsonSchemaArrayBuilder(itemSchema);
+        return new JArray(itemSchema);
     },
     tuple(items) {
-        return new JsonSchemaTupleBuilder(items);
+        return new JTuple(items);
     },
     set(itemSchema) {
-        return new JsonSchemaSet2Builder(itemSchema);
+        return new JSet2Builder(itemSchema);
     },
     buffer() {
-        return new JsonSchemaBufferBuilder();
+        return new JBuilder({
+            Buffer: true,
+        });
     },
     enum(input, opt) {
         let enumValues;
@@ -411,7 +122,7 @@ export const j = {
             }
         }
         _assert(enumValues, 'Unsupported enum input');
-        return new JsonSchemaEnumBuilder(enumValues, baseType, opt);
+        return new JEnum(enumValues, baseType, opt);
     },
     /**
      * Use only with primitive values, otherwise this function will throw to avoid bugs.
@@ -427,7 +138,7 @@ export const j = {
     oneOf(items) {
         const schemas = items.map(b => b.build());
         _assert(schemas.every(hasNoObjectSchemas), 'Do not use `oneOf` validation with non-primitive types!');
-        return new JsonSchemaAnyBuilder({
+        return new JBuilder({
             oneOf: schemas,
         });
     },
@@ -445,7 +156,7 @@ export const j = {
     anyOf(items) {
         const schemas = items.map(b => b.build());
         _assert(schemas.every(hasNoObjectSchemas), 'Do not use `anyOf` validation with non-primitive types!');
-        return new JsonSchemaAnyBuilder({
+        return new JBuilder({
             anyOf: schemas,
         });
     },
@@ -462,7 +173,18 @@ export const j = {
      * ```
      */
     anyOfBy(propertyName, schemaDictionary) {
-        return new JsonSchemaAnyOfByBuilder(propertyName, schemaDictionary);
+        const builtSchemaDictionary = {};
+        for (const [key, schema] of Object.entries(schemaDictionary)) {
+            builtSchemaDictionary[key] = schema.build();
+        }
+        return new JBuilder({
+            type: 'object',
+            hasIsOfTypeCheck: true,
+            anyOfBy: {
+                propertyName,
+                schemaDictionary: builtSchemaDictionary,
+            },
+        });
     },
     /**
      * Custom version of `anyOf` which - in contrast to the original function - does not mutate the input.
@@ -473,7 +195,7 @@ export const j = {
      * ```
      */
     anyOfThese(items) {
-        return new JsonSchemaAnyBuilder({
+        return new JBuilder({
             anyOfThese: items.map(b => b.build()),
         });
     },
@@ -490,13 +212,21 @@ export const j = {
             baseType = 'string';
         if (typeof v === 'number')
             baseType = 'number';
-        return new JsonSchemaEnumBuilder([v], baseType);
+        return new JEnum([v], baseType);
+    },
+    /**
+     * Create a JSchema from a plain JsonSchema object.
+     * Useful when the schema is loaded from a JSON file or generated externally.
+     *
+     * Optionally accepts a custom Ajv instance and/or inputName for error messages.
+     */
+    fromSchema(schema, cfg) {
+        return new JSchema(schema, cfg);
     },
 };
-const TS_2500 = 16725225600; // 2500-01-01
-const TS_2500_MILLIS = TS_2500 * 1000;
-const TS_2000 = 946684800; // 2000-01-01
-const TS_2000_MILLIS = TS_2000 * 1000;
+// ==== Symbol for caching compiled AjvSchema ====
+export const HIDDEN_AJV_SCHEMA = Symbol('HIDDEN_AJV_SCHEMA');
+// ==== JSchema (locked base) ====
 /*
   Notes for future reference
 
@@ -505,17 +235,41 @@ const TS_2000_MILLIS = TS_2000 * 1000;
      which means that the `foo` property would be mandatory, it's just that its value can be `undefined` as well.
      With `Opt`, we can infer it as `{ foo?: string | undefined }`.
 */
-export class JsonSchemaTerminal {
+export class JSchema {
     [HIDDEN_AJV_SCHEMA];
     schema;
-    constructor(schema) {
+    _cfg;
+    constructor(schema, cfg) {
         this.schema = schema;
-    }
-    get ajvSchema() {
-        if (!this[HIDDEN_AJV_SCHEMA]) {
-            this[HIDDEN_AJV_SCHEMA] = AjvSchema.create(this);
+        this._cfg = cfg;
+    }
+    _builtSchema;
+    _compiledFns;
+    _getBuiltSchema() {
+        if (!this._builtSchema) {
+            const builtSchema = this.build();
+            if (this instanceof JBuilder) {
+                _assert(builtSchema.type !== 'object' || builtSchema.hasIsOfTypeCheck, 'The schema must be type checked against a type or interface, using the `.isOfType()` helper in `j`.');
+            }
+            delete builtSchema.optionalField;
+            this._builtSchema = builtSchema;
+        }
+        return this._builtSchema;
+    }
+    _getCompiled(overrideAjv) {
+        const builtSchema = this._getBuiltSchema();
+        const ajv = overrideAjv ?? this._cfg?.ajv ?? getAjv();
+        this._compiledFns ??= new WeakMap();
+        let fn = this._compiledFns.get(ajv);
+        if (!fn) {
+            fn = ajv.compile(builtSchema);
+            this._compiledFns.set(ajv, fn);
+            // Cache AjvSchema wrapper for HIDDEN_AJV_SCHEMA backward compat (default ajv only)
+            if (!overrideAjv) {
+                this[HIDDEN_AJV_SCHEMA] = AjvSchema._wrap(builtSchema, fn);
+            }
         }
-        return this[HIDDEN_AJV_SCHEMA];
+        return { fn, builtSchema };
     }
     getSchema() {
         return this.schema;
@@ -533,6 +287,7 @@ export class JsonSchemaTerminal {
     clone() {
         const cloned = Object.create(Object.getPrototypeOf(this));
         cloned.schema = deepCopyPreservingFunctions(this.schema);
+        cloned._cfg = this._cfg;
         return cloned;
     }
     cloneAndUpdateSchema(schema) {
@@ -541,16 +296,29 @@ export class JsonSchemaTerminal {
         return clone;
     }
     validate(input, opt) {
-        return this.ajvSchema.validate(input, opt);
+        const [err, output] = this.getValidationResult(input, opt);
+        if (err)
+            throw err;
+        return output;
     }
     isValid(input, opt) {
-        return this.ajvSchema.isValid(input, opt);
+        const [err] = this.getValidationResult(input, opt);
+        return !err;
     }
     getValidationResult(input, opt = {}) {
-        return this.ajvSchema.getValidationResult(input, opt);
+        const { fn, builtSchema } = this._getCompiled(opt.ajv);
+        const inputName = this._cfg?.inputName || (builtSchema.$id ? _substringBefore(builtSchema.$id, '.') : undefined);
+        return executeValidation(fn, builtSchema, input, opt, inputName);
     }
-    getValidationFunction() {
-        return this.ajvSchema.getValidationFunction();
+    getValidationFunction(opt = {}) {
+        return (input, opt2) => {
+            return this.getValidationResult(input, {
+                ajv: opt.ajv,
+                mutateInput: opt2?.mutateInput ?? opt.mutateInput,
+                inputName: opt2?.inputName ?? opt.inputName,
+                inputId: opt2?.inputId ?? opt.inputId,
+            });
+        };
     }
     /**
      * Specify a function to be called after the normal validation is finished.
@@ -573,7 +341,8 @@ export class JsonSchemaTerminal {
     out;
     opt;
 }
-export class JsonSchemaAnyBuilder extends JsonSchemaTerminal {
+// ==== JBuilder (chainable base) ====
+export class JBuilder extends JSchema {
     setErrorMessage(ruleName, errorMessage) {
         if (_isUndefined(errorMessage))
             return;
@@ -585,15 +354,6 @@ export class JsonSchemaAnyBuilder extends JsonSchemaTerminal {
      *
      * When the type inferred from the schema differs from the passed-in type,
      * the schema becomes unusable, by turning its type into `never`.
-     *
-     * ```ts
-     * const schemaGood = j.string().isOfType<string>() // ✅
-     *
-     * const schemaBad = j.string().isOfType<number>() // ❌
-     * schemaBad.build() // TypeError: property "build" does not exist on type "never"
-     *
-     * const result = ajvValidateRequest.body(req, schemaBad) // result will have `unknown` type
-     * ```
      */
     isOfType() {
         return this.cloneAndUpdateSchema({ hasIsOfTypeCheck: true });
@@ -630,7 +390,7 @@ export class JsonSchemaAnyBuilder extends JsonSchemaTerminal {
         return clone;
     }
     nullable() {
-        return new JsonSchemaAnyBuilder({
+        return new JBuilder({
             anyOf: [this.build(), { type: 'null' }],
         });
     }
@@ -645,7 +405,7 @@ export class JsonSchemaAnyBuilder extends JsonSchemaTerminal {
      * Locks the given schema chain and no other modification can be done to it.
      */
     final() {
-        return new JsonSchemaTerminal(this.schema);
+        return new JSchema(this.schema);
     }
     /**
      *
@@ -676,7 +436,13 @@ export class JsonSchemaAnyBuilder extends JsonSchemaTerminal {
         });
     }
 }
-export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
+// ==== Consts
+const TS_2500 = 16725225600; // 2500-01-01
+const TS_2500_MILLIS = TS_2500 * 1000;
+const TS_2000 = 946684800; // 2000-01-01
+const TS_2000_MILLIS = TS_2000 * 1000;
+// ==== Type-specific builders ====
+export class JString extends JBuilder {
     constructor() {
         super({
             type: 'string',
@@ -690,7 +456,7 @@ export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
      *
      * Make sure this `optional()` call is at the end of your call chain.
      *
-     * When `null` is included in optionalValues, the return type becomes `JsonSchemaTerminal`
+     * When `null` is included in optionalValues, the return type becomes `JSchema`
      * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
      */
     optional(optionalValues) {
@@ -698,7 +464,7 @@ export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
             return super.optional();
         }
         _typeCast(optionalValues);
-        let newBuilder = new JsonSchemaStringBuilder().optional();
+        let newBuilder = new JString().optional();
         const alternativesSchema = j.enum(optionalValues);
         Object.assign(newBuilder.getSchema(), {
             anyOf: [this.build(), alternativesSchema.build()],
@@ -709,7 +475,7 @@ export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
         // 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({
+            newBuilder = new JSchema({
                 anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
                 optionalField: true,
             });
@@ -772,13 +538,16 @@ export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
      * because this call effectively starts a new schema chain.
      */
     isoDate() {
-        return new JsonSchemaIsoDateBuilder();
+        return new JIsoDate();
     }
     isoDateTime() {
         return this.cloneAndUpdateSchema({ IsoDateTime: true }).branded();
     }
     isoMonth() {
-        return new JsonSchemaIsoMonthBuilder();
+        return new JBuilder({
+            type: 'string',
+            IsoMonth: {},
+        });
     }
     /**
      * Validates the string format to be JWT.
@@ -830,7 +599,7 @@ export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
         return this.regex(UUID_REGEX, { msg: 'is an invalid UUID' });
     }
 }
-export class JsonSchemaIsoDateBuilder extends JsonSchemaAnyBuilder {
+export class JIsoDate extends JBuilder {
     constructor() {
         super({
             type: 'string',
@@ -843,7 +612,7 @@ export class JsonSchemaIsoDateBuilder extends JsonSchemaAnyBuilder {
      * This `null` feature only works when the current schema is nested in an object or array schema,
      * due to how mutability works in Ajv.
      *
-     * When `null` is passed, the return type becomes `JsonSchemaTerminal`
+     * When `null` is passed, the return type becomes `JSchema`
      * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
      */
     optional(nullValue) {
@@ -854,7 +623,7 @@ export class JsonSchemaIsoDateBuilder extends JsonSchemaAnyBuilder {
         // 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 an ObjectSchema anymore.
-        return new JsonSchemaTerminal({
+        return new JSchema({
             anyOf: [{ type: 'null', optionalValues: [null] }, this.build()],
             optionalField: true,
         });
@@ -882,15 +651,7 @@ export class JsonSchemaIsoDateBuilder extends JsonSchemaAnyBuilder {
         return this.cloneAndUpdateSchema(schemaPatch);
     }
 }
-export class JsonSchemaIsoMonthBuilder extends JsonSchemaAnyBuilder {
-    constructor() {
-        super({
-            type: 'string',
-            IsoMonth: {},
-        });
-    }
-}
-export class JsonSchemaNumberBuilder extends JsonSchemaAnyBuilder {
+export class JNumber extends JBuilder {
     constructor() {
         super({
             type: 'number',
@@ -904,7 +665,7 @@ export class JsonSchemaNumberBuilder extends JsonSchemaAnyBuilder {
      *
      * Make sure this `optional()` call is at the end of your call chain.
      *
-     * When `null` is included in optionalValues, the return type becomes `JsonSchemaTerminal`
+     * When `null` is included in optionalValues, the return type becomes `JSchema`
      * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
      */
     optional(optionalValues) {
@@ -912,7 +673,7 @@ export class JsonSchemaNumberBuilder extends JsonSchemaAnyBuilder {
             return super.optional();
         }
         _typeCast(optionalValues);
-        let newBuilder = new JsonSchemaNumberBuilder().optional();
+        let newBuilder = new JNumber().optional();
         const alternativesSchema = j.enum(optionalValues);
         Object.assign(newBuilder.getSchema(), {
             anyOf: [this.build(), alternativesSchema.build()],
@@ -923,7 +684,7 @@ export class JsonSchemaNumberBuilder extends JsonSchemaAnyBuilder {
         // 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({
+            newBuilder = new JSchema({
                 anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
                 optionalField: true,
             });
@@ -1024,7 +785,7 @@ export class JsonSchemaNumberBuilder extends JsonSchemaAnyBuilder {
         return this.cloneAndUpdateSchema({ precision: numberOfDigits });
     }
 }
-export class JsonSchemaBooleanBuilder extends JsonSchemaAnyBuilder {
+export class JBoolean extends JBuilder {
     constructor() {
         super({
             type: 'boolean',
@@ -1040,7 +801,7 @@ export class JsonSchemaBooleanBuilder extends JsonSchemaAnyBuilder {
         if (typeof optionalValue === 'undefined') {
             return super.optional();
         }
-        const newBuilder = new JsonSchemaBooleanBuilder().optional();
+        const newBuilder = new JBoolean().optional();
         const alternativesSchema = j.enum([optionalValue]);
         Object.assign(newBuilder.getSchema(), {
             anyOf: [this.build(), alternativesSchema.build()],
@@ -1049,7 +810,7 @@ export class JsonSchemaBooleanBuilder extends JsonSchemaAnyBuilder {
         return newBuilder;
     }
 }
-export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
+export class JObject extends JBuilder {
     constructor(props, opt) {
         super({
             type: 'object',
@@ -1061,22 +822,7 @@ export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
             keySchema: opt?.keySchema ?? undefined,
         });
         if (props)
-            this.addProperties(props);
-    }
-    addProperties(props) {
-        const properties = {};
-        const required = [];
-        for (const [key, builder] of Object.entries(props)) {
-            const isOptional = builder.getSchema().optionalField;
-            if (!isOptional) {
-                required.push(key);
-            }
-            const schema = builder.build();
-            properties[key] = schema;
-        }
-        this.schema.properties = properties;
-        this.schema.required = _uniq(required).sort();
-        return this;
+            addPropertiesToSchema(this.schema, props);
     }
     /**
      * @param nullValue Pass `null` to have `null` values be considered/converted as `undefined`.
@@ -1084,7 +830,7 @@ export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
      * This `null` feature only works when the current schema is nested in an object or array schema,
      * due to how mutability works in Ajv.
      *
-     * When `null` is passed, the return type becomes `JsonSchemaTerminal`
+     * When `null` is passed, the return type becomes `JSchema`
      * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
      */
     optional(nullValue) {
@@ -1095,7 +841,7 @@ export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
         // 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 an ObjectSchema anymore.
-        return new JsonSchemaTerminal({
+        return new JSchema({
             anyOf: [{ type: 'null', optionalValues: [null] }, this.build()],
             optionalField: true,
         });
@@ -1107,9 +853,9 @@ export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
         return this.cloneAndUpdateSchema({ additionalProperties: true });
     }
     extend(props) {
-        const newBuilder = new JsonSchemaObjectBuilder();
+        const newBuilder = new JObject();
         _objectAssign(newBuilder.schema, deepCopyPreservingFunctions(this.schema));
-        const incomingSchemaBuilder = new JsonSchemaObjectBuilder(props);
+        const incomingSchemaBuilder = new JObject(props);
         mergeJsonSchemaObjects(newBuilder.schema, incomingSchemaBuilder.schema);
         _objectAssign(newBuilder.schema, { hasIsOfTypeCheck: false });
         return newBuilder;
@@ -1120,17 +866,6 @@ export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
      * It expects you to use `isOfType<T>()` in the chain,
      * otherwise the validation will throw. This is to ensure
      * that the schemas you concatenated match the intended final type.
-     *
-     * ```ts
-     *  interface Foo { foo: string }
-     *  const fooSchema = j.object<Foo>({ foo: j.string() })
-     *
-     *  interface Bar { bar: number }
-     *  const barSchema = j.object<Bar>({ bar: j.number() })
-     *
-     *  interface Shu { foo: string, bar: number }
-     *  const shuSchema = fooSchema.concat(barSchema).isOfType<Shu>() // important
-     * ```
      */
     concat(other) {
         const clone = this.clone();
@@ -1160,7 +895,7 @@ export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
         return this.cloneAndUpdateSchema({ exclusiveProperties: [...exclusiveProperties, propNames] });
     }
 }
-export class JsonSchemaObjectInferringBuilder extends JsonSchemaAnyBuilder {
+export class JObjectInfer extends JBuilder {
     constructor(props) {
         super({
             type: 'object',
@@ -1169,22 +904,7 @@ export class JsonSchemaObjectInferringBuilder extends JsonSchemaAnyBuilder {
             additionalProperties: false,
         });
         if (props)
-            this.addProperties(props);
-    }
-    addProperties(props) {
-        const properties = {};
-        const required = [];
-        for (const [key, builder] of Object.entries(props)) {
-            const isOptional = builder.getSchema().optionalField;
-            if (!isOptional) {
-                required.push(key);
-            }
-            const schema = builder.build();
-            properties[key] = schema;
-        }
-        this.schema.properties = properties;
-        this.schema.required = _uniq(required).sort();
-        return this;
+            addPropertiesToSchema(this.schema, props);
     }
     /**
      * @param nullValue Pass `null` to have `null` values be considered/converted as `undefined`.
@@ -1192,7 +912,7 @@ export class JsonSchemaObjectInferringBuilder extends JsonSchemaAnyBuilder {
      * This `null` feature only works when the current schema is nested in an object or array schema,
      * due to how mutability works in Ajv.
      *
-     * When `null` is passed, the return type becomes `JsonSchemaTerminal`
+     * When `null` is passed, the return type becomes `JSchema`
      * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
      */
     // @ts-expect-error override adds optional parameter which is compatible but TS can't verify complex mapped types
@@ -1204,7 +924,7 @@ export class JsonSchemaObjectInferringBuilder extends JsonSchemaAnyBuilder {
         // 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 an ObjectSchema anymore.
-        return new JsonSchemaTerminal({
+        return new JSchema({
             anyOf: [{ type: 'null', optionalValues: [null] }, this.build()],
             optionalField: true,
         });
@@ -1216,9 +936,9 @@ export class JsonSchemaObjectInferringBuilder extends JsonSchemaAnyBuilder {
         return this.cloneAndUpdateSchema({ additionalProperties: true });
     }
     extend(props) {
-        const newBuilder = new JsonSchemaObjectInferringBuilder();
+        const newBuilder = new JObjectInfer();
         _objectAssign(newBuilder.schema, deepCopyPreservingFunctions(this.schema));
-        const incomingSchemaBuilder = new JsonSchemaObjectInferringBuilder(props);
+        const incomingSchemaBuilder = new JObjectInfer(props);
         mergeJsonSchemaObjects(newBuilder.schema, incomingSchemaBuilder.schema);
         // This extend function is not type-safe as it is inferring,
         // so even if the base schema was already type-checked,
@@ -1238,7 +958,7 @@ export class JsonSchemaObjectInferringBuilder extends JsonSchemaAnyBuilder {
         });
     }
 }
-export class JsonSchemaArrayBuilder extends JsonSchemaAnyBuilder {
+export class JArray extends JBuilder {
     constructor(itemsSchema) {
         super({
             type: 'array',
@@ -1262,7 +982,7 @@ export class JsonSchemaArrayBuilder extends JsonSchemaAnyBuilder {
         return this.cloneAndUpdateSchema({ uniqueItems: true });
     }
 }
-export class JsonSchemaSet2Builder extends JsonSchemaAnyBuilder {
+class JSet2Builder extends JBuilder {
     constructor(itemsSchema) {
         super({
             type: ['array', 'object'],
@@ -1276,14 +996,7 @@ export class JsonSchemaSet2Builder extends JsonSchemaAnyBuilder {
         return this.cloneAndUpdateSchema({ maxItems });
     }
 }
-export class JsonSchemaBufferBuilder extends JsonSchemaAnyBuilder {
-    constructor() {
-        super({
-            Buffer: true,
-        });
-    }
-}
-export class JsonSchemaEnumBuilder extends JsonSchemaAnyBuilder {
+export class JEnum extends JBuilder {
     constructor(enumValues, baseType, opt) {
         const jsonSchema = { enum: enumValues };
         // Specifying the base type helps in cases when we ask Ajv to coerce the types.
@@ -1302,7 +1015,7 @@ export class JsonSchemaEnumBuilder extends JsonSchemaAnyBuilder {
         return this;
     }
 }
-export class JsonSchemaTupleBuilder extends JsonSchemaAnyBuilder {
+export class JTuple extends JBuilder {
     constructor(items) {
         super({
             type: 'array',
@@ -1312,43 +1025,11 @@ export class JsonSchemaTupleBuilder extends JsonSchemaAnyBuilder {
         });
     }
 }
-export class JsonSchemaAnyOfByBuilder 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,
-            },
-        });
-    }
-}
-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);
+    return new JObject(props);
 }
 function objectInfer(props) {
-    return new JsonSchemaObjectInferringBuilder(props);
+    return new JObjectInfer(props);
 }
 function objectDbEntity(props) {
     return j.object({
@@ -1367,7 +1048,7 @@ function record(keySchema, valueSchema) {
     const finalValueSchema = isValueOptional
         ? { anyOf: [{ isUndefined: true }, valueJsonSchema] }
         : valueJsonSchema;
-    return new JsonSchemaObjectBuilder([], {
+    return new JObject([], {
         hasIsOfTypeCheck: false,
         keySchema: keyJsonSchema,
         patternProperties: {
@@ -1381,7 +1062,7 @@ function withRegexKeys(keyRegex, schema) {
     }
     const pattern = keyRegex instanceof RegExp ? keyRegex.source : keyRegex;
     const jsonSchema = schema.build();
-    return new JsonSchemaObjectBuilder([], {
+    return new JObject([], {
         hasIsOfTypeCheck: false,
         patternProperties: {
             [pattern]: jsonSchema,
@@ -1410,11 +1091,324 @@ function withEnumKeys(keys, schema) {
     _assert(enumValues, 'The key list should be an array of values, NumberEnum or a StringEnum');
     const typedValues = enumValues;
     const props = Object.fromEntries(typedValues.map(key => [key, schema]));
-    return new JsonSchemaObjectBuilder(props, { hasIsOfTypeCheck: false });
+    return new JObject(props, { hasIsOfTypeCheck: false });
+}
+// ==== AjvSchema compat wrapper ====
+/**
+ * On creation - compiles ajv validation function.
+ * Provides convenient methods, error reporting, etc.
+ */
+export class AjvSchema {
+    schema;
+    constructor(schema, cfg = {}, preCompiledFn) {
+        this.schema = schema;
+        this.cfg = {
+            lazy: false,
+            ...cfg,
+            ajv: cfg.ajv || getAjv(),
+            // Auto-detecting "InputName" from $id of the schema (e.g "Address.schema.json")
+            inputName: cfg.inputName || (schema.$id ? _substringBefore(schema.$id, '.') : undefined),
+        };
+        if (preCompiledFn) {
+            this._compiledFn = preCompiledFn;
+        }
+        else if (!cfg.lazy) {
+            this._getValidateFn(); // compile eagerly
+        }
+    }
+    /**
+     * Shortcut for AjvSchema.create(schema, { lazy: true })
+     */
+    static createLazy(schema, cfg) {
+        return AjvSchema.create(schema, {
+            lazy: true,
+            ...cfg,
+        });
+    }
+    /**
+     * Conveniently allows to pass either JsonSchema or JSchema builder, or existing AjvSchema.
+     * If it's already an AjvSchema - it'll just return it without any processing.
+     * If it's a Builder - will call `build` before proceeding.
+     * Otherwise - will construct AjvSchema instance ready to be used.
+     */
+    static create(schema, cfg) {
+        if (schema instanceof AjvSchema)
+            return schema;
+        if (AjvSchema.isSchemaWithCachedAjvSchema(schema)) {
+            return AjvSchema.requireCachedAjvSchema(schema);
+        }
+        let jsonSchema;
+        if (schema instanceof JSchema) {
+            // oxlint-disable typescript-eslint(no-unnecessary-type-assertion)
+            jsonSchema = schema.build();
+            AjvSchema.requireValidJsonSchema(jsonSchema);
+        }
+        else {
+            jsonSchema = schema;
+        }
+        // This is our own helper which marks a schema as optional
+        // in case it is going to be used in an object schema,
+        // where we need to mark the given property as not-required.
+        // But once all compilation is done, the presence of this field
+        // really upsets Ajv.
+        delete jsonSchema.optionalField;
+        const ajvSchema = new AjvSchema(jsonSchema, cfg);
+        AjvSchema.cacheAjvSchema(schema, ajvSchema);
+        return ajvSchema;
+    }
+    /**
+     * Creates a minimal AjvSchema wrapper from a pre-compiled validate function.
+     * Used internally by JSchema to cache a compatible AjvSchema instance.
+     */
+    static _wrap(schema, compiledFn) {
+        return new AjvSchema(schema, {}, compiledFn);
+    }
+    static isSchemaWithCachedAjvSchema(schema) {
+        return !!schema?.[HIDDEN_AJV_SCHEMA];
+    }
+    static cacheAjvSchema(schema, ajvSchema) {
+        return Object.assign(schema, { [HIDDEN_AJV_SCHEMA]: ajvSchema });
+    }
+    static requireCachedAjvSchema(schema) {
+        return schema[HIDDEN_AJV_SCHEMA];
+    }
+    cfg;
+    _compiledFn;
+    _getValidateFn() {
+        if (!this._compiledFn) {
+            this._compiledFn = this.cfg.ajv.compile(this.schema);
+        }
+        return this._compiledFn;
+    }
+    /**
+     * It returns the original object just for convenience.
+     */
+    validate(input, opt = {}) {
+        const [err, output] = this.getValidationResult(input, opt);
+        if (err)
+            throw err;
+        return output;
+    }
+    isValid(input, opt) {
+        const [err] = this.getValidationResult(input, opt);
+        return !err;
+    }
+    getValidationResult(input, opt = {}) {
+        const fn = this._getValidateFn();
+        return executeValidation(fn, this.schema, input, opt, this.cfg.inputName);
+    }
+    getValidationFunction() {
+        return (input, opt) => {
+            return this.getValidationResult(input, {
+                mutateInput: opt?.mutateInput,
+                inputName: opt?.inputName,
+                inputId: opt?.inputId,
+            });
+        };
+    }
+    static requireValidJsonSchema(schema) {
+        // For object schemas we require that it is type checked against an external type, e.g.:
+        // interface Foo { name: string }
+        // const schema = j.object({ name: j.string() }).ofType<Foo>()
+        _assert(schema.type !== 'object' || schema.hasIsOfTypeCheck, 'The schema must be type checked against a type or interface, using the `.isOfType()` helper in `j`.');
+    }
+}
+// ==== Shared validation logic ====
+const separator = '\n';
+function executeValidation(fn, builtSchema, input, opt = {}, defaultInputName) {
+    const item = opt.mutateInput !== false || typeof input !== 'object'
+        ? input // mutate
+        : _deepCopy(input); // not mutate
+    let valid = fn(item); // mutates item, but not input
+    _typeCast(item);
+    let output = item;
+    if (valid && builtSchema.postValidation) {
+        const [err, result] = _try(() => builtSchema.postValidation(output));
+        if (err) {
+            valid = false;
+            fn.errors = [
+                {
+                    instancePath: '',
+                    message: err.message,
+                },
+            ];
+        }
+        else {
+            output = result;
+        }
+    }
+    if (valid)
+        return [null, output];
+    const errors = fn.errors;
+    const { inputId = _isObject(input) ? input['id'] : undefined, inputName = defaultInputName || 'Object', } = opt;
+    const dataVar = [inputName, inputId].filter(Boolean).join('.');
+    applyImprovementsOnErrorMessages(errors, builtSchema);
+    let message = getAjv().errorsText(errors, {
+        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: {}
+    // Unless `getOriginalInput` function is provided - then it will be used to preserve the Input pureness.
+    const inputStringified = _inspect(opt.getOriginalInput?.() || input, { maxLen: 4000 });
+    message = [message, 'Input: ' + inputStringified].join(separator);
+    const err = new AjvValidationError(message, _filterNullishValues({
+        errors,
+        inputName,
+        inputId,
+    }));
+    return [err, output];
+}
+// ==== Error formatting helpers ====
+function applyImprovementsOnErrorMessages(errors, schema) {
+    if (!errors)
+        return;
+    filterNullableAnyOfErrors(errors, schema);
+    const { errorMessages } = schema;
+    for (const error of errors) {
+        const errorMessage = getErrorMessageForInstancePath(schema, error.instancePath, error.keyword);
+        if (errorMessage) {
+            error.message = errorMessage;
+        }
+        else if (errorMessages?.[error.keyword]) {
+            error.message = errorMessages[error.keyword];
+        }
+        else {
+            const unwrapped = unwrapNullableAnyOf(schema);
+            if (unwrapped?.errorMessages?.[error.keyword]) {
+                error.message = unwrapped.errorMessages[error.keyword];
+            }
+        }
+        error.instancePath = error.instancePath.replaceAll(/\/(\d+)/g, `[$1]`).replaceAll('/', '.');
+    }
+}
+/**
+ * Filters out noisy errors produced by nullable anyOf patterns.
+ * When `nullable()` wraps a schema in `anyOf: [realSchema, { type: 'null' }]`,
+ * AJV produces "must be null" and "must match a schema in anyOf" errors
+ * that are confusing. This method splices them out, keeping only the real errors.
+ */
+function filterNullableAnyOfErrors(errors, schema) {
+    // Collect exact schemaPaths to remove (anyOf aggregates) and prefixes (null branches)
+    const exactPaths = [];
+    const nullBranchPrefixes = [];
+    for (const error of errors) {
+        if (error.keyword !== 'anyOf')
+            continue;
+        const parentSchema = resolveSchemaPath(schema, error.schemaPath);
+        if (!parentSchema)
+            continue;
+        const nullIndex = unwrapNullableAnyOfIndex(parentSchema);
+        if (nullIndex === -1)
+            continue;
+        exactPaths.push(error.schemaPath); // e.g. "#/anyOf"
+        const anyOfBase = error.schemaPath.slice(0, -'anyOf'.length);
+        nullBranchPrefixes.push(`${anyOfBase}anyOf/${nullIndex}/`); // e.g. "#/anyOf/1/"
+    }
+    if (!exactPaths.length)
+        return;
+    for (let i = errors.length - 1; i >= 0; i--) {
+        const sp = errors[i].schemaPath;
+        if (exactPaths.includes(sp) || nullBranchPrefixes.some(p => sp.startsWith(p))) {
+            errors.splice(i, 1);
+        }
+    }
+}
+/**
+ * Navigates the schema tree using an AJV schemaPath (e.g. "#/properties/foo/anyOf")
+ * and returns the parent schema containing the last keyword.
+ */
+function resolveSchemaPath(schema, schemaPath) {
+    // schemaPath looks like "#/properties/foo/anyOf" or "#/anyOf"
+    // We want the schema that contains the final keyword (e.g. "anyOf")
+    const segments = schemaPath.replace(/^#\//, '').split('/');
+    // Remove the last segment (the keyword itself, e.g. "anyOf")
+    segments.pop();
+    let current = schema;
+    for (const segment of segments) {
+        if (!current || typeof current !== 'object')
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function getErrorMessageForInstancePath(schema, instancePath, keyword) {
+    if (!schema || !instancePath)
+        return undefined;
+    const segments = instancePath.split('/').filter(Boolean);
+    return traverseSchemaPath(schema, segments, keyword);
+}
+function traverseSchemaPath(schema, segments, keyword) {
+    if (!segments.length)
+        return undefined;
+    const [currentSegment, ...remainingSegments] = segments;
+    const nextSchema = getChildSchema(schema, currentSegment);
+    if (!nextSchema)
+        return undefined;
+    if (nextSchema.errorMessages?.[keyword]) {
+        return nextSchema.errorMessages[keyword];
+    }
+    // Check through nullable wrapper
+    const unwrapped = unwrapNullableAnyOf(nextSchema);
+    if (unwrapped?.errorMessages?.[keyword]) {
+        return unwrapped.errorMessages[keyword];
+    }
+    if (remainingSegments.length) {
+        return traverseSchemaPath(nextSchema, remainingSegments, keyword);
+    }
+    return undefined;
+}
+function getChildSchema(schema, segment) {
+    if (!segment)
+        return undefined;
+    // Unwrap nullable anyOf to find properties/items through nullable wrappers
+    const effectiveSchema = unwrapNullableAnyOf(schema) ?? schema;
+    if (/^\d+$/.test(segment) && effectiveSchema.items) {
+        return getArrayItemSchema(effectiveSchema, segment);
+    }
+    return getObjectPropertySchema(effectiveSchema, segment);
+}
+function getArrayItemSchema(schema, indexSegment) {
+    if (!schema.items)
+        return undefined;
+    if (Array.isArray(schema.items)) {
+        return schema.items[Number(indexSegment)];
+    }
+    return schema.items;
+}
+function getObjectPropertySchema(schema, segment) {
+    return schema.properties?.[segment];
+}
+function unwrapNullableAnyOf(schema) {
+    const nullIndex = unwrapNullableAnyOfIndex(schema);
+    if (nullIndex === -1)
+        return undefined;
+    return schema.anyOf[1 - nullIndex];
+}
+function unwrapNullableAnyOfIndex(schema) {
+    if (schema.anyOf?.length !== 2)
+        return -1;
+    const nullIndex = schema.anyOf.findIndex(s => s.type === 'null');
+    return nullIndex;
+}
+// ==== Utility helpers ====
+function addPropertiesToSchema(schema, props) {
+    const properties = {};
+    const required = [];
+    for (const [key, builder] of Object.entries(props)) {
+        const isOptional = builder.getSchema().optionalField;
+        if (!isOptional) {
+            required.push(key);
+        }
+        const builtSchema = builder.build();
+        properties[key] = builtSchema;
+    }
+    schema.properties = properties;
+    schema.required = _uniq(required).sort();
 }
 function hasNoObjectSchemas(schema) {
     if (Array.isArray(schema.type)) {
-        schema.type.every(type => ['string', 'number', 'integer', 'boolean', 'null'].includes(type));
+        return schema.type.every(type => ['string', 'number', 'integer', 'boolean', 'null'].includes(type));
     }
     else if (schema.anyOf) {
         return schema.anyOf.every(hasNoObjectSchemas);