@ata-project/valibot 0.1.0 → 0.2.0

package/README.md

@@ -51,9 +51,10 @@ 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.
+The package is differential-tested against valibot on 11,788 generated values
+across all three modes, including NaN and Infinity corners and the compiled
+modules the build entry emits, and the whole suite runs a second time with
+code generation blocked.
 
 ## What it costs, measured
 
@@ -83,6 +84,44 @@ 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.
 
+## Ahead of time, for the browser
+
+The runtime bridge above carries a general engine that can validate any schema
+handed to it. In a browser that is the wrong trade, and valibot users of all
+people know why: a bundle is not the place for a compiler.
+
+So compile the schema instead, at build time:
+
+```js
+import { compileToModule } from '@ata-project/valibot/build'
+import { writeFileSync } from 'node:fs'
+
+writeFileSync('validate-product.js', compileToModule(productSchema))
+```
+
+The emitted module imports nothing, not valibot and not ata. It exports
+`isValid(data)` and `validate(data)`. Measured on a four-field product schema,
+esbuild, minified and gzipped:
+
+| what ships | gz |
+|---|---|
+| valibot, tree-shaken for that schema | 1.7 KB |
+| this package's runtime bridge (the engine) | 66.2 KB |
+| **the compiled module** | **1.67 KB** |
+
+Both the compiled module and valibot's 1.7 KB include error reporting, so
+that is a fair pairing: the same size, no runtime dependency at all, and a
+function that was compiled rather than walked.
+
+Only schemas the classifier calls exact can be compiled. Anything valibot
+checks at runtime (transforms, custom checks, formats, native types) throws
+`NotExactError` rather than being quietly compiled without those checks; use
+the runtime bridge for those. `canCompile(schema)` tells you which you have
+before you build.
+
+Emitting a module uses code generation, so run it at build time in Node. What
+it emits is plain code and runs anywhere, a strict CSP included.
+
 ## Raw bytes
 
 `isValidBytes` answers from a `Buffer`, `Uint8Array` or JSON string. On an

package/build.d.ts

@@ -0,0 +1,39 @@
+import type { GenericSchema } from 'valibot'
+
+export interface CompileToModuleOptions {
+  /** Module format of the emitted source. Default 'esm'. */
+  format?: 'esm' | 'cjs'
+}
+
+export interface CanCompileResult {
+  /** Whether the schema converts exactly and can be compiled. */
+  ok: boolean
+  mode: 'ata' | 'hybrid' | 'valibot'
+  /** Why not, when it cannot. */
+  reasons: string[]
+}
+
+export declare class NotExactError extends Error {
+  name: 'NotExactError'
+  mode: 'hybrid' | 'valibot'
+  reasons: string[]
+}
+
+/**
+ * Compile a valibot schema to standalone module source that imports nothing,
+ * not valibot and not ata. The module exports `isValid(data)` and
+ * `validate(data)`.
+ *
+ * Only schemas the classifier calls exact can be compiled; anything valibot
+ * checks at runtime throws NotExactError rather than being silently dropped.
+ *
+ * Emitting needs code generation, so run this at build time in Node. What it
+ * emits is plain code and runs anywhere, including under a strict CSP.
+ */
+export declare function compileToModule(schema: GenericSchema, opts?: CompileToModuleOptions): string
+
+/** Whether a schema can be compiled ahead of time, and why not when it cannot. */
+export declare function canCompile(schema: GenericSchema): CanCompileResult
+
+/** Whether this runtime allows the code generation the emitter needs. */
+export declare function codegenAvailable(): boolean

package/build.js

