ata-validator 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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.17.0 - 2026-05-23
+
+### Added
+
+- Static type inference from JSON Schema literals. The new exported `Infer<S>` type maps a schema literal to its data type, and `new Validator(defineSchema({...}))` now returns `Validator<Infer<S>>`, so `validate()` narrows `result.data` with no manual type annotation. Write plain JSON Schema, get the type for free, no builder DSL. Covers primitives, type-array unions, `const`, `enum`, objects (required vs optional keys), and arrays; `$ref`, tuples, and `anyOf`/`oneOf` infer `unknown` for now. Pure `.d.ts` change, no runtime impact.
+
+### Fixed
+
+- `validateAndParse()` is now implemented in JavaScript (`JSON.parse` then validate) and returns `{ valid, value, errors }`. It previously called a native method that does not exist and threw on every call. It now works with or without the native addon and in the browser; malformed JSON returns `valid: false` with an `ATA9001` error instead of throwing.
+
 ## 0.16.0 - 2026-05-23
 
 ### Added

package/index.d.ts

@@ -164,6 +164,74 @@ export interface JSONSchema {
   [keyword: string]: unknown;
 }
 
+/**
+ * Collapse an intersection of mapped object types into a single readable object
+ * type. `& {}` forces TypeScript to evaluate the mapped type eagerly.
+ */
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+
+/** Keys listed in a schema's `required` array, as a string union (or never). */
+type RequiredKeys<S> = S extends { required: infer R }
+  ? R extends ReadonlyArray<infer K extends string>
+    ? K
+    : never
+  : never;
+
+/** Object shape: required keys are required, all other declared keys optional. */
+type InferObject<S> = S extends { properties: infer P }
+  ? Simplify<
+      { [K in keyof P as K extends RequiredKeys<S> ? K : never]: Infer<P[K]> } &
+      { [K in keyof P as K extends RequiredKeys<S> ? never : K]?: Infer<P[K]> }
+    >
+  : Record<string, unknown>;
+
+/** Array shape: `items` as a single schema maps to an element type; tuple/absent -> unknown[]. */
+type InferArray<S> = S extends { items: infer I }
+  ? I extends ReadonlyArray<unknown>
+    ? unknown[]
+    : Infer<I>[]
+  : unknown[];
+
+/** Map a single JSON Schema type name (+ its schema) to a TS type. */
+type InferByTypeName<N, S> = N extends 'object'
+  ? InferObject<S>
+  : N extends 'array'
+    ? InferArray<S>
+    : N extends 'string'
+      ? string
+      : N extends 'number'
+        ? number
+        : N extends 'integer'
+          ? number
+          : N extends 'boolean'
+            ? boolean
+            : N extends 'null'
+              ? null
+              : unknown;
+
+/**
+ * Infer the TypeScript data type a JSON Schema literal describes (Core scope).
+ *
+ * Handles: primitives, `type` arrays (union), `const`, `enum`, objects
+ * (`properties` + `required` -> required/optional keys), and arrays
+ * (`items` as a single schema). `$ref`/`$defs`, tuples, and `anyOf`/`oneOf`/
+ * `allOf` are not yet inferred and resolve to `unknown` rather than erroring.
+ *
+ * Pair with {@link defineSchema}:
+ * `const s = defineSchema({...}); type T = Infer<typeof s>;`
+ */
+export type Infer<S> = S extends { const: infer C }
+  ? C
+  : S extends { enum: infer E }
+    ? E extends ReadonlyArray<infer U>
+      ? U
+      : unknown
+    : S extends { type: infer T }
+      ? T extends ReadonlyArray<infer N>
+        ? InferByTypeName<N, S>
+        : InferByTypeName<T, S>
+      : unknown;
+
 export type ValidationResult<T = unknown> =
   | { valid: true;  data: T;       errors: ValidationError[] }
   | { valid: false; data?: never;  errors: ValidationError[] };
@@ -231,9 +299,8 @@ export interface StandaloneModule {
   errFn: ((data: unknown, allErrors?: boolean) => ValidationResult) | null;
 }
 
