ata-validator 0.11.0 → 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)** | **[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/index.d.ts

@@ -123,3 +123,11 @@ export function createPaddedBuffer(jsonStr: string): { buffer: Buffer; length: n
 
 /** Required padding size for simdjson buffers. */
 export const SIMDJSON_PADDING: number;
+
+/**
+ * Generate a TypeScript declaration (.d.ts source) for the given JSON Schema.
+ * Returns a string containing the generated type plus `isValid` / `validate`
+ * signatures. Used internally by the `ata compile` CLI and exposed for
+ * build-time integrations (Vite plugin, custom build steps).
+ */
+export function toTypeScript(schema: object, options?: { name?: string }): string;

package/index.js

@@ -1216,6 +1216,8 @@ function compile(schema, opts) {
   return fn;
 }
 
+const { toTypeScript } = require("./lib/ts-gen");
+
 module.exports = {
   Validator,
   compile,
@@ -1224,4 +1226,5 @@ module.exports = {
   createPaddedBuffer,
   SIMDJSON_PADDING,
   parseJSON,
+  toTypeScript,
 };

package/lib/js-compiler.js

@@ -675,8 +675,14 @@ function codegenSafe(schema, schemaMap) {
     if (siblings.length > 0 && schema.unevaluatedProperties === undefined && schema.unevaluatedItems === undefined) return false
   }
 
-  // additionalProperties as schema — bail entirely, too many edge cases with allOf interaction
-  if (typeof schema.additionalProperties === 'object') return false
+  // additionalProperties as schema — supported when no composition (allOf/oneOf/anyOf)
+  // is in play, and no patternProperties (unified loop does not emit the
+  // per-key sub-schema walk yet). Closure path handles those cases.
+  if (typeof schema.additionalProperties === 'object' && schema.additionalProperties !== null) {
+    if (schema.allOf || schema.oneOf || schema.anyOf) return false
+    if (schema.patternProperties) return false
+    if (!codegenSafe(schema.additionalProperties, schemaMap)) return false
+  }
   if (schema.additionalProperties === false && !schema.properties) return false
 
   // propertyNames: false — codegen doesn't handle this
@@ -729,6 +735,37 @@ function codegenSafe(schema, schemaMap) {
   return true
 }
 
+// Returns true if the schema (or any nested sub-schema reachable through the
+// usual keywords) has additionalProperties as a schema value. Used by the
+// combined-codegen bail since that path does not emit the per-key loop yet.
+function hasAdditionalPropertiesSchema(schema) {
+  if (typeof schema !== 'object' || schema === null) return false
+  if (typeof schema.additionalProperties === 'object' && schema.additionalProperties !== null) return true
+  const objSubs = ['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']
+  for (const key of objSubs) {
+    if (schema[key] && typeof schema[key] === 'object') {
+      for (const v of Object.values(schema[key])) {
+        if (hasAdditionalPropertiesSchema(v)) return true
+      }
+    }
+  }
+  const arrSubs = ['allOf', 'anyOf', 'oneOf', 'prefixItems']
+  for (const key of arrSubs) {
+    if (Array.isArray(schema[key])) {
+      for (const s of schema[key]) {
+        if (hasAdditionalPropertiesSchema(s)) return true
+      }
+    }
+  }
+  const singleSubs = ['items', 'contains', 'not', 'if', 'then', 'else', 'propertyNames']
+  for (const key of singleSubs) {
+    if (typeof schema[key] === 'object' && schema[key] !== null) {
+      if (hasAdditionalPropertiesSchema(schema[key])) return true
+    }
+  }
+  return false
+}
+
 // --- Codegen mode: generates a single Function (NOT CSP-safe) ---
 // This matches ajv's approach: one monolithic function, V8 JIT fully inlines it
 function compileToJSCodegen(schema, schemaMap) {
@@ -1274,6 +1311,25 @@ function genCode(schema, v, lines, ctx, knownType) {
         _deferOrInline(ctx, lines, v, isObj ? inner : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}`)
   }
 
+  // additionalProperties as a schema: validate every non-declared property
+  // against that sub-schema. Skip if patternProperties is present (handled by
+  // the unified loop). Composition cases are filtered out by codegenSafe.
+  if (typeof schema.additionalProperties === 'object' && schema.additionalProperties !== null && !schema.patternProperties) {
+    const declared = schema.properties ? Object.keys(schema.properties) : []
+    const skipCheck = declared.length === 0
+      ? null
+      : declared.map(k => `_k===${JSON.stringify(k)}`).join('||')
+    const subLines = []
+    genCode(schema.additionalProperties, '_av', subLines, ctx)
+    if (subLines.length > 0) {
+      const body = subLines.join(';')
+      const loop = skipCheck
+        ? `for(var _k in ${v}){if(${skipCheck})continue;const _av=${v}[_k];${body}}`
+        : `for(var _k in ${v}){const _av=${v}[_k];${body}}`
+      _deferOrInline(ctx, lines, v, isObj ? loop : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${loop}}`)
+    }
+  }
+
   // dependentRequired
   if (schema.dependentRequired) {
     for (const [key, deps] of Object.entries(schema.dependentRequired)) {
@@ -2251,6 +2307,9 @@ function compileToJSCodegenWithErrors(schema, schemaMap) {
     if (s.includes('unevaluatedProperties') || s.includes('unevaluatedItems')) return null
     // Bail on self-referencing schemas — error codegen doesn't support recursion
     if (s.includes('"$ref":"#"')) return null
+    // Bail on additionalProperties as a schema — genCodeE does not emit the
+    // per-key sub-schema loop. Let the closure path handle detailed errors.
+    if (hasAdditionalPropertiesSchema(schema)) return null
   }
   if (typeof schema === 'boolean') {
     return schema
@@ -2752,6 +2811,9 @@ function compileToJSCombined(schema, VALID_RESULT, schemaMap) {
     if (s.includes('unevaluatedProperties') || s.includes('unevaluatedItems')) return null
     // Bail on self-referencing schemas — combined codegen doesn't support recursion
     if (s.includes('"$ref":"#"')) return null
+    // Bail on additionalProperties as a schema — combined path doesn't emit the
+    // per-key sub-schema loop yet. The jsFn + errFn fallback handles it correctly.
+    if (hasAdditionalPropertiesSchema(schema)) return null
   }
   if (typeof schema === 'boolean') {
     return schema

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,10 +206,14 @@ function toTypeScript(schema, opts) {
   }
 
   const rootType = renderValueType(schema, defs, 0);
-  const isObjectShape = rootType.startsWith('{') || rootType.startsWith('Record<');
-  const rootDecl = isObjectShape && !rootType.includes(' | ')
-    ? `export interface ${rootName} ${rootType}`
-    : `export type ${rootName} = ${rootType};`;
+  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
+    ? `${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.0",
+  "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",
@@ -40,6 +40,9 @@
     "test:compat": "node tests/test_compat.js",
     "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",
@@ -60,7 +63,7 @@
     "standard-schema",
     "fastify"
   ],
-  "author": "Mert Can Altin <mertcanaltin01@gmail.com>",
+  "author": "Mert Can Altin <mertgold60@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -103,6 +106,7 @@
     "cmake-js": "^8.0.0",
     "mitata": "^1.0.34",
     "typebox": "^1.1.7",
+    "typescript": "^6.0.3",
     "valibot": "^1.3.1",
     "zod": "^4.3.6"
   },