ata-validator 0.12.5 → 0.13.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to ata-validator are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/), and this project adheres to semantic versioning.
+
+## 0.13.0 — 2026-05-09
+
+### Added
+
+- **`ata build <glob>`** subcommand for project-wide AOT compilation. Compiles each matched schema to a per-file `.compiled.mjs` ESM module with a sibling `.d.mts` TypeScript declaration. Production bundles can drop the runtime ata-validator dependency entirely and import compiled validators as plain ESM modules.
+- **`ata-validator/build` programmatic subpath export.** `import { build, watch } from 'ata-validator/build'` exposes the same engine the CLI uses, so build pipelines and bundler plugins can integrate without going through the CLI.
+- **CLI flags for `ata build`:** `--out-dir`, `--suffix`, `--format esm|cjs`, `--abort-early`, `--no-types`, `--cache-file`, `--check`, `--watch`, `--max-size`, `--strict`.
+- **Incremental cache** via content-hashed `--cache-file`. Second run on unchanged inputs skips compilation.
+- **YAML schema support** when the `yaml` peer dependency is installed (optional). `.yaml` and `.yml` inputs parse the same as `.json`.
+- **AOT vs AJV-runtime benchmark** at `benchmark/bench_aot_vs_ajv.mjs`. On the included fixtures, ata-AOT outputs are 25-56x smaller gzipped than the AJV runtime, cold start is ~2x faster, throughput is 2-4.5x faster, and compile time is 71-246x shorter.
+
+### Fixed
+
+- **Standalone modules now correctly serialize closure-bound helpers** (RegExp, Set, sub-validator functions, branch-property arrays) into the emitted `.mjs`. Previously, schemas using `patternProperties`, `propertyNames` with regex, or `unevaluatedProperties` with `anyOf`/`oneOf` produced standalone output that referenced undefined variables (`_ppf0_0`, `_re*`, `_es*`, `_bk*`) and threw `ReferenceError` at runtime. The runtime validation path was unaffected.
+
+### Notes
+
+- The runtime `Validator` API and the `ata-validator/compat` AJV-shim remain unchanged. Existing dynamic-schema users have no migration to do.
+- Bundler plugins (ata-vite v0.2.0, ata-webpack, ata-codemod-ajv) are out of scope for this release and will land in 0.14.0+.

package/README.md

@@ -1,161 +1,57 @@
-<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)** | **[Framework integrations](docs/integrations/)** | **[Contributing](CONTRIBUTING.md)**
-
-## Performance
-
-### Simple Schema (7 properties, type + format + range + nested object)
-
-| Scenario | ata | ajv | |
-|---|---|---|---|
-| **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 | 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 | 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)
-
-### unevaluatedProperties / unevaluatedItems
-
-| Scenario | ata | ajv | |
-|---|---|---|---|
-| **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)
-
-### vs Ecosystem (Zod, Valibot, TypeBox)
-
-| Scenario | ata | ajv | typebox | zod | valibot |
-|---|---|---|---|---|---|
-| **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. 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.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** |
+Compile JSON Schema files into per-schema ESM modules at build time. Drop the runtime validator from your production bundle. Optional runtime API for dynamic schemas.
 
