ata-validator 0.10.3 → 0.11.0

package/README.md

@@ -211,29 +211,66 @@ const v = new Validator(schema, {
   coerceTypes: true,       // "42" → 42 for integer fields
   removeAdditional: true,  // strip properties not in schema
   schemas: [otherSchema],  // cross-schema $ref registry
+  abortEarly: true,        // skip detailed error collection on failure (~4x faster on invalid data)
 });
 ```
 
-### Standalone Pre-compilation
+`abortEarly` returns a shared `{ valid: false, errors: [{ message: 'validation failed' }] }` on failure instead of running the detailed error collector. Useful when the caller only needs a pass/fail decision (Fastify route guards, high-throughput gatekeepers, request rejection at the edge).
 
-Pre-compile schemas to JS files for near-zero startup. No native addon needed at runtime.
+### 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.
+
+```bash
+npx ata compile schemas/user.json -o src/generated/user.validator.mjs
+```
+
+The CLI emits two files: the validator itself and a paired `.d.mts` (or `.d.cts`) with the inferred TypeScript type plus an `isValid` type predicate.
+
+```ts
+import { isValid, validate, type User } from './user.validator.mjs'
+
+const incoming: unknown = JSON.parse(req.body)
+
+if (isValid(incoming)) {
+  // TypeScript narrows to User here
+  incoming.id      // number
+  incoming.role    // 'admin' | 'user' | 'guest' | undefined
+}
+
+const r = validate(incoming)
+// { valid: true, errors: [] } | { valid: false, errors: ValidationError[] }
+```
+
+CLI options:
+
+| Flag | Default | Description |
+|---|---|---|
+| `-o, --output <file>` | `<schema>.validator.mjs` | Output path |
+| `-f, --format <fmt>` | `esm` | `esm` or `cjs` |
+| `--name <TypeName>` | from filename | Root type name in the `.d.ts` |
+| `--abort-early` | off | Generate the stub-error variant (~0.5 KB gzipped) |
+| `--no-types` | off | Skip the `.d.mts` / `.d.cts` output |
+
+Typical bundle sizes (10-field user schema, gzipped):
+
+| Variant | Size | Notes |
+|---|---|---|
+| `ata-validator` runtime | ~27 KB | Full compiler + all keywords |
+| `ata compile` (standard) | **~1.1 KB** | Validator + detailed error collector |
+| `ata compile --abort-early` | **~0.5 KB** | Validator + stub errors only |
+
+Programmatic API if you prefer to script it:
 
 ```javascript
 const fs = require('fs');
+const { Validator } = require('ata-validator');
 
-// Build phase (once)
 const v = new Validator(schema);
