z-schema 12.0.4 → 12.1.0

package/dist/z-schema.mjs

@@ -0,0 +1,300 @@
+import { deepClone } from "./utils/clone.mjs";
+import { jsonSymbol, schemaSymbol } from "./utils/symbols.mjs";
+import { defaultOptions } from "./z-schema-options.mjs";
+import { SchemaCache, prepareRemoteSchema } from "./schema-cache.mjs";
+import "./z-schema-versions.mjs";
+import { getRegisteredFormats, registerFormat, unregisterFormat } from "./format-validators.mjs";
+import { getSchemaReader, setSchemaReader } from "./z-schema-reader.mjs";
+import { FACTORY_TOKEN, ZSchemaBase } from "./z-schema-base.mjs";
+//#region src/z-schema.ts
+var ZSchema = class ZSchema extends ZSchemaBase {
+	/** @internal Use ZSchema.create() instead. */
+	constructor(options, token) {
+		super(options, token);
+	}
+	/**
+	* 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, validatorFunction) {
+		return registerFormat(name, validatorFunction);
+	}
+	/**
+	* Remove a globally registered format validator.
+	* @param name - The format name to unregister.
+	*/
+	static unregisterFormat(name) {
+		return unregisterFormat(name);
+	}
+	/** Returns the names of all globally registered format validators. */
+	static getRegisteredFormats() {
+		return getRegisteredFormats();
+	}
+	/** Returns a deep clone of the default options. */
+	static getDefaultOptions() {
+		return deepClone(defaultOptions);
+	}
+	/**
+	* 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, schema, validationOptions) {
+		const _schema = prepareRemoteSchema(schema, uri, validationOptions);
+		SchemaCache.cacheSchemaByUri(uri, _schema);
+	}
+	/** Returns the current global schema reader, or `undefined` if none is set. */
+	static getSchemaReader() {
+		return getSchemaReader();
+	}
+	/**
+	* 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) {
+		return setSchemaReader(schemaReader);
+	}
+	static schemaSymbol = schemaSymbol;
+	static jsonSymbol = jsonSymbol;
+	static create(options = {}) {
+		const isAsync = options.async;
+		const isSafe = options.safe;
+		delete options.async;
+		delete options.safe;
+		if (isAsync && isSafe) return new ZSchemaAsyncSafe(options, FACTORY_TOKEN);
+		if (isAsync) return new ZSchemaAsync(options, FACTORY_TOKEN);
+		if (isSafe) return new ZSchemaSafe(options, FACTORY_TOKEN);
+		return new ZSchema(options, FACTORY_TOKEN);
+	}
+	/**
+	* 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, schema, options = {}) {
+		return this._validate(json, schema, options);
+	}
+	/**
+	* 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, schema, options) {
+		try {
+			this._validate(json, schema, options ?? {});
+			return { valid: true };
+		} catch (err) {
+			return {
+				valid: false,
+				err
+			};
+		}
+	}
+	/**
+	* 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, schema, options) {
+		return new Promise((resolve, reject) => {
+			try {
+				this._validate(json, schema, options || {}, (err, valid) => err || valid !== true ? reject(err) : resolve(valid));
+			} catch (err) {
+				reject(err);
+			}
+		});
+	}
+	/**
+	* 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, schema, options) {
+		return new Promise((resolve) => {
+			try {
+				this._validate(json, schema, options || {}, (err, valid) => {
+					resolve({
+						valid,
+						err
+					});
+				});
+			} catch (err) {
+				resolve({
+					valid: false,
+					err
+				});
+			}
+		});
+	}
+	/**
+	* 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) {
+		return this._validateSchema(schemaOrArr);
+	}
+	/**
+	* 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) {
+		try {
+			this._validateSchema(schemaOrArr);
+			return { valid: true };
+		} catch (err) {
+			return {
+				valid: false,
+				err
+			};
+		}
+	}
+};
+/**
+* Synchronous safe validator — `validate()` returns `{ valid, err? }` instead of throwing.
+* Created via `ZSchema.create({ safe: true })`.
+*/
+var ZSchemaSafe = class extends ZSchemaBase {
+	/** @internal Use ZSchema.create() instead. */
+	constructor(options, token) {
+		super(options, token);
+	}
+	/**
+	* 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, schema, options = {}) {
+		try {
+			this._validate(json, schema, options);
+			return { valid: true };
+		} catch (err) {
+			return {
+				valid: false,
+				err
+			};
+		}
+	}
+	/**
+	* 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) {
+		try {
+			this._validateSchema(schemaOrArr);
+			return { valid: true };
+		} catch (err) {
+			return {
+				valid: false,
+				err
+			};
+		}
+	}
+};
+/**
+* Asynchronous throw validator — `validate()` returns `Promise<true>` or rejects.
+* Created via `ZSchema.create({ async: true })`.
+*/
+var ZSchemaAsync = class extends ZSchemaBase {
+	/** @internal Use ZSchema.create() instead. */
+	constructor(options, token) {
+		super(options, token);
+	}
+	/**
+	* 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, schema, options = {}) {
+		return new Promise((resolve, reject) => {
+			try {
+				this._validate(json, schema, options, (err, valid) => err || valid !== true ? reject(err) : resolve(valid));
+			} catch (err) {
+				reject(err);
+			}
+		});
+	}
+	/**
+	* 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) {
+		return this._validateSchema(schemaOrArr);
+	}
+};
+/**
+* Asynchronous safe validator — `validate()` returns `Promise<{ valid, err? }>` (never rejects).
+* Created via `ZSchema.create({ async: true, safe: true })`.
+*/
+var ZSchemaAsyncSafe = class extends ZSchemaBase {
+	/** @internal Use ZSchema.create() instead. */
+	constructor(options, token) {
+		super(options, token);
+	}
+	/**
+	* 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, schema, options = {}) {
+		return new Promise((resolve) => {
+			try {
+				this._validate(json, schema, options, (err, valid) => {
+					resolve({
+						valid,
+						err
+					});
+				});
+			} catch (err) {
+				resolve({
+					valid: false,
+					err
+				});
+			}
+		});
+	}
+	/**
+	* 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) {
+		try {
+			this._validateSchema(schemaOrArr);
+			return { valid: true };
+		} catch (err) {
+			return {
+				valid: false,
+				err
+			};
+		}
+	}
+};
+//#endregion
+export { ZSchema };

package/package.json

@@ -1,53 +1,31 @@
 {
   "name": "z-schema",
-  "version": "12.0.4",
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "sideEffects": [
-    "./dist/z-schema-versions.js"
-  ],
+  "version": "12.1.0",
   "description": "Fast, lightweight JSON Schema validator for Node.js and browsers — full support for draft-04, draft-06, draft-07, draft-2019-09, and draft-2020-12 (latest)",
-  "homepage": "https://github.com/zaggino/z-schema",
-  "authors": [
-    "Martin Zagora <zaggino@gmail.com>"
-  ],
-  "license": "MIT",
   "keywords": [
-    "json-schema",
-    "json",
-    "schema",
-    "validator",
-    "validation",
-    "json-schema-validator",
     "draft-04",
     "draft-06",
     "draft-07",
     "draft-2019-09",
     "draft-2020-12",
+    "esm",
+    "json",
+    "json-schema",
+    "json-schema-validator",
     "jsonschema",
+    "schema",
     "typescript",
-    "esm"
+    "validation",
+    "validator"
   ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/zaggino/z-schema.git"
-  },
+  "homepage": "https://github.com/zaggino/z-schema",
   "bugs": {
     "url": "https://github.com/zaggino/z-schema/issues"
   },
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/types/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./cjs/index.d.ts",
-        "default": "./cjs/index.js"
-      },
-      "default": "./dist/index.js"
-    }
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zaggino/z-schema.git"
   },
   "bin": {
     "z-schema": "bin/z-schema"
@@ -61,20 +39,34 @@
     "LICENSE",
     "README.md"
   ],
+  "sideEffects": [
+    "./dist/z-schema-versions.mjs"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./cjs/index.d.ts",
+        "default": "./cjs/index.js"
+      },
+      "default": "./dist/index.mjs"
+    }
+  },
   "scripts": {
     "prepare": "husky",
     "pre-commit": "npx lint-staged",
     "pre-push": "npm run build && npm run build:tests",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "lint": "eslint --fix",
-    "lint:check": "eslint",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint --fix",
+    "lint:check": "oxlint",
     "clean": "rimraf ./cjs && rimraf ./dist && rimraf ./umd && rimraf --glob \"./src/schemas/*.json\"",
-    "build": "npm run copy:schemas && tsc && npm run copy:module-json && rollup -c",
-    "build:browser": "rollup -c --environment BROWSER",
-    "build:watch": "rollup -c -w",
+    "build": "npm run copy:schemas && tsdown",
+    "build:watch": "npm run copy:schemas && tsdown --watch",
     "build:tests": "tsc --noEmit --project test/tsconfig.json",
-    "copy:module-json": "node -e \"fs.copyFileSync('./src/package.json', './dist/package.json')\"",
     "copy:schemas": "node ./scripts/copy-schemas.mts",
     "coverage:artifacts": "node ./scripts/generate-test-coverage-report.mts",
     "coverage:update-badge": "node ./scripts/update-readme-coverage-badge.mts",
@@ -87,20 +79,10 @@
   },
   "dependencies": {
     "punycode": "^2.3.1",
+    "safe-regex2": "^5.1.0",
     "validator": "^13.15.26"
   },
-  "optionalDependencies": {
-    "commander": "^14.0.3"
-  },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@eslint/json": "^1.0.0",
-    "@eslint/markdown": "^7.5.1",
-    "@rollup/plugin-commonjs": "^29.0.0",
-    "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^16.0.3",
-    "@rollup/plugin-terser": "^1.0.0",
-    "@rollup/plugin-typescript": "^12.3.0",
     "@types/lodash.isequal": "^4.5.8",
     "@types/node": "^25.2.0",
     "@types/punycode": "^2.1.4",
@@ -108,20 +90,23 @@
     "@vitest/browser-playwright": "^4.0.18",
     "@vitest/coverage-istanbul": "^4.0.18",
     "@vitest/coverage-v8": "^4.0.18",
-    "@vitest/eslint-plugin": "^1.6.6",
-    "eslint": "^9.39.2",
-    "eslint-plugin-simple-import-sort": "^12.1.1",
-    "globals": "^17.3.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.7",
     "lodash.isequal": "^4.5.0",
-    "prettier": "^3.8.1",
+    "oxfmt": "^0.41.0",
+    "oxlint": "^1.56.0",
     "rimraf": "^6.1.2",
-    "rollup": "^4.59.0",
-    "rollup-plugin-dts": "^6.3.0",
-    "tslib": "^2.8.1",
+    "tsdown": "^0.21.4",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.54.0",
     "vitest": "^4.0.18"
-  }
+  },
+  "optionalDependencies": {
+    "commander": "^14.0.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "authors": [
+    "Martin Zagora <zaggino@gmail.com>"
+  ]
 }

package/src/index.ts

@@ -26,8 +26,8 @@ export type {
 } from './json-schema-versions.js';
 export type { Report, SchemaErrorDetail } from './report.js';
 export type { ZSchema, ZSchemaAsync, ZSchemaAsyncSafe, ZSchemaSafe } from './z-schema.js';
-export { ValidateOptions, ValidateResponse } from './z-schema-base.js';
-export { ZSchemaOptions } from './z-schema-options.js';
-export { SchemaReader } from './z-schema-reader.js';
+export type { ValidateOptions, ValidateResponse } from './z-schema-base.js';
+export type { ZSchemaOptions } from './z-schema-options.js';
+export type { SchemaReader } from './z-schema-reader.js';
 
 export default ZSchema;

package/src/schema-compiler.ts

@@ -7,14 +7,20 @@ import { DEFAULT_MAX_RECURSION_DEPTH } from './utils/constants.js';
 import { getRemotePath, isAbsoluteUri } from './utils/uri.js';
 import { getSchemaReader } from './z-schema-reader.js';
 
+const UNSAFE_TARGETS = [
+  Object.prototype as unknown as Record<string, unknown>,
+  Function.prototype as unknown as Record<string, unknown>,
+  Array.prototype as unknown as Record<string, unknown>,
+];
+
+/** Returns true if `obj` is a built-in prototype that must not be mutated. */
+function isUnsafeTarget(obj: Record<string, unknown>): boolean {
+  return UNSAFE_TARGETS.includes(obj);
+}
+
 /** Safely assign a property on `obj`, refusing prototype-polluting keys. */
 function safeSetProperty(obj: Record<string, unknown>, key: string, value: unknown): void {
-  const unsafeTargets = [
-    Object.prototype as unknown as Record<string, unknown>,
-    Function.prototype as unknown as Record<string, unknown>,
-    Array.prototype as unknown as Record<string, unknown>,
-  ];
-  if (unsafeTargets.includes(obj)) {
+  if (isUnsafeTarget(obj)) {
     return;
   }
   /** Reject property names that could pollute Object.prototype (CWE-1321). */
@@ -23,6 +29,16 @@ function safeSetProperty(obj: Record<string, unknown>, key: string, value: unkno
   }
 }
 
+/** Safely delete a property from `obj`, refusing to mutate built-in prototypes (CWE-1321). */
+function safeDeleteProperty(obj: Record<string, unknown>, key: string): void {
+  if (isUnsafeTarget(obj)) {
+    return;
+  }
+  if (key !== '__proto__' && key !== 'constructor' && key !== 'prototype') {
+    delete obj[key];
+  }
+}
+
 interface Id {
   id: string;
   type: 'absolute' | 'relative' | 'root';
@@ -348,7 +364,7 @@ export class SchemaCompiler {
     // delete all __$missingReferences from previous compilation attempts
     const isValidExceptReferences = report.isValid();
     if (canMutateSchemaObject) {
-      delete schema.__$missingReferences;
+      safeDeleteProperty(schema as unknown as Record<string, unknown>, '__$missingReferences');
     }
 
     // collect all references that need to be resolved - $ref and $schema
@@ -412,8 +428,12 @@ export class SchemaCompiler {
           report.addError('UNRESOLVABLE_REFERENCE', [refObj.ref]);
           report.path = report.path.slice(0, -refObj.path.length);
 
-          // pusblish unresolved references out
-          if (isValidExceptReferences && canMutateSchemaObject) {
+          // publish unresolved references out
+          if (
+            isValidExceptReferences &&
+            canMutateSchemaObject &&
+            !isUnsafeTarget(schema as unknown as Record<string, unknown>)
+          ) {
             schema.__$missingReferences = schema.__$missingReferences || [];
             schema.__$missingReferences.push(refObj);
           }
@@ -471,7 +491,7 @@ export class SchemaCompiler {
             }
           }
           if (sch.__$missingReferences.length === 0) {
-            delete sch.__$missingReferences;
+            safeDeleteProperty(sch as unknown as Record<string, unknown>, '__$missingReferences');
           }
         }
       }

package/src/schema-validator.ts

@@ -689,7 +689,7 @@ const SchemaValidators = {
       report.addError('KEYWORD_TYPE_EXPECTED', ['description', 'string'], undefined, schema, 'description');
     }
   },
-  default: function (this: SchemaValidator /* report, schema */) {
+  default: function (this: SchemaValidator) /* report, schema */ {
     // http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.2
     // There are no restrictions placed on the value of this keyword.
   },

package/src/utils/schema-regex.ts

@@ -1,6 +1,8 @@
 // Shared regex compilation helper for JSON Schema patterns
 // Returns { ok: true, value: RegExp } or { ok: false, error: { pattern, message } }
 
+import isSafeRegex from 'safe-regex2';
+
 import { MAX_SCHEMA_REGEX_LENGTH } from './constants.js';
 
 export function compileSchemaRegex(
@@ -16,6 +18,17 @@ export function compileSchemaRegex(
     };
   }
 
+  // Reject patterns vulnerable to catastrophic backtracking (ReDoS) before compiling
+  if (!isSafeRegex(pattern)) {
+    return {
+      ok: false,
+      error: {
+        pattern,
+        message: 'Pattern rejected as potentially unsafe (ReDoS)',
+      },
+    };
+  }
+
   const unicodePropertyEscape = /\\[pP]{/;
   const nonBmpCharacter = /[\u{10000}-\u{10FFFF}]/u;
   const surrogatePairEscape = /\\uD[89AB][0-9A-Fa-f]{2}\\uD[CDEF][0-9A-Fa-f]{2}/;
@@ -25,7 +38,6 @@ export function compileSchemaRegex(
   if (needsUnicode) {
     // Try compiling with 'u' flag only
     try {
-      // lgtm[js/regex-injection] JSON Schema `pattern` is intentionally regex syntax and constrained by MAX_SCHEMA_REGEX_LENGTH.
       const re = new RegExp(pattern, 'u');
       return { ok: true, value: re };
     } catch (e: any) {
@@ -39,7 +51,6 @@ export function compileSchemaRegex(
     }
   } else {
     try {
-      // lgtm[js/regex-injection] JSON Schema `pattern` is intentionally regex syntax and constrained by MAX_SCHEMA_REGEX_LENGTH.
       const re = new RegExp(pattern);
       return { ok: true, value: re };
     } catch (e: any) {

package/src/z-schema-base.ts

@@ -6,8 +6,8 @@ import type { ZSchemaOptions } from './z-schema-options.js';
 
 import { type Errors, getValidateError } from './errors.js';
 import { getSupportedFormats } from './format-validators.js';
-import { isInternalKey } from './json-schema.js';
 import { VERSION_SCHEMA_URL_MAPPING } from './json-schema-versions.js';
+import { isInternalKey } from './json-schema.js';
 import { validate as validateJson } from './json-validation.js';
 import { Report } from './report.js';
 import { prepareRemoteSchema, SchemaCache } from './schema-cache.js';

package/src/z-schema-versions.ts

@@ -11,8 +11,6 @@ import type {
 import type { ZSchemaOptions } from './z-schema-options.js';
 
 import { SchemaCache } from './schema-cache.js';
-import { normalizeOptions } from './z-schema-options.js';
-
 // draft-04
 import _Draft4Schema from './schemas/draft-04-schema.json' with { type: 'json' };
 // draft-06
@@ -37,6 +35,7 @@ import _Draft202012MetaMetaData from './schemas/draft-2020-12-meta-meta-data.jso
 import _Draft202012MetaUnevaluated from './schemas/draft-2020-12-meta-unevaluated.json' with { type: 'json' };
 import _Draft202012MetaValidation from './schemas/draft-2020-12-meta-validation.json' with { type: 'json' };
 import _Draft202012Schema from './schemas/draft-2020-12-schema.json' with { type: 'json' };
+import { normalizeOptions } from './z-schema-options.js';
 
 // draft-04
 const Draft4Schema: JsonSchemaDraft4 = _Draft4Schema;

package/src/z-schema.ts

@@ -6,7 +6,6 @@ import type { ZSchemaOptions } from './z-schema-options.js';
 import type { SchemaReader } from './z-schema-reader.js';
 
 import './z-schema-versions.js';
-
 import { getRegisteredFormats, registerFormat, unregisterFormat } from './format-validators.js';
 import { prepareRemoteSchema, SchemaCache } from './schema-cache.js';
 import { deepClone } from './utils/clone.js';