ata-validator 0.11.1 → 0.12.0

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
 
@@ -54,8 +58,8 @@ Three-tier hybrid codegen: static schemas compile to zero-overhead key checks, d
 |---|---|---|---|---|---|
 | **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 | — | — |
+| **compilation** | **453ns** | 1.24ms | 52μs | n/a | n/a |
+| **first validation** | **2.1μs** | 1.11ms | 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)
 
@@ -219,7 +223,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 +318,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/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,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "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.",
   "main": "index.js",
   "module": "index.mjs",
@@ -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",