ata-validator 0.18.2 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 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.20.1 - 2026-05-27
+
+### Fixed
+
+- `JSONSchema.items` now accepts `boolean` so the typed `t.tuple([...])` output (which sets `items: false` to close the tail) type-checks against `JSONSchema` without a constraint error. `items: false` is valid JSON Schema and the runtime already honoured it; the type definition just had not been widened. Anyone consuming `t.tuple` from outside a project with `skipLibCheck` ran into a `TTuple incorrectly extends JSONSchema` error.
+
+## 0.20.0 - 2026-05-27
+
+### Added
+
+- New chainable schema builder at `ata-validator/t`. Each `t.X(...)` returns a plain JSON Schema literal, so the output drops straight into `new Validator(...)`, `defineSchema`, `Infer<S>`, and the AOT pipeline with no adapter. The migration target is TypeBox: rename `import { Type } from '@sinclair/typebox'` to `import { t } from 'ata-validator/t'` and keep the same authoring shape while picking up ata's runtime and AOT precompile.
+
+  ```ts
+  import { t } from 'ata-validator/t'
+  import { Validator, type Infer } from 'ata-validator'
+
+  const User = t.object({
+    id: t.integer(),
+    name: t.string({ minLength: 1 }),
+    email: t.optional(t.string({ format: 'email' })),
+    role: t.union([t.literal('admin'), t.literal('user')]),
+  })
+  type User = Infer<typeof User>
+  const v = new Validator(User)
+  ```
+
+  Covered: primitives (`string`, `number`, `integer`, `boolean`, `null`), composites (`object` with `optional` keys, `array`, `tuple`, `record`, `union`, `intersect`, `literal`, `const`, `enum`), and refs (`ref`). Optionality is carried by a Symbol-keyed marker that the emitted JSON Schema, `Object.keys`, `JSON.stringify`, and ata's codegen never see; the parent `t.object` reads it to compute `required`.
+
+### Changed
+
+- `Infer<S>` now resolves object schemas without `properties` but with a schema-valued `additionalProperties` to `Record<string, V>` instead of `Record<string, unknown>`. Closes the last common JSON Schema shape that was not inferred.
+
+## 0.19.0 - 2026-05-27
+
+### Added
+
+- `ata-validator/build` now exports the AOT primitives `bundleStandalone`, `bundleCompact`, and `toStandaloneModule` as named functions, so callers that want the build surface in one place (bundler plugins, build scripts) no longer have to go through the `Validator` class. Same code paths as the Validator-bound forms, no behaviour difference.
+- New top-level `ARCHITECTURE.md` reference document covering design principles, runtime dispatch, AOT pipeline, error enrichment, the two TypeScript paths, and the native layer.
+
+### Changed
+
+- Internal refactor: AOT (`toStandalone`, `toStandaloneModule`, `bundle`, `bundleStandalone`, `bundleCompact`, `loadBundle`) lives in `lib/aot.js`, the native addon loader in `lib/native-load.js`, the version string in `lib/version.js`. `index.js` lazy-requires the AOT module so a plain import never pays for code it does not call. The browser bundle drops `pkg-prebuilds`, `__dirname`, and `package.json` (with its dependency strings) entirely; it is roughly 15 KB smaller and contains no Node-only identifiers outside comments.
+- The safe-regex engine is now embedded into standalone output from a baked string (`lib/safe-regex-source.js`, generated from `lib/safe-regex.js`) instead of a runtime `fs.readFileSync`. Browser AOT calls (`Validator.bundle`, `toStandaloneModule`, …) work in any bundler without an fs polyfill. A structural test (`tests/test_browser_imports_guard.js`) bundles both entries with esbuild and asserts no `readFileSync`, `pkg-prebuilds`, or `__dirname` survives outside comments; sync tests catch drift between the bundled strings and their sources.
+
 ## 0.18.2 - 2026-05-26
 
 ### Fixed

package/README.md