-fs.writeFileSync('./compiled.js', v.toStandalone());
-
-// Read phase (every startup) - 0.6μs per schema, pure JS
-const v2 = Validator.fromStandalone(require('./compiled.js'), schema);
-
-// Bundle multiple schemas - deduplicated, single file
-fs.writeFileSync('./bundle.js', Validator.bundleCompact(schemas));
-const validators = Validator.loadBundle(require('./bundle.js'), schemas);
+fs.writeFileSync('./user.validator.mjs', v.toStandaloneModule({ format: 'esm' }));
 ```
 
-**Fastify startup (5 routes): ajv 6.0ms → ata 0.5ms (12x faster, no build step needed)**
+**Fastify startup (10 routes cold): ajv 12.6ms → ata 0.5ms (24x faster boot, no build step required)**
 
 ### Standard Schema V1
 

package/bin/ata.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function usage() {
+  process.stdout.write(`ata-validator CLI
+
+Usage:
+  ata compile <schema-file> [options]
+
+Options:
+  -o, --output <file>     Output path. Default: <schema-file>.validator.mjs
+  -f, --format <fmt>      Module format: esm | cjs. Default: esm
+  --name <TypeName>       Name of the top-level type in .d.ts. Default: inferred from filename
+  --no-types              Skip .d.ts generation
+  --abort-early           Use stub errors (smallest bundle)
+  -h, --help              Show this message
+
+Examples:
+  ata compile schemas/user.json -o src/generated/user.validator.mjs
+  ata compile schemas/user.json --format cjs -o dist/user.validator.cjs
+  ata compile schemas/public-api.json --abort-early -o dist/api.mjs
+`);
+}
+
+function parseArgs(argv) {
+  const out = { _: [], opts: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') { out.opts.help = true; continue; }
+    if (a === '-o' || a === '--output') { out.opts.output = argv[++i]; continue; }
+    if (a === '-f' || a === '--format') { out.opts.format = argv[++i]; continue; }
+    if (a === '--name') { out.opts.name = argv[++i]; continue; }
+    if (a === '--no-types') { out.opts.types = false; continue; }
+    if (a === '--abort-early') { out.opts.abortEarly = true; continue; }
+    if (a.startsWith('-')) { throw new Error(`Unknown option: ${a}`); }
+    out._.push(a);
+  }
+  return out;
+}
+
+function inferOutput(inputPath, format) {
+  const dir = path.dirname(inputPath);
+  const base = path.basename(inputPath, path.extname(inputPath));
+  const ext = format === 'cjs' ? '.validator.cjs' : '.validator.mjs';
+  return path.join(dir, base + ext);
+}
+
+function cmdCompile(args) {
+  if (args._.length === 0) {
+    process.stderr.write('error: missing <schema-file>\n\n');
+    usage();
+    process.exit(1);
+  }
+  const input = args._[0];
+  const format = args.opts.format || 'esm';
+  if (format !== 'esm' && format !== 'cjs') {
+    process.stderr.write(`error: --format must be esm or cjs (got "${format}")\n`);
+    process.exit(1);
+  }
+  const output = args.opts.output || inferOutput(input, format);
+  const abortEarly = !!args.opts.abortEarly;
+
+  let schemaStr;
+  try {
+    schemaStr = fs.readFileSync(input, 'utf8');
+  } catch (e) {
+    process.stderr.write(`error: cannot read ${input}: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  let schema;
+  try {
+    schema = JSON.parse(schemaStr);
+  } catch (e) {
+    process.stderr.write(`error: ${input} is not valid JSON: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  const { Validator } = require('..');
+  const v = new Validator(schema);
+  const src = v.toStandaloneModule({ format, abortEarly });
+  if (!src) {
+    process.stderr.write('error: schema is too complex for standalone compilation\n');
+    process.exit(1);
+  }
+
+  fs.mkdirSync(path.dirname(output), { recursive: true });
+  fs.writeFileSync(output, src);
+
+  const sizeBytes = Buffer.byteLength(src, 'utf8');
+  process.stdout.write(`ata: compiled ${input} -> ${output} (${sizeBytes.toLocaleString()} bytes, ${format}${abortEarly ? ', abort-early' : ''})\n`);
+
+  // Emit paired declaration file unless --no-types.
+  // TypeScript resolution: .mjs -> .d.mts, .cjs -> .d.cts, .js -> .d.ts.
+  const emitTypes = args.opts.types !== false;
+  if (emitTypes) {
+    const { toTypeScript } = require('../lib/ts-gen');
+    const typeName = args.opts.name || path.basename(input, path.extname(input))
+      .replace(/[^A-Za-z0-9_]/g, '_')
+      .replace(/^([a-z])/, (m) => m.toUpperCase()) || 'Data';
+    const dts = toTypeScript(schema, { name: typeName });
+    const ext = path.extname(output);
+    const dtsExt = ext === '.mjs' ? '.d.mts'
+      : ext === '.cjs' ? '.d.cts'
+      : '.d.ts';
+    const dtsPath = output.slice(0, output.length - ext.length) + dtsExt;
+    const finalDtsPath = dtsPath === output ? output + dtsExt : dtsPath;
+    fs.writeFileSync(finalDtsPath, dts);
+    process.stdout.write(`ata: wrote types       -> ${finalDtsPath}\n`);
+  }
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0) { usage(); process.exit(0); }
+
+  const cmd = argv[0];
+  if (cmd === '-h' || cmd === '--help' || cmd === 'help') { usage(); return; }
+
+  const rest = argv.slice(1);
+  let args;
+  try {
+    args = parseArgs(rest);
+  } catch (e) {
+    process.stderr.write(`error: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  if (args.opts.help) { usage(); return; }
+
+  if (cmd === 'compile') {
+    cmdCompile(args);
+    return;
+  }
+
+  process.stderr.write(`error: unknown command "${cmd}"\n\n`);
+  usage();
+  process.exit(1);
+}
+
+main();

package/index.js

@@ -272,6 +272,19 @@ const _identityCache = new WeakMap();
 
 const SIMDJSON_PADDING = 64;
 const VALID_RESULT = Object.freeze({ valid: true, errors: Object.freeze([]) });
+const ABORT_EARLY_RESULT = Object.freeze({ valid: false, errors: Object.freeze([Object.freeze({ message: 'validation failed' })]) });
+
+// Embedded verbatim in standalone modules so the output file has no runtime
+// dependency on ata-validator. ASCII fast-path plus surrogate-aware slow path.
+const _CP_LEN_SOURCE = `function _cpLen(s) {
+  const len = s.length;
+  for (let i = 0; i < len; i++) {
+    if (s.charCodeAt(i) >= 0xD800 && s.charCodeAt(i) <= 0xDBFF) {
+      let n = 0; for (const _ of s) n++; return n;
+    }
+  }
+  return len;
+}`;
 
 // Above this size, simdjson On Demand (selective field access) beats JSON.parse
 // (which must materialize the full JS object tree). Buffer.from + NAPI ~2x faster.
@@ -359,7 +372,21 @@ class Validator {
       return this.validate(data);
     };
     this.isValidObject = (data) => {
-      this._ensureCodegen();
+      // Lazy: classify + build tier 0 plan on first call, not in constructor.
+      const _tier = classify(this._schemaObj);
+      if (_tier.tier === 0) {
+        const _plan = buildTier0Plan(this._schemaObj);
+        let _n = 0;
+        this.isValidObject = (d) => {
+          const r = tier0Validate(_plan, d);
+          if (++_n === 2) {
+            try { this._ensureCodegen(); } catch {}
+          }
+          return r;
+        };
+      } else {
+        this._ensureCodegen();
+      }
       return this.isValidObject(data);
     };
     this.validateJSON = (jsonStr) => {
@@ -416,15 +443,6 @@ class Validator {
       configurable: false,
     });
 
-    // Tier 0 fast path: override isValidObject with a direct bound validator.
-    // All other methods (validate, validateJSON, etc.) stay on the lazy stubs above.
-    // Tier 0/1 are boolean-only; error paths continue through codegen.
-    const _tier = classify(schemaObj);
-    if (_tier.tier === 0) {
-      const _plan = buildTier0Plan(schemaObj);
-      this.isValidObject = (data) => tier0Validate(_plan, data);
-    }
-
     // Populate identity cache so repeated `new Validator(sameSchema)` short-circuits.
     if (!opts && typeof schema === "object" && schema !== null) {
       _identityCache.set(schema, this);
@@ -552,7 +570,14 @@ class Validator {
         } catch {}
       }
 
-      if (hasDynRef && _isCodegen && jsFn) {
+      if (options.abortEarly && jsFn && !hasDynRef) {
+        // Abort-early fast path: skip detailed error collection on failure.
+        // Returns a shared frozen result, no per-call allocation, no errFn work.
+        const _fn = jsFn;
+        this.validate = preprocess
+          ? (data) => { preprocess(data); return _fn(data) ? VALID_RESULT : ABORT_EARLY_RESULT; }
+          : (data) => (_fn(data) ? VALID_RESULT : ABORT_EARLY_RESULT);
+      } else if (hasDynRef && _isCodegen && jsFn) {
         // $dynamicRef with JS codegen: direct path, no wrapper layers
         const _fn = jsFn, _efn = safeErrFn || errFn, _R = VALID_RESULT;
         this.validate = preprocess
@@ -809,6 +834,7 @@ class Validator {
 
     return `// Auto-generated by ata-validator — do not edit
 'use strict';
+${_CP_LEN_SOURCE}
 const boolFn = function(d) {
   ${src}
 };
@@ -822,6 +848,57 @@ module.exports = { boolFn, hybridFactory, errFn };
 `;
   }
 
+  // --- Fully standalone module ---
+  // Generates a self-contained module that can be imported directly without
+  // pulling in ata-validator at runtime. Browser bundle gets only the
+  // generated validator (~2 KB typical) instead of the 165 KB compiler.
+  //
+  //   import { validate, isValid } from './user-validator.mjs'
+  //   if (isValid(data)) { ... }
+  //
+  // format: 'esm' | 'cjs'. Default 'esm'.
+  // abortEarly: if true, invalid result is a shared stub; smaller output.
+  toStandaloneModule(opts) {
+    this._ensureCompiled();
+    const jsFn = this._jsFn;
+    if (!jsFn || !jsFn._source) return null;
+    const format = (opts && opts.format) || 'esm';
+    const abortEarly = !!(opts && opts.abortEarly);
+    const src = jsFn._source;
+
+    let errCore = '';
+    if (!abortEarly) {
+      const jsErrFn = compileToJSCodegenWithErrors(
+        typeof this._schemaObj === 'object' ? this._schemaObj : {},
+      );
+      const errSrc = jsErrFn && jsErrFn._errSource ? jsErrFn._errSource : '';
+      if (errSrc) {
+        errCore = `const errFn = function(d, _all) {\n  ${errSrc}\n};\n`;
+      }
+    }
+
+    const validBody = errCore
+      ? 'return _fn(data) ? VALID : { valid: false, errors: errFn(data, true).errors }'
+      : 'return _fn(data) ? VALID : ABORT';
+
+    const exports = format === 'esm'
+      ? `export { validate, isValid };\nexport default { validate, isValid };\n`
+      : `module.exports = { validate, isValid };\nmodule.exports.default = module.exports;\n`;
+
+    return `// Auto-generated by ata-validator — do not edit.
+// Schema is embedded; runtime has zero dependency on ata-validator.
+'use strict';
+${_CP_LEN_SOURCE}
+const VALID = Object.freeze({ valid: true, errors: Object.freeze([]) });
+const ABORT = Object.freeze({ valid: false, errors: Object.freeze([Object.freeze({ message: 'validation failed' })]) });
+const _fn = function(d) {
+  ${src}
+};
+${errCore}function isValid(data) { return _fn(data); }
+function validate(data) { ${validBody}; }
+${exports}`;
+  }
+
   // Load a pre-compiled standalone module. Zero schema compilation.
   // No NAPI, no native compile — pure JS. Startup in microseconds.
   // Usage: const v = Validator.fromStandalone(require('./compiled.js'), schema, opts)

package/lib/js-compiler.js

@@ -927,15 +927,26 @@ function tryGenCombined(schema, access, ctx) {
   if (!types || types.length !== 1) return null
   const t = types[0]
 
+  // If access is already a simple identifier (optional-property hoist, a `_o0`
+  // or similar), skip the `{const _v = access}` wrapping and use it directly.
+  const isIdent = /^_[a-zA-Z]\w*$/.test(access)
+  const bind = (conds) => isIdent
+    ? `if(${conds.join('||').replace(/\b_v\b/g, access)})return false`
+    : `{const _v=${access};if(${conds.join('||')})return false}`
+
   if (t === 'string') {
+    if (schema.pattern || schema.format) return null
+    // Both bounds set: hoist _cpLen once so ASCII strings are not scanned twice.
+    if (schema.minLength !== undefined && schema.maxLength !== undefined) {
+      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}`
+    }
     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 (conds.length < 2 && !schema.pattern && !schema.format) return null // not worth combining
-    // pattern and format need separate statements, fall back if present
-    if (schema.pattern || schema.format) return null
-    const vi = ctx.varCounter++
-    return `{const _v=${access};if(${conds.join('||')})return false}`
+    if (conds.length < 2) return null
+    return bind(conds)
   }
 
   if (t === 'integer') {
@@ -946,8 +957,7 @@ function tryGenCombined(schema, access, ctx) {
     if (schema.exclusiveMaximum !== undefined) conds.push(`_v>=${schema.exclusiveMaximum}`)
     if (schema.multipleOf !== undefined) conds.push(`_v%${schema.multipleOf}!==0`)
     if (conds.length < 2) return null
-    const vi = ctx.varCounter++
-    return `{const _v=${access};if(${conds.join('||')})return false}`
+    return bind(conds)
   }
 
   if (t === 'number') {
@@ -958,13 +968,25 @@ function tryGenCombined(schema, access, ctx) {
     if (schema.exclusiveMaximum !== undefined) conds.push(`_v>=${schema.exclusiveMaximum}`)
     if (schema.multipleOf !== undefined) conds.push(`_v%${schema.multipleOf}!==0`)
     if (conds.length < 2) return null
-    const vi = ctx.varCounter++
-    return `{const _v=${access};if(${conds.join('||')})return false}`
+    return bind(conds)
   }
 
   return null
 }
 
+// Deferred checks (additionalProperties, unevaluatedProperties, ...) reference
+// the current node variable (`${v}`). Deferring them to the end of the root
+// function is only safe when we're at the root (`v === 'd'`). For nested
+// nodes, emit inline so block-scoped variables like `_o0` stay in scope.
+function _deferOrInline(ctx, lines, v, check) {
+  if (v === 'd') {
+    if (!ctx.deferredChecks) ctx.deferredChecks = []
+    ctx.deferredChecks.push(check)
+  } else {
+    lines.push(check)
+  }
+}
+
 // knownType: if parent already verified the type, skip redundant guards.
 // 'object' = we know v is a non-null non-array object
 // 'array'  = we know v is an array
@@ -1176,9 +1198,21 @@ 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
-  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`)
+  // 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.
+  if (schema.minLength !== undefined && schema.maxLength !== undefined) {
+    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}`)
+    }
+  } 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`)
+  }
 
   // array size — skip guard if known array
   if (schema.minItems !== undefined) lines.push(isArr ? `if(${v}.length<${schema.minItems})return false` : `if(Array.isArray(${v})&&${v}.length<${schema.minItems})return false`)
@@ -1237,8 +1271,7 @@ function genCode(schema, v, lines, ctx, knownType) {
           ? `var _n=0;for(var _k in ${v})_n++;if(_n!==${propCount})return false`
           : `if(Object.keys(${v}).length!==${propCount})return false`)
       : `for(var _k in ${v})if(${Object.keys(schema.properties).map(k => `_k!==${JSON.stringify(k)}`).join('&&')})return false`
-    if (!ctx.deferredChecks) ctx.deferredChecks = []
-    ctx.deferredChecks.push(isObj ? inner : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}`)
+        _deferOrInline(ctx, lines, v, isObj ? inner : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}`)
   }
 
   // dependentRequired
