zod-aot 0.13.0 → 0.14.0

package/README.md

@@ -7,467 +7,368 @@
 [![npm](https://img.shields.io/npm/v/zod-aot)](https://www.npmjs.com/package/zod-aot)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-No code changes required — keep your existing Zod schemas and get **2-64x faster** validation.
+Keep your existing Zod schemas. Get **2-64x faster** validation. No code changes required.
 
-## Why
-
-Zod v4 is already fast, but runtime schema traversal still costs ~10x compared to ahead-of-time (AOT) compiled approaches. Existing AOT solutions like [Typia](https://typia.io/) require rewriting your schemas as TypeScript types. **zod-aot** bridges this gap — it takes your existing Zod schemas and generates optimized, plain JavaScript validation functions at build time.
+```typescript
+// vite.config.ts — add one line
+import zodAot from "zod-aot/vite";
+export default defineConfig({
+  plugins: [zodAot({ autoDiscover: true })],
+});
+```
 
-| | Zod AOT             | Typia | AJV standalone | Zod v3 | Zod v4 |
-|---|---------------------|---|---|---|---|
-| **Input** | Zod schemas         | TS types | JSON Schema | Zod schemas | Zod schemas |
-| **Existing code changes** | None                | Full rewrite | Full rewrite | N/A | N/A |
-| **Type inference** | Inherited from Zod  | Native | External | Native | Native |
-| **Runtime dependency** | None (generated code) | Typia runtime | AJV runtime | Zod | Zod |
+```typescript
+// src/schemas.ts — write plain Zod, nothing else
+import { z } from "zod";
 
-## Benchmarks
+export const UserSchema = z.object({
+  name: z.string().min(3),
+  email: z.email(),
+  age: z.number().int().positive(),
+});
 
-Measured with `vitest bench` on Node.js (Apple M-series). The benchmark suite compares **Zod v3**, **Zod v4**, **zod-aot**, **[ajv](https://ajv.js.org/)**, and **[typia](https://typia.io/)** across primitives, objects, collections, unions, recursive schemas, and real-world scenarios.
+// Use it anywhere — tRPC, Hono, React Hook Form, etc.
+// At build time, zod-aot compiles it to a 3-64x faster validator.
+```
 
-Run benchmarks locally:
+## Install
 
 ```bash
-pnpm bench
+npm install zod-aot zod@^4
 ```
 
-### safeParse
+| Runtime | Version |
+|---------|---------|
+| Node.js | 20+     |
+| Bun     | 1.3+    |
+| Deno    | 2.0+    |
 
-| Scenario | Zod v3 | Zod v4 | **Zod AOT** | Typia | AJV | vs Zod v4 |
-|---|---|---|---|---|---|---|
-| simple string | 8.7M | 10.0M | **11.0M** | 11.0M | 11.1M | 1.1x |
-| string (min/max) | 8.3M | 6.0M | **11.1M** | 11.3M | 9.5M | 1.8x |
-| number (int+positive) | 8.2M | 5.8M | **10.9M** | 10.7M | 10.9M | 1.9x |
-| enum | 8.0M | 9.5M | **10.6M** | 10.6M | 10.5M | 1.1x |
-| bigint (min/max) | 8.0M | 6.0M | **10.9M** | — | — | 1.8x |
-| tuple [string, int, bool] | 4.0M | 4.4M | **10.5M** | 10.8M | 10.5M | 2.4x |
-| record\<string, number\> | 2.3M | 1.9M | **5.4M** | 7.5M | 9.4M | 2.8x |
-| set\<string\> (5 items) | 2.7M | 1.6M | **9.8M** | — | — | 6.3x |
-| set\<string\> (20 items) | 1.0M | 475K | **7.7M** | — | — | **16x** |
-| map\<string, number\> (5 entries) | 1.5M | 946K | **8.5M** | — | — | 9.0x |
-| map\<string, number\> (20 entries) | 490K | 238K | **5.2M** | — | — | **22x** |
-| pipe (non-transform) | 6.3M | 3.8M | **10.8M** | — | — | 2.8x |
-| discriminatedUnion (3 variants) | 2.3M | 2.9M | **9.8M** | 10.4M | 5.6M | 3.4x |
-| medium object (valid) | 1.3M | 1.7M | **5.4M** | 7.3M | 5.0M | 3.1x |
-| medium object (invalid) | 351K | 65K | **471K** | 2.1M | 5.6M | 7.3x |
-| large object (10 items) | 82K | 111K | **4.0M** | 4.1M | 834K | **36x** |
-| large object (100 items) | 9.0K | 11.6K | **676K** | 808K | 89K | **58x** |
-| recursive tree (7 nodes) | 424K | 1.5M | **6.4M** | 8.1M | 3.1M | 4.1x |
-| recursive tree (121 nodes) | 24K | 101K | **741K** | 1.4M | 250K | 7.4x |
-| event log (combined) | 260K | 479K | **4.5M** | — | — | 9.4x |
-| partial fallback obj (transform) | 817K | 1.4M | **3.3M** | — | — | 2.3x |
-| partial fallback arr 10 (transform) | 88K | 139K | **841K** | — | — | 6.1x |
-| partial fallback arr 50 (transform) | 18K | 28K | **175K** | — | — | 6.3x |
+## Usage
 
-*ops/s, higher is better. "—" = not supported by the library. Measured with `vitest bench` on Apple M-series.*
+There are three ways to use zod-aot. Choose the one that fits your project.
 
-Performance gains scale with schema complexity. The `discriminatedUnion` optimization uses an O(1) `switch` dispatch instead of Zod's sequential trial approach. Partial fallback schemas (containing `transform`/`refine`) still show 2-6x speedups by compiling the optimizable portions. Set/Map/BigInt are only benchmarked among Zod variants as AJV and Typia lack native support for these types.
+### 1. autoDiscover (Recommended)
 
-## Runtime Support
+The plugin automatically detects and compiles all exported Zod schemas at build time. No wrappers, no imports from `zod-aot` in your source code.
 
-| Runtime | Version | Status |
-|---------|---------|--------|
-| Node.js | 20+     | Fully supported |
-| Bun     | 1.3+    | Fully supported |
-| Deno    | 2.0+    | Fully supported |
+**vite.config.ts:**
 
-## Install
+```typescript
+import zodAot from "zod-aot/vite";
 
-```bash
-npm install zod-aot
-# zod v4 is a peer dependency
-npm install zod@^4
+export default defineConfig({
+  plugins: [zodAot({ autoDiscover: true })],
+});
 ```
 
-## Quick Start
-
-### 1. Define schemas with `compile()`
+**Your schema file stays pure Zod:**
 
 ```typescript
 // src/schemas.ts
 import { z } from "zod";
-import { compile } from "zod-aot";
 
-const UserSchema = z.object({
-  name: z.string().min(3),
-  age: z.number().int().positive(),
+export const CreateUserSchema = z.object({
+  name: z.string().min(1).max(100),
   email: z.email(),
-  role: z.enum(["admin", "user"]),
+  age: z.number().int().min(0).max(150),
+  role: z.enum(["admin", "editor", "viewer"]),
 });
 
-// compile() falls back to Zod in dev, uses generated functions after build
-export const validateUser = compile(UserSchema);
+export const UpdateUserSchema = z.object({
+  name: z.string().min(1).max(100).optional(),
+  email: z.email().optional(),
+});
+
+export const ListUsersSchema = z.object({
+  page: z.number().int().min(1).optional().default(1),
+  limit: z.number().int().min(1).max(100).optional().default(20),
+});
 ```
 
-### 2. Use the compiled validator
+**Use them as usual:**
 
 ```typescript
-// Same interface as Zod — works in both dev and production
-const user = validateUser.parse(data);          // throws on failure
-const result = validateUser.safeParse(data);    // { success, data/error }
+const user = CreateUserSchema.parse(data);          // throws on failure
+const result = CreateUserSchema.safeParse(data);    // { success, data/error }
 ```
 
-### 3. Generate optimized code
+At build time, the plugin:
+1. Finds every file with `import ... from "zod"` (skips type-only imports)
+2. Executes the file and detects exported Zod schemas
+3. Compiles each schema into an optimized validator
+4. Replaces the export with a tree-shakeable IIFE that preserves the full Zod API
+
+**What "preserves the full Zod API" means:** The compiled schema inherits from the original Zod schema via `Object.create()`. So `._zod`, `.shape`, Standard Schema (`~standard`), `instanceof` checks — all still work. Libraries that accept Zod schemas (tRPC, Hono, React Hook Form) work without changes.
 
-Choose one of these approaches:
+### 2. compile() (Explicit)
 
-**Option A: Build plugin (Vite / webpack / esbuild / Rollup / Rolldown / rspack)**
+If you prefer explicit opt-in, wrap specific schemas with `compile()`:
 
 ```typescript
-// vite.config.ts
-import zodAot from "zod-aot/vite";
+import { z } from "zod";
+import { compile } from "zod-aot";
 
-export default defineConfig({
-  plugins: [zodAot()],
+const UserSchema = z.object({
+  name: z.string().min(3),
+  email: z.email(),
 });
+
+export const validateUser = compile(UserSchema);
+
+// In dev: falls back to Zod's runtime validation
+// After build: uses AOT-compiled optimized code
+validateUser.parse(data);
+validateUser.safeParse(data);
 ```
 
-Also available: `zod-aot/webpack`, `zod-aot/esbuild`, `zod-aot/rollup`, `zod-aot/rolldown`, `zod-aot/rspack`, `zod-aot/bun`
+`compile()` and `autoDiscover` coexist — `compile()` schemas are detected first, then `autoDiscover` picks up remaining plain Zod exports.
+
+### 3. CLI (No Bundler)
 
-**Option B: CLI**
+Generate optimized validation files from the command line:
 
 ```bash
-# Generate optimized validators
+# Single file
 npx zod-aot generate src/schemas.ts -o src/schemas.compiled.ts
 
-# Generate from a directory
+# Directory
 npx zod-aot generate src/ -o src/compiled/
 
-# Watch mode — regenerate on file changes
+# Watch mode
 npx zod-aot generate src/ --watch
+```
 
-# Diagnose schemas — tree view, coverage, Fast Path, hints
-npx zod-aot check src/schemas.ts
+## Build Plugin
 
-# JSON output for CI integration
-npx zod-aot check src/schemas.ts --json
+### Supported Build Tools
 
-# Fail CI if coverage < 80%
-npx zod-aot check src/schemas.ts --json --fail-under 80
-```
+| Build Tool | Import |
+|---|---|
+| Vite | `import zodAot from "zod-aot/vite"` |
+| webpack | `import zodAot from "zod-aot/webpack"` |
+| esbuild | `import zodAot from "zod-aot/esbuild"` |
+| Rollup | `import zodAot from "zod-aot/rollup"` |
+| Rolldown | `import zodAot from "zod-aot/rolldown"` |
+| rspack | `import zodAot from "zod-aot/rspack"` |
+| Bun | `import zodAot from "zod-aot/bun"` |
 
-## Build Plugin (unplugin)
+### Options
 
-The build plugin automatically replaces `compile()` calls with optimized inline validators during the build step. No code changes needed — your source files stay the same.
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `autoDiscover` | `boolean` | `false` | Auto-detect all exported Zod schemas without `compile()` |
+| `include` | `string[]` | — | Only process files matching these substrings |
+| `exclude` | `string[]` | — | Skip files matching these substrings |
+| `zodCompat` | `boolean` | `true` | Preserve Zod API via `Object.create()`. Set `false` for smaller output |
+| `verbose` | `boolean` | `false` | Log per-schema compilation status during build |
 
 ```typescript
-// vite.config.ts
-import zodAot from "zod-aot/vite";
-export default defineConfig({ plugins: [zodAot()] });
-
-// webpack.config.js
-const zodAot = require("zod-aot/webpack");
-module.exports = { plugins: [zodAot()] };
+zodAot({
+  autoDiscover: true,
+  include: ["src/schemas"],
+  verbose: true,
+})
 ```
 
-### Options
+### autoDiscover: Side Effects Warning
+
+With `autoDiscover`, the plugin executes files to inspect their exports. If a file imports Zod AND has side effects (starts a server, connects to a database), those side effects run at build time.
+
+**Fix:** Use `include` to limit which files are scanned:
 
 ```typescript
 zodAot({
-  include: ["src/schemas"],   // only process files matching these substrings
-  exclude: ["test", "mock"],  // skip files matching these substrings
-  verbose: true,              // log per-schema compilation status and build summary
+  autoDiscover: true,
+  include: ["src/schemas", "src/validators"],
 })
 ```
 
-The plugin:
-- Runs at build time (`enforce: "pre"`)
-- Replaces `compile(Schema)` with optimized IIFE inline validators
-- Adds `/* @__PURE__ */` annotations for tree-shaking
-- Supports HMR in development
+### autoDiscover vs compile()
 
-## Zod Ecosystem Compatibility
+| | autoDiscover | compile() |
+|---|---|---|
+| Source code changes | None | Wrap each schema |
+| `zod-aot` import needed | No | Yes |
+| What gets compiled | All exported Zod schemas | Only wrapped schemas |
+| Build-time file execution | Files with `import ... from "zod"` | Files with `import ... from "zod-aot"` |
+| Best for | New projects, framework integration | Gradual adoption, selective optimization |
 
-`compile()` returns a full Zod schema (`T & CompiledSchema<T>`) — it preserves all original Zod methods and only replaces validation methods (`safeParse`, `parse`, etc.) with AOT-optimized versions. This means compiled schemas work with any library that accepts Zod schemas.
+## Framework Examples
 
-### Hono
+### tRPC
 
 ```typescript
-import { Hono } from "hono";
-import { zValidator } from "@hono/zod-validator";
+// src/schemas.ts
 import { z } from "zod";
-import { compile } from "zod-aot";
 
-const UserSchema = z.object({
-  name: z.string().min(3),
-  age: z.number().int().positive(),
+export const CreateUserSchema = z.object({
+  name: z.string().min(1).max(100),
   email: z.email(),
+  age: z.number().int().min(0).max(150),
+});
+
+// src/router.ts
+import { CreateUserSchema } from "./schemas";
+
+export const appRouter = t.router({
+  createUser: t.procedure
+    .input(CreateUserSchema)
+    .mutation(({ input }) => createUser(input)),
 });
+```
 
-// Still a Zod schema — but safeParse is AOT-optimized
-const validateUser = compile(UserSchema);
+With `autoDiscover: true`, `CreateUserSchema` is compiled at build time. The tRPC router uses the optimized version automatically. No `.input(compile(CreateUserSchema))` needed.
+
+### Hono
+
+```typescript
+import { Hono } from "hono";
+import { zValidator } from "@hono/zod-validator";
+import { UserSchema } from "./schemas";
 
 const app = new Hono();
 
-app.post("/users", zValidator("json", validateUser), (c) => {
+app.post("/users", zValidator("json", UserSchema), (c) => {
   const user = c.req.valid("json");
   return c.json(user);
 });
 ```
 
-`@hono/zod-validator` internally calls `schema.safeParse()` — with zod-aot, this call is replaced by the generated optimized validator at build time, giving you faster request validation with zero code changes.
-
-## Schema Diagnostics (`check`)
-
-The `check` command analyzes schemas for compilation coverage, Fast Path eligibility, and actionable hints — without generating code.
+### React Hook Form
 
-```bash
-npx zod-aot check src/schemas.ts
+```typescript
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { UserSchema } from "./schemas";
+
+function UserForm() {
+  const form = useForm({
+    resolver: zodResolver(UserSchema),
+  });
+  // ...
+}
 ```
 
-**Output includes:**
-
-- **Tree view** — hierarchical visualization of schema structure with compile/fallback status per node
-- **Coverage** — percentage of schema nodes that are compiled (e.g. `85% compiled (17/20 nodes)`)
-- **Fast Path eligibility** — whether the schema qualifies for two-phase validation, with the specific blocker if ineligible
-- **Hints** — actionable suggestions (e.g. "Replace `.refine()` with built-in checks")
+### Any Standard Schema Consumer
 
-### Options
+zod-aot compiled schemas implement [Standard Schema](https://standardschema.dev) via prototype chain. Any library that accepts Standard Schema validators works automatically.
 
-| Flag | Description |
-|---|---|
-| `--json` | Output structured JSON (for CI/CD integration) |
-| `--fail-under <pct>` | Exit with code 1 if any schema's coverage is below the threshold |
-| `--no-color` | Disable colored output |
+## Schema Diagnostics
 
-### JSON output
+Analyze your schemas before compiling — check coverage, Fast Path eligibility, and get actionable hints:
 
 ```bash
-npx zod-aot check src/schemas.ts --json
-```
-
-```json
-[
-  {
-    "file": "src/schemas.ts",
-    "schemas": [
-      {
-        "exportName": "validateUser",
-        "coverage": { "total": 5, "compilable": 5, "percent": 100 },
-        "fastPath": { "eligible": true },
-        "fallbacks": []
-      }
-    ]
-  }
-]
+npx zod-aot check src/schemas.ts
 ```
 
-### CI gate
+Output:
 
-```bash
-npx zod-aot check src/schemas.ts --json --fail-under 80
 ```
+src/schemas.ts
 
-Exits with code 1 if any schema's compilation coverage drops below 80%.
+  CreateUserSchema  [Fast Path]  100% compiled  (5 checks)
+  ├─ name: string (min_length, max_length)
+  ├─ email: string (string_format[email])
+  ├─ age: number (number_format[safeint], greater_than)
+  └─ role: enum
 
-## How It Works
+  OrderSchema  [Slow Path]  85% compiled  (3 checks)
+  ├─ id: string (string_format[uuid])
+  └─ metadata: object
+      └─ audit: fallback(transform)
+         Hint: Consider z.pipe() to keep inner schema compilable
 
+  Summary: 2 schemas | 1 Fast Path, 1 Slow Path | 8/9 nodes (88.9%)
 ```
-Zod Schema
-    │
-    ▼
-┌─────────────────────┐
-│  Extractor          │  Traverse _zod.def recursively
-│  extractSchema()    │  → produce JSON-serializable IR
-└─────────┬───────────┘
-          │ SchemaIR
-          ▼
-┌─────────────────────┐
-│  CodeGen            │  IR → optimized JS with:
-│  generateValidator()│  • inline type checks
-└─────────┬───────────┘  • pre-compiled RegExps
-          │              • Set-based enum lookups
-          ▼              • early returns
-   Optimized JS function
-   (no runtime dependencies)
-```
-
-### Why Runtime Extraction (not static analysis)
-
-- Zod v4's `_zod.def` is JSON-serializable — perfect for IR extraction
-- Static AST analysis cannot handle dynamic schemas (variable references, function calls, spread operators)
-- `_zod.bag` contains aggregated metadata from checks (minimum, maximum, regex patterns, etc.)
-- Reliable detection of `transform`/`refine` for automatic fallback
-
-### Generated Code Example
 
-**Input:**
+### CI Integration
 
-```typescript
-z.object({
-  name: z.string().min(3).max(50),
-  role: z.enum(["admin", "user"]),
-})
-```
+```bash
+# JSON output
+npx zod-aot check src/schemas.ts --json
 
-**Output:**
-
-```javascript
-/* zod-aot */
-var __set_0 = new Set(["admin", "user"]);
-
-function safeParse_validate(input) {
-  var __issues = [];
-  if (typeof input !== "object" || input === null || Array.isArray(input)) {
-    __issues.push({ code: "invalid_type", expected: "object", path: [] });
-  } else {
-    // name: string().min(3).max(50)
-    if (typeof input["name"] !== "string") {
-      __issues.push({ code: "invalid_type", expected: "string", path: ["name"] });
-    } else {
-      if (input["name"].length < 3)
-        __issues.push({ code: "too_small", minimum: 3, path: ["name"] });
-      if (input["name"].length > 50)
-        __issues.push({ code: "too_big", maximum: 50, path: ["name"] });
-    }
-
-    // role: enum(["admin", "user"])
-    if (!__set_0.has(input["role"])) {
-      __issues.push({ code: "invalid_enum_value", path: ["role"] });
-    }
-  }
-  if (__issues.length > 0) return { success: false, error: { issues: __issues } };
-  return { success: true, data: input };
-}
+# Fail if any schema below 80% coverage
+npx zod-aot check src/schemas.ts --json --fail-under 80
 ```
 
-Key optimizations in the generated code:
-
-- **No schema traversal** — all validation logic is inlined
-- **Pre-compiled RegExps** — regex patterns are compiled once, reused across calls
-- **Set-based enum lookups** — O(1) membership tests instead of array iteration
-- **Early type checks** — nested checks only run if the type is correct
-- **Minimal allocations** — issues array is only created once per call
-
-## API Reference
+| Flag | Description |
+|---|---|
+| `--json` | Structured JSON output |
+| `--fail-under <pct>` | Exit code 1 if coverage below threshold |
+| `--no-color` | Disable colored output |
 
-### `compile<T>(zodSchema): CompiledSchema<T>`
+## What Gets Compiled
 
-Wraps a Zod schema for AOT compilation. In development, it falls back to Zod's built-in validation. After build (via CLI or unplugin), it uses the generated optimized validator.
+### Fully Compiled (3-64x faster)
 
-```typescript
-import { z } from "zod";
-import { compile } from "zod-aot";
+`string`, `number`, `bigint`, `boolean`, `null`, `undefined`, `any`, `unknown`, `literal`, `enum`, `date`, `object`, `array`, `tuple`, `record`, `set`, `map`, `union`, `discriminatedUnion`, `intersection`, `pipe` (non-transform), `optional`, `nullable`, `readonly`, `default`, `catch`, `coerce`, `templateLiteral`, `symbol`, `void`, `nan`, `never`, `lazy` (self-recursive)
 
-const validateUser = compile(z.object({
-  name: z.string().min(3),
-  age: z.number().int().positive(),
-}));
-```
+All standard Zod checks are supported: `min`, `max`, `length`, `email`, `url`, `uuid`, `regex`, `int`, `positive`, `negative`, `multipleOf`, `int32`, `uint32`, `float32`, `float64`, `includes`, `startsWith`, `endsWith`, and more.
 
-### `CompiledSchema<T>`
+### Falls Back to Zod (Still Works, Not Faster)
 
-The interface returned by `compile()`:
+These types contain JavaScript closures that cannot be compiled to static code:
 
-```typescript
-interface CompiledSchema<T> {
-  parse(input: unknown): T;           // throws on failure
-  safeParse(input: unknown): SafeParseResult<T>;  // { success, data/error }
-  schema: unknown;                    // reference to original Zod schema
-}
-```
+| Type | Why | Alternative |
+|---|---|---|
+| `transform` | Runtime data transformation function | Use `z.pipe()` when possible |
+| `refine` / `superRefine` | Custom validation closures | Use built-in checks when possible |
+| `custom` | Arbitrary validation logic | — |
+| `preprocess` | Input preprocessing function | Use `z.coerce` when possible |
+| `lazy` (non-recursive) | Cannot resolve inner type | Use self-referencing lazy for recursion |
 
-## Supported Types
+**Partial fallback:** If an object has 10 properties and 1 uses `transform`, the other 9 are still compiled. Only the `transform` property falls back to Zod.
 
-| Type | Supported Checks |
-|---|---|
-| `string` | `min`, `max`, `length`, `email`, `url`, `uuid`, `regex`, `includes`, `startsWith`, `endsWith` |
-| `number` | `int`, `positive`, `negative`, `nonnegative`, `nonpositive`, `min`, `max`, `multipleOf`, `int32`, `uint32`, `float32`, `float64` |
-| `bigint` | `min`, `max`, `positive`, `negative`, `nonnegative`, `nonpositive`, `multipleOf` |
-| `boolean` | — |
-| `null` | — |
-| `undefined` | — |
-| `any` | — (always passes) |
-| `unknown` | — (always passes) |
-| `literal` | single value, multi-value |
-| `enum` | string enum values |
-| `date` | `min`, `max` (timestamp comparison) |
-| `object` | nested objects, mixed property types |
-| `array` | `min`, `max`, `length`, element validation |
-| `tuple` | per-element types, optional rest element |
-| `record` | key and value type validation |
-| `set` | `min`, `max` (size), element validation |
-| `map` | key and value type validation |
-| `union` | sequential trial of all options |
-| `discriminatedUnion` | O(1) `switch` dispatch on discriminator field |
-| `intersection` | validates both left and right schemas |
-| `pipe` (non-transform) | sequential in→out validation |
-| `optional` | wraps any supported type |
-| `nullable` | wraps any supported type |
-| `readonly` | validates inner type (TS-only concept) |
-| `default` | replaces `undefined` with default value, then validates inner |
-| `symbol` | — (typeof check) |
-| `void` | — (accepts `undefined`) |
-| `nan` | — (Number.isNaN check) |
-| `never` | — (always fails) |
-| `lazy` (self-recursive) | cycle detection → self-recursive codegen |
-
-### Automatic Fallback to Zod
-
-These schema types contain JavaScript closures or runtime-dependent logic that cannot be compiled to static code. They are detected during extraction and produce a `FallbackIR`:
-
-- `transform` — runtime data transformation
-- `refine` / `superRefine` — custom validation with closures
-- `custom` — arbitrary validation logic
-- `preprocess` — input preprocessing
-- `lazy` (non-recursive) — deferred schema resolution where inner type cannot be resolved
-
-#### Partial Fallback
-
-When a schema contains a mix of compilable and non-compilable parts (e.g., an object where some properties use `transform`/`refine`), zod-aot compiles the optimizable parts and delegates only the non-compilable properties to Zod at runtime.
-
-> **Note:** If a schema heavily relies on `transform`, `refine`, or other non-compilable features, the performance benefit from partial fallback will be minimal — most of the validation work is still delegated to Zod. Partial fallback is most effective when only a small portion of the schema uses these features.
-
-## Development
+**Tip:** Run `npx zod-aot check` to see exactly which parts of your schemas are compiled and which fall back.
 
-```bash
-# Install dependencies
-pnpm install
+## Benchmarks
 
-# Run tests
-pnpm test
+5-way comparison: **Zod v3** vs **Zod v4** vs **Zod AOT** vs **[Typia](https://typia.io/)** vs **[AJV](https://ajv.js.org/)**
 
-# Run benchmarks (zod v3 vs zod v4 vs zod-aot vs ajv vs typia)
-pnpm bench
+| Scenario | Zod v3 | Zod v4 | **Zod AOT** | Typia | AJV | vs Zod v4 |
+|---|---|---|---|---|---|---|
+| simple string | 8.7M | 10.0M | **11.0M** | 11.0M | 11.1M | 1.1x |
+| string (min/max) | 8.3M | 6.0M | **11.1M** | 11.3M | 9.5M | 1.8x |
+| number (int+positive) | 8.2M | 5.8M | **10.9M** | 10.7M | 10.9M | 1.9x |
+| enum | 8.0M | 9.5M | **10.6M** | 10.6M | 10.5M | 1.1x |
+| bigint (min/max) | 8.0M | 6.0M | **10.9M** | — | — | 1.8x |
+| tuple [string, int, bool] | 4.0M | 4.4M | **10.5M** | 10.8M | 10.5M | 2.4x |
+| record\<string, number\> | 2.3M | 1.9M | **5.4M** | 7.5M | 9.4M | 2.8x |
+| set\<string\> (5 items) | 2.7M | 1.6M | **9.8M** | — | — | 6.3x |
+| set\<string\> (20 items) | 1.0M | 475K | **7.7M** | — | — | **16x** |
+| map\<string, number\> (5 entries) | 1.5M | 946K | **8.5M** | — | — | 9.0x |
+| map\<string, number\> (20 entries) | 490K | 238K | **5.2M** | — | — | **22x** |
+| pipe (non-transform) | 6.3M | 3.8M | **10.8M** | — | — | 2.8x |
+| discriminatedUnion (3 variants) | 2.3M | 2.9M | **9.8M** | 10.4M | 5.6M | 3.4x |
+| medium object (valid) | 1.3M | 1.7M | **5.4M** | 7.3M | 5.0M | 3.1x |
+| medium object (invalid) | 351K | 65K | **471K** | 2.1M | 5.6M | 7.3x |
+| large object (10 items) | 82K | 111K | **4.0M** | 4.1M | 834K | **36x** |
+| large object (100 items) | 9.0K | 11.6K | **676K** | 808K | 89K | **58x** |
+| recursive tree (7 nodes) | 424K | 1.5M | **6.4M** | 8.1M | 3.1M | 4.1x |
+| recursive tree (121 nodes) | 24K | 101K | **741K** | 1.4M | 250K | 7.4x |
+| event log (combined) | 260K | 479K | **4.5M** | — | — | 9.4x |
+| partial fallback obj (transform) | 817K | 1.4M | **3.3M** | — | — | 2.3x |
+| partial fallback arr 10 (transform) | 88K | 139K | **841K** | — | — | 6.1x |
+| partial fallback arr 50 (transform) | 18K | 28K | **175K** | — | — | 6.3x |
 
-# Lint (Biome)
-pnpm lint
+*ops/s, higher is better. "—" = not supported by the library. Measured with `vitest bench` on Apple M-series.*
 
-# Type check
-pnpm -r typecheck
+Performance scales with schema complexity. Nested objects and arrays see the biggest gains because zod-aot eliminates per-node traversal overhead. `discriminatedUnion` uses O(1) `switch` dispatch instead of Zod's sequential trial. Partial fallback schemas (containing `transform`/`refine`) still show 2-6x speedups.
 
-# Build
-pnpm -r build
+```bash
+pnpm bench   # run locally
 ```
 
-### Project Structure
+### Performance Architecture
 
-```
-zod-aot/
-├── packages/zod-aot/        # Main npm package
-│   ├── src/
-│   │   ├── index.ts          # Public API exports (zod-aot)
-│   │   ├── discovery.ts      # Schema discovery (shared by CLI & unplugin)
-│   │   ├── loader.ts         # Runtime-aware file loader
-│   │   ├── core/             # Pure logic (no CLI/unplugin deps)
-│   │   │   ├── types.ts      # SchemaIR, CompiledSchema, CheckIR
-│   │   │   ├── compile.ts    # compile() marker + isCompiledSchema()
-│   │   │   ├── runtime.ts    # createFallback (dev-time)
-│   │   │   ├── extract/      # _zod.def → SchemaIR (extractors per type)
-│   │   │   └── codegen/      # SchemaIR → optimized JS
-│   │   ├── cli/              # CLI commands (generate, check, watch)
-│   │   └── unplugin/         # Build plugin (Vite/webpack/esbuild/Rollup/Rolldown/rspack/Bun)
-│   └── tests/
-├── benchmarks/               # vitest bench (zod v3 vs v4 vs zod-aot vs ajv vs typia)
-└── .github/workflows/        # CI + release automation
-```
+For eligible schemas, zod-aot generates a **two-phase validator**:
 
-## Contributing
+1. **Fast Path** — A single `&&` expression chain that validates the entire input with zero allocations. Valid input returns immediately.
+2. **Slow Path** — Error-collecting validation that only runs when the Fast Path fails.
 
-Contributions are welcome! Please ensure your changes pass all checks before submitting a PR:
+Additional optimizations: check ordering (cheap checks first), pre-compiled regex, Set-based enum lookups, small enum inlining (`===` for 1-3 values).
 
-```bash
-pnpm lint && pnpm -r typecheck && pnpm test
-```
+Run `npx zod-aot check --json` to see which schemas qualify for Fast Path.
 
 ## License