ata-validator 1.17.0 → 1.17.2

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 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.17.2 - 2026-09-13
+
+### Changed
+
+- `new Validator(schema)` no longer walks the schema. Normalization (the draft-07 rewrites, `nullable`, `format` removal under `assertFormat: false`) and the scan that decides whether any of it is needed now run on the first read of the schema, which is the first compile. Construction is the instance and its fields. Measured on the schema-benchmarks product schema built fresh each time: 4.28 to 0.91 µs; with the `@ata-project/keywords` wrapper (0.3.1, which reads the schema lazily too) 6.70 to 2.81 µs. Nothing observable changes for a schema that is used: the same normalized document reaches the engines, and the identity cache, `keywords`, `assertFormat` and `source` options behave as before. `tests/test_lazy_normalization.js` counts property reads on the schema during construction and holds them at the dialect lookup alone.
+
+## 1.17.1 - 2026-09-13
+
+### Changed
+
+- The rejection object behind a failing `validate()` is an instance of a class with prototype accessors rather than an object literal that defined a getter and a closure on every rejection. Same shape, same laziness, same caching; `JSON.stringify` still sees the errors.
+- Declaration-order sorting of short error lists is a stable in-place insertion sort over the integer keys, with no comparator and no index array. Measured on the raw error list of the schema-benchmarks product schema, 15 errors: 1.49 to 1.10 µs; through the Standard Schema bridge 2.02 to 1.63 µs. Since 1.16.2 that row has gone from 3.30 to 1.63 µs on the same machine, and in the schema-benchmarks harness itself standard invalid went from 3.57 to 1.44 µs (60 percent less), every other row within noise.
+
+### Fixed
+
+- `validateJSON()` reports errors in schema declaration order, as `validate()` does. The text path enriched errors in emission order, so the first error could differ between the two entry points for the same document.
+- An instance built with options no longer answers a later `new Validator(sameSchema)` without options. The identity cache was seeded by every instance, so a validator created with `richErrors: false` or `coerceTypes` could be handed back to a caller that asked for the defaults.
+
 ## 1.17.0 - 2026-09-13
 
 ### Changed

package/index.js