@@ -1586,19 +1619,16 @@ function genCode(schema, v, lines, ctx, knownType) {
             inner = propCount <= 15
               ? `var _n=0;for(var _k in ${v})_n++;if(_n!==${propCount})return false`
               : `if(Object.keys(${v}).length!==${propCount})return false`
-            if (!ctx.deferredChecks) ctx.deferredChecks = []
-            ctx.deferredChecks.push(isObj ? inner : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}`)
+                        _deferOrInline(ctx, lines, v, isObj ? inner : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}`)
           }
           // else: already emitted early (before properties)
         } else if (propCount > 0) {
           // TRICK 3: charCodeAt switch tree
           inner = genCharCodeSwitch(knownKeys, v)
-          if (!ctx.deferredChecks) ctx.deferredChecks = []
-          ctx.deferredChecks.push(isObj ? inner : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}`)
+                    _deferOrInline(ctx, lines, v, isObj ? inner : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}`)
         } else {
           inner = `for(var _k in ${v})return false`
-          if (!ctx.deferredChecks) ctx.deferredChecks = []
-          ctx.deferredChecks.push(isObj ? inner : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}`)
+                    _deferOrInline(ctx, lines, v, isObj ? inner : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}`)
         }
       } else if (typeof schema.unevaluatedProperties === 'object') {
         // unevaluatedProperties: {schema} — validate unknown keys
@@ -1611,8 +1641,7 @@ function genCode(schema, v, lines, ctx, knownType) {
           const keyChecks = knownKeys.map(k => `${ukVar}===${JSON.stringify(k)}`).join('||')
           const skipKnown = knownKeys.length > 0 ? `if(${keyChecks})continue;` : ''
           const inner = `for(var ${ukVar} in ${v}){${skipKnown}${check}}`
-          if (!ctx.deferredChecks) ctx.deferredChecks = []
-          ctx.deferredChecks.push(isObj ? inner : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}`)
+                    _deferOrInline(ctx, lines, v, isObj ? inner : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}`)
         }
       }
     } else {
@@ -1730,8 +1759,7 @@ function genCode(schema, v, lines, ctx, knownType) {
             const inner = staticCheck
               ? `for(var _k in ${v}){if(${staticCheck})continue;${dynamicCheck}return false}`
               : `for(var _k in ${v}){${dynamicCheck}return false}`
-            if (!ctx.deferredChecks) ctx.deferredChecks = []
-            ctx.deferredChecks.push(isObj ? inner + '}' : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}}`)
+                        _deferOrInline(ctx, lines, v, isObj ? inner + '}' : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}}`)
           } else {
             // Fallback: plain object tracking
             const ei = ctx.varCounter++
@@ -1756,8 +1784,7 @@ function genCode(schema, v, lines, ctx, knownType) {
               lines.push(`let _am${bfi}=false;for(let _bi=0;_bi<_bf${bfi}.length;_bi++){if(_bf${bfi}[_bi](${v})){_am${bfi}=true;for(const _p of _bk${bfi}[_bi])${evVar}[_p]=1}}if(!_am${bfi})return false`)
             }
             const inner = `for(var _k in ${v}){if(!${evVar}[_k])return false}`
-            if (!ctx.deferredChecks) ctx.deferredChecks = []
-            ctx.deferredChecks.push(isObj ? inner + '}' : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}}`)
+                        _deferOrInline(ctx, lines, v, isObj ? inner + '}' : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}}`)
           }
         } else if (schema.dependentSchemas) {
           // dependentSchemas: conditional merge at runtime
@@ -1772,8 +1799,7 @@ function genCode(schema, v, lines, ctx, knownType) {
             }
           }
           const inner = `for(var _k in ${v}){if(!${evVar}[_k])return false}`
