ata-validator 0.13.4 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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.14.0 - 2026-05-16
+
+### Added
+
+- Generic `Validator<T>` with type predicate `isValidObject(data): data is T`. Pairs naturally with TypeBox, Zod-from-JSON-Schema, Valibot, or hand-written types over JSON Schema literals.
+- `ValidationResult<T>` and `ValidateAndParseResult<T>` are discriminated unions. On the `valid: true` branch the parsed data is typed; on `valid: false` the `errors` array carries the diagnostic information.
+
+### Changed
+
+- Type-level only: accessing `result.data` (or `result.value` on `validateAndParse`) without first checking `result.valid` is now a TypeScript compile error. Runtime behavior is unchanged. The previous shape returned `undefined` in that position, so this surfaces an existing latent bug at compile time.
+
+### Notes
+
+- Pure `.d.ts` change. No JS, C++, AOT, or CLI behavior is affected. Bundle size unchanged. Runtime performance unchanged.
+
 ## 0.13.4 — 2026-05-14
 
 ### Fixed

package/README.md

@@ -90,6 +90,39 @@ v.isValidParallel(ndjson);  // bool[]
 v.countValid(ndjson);        // number
 ```
 
+### Type-safe schemas
+
+`Validator` is generic. Pair it with any schema authoring tool, or a hand-written type, to get TypeScript narrowing in your handler code.
+
+```ts
+import { Type, type Static } from '@sinclair/typebox'
+import { Validator } from 'ata-validator'
+
+const UserSchema = Type.Object({
+  id: Type.Integer({ minimum: 1 }),
+  name: Type.String({ minLength: 1 }),
+  email: Type.String({ format: 'email' }),
+})
+
+type User = Static<typeof UserSchema>
+
+const v = new Validator<User>(UserSchema)
+
+if (v.isValidObject(data)) {
+  // data is narrowed to User, no cast needed
+  console.log(data.name)
+}
+
+const result = v.validate(data)
+if (result.valid) {
+  // result.data is User
+} else {
+  // result.errors: ValidationError[]
+}
+```
+
+The same pattern works with Zod-from-JSON-Schema, Valibot, or a hand-written `type User = {...}` alongside a JSON Schema literal. `Validator<T>` makes no library-specific assumption.
+
 ### Cross-Schema `$ref`
 
 ```javascript

package/index.d.ts