@@ -425,6 +425,63 @@ function resolveSchemaByPath(rootSchema, schemaPath) {
 const _rankCache = new WeakMap();
 const { rankFor: schemaOrderRank, ordinalFor: schemaOrdinal } = require('./lib/schema-order');
 
+// The rejection the rich-errors wrapper returns. `errors` is built on first
+// read and cached; `_ataRaw()` is the raw, schema-ordered list for consumers
+// that carry only message and path, such as the Standard Schema bridge.
+// Prototype accessors, not per-instance ones: see LazyRejection.
+class RichRejection {
+  constructor(result, data, positions, self, root, enrich) {
+    this.valid = false;
+    this._result = result;
+    this._data = data;
+    this._positions = positions;
+    this._self = self;
+    this._root = root;
+    this._enrich = enrich;
+    this._cached = null;
+  }
+  toJSON() {
+    return { valid: false, errors: this.errors };
+  }
+  _ataRaw() {
+    let raw = this._result.errors || [];
+    if (raw.length > 1) raw = sortErrorsBySchemaOrder(this._root, raw);
+    return raw;
+  }
+}
+Object.defineProperty(RichRejection.prototype, 'errors', {
+  enumerable: true,
+  configurable: true,
+  get() {
+    if (this._cached === null) {
+      const self = this._self;
+      const enrich = this._enrich;
+      let raw = this._result.errors || [];
+      if (raw.length > 1) raw = sortErrorsBySchemaOrder(this._root, raw);
+      const cached = (enrich && raw.length)
+        ? raw.map((e) => enrich(e, {
+            data: this._data,
+            positions: this._positions,
+            schemaPositions: self._schemaPositions,
+            schemaFile: self._source ? self._source.path : undefined,
+          }))
+        // The v0.14 shape is a fixed key set; the ordering key the
+        // generated code carries is dropped from it here.
+        : raw.map(stripOrdinal);
+      // Correlation is published, never applied. Both halves of a typo pair
+      // stay in the array; `related` only says they are one mistake, so a
+      // wrong pairing costs a sentence rather than a hidden violation.
+      if (enrich && cached.length > 1) attachRelated(cached);
+      // No diagnostic payload here. validate(data) is the library hot path,
+      // and attaching one cost about 100 ns per rejection for a consumer
+      // that never renders. The text path attaches it, and a renderer given
+      // `{ data }` builds frames for object input on request.
+      this._cached = cached;
+    }
+    return this._cached;
+  },
+});
+
 // A raw error without the `_o` ordering key, for the legacy error shape.
 function stripOrdinal(e) {
   if (e === null || typeof e !== 'object' || e._o === undefined) return e;
@@ -454,11 +511,17 @@ function sortErrorsBySchemaOrder(rootSchema, errors) {
     prev = o;
   }
   if (sorted) return errors;
-  const idx = new Array(n);
-  for (let i = 0; i < n; i++) idx[i] = i;
-  idx.sort((a, b) => keys[a] - keys[b] || a - b);
-  const out = new Array(n);
-  for (let i = 0; i < n; i++) out[i] = errors[idx[i]];
+  // Error lists are short. A stable insertion sort over the integer keys
+  // moves the errors in tandem with no comparator calls and no index array.
+  const out = errors.slice();
+  for (let i = 1; i < n; i++) {
+    const k = keys[i];
+    const e = out[i];
+    let j = i - 1;
+    while (j >= 0 && keys[j] > k) { keys[j + 1] = keys[j]; out[j + 1] = out[j]; j--; }
+    keys[j + 1] = k;
+    out[j + 1] = e;
+  }
   return out;
 }
 
@@ -734,6 +797,26 @@ function resolveSchemaForPreprocess(schema, schemaMap) {
   return cloned || s
 }
 
+// `_schemaObj` and `_usesKeywords` are materialized together on first read:
+// the caller's schema normalized on a clone (the caller's object is never
+// touched), `format` stripped under `assertFormat: false`, and the custom
+// keyword scan. The accessors then step aside for own data properties, so
+// every later read is a plain field.
+function _materializeSchema(self) {
+  const raw = self._rawSchema;
+  const options = self._options;
+  let schemaObj = _normalizeCallerSchema(raw);
+  const isCallers = self._rawIsCallers && schemaObj === raw;
+  if (options.assertFormat === false) {
+    schemaObj = stripFormatAssertions(isCallers ? _deepCloneWithSymbols(schemaObj) : schemaObj);
+  }
+  const usesKeywords = self._keywords !== null && schemaUsesKeywords(schemaObj, self._keywords);
+  Object.defineProperty(self, '_schemaObj', { value: schemaObj, writable: true, configurable: true, enumerable: true });
+  Object.defineProperty(self, '_usesKeywords', { value: usesKeywords, writable: true, configurable: true, enumerable: true });
+  Object.defineProperty(self, '_schemaIsCallers', { value: isCallers && schemaObj === raw, writable: true, configurable: true, enumerable: true });
+  return schemaObj;
+}
+
 class Validator {
   constructor(schema, opts) {
     const options = opts || {};
@@ -746,22 +829,16 @@ class Validator {
       if (hit) return hit;
     }
 
+    // The schema is not walked here. Normalization (draft-07 rewrites,
+    // nullable, `assertFormat: false`) and the scan that decides whether any
+    // of it is needed run on the first read of `_schemaObj`, which is the
+    // first compile. Construction is the object and its fields; a server
+    // building a validator per request pays nothing for a schema it never
+    // uses, and a benchmark timing construction measures construction.
     // When schema is a string, JSON.parse already produces a fresh object.
-    // When schema is an object, normalization runs on a clone so the caller's
-    // object is never touched.
-    let schemaObj = typeof schema === "string"
-      ? _normalizeCallerSchema(JSON.parse(schema))
-      : _normalizeCallerSchema(schema);
-    const rootIsDraft7 = !!(schemaObj && typeof schemaObj === 'object' && typeof schemaObj.$schema === 'string' &&
-      (schemaObj.$schema === 'http://json-schema.org/draft-07/schema#' || schemaObj.$schema === 'http://json-schema.org/draft-07/schema'));
-
-    // assertFormat: false makes `format` annotation-only. Strip it on a clone
-    // so the caller's schema keeps the keyword.
-    if (options.assertFormat === false) {
-      schemaObj = stripFormatAssertions(
-        schemaObj === schema ? _deepCloneWithSymbols(schemaObj) : schemaObj,
-      );
-    }
+    const raw = typeof schema === "string" ? JSON.parse(schema) : schema;
+    const rootIsDraft7 = !!(raw && typeof raw === 'object' && typeof raw.$schema === 'string' &&
+      (raw.$schema === 'http://json-schema.org/draft-07/schema#' || raw.$schema === 'http://json-schema.org/draft-07/schema'));
 
     // Built here rather than below because `$vocabulary` is resolved against
     // it, and that resolution waits until compilation so a meta-schema
@@ -769,22 +846,19 @@ class Validator {
     const shared = buildSchemaMap(options.schemas, rootIsDraft7);
     const schemaMap = shared || new Map();
     this._schemaMapShared = shared !== null;
-    this._schemaIsCallers = schemaObj === schema;
     this._vocabulariesApplied = false;
 
-    // Custom keywords, normalized once. `_usesKeywords` is what routes the
-    // schema to the interpreted engine and keeps it out of the shared
-    // compile cache; a schema that registers keywords but uses none of them
-    // takes the ordinary path.
+    // Custom keywords, normalized once. `_usesKeywords` (resolved with the
+    // schema) is what routes the schema to the interpreted engine and keeps
+    // it out of the shared compile cache; a schema that registers keywords
+    // but uses none of them takes the ordinary path.
     this._keywords = normalizeKeywords(options.keywords);
-    this._usesKeywords = false;
-    if (this._keywords !== null && schemaUsesKeywords(schemaObj, this._keywords)) {
-      this._usesKeywords = true;
-    }
 
     this._schemaStr = null; // lazy: computed on first use
-    this._schemaObj = schemaObj;
+    this._rawSchema = raw;
+    this._rawIsCallers = typeof schema !== "string";
     this._options = options;
+    this._noOpts = !opts;
     this._initialized = false;
     this._nativeReady = false;
     this._compiled = null;
@@ -1422,45 +1496,11 @@ class Validator {
           // resolved eagerly since the cache is reset per call.
           const positions = (enrich && self._lastRawInput != null) ? self._pos().get(self._lastRawInput) : null;
           if (positions) self._posCache.reset();
-          let cached = null;
-          return {
-            valid: false,
-            // Raw shape for consumers that carry only message and path, such
-            // as the Standard Schema bridge: schema order, no enrichment.
-            // Reading `errors` afterwards still enriches from the same build.
-            _ataRaw() {
-              let raw = result.errors || [];
-              if (raw.length > 1) raw = sortErrorsBySchemaOrder(root, raw);
-              return raw;
-            },
-            get errors() {
-              if (cached === null) {
-                let raw = result.errors || [];
-                if (raw.length > 1) raw = sortErrorsBySchemaOrder(root, raw);
-                cached = (enrich && raw.length)
-                  ? raw.map((e) => enrich(e, {
-                      data,
-                      positions,
-                      schemaPositions: self._schemaPositions,
-                      schemaFile: self._source ? self._source.path : undefined,
-                    }))
-                  // The v0.14 shape is a fixed key set; the ordering key the
-                  // generated code carries is dropped from it here.
-                  : raw.map(stripOrdinal);
-                // Correlation is published, never applied. Both halves of a
-                // typo pair stay in the array; `related` only says they are
-                // one mistake, so a wrong pairing costs a sentence rather
-                // than a hidden violation.
-                if (enrich && cached.length > 1) attachRelated(cached);
-                // No diagnostic payload here. validate(data) is the library
-                // hot path, and attaching one cost about 100 ns per rejection
-                // for a consumer that never renders. The text path attaches
-                // it below, and a renderer given `{ data }` builds frames for
-                // object input on request.
-              }
-              return cached;
-            },
-          };
+          // One instance of a class with prototype accessors. An object
+          // literal with a getter here cost a closure plus an accessor
+          // definition on every rejection, several hundred nanoseconds
+          // before any error was read.
+          return new RichRejection(result, data, positions, self, root, enrich);
         }
         return result;
       };
@@ -1496,7 +1536,10 @@ class Validator {
             try { parsedData = JSON.parse(jsonStr); } catch { parsedData = undefined; }
             if (!first || !first.docUrl) {
               const positions = (this._lastRawInput != null) ? this._pos().get(this._lastRawInput) : null;
-              const enriched = result.errors.map((e) => enrich(e, {
+              // Declaration order, as validate() applies it; the text path
+              // used to enrich in emission order.
+              const ordered = result.errors.length > 1 ? sortErrorsBySchemaOrder(this._schemaObj, result.errors) : result.errors;
+              const enriched = ordered.map((e) => enrich(e, {
                 data: parsedData,
                 positions,
                 schemaPositions: this._schemaPositions,
@@ -1635,8 +1678,12 @@ class Validator {
       if (bufferNeedsSlowPath(schemaObj, this._schemaMap, this._keywords)) installSlowBufferApis(this);
     }
 
-    // Save to identity cache for ultra-fast reuse with same schema object
-    if (this._schemaObj && typeof this._schemaObj === 'object') {
+    // Save to identity cache for ultra-fast reuse with same schema object.
+    // Only an instance built without options may answer a later
+    // `new Validator(schema)`: one built with options (richErrors: false,
+    // coerceTypes, formats, ...) would hand its options to a caller that
+    // asked for none.
+    if (this._noOpts && this._schemaObj && typeof this._schemaObj === 'object') {
       _identityCache.set(this._schemaObj, this);
     }
   }
@@ -2125,6 +2172,18 @@ function _defineLazyMethod(name, maker) {
   });
 }
 
+for (const [name, pick] of [
+  ['_schemaObj', (self) => _materializeSchema(self)],
+  ['_usesKeywords', (self) => { _materializeSchema(self); return self._usesKeywords; }],
+  ['_schemaIsCallers', (self) => { _materializeSchema(self); return self._schemaIsCallers; }],
+]) {
+  Object.defineProperty(Validator.prototype, name, {
+    configurable: true,
+    get() { return pick(this); },
+    set(v) { Object.defineProperty(this, name, { value: v, writable: true, configurable: true, enumerable: true }); },
+  });
+}
+
 _defineLazyMethod('validate', (self) => (data) => {
   self._ensureCompiled();
   return self.validate(data);

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.17.0",
+  "version": "1.17.2",
   "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",
@@ -51,7 +51,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_buffer_reject_cost.js && node tests/test_nan_verdict.js && node tests/test_remove_additional_nested.js && node tests/test_aot_parse.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_formats_single_pass.js && node tests/test_format_single_error.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_hybrid_agreement.js && node tests/test_codegen_edge_shapes.js && node tests/test_ajv_errors.js && node tests/test_custom_keywords.js && node tests/test_ajv_parity.js && node tests/test_user_format_error_path.js && node tests/test_unevaluated_error_path.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_error_order_ordinal.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_lazy_instance.js && node tests/test_cyclic_input.js && node tests/test_native_error_codes.js && node tests/test_verdict_preprocess.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_additive_fields.js && node tests/test_diagnostic_source.js && node tests/test_diagnose.js && node tests/test_correlate.js && node tests/test_diagnostics_score.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_buffer_reject_cost.js && node tests/test_nan_verdict.js && node tests/test_remove_additional_nested.js && node tests/test_aot_parse.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_formats_single_pass.js && node tests/test_format_single_error.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_hybrid_agreement.js && node tests/test_codegen_edge_shapes.js && node tests/test_ajv_errors.js && node tests/test_custom_keywords.js && node tests/test_ajv_parity.js && node tests/test_user_format_error_path.js && node tests/test_unevaluated_error_path.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_error_order_ordinal.js && node tests/test_rejection_shape.js && node tests/test_lazy_normalization.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_lazy_instance.js && node tests/test_cyclic_input.js && node tests/test_native_error_codes.js && node tests/test_verdict_preprocess.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_additive_fields.js && node tests/test_diagnostic_source.js && node tests/test_diagnose.js && node tests/test_correlate.js && node tests/test_diagnostics_score.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",
@@ -122,13 +122,13 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.17.0",
-    "@ata-validator/native-darwin-x64": "1.17.0",
-    "@ata-validator/native-linux-arm64-gnu": "1.17.0",
-    "@ata-validator/native-linux-arm64-musl": "1.17.0",
-    "@ata-validator/native-linux-x64-gnu": "1.17.0",
-    "@ata-validator/native-linux-x64-musl": "1.17.0",
-    "@ata-validator/native-win32-x64": "1.17.0"
+    "@ata-validator/native-darwin-arm64": "1.17.2",
+    "@ata-validator/native-darwin-x64": "1.17.2",
+    "@ata-validator/native-linux-arm64-gnu": "1.17.2",
+    "@ata-validator/native-linux-arm64-musl": "1.17.2",
+    "@ata-validator/native-linux-x64-gnu": "1.17.2",
+    "@ata-validator/native-linux-x64-musl": "1.17.2",
+    "@ata-validator/native-win32-x64": "1.17.2"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"