ata-validator 0.17.4 → 0.18.0

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.
 
+## 0.18.0 - 2026-05-25
+
+### Added
+
+- `Infer<S>` resolves the shapes 0.17.0 left as `unknown`. `anyOf` and `oneOf` map to unions, `allOf` to an intersection, `prefixItems` to a tuple, and a `$ref` to a local `#/$defs/...` or `#/definitions/...` entry resolves to the referenced type, including recursive references. An external or otherwise unresolvable `$ref` still resolves to `unknown` rather than erroring. `new Validator(schema)` carries the wider inference, so handlers narrow `result.data` for these schemas with no manual annotation, and the same applies to the Fastify type provider that builds on `Infer`. Pure `.d.ts` change, no runtime impact.
+
+## 0.17.5 - 2026-05-25
+
+### Fixed
+
+- Compiled validators resolve draft-07 plain-name anchors. A `$defs`/`definitions` entry that declares an anchor with `$id: "#name"` and is referenced by `$ref: "#name"` now compiles through the codegen on every path (boolean, error, combined) instead of bailing. The bail forced a fallback that could not resolve sibling cross-schema refs, which surfaced as `cannot resolve $ref`. This is how shared schemas are referenced under Fastify.
+
 ## 0.17.4 - 2026-05-25
 
 ### Fixed

package/README.md

@@ -180,6 +180,36 @@ const v = new Validator(userSchema)
 
 The exported `JSONSchema` type is also available directly if you want to annotate a schema yourself. Custom and vendor keywords are allowed, so exotic schemas still type-check. Requires TypeScript >= 5.0.
 
+#### Extracting the type: `Infer`
+
+Because `defineSchema` leaves the schema as a plain object, you can pull a TypeScript type straight out of it with `Infer`, with no second type declaration to keep in sync.
+
+```ts
+import { defineSchema, type Infer } from 'ata-validator'
+
+const event = defineSchema({
+  $defs: {
+    Point: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, required: ['x', 'y'] },
+  },
+  type: 'object',
+  properties: {
+    kind: { enum: ['click', 'scroll'] },
+    at: { $ref: '#/$defs/Point' },
+    path: { type: 'array', prefixItems: [{ type: 'string' }, { type: 'integer' }] },
+  },
+  required: ['kind', 'at'],
+})
+
+type Event = Infer<typeof event>
+// {
+//   kind: 'click' | 'scroll'
+//   at: { x: number; y: number }
+//   path?: [string, number]
+// }
+```
+
+`Infer` resolves `const`/`enum` to literals, `anyOf`/`oneOf` to unions, `allOf` to intersections, `prefixItems` to tuples, and local `$ref` into `#/$defs` or `#/definitions`, including recursive references. `new Validator(schema)` carries the same type, so a successful `validate` narrows `result.data` without a manual annotation. An external or unresolvable `$ref` resolves to `unknown` rather than erroring.
+
 ### Cross-Schema `$ref`
 
 ```javascript

package/index.d.ts

@@ -177,26 +177,55 @@ type RequiredKeys<S> = S extends { required: infer R }
     : never
   : never;
 
+/** Collapse a union of types into their intersection (used for `allOf`). */
+type UnionToIntersection<U> =
+  (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+
+/** The root `$defs`/`definitions` map, threaded through inference for `$ref` resolution. */
+type RootDefs<S> = S extends { $defs: infer D }
+  ? D
+  : S extends { definitions: infer D }
+    ? D
+    : {};
+
+/** Extract the definition name from a local `#/$defs/...` or `#/definitions/...` pointer. */
+type RefName<R> = R extends `#/$defs/${infer N}`
+  ? N
+  : R extends `#/definitions/${infer N}`
+    ? N
+    : never;
+
+/** Resolve a `$ref` against the root defs map; external/unresolvable refs -> unknown. */
+type ResolveRef<R, D> = [RefName<R>] extends [never]
+  ? unknown
+  : RefName<R> extends keyof D
+    ? InferWith<D[RefName<R>], D>
+    : unknown;
+
 /** Object shape: required keys are required, all other declared keys optional. */