@@ -0,0 +1,102 @@
+'use strict'
+
+// Build-time compilation: a valibot schema becomes a standalone JavaScript
+// module that imports nothing, not even this package or ata.
+//
+//   const { compileToModule } = require('@ata-project/valibot/build')
+//   fs.writeFileSync('validate-user.js', compileToModule(userSchema))
+//
+// The emitted module is a plain function. Nothing about valibot or the ata
+// engine ships with it, which is the point: the runtime bridge carries a
+// general engine that can validate any schema handed to it, while this
+// carries only the code for the one schema you compiled.
+//
+// Only schemas the classifier calls exact (`engine: 'ata'`) can be compiled.
+// A hybrid schema is one whose JSON Schema conversion is deliberately looser
+// than valibot, with valibot confirming the acceptances at runtime; emitting
+// a standalone module for it would drop those checks silently and accept
+// documents valibot rejects. This refuses instead. Declining to compile is
+// recoverable; a validator that wrongly accepts is not.
+
+const { analyze, toJSONSchema } = require('./index.js')
+
+// The emitter builds the module source through the code generator, so this
+// runs at build time in Node. What it emits is plain code with no generation
+// of its own, so the compiled module runs anywhere, CSP included.
+function codegenAvailable () {
+  try {
+    // eslint-disable-next-line no-new-func
+    new Function('return 1')
+    return true
+  } catch {
+    return false
+  }
+}
+
+class NotExactError extends Error {
+  constructor (analysis) {
+    super(
+      'this schema cannot be compiled ahead of time: ' + analysis.reasons.join(', ') +
+      '. Those features are checked by valibot at runtime, so a standalone module ' +
+      'would accept documents valibot rejects. Use compile() from the package root instead.',
+    )
+    this.name = 'NotExactError'
+    this.mode = analysis.mode
+    this.reasons = analysis.reasons
+  }
+}
+
+function header () {
+  return '// Generated by @ata-project/valibot from a valibot schema.\n' +
+    '// Standalone: imports nothing, including valibot and ata.\n' +
+    '//\n' +
+    '// This follows JSON Schema semantics, which is what the wire carries.\n' +
+    '// One documented difference from valibot in this direction: valibot\'s\n' +
+    '// number() accepts Infinity, a value JSON cannot express, and this\n' +
+    '// rejects it. Any document that arrived as JSON behaves identically.\n' +
+    '//\n' + '// Exports: isValid(data) and validate(data).\n'
+}
+
+// Compile a valibot schema to standalone module source.
+//
+// opts.format: 'esm' (default) or 'cjs'
+//
+// The module exports `isValid(data)` for the verdict and `validate(data)` for
+// the verdict with an error report. Rename at the import site if you are
+// compiling several schemas into one place; this deliberately does not
+// rewrite the generated source to rename them, because rewriting emitted
+// code is how validators start silently accepting things.
+function compileToModule (schema, opts) {
+  const options = opts || {}
+  const analysis = analyze(schema)
+  if (analysis.mode !== 'ata') throw new NotExactError(analysis)
+
+  const { Validator } = require('ata-validator')
+  const { toStandaloneModule } = require('ata-validator/aot')
+  const jsonSchema = toJSONSchema(schema)
+  const validator = new Validator(jsonSchema, { assertFormat: false })
+  const src = toStandaloneModule(validator, { format: options.format || 'esm' })
+  if (!src) {
+    throw new Error(
+      codegenAvailable()
+        ? 'the ata engine declined to emit a standalone module for this schema. ' +
+          'Use compile() from the package root instead.'
+        : 'compiling to a module needs code generation, which this runtime blocks. ' +
+          'Run the compile step at build time in Node; the module it emits is plain ' +
+          'code and runs anywhere, including under a strict CSP.',
+    )
+  }
+  return header() + src
+}
+
+// Whether a schema can be compiled ahead of time, and why not when it cannot.
+function canCompile (schema) {
+  const analysis = analyze(schema)
+  return {
+    ok: analysis.mode === 'ata',
+    mode: analysis.mode,
+    reasons: analysis.reasons,
+  }
+}
+
+module.exports = { compileToModule, canCompile, codegenAvailable, NotExactError }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ata-project/valibot",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Run valibot schemas on the ata engine: same answers, verdicts in nanoseconds",
   "license": "MIT",
   "main": "index.js",
@@ -8,6 +8,8 @@
   "files": [
     "index.js",
     "index.d.ts",
+    "build.js",
+    "build.d.ts",
     "README.md",
     "LICENSE"
   ],
@@ -34,5 +36,16 @@
     "@types/node": "^26.5.0",
     "typescript": "^5.6.0",
     "valibot": "^1.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./build": {
+      "types": "./build.d.ts",
+      "default": "./build.js"
+    },
+    "./package.json": "./package.json"
   }
 }