ata-validator 1.8.0 → 1.8.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to ata-validator are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/), and this project adheres to semantic versioning.
 
+## 1.8.1 - 2026-08-27
+
+### Changed
+
+- Constructing a validator no longer clones and serializes every schema to find out whether it needed normalizing. It did that on the root and on each registered schema: serialize, deep clone, normalize the clone, serialize again, compare. For a schema with no `nullable` field and no draft-07 keyword the answer is always no, and the work was thrown away. Every question the normalizers ask is whether some key appears anywhere in the tree, so one walk answers all of them, and the clone now happens only for schemas that need it. No registry and ten fields goes from 18.5 to 4.6 µs; fifty registered schemas of fifty fields, which is a small server's worth, from 2570 to 260 µs.
+
+  The walk descends through every object-valued key rather than the subschema keywords the normalizers recurse through, so it is a superset of what they visit: it can report work where there is none, costing one clone, and cannot miss work there is. Across the 2344 schemas in the official suite it reports work on 335 where normalization changes 334. `tests/test_schema_scan.js` asserts that direction over the whole suite, and asserts the check is load-bearing by breaking the scan deliberately and confirming the broken one is caught.
+
+  The answer is remembered against the schema object, the way whole compiled validators already are, and so is the schema map built from a registry. Both were being redone once per validator, so a server building one validator per route over a shared registry paid for that registry once per route. Fifty routes over twenty shared schemas boots in 0.046 ms rather than 20.66 ms. Validators share the map, and anything that writes to one, which is `addSchema()` and the meta-schema registration during compilation, takes a private copy first.
+
+  Nothing about what any schema validates to changes. The comparison that decided the old answer is still there behind the walk, so a schema the walk sends down the slow path gets exactly the result it got before.
+
 ## 1.8.0 - 2026-08-27
 
 ### Added
