ata-validator 0.18.2 → 0.21.0

package/lib/t.js

@@ -0,0 +1,149 @@
+'use strict';
+
+// Chainable schema builder. Each `t.X(...)` returns a plain JSON Schema
+// object, so the output drops straight into `new Validator(...)`,
+// `defineSchema`, `Infer<S>`, and the AOT pipeline with no adapter. The
+// builder is pure: no runtime state, no class instances, no closures held
+// across calls.
+//
+// Optionality is carried by a Symbol-keyed marker that JSON Schema
+// consumers (including ata's own codegen) never see, because they iterate
+// `Object.keys`, which excludes Symbol keys. `t.object` reads the marker
+// 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);
+}
+
+function number(opts) {
+  return Object.assign({ type: 'number' }, opts);
+}
+
+function integer(opts) {
+  return Object.assign({ type: 'integer' }, opts);
+}
+
+function boolean() {
+  return { type: 'boolean' };
+}
+
+function nul() {
+  return { type: 'null' };
+}
+
+function literal(value) {
+  return { const: value };
+}
+
+function constant(value) {
+  return { const: value };
+}
+
+function enumOf(values) {
+  return { enum: values };
+}
+
+function array(items, opts) {
+  return Object.assign({ type: 'array', items }, opts);
+}
+
+function tuple(items, opts) {
+  // JSON Schema 2020-12 uses `prefixItems` for tuples. `items: false`
+  // closes the tail, and a default `minItems` matching the tuple length
+  // enforces "exactly N elements" so the runtime check matches the
+  // TypeScript tuple type that `Infer<S>` produces. A caller can override
+  // either bound through `opts`.
+  return Object.assign(
+    { type: 'array', prefixItems: items, items: false, minItems: items.length },
+    opts,
+  );
+}
+
+function record(values, opts) {
+  return Object.assign({ type: 'object', additionalProperties: values }, opts);
+}
+
+function object(properties, opts) {
+  const props = {};
+  const required = [];
+  const keys = Object.keys(properties);
+  for (const key of keys) {
+    const schema = properties[key];
+    if (schema && schema[OPTIONAL] === true) {
+      const { [OPTIONAL]: _drop, ...rest } = schema;
+      props[key] = rest;
+    } else {
+      props[key] = schema;
+      required.push(key);
+    }
+  }
+  const out = { type: 'object', properties: props };
+  if (required.length) out.required = required;
+  return Object.assign(out, opts);
+}
+
+function optional(schema) {
+  // Brand the schema so the parent `t.object` can detect it. The Symbol
+  // key is invisible to Object.keys / JSON.stringify and to ata's codegen,
+  // so a standalone `t.optional(t.string())` still validates as a string
+  // if passed directly to `new Validator(...)`.
+  return Object.assign({}, schema, { [OPTIONAL]: true });
+}
+
+function union(schemas) {
+  return { anyOf: schemas };
+}
+
+function intersect(schemas) {
+  return { allOf: schemas };
+}
+
+function ref(pointer) {
+  return { $ref: pointer };
+}
+
+function any() {
+  return {};
+}
+
+function unknown() {
+  return {};
+}
+
+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,
+  integer,
+  boolean,
+  null: nul,
+  literal,
+  const: constant,
+  enum: enumOf,
+  array,
+  tuple,
+  record,
+  object,
+  optional,
+  union,
+  intersect,
+  ref,
+  any,
+  unknown,
+  never,
+  refine,
+  OPTIONAL,
+};

package/lib/version.js

@@ -0,0 +1,10 @@
+'use strict';
+
+// The package version, exported as a plain string so neither the default nor
+// the browser entry has to `require('./package.json')`. Bundling package.json
+// would drag dependency strings (e.g. `pkg-prebuilds`) into browser builds
+// even though the runtime never touches them.
+//
+// Kept in lockstep with package.json by `tests/test_version_sync.js`.
+
+module.exports = '0.21.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ata-validator",
-  "version": "0.18.2",
+  "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",
@@ -25,6 +25,11 @@
       "import": "./build.mjs",
       "require": "./build.js"
     },
