z-schema 12.0.4 → 12.1.0

package/dist/z-schema-base.mjs

@@ -0,0 +1,230 @@
+import { getRemotePath } from "./utils/uri.mjs";
+import { isObject, whatIs } from "./utils/what-is.mjs";
+import { isInternalKey } from "./json-schema.mjs";
+import { getValidateError } from "./errors.mjs";
+import { copyProp } from "./utils/properties.mjs";
+import { deepClone } from "./utils/clone.mjs";
+import { get, sortedKeys } from "./utils/json.mjs";
+import { Report } from "./report.mjs";
+import { VERSION_SCHEMA_URL_MAPPING } from "./json-schema-versions.mjs";
+import { defaultOptions, normalizeOptions } from "./z-schema-options.mjs";
+import { SchemaCache, prepareRemoteSchema } from "./schema-cache.mjs";
+import { getSupportedFormats } from "./format-validators.mjs";
+import { validate } from "./json-validation.mjs";
+import { SchemaCompiler } from "./schema-compiler.mjs";
+import { SchemaValidator } from "./schema-validator.mjs";
+//#region src/z-schema-base.ts
+/**
+* Module-private symbol used by `ZSchema.create()` to authorise construction.
+* Not exported — external code cannot instantiate ZSchema variants directly.
+*/
+const FACTORY_TOKEN = Symbol("ZSchema.factory");
+var ZSchemaBase = class {
+	scache;
+	sc;
+	sv;
+	validateOptions = {};
+	options;
+	constructor(options, token) {
+		if (token !== FACTORY_TOKEN) throw new Error("do not use new ZSchema(), use ZSchema.create() instead");
+		this.scache = new SchemaCache(this);
+		this.sc = new SchemaCompiler(this);
+		this.sv = new SchemaValidator(this);
+		this.options = normalizeOptions(options);
+	}
+	/**
+	* Internal recursive JSON validation — delegates to the `validate` function
+	* in `json-validation.ts`. Exposed as a method so that per-keyword validator
+	* modules (array, combinators, object) can call back into the core validator
+	* via `this` without importing `json-validation.ts` directly (which would
+	* create a circular dependency).
+	*/
+	_jsonValidate(report, schema, json) {
+		return validate.call(this, report, schema, json);
+	}
+	getDefaultSchemaId() {
+		return this.options.version && this.options.version !== "none" ? VERSION_SCHEMA_URL_MAPPING[this.options.version] : VERSION_SCHEMA_URL_MAPPING[defaultOptions.version];
+	}
+	_validate(json, schema, options, callback) {
+		if (typeof options === "function") {
+			callback = options;
+			options = {};
+		}
+		if (!options) options = {};
+		this.validateOptions = options;
+		if (typeof schema !== "string" && typeof schema !== "boolean" && !isObject(schema)) {
+			const e = /* @__PURE__ */ new Error("Invalid .validate call - schema must be a string or object but " + whatIs(schema) + " was passed!");
+			if (callback) {
+				setTimeout(function() {
+					callback(e, false);
+				}, 0);
+				return;
+			}
+			throw e;
+		}
+		let foundError = false;
+		const report = new Report(this.options, options);
+		report.json = json;
+		let _schema;
+		if (typeof schema === "string") {
+			const schemaName = schema;
+			_schema = this.scache.getSchema(report, schemaName);
+			if (!_schema) {
+				const e = /* @__PURE__ */ new Error("Schema with id '" + schemaName + "' wasn't found in the validator cache!");
+				if (callback) {
+					setTimeout(function() {
+						callback(e, false);
+					}, 0);
+					return;
+				}
+				throw e;
+			}
+		} else _schema = this.scache.getSchema(report, schema);
+		let compiled = false;
+		if (!foundError) compiled = this.sc.compileSchema(report, _schema);
+		if (!compiled) foundError = true;
+		let validated = false;
+		if (!foundError) validated = this.sv.validateSchema(report, _schema);
+		if (!validated) foundError = true;
+		if (options.schemaPath) {
+			report.rootSchema = _schema;
+			_schema = get(_schema, options.schemaPath);
+			if (!_schema) {
+				const e = /* @__PURE__ */ new Error("Schema path '" + options.schemaPath + "' wasn't found in the schema!");
+				if (callback) {
+					setTimeout(function() {
+						callback(e, false);
+					}, 0);
+					return;
+				}
+				throw e;
+			}
+		}
+		if (!foundError) validate.call(this, report, _schema, json);
+		if (callback) {
+			report.processAsyncTasks(this.options.asyncTimeout, callback);
+			return;
+		} else if (report.asyncTasks.length > 0) throw new Error("This validation has async tasks and cannot be done in sync mode, please provide callback argument.");
+		if (!report.isValid()) throw getValidateError({
+			message: report.commonErrorMessage,
+			details: report.errors
+		});
+		return true;
+	}
+	_validateSchema(schemaOrArr) {
+		if (Array.isArray(schemaOrArr) && schemaOrArr.length === 0) throw new Error(".compileSchema was called with an empty array");
+		const report = new Report(this.options);
+		if (Array.isArray(schemaOrArr)) {
+			const arr = this.scache.getSchema(report, schemaOrArr);
+			if (this.sc.compileSchema(report, arr)) this.sv.validateSchema(report, arr);
+		} else {
+			const schema = this.scache.getSchema(report, schemaOrArr);
+			if (this.sc.compileSchema(report, schema)) this.sv.validateSchema(report, schema);
+		}
+		if (!report.isValid()) throw getValidateError({
+			message: report.commonErrorMessage,
+			details: report.errors
+		});
+		return true;
+	}
+	/**
+	* Register a format validator on this instance only (does not affect other instances or the global registry).
+	* @param name - The format name.
+	* @param validatorFunction - A sync or async function `(value: unknown) => boolean | Promise<boolean>`.
+	*/
+	registerFormat(name, validatorFunction) {
+		if (!this.options.customFormats) this.options.customFormats = {};
+		this.options.customFormats[name] = validatorFunction;
+	}
+	/**
+	* Unregister an instance-scoped format validator.
+	* @param name - The format name to unregister.
+	*/
+	unregisterFormat(name) {
+		if (!this.options.customFormats) this.options.customFormats = {};
+		this.options.customFormats[name] = null;
+	}
+	/** Returns the names of format validators registered on this instance. */
+	getRegisteredFormats() {
+		return sortedKeys(this.options.customFormats || {}).filter((key) => this.options.customFormats?.[key] != null);
+	}
+	/** Returns all supported format names (global + instance-registered). */
+	getSupportedFormats() {
+		return getSupportedFormats(this.options.customFormats);
+	}
+	/**
+	* Register a remote schema in this instance's cache so `$ref` can resolve to it.
+	* @param uri - The URI the schema will be known by.
+	* @param schema - The schema object or JSON string.
+	* @param validationOptions - Optional options used for schema preparation.
+	*/
+	setRemoteReference(uri, schema, validationOptions) {
+		const _schema = prepareRemoteSchema(schema, uri, validationOptions, this.options.maxRecursionDepth);
+		this.scache.cacheSchemaByUri(uri, _schema);
+	}
+	/**
+	* Extract unresolvable `$ref` URIs from a validation error.
+	* @param err - A `ValidateError` from a failed validation.
+	* @returns An array of unresolvable reference URIs.
+	*/
+	getMissingReferences(err) {
+		if (!err) return [];
+		const details = err.details || [];
+		const missingRefs = [];
+		function collect(details) {
+			for (const detail of details) {
+				if (detail.code === "UNRESOLVABLE_REFERENCE" || detail.code === "SCHEMA_NOT_REACHABLE") missingRefs.push(detail.params[0]);
+				if (detail.inner) collect(detail.inner);
+			}
+		}
+		collect(details);
+		return missingRefs;
+	}
+	/**
+	* Extract unresolvable **remote** `$ref` URIs from a validation error (local fragment-only refs are excluded).
+	* @param err - A `ValidateError` from a failed validation.
+	* @returns An array of remote reference base URIs.
+	*/
+	getMissingRemoteReferences(err) {
+		const missingReferences = this.getMissingReferences(err);
+		const missingRemoteReferences = [];
+		for (const ref of missingReferences) {
+			const remoteReference = getRemotePath(ref);
+			if (remoteReference && !missingRemoteReferences.includes(remoteReference)) missingRemoteReferences.push(remoteReference);
+		}
+		return missingRemoteReferences;
+	}
+	/**
+	* Resolve a previously compiled schema by its `$id` / `id`, cleaning up internal bookkeeping properties
+	* and inlining resolved `$ref` targets.
+	* @param schemaId - The schema identifier to look up.
+	* @returns A clean, resolved copy of the schema, or `undefined` if not found.
+	*/
+	getResolvedSchema(schemaId) {
+		const report = new Report(this.options);
+		const schema = this.scache.getSchemaByUri(report, schemaId);
+		if (!schema) return void 0;
+		const clonedSchema = deepClone(schema, this.options.maxRecursionDepth);
+		const visited = /* @__PURE__ */ new WeakSet();
+		const cleanup = function(schema) {
+			let key;
+			const typeOf = whatIs(schema);
+			if (typeOf !== "object" && typeOf !== "array") return;
+			if (visited.has(schema)) return;
+			visited.add(schema);
+			if (schema.$ref && schema.__$refResolved) {
+				const from = schema.__$refResolved;
+				const to = schema;
+				delete schema.$ref;
+				delete schema.__$refResolved;
+				for (key in from) copyProp(from, to, key);
+			}
+			for (key in schema) if (Object.hasOwn(schema, key)) if (isInternalKey(key)) delete schema[key];
+			else cleanup(schema[key]);
+		};
+		cleanup(clonedSchema);
+		return clonedSchema;
+	}
+};
+//#endregion
+export { FACTORY_TOKEN, ZSchemaBase };

