ata-validator 1.48.0 → 1.50.0

package/README.md

@@ -43,10 +43,12 @@ npm install ata-validator --omit=optional
 
 or set `ATA_NO_NATIVE=1` at runtime. Typical schemas compile to specialized JS; shapes the compiler cannot represent (some `$dynamicRef`, cyclic `$ref`, unusual keyword interactions) fall back to an interpreted engine, so every schema validates in every environment. The pure-JS setup scores the same on the official suite as the native one, 1301 of 1301 Draft 2020-12 cases. The buffer and parallel APIs (`isValid` on raw buffers, `isValidPrepadded`, `isValidNDJSON`, `isValidParallel`, `countValid`, `batchIsValid`, `validateAndParse`) work without the addon too, answering through the same checks as `isValidJSON()`, slower than the addon: 177 ns against 92 for a small document on Node 25. In a browser, which has no `Buffer`, they throw and name the methods to use instead.
 
-Where the size of what ships matters more than nanoseconds per call, `ata-validator/lite` is
-the same `Validator` on the interpreted engine alone, without the code generator: the same
-verdicts and errors, 58 KB gzipped in a bundled worker against 136 KB for the full entry.
-It leaves out what needs the generator, `parse()` and the ahead-of-time bundle methods.
+In Cloudflare Workers and Vercel Edge, where generated code cannot run, `ata-validator`
+resolves to an entry without the code generator through the `workerd` and `edge-light` export
+conditions: the same names and answers, and a Worker bundled by wrangler goes from 179.1 to
+70.4 KiB gzipped. On a page whose Content-Security-Policy blocks `unsafe-eval`, or in a
+browser extension, no condition tells the bundler, so import `ata-validator/lite` there: the
+same `Validator` on the interpreted engine alone.
 
 On Deno the same package is `npm:ata-validator` or `jsr:@ata/validator`; the JSR package
 re-exports the npm one at the same version, and CI runs the official suite under Deno. The
@@ -109,6 +111,29 @@ file.
   passes with nothing failed, errored or skipped under Bowtie's own runner. The v1 dialect is
   declared in a pending harness change that waits for a Bowtie release.
 