-### Real-World Scenarios
+[![npm](https://img.shields.io/npm/v/ata-validator)](https://www.npmjs.com/package/ata-validator)
+[![License](https://img.shields.io/npm/l/ata-validator)](LICENSE)
 
-| Scenario | ata | ajv | |
-|---|---|---|---|
-| **Serverless cold start** (50 schemas) | 0.087ms | 3.67ms | **ata 42x faster** |
-| **ReDoS protection** (`^(a+)+$`) | 0.3ms | 765ms | **ata immune (RE2)** |
-| **Batch NDJSON** (10K items, multi-core) | 13.4M/sec | 5.1M/sec | **ata 2.6x faster** |
-| **Fastify startup** (5 routes) | 0.5ms | 6.0ms | **ata 12x faster** |
+## Quick start
 
-> Isolated single-schema benchmarks. Results vary by workload and hardware.
-
-### How it works
-
-**Combined single-pass validator**: ata compiles schemas into a single function that validates and collects errors in one pass. Valid data returns `VALID_RESULT` with zero allocation. Invalid data collects errors inline with pre-allocated frozen error objects - no double validation, no try/catch (3.3x V8 deopt). Lazy compilation defers all work to first usage - constructor is near-zero cost.
-
-**JS codegen**: Schemas are compiled to monolithic JS functions (like ajv). Full keyword support including `patternProperties`, `dependentSchemas`, `propertyNames`, `unevaluatedProperties`, `unevaluatedItems`, cross-schema `$ref` with `$id` registry, and Draft 7 auto-detection. Three-tier hybrid approach for unevaluated keywords: compile-time resolution for static schemas, bitmask tracking for dynamic ones. charCodeAt prefix matching replaces regex for simple patterns (4x faster). Merged key iteration loops (patternProperties + propertyNames + additionalProperties in a single `for..in`).
-
-**V8 TurboFan optimizations**: Destructuring batch reads, `undefined` checks instead of `in` operator, context-aware type guard elimination, property hoisting to local variables, tiered uniqueItems (nested loop for small arrays), inline key comparison for small property sets (no Set.has overhead).
-
-**Adaptive simdjson**: For large documents (>8KB) with selective schemas, simdjson On Demand seeks only the needed fields - skipping irrelevant data at GB/s speeds.
-
-### $dynamicRef / $dynamicAnchor / $anchor
+```bash
+npm install --save-dev ata-validator
+npx ata build 'schemas/*.json' --out-dir src/generated
+```
 
-| Scenario | ata | ajv | |
-|---|---|---|---|
-| **$dynamicRef tree** valid | 22ns | 54ns | **ata 2.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** |
+In your code:
 
-Self-recursive named functions for $dynamicRef, compile-time cross-schema resolution, zero-wrapper hybrid path. [Benchmark code](benchmark/bench_dynamicref_vs_ajv.mjs)
+```ts
+import { validate, isValid, type User } from './generated/user.compiled.mjs'
 
-### JSON Schema Test Suite
+if (isValid(req.body)) {
+  const user: User = req.body
+  // ...
+}
+```
 
-**98.5%** pass rate (1172/1190) on official [JSON Schema Test Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite) (Draft 2020-12), excluding remote refs and vocabulary (intentionally unsupported). **95.3%** on [@exodus/schemasafe](https://github.com/ExodusMovement/schemasafe) test suite.
+The `.compiled.mjs` modules are self-contained: zero runtime dependency on ata-validator, fully tree-shakeable, with TypeScript types emitted alongside.
 
-## When to use ata
+## Why AOT
 
-- **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
-- **Serverless / cold starts** - 6,904x faster compilation, 5,148x faster first validation
-- **Security-sensitive apps** - RE2 regex, immune to ReDoS attacks
-- **Batch/streaming validation** - NDJSON log processing, data pipelines (2.6x faster)
-- **Standard Schema V1** - native support for Fastify v5, tRPC, TanStack
-- **C/C++ embedding** - native library, no JS runtime needed
+| Dimension | Schema | ata-AOT | AJV-runtime | Difference |
+|---|---|---|---|---|
+| Bundle (gzipped) | simple | 955 B | 52.7 KB | 56x smaller |
+| Bundle (gzipped) | complex | 1.6 KB | 52.7 KB | 32x smaller |
+| Cold start | simple | 21 ms | 38 ms | 1.8x faster |
+| Throughput (10M ops) | simple | 345 Mops/s | 116 Mops/s | 3.0x faster |
+| Compile time | simple | 6 µs | 1.5 ms | 246x faster |
 
-## When to use ajv
+Reproduce on your machine with `npm run bench:aot-vs-ajv`. Numbers measured on Apple M4 Pro, Node 25.2.1.
 
-- **Existing ajv ecosystem** - plugins, custom keywords, large community
-- **Full unevaluatedProperties/Items** - ata covers most cases but some edge cases remain
+The wins are largest on bundle size and compile time because AOT moves work from runtime to build time. Throughput and cold start are also faster because the compiled validator is a tight straight-line function with no schema-walk overhead.
 
-## Features
+## When to use the runtime API instead
 
-- **Hybrid validator**: 4.1x faster than ajv, up to 70x faster on $dynamicRef - zero-wrapper hybrid path for valid data (no allocation), combined codegen for error collection. Schema compilation cache for repeated schemas
-- **$dynamicRef / $dynamicAnchor / $anchor**: Full Draft 2020-12 dynamic reference support. Self-recursive named functions, compile-time cross-schema resolution (42/42 spec tests)
-- **Cross-schema `$ref`**: `schemas` option and `addSchema()` API. Compile-time resolution with `$id` registry, zero runtime overhead
-- **Draft 7 support**: Auto-detects `$schema` field, normalizes `dependencies`/`additionalItems`/`definitions` transparently
-- **Multi-core**: Parallel validation across all CPU cores - 13.4M validations/sec
-- **simdjson**: SIMD-accelerated JSON parsing at GB/s speeds, adaptive On Demand for large docs
-- **RE2 regex**: Linear-time guarantees, immune to ReDoS attacks (2391x faster on pathological input)
-- **V8-optimized codegen**: Destructuring batch reads, type guard elimination, property hoisting
-- **Standard Schema V1**: Compatible with Fastify, tRPC, TanStack, Drizzle
-- **Zero-copy paths**: Buffer and pre-padded input support - no unnecessary copies
-- **Defaults + coercion**: `default` values, `coerceTypes`, `removeAdditional` support
-- **C/C++ library**: Native API for non-Node.js environments
-- **98.5% spec compliant**: Draft 2020-12
+`ata build` is for schemas you know at build time. If your schemas are user-supplied at runtime (form builders, no-code platforms, dynamic API ingestion), use the runtime API:
 
-## Installation
+```js
+import { Validator } from 'ata-validator'
 
-```bash
-npm install ata-validator
+const v = new Validator(schema)
+const result = v.validate(data)
 ```
 
+The runtime API is unchanged from previous releases. AJV-shim users continue importing from `ata-validator/compat`.
+
 ## Usage
 
 ### Node.js
@@ -265,6 +161,14 @@ CLI options:
 | `--abort-early` | off | Generate the stub-error variant (~0.5 KB gzipped) |
 | `--no-types` | off | Skip the `.d.mts` / `.d.cts` output |
 
+For a project with many schemas, `ata build <glob>` compiles them all in one command:
+
+```bash
+npx ata build 'schemas/*.json' --out-dir build/validators --check
+```
+
+Run with `--watch` during development for incremental rebuilds.
+
 Typical bundle sizes (10-field user schema, gzipped):
 
 | Variant | Size | Notes |

package/bin/ata.js

@@ -8,20 +8,34 @@ function usage() {
   process.stdout.write(`ata-validator CLI
 
 Usage:
-  ata compile <schema-file> [options]
+  ata compile <schema-file> [options]   Compile one schema to a standalone module.
+  ata build   <glob>...    [options]    Compile a project's schemas (glob pattern) per file.
 
-Options:
+Compile 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)
+
+Build options:
+  --out-dir <dir>         Write outputs into this directory instead of alongside sources
+  --suffix <str>          Output filename suffix (default: ".compiled")
+  -f, --format <fmt>      Module format: esm | cjs. Default: esm
+  --abort-early           Use stub errors (smallest bundle)
+  --check                 Check (don't write); exit 1 if any output is stale
+  --cache-file <path>     Cache file for incremental builds (default: cache disabled)
+  --max-size <bytes>      Fail build if any compiled module exceeds this gzipped size
+  --strict                Treat any AOT-incompatible schema as a build error (default: skip + warn)
+  --watch                 Re-emit on schema change (Ctrl-C to exit)
+  --no-types              Skip .d.mts/.d.cts emission alongside compiled modules
+
   -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
+  ata build 'schemas/*.json'
+  ata build 'src/**/*.schema.json' --out-dir build/validators
 `);
 }
 
@@ -35,6 +49,21 @@ function parseArgs(argv) {
     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 === '--check') { out.opts.check = true; continue; }
+    if (a === '--strict') { out.opts.strict = true; continue; }
+    if (a === '--out-dir') { out.opts.outDir = argv[++i]; continue; }
+    if (a === '--suffix') { out.opts.suffix = argv[++i]; continue; }
+    if (a === '--cache-file') { out.opts.cacheFile = argv[++i]; continue; }
+    if (a === '--max-size') {
+      const v = argv[++i];
+      const n = Number(v);
+      if (!Number.isFinite(n) || n <= 0 || !Number.isInteger(n)) {
+        throw new Error(`--max-size requires a positive integer (got "${v}")`);
+      }
+      out.opts.maxSize = n;
+      continue;
+    }
+    if (a === '--watch') { out.opts.watch = true; continue; }
     if (a.startsWith('-')) { throw new Error(`Unknown option: ${a}`); }
     out._.push(a);
   }
@@ -113,6 +142,73 @@ function cmdCompile(args) {
   }
 }
 
+function cmdBuild(args) {
+  if (args._.length === 0) {
+    process.stderr.write('error: missing <glob>\n\n');
+    usage();
+    process.exit(1);
+  }
+  const buildLib = require('../lib/aot-build');
+  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 buildOpts = {
+    globs: args._,
+    format,
+    outDir: args.opts.outDir,
+    suffix: args.opts.suffix,
+    abortEarly: !!args.opts.abortEarly,
+    check: !!args.opts.check,
+    maxSize: args.opts.maxSize,
+    strict: !!args.opts.strict,
+    types: args.opts.types,
+    cacheFile: args.opts.cacheFile,
+  };
+
+  const printReport = (report) => {
+    if (args.opts.check) {
+      process.stdout.write(`ata: check — ${report.cached.length} up to date, ${report.staleCount} stale\n`);
+      return;
+    }
+    for (const c of report.compiled) {
+      process.stdout.write(`ata: ${c.input} -> ${c.output} (${c.bytes.toLocaleString()} bytes)\n`);
+    }
+    for (const c of report.cached) {
+      process.stdout.write(`ata: cached  ${c.input}\n`);
+    }
+    for (const s of report.skipped) {
+      process.stdout.write(`ata: skipped ${s.input}: ${s.reason}\n`);
+    }
+    for (const f of report.failed) {
+      process.stderr.write(`ata: failed  ${f.input}: ${f.error}\n`);
+    }
+  };
+
+  if (args.opts.watch) {
+    let handle;
+    buildLib.watch(buildOpts, printReport).then((h) => {
+      handle = h;
+      process.stdout.write('ata: watching for changes (Ctrl-C to exit)\n');
+    });
+    process.on('SIGINT', () => {
+      if (handle) handle.close();
+      process.exit(0);
+    });
+    return;
+  }
+
+  buildLib.build(buildOpts).then((report) => {
+    printReport(report);
+    if (args.opts.check && report.staleCount > 0) process.exit(1);
+    if (report.failed.length > 0) process.exit(1);
+  }).catch((e) => {
+    process.stderr.write(`error: ${e.message}\n`);
+    process.exit(1);
+  });
+}
+
 function main() {
   const argv = process.argv.slice(2);
   if (argv.length === 0) { usage(); process.exit(0); }
@@ -136,6 +232,11 @@ function main() {
     return;
   }
 
+  if (cmd === 'build') {
+    cmdBuild(args);
+    return;
+  }
+
   process.stderr.write(`error: unknown command "${cmd}"\n\n`);
   usage();
   process.exit(1);

package/build.d.ts

@@ -0,0 +1,63 @@
+export interface BuildOptions {
+  /** Glob patterns to expand into input schema files. */
+  globs: string[];
+  /** Module format for compiled outputs. Default: 'esm'. */
+  format?: 'esm' | 'cjs';
+  /** Write outputs into this directory instead of alongside sources. */
+  outDir?: string;
+  /** Output filename suffix. Default: '.compiled'. */
+  suffix?: string;
+  /** Use stub error functions for the smallest output. Default: false. */
+  abortEarly?: boolean;
+  /** Path to incremental cache file. Default: cache disabled. */
+  cacheFile?: string;
+  /** When true, do not write outputs; only report stale count. */
+  check?: boolean;
+  /** Maximum gzipped output size per compiled module, in bytes. */
+  maxSize?: number;
+  /** When true, AOT-incompatible schemas become failures (default: skipped). */
+  strict?: boolean;
+  /** Emit a .d.mts/.d.cts/.d.ts sibling for each compiled module. Default: true. */
+  types?: boolean;
+}
+
+export interface CompiledEntry {
+  input: string;
+  output: string;
+  bytes: number;
+  gzipBytes?: number;
+}
+
+export interface CachedEntry {
+  input: string;
+  output: string;
+}
+
+export interface SkippedEntry {
+  input: string;
+  reason: string;
+}
+
+export interface FailedEntry {
+  input: string;
+  error: string;
+}
+
+export interface BuildReport {
+  compiled: CompiledEntry[];
+  cached: CachedEntry[];
+  skipped: SkippedEntry[];
+  failed: FailedEntry[];
+  /** Only set when opts.check === true. */
+  staleCount?: number;
+}
+
+export function build(opts: BuildOptions): Promise<BuildReport>;
+export function expandGlobs(globs: string[]): Promise<string[]>;
+export function parseSchemaFile(filePath: string): unknown;
+export function outputPathFor(input: string, opts: { format?: 'esm' | 'cjs'; outDir?: string; suffix?: string }): string;
+
+export interface WatchHandle {
+  close(): void;
+}
+export function watch(opts: BuildOptions, onReport?: (r: BuildReport) => void): Promise<WatchHandle>;

package/build.js

@@ -0,0 +1,6 @@
+'use strict';
+
+// Public subpath: `ata-validator/build`
+// Re-exports the programmatic build API. The CLI in bin/ata.js is a thin
+// wrapper around the same module.
+module.exports = require('./lib/aot-build');

package/build.mjs

@@ -0,0 +1,8 @@
+import mod from './build.js';
+
+export const build = mod.build;
+export const expandGlobs = mod.expandGlobs;
+export const parseSchemaFile = mod.parseSchemaFile;
+export const outputPathFor = mod.outputPathFor;
+export const watch = mod.watch;
+export default mod;

package/index.d.ts

@@ -140,8 +140,12 @@ export class Validator {
    */
   static bundleStandalone(schemas: object[], options?: BundleStandaloneOptions): string;
 
-  /** Bundle multiple schemas with deduplicated shared templates. Smaller output than bundle(). */
-  static bundleCompact(schemas: object[], options?: ValidatorOptions): string;
+  /**
+   * Bundle multiple schemas with deduplicated shared templates. Smaller output
+   * than bundle(). Accepts the same options as bundleStandalone, including
+   * `format: 'esm' | 'cjs'` and cross-schema `$ref` resolution.
+   */
+  static bundleCompact(schemas: object[], options?: BundleStandaloneOptions): string;
 
   /** Load a bundle created by Validator.bundle(). Returns array of Validator instances. */
   static loadBundle(mods: object[], schemas: object[], options?: ValidatorOptions): Validator[];

package/index.js

@@ -964,6 +964,32 @@ module.exports = { boolFn, hybridFactory, errFn };
       }
     }
 
+    // Serialize closure vars referenced in _fn body: regex, sub-validators, sets.
+    let closureDecls = '';
+    if (jsFn._closures && jsFn._closures.length > 0) {
+      const lines = [];
+      for (const { name, val } of jsFn._closures) {
+        if (Array.isArray(val)) {
+          lines.push(`const ${name} = ${JSON.stringify(val)};`);
+          continue;
+        }
+        if (val instanceof RegExp) {
+          const flags = val.flags;
+          lines.push(`const ${name} = new RegExp(${JSON.stringify(val.source)}${flags ? ', ' + JSON.stringify(flags) : ''});`);
+        } else if (val instanceof Set) {
+          lines.push(`const ${name} = new Set(${JSON.stringify([...val])});`);
+        } else if (typeof val === 'function') {
+          // new Function('_ppv', body) — extract body from toString()
+          const str = val.toString();
+          // Matches: "function anonymous(_ppv\n) {\nbody\n}" or "function(_ppv){body}"
+          const m = str.match(/^function[^(]*\([^)]*\)\s*\{([\s\S]*)\}$/)
+          const body = m ? m[1].trim() : str;
+          lines.push(`const ${name} = function(_ppv) { ${body} };`);
+        }
+      }
+      if (lines.length) closureDecls = lines.join('\n') + '\n';
+    }
+
     const validBody = errCore
       ? 'return _fn(data) ? VALID : { valid: false, errors: errFn(data, true).errors }'
       : 'return _fn(data) ? VALID : ABORT';
@@ -978,7 +1004,7 @@ module.exports = { boolFn, hybridFactory, errFn };
 ${_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) {
+${closureDecls}const _fn = function(d) {
   ${src}
 };
 ${errCore}function isValid(data) { return _fn(data); }
@@ -1187,10 +1213,12 @@ Validator.bundle = function (schemas, opts) {
 
 // Zero-dependency self-contained bundle — no require('ata-validator') needed at runtime.
 // opts.format: 'cjs' (default) or 'esm'.
+// opts.formats: { name: fn } — embedded in the output via Function#toString.
 Validator.bundleStandalone = function (schemas, opts) {
-  // Cross-schema $ref resolution: every Validator in the bundle needs to know
-  // about the others so $ref to a sibling $id can resolve at compile time.
-  const bundleOpts = { ...(opts || {}), schemas };
+  // Cross-schema $ref resolution: only meaningful when at least one schema has
+  // an $id. Skip the schemas-as-map plumbing when none of them do.
+  const haveIds = schemas.some((s) => s && typeof s === 'object' && s.$id);
+  const bundleOpts = haveIds ? { ...(opts || {}), schemas } : (opts || {});
   const format = (opts && opts.format) || 'cjs';
   const R = "Object.freeze({valid:true,errors:Object.freeze([])})";
   const fns = schemas.map((schema) => {
@@ -1201,12 +1229,25 @@ Validator.bundleStandalone = function (schemas, opts) {
     const jsErrFn = compileToJSCodegenWithErrors(
       typeof schema === "string" ? JSON.parse(schema) : schema,
       v._schemaMap,
+      v._userFormats,
     );
     const errBody =
       jsErrFn && jsErrFn._errSource
         ? jsErrFn._errSource
         : "return{valid:false,errors:[{code:'error',path:'',message:'validation failed'}]}";
-    return `(function(R){var E=function(d){var _all=true;${errBody}};return function(d){${jsFn._hybridSource}}})(R)`;
+    // Serialize custom format closures so the bundle has no runtime dep on ata.
+    let preamble = '';
+    if (jsFn._formatClosures) {
+      preamble = jsFn._formatClosures
+        .map(({ name, fn }) => `var ${name}=${fn.toString()};`)
+        .join('\n');
+    }
+    if (opts && opts.verbose) {
+      // Embed the schema and a small resolver so errors carry parentSchema.
+      const schemaLit = JSON.stringify(typeof schema === 'string' ? JSON.parse(schema) : schema);
+      return `(function(R){${preamble}var _S=${schemaLit};function _PS(p){if(!p||p[0]!=='#')return undefined;var s=p.slice(1);if(!s)return _S;var ps=s.split('/').filter(Boolean).map(function(x){return x.replace(/~1/g,'/').replace(/~0/g,'~')});var t=_S;for(var i=0;i<ps.length-1;i++){if(t==null||typeof t!=='object')return undefined;t=t[ps[i]]}return t}var E=function(d){var _all=true;${errBody}};var _v=function(d){${jsFn._hybridSource}};return function(d){var r=_v(d);if(r&&r.valid===false&&r.errors){var es=[];for(var i=0;i<r.errors.length;i++){var e=r.errors[i];es.push(Object.assign({},e,{parentSchema:_PS(e.schemaPath)}))}return{valid:false,errors:es}}return r}})(R)`;
+    }
+    return `(function(R){${preamble}var E=function(d){var _all=true;${errBody}};return function(d){${jsFn._hybridSource}}})(R)`;
   });
   const arr = `[${fns.join(",")}]`;
   if (format === 'esm') {
@@ -1217,15 +1258,20 @@ Validator.bundleStandalone = function (schemas, opts) {
 
 // Compact bundle: deduplicated code. Shared template functions + per-schema params.
 // Much smaller file → faster V8 parse → faster startup.
+// opts.format: 'cjs' (default) or 'esm'.
 Validator.bundleCompact = function (schemas, opts) {
+  const haveIds = schemas.some((s) => s && typeof s === 'object' && s.$id);
+  const bundleOpts = haveIds ? { ...(opts || {}), schemas } : (opts || {});
+  const format = (opts && opts.format) || 'cjs';
   // Analyze schemas and group by structure
   const entries = schemas.map((schema) => {
-    const v = new Validator(schema, opts);
+    const v = new Validator(schema, bundleOpts);
     v._ensureCompiled();
     const jsFn = v._jsFn;
     if (!jsFn || !jsFn._hybridSource) return null;
     const jsErrFn = compileToJSCodegenWithErrors(
       typeof schema === "string" ? JSON.parse(schema) : schema,
+      v._schemaMap,
     );
     return {
       hybrid: jsFn._hybridSource,
@@ -1260,31 +1306,38 @@ Validator.bundleCompact = function (schemas, opts) {
   });
 
   // Generate compact bundle
-  let out = "'use strict';\n";
-  out += "var R=Object.freeze({valid:true,errors:Object.freeze([])});\n";
+  const isEsm = format === 'esm';
+  let out = isEsm
+    ? "// Auto-generated by ata-validator — do not edit\n"
+    : "'use strict';\n";
+  const declKW = isEsm ? "const" : "var";
+  out += `${declKW} R=Object.freeze({valid:true,errors:Object.freeze([])});\n`;
 
   // Shared hybrid factories
-  out += "var H=[\n";
+  out += `${declKW} H=[\n`;
   out += bodies
     .map((b) => `function(R,E){return function(d){${b}}}`)
     .join(",\n");
   out += "\n];\n";
 
   // Shared error functions
-  out += "var EF=[\n";
+  out += `${declKW} EF=[\n`;
   out += errBodies.map((b) => `function(d){var _all=true;${b}}`).join(",\n");
   out += "\n];\n";
 
   // Build validators from shared templates
-  out += "module.exports=[";
-  out += indices
+  const arrBody = indices
     .map(([hi, ei]) => {
       if (hi < 0) return "null";
       if (ei >= 0) return `H[${hi}](R,EF[${ei}])`;
       return `H[${hi}](R,function(){return{valid:false,errors:[]}})`;
     })
     .join(",");
-  out += "];\n";
+  if (isEsm) {
+    out += `const validators=[${arrBody}];\nexport default validators;\nexport { validators };\n`;
+  } else {
+    out += `module.exports=[${arrBody}];\n`;
+  }
 
   return out;
 };

package/lib/aot-build.js

@@ -0,0 +1,206 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+const { Validator } = require('..');
+
+async function expandGlobs(globs) {
+  const out = [];
+  for (const g of globs) {
+    if (typeof fs.promises.glob === 'function') {
+      // Node 22+
+      for await (const f of fs.promises.glob(g)) out.push(path.resolve(f));
+    } else {
+      // Node 18-21 fallback: simple non-recursive directory + extension match
+      // Pattern accepted: '<dir>/*.<ext>' or absolute file path.
+      if (fs.existsSync(g) && fs.statSync(g).isFile()) {
+        out.push(path.resolve(g));
+        continue;
+      }
+      const m = g.match(/^(.*?)(?:\/\*\.(.+))?$/);
+      const dir = m && m[1] ? m[1] : '.';
+      const ext = m && m[2] ? '.' + m[2] : null;
+      if (!fs.existsSync(dir)) continue;
+      for (const entry of fs.readdirSync(dir)) {
+        if (ext && !entry.endsWith(ext)) continue;
+        const full = path.join(dir, entry);
+        if (fs.statSync(full).isFile()) out.push(path.resolve(full));
+      }
+    }
+  }
+  return [...new Set(out)];
+}
+
+function parseSchemaFile(filePath) {
+  const text = fs.readFileSync(filePath, 'utf8');
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.json') return JSON.parse(text);
+  if (ext === '.yaml' || ext === '.yml') {
+    let yaml;
+    try { yaml = require('yaml'); }
+    catch { throw new Error(`install the 'yaml' package to compile YAML schemas (file: ${filePath})`); }
+    return yaml.parse(text);
+  }
+  throw new Error(`unsupported schema extension: ${ext} (file: ${filePath})`);
+}
+
+function outputPathFor(input, opts) {
+  const suffix = opts.suffix || '.compiled';
+  const ext = opts.format === 'cjs' ? '.cjs' : '.mjs';
+  const dir = opts.outDir || path.dirname(input);
+  const base = path.basename(input, path.extname(input));
+  // Strip a trailing ".schema" for cleaner output names: foo.schema.json -> foo.compiled.mjs
+  const stem = base.endsWith('.schema') ? base.slice(0, -('.schema'.length)) : base;
+  return path.join(dir, stem + suffix + ext);
+}
+
+function readCache(cacheFile) {
+  if (!cacheFile || !fs.existsSync(cacheFile)) return {};
+  try { return JSON.parse(fs.readFileSync(cacheFile, 'utf8')); } catch { return {}; }
+}
+
+function writeCache(cacheFile, data) {
+  if (!cacheFile) return;
+  fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+  fs.writeFileSync(cacheFile, JSON.stringify(data, null, 2));
+}
+
+function hashContent(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex').slice(0, 32);
+}
+
+async function build(opts) {
+  const globs = opts.globs || [];
+  if (globs.length === 0) throw new Error('build: at least one glob required');
+  const format = opts.format || 'esm';
+  const inputs = await expandGlobs(globs);
+  const cache = readCache(opts.cacheFile);
+  const newCache = {};
+
+  const compiled = [];
+  const cached = [];
+  const skipped = [];
+  const failed = [];
+
+  for (const input of inputs) {
+    try {
+      const raw = fs.readFileSync(input);
+      const inputHash = hashContent(raw);
+      const output = outputPathFor(input, { ...opts, format });
+      const cacheEntry = cache[input];
+      if (opts.check) {
+        const upToDate = (
+          cacheEntry &&
+          cacheEntry.inputHash === inputHash &&
+          cacheEntry.output === output &&
+          fs.existsSync(output) &&
+          cacheEntry.outputHash === hashContent(fs.readFileSync(output))
+        );
+        if (upToDate) {
+          cached.push({ input, output });
+        }
+        continue;
+      }
+      if (
+        cacheEntry &&
+        cacheEntry.inputHash === inputHash &&
+        cacheEntry.output === output &&
+        fs.existsSync(output) &&
+        cacheEntry.outputHash === hashContent(fs.readFileSync(output))
+      ) {
+        cached.push({ input, output });
+        newCache[input] = cacheEntry;
+        continue;
+      }
+      const schema = parseSchemaFile(input);
+      const v = new Validator(schema);
+      const src = v.toStandaloneModule({ format, abortEarly: !!opts.abortEarly });
+      if (!src) {
+        const reason = 'schema is not AOT-compatible (toStandaloneModule returned null)';
+        if (opts.strict) failed.push({ input, error: reason });
+        else skipped.push({ input, reason });
+        continue;
+      }
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.writeFileSync(output, src);
+      const outBytes = Buffer.byteLength(src, 'utf8');
+      const gz = zlib.gzipSync(src);
+      const gzBytes = gz.length;
+      if (typeof opts.maxSize === 'number' && gzBytes > opts.maxSize) {
+        // Roll back the write so a failed build doesn't leave a stale artifact.
+        try { fs.unlinkSync(output); } catch {}
+        failed.push({ input, error: `output ${output} exceeds --max-size: ${gzBytes} > ${opts.maxSize} (gzipped bytes)` });
+        continue;
+      }
+      compiled.push({ input, output, bytes: outBytes, gzipBytes: gzBytes });
+      if (opts.types !== false) {
+        const { toTypeScript } = require('./ts-gen');
+        const stem = path.basename(input, path.extname(input)).replace(/\.schema$/, '');
+        const typeName = stem
+          .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 base = output.slice(0, output.length - ext.length);
+        fs.writeFileSync(base + dtsExt, dts);
+      }
+      newCache[input] = {
+        inputHash,
+        output,
+        outputHash: hashContent(Buffer.from(src, 'utf8')),
+      };
+    } catch (e) {
+      failed.push({ input, error: e.message });
+    }
+  }
+
+  if (opts.check) {
+    const staleCount = inputs.length - cached.length;
+    return { compiled: [], cached, skipped, failed, staleCount };
+  }
+
+  writeCache(opts.cacheFile, newCache);
+
+  return { compiled, cached, skipped, failed };
+}
+
+async function watch(opts, onReport) {
+  const initial = await build(opts);
+  if (typeof onReport === 'function') onReport(initial);
+
+  const inputs = await expandGlobs(opts.globs || []);
+  const dirs = [...new Set(inputs.map((p) => path.dirname(p)))];
+  let debounceTimer = null;
+
+  const runOnce = async () => {
+    debounceTimer = null;
+    try {
+      const r = await build(opts);
+      if (typeof onReport === 'function') onReport(r);
+    } catch (e) {
+      if (typeof onReport === 'function') onReport({ compiled: [], cached: [], skipped: [], failed: [{ input: '<watch>', error: e.message }] });
+    }
+  };
+
+  const watchers = dirs.map((d) => fs.watch(d, (_event, filename) => {
+    if (!filename) return;
+    const ext = path.extname(filename).toLowerCase();
+    if (ext !== '.json' && ext !== '.yaml' && ext !== '.yml') return;
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(runOnce, 100);
+  }));
+
+  return {
+    close() {
+      if (debounceTimer) clearTimeout(debounceTimer);
+      for (const w of watchers) w.close();
+    },
+  };
+}
+
+module.exports = { build, expandGlobs, parseSchemaFile, outputPathFor, watch };

package/lib/js-compiler.js

@@ -946,6 +946,29 @@ function compileToJSCodegen(schema, schemaMap, userFormats) {
     boolFn._source = helperStr + body
     boolFn._preambleSource = preambleStr
     boolFn._hybridSource = helperStr + hybridBody
+    // Custom-format closure entries that the bundle output needs to recreate.
+    // Stored as { name, fn } so consumers can serialize via Function#toString.
+    if (ctx.userFormats) {
+      const fmtEntries = []
+      for (let i = 0; i < closureNames.length; i++) {
+        if (closureNames[i].startsWith('_uf_')) {
+          fmtEntries.push({ name: closureNames[i], fn: closureValues[i] })
+        }
+      }
+      if (fmtEntries.length) boolFn._formatClosures = fmtEntries
+    }
+    // Closure variables (regex, sub-validators, sets) referenced in _source that
+    // standalone module output must declare. Excludes _cpLen (emitted by _CP_LEN_SOURCE)
+    // and _uf_* (emitted via _formatClosures).
+    {
+      const entries = []
+      for (let i = 0; i < closureNames.length; i++) {
+        const name = closureNames[i]
+        if (name === '_cpLen' || name.startsWith('_uf_')) continue
+        entries.push({ name, val: closureValues[i] })
+      }
+      if (entries.length) boolFn._closures = entries
+    }
 
     return boolFn
   } catch {
@@ -2448,7 +2471,7 @@ function genCharCodeSwitch(keys, v) {
 // --- Error-collecting codegen: same checks, but pushes errors instead of returning false ---
 // Returns a function: (data, allErrors) => { valid, errors }
 // Valid path is still fast — only error path does extra work.
-function compileToJSCodegenWithErrors(schema, schemaMap) {
+function compileToJSCodegenWithErrors(schema, schemaMap, userFormats) {
   // Bail on unevaluated keywords — error codegen doesn't support them yet
   if (typeof schema === 'object' && schema !== null) {
     const s = JSON.stringify(schema)
@@ -2509,7 +2532,7 @@ function compileToJSCodegenWithErrors(schema, schemaMap) {
     }
   }
 
-  const ctx = { varCounter: 0, helperCode: [], rootDefs: eRootDefs, refStack: new Set(), schemaMap: schemaMap || null, anchors: eAnchors, rootSchema: schema }
+  const ctx = { varCounter: 0, helperCode: [], rootDefs: eRootDefs, refStack: new Set(), schemaMap: schemaMap || null, anchors: eAnchors, rootSchema: schema, userFormats: userFormats || null }
   ctx.helperCode.push('const _cpLen=s=>{let n=0;for(const _ of s)n++;return n}')
   const lines = []
   genCodeE(schema, 'd', '', lines, ctx, '#')
@@ -2733,15 +2756,23 @@ function genCodeE(schema, v, pathExpr, lines, ctx, schemaPrefix) {
   }
   if (schema.format) {
     const fc = FORMAT_CODEGEN[schema.format]
+    const failPush = `_e.push({keyword:'format',instancePath:${pathExpr||'""'},schemaPath:'${schemaPrefix}/format',params:{format:'${esc(schema.format)}'},message:'must match format "${esc(schema.format)}"'});if(!_all)return{valid:false,errors:_e}`
     // Format errors use the boolean codegen — just wrap with error push
     if (fc) {
       const ri = ctx.varCounter++
       const boolLines = []
       boolLines.push(fc(v, isStr))
       // Replace `return false` with error push in the format check
-      const fmtCode = boolLines.join(';').replace(/return false/g,
-        `{_e.push({keyword:'format',instancePath:${pathExpr||'""'},schemaPath:'${schemaPrefix}/format',params:{format:'${esc(schema.format)}'},message:'must match format "${esc(schema.format)}"'});if(!_all)return{valid:false,errors:_e}}`)
+      const fmtCode = boolLines.join(';').replace(/return false/g, `{${failPush}}`)
       lines.push(fmtCode)
+    } else if (ctx.userFormats && typeof ctx.userFormats[schema.format] === 'function') {
+      // User-supplied format checker on the error path. Same closure plumbing
+      // as the boolean codegen — but error codegen has no closure factory, so
+      // bundle output serializes the function via Function#toString separately.
+      const safeName = schema.format.replace(/[^a-zA-Z0-9_]/g, '_')
+      const closureName = `_uf_${safeName}`
+      const guard = isStr ? '' : `typeof ${v}==='string'&&`
+      lines.push(`if(${guard}!${closureName}(${v})){${failPush}}`)
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "0.12.5",
+  "version": "0.13.0",
   "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",
@@ -20,6 +20,11 @@
       "import": "./compat.mjs",
       "require": "./compat.js"
     },
+    "./build": {
+      "types": "./build.d.ts",
+      "import": "./build.mjs",
+      "require": "./build.js"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -35,7 +40,7 @@
     "rebuild": "cmake-js rebuild --target ata",
     "prebuild": "pkg-prebuilds-copy --baseDir build/Release --source ata.node --name=ata --strip --napi_version=10",
     "prebuild-all": "npm run prebuild -- --arch x64 && npm run prebuild -- --arch arm64",
-    "test": "node test.js",
+    "test": "node test.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js",
     "test:suite": "node tests/run_suite.js",
     "test:compat": "node tests/test_compat.js",
     "test:standard-schema": "node tests/test_standard_schema.js",
@@ -46,7 +51,11 @@
     "bench": "node benchmark/bench_large.js",
     "fuzz": "node tests/fuzz_differential.js",
     "fuzz:long": "FUZZ_ITERATIONS=100000 node tests/fuzz_differential.js",
-    "test:json-suite": "node tests/run_json_test_suite.js"
+    "test:aot": "node tests/test_aot_build.js",
+    "test:aot-differential": "node tests/test_aot_differential.js",
+    "test:aot-cli": "node tests/test_aot_cli_build.js",
+    "test:json-suite": "node tests/run_json_test_suite.js",
+    "bench:aot-vs-ajv": "node benchmark/bench_aot_vs_ajv.mjs"
   },
   "keywords": [
     "json",
@@ -85,6 +94,9 @@
     "compat.js",
     "compat.mjs",
     "compat.d.ts",
+    "build.js",
+    "build.mjs",
+    "build.d.ts",
     "binding-options.js",
     "binding/",
     "include/",
@@ -94,6 +106,7 @@
     "scripts/",
     "CMakeLists.txt",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "dependencies": {
@@ -101,6 +114,12 @@
     "node-api-headers": "^1.8.0",
     "pkg-prebuilds": "^1.0.0"
   },
+  "peerDependencies": {
+    "yaml": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "yaml": { "optional": true }
+  },
   "devDependencies": {
     "@sinclair/typebox": "^0.34.49",
     "cmake-js": "^8.0.0",