feat(server): Add comprehensive Zod v4 integration

CLAUDE.md

@@ -0,0 +1,70 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Development
+- `npm install` - Install all dependencies
+- `npm run dev` - Start full development environment (backend + frontend + helpers watch)
+- `npm run build` - Build the convex-helpers package
+- `npm test` - Run all tests
+- `npm run test:watch` - Run tests in watch mode
+- `npm run lint` - Run TypeScript type checking and Prettier format check
+- `npm run format` - Auto-format code with Prettier
+
+### Testing
+- `npm test -- path/to/test.ts` - Run a specific test file
+- `npm run test:coverage` - Run tests with coverage report
+- `npm run testFunctions` - Run Convex function tests against local backend
+
+### Publishing
+- `npm run alpha` - Publish alpha release
+- `npm run release` - Publish stable release
+
+## Architecture
+
+This is a TypeScript monorepo providing helper utilities for Convex applications:
+
+- **Main Package**: `/packages/convex-helpers/` - Published npm package
+  - `/server/` - Server-side utilities (custom functions, relationships, migrations, etc.)
+  - `/react/` - React hooks and providers
+  - `/cli/` - CLI tools for TypeScript/OpenAPI generation
+
+- **Example App**: Root directory contains example Convex backend and React frontend
+  - `/convex/` - Example Convex functions
+  - `/src/` - Example React application
+
+## Key Patterns
+
+### Custom Functions
+Wrap Convex primitives with authentication and context injection:
+```typescript
+import { customQuery } from "convex-helpers/server/customFunctions";
+```
+
+### Zod Validation
+Use `zod` for runtime validation with type inference:
+```typescript
+import { zodToConvex } from "convex-helpers/server/zod";
+```
+
+### Testing
+Use `ConvexTestingHelper` for testing Convex functions:
+```typescript
+import { ConvexTestingHelper } from "convex-helpers/testing";
+```
+
+### Development Workflow
+1. The package is symlinked for live development
+2. Changes to helpers trigger automatic rebuilds via chokidar
+3. TypeScript strict mode is enforced
+4. All code must pass Prettier formatting
+
+## Important Notes
+
+- This library extends Convex functionality - always check if Convex has native support first
+- Many utilities have optional peer dependencies (React, Zod, Hono)
+- Server utilities are framework-agnostic and work with any client
+- Tests run in different environments: `edge-runtime` for server, `jsdom` for React
+- The example app demonstrates usage patterns for most utilities

packages/convex-helpers/README.md

@@ -353,7 +353,9 @@ features for validating arguments, this is for you!
 
 See the [Stack post on Zod validation](https://stack.convex.dev/typescript-zod-function-validation) to see how to validate your Convex functions using the [zod](https://www.npmjs.com/package/zod) library.
 
-Example:
+### Zod v3 (Stable)
+
+The default export from `convex-helpers/server/zod` uses Zod v3:
 
 ```js
 import { z } from "zod";
@@ -391,6 +393,36 @@ export const myComplexQuery = zodQuery({
 });
 ```
 
+### Zod v4 (Beta)
+
+For projects that want to leverage Zod v4's performance improvements (14x faster string parsing, 7x faster array parsing), we provide a v4-optimized implementation:
+
+```js
+import { z } from "zod";
+import { zCustomQuery, zid } from "convex-helpers/server/zodV4";
+import { NoOp } from "convex-helpers/server/customFunctions";
+
+// Same API as v3, but with v4 performance benefits
+const zodQuery = zCustomQuery(query, NoOp);
+
+export const myQuery = zodQuery({
+  args: {
+    userId: zid("users"),
+    email: z.string().email(),
+    // All the same features work with v4
+  },
+  handler: async (ctx, args) => {
+    // Benefit from v4's performance improvements
+  },
+});
+```
+
+Key benefits of v4:
+- 14x faster string parsing
+- 7x faster array parsing
+- 100x reduction in TypeScript type instantiations
+- Same API as v3 for easy migration
+
 ## Hono for advanced HTTP endpoint definitions
 
 [Hono](https://hono.dev/) is an optimized web framework you can use to define

packages/convex-helpers/package.json

@@ -115,6 +115,14 @@
       "types": "./server/zod.d.ts",
       "default": "./server/zod.js"
     },
+    "./server/zodV4.example": {
+      "types": "./server/zodV4.example.d.ts",
+      "default": "./server/zodV4.example.js"
+    },
+    "./server/zodV4": {
+      "types": "./server/zodV4.d.ts",
+      "default": "./server/zodV4.js"
+    },
     "./react/*": {
       "types": "./react/*.d.ts",
       "default": "./react/*.js"