@naturalcycles/nodejs-lib 15.90.2 → 15.91.0

package/src/validation/ajv/ajvSchema.ts

@@ -1,16 +1,61 @@
-import { _isObject, _lazyValue } from '@naturalcycles/js-lib'
+/* eslint-disable id-denylist */
+// oxlint-disable max-lines
+
 import type { ValidationFunction, ValidationFunctionResult } from '@naturalcycles/js-lib'
+import {
+  _isObject,
+  _isUndefined,
+  _lazyValue,
+  _numberEnumValues,
+  _stringEnumValues,
+  getEnumType,
+} from '@naturalcycles/js-lib'
+import { _uniq } from '@naturalcycles/js-lib/array'
 import { _assert } from '@naturalcycles/js-lib/error'
-import { _deepCopy, _filterNullishValues } from '@naturalcycles/js-lib/object'
+import type { Set2 } from '@naturalcycles/js-lib/object'
+import { _deepCopy, _filterNullishValues, _sortObject } from '@naturalcycles/js-lib/object'
 import { _substringBefore } from '@naturalcycles/js-lib/string'
-import { _typeCast } from '@naturalcycles/js-lib/types'
-import type { AnyObject } from '@naturalcycles/js-lib/types'
+import type {
+  AnyObject,
+  BaseDBEntity,
+  IANATimezone,
+  Inclusiveness,
+  IsoDate,
+  IsoDateTime,
+  IsoMonth,
+  NumberEnum,
+  StringEnum,
+  StringMap,
+  UnixTimestamp,
+  UnixTimestampMillis,
+} from '@naturalcycles/js-lib/types'
+import { _objectAssign, _typeCast, JWT_REGEX } from '@naturalcycles/js-lib/types'
 import type { Ajv, ErrorObject } from 'ajv'
 import { _inspect } from '../../string/inspect.js'
+import {
+  BASE64URL_REGEX,
+  COUNTRY_CODE_REGEX,
+  CURRENCY_REGEX,
+  IPV4_REGEX,
+  IPV6_REGEX,
+  LANGUAGE_TAG_REGEX,
+  SEMVER_REGEX,
+  SLUG_REGEX,
+  URL_REGEX,
+  UUID_REGEX,
+} from '../regexes.js'
+import { TIMEZONES } from '../timezones.js'
 import { AjvValidationError } from './ajvValidationError.js'
 import { getAjv } from './getAjv.js'