@@ -70,6 +70,27 @@ The `ata` CLI ships `ata validate <schema> <data>` for one-off checks. TTY auto-
 
 Errors carry a stable `code` field (`ATA####`), see the [error code registry](docs/error-codes.md). Each code has a permalink at `https://ata-validator.com/e/<CODE>`.
 
+### Custom messages
+
+A subschema can override the human-facing message with an `errorMessage` keyword. A string replaces the message for any failing keyword on that subschema; an object overrides per keyword, with `required` keyed by the missing property name (or a single string) and `_` as a fallback. The `code`, `keyword`, and `path` fields are untouched, so dashboards and renderers keep working.
+
+```js
+const v = new Validator({
+  type: 'object',
+  properties: {
+    age: { type: 'integer', minimum: 18, errorMessage: { minimum: 'must be 18 or older', type: 'age has to be a number' } },
+    email: { type: 'string', format: 'email', errorMessage: 'enter a valid email address' },
+  },
+  required: ['email'],
+  errorMessage: { required: { email: 'email is required' } },
+})
+
+v.validate({ age: 5 }).errors[0].message      // 'must be 18 or older'
+v.validate({}).errors[0].message              // 'email is required'
+```
+
+Schemas without an `errorMessage` keyword pay nothing: the override pass is only installed when one is present.
+
 ### Opting out
 
 For consumers who built log dashboards on the v0.14 error shape, `new Validator(schema, { richErrors: false })` returns the legacy shape exactly. For high-throughput paths, `abortEarly: true` continues to short-circuit; the returned error carries `code: 'ATA9000'` and no enrichment.
@@ -183,6 +204,52 @@ type Event = Infer<typeof event>
 
 `Infer` resolves `const`/`enum` to literals, `anyOf`/`oneOf` to unions, `allOf` to intersections, `prefixItems` to tuples, and local `$ref` into `#/$defs` or `#/definitions`, including recursive references. An external or unresolvable `$ref` resolves to `unknown` rather than erroring. The exported `JSONSchema` type is available if you want to annotate a schema by hand; custom and vendor keywords are allowed. Requires TypeScript >= 5.0.
 
+#### Chainable authoring with `ata-validator/t`
+
+If you prefer a chainable builder over JSON Schema literals, `ata-validator/t` ships one whose output is still plain JSON Schema. The runtime validator, `Infer<S>`, and the AOT pipeline all keep working without an adapter. The migration from TypeBox is one import rename, then the same authoring shape:
+
+```ts
+import { t } from 'ata-validator/t'
+import { Validator, type Infer } from 'ata-validator'
+
+const User = t.object({
+  id: t.integer(),
+  name: t.string({ minLength: 1 }),
+  email: t.optional(t.string({ format: 'email' })),
+  role: t.union([t.literal('admin'), t.literal('user')]),
+})
+
+type User = Infer<typeof User>
+// { id: number; name: string; role: 'admin' | 'user'; email?: string }
+
+const v = new Validator(User)
+```
+
+The builder covers primitives (`string`, `number`, `integer`, `boolean`, `null`), composites (`object` with `optional` keys, `array`, `tuple`, `record`, `union`, `intersect`, `literal`, `const`, `enum`), and refs (`ref`). Optionality is carried by a Symbol marker that the emitted JSON Schema and ata's codegen never see, so the output is still a plain JSON Schema literal that you can pass to anything that takes one.
+
+#### Async refinement
+
+JSON Schema is synchronous, so checks that need to await, a uniqueness lookup, a remote call, a cross-field rule, attach to a schema with `t.refine` and run through `validateAsync`. The refinement rides on a Symbol marker, so `new Validator(schema)` still does plain structural validation and ignores it; only `validateAsync`/`parseAsync` evaluate it, and only after the value is structurally valid.
+
+```ts
+import { t } from 'ata-validator/t'
+import { validateAsync, parseAsync } from 'ata-validator'
+
+const Signup = t.refine(
+  t.object({ username: t.string({ minLength: 3 }), email: t.string({ format: 'email' }) }),
+  async (value) => !(await usernameTaken(value.username)),
+  { message: 'username is already taken', path: '/username' },
+)
+
+const r = await validateAsync(Signup, body)
+if (!r.valid) return reply.code(400).send(r.errors)
+
+// or: resolves to the typed value, throws on failure with err.errors
+const user = await parseAsync(Signup, body)
+```
+
+Refinements compose by wrapping again, and a failing one surfaces as an error with `keyword: 'refine'` carrying your `message` and `path`. A `check` may be sync or async.
+
 #### Composes with TypeBox, Zod, or your own types
 
 `Validator<T>` is generic, so if you already author schemas with a library, pass the type and ata narrows to it. No library-specific assumption.