-export class Validator<T = unknown> {
-  constructor(schema: object | string, options?: ValidatorOptions);
-
+/** Instance surface of a compiled validator. */
+export interface Validator<T = unknown> {
   /** Add a schema to the registry for cross-schema $ref resolution */
   addSchema(schema: object): void;
 
@@ -249,7 +316,7 @@ export class Validator<T = unknown> {
   /** 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. */
+  /** Parse JSON and validate against the schema. Returns the parsed value and the validation result. Works without the native addon. */
   validateAndParse(jsonString: string | Buffer): ValidateAndParseResult<T>;
 
   /** Ultra-fast buffer validation via native addon */
@@ -276,41 +343,48 @@ export class Validator<T = unknown> {
   /**
    * Generate a self-contained module string with `validate`/`isValid` exports.
    * The output has zero runtime dependency on ata-validator.
-   *
-   * - format: 'esm' (default) or 'cjs'.
-   * - abortEarly: if true, invalid results are a shared frozen stub (smaller output, no error details).
-   *
-   * Returns null if the schema cannot be compiled to a standalone module.
    */
   toStandaloneModule(options?: { format?: 'esm' | 'cjs'; abortEarly?: boolean }): string | null;
 
+  /** Standard Schema V1 interface, compatible with Fastify, tRPC, TanStack, etc. */
+  readonly "~standard": StandardSchemaV1Props;
+}
+
+/** Constructor + statics for {@link Validator}. */
+export interface ValidatorConstructor {
+  /** Construct from a JSON Schema literal; the validated data type is inferred. */
+  new <const S extends JSONSchema>(schema: S, options?: ValidatorOptions): Validator<Infer<S>>;
+  /** Construct from a plain object/string schema, or with an explicit data type. */
+  new <T = unknown>(schema: object | string, options?: ValidatorOptions): Validator<T>;
+
   /** Load a pre-compiled standalone module. Zero schema compilation at startup. */
-  static fromStandalone<T = unknown>(mod: StandaloneModule, schema: object | string, options?: ValidatorOptions): Validator<T>;
+  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;
+  bundle(schemas: object[], options?: ValidatorOptions): string;
 
   /**
    * Bundle multiple schemas into a self-contained JS module with no
    * ata-validator runtime dependency. Cross-schema `$ref` resolves between
    * the supplied schemas. Set `format: 'esm'` for ESM output (default 'cjs').
    */
-  static bundleStandalone(schemas: object[], options?: BundleStandaloneOptions): string;
+  bundleStandalone(schemas: object[], options?: BundleStandaloneOptions): string;
 
   /**
    * Bundle multiple schemas with deduplicated shared templates. Smaller output
-   * than bundle(). Accepts the same options as bundleStandalone, including
-   * `format: 'esm' | 'cjs'` and cross-schema `$ref` resolution.
+   * than bundle(). Accepts the same options as bundleStandalone.
    */
-  static bundleCompact(schemas: object[], options?: BundleStandaloneOptions): string;
+  bundleCompact(schemas: object[], options?: BundleStandaloneOptions): string;
 
   /** Load a bundle created by Validator.bundle(). Returns array of Validator instances. */
-  static loadBundle(mods: object[], schemas: object[], options?: ValidatorOptions): Validator[];
+  loadBundle(mods: object[], schemas: object[], options?: ValidatorOptions): Validator[];
 
-  /** Standard Schema V1 interface, compatible with Fastify, tRPC, TanStack, etc. */
-  readonly "~standard": StandardSchemaV1Props;
+  readonly prototype: Validator;
 }
 
+/** Compile a schema into a reusable validator. */
+export const Validator: ValidatorConstructor;
+
 /** One-shot validate: creates a Validator, validates data, returns result. */
 export function validate<T = unknown>(
   schema: object | string,

package/index.js

@@ -868,16 +868,20 @@ class Validator {
               return false;
             }
           };
-      // validateAndParse: requires native addon for simdjson parsing
-      if (native) {
+      // validateAndParse: parse the JSON, then validate. Pure JS (JSON.parse +
+      // validate) so it works with or without the native addon and in browsers.
+      {
         const self = this;
         this.validateAndParse = (jsonStr) => {
-          self._ensureNative();
-          self.validateAndParse = (s) => self._compiled.validateAndParse(s);
-          return self.validateAndParse(jsonStr);
+          let value;
+          try {
+            value = JSON.parse(typeof jsonStr === 'string' ? jsonStr : new TextDecoder().decode(jsonStr));
+          } catch (e) {
+            return { valid: false, value: undefined, errors: [{ code: 'ATA9001', message: 'invalid JSON: ' + e.message, keyword: '__parse__', instancePath: '', schemaPath: '', params: {} }] };
+          }
+          const r = self.validate(value);
+          return { valid: r.valid, value, errors: r.errors };
         };
-      } else {
-        this.validateAndParse = () => { throw new Error('Native addon required for validateAndParse()'); };
       }
       // Buffer APIs: lazy native init — only compile native schema on first buffer call.
       // This keeps cold start fast (JS codegen only) for users who only use validate().

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "0.16.0",
+  "version": "0.17.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",
@@ -42,7 +42,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 && 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_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 benchmark/bench_aot_size.mjs",
+    "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 && 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_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 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",