ata-validator 1.6.1 → 1.6.2

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 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.6.2 - 2026-08-19
+
+### Fixed
+
+- The Standard Schema surface carried no output type. `~standard.validate()` returned `{ value: unknown }` and the `types` carrier the specification defines for inference was missing, so every consumer that reads the validated type off `~standard` (Fastify, tRPC, TanStack Form, Drizzle) saw `unknown` and needed a cast. `~standard` is now typed against the validator's own data type, and `types.output` carries it. Type-only: the runtime object is unchanged, and the specification defines `types` as never present at runtime.
+- Boolean schemas were rejected by the `Validator` constructor's TypeScript signature. `true` and `false` are schemas anywhere JSON Schema allows one, and both have always worked at runtime; only the types disagreed, which made a schema of unknown shape (`object | boolean`) impossible to pass without a cast. Nested boolean subschemas are still typed as objects, so `{ properties: { a: true } }` needs `defineSchema` or a cast.
+- The `t` builder's option bags rejected vendor keywords. `t.object({}, { instanceof: 'Date' })` is what a custom keyword package expects to be given, and the option types only allowed the keywords the builder itself emits, so callers wrote `as never`. Every option bag now accepts unknown keywords alongside the typed ones.
+- `tests/test_interop_types.ts` covers all three under `tsc --noEmit`.
+
 ## 1.6.1 - 2026-08-09
 
 ### Fixed

package/README.md

@@ -43,15 +43,29 @@ The `.compiled.mjs` modules are self-contained: zero runtime dependency on ata-v
 
 | Dimension | Schema | ata-AOT | AJV-runtime | Difference |
 |---|---|---|---|---|
-| Bundle (gzipped) | simple | 955 B | 52.7 KB | 56x smaller |
-| Bundle (gzipped) | complex | 1.6 KB | 52.7 KB | 32x smaller |
-| Cold start | simple | 21 ms | 38 ms | 1.8x faster |
-| Throughput (10M ops) | simple | 345 Mops/s | 116 Mops/s | 3.0x faster |
-| Compile time | simple | 6 µs | 1.5 ms | 246x faster |
-
-Reproduce on your machine with `npm run bench:aot-vs-ajv`. Numbers measured on Apple M4 Pro, Node 25.2.1.
-
-The wins are largest on bundle size and compile time because AOT moves work from runtime to build time. Throughput and cold start are also faster because the compiled validator is a tight straight-line function with no schema-walk overhead.
+| Bundle (gzipped) | simple | 1.0 KB | 52.7 KB | 50.5x smaller |
+| Bundle (gzipped) | complex | 4.8 KB | 52.7 KB | 11.0x smaller |
+| Bundle (gzipped) | nested | 2.3 KB | 52.7 KB | 23.1x smaller |
+| Cold start | simple | 21 ms | 40 ms | 1.9x faster |
+| Throughput (1M ops) | simple | 258 Mops/s | 102 Mops/s | 2.5x faster |
+| Compile time | simple | 8 µs | 1.61 ms | 191x faster |
+
+Reproduce on your machine with `npm run bench:aot-vs-ajv`. Numbers from one run on Apple
+M4 Pro, Node 25.2.1, 2026-08-13. Across three runs throughput moved between 258 and 278
+Mops/s and the compile ratio between 150x and 199x, so treat the last two rows as an order
+of magnitude rather than a constant.
+
+The wins are largest on bundle size and compile time because AOT moves work from runtime to
+build time. Throughput and cold start are also faster because the compiled validator is a
+tight straight-line function with no schema-walk overhead.
+
+What the table does not cover is data that fails. It measures compiled modules on input that
+passes, and a rejection costs more than a verdict: ata builds an error carrying a code, the
+offending value, a documentation link and a suggestion. On a five-field object schema a
+passing payload costs about 17 ns and a rejected one about 155 ns. `abortEarly: true` or
+`isValidObject()` skips that work when only the verdict matters. Schemas ata declines to
+compile, mostly cross-document `$ref`, `$dynamicRef` and `unevaluated*`, run on the
+interpreted engine and are slower again.
 
 ## Error messages
 
