@naturalcycles/nodejs-lib 15.90.2 → 15.92.0

package/dist/validation/ajv/ajvSchema.js

@@ -1,12 +1,18 @@
-import { _isObject, _lazyValue } from '@naturalcycles/js-lib';
-import { _assert } from '@naturalcycles/js-lib/error';
-import { _deepCopy, _filterNullishValues } from '@naturalcycles/js-lib/object';
+/* eslint-disable id-denylist */
+// oxlint-disable max-lines
+import { _isObject, _isUndefined, _lazyValue, _numberEnumValues, _stringEnumValues, getEnumType, } from '@naturalcycles/js-lib';
+import { _uniq } from '@naturalcycles/js-lib/array';
+import { _assert, _try } from '@naturalcycles/js-lib/error';
+import { _deepCopy, _filterNullishValues, _sortObject } from '@naturalcycles/js-lib/object';
 import { _substringBefore } from '@naturalcycles/js-lib/string';
-import { _typeCast } from '@naturalcycles/js-lib/types';
+import { _objectAssign, _typeCast, JWT_REGEX } from '@naturalcycles/js-lib/types';
 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 { isEveryItemNumber, isEveryItemPrimitive, isEveryItemString, JSON_SCHEMA_ORDER, mergeJsonSchemaObjects, } from './jsonSchemaBuilder.util.js';