-          if (!ctx.deferredChecks) ctx.deferredChecks = []
-          ctx.deferredChecks.push(isObj ? inner + '}' : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}}`)
+                    _deferOrInline(ctx, lines, v, isObj ? inner + '}' : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}}`)
         } else {
           // General fallback: collect all patternProperties from root + allOf sub-schemas + if
           // and use runtime regex matching
@@ -1833,12 +1859,10 @@ function genCode(schema, v, lines, ctx, knownType) {
               const rootPatCheck = rootReVars.map(rv => `if(${rv}.test(_k))continue;`).join('')
               const ifPatCheck = ifReVars.map(rv => `if(${rv}.test(_k))continue;`).join('')
               const inner = `const _uif${ufi}=${ifFn};if(_uif${ufi}(${v})){for(var _k in ${v}){if(${evVar}[_k])continue;${rootPatCheck}${ifPatCheck}return false}}else{for(var _k in ${v}){if(${evVar}[_k])continue;${rootPatCheck}return false}}`
-              if (!ctx.deferredChecks) ctx.deferredChecks = []
-              ctx.deferredChecks.push(isObj ? inner + '}' : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}}`)
+                            _deferOrInline(ctx, lines, v, isObj ? inner + '}' : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}}`)
             } else {
               const inner = `for(var _k in ${v}){if(${evVar}[_k])continue;${reVars.map(rv => `if(${rv}.test(_k)){${evVar}[_k]=1;continue}`).join('')}return false}`
-              if (!ctx.deferredChecks) ctx.deferredChecks = []
-              ctx.deferredChecks.push(isObj ? inner + '}' : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}}`)
+                            _deferOrInline(ctx, lines, v, isObj ? inner + '}' : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}}`)
             }
           }
         }