package/dist/z-schema-options.d.mts

@@ -0,0 +1,35 @@
+import { FormatValidatorFn } from "./format-validators.mjs";
+import { Report } from "./report.mjs";
+import { JsonSchemaVersion } from "./json-schema-versions.mjs";
+
+//#region src/z-schema-options.d.ts
+interface ZSchemaOptions {
+  version?: JsonSchemaVersion | 'none';
+  asyncTimeout?: number;
+  forceAdditional?: boolean;
+  assumeAdditional?: boolean | string[];
+  enumCaseInsensitiveComparison?: boolean;
+  forceItems?: boolean;
+  forceMinItems?: boolean;
+  forceMaxItems?: boolean;
+  forceMinLength?: boolean;
+  forceMaxLength?: boolean;
+  forceProperties?: boolean;
+  ignoreUnresolvableReferences?: boolean;
+  noExtraKeywords?: boolean;
+  noTypeless?: boolean;
+  noEmptyStrings?: boolean;
+  noEmptyArrays?: boolean;
+  strictUris?: boolean;
+  strictMode?: boolean;
+  reportPathAsArray?: boolean;
+  breakOnFirstError?: boolean;
+  pedanticCheck?: boolean;
+  ignoreUnknownFormats?: boolean;
+  formatAssertions?: boolean | null;
+  customValidator?: (report: Report, schema: unknown, json: unknown) => void;
+  customFormats?: Record<string, FormatValidatorFn | null>;
+  maxRecursionDepth?: number;
+}
+//#endregion
+export { ZSchemaOptions };