@@ -24,7 +36,7 @@ All notable changes to ata-validator are documented here. The format follows [Ke
 
 ### Changed
 
-- Rejecting a document through the buffer APIs no longer costs more than accepting one. The On-Demand plan answers first, and a `false` from it used to be ambiguous: it could mean the document failed a constraint, or that the plan could not decide. The caller had to assume the second, so it re-created the padded view, parsed the whole document again into a DOM, tried the generated plan, and then walked the tree. A rejected document was therefore parsed twice and walked up to three times. The plan now reports whether it stopped because the document failed a constraint or because it could not be read, and only the second falls through. simdjson's `INCORRECT_TYPE` is a constraint failure rather than a read failure, which is the distinction that makes this work: a property holding a string where the schema wants an integer surfaces as a read error from `get<int64>`, not as a type mismatch. On a 62 KB array of a thousand objects with one bad element: 316 µs to 11 µs when the bad element is first, 315 µs to 40 µs when it is last, and rejecting is now never dearer than accepting. `tests/test_buffer_path_parity.js` holds the buffer path to the same answers as `validate()` across all 3359 suite cases, and still reports zero disagreements.
+- Rejecting a document through the buffer APIs no longer costs more than accepting one. The On-Demand plan answers first, and a `false` from it used to be ambiguous: it could mean the document failed a constraint, or that the plan could not decide. The caller had to assume the second, so it re-created the padded view, parsed the whole document again into a DOM, tried the generated plan, and then walked the tree. A rejected document was therefore parsed twice and walked up to three times. The plan now reports whether it stopped because the document failed a constraint or because it could not be read, and only the second falls through. simdjson's `INCORRECT_TYPE` is a constraint failure rather than a read failure, which is the distinction that makes this work: a property holding a string where the schema wants an integer surfaces as a read error from `get<int64>`, not as a type mismatch. On a 62 KB array of a thousand objects with one bad element: 316 µs to 11 µs when the bad element is first, 315 µs to 40 µs when it is last. On that shape rejecting is no longer dearer than accepting, and when the bad element is early it is several times cheaper. It is still dearer on a small document, where there is no bulk of parsing for an early exit to save: on a two-field object, 129 ns to accept and 278 ns to reject. `tests/test_buffer_path_parity.js` holds the buffer path to the same answers as `validate()` across all 3359 suite cases, and still reports zero disagreements.
 
 ## 1.7.3 - 2026-08-26
 

package/index.js

@@ -11,6 +11,7 @@ const {
 } = require("./lib/js-compiler");
 const { normalizeDraft7, normalizeNullable, stripFormatAssertions } = require("./lib/draft7");
 const { enabledKeywords, stripDisabledKeywords } = require("./lib/vocabularies");
+const { needsNormalization } = require("./lib/schema-scan");
 const { isV1Dialect } = require("./lib/dialect");
 const { classify } = require("./lib/shape-classifier");
 const { buildTier0Plan, tier0Validate } = require("./lib/tier0");
@@ -460,11 +461,20 @@ function _normalizeCallerSchema(s, inheritDraft7) {
   const needsDraft7 = declares
     ? (s.$schema === 'http://json-schema.org/draft-07/schema#' || s.$schema === 'http://json-schema.org/draft-07/schema')
     : !!inheritDraft7
+  // One walk answers whether there is anything to do. Almost always there is
+  // not, and then the serialize, clone, normalize, serialize, compare below is
+  // work spent to find that out. The walk over-reports rather than under, so a
+  // schema it clears is one no normalizer would have touched;
+  // `tests/test_schema_scan.js` holds that direction against the whole suite.
+  if (!needsNormalization(s, needsDraft7)) return s
+
   const str = JSON.stringify(s)
   const copy = _deepCloneWithSymbols(s)
   if (needsDraft7) normalizeDraft7(copy, true)
   normalizeNullable(copy)
   // Return original when normalization produced no change, copy otherwise.
+  // Kept even though the walk has already said there is work, so that a walk
+  // which over-reports still returns exactly what it returned before.
   // Change-detection uses JSON content only; symbols do not affect it.
   return JSON.stringify(copy) === str ? s : copy
 }
@@ -488,8 +498,33 @@ function declaredId(original, normalized) {
 
 // `inheritDraft7` is true when the root schema is draft-07: a retrieved
 // document that declares no dialect is read under the root's draft.
+// The map is derived entirely from what the caller passed, so the same
+// `schemas` gives the same map. A server building one validator per route over
+// a shared registry rebuilt it once per route, normalizing and re-reading the
+// `$id` of every registered schema each time. Keyed by the registry object,
+// and by the draft it is read under, since that changes what normalization
+// does to a document which declares no dialect of its own.
+//
+// Validators share the returned map, so anything that mutates one calls
+// `_ownSchemaMap()` first. There are two such places: registering the vendored
+// meta-schemas during compilation, and `addSchema()`.
+const _schemaMapCache = new WeakMap()
+
 function buildSchemaMap(schemas, inheritDraft7) {
   if (!schemas) return null
+  const byDraft = _schemaMapCache.get(schemas)
+  if (byDraft) {
+    const hit = byDraft[inheritDraft7 ? 1 : 0]
+    if (hit) return hit
+  }
+  const map = _buildSchemaMap(schemas, inheritDraft7)
+  const slot = byDraft || [null, null]
+  slot[inheritDraft7 ? 1 : 0] = map
+  if (!byDraft) _schemaMapCache.set(schemas, slot)
+  return map
+}
+
+function _buildSchemaMap(schemas, inheritDraft7) {
   const map = new Map()
   if (Array.isArray(schemas)) {
     for (const s of schemas) {
@@ -648,7 +683,9 @@ class Validator {
     // Built here rather than below because `$vocabulary` is resolved against
     // it, and that resolution waits until compilation so a meta-schema
     // registered by addSchema() still counts.
-    const schemaMap = buildSchemaMap(options.schemas, rootIsDraft7) || new Map();
+    const shared = buildSchemaMap(options.schemas, rootIsDraft7);
+    const schemaMap = shared || new Map();
+    this._schemaMapShared = shared !== null;
     this._schemaIsCallers = schemaObj === schema;
     this._vocabulariesApplied = false;
 
@@ -824,6 +861,7 @@ class Validator {
     // reference pay for the lookup.
     if (this._schemaStr.includes('json-schema.org/draft')) {
       const { METASCHEMAS } = require('./lib/metaschemas');
+      this._ownSchemaMap();
       for (const [id, meta] of METASCHEMAS) {
         const bare = id.replace(/#$/, '');
         for (const key of [id, bare, bare + '#', bare.replace(/^https:/, 'http:'), bare.replace(/^http:/, 'https:')]) {
@@ -1532,9 +1570,18 @@ class Validator {
     const rootIsDraft7 = !!(root && typeof root === 'object' && typeof root.$schema === 'string' &&
       (root.$schema === 'http://json-schema.org/draft-07/schema#' || root.$schema === 'http://json-schema.org/draft-07/schema'))
     const normalized = _normalizeCallerSchema(schema, rootIsDraft7)
+    this._ownSchemaMap()
     this._schemaMap.set(normalized.$id, normalized)
   }
 
+  // buildSchemaMap hands the same map to every validator built from the same
+  // registry. Take a private copy before writing to it.
+  _ownSchemaMap() {
+    if (!this._schemaMapShared) return
+    this._schemaMap = new Map(this._schemaMap)
+    this._schemaMapShared = false
+  }
+
   _ensureCodegen() {
     if (this._jsFn) return;
     this._ensureVocabularies();

package/lib/schema-scan.js

@@ -0,0 +1,115 @@
+'use strict';
+
+// One walk of a schema, answering in a single integer the questions that are
+// currently answered by doing work and looking at the result.
+//
+// `_normalizeCallerSchema` decides whether a schema needs normalizing by
+// serializing it, cloning it, normalizing the clone and serializing again to
+// compare. Two serializations and a deep copy, on every schema, to find out
+// that a modern schema needs nothing. The questions the normalizers actually
+// ask are all of the form "does this key appear anywhere in the tree", and one
+// traversal answers all of them at once. Daniel Lemire's rule from the C++
+// side, a layer up: do not do the work to find out whether the work is needed.
+//
+// The walk deliberately descends through **every** object-valued key, not the
+// list of subschema keywords the normalizers recurse through. That makes it a
+// superset of what they visit, so it can report work where there is none, but
+// never miss work there is. A false positive costs one clone. A false negative
+// would hand an un-normalized schema to the engines, which is the silent
+// acceptance this codebase treats as its worst failure. `tests/test_schema_scan.js`
+// pins the direction of that error against the whole suite.
+
+// One bit per question. Kept small and explicit; a schema which trips none of
+// them scans to 0 and can skip normalization entirely.
+const NULLABLE = 1 << 0;         // `nullable`, which normalizeNullable folds into `type`
+const REF_SIBLINGS = 1 << 1;     // a draft-07 `$ref` carrying keywords which are ignored
+const ANCHOR_ID = 1 << 2;        // a fragment-only `$id`, which is an anchor in draft-07
+const DEFINITIONS = 1 << 3;      // `definitions`, renamed to `$defs`
+const DEPENDENCIES = 1 << 4;     // `dependencies`, split into two keywords
+const TUPLE_ITEMS = 1 << 5;      // array-valued `items`, split into `prefixItems`
+
+// Everything only draft-07 normalization acts on. A schema of another dialect
+// can carry these without them meaning anything, so they are read together
+// with whether the document is draft-07 at all.
+const DRAFT7_WORK = REF_SIBLINGS | ANCHOR_ID | DEFINITIONS | DEPENDENCIES | TUPLE_ITEMS;
+
+// Copied from the normalizer rather than shared, so that a change there which
+// forgets this file shows up as a differential test failure rather than as a
+// silently wider scan. The test asserts the two agree.
+const REF_SIBLINGS_KEPT = new Set([
+  '$ref', '$defs', 'definitions', '$schema', '$comment',
+  'title', 'description', 'examples', 'default', 'readOnly', 'writeOnly',
+]);
+const ANCHOR_ID_RE = /^#[A-Za-z][A-Za-z0-9_.:-]*$/;
+
+// The answer depends only on the object, so it is remembered against it. A
+// server building one validator per route over a shared registry hands the
+// same registry objects to every one of them: fifty routes over twenty shared
+// schemas scanned those twenty a thousand times. Identity caching is what
+// `_identityCache` already does for whole compiled validators.
+//
+// This assumes a schema is not mutated after being handed to a Validator,
+// which is already true of everything else here: the compile cache, the
+// identity cache and the schema map would all be stale too.
+const CACHE = new WeakMap();
+
+function scan(schema) {
+  if (typeof schema !== 'object' || schema === null) return 0;
+  const hit = CACHE.get(schema);
+  if (hit !== undefined) return hit;
+
+  let bits = 0;
+  const seen = new Set();
+
+  const walk = (node) => {
+    if (typeof node !== 'object' || node === null) return;
+    if (Array.isArray(node)) {
+      for (let i = 0; i < node.length; i++) walk(node[i]);
+      return;
+    }
+    if (seen.has(node)) return;
+    seen.add(node);
+
+    if ('nullable' in node) bits |= NULLABLE;
+    if (node.definitions !== undefined && node.$defs === undefined) bits |= DEFINITIONS;
+    if (node.dependencies !== undefined) bits |= DEPENDENCIES;
+    if (Array.isArray(node.items)) bits |= TUPLE_ITEMS;
+    if (typeof node.$id === 'string' && ANCHOR_ID_RE.test(node.$id)) bits |= ANCHOR_ID;
+
+    // `Object.keys` rather than `for...in`: the prototype chain has nothing
+    // to contribute here, and walking it is the slower path in V8.
+    const keys = Object.keys(node);
+    if (typeof node.$ref === 'string') {
+      for (let i = 0; i < keys.length; i++) {
+        if (!REF_SIBLINGS_KEPT.has(keys[i])) { bits |= REF_SIBLINGS; break; }
+      }
+    }
+    // Every key, not just the subschema keywords, so this cannot miss a place
+    // the normalizers would reach.
+    for (let i = 0; i < keys.length; i++) walk(node[keys[i]]);
+  };
+
+  walk(schema);
+  CACHE.set(schema, bits);
+  return bits;
+}
+
+// Would normalization change this schema? `isDraft7` says whether the draft-07
+// rules apply at all, which the caller already knows.
+function needsNormalization(schema, isDraft7) {
+  const bits = scan(schema);
+  if (bits & NULLABLE) return true;
+  return isDraft7 ? (bits & DRAFT7_WORK) !== 0 : false;
+}
+
+module.exports = {
+  scan,
+  needsNormalization,
+  NULLABLE,
+  REF_SIBLINGS,
+  ANCHOR_ID,
+  DEFINITIONS,
+  DEPENDENCIES,
+  TUPLE_ITEMS,
+  DRAFT7_WORK,
+};

package/lib/version.js

@@ -7,4 +7,4 @@
 //
 // Kept in lockstep with package.json by `tests/test_version_sync.js`.
 
-module.exports = '1.8.0';
+module.exports = '1.8.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "JSON Schema validation with first-class TypeScript and zero runtime cost. AOT compile to per-schema ESM modules with zero validator dependency. Generic Validator<T> for TypeBox/Zod/Valibot composition. Optional runtime API. Standard Schema V1 compatible.",
   "main": "index.js",
   "module": "index.mjs",
@@ -44,7 +44,7 @@
     "release:check": "node scripts/regen-safe-regex-source.js && node tests/test_pack_purity.js && node scripts/check-doc-coverage.js && node tests/test_error_codes_lock.js && node tests/test_safe_regex_source_sync.js && node tests/test_version_sync.js",
     "build": "cmake-js build --target ata",
     "rebuild": "cmake-js rebuild --target ata",
-    "test": "node test.js && node tests/test_removed_aot_methods.js && node tests/test_no_native.js && node tests/test_no_eval.js && node tests/test_property_dependencies.js && node tests/test_v1_dialect.js && node tests/test_buffer_path_parity.js && node tests/test_buffer_gate.js && node tests/test_draft7_semantics.js && node tests/test_metaschema_ref.js && node tests/test_pure_js_unsupported.js && node tests/test_native_load_order.js && node tests/test_pack_purity.js && node tests/test_make_native_package.js && node tests/test_browser_nofs.js && node tests/test_browser_imports_guard.js && node tests/test_version_sync.js && node tests/test_native_loaded.js && node tests/test_safe_regex_source_sync.js && node tests/test_t_builder.js && node tests/test_async_refine.js && node tests/test_safe_regex.js && node tests/test_safe_regex_integration.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_standalone_anyof.js && node tests/test_standalone_formats.js && node tests/test_aot_format_mode.js && node tests/test_aot_additional_props_errors.js && node tests/test_id_anchor_refs.js && node tests/test_engine_routing.js && node tests/test_engine_diagnostic.js && node tests/test_format_engine_parity.js && node tests/test_defs_pointer_alias.js && node tests/test_cross_doc_root_ref.js && node tests/test_codegen_entrypoint_agreement.js && node tests/test_pattern_properties_errors.js && node tests/test_no_input_mutation.js && node tests/test_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.js && node tests/test_error_code_lookup.js && node tests/test_error_order.js && node tests/test_value_equality.js && node tests/test_vocabulary.js && node tests/test_lazy_errors.js && node tests/test_plan_compiler.js && node tests/test_nullable.js && node tests/test_validate_and_parse.js && node tests/test_validate_data.js && node tests/test_enrich_error.js && node tests/test_enrich_received.js && node tests/test_rich_errors_optout.js && node tests/test_error_messages.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node tests/test_cli_version.js && node benchmark/bench_aot_size.mjs",
+    "test": "node test.js && node tests/test_removed_aot_methods.js && node tests/test_no_native.js && node tests/test_no_eval.js && node tests/test_property_dependencies.js && node tests/test_v1_dialect.js && node tests/test_buffer_path_parity.js && node tests/test_buffer_gate.js && node tests/test_draft7_semantics.js && node tests/test_metaschema_ref.js && node tests/test_pure_js_unsupported.js && node tests/test_native_load_order.js && node tests/test_pack_purity.js && node tests/test_make_native_package.js && node tests/test_browser_nofs.js && node tests/test_browser_imports_guard.js && node tests/test_version_sync.js && node tests/test_native_loaded.js && node tests/test_safe_regex_source_sync.js && node tests/test_t_builder.js && node tests/test_async_refine.js && node tests/test_safe_regex.js && node tests/test_safe_regex_integration.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_standalone_anyof.js && node tests/test_standalone_formats.js && node tests/test_aot_format_mode.js && node tests/test_aot_additional_props_errors.js && node tests/test_id_anchor_refs.js && node tests/test_engine_routing.js && node tests/test_engine_diagnostic.js && node tests/test_format_engine_parity.js && node tests/test_defs_pointer_alias.js && node tests/test_cross_doc_root_ref.js && node tests/test_codegen_entrypoint_agreement.js && node tests/test_pattern_properties_errors.js && node tests/test_no_input_mutation.js && node tests/test_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.js && node tests/test_error_code_lookup.js && node tests/test_error_order.js && node tests/test_value_equality.js && node tests/test_vocabulary.js && node tests/test_schema_scan.js && node tests/test_lazy_errors.js && node tests/test_plan_compiler.js && node tests/test_nullable.js && node tests/test_validate_and_parse.js && node tests/test_validate_data.js && node tests/test_enrich_error.js && node tests/test_enrich_received.js && node tests/test_rich_errors_optout.js && node tests/test_error_messages.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node tests/test_cli_version.js && node benchmark/bench_aot_size.mjs",
     "bench:size": "node benchmark/bench_aot_size.mjs",
     "test:suite": "node tests/run_suite.js && node tests/run_suite.js draft7 && node tests/run_suite.js v1",
     "test:compat": "node tests/test_compat.js",
@@ -112,13 +112,13 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.8.0",
-    "@ata-validator/native-darwin-x64": "1.8.0",
-    "@ata-validator/native-linux-x64-gnu": "1.8.0",
-    "@ata-validator/native-linux-arm64-gnu": "1.8.0",
-    "@ata-validator/native-linux-x64-musl": "1.8.0",
-    "@ata-validator/native-linux-arm64-musl": "1.8.0",
-    "@ata-validator/native-win32-x64": "1.8.0"
+    "@ata-validator/native-darwin-arm64": "1.8.1",
+    "@ata-validator/native-darwin-x64": "1.8.1",
+    "@ata-validator/native-linux-x64-gnu": "1.8.1",
+    "@ata-validator/native-linux-arm64-gnu": "1.8.1",
+    "@ata-validator/native-linux-x64-musl": "1.8.1",
+    "@ata-validator/native-linux-arm64-musl": "1.8.1",
+    "@ata-validator/native-win32-x64": "1.8.1"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"