+    "./t": {
+      "types": "./t.d.ts",
+      "import": "./t.mjs",
+      "require": "./t.js"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -32,17 +37,18 @@
     "ata": "bin/ata.js"
   },
   "browser": {
-    "pkg-prebuilds": false
+    "pkg-prebuilds": false,
+    "./lib/native-load.js": "./lib/native-load.browser.js"
   },
   "scripts": {
     "install": "node scripts/install.js",
-    "prepublishOnly": "node scripts/check-prebuilds.js && ATA_ALLOW_DOC_PLACEHOLDERS=1 node scripts/check-doc-coverage.js && node tests/test_error_codes_lock.js",
-    "release:check": "node scripts/check-prebuilds.js && node scripts/check-doc-coverage.js && node tests/test_error_codes_lock.js",
+    "prepublishOnly": "node scripts/regen-safe-regex-source.js && node scripts/check-prebuilds.js && ATA_ALLOW_DOC_PLACEHOLDERS=1 node scripts/check-doc-coverage.js && node tests/test_error_codes_lock.js && node tests/test_safe_regex_source_sync.js && node tests/test_version_sync.js",
+    "release:check": "node scripts/regen-safe-regex-source.js && node scripts/check-prebuilds.js && node scripts/check-doc-coverage.js && node tests/test_error_codes_lock.js && node tests/test_safe_regex_source_sync.js && node tests/test_version_sync.js",
     "build": "cmake-js build --target ata",
     "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_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",
@@ -101,6 +107,9 @@
     "build.js",
     "build.mjs",
     "build.d.ts",
+    "t.js",
+    "t.mjs",
+    "t.d.ts",
     "binding-options.js",
     "binding/",
     "include/",

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

@@ -0,0 +1,33 @@
+'use strict';
+
+// Bake `lib/safe-regex.js` into `lib/safe-regex-source.js` as a plain string
+// export so the AOT path (`lib/aot.js`) can embed the engine into generated
+// modules without reading from disk at runtime. The runtime read used to be
+// the reason browser bundles broke on first AOT call (and the reason the
+// default entry had to carry `__dirname`/`fs`/`path`).
+//
+// Run from `prepublishOnly` and from a sync test so the bundled string never
+// drifts from the engine source.
+
+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 out =
+  "'use strict';\n\n" +
+  "// Auto-generated by scripts/regen-safe-regex-source.js — do not edit.\n" +
+  "// Mirrors `lib/safe-regex.js` verbatim so `lib/aot.js` can embed the engine\n" +
+  "// into standalone output without a runtime `fs` read. Kept in sync by\n" +
+  "// `tests/test_safe_regex_source_sync.js`.\n\n" +
+  'module.exports = ' + JSON.stringify(src) + ';\n';
+
+const outPath = path.join(root, 'lib', 'safe-regex-source.js');
+const prev = fs.existsSync(outPath) ? fs.readFileSync(outPath, 'utf8') : '';
+if (prev === out) {
+  console.log('lib/safe-regex-source.js: up to date');
+} else {
+  fs.writeFileSync(outPath, out);
+  console.log('lib/safe-regex-source.js: regenerated');
+}

package/t.d.ts

@@ -0,0 +1,205 @@
+// Chainable builder for ata. Each function returns a plain JSON Schema
+// literal, so `Infer<typeof X>` from the main entry resolves the inferred
+// TypeScript type with no additional plumbing.
+//
+//   import { t } from 'ata-validator/t'
+//   import { Validator, Infer } from 'ata-validator'
+//
+//   const User = t.object({
+//     name: t.string({ minLength: 1 }),
+//     age: t.integer({ minimum: 0 }),
+//     email: t.optional(t.string({ format: 'email' })),
+//   })
+//   type User = Infer<typeof User>
+//   // { name: string; age: number; email?: string }
+//
+//   const v = new Validator(User)  // schema is plain JSON Schema
+
+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;
+
+export interface StringOptions {
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: string;
+  description?: string;
+  title?: string;
+  default?: string;
+  examples?: readonly string[];
+}
+
+export interface NumericOptions {
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+  multipleOf?: number;
+  description?: string;
+  title?: string;
+  default?: number;
+  examples?: readonly number[];
+}
+
+export interface ArrayOptions {
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+  description?: string;
+  title?: string;
+}
+
+export interface ObjectOptions {
+  additionalProperties?: boolean | JSONSchema;
+  description?: string;
+  title?: string;
+}
+
+export interface RecordOptions {
+  minProperties?: number;
+  maxProperties?: number;
+  description?: string;
+  title?: string;
+}
+
+// `Omit` against an `OPTIONAL`-branded schema collapses literal property types
+// through the JSONSchema index signature, which breaks downstream `Infer`. The
+// branded property is a Symbol key, so it doesn't intersect with any string
+// index lookup; we leave it in place and just compute `RequiredKeys` from it.
+// Infer reads `type`, `properties`, etc. and ignores extra phantom keys.
+
+type RequiredKeysOf<T> = {
+  [K in keyof T]: T[K] extends { readonly [OPTIONAL]: true } ? never : K;
+}[keyof T];
+
+type StrippedProperties<T> = { [K in keyof T]: T[K] };
+
+export interface TString extends JSONSchema {
+  type: 'string';
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: string;
+  description?: string;
+  title?: string;
+  default?: string;
+}
+
+export interface TNumber extends JSONSchema {
+  type: 'number';
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+  multipleOf?: number;
+  description?: string;
+  title?: string;
+  default?: number;
+}
+
+export interface TInteger extends JSONSchema {
+  type: 'integer';
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+  multipleOf?: number;
+  description?: string;
+  title?: string;
+  default?: number;
+}
+
+export interface TBoolean extends JSONSchema { type: 'boolean' }
+export interface TNull extends JSONSchema { type: 'null' }
+
+export interface TLiteral<V extends string | number | boolean | null> extends JSONSchema { const: V }
+export interface TEnum<V extends readonly (string | number | boolean | null)[]> extends JSONSchema { enum: V }
+
+export interface TArray<S extends JSONSchema> extends JSONSchema {
+  type: 'array';
+  items: S;
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+}
+
+export interface TTuple<S extends ReadonlyArray<JSONSchema>> extends JSONSchema {
+  type: 'array';
+  prefixItems: S;
+  items: false;
+  minItems?: number;
+  maxItems?: number;
+}
+
+export interface TRecord<S extends JSONSchema> extends JSONSchema {
+  type: 'object';
+  additionalProperties: S;
+  minProperties?: number;
+  maxProperties?: number;
+}
+
+export interface TObject<T extends Record<string, JSONSchema>> extends JSONSchema {
+  type: 'object';
+  properties: StrippedProperties<T>;
+  required: ReadonlyArray<Extract<RequiredKeysOf<T>, string>>;
+  additionalProperties?: boolean | JSONSchema;
+}
+
+export interface TUnion<S extends ReadonlyArray<JSONSchema>> extends JSONSchema { anyOf: S }
+export interface TIntersect<S extends ReadonlyArray<JSONSchema>> extends JSONSchema { allOf: S }
+export interface TRef extends JSONSchema { $ref: string }
+export interface TAny extends JSONSchema {}
+export interface TNever extends JSONSchema { not: {} }
+
+export interface TBuilder {
+  string(opts?: StringOptions): TString;
+  number(opts?: NumericOptions): TNumber;
+  integer(opts?: NumericOptions): TInteger;
+  boolean(): TBoolean;
+  null(): TNull;
+
+  literal<const V extends string | number | boolean | null>(value: V): TLiteral<V>;
+  const<const V extends string | number | boolean | null>(value: V): TLiteral<V>;
+  enum<const V extends readonly (string | number | boolean | null)[]>(values: V): TEnum<V>;
+
+  array<S extends JSONSchema>(items: S, opts?: ArrayOptions): TArray<S>;
+  tuple<const S extends ReadonlyArray<JSONSchema>>(items: S, opts?: ArrayOptions): TTuple<S>;
+  record<S extends JSONSchema>(values: S, opts?: RecordOptions): TRecord<S>;
+
+  object<const T extends Record<string, JSONSchema>>(properties: T, opts?: ObjectOptions): TObject<T>;
+  optional<S extends JSONSchema>(schema: S): TOptional<S>;
+
+  union<const S extends ReadonlyArray<JSONSchema>>(schemas: S): TUnion<S>;
+  intersect<const S extends ReadonlyArray<JSONSchema>>(schemas: S): TIntersect<S>;
+  ref(pointer: string): TRef;
+
+  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;

package/t.js

@@ -0,0 +1,9 @@
+'use strict';
+
+// CJS entry for `ata-validator/t`. The implementation lives in `lib/t.js`
+// so the default entry can lazy-require it for users who never touch the
+// builder. Re-export shape matches the `TBuilder` interface in `t.d.ts`.
+
+const t = require('./lib/t');
+
+module.exports = { t, OPTIONAL: t.OPTIONAL };

package/t.mjs

@@ -0,0 +1,6 @@
+// ESM entry for `ata-validator/t`. Re-exports the builder from the CJS
+// implementation so there is one source of truth.
+
+import mod from './t.js';
+export const { t, OPTIONAL } = mod;
+export default mod;