ata-validator 0.21.0 → 1.0.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 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.
 
+## 1.0.0 - 2026-07-15
+
+1.0 is a stability commitment, not a feature release. The API surface, the error result shape, and the error code registry are now covered by the semver guarantees in [docs/STABILITY.md](docs/STABILITY.md).
+
+### Removed
+
+- `Validator.prototype.toStandalone()` and `Validator.prototype.toStandaloneModule()`, deprecated in 0.22.0. Use `toStandaloneModule()`/`bundleStandalone()`/`bundleCompact()` from `ata-validator/build`. See [docs/migration-to-1.0.md](docs/migration-to-1.0.md).
+
+### Changed
+
+- Node.js 20 or newer is required. Node 18 reached end of life in April 2025.
+
+### Added
+
+- [docs/STABILITY.md](docs/STABILITY.md): semver, deprecation, and error-code guarantees.
+- README "Known limitations" section documenting the deliberate 1.x scope edges.
+
+## 0.22.0 - 2026-07-14
+
+### Deprecated
+
+- `Validator.prototype.toStandalone()` and `Validator.prototype.toStandaloneModule()` now emit a one-time DeprecationWarning. Both will be removed in 1.0. The replacements have been stable since 0.19: `toStandaloneModule()`/`bundleStandalone()`/`bundleCompact()` from `ata-validator/build`, and the `Validator.bundle*()` statics.
+
+## 0.21.0 - 2026-06-01
+
+### Added
+
+- `errorMessage` keyword for custom error messages. A string on a subschema replaces the message for any failing keyword there; an object overrides per keyword, with `required` keyed by missing property name and `_` as fallback. `code`, `keyword`, and `path` fields are untouched. Schemas without `errorMessage` pay nothing; the override pass is only installed when one is present.
+- Async refinement: `t.refine(schema, fn, { message, path })` attaches an async (or sync) check that runs through `validateAsync`/`parseAsync` after structural validation passes. `new Validator(schema)` ignores the refinement marker, so plain structural validation is unchanged. Failing refinements surface as errors with `keyword: 'refine'`.
+
 ## 0.20.1 - 2026-05-27
 
 ### Fixed

package/README.md