-import { JsonSchemaTerminal } from './jsonSchemaBuilder.js'
-import type { JsonSchema } from './jsonSchemaBuilder.js'
+import {
+  isEveryItemNumber,
+  isEveryItemPrimitive,
+  isEveryItemString,
+  JSON_SCHEMA_ORDER,
+  mergeJsonSchemaObjects,
+} from './jsonSchemaBuilder.util.js'
+
+// ==== AJV =====
 
 /**
  * On creation - compiles ajv validation function.
@@ -354,3 +399,1960 @@ export type SchemaHandledByAjv<IN, OUT = IN> =
   | JsonSchemaTerminal<IN, OUT, any>
   | JsonSchema<IN, OUT>
   | AjvSchema<IN, OUT>
+
+// ===== JsonSchemaBuilders ===== //
+
+export const j = {
+  /**
+   * Matches literally any value - equivalent to TypeScript's `any` type.
+   * Use sparingly, as it bypasses type validation entirely.
+   */
+  any(): JsonSchemaAnyBuilder<any, any, false> {
+    return new JsonSchemaAnyBuilder({})
+  },
+
+  string(): JsonSchemaStringBuilder<string, string, false> {
+    return new JsonSchemaStringBuilder()
+  },
+
+  number(): JsonSchemaNumberBuilder<number, number, false> {
+    return new JsonSchemaNumberBuilder()
+  },
+
+  boolean(): JsonSchemaBooleanBuilder<boolean, boolean, false> {
+    return new JsonSchemaBooleanBuilder()
+  },
+
+  object: Object.assign(object, {
+    dbEntity: objectDbEntity,
+    infer: objectInfer,
+    any() {
+      return j.object<AnyObject>({}).allowAdditionalProperties()
+    },
+
+    stringMap<S extends JsonSchemaTerminal<any, any, any>>(
+      schema: S,
+    ): JsonSchemaObjectBuilder<StringMap<SchemaIn<S>>, StringMap<SchemaOut<S>>> {
+      const isValueOptional = schema.getSchema().optionalField
+      const builtSchema = schema.build()
+      const finalValueSchema: JsonSchema = isValueOptional
+        ? { anyOf: [{ isUndefined: true }, builtSchema] }
+        : builtSchema
+
+      return new JsonSchemaObjectBuilder<StringMap<SchemaIn<S>>, StringMap<SchemaOut<S>>>(
+        {},
+        {
+          hasIsOfTypeCheck: false,
+          patternProperties: {
+            '^.+$': finalValueSchema,
+          },
+        },
+      )
+    },
+
+    /**
+     * @experimental Look around, maybe you find a rule that is better for your use-case.
+     *
+     * For Record<K, V> type of validations.
+     * ```ts
+     * const schema = j.object
+     *  .record(
+     *    j
+     *      .string()
+     *      .regex(/^\d{3,4}$/)
+     *      .branded<B>(),
+     *    j.number().nullable(),
+     *  )
+     *  .isOfType<Record<B, number | null>>()
+     * ```
+     *
+     * When the keys of the Record are values from an Enum, prefer `j.object.withEnumKeys`!
+     *
+     * Non-matching keys will be stripped from the object, i.e. they will not cause an error.
+     *
+     * Caveat: This rule first validates values of every properties of the object, and only then validates the keys.
+     * A consequence of that is that the validation will throw when there is an unexpected property with a value not matching the value schema.
+     */
+    record,
+
+    /**
+     * For Record<ENUM, V> type of validations.
+     *
+     * When the keys of the Record are values from an Enum,
+     * this helper is more performant and behaves in a more conventional manner than `j.object.record` would.
+     *
+     *
+     */
+    withEnumKeys,
+    withRegexKeys,
+  }),
+
+  array<IN, OUT, Opt>(
+    itemSchema: JsonSchemaAnyBuilder<IN, OUT, Opt>,
+  ): JsonSchemaArrayBuilder<IN, OUT, Opt> {
+    return new JsonSchemaArrayBuilder(itemSchema)
+  },
+
+  tuple<const S extends JsonSchemaAnyBuilder<any, any, any>[]>(
+    items: S,
+  ): JsonSchemaTupleBuilder<S> {
+    return new JsonSchemaTupleBuilder<S>(items)
+  },
+
+  set<IN, OUT, Opt>(
+    itemSchema: JsonSchemaAnyBuilder<IN, OUT, Opt>,
+  ): JsonSchemaSet2Builder<IN, OUT, Opt> {
+    return new JsonSchemaSet2Builder(itemSchema)
+  },
+
+  buffer(): JsonSchemaBufferBuilder {
+    return new JsonSchemaBufferBuilder()
+  },
+
+  enum<const T extends readonly (string | number | boolean | null)[] | StringEnum | NumberEnum>(
+    input: T,
+    opt?: JsonBuilderRuleOpt,
+  ): JsonSchemaEnumBuilder<
+    T extends readonly (infer U)[]
+      ? U
+      : T extends StringEnum
+        ? T[keyof T]
+        : T extends NumberEnum
+          ? T[keyof T]
+          : never
+  > {
+    let enumValues: readonly (string | number | boolean | null)[] | undefined
+    let baseType: EnumBaseType = 'other'
+
+    if (Array.isArray(input)) {
+      enumValues = input
+      if (isEveryItemNumber(input)) {
+        baseType = 'number'
+      } else if (isEveryItemString(input)) {
+        baseType = 'string'
+      }
+    } else if (typeof input === 'object') {
+      const enumType = getEnumType(input)
+      if (enumType === 'NumberEnum') {
+        enumValues = _numberEnumValues(input as NumberEnum)
+        baseType = 'number'
+      } else if (enumType === 'StringEnum') {
+        enumValues = _stringEnumValues(input as StringEnum)
+        baseType = 'string'
+      }
+    }
+
+    _assert(enumValues, 'Unsupported enum input')
+    return new JsonSchemaEnumBuilder(enumValues as any, baseType, opt)
+  },
+
+  /**
+   * Use only with primitive values, otherwise this function will throw to avoid bugs.
+   * To validate objects, use `anyOfBy`.
+   *
+   * Our Ajv is configured to strip unexpected properties from objects,
+   * and since Ajv is mutating the input, this means that it cannot
+   * properly validate the same data over multiple schemas.
+   *
+   * 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, any, boolean>[],
+    IN = BuilderInUnion<B>,
+    OUT = BuilderOutUnion<B>,
+  >(items: [...B]): JsonSchemaAnyBuilder<IN, 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<IN, OUT, false>({
+      oneOf: schemas,
+    })
+  },
+
+  /**
+   * Use only with primitive values, otherwise this function will throw to avoid bugs.
+   * To validate objects, use `anyOfBy` or `anyOfThese`.
+   *
+   * Our Ajv is configured to strip unexpected properties from objects,
+   * and since Ajv is mutating the input, this means that it cannot
+   * properly validate the same data over multiple schemas.
+   *
+   * 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, any, boolean>[],
+    IN = BuilderInUnion<B>,
+    OUT = BuilderOutUnion<B>,
+  >(items: [...B]): JsonSchemaAnyBuilder<IN, 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<IN, OUT, false>({
+      anyOf: schemas,
+    })
+  },
+
+  /**
+   * Pick validation schema for an object based on the value of a specific property.
+   *
+   * ```
+   * const schemaMap = {
+   *   true: successSchema,
+   *   false: errorSchema
+   * }
+   *
+   * const schema = j.anyOfBy('success', schemaMap)
+   * ```
+   */
+  anyOfBy<
+    P extends string,
+    D extends Record<PropertyKey, JsonSchemaTerminal<any, any, any>>,
+    IN = AnyOfByIn<D>,
+    OUT = AnyOfByOut<D>,
+  >(propertyName: P, schemaDictionary: D): JsonSchemaAnyOfByBuilder<IN, OUT, P> {
+    return new JsonSchemaAnyOfByBuilder<IN, OUT, P>(propertyName, schemaDictionary)
+  },
+
+  /**
+   * Custom version of `anyOf` which - in contrast to the original function - does not mutate the input.
+   * This comes with a performance penalty, so do not use it where performance matters.
+   *
+   * ```
+   * const schema = j.anyOfThese([successSchema, errorSchema])
+   * ```
+   */
+  anyOfThese<
+    B extends readonly JsonSchemaAnyBuilder<any, any, boolean>[],
+    IN = BuilderInUnion<B>,
+    OUT = BuilderOutUnion<B>,
+  >(items: [...B]): JsonSchemaAnyBuilder<IN, OUT, false> {
+    return new JsonSchemaAnyBuilder<IN, OUT, false>({
+      anyOfThese: items.map(b => b.build()),
+    })
+  },
+
+  and() {
+    return {
+      silentBob: () => {
+        throw new Error('...strike back!')
+      },
+    }
+  },
+
+  literal<const V extends string | number | boolean | null>(v: V) {
+    let baseType: EnumBaseType = 'other'
+    if (typeof v === 'string') baseType = 'string'
+    if (typeof v === 'number') baseType = 'number'
+    return new JsonSchemaEnumBuilder<V>([v], baseType)
+  },
+}
+
+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
+
+/*
+  Notes for future reference
+
+  Q: Why do we need `Opt` - when `IN` and `OUT` already carries the `| undefined`?
+  A: Because of objects. Without `Opt`, an optional field would be inferred as `{ foo: string | undefined }`,
+     which means that the `foo` property would be mandatory, it's just that its value can be `undefined` as well.
+     With `Opt`, we can infer it as `{ foo?: string | undefined }`.
+*/
+
+export class JsonSchemaTerminal<IN, OUT, Opt> {
+  protected [HIDDEN_AJV_SCHEMA]: AjvSchema<any, any> | undefined
+  protected schema: JsonSchema
+
+  constructor(schema: JsonSchema) {
+    this.schema = schema
+  }
+
+  get ajvSchema(): AjvSchema<any, any> {
+    if (!this[HIDDEN_AJV_SCHEMA]) {
+      this[HIDDEN_AJV_SCHEMA] = AjvSchema.create<IN, OUT>(this)
+    }
+
+    return this[HIDDEN_AJV_SCHEMA]
+  }
+
+  getSchema(): JsonSchema {
+    return this.schema
+  }
+
+  /**
+   * Produces a "clean schema object" without methods.
+   * Same as if it would be JSON.stringified.
+   */
+  build(): JsonSchema<IN, OUT> {
+    _assert(
+      !(this.schema.optionalField && this.schema.default !== undefined),
+      '.optional() and .default() should not be used together - the default value makes .optional() redundant and causes incorrect type inference',
+    )
+
+    const jsonSchema = _sortObject(
+      deepCopyPreservingFunctions(this.schema) as AnyObject,
+      JSON_SCHEMA_ORDER,
+    ) as JsonSchema<IN, OUT>
+
+    delete jsonSchema.optionalField
+
+    return jsonSchema
+  }
+
+  clone(): this {
+    const cloned = Object.create(Object.getPrototypeOf(this))
+    cloned.schema = deepCopyPreservingFunctions(this.schema)
+    return cloned
+  }
+
+  cloneAndUpdateSchema(schema: Partial<JsonSchema>): this {
+    const clone = this.clone()
+    _objectAssign(clone.schema, schema)
+    return clone
+  }
+
+  validate(input: any, opt?: AjvValidationOptions<IN>): OUT {
+    return this.ajvSchema.validate(input, opt)
+  }
+
+  isValid(input: any, opt?: AjvValidationOptions<IN>): boolean {
+    return this.ajvSchema.isValid(input, opt)
+  }
+
+  getValidationResult(
+    input: any,
+    opt: AjvValidationOptions<IN> = {},
+  ): ValidationFunctionResult<OUT, AjvValidationError> {
+    return this.ajvSchema.getValidationResult(input, opt)
+  }
+
+  getValidationFunction(): ValidationFunction<any, OUT, AjvValidationError> {
+    return this.ajvSchema.getValidationFunction()
+  }
+
+  /**
+   * @experimental
+   */
+  in!: IN
+  out!: OUT
+  opt!: Opt
+}
+
+export class JsonSchemaAnyBuilder<IN, OUT, Opt> extends JsonSchemaTerminal<IN, OUT, Opt> {
+  protected setErrorMessage(ruleName: string, errorMessage: string | undefined): void {
+    if (_isUndefined(errorMessage)) return
+
+    this.schema.errorMessages ||= {}
+    this.schema.errorMessages[ruleName] = errorMessage
+  }
+
+  /**
+   * A helper function that takes a type parameter and compares it with the type inferred from the schema.
+   *
+   * 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
+  }
+
+  $schema($schema: string): this {
+    return this.cloneAndUpdateSchema({ $schema })
+  }
+
+  $schemaDraft7(): this {
+    return this.$schema('http://json-schema.org/draft-07/schema#')
+  }
+
+  $id($id: string): this {
+    return this.cloneAndUpdateSchema({ $id })
+  }
+
+  title(title: string): this {
+    return this.cloneAndUpdateSchema({ title })
+  }
+
+  description(description: string): this {
+    return this.cloneAndUpdateSchema({ description })
+  }
+
+  deprecated(deprecated = true): this {
+    return this.cloneAndUpdateSchema({ deprecated })
+  }
+
+  type(type: string): this {
+    return this.cloneAndUpdateSchema({ type })
+  }
+
+  default(v: any): this {
+    return this.cloneAndUpdateSchema({ default: v })
+  }
+
+  instanceof(of: string): this {
+    return this.cloneAndUpdateSchema({ type: 'object', instanceof: of })
+  }
+
+  optional(): JsonSchemaAnyBuilder<IN | undefined, OUT | undefined, true> {
+    const clone = this.cloneAndUpdateSchema({ optionalField: true })
+    return clone as unknown as JsonSchemaAnyBuilder<IN | undefined, OUT | undefined, true>
+  }
+
+  nullable(): JsonSchemaAnyBuilder<IN | null, OUT | null, Opt> {
+    return new JsonSchemaAnyBuilder({
+      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>(): JsonSchemaAnyBuilder<T, T, Opt> {
+    return this as unknown as JsonSchemaAnyBuilder<T, T, Opt>
+  }
+
+  /**
+   * Locks the given schema chain and no other modification can be done to it.
+   */
+  final(): JsonSchemaTerminal<IN, OUT, Opt> {
+    return new JsonSchemaTerminal<IN, OUT, Opt>(this.schema)
+  }
+
+  /**
+   *
+   * @param validator A validator function that returns an error message or undefined.
+   *
+   * You may add multiple custom validators and they will be executed in the order you added them.
+   */
+  custom<OUT2 = OUT>(validator: CustomValidatorFn): JsonSchemaAnyBuilder<IN, OUT2, Opt> {
+    const { customValidations = [] } = this.schema
+    return this.cloneAndUpdateSchema({
+      customValidations: [...customValidations, validator],
+    }) as unknown as JsonSchemaAnyBuilder<IN, OUT2, Opt>
+  }
+
+  /**
+   *
+   * @param converter A converter function that returns a new value.
+   *
+   * You may add multiple converters and they will be executed in the order you added them,
+   * each converter receiving the result from the previous one.
+   *
+   * This feature only works when the current schema is nested in an object or array schema,
+   * due to how mutability works in Ajv.
+   */
+  convert<OUT2>(converter: CustomConverterFn<OUT2>): JsonSchemaAnyBuilder<IN, OUT2, Opt> {
+    const { customConversions = [] } = this.schema
+    return this.cloneAndUpdateSchema({
+      customConversions: [...customConversions, converter],
+    }) as unknown as JsonSchemaAnyBuilder<IN, OUT2, Opt>
+  }
+}
+
+export class JsonSchemaStringBuilder<
+  IN extends string | undefined = string,
+  OUT = IN,
+  Opt extends boolean = false,
+> extends JsonSchemaAnyBuilder<IN, 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 `JsonSchemaTerminal`
+   * (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
+      ? JsonSchemaTerminal<IN | undefined, OUT | undefined, true>
+      : JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true>
+    : JsonSchemaStringBuilder<IN | undefined, OUT | undefined, true> {
+    if (!optionalValues) {
+      return super.optional() as any
+    }
+
+    _typeCast<(string | null)[]>(optionalValues)
+
+    let newBuilder: JsonSchemaTerminal<IN | undefined, OUT | undefined, true> =
+      new JsonSchemaStringBuilder<IN, OUT, Opt>().optional()
+    const alternativesSchema = j.enum(optionalValues)
+    Object.assign(newBuilder.getSchema(), {
+      anyOf: [this.build(), alternativesSchema.build()],
+      optionalValues,
+    })
+
+    // When `null` is specified, we want `null` to be stripped and the value to become `undefined`,
+    // so we must allow `null` values to be parsed by Ajv,
+    // but the typing should not reflect that.
+    // We also cannot accept more rules attached, since we're not building a StringSchema anymore.
+    if (optionalValues.includes(null)) {
+      newBuilder = new JsonSchemaTerminal({
+        anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
+        optionalField: true,
+      })
+    }
+
+    return newBuilder as any
+  }
+
+  regex(pattern: RegExp, opt?: JsonBuilderRuleOpt): this {
+    _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>(): JsonSchemaStringBuilder<B, B, Opt> {
+    return this as unknown as JsonSchemaStringBuilder<B, 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(): JsonSchemaIsoDateBuilder {
+    return new JsonSchemaIsoDateBuilder()
+  }
+
+  isoDateTime(): JsonSchemaStringBuilder<IsoDateTime | IN, IsoDateTime, Opt> {
+    return this.cloneAndUpdateSchema({ IsoDateTime: true }).branded<IsoDateTime>() as any
+  }
+
+  isoMonth(): JsonSchemaIsoMonthBuilder {
+    return new JsonSchemaIsoMonthBuilder()
+  }
+
+  /**
+   * 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(): JsonSchemaEnumBuilder<string | IANATimezone, 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>() as any
+  }
+
+  base64Url(): this {
+    return this.regex(BASE64URL_REGEX, {
+      msg: 'contains characters not allowed in Base64 URL characterset',
+    })
+  }
+
+  uuid(): this {
+    return this.regex(UUID_REGEX, { msg: 'is an invalid UUID' })
+  }
+}
+
+export interface JsonSchemaStringEmailOptions {
+  checkTLD: boolean
+}
+
+export class JsonSchemaIsoDateBuilder<Opt extends boolean = false> extends JsonSchemaAnyBuilder<
+  string | IsoDate,
+  IsoDate,
+  Opt
+> {
+  constructor() {
+    super({
+      type: 'string',
+      IsoDate: {},
+    })
+  }
+
+  /**
+   * @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.
+   */
+  override optional<N extends null | undefined = undefined>(
+    nullValue?: N,
+  ): N extends null
+    ? JsonSchemaTerminal<string | IsoDate | null | undefined, IsoDate | undefined, true>
+    : JsonSchemaAnyBuilder<string | IsoDate | undefined, 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 JsonSchemaTerminal({
+      anyOf: [{ type: 'null', optionalValues: [null] }, this.build()],
+      optionalField: true,
+    }) as any
+  }
+
+  before(date: string): this {
+    return this.cloneAndUpdateSchema({ IsoDate: { before: date } })
+  }
+
+  sameOrBefore(date: string): this {
+    return this.cloneAndUpdateSchema({ IsoDate: { sameOrBefore: date } })
+  }
+
+  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 interface JsonSchemaIsoDateOptions {
+  before?: string
+  sameOrBefore?: string
+  after?: string
+  sameOrAfter?: string
+}
+
+export class JsonSchemaIsoMonthBuilder<Opt extends boolean = false> extends JsonSchemaAnyBuilder<
+  string | IsoDate,
+  IsoMonth,
+  Opt
+> {
+  constructor() {
+    super({
+      type: 'string',
+      IsoMonth: {},
+    })
+  }
+}
+
+export interface JsonSchemaIsoMonthOptions {}
+
+export class JsonSchemaNumberBuilder<
+  IN extends number | undefined = number,
+  OUT = IN,
+  Opt extends boolean = false,
+> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
+  constructor() {
+    super({
+      type: 'number',
+    })
+  }
+
+  /**
+   * @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<IN | undefined, OUT | undefined, true>
+      : JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true>
+    : JsonSchemaNumberBuilder<IN | undefined, OUT | undefined, true> {
+    if (!optionalValues) {
+      return super.optional() as any
+    }
+
+    _typeCast<(number | null)[]>(optionalValues)
+
+    let newBuilder: JsonSchemaTerminal<IN | undefined, OUT | undefined, true> =
+      new JsonSchemaNumberBuilder<IN, OUT, Opt>().optional()
+    const alternativesSchema = j.enum(optionalValues)
+    Object.assign(newBuilder.getSchema(), {
+      anyOf: [this.build(), alternativesSchema.build()],
+      optionalValues,
+    })
+
+    // When `null` is specified, we want `null` to be stripped and the value to become `undefined`,
+    // so we must allow `null` values to be parsed by Ajv,
+    // but the typing should not reflect that.
+    // We also cannot accept more rules attached, since we're not building a NumberSchema anymore.
+    if (optionalValues.includes(null)) {
+      newBuilder = new JsonSchemaTerminal({
+        anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
+        optionalField: true,
+      })
+    }
+
+    return newBuilder as any
+  }
+
+  integer(): this {
+    return this.cloneAndUpdateSchema({ type: 'integer' })
+  }
+
+  branded<B extends number>(): JsonSchemaNumberBuilder<B, B, Opt> {
+    return this as unknown as JsonSchemaNumberBuilder<B, B, Opt>
+  }
+
+  multipleOf(multipleOf: number): this {
+    return this.cloneAndUpdateSchema({ multipleOf })
+  }
+
+  min(minimum: number): this {
+    return this.cloneAndUpdateSchema({ minimum })
+  }
+
+  exclusiveMin(exclusiveMinimum: number): this {
+    return this.cloneAndUpdateSchema({ exclusiveMinimum })
+  }
+
+  max(maximum: number): this {
+    return this.cloneAndUpdateSchema({ maximum })
+  }
+
+  exclusiveMax(exclusiveMaximum: number): this {
+    return this.cloneAndUpdateSchema({ exclusiveMaximum })
+  }
+
+  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(): JsonSchemaNumberBuilder<UnixTimestamp, UnixTimestamp, Opt> {
+    return this.integer().min(0).max(TS_2500).branded<UnixTimestamp>()
+  }
+
+  unixTimestamp2000(): JsonSchemaNumberBuilder<UnixTimestamp, UnixTimestamp, Opt> {
+    return this.integer().min(TS_2000).max(TS_2500).branded<UnixTimestamp>()
+  }
+
+  unixTimestampMillis(): JsonSchemaNumberBuilder<UnixTimestampMillis, UnixTimestampMillis, Opt> {
+    return this.integer().min(0).max(TS_2500_MILLIS).branded<UnixTimestampMillis>()
+  }
+
+  unixTimestamp2000Millis(): JsonSchemaNumberBuilder<
+    UnixTimestampMillis,
+    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 JsonSchemaBooleanBuilder<
+  IN extends boolean | undefined = boolean,
+  OUT = IN,
+  Opt extends boolean = false,
+> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
+  constructor() {
+    super({
+      type: 'boolean',
+    })
+  }
+
+  /**
+   * @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<IN | undefined, OUT | undefined, true> {
+    if (typeof optionalValue === 'undefined') {
+      return super.optional() as unknown as JsonSchemaBooleanBuilder<
+        IN | undefined,
+        OUT | undefined,
+        true
+      >
+    }
+
+    const newBuilder = new JsonSchemaBooleanBuilder<IN, OUT, Opt>().optional()
+    const alternativesSchema = j.enum([optionalValue])
+    Object.assign(newBuilder.getSchema(), {
+      anyOf: [this.build(), alternativesSchema.build()],
+      optionalValues: [optionalValue],
+    })
+
+    return newBuilder
+  }
+}
+
+export class JsonSchemaObjectBuilder<
+  IN extends AnyObject,
+  OUT extends AnyObject,
+  Opt extends boolean = false,
+> extends JsonSchemaAnyBuilder<IN, 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)
+  }
+
+  addProperties(props: AnyObject): this {
+    const properties: Record<string, JsonSchema> = {}
+    const required: string[] = []
+
+    for (const [key, builder] of Object.entries(props)) {
+      const isOptional = (builder as JsonSchemaTerminal<any, any, any>).getSchema().optionalField
+      if (!isOptional) {
+        required.push(key)
+      }
+
+      const schema = builder.build()
+      properties[key] = schema
+    }
+
+    this.schema.properties = properties
+    this.schema.required = _uniq(required).sort()
+
+    return this
+  }
+
+  /**
+   * @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.
+   */
+  override optional<N extends null | undefined = undefined>(
+    nullValue?: N,
+  ): N extends null
+    ? JsonSchemaTerminal<IN | null | undefined, OUT | undefined, true>
+    : JsonSchemaAnyBuilder<IN | undefined, 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
+  }
+
+  /**
+   * 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<P extends Record<string, JsonSchemaAnyBuilder<any, any, any>>>(
+    props: P,
+  ): JsonSchemaObjectBuilder<
+    RelaxIndexSignature<
+      OptionalDbEntityFields<
+        Override<
+          IN,
+          {
+            [K in keyof P]?: P[K] extends JsonSchemaAnyBuilder<infer IN2, any, any> ? IN2 : never
+          }
+        >
+      >
+    >,
+    Override<
+      OUT,
+      {
+        // required keys
+        [K in keyof P as P[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+          ? IsOpt extends true
+            ? never
+            : K
+          : never]: P[K] extends JsonSchemaAnyBuilder<any, infer OUT2, any> ? OUT2 : never
+      } & {
+        // optional keys
+        [K in keyof P as P[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+          ? IsOpt extends true
+            ? K
+            : never
+          : never]?: P[K] extends JsonSchemaAnyBuilder<any, 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
+  }
+
+  /**
+   * 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<IN2 extends AnyObject, OUT2 extends AnyObject>(
+    other: JsonSchemaObjectBuilder<IN2, OUT2, any>,
+  ): JsonSchemaObjectBuilder<IN & IN2, 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<IN & IN2, OUT & OUT2, false>
+  }
+
+  /**
+   * 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(),
+    })
+  }
+
+  minProperties(minProperties: number): this {
+    return this.cloneAndUpdateSchema({ minProperties, minProperties2: minProperties })
+  }
+
+  maxProperties(maxProperties: number): this {
+    return this.cloneAndUpdateSchema({ maxProperties })
+  }
+
+  exclusiveProperties(propNames: readonly (keyof IN & string)[]): this {
+    const exclusiveProperties = this.schema.exclusiveProperties ?? []
+    return this.cloneAndUpdateSchema({ exclusiveProperties: [...exclusiveProperties, propNames] })
+  }
+}
+
+interface JsonSchemaObjectBuilderOpts {
+  hasIsOfTypeCheck?: false
+  patternProperties?: StringMap<JsonSchema<any, any>>
+  keySchema?: JsonSchema
+}
+
+export class JsonSchemaObjectInferringBuilder<
+  PROPS extends Record<string, JsonSchemaAnyBuilder<any, any, any>>,
+  Opt extends boolean = false,
+> extends JsonSchemaAnyBuilder<
+  Expand<
+    {
+      [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+        ? IsOpt extends true
+          ? never
+          : K
+        : never]: PROPS[K] extends JsonSchemaAnyBuilder<infer IN, any, any> ? IN : never
+    } & {
+      [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+        ? IsOpt extends true
+          ? K
+          : never
+        : never]?: PROPS[K] extends JsonSchemaAnyBuilder<infer IN, any, any> ? IN : never
+    }
+  >,
+  Expand<
+    {
+      [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+        ? IsOpt extends true
+          ? never
+          : K
+        : never]: PROPS[K] extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never
+    } & {
+      [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+        ? IsOpt extends true
+          ? K
+          : never
+        : never]?: PROPS[K] extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never
+    }
+  >,
+  Opt
+> {
+  constructor(props?: PROPS) {
+    super({
+      type: 'object',
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    })
+
+    if (props) this.addProperties(props)
+  }
+
+  addProperties(props: PROPS): this {
+    const properties: Record<string, JsonSchema> = {}
+    const required: string[] = []
+
+    for (const [key, builder] of Object.entries(props)) {
+      const isOptional = (builder as JsonSchemaTerminal<any, any, any>).getSchema().optionalField
+      if (!isOptional) {
+        required.push(key)
+      }
+
+      const schema = builder.build()
+      properties[key] = schema
+    }
+
+    this.schema.properties = properties
+    this.schema.required = _uniq(required).sort()
+
+    return this
+  }
+
+  /**
+   * @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, any, infer IsOpt>
+                ? IsOpt extends true
+                  ? never
+                  : K
+                : never]: PROPS[K] extends JsonSchemaAnyBuilder<infer IN, any, any> ? IN : never
+            } & {
+              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+                ? IsOpt extends true
+                  ? K
+                  : never
+                : never]?: PROPS[K] extends JsonSchemaAnyBuilder<infer IN, any, any> ? IN : never
+            }
+          >
+        | undefined,
+        | Expand<
+            {
+              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+                ? IsOpt extends true
+                  ? never
+                  : K
+                : never]: PROPS[K] extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never
+            } & {
+              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+                ? IsOpt extends true
+                  ? K
+                  : never
+                : never]?: PROPS[K] extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never
+            }
+          >
+        | undefined,
+        true
+      >
+    : JsonSchemaAnyBuilder<
+        | Expand<
+            {
+              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+                ? IsOpt extends true
+                  ? never
+                  : K
+                : never]: PROPS[K] extends JsonSchemaAnyBuilder<infer IN, any, any> ? IN : never
+            } & {
+              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+                ? IsOpt extends true
+                  ? K
+                  : never
+                : never]?: PROPS[K] extends JsonSchemaAnyBuilder<infer IN, any, any> ? IN : never
+            }
+          >
+        | undefined,
+        | Expand<
+            {
+              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+                ? IsOpt extends true
+                  ? never
+                  : K
+                : never]: PROPS[K] extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never
+            } & {
+              [K in keyof PROPS as PROPS[K] extends JsonSchemaAnyBuilder<any, any, infer IsOpt>
+                ? IsOpt extends true
+                  ? K
+                  : never
+                : never]?: PROPS[K] extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never
+            }
+          >
+        | 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
+  }
+
+  /**
+   * 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, JsonSchemaAnyBuilder<any, 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 incomingSchemaBuilder = new JsonSchemaObjectInferringBuilder<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 JsonSchemaObjectInferringBuilder<
+      {
+        [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 JsonSchemaArrayBuilder<IN, OUT, Opt> extends JsonSchemaAnyBuilder<IN[], OUT[], Opt> {
+  constructor(itemsSchema: JsonSchemaAnyBuilder<IN, 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)
+  }
+
+  exactLength(length: number): this {
+    return this.minLength(length).maxLength(length)
+  }
+
+  unique(): this {
+    return this.cloneAndUpdateSchema({ uniqueItems: true })
+  }
+}
+
+export class JsonSchemaSet2Builder<IN, OUT, Opt> extends JsonSchemaAnyBuilder<
+  Iterable<IN>,
+  Set2<OUT>,
+  Opt
+> {
+  constructor(itemsSchema: JsonSchemaAnyBuilder<IN, OUT, Opt>) {
+    super({
+      type: ['array', 'object'],
+      Set2: itemsSchema.build(),
+    })
+  }
+
+  min(minItems: number): this {
+    return this.cloneAndUpdateSchema({ minItems })
+  }
+
+  max(maxItems: number): this {
+    return this.cloneAndUpdateSchema({ maxItems })
+  }
+}
+
+export class JsonSchemaBufferBuilder extends JsonSchemaAnyBuilder<
+  string | any[] | ArrayBuffer | Buffer,
+  Buffer,
+  false
+> {
+  constructor() {
+    super({
+      Buffer: true,
+    })
+  }
+}
+
+export class JsonSchemaEnumBuilder<
+  IN extends string | number | boolean | null,
+  OUT extends IN = IN,
+  Opt extends boolean = false,
+> extends JsonSchemaAnyBuilder<IN, OUT, Opt> {
+  constructor(enumValues: readonly IN[], 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'
+
+    super(jsonSchema)
+
+    if (opt?.name) this.setErrorMessage('pattern', `is not a valid ${opt.name}`)
+    if (opt?.msg) this.setErrorMessage('enum', opt.msg)
+  }
+
+  branded<B extends IN>(): JsonSchemaEnumBuilder<B | IN, B, Opt> {
+    return this as unknown as JsonSchemaEnumBuilder<B | IN, B, Opt>
+  }
+}
+
+export class JsonSchemaTupleBuilder<
+  ITEMS extends JsonSchemaAnyBuilder<any, any, any>[],
+> extends JsonSchemaAnyBuilder<TupleIn<ITEMS>, TupleOut<ITEMS>, false> {
+  private readonly _items: ITEMS
+
+  constructor(items: ITEMS) {
+    super({
+      type: 'array',
+      prefixItems: items.map(i => i.build()),
+      minItems: items.length,
+      maxItems: items.length,
+    })
+
+    this._items = items
+  }
+}
+
+export class JsonSchemaAnyOfByBuilder<
+  IN,
+  OUT,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  _P extends string = string,
+> extends JsonSchemaAnyBuilder<AnyOfByInput<IN, _P> | IN, OUT, false> {
+  declare in: IN
+
+  constructor(
+    propertyName: string,
+    schemaDictionary: Record<PropertyKey, JsonSchemaTerminal<any, any, any>>,
+  ) {
+    const builtSchemaDictionary: Record<string, JsonSchema> = {}
+    for (const [key, schema] of Object.entries(schemaDictionary)) {
+      builtSchemaDictionary[key] = schema.build()
+    }
+
+    super({
+      type: 'object',
+      hasIsOfTypeCheck: true,
+      anyOfBy: {
+        propertyName,
+        schemaDictionary: builtSchemaDictionary,
+      },
+    })
+  }
+}
+
+export class JsonSchemaAnyOfTheseBuilder<
+  IN,
+  OUT,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  _P extends string = string,
+> extends JsonSchemaAnyBuilder<AnyOfByInput<IN, _P> | IN, OUT, false> {
+  declare in: IN
+
+  constructor(
+    propertyName: string,
+    schemaDictionary: Record<PropertyKey, JsonSchemaTerminal<any, any, any>>,
+  ) {
+    const builtSchemaDictionary: Record<string, JsonSchema> = {}
+    for (const [key, schema] of Object.entries(schemaDictionary)) {
+      builtSchemaDictionary[key] = schema.build()
+    }
+
+    super({
+      type: 'object',
+      hasIsOfTypeCheck: true,
+      anyOfBy: {
+        propertyName,
+        schemaDictionary: builtSchemaDictionary,
+      },
+    })
+  }
+}
+
+type EnumBaseType = 'string' | 'number' | 'other'
+
+export interface JsonSchema<IN = unknown, OUT = IN> {
+  readonly in?: IN
+  readonly out?: OUT
+
+  $schema?: string
+  $id?: string
+  title?: string
+  description?: string
+  // $comment?: string
+  deprecated?: boolean
+  readOnly?: boolean
+  writeOnly?: boolean
+
+  type?: string | string[]
+  items?: JsonSchema
+  prefixItems?: JsonSchema[]
+  properties?: {
+    [K in keyof IN & keyof OUT]: JsonSchema<IN[K], OUT[K]>
+  }
+  patternProperties?: StringMap<JsonSchema<any, any>>
+  required?: string[]
+  additionalProperties?: boolean
+  minProperties?: number
+  maxProperties?: number
+
+  default?: IN
+
+  // https://json-schema.org/understanding-json-schema/reference/conditionals.html#id6
+  if?: JsonSchema
+  then?: JsonSchema
+  else?: JsonSchema
+
+  anyOf?: JsonSchema[]
+  oneOf?: JsonSchema[]
+
+  /**
+   * This is a temporary "intermediate AST" field that is used inside the parser.
+   * In the final schema this field will NOT be present.
+   */
+  optionalField?: true
+
+  pattern?: string
+  minLength?: number
+  maxLength?: number
+  format?: string
+
+  contentMediaType?: string
+  contentEncoding?: string // e.g 'base64'
+
+  multipleOf?: number
+  minimum?: number
+  exclusiveMinimum?: number
+  maximum?: number
+  exclusiveMaximum?: number
+  minItems?: number
+  maxItems?: number
+  uniqueItems?: boolean
+
+  enum?: any
+
+  hasIsOfTypeCheck?: boolean
+
+  // Below we add custom Ajv keywords
+
+  email?: JsonSchemaStringEmailOptions
+  Set2?: JsonSchema
+  Buffer?: true
+  IsoDate?: JsonSchemaIsoDateOptions
+  IsoDateTime?: true
+  IsoMonth?: JsonSchemaIsoMonthOptions
+  instanceof?: string | string[]
+  transform?: { trim?: true; toLowerCase?: true; toUpperCase?: true; truncate?: number }
+  errorMessages?: StringMap<string>
+  optionalValues?: (string | number | boolean | null)[]
+  keySchema?: JsonSchema
+  isUndefined?: true
+  minProperties2?: number
+  exclusiveProperties?: (readonly string[])[]
+  anyOfBy?: {
+    propertyName: string
+    schemaDictionary: Record<string, JsonSchema>
+  }
+  anyOfThese?: JsonSchema[]
+  precision?: number
+  customValidations?: CustomValidatorFn[]
+  customConversions?: CustomConverterFn<any>[]
+}
+
+function object(props: AnyObject): never
+function object<IN extends AnyObject>(props: {
+  [K in keyof Required<IN>]-?: JsonSchemaTerminal<any, IN[K], any>
+}): JsonSchemaObjectBuilder<IN, IN, false>
+
+function object<IN extends AnyObject>(props: {
+  [key in keyof IN]: JsonSchemaTerminal<any, IN[key], any>
+}): JsonSchemaObjectBuilder<IN, IN, false> {
+  return new JsonSchemaObjectBuilder<IN, IN, false>(props)
+}
+
+function objectInfer<P extends Record<string, JsonSchemaAnyBuilder<any, any, any>>>(
+  props: P,
+): JsonSchemaObjectInferringBuilder<P, false> {
+  return new JsonSchemaObjectInferringBuilder<P, false>(props)
+}
+
+function objectDbEntity(props: AnyObject): never
+function objectDbEntity<
+  IN extends BaseDBEntity,
+  EXTRA_KEYS extends Exclude<keyof IN, keyof BaseDBEntity> = Exclude<keyof IN, keyof BaseDBEntity>,
+>(
+  props: {
+    // ✅ all non-system fields must be explicitly provided
+    [K in EXTRA_KEYS]-?: BuilderFor<IN[K]>
+  } &
+    // ✅ if `id` differs, it’s required
+    (ExactMatch<IN['id'], BaseDBEntity['id']> extends true
+      ? { id?: BuilderFor<BaseDBEntity['id']> }
+      : { id: BuilderFor<IN['id']> }) &
+    (ExactMatch<IN['created'], BaseDBEntity['created']> extends true
+      ? { created?: BuilderFor<BaseDBEntity['created']> }
+      : { created: BuilderFor<IN['created']> }) &
+    (ExactMatch<IN['updated'], BaseDBEntity['updated']> extends true
+      ? { updated?: BuilderFor<BaseDBEntity['updated']> }
+      : { updated: BuilderFor<IN['updated']> }),
+): JsonSchemaObjectBuilder<IN, IN, 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, any>,
+  VS extends JsonSchemaAnyBuilder<any, any, any>,
+  Opt extends boolean = SchemaOpt<VS>,
+>(
+  keySchema: KS,
+  valueSchema: VS,
+): JsonSchemaObjectBuilder<
+  Opt extends true
+    ? Partial<Record<SchemaIn<KS>, SchemaIn<VS>>>
+    : Record<SchemaIn<KS>, SchemaIn<VS>>,
+  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, any>).getSchema()
+    .optionalField
+  const valueJsonSchema = valueSchema.build()
+
+  // When value schema is optional, wrap in anyOf to allow undefined values
+  const finalValueSchema: JsonSchema = isValueOptional
+    ? { anyOf: [{ isUndefined: true }, valueJsonSchema] }
+    : valueJsonSchema
+
+  return new JsonSchemaObjectBuilder<
+    Opt extends true
+      ? Partial<Record<SchemaIn<KS>, SchemaIn<VS>>>
+      : Record<SchemaIn<KS>, SchemaIn<VS>>,
+    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, any>,
+  Opt extends boolean = SchemaOpt<S>,
+>(
+  keyRegex: RegExp | string,
+  schema: S,
+): JsonSchemaObjectBuilder<
+  Opt extends true ? StringMap<SchemaIn<S>> : StringMap<SchemaIn<S>>,
+  Opt extends true ? StringMap<SchemaOut<S>> : 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<
+    Opt extends true ? StringMap<SchemaIn<S>> : StringMap<SchemaIn<S>>,
+    Opt extends true ? StringMap<SchemaOut<S>> : 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, any>,
+  K extends string | number = EnumKeyUnion<T>,
+  Opt extends boolean = SchemaOpt<S>,
+>(
+  keys: T,
+  schema: S,
+): JsonSchemaObjectBuilder<
+  Opt extends true ? { [P in K]?: SchemaIn<S> } : { [P in K]: SchemaIn<S> },
+  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]?: SchemaIn<S> } : { [P in K]: SchemaIn<S> },
+    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
+}
+
+type Expand<T> = { [K in keyof T]: T[K] }
+
+type StripIndexSignatureDeep<T> = T extends readonly unknown[]
+  ? T
+  : T extends Record<string, any>
+    ? {
+        [K in keyof T as string extends K
+          ? never
+          : number extends K
+            ? never
+            : symbol extends K
+              ? never
+              : K]: StripIndexSignatureDeep<T[K]>
+      }
+    : T
+
+type RelaxIndexSignature<T> = T extends readonly unknown[]
+  ? T
+  : T extends AnyObject
+    ? { [K in keyof T]: RelaxIndexSignature<T[K]> }
+    : T
+
+type Override<T, U> = Omit<T, keyof U> & U
+
+declare const allowExtraKeysSymbol: unique symbol
+
+type HasAllowExtraKeys<T> = T extends { readonly [allowExtraKeysSymbol]?: true } ? true : false
+
+type IsAny<T> = 0 extends 1 & T ? true : false
+
+type IsAssignableRelaxed<A, B> =
+  IsAny<RelaxIndexSignature<A>> extends true
+    ? true
+    : [RelaxIndexSignature<A>] extends [B]
+      ? true
+      : false
+
+type OptionalDbEntityFields<T> = T extends BaseDBEntity
+  ? Omit<T, keyof BaseDBEntity> & Partial<Pick<T, keyof BaseDBEntity>>
+  : T
+
+type ExactMatchBase<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+    ? (<T>() => T extends B ? 1 : 2) extends <T>() => T extends A ? 1 : 2
+      ? true
+      : false
+    : false
+
+type ExactMatch<A, B> =
+  HasAllowExtraKeys<B> extends true
+    ? IsAssignableRelaxed<B, A>
+    : ExactMatchBase<Expand<A>, Expand<B>> extends true
+      ? true
+      : ExactMatchBase<Expand<StripIndexSignatureDeep<A>>, Expand<StripIndexSignatureDeep<B>>>
+
+type BuilderOutUnion<B extends readonly JsonSchemaAnyBuilder<any, any, any>[]> = {
+  [K in keyof B]: B[K] extends JsonSchemaAnyBuilder<any, infer O, any> ? O : never
+}[number]
+
+type BuilderInUnion<B extends readonly JsonSchemaAnyBuilder<any, any, any>[]> = {
+  [K in keyof B]: B[K] extends JsonSchemaAnyBuilder<infer I, any, any> ? I : never
+}[number]
+
+type AnyOfByIn<D extends Record<PropertyKey, JsonSchemaTerminal<any, any, any>>> = {
+  [K in keyof D]: D[K] extends JsonSchemaTerminal<infer I, any, any> ? I : never
+}[keyof D]
+
+type AnyOfByOut<D extends Record<PropertyKey, JsonSchemaTerminal<any, any, any>>> = {
+  [K in keyof D]: D[K] extends JsonSchemaTerminal<any, infer O, any> ? O : never
+}[keyof D]
+
+type AnyOfByDiscriminant<IN, P extends string> = IN extends { [K in P]: infer V } ? V : never
+
+type AnyOfByInput<IN, P extends string, D = AnyOfByDiscriminant<IN, P>> = IN extends unknown
+  ? Omit<Partial<IN>, P> & { [K in P]?: D }
+  : never
+
+type BuilderFor<T> = JsonSchemaAnyBuilder<any, T, any>
+
+interface JsonBuilderRuleOpt {
+  /**
+   * Text of error message to return when the validation fails for the given rule:
+   *
+   * `{ msg: "is not a valid Oompa-loompa" } => "Object.property is not a valid Oompa-loompa"`
+   */
+  msg?: string
+  /**
+   * A friendly name for what we are validating, that will be used in error messages:
+   *
+   * `{ name: "Oompa-loompa" } => "Object.property is not a valid Oompa-loompa"`
+   */
+  name?: string
+}
+
+type EnumKeyUnion<T> =
+  // array of literals -> union of its elements
+  T extends readonly (infer U)[]
+    ? U
+    : // enum object -> union of its values
+      T extends StringEnum | NumberEnum
+      ? T[keyof T]
+      : never
+
+type SchemaIn<S> = S extends JsonSchemaAnyBuilder<infer IN, any, any> ? IN : never
+type SchemaOut<S> = S extends JsonSchemaAnyBuilder<any, infer OUT, any> ? OUT : never
+type SchemaOpt<S> =
+  S extends JsonSchemaAnyBuilder<any, any, infer Opt> ? (Opt extends true ? true : false) : false
+
+type TupleIn<T extends readonly JsonSchemaAnyBuilder<any, any, any>[]> = {
+  [K in keyof T]: T[K] extends JsonSchemaAnyBuilder<infer I, any, any> ? I : never
+}
+
+type TupleOut<T extends readonly JsonSchemaAnyBuilder<any, any, any>[]> = {
+  [K in keyof T]: T[K] extends JsonSchemaAnyBuilder<any, infer O, any> ? O : never
+}
+
+export type CustomValidatorFn = (v: any) => string | undefined
+export type CustomConverterFn<OUT> = (v: any) => OUT
+
+/**
+ * Deep copy that preserves functions in customValidations/customConversions.
+ * Unlike structuredClone, this handles function references (which only exist in those two properties).
+ */
+function deepCopyPreservingFunctions<T>(obj: T): T {
+  if (obj === null || typeof obj !== 'object') return obj
+  if (Array.isArray(obj)) return obj.map(deepCopyPreservingFunctions) as T
+  const copy = {} as T
+  for (const key of Object.keys(obj)) {
+    const value = (obj as any)[key]
+    // customValidations/customConversions are arrays of functions - shallow copy the array
+    ;(copy as any)[key] =
+      (key === 'customValidations' || key === 'customConversions') && Array.isArray(value)
+        ? [...value]
+        : deepCopyPreservingFunctions(value)
+  }
+  return copy
+}