zod-aot 0.0.4 → 0.0.5

package/README.md

@@ -60,11 +60,13 @@ npm install zod@^4
 
 ## Quick Start
 
+### 1. Define schemas with `compile()`
+
 ```typescript
+// src/schemas.ts
 import { z } from "zod";
-import { extractSchema, generateValidator } from "zod-aot";
+import { compile } from "zod-aot";
 
-// 1. Define your Zod schema as usual
 const UserSchema = z.object({
   name: z.string().min(3),
   age: z.number().int().positive(),
@@ -72,70 +74,115 @@ const UserSchema = z.object({
   role: z.enum(["admin", "user"]),
 });
 
-// 2. Extract the schema into an intermediate representation (IR)
-const ir = extractSchema(UserSchema);
+// compile() falls back to Zod in dev, uses generated functions after build
+export const validateUser = compile(UserSchema);
+```
 
-// 3. Generate an optimized validator function
-const { code, functionName } = generateValidator(ir, "validateUser");
+### 2. Use the compiled validator
 
-// 4. The generated code is a self-contained JS function
-//    In production, write this to a file at build time
-console.log(code);         // preamble: Set/RegExp declarations
-console.log(functionName); // function safeParse_validateUser(input) { ... }
+```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 isUser = validateUser.is(data);           // type guard (boolean)
 ```
 
-### Using the Generated Code
+### 3. Generate optimized code
 
-The generated code can be evaluated at build time and written to a file:
+Choose one of these approaches:
+
+**Option A: Build plugin (Vite / webpack / esbuild / Rollup)**
 
 ```typescript
-// Build script example
-import { writeFileSync } from "node:fs";
-import { extractSchema, generateValidator } from "zod-aot";
+// vite.config.ts
+import zodAot from "zod-aot/vite";
 
-const ir = extractSchema(UserSchema);
-const { code, functionName } = generateValidator(ir, "validateUser");
+export default defineConfig({
+  plugins: [zodAot()],
+});
+```
+
+Also available: `zod-aot/webpack`, `zod-aot/esbuild`, `zod-aot/rollup`
+
+**Option B: CLI**
+
+```bash
+# Generate optimized validators
+npx zod-aot generate src/schemas.ts -o src/schemas.compiled.ts
 
-// Write to a .js file
-writeFileSync(
-  "src/validators/user.generated.js",
-  `${code}\nexport const validateUser = ${functionName}`,
-);
+# Generate from a directory
+npx zod-aot generate src/ -o src/compiled/
+
+# Check if schemas are compilable (without generating)
+npx zod-aot check src/schemas.ts
 ```
 
-Then import and use in your application:
+## Build Plugin (unplugin)
+
+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.
 
 ```typescript
-import { validateUser } from "./validators/user.generated.js";
+// vite.config.ts
+import zodAot from "zod-aot/vite";
+export default defineConfig({ plugins: [zodAot()] });
 
-const result = validateUser(data);
-// { success: true, data: { name: "Alice", ... } }
-// or { success: false, error: { issues: [...] } }
+// webpack.config.js
+const zodAot = require("zod-aot/webpack");
+module.exports = { plugins: [zodAot()] };
 ```
 
-### Runtime Fallback (Development)
+### Options
 
-During development — before running the build step — use `createFallback` to wrap Zod schemas with the same interface:
+```typescript
+zodAot({
+  include: ["src/schemas"],   // only process files matching these substrings
+  exclude: ["test", "mock"],  // skip files matching these substrings
+})
+```
+
+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
+
+## Low-Level API
+
+For custom build scripts or advanced use cases, you can use the extractor and code generator directly:
 
 ```typescript
 import { z } from "zod";
-import { createFallback } from "zod-aot";
+import { extractSchema, generateValidator } from "zod-aot";
 
 const UserSchema = z.object({
   name: z.string().min(3),
   age: z.number().int().positive(),
 });
 
-// Delegates to Zod at runtime — same interface as compiled validators
-const validator = createFallback(UserSchema);
+// Extract schema into intermediate representation (IR)
+const ir = extractSchema(UserSchema);
+
+// Generate optimized JavaScript validation code
+const { code, functionName } = generateValidator(ir, "validateUser");
+
+// Execute the generated code
+const safeParse = new Function(`${code}\nreturn ${functionName};`)();
+const result = safeParse({ name: "Alice", age: 30 });
+```
+
+### `createFallback(zodSchema)`
+
+Wraps a Zod schema to provide the `CompiledSchema` interface, delegating to Zod at runtime. Useful for development or unsupported schema types:
 
-validator.parse(data);      // throws ZodError on failure
+```typescript
+import { createFallback } from "zod-aot";
+
+const validator = createFallback(UserSchema);
+validator.parse(data);      // throws on failure
 validator.safeParse(data);  // { success, data/error }
 validator.is(data);         // type guard (boolean)
 ```
 
-This lets you write code against the `CompiledSchema` interface and swap in the generated code at build time without changing any call sites.
-
 ## How It Works
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod-aot",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Compile Zod schemas into zero-overhead validation functions at build time",
   "type": "module",
   "keywords": [
@@ -22,7 +22,8 @@
     "zod-aot": "./dist/cli/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "LICENSE"
   ],
   "imports": {
     "#src/*": "./src/*"