+// ==== AJV =====
 /**
  * On creation - compiles ajv validation function.
  * Provides convenient methods, error reporting, etc.
@@ -98,10 +104,26 @@ export class AjvSchema {
         const item = opt.mutateInput !== false || typeof input !== 'object'
             ? input // mutate
             : _deepCopy(input); // not mutate
-        const valid = fn(item); // mutates item, but not input
+        let valid = fn(item); // mutates item, but not input
         _typeCast(item);
+        let output = item;
+        if (valid && this.schema.postValidation) {
+            const [err, result] = _try(() => this.schema.postValidation(output));
+            if (err) {
+                valid = false;
+                fn.errors = [
+                    {
+                        instancePath: '',
+                        message: err.message,
+                    },
+                ];
+            }
+            else {
+                output = result;
+            }
+        }
         if (valid)
-            return [null, item];
+            return [null, output];
         const errors = fn.errors;
         const { inputId = _isObject(input) ? input['id'] : undefined, inputName = this.cfg.inputName || 'Object', } = opt;
         const dataVar = [inputName, inputId].filter(Boolean).join('.');
@@ -120,7 +142,7 @@ export class AjvSchema {
             inputName,
             inputId,
         }));
-        return [err, item];
+        return [err, output];
     }
     getValidationFunction() {
         return (input, opt) => {
@@ -205,3 +227,1152 @@ export class AjvSchema {
 }
 const separator = '\n';
 export const HIDDEN_AJV_SCHEMA = Symbol('HIDDEN_AJV_SCHEMA');
+// ===== JsonSchemaBuilders ===== //
+export const j = {
+    /**
+     * Matches literally any value - equivalent to TypeScript's `any` type.
+     * Use sparingly, as it bypasses type validation entirely.
+     */
+    any() {
+        return new JsonSchemaAnyBuilder({});
+    },
+    string() {
+        return new JsonSchemaStringBuilder();
+    },
+    number() {
+        return new JsonSchemaNumberBuilder();
+    },
+    boolean() {
+        return new JsonSchemaBooleanBuilder();
+    },
+    object: Object.assign(object, {
+        dbEntity: objectDbEntity,
+        infer: objectInfer,
+        any() {
+            return j.object({}).allowAdditionalProperties();
+        },
+        stringMap(schema) {
+            const isValueOptional = schema.getSchema().optionalField;
+            const builtSchema = schema.build();
+            const finalValueSchema = isValueOptional
+                ? { anyOf: [{ isUndefined: true }, builtSchema] }
+                : builtSchema;
+            return new JsonSchemaObjectBuilder({}, {
+                hasIsOfTypeCheck: false,
+                patternProperties: {
+                    '^.+$': 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(itemSchema) {
+        return new JsonSchemaArrayBuilder(itemSchema);
+    },
+    tuple(items) {
+        return new JsonSchemaTupleBuilder(items);
+    },
+    set(itemSchema) {
+        return new JsonSchemaSet2Builder(itemSchema);
+    },
+    buffer() {
+        return new JsonSchemaBufferBuilder();
+    },
+    enum(input, opt) {
+        let enumValues;
+        let baseType = '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);
+                baseType = 'number';
+            }
+            else if (enumType === 'StringEnum') {
+                enumValues = _stringEnumValues(input);
+                baseType = 'string';
+            }
+        }
+        _assert(enumValues, 'Unsupported enum input');
+        return new JsonSchemaEnumBuilder(enumValues, 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(items) {
+        const schemas = items.map(b => b.build());
+        _assert(schemas.every(hasNoObjectSchemas), 'Do not use `oneOf` validation with non-primitive types!');
+        return new JsonSchemaAnyBuilder({
+            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(items) {
+        const schemas = items.map(b => b.build());
+        _assert(schemas.every(hasNoObjectSchemas), 'Do not use `anyOf` validation with non-primitive types!');
+        return new JsonSchemaAnyBuilder({
+            anyOf: schemas,
+        });
+    },
+    /**
+     * Pick validation schema for an object based on the value of a specific property.
+     *
+     * ```
+     * const schemaMap = {
+     *   true: successSchema,
+     *   false: errorSchema
+     * }
+     *
+     * const schema = j.anyOfBy('success', schemaMap)
+     * ```
+     */
+    anyOfBy(propertyName, schemaDictionary) {
+        return new JsonSchemaAnyOfByBuilder(propertyName, schemaDictionary);
+    },
+    /**
+     * Custom version of `anyOf` which - in contrast to the original function - does not mutate the input.
+     * This comes with a performance penalty, so do not use it where performance matters.
+     *
+     * ```
+     * const schema = j.anyOfThese([successSchema, errorSchema])
+     * ```
+     */
+    anyOfThese(items) {
+        return new JsonSchemaAnyBuilder({
+            anyOfThese: items.map(b => b.build()),
+        });
+    },
+    and() {
+        return {
+            silentBob: () => {
+                throw new Error('...strike back!');
+            },
+        };
+    },
+    literal(v) {
+        let baseType = 'other';
+        if (typeof v === 'string')
+            baseType = 'string';
+        if (typeof v === 'number')
+            baseType = 'number';
+        return new JsonSchemaEnumBuilder([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 {
+    [HIDDEN_AJV_SCHEMA];
+    schema;
+    constructor(schema) {
+        this.schema = schema;
+    }
+    get ajvSchema() {
+        if (!this[HIDDEN_AJV_SCHEMA]) {
+            this[HIDDEN_AJV_SCHEMA] = AjvSchema.create(this);
+        }
+        return this[HIDDEN_AJV_SCHEMA];
+    }
+    getSchema() {
+        return this.schema;
+    }
+    /**
+     * Produces a "clean schema object" without methods.
+     * Same as if it would be JSON.stringified.
+     */
+    build() {
+        _assert(!(this.schema.optionalField && this.schema.default !== undefined), '.optional() and .default() should not be used together - the default value makes .optional() redundant and causes incorrect type inference');
+        const jsonSchema = _sortObject(deepCopyPreservingFunctions(this.schema), JSON_SCHEMA_ORDER);
+        delete jsonSchema.optionalField;
+        return jsonSchema;
+    }
+    clone() {
+        const cloned = Object.create(Object.getPrototypeOf(this));
+        cloned.schema = deepCopyPreservingFunctions(this.schema);
+        return cloned;
+    }
+    cloneAndUpdateSchema(schema) {
+        const clone = this.clone();
+        _objectAssign(clone.schema, schema);
+        return clone;
+    }
+    validate(input, opt) {
+        return this.ajvSchema.validate(input, opt);
+    }
+    isValid(input, opt) {
+        return this.ajvSchema.isValid(input, opt);
+    }
+    getValidationResult(input, opt = {}) {
+        return this.ajvSchema.getValidationResult(input, opt);
+    }
+    getValidationFunction() {
+        return this.ajvSchema.getValidationFunction();
+    }
+    /**
+     * Specify a function to be called after the normal validation is finished.
+     *
+     * This function will receive the validated, type-safe data, and you can use it
+     * to do further validations, e.g. conditional validations based on certain property values,
+     * or to do data modifications either by mutating the input or returning a new value.
+     *
+     * If you throw an error from this function, it will show up as an error in the validation.
+     */
+    postValidation(fn) {
+        const clone = this.cloneAndUpdateSchema({
+            postValidation: fn,
+        });
+        return clone;
+    }
+    /**
+     * @experimental
+     */
+    out;
+    opt;
+}
+export class JsonSchemaAnyBuilder extends JsonSchemaTerminal {
+    setErrorMessage(ruleName, errorMessage) {
+        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() {
+        return this.cloneAndUpdateSchema({ hasIsOfTypeCheck: true });
+    }
+    $schema($schema) {
+        return this.cloneAndUpdateSchema({ $schema });
+    }
+    $schemaDraft7() {
+        return this.$schema('http://json-schema.org/draft-07/schema#');
+    }
+    $id($id) {
+        return this.cloneAndUpdateSchema({ $id });
+    }
+    title(title) {
+        return this.cloneAndUpdateSchema({ title });
+    }
+    description(description) {
+        return this.cloneAndUpdateSchema({ description });
+    }
+    deprecated(deprecated = true) {
+        return this.cloneAndUpdateSchema({ deprecated });
+    }
+    type(type) {
+        return this.cloneAndUpdateSchema({ type });
+    }
+    default(v) {
+        return this.cloneAndUpdateSchema({ default: v });
+    }
+    instanceof(of) {
+        return this.cloneAndUpdateSchema({ type: 'object', instanceof: of });
+    }
+    optional() {
+        const clone = this.cloneAndUpdateSchema({ optionalField: true });
+        return clone;
+    }
+    nullable() {
+        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() {
+        return this;
+    }
+    /**
+     * Locks the given schema chain and no other modification can be done to it.
+     */
+    final() {
+        return new JsonSchemaTerminal(this.schema);
+    }
+    /**
+     *
+     * @param validator A validator function that returns an error message or undefined.
+     *
+     * You may add multiple custom validators and they will be executed in the order you added them.
+     */
+    custom(validator) {
+        const { customValidations = [] } = this.schema;
+        return this.cloneAndUpdateSchema({
+            customValidations: [...customValidations, validator],
+        });
+    }
+    /**
+     *
+     * @param converter A converter function that returns a new value.
+     *
+     * You may add multiple converters and they will be executed in the order you added them,
+     * each converter receiving the result from the previous one.
+     *
+     * This feature only works when the current schema is nested in an object or array schema,
+     * due to how mutability works in Ajv.
+     */
+    convert(converter) {
+        const { customConversions = [] } = this.schema;
+        return this.cloneAndUpdateSchema({
+            customConversions: [...customConversions, converter],
+        });
+    }
+}
+export class JsonSchemaStringBuilder extends JsonSchemaAnyBuilder {
+    constructor() {
+        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.
+     */
+    optional(optionalValues) {
+        if (!optionalValues) {
+            return super.optional();
+        }
+        _typeCast(optionalValues);
+        let newBuilder = new JsonSchemaStringBuilder().optional();
+        const alternativesSchema = j.enum(optionalValues);
+        Object.assign(newBuilder.getSchema(), {
+            anyOf: [this.build(), alternativesSchema.build()],
+            optionalValues,
+        });
+        // When `null` is specified, we want `null` to be stripped and the value to become `undefined`,
+        // so we must allow `null` values to be parsed by Ajv,
+        // but the typing should not reflect that.
+        // We also cannot accept more rules attached, since we're not building a StringSchema anymore.
+        if (optionalValues.includes(null)) {
+            newBuilder = new JsonSchemaTerminal({
+                anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
+                optionalField: true,
+            });
+        }
+        return newBuilder;
+    }
+    regex(pattern, opt) {
+        _assert(!pattern.flags, `Regex flags are not supported by JSON Schema. Received: /${pattern.source}/${pattern.flags}`);
+        return this.pattern(pattern.source, opt);
+    }
+    pattern(pattern, opt) {
+        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) {
+        return this.cloneAndUpdateSchema({ minLength });
+    }
+    maxLength(maxLength) {
+        return this.cloneAndUpdateSchema({ maxLength });
+    }
+    length(minLengthOrExactLength, maxLength) {
+        const maxLengthActual = maxLength ?? minLengthOrExactLength;
+        return this.minLength(minLengthOrExactLength).maxLength(maxLengthActual);
+    }
+    email(opt) {
+        const defaultOptions = { checkTLD: true };
+        return this.cloneAndUpdateSchema({ email: { ...defaultOptions, ...opt } })
+            .trim()
+            .toLowerCase();
+    }
+    trim() {
+        return this.cloneAndUpdateSchema({ transform: { ...this.schema.transform, trim: true } });
+    }
+    toLowerCase() {
+        return this.cloneAndUpdateSchema({
+            transform: { ...this.schema.transform, toLowerCase: true },
+        });
+    }
+    toUpperCase() {
+        return this.cloneAndUpdateSchema({
+            transform: { ...this.schema.transform, toUpperCase: true },
+        });
+    }
+    truncate(toLength) {
+        return this.cloneAndUpdateSchema({
+            transform: { ...this.schema.transform, truncate: toLength },
+        });
+    }
+    branded() {
+        return this;
+    }
+    /**
+     * 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() {
+        return new JsonSchemaIsoDateBuilder();
+    }
+    isoDateTime() {
+        return this.cloneAndUpdateSchema({ IsoDateTime: true }).branded();
+    }
+    isoMonth() {
+        return new JsonSchemaIsoMonthBuilder();
+    }
+    /**
+     * Validates the string format to be JWT.
+     * Expects the JWT to be signed!
+     */
+    jwt() {
+        return this.regex(JWT_REGEX, { msg: 'is not a valid JWT format' });
+    }
+    url() {
+        return this.regex(URL_REGEX, { msg: 'is not a valid URL format' });
+    }
+    ipv4() {
+        return this.regex(IPV4_REGEX, { msg: 'is not a valid IPv4 format' });
+    }
+    ipv6() {
+        return this.regex(IPV6_REGEX, { msg: 'is not a valid IPv6 format' });
+    }
+    slug() {
+        return this.regex(SLUG_REGEX, { msg: 'is not a valid slug format' });
+    }
+    semVer() {
+        return this.regex(SEMVER_REGEX, { msg: 'is not a valid semver format' });
+    }
+    languageTag() {
+        return this.regex(LANGUAGE_TAG_REGEX, { msg: 'is not a valid language format' });
+    }
+    countryCode() {
+        return this.regex(COUNTRY_CODE_REGEX, { msg: 'is not a valid country code format' });
+    }
+    currency() {
+        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() {
+        // 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();
+    }
+    base64Url() {
+        return this.regex(BASE64URL_REGEX, {
+            msg: 'contains characters not allowed in Base64 URL characterset',
+        });
+    }
+    uuid() {
+        return this.regex(UUID_REGEX, { msg: 'is an invalid UUID' });
+    }
+}
+export class JsonSchemaIsoDateBuilder extends JsonSchemaAnyBuilder {
+    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.
+     */
+    optional(nullValue) {
+        if (nullValue === undefined) {
+            return super.optional();
+        }
+        // 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,
+        });
+    }
+    before(date) {
+        return this.cloneAndUpdateSchema({ IsoDate: { before: date } });
+    }
+    sameOrBefore(date) {
+        return this.cloneAndUpdateSchema({ IsoDate: { sameOrBefore: date } });
+    }
+    after(date) {
+        return this.cloneAndUpdateSchema({ IsoDate: { after: date } });
+    }
+    sameOrAfter(date) {
+        return this.cloneAndUpdateSchema({ IsoDate: { sameOrAfter: date } });
+    }
+    between(fromDate, toDate, incl) {
+        let schemaPatch = {};
+        if (incl === '[)') {
+            schemaPatch = { IsoDate: { sameOrAfter: fromDate, before: toDate } };
+        }
+        else if (incl === '[]') {
+            schemaPatch = { IsoDate: { sameOrAfter: fromDate, sameOrBefore: toDate } };
+        }
+        return this.cloneAndUpdateSchema(schemaPatch);
+    }
+}
+export class JsonSchemaIsoMonthBuilder extends JsonSchemaAnyBuilder {
+    constructor() {
+        super({
+            type: 'string',
+            IsoMonth: {},
+        });
+    }
+}
+export class JsonSchemaNumberBuilder extends JsonSchemaAnyBuilder {
+    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.
+     */
+    optional(optionalValues) {
+        if (!optionalValues) {
+            return super.optional();
+        }
+        _typeCast(optionalValues);
+        let newBuilder = new JsonSchemaNumberBuilder().optional();
+        const alternativesSchema = j.enum(optionalValues);
+        Object.assign(newBuilder.getSchema(), {
+            anyOf: [this.build(), alternativesSchema.build()],
+            optionalValues,
+        });
+        // When `null` is specified, we want `null` to be stripped and the value to become `undefined`,
+        // so we must allow `null` values to be parsed by Ajv,
+        // but the typing should not reflect that.
+        // We also cannot accept more rules attached, since we're not building a NumberSchema anymore.
+        if (optionalValues.includes(null)) {
+            newBuilder = new JsonSchemaTerminal({
+                anyOf: [{ type: 'null', optionalValues }, newBuilder.build()],
+                optionalField: true,
+            });
+        }
+        return newBuilder;
+    }
+    integer() {
+        return this.cloneAndUpdateSchema({ type: 'integer' });
+    }
+    branded() {
+        return this;
+    }
+    multipleOf(multipleOf) {
+        return this.cloneAndUpdateSchema({ multipleOf });
+    }
+    min(minimum) {
+        return this.cloneAndUpdateSchema({ minimum });
+    }
+    exclusiveMin(exclusiveMinimum) {
+        return this.cloneAndUpdateSchema({ exclusiveMinimum });
+    }
+    max(maximum) {
+        return this.cloneAndUpdateSchema({ maximum });
+    }
+    exclusiveMax(exclusiveMaximum) {
+        return this.cloneAndUpdateSchema({ exclusiveMaximum });
+    }
+    lessThan(value) {
+        return this.exclusiveMax(value);
+    }
+    lessThanOrEqual(value) {
+        return this.max(value);
+    }
+    moreThan(value) {
+        return this.exclusiveMin(value);
+    }
+    moreThanOrEqual(value) {
+        return this.min(value);
+    }
+    equal(value) {
+        return this.min(value).max(value);
+    }
+    range(minimum, maximum, incl) {
+        if (incl === '[)') {
+            return this.moreThanOrEqual(minimum).lessThan(maximum);
+        }
+        return this.moreThanOrEqual(minimum).lessThanOrEqual(maximum);
+    }
+    int32() {
+        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() {
+        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() {
+        return this;
+    }
+    double() {
+        return this;
+    }
+    unixTimestamp() {
+        return this.integer().min(0).max(TS_2500).branded();
+    }
+    unixTimestamp2000() {
+        return this.integer().min(TS_2000).max(TS_2500).branded();
+    }
+    unixTimestampMillis() {
+        return this.integer().min(0).max(TS_2500_MILLIS).branded();
+    }
+    unixTimestamp2000Millis() {
+        return this.integer().min(TS_2000_MILLIS).max(TS_2500_MILLIS).branded();
+    }
+    utcOffset() {
+        return this.integer()
+            .multipleOf(15)
+            .min(-12 * 60)
+            .max(14 * 60);
+    }
+    utcOffsetHour() {
+        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) {
+        return this.cloneAndUpdateSchema({ precision: numberOfDigits });
+    }
+}
+export class JsonSchemaBooleanBuilder extends JsonSchemaAnyBuilder {
+    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.
+     */
+    optional(optionalValue) {
+        if (typeof optionalValue === 'undefined') {
+            return super.optional();
+        }
+        const newBuilder = new JsonSchemaBooleanBuilder().optional();
+        const alternativesSchema = j.enum([optionalValue]);
+        Object.assign(newBuilder.getSchema(), {
+            anyOf: [this.build(), alternativesSchema.build()],
+            optionalValues: [optionalValue],
+        });
+        return newBuilder;
+    }
+}
+export class JsonSchemaObjectBuilder extends JsonSchemaAnyBuilder {
+    constructor(props, opt) {
+        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) {
+        const properties = {};
+        const required = [];
+        for (const [key, builder] of Object.entries(props)) {
+            const isOptional = builder.getSchema().optionalField;
+            if (!isOptional) {
+                required.push(key);
+            }
+            const schema = builder.build();
+            properties[key] = schema;
+        }
+        this.schema.properties = properties;
+        this.schema.required = _uniq(required).sort();
+        return this;
+    }
+    /**
+     * @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.
+     */
+    optional(nullValue) {
+        if (nullValue === undefined) {
+            return super.optional();
+        }
+        // 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,
+        });
+    }
+    /**
+     * When set, the validation will not strip away properties that are not specified explicitly in the schema.
+     */
+    allowAdditionalProperties() {
+        return this.cloneAndUpdateSchema({ additionalProperties: true });
+    }
+    extend(props) {
+        const newBuilder = new JsonSchemaObjectBuilder();
+        _objectAssign(newBuilder.schema, deepCopyPreservingFunctions(this.schema));
+        const incomingSchemaBuilder = new JsonSchemaObjectBuilder(props);
+        mergeJsonSchemaObjects(newBuilder.schema, incomingSchemaBuilder.schema);
+        _objectAssign(newBuilder.schema, { hasIsOfTypeCheck: false });
+        return newBuilder;
+    }
+    /**
+     * 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(other) {
+        const clone = this.clone();
+        mergeJsonSchemaObjects(clone.schema, other.schema);
+        _objectAssign(clone.schema, { hasIsOfTypeCheck: false });
+        return clone;
+    }
+    /**
+     * 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) {
+        return this.cloneAndUpdateSchema({ minProperties, minProperties2: minProperties });
+    }
+    maxProperties(maxProperties) {
+        return this.cloneAndUpdateSchema({ maxProperties });
+    }
+    exclusiveProperties(propNames) {
+        const exclusiveProperties = this.schema.exclusiveProperties ?? [];
+        return this.cloneAndUpdateSchema({ exclusiveProperties: [...exclusiveProperties, propNames] });
+    }
+}
+export class JsonSchemaObjectInferringBuilder extends JsonSchemaAnyBuilder {
+    constructor(props) {
+        super({
+            type: 'object',
+            properties: {},
+            required: [],
+            additionalProperties: false,
+        });
+        if (props)
+            this.addProperties(props);
+    }
+    addProperties(props) {
+        const properties = {};
+        const required = [];
+        for (const [key, builder] of Object.entries(props)) {
+            const isOptional = builder.getSchema().optionalField;
+            if (!isOptional) {
+                required.push(key);
+            }
+            const schema = builder.build();
+            properties[key] = schema;
+        }
+        this.schema.properties = properties;
+        this.schema.required = _uniq(required).sort();
+        return this;
+    }
+    /**
+     * @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
+    optional(nullValue) {
+        if (nullValue === undefined) {
+            return super.optional();
+        }
+        // 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,
+        });
+    }
+    /**
+     * When set, the validation will not strip away properties that are not specified explicitly in the schema.
+     */
+    allowAdditionalProperties() {
+        return this.cloneAndUpdateSchema({ additionalProperties: true });
+    }
+    extend(props) {
+        const newBuilder = new JsonSchemaObjectInferringBuilder();
+        _objectAssign(newBuilder.schema, deepCopyPreservingFunctions(this.schema));
+        const incomingSchemaBuilder = new JsonSchemaObjectInferringBuilder(props);
+        mergeJsonSchemaObjects(newBuilder.schema, incomingSchemaBuilder.schema);
+        // This extend function is not type-safe as it is inferring,
+        // so even if the base schema was already type-checked,
+        // the new schema loses that quality.
+        _objectAssign(newBuilder.schema, { hasIsOfTypeCheck: false });
+        return newBuilder;
+    }
+    /**
+     * 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 extends JsonSchemaAnyBuilder {
+    constructor(itemsSchema) {
+        super({
+            type: 'array',
+            items: itemsSchema.build(),
+        });
+    }
+    minLength(minItems) {
+        return this.cloneAndUpdateSchema({ minItems });
+    }
+    maxLength(maxItems) {
+        return this.cloneAndUpdateSchema({ maxItems });
+    }
+    length(minItemsOrExact, maxItems) {
+        const maxItemsActual = maxItems ?? minItemsOrExact;
+        return this.minLength(minItemsOrExact).maxLength(maxItemsActual);
+    }
+    exactLength(length) {
+        return this.minLength(length).maxLength(length);
+    }
+    unique() {
+        return this.cloneAndUpdateSchema({ uniqueItems: true });
+    }
+}
+export class JsonSchemaSet2Builder extends JsonSchemaAnyBuilder {
+    constructor(itemsSchema) {
+        super({
+            type: ['array', 'object'],
+            Set2: itemsSchema.build(),
+        });
+    }
+    min(minItems) {
+        return this.cloneAndUpdateSchema({ minItems });
+    }
+    max(maxItems) {
+        return this.cloneAndUpdateSchema({ maxItems });
+    }
+}
+export class JsonSchemaBufferBuilder extends JsonSchemaAnyBuilder {
+    constructor() {
+        super({
+            Buffer: true,
+        });
+    }
+}
+export class JsonSchemaEnumBuilder extends JsonSchemaAnyBuilder {
+    constructor(enumValues, baseType, opt) {
+        const 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() {
+        return this;
+    }
+}
+export class JsonSchemaTupleBuilder extends JsonSchemaAnyBuilder {
+    constructor(items) {
+        super({
+            type: 'array',
+            prefixItems: items.map(i => i.build()),
+            minItems: items.length,
+            maxItems: items.length,
+        });
+    }
+}
+export class JsonSchemaAnyOfByBuilder extends JsonSchemaAnyBuilder {
+    constructor(propertyName, schemaDictionary) {
+        const builtSchemaDictionary = {};
+        for (const [key, schema] of Object.entries(schemaDictionary)) {
+            builtSchemaDictionary[key] = schema.build();
+        }
+        super({
+            type: 'object',
+            hasIsOfTypeCheck: true,
+            anyOfBy: {
+                propertyName,
+                schemaDictionary: builtSchemaDictionary,
+            },
+        });
+    }
+}
+export class JsonSchemaAnyOfTheseBuilder extends JsonSchemaAnyBuilder {
+    constructor(propertyName, schemaDictionary) {
+        const builtSchemaDictionary = {};
+        for (const [key, schema] of Object.entries(schemaDictionary)) {
+            builtSchemaDictionary[key] = schema.build();
+        }
+        super({
+            type: 'object',
+            hasIsOfTypeCheck: true,
+            anyOfBy: {
+                propertyName,
+                schemaDictionary: builtSchemaDictionary,
+            },
+        });
+    }
+}
+function object(props) {
+    return new JsonSchemaObjectBuilder(props);
+}
+function objectInfer(props) {
+    return new JsonSchemaObjectInferringBuilder(props);
+}
+function objectDbEntity(props) {
+    return j.object({
+        id: j.string(),
+        created: j.number().unixTimestamp2000(),
+        updated: j.number().unixTimestamp2000(),
+        ...props,
+    });
+}
+function record(keySchema, valueSchema) {
+    const keyJsonSchema = keySchema.build();
+    // Check if value schema is optional before build() strips the optionalField flag
+    const isValueOptional = valueSchema.getSchema().optionalField;
+    const valueJsonSchema = valueSchema.build();
+    // When value schema is optional, wrap in anyOf to allow undefined values
+    const finalValueSchema = isValueOptional
+        ? { anyOf: [{ isUndefined: true }, valueJsonSchema] }
+        : valueJsonSchema;
+    return new JsonSchemaObjectBuilder([], {
+        hasIsOfTypeCheck: false,
+        keySchema: keyJsonSchema,
+        patternProperties: {
+            ['^.*$']: finalValueSchema,
+        },
+    });
+}
+function withRegexKeys(keyRegex, schema) {
+    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([], {
+        hasIsOfTypeCheck: false,
+        patternProperties: {
+            [pattern]: jsonSchema,
+        },
+    });
+}
+/**
+ * Builds the object schema with the indicated `keys` and uses the `schema` for their validation.
+ */
+function withEnumKeys(keys, schema) {
+    let enumValues;
+    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);
+        }
+        else if (enumType === 'StringEnum') {
+            enumValues = _stringEnumValues(keys);
+        }
+    }
+    _assert(enumValues, 'The key list should be an array of values, NumberEnum or a StringEnum');
+    const typedValues = enumValues;
+    const props = Object.fromEntries(typedValues.map(key => [key, schema]));
+    return new JsonSchemaObjectBuilder(props, { hasIsOfTypeCheck: false });
+}
+function hasNoObjectSchemas(schema) {
+    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;
+}
+/**
+ * Deep copy that preserves functions in customValidations/customConversions.
+ * Unlike structuredClone, this handles function references (which only exist in those two properties).
+ */
+function deepCopyPreservingFunctions(obj) {
+    if (obj === null || typeof obj !== 'object')
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(deepCopyPreservingFunctions);
+    const copy = {};
+    for (const key of Object.keys(obj)) {
+        const value = obj[key];
+        copy[key] =
+            (key === 'customValidations' || key === 'customConversions') && Array.isArray(value)
+                ? [...value]
+                : deepCopyPreservingFunctions(value);
+    }
+    return copy;
+}