ata-validator 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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

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/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;
 }
@@ -444,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,

package/index.js

@@ -1064,6 +1064,44 @@ class Validator {
       };
     }
 
+    // Custom error messages: if any subschema declares an `errorMessage`
+    // keyword, install an outermost decorator that overrides the `message`
+    // field of the errors it owns. Gated on a one-time scan so schemas without
+    // errorMessage keep the validate hot path untouched. Layered after rich
+    // enrichment so `code`/`keyword`/`path` are already final and only the
+    // human-facing message changes.
+    {
+      const emLib = require('./lib/error-messages');
+      const schemaStr = this._schemaStr || (this._schemaObj ? JSON.stringify(this._schemaObj) : '');
+      if (emLib.schemaHasErrorMessages(schemaStr)) {
+        const root = this._schemaObj;
+        const wrap = (inner) => (arg) => {
+          const result = inner(arg);
+          if (result && result.valid === false && result.errors && result.errors.length && result !== ABORT_EARLY_RESULT) {
+            const overridden = emLib.applyErrorMessages(result.errors, root);
+            if (overridden !== result.errors) return { valid: false, errors: overridden };
+          }
+          return result;
+        };
+        if (this.validate) this.validate = wrap(this.validate);
+        if (this.validateJSON) this.validateJSON = wrap(this.validateJSON);
+        // validateAndParse routes through self.validate on the codegen path, but
+        // the native-only path returns directly from the addon — wrap it so both
+        // paths get overrides. The result shape carries `value`, preserved here.
+        if (this.validateAndParse) {
+          const innerVP = this.validateAndParse;
+          this.validateAndParse = (arg) => {
+            const result = innerVP(arg);
+            if (result && result.valid === false && result.errors && result.errors.length) {
+              const overridden = emLib.applyErrorMessages(result.errors, root);
+              if (overridden !== result.errors) return { valid: false, value: result.value, errors: overridden };
+            }
+            return result;
+          };
+        }
+      }
+    }
+
     // Save to identity cache for ultra-fast reuse with same schema object
     if (this._schemaObj && typeof this._schemaObj === 'object') {
       _identityCache.set(this._schemaObj, this);
@@ -1322,6 +1360,41 @@ function validate(schema, data) {
   return v.validate(data);
 }
 
+// Async validation for schemas built with `t.refine(...)`. Structural
+// validation runs synchronously first; refinements are awaited only when the
+// value is structurally valid (a refinement body may assume the right shape).
+// Accepts a schema literal or an existing Validator instance plus its schema.
+// Returns a Promise<ValidationResult>.
+async function validateAsync(schemaOrValidator, data) {
+  const refineLib = require('./lib/refine');
+  let validator, schema;
+  if (schemaOrValidator instanceof Validator) {
+    validator = schemaOrValidator;
+    schema = validator._schemaObj;
+  } else {
+    schema = schemaOrValidator;
+    validator = new Validator(schema);
+  }
+  const structural = validator.validate(data);
+  if (!structural.valid) return structural;
+  const refinements = refineLib.getRefinements(schema);
+  if (!refinements) return structural;
+  const issues = await refineLib.runRefinements(refinements, structural.data !== undefined ? structural.data : data);
+  if (issues.length) return { valid: false, errors: issues };
+  return structural;
+}
+
+// parseAsync resolves to the validated data, or rejects with an Error whose
+// `.errors` carries the ValidationError list. Mirrors the parse/validate split
+// used by Zod-style callers.
+async function parseAsync(schemaOrValidator, data) {
+  const result = await validateAsync(schemaOrValidator, data);
+  if (result.valid) return result.data !== undefined ? result.data : data;
+  const err = new Error('ata: async validation failed');
+  err.errors = result.errors;
+  throw err;
+}
+
 function version() {
   if (native) return native.version();
   try { return require("./lib/version"); } catch { return "unknown"; }
@@ -1420,6 +1493,8 @@ module.exports = {
   Validator,
   compile,
   validate,
+  validateAsync,
+  parseAsync,
   version,
   createPaddedBuffer,
   SIMDJSON_PADDING,

package/index.mjs

@@ -1,3 +1,3 @@
 import mod from './index.js';
-export const { Validator, validate, version, createPaddedBuffer, SIMDJSON_PADDING, defineSchema, renderPretty, renderCompact, renderJSON } = mod;
+export const { Validator, validate, validateAsync, parseAsync, version, createPaddedBuffer, SIMDJSON_PADDING, defineSchema, renderPretty, renderCompact, renderJSON } = mod;
 export default mod;

package/lib/error-messages.js

@@ -0,0 +1,88 @@
+'use strict';
+
+// Custom error messages via the `errorMessage` keyword.
+//
+// A subschema may declare an `errorMessage` keyword to override the generated
+// `message` on any error it owns:
+//
+//   errorMessage: "single message for any failure of this subschema"
+//   errorMessage: {
+//     <keyword>: "msg",                 // e.g. minimum, type, pattern, format
+//     required: "msg" | { prop: "msg" },// keyed by missing property, or one string
+//     additionalProperties: "msg",
+//     _: "fallback msg",                // used when no keyword-specific entry matches
+//   }
+//
+// Resolution: each error's owning subschema is located from its schemaPath (the
+// keyword is the last pointer segment, the owner is everything before it). If the
+// owner declares an errorMessage, the error's `message` is replaced. Errors are
+// cloned, never mutated, so frozen/shared results stay intact. When no schema in
+// the tree carries an errorMessage the decorator is never installed, so the
+// validate hot path keeps its original cost.
+
+// Locate the schema object that owns the failing keyword. Mirrors
+// resolveSchemaByPath() in index.js: the last pointer segment is the keyword,
+// so the owner is the node reached by walking every segment before it.
+function resolveOwner (rootSchema, schemaPath) {
+  if (!schemaPath || typeof schemaPath !== 'string' || schemaPath[0] !== '#') return undefined;
+  const stripped = schemaPath.slice(1);
+  if (!stripped || stripped === '/') return rootSchema;
+  const parts = stripped.split('/').filter(Boolean).map((s) => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let target = rootSchema;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (target == null || typeof target !== 'object') return undefined;
+    target = target[parts[i]];
+  }
+  return target;
+}
+
+// Pick the override string for a single error from its owner's errorMessage.
+// Returns undefined when nothing matches, leaving the default message in place.
+function pickMessage (em, err) {
+  if (em == null) return undefined;
+  if (typeof em === 'string') return em;
+  if (typeof em !== 'object') return undefined;
+
+  const kw = err.keyword;
+
+  if (kw === 'required') {
+    const r = em.required;
+    if (typeof r === 'string') return r;
+    if (r && typeof r === 'object') {
+      const prop = err.params && err.params.missingProperty;
+      if (prop != null && typeof r[prop] === 'string') return r[prop];
+    }
+  }
+
+  if (kw != null && typeof em[kw] === 'string') return em[kw];
+  if (typeof em._ === 'string') return em._;
+  return undefined;
+}
+
+// Returns true when the schema string is worth scanning at validate time.
+function schemaHasErrorMessages (schemaStr) {
+  return typeof schemaStr === 'string' && schemaStr.indexOf('"errorMessage"') !== -1;
+}
+
+// Apply overrides across an error array. Returns the same array reference when
+// nothing changed (so callers can cheaply detect a no-op), or a new array with
+// cloned-and-overridden entries.
+function applyErrorMessages (errors, rootSchema) {
+  if (!errors || !errors.length) return errors;
+  let changed = false;
+  const out = new Array(errors.length);
+  for (let i = 0; i < errors.length; i++) {
+    const err = errors[i];
+    out[i] = err;
+    if (!err || typeof err.schemaPath !== 'string') continue;
+    const owner = resolveOwner(rootSchema, err.schemaPath);
+    if (!owner || typeof owner !== 'object') continue;
+    const msg = pickMessage(owner.errorMessage, err);
+    if (msg == null) continue;
+    out[i] = Object.assign({}, err, { message: msg });
+    changed = true;
+  }
+  return changed ? out : errors;
+}
+
+module.exports = { schemaHasErrorMessages, applyErrorMessages, resolveOwner, pickMessage };

package/lib/refine.js

@@ -0,0 +1,68 @@
+'use strict';
+
+// Async refinement support for the `/t` builder.
+//
+// JSON Schema is synchronous by design and cannot express a check that needs to
+// await (uniqueness, a remote lookup, cross-field business rules). Those live on
+// the builder via `t.refine(schema, check, opts)`. A refinement is carried on a
+// Symbol key (like the OPTIONAL marker), so it is invisible to Object.keys,
+// JSON.stringify, and ata's codegen: `new Validator(schema)` still performs
+// plain structural validation and ignores refinements entirely.
+//
+// `validateAsync()` (in index.js) runs structural validation first and only
+// awaits the refinements when the value is structurally valid — a refinement
+// body may assume the value already has the right shape.
+
+const REFINE = Symbol.for('ata.t.refine');
+
+// Pull the refinement list off a schema node, or null when there is none.
+function getRefinements (schema) {
+  if (!schema || typeof schema !== 'object') return null;
+  const r = schema[REFINE];
+  return Array.isArray(r) && r.length ? r : null;
+}
+
+// Attach a refinement to a schema, composing with any already present. Returns a
+// new object; the input is not mutated. Enumerable Symbol keys (OPTIONAL, prior
+// refinements) are copied by the spread, then the refinement list is replaced.
+function attach (schema, check, opts) {
+  if (typeof check !== 'function') {
+    throw new TypeError('t.refine(schema, check, opts?) — check must be a function');
+  }
+  const prev = (schema && Array.isArray(schema[REFINE])) ? schema[REFINE] : [];
+  const o = opts || {};
+  const entry = { check, message: o.message, path: o.path || '' };
+  return Object.assign({}, schema, { [REFINE]: prev.concat(entry) });
+}
+
+// Build a single refinement issue in the validator's error shape.
+function issue (entry, message) {
+  return {
+    keyword: 'refine',
+    instancePath: entry.path || '',
+    path: entry.path || '',
+    schemaPath: '',
+    params: {},
+    message: message != null ? message : (entry.message || 'value failed refinement'),
+  };
+}
+
+// Evaluate every refinement against `data`, awaiting async checks concurrently.
+// A check that returns falsy — or throws — yields an issue. Returns the issues
+// array (empty when all pass).
+async function runRefinements (refinements, data) {
+  const issues = [];
+  await Promise.all(refinements.map(async (entry) => {
+    let passed;
+    try {
+      passed = await entry.check(data);
+    } catch (e) {
+      issues.push(issue(entry, entry.message || (e && e.message) || 'refinement threw'));
+      return;
+    }
+    if (!passed) issues.push(issue(entry));
+  }));
+  return issues;
+}
+
+module.exports = { REFINE, getRefinements, attach, runRefinements };

package/lib/t.js

@@ -12,6 +12,7 @@
 // to compute `required` and strips it from the emitted property schema.
 
 const OPTIONAL = Symbol.for('ata.t.optional');
+const { attach: attachRefine } = require('./refine');
 
 function string(opts) {
   return Object.assign({ type: 'string' }, opts);
@@ -116,6 +117,13 @@ function never() {
   return { not: {} };
 }
 
+function refine(schema, check, opts) {
+  // Attach an async/sync refinement. The schema stays plain JSON Schema for
+  // structural validation; the refinement is carried on a Symbol key and only
+  // runs via validateAsync()/parseAsync(). Compose by wrapping again.
+  return attachRefine(schema, check, opts);
+}
+
 module.exports = {
   string,
   number,
@@ -136,5 +144,6 @@ module.exports = {
   any,
   unknown,
   never,
+  refine,
   OPTIONAL,
 };

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "JSON Schema validation with first-class TypeScript and zero runtime cost. AOT compile to per-schema ESM modules with zero validator dependency. Generic Validator<T> for TypeBox/Zod/Valibot composition. Optional runtime API. Standard Schema V1 compatible.",
   "main": "index.js",
   "module": "index.mjs",
@@ -48,7 +48,7 @@
     "rebuild": "cmake-js rebuild --target ata",
     "prebuild": "pkg-prebuilds-copy --baseDir build/Release --source ata.node --name=ata --strip --napi_version=10",
     "prebuild-all": "npm run prebuild -- --arch x64 && npm run prebuild -- --arch arm64",
-    "test": "node test.js && node tests/test_no_native.js && node tests/test_browser_nofs.js && node tests/test_browser_imports_guard.js && node tests/test_version_sync.js && node tests/test_safe_regex_source_sync.js && node tests/test_t_builder.js && node tests/test_safe_regex.js && node tests/test_safe_regex_integration.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_standalone_anyof.js && node tests/test_standalone_formats.js && node tests/test_aot_additional_props_errors.js && node tests/test_id_anchor_refs.js && node tests/test_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.js && node tests/test_nullable.js && node tests/test_validate_and_parse.js && node tests/test_validate_data.js && node tests/test_enrich_error.js && node tests/test_rich_errors_optout.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node tests/test_cli_version.js && node benchmark/bench_aot_size.mjs",
+    "test": "node test.js && node tests/test_no_native.js && node tests/test_browser_nofs.js && node tests/test_browser_imports_guard.js && node tests/test_version_sync.js && node tests/test_safe_regex_source_sync.js && node tests/test_t_builder.js && node tests/test_async_refine.js && node tests/test_safe_regex.js && node tests/test_safe_regex_integration.js && node tests/test_aot_build.js && node tests/test_aot_differential.js && node tests/test_aot_cli_build.js && node tests/test_aot_cli_smoke.js && node tests/test_bundle_standalone.js && node tests/test_standalone_anyof.js && node tests/test_standalone_formats.js && node tests/test_aot_additional_props_errors.js && node tests/test_id_anchor_refs.js && node tests/test_typed_validator_runner.js && node tests/test_define_schema.js && node tests/test_error_codes_lock.js && node tests/test_nullable.js && node tests/test_validate_and_parse.js && node tests/test_validate_data.js && node tests/test_enrich_error.js && node tests/test_rich_errors_optout.js && node tests/test_error_messages.js && node tests/test_source_positions.js && node tests/fuzz_positions.js && node tests/test_data_positions.js && node tests/test_render_shared.js && node tests/test_renderers.js && node tests/test_runtime_error_dx.js && node tests/test_aot_error_dx.js && node tests/test_abort_early.js && node tests/test_branch_collapse.js && node tests/test_suggestions.js && node tests/test_cli_validate.js && node tests/test_cli_version.js && node benchmark/bench_aot_size.mjs",
     "bench:size": "node benchmark/bench_aot_size.mjs",
     "test:suite": "node tests/run_suite.js",
     "test:compat": "node tests/test_compat.js",

package/t.d.ts

@@ -15,10 +15,21 @@
 //
 //   const v = new Validator(User)  // schema is plain JSON Schema
 
-import type { JSONSchema } from './index.js';
+import type { JSONSchema, Infer } from './index.js';
 
 export declare const OPTIONAL: unique symbol;
 
+/** Options for {@link TBuilder.refine}. */
+export interface RefineOptions {
+  /** Message attached to the error when the refinement fails. */
+  message?: string;
+  /** instancePath the error points at (e.g. `/email`). Defaults to the root. */
+  path?: string;
+}
+
+/** A refinement check: receives the structurally-valid value, returns (a promise of) a boolean. */
+export type RefineCheck<T> = (value: T) => boolean | Promise<boolean>;
+
 export type TOptional<S> = S & { readonly [OPTIONAL]: true };
 
 export type TSchema = JSONSchema;
@@ -181,6 +192,14 @@ export interface TBuilder {
   any(): TAny;
   unknown(): TAny;
   never(): TNever;
+
+  /**
+   * Attach an async (or sync) refinement to a schema. The schema stays plain
+   * JSON Schema for structural validation; the refinement runs only via
+   * `validateAsync()` / `parseAsync()`. Compose by wrapping again. The returned
+   * schema infers the same type, so `Infer<typeof refined>` is unchanged.
+   */
+  refine<S extends JSONSchema>(schema: S, check: RefineCheck<Infer<S>>, opts?: RefineOptions): S;
 }
 
 export declare const t: TBuilder;