@@ -15,16 +15,13 @@ export interface ValidationError {
 /** A user-supplied format checker. Receives the candidate value, returns true if valid. */
 export type FormatChecker = (value: string) => boolean;
 
-export interface ValidationResult {
-  valid: boolean;
-  errors: ValidationError[];
-}
+export type ValidationResult<T = unknown> =
+  | { valid: true;  data: T;       errors: ValidationError[] }
+  | { valid: false; data?: never;  errors: ValidationError[] };
 
-export interface ValidateAndParseResult {
-  valid: boolean;
-  value: unknown;
-  errors: ValidationError[];
-}
+export type ValidateAndParseResult<T = unknown> =
+  | { valid: true;  value: T;       errors: ValidationError[] }
+  | { valid: false; value: unknown; errors: ValidationError[] };
 
 export interface ValidatorOptions {
   coerceTypes?: boolean;
@@ -74,26 +71,26 @@ export interface StandaloneModule {
   errFn: ((data: unknown, allErrors?: boolean) => ValidationResult) | null;
 }
 
-export class Validator {
+export class Validator<T = unknown> {
   constructor(schema: object | string, options?: ValidatorOptions);
 
   /** Add a schema to the registry for cross-schema $ref resolution */
   addSchema(schema: object): void;
 
   /** Validate data, returns result with errors. Applies defaults, coerceTypes, removeAdditional. */
-  validate(data: unknown): ValidationResult;
+  validate(data: unknown): ValidationResult<T>;
 
   /** Fast boolean check via JS codegen or tier 0 interpreter. No error collection. */
-  isValidObject(data: unknown): boolean;
+  isValidObject(data: unknown): data is T;
 
   /** Validate a JSON string. Uses simdjson fast path for large documents. */
-  validateJSON(jsonString: string): ValidationResult;
+  validateJSON(jsonString: string): ValidationResult<T>;
 
   /** Fast boolean check for a JSON string */
   isValidJSON(jsonString: string): boolean;
 
   /** Parse JSON with simdjson + validate against schema. Returns parsed value and validation result. Requires native addon. */
-  validateAndParse(jsonString: string | Buffer): ValidateAndParseResult;
+  validateAndParse(jsonString: string | Buffer): ValidateAndParseResult<T>;
 
   /** Ultra-fast buffer validation via native addon */
   isValid(input: Buffer | Uint8Array | string): boolean;
@@ -128,7 +125,7 @@ export class Validator {
   toStandaloneModule(options?: { format?: 'esm' | 'cjs'; abortEarly?: boolean }): string | null;
 
   /** Load a pre-compiled standalone module. Zero schema compilation at startup. */
-  static fromStandalone(mod: StandaloneModule, schema: object | string, options?: ValidatorOptions): Validator;
+  static fromStandalone<T = unknown>(mod: StandaloneModule, schema: object | string, options?: ValidatorOptions): Validator<T>;
 
   /** Bundle multiple schemas into a single JS module string. Load with Validator.loadBundle(). */
   static bundle(schemas: object[], options?: ValidatorOptions): string;
@@ -155,16 +152,16 @@ export class Validator {
 }
 
 /** One-shot validate: creates a Validator, validates data, returns result. */
-export function validate(
+export function validate<T = unknown>(
   schema: object | string,
   data: unknown
-): ValidationResult;
+): ValidationResult<T>;
 
 /** Fast compile: returns a validate function directly. WeakMap cached, second call with same schema is near-zero cost. */
-export function compile(
+export function compile<T = unknown>(
   schema: object | string,
   options?: ValidatorOptions
-): (data: unknown) => ValidationResult;
+): (data: unknown) => ValidationResult<T>;
 
 /** Parse JSON using simdjson (native addon) or JSON.parse (fallback). */
 export function parseJSON(jsonString: string | Buffer): unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "0.13.4",
+  "version": "0.14.0",
   "description": "Ultra-fast JSON Schema validator. 5x faster validation, 159,000x faster compilation. Works without native addon. Cross-schema $ref, Draft 2020-12 + Draft 7, V8-optimized JS codegen, simdjson, RE2, multi-core. Standard Schema V1 compatible.",
   "main": "index.js",
   "module": "index.mjs",
@@ -41,7 +41,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_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",
+    "test": "node test.js && node tests/test_no_native.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_typed_validator_runner.js",
     "test:suite": "node tests/run_suite.js",
     "test:compat": "node tests/test_compat.js",
     "test:standard-schema": "node tests/test_standard_schema.js",
@@ -49,6 +49,7 @@
     "test:ts": "node tests/test_ts_gen.js",
     "test:ts-corpus": "node tests/test_ts_corpus.js",
     "test:ts-differential": "node tests/test_ts_differential.js",
+    "test:typed": "node tests/test_typed_validator_runner.js",
     "bench": "node benchmark/bench_large.js",
     "fuzz": "node tests/fuzz_differential.js",
     "fuzz:long": "FUZZ_ITERATIONS=100000 node tests/fuzz_differential.js",
@@ -119,10 +120,13 @@
     "yaml": "^2.0.0"
   },
   "peerDependenciesMeta": {
-    "yaml": { "optional": true }
+    "yaml": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@sinclair/typebox": "^0.34.49",
+    "@types/node": "^25.8.0",
     "cmake-js": "^8.0.0",
     "mitata": "^1.0.34",
     "typebox": "^1.1.7",