package/dist/z-schema-options.mjs

@@ -0,0 +1,55 @@
+import { MAX_ASYNC_TIMEOUT } from "./utils/constants.mjs";
+import { shallowClone } from "./utils/clone.mjs";
+import { CURRENT_DEFAULT_SCHEMA_VERSION } from "./json-schema-versions.mjs";
+//#region src/z-schema-options.ts
+const defaultOptions = {
+	version: CURRENT_DEFAULT_SCHEMA_VERSION,
+	asyncTimeout: 2e3,
+	forceAdditional: false,
+	assumeAdditional: false,
+	enumCaseInsensitiveComparison: false,
+	forceItems: false,
+	forceMinItems: false,
+	forceMaxItems: false,
+	forceMinLength: false,
+	forceMaxLength: false,
+	forceProperties: false,
+	ignoreUnresolvableReferences: false,
+	noExtraKeywords: false,
+	noTypeless: false,
+	noEmptyStrings: false,
+	noEmptyArrays: false,
+	strictUris: false,
+	strictMode: false,
+	reportPathAsArray: false,
+	breakOnFirstError: false,
+	pedanticCheck: false,
+	ignoreUnknownFormats: false,
+	formatAssertions: null,
+	customValidator: null,
+	maxRecursionDepth: 100
+};
+const normalizeOptions = (options) => {
+	let normalized;
+	if (typeof options === "object") {
+		let keys = Object.keys(options);
+		for (const key of keys) if (defaultOptions[key] === void 0) throw new Error("Unexpected option passed to constructor: " + key);
+		keys = Object.keys(defaultOptions);
+		for (const key of keys) if (options[key] === void 0) options[key] = shallowClone(defaultOptions[key]);
+		normalized = options;
+	} else normalized = shallowClone(defaultOptions);
+	if (normalized.asyncTimeout != null) normalized.asyncTimeout = Math.min(Math.max(normalized.asyncTimeout, 0), MAX_ASYNC_TIMEOUT);
+	if (normalized.strictMode === true) {
+		normalized.forceAdditional = true;
+		normalized.forceItems = true;
+		normalized.forceMaxLength = true;
+		normalized.forceProperties = true;
+		normalized.noExtraKeywords = true;
+		normalized.noTypeless = true;
+		normalized.noEmptyStrings = true;
+		normalized.noEmptyArrays = true;
+	}
+	return normalized;
+};
+//#endregion
+export { defaultOptions, normalizeOptions };