package/build.d.ts

@@ -67,3 +67,31 @@ export interface WatchHandle {
   close(): void;
 }
 export function watch(opts: BuildOptions, onReport?: (r: BuildReport) => void): Promise<WatchHandle>;
+
+// --- AOT primitives ---
+// Programmatic counterparts to `Validator.bundleStandalone` / `bundleCompact`
+// and `validator.toStandaloneModule`. Kept here so callers that only want the
+// build surface (e.g. a bundler plugin) don't have to import the full runtime.
+
+export interface BundleStandaloneOptions {
+  format?: 'cjs' | 'esm';
+  formats?: Record<string, (value: unknown) => boolean>;
+  verbose?: boolean;
+}
+
+export interface ToStandaloneModuleOptions {
+  format?: 'cjs' | 'esm';
+  abortEarly?: boolean;
+  source?: boolean;
+  sourceMap?: unknown;
+  schemaFile?: string;
+}
+
+/** Bundle multiple schemas into one self-contained module (no ata-validator runtime). */
+export function bundleStandalone(schemas: unknown[], options?: BundleStandaloneOptions): string;
+
+/** Like {@link bundleStandalone} but deduplicates shared bodies for smaller output. */
+export function bundleCompact(schemas: unknown[], options?: BundleStandaloneOptions): string;
+
+/** Emit a self-contained `validate`/`isValid` module string for a single schema. */
+export function toStandaloneModule(schema: unknown, options?: ToStandaloneModuleOptions): string | null;

package/build.mjs

@@ -5,4 +5,7 @@ export const expandGlobs = mod.expandGlobs;
 export const parseSchemaFile = mod.parseSchemaFile;
 export const outputPathFor = mod.outputPathFor;
 export const watch = mod.watch;
+export const bundleStandalone = mod.bundleStandalone;
+export const bundleCompact = mod.bundleCompact;
+export const toStandaloneModule = mod.toStandaloneModule;
 export default mod;

package/index.browser.mjs

@@ -1,4 +1,4 @@
 // Browser ESM entry — same code, native addon stubbed out by bundler via "browser" field.
 import mod from './index.js';
-export const { Validator, validate, version, createPaddedBuffer, SIMDJSON_PADDING, renderPretty, renderCompact, renderJSON, toTypeScript } = mod;
+export const { Validator, validate, validateAsync, parseAsync, version, createPaddedBuffer, SIMDJSON_PADDING, renderPretty, renderCompact, renderJSON, toTypeScript } = mod;
 export default mod;

package/index.d.ts

