ata-validator 0.11.1 → 0.12.1

package/README.md

@@ -1,8 +1,12 @@
+<p align="center">
+  <img src="./assets/ata-validator.svg" alt="ata-validator" width="640" />
+</p>
+
 # ata-validator
 
 Ultra-fast JSON Schema validator powered by [simdjson](https://github.com/simdjson/simdjson). Multi-core parallel validation, RE2 regex, codegen bytecode engine. Standard Schema V1 compatible.
 
-**[ata-validator.com](https://ata-validator.com)** | **[API Docs](docs/API.md)** | **[Migrate from ajv](docs/migration-from-ajv.md)** | **[Contributing](CONTRIBUTING.md)**
+**[ata-validator.com](https://ata-validator.com)** | **[API Docs](docs/API.md)** | **[Migrate from ajv](docs/migration-from-ajv.md)** | **[Framework integrations](docs/integrations/)** | **[Contributing](CONTRIBUTING.md)**
 
 ## Performance
 
@@ -10,26 +14,34 @@ Ultra-fast JSON Schema validator powered by [simdjson](https://github.com/simdjs
 
 | Scenario | ata | ajv | |
 |---|---|---|---|
-| **validate(obj)** valid | 22ns | 102ns | **ata 4.6x faster** |
-| **validate(obj)** invalid | 87ns | 182ns | **ata 2.1x faster** |
-| **isValidObject(obj)** | 21ns | 100ns | **ata 4.7x faster** |
-| **Schema compilation** | 453ns | 1.24ms | **ata 2,729x faster** |
-| **First validation** | 2.07μs | 1.11ms | **ata 534x faster** |
+| **validate(obj)** valid | 21ns | 108ns | **ata 5.1x faster** |
+| **validate(obj)** invalid | 86ns | 104ns | **ata 1.2x faster** |
+| **isValidObject(obj)** | 20ns | 109ns | **ata 5.4x faster** |
+| **Schema instantiation** (lazy compile) | 8ns | 1.33ms | **ata 159,000x faster** |
+| **First validation** (compile + validate) | 28ns | 1.21ms | **ata 43,000x faster** |
+
+> **Honest read of the three rows above:**
+>
+> - **Hot loop** (millions of `validate(obj)` calls on a warm validator): ata is **~5× faster** than ajv. This is the steady-state advantage and what most apps care about most of the time.
+> - **Cold start** (construct + first validate, apples-to-apples vs `ajv.compile(schema) + validate(obj)`): ata is **~43,000× faster**. Matters for serverless cold starts, CLI tools, batch workers — anywhere you instantiate a schema and exercise it once or a few times.
+> - **Instantiation only** (`new Validator(schema)` with no validation yet): ata is **~159,000× faster**, but only because ata defers codegen to first use (lazy compile + a tier-0 interpreter for low-traffic schemas). The number is real but it is constructor cost vs ajv's full compile cost — not the same unit of work. Quote it carefully.
+>
+> The lazy compile architecture is also why an instantiated-but-never-validated schema is essentially free in ata, while in ajv it costs the full compile. That's the underlying real win, beyond the multiplier above.
 
 ### Complex Schema (patternProperties + dependentSchemas + propertyNames + additionalProperties)
 
 | Scenario | ata | ajv | |
 |---|---|---|---|
-| **validate(obj)** valid | 17ns | 115ns | **ata 6.8x faster** |
-| **validate(obj)** invalid | 59ns | 194ns | **ata 3.3x faster** |
-| **isValidObject(obj)** | 19ns | 124ns | **ata 6.6x faster** |
+| **validate(obj)** valid | 19ns | 116ns | **ata 6.1x faster** |
+| **validate(obj)** invalid | 62ns | 195ns | **ata 3.1x faster** |
+| **isValidObject(obj)** | 18ns | 122ns | **ata 6.8x faster** |
 
 ### Cross-Schema `$ref` (multi-schema with `$id` registry)
 
 | Scenario | ata | ajv | |
 |---|---|---|---|
-| **validate(obj)** valid | 17ns | 25ns | **ata 1.5x faster** |
-| **validate(obj)** invalid | 34ns | 54ns | **ata 1.6x faster** |
+| **validate(obj)** valid | 13ns | 25ns | **ata 2.0x faster** |
+| **validate(obj)** invalid | 28ns | 56ns | **ata 2.0x faster** |
 
 > Measured with [mitata](https://github.com/evanwashere/mitata) on Apple M4 Pro (process-isolated). [Benchmark code](benchmark/bench_complex_mitata.mjs)
 
@@ -37,14 +49,14 @@ Ultra-fast JSON Schema validator powered by [simdjson](https://github.com/simdjs
 
 | Scenario | ata | ajv | |
 |---|---|---|---|
-| **Tier 1** (properties only) valid | 3.3ns | 8.7ns | **ata 2.6x faster** |
-| **Tier 1** invalid | 3.7ns | 19.1ns | **ata 5.2x faster** |
-| **Tier 2** (allOf) valid | 3.3ns | 9.9ns | **ata 3.0x faster** |
-| **Tier 3** (anyOf) valid | 6.7ns | 23.2ns | **ata 3.5x faster** |
-| **Tier 3** invalid | 7.1ns | 42.4ns | **ata 6.0x faster** |
-| **unevaluatedItems** valid | 1.0ns | 5.5ns | **ata 5.4x faster** |
-| **unevaluatedItems** invalid | 0.96ns | 14.2ns | **ata 14.8x faster** |
-| **Compilation** | 375ns | 2.59ms | **ata 6,904x faster** |
+| **Tier 1** (properties only) valid | 3.3ns | 8.5ns | **ata 2.6x faster** |
+| **Tier 1** invalid | 3.6ns | 18.6ns | **ata 5.2x faster** |
+| **Tier 2** (allOf) valid | 3.3ns | 10.1ns | **ata 3.0x faster** |
+| **Tier 3** (anyOf) valid | 6.7ns | 22.9ns | **ata 3.4x faster** |
+| **Tier 3** invalid | 7.5ns | 41.8ns | **ata 5.6x faster** |
+| **unevaluatedItems** valid | 0.97ns | 5.4ns | **ata 5.6x faster** |
+| **unevaluatedItems** invalid | 0.99ns | 14.9ns | **ata 15.0x faster** |
+| **Compilation** | 8.8ns | 2.64ms | **ata 298,000x faster** |
 
 Three-tier hybrid codegen: static schemas compile to zero-overhead key checks, dynamic schemas (anyOf/oneOf) use bitmask tracking with V8-inlined branch functions. [Benchmark code](benchmark/bench_unevaluated_mitata.mjs)
 
@@ -52,20 +64,21 @@ Three-tier hybrid codegen: static schemas compile to zero-overhead key checks, d
 
 | Scenario | ata | ajv | typebox | zod | valibot |
 |---|---|---|---|---|---|
-| **validate (valid)** | **9ns** | 38ns | 50ns | 334ns | 326ns |
-| **validate (invalid)** | **37ns** | 103ns | 4ns | 11.8μs | 842ns |
-| **compilation** | **453ns** | 1.24ms | 52μs | — | — |
-| **first validation** | **2.1μs** | 1.11ms | 54μs | — | — |
+| **validate (valid)** | **7ns** | 38ns | 50ns | 342ns | 337ns |
+| **validate (invalid, all errors)** | **38ns** | 102ns | n/a | 11.9μs | 855ns |
+| **isValid (invalid, boolean)** | **0.93ns** | 16ns | 2.3ns | n/a | n/a |
+| **compilation** | **9ns** | 1.20ms | 53μs | n/a | n/a |
+| **first validation** | **16ns** | 1.16ms | 54μs | n/a | n/a |
 
-> Different categories: ata/ajv/typebox are JSON Schema validators, zod/valibot are schema-builder DSLs. [Benchmark code](benchmark/bench_all_mitata.mjs)
+> Different categories: ata/ajv/typebox are JSON Schema validators, zod/valibot are schema-builder DSLs. The two invalid-path rows compare different units of work — `validate(invalid, all errors)` walks the full schema and builds an errors array (apples-to-apples vs ajv `{allErrors: true}`), while `isValid(invalid, boolean)` returns false on the first failed check (apples-to-apples vs typebox `Check()` and ajv `{allErrors: false}`). Reading both rows together avoids the trap of comparing a full error walk against a first-fail boolean. [Benchmark code](benchmark/bench_all_mitata.mjs)
 
 ### Large Data - JS Object Validation
 
 | Size | ata | ajv | |
 |---|---|---|---|
-| 10 users (2KB) | 6.2M ops/sec | 2.5M ops/sec | **ata 2.5x faster** |
-| 100 users (20KB) | 658K ops/sec | 243K ops/sec | **ata 2.7x faster** |
-| 1,000 users (205KB) | 64K ops/sec | 23.5K ops/sec | **ata 2.7x faster** |
+| 10 users (2KB) | 6.0M ops/sec | 2.4M ops/sec | **ata 2.5x faster** |
+| 100 users (20KB) | 621K ops/sec | 229K ops/sec | **ata 2.7x faster** |
+| 1,000 users (205KB) | 63K ops/sec | 22.5K ops/sec | **ata 2.8x faster** |
 
 ### Real-World Scenarios
 
@@ -93,10 +106,10 @@ Three-tier hybrid codegen: static schemas compile to zero-overhead key checks, d
 | Scenario | ata | ajv | |
 |---|---|---|---|
 | **$dynamicRef tree** valid | 22ns | 54ns | **ata 2.4x faster** |
-| **$dynamicRef tree** invalid | 70ns | 76ns | **ata 1.1x faster** |
-| **$dynamicRef override** valid | 2.6ns | 183ns | **ata 70x faster** |
-| **$dynamicRef override** invalid | 48ns | 185ns | **ata 3.8x faster** |
-| **$anchor array** valid | 2.3ns | 3.1ns | **ata 1.4x faster** |
+| **$dynamicRef tree** invalid | 71ns | 77ns | **ata 1.1x faster** |
+| **$dynamicRef override** valid | 2.6ns | 187ns | **ata 71x faster** |
+| **$dynamicRef override** invalid | 50ns | 189ns | **ata 3.8x faster** |
+| **$anchor array** valid | 2.2ns | 3.2ns | **ata 1.4x faster** |
 
 Self-recursive named functions for $dynamicRef, compile-time cross-schema resolution, zero-wrapper hybrid path. [Benchmark code](benchmark/bench_dynamicref_vs_ajv.mjs)
 
@@ -106,7 +119,7 @@ Self-recursive named functions for $dynamicRef, compile-time cross-schema resolu
 
 ## When to use ata
 
-- **High-throughput `validate(obj)`** - 3.1x faster than ajv, 38x faster than zod
+- **High-throughput `validate(obj)`** - 5.1x faster than ajv, 47x faster than zod
 - **Complex schemas** - `patternProperties`, `dependentSchemas`, `propertyNames`, `unevaluatedProperties` all inline JS codegen
 - **Multi-schema projects** - cross-schema `$ref` with `$id` registry, `addSchema()` API
 - **Draft 7 migration** - auto-detects `$schema`, normalizes Draft 7 keywords transparently
@@ -219,7 +232,7 @@ const v = new Validator(schema, {
 
 ### Build-time compile (`ata compile`)
 
-The `ata` CLI turns a JSON Schema file into a self-contained JavaScript module. No runtime dependency on `ata-validator`, so only the generated validator ships to the browser — typical output is ~1 KB gzipped compared to ~27 KB for the full runtime.
+The `ata` CLI turns a JSON Schema file into a self-contained JavaScript module. No runtime dependency on `ata-validator`, so only the generated validator ships to the browser. Typical output is ~1 KB gzipped compared to ~27 KB for the full runtime.
 
 ```bash
 npx ata compile schemas/user.json -o src/generated/user.validator.mjs
@@ -314,6 +327,24 @@ auto result = ata::validate(schema, R"({"name": "Mert"})");
 // result.valid == true
 ```
 
+## Framework integrations
+
+Copy-paste recipes for the common frameworks. Most need 10-20 lines of glue. See [docs/integrations](docs/integrations/) for the full set.
+
+| Framework | Pattern | Recipe |
+|---|---|---|
+| Fastify | dedicated plugin | [`fastify-ata`](https://github.com/ata-core/fastify-ata) |
+| Vite (build-time compile) | dedicated plugin | [`ata-vite`](https://github.com/ata-core/ata-vite) |
+| Hono | async middleware | [docs/integrations/hono.md](docs/integrations/hono.md) |
+| Elysia | direct handler check | [docs/integrations/elysia.md](docs/integrations/elysia.md) |
+| tRPC | Standard Schema V1 input | [docs/integrations/trpc.md](docs/integrations/trpc.md) |
+| TanStack Form | Standard Schema V1 validator | [docs/integrations/tanstack-form.md](docs/integrations/tanstack-form.md) |
+| Express | sync middleware | [docs/integrations/express.md](docs/integrations/express.md) |
+| Koa | async ctx middleware | [docs/integrations/koa.md](docs/integrations/koa.md) |
+| NestJS | validation pipe | [docs/integrations/nestjs.md](docs/integrations/nestjs.md) |
+| SvelteKit | form action, API route | [docs/integrations/sveltekit.md](docs/integrations/sveltekit.md) |
+| Astro | API route, server action | [docs/integrations/astro.md](docs/integrations/astro.md) |
+
 ## Supported Keywords
 
 | Category | Keywords |

package/lib/js-compiler.js

@@ -973,15 +973,27 @@ function tryGenCombined(schema, access, ctx) {
 
   if (t === 'string') {
     if (schema.pattern || schema.format) return null
-    // Both bounds set: hoist _cpLen once so ASCII strings are not scanned twice.
+    // s.length is an upper bound on cpLen and at least cpLen / 2 (worst case
+    // all-surrogate). Use s.length fast paths and only call _cpLen in the
+    // uncertain band; ASCII strings (>99% of real data) skip _cpLen entirely.
     if (schema.minLength !== undefined && schema.maxLength !== undefined) {
+      const M = schema.minLength
+      const X = schema.maxLength
       const v2 = isIdent ? access : '_v'
       const prelude = isIdent ? '' : `const _v=${access};`
-      return `{${prelude}if(typeof ${v2}!=='string')return false;const _lv=_cpLen(${v2});if(_lv<${schema.minLength}||_lv>${schema.maxLength})return false}`
+      return `{${prelude}if(typeof ${v2}!=='string')return false;const _lv=${v2}.length;if(_lv<${M}||_lv>${X * 2})return false;if(_lv<${M * 2}||_lv>${X}){const _cp=_cpLen(${v2});if(_cp<${M}||_cp>${X})return false}}`
     }
     const conds = [`typeof _v!=='string'`]
-    if (schema.minLength !== undefined) conds.push(`_cpLen(_v)<${schema.minLength}`)
-    if (schema.maxLength !== undefined) conds.push(`_cpLen(_v)>${schema.maxLength}`)
+    if (schema.minLength !== undefined) {
+      const M = schema.minLength
+      conds.push(`_v.length<${M}`)
+      conds.push(`_v.length<${M * 2}&&_cpLen(_v)<${M}`)
+    }
+    if (schema.maxLength !== undefined) {
+      const X = schema.maxLength
+      conds.push(`_v.length>${X * 2}`)
+      conds.push(`_v.length>${X}&&_cpLen(_v)>${X}`)
+    }
     if (conds.length < 2) return null
     return bind(conds)
   }
@@ -1235,20 +1247,32 @@ function genCode(schema, v, lines, ctx, knownType) {
   if (schema.exclusiveMaximum !== undefined) lines.push(isNum ? `if(${v}>=${schema.exclusiveMaximum})return false` : `if(typeof ${v}==='number'&&${v}>=${schema.exclusiveMaximum})return false`)
   if (schema.multipleOf !== undefined) lines.push(isNum ? `if(${v}%${schema.multipleOf}!==0)return false` : `if(typeof ${v}==='number'&&${v}%${schema.multipleOf}!==0)return false`)
 
-  // string — skip type guard if known string. When both bounds are set, call
-  // _cpLen once and compare the cached result so ASCII strings do not get
-  // scanned twice.
+  // string length — skip type guard if known string.
+  // s.length (UTF-16 code units) is an upper bound on cpLen, and at least cpLen
+  // (worst case all surrogate pairs gives s.length = 2 * cpLen). So:
+  //   length < M           → certain fail minLength
+  //   length > 2*X         → certain fail maxLength
+  //   2*M <= length <= X   → certain pass both
+  // Only call _cpLen in the uncertain band. ASCII strings (>99% of real data)
+  // never enter the band.
   if (schema.minLength !== undefined && schema.maxLength !== undefined) {
+    const M = schema.minLength
+    const X = schema.maxLength
     const li = ctx.varCounter++
     const lv = `_l${li}`
-    if (isStr) {
-      lines.push(`{const ${lv}=_cpLen(${v});if(${lv}<${schema.minLength}||${lv}>${schema.maxLength})return false}`)
-    } else {
-      lines.push(`if(typeof ${v}==='string'){const ${lv}=_cpLen(${v});if(${lv}<${schema.minLength}||${lv}>${schema.maxLength})return false}`)
-    }
+    const body = `{const ${lv}=${v}.length;if(${lv}<${M}||${lv}>${X * 2})return false;if(${lv}<${M * 2}||${lv}>${X}){const _cp=_cpLen(${v});if(_cp<${M}||_cp>${X})return false}}`
+    lines.push(isStr ? body : `if(typeof ${v}==='string')${body}`)
   } else {
-    if (schema.minLength !== undefined) lines.push(isStr ? `if(_cpLen(${v})<${schema.minLength})return false` : `if(typeof ${v}==='string'&&_cpLen(${v})<${schema.minLength})return false`)
-    if (schema.maxLength !== undefined) lines.push(isStr ? `if(_cpLen(${v})>${schema.maxLength})return false` : `if(typeof ${v}==='string'&&_cpLen(${v})>${schema.maxLength})return false`)
+    if (schema.minLength !== undefined) {
+      const M = schema.minLength
+      const body = `if(${v}.length<${M})return false;if(${v}.length<${M * 2}&&_cpLen(${v})<${M})return false`
+      lines.push(isStr ? body : `if(typeof ${v}==='string'){${body}}`)
+    }
+    if (schema.maxLength !== undefined) {
+      const X = schema.maxLength
+      const body = `if(${v}.length>${X * 2})return false;if(${v}.length>${X}&&_cpLen(${v})>${X})return false`
+      lines.push(isStr ? body : `if(typeof ${v}==='string'){${body}}`)
+    }
   }
 
   // array size — skip guard if known array
@@ -2199,9 +2223,20 @@ function compilePatternInline(pattern, varName) {
   // Match: ^[chars]{exact}$ — e.g., ^[0-9]{5}$
   let m = pattern.match(/^\^(\[[\w\-]+\])\{(\d+)\}\$$/)
   if (m) {
+    const len = parseInt(m[2])
+    // For small fixed-length patterns, fully unroll: avoids the per-call closure
+    // allocation of the IIFE form. Cap at 16 chars to keep emitted code small.
+    if (len <= 16) {
+      const checks = []
+      for (let i = 0; i < len; i++) {
+        const ck = charClassToCheck(m[1], `${varName}.charCodeAt(${i})`)
+        if (!ck) return null
+        checks.push(ck)
+      }
+      return `${varName}.length===${len}&&${checks.join('&&')}`
+    }
     const rangeCheck = charClassToCheck(m[1], `${varName}.charCodeAt(_pi)`)
     if (!rangeCheck) return null
-    const len = parseInt(m[2])
     return `${varName}.length===${len}&&(()=>{for(let _pi=0;_pi<${len};_pi++){if(!(${rangeCheck}))return false}return true})()`
   }
   // Match: ^[chars]+$ — e.g., ^[a-z]+$
@@ -2539,14 +2574,21 @@ function genCodeE(schema, v, pathExpr, lines, ctx, schemaPrefix) {
     lines.push(`{const _r${ci}=typeof ${v}==='number'?${v}%${m}:NaN;if(typeof ${v}==='number'&&Math.abs(_r${ci})>1e-8&&Math.abs(_r${ci}-${m})>1e-8){${fail('multipleOf', 'multipleOf', `{multipleOf:${m}}`, `'must be multiple of ${m}'`)}}}`)
   }
 
-  // string
+  // string length — same s.length fast paths as the boolean codegen above.
+  // length < M → certain fail; length > 2*X → certain fail; sweet spot
+  // 2*M <= length <= X passes without scanning. Only call _cpLen in the
+  // uncertain band (caches it so it isn't called twice when both bounds are set).
   if (schema.minLength !== undefined) {
-    const c = isStr ? `_cpLen(${v})<${schema.minLength}` : `typeof ${v}==='string'&&_cpLen(${v})<${schema.minLength}`
-    lines.push(`if(${c}){${fail('minLength', 'minLength', `{limit:${schema.minLength}}`, `'must NOT have fewer than ${schema.minLength} characters'`)}}`)
+    const M = schema.minLength
+    const inner = `${v}.length<${M}||(${v}.length<${M * 2}&&_cpLen(${v})<${M})`
+    const c = isStr ? inner : `typeof ${v}==='string'&&(${inner})`
+    lines.push(`if(${c}){${fail('minLength', 'minLength', `{limit:${M}}`, `'must NOT have fewer than ${M} characters'`)}}`)
   }
   if (schema.maxLength !== undefined) {
-    const c = isStr ? `_cpLen(${v})>${schema.maxLength}` : `typeof ${v}==='string'&&_cpLen(${v})>${schema.maxLength}`
-    lines.push(`if(${c}){${fail('maxLength', 'maxLength', `{limit:${schema.maxLength}}`, `'must NOT have more than ${schema.maxLength} characters'`)}}`)
+    const X = schema.maxLength
+    const inner = `${v}.length>${X * 2}||(${v}.length>${X}&&_cpLen(${v})>${X})`
+    const c = isStr ? inner : `typeof ${v}==='string'&&(${inner})`
+    lines.push(`if(${c}){${fail('maxLength', 'maxLength', `{limit:${X}}`, `'must NOT have more than ${X} characters'`)}}`)
   }
   if (schema.pattern) {
     const inlineCheck = compilePatternInline(schema.pattern, v)
@@ -3081,9 +3123,19 @@ function genCodeC(schema, v, pathExpr, lines, ctx, schemaPrefix) {
     lines.push(`{const _r${ci}=typeof ${v}==='number'?${v}%${m}:NaN;if(typeof ${v}==='number'&&Math.abs(_r${ci})>1e-8&&Math.abs(_r${ci}-${m})>1e-8){${fail('multipleOf', 'multipleOf', `{multipleOf:${m}}`, `'must be multiple of ${m}'`)}}}`)
   }
 
-  // string — skip guard if known
-  if (schema.minLength !== undefined) { const c = isStr ? `_cpLen(${v})<${schema.minLength}` : `typeof ${v}==='string'&&_cpLen(${v})<${schema.minLength}`; lines.push(`if(${c}){${fail('minLength', 'minLength', `{limit:${schema.minLength}}`, `'must NOT have fewer than ${schema.minLength} characters'`)}}`) }
-  if (schema.maxLength !== undefined) { const c = isStr ? `_cpLen(${v})>${schema.maxLength}` : `typeof ${v}==='string'&&_cpLen(${v})>${schema.maxLength}`; lines.push(`if(${c}){${fail('maxLength', 'maxLength', `{limit:${schema.maxLength}}`, `'must NOT have more than ${schema.maxLength} characters'`)}}`) }
+  // string length — s.length fast paths, _cpLen only in the uncertain band.
+  if (schema.minLength !== undefined) {
+    const M = schema.minLength
+    const inner = `${v}.length<${M}||(${v}.length<${M * 2}&&_cpLen(${v})<${M})`
+    const c = isStr ? inner : `typeof ${v}==='string'&&(${inner})`
+    lines.push(`if(${c}){${fail('minLength', 'minLength', `{limit:${M}}`, `'must NOT have fewer than ${M} characters'`)}}`)
+  }
+  if (schema.maxLength !== undefined) {
+    const X = schema.maxLength
+    const inner = `${v}.length>${X * 2}||(${v}.length>${X}&&_cpLen(${v})>${X})`
+    const c = isStr ? inner : `typeof ${v}==='string'&&(${inner})`
+    lines.push(`if(${c}){${fail('maxLength', 'maxLength', `{limit:${X}}`, `'must NOT have more than ${X} characters'`)}}`)
+  }
   if (schema.pattern) {
     const inlineCheck = compilePatternInline(schema.pattern, v)
     if (inlineCheck) {

package/lib/ts-gen.js

@@ -56,6 +56,28 @@ function renderValueType(schema, defs, depth = 0) {
 
   if (t === 'array') {
     const items = schema.items;
+    const prefix = Array.isArray(schema.prefixItems) ? schema.prefixItems : null;
+
+    if (prefix) {
+      const prefixTypes = prefix.map((s) => renderValueType(s, defs, depth + 1));
+      const minItems = typeof schema.minItems === 'number' ? schema.minItems : 0;
+      // Elements before minItems are required; the remainder are optional
+      // because JSON Schema does not require prefixItems to be present.
+      const elements = prefixTypes.map((t, i) => (i < minItems ? t : `${t}?`));
+      if (items === false) {
+        return `[${elements.join(', ')}]`;
+      }
+      if (items === undefined || items === true) {
+        return `[${elements.join(', ')}, ...unknown[]]`;
+      }
+      if (typeof items === 'object' && items !== null) {
+        const rest = renderValueType(items, defs, depth + 1);
+        const restType = rest.includes(' | ') ? `(${rest})` : rest;
+        return `[${elements.join(', ')}, ...${restType}[]]`;
+      }
+    }
+
+    if (items === false) return 'never[]';
     if (items === undefined || items === true) return 'unknown[]';
     const inner = renderValueType(items, defs, depth + 1);
     return inner.includes(' | ') ? `Array<${inner}>` : `${inner}[]`;
@@ -84,15 +106,30 @@ function renderObject(schema, defs, depth) {
     const t = renderValueType(props[k], defs, depth + 1);
     const opt = required.has(k) ? '' : '?';
     const safeKey = /^[A-Za-z_$][\w$]*$/.test(k) ? k : JSON.stringify(k);
-    const desc = typeof props[k] === 'object' && props[k] && typeof props[k].description === 'string'
-      ? `  /** ${props[k].description.replace(/\*\//g, '* /')} */\n`
-      : '';
-    return `${desc}  ${safeKey}${opt}: ${t};`;
+    const doc = renderJsDoc(props[k], '  ');
+    return `${doc}  ${safeKey}${opt}: ${t};`;
   });
   // extra keys when additionalProperties is present as a schema or true
   const extra = schema.additionalProperties;
   if (extra && typeof extra === 'object') {
-    lines.push(`  [key: string]: ${renderValueType(extra, defs, depth + 1)};`);
+    // TypeScript requires the index signature to be a supertype of every
+    // named property's emitted type. Widen to a union covering each property
+    // type, plus undefined when any property is optional.
+    const widen = new Set();
+    widen.add(renderValueType(extra, defs, depth + 1));
+    let hasOptional = false;
+    for (const k of keys) {
+      widen.add(renderValueType(props[k], defs, depth + 1));
+      if (!required.has(k)) hasOptional = true;
+    }
+    if (hasOptional) widen.add('undefined');
+    const indexType = widen.has('unknown') ? 'unknown' : Array.from(widen).join(' | ');
+    lines.push(`  [key: string]: ${indexType};`);
+  } else if (extra !== false) {
+    // JSON Schema accepts extra keys by default. Emit a permissive index
+    // signature so tsc does not reject excess properties that the runtime
+    // would consider valid.
+    lines.push(`  [key: string]: unknown;`);
   }
   return `{\n${lines.join('\n')}\n}`;
 }
@@ -106,10 +143,54 @@ function renderLiteral(v) {
 
 function toTypeName(name) {
   const cleaned = String(name).replace(/[^A-Za-z0-9_]/g, '_');
+  if (cleaned === '') return '_Anon';
   if (/^[0-9]/.test(cleaned)) return `_${cleaned}`;
   return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
 }
 
+// Build a JSDoc block that captures the description plus any runtime-only
+// constraints the TypeScript type cannot express (minLength, format, range,
+// etc.). Editors and TypeDoc surface these on hover, so authors can see what
+// the schema requires even though tsc does not enforce it.
+function renderJsDoc(schema, indent) {
+  if (!schema || typeof schema !== 'object') return '';
+
+  let description = '';
+  if (typeof schema.description === 'string' && schema.description.length > 0) {
+    description = schema.description.replace(/\*\//g, '* /');
+  }
+
+  const tags = [];
+  const numKeys = ['minLength', 'maxLength', 'minItems', 'maxItems', 'minProperties', 'maxProperties',
+    'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf'];
+  for (const k of numKeys) {
+    if (typeof schema[k] === 'number') tags.push(`@${k} ${schema[k]}`);
+  }
+  if (typeof schema.pattern === 'string') tags.push(`@pattern ${schema.pattern}`);
+  if (typeof schema.format === 'string') tags.push(`@format ${schema.format}`);
+  if (schema.uniqueItems === true) tags.push('@uniqueItems');
+  if (schema.deprecated === true) tags.push('@deprecated');
+  if (schema.default !== undefined) {
+    try { tags.push(`@default ${JSON.stringify(schema.default)}`); } catch (_) {}
+  }
+  if (Array.isArray(schema.examples) && schema.examples.length > 0) {
+    try { tags.push(`@example ${JSON.stringify(schema.examples[0])}`); } catch (_) {}
+  }
+
+  if (description === '' && tags.length === 0) return '';
+
+  if (description !== '' && tags.length === 0) {
+    return `${indent}/** ${description} */\n`;
+  }
+
+  const lines = [`${indent}/**`];
+  if (description !== '') lines.push(`${indent} * ${description}`);
+  if (description !== '' && tags.length > 0) lines.push(`${indent} *`);
+  for (const t of tags) lines.push(`${indent} * ${t}`);
+  lines.push(`${indent} */`);
+  return lines.join('\n') + '\n';
+}
+
 // Public: given a schema and optional type name, return a .d.ts source.
 function toTypeScript(schema, opts) {
   const options = opts || {};
@@ -125,13 +206,14 @@ function toTypeScript(schema, opts) {
   }
 
   const rootType = renderValueType(schema, defs, 0);
+  const rootDoc = renderJsDoc(schema, '');
   // Use `interface` only for a pure object literal; otherwise fall back to
   // `type`. Catches cases like `{...}[]` (array of object) and `Record<...>`
   // which are valid TS but cannot be expressed as an interface body.
   const isPureObjectLiteral = rootType.startsWith('{') && rootType.endsWith('}') && !rootType.includes(' | ');
   const rootDecl = isPureObjectLiteral
-    ? `export interface ${rootName} ${rootType}`
-    : `export type ${rootName} = ${rootType};`;
+    ? `${rootDoc}export interface ${rootName} ${rootType}`
+    : `${rootDoc}export type ${rootName} = ${rootType};`;
 
   return `// Auto-generated by ata-validator — do not edit.
 ${defLines.length ? defLines.join('\n\n') + '\n\n' : ''}${rootDecl}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ata-validator",
-  "version": "0.11.1",
-  "description": "Ultra-fast JSON Schema validator. 4.7x faster validation, 1,800x faster compilation. Works without native addon. Cross-schema $ref, Draft 2020-12 + Draft 7, V8-optimized JS codegen, simdjson, RE2, multi-core. Standard Schema V1 compatible.",
+  "version": "0.12.1",
+  "description": "Ultra-fast JSON Schema validator. 5x faster validation, 159,000x faster compilation. Works without native addon. Cross-schema $ref, Draft 2020-12 + Draft 7, V8-optimized JS codegen, simdjson, RE2, multi-core. Standard Schema V1 compatible.",
   "main": "index.js",
   "module": "index.mjs",
   "types": "index.d.ts",
@@ -41,6 +41,8 @@
     "test:standard-schema": "node tests/test_standard_schema.js",
     "test:browser": "node tests/test_browser.js",
     "test:ts": "node tests/test_ts_gen.js",
+    "test:ts-corpus": "node tests/test_ts_corpus.js",
+    "test:ts-differential": "node tests/test_ts_differential.js",
     "bench": "node benchmark/bench_large.js",
     "fuzz": "node tests/fuzz_differential.js",
     "fuzz:long": "FUZZ_ITERATIONS=100000 node tests/fuzz_differential.js",