ata-validator 1.34.0 → 1.36.0

package/README.md

@@ -240,20 +240,21 @@ 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.2 KB** | 92.3 KB |
-| Time to a served request | **3.5 ms** | 11.2 ms |
+| In a bundle, gzipped | **2.2 KB** | 93.2 KB |
+| Time to a served request | **3.5 ms** | 7.7 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.33.1. The startup row is a Hono route on
-Bun 1.4, 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 a schema that arrives at run time can use any keyword, so
-the whole engine has to be there. The compiled module imports nothing and contains only
-the checks your schema asks for.
-
-**On a server, use whichever fits your schemas.** 92 KB of JavaScript on a Node or Bun
+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.35.0.
+The startup row is a Hono route on Bun 1.4, best of seven, median of three rounds, 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
+a schema that arrives at run time can use any keyword, so the whole engine has to be
+there. The compiled module imports nothing and contains only the checks your schema asks
+for.
+
+**On a server, use whichever fits your schemas.** 93 KB of JavaScript on a Node or Bun
 process is not a cost anyone notices, and the runtime API is the simpler thing to reach
 for. Speed is the same either way once warm.
 
@@ -485,7 +486,7 @@ const v = new Validator(schema, {
 
 ### Build-time compile (`ata compile`)
 
-The `ata` CLI turns a JSON Schema file into a self-contained JavaScript module. No runtime dependency on `ata-validator`, so only the generated validator ships to the browser. For the ten-field user schema in `tests/fixtures/error-dx/user.schema.json` the module is 2.6 KB gzipped, full error detail included, against 91 KB for the runtime bundled for the browser.
+The `ata` CLI turns a JSON Schema file into a self-contained JavaScript module. No runtime dependency on `ata-validator`, so only the generated validator ships to the browser. For the ten-field user schema in `tests/fixtures/error-dx/user.schema.json` the module is 2.2 KB gzipped, full error detail included, against 93.2 KB for the runtime bundled for the browser.
 
 ```bash
 npx ata compile schemas/user.json -o src/generated/user.validator.mjs
@@ -527,11 +528,11 @@ npx ata build 'schemas/*.json' --out-dir build/validators --check
 Run with `--watch` during development for incremental rebuilds.
 
 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.33.1:
+minified and gzipped, measured with `bun build --minify --target=browser` on ata 1.35.0:
 
 | What the app imports | Size | Notes |
 |---|---|---|
-| `Validator` from `ata-validator` | 92.3 KB | The compiler ships with it, because a runtime schema can use any keyword |
+| `Validator` from `ata-validator` | 93.2 KB | The compiler ships with it, because a runtime schema can use any keyword |
 | `isValid` from the compiled module | **1.3 KB** | Nothing else is reachable, so the error collector is dropped |
 | `validate` from the compiled module | **2.0 KB** | Adds the detailed error collector |
 

package/build.d.ts

@@ -155,3 +155,26 @@ export function schemaHash(schema: unknown): string;
  * schema, plus `parse` when {@link ToStandaloneModuleOptions.parse} is set
  * and `validateJSON` when {@link ToStandaloneModuleOptions.positions} is. */
 export function toStandaloneModule(schema: unknown, options?: ToStandaloneModuleOptions): string | null;
+
+/**
+ * Whether `new Validator(schema)` with default options can be replaced by
+ * `fromCompiled()` from `ata-validator/compiled`. False for a schema with
+ * custom `errorMessage`s. A caller also needs {@link compiledModuleFor} to
+ * return a module.
+ */
+export function compiledEligible(schema: unknown): boolean;
+
+/**
+ * The schema a default `Validator` reads after normalization. Pass it to
+ * `fromCompiled()`, so defaults, error order and diagnostics follow the same
+ * document the runtime does.
+ */
+export function compiledSchemaFor(schema: unknown): object;
+
+/**
+ * The module that replaces `new Validator(schema)`, or null where the
+ * replacement would not answer as the runtime does: a schema
+ * {@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;

package/build.mjs

@@ -8,4 +8,8 @@ export const watch = mod.watch;
 export const bundleStandalone = mod.bundleStandalone;
 export const bundleCompact = mod.bundleCompact;
 export const toStandaloneModule = mod.toStandaloneModule;
+export const schemaHash = mod.schemaHash;
+export const compiledEligible = mod.compiledEligible;
+export const compiledSchemaFor = mod.compiledSchemaFor;
+export const compiledModuleFor = mod.compiledModuleFor;
 export default mod;

package/compiled.d.ts

@@ -0,0 +1,17 @@
+// ata-validator/compiled: the wrapper a bundler plugin puts in place of
+// `new Validator(schema)` for a schema known at build time.
+import type { ValidationResult } from './index.js';
+
+export interface CompiledModule {
+  validate(data: unknown): { valid: boolean; errors: unknown[] };
+  isValid(data: unknown): boolean;
+}
+
+export interface CompiledValidator<T = unknown> {
+  validate(data: unknown): ValidationResult<T>;
+  isValidObject(data: unknown): data is T;
+  validateJSON(json: string): { valid: boolean; errors: unknown[] };
+  isValidJSON(json: string): boolean;
+}
+
+export function fromCompiled<T = unknown>(mod: CompiledModule, schema: object): CompiledValidator<T>;

package/compiled.js

@@ -0,0 +1,7 @@
+'use strict';
+
+// ata-validator/compiled: the wrapper a bundler plugin puts in place of
+// `new Validator(schema)` when the schema is known at build time. It takes the
+// module `compiledModuleFor(schema)` from ata-validator/build wrote, and answers
+// as a default Validator does, without the runtime compiler in the bundle.
+module.exports = require('./lib/compiled.js');

package/compiled.mjs

@@ -0,0 +1,3 @@
+import mod from './compiled.js';
+export const { fromCompiled } = mod;
+export default mod;

package/index.browser.mjs

@@ -1,4 +1,5 @@
-// Browser ESM entry — same code, native addon stubbed out by bundler via "browser" field.
+// 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, validate, validateAsync, parseAsync, version, createPaddedBuffer, SIMDJSON_PADDING, renderPretty, renderCompact, renderJSON, toTypeScript } = mod;
+export const { Validator, compile, validate, validateAsync, parseAsync, version, createPaddedBuffer, SIMDJSON_PADDING, parseJSON, toTypeScript, defineSchema, renderPretty, renderCompact, toOutput, toRetryMessage, describeSchema, renderJSON } = mod;
 export default mod;

package/index.d.ts

@@ -407,6 +407,12 @@ export interface ValidatorOptions {
    * `'log'` warns through `logger` (or the console) and continues.
    */
   strictSchema?: boolean | 'log';
+  /**
+   * The URI the schema was retrieved from. Relative references resolve against
+   * it when the schema declares no `$id` of its own, including a draft-07 root
+   * whose `$id` sits beside a `$ref` and is therefore ignored.
+   */
+  baseURI?: string;
   /** Receives `strictSchema: 'log'` warnings; `false` silences them. */
   logger?: { warn(...args: unknown[]): void } | false;
   /**