@@ -5,6 +5,8 @@ JSON Schema validation with first-class TypeScript and zero runtime cost. AOT co
 [![npm](https://img.shields.io/npm/v/ata-validator)](https://www.npmjs.com/package/ata-validator)
 [![License](https://img.shields.io/npm/l/ata-validator)](LICENSE)
 
+1.0 is a stability commitment: see [docs/STABILITY.md](docs/STABILITY.md) for the semver, deprecation, and error-code guarantees.
+
 ## Quick start
 
 ```bash
@@ -359,10 +361,9 @@ Programmatic API if you prefer to script it:
 
 ```javascript
 const fs = require('fs');
-const { Validator } = require('ata-validator');
+const { toStandaloneModule } = require('ata-validator/build');
 
-const v = new Validator(schema);
-fs.writeFileSync('./user.validator.mjs', v.toStandaloneModule({ format: 'esm' }));
+fs.writeFileSync('./user.validator.mjs', toStandaloneModule(schema, { format: 'esm' }));
 ```
 
 **Fastify startup (10 routes cold): ajv 12.6ms → ata 0.5ms (24x faster boot, no build step required)**
@@ -446,6 +447,19 @@ Copy-paste recipes for the common frameworks. Most need 10-20 lines of glue. See
 
 `email`, `date`, `date-time`, `time`, `uri`, `uri-reference`, `ipv4`, `ipv6`, `uuid`, `hostname`
 
+### Known limitations
+
+The 98.5% Draft 2020-12 pass rate excludes areas that are deliberate scope decisions for 1.x:
+
+- **Remote `$ref` over the network** is not fetched. Register cross-schema refs explicitly with `schemas: [...]` or `addSchema()`.
+- **`$vocabulary`** is not implemented; custom vocabularies are ignored rather than enforced.
+- **`contentEncoding` / `contentMediaType` / `contentSchema`** are annotation-only, as the spec permits, and are not validated.
+- **`minLength`/`maxLength`** count UTF-16 code units, not grapheme clusters.
+- **Infinite-loop detection** suite cases are skipped; circular `$ref` chains are cut off by a recursion depth guard instead.
+- **`default`** optional suite tests are excluded; ata applies `default` values to validated data, where the spec treats `default` as a non-enforcing annotation.
+
+If one of these blocks you, open an issue; scope decisions get revisited with real use cases.
+
 ## Building from Source
 
 ### Development prerequisites

package/bin/ata.js

@@ -181,6 +181,7 @@ function cmdCompile(args) {
   }
 
   const { Validator } = require('..');
+  const aot = require('../lib/aot');
   let v;
   try {
     v = new Validator(schema);
@@ -199,7 +200,7 @@ function cmdCompile(args) {
     }
   }
   const schemaFile = path.relative(process.cwd(), input) || input;
-  const src = v.toStandaloneModule({ format, abortEarly, source, sourceMap, schemaFile });
+  const src = aot.toStandaloneModule(v, { format, abortEarly, source, sourceMap, schemaFile });
   if (!src) {
     reportCompileError(input, 'schema is too complex for standalone compilation');
     process.exit(1);

package/build.d.ts

@@ -69,13 +69,13 @@ export interface WatchHandle {
 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.
+// Programmatic counterparts to `Validator.bundleStandalone` / `bundleCompact`.
+// 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>;
+  formats?: Record<string, (value: string) => boolean>;
   verbose?: boolean;
 }
 

package/index.d.ts

@@ -411,15 +411,6 @@ export interface Validator<T = unknown> {
   /** Single-thread NDJSON batch validation. Requires native addon. */
   isValidNDJSON(ndjsonBuffer: Buffer): boolean[];
 
-  /** Generate a standalone JS module string for zero-compile loading. Returns null if schema can't be standalone-compiled. */
-  toStandalone(): string | null;
-
-  /**
-   * Generate a self-contained module string with `validate`/`isValid` exports.
-   * The output has zero runtime dependency on ata-validator.
-   */
-  toStandaloneModule(options?: { format?: 'esm' | 'cjs'; abortEarly?: boolean }): string | null;
-
   /** Standard Schema V1 interface, compatible with Fastify, tRPC, TanStack, etc. */
   readonly "~standard": StandardSchemaV1Props;
 }

package/index.js

@@ -290,9 +290,9 @@ const ABORT_EARLY_RESULT = Object.freeze({
 
 // `_CP_LEN_SOURCE`, the safe-regex embed, and the AOT helpers that consume them
 // now live in `lib/aot.js` — keeping this file free of `fs`/`path`/`__dirname`
-// references so a default import never touches disk. The instance and static
-// AOT methods further down lazily require `./lib/aot`, so they pay nothing
-// until a user calls `toStandaloneModule`/`bundleStandalone`/etc.
+// references so a default import never touches disk. The static AOT methods
+// further down lazily require `./lib/aot`, so they pay nothing until a user
+// calls `bundleStandalone`/`bundle`/etc.
 
 // Above this size, simdjson On Demand (selective field access) beats JSON.parse
 // (which must materialize the full JS object tree). Buffer.from + NAPI ~2x faster.
@@ -1165,20 +1165,6 @@ class Validator {
     }
   }
 
-  // --- AOT pre-compilation ---
-  // The bodies of `toStandalone` and `toStandaloneModule` live in `lib/aot.js`
-  // so this entry stays free of `fs`/`path`/`__dirname`. The lazy require runs
-  // only on first call, never during a plain `import 'ata-validator'`. Browser
-  // bundlers swap `lib/aot.js` with `lib/aot.browser.js`, which throws a
-  // pointed error instead of attempting to read source from disk.
-  toStandalone() {
-    return require('./lib/aot').toStandalone(this);
-  }
-
-  toStandaloneModule(opts) {
-    return require('./lib/aot').toStandaloneModule(this, opts);
-  }
-
   // Load a pre-compiled standalone module. Zero schema compilation.
   // No NAPI, no native compile — pure JS. Startup in microseconds.
   // Usage: const v = Validator.fromStandalone(require('./compiled.js'), schema, opts)
@@ -1504,5 +1490,5 @@ module.exports = {
   renderPretty,
   renderCompact,
   renderJSON,
-  attachSuggestions,
+  attachSuggestions, // internal: used by the renderers; not public API
 };

package/lib/aot-build.js

@@ -138,7 +138,7 @@ async function build(opts) {
         }
       }
       const schemaFile = path.relative(process.cwd(), input) || input;
-      const src = v.toStandaloneModule({
+      const src = aot.toStandaloneModule(v, {
         format,
         abortEarly: !!opts.abortEarly,
         source,
@@ -233,9 +233,9 @@ async function watch(opts, onReport) {
 
 // AOT primitives also surface here so consumers can do
 //   import { bundleStandalone, toStandaloneModule, bundleCompact } from 'ata-validator/build'
-// without poking at the Validator class. The Validator-bound forms (Validator.bundleStandalone,
-// validator.toStandaloneModule) remain available from the default entry; this is the
-// programmatic alias for code that wants the build surface in one place.
+// without poking at the Validator class. The class-bound statics (Validator.bundleStandalone,
+// Validator.bundle, Validator.bundleCompact) remain available from the default entry; this
+// build entry is the programmatic alias for code that wants the build surface in one place.
 const aot = require('./aot');
 
 function bundleStandalone(schemas, opts) {

package/lib/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "0.21.0",
+  "version": "1.0.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_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",
+    "test": "node test.js && node tests/test_removed_aot_methods.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",
@@ -86,14 +86,14 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mertcanaltin/ata-validator.git"
+    "url": "git+https://github.com/ata-core/ata-validator.git"
   },
   "bugs": {
-    "url": "https://github.com/mertcanaltin/ata-validator/issues"
+    "url": "https://github.com/ata-core/ata-validator/issues"
   },
   "homepage": "https://ata-validator.com",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "files": [
     "index.js",

package/scripts/regen-safe-regex-source.js

@@ -13,7 +13,7 @@ const fs = require('fs');
 const path = require('path');
 
 const root = path.resolve(__dirname, '..');
-const src = fs.readFileSync(path.join(root, 'lib', 'safe-regex.js'), 'utf8');
+const src = fs.readFileSync(path.join(root, 'lib', 'safe-regex.js'), 'utf8').replace(/\r\n/g, '\n');
 
 const out =
   "'use strict';\n\n" +