ata-validator 1.61.1 → 1.61.3

package/README.md

@@ -1,6 +1,6 @@
 # ata-validator
 
-JSON Schema validation that compiles for speed and still runs where code generation is blocked. The compiled and interpreted engines answer identically, at 100% of the official suite in both modes, across Draft 2020-12, draft 7 and the [JSON Schema v1 dialect](#dialects). First-class TypeScript inference, and `ata build` emits a standalone module that imports nothing.
+JSON Schema validation where the TypeScript type comes from the schema, or the schema from the type. Write the schema once and `validate` narrows to it; write the type once and the bundler plugin writes its schema in at build time. The compiled and interpreted engines answer identically, at 100% of the official suite in both modes, across Draft 2020-12, 2019-09, drafts 7, 6 and 4 and the [JSON Schema v1 dialect](#dialects), and `ata build` emits a standalone module that imports nothing, with its `.d.mts` beside it.
 
 [![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)
@@ -10,6 +10,60 @@ JSON Schema validation that compiles for speed and still runs where code generat
 
 1.0 is a stability commitment: see [docs/STABILITY.md](docs/STABILITY.md) for the semver, deprecation, and error-code guarantees.
 
+## The type and the schema
+
+One source of truth, in either direction. A schema written with `defineSchema` carries its
+type: `validate` narrows `data` to it, and `Infer` pulls the type out for a signature.
+
+```ts
+import { defineSchema, Validator, type Infer } from 'ata-validator'
+
+const User = defineSchema({
+  type: 'object',
+  properties: {
+    id: { type: 'integer', minimum: 1 },
+    email: { type: 'string', format: 'email' },
+    role: { enum: ['admin', 'user'] },
+  },
+  required: ['id', 'email'],
+})
+
+const users = new Validator(User)
+const r = users.validate(JSON.parse(body))
+if (r.valid) {
+  r.data.id    // number
+  r.data.role  // 'admin' | 'user' | undefined
+  r.data.name  // a type error: the schema has no name
+}
+
+type User = Infer<typeof User>
+```
+
+Or start from the type. `schemaOf<T>()` has no run-time form; the bundler plugin reads `T`
+with the TypeScript checker and writes its JSON Schema in place of the call, with the JSDoc
+tags carrying what a type cannot say, and the `new Validator(...)` then compiles away like any
+static schema.
+
+```ts
+import { Validator, schemaOf } from 'ata-validator'
+
+interface Account {
+  /** @minimum 1 */
+  id: number
+  /** @format email */
+  email: string
+  role?: 'admin' | 'user'
+}
+
+const accounts = new Validator(schemaOf<Account>())
+```
+
+`ata build` writes a `.d.mts` next to every compiled module, with the inferred type and an
+`isValid` predicate on it, so a module that imports nothing still narrows. The chainable
+builder in `ata-validator/t`, `Infer` on `anyOf`, `allOf`, tuples and recursive `$ref`, and
+the async `t.refine` are in [Type-safe schemas](#type-safe-schemas); the plugin's type reading
+is in [its README](https://github.com/ata-core/unplugin-ata#a-schema-from-a-typescript-type-schemaofuser).
+
 ## Who uses ata
 
 Projects whose code depends on ata, from GitHub's dependency graph, a framework that lists its
@@ -399,31 +453,7 @@ v.countValid(ndjson);        // number
 
 ### Type-safe schemas
 
-ata infers TypeScript types straight from plain JSON Schema. Write the schema once with `defineSchema`, and both runtime validation and the static type come from it, with no builder DSL and no second type declaration to keep in sync.
-
-```ts
-import { defineSchema, Validator } from 'ata-validator'
-
-const userSchema = defineSchema({
-  type: 'object',
-  properties: {
-    id: { type: 'integer', minimum: 1 },
-    role: { type: 'string', enum: ['admin', 'user'] },
-  },
-  required: ['id'],
-})
-
-const v = new Validator(userSchema)
-const result = v.validate(data)
-if (result.valid) {
-  result.data.id   // number
-  result.data.role // 'admin' | 'user' | undefined
-} else {
-  // result.errors: ValidationError[]
-}
-```
-
-`defineSchema` returns the schema untouched at runtime; in TypeScript it gives keyword autocomplete and an error when a value has the wrong shape, with no `as const` needed. `new Validator(schema)` carries the inferred type, so a successful `validate` narrows `result.data` with no manual annotation.
+ata infers TypeScript types straight from plain JSON Schema, as in [the opening example](#the-type-and-the-schema): `defineSchema` returns the schema untouched at runtime and, in TypeScript, gives keyword autocomplete and an error when a value has the wrong shape, with no `as const` needed. `new Validator(schema)` carries the inferred type, so a successful `validate` narrows `result.data` with no manual annotation.
 
 #### Extracting the type: `Infer`
 
@@ -671,7 +701,11 @@ validator only ever called (`v.validate(x)`, `v.isValidObject(x)`), never handed
 it uses the bare wrappers of `ata-validator/compiled-bare` instead, which leave out Standard
 Schema and the extension hook nothing can reach there: 0.3 KB gzipped for both, and
 `ata-validator/compiled-bare-rich` for one that reads ata's own errors. The same form app
-bundles to 10.7 KB gzipped, or 3.1 KB with `richErrors: false` on the validator that reads errors. The errors
+bundles to 10.7 KB gzipped, or 3.1 KB with `richErrors: false` on the validator that reads errors.
+A validator handed only to a Standard Schema consumer the plugin knows (Hono's
+`sValidator`, `hono-openapi`, TanStack Form, oRPC, tRPC, Elysia) takes `ata-validator/compiled-standard`, which
+carries `~standard` alone on a module with plain errors: a Hono route on Cloudflare Workers goes
+from 21.0 to 12.2 KB gzipped, 4.4 KB over Hono by itself. The errors
 then carry `keyword`, `instancePath`, `schemaPath`, `params` and `message`, as that option has
 always given them, without `received`, `suggestion` or `docUrl`.
 
@@ -728,6 +762,37 @@ works as a CI step. This is the check that found the two silent divergences
 fixed in 1.59.0 and 1.60.0, now in a form a project can run on every change.
 It does not run the `.bun.ts` target, which needs Bun's compiler.
 
+### What a schema change does (`ata diff`)
+
+Reading two versions of a schema side by side says which keywords changed. It
+does not say which documents change verdict, and that is the question before
+a deploy: which requests that pass today get a 400 tomorrow. `ata diff` answers
+it with documents:
+
+```bash
+npx ata diff schemas/user.json schemas/user-v2.json --samples test/fixtures
+```
+
+```
+401 documents: 102 accepted by both, 293 rejected by both, 6 rejected only by user-v2.json, 0 accepted only by user-v2.json
+
+Rejected by user-v2.json, accepted by user.json (a client sending these gets a rejection after the change):
+  minimum@/age: 4 documents, 1 of them the project's own, must be >= 18
+    {"email":"kid@example.com","name":"Kid","age":15}  (test/fixtures/signup-teen.json)
+  maxLength@/name: 2 documents, must NOT have more than 40 characters
+    {"email":"a@b.co","name":"abcdefghijabcdefghijabcdefghijabcdefghijabcdefghijabcdefghij...
+```
+
+The documents are the ones `ata verify` makes, from both schemas (200 each by
+default, half with one rule broken, then a value on either side of every
+bound), plus the project's own samples. Each one is checked by a `Validator`
+built from each schema, and the ones that change verdict are grouped by the
+rule that decides them, with one example each, the project's own document
+when there is one. The exit code is 1 when a document the old schema accepts
+is rejected by the new one, so a pull request that tightens a schema fails
+the check until someone looks. Generated documents are a sample, not a proof:
+a change this reports is real, one it does not report may still exist.
+
 ### Bun, compiled ahead of time
 
 Bun's ahead-of-time compiler (`bun build --compile --aot`, an open pull
@@ -748,10 +813,12 @@ So, in order of preference:
    module by hand. The module is plain JavaScript and compiles with the
    program: 24 ns, the same errors as the runtime.
 2. Where the runtime `Validator` stays, let it take the interpreted engine.
-   It does so by itself when Bun reports `Bun.isAOT`, when the executable is
-   built with `--disallow-code-generation-from-strings` (the program then
-   counts as closed for the compiler, too), or when `ATA_ENGINE=interpreter`
-   is set: 80 ns against 492 for the generated code there.
+   It does so by itself under `bun build --compile --aot` and `bun run --aot`,
+   where Bun resolves the package's `"aot"` export condition to an entry that
+   says so; also when the executable is built with
+   `--disallow-code-generation-from-strings` (the program then counts as
+   closed for the compiler, too), or when `ATA_ENGINE=interpreter` is set:
+   78 ns against 487 for the generated code there.
 3. Write the module for the compiler. `ata build schema.json --target bun`
    writes it with a closed object's keys read once and compared with the
    declared list in order (on a ten-item order with 1024 distinct documents,

package/bin/ata.js

@@ -15,6 +15,8 @@ Usage:
   ata migrate  [dir]         [options]  Report what switching from ajv would change; --write applies it.
   ata verify   <glob>...     [options]  Check that each schema's compiled module answers as the runtime
                                         does, on generated documents and the project's samples.
+  ata diff     <old> <new>   [options]  What a change to a schema does: the documents the old schema
+                                        accepts and the new one rejects, and the reverse, by rule.
 
 Verify options:
   --generate <n>          Documents made from each schema, half with one rule broken. Default: 200
@@ -23,6 +25,13 @@ Verify options:
   --json                  Report as JSON
   --out-dir, --suffix, --format    Where the modules are, as given to ata build
 
+Diff options:
+  --generate <n>          Documents made from each schema. Default: 200
+  --samples <path>        The project's own documents, checked too (repeatable)
+  --seed <n>              Seed for the generated documents. Default: 1
+  --json                  Report as JSON
+  Exit status 1 when a document the old schema accepts is rejected by the new one.
+
 Validate options:
   --pretty                Render errors with source frames (default on TTY)
   --compact               Render errors as one line each (default when piped)
@@ -487,6 +496,24 @@ function cmdVerify (args) {
   })().catch((e) => { process.stderr.write(`error: ${e.message}\n`); process.exit(1); });
 }
 
+function cmdDiff (args) {
+  if (args._.length < 2) {
+    process.stderr.write('error: ata diff <old-schema> <new-schema>\n');
+    process.exit(2);
+  }
+  const buildLib = require('../lib/aot-build');
+  const { diffSchemas, renderDiff, breaking } = require('../lib/schema-diff');
+  let oldSchema, newSchema;
+  try { oldSchema = buildLib.parseSchemaFile(args._[0]); newSchema = buildLib.parseSchemaFile(args._[1]); } catch (e) { process.stderr.write(`error: ${e.message}\n`); process.exit(2); }
+  const samples = args.opts.samples === undefined ? [] : [].concat(args.opts.samples);
+  let report;
+  try {
+    report = diffSchemas(oldSchema, newSchema, { generate: Number.isFinite(args.opts.generate) ? args.opts.generate : 200, seed: Number.isFinite(args.opts.seed) ? args.opts.seed : 1, samples });
+  } catch (e) { process.stderr.write(`error: ${e.message}\n`); process.exit(2); }
+  process.stdout.write(renderDiff(report, { json: !!args.opts.json, oldName: path.basename(args._[0]), newName: path.basename(args._[1]) }) + '\n');
+  process.exit(breaking(report) ? 1 : 0);
+}
+
 function cmdValidate (args) {
   if (args._.length < 2) {
     process.stderr.write('error: ata validate <schema> <data-file>\n');
@@ -592,6 +619,11 @@ function main() {
     return;
   }
 
+  if (cmd === 'diff') {
+    cmdDiff(args);
+    return;
+  }
+
   if (cmd === 'migrate') {
     const { migrate, formatReport } = require('../lib/migrate');
     const result = migrate(args._[0] || '.', { write: !!args.opts.write });

package/compiled-standard.d.ts

@@ -0,0 +1,6 @@
+// ata-validator/compiled-standard: the compiled-module wrapper for a validator
+// a bundler plugin sees handed to Standard Schema consumers only.
+import type { StandardSchemaV1Props } from './index.js';
+import type { CompiledModule } from './compiled.js';
+
+export function bareStandard<T = unknown>(mod: CompiledModule, schema: object | boolean, useDefaults?: boolean): { '~standard': StandardSchemaV1Props<T> };

package/compiled-standard.mjs

@@ -0,0 +1,66 @@
+// ata-validator/compiled-standard as an ES module of its own, not a re-export
+// of the CommonJS file, so a bundler adds no interop code (see
+// compiled-bare.mjs). The same `~standard` as lib/compiled-standard.js builds
+// through lib/standard-schema.js; tests/test_compiled_standard.js holds the
+// two to the same issues and the same schema documents.
+
+// When the module's error function answers valid where its verdict said no,
+// the disagreement is reported rather than turned into an acceptance.
+const DISAGREES = [{ message: 'schema validation failed', instancePath: '' }];
+const EMPTY_PATH = Object.freeze([]);
+
+// A JSON pointer as a Standard Schema path: an all-digit segment without a
+// leading zero is an array index and comes out as a number.
+function pathOf(pointer) {
+  if (!pointer) return EMPTY_PATH;
+  const out = [];
+  for (const raw of pointer.split('/').slice(1)) {
+    const seg = raw.indexOf('~') >= 0 ? raw.replace(/~1/g, '/').replace(/~0/g, '~') : raw;
+    out.push({ key: /^(?:0|[1-9][0-9]*)$/.test(seg) ? Number(seg) : seg });
+  }
+  return Object.freeze(out);
+}
+
+// Standard JSON Schema: the document, as a copy, for its own dialect.
+function jsonSchemaOf(schema) {
+  const convert = (options) => {
+    const target = options && options.target;
+    if (schema === true) return {};
+    if (schema === false) return { not: {} };
+    const declared = typeof schema.$schema === 'string' ? schema.$schema : '';
+    const dialect = declared === '' || declared.includes('draft/2020-12/schema') ? 'draft-2020-12'
+      : declared.includes('draft-07/schema') ? 'draft-07' : declared;
+    if (target !== dialect) {
+      throw new TypeError(`ata-validator cannot provide a ${dialect} schema as ${String(target)}; it does not convert between dialects`);
+    }
+    return JSON.parse(JSON.stringify(schema));
+  };
+  return Object.freeze({ input: convert, output: convert });
+}
+
+export function bareStandard(mod, schema, useDefaults) {
+  const fill = useDefaults !== false && typeof mod.applyDefaults === 'function' ? mod.applyDefaults : null;
+  const isValid = mod.isValid;
+  const errFn = mod.validate;
+  return {
+    '~standard': Object.freeze({
+      version: 1,
+      vendor: 'ata-validator',
+      jsonSchema: jsonSchemaOf(schema),
+      validate(value) {
+        if (fill !== null) fill(value);
+        if (isValid(value)) return { value };
+        const r = errFn(value);
+        const errors = r && r.valid === false ? r.errors : DISAGREES;
+        const issues = new Array(errors.length);
+        for (let i = 0; i < errors.length; i++) {
+          const e = errors[i];
+          issues[i] = { message: e.message || 'validation failed', path: pathOf(e.instancePath != null ? e.instancePath : (e.path || '')) };
+        }
+        return { issues };
+      },
+    }),
+  };
+}
+
+export default { bareStandard };

package/index.aot.js

@@ -0,0 +1,8 @@
+'use strict';
+
+// ata-validator under Bun's ahead-of-time compiler, where Bun resolves the
+// `"aot"` export condition: the same package, with validators on the
+// interpreted engine by default, which is compiled with the program, rather
+// than on code made at run time, which is not (lib/aot-mark.js).
+require('./lib/aot-mark.js');
+module.exports = require('./index.js');

package/index.aot.mjs

@@ -0,0 +1,5 @@
+// ata-validator under Bun's ahead-of-time compiler; see index.aot.js. The mark
+// is imported first, so it runs before the package and before any caller.
+import './lib/aot-mark.js';
+export * from './index.mjs';
+export { default } from './index.mjs';

package/lib/aot-mark.js

@@ -0,0 +1,7 @@
+'use strict';
+
+// Loaded first by index.aot.js and index.aot.mjs, the entries Bun resolves
+// through the `"aot"` export condition when it compiles a program ahead of
+// time: every Validator made after this takes the interpreted engine by
+// default (see aotHost in lib/validator-core.js).
+require('./validator-core')._markAotHost();

package/lib/compiled-standard.js

@@ -0,0 +1,33 @@
+'use strict';
+
+// bareStandard: the compiled-module wrapper for a validator that is only ever
+// handed to a Standard Schema consumer (a router's validator middleware, a
+// form library, an RPC layer) and never called by its own code. Such a
+// consumer reads `~standard` and nothing else, and an issue carries a message
+// and a path, so the wrapper is built on a module written with
+// `plainErrors: true`, whose errors are those two things in schema order, and
+// carries no error pipeline, no Standard Schema install and no extension hook.
+// The issues are the runtime's (tests/test_compiled_standard.js). A bundler
+// plugin puts this in place of `new Validator(schema)` where it sees that use.
+
+const { standardSchemaFor } = require('./standard-schema');
+
+const VALID = Object.freeze({ valid: true, errors: Object.freeze([]) });
+// When the module's error function answers valid where its verdict said no,
+// the disagreement is reported rather than turned into an acceptance.
+const VERDICT_DISAGREES = Object.freeze({ valid: false, errors: Object.freeze([Object.freeze({ keyword: 'validation', instancePath: '', schemaPath: '#', params: Object.freeze({}), message: 'schema validation failed' })]) });
+
+function bareStandard(mod, schema, useDefaults) {
+  const fill = useDefaults !== false && typeof mod.applyDefaults === 'function' ? mod.applyDefaults : null;
+  const isValid = mod.isValid;
+  const errFn = mod.validate;
+  const validate = (data) => {
+    if (fill !== null) fill(data);
+    if (isValid(data)) return VALID;
+    const r = errFn(data);
+    return r && r.valid === false ? r : VERDICT_DISAGREES;
+  };
+  return { '~standard': standardSchemaFor(null, () => schema, (_, value) => validate(value)) };
+}
+
+module.exports = { bareStandard };

package/lib/formats.js

@@ -538,4 +538,31 @@ function email(s) {
 const DURATION_RE = /^P(?:\d+W|(?:\d+Y(?:\d+M(?:\d+D)?)?|\d+M(?:\d+D)?|\d+D)(?:T(?:\d+H(?:\d+M(?:\d+S)?)?|\d+M(?:\d+S)?|\d+S))?|T(?:\d+H(?:\d+M(?:\d+S)?)?|\d+M(?:\d+S)?|\d+S))$/;
 function duration (s) { return DURATION_RE.test(s); }
 
-module.exports = { IPV4, DURATION_RE, IPV6_FULL, ipv4Range, URI_FAST, date, ipv4, dateTime, ipv6, hostname, uri, uriReference, uriWalk: _uriWalk, uuid, time, noReserved, jsonPointer, relativeJsonPointer, uriTemplate, email, duration, iri, iriReference, idnEmail, DURATION_RE, URI_TEMPLATE_EXPR };
+// The built-in format checks by name, built on first use. The interpreted
+// engine and the tier-0 verdict (lib/tier0.js) read the same table, so the two
+// cannot answer differently for a format.
+let _checks = null;
+function formatChecks () {
+  return _checks || (_checks = {
+    email,
+    date,
+    'date-time': dateTime,
+    time,
+    duration,
+    uuid,
+    uri,
+    'uri-reference': uriReference,
+    ipv4,
+    ipv6,
+    hostname,
+    regex: (s) => { try { new RegExp(s, 'u'); return true; } catch { return false; } },
+    'json-pointer': jsonPointer,
+    'relative-json-pointer': relativeJsonPointer,
+    'uri-template': uriTemplate,
+    iri,
+    'iri-reference': iriReference,
+    'idn-email': idnEmail,
+  });
+}
+
+module.exports = { formatChecks, IPV4, DURATION_RE, IPV6_FULL, ipv4Range, URI_FAST, date, ipv4, dateTime, ipv6, hostname, uri, uriReference, uriWalk: _uriWalk, uuid, time, noReserved, jsonPointer, relativeJsonPointer, uriTemplate, email, duration, iri, iriReference, idnEmail, DURATION_RE, URI_TEMPLATE_EXPR };

package/lib/interpreter-core.js

@@ -288,33 +288,9 @@ function multipleOfOk(d, m) {
   return Math.abs(q - Math.round(q)) < 1e-9;
 }
 
-// The built-in format checks, built on the first schema that names a format:
-// the engine loads without lib/formats.js, which schemas without `format`
-// never need.
-let _formatChecks = null;
-function buildFormatChecks() {
-  const _formats = require('./formats');
-  return {
-  email: _formats.email,
-  date: _formats.date,
-  'date-time': _formats.dateTime,
-  time: _formats.time,
-  duration: _formats.duration,
-  uuid: _formats.uuid,
-  uri: _formats.uri,
-  'uri-reference': _formats.uriReference,
-  ipv4: _formats.ipv4,
-  ipv6: _formats.ipv6,
-  hostname: _formats.hostname,
-  regex: (s) => { try { new RegExp(s, 'u'); return true; } catch { return false; } },
-  'json-pointer': _formats.jsonPointer,
-  'relative-json-pointer': _formats.relativeJsonPointer,
-  'uri-template': _formats.uriTemplate,
-  iri: _formats.iri,
-  'iri-reference': _formats.iriReference,
-  'idn-email': _formats.idnEmail,
-  };
-}
+// The built-in format checks come from lib/formats.js (formatChecks), loaded
+// on the first schema that names a format: the engine loads without it, which
+// schemas without `format` never need.
 
 // ---------- evaluation ----------
 
@@ -454,7 +430,7 @@ class Plan {
     this.formatFn = null;
     if (schema.format !== undefined) {
       const uf = interp.userFormats;
-      const fc = (uf && typeof uf[schema.format] === 'function') ? uf[schema.format] : (_formatChecks || (_formatChecks = buildFormatChecks()))[schema.format];
+      const fc = (uf && typeof uf[schema.format] === 'function') ? uf[schema.format] : require('./formats').formatChecks()[schema.format];
       this.formatFn = fc || null;
     }
     this.hasString = this.minLength !== undefined || this.maxLength !== undefined || this.pattern !== null || this.formatFn !== null;

package/lib/schema-diff.js

@@ -0,0 +1,103 @@
+'use strict';
+
+// What a change to a schema does to documents: which ones the old schema
+// accepted and the new one rejects (a client sending what used to pass gets a
+// 400), and which ones the new one accepts and the old one did not (a rule
+// was loosened). Reading two schemas side by side tells you which keywords
+// changed; it does not tell you which documents change verdict, and that is
+// the question before a deploy. The documents come from `generate` in
+// lib/verify.js, made from both schemas, half of them with one rule broken,
+// plus the values on either side of every bound, plus the project's own
+// samples. Generated documents are a sample, not a proof: a change this
+// finds is real, one it does not find may still exist.
+
+const { Validator } = require('../index.js');
+const { generate, readSamples } = require('./verify');
+
+const clone = (v) => (v === undefined ? v : JSON.parse(JSON.stringify(v)));
+const errorKey = (e) => `${e.keyword || ''}@${e.instancePath || ''}`;
+const first = (errors) => (errors && errors.length ? errors[0] : { keyword: 'validation', instancePath: '', message: 'validation failed' });
+
+// `samples`: paths of JSON or JSON Lines files, or directories of them.
+function diffSchemas (oldSchema, newSchema, { generate: count = 200, seed = 1, samples = [] } = {}) {
+  const before = new Validator(oldSchema);
+  const after = new Validator(newSchema);
+  const docs = [];
+  const seen = new Set();
+  const add = (doc, source) => {
+    if (doc === undefined) return;
+    const key = JSON.stringify(doc);
+    if (seen.has(key)) return;
+    seen.add(key);
+    docs.push({ doc, source });
+  };
+  for (const d of generate(oldSchema, count, seed, (x) => before.isValidObject(clone(x)))) add(d, 'generated from the old schema');
+  for (const d of generate(newSchema, count, seed + 1, (x) => after.isValidObject(clone(x)))) add(d, 'generated from the new schema');
+  for (const s of readSamples(samples)) if (!s.bad) add(s.doc, s.source);
+
+  const nowRejected = [];
+  const nowAccepted = [];
+  let bothAccept = 0;
+  let bothReject = 0;
+  for (const { doc, source } of docs) {
+    const a = before.validate(clone(doc));
+    const b = after.validate(clone(doc));
+    if (a.valid && b.valid) bothAccept++;
+    else if (!a.valid && !b.valid) bothReject++;
+    else if (a.valid) nowRejected.push({ doc, source, error: first(b.errors) });
+    else nowAccepted.push({ doc, source, error: first(a.errors) });
+  }
+  return {
+    documents: docs.length,
+    bothAccept,
+    bothReject,
+    nowRejected: grouped(nowRejected),
+    nowAccepted: grouped(nowAccepted),
+  };
+}
+
+// The documents of one kind, grouped by the rule that decides them (the
+// first error's keyword and place), each group with one example: one of the
+// project's own documents when the group holds one, since that is a document
+// somebody actually sends, else the first generated one.
+const generated = (source) => source.startsWith('generated');
+function grouped (list) {
+  const groups = new Map();
+  for (const item of list) {
+    const key = errorKey(item.error);
+    let g = groups.get(key);
+    if (g === undefined) groups.set(key, (g = { rule: key, message: item.error.message, count: 0, samples: 0, example: item.doc, source: item.source }));
+    g.count++;
+    if (!generated(item.source)) { g.samples++; if (generated(g.source)) { g.example = item.doc; g.source = item.source; } }
+  }
+  return { count: list.length, rules: [...groups.values()].sort((x, y) => y.count - x.count) };
+}
+
+function breaking (report) { return report.nowRejected.count > 0; }
+
+function renderDiff (report, { json = false, oldName = 'old', newName = 'new' } = {}) {
+  if (json) return JSON.stringify(report, null, 2);
+  const lines = [];
+  const show = (doc) => { const s = JSON.stringify(doc); return s.length > 120 ? s.slice(0, 117) + '...' : s; };
+  lines.push(`${report.documents} documents: ${report.bothAccept} accepted by both, ${report.bothReject} rejected by both, ${report.nowRejected.count} rejected only by ${newName}, ${report.nowAccepted.count} accepted only by ${newName}`);
+  if (report.nowRejected.count) {
+    lines.push('');
+    lines.push(`Rejected by ${newName}, accepted by ${oldName} (a client sending these gets a rejection after the change):`);
+    for (const g of report.nowRejected.rules) {
+      lines.push(`  ${g.rule}: ${g.count} ${g.count === 1 ? 'document' : 'documents'}${g.samples ? `, ${g.samples} of them the project's own` : ''}, ${g.message}`);
+      lines.push(`    ${show(g.example)}${generated(g.source) ? '' : `  (${g.source})`}`);
+    }
+  }
+  if (report.nowAccepted.count) {
+    lines.push('');
+    lines.push(`Accepted by ${newName}, rejected by ${oldName} (what ${oldName} refused with):`);
+    for (const g of report.nowAccepted.rules) {
+      lines.push(`  ${g.rule}: ${g.count} ${g.count === 1 ? 'document' : 'documents'}${g.samples ? `, ${g.samples} of them the project's own` : ''}, ${g.message}`);
+      lines.push(`    ${show(g.example)}${generated(g.source) ? '' : `  (${g.source})`}`);
+    }
+  }
+  if (!report.nowRejected.count && !report.nowAccepted.count) lines.push('No document changed verdict.');
+  return lines.join('\n');
+}
+
+module.exports = { diffSchemas, renderDiff, breaking };

package/lib/shape-classifier.js

@@ -24,7 +24,7 @@ const TIER0_PRIMITIVE_ALLOWED = new Set([
   'type', 'enum', 'const',
   'minLength', 'maxLength',
   'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum',
-  'multipleOf',
+  'multipleOf', 'format',
   ...META_KEYS,
 ]);
 
@@ -54,6 +54,11 @@ function isTier0Primitive(schema) {
     }
   }
   if (schema.const !== undefined && !isPrimitiveEnumValue(schema.const)) return false;
+  // `format` on a string, by name: tier 0 checks it with the table the
+  // interpreted engine reads (formats.formatChecks) or the caller's own
+  // function. A format on another type is a compat check for numbers, which
+  // the full engines handle.
+  if (schema.format !== undefined && (schema.type !== 'string' || typeof schema.format !== 'string')) return false;
   return true;
 }
 

package/lib/tier0.js

@@ -49,7 +49,17 @@ const _hop = Object.prototype.hasOwnProperty;
 // Deno removes the __proto__ accessor; read the prototype another way there.
 const _PN = typeof Bun === 'undefined' && ({}).__proto__ === Object.prototype; // JavaScriptCore goes through Object.getPrototypeOf, see js-compiler's _PN
 
-function primConstraint(key, propSchema) {
+// The check for a string's `format`: the caller's own function by that name,
+// else the built-in one, else none (an unknown format is an annotation), as
+// the interpreted engine picks it.
+function formatFnOf(propSchema, userFormats) {
+  const f = propSchema.format;
+  if (typeof f !== 'string') return null;
+  if (userFormats && typeof userFormats[f] === 'function') return userFormats[f];
+  return require('./formats').formatChecks()[f] || null;
+}
+
+function primConstraint(key, propSchema, userFormats) {
   const t = propSchema.type;
   const hasEnum = Array.isArray(propSchema.enum);
   const hasConst = propSchema.const !== undefined;
@@ -75,14 +85,15 @@ function primConstraint(key, propSchema) {
     exclMin: typeof propSchema.exclusiveMinimum === 'number' ? propSchema.exclusiveMinimum : 0,
     exclMax: typeof propSchema.exclusiveMaximum === 'number' ? propSchema.exclusiveMaximum : 0,
     multipleOf: typeof propSchema.multipleOf === 'number' ? propSchema.multipleOf : 0,
+    formatFn: propSchema.type === 'string' ? formatFnOf(propSchema, userFormats) : null,
   };
 }
 
-function buildTier0Plan(schema) {
+function buildTier0Plan(schema, userFormats) {
   if (schema.type !== 'object') {
     return {
       isPrimitive: true,
-      constraints: [primConstraint('__root__', schema)],
+      constraints: [primConstraint('__root__', schema, userFormats)],
       requiredMask: 0,
       additionalAllowed: true,
       knownKeys: null,
@@ -96,7 +107,7 @@ function buildTier0Plan(schema) {
   let requiredMask = 0;
   for (let i = 0; i < keys.length; i++) {
     const k = keys[i];
-    constraints[i] = primConstraint(k, props[k]);
+    constraints[i] = primConstraint(k, props[k], userFormats);
     knownKeys.add(k);
     if (required && required.has(k)) requiredMask |= (1 << i);
   }
@@ -128,6 +139,7 @@ function checkPrimitive(c, v) {
     const maxLen = c.maxLen;
     if (minLen >= 0) { const l = v.length; if (l < minLen) return false; if (l < minLen * 2 && codePointLength(v) < minLen) return false; }
     if (maxLen >= 0) { const l = v.length; if (l > maxLen && codePointLength(v) > maxLen) return false; }
+    if (c.formatFn !== null && !c.formatFn(v)) return false;
   } else if (m === T_INTEGER) {
     if (typeof v !== 'number' || !Number.isInteger(v)) return false;
     const f = c.numFlags;
@@ -186,6 +198,7 @@ function tier0ValidateObject(plan, data) {
       const maxLen = c.maxLen;
       if (minLen >= 0) { const l = v.length; if (l < minLen) return false; if (l < minLen * 2 && codePointLength(v) < minLen) return false; }
       if (maxLen >= 0) { const l = v.length; if (l > maxLen && codePointLength(v) > maxLen) return false; }
+      if (c.formatFn !== null && !c.formatFn(v)) return false;
     } else if (m === T_INTEGER) {
       if (typeof v !== 'number' || !Number.isInteger(v)) return false;
       const f = c.numFlags;

package/lib/validator-core.js

@@ -19,10 +19,17 @@ const { normalizeKeywords, schemaUsesKeywords } = require('./keywords');
 // bundle built from lite.js never contains it. Until something registers, the
 // core behaves exactly as it does where `new Function` is blocked: every
 // schema runs on the interpreted engine, which passes the same test suite.
-// Whether this process runs code compiled ahead of time, where generated
-// code falls to an interpreter: Bun's flag for its compiler, or the
-// environment saying so (an executable built before the flag existed).
+// Whether this process runs code compiled ahead of time, where code made at
+// run time with `new Function` falls to an interpreter and ata's interpreted
+// engine, compiled with the program, is six times faster (481 against 78 ns
+// a document under bun build --compile --aot). Bun resolves the package's
+// `"aot"` export condition there, which loads index.aot.js and marks the
+// process (_markAotHost); `Bun.isAOT` was the earlier signal, and
+// ATA_ENGINE=interpreter says so from outside.
+let _aotEntry = false;
+function _markAotHost() { _aotEntry = true; }
 function aotHost() {
+  if (_aotEntry) return true;
   if (env('ATA_ENGINE') === 'interpreter') return true;
   const b = typeof Bun !== 'undefined' ? Bun : undefined;
   return !!(b && b.isAOT === true);
@@ -1213,7 +1220,13 @@ class Validator {
       // once per call: deciding first and walking again for the errors would
       // run the keyword twice, the second time on what the first left.
       const once = interp.dataContext === true;
-      if (!preprocess && !once) this._fastVerdict = (d) => interp.isValid(d);
+      // A schema tier 0 takes answers its verdict there, with or without a
+      // call to validate() first: the shared walk over a flat plan beats the
+      // closure tree, 76 to 60 ns on Node and 85 to 49 under Bun's compiler,
+      // where the closures are not typed. Not for custom keywords, which
+      // tier 0 does not know.
+      const t0 = !preprocess && !once && !this._usesKeywords ? _tier0Verdict(this) : null;
+      if (!preprocess && !once) this._fastVerdict = t0 !== null ? t0 : (d) => interp.isValid(d);
       if (preprocess && !once) _preVerdict = (d) => { preprocess(d); return interp.isValid(d); };
       // abortEarly is a documented contract, not a property of whichever engine
       // answered: it promises the frozen ATA9000 stub instead of a detailed
@@ -2332,6 +2345,22 @@ for (const [name, pick] of [
 
 // Cold start: an interpreted twin answers a large schema's first calls where
 // the code generator is registered (see coldTwin in index.js). Lite has none.
+// Whether this validator, in the browser build before the generator has
+// come, counts its calls so a busy one moves to generated code (lib/tiering.js).
+function _ticks(self) {
+  return _codegen === null && _tiering !== null && !self._interpretOnly && !env('ATA_FORCE_NAPI');
+}
+// The tier-0 verdict for a schema it takes, or null: counting calls where
+// _ticks says so.
+function _tier0Verdict(self) {
+  if (require('./shape-classifier').classify(self._schemaObj).tier !== 0) return null;
+  const { buildTier0Plan, tier0Validate } = require('./tier0');
+  const plan = buildTier0Plan(self._schemaObj, self._userFormats);
+  if (!_ticks(self)) return (d) => tier0Validate(plan, d);
+  const tick = _tiering.counter(self);
+  return (d) => { tick(); return tier0Validate(plan, d); };
+}
+
 Validator.prototype._coldTwin = function () {
   const cg = _loadCodegen();
   return cg === null || cg.coldTwin === undefined ? null : cg.coldTwin(this, Validator);
@@ -2363,21 +2392,13 @@ _defineLazyMethod('isValidObject', (self) => {
     return self.isValidObject(data);
   }
   // Lazy: classify + build tier 0 plan on first call, not in constructor.
-  const _tier = require("./shape-classifier").classify(self._schemaObj);
-  if (_tier.tier === 0) {
-    // Bound once here, so the verdict below reads a local, not the module.
-    const { buildTier0Plan, tier0Validate } = require("./tier0");
-    const _plan = buildTier0Plan(self._schemaObj);
+  const _t0 = _tier0Verdict(self);
+  if (_t0 !== null) {
+    // In the browser build the verdict counts its calls (see _tier0Verdict);
+    // elsewhere the second call builds the generated code behind it.
     let _n = 0;
-    // In the browser build the generator is not there yet: count the calls
-    // like the interpreted engine does, or a schema checked only through
-    // this method stays on the plan walk, four times slower, for good.
-    const _tick = _codegen === null && _tiering !== null && !self._interpretOnly && !env('ATA_FORCE_NAPI') ? _tiering.counter(self) : null;
-    _bindVerdict(self, _tick !== null ? (d) => {
-      _tick();
-      return tier0Validate(_plan, d);
-    } : (d) => {
-      const r = tier0Validate(_plan, d);
+    _bindVerdict(self, _ticks(self) ? _t0 : (d) => {
+      const r = _t0(d);
       if (++_n === 2) {
         try { self._ensureCodegen(); } catch {}
       }
@@ -2450,6 +2471,7 @@ Object.defineProperty(module.exports, '_registerCodegen', { value: _registerCode
 Object.defineProperty(module.exports, '_setCodegenLoader', { value: (load) => { _loadCodegen = load; }, enumerable: false });
 Object.defineProperty(module.exports, '_registerTiering', { value: _registerTiering, enumerable: false });
 Object.defineProperty(module.exports, '_registerBuiltHook', { value: _registerBuiltHook, enumerable: false });
+Object.defineProperty(module.exports, '_markAotHost', { value: _markAotHost, enumerable: false });
 Object.defineProperty(module.exports, '_codegenRegistered', { value: () => _codegen !== null, enumerable: false });
 Object.defineProperty(module.exports, '_tiering', { get: () => _tiering, enumerable: false });
 Object.defineProperty(module.exports, '_registerAot', { value: _registerAot, enumerable: false });

package/lib/version.js

@@ -7,4 +7,4 @@
 //
 // Kept in lockstep with package.json by `tests/test_version_sync.js`.
 
-module.exports = '1.61.1';
+module.exports = '1.61.3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "1.61.1",
+  "version": "1.61.3",
   "description": "JSON Schema validator that compiles to plain JavaScript, still runs where code generation is blocked, and can be compiled away at build time. Passes the full official test suite.",
   "type": "commonjs",
   "main": "index.js",
@@ -8,6 +8,11 @@
   "types": "index.d.ts",
   "exports": {
     ".": {
+      "aot": {
+        "types": "./index.d.ts",
+        "import": "./index.aot.mjs",
+        "require": "./index.aot.js"
+      },
       "workerd": {
         "types": "./index.d.ts",
         "import": "./index.edge.mjs",
@@ -79,6 +84,11 @@
       "types": "./compiled-bare-rich.d.ts",
       "default": "./lib/compiled-bare-rich.js"
     },
+    "./compiled-standard": {
+      "types": "./compiled-standard.d.ts",
+      "import": "./compiled-standard.mjs",
+      "default": "./lib/compiled-standard.js"
+    },
     "./lite": {
       "types": "./lite.d.ts",
       "import": "./lite.mjs",
@@ -98,7 +108,10 @@
   },
   "sideEffects": [
     "./codegen.js",
-    "./codegen.mjs"
+    "./codegen.mjs",
+    "./lib/aot-mark.js",
+    "./index.aot.js",
+    "./index.aot.mjs"
   ],
   "bin": {
     "ata": "bin/ata.js"
@@ -170,6 +183,8 @@
   },
   "files": [
     "index.js",
+    "index.aot.js",
+    "index.aot.mjs",
     "index.mjs",
     "index.node.mjs",
     "index.bundle.mjs",
@@ -207,6 +222,8 @@
     "compiled-bare.mjs",
     "compiled-bare.d.ts",
     "compiled-bare-rich.d.ts",
+    "compiled-standard.mjs",
+    "compiled-standard.d.ts",
     "lite.js",
     "lite.mjs",
     "lite.d.ts",
@@ -221,13 +238,13 @@
     "codegen.d.ts"
   ],
   "optionalDependencies": {
-    "@ata-validator/native-darwin-arm64": "1.61.1",
-    "@ata-validator/native-darwin-x64": "1.61.1",
-    "@ata-validator/native-linux-arm64-gnu": "1.61.1",
-    "@ata-validator/native-linux-arm64-musl": "1.61.1",
-    "@ata-validator/native-linux-x64-gnu": "1.61.1",
-    "@ata-validator/native-linux-x64-musl": "1.61.1",
-    "@ata-validator/native-win32-x64": "1.61.1"
+    "@ata-validator/native-darwin-arm64": "1.61.3",
+    "@ata-validator/native-darwin-x64": "1.61.3",
+    "@ata-validator/native-linux-arm64-gnu": "1.61.3",
+    "@ata-validator/native-linux-arm64-musl": "1.61.3",
+    "@ata-validator/native-linux-x64-gnu": "1.61.3",
+    "@ata-validator/native-linux-x64-musl": "1.61.3",
+    "@ata-validator/native-win32-x64": "1.61.3"
   },
   "peerDependencies": {
     "yaml": "^2.0.0"