@naturalcycles/nodejs-lib 15.93.0 → 15.95.0

package/src/validation/ajv/{ajvSchema.ts → jSchema.ts}

@@ -5,7 +5,6 @@ import type { ValidationFunction, ValidationFunctionResult } from '@naturalcycle
 import {
   _isObject,
   _isUndefined,
-  _lazyValue,
   _numberEnumValues,
   _stringEnumValues,
   getEnumType,
@@ -55,469 +54,27 @@ import {
   mergeJsonSchemaObjects,
 } from './jsonSchemaBuilder.util.js'
 
-// ==== AJV =====
-
-/**
- * On creation - compiles ajv validation function.
- * Provides convenient methods, error reporting, etc.
- */
-export class AjvSchema<OUT> {
-  private constructor(
-    public schema: JsonSchema<OUT>,
-    cfg: Partial<AjvSchemaCfg> = {},
-  ) {
-    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<OUT>(
-    schema: SchemaHandledByAjv<OUT>,
-    cfg?: Partial<AjvSchemaCfg>,
-  ): AjvSchema<OUT> {
-    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<OUT>(schema: SchemaHandledByAjv<OUT>, cfg?: Partial<AjvSchemaCfg>): AjvSchema<OUT> {
-    if (schema instanceof AjvSchema) return schema
-
-    if (AjvSchema.isSchemaWithCachedAjvSchema<typeof schema, OUT>(schema)) {
-      return AjvSchema.requireCachedAjvSchema<typeof schema, OUT>(schema)
-    }
-
-    let jsonSchema: JsonSchema<OUT>
-
-    if (AjvSchema.isJsonSchemaBuilder(schema)) {
-      // oxlint-disable typescript-eslint(no-unnecessary-type-assertion)
-      jsonSchema = (schema as JsonSchemaTerminal<OUT, any>).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<OUT>(jsonSchema, cfg)
-    AjvSchema.cacheAjvSchema(schema, ajvSchema)
-
-    return ajvSchema
-  }
-
-  static isJsonSchemaBuilder<OUT>(schema: unknown): schema is JsonSchemaTerminal<OUT, any> {
-    return schema instanceof JsonSchemaTerminal
-  }
-
-  readonly cfg: AjvSchemaCfg
-
-  /**
-   * 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: unknown, opt: AjvValidationOptions = {}): OUT {
-    const [err, output] = this.getValidationResult(input, opt)
-    if (err) throw err
-    return output
-  }
-
-  isValid(input: unknown, opt?: AjvValidationOptions): boolean {
-    // todo: we can make it both fast and non-mutating by using Ajv
-    // with "removeAdditional" and "useDefaults" disabled.
-    const [err] = this.getValidationResult(input, opt)
-    return !err
-  }
-
-  getValidationResult(
-    input: unknown,
-    opt: AjvValidationOptions = {},
-  ): ValidationFunctionResult<OUT, AjvValidationError> {
-    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<OUT>(item)
-
-    let output: OUT = item
-    if (valid && this.schema.postValidation) {
-      const [err, result] = _try(() => this.schema.postValidation!(output))
-      if (err) {
-        valid = false
-        ;(fn as any).errors = [
-          {
-            instancePath: '',
-            message: err.message,
-          },
-        ]
-      } else {
-        output = result
-      }
-    }
-
-    if (valid) return [null, output]
-
-    const errors = fn.errors!
-
-    const {
-      inputId = _isObject(input) ? (input as any)['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(): ValidationFunction<OUT, AjvValidationError> {
-    return (input, opt) => {
-      return this.getValidationResult(input, {
-        mutateInput: opt?.mutateInput,
-        inputName: opt?.inputName,
-        inputId: opt?.inputId,
-      })
-    }
-  }
-
-  static isSchemaWithCachedAjvSchema<Base, OUT>(
-    schema: Base,
-  ): schema is WithCachedAjvSchema<Base, OUT> {
-    return !!(schema as any)?.[HIDDEN_AJV_SCHEMA]
-  }
-
-  static cacheAjvSchema<Base extends AnyObject, OUT>(
-    schema: Base,
-    ajvSchema: AjvSchema<OUT>,
-  ): WithCachedAjvSchema<Base, OUT> {
-    return Object.assign(schema, { [HIDDEN_AJV_SCHEMA]: ajvSchema })
-  }
-
-  static requireCachedAjvSchema<Base, OUT>(schema: WithCachedAjvSchema<Base, OUT>): AjvSchema<OUT> {
-    return schema[HIDDEN_AJV_SCHEMA]
-  }
-
-  private getAJVValidateFunction = _lazyValue(() => this.cfg.ajv.compile(this.schema as any))
-
-  private static requireValidJsonSchema(schema: JsonSchema): void {
-    // 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`.',
-    )
-  }
-
-  private applyImprovementsOnErrorMessages(
-    errors: ErrorObject<string, Record<string, any>, unknown>[] | null | undefined,
-  ): void {
-    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.
-   */
-  private filterNullableAnyOfErrors(
-    errors: ErrorObject<string, Record<string, any>, unknown>[],
-  ): void {
-    // Collect exact schemaPaths to remove (anyOf aggregates) and prefixes (null branches)
-    const exactPaths: string[] = []
-    const nullBranchPrefixes: string[] = []
-
-    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.
-   */
-  private resolveSchemaPath(schemaPath: string): JsonSchema | undefined {
-    // 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: any = this.schema
-    for (const segment of segments) {
-      if (!current || typeof current !== 'object') return undefined
-      current = current[segment]
-    }
-    return current as JsonSchema | undefined
-  }
-
-  private getErrorMessageForInstancePath(
-    schema: JsonSchema<OUT> | undefined,
-    instancePath: string,
-    keyword: string,
-  ): string | undefined {
-    if (!schema || !instancePath) return undefined
-
-    const segments = instancePath.split('/').filter(Boolean)
-    return this.traverseSchemaPath(schema, segments, keyword)
-  }
-
-  private traverseSchemaPath<T>(
-    schema: JsonSchema<T>,
-    segments: string[],
-    keyword: string,
-  ): string | undefined {
-    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
-  }
-
-  private getChildSchema(schema: JsonSchema, segment: string | undefined): JsonSchema | undefined {
-    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)
-  }
-
-  private getArrayItemSchema(schema: JsonSchema, indexSegment: string): JsonSchema | undefined {
-    if (!schema.items) return undefined
-
-    if (Array.isArray(schema.items)) {
-      return schema.items[Number(indexSegment)]
-    }
-
-    return schema.items
-  }
-
-  private getObjectPropertySchema(schema: JsonSchema, segment: string): JsonSchema | undefined {
-    return schema.properties?.[segment as keyof typeof schema.properties]
-  }
-}
-
-function unwrapNullableAnyOf(schema: JsonSchema): JsonSchema | undefined {
-  const nullIndex = unwrapNullableAnyOfIndex(schema)
-  if (nullIndex === -1) return undefined
-  return schema.anyOf![1 - nullIndex]!
-}
-
-function unwrapNullableAnyOfIndex(schema: JsonSchema): number {
-  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')
-
-export type WithCachedAjvSchema<Base, OUT> = Base & {
-  [HIDDEN_AJV_SCHEMA]: AjvSchema<OUT>
-}
-
-export interface AjvValidationOptions {
-  /**
-   * Defaults to true,
-   * because that's how AJV works by default,
-   * and what gives it performance advantage.
-   * (Because we have found that deep-clone is surprisingly slow,
-   * nearly as slow as Joi validation).
-   *
-   * If set to true - AJV will mutate the input in case it needs to apply transformations
-   * (strip unknown properties, convert types, etc).
-   *
-   * If false - it will deep-clone (using JSON.stringify+parse) the input to prevent its mutation.
-   * Will return the cloned/mutated object.
-   * Please note that JSON.stringify+parse has side-effects,
-   * e.g it will transform Buffer into a weird object.
-   */
-  mutateInput?: boolean
-  inputName?: string
-  inputId?: string
-  /**
-   * Function that returns "original input".
-   * What is original input?
-   * It's an input in its original non-mutated form.
-   * Why is it needed?
-   * Because we mutates the Input here. And after its been mutated - we no longer
-   * can include it "how it was" in an error message. So, for that reason we'll use
-   * `getOriginalInput()`, if it's provided.
-   */
-  getOriginalInput?: () => unknown
-}
-
-export interface AjvSchemaCfg {
-  /**
-   * Pass Ajv instance, otherwise Ajv will be created with
-   * AjvSchema default (not the same as Ajv defaults) parameters
-   */
-  ajv: Ajv
-
-  inputName?: string
-
-  /**
-   * Option of Ajv.
-   * If set to true - will mutate your input objects!
-   * Defaults to false.
-   *
-   * This option is a "shortcut" to skip creating and passing Ajv instance.
-   */
-  // coerceTypes?: boolean
-
-  /**
-   * If true - schema will be compiled on-demand (lazily).
-   * Default: false.
-   */
-  lazy?: boolean
-}
-
-export type SchemaHandledByAjv<OUT> =
-  | JsonSchemaTerminal<OUT, any>
-  | JsonSchema<OUT>
-  | AjvSchema<OUT>
-
-// ===== 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(): JsonSchemaAnyBuilder<any, false> {
-    return new JsonSchemaAnyBuilder({})
+  any(): JBuilder<any, false> {
+    return new JBuilder({})
   },
 
-  string(): JsonSchemaStringBuilder<string, false> {
-    return new JsonSchemaStringBuilder()
+  string(): JString<string, false> {
+    return new JString()
   },
 
-  number(): JsonSchemaNumberBuilder<number, false> {
-    return new JsonSchemaNumberBuilder()
+  number(): JNumber<number, false> {
+    return new JNumber()
   },
 
-  boolean(): JsonSchemaBooleanBuilder<boolean, false> {
-    return new JsonSchemaBooleanBuilder()
+  boolean(): JBoolean<boolean, false> {
+    return new JBoolean()
   },
 
   object: Object.assign(object, {
@@ -527,16 +84,14 @@ export const j = {
       return j.object<AnyObject>({}).allowAdditionalProperties()
     },
 
-    stringMap<S extends JsonSchemaTerminal<any, any>>(
-      schema: S,
-    ): JsonSchemaObjectBuilder<StringMap<SchemaOut<S>>> {
+    stringMap<S extends JSchema<any, any>>(schema: S): JObject<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<SchemaOut<S>>>(
+      return new JObject<StringMap<SchemaOut<S>>>(
         {},
         {
           hasIsOfTypeCheck: false,
@@ -584,26 +139,28 @@ export const j = {
     withRegexKeys,
   }),
 
-  array<OUT, Opt>(itemSchema: JsonSchemaAnyBuilder<OUT, Opt>): JsonSchemaArrayBuilder<OUT, Opt> {
-    return new JsonSchemaArrayBuilder(itemSchema)
+  array<OUT, Opt>(itemSchema: JBuilder<OUT, Opt>): JArray<OUT, Opt> {
+    return new JArray(itemSchema)
   },
 
-  tuple<const S extends JsonSchemaAnyBuilder<any, any>[]>(items: S): JsonSchemaTupleBuilder<S> {
-    return new JsonSchemaTupleBuilder<S>(items)
+  tuple<const S extends JBuilder<any, any>[]>(items: S): JTuple<S> {
+    return new JTuple<S>(items)
   },
 
-  set<OUT, Opt>(itemSchema: JsonSchemaAnyBuilder<OUT, Opt>): JsonSchemaSet2Builder<OUT, Opt> {
-    return new JsonSchemaSet2Builder(itemSchema)
+  set<OUT, Opt>(itemSchema: JBuilder<OUT, Opt>): JSet2Builder<OUT, Opt> {
+    return new JSet2Builder(itemSchema)
   },
 
-  buffer(): JsonSchemaBufferBuilder {
-    return new JsonSchemaBufferBuilder()
+  buffer(): JBuilder<Buffer, false> {
+    return new JBuilder<Buffer, false>({
+      Buffer: true,
+    })
   },
 
   enum<const T extends readonly (string | number | boolean | null)[] | StringEnum | NumberEnum>(
     input: T,
     opt?: JsonBuilderRuleOpt,
-  ): JsonSchemaEnumBuilder<
+  ): JEnum<
     T extends readonly (infer U)[]
       ? U
       : T extends StringEnum
@@ -634,7 +191,7 @@ export const j = {
     }
 
     _assert(enumValues, 'Unsupported enum input')
-    return new JsonSchemaEnumBuilder(enumValues as any, baseType, opt)
+    return new JEnum(enumValues as any, baseType, opt)
   },
 
   /**
@@ -648,16 +205,16 @@ export const j = {
    * Use `anyOf` when schemas may overlap (e.g., AccountId | PartnerId with same format).
    * Use `oneOf` when schemas are mutually exclusive.
    */
-  oneOf<B extends readonly JsonSchemaAnyBuilder<any, boolean>[], OUT = BuilderOutUnion<B>>(
+  oneOf<B extends readonly JBuilder<any, boolean>[], OUT = BuilderOutUnion<B>>(
     items: [...B],
-  ): JsonSchemaAnyBuilder<OUT, false> {
+  ): JBuilder<OUT, false> {
     const schemas = items.map(b => b.build())
     _assert(
       schemas.every(hasNoObjectSchemas),
       'Do not use `oneOf` validation with non-primitive types!',
     )
 
-    return new JsonSchemaAnyBuilder<OUT, false>({
+    return new JBuilder<OUT, false>({
       oneOf: schemas,
     })
   },
@@ -673,16 +230,16 @@ export const j = {
    * Use `anyOf` when schemas may overlap (e.g., AccountId | PartnerId with same format).
    * Use `oneOf` when schemas are mutually exclusive.
    */
-  anyOf<B extends readonly JsonSchemaAnyBuilder<any, boolean>[], OUT = BuilderOutUnion<B>>(
+  anyOf<B extends readonly JBuilder<any, boolean>[], OUT = BuilderOutUnion<B>>(
     items: [...B],
-  ): JsonSchemaAnyBuilder<OUT, false> {
+  ): JBuilder<OUT, false> {
     const schemas = items.map(b => b.build())
     _assert(
       schemas.every(hasNoObjectSchemas),
       'Do not use `anyOf` validation with non-primitive types!',
     )
 
-    return new JsonSchemaAnyBuilder<OUT, false>({
+    return new JBuilder<OUT, false>({
       anyOf: schemas,
     })
   },
@@ -699,11 +256,23 @@ export const j = {
    * const schema = j.anyOfBy('success', schemaMap)
    * ```
    */
-  anyOfBy<D extends Record<PropertyKey, JsonSchemaTerminal<any, any>>, OUT = AnyOfByOut<D>>(
+  anyOfBy<D extends Record<PropertyKey, JSchema<any, any>>, OUT = AnyOfByOut<D>>(
     propertyName: string,
     schemaDictionary: D,
-  ): JsonSchemaAnyOfByBuilder<OUT> {
-    return new JsonSchemaAnyOfByBuilder<OUT>(propertyName, schemaDictionary)
+  ): JBuilder<OUT, false> {
+    const builtSchemaDictionary: Record<string, JsonSchema> = {}
+    for (const [key, schema] of Object.entries(schemaDictionary)) {
+      builtSchemaDictionary[key] = schema.build()
+    }
+
+    return new JBuilder<OUT, false>({
+      type: 'object',
+      hasIsOfTypeCheck: true,
+      anyOfBy: {
+        propertyName,
+        schemaDictionary: builtSchemaDictionary,
+      },
+    })
   },
 
   /**
@@ -714,10 +283,10 @@ export const j = {
    * const schema = j.anyOfThese([successSchema, errorSchema])
    * ```
    */
-  anyOfThese<B extends readonly JsonSchemaAnyBuilder<any, boolean>[], OUT = BuilderOutUnion<B>>(
+  anyOfThese<B extends readonly JBuilder<any, boolean>[], OUT = BuilderOutUnion<B>>(
     items: [...B],
-  ): JsonSchemaAnyBuilder<OUT, false> {
-    return new JsonSchemaAnyBuilder<OUT, false>({
+  ): JBuilder<OUT, false> {
+    return new JBuilder<OUT, false>({
       anyOfThese: items.map(b => b.build()),
     })
   },
@@ -734,14 +303,32 @@ export const j = {
     let baseType: EnumBaseType = 'other'
     if (typeof v === 'string') baseType = 'string'
     if (typeof v === 'number') baseType = 'number'
-    return new JsonSchemaEnumBuilder<V>([v], baseType)
+    return new JEnum<V>([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<OUT>(
+    schema: JsonSchema<OUT>,
+    cfg?: { ajv?: Ajv; inputName?: string },
+  ): JSchema<OUT, false> {
+    return new JSchema<OUT, false>(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')
+
+export type WithCachedAjvSchema<Base, OUT> = Base & {
+  [HIDDEN_AJV_SCHEMA]: AjvSchema<OUT>
+}
+
+// ==== JSchema (locked base) ====
 
 /*
   Notes for future reference
@@ -752,20 +339,54 @@ const TS_2000_MILLIS = TS_2000 * 1000
      With `Opt`, we can infer it as `{ foo?: string | undefined }`.
 */
 
-export class JsonSchemaTerminal<OUT, Opt> {
-  protected [HIDDEN_AJV_SCHEMA]: AjvSchema<any> | undefined
-  protected schema: JsonSchema
+export class JSchema<OUT, Opt> {
+  protected [HIDDEN_AJV_SCHEMA]: AjvSchema<any> | undefined
+  protected schema: JsonSchema
+  private _cfg?: { ajv?: Ajv; inputName?: string }
+
+  constructor(schema: JsonSchema, cfg?: { ajv?: Ajv; inputName?: string }) {
+    this.schema = schema
+    this._cfg = cfg
+  }
+
+  private _builtSchema?: JsonSchema
+  private _compiledFns?: WeakMap<Ajv, any>
+
+  private _getBuiltSchema(): JsonSchema {
+    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
+    }
 
-  constructor(schema: JsonSchema) {
-    this.schema = schema
+    return this._builtSchema
   }
 
-  get ajvSchema(): AjvSchema<any> {
-    if (!this[HIDDEN_AJV_SCHEMA]) {
-      this[HIDDEN_AJV_SCHEMA] = AjvSchema.create<OUT>(this)
+  private _getCompiled(overrideAjv?: Ajv): { fn: any; builtSchema: JsonSchema } {
+    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 as any)
+      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<any>(builtSchema, fn)
+      }
     }
 
-    return this[HIDDEN_AJV_SCHEMA]
+    return { fn, builtSchema }
   }
 
   getSchema(): JsonSchema {
@@ -795,6 +416,7 @@ export class JsonSchemaTerminal<OUT, Opt> {
   clone(): this {
     const cloned = Object.create(Object.getPrototypeOf(this))
     cloned.schema = deepCopyPreservingFunctions(this.schema)
+    cloned._cfg = this._cfg
     return cloned
   }
 
@@ -805,22 +427,37 @@ export class JsonSchemaTerminal<OUT, Opt> {
   }
 
   validate(input: unknown, opt?: AjvValidationOptions): OUT {
-    return this.ajvSchema.validate(input, opt)
+    const [err, output] = this.getValidationResult(input, opt)
+    if (err) throw err
+    return output
   }
 
   isValid(input: unknown, opt?: AjvValidationOptions): boolean {
-    return this.ajvSchema.isValid(input, opt)
+    const [err] = this.getValidationResult(input, opt)
+    return !err
   }
 
   getValidationResult(
     input: unknown,
     opt: AjvValidationOptions = {},
   ): ValidationFunctionResult<OUT, AjvValidationError> {
-    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<OUT>(fn, builtSchema, input, opt, inputName)
   }
 
-  getValidationFunction(): ValidationFunction<OUT, AjvValidationError> {
-    return this.ajvSchema.getValidationFunction()
+  getValidationFunction(
+    opt: AjvValidationOptions = {},
+  ): ValidationFunction<OUT, AjvValidationError> {
+    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,
+      })
+    }
   }
 
   /**
@@ -832,11 +469,11 @@ export class JsonSchemaTerminal<OUT, Opt> {
    *
    * If you throw an error from this function, it will show up as an error in the validation.
    */
-  postValidation<OUT2 = OUT>(fn: PostValidatonFn<OUT, OUT2>): JsonSchemaTerminal<OUT2, Opt> {
+  postValidation<OUT2 = OUT>(fn: PostValidatonFn<OUT, OUT2>): JSchema<OUT2, Opt> {
     const clone = this.cloneAndUpdateSchema({
       postValidation: fn,
     })
-    return clone as unknown as JsonSchemaTerminal<OUT2, Opt>
+    return clone as unknown as JSchema<OUT2, Opt>
   }
 
   /**
@@ -846,7 +483,9 @@ export class JsonSchemaTerminal<OUT, Opt> {
   opt!: Opt
 }
 
-export class JsonSchemaAnyBuilder<OUT, Opt> extends JsonSchemaTerminal<OUT, Opt> {
+// ==== JBuilder (chainable base) ====
+
+export class JBuilder<OUT, Opt> extends JSchema<OUT, Opt> {
   protected setErrorMessage(ruleName: string, errorMessage: string | undefined): void {
     if (_isUndefined(errorMessage)) return
 
@@ -859,15 +498,6 @@ export class JsonSchemaAnyBuilder<OUT, Opt> extends JsonSchemaTerminal<OUT, Opt>
    *
    * 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<ExpectedType>(): ExactMatch<ExpectedType, OUT> extends true ? this : never {
     return this.cloneAndUpdateSchema({ hasIsOfTypeCheck: true }) as any
@@ -901,78 +531,364 @@ export class JsonSchemaAnyBuilder<OUT, Opt> extends JsonSchemaTerminal<OUT, Opt>
     return this.cloneAndUpdateSchema({ type })
   }
 
-  default(v: any): this {
-    return this.cloneAndUpdateSchema({ default: v })
+  default(v: any): this {
+    return this.cloneAndUpdateSchema({ default: v })
+  }
+
+  instanceof(of: string): this {
+    return this.cloneAndUpdateSchema({ type: 'object', instanceof: of })
+  }
+
+  optional(): JBuilder<OUT | undefined, true> {
+    const clone = this.cloneAndUpdateSchema({ optionalField: true })
+    return clone as unknown as JBuilder<OUT | undefined, true>
+  }
+
+  nullable(): JBuilder<OUT | null, Opt> {
+    return new JBuilder({
+      anyOf: [this.build(), { type: 'null' }],
+    })
+  }
+
+  /**
+   * @deprecated
+   * The usage of this function is discouraged as it defeats the purpose of having type-safe validation.
+   */
+  castAs<T>(): JBuilder<T, Opt> {
+    return this as unknown as JBuilder<T, Opt>
+  }
+
+  /**
+   * Locks the given schema chain and no other modification can be done to it.
+   */
+  final(): JSchema<OUT, Opt> {
+    return new JSchema<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): JBuilder<OUT2, Opt> {
+    const { customValidations = [] } = this.schema
+    return this.cloneAndUpdateSchema({
+      customValidations: [...customValidations, validator],
+    }) as unknown as JBuilder<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>): JBuilder<OUT2, Opt> {
+    const { customConversions = [] } = this.schema
+    return this.cloneAndUpdateSchema({
+      customConversions: [...customConversions, converter],
+    }) as unknown as JBuilder<OUT2, Opt>
+  }
+}
+
+// ==== 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<
+  OUT extends string | undefined = string,
+  Opt extends boolean = false,
+> extends JBuilder<OUT, Opt> {
+  constructor() {
+    super({
+      type: 'string',
+    })
+  }
+
+  /**
+   * @param optionalValues List of values that should be considered/converted as `undefined`.
+   *
+   * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
+   * due to how mutability works in Ajv.
+   *
+   * Make sure this `optional()` call is at the end of your call chain.
+   *
+   * When `null` is included in optionalValues, the return type becomes `JSchema`
+   * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
+   */
+  override optional<T extends readonly (string | null)[] | undefined = undefined>(
+    optionalValues?: T,
+  ): T extends readonly (infer U)[]
+    ? null extends U
+      ? JSchema<OUT | undefined, true>
+      : JString<OUT | undefined, true>
+    : JString<OUT | undefined, true> {
+    if (!optionalValues) {
+      return super.optional() as any
+    }
+
+    _typeCast<(string | null)[]>(optionalValues)
+
+    let newBuilder: JSchema<OUT | undefined, true> = new JString<OUT, Opt>().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 JSchema({
+        anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
+        optionalField: true,
+      })
+    }
+
+    return newBuilder as any
+  }
+
+  regex(pattern: RegExp, opt?: JsonBuilderRuleOpt): this {
+    _assert(
+      !pattern.flags,
+      `Regex flags are not supported by JSON Schema. Received: /${pattern.source}/${pattern.flags}`,
+    )
+    return this.pattern(pattern.source, opt)
+  }
+
+  pattern(pattern: string, opt?: JsonBuilderRuleOpt): this {
+    const clone = this.cloneAndUpdateSchema({ pattern })
+    if (opt?.name) clone.setErrorMessage('pattern', `is not a valid ${opt.name}`)
+    if (opt?.msg) clone.setErrorMessage('pattern', opt.msg)
+    return clone
+  }
+
+  minLength(minLength: number): this {
+    return this.cloneAndUpdateSchema({ minLength })
+  }
+
+  maxLength(maxLength: number): this {
+    return this.cloneAndUpdateSchema({ maxLength })
+  }
+
+  length(exactLength: number): this
+  length(minLength: number, maxLength: number): this
+  length(minLengthOrExactLength: number, maxLength?: number): this {
+    const maxLengthActual = maxLength ?? minLengthOrExactLength
+    return this.minLength(minLengthOrExactLength).maxLength(maxLengthActual)
+  }
+
+  email(opt?: Partial<JsonSchemaStringEmailOptions>): this {
+    const defaultOptions: JsonSchemaStringEmailOptions = { checkTLD: true }
+    return this.cloneAndUpdateSchema({ email: { ...defaultOptions, ...opt } })
+      .trim()
+      .toLowerCase()
+  }
+
+  trim(): this {
+    return this.cloneAndUpdateSchema({ transform: { ...this.schema.transform, trim: true } })
+  }
+
+  toLowerCase(): this {
+    return this.cloneAndUpdateSchema({
+      transform: { ...this.schema.transform, toLowerCase: true },
+    })
+  }
+
+  toUpperCase(): this {
+    return this.cloneAndUpdateSchema({
+      transform: { ...this.schema.transform, toUpperCase: true },
+    })
+  }
+
+  truncate(toLength: number): this {
+    return this.cloneAndUpdateSchema({
+      transform: { ...this.schema.transform, truncate: toLength },
+    })
+  }
+
+  branded<B extends string>(): JString<B, Opt> {
+    return this as unknown as JString<B, Opt>
+  }
+
+  /**
+   * Validates that the input is a fully-specified YYYY-MM-DD formatted valid IsoDate value.
+   *
+   * All previous expectations in the schema chain are dropped - including `.optional()` -
+   * because this call effectively starts a new schema chain.
+   */
+  isoDate(): JIsoDate {
+    return new JIsoDate()
+  }
+
+  isoDateTime(): JString<IsoDateTime, Opt> {
+    return this.cloneAndUpdateSchema({ IsoDateTime: true }).branded<IsoDateTime>()
+  }
+
+  isoMonth(): JBuilder<IsoMonth, false> {
+    return new JBuilder<IsoMonth, false>({
+      type: 'string',
+      IsoMonth: {},
+    })
+  }
+
+  /**
+   * Validates the string format to be JWT.
+   * Expects the JWT to be signed!
+   */
+  jwt(): this {
+    return this.regex(JWT_REGEX, { msg: 'is not a valid JWT format' })
+  }
+
+  url(): this {
+    return this.regex(URL_REGEX, { msg: 'is not a valid URL format' })
+  }
+
+  ipv4(): this {
+    return this.regex(IPV4_REGEX, { msg: 'is not a valid IPv4 format' })
+  }
+
+  ipv6(): this {
+    return this.regex(IPV6_REGEX, { msg: 'is not a valid IPv6 format' })
+  }
+
+  slug(): this {
+    return this.regex(SLUG_REGEX, { msg: 'is not a valid slug format' })
+  }
+
+  semVer(): this {
+    return this.regex(SEMVER_REGEX, { msg: 'is not a valid semver format' })
+  }
+
+  languageTag(): this {
+    return this.regex(LANGUAGE_TAG_REGEX, { msg: 'is not a valid language format' })
+  }
+
+  countryCode(): this {
+    return this.regex(COUNTRY_CODE_REGEX, { msg: 'is not a valid country code format' })
+  }
+
+  currency(): this {
+    return this.regex(CURRENCY_REGEX, { msg: 'is not a valid currency format' })
+  }
+
+  /**
+   * Validates that the input is a valid IANATimzone value.
+   *
+   * All previous expectations in the schema chain are dropped - including `.optional()` -
+   * because this call effectively starts a new schema chain as an `enum` validation.
+   */
+  ianaTimezone(): JEnum<IANATimezone, false> {
+    // UTC is added to assist unit-testing, which uses UTC by default (not technically a valid Iana timezone identifier)
+    return j.enum(TIMEZONES, { msg: 'is an invalid IANA timezone' }).branded<IANATimezone>()
+  }
+
+  base64Url(): this {
+    return this.regex(BASE64URL_REGEX, {
+      msg: 'contains characters not allowed in Base64 URL characterset',
+    })
   }
 
-  instanceof(of: string): this {
-    return this.cloneAndUpdateSchema({ type: 'object', instanceof: of })
+  uuid(): this {
+    return this.regex(UUID_REGEX, { msg: 'is an invalid UUID' })
   }
+}
 
-  optional(): JsonSchemaAnyBuilder<OUT | undefined, true> {
-    const clone = this.cloneAndUpdateSchema({ optionalField: true })
-    return clone as unknown as JsonSchemaAnyBuilder<OUT | undefined, true>
-  }
+export interface JsonSchemaStringEmailOptions {
+  checkTLD: boolean
+}
 
-  nullable(): JsonSchemaAnyBuilder<OUT | null, Opt> {
-    return new JsonSchemaAnyBuilder({
-      anyOf: [this.build(), { type: 'null' }],
+export class JIsoDate<Opt extends boolean = false> extends JBuilder<IsoDate, Opt> {
+  constructor() {
+    super({
+      type: 'string',
+      IsoDate: {},
     })
   }
 
   /**
-   * @deprecated
-   * The usage of this function is discouraged as it defeats the purpose of having type-safe validation.
+   * @param nullValue Pass `null` to have `null` values be considered/converted as `undefined`.
+   *
+   * 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 `JSchema`
+   * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
    */
-  castAs<T>(): JsonSchemaAnyBuilder<T, Opt> {
-    return this as unknown as JsonSchemaAnyBuilder<T, Opt>
+  override optional<N extends null | undefined = undefined>(
+    nullValue?: N,
+  ): N extends null ? JSchema<IsoDate | undefined, true> : JBuilder<IsoDate | undefined, true> {
+    if (nullValue === undefined) {
+      return super.optional() as any
+    }
+
+    // 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 an ObjectSchema anymore.
+    return new JSchema({
+      anyOf: [{ type: 'null', optionalValues: [null] }, this.build()],
+      optionalField: true,
+    }) as any
   }
 
-  /**
-   * Locks the given schema chain and no other modification can be done to it.
-   */
-  final(): JsonSchemaTerminal<OUT, Opt> {
-    return new JsonSchemaTerminal<OUT, Opt>(this.schema)
+  before(date: string): this {
+    return this.cloneAndUpdateSchema({ IsoDate: { before: date } })
   }
 
-  /**
-   *
-   * @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<OUT2, Opt> {
-    const { customValidations = [] } = this.schema
-    return this.cloneAndUpdateSchema({
-      customValidations: [...customValidations, validator],
-    }) as unknown as JsonSchemaAnyBuilder<OUT2, Opt>
+  sameOrBefore(date: string): this {
+    return this.cloneAndUpdateSchema({ IsoDate: { sameOrBefore: date } })
   }
 
-  /**
-   *
-   * @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<OUT2, Opt> {
-    const { customConversions = [] } = this.schema
-    return this.cloneAndUpdateSchema({
-      customConversions: [...customConversions, converter],
-    }) as unknown as JsonSchemaAnyBuilder<OUT2, Opt>
+  after(date: string): this {
+    return this.cloneAndUpdateSchema({ IsoDate: { after: date } })
+  }
+
+  sameOrAfter(date: string): this {
+    return this.cloneAndUpdateSchema({ IsoDate: { sameOrAfter: date } })
+  }
+
+  between(fromDate: string, toDate: string, incl: Inclusiveness): this {
+    let schemaPatch: Partial<JsonSchema> = {}
+
+    if (incl === '[)') {
+      schemaPatch = { IsoDate: { sameOrAfter: fromDate, before: toDate } }
+    } else if (incl === '[]') {
+      schemaPatch = { IsoDate: { sameOrAfter: fromDate, sameOrBefore: toDate } }
+    }
+
+    return this.cloneAndUpdateSchema(schemaPatch)
   }
 }
 
-export class JsonSchemaStringBuilder<
-  OUT extends string | undefined = string,
+export interface JsonSchemaIsoDateOptions {
+  before?: string
+  sameOrBefore?: string
+  after?: string
+  sameOrAfter?: string
+}
+
+export interface JsonSchemaIsoMonthOptions {}
+
+export class JNumber<
+  OUT extends number | undefined = number,
   Opt extends boolean = false,
-> extends JsonSchemaAnyBuilder<OUT, Opt> {
+> extends JBuilder<OUT, Opt> {
   constructor() {
     super({
-      type: 'string',
+      type: 'number',
     })
   }
 
@@ -984,26 +900,23 @@ export class JsonSchemaStringBuilder<
    *
    * 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.
    */
-  override optional<T extends readonly (string | null)[] | undefined = undefined>(
+  override optional<T extends readonly (number | null)[] | undefined = undefined>(
     optionalValues?: T,
   ): T extends readonly (infer U)[]
     ? null extends U
-      ? JsonSchemaTerminal<OUT | undefined, true>
-      : JsonSchemaStringBuilder<OUT | undefined, true>
-    : JsonSchemaStringBuilder<OUT | undefined, true> {
+      ? JSchema<OUT | undefined, true>
+      : JNumber<OUT | undefined, true>
+    : JNumber<OUT | undefined, true> {
     if (!optionalValues) {
       return super.optional() as any
     }
 
-    _typeCast<(string | null)[]>(optionalValues)
+    _typeCast<(number | null)[]>(optionalValues)
 
-    let newBuilder: JsonSchemaTerminal<OUT | undefined, true> = new JsonSchemaStringBuilder<
-      OUT,
-      Opt
-    >().optional()
+    let newBuilder: JSchema<OUT | undefined, true> = new JNumber<OUT, Opt>().optional()
     const alternativesSchema = j.enum(optionalValues)
     Object.assign(newBuilder.getSchema(), {
       anyOf: [this.build(), alternativesSchema.build()],
@@ -1013,9 +926,9 @@ export class JsonSchemaStringBuilder<
     // 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.
+    // 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,162 +937,318 @@ export class JsonSchemaStringBuilder<
     return newBuilder as any
   }
 
-  regex(pattern: RegExp, opt?: JsonBuilderRuleOpt): this {
-    _assert(
-      !pattern.flags,
-      `Regex flags are not supported by JSON Schema. Received: /${pattern.source}/${pattern.flags}`,
-    )
-    return this.pattern(pattern.source, opt)
+  integer(): this {
+    return this.cloneAndUpdateSchema({ type: 'integer' })
   }
 
-  pattern(pattern: string, opt?: JsonBuilderRuleOpt): this {
-    const clone = this.cloneAndUpdateSchema({ pattern })
-    if (opt?.name) clone.setErrorMessage('pattern', `is not a valid ${opt.name}`)
-    if (opt?.msg) clone.setErrorMessage('pattern', opt.msg)
-    return clone
+  branded<B extends number>(): JNumber<B, Opt> {
+    return this as unknown as JNumber<B, Opt>
   }
 
-  minLength(minLength: number): this {
-    return this.cloneAndUpdateSchema({ minLength })
+  multipleOf(multipleOf: number): this {
+    return this.cloneAndUpdateSchema({ multipleOf })
   }
 
-  maxLength(maxLength: number): this {
-    return this.cloneAndUpdateSchema({ maxLength })
+  min(minimum: number): this {
+    return this.cloneAndUpdateSchema({ minimum })
   }
 
-  length(exactLength: number): this
-  length(minLength: number, maxLength: number): this
-  length(minLengthOrExactLength: number, maxLength?: number): this {
-    const maxLengthActual = maxLength ?? minLengthOrExactLength
-    return this.minLength(minLengthOrExactLength).maxLength(maxLengthActual)
+  exclusiveMin(exclusiveMinimum: number): this {
+    return this.cloneAndUpdateSchema({ exclusiveMinimum })
   }
 
-  email(opt?: Partial<JsonSchemaStringEmailOptions>): this {
-    const defaultOptions: JsonSchemaStringEmailOptions = { checkTLD: true }
-    return this.cloneAndUpdateSchema({ email: { ...defaultOptions, ...opt } })
-      .trim()
-      .toLowerCase()
+  max(maximum: number): this {
+    return this.cloneAndUpdateSchema({ maximum })
   }
 
-  trim(): this {
-    return this.cloneAndUpdateSchema({ transform: { ...this.schema.transform, trim: true } })
+  exclusiveMax(exclusiveMaximum: number): this {
+    return this.cloneAndUpdateSchema({ exclusiveMaximum })
   }
 
-  toLowerCase(): this {
-    return this.cloneAndUpdateSchema({
-      transform: { ...this.schema.transform, toLowerCase: true },
+  lessThan(value: number): this {
+    return this.exclusiveMax(value)
+  }
+
+  lessThanOrEqual(value: number): this {
+    return this.max(value)
+  }
+
+  moreThan(value: number): this {
+    return this.exclusiveMin(value)
+  }
+
+  moreThanOrEqual(value: number): this {
+    return this.min(value)
+  }
+
+  equal(value: number): this {
+    return this.min(value).max(value)
+  }
+
+  range(minimum: number, maximum: number, incl: Inclusiveness): this {
+    if (incl === '[)') {
+      return this.moreThanOrEqual(minimum).lessThan(maximum)
+    }
+    return this.moreThanOrEqual(minimum).lessThanOrEqual(maximum)
+  }
+
+  int32(): this {
+    const MIN_INT32 = -(2 ** 31)
+    const MAX_INT32 = 2 ** 31 - 1
+    const currentMin = this.schema.minimum ?? Number.MIN_SAFE_INTEGER
+    const currentMax = this.schema.maximum ?? Number.MAX_SAFE_INTEGER
+    const newMin = Math.max(MIN_INT32, currentMin)
+    const newMax = Math.min(MAX_INT32, currentMax)
+    return this.integer().min(newMin).max(newMax)
+  }
+
+  int64(): this {
+    const currentMin = this.schema.minimum ?? Number.MIN_SAFE_INTEGER
+    const currentMax = this.schema.maximum ?? Number.MAX_SAFE_INTEGER
+    const newMin = Math.max(Number.MIN_SAFE_INTEGER, currentMin)
+    const newMax = Math.min(Number.MAX_SAFE_INTEGER, currentMax)
+    return this.integer().min(newMin).max(newMax)
+  }
+
+  float(): this {
+    return this
+  }
+
+  double(): this {
+    return this
+  }
+
+  unixTimestamp(): JNumber<UnixTimestamp, Opt> {
+    return this.integer().min(0).max(TS_2500).branded<UnixTimestamp>()
+  }
+
+  unixTimestamp2000(): JNumber<UnixTimestamp, Opt> {
+    return this.integer().min(TS_2000).max(TS_2500).branded<UnixTimestamp>()
+  }
+
+  unixTimestampMillis(): JNumber<UnixTimestampMillis, Opt> {
+    return this.integer().min(0).max(TS_2500_MILLIS).branded<UnixTimestampMillis>()
+  }
+
+  unixTimestamp2000Millis(): JNumber<UnixTimestampMillis, Opt> {
+    return this.integer().min(TS_2000_MILLIS).max(TS_2500_MILLIS).branded<UnixTimestampMillis>()
+  }
+
+  utcOffset(): this {
+    return this.integer()
+      .multipleOf(15)
+      .min(-12 * 60)
+      .max(14 * 60)
+  }
+
+  utcOffsetHour(): this {
+    return this.integer().min(-12).max(14)
+  }
+
+  /**
+   * Specify the precision of the floating point numbers by the number of digits after the ".".
+   * Excess digits will be cut-off when the current schema is nested in an object or array schema,
+   * due to how mutability works in Ajv.
+   */
+  precision(numberOfDigits: number): this {
+    return this.cloneAndUpdateSchema({ precision: numberOfDigits })
+  }
+}
+
+export class JBoolean<
+  OUT extends boolean | undefined = boolean,
+  Opt extends boolean = false,
+> extends JBuilder<OUT, Opt> {
+  constructor() {
+    super({
+      type: 'boolean',
     })
   }
 
-  toUpperCase(): this {
-    return this.cloneAndUpdateSchema({
-      transform: { ...this.schema.transform, toUpperCase: true },
+  /**
+   * @param optionalValue One of the two possible boolean values that should be considered/converted as `undefined`.
+   *
+   * This `optionalValue` feature only works when the current schema is nested in an object or array schema,
+   * due to how mutability works in Ajv.
+   */
+  override optional(optionalValue?: boolean): JBoolean<OUT | undefined, true> {
+    if (typeof optionalValue === 'undefined') {
+      return super.optional() as unknown as JBoolean<OUT | undefined, true>
+    }
+
+    const newBuilder = new JBoolean<OUT, Opt>().optional()
+    const alternativesSchema = j.enum([optionalValue])
+    Object.assign(newBuilder.getSchema(), {
+      anyOf: [this.build(), alternativesSchema.build()],
+      optionalValues: [optionalValue],
     })
+
+    return newBuilder
   }
+}
 
-  truncate(toLength: number): this {
-    return this.cloneAndUpdateSchema({
-      transform: { ...this.schema.transform, truncate: toLength },
+export class JObject<OUT extends AnyObject, Opt extends boolean = false> extends JBuilder<
+  OUT,
+  Opt
+> {
+  constructor(props?: AnyObject, opt?: JObjectOpts) {
+    super({
+      type: 'object',
+      properties: {},
+      required: [],
+      additionalProperties: false,
+      hasIsOfTypeCheck: opt?.hasIsOfTypeCheck ?? true,
+      patternProperties: opt?.patternProperties ?? undefined,
+      keySchema: opt?.keySchema ?? undefined,
     })
-  }
 
-  branded<B extends string>(): JsonSchemaStringBuilder<B, Opt> {
-    return this as unknown as JsonSchemaStringBuilder<B, Opt>
+    if (props) addPropertiesToSchema(this.schema, props)
   }
 
   /**
-   * Validates that the input is a fully-specified YYYY-MM-DD formatted valid IsoDate value.
+   * @param nullValue Pass `null` to have `null` values be considered/converted as `undefined`.
    *
-   * All previous expectations in the schema chain are dropped - including `.optional()` -
-   * because this call effectively starts a new schema chain.
+   * 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 `JSchema`
+   * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
    */
-  isoDate(): JsonSchemaIsoDateBuilder {
-    return new JsonSchemaIsoDateBuilder()
-  }
-
-  isoDateTime(): JsonSchemaStringBuilder<IsoDateTime, Opt> {
-    return this.cloneAndUpdateSchema({ IsoDateTime: true }).branded<IsoDateTime>()
-  }
+  override optional<N extends null | undefined = undefined>(
+    nullValue?: N,
+  ): N extends null ? JSchema<OUT | undefined, true> : JBuilder<OUT | undefined, true> {
+    if (nullValue === undefined) {
+      return super.optional() as any
+    }
 
-  isoMonth(): JsonSchemaIsoMonthBuilder {
-    return new JsonSchemaIsoMonthBuilder()
+    // 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 an ObjectSchema anymore.
+    return new JSchema({
+      anyOf: [{ type: 'null', optionalValues: [null] }, this.build()],
+      optionalField: true,
+    }) as any
   }
 
   /**
-   * Validates the string format to be JWT.
-   * Expects the JWT to be signed!
+   * When set, the validation will not strip away properties that are not specified explicitly in the schema.
    */
-  jwt(): this {
-    return this.regex(JWT_REGEX, { msg: 'is not a valid JWT format' })
-  }
-
-  url(): this {
-    return this.regex(URL_REGEX, { msg: 'is not a valid URL format' })
-  }
-
-  ipv4(): this {
-    return this.regex(IPV4_REGEX, { msg: 'is not a valid IPv4 format' })
-  }
-
-  ipv6(): this {
-    return this.regex(IPV6_REGEX, { msg: 'is not a valid IPv6 format' })
-  }
 
-  slug(): this {
-    return this.regex(SLUG_REGEX, { msg: 'is not a valid slug format' })
+  allowAdditionalProperties(): this {
+    return this.cloneAndUpdateSchema({ additionalProperties: true })
   }
 
-  semVer(): this {
-    return this.regex(SEMVER_REGEX, { msg: 'is not a valid semver format' })
-  }
+  extend<P extends Record<string, JBuilder<any, any>>>(
+    props: P,
+  ): JObject<
+    Override<
+      OUT,
+      {
+        // required keys
+        [K in keyof P as P[K] extends JBuilder<any, infer IsOpt>
+          ? IsOpt extends true
+            ? never
+            : K
+          : never]: P[K] extends JBuilder<infer OUT2, any> ? OUT2 : never
+      } & {
+        // optional keys
+        [K in keyof P as P[K] extends JBuilder<any, infer IsOpt>
+          ? IsOpt extends true
+            ? K
+            : never
+          : never]?: P[K] extends JBuilder<infer OUT2, any> ? OUT2 : never
+      }
+    >,
+    false
+  > {
+    const newBuilder = new JObject()
+    _objectAssign(newBuilder.schema, deepCopyPreservingFunctions(this.schema))
 
-  languageTag(): this {
-    return this.regex(LANGUAGE_TAG_REGEX, { msg: 'is not a valid language format' })
-  }
+    const incomingSchemaBuilder = new JObject(props)
+    mergeJsonSchemaObjects(newBuilder.schema as any, incomingSchemaBuilder.schema as any)
 
-  countryCode(): this {
-    return this.regex(COUNTRY_CODE_REGEX, { msg: 'is not a valid country code format' })
-  }
+    _objectAssign(newBuilder.schema, { hasIsOfTypeCheck: false })
 
-  currency(): this {
-    return this.regex(CURRENCY_REGEX, { msg: 'is not a valid currency format' })
+    return newBuilder as any
   }
 
   /**
-   * Validates that the input is a valid IANATimzone value.
+   * Concatenates another schema to the current schema.
    *
-   * All previous expectations in the schema chain are dropped - including `.optional()` -
-   * because this call effectively starts a new schema chain as an `enum` validation.
+   * 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.
    */
-  ianaTimezone(): JsonSchemaEnumBuilder<IANATimezone, false> {
-    // UTC is added to assist unit-testing, which uses UTC by default (not technically a valid Iana timezone identifier)
-    return j.enum(TIMEZONES, { msg: 'is an invalid IANA timezone' }).branded<IANATimezone>()
+  concat<OUT2 extends AnyObject>(other: JObject<OUT2, any>): JObject<OUT & OUT2, false> {
+    const clone = this.clone()
+    mergeJsonSchemaObjects(clone.schema as any, other.schema as any)
+    _objectAssign(clone.schema, { hasIsOfTypeCheck: false })
+    return clone as unknown as JObject<OUT & OUT2, false>
   }
 
-  base64Url(): this {
-    return this.regex(BASE64URL_REGEX, {
-      msg: 'contains characters not allowed in Base64 URL characterset',
+  /**
+   * Extends the current schema with `id`, `created` and `updated` according to NC DB conventions.
+   */
+  // oxlint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
+  dbEntity() {
+    return this.extend({
+      id: j.string(),
+      created: j.number().unixTimestamp2000(),
+      updated: j.number().unixTimestamp2000(),
     })
   }
 
-  uuid(): this {
-    return this.regex(UUID_REGEX, { msg: 'is an invalid UUID' })
+  minProperties(minProperties: number): this {
+    return this.cloneAndUpdateSchema({ minProperties, minProperties2: minProperties })
+  }
+
+  maxProperties(maxProperties: number): this {
+    return this.cloneAndUpdateSchema({ maxProperties })
+  }
+
+  exclusiveProperties(propNames: readonly (keyof OUT & string)[]): this {
+    const exclusiveProperties = this.schema.exclusiveProperties ?? []
+    return this.cloneAndUpdateSchema({ exclusiveProperties: [...exclusiveProperties, propNames] })
   }
 }
 
-export interface JsonSchemaStringEmailOptions {
-  checkTLD: boolean
+interface JObjectOpts {
+  hasIsOfTypeCheck?: false
+  patternProperties?: StringMap<JsonSchema<any>>
+  keySchema?: JsonSchema
 }
 
-export class JsonSchemaIsoDateBuilder<Opt extends boolean = false> extends JsonSchemaAnyBuilder<
-  IsoDate,
+export class JObjectInfer<
+  PROPS extends Record<string, JBuilder<any, any>>,
+  Opt extends boolean = false,
+> extends JBuilder<
+  Expand<
+    {
+      [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt>
+        ? IsOpt extends true
+          ? never
+          : K
+        : never]: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never
+    } & {
+      [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt>
+        ? IsOpt extends true
+          ? K
+          : never
+        : never]?: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never
+    }
+  >,
   Opt
 > {
-  constructor() {
+  constructor(props?: PROPS) {
     super({
-      type: 'string',
-      IsoDate: {},
+      type: 'object',
+      properties: {},
+      required: [],
+      additionalProperties: false,
     })
+
+    if (props) addPropertiesToSchema(this.schema, props)
   }
 
   /**
@@ -1188,14 +1257,51 @@ export class JsonSchemaIsoDateBuilder<Opt extends boolean = false> extends JsonS
    * 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
   override optional<N extends null | undefined = undefined>(
     nullValue?: N,
   ): N extends null
-    ? JsonSchemaTerminal<IsoDate | undefined, true>
-    : JsonSchemaAnyBuilder<IsoDate | undefined, true> {
+    ? JSchema<
+        | Expand<
+            {
+              [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt>
+                ? IsOpt extends true
+                  ? never
+                  : K
+                : never]: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never
+            } & {
+              [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt>
+                ? IsOpt extends true
+                  ? K
+                  : never
+                : never]?: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never
+            }
+          >
+        | undefined,
+        true
+      >
+    : JBuilder<
+        | Expand<
+            {
+              [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt>
+                ? IsOpt extends true
+                  ? never
+                  : K
+                : never]: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never
+            } & {
+              [K in keyof PROPS as PROPS[K] extends JBuilder<any, infer IsOpt>
+                ? IsOpt extends true
+                  ? K
+                  : never
+                : never]?: PROPS[K] extends JBuilder<infer OUT, any> ? OUT : never
+            }
+          >
+        | undefined,
+        true
+      > {
     if (nullValue === undefined) {
       return super.optional() as any
     }
@@ -1204,745 +1310,811 @@ export class JsonSchemaIsoDateBuilder<Opt extends boolean = false> extends JsonS
     // 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,
     }) as any
   }
 
-  before(date: string): this {
-    return this.cloneAndUpdateSchema({ IsoDate: { before: date } })
+  /**
+   * When set, the validation will not strip away properties that are not specified explicitly in the schema.
+   */
+
+  allowAdditionalProperties(): this {
+    return this.cloneAndUpdateSchema({ additionalProperties: true })
+  }
+
+  extend<NEW_PROPS extends Record<string, JBuilder<any, any>>>(
+    props: NEW_PROPS,
+  ): JObjectInfer<
+    {
+      [K in keyof PROPS | keyof NEW_PROPS]: K extends keyof NEW_PROPS
+        ? NEW_PROPS[K]
+        : K extends keyof PROPS
+          ? PROPS[K]
+          : never
+    },
+    Opt
+  > {
+    const newBuilder = new JObjectInfer<PROPS, Opt>()
+    _objectAssign(newBuilder.schema, deepCopyPreservingFunctions(this.schema))
+
+    const incomingSchemaBuilder = new JObjectInfer<NEW_PROPS, false>(props)
+    mergeJsonSchemaObjects(newBuilder.schema as any, incomingSchemaBuilder.schema as any)
+
+    // This extend function is not type-safe as it is inferring,
+    // so even if the base schema was already type-checked,
+    // the new schema loses that quality.
+    _objectAssign(newBuilder.schema, { hasIsOfTypeCheck: false })
+
+    return newBuilder as unknown as JObjectInfer<
+      {
+        [K in keyof PROPS | keyof NEW_PROPS]: K extends keyof NEW_PROPS
+          ? NEW_PROPS[K]
+          : K extends keyof PROPS
+            ? PROPS[K]
+            : never
+      },
+      Opt
+    >
+  }
+
+  /**
+   * Extends the current schema with `id`, `created` and `updated` according to NC DB conventions.
+   */
+  // oxlint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
+  dbEntity() {
+    return this.extend({
+      id: j.string(),
+      created: j.number().unixTimestamp2000(),
+      updated: j.number().unixTimestamp2000(),
+    })
+  }
+}
+
+export class JArray<OUT, Opt> extends JBuilder<OUT[], Opt> {
+  constructor(itemsSchema: JBuilder<OUT, Opt>) {
+    super({
+      type: 'array',
+      items: itemsSchema.build(),
+    })
+  }
+
+  minLength(minItems: number): this {
+    return this.cloneAndUpdateSchema({ minItems })
+  }
+
+  maxLength(maxItems: number): this {
+    return this.cloneAndUpdateSchema({ maxItems })
+  }
+
+  length(exactLength: number): this
+  length(minItems: number, maxItems: number): this
+  length(minItemsOrExact: number, maxItems?: number): this {
+    const maxItemsActual = maxItems ?? minItemsOrExact
+    return this.minLength(minItemsOrExact).maxLength(maxItemsActual)
   }
 
-  sameOrBefore(date: string): this {
-    return this.cloneAndUpdateSchema({ IsoDate: { sameOrBefore: date } })
+  exactLength(length: number): this {
+    return this.minLength(length).maxLength(length)
   }
 
-  after(date: string): this {
-    return this.cloneAndUpdateSchema({ IsoDate: { after: date } })
+  unique(): this {
+    return this.cloneAndUpdateSchema({ uniqueItems: true })
   }
+}
 
-  sameOrAfter(date: string): this {
-    return this.cloneAndUpdateSchema({ IsoDate: { sameOrAfter: date } })
+class JSet2Builder<OUT, Opt> extends JBuilder<Set2<OUT>, Opt> {
+  constructor(itemsSchema: JBuilder<OUT, Opt>) {
+    super({
+      type: ['array', 'object'],
+      Set2: itemsSchema.build(),
+    })
   }
 
-  between(fromDate: string, toDate: string, incl: Inclusiveness): this {
-    let schemaPatch: Partial<JsonSchema> = {}
-
-    if (incl === '[)') {
-      schemaPatch = { IsoDate: { sameOrAfter: fromDate, before: toDate } }
-    } else if (incl === '[]') {
-      schemaPatch = { IsoDate: { sameOrAfter: fromDate, sameOrBefore: toDate } }
-    }
+  min(minItems: number): this {
+    return this.cloneAndUpdateSchema({ minItems })
+  }
 
-    return this.cloneAndUpdateSchema(schemaPatch)
+  max(maxItems: number): this {
+    return this.cloneAndUpdateSchema({ maxItems })
   }
 }
 
-export interface JsonSchemaIsoDateOptions {
-  before?: string
-  sameOrBefore?: string
-  after?: string
-  sameOrAfter?: string
-}
+export class JEnum<
+  OUT extends string | number | boolean | null,
+  Opt extends boolean = false,
+> extends JBuilder<OUT, Opt> {
+  constructor(enumValues: readonly OUT[], baseType: EnumBaseType, opt?: JsonBuilderRuleOpt) {
+    const jsonSchema: JsonSchema = { enum: enumValues }
+    // Specifying the base type helps in cases when we ask Ajv to coerce the types.
+    // Having only the `enum` in the schema does not trigger a coercion in Ajv.
+    if (baseType === 'string') jsonSchema.type = 'string'
+    if (baseType === 'number') jsonSchema.type = 'number'
 
-export class JsonSchemaIsoMonthBuilder<Opt extends boolean = false> extends JsonSchemaAnyBuilder<
-  IsoMonth,
-  Opt
-> {
-  constructor() {
-    super({
-      type: 'string',
-      IsoMonth: {},
-    })
+    super(jsonSchema)
+
+    if (opt?.name) this.setErrorMessage('pattern', `is not a valid ${opt.name}`)
+    if (opt?.msg) this.setErrorMessage('enum', opt.msg)
   }
-}
 
-export interface JsonSchemaIsoMonthOptions {}
+  branded<B extends OUT>(): JEnum<B, Opt> {
+    return this as unknown as JEnum<B, Opt>
+  }
+}
 
-export class JsonSchemaNumberBuilder<
-  OUT extends number | undefined = number,
-  Opt extends boolean = false,
-> extends JsonSchemaAnyBuilder<OUT, Opt> {
-  constructor() {
+export class JTuple<ITEMS extends JBuilder<any, any>[]> extends JBuilder<TupleOut<ITEMS>, false> {
+  constructor(items: ITEMS) {
     super({
-      type: 'number',
+      type: 'array',
+      prefixItems: items.map(i => i.build()),
+      minItems: items.length,
+      maxItems: items.length,
     })
   }
+}
 
-  /**
-   * @param optionalValues List of values that should be considered/converted as `undefined`.
-   *
-   * This `optionalValues` feature only works when the current schema is nested in an object or array schema,
-   * due to how mutability works in Ajv.
-   *
-   * Make sure this `optional()` call is at the end of your call chain.
-   *
-   * When `null` is included in optionalValues, the return type becomes `JsonSchemaTerminal`
-   * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
-   */
-  override optional<T extends readonly (number | null)[] | undefined = undefined>(
-    optionalValues?: T,
-  ): T extends readonly (infer U)[]
-    ? null extends U
-      ? JsonSchemaTerminal<OUT | undefined, true>
-      : JsonSchemaNumberBuilder<OUT | undefined, true>
-    : JsonSchemaNumberBuilder<OUT | undefined, true> {
-    if (!optionalValues) {
-      return super.optional() as any
-    }
-
-    _typeCast<(number | null)[]>(optionalValues)
+// ==== Standalone functions for j.object ====
 
-    let newBuilder: JsonSchemaTerminal<OUT | undefined, true> = new JsonSchemaNumberBuilder<
-      OUT,
-      Opt
-    >().optional()
-    const alternativesSchema = j.enum(optionalValues)
-    Object.assign(newBuilder.getSchema(), {
-      anyOf: [this.build(), alternativesSchema.build()],
-      optionalValues,
-    })
+function object(props: AnyObject): never
+function object<OUT extends AnyObject>(props: {
+  [K in keyof Required<OUT>]-?: JSchema<OUT[K], any>
+}): JObject<OUT, false>
 
-    // 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,
-      })
-    }
+function object<OUT extends AnyObject>(props: {
+  [key in keyof OUT]: JSchema<OUT[key], any>
+}): JObject<OUT, false> {
+  return new JObject<OUT, false>(props)
+}
 
-    return newBuilder as any
-  }
+function objectInfer<P extends Record<string, JBuilder<any, any>>>(
+  props: P,
+): JObjectInfer<P, false> {
+  return new JObjectInfer<P, false>(props)
+}
 
-  integer(): this {
-    return this.cloneAndUpdateSchema({ type: 'integer' })
-  }
+function objectDbEntity(props: AnyObject): never
+function objectDbEntity<
+  OUT extends BaseDBEntity,
+  EXTRA_KEYS extends Exclude<keyof OUT, keyof BaseDBEntity> = Exclude<
+    keyof OUT,
+    keyof BaseDBEntity
+  >,
+>(
+  props: {
+    // ✅ all non-system fields must be explicitly provided
+    [K in EXTRA_KEYS]-?: BuilderFor<OUT[K]>
+  } &
+    // ✅ if `id` differs, it's required
+    (ExactMatch<OUT['id'], BaseDBEntity['id']> extends true
+      ? { id?: BuilderFor<BaseDBEntity['id']> }
+      : { id: BuilderFor<OUT['id']> }) &
+    (ExactMatch<OUT['created'], BaseDBEntity['created']> extends true
+      ? { created?: BuilderFor<BaseDBEntity['created']> }
+      : { created: BuilderFor<OUT['created']> }) &
+    (ExactMatch<OUT['updated'], BaseDBEntity['updated']> extends true
+      ? { updated?: BuilderFor<BaseDBEntity['updated']> }
+      : { updated: BuilderFor<OUT['updated']> }),
+): JObject<OUT, false>
 
-  branded<B extends number>(): JsonSchemaNumberBuilder<B, Opt> {
-    return this as unknown as JsonSchemaNumberBuilder<B, Opt>
-  }
+function objectDbEntity(props: AnyObject): any {
+  return j.object({
+    id: j.string(),
+    created: j.number().unixTimestamp2000(),
+    updated: j.number().unixTimestamp2000(),
+    ...props,
+  })
+}
 
-  multipleOf(multipleOf: number): this {
-    return this.cloneAndUpdateSchema({ multipleOf })
-  }
+function record<
+  KS extends JBuilder<any, any>,
+  VS extends JBuilder<any, any>,
+  Opt extends boolean = SchemaOpt<VS>,
+>(
+  keySchema: KS,
+  valueSchema: VS,
+): JObject<
+  Opt extends true
+    ? Partial<Record<SchemaOut<KS>, SchemaOut<VS>>>
+    : Record<SchemaOut<KS>, SchemaOut<VS>>,
+  false
+> {
+  const keyJsonSchema = keySchema.build()
+  // Check if value schema is optional before build() strips the optionalField flag
+  const isValueOptional = (valueSchema as JSchema<any, any>).getSchema().optionalField
+  const valueJsonSchema = valueSchema.build()
 
-  min(minimum: number): this {
-    return this.cloneAndUpdateSchema({ minimum })
-  }
+  // When value schema is optional, wrap in anyOf to allow undefined values
+  const finalValueSchema: JsonSchema = isValueOptional
+    ? { anyOf: [{ isUndefined: true }, valueJsonSchema] }
+    : valueJsonSchema
 
-  exclusiveMin(exclusiveMinimum: number): this {
-    return this.cloneAndUpdateSchema({ exclusiveMinimum })
-  }
+  return new JObject<
+    Opt extends true
+      ? Partial<Record<SchemaOut<KS>, SchemaOut<VS>>>
+      : Record<SchemaOut<KS>, SchemaOut<VS>>,
+    false
+  >([], {
+    hasIsOfTypeCheck: false,
+    keySchema: keyJsonSchema,
+    patternProperties: {
+      ['^.*$']: finalValueSchema,
+    },
+  })
+}
 
-  max(maximum: number): this {
-    return this.cloneAndUpdateSchema({ maximum })
+function withRegexKeys<S extends JBuilder<any, any>>(
+  keyRegex: RegExp | string,
+  schema: S,
+): JObject<StringMap<SchemaOut<S>>, false> {
+  if (keyRegex instanceof RegExp) {
+    _assert(
+      !keyRegex.flags,
+      `Regex flags are not supported by JSON Schema. Received: /${keyRegex.source}/${keyRegex.flags}`,
+    )
   }
+  const pattern = keyRegex instanceof RegExp ? keyRegex.source : keyRegex
+  const jsonSchema = schema.build()
 
-  exclusiveMax(exclusiveMaximum: number): this {
-    return this.cloneAndUpdateSchema({ exclusiveMaximum })
-  }
+  return new JObject<StringMap<SchemaOut<S>>, false>([], {
+    hasIsOfTypeCheck: false,
+    patternProperties: {
+      [pattern]: jsonSchema,
+    },
+  })
+}
 
-  lessThan(value: number): this {
-    return this.exclusiveMax(value)
+/**
+ * Builds the object schema with the indicated `keys` and uses the `schema` for their validation.
+ */
+function withEnumKeys<
+  const T extends readonly (string | number)[] | StringEnum | NumberEnum,
+  S extends JBuilder<any, any>,
+  K extends string | number = EnumKeyUnion<T>,
+  Opt extends boolean = SchemaOpt<S>,
+>(
+  keys: T,
+  schema: S,
+): JObject<Opt extends true ? { [P in K]?: SchemaOut<S> } : { [P in K]: SchemaOut<S> }, false> {
+  let enumValues: readonly (string | number)[] | undefined
+  if (Array.isArray(keys)) {
+    _assert(
+      isEveryItemPrimitive(keys),
+      'Every item in the key list should be string, number or symbol',
+    )
+    enumValues = keys
+  } else if (typeof keys === 'object') {
+    const enumType = getEnumType(keys)
+    _assert(
+      enumType === 'NumberEnum' || enumType === 'StringEnum',
+      'The key list should be StringEnum or NumberEnum',
+    )
+    if (enumType === 'NumberEnum') {
+      enumValues = _numberEnumValues(keys as NumberEnum)
+    } else if (enumType === 'StringEnum') {
+      enumValues = _stringEnumValues(keys as StringEnum)
+    }
   }
 
-  lessThanOrEqual(value: number): this {
-    return this.max(value)
-  }
+  _assert(enumValues, 'The key list should be an array of values, NumberEnum or a StringEnum')
 
-  moreThan(value: number): this {
-    return this.exclusiveMin(value)
-  }
+  const typedValues = enumValues as readonly K[]
+  const props = Object.fromEntries(typedValues.map(key => [key, schema])) as any
 
-  moreThanOrEqual(value: number): this {
-    return this.min(value)
-  }
+  return new JObject<
+    Opt extends true ? { [P in K]?: SchemaOut<S> } : { [P in K]: SchemaOut<S> },
+    false
+  >(props, { hasIsOfTypeCheck: false })
+}
 
-  equal(value: number): this {
-    return this.min(value).max(value)
-  }
+// ==== AjvSchema compat wrapper ====
 
-  range(minimum: number, maximum: number, incl: Inclusiveness): this {
-    if (incl === '[)') {
-      return this.moreThanOrEqual(minimum).lessThan(maximum)
+/**
+ * On creation - compiles ajv validation function.
+ * Provides convenient methods, error reporting, etc.
+ */
+export class AjvSchema<OUT> {
+  private constructor(
+    public schema: JsonSchema<OUT>,
+    cfg: Partial<AjvSchemaCfg> = {},
+    preCompiledFn?: any,
+  ) {
+    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),
     }
-    return this.moreThanOrEqual(minimum).lessThanOrEqual(maximum)
-  }
-
-  int32(): this {
-    const MIN_INT32 = -(2 ** 31)
-    const MAX_INT32 = 2 ** 31 - 1
-    const currentMin = this.schema.minimum ?? Number.MIN_SAFE_INTEGER
-    const currentMax = this.schema.maximum ?? Number.MAX_SAFE_INTEGER
-    const newMin = Math.max(MIN_INT32, currentMin)
-    const newMax = Math.min(MAX_INT32, currentMax)
-    return this.integer().min(newMin).max(newMax)
-  }
 
-  int64(): this {
-    const currentMin = this.schema.minimum ?? Number.MIN_SAFE_INTEGER
-    const currentMax = this.schema.maximum ?? Number.MAX_SAFE_INTEGER
-    const newMin = Math.max(Number.MIN_SAFE_INTEGER, currentMin)
-    const newMax = Math.min(Number.MAX_SAFE_INTEGER, currentMax)
-    return this.integer().min(newMin).max(newMax)
+    if (preCompiledFn) {
+      this._compiledFn = preCompiledFn
+    } else if (!cfg.lazy) {
+      this._getValidateFn() // compile eagerly
+    }
   }
 
-  float(): this {
-    return this
+  /**
+   * Shortcut for AjvSchema.create(schema, { lazy: true })
+   */
+  static createLazy<OUT>(
+    schema: SchemaHandledByAjv<OUT>,
+    cfg?: Partial<AjvSchemaCfg>,
+  ): AjvSchema<OUT> {
+    return AjvSchema.create(schema, {
+      lazy: true,
+      ...cfg,
+    })
   }
 
-  double(): this {
-    return this
-  }
+  /**
+   * 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<OUT>(schema: SchemaHandledByAjv<OUT>, cfg?: Partial<AjvSchemaCfg>): AjvSchema<OUT> {
+    if (schema instanceof AjvSchema) return schema
 
-  unixTimestamp(): JsonSchemaNumberBuilder<UnixTimestamp, Opt> {
-    return this.integer().min(0).max(TS_2500).branded<UnixTimestamp>()
-  }
+    if (AjvSchema.isSchemaWithCachedAjvSchema<typeof schema, OUT>(schema)) {
+      return AjvSchema.requireCachedAjvSchema<typeof schema, OUT>(schema)
+    }
 
-  unixTimestamp2000(): JsonSchemaNumberBuilder<UnixTimestamp, Opt> {
-    return this.integer().min(TS_2000).max(TS_2500).branded<UnixTimestamp>()
-  }
+    let jsonSchema: JsonSchema<OUT>
 
-  unixTimestampMillis(): JsonSchemaNumberBuilder<UnixTimestampMillis, Opt> {
-    return this.integer().min(0).max(TS_2500_MILLIS).branded<UnixTimestampMillis>()
-  }
+    if (schema instanceof JSchema) {
+      // oxlint-disable typescript-eslint(no-unnecessary-type-assertion)
+      jsonSchema = (schema as JSchema<OUT, any>).build()
+      AjvSchema.requireValidJsonSchema(jsonSchema)
+    } else {
+      jsonSchema = schema
+    }
 
-  unixTimestamp2000Millis(): JsonSchemaNumberBuilder<UnixTimestampMillis, Opt> {
-    return this.integer().min(TS_2000_MILLIS).max(TS_2500_MILLIS).branded<UnixTimestampMillis>()
-  }
+    // 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
 
-  utcOffset(): this {
-    return this.integer()
-      .multipleOf(15)
-      .min(-12 * 60)
-      .max(14 * 60)
-  }
+    const ajvSchema = new AjvSchema<OUT>(jsonSchema, cfg)
+    AjvSchema.cacheAjvSchema(schema, ajvSchema)
 
-  utcOffsetHour(): this {
-    return this.integer().min(-12).max(14)
+    return ajvSchema
   }
 
   /**
-   * Specify the precision of the floating point numbers by the number of digits after the ".".
-   * Excess digits will be cut-off when the current schema is nested in an object or array schema,
-   * due to how mutability works in Ajv.
+   * Creates a minimal AjvSchema wrapper from a pre-compiled validate function.
+   * Used internally by JSchema to cache a compatible AjvSchema instance.
    */
-  precision(numberOfDigits: number): this {
-    return this.cloneAndUpdateSchema({ precision: numberOfDigits })
+  static _wrap<OUT>(schema: JsonSchema<OUT>, compiledFn: any): AjvSchema<OUT> {
+    return new AjvSchema<OUT>(schema, {}, compiledFn)
   }
-}
 
-export class JsonSchemaBooleanBuilder<
-  OUT extends boolean | undefined = boolean,
-  Opt extends boolean = false,
-> extends JsonSchemaAnyBuilder<OUT, Opt> {
-  constructor() {
-    super({
-      type: 'boolean',
-    })
+  static isSchemaWithCachedAjvSchema<Base, OUT>(
+    schema: Base,
+  ): schema is WithCachedAjvSchema<Base, OUT> {
+    return !!(schema as any)?.[HIDDEN_AJV_SCHEMA]
   }
 
-  /**
-   * @param optionalValue One of the two possible boolean values that should be considered/converted as `undefined`.
-   *
-   * This `optionalValue` feature only works when the current schema is nested in an object or array schema,
-   * due to how mutability works in Ajv.
-   */
-  override optional(optionalValue?: boolean): JsonSchemaBooleanBuilder<OUT | undefined, true> {
-    if (typeof optionalValue === 'undefined') {
-      return super.optional() as unknown as JsonSchemaBooleanBuilder<OUT | undefined, true>
-    }
-
-    const newBuilder = new JsonSchemaBooleanBuilder<OUT, Opt>().optional()
-    const alternativesSchema = j.enum([optionalValue])
-    Object.assign(newBuilder.getSchema(), {
-      anyOf: [this.build(), alternativesSchema.build()],
-      optionalValues: [optionalValue],
-    })
-
-    return newBuilder
+  static cacheAjvSchema<Base extends AnyObject, OUT>(
+    schema: Base,
+    ajvSchema: AjvSchema<OUT>,
+  ): WithCachedAjvSchema<Base, OUT> {
+    return Object.assign(schema, { [HIDDEN_AJV_SCHEMA]: ajvSchema })
   }
-}
-
-export class JsonSchemaObjectBuilder<
-  OUT extends AnyObject,
-  Opt extends boolean = false,
-> extends JsonSchemaAnyBuilder<OUT, Opt> {
-  constructor(props?: AnyObject, opt?: JsonSchemaObjectBuilderOpts) {
-    super({
-      type: 'object',
-      properties: {},
-      required: [],
-      additionalProperties: false,
-      hasIsOfTypeCheck: opt?.hasIsOfTypeCheck ?? true,
-      patternProperties: opt?.patternProperties ?? undefined,
-      keySchema: opt?.keySchema ?? undefined,
-    })
 
-    if (props) this.addProperties(props)
+  static requireCachedAjvSchema<Base, OUT>(schema: WithCachedAjvSchema<Base, OUT>): AjvSchema<OUT> {
+    return schema[HIDDEN_AJV_SCHEMA]
   }
 
-  addProperties(props: AnyObject): this {
-    const properties: Record<string, JsonSchema> = {}
-    const required: string[] = []
+  readonly cfg: AjvSchemaCfg
 
-    for (const [key, builder] of Object.entries(props)) {
-      const isOptional = (builder as JsonSchemaTerminal<any, any>).getSchema().optionalField
-      if (!isOptional) {
-        required.push(key)
-      }
+  private _compiledFn: any
 
-      const schema = builder.build()
-      properties[key] = schema
+  private _getValidateFn(): any {
+    if (!this._compiledFn) {
+      this._compiledFn = this.cfg.ajv.compile(this.schema as any)
     }
-
-    this.schema.properties = properties
-    this.schema.required = _uniq(required).sort()
-
-    return this
+    return this._compiledFn
   }
 
   /**
-   * @param nullValue Pass `null` to have `null` values be considered/converted as `undefined`.
-   *
-   * 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`
-   * (no further chaining allowed) because the schema is wrapped in an anyOf structure.
+   * It returns the original object just for convenience.
    */
-  override optional<N extends null | undefined = undefined>(
-    nullValue?: N,
-  ): N extends null
-    ? JsonSchemaTerminal<OUT | undefined, true>
-    : JsonSchemaAnyBuilder<OUT | undefined, true> {
-    if (nullValue === undefined) {
-      return super.optional() as any
-    }
-
-    // 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 an ObjectSchema anymore.
-    return new JsonSchemaTerminal({
-      anyOf: [{ type: 'null', optionalValues: [null] }, this.build()],
-      optionalField: true,
-    }) as any
+  validate(input: unknown, opt: AjvValidationOptions = {}): OUT {
+    const [err, output] = this.getValidationResult(input, opt)
+    if (err) throw err
+    return output
   }
 
-  /**
-   * When set, the validation will not strip away properties that are not specified explicitly in the schema.
-   */
-
-  allowAdditionalProperties(): this {
-    return this.cloneAndUpdateSchema({ additionalProperties: true })
+  isValid(input: unknown, opt?: AjvValidationOptions): boolean {
+    const [err] = this.getValidationResult(input, opt)
+    return !err
   }
 
-  extend<P extends Record<string, JsonSchemaAnyBuilder<any, any>>>(
-    props: P,
-  ): JsonSchemaObjectBuilder<
-    Override<
-      OUT,
-      {
-        // required keys
-        [K in keyof P as P[K] extends JsonSchemaAnyBuilder<any, infer IsOpt>
-          ? IsOpt extends true
-            ? never
-            : K
-          : never]: P[K] extends JsonSchemaAnyBuilder<infer OUT2, any> ? OUT2 : never
-      } & {
-        // optional keys
-        [K in keyof P as P[K] extends JsonSchemaAnyBuilder<any, infer IsOpt>
-          ? IsOpt extends true
-            ? K
-            : never
-          : never]?: P[K] extends JsonSchemaAnyBuilder<infer OUT2, any> ? OUT2 : never
-      }
-    >,
-    false
-  > {
-    const newBuilder = new JsonSchemaObjectBuilder()
-    _objectAssign(newBuilder.schema, deepCopyPreservingFunctions(this.schema))
-
-    const incomingSchemaBuilder = new JsonSchemaObjectBuilder(props)
-    mergeJsonSchemaObjects(newBuilder.schema as any, incomingSchemaBuilder.schema as any)
-
-    _objectAssign(newBuilder.schema, { hasIsOfTypeCheck: false })
-
-    return newBuilder as any
+  getValidationResult(
+    input: unknown,
+    opt: AjvValidationOptions = {},
+  ): ValidationFunctionResult<OUT, AjvValidationError> {
+    const fn = this._getValidateFn()
+    return executeValidation<OUT>(fn, this.schema, input, opt, this.cfg.inputName)
   }
 
-  /**
-   * Concatenates another schema to the current schema.
-   *
-   * 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<OUT2 extends AnyObject>(
-    other: JsonSchemaObjectBuilder<OUT2, any>,
-  ): JsonSchemaObjectBuilder<OUT & OUT2, false> {
-    const clone = this.clone()
-    mergeJsonSchemaObjects(clone.schema as any, other.schema as any)
-    _objectAssign(clone.schema, { hasIsOfTypeCheck: false })
-    return clone as unknown as JsonSchemaObjectBuilder<OUT & OUT2, false>
+  getValidationFunction(): ValidationFunction<OUT, AjvValidationError> {
+    return (input, opt) => {
+      return this.getValidationResult(input, {
+        mutateInput: opt?.mutateInput,
+        inputName: opt?.inputName,
+        inputId: opt?.inputId,
+      })
+    }
   }
 
-  /**
-   * Extends the current schema with `id`, `created` and `updated` according to NC DB conventions.
-   */
-  // oxlint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
-  dbEntity() {
-    return this.extend({
-      id: j.string(),
-      created: j.number().unixTimestamp2000(),
-      updated: j.number().unixTimestamp2000(),
-    })
+  private static requireValidJsonSchema(schema: JsonSchema): void {
+    // 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`.',
+    )
   }
+}
 
-  minProperties(minProperties: number): this {
-    return this.cloneAndUpdateSchema({ minProperties, minProperties2: minProperties })
-  }
+// ==== Shared validation logic ====
 
-  maxProperties(maxProperties: number): this {
-    return this.cloneAndUpdateSchema({ maxProperties })
-  }
+const separator = '\n'
 
-  exclusiveProperties(propNames: readonly (keyof OUT & string)[]): this {
-    const exclusiveProperties = this.schema.exclusiveProperties ?? []
-    return this.cloneAndUpdateSchema({ exclusiveProperties: [...exclusiveProperties, propNames] })
+function executeValidation<OUT>(
+  fn: any,
+  builtSchema: JsonSchema,
+  input: unknown,
+  opt: AjvValidationOptions = {},
+  defaultInputName?: string,
+): ValidationFunctionResult<OUT, AjvValidationError> {
+  const item =
+    opt.mutateInput !== false || typeof input !== 'object'
+      ? input // mutate
+      : _deepCopy(input) // not mutate
+
+  let valid = fn(item) // mutates item, but not input
+  _typeCast<OUT>(item)
+
+  let output: OUT = item
+  if (valid && builtSchema.postValidation) {
+    const [err, result] = _try(() => builtSchema.postValidation!(output))
+    if (err) {
+      valid = false
+      ;(fn as any).errors = [
+        {
+          instancePath: '',
+          message: err.message,
+        },
+      ]
+    } else {
+      output = result as OUT
+    }
   }
-}
 
-interface JsonSchemaObjectBuilderOpts {
-  hasIsOfTypeCheck?: false
-  patternProperties?: StringMap<JsonSchema<any>>
-  keySchema?: JsonSchema
+  if (valid) return [null, output]
+
+  const errors = fn.errors!
+
+  const {
+    inputId = _isObject(input) ? (input as any)['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]
 }
 
-export class JsonSchemaObjectInferringBuilder<
-  PROPS extends Record<string, JsonSchemaAnyBuilder<any, any>>,
-  Opt extends boolean = false,
-> extends JsonSchemaAnyBuilder<
-  Expand<
-    {
-      [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, infer IsOpt>
-        ? IsOpt extends true
-          ? never
-          : K
-        : never]: PROPS[K] extends JsonSchemaAnyBuilder<infer OUT, any> ? OUT : never
-    } & {
-      [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, infer IsOpt>
-        ? IsOpt extends true
-          ? K
-          : never
-        : never]?: PROPS[K] extends JsonSchemaAnyBuilder<infer OUT, any> ? OUT : never
+// ==== Error formatting helpers ====
+
+function applyImprovementsOnErrorMessages(
+  errors: ErrorObject<string, Record<string, any>, unknown>[] | null | undefined,
+  schema: JsonSchema,
+): void {
+  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]
+      }
     }
-  >,
-  Opt
-> {
-  constructor(props?: PROPS) {
-    super({
-      type: 'object',
-      properties: {},
-      required: [],
-      additionalProperties: false,
-    })
 
-    if (props) this.addProperties(props)
+    error.instancePath = error.instancePath.replaceAll(/\/(\d+)/g, `[$1]`).replaceAll('/', '.')
   }
+}
 
-  addProperties(props: PROPS): this {
-    const properties: Record<string, JsonSchema> = {}
-    const required: string[] = []
+/**
+ * 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: ErrorObject<string, Record<string, any>, unknown>[],
+  schema: JsonSchema,
+): void {
+  // Collect exact schemaPaths to remove (anyOf aggregates) and prefixes (null branches)
+  const exactPaths: string[] = []
+  const nullBranchPrefixes: string[] = []
 
-    for (const [key, builder] of Object.entries(props)) {
-      const isOptional = (builder as JsonSchemaTerminal<any, any>).getSchema().optionalField
-      if (!isOptional) {
-        required.push(key)
-      }
+  for (const error of errors) {
+    if (error.keyword !== 'anyOf') continue
 
-      const schema = builder.build()
-      properties[key] = schema
-    }
+    const parentSchema = resolveSchemaPath(schema, error.schemaPath)
+    if (!parentSchema) continue
 
-    this.schema.properties = properties
-    this.schema.required = _uniq(required).sort()
+    const nullIndex = unwrapNullableAnyOfIndex(parentSchema)
+    if (nullIndex === -1) continue
 
-    return this
+    exactPaths.push(error.schemaPath) // e.g. "#/anyOf"
+    const anyOfBase = error.schemaPath.slice(0, -'anyOf'.length)
+    nullBranchPrefixes.push(`${anyOfBase}anyOf/${nullIndex}/`) // e.g. "#/anyOf/1/"
   }
 
-  /**
-   * @param nullValue Pass `null` to have `null` values be considered/converted as `undefined`.
-   *
-   * 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`
-   * (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
-  override optional<N extends null | undefined = undefined>(
-    nullValue?: N,
-  ): N extends null
-    ? JsonSchemaTerminal<
-        | Expand<
-            {
-              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, infer IsOpt>
-                ? IsOpt extends true
-                  ? never
-                  : K
-                : never]: PROPS[K] extends JsonSchemaAnyBuilder<infer OUT, any> ? OUT : never
-            } & {
-              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, infer IsOpt>
-                ? IsOpt extends true
-                  ? K
-                  : never
-                : never]?: PROPS[K] extends JsonSchemaAnyBuilder<infer OUT, any> ? OUT : never
-            }
-          >
-        | undefined,
-        true
-      >
-    : JsonSchemaAnyBuilder<
-        | Expand<
-            {
-              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, infer IsOpt>
-                ? IsOpt extends true
-                  ? never
-                  : K
-                : never]: PROPS[K] extends JsonSchemaAnyBuilder<infer OUT, any> ? OUT : never
-            } & {
-              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, infer IsOpt>
-                ? IsOpt extends true
-                  ? K
-                  : never
-                : never]?: PROPS[K] extends JsonSchemaAnyBuilder<infer OUT, any> ? OUT : never
-            }
-          >
-        | undefined,
-        true
-      > {
-    if (nullValue === undefined) {
-      return super.optional() as any
-    }
+  if (!exactPaths.length) return
 
-    // 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 an ObjectSchema anymore.
-    return new JsonSchemaTerminal({
-      anyOf: [{ type: 'null', optionalValues: [null] }, this.build()],
-      optionalField: true,
-    }) as any
+  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)
+    }
   }
+}
 
-  /**
-   * When set, the validation will not strip away properties that are not specified explicitly in the schema.
-   */
+/**
+ * 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: JsonSchema, schemaPath: string): JsonSchema | undefined {
+  // 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: any = schema
+  for (const segment of segments) {
+    if (!current || typeof current !== 'object') return undefined
+    current = current[segment]
+  }
+  return current as JsonSchema | undefined
+}
 
-  allowAdditionalProperties(): this {
-    return this.cloneAndUpdateSchema({ additionalProperties: true })
-  }
+function getErrorMessageForInstancePath(
+  schema: JsonSchema | undefined,
+  instancePath: string,
+  keyword: string,
+): string | undefined {
+  if (!schema || !instancePath) return undefined
 
-  extend<NEW_PROPS extends Record<string, JsonSchemaAnyBuilder<any, any>>>(
-    props: NEW_PROPS,
-  ): JsonSchemaObjectInferringBuilder<
-    {
-      [K in keyof PROPS | keyof NEW_PROPS]: K extends keyof NEW_PROPS
-        ? NEW_PROPS[K]
-        : K extends keyof PROPS
-          ? PROPS[K]
-          : never
-    },
-    Opt
-  > {
-    const newBuilder = new JsonSchemaObjectInferringBuilder<PROPS, Opt>()
-    _objectAssign(newBuilder.schema, deepCopyPreservingFunctions(this.schema))
+  const segments = instancePath.split('/').filter(Boolean)
+  return traverseSchemaPath(schema, segments, keyword)
+}
 
-    const incomingSchemaBuilder = new JsonSchemaObjectInferringBuilder<NEW_PROPS, false>(props)
-    mergeJsonSchemaObjects(newBuilder.schema as any, incomingSchemaBuilder.schema as any)
+function traverseSchemaPath(
+  schema: JsonSchema,
+  segments: string[],
+  keyword: string,
+): string | undefined {
+  if (!segments.length) return undefined
 
-    // This extend function is not type-safe as it is inferring,
-    // so even if the base schema was already type-checked,
-    // the new schema loses that quality.
-    _objectAssign(newBuilder.schema, { hasIsOfTypeCheck: false })
+  const [currentSegment, ...remainingSegments] = segments
 
-    return newBuilder as unknown as JsonSchemaObjectInferringBuilder<
-      {
-        [K in keyof PROPS | keyof NEW_PROPS]: K extends keyof NEW_PROPS
-          ? NEW_PROPS[K]
-          : K extends keyof PROPS
-            ? PROPS[K]
-            : never
-      },
-      Opt
-    >
-  }
+  const nextSchema = getChildSchema(schema, currentSegment)
+  if (!nextSchema) return undefined
 
-  /**
-   * Extends the current schema with `id`, `created` and `updated` according to NC DB conventions.
-   */
-  // oxlint-disable-next-line @typescript-eslint/explicit-function-return-type, @typescript-eslint/explicit-module-boundary-types
-  dbEntity() {
-    return this.extend({
-      id: j.string(),
-      created: j.number().unixTimestamp2000(),
-      updated: j.number().unixTimestamp2000(),
-    })
+  if (nextSchema.errorMessages?.[keyword]) {
+    return nextSchema.errorMessages[keyword]
   }
-}
 
-export class JsonSchemaArrayBuilder<OUT, Opt> extends JsonSchemaAnyBuilder<OUT[], Opt> {
-  constructor(itemsSchema: JsonSchemaAnyBuilder<OUT, Opt>) {
-    super({
-      type: 'array',
-      items: itemsSchema.build(),
-    })
+  // Check through nullable wrapper
+  const unwrapped = unwrapNullableAnyOf(nextSchema)
+  if (unwrapped?.errorMessages?.[keyword]) {
+    return unwrapped.errorMessages[keyword]
   }
 
-  minLength(minItems: number): this {
-    return this.cloneAndUpdateSchema({ minItems })
+  if (remainingSegments.length) {
+    return traverseSchemaPath(nextSchema, remainingSegments, keyword)
   }
 
-  maxLength(maxItems: number): this {
-    return this.cloneAndUpdateSchema({ maxItems })
-  }
+  return undefined
+}
 
-  length(exactLength: number): this
-  length(minItems: number, maxItems: number): this
-  length(minItemsOrExact: number, maxItems?: number): this {
-    const maxItemsActual = maxItems ?? minItemsOrExact
-    return this.minLength(minItemsOrExact).maxLength(maxItemsActual)
-  }
+function getChildSchema(schema: JsonSchema, segment: string | undefined): JsonSchema | undefined {
+  if (!segment) return undefined
 
-  exactLength(length: number): this {
-    return this.minLength(length).maxLength(length)
-  }
+  // Unwrap nullable anyOf to find properties/items through nullable wrappers
+  const effectiveSchema = unwrapNullableAnyOf(schema) ?? schema
 
-  unique(): this {
-    return this.cloneAndUpdateSchema({ uniqueItems: true })
+  if (/^\d+$/.test(segment) && effectiveSchema.items) {
+    return getArrayItemSchema(effectiveSchema, segment)
   }
+
+  return getObjectPropertySchema(effectiveSchema, segment)
 }
 
-export class JsonSchemaSet2Builder<OUT, Opt> extends JsonSchemaAnyBuilder<Set2<OUT>, Opt> {
-  constructor(itemsSchema: JsonSchemaAnyBuilder<OUT, Opt>) {
-    super({
-      type: ['array', 'object'],
-      Set2: itemsSchema.build(),
-    })
-  }
+function getArrayItemSchema(schema: JsonSchema, indexSegment: string): JsonSchema | undefined {
+  if (!schema.items) return undefined
 
-  min(minItems: number): this {
-    return this.cloneAndUpdateSchema({ minItems })
+  if (Array.isArray(schema.items)) {
+    return schema.items[Number(indexSegment)]
   }
 
-  max(maxItems: number): this {
-    return this.cloneAndUpdateSchema({ maxItems })
-  }
+  return schema.items
 }
 
-export class JsonSchemaBufferBuilder extends JsonSchemaAnyBuilder<Buffer, false> {
-  constructor() {
-    super({
-      Buffer: true,
-    })
-  }
+function getObjectPropertySchema(schema: JsonSchema, segment: string): JsonSchema | undefined {
+  return schema.properties?.[segment as keyof typeof schema.properties]
 }
 
-export class JsonSchemaEnumBuilder<
-  OUT extends string | number | boolean | null,
-  Opt extends boolean = false,
-> extends JsonSchemaAnyBuilder<OUT, Opt> {
-  constructor(enumValues: readonly OUT[], baseType: EnumBaseType, opt?: JsonBuilderRuleOpt) {
-    const jsonSchema: JsonSchema = { enum: enumValues }
-    // Specifying the base type helps in cases when we ask Ajv to coerce the types.
-    // Having only the `enum` in the schema does not trigger a coercion in Ajv.
-    if (baseType === 'string') jsonSchema.type = 'string'
-    if (baseType === 'number') jsonSchema.type = 'number'
+function unwrapNullableAnyOf(schema: JsonSchema): JsonSchema | undefined {
+  const nullIndex = unwrapNullableAnyOfIndex(schema)
+  if (nullIndex === -1) return undefined
+  return schema.anyOf![1 - nullIndex]!
+}
 
-    super(jsonSchema)
+function unwrapNullableAnyOfIndex(schema: JsonSchema): number {
+  if (schema.anyOf?.length !== 2) return -1
+  const nullIndex = schema.anyOf.findIndex(s => s.type === 'null')
+  return nullIndex
+}
 
-    if (opt?.name) this.setErrorMessage('pattern', `is not a valid ${opt.name}`)
-    if (opt?.msg) this.setErrorMessage('enum', opt.msg)
+// ==== Utility helpers ====
+
+function addPropertiesToSchema(schema: JsonSchema, props: AnyObject): void {
+  const properties: Record<string, JsonSchema> = {}
+  const required: string[] = []
+
+  for (const [key, builder] of Object.entries(props)) {
+    const isOptional = (builder as JSchema<any, any>).getSchema().optionalField
+    if (!isOptional) {
+      required.push(key)
+    }
+
+    const builtSchema = builder.build()
+    properties[key] = builtSchema
   }
 
-  branded<B extends OUT>(): JsonSchemaEnumBuilder<B, Opt> {
-    return this as unknown as JsonSchemaEnumBuilder<B, Opt>
+  schema.properties = properties
+  schema.required = _uniq(required).sort()
+}
+
+function hasNoObjectSchemas(schema: JsonSchema): boolean {
+  if (Array.isArray(schema.type)) {
+    return schema.type.every(type =>
+      ['string', 'number', 'integer', 'boolean', 'null'].includes(type),
+    )
+  } else if (schema.anyOf) {
+    return schema.anyOf.every(hasNoObjectSchemas)
+  } else if (schema.oneOf) {
+    return schema.oneOf.every(hasNoObjectSchemas)
+  } else if (schema.enum) {
+    return true
+  } else if (schema.type === 'array') {
+    return !schema.items || hasNoObjectSchemas(schema.items)
+  } else {
+    return !!schema.type && ['string', 'number', 'integer', 'boolean', 'null'].includes(schema.type)
   }
+
+  return false
 }
 
-export class JsonSchemaTupleBuilder<
-  ITEMS extends JsonSchemaAnyBuilder<any, any>[],
-> extends JsonSchemaAnyBuilder<TupleOut<ITEMS>, false> {
-  constructor(items: ITEMS) {
-    super({
-      type: 'array',
-      prefixItems: items.map(i => i.build()),
-      minItems: items.length,
-      maxItems: items.length,
-    })
+type EnumBaseType = 'string' | 'number' | 'other'
+
+/**
+ * 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
 }
 
-export class JsonSchemaAnyOfByBuilder<OUT> extends JsonSchemaAnyBuilder<OUT, false> {
-  constructor(
-    propertyName: string,
-    schemaDictionary: Record<PropertyKey, JsonSchemaTerminal<any, any>>,
-  ) {
-    const builtSchemaDictionary: Record<string, JsonSchema> = {}
-    for (const [key, schema] of Object.entries(schemaDictionary)) {
-      builtSchemaDictionary[key] = schema.build()
-    }
+// ==== Types & Interfaces ====
 
-    super({
-      type: 'object',
-      hasIsOfTypeCheck: true,
-      anyOfBy: {
-        propertyName,
-        schemaDictionary: builtSchemaDictionary,
-      },
-    })
-  }
+export interface AjvValidationOptions {
+  /**
+   * Custom Ajv instance to use for this validation.
+   * Overrides the default Ajv or any Ajv set at construction time.
+   * Compiled functions are cached per Ajv instance.
+   */
+  ajv?: Ajv
+
+  /**
+   * Defaults to true,
+   * because that's how AJV works by default,
+   * and what gives it performance advantage.
+   * (Because we have found that deep-clone is surprisingly slow,
+   * nearly as slow as Joi validation).
+   *
+   * If set to true - AJV will mutate the input in case it needs to apply transformations
+   * (strip unknown properties, convert types, etc).
+   *
+   * If false - it will deep-clone (using JSON.stringify+parse) the input to prevent its mutation.
+   * Will return the cloned/mutated object.
+   * Please note that JSON.stringify+parse has side-effects,
+   * e.g it will transform Buffer into a weird object.
+   */
+  mutateInput?: boolean
+  inputName?: string
+  inputId?: string
+  /**
+   * Function that returns "original input".
+   * What is original input?
+   * It's an input in its original non-mutated form.
+   * Why is it needed?
+   * Because we mutates the Input here. And after its been mutated - we no longer
+   * can include it "how it was" in an error message. So, for that reason we'll use
+   * `getOriginalInput()`, if it's provided.
+   */
+  getOriginalInput?: () => unknown
 }
 
-export class JsonSchemaAnyOfTheseBuilder<OUT> extends JsonSchemaAnyBuilder<OUT, false> {
-  constructor(
-    propertyName: string,
-    schemaDictionary: Record<PropertyKey, JsonSchemaTerminal<any, any>>,
-  ) {
-    const builtSchemaDictionary: Record<string, JsonSchema> = {}
-    for (const [key, schema] of Object.entries(schemaDictionary)) {
-      builtSchemaDictionary[key] = schema.build()
-    }
+export interface AjvSchemaCfg {
+  /**
+   * Pass Ajv instance, otherwise Ajv will be created with
+   * AjvSchema default (not the same as Ajv defaults) parameters
+   */
+  ajv: Ajv
 
-    super({
-      type: 'object',
-      hasIsOfTypeCheck: true,
-      anyOfBy: {
-        propertyName,
-        schemaDictionary: builtSchemaDictionary,
-      },
-    })
-  }
+  inputName?: string
+
+  /**
+   * If true - schema will be compiled on-demand (lazily).
+   * Default: false.
+   */
+  lazy?: boolean
 }
 
-type EnumBaseType = 'string' | 'number' | 'other'
+export type SchemaHandledByAjv<OUT> = JSchema<OUT, any> | JsonSchema<OUT> | AjvSchema<OUT>
 
 export interface JsonSchema<OUT = unknown> {
   readonly out?: OUT
@@ -1951,7 +2123,6 @@ export interface JsonSchema<OUT = unknown> {
   $id?: string
   title?: string
   description?: string
-  // $comment?: string
   deprecated?: boolean
   readOnly?: boolean
   writeOnly?: boolean
@@ -2032,177 +2203,9 @@ export interface JsonSchema<OUT = unknown> {
   postValidation?: PostValidatonFn<any, OUT>
 }
 
-function object(props: AnyObject): never
-function object<OUT extends AnyObject>(props: {
-  [K in keyof Required<OUT>]-?: JsonSchemaTerminal<OUT[K], any>
-}): JsonSchemaObjectBuilder<OUT, false>
-
-function object<OUT extends AnyObject>(props: {
-  [key in keyof OUT]: JsonSchemaTerminal<OUT[key], any>
-}): JsonSchemaObjectBuilder<OUT, false> {
-  return new JsonSchemaObjectBuilder<OUT, false>(props)
-}
-
-function objectInfer<P extends Record<string, JsonSchemaAnyBuilder<any, any>>>(
-  props: P,
-): JsonSchemaObjectInferringBuilder<P, false> {
-  return new JsonSchemaObjectInferringBuilder<P, false>(props)
-}
-
-function objectDbEntity(props: AnyObject): never
-function objectDbEntity<
-  OUT extends BaseDBEntity,
-  EXTRA_KEYS extends Exclude<keyof OUT, keyof BaseDBEntity> = Exclude<
-    keyof OUT,
-    keyof BaseDBEntity
-  >,
->(
-  props: {
-    // ✅ all non-system fields must be explicitly provided
-    [K in EXTRA_KEYS]-?: BuilderFor<OUT[K]>
-  } &
-    // ✅ if `id` differs, it's required
-    (ExactMatch<OUT['id'], BaseDBEntity['id']> extends true
-      ? { id?: BuilderFor<BaseDBEntity['id']> }
-      : { id: BuilderFor<OUT['id']> }) &
-    (ExactMatch<OUT['created'], BaseDBEntity['created']> extends true
-      ? { created?: BuilderFor<BaseDBEntity['created']> }
-      : { created: BuilderFor<OUT['created']> }) &
-    (ExactMatch<OUT['updated'], BaseDBEntity['updated']> extends true
-      ? { updated?: BuilderFor<BaseDBEntity['updated']> }
-      : { updated: BuilderFor<OUT['updated']> }),
-): JsonSchemaObjectBuilder<OUT, false>
-
-function objectDbEntity(props: AnyObject): any {
-  return j.object({
-    id: j.string(),
-    created: j.number().unixTimestamp2000(),
-    updated: j.number().unixTimestamp2000(),
-    ...props,
-  })
-}
-
-function record<
-  KS extends JsonSchemaAnyBuilder<any, any>,
-  VS extends JsonSchemaAnyBuilder<any, any>,
-  Opt extends boolean = SchemaOpt<VS>,
->(
-  keySchema: KS,
-  valueSchema: VS,
-): JsonSchemaObjectBuilder<
-  Opt extends true
-    ? Partial<Record<SchemaOut<KS>, SchemaOut<VS>>>
-    : Record<SchemaOut<KS>, SchemaOut<VS>>,
-  false
-> {
-  const keyJsonSchema = keySchema.build()
-  // Check if value schema is optional before build() strips the optionalField flag
-  const isValueOptional = (valueSchema as JsonSchemaTerminal<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<SchemaOut<KS>, SchemaOut<VS>>>
-      : Record<SchemaOut<KS>, SchemaOut<VS>>,
-    false
-  >([], {
-    hasIsOfTypeCheck: false,
-    keySchema: keyJsonSchema,
-    patternProperties: {
-      ['^.*$']: finalValueSchema,
-    },
-  })
-}
-
-function withRegexKeys<S extends JsonSchemaAnyBuilder<any, any>>(
-  keyRegex: RegExp | string,
-  schema: S,
-): JsonSchemaObjectBuilder<StringMap<SchemaOut<S>>, false> {
-  if (keyRegex instanceof RegExp) {
-    _assert(
-      !keyRegex.flags,
-      `Regex flags are not supported by JSON Schema. Received: /${keyRegex.source}/${keyRegex.flags}`,
-    )
-  }
-  const pattern = keyRegex instanceof RegExp ? keyRegex.source : keyRegex
-  const jsonSchema = schema.build()
-
-  return new JsonSchemaObjectBuilder<StringMap<SchemaOut<S>>, false>([], {
-    hasIsOfTypeCheck: false,
-    patternProperties: {
-      [pattern]: jsonSchema,
-    },
-  })
-}
-
-/**
- * Builds the object schema with the indicated `keys` and uses the `schema` for their validation.
- */
-function withEnumKeys<
-  const T extends readonly (string | number)[] | StringEnum | NumberEnum,
-  S extends JsonSchemaAnyBuilder<any, any>,
-  K extends string | number = EnumKeyUnion<T>,
-  Opt extends boolean = SchemaOpt<S>,
->(
-  keys: T,
-  schema: S,
-): JsonSchemaObjectBuilder<
-  Opt extends true ? { [P in K]?: SchemaOut<S> } : { [P in K]: SchemaOut<S> },
-  false
-> {
-  let enumValues: readonly (string | number)[] | undefined
-  if (Array.isArray(keys)) {
-    _assert(
-      isEveryItemPrimitive(keys),
-      'Every item in the key list should be string, number or symbol',
-    )
-    enumValues = keys
-  } else if (typeof keys === 'object') {
-    const enumType = getEnumType(keys)
-    _assert(
-      enumType === 'NumberEnum' || enumType === 'StringEnum',
-      'The key list should be StringEnum or NumberEnum',
-    )
-    if (enumType === 'NumberEnum') {
-      enumValues = _numberEnumValues(keys as NumberEnum)
-    } else if (enumType === 'StringEnum') {
-      enumValues = _stringEnumValues(keys as StringEnum)
-    }
-  }
-
-  _assert(enumValues, 'The key list should be an array of values, NumberEnum or a StringEnum')
-
-  const typedValues = enumValues as readonly K[]
-  const props = Object.fromEntries(typedValues.map(key => [key, schema])) as any
-
-  return new JsonSchemaObjectBuilder<
-    Opt extends true ? { [P in K]?: SchemaOut<S> } : { [P in K]: SchemaOut<S> },
-    false
-  >(props, { hasIsOfTypeCheck: false })
-}
-
-function hasNoObjectSchemas(schema: JsonSchema): boolean {
-  if (Array.isArray(schema.type)) {
-    schema.type.every(type => ['string', 'number', 'integer', 'boolean', 'null'].includes(type))
-  } else if (schema.anyOf) {
-    return schema.anyOf.every(hasNoObjectSchemas)
-  } else if (schema.oneOf) {
-    return schema.oneOf.every(hasNoObjectSchemas)
-  } else if (schema.enum) {
-    return true
-  } else if (schema.type === 'array') {
-    return !schema.items || hasNoObjectSchemas(schema.items)
-  } else {
-    return !!schema.type && ['string', 'number', 'integer', 'boolean', 'null'].includes(schema.type)
-  }
-
-  return false
-}
+export type PostValidatonFn<OUT, OUT2> = (v: OUT) => OUT2
+export type CustomValidatorFn = (v: any) => string | undefined
+export type CustomConverterFn<OUT> = (v: any) => OUT
 
 type Expand<T> = { [K in keyof T]: T[K] }
 
@@ -2255,17 +2258,17 @@ type ExactMatch<A, B> =
       ? true
       : ExactMatchBase<Expand<StripIndexSignatureDeep<A>>, Expand<StripIndexSignatureDeep<B>>>
 
-type BuilderOutUnion<B extends readonly JsonSchemaAnyBuilder<any, any>[]> = {
-  [K in keyof B]: B[K] extends JsonSchemaAnyBuilder<infer O, any> ? O : never
+type BuilderOutUnion<B extends readonly JBuilder<any, any>[]> = {
+  [K in keyof B]: B[K] extends JBuilder<infer O, any> ? O : never
 }[number]
 
-type AnyOfByOut<D extends Record<PropertyKey, JsonSchemaTerminal<any, any>>> = {
-  [K in keyof D]: D[K] extends JsonSchemaTerminal<infer O, any> ? O : never
+type AnyOfByOut<D extends Record<PropertyKey, JSchema<any, any>>> = {
+  [K in keyof D]: D[K] extends JSchema<infer O, any> ? O : never
 }[keyof D]
 
-type BuilderFor<T> = JsonSchemaAnyBuilder<T, any>
+type BuilderFor<T> = JBuilder<T, any>
 
-interface JsonBuilderRuleOpt {
+export interface JsonBuilderRuleOpt {
   /**
    * Text of error message to return when the validation fails for the given rule:
    *
@@ -2289,33 +2292,9 @@ type EnumKeyUnion<T> =
       ? T[keyof T]
       : never
 
-type SchemaOut<S> = S extends JsonSchemaAnyBuilder<infer OUT, any> ? OUT : never
-type SchemaOpt<S> =
-  S extends JsonSchemaAnyBuilder<any, infer Opt> ? (Opt extends true ? true : false) : false
-
-type TupleOut<T extends readonly JsonSchemaAnyBuilder<any, any>[]> = {
-  [K in keyof T]: T[K] extends JsonSchemaAnyBuilder<infer O, any> ? O : never
-}
-
-export type PostValidatonFn<OUT, OUT2> = (v: OUT) => OUT2
-export type CustomValidatorFn = (v: any) => string | undefined
-export type CustomConverterFn<OUT> = (v: any) => OUT
+type SchemaOut<S> = S extends JBuilder<infer OUT, any> ? OUT : never
+type SchemaOpt<S> = S extends JBuilder<any, infer Opt> ? (Opt extends true ? true : false) : false
 
-/**
- * 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
+type TupleOut<T extends readonly JBuilder<any, any>[]> = {
+  [K in keyof T]: T[K] extends JBuilder<infer O, any> ? O : never
 }