+### Side by side
+
+[validator-benchmarks](https://github.com/ata-core/validator-benchmarks) is ata's own
+comparison, so it comes after the ones above: eleven validators on three realistic bodies
+and four scenes, each library in its own process, 27 samples per cell, every schema and
+document in the repository. On an order body with formats and a pattern, 900 valid
+documents, Node 24:
+
+[![Documents a second on one order body, eleven validators](https://raw.githubusercontent.com/ata-core/validator-benchmarks/main/media/race-order-verdict-valid.gif)](https://github.com/ata-core/validator-benchmarks/blob/main/media/race-order-verdict-valid.mp4)
+
+| | documents a second, the verdict | same, `new Function` refused |
+|---|---:|---:|
+| ata | 3,295,880 | 607,614 |
+| ata, compiled module | 3,319,594 | 3,344,948 |
+| typebox | 1,638,813 | EvalError |
+| ajv | 1,285,492 | EvalError |
+| typia | 939,572 | 964,507 |
+| zod | 440,473 | 237,176 |
+
+Where ata is behind is in the same tables: on a four-field body that fails, ajv answers the
+verdict faster, and with every error read it does 6.6M a second against ata's 2.9M with rich
+errors (7.6M with `richErrors: false`).
+
 ## Why AOT
 
 | Dimension | Schema | ata-AOT | runtime validator | Difference |
@@ -254,13 +279,13 @@ is the most common way to get a misleading number out of this library.
 
 | | compiled with `ata build` | runtime `new Validator(schema)` |
 |---|---|---|
-| In a bundle, gzipped | **2.1 KB** | 125.0 KB |
+| In a bundle, gzipped | **2.1 KB** | 126.1 KB |
 | Time to a served request | **3.5 ms** | 7.6 ms |
 | Schema known when | build time | any time |
 
 The bundle row is the ten-field user schema in
 `tests/fixtures/error-dx/user.schema.json`, every export of the compiled module against
-`new Validator(schema)`, built with `bun build --minify --target=browser` on ata 1.47.0.
+`new Validator(schema)`, built with `bun build --minify --target=browser` on ata 1.48.0.
 The startup row is a Hono route on Bun 1.4, the median of three rounds of best-of-seven, from
 `benchmark/bundle`, against 3.5 ms for the same app doing no validation at all, so the
 compiled path costs nothing measurable to start. The runtime figure is what it is because
@@ -551,6 +576,19 @@ npx ata build 'schemas/*.json' --out-dir build/validators --check
 
 Run with `--watch` during development for incremental rebuilds.
 
+In a production build (`--no-source`, or `NODE_ENV=production`), `ata build` can leave the
+error collector out of the modules: each one carries its verdict and its schema, and takes
+its errors from one `ata-errors.mjs` the build writes beside them. The build does this only
+where it makes the output smaller, so a single small schema keeps its self-contained module.
+The errors are the ones `new Validator(schema, { richErrors: false })` reports, in the same
+order. Seven SchemaStore schemas imported into one app, minified with esbuild, go from 148.9 KB
+to 63.3 KB gzipped, and from 35.8 ms to 13.8 ms to import with code generation blocked. A
+rejected document costs more this way, since its errors come from an interpreted walk:
+`--errors inline` keeps every module self-contained. `--mode schema` writes each module as
+its schema and takes the verdict from the runtime too: forty SchemaStore schemas in one app
+come to 101.6 KB gzipped against 212.6 KB as compact modules, and load and check each once in
+23.0 ms against 35.5, while a check once warm costs about five times what generated code costs.
+
 Bundle sizes for the 10-field user schema in `tests/fixtures/error-dx/user.schema.json`,
 minified and gzipped, measured with `bun build --minify --target=browser` on ata 1.45.0:
 
@@ -703,7 +741,7 @@ Copy-paste recipes for the common frameworks. Most need 10-20 lines of glue. See
 
 ### Dialects
 
-`$schema` selects the dialect. Draft 2020-12 is the default, draft-07 is normalized on the way in, and `https://json-schema.org/v1` (or the dated `https://json-schema.org/v1/2026`) selects JSON Schema v1.
+`$schema` selects the dialect. Draft 2020-12 is the default; draft-07, draft-06 and Draft 2019-09 are rewritten to the 2020-12 spelling on the way in (draft-06 as draft-07 without `if`/`then`/`else`, 2019-09's tuple `items` and `$recursiveRef` as `prefixItems` and `$dynamicRef`); and `https://json-schema.org/v1` (or the dated `https://json-schema.org/v1/2026`) selects JSON Schema v1. The official suite passes in full on all five: 1301 of 1301 on 2020-12, 1261 of 1261 on 2019-09, 929 of 929 on draft-07, 841 of 841 on draft-06 and 1135 of 1135 on v1, with code generation allowed and blocked. Draft-04 and earlier are not supported; draft-04's boolean `exclusiveMinimum`/`exclusiveMaximum` is read wherever it appears.
 
 Two things differ under v1. `propertyDependencies` selects a subschema by the value of a property rather than by its presence, which is what `dependentSchemas` does. And `$dynamicRef` no longer requires bookending: the reference resolves through the dynamic scope whether or not the schema it first lands on carries a matching `$dynamicAnchor`, so the outermost matching anchor still in scope wins. Everything else ata implements is identical under both dialects, so a schema that declares no `$schema` behaves exactly as before.
 

package/aot.d.ts

@@ -24,6 +24,46 @@ export function toStandalone(validator: Validator<unknown>): string | null;
 /** Emit one standalone module (no runtime dependency) for one validator. */
 export function toStandaloneModule(validator: Validator<unknown>, opts?: StandaloneOptions): string;
 
+/** Options of toCompactModule. */
+export interface CompactModuleOptions {
+  /** Import specifier of the error runtime the module takes its errors from. */
+  errorRuntime: string;
+  /** Module format for the emitted source. Default: 'esm'. */
+  format?: 'esm' | 'cjs';
+  [key: string]: unknown;
+}
+
+/**
+ * Emit a compact module: the verdict function and the schema without its
+ * descriptive keywords, with error detail from the shared runtime at
+ * `opts.errorRuntime` (see errorRuntimeSource). The errors are the ones the
+ * runtime Validator reports with `richErrors: false`, in its order, and
+ * `errorMessage` is not applied, as in toStandaloneModule. Null when the validator depends on
+ * something outside its schema (custom keywords or formats, registered
+ * schemas, options other than the defaults); write the self-contained module
+ * then. `ata build` makes this choice by itself.
+ */
+export function toCompactModule(validator: Validator<unknown>, opts: CompactModuleOptions): string | null;
+
+/** Why a validator cannot be written as a compact module, or null when it can. */
+export function compactDecline(validator: Validator<unknown>): string | null;
+
+/**
+ * Emit a schema module: the schema without its descriptive keywords and a few
+ * lines; the verdict and the errors come from the runtime at `opts.runtime`
+ * (errorRuntimeSource with `schemaMode`). Far smaller and quicker to load than
+ * generated code, about five times slower per check once warm. Answers as the
+ * runtime Validator does with `richErrors: false`. Null where
+ * toCompactModule would be null. `ata build --mode schema` writes these.
+ */
+export function toSchemaModule(validator: Validator<unknown>, opts: { runtime: string; format?: 'esm' | 'cjs' }): string | null;
+
+/** Source of the runtime compact modules (and, with `schemaMode`, schema
+ * modules) import. With `schemas`, the validators or schemas whose modules
+ * will import it, parts none of them needs are left out. Node only: it is put
+ * together from the library's files. */
+export function errorRuntimeSource(format?: 'esm' | 'cjs', schemas?: ReadonlyArray<unknown> | null, schemaMode?: boolean): string;
+
 /** Emit a module of per-schema compiled validators that `loadBundle` consumes. */
 export function bundle(V: ValidatorClass, schemas: ReadonlyArray<JSONSchema | boolean | object>, opts?: StandaloneOptions): string;
 

package/aot.mjs

@@ -1,3 +1,3 @@
 import mod from './lib/aot-impl.js';
-export const { toStandalone, toStandaloneModule, bundle, bundleStandalone, bundleCompact, loadBundle } = mod;
+export const { toStandalone, toStandaloneModule, toCompactModule, toSchemaModule, compactDecline, errorRuntimeSource, bundle, bundleStandalone, bundleCompact, loadBundle } = mod;
 export default mod;

package/bin/ata.js

@@ -45,6 +45,12 @@ Build options:
   --abort-early           Use stub errors (smallest bundle)
   --one-pass              Report errors with the runtime's one-pass function: faster on
                           rejected documents, a module 1.3 to 1.7x the size
+  --errors <mode>         Where error detail comes from: auto | inline | shared. auto
+                          (default) has modules share one error runtime file when that
+                          makes the output smaller; production builds only (--no-source)
+  --mode <mode>           code (default) | schema. schema writes each module as its
+                          schema and takes the verdict and errors from one runtime
+                          file: far smaller and quicker to load, slower per check
   --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
@@ -94,6 +100,8 @@ function parseArgs(argv) {
     if (a === '--no-types') { out.opts.types = false; continue; }
     if (a === '--abort-early') { out.opts.abortEarly = true; continue; }
     if (a === '--one-pass') { out.opts.onePass = true; continue; }
+    if (a === '--errors') { out.opts.errors = argv[++i]; continue; }
+    if (a === '--mode') { out.opts.mode = argv[++i]; continue; }
     if (a === '--check') { out.opts.check = true; continue; }
     if (a === '--strict') { out.opts.strict = true; continue; }
     if (a === '--strict-schema') { out.opts.strictSchema = true; continue; }
@@ -296,6 +304,8 @@ function cmdBuild(args) {
     suffix: args.opts.suffix,
     abortEarly: !!args.opts.abortEarly,
     onePass: args.opts.onePass === true ? true : undefined,
+    errors: args.opts.errors,
+    mode: args.opts.mode,
     check: !!args.opts.check,
     maxSize: args.opts.maxSize,
     strict: !!args.opts.strict,
@@ -312,7 +322,10 @@ function cmdBuild(args) {
       return;
     }
     for (const c of report.compiled) {
-      process.stdout.write(`ata: ${c.input} -> ${c.output} (${c.bytes.toLocaleString()} bytes)\n`);
+      process.stdout.write(`ata: ${c.input} -> ${c.output} (${c.bytes.toLocaleString()} bytes${c.errors === 'compact' ? ', shared errors' : c.errors === 'schema' ? ', schema module' : ''})\n`);
+    }
+    if (report.runtime) {
+      process.stdout.write(`ata: error runtime -> ${report.runtime.output} (${report.runtime.bytes.toLocaleString()} bytes, shared by the modules above)\n`);
     }
     for (const c of report.cached) {
       process.stdout.write(`ata: cached  ${c.input}\n`);

package/build.d.ts

@@ -190,7 +190,7 @@ export function compiledSchemaFor(schema: unknown): object;
  * {@link compiledEligible} declines, one the emitter cannot compile, and one
  * whose detailed errors the generator cannot produce.
  */
-export function compiledModuleFor(schema: unknown, opts?: { format?: 'esm' | 'cjs' }): string | null;
+export function compiledModuleFor(schema: unknown, opts?: { format?: 'esm' | 'cjs'; errorRuntime?: string }): string | null;
 
 /**
  * The Validator options `fromCompiled()` reproduces, so a plugin can tell

package/error-runtime.d.ts

@@ -0,0 +1,24 @@
+/** One error as a compact module reports it. */
+export interface CompactError {
+  code?: string;
+  keyword: string;
+  instancePath: string;
+  schemaPath: string;
+  params: Record<string, unknown>;
+  message: string;
+  docUrl?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * The error function a compact module calls for a document its verdict
+ * rejected: the errors the runtime Validator reports with
+ * `richErrors: false`, in schema order, or null when it finds none.
+ */
+export function createErrors(schema: object, options?: { v1?: boolean }): (data: unknown) => CompactError[] | null;
+
+/** The linear-time pattern engine compact modules share (the RegExp-like object it returns has `test`). */
+export function compileSafe(source: string): { test(input: string): boolean };
+
+/** The ata-validator version this runtime belongs to. */
+export const ataVersion: string;

package/error-runtime.js

@@ -0,0 +1,40 @@
+'use strict';
+
+// ata-validator/error-runtime: the error runtime compact modules import, for a
+// bundler plugin that writes compact modules into the application's own
+// bundle. The bundler then keeps one copy, shared with ata-validator/compiled
+// where both are used. `ata build` writes the same runtime as a file instead
+// (errorRuntimeSource in ata-validator/aot).
+const ataVersion = require('./lib/version.js');
+
+// The interpreter and the code table load on the first call, not at import:
+// a compact module calls this only when a document it rejected is asked for
+// its errors.
+function createErrors(schema, options) {
+  const { createErrors: create } = require('./lib/error-runtime-entry.js');
+  const { codeOf } = require('./lib/error-code-of.js');
+  return create(schema, codeOf, options);
+}
+
+// The linear-time pattern engine, which a compact module imports from here
+// instead of embedding its own copy.
+let _safe = null;
+function compileSafe(src) {
+  if (_safe === null) _safe = require('./lib/safe-regex.js').compileSafe;
+  return _safe(src);
+}
+
+// Warm-up, in a browser only: the runtime's code compiles on its first use,
+// which a page would otherwise pay for on its first rejected document, about
+// a millisecond. When the browser is idle, one small error list is built here
+// instead, once, so the first real one finds the code compiled. Nothing it
+// does reaches a caller.
+const WARM_SCHEMA = { type: 'object', properties: { a: { type: 'string' }, b: { type: 'integer', minimum: 0 }, c: { anyOf: [{ type: 'string' }, { type: 'null' }] }, f: { type: 'string', format: 'email' } }, required: ['d'], additionalProperties: false };
+function warm() { try { createErrors(WARM_SCHEMA, { flat: true })({ a: 1, b: -1, c: 2, f: 'x', e: 0 }); } catch (_) {} }
+if (typeof requestIdleCallback === 'function') { try { requestIdleCallback(warm); } catch (_) {} }
+// In Node the same happens once the event loop is first free after start-up,
+// on a timer that does not keep the process alive: a script that exits at
+// once never runs it, and a server has it done before its first request.
+else if (typeof process === 'object' && process !== null && process.versions && process.versions.node && typeof setTimeout === 'function') { try { const t = setTimeout(warm, 0); if (t && typeof t.unref === 'function') t.unref(); } catch (_) {} }
+
+module.exports = { createErrors, compileSafe, ataVersion };

package/error-runtime.mjs

@@ -0,0 +1,3 @@
+import mod from './error-runtime.js';
+export const { createErrors, compileSafe, ataVersion } = mod;
+export default mod;

package/index.browser.mjs

@@ -1,5 +1,14 @@
-// Browser ESM entry: the same code, with the native addon stubbed out by the
-// bundler through the package.json "browser" field.
-import mod from './index.js';
-export const { Validator, compile, validate, validateAsync, parseAsync, version, createPaddedBuffer, SIMDJSON_PADDING, parseJSON, toTypeScript, defineSchema, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON } = mod;
-export default mod;
+// Browser ESM entry, for bundlers: the validator core with the code generator
+// registered, as index.js, but with each tool imported on its own (see
+// lib/tools.mjs) so that the tools an application does not import stay out
+// of its bundle. The native addon is stubbed by the package.json "browser"
+// field.
+import core from './lib/validator-core.js';
+import engine from './lib/codegen-engine.js';
+import { toTypeScript, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON } from './lib/tools.mjs';
+
+core._registerCodegen(engine);
+
+export const { Validator, compile, validate, validateAsync, parseAsync, version, createPaddedBuffer, SIMDJSON_PADDING, parseJSON, defineSchema } = core;
+export { toTypeScript, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON };
+export default { Validator, compile, validate, validateAsync, parseAsync, version, createPaddedBuffer, SIMDJSON_PADDING, parseJSON, toTypeScript, defineSchema, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON };

package/index.edge.js

@@ -0,0 +1,14 @@
+'use strict';
+
+// The package for runtimes that cannot run generated code: Cloudflare Workers
+// (the `workerd` export condition) and Vercel Edge (`edge-light`) refuse
+// `new Function`, so the code generator in the full package could only ever
+// fail there and fall back. This entry leaves it out and answers through the
+// interpreted engine, as the full package does in those runtimes: the same
+// names, the same verdicts and errors, a bundle about half the size. Modules
+// from `ata build` and Validator.bundle() load as they do in a browser bundle
+// (lib/aot.browser.js); the emitters are not here, as they are not there.
+const core = require('./lib/validator-core.js');
+core._registerAot(() => require('./lib/aot.browser.js'));
+
+module.exports = require('./lib/public-api.js');

package/index.edge.mjs

@@ -0,0 +1,13 @@
+// ESM edge entry (see index.edge.js): the core without the code generator,
+// for Cloudflare Workers and Vercel Edge, with each tool imported on its own
+// (lib/tools.mjs) so the ones an application does not import stay out of its
+// bundle.
+import core from './lib/validator-core.js';
+import aotBrowser from './lib/aot.browser.js';
+import { toTypeScript, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON } from './lib/tools.mjs';
+
+core._registerAot(() => aotBrowser);
+
+export const { Validator, compile, validate, validateAsync, parseAsync, version, createPaddedBuffer, SIMDJSON_PADDING, parseJSON, defineSchema } = core;
+export { toTypeScript, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON };
+export default { Validator, compile, validate, validateAsync, parseAsync, version, createPaddedBuffer, SIMDJSON_PADDING, parseJSON, toTypeScript, defineSchema, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON };