ata-validator 1.49.0 → 1.51.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
@@ -574,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:
 

package/aot.d.ts

@@ -24,6 +24,56 @@ 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; registry?: string; format?: 'esm' | 'cjs' }): string | null;
+
+/**
+ * Source of the registry module schema modules import when their schemas
+ * reference each other by `$id`: the schemas, without descriptive keywords,
+ * as one array. Pass its import specifier as `registry` to toSchemaModule,
+ * for a validator built with those schemas in its `schemas` option; the module
+ * then names its schema by `$id` and carries no copy of it. `ata build --mode
+ * schema` does this for inputs that reference each other.
+ */
+export function registrySource(schemas: ReadonlyArray<object | Validator<unknown>>, format?: 'esm' | 'cjs'): string;
+
+/** 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, registrySource, compactDecline, errorRuntimeSource, bundle, bundleStandalone, bundleCompact, loadBundle } = mod;
 export default mod;

package/bin/ata.js

@@ -45,6 +45,15 @@ 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
+  --base-uri <uri>        The URI an input without $id is known by: <uri> plus its
+                          file name, for schemas that reference a shared file by URL
+                          or relative path
   --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 +103,9 @@ 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 === '--base-uri') { out.opts.baseUri = 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 +308,9 @@ 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,
+    baseUri: args.opts.baseUri,
     check: !!args.opts.check,
     maxSize: args.opts.maxSize,
     strict: !!args.opts.strict,
@@ -312,7 +327,26 @@ 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`);
+      if (report.runtime.registry) process.stdout.write(`ata: schema registry -> ${report.runtime.registry.output} (${report.runtime.registry.bytes.toLocaleString()} bytes, the schemas the modules above reference)\n`);
+    }
+    // A module the error generator declined still has an exact verdict, but
+    // every failure is the one ATA9000 error. Said once per module, short,
+    // and once with what to do about it.
+    let noDetail = 0;
+    for (const w of report.warnings || []) {
+      if (w.kind === 'error-detail') {
+        noDetail++;
+        process.stderr.write(`ata: warning ${w.input}: no error detail, failures report the single ATA9000 error (the verdict is exact)\n`);
+      } else {
+        process.stderr.write(`ata: warning ${w.input}: ${w.warning}\n`);
+      }
+    }
+    if (noDetail > 0 && args.opts.mode !== 'schema') {
+      process.stderr.write(`ata: ${noDetail} module${noDetail === 1 ? '' : 's'} without error detail; with --mode schema a module takes its errors from the interpreted engine instead\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 };