-type InferObject<S> = S extends { properties: infer P }
+type InferObject<S, D> = S extends { properties: infer P }
   ? Simplify<
-      { [K in keyof P as K extends RequiredKeys<S> ? K : never]: Infer<P[K]> } &
-      { [K in keyof P as K extends RequiredKeys<S> ? never : K]?: Infer<P[K]> }
+      { [K in keyof P as K extends RequiredKeys<S> ? K : never]: InferWith<P[K], D> } &
+      { [K in keyof P as K extends RequiredKeys<S> ? never : K]?: InferWith<P[K], D> }
     >
   : Record<string, unknown>;
 
-/** Array shape: `items` as a single schema maps to an element type; tuple/absent -> unknown[]. */
-type InferArray<S> = S extends { items: infer I }
-  ? I extends ReadonlyArray<unknown>
-    ? unknown[]
-    : Infer<I>[]
-  : unknown[];
+/** Array shape: `prefixItems` -> tuple; `items` (single schema) -> element type; otherwise unknown[]. */
+type InferArray<S, D> = S extends { prefixItems: infer P }
+  ? P extends ReadonlyArray<unknown>
+    ? { -readonly [K in keyof P]: InferWith<P[K], D> }
+    : unknown[]
+  : S extends { items: infer I }
+    ? I extends ReadonlyArray<unknown>
+      ? unknown[]
+      : InferWith<I, D>[]
+    : unknown[];
 
 /** Map a single JSON Schema type name (+ its schema) to a TS type. */
-type InferByTypeName<N, S> = N extends 'object'
-  ? InferObject<S>
+type InferByTypeName<N, S, D> = N extends 'object'
+  ? InferObject<S, D>
   : N extends 'array'
-    ? InferArray<S>
+    ? InferArray<S, D>
     : N extends 'string'
       ? string
       : N extends 'number'
@@ -209,28 +238,46 @@ type InferByTypeName<N, S> = N extends 'object'
               ? null
               : unknown;
 
+/** Core inference with the root defs map `D` threaded for `$ref` resolution. */
+type InferWith<S, D> = S extends { $ref: infer R }
+  ? ResolveRef<R, D>
+  : S extends { const: infer C }
+    ? C
+    : S extends { enum: infer E }
+      ? E extends ReadonlyArray<infer U>
+        ? U
+        : unknown
+      : S extends { allOf: infer A }
+        ? A extends ReadonlyArray<unknown>
+          ? Simplify<UnionToIntersection<{ [K in keyof A]: InferWith<A[K], D> }[number]>>
+          : unknown
+        : S extends { anyOf: infer A }
+          ? A extends ReadonlyArray<unknown>
+            ? { [K in keyof A]: InferWith<A[K], D> }[number]
+            : unknown
+          : S extends { oneOf: infer A }
+            ? A extends ReadonlyArray<unknown>
+              ? { [K in keyof A]: InferWith<A[K], D> }[number]
+              : unknown
+            : S extends { type: infer T }
+              ? T extends ReadonlyArray<infer N>
+                ? InferByTypeName<N, S, D>
+                : InferByTypeName<T, S, D>
+              : unknown;
+
 /**
- * Infer the TypeScript data type a JSON Schema literal describes (Core scope).
+ * Infer the TypeScript data type a JSON Schema literal describes.
  *
  * Handles: primitives, `type` arrays (union), `const`, `enum`, objects
- * (`properties` + `required` -> required/optional keys), and arrays
- * (`items` as a single schema). `$ref`/`$defs`, tuples, and `anyOf`/`oneOf`/
- * `allOf` are not yet inferred and resolve to `unknown` rather than erroring.
+ * (`properties` + `required` -> required/optional keys), arrays (`items`),
+ * tuples (`prefixItems`), `anyOf`/`oneOf` (union), `allOf` (intersection),
+ * and `$ref` to local `#/$defs/...` or `#/definitions/...`. External or
+ * unresolvable `$ref` resolves to `unknown` rather than erroring.
  *
  * Pair with {@link defineSchema}:
  * `const s = defineSchema({...}); type T = Infer<typeof s>;`
  */
-export type Infer<S> = S extends { const: infer C }
-  ? C
-  : S extends { enum: infer E }
-    ? E extends ReadonlyArray<infer U>
-      ? U
-      : unknown
-    : S extends { type: infer T }
-      ? T extends ReadonlyArray<infer N>
-        ? InferByTypeName<N, S>
-        : InferByTypeName<T, S>
-      : unknown;
+export type Infer<S> = InferWith<S, RootDefs<S>>;
 
 export type ValidationResult<T = unknown> =
   | { valid: true;  data: T;       errors: ValidationError[] }

package/lib/js-compiler.js

@@ -699,23 +699,6 @@ function canResolveDynamicRefs(target, callingSchema, schemaMap) {
 
 // Recursively check if a schema can be safely compiled to JS codegen.
 // Returns false if any sub-schema contains features codegen gets wrong.
-// Does the schema (recursively) contain an anchor-style `$ref` equal to anchorId
-// (e.g. `$ref: '#address'`)? Used to keep codegen away from anchor refs it can't
-// resolve in the combined/error paths.
-function schemaHasAnchorRef(node, anchorId) {
-  if (!node || typeof node !== 'object') return false
-  if (Array.isArray(node)) {
-    for (const x of node) if (schemaHasAnchorRef(x, anchorId)) return true
-    return false
-  }
-  if (node.$ref === anchorId) return true
-  for (const k in node) {
-    if (k === '$ref') continue
-    if (schemaHasAnchorRef(node[k], anchorId)) return true
-  }
-  return false
-}
-
 function codegenSafe(schema, schemaMap) {
   if (typeof schema === 'boolean') return true
   if (typeof schema !== 'object' || schema === null) return true
@@ -826,14 +809,10 @@ function codegenSafe(schema, schemaMap) {
       if (typeof def === 'boolean') return false
       if (typeof def === 'object' && def !== null) {
         // A non-fragment $id (e.g. 'sub.json', 'http://...') opens a new base URI
-        // scope — bail. A fragment-only $id ('#name') is a draft-07 anchor; it is
-        // safe to codegen when reached by JSON pointer (#/definitions/name), but the
-        // combined/error codegen paths do not resolve anchor refs (`$ref: '#name'`)
-        // to it, so bail if the schema anchor-references this def.
-        if (def.$id) {
-          if (!def.$id.startsWith('#')) return false
-          if (schemaHasAnchorRef(schema, def.$id)) return false
-        }
+        // scope — bail. A fragment-only $id ('#name') is a draft-07 anchor; the
+        // codegen anchor maps register it (see "Build anchors map"), so anchor
+        // refs (`$ref: '#name'`) resolve to it on all paths.
+        if (def.$id && !def.$id.startsWith('#')) return false
         if (def.$ref) return false // nested ref chain — bail
         if (!codegenSafe(def, schemaMap)) return false
       }
@@ -933,12 +912,15 @@ function compileToJSCodegen(schema, schemaMap, userFormats) {
   // Root schema's own $dynamicAnchor / $anchor
   if (schema.$dynamicAnchor) anchors['#' + schema.$dynamicAnchor] = schema
   if (schema.$anchor) anchors['#' + schema.$anchor] = schema
+  // Draft-07 plain-name anchor: declared as `$id: "#name"`.
+  if (typeof schema.$id === 'string' && schema.$id.startsWith('#')) anchors[schema.$id] = schema
   // Anchors from $defs
   if (rootDefs) {
     for (const def of Object.values(rootDefs)) {
       if (def && typeof def === 'object') {
         if (def.$dynamicAnchor) anchors['#' + def.$dynamicAnchor] = def
         if (def.$anchor) anchors['#' + def.$anchor] = def
+        if (typeof def.$id === 'string' && def.$id.startsWith('#')) anchors[def.$id] = def
       }
     }
   }
@@ -948,6 +930,7 @@ function compileToJSCodegen(schema, schemaMap, userFormats) {
       if (ext && typeof ext === 'object') {
         if (ext.$dynamicAnchor && !anchors['#' + ext.$dynamicAnchor]) anchors['#' + ext.$dynamicAnchor] = ext
         if (ext.$anchor && !anchors['#' + ext.$anchor]) anchors['#' + ext.$anchor] = ext
+        if (typeof ext.$id === 'string' && ext.$id.startsWith('#') && !anchors[ext.$id]) anchors[ext.$id] = ext
       }
     }
   }
@@ -2592,11 +2575,13 @@ function compileToJSCodegenWithErrors(schema, schemaMap, userFormats, sourceOpts
   const eAnchors = {}
   if (schema.$dynamicAnchor) eAnchors['#' + schema.$dynamicAnchor] = schema
   if (schema.$anchor) eAnchors['#' + schema.$anchor] = schema
+  if (typeof schema.$id === 'string' && schema.$id.startsWith('#')) eAnchors[schema.$id] = schema
   if (eRootDefs) {
     for (const def of Object.values(eRootDefs)) {
       if (def && typeof def === 'object') {
         if (def.$dynamicAnchor) eAnchors['#' + def.$dynamicAnchor] = def
         if (def.$anchor) eAnchors['#' + def.$anchor] = def
+        if (typeof def.$id === 'string' && def.$id.startsWith('#')) eAnchors[def.$id] = def
       }
     }
   }
@@ -2605,6 +2590,7 @@ function compileToJSCodegenWithErrors(schema, schemaMap, userFormats, sourceOpts
       if (ext && typeof ext === 'object') {
         if (ext.$dynamicAnchor && !eAnchors['#' + ext.$dynamicAnchor]) eAnchors['#' + ext.$dynamicAnchor] = ext
         if (ext.$anchor && !eAnchors['#' + ext.$anchor]) eAnchors['#' + ext.$anchor] = ext
+        if (typeof ext.$id === 'string' && ext.$id.startsWith('#') && !eAnchors[ext.$id]) eAnchors[ext.$id] = ext
       }
     }
   }
@@ -3210,11 +3196,13 @@ function compileToJSCombined(schema, VALID_RESULT, schemaMap, userFormats) {
   const cAnchors = {}
   if (schema.$dynamicAnchor) cAnchors['#' + schema.$dynamicAnchor] = schema
   if (schema.$anchor) cAnchors['#' + schema.$anchor] = schema
+  if (typeof schema.$id === 'string' && schema.$id.startsWith('#')) cAnchors[schema.$id] = schema
   if (cRootDefs) {
     for (const def of Object.values(cRootDefs)) {
       if (def && typeof def === 'object') {
         if (def.$dynamicAnchor) cAnchors['#' + def.$dynamicAnchor] = def
         if (def.$anchor) cAnchors['#' + def.$anchor] = def
+        if (typeof def.$id === 'string' && def.$id.startsWith('#')) cAnchors[def.$id] = def
       }
     }
   }
@@ -3223,6 +3211,7 @@ function compileToJSCombined(schema, VALID_RESULT, schemaMap, userFormats) {
       if (ext && typeof ext === 'object') {
         if (ext.$dynamicAnchor && !cAnchors['#' + ext.$dynamicAnchor]) cAnchors['#' + ext.$dynamicAnchor] = ext
         if (ext.$anchor && !cAnchors['#' + ext.$anchor]) cAnchors['#' + ext.$anchor] = ext
+        if (typeof ext.$id === 'string' && ext.$id.startsWith('#') && !cAnchors[ext.$id]) cAnchors[ext.$id] = ext
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "0.17.4",
+  "version": "0.18.0",
   "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",
@@ -42,7 +42,7 @@
     "rebuild": "cmake-js rebuild --target ata",
     "prebuild": "pkg-prebuilds-copy --baseDir build/Release --source ata.node --name=ata --strip --napi_version=10",
     "prebuild-all": "npm run prebuild -- --arch x64 && npm run prebuild -- --arch arm64",
-    "test": "node test.js && node tests/test_no_native.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_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.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_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_no_native.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_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.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_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",
     "test:compat": "node tests/test_compat.js",