zodvex 0.2.1 → 0.2.3

package/README.md

@@ -4,271 +4,316 @@
 
 Type-safe Convex functions with Zod schemas. Preserve Convex's optional/nullable semantics while leveraging Zod's powerful validation.
 
-> Heavily inspired by [convex-helpers](https://github.com/get-convex/convex-helpers). Built on top of their excellent utilities.
+> Built on top of [convex-helpers](https://github.com/get-convex/convex-helpers)
 
-## 📦 Installation
+## Table of Contents
 
-```bash
-npm install zodvex zod convex convex-helpers
-```
-
-```bash
-pnpm add zodvex zod convex convex-helpers
-```
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Defining Schemas](#defining-schemas)
+- [Table Definitions](#table-definitions)
+- [Building Your Schema](#building-your-schema)
+- [Defining Functions](#defining-functions)
+- [Working with Subsets](#working-with-subsets)
+- [Form Validation](#form-validation)
+- [API Reference](#api-reference)
+- [Advanced Usage](#advanced-usage)
 
-```bash
-yarn add zodvex zod convex convex-helpers
-```
+## Installation
 
 ```bash
-bun add zodvex zod convex convex-helpers
+npm install zodvex zod@^4.1.0 convex convex-helpers
 ```
 
 **Peer dependencies:**
 
-- `zod` (v4)
-- `convex` (>= 1.27)
-- `convex-helpers` (>= 0.1.101-alpha.1)
+- `zod` (^4.1.0 or later)
+- `convex` (>= 1.27.0)
+- `convex-helpers` (>= 0.1.104)
+
+## Quick Start
 
-## 🚀 Quick Start
+### 1. Set up your builders
 
-### 1. Define a Zod schema and create type-safe Convex functions
+Create a `convex/util.ts` file with reusable builders ([copy full example](./examples/queries.ts)):
+
+```ts
+// convex/util.ts
+import { query, mutation, action } from './_generated/server'
+import { zQueryBuilder, zMutationBuilder, zActionBuilder } from 'zodvex'
+
+export const zq = zQueryBuilder(query)
+export const zm = zMutationBuilder(mutation)
+export const za = zActionBuilder(action)
+```
+
+### 2. Use builders to create type-safe functions
 
 ```ts
 // convex/users.ts
-import { z } from "zod";
-import { query, mutation } from "./_generated/server";
-import { zQuery, zMutation } from "zodvex";
+import { z } from 'zod'
+import { zid } from 'zodvex'
+import { zq, zm } from './util'
+import { Users } from './schemas/users'
+
+export const getUser = zq({
+  args: { id: zid('users') },
+  returns: Users.zDoc.nullable(),
+  handler: async (ctx, { id }) => {
+    return await ctx.db.get(id)
+  }
+})
+
+export const createUser = zm({
+  args: Users.shape,
+  returns: zid('users'),
+  handler: async (ctx, user) => {
+    // user is fully typed and validated
+    return await ctx.db.insert('users', user)
+  }
+})
+```
+
+## Defining Schemas
 
-// Define your schema
-const UserInput = z.object({
-  name: z.string().min(1),
+Define your Zod schemas as plain objects for best type inference:
+
+```ts
+import { z } from 'zod'
+import { zid } from 'zodvex'
+
+// Plain object shape - recommended
+export const userShape = {
+  name: z.string(),
   email: z.string().email(),
   age: z.number().optional(),
-});
+  avatarUrl: z.string().url().nullable(),
+  teamId: zid('teams').optional() // Convex ID reference
+}
 
-// Create type-safe queries
-export const getUser = zQuery(
-  query,
-  { id: z.string() },
-  async (ctx, { id }) => {
-    return await ctx.db.get(id);
-  },
-);
-
-// Create type-safe mutations
-export const createUser = zMutation(mutation, UserInput, async (ctx, user) => {
-  // `user` is fully typed and validated!
-  return await ctx.db.insert("users", user);
-});
+// Can also use z.object() if preferred
+export const User = z.object(userShape)
 ```
 
-### 2. Use with Convex schemas
+## Table Definitions
+
+Use `zodTable` as a drop-in replacement for Convex's `Table`:
 
 ```ts
 // convex/schema.ts
-import { defineSchema } from "convex/server";
-import { z } from "zod";
-import { zodTable } from "zodvex";
+import { z } from 'zod'
+import { zodTable, zid } from 'zodvex'
 
-// Define a table from a plain object shape
-const usersShape = {
+export const Users = zodTable('users', {
   name: z.string(),
   email: z.string().email(),
   age: z.number().optional(), // → v.optional(v.float64())
   deletedAt: z.date().nullable(), // → v.union(v.float64(), v.null())
-};
-
-export const Users = zodTable("users", usersShape);
-
-// Use in your Convex schema
-export default defineSchema({
-  users: Users.table.index("by_email", ["email"]).searchIndex("search_name", {
-    searchField: "name",
-  }),
-});
+  teamId: zid('teams').optional()
+})
+
+// Access the underlying table
+Users.table // Convex table definition
+Users.shape // Original Zod shape
+Users.zDoc // Zod schema with _id and _creationTime
+Users.docArray // z.array(zDoc) for return types
 ```
 
-## ✨ Features
+## Building Your Schema
 
-### Why zodvex?
+Use `zodTable().table` in your Convex schema:
 
-- **Correct optional/nullable semantics**: Preserves Convex's distinction between optional and nullable fields
-  - `.optional()` → `v.optional(T)` (field can be omitted)
-  - `.nullable()` → `v.union(T, v.null())` (field required but can be null)
-  - `.optional().nullable()` → `v.optional(v.union(T, v.null()))` (can be omitted or null)
-- **Type-safe function wrappers**: Full TypeScript inference for inputs and outputs
-- **Date handling**: Automatic conversion between JavaScript `Date` objects and Convex timestamps
-- **CRUD scaffolding**: Generate complete CRUD operations from a single schema
+```ts
+// convex/schema.ts
+import { defineSchema } from 'convex/server'
+import { Users } from './tables/users'
+import { Teams } from './tables/teams'
 
-### Supported Types
+export default defineSchema({
+  users: Users.table
+    .index('by_email', ['email'])
+    .index('by_team', ['teamId'])
+    .searchIndex('search_name', { searchField: 'name' }),
 
-This library intentionally supports only Zod types that map cleanly to Convex validators. Anything outside this list is unsupported (or best-effort with caveats).
+  teams: Teams.table.index('by_created', ['_creationTime'])
+})
+```
 
-- Primitives: `z.string()`, `z.number()` → `v.float64()`, `z.boolean()`, `z.null()`
-- Date: `z.date()` → `v.float64()` (timestamp), encoded/decoded automatically
-- Literals: `z.literal(x)` → `v.literal(x)`
-- Enums: `z.enum([...])` → `v.union(v.literal(...))`
-- Arrays: `z.array(T)` → `v.array(T')`
-- Objects: `z.object({...})` → `v.object({...})`
-- Records: `z.record(T)` or `z.record(z.string(), T)` → `v.record(v.string(), T')` (string keys only)
-- Unions: `z.union([...])` (members must be supported types)
-- Optional/nullable wrappers: `.optional()` → `v.optional(T')`, `.nullable()` → `v.union(T', v.null())`
-- Convex IDs: `zid('table')` → `v.id('table')`
+## Defining Functions
 
-Unsupported or partial (explicitly out-of-scope):
+Use your builders from `util.ts` to create type-safe functions:
 
-- Tuples (fixed-length) — Convex has no fixed-length tuple validator; mapping would be lossy
-- Intersections — combining object shapes widens overlapping fields; not equivalent to true intersection
-- Transforms/effects/pipelines — not used for validator mapping; if you use them, conversions happen at runtime only
-- Lazy, function, promise, set, map, symbol, branded/readonly, NaN/catch — unsupported
+```ts
+import { z } from 'zod'
+import { zid } from 'zodvex'
+import { zq, zm } from './util'
+import { Users } from './tables/users'
 
-Note: `z.bigint()` → `v.int64()` is recognized for validator mapping but currently has no special runtime encode/decode; prefer numbers where possible.
+// Query with return type validation
+export const listUsers = zq({
+  args: {},
+  returns: Users.docArray,
+  handler: async (ctx) => {
+    return await ctx.db.query('users').collect()
+  }
+})
 
-## 📚 API Reference
+// Mutation with Convex ID
+export const deleteUser = zm({
+  args: { id: zid('users') },
+  returns: z.null(),
+  handler: async (ctx, { id }) => {
+    await ctx.db.delete(id)
+    return null
+  }
+})
+
+// Using the full schema
+export const createUser = zm({
+  args: Users.shape,
+  returns: zid('users'),
+  handler: async (ctx, user) => {
+    return await ctx.db.insert('users', user)
+  }
+})
+```
 
-### Mapping Helpers
+## Working with Subsets
 
-Convert Zod schemas to Convex validators:
+Pick a subset of fields for focused operations:
 
 ```ts
-import { z } from "zod";
-import { zodToConvex, zodToConvexFields, pickShape, safePick } from "zodvex";
+import { z } from 'zod'
+import { zid } from 'zodvex'
+import { zm } from './util'
+import { Users, zUsers } from './tables/users'
+
+// Use Zod's .pick() to select fields
+const UpdateFields = zUsers.pick({
+  firstName: true,
+  lastName: true,
+  email: true
+})
+
+export const updateUserProfile = zm({
+  args: {
+    id: zid('users'),
+    ...UpdateFields.shape
+  },
+  handler: async (ctx, { id, ...fields }) => {
+    await ctx.db.patch(id, fields)
+  }
+})
 
-// Convert a single Zod type to a Convex validator
-const validator = zodToConvex(z.string().optional());
-// → v.optional(v.string())
+// Or inline for simple cases
+export const updateUserName = zm({
+  args: {
+    id: zid('users'),
+    name: z.string()
+  },
+  handler: async (ctx, { id, name }) => {
+    await ctx.db.patch(id, { name })
+  }
+})
+```
 
-// Convert a Zod object shape to Convex field validators
-const fields = zodToConvexFields({
-  name: z.string(),
-  age: z.number().nullable(),
-});
-// → { name: v.string(), age: v.union(v.float64(), v.null()) }
+## Form Validation
 
-// Safe picking from large schemas
-// IMPORTANT: Avoid Zod's .pick() on large schemas (30+ fields) as it can cause
-// TypeScript instantiation depth errors. Use pickShape/safePick instead.
+Use your schemas with form libraries like react-hook-form:
 
-const User = z.object({
-  id: z.string(),
-  email: z.string().email(),
-  firstName: z.string().optional(),
-  lastName: z.string().optional(),
-  createdAt: z.date().nullable(),
-});
-
-// ❌ DON'T use Zod's .pick() on large schemas (type instantiation issues)
-// const Clerk = User.pick({ email: true, firstName: true, lastName: true });
-
-// ✅ DO use pickShape to extract a plain object shape
-const clerkShape = pickShape(User, ["email", "firstName", "lastName"]);
-// Use directly in wrappers or build a new z.object()
-const Clerk = z.object(clerkShape);
-
-// Alternative: safePick builds the z.object() for you
-const ClerkAlt = safePick(User, { email: true, firstName: true, lastName: true });
-// Both Clerk and ClerkAlt are equivalent - use whichever is more readable
-```
+```tsx
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { z } from 'zod'
+import { useMutation } from 'convex/react'
+import { api } from '../convex/_generated/api'
+import { Users } from '../convex/tables/users'
 
-### Function Wrappers
+// Create form schema from your table schema
+const CreateUserForm = z.object(Users.shape)
+type CreateUserForm = z.infer<typeof CreateUserForm>
 
-Type-safe wrappers for Convex functions:
+function UserForm() {
+  const createUser = useMutation(api.users.createUser)
 
-```ts
-import { z } from "zod";
-import { query, mutation, action } from "./_generated/server";
-import { zQuery, zMutation, zAction } from "zodvex";
+  const {
+    register,
+    handleSubmit,
+    formState: { errors }
+  } = useForm<CreateUserForm>({
+    resolver: zodResolver(CreateUserForm)
+  })
 
-// Query with validated input and optional return validation
-export const getById = zQuery(
-  query,
-  { id: z.string() },
-  async (ctx, { id }) => ctx.db.get(id),
-  {
-    returns: z.object({
-      name: z.string(),
-      createdAt: z.date(),
-    }),
-  },
-);
+  const onSubmit = async (data: CreateUserForm) => {
+    await createUser(data)
+  }
 
-// Mutation with Zod object
-export const updateUser = zMutation(
-  mutation,
-  z.object({
-    id: z.string(),
-    name: z.string().min(1),
-  }),
-  async (ctx, { id, name }) => ctx.db.patch(id, { name }),
-);
-
-// Action with single value (normalizes to { value })
-export const sendEmail = zAction(
-  action,
-  z.string().email(),
-  async (ctx, { value: email }) => {
-    // Send email to the address
-  },
-);
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('name')} />
+      {errors.name && <span>{errors.name.message}</span>}
 
-// Internal functions also supported
-import { zInternalQuery, zInternalMutation, zInternalAction } from "zodvex";
+      <input {...register('email')} />
+      {errors.email && <span>{errors.email.message}</span>}
 
-// Handler return typing
-// When `returns` is provided, your handler must return z.input<typeof returns>
-// (domain values like Date). zodvex validates and encodes to Convex Values for you.
+      <button type="submit">Create User</button>
+    </form>
+  )
+}
 ```
 
-#### Return Typing + Helpers
+## API Reference
+
+### Builders
 
-Handlers should return domain values shaped by your `returns` schema. zodvex validates and encodes them to Convex Values for you. For common patterns:
+**Basic builders** - Create type-safe functions without auth:
 
 ```ts
-import { z } from "zod";
-import { zQuery, zodTable, returnsAs } from "zodvex";
-import { query } from "./_generated/server";
+zQueryBuilder(query) // Creates query builder
+zMutationBuilder(mutation) // Creates mutation builder
+zActionBuilder(action) // Creates action builder
+```
 
-// Table with doc helpers
-export const Users = zodTable("users", {
-  name: z.string(),
-  createdAt: z.date()
-});
+**Custom builders** - Add auth or custom context:
 
-// 1) Return full docs, strongly typed
-export const listUsers = zQuery(
-  query,
-  {},
-  async (ctx) => {
-    const rows = await ctx.db.query("users").collect();
-    // No cast needed — handler returns domain values; wrapper encodes to Convex Values
-    return rows;
-  },
-  { returns: Users.docArray }
-);
+```ts
+import { type QueryCtx } from './_generated/server'
+import { customCtx } from 'zodvex'
 
-// 2) Return a custom shape (with Dates)
-export const createdBounds = zQuery(
+const authQuery = zCustomQueryBuilder(
   query,
-  {},
-  async (ctx) => {
-    const first = await ctx.db.query("users").order("asc").first();
-    const last = await ctx.db.query("users").order("desc").first();
-    return { first: first?.createdAt ?? null, last: last?.createdAt ?? null };
-  },
-  { returns: z.object({ first: z.date().nullable(), last: z.date().nullable() }) }
-);
+  customCtx(async (ctx: QueryCtx) => {
+    const user = await getUserOrThrow(ctx)
+    return { user }
+  })
+)
 
-// 3) In tricky inference spots, use a typed identity
-export const listUsersOk = zQuery(
-  query,
-  {},
-  async (ctx) => {
-    const rows = await ctx.db.query("users").collect();
-    return returnsAs<typeof Users.docArray>()(rows);
-  },
-  { returns: Users.docArray }
-);
+// Use with automatic context injection
+export const getMyProfile = authQuery({
+  args: {},
+  returns: Users.zDoc.nullable(),
+  handler: async (ctx) => {
+    if (!ctx.user) return null
+    return ctx.db.get(ctx.user._id)
+  }
+})
+```
+
+### Mapping Helpers
+
+```ts
+import { zodToConvex, zodToConvexFields } from 'zodvex'
+
+// Convert single Zod type to Convex validator
+const validator = zodToConvex(z.string().optional())
+// → v.optional(v.string())
+
+// Convert object shape to Convex field validators
+const fields = zodToConvexFields({
+  name: z.string(),
+  age: z.number().nullable()
+})
+// → { name: v.string(), age: v.union(v.float64(), v.null()) }
 ```
 
 ### Codecs
@@ -276,272 +321,204 @@ export const listUsersOk = zQuery(
 Convert between Zod-shaped data and Convex-safe JSON:
 
 ```ts
-import { convexCodec } from "zodvex";
-import { z } from "zod";
+import { convexCodec } from 'zodvex'
 
 const UserSchema = z.object({
   name: z.string(),
-  birthday: z.date().optional(),
-  metadata: z.record(z.string()),
-});
-
-const codec = convexCodec(UserSchema);
+  birthday: z.date().optional()
+})
 
-// Get Convex validators for table definition
-const validators = codec.toConvexSchema();
+const codec = convexCodec(UserSchema)
 
-// Encode: Zod data → Convex JSON (Date → timestamp, omit undefined)
+// Encode: Date → timestamp, omit undefined
 const encoded = codec.encode({
-  name: "Alice",
-  birthday: new Date("1990-01-01"),
-  metadata: { role: "admin" },
-});
-// → { name: 'Alice', birthday: 631152000000, metadata: { role: 'admin' } }
-
-// Decode: Convex JSON → Zod data (timestamp → Date)
-const decoded = codec.decode(encoded);
-// → { name: 'Alice', birthday: Date('1990-01-01'), metadata: { role: 'admin' } }
-
-// Create sub-codecs (ZodObject only)
-const nameCodec = codec.pick({ name: true });
+  name: 'Alice',
+  birthday: new Date('1990-01-01')
+})
+// → { name: 'Alice', birthday: 631152000000 }
+
+// Decode: timestamp → Date
+const decoded = codec.decode(encoded)
+// → { name: 'Alice', birthday: Date('1990-01-01') }
 ```
 
-### Table Helpers
-
-Define Convex tables from Zod schemas. `zodTable` accepts a **plain object shape** for best type inference:
-
-```ts
-import { z } from "zod";
-import { zodTable, zid } from "zodvex";
-import { defineSchema } from "convex/server";
-
-// Define your schema as a plain object
-const postShape = {
-  title: z.string(),
-  content: z.string(),
-  authorId: zid("users"), // Convex ID reference
-  published: z.boolean().default(false),
-  tags: z.array(z.string()).optional(),
-};
-
-// Create table helper - pass the plain object shape
-export const Posts = zodTable("posts", postShape);
-
-// Access properties
-Posts.table;    // → Table definition for defineSchema
-Posts.shape;    // → Original plain object shape
-Posts.zDoc;     // → ZodObject with _id and _creationTime system fields
-Posts.docArray; // → z.array(zDoc) for return type validation
-
-// Use in schema.ts
-export default defineSchema({
-  posts: Posts.table
-    .index("by_author", ["authorId"])
-    .index("by_published", ["published"]),
-});
+### Supported Types
 
-// Use docArray for return types
-export const listPosts = zQuery(
-  query,
-  {},
-  async (ctx) => ctx.db.query("posts").collect(),
-  { returns: Posts.docArray }
-);
+| Zod Type             | Convex Validator                            |
+| -------------------- | ------------------------------------------- |
+| `z.string()`         | `v.string()`                                |
+| `z.number()`         | `v.float64()`                               |
+| `z.bigint()`         | `v.int64()`                                 |
+| `z.boolean()`        | `v.boolean()`                               |
+| `z.date()`           | `v.float64()` (timestamp)                   |
+| `z.null()`           | `v.null()`                                  |
+| `z.array(T)`         | `v.array(T)`                                |
+| `z.object({...})`    | `v.object({...})`                           |
+| `z.record(T)`        | `v.record(v.string(), T)`                   |
+| `z.union([...])`     | `v.union(...)`                              |
+| `z.literal(x)`       | `v.literal(x)`                              |
+| `z.enum(['a', 'b'])` | `v.union(v.literal('a'), v.literal('b'))` ¹ |
+| `z.optional(T)`      | `v.optional(T)`                             |
+| `z.nullable(T)`      | `v.union(T, v.null())`                      |
+
+**Zod v4 Enum Type Note:**
+
+¹ Enum types in Zod v4 produce a slightly different TypeScript signature than manually created unions:
+
+```typescript
+// Manual union (precise tuple type)
+const manual = v.union(v.literal('a'), v.literal('b'))
+// Type: VUnion<"a" | "b", [VLiteral<"a", "required">, VLiteral<"b", "required">], "required", never>
+
+// From Zod enum (array type)
+const fromZod = zodToConvex(z.enum(['a', 'b']))
+// Type: VUnion<"a" | "b", Array<VLiteral<"a" | "b", "required">>, "required", never>
 ```
 
-#### Working with Large Schemas
-
-For large schemas (30+ fields), the plain object pattern is recommended:
-
-```ts
-// Define as plain object for better maintainability
-export const users = {
-  // Meta
-  tokenId: z.string(),
-  type: z.literal("member"),
-  isAdmin: z.boolean(),
-
-  // User info
-  email: z.string(),
-  firstName: z.string().optional(),
-  lastName: z.string().optional(),
-  phone: z.string().optional(),
-
-  // References
-  favoriteUsers: z.array(zid("users")).optional(),
-  activeDancerId: zid("dancers").optional(),
-  // ... 40+ more fields
-};
-
-// Create table
-export const Users = zodTable("users", users);
-
-// Extract subsets without Zod's .pick() to avoid type complexity
-const zClerkFields = z.object(pickShape(users, ["email", "firstName", "lastName", "tokenId"]));
-// Use zClerkFields in function wrappers or validators
-```
+**This difference is purely cosmetic with no functional impact:**
 
-## 🔧 Advanced Usage
+- ✅ Value types are identical (`"a" | "b"`)
+- ✅ Runtime validation is identical
+- ✅ Type safety for function arguments/returns is preserved
+- ✅ Convex uses `T[number]` which works identically for both array and tuple types
 
-### Builder Pattern for Reusable Function Creators
+This limitation exists because Zod v4 changed enum types from tuple-based to Record-based ([`ToEnum<T>`](https://github.com/colinhacks/zod/blob/v4/src/v4/core/util.ts#L83-L85)). TypeScript cannot convert a Record type to a specific tuple without knowing the keys at compile time. See [Zod v4 changelog](https://zod.dev/v4/changelog) and [enum evolution discussion](https://github.com/colinhacks/zod/discussions/2125) for more details.
 
-For projects with many functions, create reusable builders instead of repeating the base builder.
-Builders use Convex's native `{ args, handler, returns }` object syntax:
+**Convex IDs:**
 
 ```ts
-import { query, mutation } from "./_generated/server";
-import { zQueryBuilder, zMutationBuilder } from "zodvex";
+import { zid } from 'zodvex'
 
-// Create reusable builders
-export const zq = zQueryBuilder(query);
-export const zm = zMutationBuilder(mutation);
+zid('tableName') // → v.id('tableName')
+zid('tableName').optional() // → v.optional(v.id('tableName'))
+```
 
-// Use them with Convex-style object syntax
-export const getUser = zq({
-  args: { id: z.string() },
-  handler: async (ctx, { id }) => {
-    return ctx.db.get(id);
-  }
-});
+## Advanced Usage
 
-export const updateUser = zm({
-  args: { id: z.string(), name: z.string() },
-  handler: async (ctx, { id, name }) => {
-    return ctx.db.patch(id, { name });
-  }
-});
-```
+### Custom Context Builders
 
-### Custom Context with Middleware
+Create builders with injected auth, permissions, or other context:
 
-Use custom builders to inject auth, permissions, or other context into your functions.
-zodvex provides `customCtx` (re-exported from convex-helpers) for convenience:
+> **Best Practice:** Always add explicit type annotations to the `ctx` parameter in your `customCtx` functions. This improves TypeScript performance and prevents `ctx` from falling back to `any` in complex type scenarios. Import context types from `./_generated/server` (e.g., `QueryCtx`, `MutationCtx`, `ActionCtx`).
 
 ```ts
-import { query, mutation } from "./_generated/server";
-import { zCustomQueryBuilder, zCustomMutationBuilder, customCtx } from "zodvex";
+import { zCustomQueryBuilder, zCustomMutationBuilder, customCtx } from 'zodvex'
+import { type QueryCtx, type MutationCtx, query, mutation } from './_generated/server'
 
-// Create authenticated query builder
+// Add user to all queries
 export const authQuery = zCustomQueryBuilder(
   query,
-  customCtx(async (ctx) => {
-    const user = await getUserOrThrow(ctx);
-    return { user };
+  customCtx(async (ctx: QueryCtx) => {
+    const user = await getUserOrThrow(ctx)
+    return { user }
   })
-);
+)
 
-// Create authenticated mutation builder
+// Add user + permissions to mutations
 export const authMutation = zCustomMutationBuilder(
   mutation,
-  customCtx(async (ctx) => {
-    const user = await getUserOrThrow(ctx);
-    return { user };
+  customCtx(async (ctx: MutationCtx) => {
+    const user = await getUserOrThrow(ctx)
+    const permissions = await getPermissions(ctx, user)
+    return { user, permissions }
   })
-);
-
-// Use them with automatic type-safe context
-export const getProfile = authQuery({
-  args: {},
-  handler: async (ctx) => {
-    // ctx.user is automatically available and typed!
-    return ctx.db.query("users").filter(q => q.eq(q.field("_id"), ctx.user._id)).first();
-  }
-});
+)
 
+// Use them
 export const updateProfile = authMutation({
   args: { name: z.string() },
+  returns: z.null(),
   handler: async (ctx, { name }) => {
-    // ctx.user is automatically available and typed!
-    return ctx.db.patch(ctx.user._id, { name });
+    // ctx.user and ctx.permissions are available
+    if (!ctx.permissions.canEdit) {
+      throw new Error('No permission')
+    }
+    await ctx.db.patch(ctx.user._id, { name })
+    return null
   }
-});
+})
 ```
 
-**Available custom builders:**
-- `zCustomQueryBuilder` - for queries with custom context
-- `zCustomMutationBuilder` - for mutations with custom context
-- `zCustomActionBuilder` - for actions with custom context
+### Date Handling
 
-### Working with Dates
+Dates are automatically converted to timestamps:
 
 ```ts
-// Dates are automatically converted to timestamps
 const eventShape = {
   title: z.string(),
   startDate: z.date(),
-  endDate: z.date().nullable(),
-};
+  endDate: z.date().nullable()
+}
 
-const Events = zodTable("events", eventShape);
+export const Events = zodTable('events', eventShape)
 
-// In mutations - Date objects work seamlessly
-export const createEvent = zMutation(
-  mutation,
-  z.object(eventShape),
-  async (ctx, event) => {
+export const createEvent = zm({
+  args: eventShape,
+  handler: async (ctx, event) => {
     // event.startDate is a Date object
-    // It's automatically converted to timestamp for storage
-    return ctx.db.insert("events", event);
-  },
-);
+    // Automatically converted to timestamp for storage
+    return await ctx.db.insert('events', event)
+  }
+})
 ```
 
-### Using Convex IDs
+### Return Type Helpers
 
 ```ts
-import { zid } from "zodvex";
-
-const CommentSchema = z.object({
-  text: z.string(),
-  postId: zid("posts"), // Reference to posts table
-  authorId: zid("users"), // Reference to users table
-  parentId: zid("comments").optional(), // Self-reference
-});
-```
-
-## ⚙️ Behavior & Semantics
+import { returnsAs } from 'zodvex'
 
-### Type Mappings
+export const listUsers = zq({
+  args: {},
+  handler: async (ctx) => {
+    const rows = await ctx.db.query('users').collect()
+    // Use returnsAs for type hint in tricky inference spots
+    return returnsAs<typeof Users.docArray>()(rows)
+  },
+  returns: Users.docArray
+})
+```
 
-| Zod Type          | Convex Validator          |
-| ----------------- | ------------------------- |
-| `z.string()`      | `v.string()`              |
-| `z.number()`      | `v.float64()`             |
-| `z.bigint()`      | `v.int64()`               |
-| `z.boolean()`     | `v.boolean()`             |
-| `z.date()`        | `v.float64()` (timestamp) |
-| `z.null()`        | `v.null()`                |
-| `z.array(T)`      | `v.array(T)`              |
-| `z.object({...})` | `v.object({...})`         |
-| `z.record(T)`     | `v.record(v.string(), T)` |
-| `z.union([...])`  | `v.union(...)`            |
-| `z.literal(x)`    | `v.literal(x)`            |
-| `z.enum([...])`   | `v.union(literals...)`    |
-| `z.optional(T)`   | `v.optional(T)`           |
-| `z.nullable(T)`   | `v.union(T, v.null())`    |
+### Working with Large Schemas
 
-### Important Notes
+zodvex provides `pickShape` and `safePick` helpers as alternatives to Zod's `.pick()`:
 
-- **Defaults**: Zod defaults imply optional at the Convex schema level. Apply defaults in your application code.
-- **Numbers**: `z.number()` maps to `v.float64()`. For integers, use `z.bigint()` → `v.int64()`.
-- **Transforms**: Zod transforms (`.transform()`, `.refine()`) are not supported in schema mapping and fall back to `v.any()`.
- - **Return encoding**: Return values are always encoded to Convex Values. When `returns` is specified, values are validated and then encoded according to the schema; without `returns`, values are still encoded (e.g., Date → timestamp) for runtime safety.
+```ts
+import { pickShape, safePick } from 'zodvex'
+
+// Standard Zod .pick() works great for most schemas
+const UserUpdate = User.pick({ email: true, firstName: true, lastName: true })
+
+// If you hit TypeScript instantiation depth limits (rare, 100+ fields),
+// use pickShape or safePick:
+const userShape = pickShape(User, ['email', 'firstName', 'lastName'])
+const UserUpdate = z.object(userShape)
+
+// Or use safePick (convenience wrapper that does the same thing)
+const UserUpdate = safePick(User, {
+  email: true,
+  firstName: true,
+  lastName: true
+})
+```
 
-### Runtime Conversion Consistency
+## Why zodvex?
 
-zodvex uses an internal base-type codec registry to keep validator mapping and runtime value conversion aligned (e.g., `Date` ↔ timestamp). Composite types (arrays, objects, records, unions, optional/nullable) are composed from these base entries.
+- **Correct optional/nullable semantics** - Preserves Convex's distinction
+  - `.optional()` → `v.optional(T)` (field can be omitted)
+  - `.nullable()` → `v.union(T, v.null())` (required but can be null)
+  - Both → `v.optional(v.union(T, v.null()))`
+- **Superior type safety** - Builders provide better type inference than wrapper functions
+- **Date handling** - Automatic `Date` ↔ timestamp conversion
+- **End-to-end validation** - Same schema from database to frontend forms
 
-## 📝 Compatibility
+## Compatibility
 
-- **Zod**: v4 only (uses public v4 APIs)
-- **Convex**: >= 1.27
+- **Zod**: ^4.1.0 or later
+- **Convex**: >= 1.27.0
+- **convex-helpers**: >= 0.1.104
 - **TypeScript**: Full type inference support
 
-## 🤝 Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-## 📄 License
+## License
 
 MIT