@@ -1879,8 +1903,7 @@ function genCode(schema, v, lines, ctx, knownType) {
         if (subLines2.length > 0) {
           const check = subLines2.join(';')
           const inner = `for(var ${ukVar} in ${v}){if(${evVar}[${ukVar}])continue;${check}}`
-          if (!ctx.deferredChecks) ctx.deferredChecks = []
-          ctx.deferredChecks.push(isObj ? inner + '}' : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}}`)
+                    _deferOrInline(ctx, lines, v, isObj ? inner + '}' : `if(typeof ${v}==='object'&&${v}!==null&&!Array.isArray(${v})){${inner}}}`)
         } else {
           lines.push('}')
         }
@@ -1905,8 +1928,7 @@ function genCode(schema, v, lines, ctx, knownType) {
         // TRICK 6: Array.length comparison only
         const maxIdx = evalResult.items || 0
         const inner = `if(${v}.length>${maxIdx})return false`
-        if (!ctx.deferredChecks) ctx.deferredChecks = []
-        ctx.deferredChecks.push(isArr ? inner : `if(Array.isArray(${v})){${inner}}`)
+                _deferOrInline(ctx, lines, v, isArr ? inner : `if(Array.isArray(${v})){${inner}}`)
       } else if (typeof schema.unevaluatedItems === 'object') {
         const maxIdx = evalResult.items || 0
         const ui = ctx.varCounter++
@@ -1917,8 +1939,7 @@ function genCode(schema, v, lines, ctx, knownType) {
         if (subLines.length > 0) {
           const check = subLines.join(';')
           const inner = `for(let ${idxVar}=${maxIdx};${idxVar}<${v}.length;${idxVar}++){const ${elemVar}=${v}[${idxVar}];${check}}`
-          if (!ctx.deferredChecks) ctx.deferredChecks = []
-          ctx.deferredChecks.push(isArr ? inner : `if(Array.isArray(${v})){${inner}}`)
+                    _deferOrInline(ctx, lines, v, isArr ? inner : `if(Array.isArray(${v})){${inner}}`)
         }
       }
     } else {
@@ -1970,8 +1991,7 @@ function genCode(schema, v, lines, ctx, knownType) {
         }
         if (schema.unevaluatedItems === false) {
           const inner = `if(${v}.length>${evVar})return false`
-          if (!ctx.deferredChecks) ctx.deferredChecks = []
-          ctx.deferredChecks.push(isArr ? inner + '}' : `if(Array.isArray(${v})){${inner}}}`)
+                    _deferOrInline(ctx, lines, v, isArr ? inner + '}' : `if(Array.isArray(${v})){${inner}}}`)
         } else {
           const ui = ctx.varCounter++
           const elemVar = `_ue${ui}`
@@ -1981,8 +2001,7 @@ function genCode(schema, v, lines, ctx, knownType) {
           if (subLines.length > 0) {
             const check = subLines.join(';')
             const inner = `for(let ${idxVar}=${evVar};${idxVar}<${v}.length;${idxVar}++){const ${elemVar}=${v}[${idxVar}];${check}}`
-            if (!ctx.deferredChecks) ctx.deferredChecks = []
-            ctx.deferredChecks.push(isArr ? inner + '}' : `if(Array.isArray(${v})){${inner}}}`)
+                        _deferOrInline(ctx, lines, v, isArr ? inner + '}' : `if(Array.isArray(${v})){${inner}}}`)
           } else {
             lines.push('}')
           }
@@ -2038,8 +2057,7 @@ function genCode(schema, v, lines, ctx, knownType) {
         lines.push(`if(Array.isArray(${v})){for(let _ci=0;_ci<${v}.length;_ci++){for(let _cj=0;_cj<${cfnArr}.length;_cj++){if(${cfnArr}[_cj](${v}[_ci])){${evArr}[_ci]=true;break}}}}`)
         if (schema.unevaluatedItems === false) {
           const inner = `if(Array.isArray(${v})){for(let _ci=0;_ci<${v}.length;_ci++){if(!${evArr}[_ci])return false}}`
-          if (!ctx.deferredChecks) ctx.deferredChecks = []
-          ctx.deferredChecks.push(inner + '}')
+                    _deferOrInline(ctx, lines, v, inner + '}')
         } else {
           // unevaluatedItems: {schema}
           const ui = ctx.varCounter++
@@ -2049,8 +2067,7 @@ function genCode(schema, v, lines, ctx, knownType) {
           if (subLines.length > 0) {
             const check = subLines.join(';')
             const inner = `if(Array.isArray(${v})){for(let _ci=0;_ci<${v}.length;_ci++){if(!${evArr}[_ci]){const ${elemVar}=${v}[_ci];${check}}}}`
-            if (!ctx.deferredChecks) ctx.deferredChecks = []
-            ctx.deferredChecks.push(inner + '}')
+                        _deferOrInline(ctx, lines, v, inner + '}')
           } else {
             lines.push('}')
           }
@@ -2059,8 +2076,7 @@ function genCode(schema, v, lines, ctx, knownType) {
         // Fallback: use static base index (may not be fully correct for all dynamic cases)
         const maxIdx = evalResult.items || 0
         const inner = `if(${v}.length>${maxIdx})return false`
-        if (!ctx.deferredChecks) ctx.deferredChecks = []
-        ctx.deferredChecks.push(isArr ? inner : `if(Array.isArray(${v})){${inner}}`)
+                _deferOrInline(ctx, lines, v, isArr ? inner : `if(Array.isArray(${v})){${inner}}`)
       }
     }
   }
@@ -2802,12 +2818,12 @@ function compileToJSCombined(schema, VALID_RESULT, schemaMap) {
     `\n  return _e?{valid:false,errors:_e}:R`
 
   try {
-    if (process.env.ATA_DUMP_CODEGEN) console.log('=== COMBINED CODEGEN ===\n' + inner + '\n=== CLOSURE VARS: ' + ctx.closureVars.length + ' ===')
+    if (typeof process !== 'undefined' && process.env && process.env.ATA_DUMP_CODEGEN) console.log('=== COMBINED CODEGEN ===\n' + inner + '\n=== CLOSURE VARS: ' + ctx.closureVars.length + ' ===')
     const factory = new Function('R' + (closureParams ? ',' + closureParams : ''),
       `return function(d){${inner}}`)
     return factory(VALID_RESULT, ...ctx.closureVals)
   } catch (e) {
-    if (process.env.ATA_DEBUG) console.error('compileToJSCombined error:', e.message, '\n', inner.slice(0, 500))
+    if (typeof process !== 'undefined' && process.env && process.env.ATA_DEBUG) console.error('compileToJSCombined error:', e.message, '\n', inner.slice(0, 500))
     return null
   }
 }

package/lib/ts-gen.js

@@ -0,0 +1,161 @@
+'use strict';
+
+// Schema -> TypeScript type declaration.
+// Emits an interface or type alias for each top-level schema, plus
+// `isValid` (type predicate) and `validate` signatures.
+//
+// Scope: the common shapes in real-world APIs.
+//   - type: string | number | integer | boolean | null | array | object
+//   - properties + required (required field narrows to required, optional to optional)
+//   - enum (narrows to literal union)
+//   - const (narrows to literal)
+//   - items (array element type)
+//   - oneOf / anyOf (union)
+//   - $ref to local $defs (resolved by name)
+// Falls back to `unknown` for shapes we cannot represent.
+
+function renderValueType(schema, defs, depth = 0) {
+  if (depth > 32) return 'unknown';
+  if (schema === true) return 'unknown';
+  if (schema === false) return 'never';
+  if (typeof schema !== 'object' || schema === null) return 'unknown';
+
+  // $ref to local $defs
+  if (schema.$ref) {
+    const m = schema.$ref.match(/^#\/(?:\$defs|definitions)\/(.+)$/);
+    if (m && defs && defs[m[1]]) return toTypeName(m[1]);
+    return 'unknown';
+  }
+
+  // const narrows to literal
+  if (schema.const !== undefined) return renderLiteral(schema.const);
+
+  // enum narrows to literal union
+  if (Array.isArray(schema.enum)) {
+    return schema.enum.map(renderLiteral).join(' | ') || 'never';
+  }
+
+  // oneOf / anyOf → union
+  if (Array.isArray(schema.oneOf)) {
+    return schema.oneOf.map((s) => renderValueType(s, defs, depth + 1)).join(' | ') || 'unknown';
+  }
+  if (Array.isArray(schema.anyOf)) {
+    return schema.anyOf.map((s) => renderValueType(s, defs, depth + 1)).join(' | ') || 'unknown';
+  }
+
+  // type
+  const t = schema.type;
+  if (Array.isArray(t)) {
+    return t.map((tt) => renderValueType({ ...schema, type: tt }, defs, depth + 1)).join(' | ');
+  }
+
+  if (t === 'string') return 'string';
+  if (t === 'number' || t === 'integer') return 'number';
+  if (t === 'boolean') return 'boolean';
+  if (t === 'null') return 'null';
+
+  if (t === 'array') {
+    const items = schema.items;
+    if (items === undefined || items === true) return 'unknown[]';
+    const inner = renderValueType(items, defs, depth + 1);
+    return inner.includes(' | ') ? `Array<${inner}>` : `${inner}[]`;
+  }
+
+  if (t === 'object' || (!t && schema.properties)) {
+    return renderObject(schema, defs, depth + 1);
+  }
+
+  return 'unknown';
+}
+
+function renderObject(schema, defs, depth) {
+  const props = schema.properties || {};
+  const required = new Set(schema.required || []);
+  const keys = Object.keys(props);
+  if (keys.length === 0) {
+    if (schema.additionalProperties === false) return 'Record<string, never>';
+    const ap = schema.additionalProperties;
+    if (ap && typeof ap === 'object') {
+      return `Record<string, ${renderValueType(ap, defs, depth + 1)}>`;
+    }
+    return 'Record<string, unknown>';
+  }
+  const lines = keys.map((k) => {
+    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};`;
+  });
+  // 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)};`);
+  }
+  return `{\n${lines.join('\n')}\n}`;
+}
+
+function renderLiteral(v) {
+  if (v === null) return 'null';
+  if (typeof v === 'string') return JSON.stringify(v);
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  return 'unknown';
+}
+
+function toTypeName(name) {
+  const cleaned = String(name).replace(/[^A-Za-z0-9_]/g, '_');
+  if (/^[0-9]/.test(cleaned)) return `_${cleaned}`;
+  return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+}
+
+// Public: given a schema and optional type name, return a .d.ts source.
+function toTypeScript(schema, opts) {
+  const options = opts || {};
+  const rootName = toTypeName(options.name || 'Data');
+  const defs = schema && (schema.$defs || schema.definitions);
+
+  const defLines = [];
+  if (defs && typeof defs === 'object') {
+    for (const [defName, defSchema] of Object.entries(defs)) {
+      const body = renderValueType(defSchema, defs, 0);
+      defLines.push(`export type ${toTypeName(defName)} = ${body};`);
+    }
+  }
+
+  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};`;
+
+  return `// Auto-generated by ata-validator — do not edit.
+${defLines.length ? defLines.join('\n\n') + '\n\n' : ''}${rootDecl}
+
+export interface ValidationError {
+  keyword?: string;
+  instancePath?: string;
+  schemaPath?: string;
+  params?: Record<string, unknown>;
+  message?: string;
+}
+
+export interface ValidResult {
+  valid: true;
+  errors: readonly never[];
+}
+export interface InvalidResult {
+  valid: false;
+  errors: readonly ValidationError[];
+}
+export type Result = ValidResult | InvalidResult;
+
+export declare function isValid(data: unknown): data is ${rootName};
+export declare function validate(data: unknown): Result;
+declare const _default: { validate: typeof validate; isValid: typeof isValid };
+export default _default;
+`;
+}
+
+module.exports = { toTypeScript };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "0.10.3",
+  "version": "0.11.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",
@@ -23,6 +23,9 @@
     "./package.json": "./package.json"
   },
   "sideEffects": false,
+  "bin": {
+    "ata": "bin/ata.js"
+  },
   "browser": {
     "pkg-prebuilds": false
   },