package/dist/z-schema-reader.d.mts

@@ -0,0 +1,6 @@
+import { JsonSchema } from "./json-schema-versions.mjs";
+
+//#region src/z-schema-reader.d.ts
+type SchemaReader = (uri: string) => JsonSchema;
+//#endregion
+export { SchemaReader };

package/dist/z-schema-reader.mjs

@@ -0,0 +1,10 @@
+//#region src/z-schema-reader.ts
+let _schemaReader;
+function getSchemaReader() {
+	return _schemaReader;
+}
+function setSchemaReader(schemaReader) {
+	_schemaReader = schemaReader;
+}
+//#endregion
+export { getSchemaReader, setSchemaReader };

package/dist/z-schema-versions.mjs

@@ -0,0 +1,67 @@
+import { normalizeOptions } from "./z-schema-options.mjs";
+import { SchemaCache } from "./schema-cache.mjs";
+import draft_04_schema_default from "./schemas/draft-04-schema.mjs";
+import draft_06_schema_default from "./schemas/draft-06-schema.mjs";
+import draft_07_schema_default from "./schemas/draft-07-schema.mjs";
+import draft_2019_09_meta_applicator_default from "./schemas/draft-2019-09-meta-applicator.mjs";
+import draft_2019_09_meta_content_default from "./schemas/draft-2019-09-meta-content.mjs";
+import draft_2019_09_meta_core_default from "./schemas/draft-2019-09-meta-core.mjs";
+import draft_2019_09_meta_format_default from "./schemas/draft-2019-09-meta-format.mjs";
+import draft_2019_09_meta_meta_data_default from "./schemas/draft-2019-09-meta-meta-data.mjs";
+import draft_2019_09_meta_validation_default from "./schemas/draft-2019-09-meta-validation.mjs";
+import draft_2019_09_schema_default from "./schemas/draft-2019-09-schema.mjs";
+import draft_2020_12_meta_applicator_default from "./schemas/draft-2020-12-meta-applicator.mjs";
+import draft_2020_12_meta_content_default from "./schemas/draft-2020-12-meta-content.mjs";
+import draft_2020_12_meta_core_default from "./schemas/draft-2020-12-meta-core.mjs";
+import draft_2020_12_meta_format_annotation_default from "./schemas/draft-2020-12-meta-format-annotation.mjs";
+import draft_2020_12_meta_format_assertion_default from "./schemas/draft-2020-12-meta-format-assertion.mjs";
+import draft_2020_12_meta_meta_data_default from "./schemas/draft-2020-12-meta-meta-data.mjs";
+import draft_2020_12_meta_unevaluated_default from "./schemas/draft-2020-12-meta-unevaluated.mjs";
+import draft_2020_12_meta_validation_default from "./schemas/draft-2020-12-meta-validation.mjs";
+import draft_2020_12_schema_default from "./schemas/draft-2020-12-schema.mjs";
+//#region src/z-schema-versions.ts
+const Draft4Schema = draft_04_schema_default;
+const Draft6Schema = draft_06_schema_default;
+const Draft7Schema = draft_07_schema_default;
+const Draft201909Schema = draft_2019_09_schema_default;
+const Draft201909MetaApplicator = draft_2019_09_meta_applicator_default;
+const Draft201909MetaContent = draft_2019_09_meta_content_default;
+const Draft201909MetaCore = draft_2019_09_meta_core_default;
+const Draft201909MetaFormat = draft_2019_09_meta_format_default;
+const Draft201909MetaMetaData = draft_2019_09_meta_meta_data_default;
+const Draft201909MetaValidation = draft_2019_09_meta_validation_default;
+const Draft202012Schema = draft_2020_12_schema_default;
+const Draft202012MetaApplicator = draft_2020_12_meta_applicator_default;
+const Draft202012MetaContent = draft_2020_12_meta_content_default;
+const Draft202012MetaCore = draft_2020_12_meta_core_default;
+const Draft202012MetaFormatAnnotation = draft_2020_12_meta_format_annotation_default;
+const Draft202012MetaFormatAssertion = draft_2020_12_meta_format_assertion_default;
+const Draft202012MetaMetaData = draft_2020_12_meta_meta_data_default;
+const Draft202012MetaUnevaluated = draft_2020_12_meta_unevaluated_default;
+const Draft202012MetaValidation = draft_2020_12_meta_validation_default;
+const registerRemoteReference = (uri, schema, validationOptions) => {
+	const preparedSchema = schema;
+	if (!preparedSchema.id) preparedSchema.id = uri;
+	if (validationOptions) preparedSchema.__$validationOptions = normalizeOptions(validationOptions);
+	SchemaCache.cacheSchemaByUri(uri, preparedSchema);
+};
+registerRemoteReference("http://json-schema.org/draft-04/schema", Draft4Schema, { version: "none" });
+registerRemoteReference("http://json-schema.org/draft-06/schema", Draft6Schema, { version: "none" });
+registerRemoteReference("http://json-schema.org/draft-07/schema", Draft7Schema, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2019-09/schema", Draft201909Schema, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2019-09/meta/applicator", Draft201909MetaApplicator, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2019-09/meta/content", Draft201909MetaContent, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2019-09/meta/core", Draft201909MetaCore, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2019-09/meta/format", Draft201909MetaFormat, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2019-09/meta/meta-data", Draft201909MetaMetaData, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2019-09/meta/validation", Draft201909MetaValidation, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2020-12/schema", Draft202012Schema, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2020-12/meta/applicator", Draft202012MetaApplicator, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2020-12/meta/content", Draft202012MetaContent, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2020-12/meta/core", Draft202012MetaCore, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2020-12/meta/format-annotation", Draft202012MetaFormatAnnotation, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2020-12/meta/format-assertion", Draft202012MetaFormatAssertion, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2020-12/meta/meta-data", Draft202012MetaMetaData, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2020-12/meta/unevaluated", Draft202012MetaUnevaluated, { version: "none" });
+registerRemoteReference("https://json-schema.org/draft/2020-12/meta/validation", Draft202012MetaValidation, { version: "none" });
+//#endregion

package/dist/z-schema.d.mts

@@ -0,0 +1,193 @@
+import { FormatValidatorFn } from "./format-validators.mjs";
+import { ZSchemaOptions } from "./z-schema-options.mjs";
+import { ValidateOptions, ValidateResponse, ZSchemaBase } from "./z-schema-base.mjs";
+import { JsonSchema } from "./json-schema-versions.mjs";
+import { SchemaReader } from "./z-schema-reader.mjs";
+
+//#region src/z-schema.d.ts
+declare class ZSchema extends ZSchemaBase {
+  /** @internal Use ZSchema.create() instead. */
+  constructor(options: ZSchemaOptions | undefined, token: symbol);
+  /**
+   * Register a global format validator available to all instances.
+   * @param name - The format name (e.g. `'email'`, `'date'`).
+   * @param validatorFunction - A sync or async function `(value: unknown) => boolean | Promise<boolean>`.
+   */
+  static registerFormat(name: string, validatorFunction: FormatValidatorFn): void;
+  /**
+   * Remove a globally registered format validator.
+   * @param name - The format name to unregister.
+   */
+  static unregisterFormat(name: string): void;
+  /** Returns the names of all globally registered format validators. */
+  static getRegisteredFormats(): string[];
+  /** Returns a deep clone of the default options. */
+  static getDefaultOptions(): ZSchemaOptions;
+  /**
+   * Register a remote schema in the global cache so any instance can resolve `$ref` to it.
+   * @param uri - The URI the schema will be known by.
+   * @param schema - The schema object or JSON string.
+   * @param validationOptions - Optional options used for schema preparation.
+   */
+  static setRemoteReference(uri: string, schema: string | JsonSchema, validationOptions?: ZSchemaOptions): void;
+  /** Returns the current global schema reader, or `undefined` if none is set. */
+  static getSchemaReader(): SchemaReader | undefined;
+  /**
+   * Set a global schema reader function used to resolve remote `$ref` URIs.
+   * @param schemaReader - A function `(uri: string) => JsonSchema | undefined`, or `undefined` to clear.
+   */
+  static setSchemaReader(schemaReader: SchemaReader | undefined): void;
+  static schemaSymbol: symbol;
+  static jsonSymbol: symbol;
+  /**
+   * Create a validator instance.
+   *
+   * The returned type depends on the `async` and `safe` options:
+   * - `{}` → `ZSchema` — `validate()` returns `true` or throws.
+   * - `{ safe: true }` → `ZSchemaSafe` — `validate()` returns `{ valid, err? }`.
+   * - `{ async: true }` → `ZSchemaAsync` — `validate()` returns `Promise<true>` or rejects.
+   * - `{ async: true, safe: true }` → `ZSchemaAsyncSafe` — `validate()` returns `Promise<{ valid, err? }>`.
+   *
+   * @param options - Validator configuration. See `ZSchemaOptions` for all available settings.
+   * @returns A validator instance of the appropriate variant.
+   *
+   * @example
+   * ```ts
+   * const validator = ZSchema.create();
+   * validator.validate(data, schema); // throws on error
+   *
+   * const safe = ZSchema.create({ safe: true });
+   * const result = safe.validate(data, schema); // { valid, err? }
+   * ```
+   */
+  static create(options: ZSchemaOptions & {
+    async: true;
+    safe: true;
+  }): ZSchemaAsyncSafe;
+  static create(options: ZSchemaOptions & {
+    async: true;
+  }): ZSchemaAsync;
+  static create(options: ZSchemaOptions & {
+    safe: true;
+  }): ZSchemaSafe;
+  static create(options?: ZSchemaOptions): ZSchema;
+  /**
+   * Validate JSON data against a schema.
+   * @param json - The data to validate.
+   * @param schema - A JSON Schema object or a schema id string (previously registered via `validateSchema`).
+   * @param options - Per-call options (`schemaPath`, `includeErrors`, `excludeErrors`).
+   * @returns `true` if valid.
+   * @throws {@link ValidateError} if validation fails, with a `details` array of structured errors.
+   */
+  validate(json: unknown, schema: JsonSchema | string, options?: ValidateOptions): true;
+  /**
+   * Validate JSON data against a schema, returning a result object instead of throwing.
+   * @param json - The data to validate.
+   * @param schema - A JSON Schema object or a schema id string.
+   * @param options - Per-call options.
+   * @returns `{ valid: true }` on success, or `{ valid: false, err: ValidateError }` on failure.
+   */
+  validateSafe(json: unknown, schema: JsonSchema | string, options?: ValidateOptions): ValidateResponse;
+  /**
+   * Validate JSON data against a schema asynchronously (supports async format validators).
+   * @param json - The data to validate.
+   * @param schema - A JSON Schema object or a schema id string.
+   * @param options - Per-call options.
+   * @returns A promise that resolves to `true` if valid.
+   * @throws {@link ValidateError} if validation fails (the promise rejects).
+   */
+  validateAsync(json: unknown, schema: JsonSchema | string, options?: ValidateOptions): Promise<true>;
+  /**
+   * Validate JSON data against a schema asynchronously, returning a result object.
+   * The promise always resolves (never rejects).
+   * @param json - The data to validate.
+   * @param schema - A JSON Schema object or a schema id string.
+   * @param options - Per-call options.
+   * @returns A promise resolving to `{ valid: true }` or `{ valid: false, err: ValidateError }`.
+   */
+  validateAsyncSafe(json: unknown, schema: JsonSchema | string, options?: ValidateOptions): Promise<ValidateResponse>;
+  /**
+   * Validate one or more JSON Schemas, compiling and caching them for later use with `validate()`.
+   * @param schemaOrArr - A single schema or an array of schemas (for cross-referencing).
+   * @returns `true` if all schemas are valid.
+   * @throws {@link ValidateError} if any schema is invalid.
+   */
+  validateSchema(schemaOrArr: JsonSchema | JsonSchema[]): true;
+  /**
+   * Validate one or more JSON Schemas, returning a result object instead of throwing.
+   * @param schemaOrArr - A single schema or an array of schemas.
+   * @returns `{ valid: true }` on success, or `{ valid: false, err: ValidateError }` on failure.
+   */
+  validateSchemaSafe(schemaOrArr: JsonSchema | JsonSchema[]): ValidateResponse;
+}
+/**
+ * Synchronous safe validator — `validate()` returns `{ valid, err? }` instead of throwing.
+ * Created via `ZSchema.create({ safe: true })`.
+ */
+declare class ZSchemaSafe extends ZSchemaBase {
+  /** @internal Use ZSchema.create() instead. */
+  constructor(options: ZSchemaOptions | undefined, token: symbol);
+  /**
+   * Validate JSON data against a schema.
+   * @param json - The data to validate.
+   * @param schema - A JSON Schema object or a schema id string.
+   * @param options - Per-call options.
+   * @returns `{ valid: true }` on success, or `{ valid: false, err: ValidateError }` on failure.
+   */
+  validate(json: unknown, schema: JsonSchema | string, options?: ValidateOptions): ValidateResponse;
+  /**
+   * Validate one or more JSON Schemas.
+   * @param schemaOrArr - A single schema or an array of schemas.
+   * @returns `{ valid: true }` on success, or `{ valid: false, err: ValidateError }` on failure.
+   */
+  validateSchema(schemaOrArr: JsonSchema | JsonSchema[]): ValidateResponse;
+}
+/**
+ * Asynchronous throw validator — `validate()` returns `Promise<true>` or rejects.
+ * Created via `ZSchema.create({ async: true })`.
+ */
+declare class ZSchemaAsync extends ZSchemaBase {
+  /** @internal Use ZSchema.create() instead. */
+  constructor(options: ZSchemaOptions | undefined, token: symbol);
+  /**
+   * Validate JSON data against a schema asynchronously.
+   * @param json - The data to validate.
+   * @param schema - A JSON Schema object or a schema id string.
+   * @param options - Per-call options.
+   * @returns A promise that resolves to `true` if valid.
+   * @throws {@link ValidateError} if validation fails (the promise rejects).
+   */
+  validate(json: unknown, schema: JsonSchema | string, options?: ValidateOptions): Promise<true>;
+  /**
+   * Validate one or more JSON Schemas (synchronous, throws on error).
+   * @param schemaOrArr - A single schema or an array of schemas.
+   * @returns `true` if all schemas are valid.
+   * @throws {@link ValidateError} if any schema is invalid.
+   */
+  validateSchema(schemaOrArr: JsonSchema | JsonSchema[]): true;
+}
+/**
+ * Asynchronous safe validator — `validate()` returns `Promise<{ valid, err? }>` (never rejects).
+ * Created via `ZSchema.create({ async: true, safe: true })`.
+ */
+declare class ZSchemaAsyncSafe extends ZSchemaBase {
+  /** @internal Use ZSchema.create() instead. */
+  constructor(options: ZSchemaOptions | undefined, token: symbol);
+  /**
+   * Validate JSON data against a schema asynchronously.
+   * The promise always resolves (never rejects).
+   * @param json - The data to validate.
+   * @param schema - A JSON Schema object or a schema id string.
+   * @param options - Per-call options.
+   * @returns A promise resolving to `{ valid: true }` or `{ valid: false, err: ValidateError }`.
+   */
+  validate(json: unknown, schema: JsonSchema | string, options?: ValidateOptions): Promise<ValidateResponse>;
+  /**
+   * Validate one or more JSON Schemas.
+   * @param schemaOrArr - A single schema or an array of schemas.
+   * @returns `{ valid: true }` on success, or `{ valid: false, err: ValidateError }` on failure.
+   */
+  validateSchema(schemaOrArr: JsonSchema | JsonSchema[]): ValidateResponse;
+}
+//#endregion
+export { ZSchema, ZSchemaAsync, ZSchemaAsyncSafe, ZSchemaSafe };