@ata-project/valibot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mert Can Altin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# @ata-project/valibot
+
+Run a valibot schema on the [ata engine](https://github.com/ata-core/ata-validator).
+The schema stays valibot, the answers always match valibot's own, and the
+verdicts arrive in nanoseconds.
+
+```
+npm install @ata-project/valibot
+```
+
+valibot and ata-validator are installed alongside; valibot is a peer.
+
+```js
+import * as v from 'valibot'
+import { compile } from '@ata-project/valibot'
+
+const user = v.object({
+  id: v.pipe(v.number(), v.integer(), v.minValue(1)),
+  name: v.pipe(v.string(), v.minLength(1)),
+})
+
+const check = compile(user)
+check.isValid(data)        // ata answers
+check.safeParse(data)      // valibot-shaped result, valibot-produced value
+check.parse(data)          // throws a real ValiError
+check.isValidBytes(bytes)  // verdict from a Buffer or JSON string
+```
+
+## How it stays correct
+
+valibot ships an official JSON Schema conversion (`@valibot/to-json-schema`).
+The bridge asks it for the input side with unrepresentable features ignored,
+which can only make the emitted schema looser than valibot, never stricter.
+Then the schema is classified by walking valibot's own tree before anything
+runs:
+
+| Mode | When | Who answers |
+|---|---|---|
+| `ata` | the conversion is exact | ata alone |
+| `hybrid` | provably looser (transforms, checks, formats, native types) | ata's rejections are final, valibot confirms acceptances |
+| `valibot` | valibot accepts what the conversion rejects (fallback, records, async) or a node is unknown | valibot |
+
+The classification is conservative: an unrecognised node lands in `valibot`
+mode, so a new valibot feature can make the bridge slower, never wrong.
+`compiled.engine` tells you which mode you got, `compiled.reasons` says why.
+
+Two valibot semantics survive nowhere in JSON Schema and are handled
+explicitly rather than papered over. valibot's `number` accepts Infinity,
+which JSON has no word for: schemas that constrain numbers get a scan of the
+rejected value, and a rejection that might be Infinity-caused is handed to
+valibot for the final word. And `v.record` runs on arrays too, so records stay
+valibot's entirely.
+
+The package is differential-tested against valibot on 10,249 generated values
+across all three modes, including NaN and Infinity corners, and the whole
+suite runs a second time with code generation blocked.
+
+## What it costs, measured
+
+One representative API-boundary object schema (nine fields, nested arrays of
+objects, picklist, nullable), interleaved medians of 7 rounds on an M-series
+Mac, Node 25, valibot 1.4.2, ata-validator 1.13.2:
+
+| | valibot `safeParse` | this package |
+|---|---|---|
+| accept, verdict only | 1,051 ns | **20 ns** |
+| reject, verdict only | 1,117 ns | **83 ns** |
+| reject, `safeParse` | 1,117 ns | **84 ns** |
+| accept, `safeParse` | 1,051 ns | 1,062 ns |
+
+The last row is by design, not a gap: an accepted value's output is valibot's
+to make. Plain `v.object` strips unknown keys, defaults fill, transforms
+rewrite, so `safeParse` hands every accepted value to valibot and returns
+exactly what valibot returns. What this package owns is the verdict and the
+rejection, and a rejected `safeParse` builds its issues only when somebody
+reads them, by running valibot once at that moment.
+
+The reject rows carry the Infinity scan described above; on schemas with no
+number constraints they drop to the bare engine verdict.
+
+With code generation blocked, the way a strict CSP or a locked-down edge
+runtime blocks it: valibot stays at its usual speed, and the bridge falls back
+to ata's interpreted engine at 624 ns for accepts and 187 ns for rejects,
+still ahead on both.
+
+## Raw bytes
+
+`isValidBytes` answers from a `Buffer`, `Uint8Array` or JSON string. On an
+`engine: 'ata'` schema with no number constraints and the native engine
+present, the verdict comes straight off the bytes with no `JSON.parse`; other
+schemas parse first so number semantics stay exact. Bytes that are not valid
+JSON return `false` rather than throwing.
+
+## Limitations, plainly
+
+- Accepted values in `hybrid` mode and every value in `valibot` mode run
+  valibot, so those paths are valibot-speed. The win is the rejection and the
+  pure-schema case.
+- `validate()` reports ata's errors for the schema-representable part, which
+  are JSON Schema errors, not valibot issues. Use `safeParse` when you need
+  valibot's issue shape.
+- The classifier reads valibot's public schema tree and the peer range is
+  pinned to valibot 1; the differential suite is the tripwire for internals
+  moving.
+- Async schemas are not supported; `safeParse` is synchronous, as in valibot.
+
+## Standard Schema
+
+The compiled object implements Standard Schema V1, so anything that accepts a
+standard schema runs the fast path without knowing either library.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,71 @@
+import type { BaseIssue, GenericSchema, InferInput, InferOutput, ValiError } from 'valibot'
+
+/** How a schema was classified, and why. */
+export interface Analysis {
+  /**
+   * 'ata': the JSON Schema conversion is exact and ata answers alone.
+   * 'hybrid': the conversion is provably looser (transforms, checks, formats,
+   * native types), so ata's rejections are final and valibot confirms the
+   * acceptances.
+   * 'valibot': a feature makes valibot accept what the converted schema
+   * rejects (fallback, records over arrays, async) or a node is unknown;
+   * valibot answers.
+   */
+  mode: 'ata' | 'hybrid' | 'valibot'
+  /** The nodes that forced the mode, first eight. */
+  reasons: string[]
+  /** Whether parsing can return a value that differs from the input. */
+  producesValue: boolean
+}
+
+export type SafeParseResult<S extends GenericSchema> =
+  | { typed: true; success: true; output: InferOutput<S>; issues?: undefined }
+  | { typed: boolean; success: false; output: unknown; issues: [BaseIssue<unknown>, ...BaseIssue<unknown>[]] }
+
+export interface CompiledValibot<S extends GenericSchema> {
+  /** The verdict, at ata speed where the classification allows it. */
+  isValid(data: unknown): boolean
+  /**
+   * Verdict on raw bytes or a JSON string. An engine:'ata' schema with no
+   * number constraints is decided without JSON.parse when the native engine
+   * is present; other schemas and pure-JS installs parse first. Bytes that
+   * are not JSON return false.
+   */
+  isValidBytes(input: Uint8Array | string): boolean
+  /** valibot-shaped result. Accepted values run valibot, so `output` is
+   * exactly what valibot returns (unknown keys stripped, defaults filled,
+   * transforms applied). Rejections are decided by ata; the issues are built
+   * on first read. */
+  safeParse(data: unknown): SafeParseResult<S>
+  /** Like safeParse but throwing the ValiError. */
+  parse(data: unknown): InferOutput<S>
+  /** ata's error report for the schema-representable part; valibot's issues
+   * where only valibot knows why. */
+  validate(data: unknown): { valid: true; data: unknown } | { valid: false; errors: unknown[] }
+  /** The emitted JSON Schema, or null in valibot mode. */
+  schema: object | null
+  /** The original valibot schema. */
+  valibotSchema: S
+  /** Which mode the classification chose. */
+  engine: 'ata' | 'hybrid' | 'valibot'
+  /** Why, first eight reasons. */
+  reasons: string[]
+  /** Standard Schema V1. */
+  '~standard': {
+    version: 1
+    vendor: 'ata-valibot'
+    validate(value: unknown):
+      | { value: InferOutput<S> }
+      | { issues: Array<{ message: string; path?: Array<PropertyKey> }> }
+  }
+}
+
+export interface CompileOptions {
+  /** Options forwarded to the ata Validator (formats stay unasserted). */
+  validator?: object
+}
+
+export declare function compile<S extends GenericSchema>(schema: S, opts?: CompileOptions): CompiledValibot<S>
+export declare function analyze(schema: unknown): Analysis
+export declare function toJSONSchema(schema: GenericSchema): object
+export type { InferInput, InferOutput, ValiError }

package/index.js

@@ -0,0 +1,317 @@
+'use strict'
+
+// Run a valibot schema on the ata engine.
+//
+//   const check = compile(schema)
+//   check.isValid(data)                 // ata answers
+//   check.safeParse(data)               // valibot-shaped result, valibot value
+//
+// valibot ships an official JSON Schema conversion (@valibot/to-json-schema),
+// and ata is a JSON Schema engine. The conversion is asked for the input side
+// (`typeMode: 'input'`) with unrepresentable features ignored, which can only
+// make the emitted schema looser than valibot, never stricter. That gives the
+// same contract as the zod bridge: a schema classified `ata` is exact and the
+// engine answers alone; a schema with residue (transforms, checks, formats,
+// native types) runs in `hybrid` mode, where ata's rejections are final and
+// valibot confirms the acceptances; anything that widens acceptance beyond
+// the emitted schema (fallback) or that the classifier has never seen hands
+// the whole schema to valibot. Unknown nodes land in `valibot` mode, so a new
+// valibot feature can make the bridge slower, never wrong.
+
+// ---------------------------------------------------------------------------
+// classification
+
+// Schema node types whose emitted schema equals valibot's acceptance, given
+// their children do.
+const EXACT = new Set([
+  'string', 'number', 'boolean', 'null', 'literal', 'picklist', 'enum',
+  'object', 'strict_object', 'loose_object', 'array', 'tuple', 'union',
+  'variant', 'intersect', 'optional', 'nullable', 'nullish',
+  'exact_optional', 'any', 'unknown', 'lazy',
+])
+
+// Schema node types JSON Schema cannot express: the emitted input schema is
+// `{}` for them, strictly looser, so ata's rejections stay sound and valibot
+// owns the acceptance.
+const RESIDUE = new Set([
+  'date', 'bigint', 'blob', 'file', 'map', 'set', 'symbol', 'undefined',
+  'void', 'nan', 'promise', 'function', 'instance', 'custom', 'never',
+])
+
+// Pipe validations the converter emits as structural JSON Schema keywords
+// with the same semantics ata checks. Formats (email, url, uuid and friends)
+// are deliberately NOT here: ata's format checks are not guaranteed to match
+// valibot's character for character, so the engine is compiled with format
+// assertion off and every format action stays residue for valibot to confirm.
+const EXACT_ACTIONS = new Set([
+  'min_length', 'max_length', 'length', 'min_value', 'max_value',
+  'multiple_of', 'integer', 'regex', 'min_entries', 'max_entries',
+])
+
+const CHILD_LISTS = ['options', 'items', 'pipe']
+const CHILD_NODES = ['item', 'wrapped', 'key', 'value', 'rest']
+
+function analyze (schema) {
+  const seen = new Set()
+  const reasons = []
+  let mode = 'ata'
+  let producesValue = false
+
+  const escalate = (to, why) => {
+    if (to === 'valibot') mode = 'valibot'
+    else if (to === 'hybrid' && mode === 'ata') mode = 'hybrid'
+    if (reasons.length < 8) reasons.push(why)
+  }
+
+  const walk = (node) => {
+    if (!node || typeof node !== 'object' || seen.has(node)) return
+    seen.add(node)
+    if (node.kind !== 'schema') { escalate('valibot', 'node without a schema kind'); return }
+    const type = node.type
+
+    if (node.async) escalate('valibot', 'async schema at ' + type)
+    // v.fallback() swallows failures and returns a value, so valibot accepts
+    // input the emitted schema turns away. A fast rejection would be a wrong
+    // rejection.
+    if (node.fallback !== undefined) { escalate('valibot', 'fallback at ' + type); producesValue = true }
+    if (node.default !== undefined) producesValue = true
+
+    // valibot's record runs on anything object-typed, arrays included, while
+    // the emitted schema's `object` excludes them; a fast rejection of an
+    // array would be a wrong rejection, so records stay valibot's.
+    if (type === 'record') escalate('valibot', 'record accepts arrays')
+    else if (RESIDUE.has(type)) escalate('hybrid', type)
+    else if (!EXACT.has(type)) escalate('valibot', 'unrecognised node ' + type)
+
+    if (Array.isArray(node.pipe)) {
+      // pipe[0] is the base schema and the only stage the input-side
+      // conversion emits beyond whitelisted validations. Everything after it
+      // can only tighten what valibot accepts, so residue stays sound.
+      for (let i = 1; i < node.pipe.length; i++) {
+        const item = node.pipe[i]
+        if (!item || typeof item !== 'object') continue
+        if (item.kind === 'metadata') continue
+        if (item.kind === 'validation') {
+          if (!EXACT_ACTIONS.has(item.type)) escalate('hybrid', item.type + ' at ' + type)
+        } else if (item.kind === 'transformation') {
+          escalate('hybrid', item.type + ' at ' + type)
+          producesValue = true
+        } else if (item.kind === 'schema') {
+          escalate('hybrid', 'piped schema at ' + type)
+          producesValue = true
+        } else {
+          escalate('valibot', 'unrecognised pipe item ' + String(item.kind))
+        }
+      }
+    }
+
+    if (node.entries) for (const k of Object.keys(node.entries)) walk(node.entries[k])
+    for (const k of CHILD_NODES) if (node[k] && typeof node[k] === 'object') walk(node[k])
+    for (const k of CHILD_LISTS) {
+      if (k === 'pipe') continue
+      if (Array.isArray(node[k])) for (const child of node[k]) walk(child)
+    }
+    if (Array.isArray(node.pipe) && node.pipe[0] && node.pipe[0] !== node) walk(node.pipe[0])
+    if (typeof node.getter === 'function') {
+      try { walk(node.getter(undefined)) } catch { escalate('valibot', 'lazy getter threw') }
+    }
+  }
+
+  walk(schema)
+  return { mode, reasons, producesValue }
+}
+
+// ---------------------------------------------------------------------------
+// compile
+
+function requireValibot () {
+  // Resolved lazily from the peer so this package never pins its own copy.
+  return require('valibot')
+}
+
+function toJSONSchema (schema) {
+  const { toJsonSchema } = require('@valibot/to-json-schema')
+  return toJsonSchema(schema, { typeMode: 'input', errorMode: 'ignore' })
+}
+
+// One semantic gap survives the conversion: valibot's `number` accepts
+// Infinity and -Infinity (it only turns away NaN), while ata follows JSON,
+// where no such values exist. Values holding them can only be built in
+// JavaScript, never parsed from JSON, so the engine's verdict stands unless
+// the schema constrains numbers somewhere AND the rejected value actually
+// carries a non-finite number, in which case valibot gets the final word.
+function schemaChecksNumbers (node, seen) {
+  if (!node || typeof node !== 'object') return false
+  if (seen.has(node)) return false
+  seen.add(node)
+  if (node.type === 'number' || (Array.isArray(node.type) && node.type.includes('number'))) return true
+  for (const k of Object.keys(node)) {
+    const child = node[k]
+    if (Array.isArray(child)) {
+      for (const it of child) if (schemaChecksNumbers(it, seen)) return true
+    } else if (schemaChecksNumbers(child, seen)) return true
+  }
+  return false
+}
+
+// Depth-capped so cyclic input cannot loop: past the cap the scan reports
+// "might", and the delegate below decides inside a try/catch.
+function hasNonFinite (value, depth) {
+  if (typeof value === 'number') return value === Infinity || value === -Infinity
+  if (value === null || typeof value !== 'object') return false
+  if (depth > 256) return true
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) if (hasNonFinite(value[i], depth + 1)) return true
+    return false
+  }
+  for (const k in value) if (hasNonFinite(value[k], depth + 1)) return true
+  return false
+}
+
+function confirmNonFinite (v, schema, d) {
+  try {
+    return v.safeParse(schema, d).success
+  } catch {
+    // valibot could not decide (cyclic input past the scan cap); the engine's
+    // rejection stands.
+    return false
+  }
+}
+
+// A rejection whose issues are built on first read, by running valibot once
+// at that moment. The getter lives on the prototype: an object-literal
+// accessor per rejection costs about a hundred nanoseconds, which is the
+// whole budget of the fast path. The classifier proves ata only rejects what
+// valibot rejects; were that ever broken, the getter hands back what ata saw
+// rather than nothing, and the differential suite is the place that fails.
+class LazyRejection {
+  constructor (schema, engine, data) {
+    this.typed = false
+    this.success = false
+    this.output = data
+    this._schema = schema
+    this._engine = engine
+    this._issues = null
+  }
+}
+Object.defineProperty(LazyRejection.prototype, 'issues', {
+  enumerable: true,
+  configurable: true,
+  get () {
+    if (this._issues === null) {
+      const v = requireValibot()
+      const r = v.safeParse(this._schema, this.output)
+      this._issues = r.success
+        ? this._engine.validate(this.output).errors.map((e) => ({
+            kind: 'schema', type: 'ata', input: this.output, expected: null,
+            received: 'unknown', message: e.message, path: undefined,
+          }))
+        : r.issues
+    }
+    return this._issues
+  },
+})
+
+function compile (schema, opts) {
+  const options = opts || {}
+  const v = requireValibot()
+  const analysis = analyze(schema)
+  const jsonSchema = analysis.mode === 'valibot' ? null : toJSONSchema(schema)
+  const engine = jsonSchema
+    ? new (require('ata-validator').Validator)(jsonSchema, { assertFormat: false, ...options.validator })
+    : null
+  const rawFast = engine ? (d) => engine.isValidObject(d) : null
+  // A rejection is final unless the value carries Infinity, which valibot
+  // accepts where JSON has no word for it. The escape only exists for
+  // schemas that constrain numbers at all, and it only ever runs on the
+  // rejected path, so JSON-borne data never pays for it.
+  const numeric = engine ? schemaChecksNumbers(jsonSchema, new Set()) : false
+  const fast = !rawFast ? null : !numeric ? rawFast
+    : (d) => rawFast(d) || (hasNonFinite(d, 0) && confirmNonFinite(v, schema, d))
+
+  let isValid
+  if (analysis.mode === 'ata') {
+    isValid = fast
+  } else if (analysis.mode === 'hybrid') {
+    // ata turning a value down is final; ata letting it through hands it to
+    // valibot for the checks and native types the JSON Schema cannot carry.
+    isValid = (d) => fast(d) && v.safeParse(schema, d).success
+  } else {
+    isValid = (d) => v.safeParse(schema, d).success
+  }
+
+  // The parsed value is valibot's to make: plain v.object strips unknown
+  // keys, defaults fill, transforms rewrite, so an accepted value always runs
+  // valibot and comes back exactly as valibot would return it. What ata owns
+  // is the rejection: it is decided at ata speed, and the issues are built
+  // only if somebody reads them, by running valibot once at that moment.
+  const safeParse = (d) => {
+    if (fast && !fast(d)) return new LazyRejection(schema, engine, d)
+    return v.safeParse(schema, d)
+  }
+
+  // Raw bytes: an engine:'ata' schema is decided without JSON.parse, straight
+  // off the buffer by the native walker when it is present. The other modes
+  // need the materialized value for valibot, and so does a pure-JS install,
+  // so they parse and take the object path. Bytes that are not JSON are a
+  // rejection, not an exception.
+  let isValidBytes
+  if (analysis.mode === 'ata' && engine && !numeric && typeof engine.isValid === 'function') {
+    isValidBytes = (input) => engine.isValid(input)
+  } else {
+    const td = new TextDecoder()
+    isValidBytes = (input) => {
+      let value
+      try {
+        value = JSON.parse(typeof input === 'string' ? input : td.decode(input))
+      } catch {
+        return false
+      }
+      return isValid(value)
+    }
+  }
+
+  // ata's error report for the schema-representable part; valibot's issues
+  // where only valibot knows why.
+  const validate = (d) => {
+    if (engine) {
+      const r = engine.validate(d)
+      if (!r.valid) return { valid: false, errors: r.errors }
+    }
+    if (analysis.mode !== 'ata') {
+      const vr = v.safeParse(schema, d)
+      if (!vr.success) return { valid: false, errors: vr.issues }
+    }
+    return { valid: true, data: d }
+  }
+
+  const compiled = {
+    isValid,
+    isValidBytes,
+    safeParse,
+    parse: (d) => {
+      const r = safeParse(d)
+      if (r.success) return r.output
+      throw new v.ValiError(r.issues)
+    },
+    validate,
+    schema: jsonSchema,
+    valibotSchema: schema,
+    engine: analysis.mode,
+    reasons: analysis.reasons,
+  }
+
+  compiled['~standard'] = {
+    version: 1,
+    vendor: 'ata-valibot',
+    validate (value) {
+      const r = safeParse(value)
+      if (r.success) return { value: r.output }
+      return { issues: r.issues.map((i) => ({ message: i.message, path: i.path && i.path.map((p) => p.key) })) }
+    },
+  }
+
+  return compiled
+}
+
+module.exports = { compile, analyze, toJSONSchema }

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@ata-project/valibot",
+  "version": "0.1.0",
+  "description": "Run valibot schemas on the ata engine: same answers, verdicts in nanoseconds",
+  "license": "MIT",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ata-core/ata-valibot.git"
+  },
+  "scripts": {
+    "test": "node test.js && node --disallow-code-generation-from-strings test.js && npm run test:types",
+    "bench": "node bench.mjs",
+    "test:types": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@valibot/to-json-schema": "^1.3.0",
+    "ata-validator": "^1.13.2"
+  },
+  "peerDependencies": {
+    "valibot": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.0",
+    "typescript": "^5.6.0",
+    "valibot": "^1.0.0"
+  }
+}