@@ -385,7 +399,10 @@ const { toStandaloneModule } = require('ata-validator/build');
 fs.writeFileSync('./user.validator.mjs', toStandaloneModule(schema, { format: 'esm' }));
 ```
 
-**Fastify startup (10 routes cold): ajv 12.6ms → ata 0.5ms (24x faster boot, no build step required)**
+**Fastify startup, 10 route schemas, from a cold process to the first validated request:
+ajv 19.6 ms, ata 3.1 ms, no build step required.** ata registers in 1.1 ms of that and
+compiles on the first request, so counting only registration would overstate the gap.
+Reproduce with `node benchmark/bench_fastify_boot.mjs`.
 
 ### Standard Schema V1
 

package/index.d.ts

@@ -364,13 +364,13 @@ export interface BundleStandaloneOptions extends ValidatorOptions {
   format?: 'esm' | 'cjs';
 }
 
-export interface StandardSchemaV1Props {
+export interface StandardSchemaV1Props<Output = unknown, Input = unknown> {
   version: 1;
   vendor: "ata-validator";
   validate(
     value: unknown
   ):
-    | { value: unknown }
+    | { value: Output }
     | {
         issues: Array<{
           message: string;
@@ -378,6 +378,11 @@ export interface StandardSchemaV1Props {
           path?: ReadonlyArray<{ key: PropertyKey }>;
         }>;
       };
+  /**
+   * Type-only carrier the Standard Schema spec uses for inference: consumers
+   * read the validated type off `types.output`. Never present at runtime.
+   */
+  readonly types?: { readonly input: Input; readonly output: Output } | undefined;
 }
 
 export interface StandaloneModule {
@@ -425,7 +430,7 @@ export interface Validator<T = unknown> {
   isValidNDJSON(ndjsonBuffer: Buffer): boolean[];
 
   /** Standard Schema V1 interface, compatible with Fastify, tRPC, TanStack, etc. */
-  readonly "~standard": StandardSchemaV1Props;
+  readonly "~standard": StandardSchemaV1Props<T>;
 }
 
 /** Constructor + statics for {@link Validator}. */
@@ -433,7 +438,7 @@ export interface ValidatorConstructor {
   /** Construct from a JSON Schema literal; the validated data type is inferred. */
   new <const S extends JSONSchema>(schema: S, options?: ValidatorOptions): Validator<Infer<S>>;
   /** Construct from a plain object/string schema, or with an explicit data type. */
-  new <T = unknown>(schema: object | string, options?: ValidatorOptions): Validator<T>;
+  new <T = unknown>(schema: object | string | boolean, options?: ValidatorOptions): Validator<T>;
 
   /** Load a pre-compiled standalone module. Zero schema compilation at startup. */
   fromStandalone<T = unknown>(mod: StandaloneModule, schema: object | string, options?: ValidatorOptions): Validator<T>;

package/lib/enrich-error.js

@@ -46,14 +46,24 @@ function expectedFor (err) {
 
 function pickReceived (err, data) {
   if (!data && data !== 0 && data !== false) return undefined;
-  // Walk JSON pointer to extract the actual offending value
+  // Walk JSON pointer to extract the actual offending value. This runs for
+  // every error on every rejected payload, so the walk reads segments straight
+  // out of the pointer: no leading-slash regex, no parts array, and no unescape
+  // pass on the segments that carry no `~`.
   const p = err.instancePath || err.path || '';
   if (!p) return reprValue(data);
-  const parts = p.replace(/^\//, '').split('/').map(s => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+  const len = p.length;
   let cur = data;
-  for (const part of parts) {
+  let i = p.charCodeAt(0) === 47 ? 1 : 0; // 47 is '/'
+  for (;;) {
+    let j = p.indexOf('/', i);
+    if (j === -1) j = len;
+    let seg = p.slice(i, j);
+    if (seg.indexOf('~') !== -1) seg = seg.replace(/~1/g, '/').replace(/~0/g, '~');
     if (cur == null) return undefined;
-    cur = cur[part];
+    cur = cur[seg];
+    if (j === len) break;
+    i = j + 1;
   }
   return reprValue(cur);
 }

package/lib/error-codes.js

@@ -77,20 +77,27 @@ function all () {
   return Object.keys(CODES).sort();
 }
 
+// Reverse lookups, built once. codeFor runs per error on every failing
+// validation, so walking the table there showed up as most of the cost of
+// enriching a rejected payload. Insertion follows sorted code order, so the
+// first writer wins and each keyword keeps the lowest code that carries it.
+const BY_KEYWORD = new Map();
+const BY_FORMAT = new Map();
+for (const c of Object.keys(CODES).sort()) {
+  const meta = CODES[c];
+  if (!BY_KEYWORD.has(meta.keyword)) BY_KEYWORD.set(meta.keyword, c);
+  if (meta.keyword === 'format' && meta.format && !BY_FORMAT.has(meta.format)) BY_FORMAT.set(meta.format, c);
+}
+
 // Map a (keyword, optional format) tuple back to a code. Used by the codegen
 // integration to attach codes to existing error sites without rewriting them all.
 function codeFor (keyword, format) {
   if (keyword === 'format' && format) {
-    for (const c of all()) {
-      const meta = CODES[c];
-      if (meta.keyword === 'format' && meta.format === format) return c;
-    }
-    return 'ATA3099';
-  }
-  for (const c of all()) {
-    if (CODES[c].keyword === keyword) return c;
+    const hit = BY_FORMAT.get(format);
+    return hit === undefined ? 'ATA3099' : hit;
   }
-  return null;
+  const hit = BY_KEYWORD.get(keyword);
+  return hit === undefined ? null : hit;
 }
 
 module.exports = { CODES, get, all, codeFor };

package/lib/js-compiler.js

@@ -845,6 +845,16 @@ function codegenSafe(schema, schemaMap) {
     if (typeof schema.unevaluatedProperties === 'object' && schema.unevaluatedProperties !== null) {
       if (!codegenSafe(schema.unevaluatedProperties, schemaMap)) return false
     }
+    // When evaluation is both dynamic (branch-dependent) and some branch
+    // unconditionally evaluates all properties, static tracking cannot
+    // correctly determine which properties are unevaluated at runtime.
+    // For example, a oneOf whose branches include both patternProperties
+    // and unevaluatedProperties:true requires annotation-aware evaluation
+    // that only the interpreted engine provides.
+    if (schema.unevaluatedProperties === false || (typeof schema.unevaluatedProperties === 'object' && schema.unevaluatedProperties !== null)) {
+      const evalResult = collectEvaluated(schema, schemaMap)
+      if (evalResult.dynamic && evalResult.allProps) return false
+    }
   }
   // unevaluatedItems: allow boolean and schema values
   if (schema.unevaluatedItems !== undefined) {
@@ -861,15 +871,52 @@ function codegenSafe(schema, schemaMap) {
   const defs = schema.$defs || schema.definitions
   if (defs) {
     const defNames = new Set(Object.keys(defs))
-    // Detect cyclic local refs: if any def's own body references back to a sibling
-    // def, the schema contains a cycle. The JS codegen returns (() => true) on cycle
-    // (permissive), so cyclic schemas must route to the interpreted engine instead.
-    // We check only the def bodies, not the top-level schema, so that a plain
-    // { $ref: '#/$defs/Name', $defs: { Name: { type: 'string' } } } (no cycle)
-    // still compiles.
-    const hasCycle = Object.values(defs).some(
-      (def) => typeof def === 'object' && def !== null && subtreeRefersToLocalDef(def, defNames)
-    )
+    // Detect cyclic local refs: build a directed graph of def->def references and
+    // check for cycles using DFS. A plain cross-reference (A -> B where B doesn't
+    // refer back to A) is fine; only true cycles (A -> B -> A) must be rejected.
+    // The JS codegen returns (() => true) on cycle (permissive), so cyclic schemas
+    // must route to the interpreted engine instead.
+    const defRefs = {}
+    for (const [name, def] of Object.entries(defs)) {
+      defRefs[name] = []
+      if (typeof def === 'object' && def !== null) {
+        const refs = []
+        const seen = new WeakSet()
+        const collectRefs = (node) => {
+          if (typeof node !== 'object' || node === null) return
+          if (seen.has(node)) return
+          seen.add(node)
+          if (node.$ref) {
+            const m = /^#\/(?:\$defs|definitions)\/([^/]+)$/.exec(node.$ref)
+            if (m && defNames.has(m[1])) refs.push(m[1])
+          }
+          for (const val of Object.values(node)) {
+            if (typeof val === 'object' && val !== null) {
+              if (Array.isArray(val)) { for (const item of val) collectRefs(item) }
+              else collectRefs(val)
+            }
+          }
+        }
+        collectRefs(def)
+        defRefs[name] = refs
+      }
+    }
+    const hasCycle = (() => {
+      const visited = new Set()
+      const inStack = new Set()
+      const dfs = (node) => {
+        if (inStack.has(node)) return true
+        if (visited.has(node)) return false
+        visited.add(node)
+        inStack.add(node)
+        for (const neighbor of (defRefs[node] || [])) {
+          if (dfs(neighbor)) return true
+        }
+        inStack.delete(node)
+        return false
+      }
+      return Object.keys(defRefs).some(dfs)
+    })()
     if (hasCycle) return false
     for (const [name, def] of Object.entries(defs)) {
       if (/[~/"']/.test(name)) return false // special chars in def name

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.6.1",
+  "version": "1.6.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",
@@ -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_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_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_additional_props_errors.js && node tests/test_id_anchor_refs.js && node tests/test_engine_routing.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_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_order.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_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_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_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_additional_props_errors.js && node tests/test_id_anchor_refs.js && node tests/test_engine_routing.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_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_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,12 +112,12 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.6.1",
-    "@ata-validator/native-linux-x64-gnu": "1.6.1",
-    "@ata-validator/native-linux-arm64-gnu": "1.6.1",
-    "@ata-validator/native-linux-x64-musl": "1.6.1",
-    "@ata-validator/native-linux-arm64-musl": "1.6.1",
-    "@ata-validator/native-win32-x64": "1.6.1"
+    "@ata-validator/native-darwin-arm64": "1.6.2",
+    "@ata-validator/native-linux-x64-gnu": "1.6.2",
+    "@ata-validator/native-linux-arm64-gnu": "1.6.2",
+    "@ata-validator/native-linux-x64-musl": "1.6.2",
+    "@ata-validator/native-linux-arm64-musl": "1.6.2",
+    "@ata-validator/native-win32-x64": "1.6.2"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"

package/t.d.ts

@@ -34,7 +34,18 @@ export type TOptional<S> = S & { readonly [OPTIONAL]: true };
 
 export type TSchema = JSONSchema;
 
-export interface StringOptions {
+/**
+ * Shared by every builder option bag. Annotations and vendor keywords (custom
+ * keywords outside the JSON Schema vocabulary) are carried through to the
+ * emitted schema, so the option types accept them.
+ */
+export interface CommonOptions {
+  description?: string;
+  title?: string;
+  [keyword: string]: unknown;
+}
+
+export interface StringOptions extends CommonOptions {
   minLength?: number;
   maxLength?: number;
   pattern?: string;
@@ -45,7 +56,7 @@ export interface StringOptions {
   examples?: readonly string[];
 }
 
-export interface NumericOptions {
+export interface NumericOptions extends CommonOptions {
   minimum?: number;
   maximum?: number;
   exclusiveMinimum?: number;
@@ -57,7 +68,7 @@ export interface NumericOptions {
   examples?: readonly number[];
 }
 
-export interface ArrayOptions {
+export interface ArrayOptions extends CommonOptions {
   minItems?: number;
   maxItems?: number;
   uniqueItems?: boolean;
@@ -65,13 +76,13 @@ export interface ArrayOptions {
   title?: string;
 }
 
-export interface ObjectOptions {
+export interface ObjectOptions extends CommonOptions {
   additionalProperties?: boolean | JSONSchema;
   description?: string;
   title?: string;
 }
 
-export interface RecordOptions {
+export interface RecordOptions extends CommonOptions {
   minProperties?: number;
   maxProperties?: number;
   description?: string;