@@ -75,6 +75,18 @@ export function renderJSON(errors: RichValidationError[], opts?: JSONRenderOptio
 /** A user-supplied format checker. Receives the candidate value, returns true if valid. */
 export type FormatChecker = (value: string) => boolean;
 
+/**
+ * Per-keyword custom error messages for a subschema's `errorMessage`. Keys are
+ * keyword names (`type`, `minimum`, `pattern`, ...). `required` may be a single
+ * string or a map keyed by the missing property name. `_` is the fallback used
+ * when no keyword-specific entry matches.
+ */
+export interface ErrorMessageMap {
+  required?: string | Record<string, string>;
+  _?: string;
+  [keyword: string]: string | Record<string, string> | undefined;
+}
+
 /** The seven primitive `type` values defined by JSON Schema. */
 export type JSONSchemaTypeName =
   | 'string'
@@ -125,7 +137,7 @@ export interface JSONSchema {
   dependentSchemas?: Record<string, JSONSchema>;
 
   // array
-  items?: JSONSchema | ReadonlyArray<JSONSchema>;
+  items?: JSONSchema | ReadonlyArray<JSONSchema> | boolean;
   prefixItems?: ReadonlyArray<JSONSchema>;
   additionalItems?: boolean | JSONSchema;
   contains?: JSONSchema;
@@ -160,6 +172,15 @@ export interface JSONSchema {
   /** OpenAPI compatibility: ata honors `nullable` as a JSON Schema extension. */
   nullable?: boolean;
 
+  /**
+   * Override the human-facing `message` on errors this subschema produces.
+   * A string replaces the message for any failing keyword; an object overrides
+   * per keyword, with `required` keyed by missing property name (or a single
+   * string) and `_` as a fallback. Other fields (`code`, `keyword`, `path`)
+   * are unaffected.
+   */
+  errorMessage?: string | ErrorMessageMap;
+
   /** Custom and vendor keywords are allowed without error. */
   [keyword: string]: unknown;
 }
@@ -202,13 +223,19 @@ type ResolveRef<R, D> = [RefName<R>] extends [never]
     ? InferWith<D[RefName<R>], D>
     : unknown;
 
-/** Object shape: required keys are required, all other declared keys optional. */
+/** Object shape: required keys are required, all other declared keys optional.
+ * When `properties` is absent and `additionalProperties` is a schema, infer
+ * a `Record<string, V>` (the JSON Schema "dictionary"/"record" shape). */
 type InferObject<S, D> = S extends { properties: infer P }
   ? Simplify<
       { [K in keyof P as K extends RequiredKeys<S> ? K : never]: InferWith<P[K], D> } &
       { [K in keyof P as K extends RequiredKeys<S> ? never : K]?: InferWith<P[K], D> }
     >
-  : Record<string, unknown>;
+  : S extends { additionalProperties: infer A }
+    ? A extends boolean
+      ? Record<string, unknown>
+      : Record<string, InferWith<A, D>>
+    : Record<string, unknown>;
 
 /** Array shape: `prefixItems` -> tuple; `items` (single schema) -> element type; otherwise unknown[]. */
 type InferArray<S, D> = S extends { prefixItems: infer P }
@@ -438,6 +465,34 @@ export function validate<T = unknown>(
   data: unknown
 ): ValidationResult<T>;
 
+/**
+ * Async validate for schemas built with `t.refine(...)`. Structural JSON Schema
+ * validation runs synchronously first; refinements are awaited only when the
+ * value is structurally valid. Failing refinements surface as errors with
+ * `keyword: 'refine'`. Accepts a schema literal or an existing {@link Validator}.
+ */
+export function validateAsync<T>(
+  validator: Validator<T>,
+  data: unknown
+): Promise<ValidationResult<T>>;
+export function validateAsync<const S extends JSONSchema>(
+  schema: S,
+  data: unknown
+): Promise<ValidationResult<Infer<S>>>;
+export function validateAsync<T = unknown>(
+  schema: object,
+  data: unknown
+): Promise<ValidationResult<T>>;
+
+/**
+ * Like {@link validateAsync}, but resolves to the validated data on success and
+ * rejects with an `Error` whose `errors` property holds the
+ * {@link ValidationError} list on failure.
+ */
+export function parseAsync<T>(validator: Validator<T>, data: unknown): Promise<T>;
+export function parseAsync<const S extends JSONSchema>(schema: S, data: unknown): Promise<Infer<S>>;
+export function parseAsync<T = unknown>(schema: object, data: unknown): Promise<T>;
+
 /** Fast compile: returns a validate function directly. WeakMap cached, second call with same schema is near-zero cost. */
 export function compile<T = unknown>(
   schema: object | string,