zodvex 0.2.2 → 0.2.4

package/README.md

@@ -26,6 +26,7 @@ npm install zodvex zod@^4.1.0 convex convex-helpers
 ```
 
 **Peer dependencies:**
+
 - `zod` (^4.1.0 or later)
 - `convex` (>= 1.27.0)
 - `convex-helpers` (>= 0.1.104)
@@ -106,16 +107,16 @@ import { zodTable, zid } from 'zodvex'
 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())
+  age: z.number().optional(), // → v.optional(v.float64())
+  deletedAt: z.date().nullable(), // → v.union(v.float64(), v.null())
   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
+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
 ```
 
 ## Building Your Schema
@@ -134,8 +135,7 @@ export default defineSchema({
     .index('by_team', ['teamId'])
     .searchIndex('search_name', { searchField: 'name' }),
 
-  teams: Teams.table
-    .index('by_created', ['_creationTime'])
+  teams: Teams.table.index('by_created', ['_creationTime'])
 })
 ```
 
@@ -236,7 +236,11 @@ type CreateUserForm = z.infer<typeof CreateUserForm>
 function UserForm() {
   const createUser = useMutation(api.users.createUser)
 
-  const { register, handleSubmit, formState: { errors } } = useForm<CreateUserForm>({
+  const {
+    register,
+    handleSubmit,
+    formState: { errors }
+  } = useForm<CreateUserForm>({
     resolver: zodResolver(CreateUserForm)
   })
 
@@ -263,19 +267,22 @@ function UserForm() {
 ### Builders
 
 **Basic builders** - Create type-safe functions without auth:
+
 ```ts
-zQueryBuilder(query)      // Creates query builder
+zQueryBuilder(query) // Creates query builder
 zMutationBuilder(mutation) // Creates mutation builder
-zActionBuilder(action)     // Creates action builder
+zActionBuilder(action) // Creates action builder
 ```
 
 **Custom builders** - Add auth or custom context:
+
 ```ts
+import { type QueryCtx } from './_generated/server'
 import { customCtx } from 'zodvex'
 
 const authQuery = zCustomQueryBuilder(
   query,
-  customCtx(async (ctx) => {
+  customCtx(async (ctx: QueryCtx) => {
     const user = await getUserOrThrow(ctx)
     return { user }
   })
@@ -337,28 +344,52 @@ const decoded = codec.decode(encoded)
 
 ### Supported Types
 
-| 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())`    |
+| 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>
+```
+
+**This difference is purely cosmetic with no functional impact:**
+
+- ✅ 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
+
+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.
 
 **Convex IDs:**
+
 ```ts
 import { zid } from 'zodvex'
 
-zid('tableName')           // → v.id('tableName')
+zid('tableName') // → v.id('tableName')
 zid('tableName').optional() // → v.optional(v.id('tableName'))
 ```
 
@@ -368,14 +399,16 @@ zid('tableName').optional() // → v.optional(v.id('tableName'))
 
 Create builders with injected auth, permissions, or other context:
 
+> **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 { zCustomQueryBuilder, zCustomMutationBuilder, customCtx } from 'zodvex'
-import { query, mutation } from './_generated/server'
+import { type QueryCtx, type MutationCtx, query, mutation } from './_generated/server'
 
 // Add user to all queries
 export const authQuery = zCustomQueryBuilder(
   query,
-  customCtx(async (ctx) => {
+  customCtx(async (ctx: QueryCtx) => {
     const user = await getUserOrThrow(ctx)
     return { user }
   })
@@ -384,7 +417,7 @@ export const authQuery = zCustomQueryBuilder(
 // Add user + permissions to mutations
 export const authMutation = zCustomMutationBuilder(
   mutation,
-  customCtx(async (ctx) => {
+  customCtx(async (ctx: MutationCtx) => {
     const user = await getUserOrThrow(ctx)
     const permissions = await getPermissions(ctx, user)
     return { user, permissions }
@@ -461,7 +494,11 @@ 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 })
+const UserUpdate = safePick(User, {
+  email: true,
+  firstName: true,
+  lastName: true
+})
 ```
 
 ## Why zodvex?

package/dist/index.d.mts

@@ -13,16 +13,29 @@ type IsZid<T> = T extends {
 type ExtractTableName<T> = T extends {
     _tableName: infer TableName;
 } ? TableName : never;
+type EnumToLiteralsTuple<T extends readonly [string, ...string[]]> = T['length'] extends 1 ? [VLiteral<T[0], 'required'>] : T['length'] extends 2 ? [VLiteral<T[0], 'required'>, VLiteral<T[1], 'required'>] : [
+    VLiteral<T[0], 'required'>,
+    VLiteral<T[1], 'required'>,
+    ...{
+        [K in keyof T]: K extends '0' | '1' ? never : K extends keyof T ? VLiteral<T[K], 'required'> : never;
+    }[keyof T & number][]
+];
 type ZodValidator = Record<string, z.ZodTypeAny>;
 type ConvexValidatorFromZodRequired<Z extends z.ZodTypeAny> = Z extends z.ZodOptional<infer T extends z.ZodTypeAny> ? VUnion<z.infer<T> | null, any[], 'required'> : ConvexValidatorFromZodBase<Z>;
-type ConvexValidatorFromZodBase<Z extends z.ZodTypeAny> = IsZid<Z> extends true ? ExtractTableName<Z> extends infer TableName extends string ? VId<GenericId<TableName>, 'required'> : VAny<'required'> : Z extends z.ZodString ? VString<z.infer<Z>, 'required'> : Z extends z.ZodNumber ? VFloat64<z.infer<Z>, 'required'> : Z extends z.ZodDate ? VFloat64<number, 'required'> : Z extends z.ZodBigInt ? VInt64<z.infer<Z>, 'required'> : Z extends z.ZodBoolean ? VBoolean<z.infer<Z>, 'required'> : Z extends z.ZodNull ? VNull<null, 'required'> : Z extends z.ZodArray<infer T extends z.ZodTypeAny> ? VArray<z.infer<Z>, ConvexValidatorFromZodRequired<T>, 'required'> : Z extends z.ZodObject<infer T> ? VObject<z.infer<Z>, ConvexValidatorFromZodFieldsAuto<T>, 'required', string> : Z extends z.ZodUnion<infer T> ? T extends readonly [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]] ? VUnion<z.infer<Z>, any[], 'required'> : never : Z extends z.ZodLiteral<infer T> ? VLiteral<T, 'required'> : Z extends z.ZodEnum<infer T> ? T extends Readonly<Record<string, infer _V>> ? T[keyof T] extends infer Values ? VUnion<Values, any[], 'required'> : never : never : Z extends z.ZodRecord<z.ZodString, infer V extends z.ZodTypeAny> ? VRecord<Record<string, z.infer<V>>, VString<string, 'required'>, ConvexValidatorFromZodRequired<V>, 'required', string> : Z extends z.ZodNullable<infer Inner extends z.ZodTypeAny> ? Inner extends z.ZodOptional<infer InnerInner extends z.ZodTypeAny> ? VOptional<VUnion<z.infer<InnerInner> | null, [
+type ConvexValidatorFromZodBase<Z extends z.ZodTypeAny> = IsZid<Z> extends true ? ExtractTableName<Z> extends infer TableName extends string ? VId<GenericId<TableName>, 'required'> : VAny<'required'> : Z extends z.ZodString ? VString<z.infer<Z>, 'required'> : Z extends z.ZodNumber ? VFloat64<z.infer<Z>, 'required'> : Z extends z.ZodDate ? VFloat64<number, 'required'> : Z extends z.ZodBigInt ? VInt64<z.infer<Z>, 'required'> : Z extends z.ZodBoolean ? VBoolean<z.infer<Z>, 'required'> : Z extends z.ZodNull ? VNull<null, 'required'> : Z extends z.ZodArray<infer T extends z.ZodTypeAny> ? VArray<z.infer<Z>, ConvexValidatorFromZodRequired<T>, 'required'> : Z extends z.ZodObject<infer T> ? VObject<z.infer<Z>, ConvexValidatorFromZodFieldsAuto<T>, 'required', string> : Z extends z.ZodUnion<infer T> ? T extends readonly [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]] ? VUnion<z.infer<Z>, any[], 'required'> : never : Z extends z.ZodLiteral<infer T> ? VLiteral<T, 'required'> : Z extends z.ZodEnum<infer T> ? T extends readonly [string, ...string[]] ? T['length'] extends 1 ? VLiteral<T[0], 'required'> : T['length'] extends 2 ? VUnion<T[number], [
+    VLiteral<T[0], 'required'>,
+    VLiteral<T[1], 'required'>
+], 'required', never> : VUnion<T[number], EnumToLiteralsTuple<T>, 'required', never> : T extends Record<string, string | number> ? VUnion<T[keyof T], Array<VLiteral<T[keyof T], 'required'>>, 'required', never> : VUnion<string, any[], 'required', any> : Z extends z.ZodRecord<z.ZodString, infer V extends z.ZodTypeAny> ? VRecord<Record<string, z.infer<V>>, VString<string, 'required'>, ConvexValidatorFromZodRequired<V>, 'required', string> : Z extends z.ZodNullable<infer Inner extends z.ZodTypeAny> ? Inner extends z.ZodOptional<infer InnerInner extends z.ZodTypeAny> ? VOptional<VUnion<z.infer<InnerInner> | null, [
     ConvexValidatorFromZodBase<InnerInner>,
     VNull<null, 'required'>
 ], 'required'>> : VUnion<z.infer<Inner> | null, [
     ConvexValidatorFromZodBase<Inner>,
     VNull<null, 'required'>
 ], 'required'> : Z extends z.ZodAny ? VAny<'required'> : Z extends z.ZodUnknown ? VAny<'required'> : VAny<'required'>;
-type ConvexValidatorFromZod<Z extends z.ZodTypeAny, Constraint extends 'required' | 'optional' = 'required'> = Z extends z.ZodAny ? VAny<'required'> : Z extends z.ZodUnknown ? VAny<'required'> : Z extends z.ZodDefault<infer T extends z.ZodTypeAny> ? ConvexValidatorFromZod<T, Constraint> : Z extends z.ZodOptional<infer T extends z.ZodTypeAny> ? T extends z.ZodNullable<infer Inner extends z.ZodTypeAny> ? VOptional<VUnion<z.infer<Inner> | null, any[], 'required'>> : Constraint extends 'required' ? VUnion<z.infer<T>, any[], 'required'> : VOptional<ConvexValidatorFromZod<T, 'required'>> : Z extends z.ZodNullable<infer T extends z.ZodTypeAny> ? VUnion<z.infer<T> | null, any[], Constraint> : IsZid<Z> extends true ? ExtractTableName<Z> extends infer TableName extends string ? VId<GenericId<TableName>, Constraint> : VAny<'required'> : Z extends z.ZodString ? VString<z.infer<Z>, Constraint> : Z extends z.ZodNumber ? VFloat64<z.infer<Z>, Constraint> : Z extends z.ZodDate ? VFloat64<number, Constraint> : Z extends z.ZodBigInt ? VInt64<z.infer<Z>, Constraint> : Z extends z.ZodBoolean ? VBoolean<z.infer<Z>, Constraint> : Z extends z.ZodNull ? VNull<null, Constraint> : Z extends z.ZodArray<infer T extends z.ZodTypeAny> ? VArray<z.infer<Z>, ConvexValidatorFromZodRequired<T>, Constraint> : Z extends z.ZodObject<infer T> ? VObject<z.infer<Z>, ConvexValidatorFromZodFields<T, 'required'>, Constraint, string> : Z extends z.ZodUnion<infer T> ? T extends readonly [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]] ? VUnion<z.infer<Z>, any[], Constraint> : never : Z extends z.ZodLiteral<infer T> ? VLiteral<T, Constraint> : Z extends z.ZodEnum<infer T> ? T extends Readonly<Record<string, infer _V>> ? T[keyof T] extends infer Values ? VUnion<Values, any[], Constraint> : never : never : Z extends z.ZodRecord<z.ZodString, infer V extends z.ZodTypeAny> ? VRecord<Record<string, z.infer<V>>, VString<string, 'required'>, ConvexValidatorFromZodRequired<V>, Constraint, string> : VAny<'required'>;
+type ConvexValidatorFromZod<Z extends z.ZodTypeAny, Constraint extends 'required' | 'optional' = 'required'> = Z extends z.ZodAny ? VAny<'required'> : Z extends z.ZodUnknown ? VAny<'required'> : Z extends z.ZodDefault<infer T extends z.ZodTypeAny> ? ConvexValidatorFromZod<T, Constraint> : Z extends z.ZodOptional<infer T extends z.ZodTypeAny> ? T extends z.ZodNullable<infer Inner extends z.ZodTypeAny> ? VOptional<VUnion<z.infer<Inner> | null, any[], 'required'>> : Constraint extends 'required' ? VUnion<z.infer<T>, any[], 'required'> : VOptional<ConvexValidatorFromZod<T, 'required'>> : Z extends z.ZodNullable<infer T extends z.ZodTypeAny> ? VUnion<z.infer<T> | null, any[], Constraint> : IsZid<Z> extends true ? ExtractTableName<Z> extends infer TableName extends string ? VId<GenericId<TableName>, Constraint> : VAny<'required'> : Z extends z.ZodString ? VString<z.infer<Z>, Constraint> : Z extends z.ZodNumber ? VFloat64<z.infer<Z>, Constraint> : Z extends z.ZodDate ? VFloat64<number, Constraint> : Z extends z.ZodBigInt ? VInt64<z.infer<Z>, Constraint> : Z extends z.ZodBoolean ? VBoolean<z.infer<Z>, Constraint> : Z extends z.ZodNull ? VNull<null, Constraint> : Z extends z.ZodArray<infer T extends z.ZodTypeAny> ? VArray<z.infer<Z>, ConvexValidatorFromZodRequired<T>, Constraint> : Z extends z.ZodObject<infer T> ? VObject<z.infer<Z>, ConvexValidatorFromZodFields<T, 'required'>, Constraint, string> : Z extends z.ZodUnion<infer T> ? T extends readonly [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]] ? VUnion<z.infer<Z>, any[], Constraint> : never : Z extends z.ZodLiteral<infer T> ? VLiteral<T, Constraint> : Z extends z.ZodEnum<infer T> ? T extends readonly [string, ...string[]] ? T['length'] extends 1 ? VLiteral<T[0], Constraint> : T['length'] extends 2 ? VUnion<T[number], [
+    VLiteral<T[0], 'required'>,
+    VLiteral<T[1], 'required'>
+], Constraint, never> : VUnion<T[number], EnumToLiteralsTuple<T>, Constraint, never> : T extends Record<string, string | number> ? VUnion<T[keyof T], Array<VLiteral<T[keyof T], 'required'>>, Constraint, never> : VUnion<string, any[], Constraint, any> : Z extends z.ZodRecord<z.ZodString, infer V extends z.ZodTypeAny> ? VRecord<Record<string, z.infer<V>>, VString<string, 'required'>, ConvexValidatorFromZodRequired<V>, Constraint, string> : VAny<'required'>;
 type ConvexValidatorFromZodFields<T extends {
     [key: string]: any;
 }, Constraint extends 'required' | 'optional' = 'required'> = {
@@ -228,13 +241,13 @@ declare function zActionBuilder<Builder extends (fn: any) => any>(builder: Build
  *
  * @example
  * ```ts
- * import { query } from './_generated/server'
+ * import { type QueryCtx, query } from './_generated/server'
  * import { zCustomQueryBuilder, customCtx } from 'zodvex'
  *
  * // Create a builder with auth context
  * export const authQuery = zCustomQueryBuilder(
  *   query,
- *   customCtx(async (ctx) => {
+ *   customCtx(async (ctx: QueryCtx) => {
  *     const user = await getUserOrThrow(ctx)
  *     return { user }
  *   })
@@ -257,13 +270,13 @@ declare function zCustomQueryBuilder<Builder extends (fn: any) => any, CustomArg
  *
  * @example
  * ```ts
- * import { mutation } from './_generated/server'
+ * import { type MutationCtx, mutation } from './_generated/server'
  * import { zCustomMutationBuilder, customCtx } from 'zodvex'
  *
  * // Create a builder with auth context
  * export const authMutation = zCustomMutationBuilder(
  *   mutation,
- *   customCtx(async (ctx) => {
+ *   customCtx(async (ctx: MutationCtx) => {
  *     const user = await getUserOrThrow(ctx)
  *     return { user }
  *   })
@@ -286,13 +299,13 @@ declare function zCustomMutationBuilder<Builder extends (fn: any) => any, Custom
  *
  * @example
  * ```ts
- * import { action } from './_generated/server'
+ * import { type ActionCtx, action } from './_generated/server'
  * import { zCustomActionBuilder, customCtx } from 'zodvex'
  *
  * // Create a builder with auth context
  * export const authAction = zCustomActionBuilder(
  *   action,
- *   customCtx(async (ctx) => {
+ *   customCtx(async (ctx: ActionCtx) => {
  *     const identity = await ctx.auth.getUserIdentity()
  *     if (!identity) throw new Error('Unauthorized')
  *     return { userId: identity.subject }

package/dist/index.d.ts

@@ -13,16 +13,29 @@ type IsZid<T> = T extends {
 type ExtractTableName<T> = T extends {
     _tableName: infer TableName;
 } ? TableName : never;
+type EnumToLiteralsTuple<T extends readonly [string, ...string[]]> = T['length'] extends 1 ? [VLiteral<T[0], 'required'>] : T['length'] extends 2 ? [VLiteral<T[0], 'required'>, VLiteral<T[1], 'required'>] : [
+    VLiteral<T[0], 'required'>,
+    VLiteral<T[1], 'required'>,
+    ...{
+        [K in keyof T]: K extends '0' | '1' ? never : K extends keyof T ? VLiteral<T[K], 'required'> : never;
+    }[keyof T & number][]
+];
 type ZodValidator = Record<string, z.ZodTypeAny>;
 type ConvexValidatorFromZodRequired<Z extends z.ZodTypeAny> = Z extends z.ZodOptional<infer T extends z.ZodTypeAny> ? VUnion<z.infer<T> | null, any[], 'required'> : ConvexValidatorFromZodBase<Z>;
-type ConvexValidatorFromZodBase<Z extends z.ZodTypeAny> = IsZid<Z> extends true ? ExtractTableName<Z> extends infer TableName extends string ? VId<GenericId<TableName>, 'required'> : VAny<'required'> : Z extends z.ZodString ? VString<z.infer<Z>, 'required'> : Z extends z.ZodNumber ? VFloat64<z.infer<Z>, 'required'> : Z extends z.ZodDate ? VFloat64<number, 'required'> : Z extends z.ZodBigInt ? VInt64<z.infer<Z>, 'required'> : Z extends z.ZodBoolean ? VBoolean<z.infer<Z>, 'required'> : Z extends z.ZodNull ? VNull<null, 'required'> : Z extends z.ZodArray<infer T extends z.ZodTypeAny> ? VArray<z.infer<Z>, ConvexValidatorFromZodRequired<T>, 'required'> : Z extends z.ZodObject<infer T> ? VObject<z.infer<Z>, ConvexValidatorFromZodFieldsAuto<T>, 'required', string> : Z extends z.ZodUnion<infer T> ? T extends readonly [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]] ? VUnion<z.infer<Z>, any[], 'required'> : never : Z extends z.ZodLiteral<infer T> ? VLiteral<T, 'required'> : Z extends z.ZodEnum<infer T> ? T extends Readonly<Record<string, infer _V>> ? T[keyof T] extends infer Values ? VUnion<Values, any[], 'required'> : never : never : Z extends z.ZodRecord<z.ZodString, infer V extends z.ZodTypeAny> ? VRecord<Record<string, z.infer<V>>, VString<string, 'required'>, ConvexValidatorFromZodRequired<V>, 'required', string> : Z extends z.ZodNullable<infer Inner extends z.ZodTypeAny> ? Inner extends z.ZodOptional<infer InnerInner extends z.ZodTypeAny> ? VOptional<VUnion<z.infer<InnerInner> | null, [
+type ConvexValidatorFromZodBase<Z extends z.ZodTypeAny> = IsZid<Z> extends true ? ExtractTableName<Z> extends infer TableName extends string ? VId<GenericId<TableName>, 'required'> : VAny<'required'> : Z extends z.ZodString ? VString<z.infer<Z>, 'required'> : Z extends z.ZodNumber ? VFloat64<z.infer<Z>, 'required'> : Z extends z.ZodDate ? VFloat64<number, 'required'> : Z extends z.ZodBigInt ? VInt64<z.infer<Z>, 'required'> : Z extends z.ZodBoolean ? VBoolean<z.infer<Z>, 'required'> : Z extends z.ZodNull ? VNull<null, 'required'> : Z extends z.ZodArray<infer T extends z.ZodTypeAny> ? VArray<z.infer<Z>, ConvexValidatorFromZodRequired<T>, 'required'> : Z extends z.ZodObject<infer T> ? VObject<z.infer<Z>, ConvexValidatorFromZodFieldsAuto<T>, 'required', string> : Z extends z.ZodUnion<infer T> ? T extends readonly [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]] ? VUnion<z.infer<Z>, any[], 'required'> : never : Z extends z.ZodLiteral<infer T> ? VLiteral<T, 'required'> : Z extends z.ZodEnum<infer T> ? T extends readonly [string, ...string[]] ? T['length'] extends 1 ? VLiteral<T[0], 'required'> : T['length'] extends 2 ? VUnion<T[number], [
+    VLiteral<T[0], 'required'>,
+    VLiteral<T[1], 'required'>
+], 'required', never> : VUnion<T[number], EnumToLiteralsTuple<T>, 'required', never> : T extends Record<string, string | number> ? VUnion<T[keyof T], Array<VLiteral<T[keyof T], 'required'>>, 'required', never> : VUnion<string, any[], 'required', any> : Z extends z.ZodRecord<z.ZodString, infer V extends z.ZodTypeAny> ? VRecord<Record<string, z.infer<V>>, VString<string, 'required'>, ConvexValidatorFromZodRequired<V>, 'required', string> : Z extends z.ZodNullable<infer Inner extends z.ZodTypeAny> ? Inner extends z.ZodOptional<infer InnerInner extends z.ZodTypeAny> ? VOptional<VUnion<z.infer<InnerInner> | null, [
     ConvexValidatorFromZodBase<InnerInner>,
     VNull<null, 'required'>
 ], 'required'>> : VUnion<z.infer<Inner> | null, [
     ConvexValidatorFromZodBase<Inner>,
     VNull<null, 'required'>
 ], 'required'> : Z extends z.ZodAny ? VAny<'required'> : Z extends z.ZodUnknown ? VAny<'required'> : VAny<'required'>;
-type ConvexValidatorFromZod<Z extends z.ZodTypeAny, Constraint extends 'required' | 'optional' = 'required'> = Z extends z.ZodAny ? VAny<'required'> : Z extends z.ZodUnknown ? VAny<'required'> : Z extends z.ZodDefault<infer T extends z.ZodTypeAny> ? ConvexValidatorFromZod<T, Constraint> : Z extends z.ZodOptional<infer T extends z.ZodTypeAny> ? T extends z.ZodNullable<infer Inner extends z.ZodTypeAny> ? VOptional<VUnion<z.infer<Inner> | null, any[], 'required'>> : Constraint extends 'required' ? VUnion<z.infer<T>, any[], 'required'> : VOptional<ConvexValidatorFromZod<T, 'required'>> : Z extends z.ZodNullable<infer T extends z.ZodTypeAny> ? VUnion<z.infer<T> | null, any[], Constraint> : IsZid<Z> extends true ? ExtractTableName<Z> extends infer TableName extends string ? VId<GenericId<TableName>, Constraint> : VAny<'required'> : Z extends z.ZodString ? VString<z.infer<Z>, Constraint> : Z extends z.ZodNumber ? VFloat64<z.infer<Z>, Constraint> : Z extends z.ZodDate ? VFloat64<number, Constraint> : Z extends z.ZodBigInt ? VInt64<z.infer<Z>, Constraint> : Z extends z.ZodBoolean ? VBoolean<z.infer<Z>, Constraint> : Z extends z.ZodNull ? VNull<null, Constraint> : Z extends z.ZodArray<infer T extends z.ZodTypeAny> ? VArray<z.infer<Z>, ConvexValidatorFromZodRequired<T>, Constraint> : Z extends z.ZodObject<infer T> ? VObject<z.infer<Z>, ConvexValidatorFromZodFields<T, 'required'>, Constraint, string> : Z extends z.ZodUnion<infer T> ? T extends readonly [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]] ? VUnion<z.infer<Z>, any[], Constraint> : never : Z extends z.ZodLiteral<infer T> ? VLiteral<T, Constraint> : Z extends z.ZodEnum<infer T> ? T extends Readonly<Record<string, infer _V>> ? T[keyof T] extends infer Values ? VUnion<Values, any[], Constraint> : never : never : Z extends z.ZodRecord<z.ZodString, infer V extends z.ZodTypeAny> ? VRecord<Record<string, z.infer<V>>, VString<string, 'required'>, ConvexValidatorFromZodRequired<V>, Constraint, string> : VAny<'required'>;
+type ConvexValidatorFromZod<Z extends z.ZodTypeAny, Constraint extends 'required' | 'optional' = 'required'> = Z extends z.ZodAny ? VAny<'required'> : Z extends z.ZodUnknown ? VAny<'required'> : Z extends z.ZodDefault<infer T extends z.ZodTypeAny> ? ConvexValidatorFromZod<T, Constraint> : Z extends z.ZodOptional<infer T extends z.ZodTypeAny> ? T extends z.ZodNullable<infer Inner extends z.ZodTypeAny> ? VOptional<VUnion<z.infer<Inner> | null, any[], 'required'>> : Constraint extends 'required' ? VUnion<z.infer<T>, any[], 'required'> : VOptional<ConvexValidatorFromZod<T, 'required'>> : Z extends z.ZodNullable<infer T extends z.ZodTypeAny> ? VUnion<z.infer<T> | null, any[], Constraint> : IsZid<Z> extends true ? ExtractTableName<Z> extends infer TableName extends string ? VId<GenericId<TableName>, Constraint> : VAny<'required'> : Z extends z.ZodString ? VString<z.infer<Z>, Constraint> : Z extends z.ZodNumber ? VFloat64<z.infer<Z>, Constraint> : Z extends z.ZodDate ? VFloat64<number, Constraint> : Z extends z.ZodBigInt ? VInt64<z.infer<Z>, Constraint> : Z extends z.ZodBoolean ? VBoolean<z.infer<Z>, Constraint> : Z extends z.ZodNull ? VNull<null, Constraint> : Z extends z.ZodArray<infer T extends z.ZodTypeAny> ? VArray<z.infer<Z>, ConvexValidatorFromZodRequired<T>, Constraint> : Z extends z.ZodObject<infer T> ? VObject<z.infer<Z>, ConvexValidatorFromZodFields<T, 'required'>, Constraint, string> : Z extends z.ZodUnion<infer T> ? T extends readonly [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]] ? VUnion<z.infer<Z>, any[], Constraint> : never : Z extends z.ZodLiteral<infer T> ? VLiteral<T, Constraint> : Z extends z.ZodEnum<infer T> ? T extends readonly [string, ...string[]] ? T['length'] extends 1 ? VLiteral<T[0], Constraint> : T['length'] extends 2 ? VUnion<T[number], [
+    VLiteral<T[0], 'required'>,
+    VLiteral<T[1], 'required'>
+], Constraint, never> : VUnion<T[number], EnumToLiteralsTuple<T>, Constraint, never> : T extends Record<string, string | number> ? VUnion<T[keyof T], Array<VLiteral<T[keyof T], 'required'>>, Constraint, never> : VUnion<string, any[], Constraint, any> : Z extends z.ZodRecord<z.ZodString, infer V extends z.ZodTypeAny> ? VRecord<Record<string, z.infer<V>>, VString<string, 'required'>, ConvexValidatorFromZodRequired<V>, Constraint, string> : VAny<'required'>;
 type ConvexValidatorFromZodFields<T extends {
     [key: string]: any;
 }, Constraint extends 'required' | 'optional' = 'required'> = {
@@ -228,13 +241,13 @@ declare function zActionBuilder<Builder extends (fn: any) => any>(builder: Build
  *
  * @example
  * ```ts
- * import { query } from './_generated/server'
+ * import { type QueryCtx, query } from './_generated/server'
  * import { zCustomQueryBuilder, customCtx } from 'zodvex'
  *
  * // Create a builder with auth context
  * export const authQuery = zCustomQueryBuilder(
  *   query,
- *   customCtx(async (ctx) => {
+ *   customCtx(async (ctx: QueryCtx) => {
  *     const user = await getUserOrThrow(ctx)
  *     return { user }
  *   })
@@ -257,13 +270,13 @@ declare function zCustomQueryBuilder<Builder extends (fn: any) => any, CustomArg
  *
  * @example
  * ```ts
- * import { mutation } from './_generated/server'
+ * import { type MutationCtx, mutation } from './_generated/server'
  * import { zCustomMutationBuilder, customCtx } from 'zodvex'
  *
  * // Create a builder with auth context
  * export const authMutation = zCustomMutationBuilder(
  *   mutation,
- *   customCtx(async (ctx) => {
+ *   customCtx(async (ctx: MutationCtx) => {
  *     const user = await getUserOrThrow(ctx)
  *     return { user }
  *   })
@@ -286,13 +299,13 @@ declare function zCustomMutationBuilder<Builder extends (fn: any) => any, Custom
  *
  * @example
  * ```ts
- * import { action } from './_generated/server'
+ * import { type ActionCtx, action } from './_generated/server'
  * import { zCustomActionBuilder, customCtx } from 'zodvex'
  *
  * // Create a builder with auth context
  * export const authAction = zCustomActionBuilder(
  *   action,
- *   customCtx(async (ctx) => {
+ *   customCtx(async (ctx: ActionCtx) => {
  *     const identity = await ctx.auth.getUserIdentity()
  *     if (!identity) throw new Error('Unauthorized')
  *     return { userId: identity.subject }

package/dist/index.js

@@ -146,7 +146,10 @@ function convertDiscriminatedUnionType(actualValidator, visited, zodToConvexInte
   if (options) {
     const opts = Array.isArray(options) ? options : Array.from(options);
     if (opts.length >= 2) {
-      const convexOptions = opts.map((opt) => zodToConvexInternal2(opt, visited));
+      const convexOptions = opts.map((opt) => {
+        const branchVisited = new Set(visited);
+        return zodToConvexInternal2(opt, branchVisited);
+      });
       const [first, second, ...rest] = convexOptions;
       return values.v.union(
         first,
@@ -166,9 +169,10 @@ function convertUnionType(actualValidator, visited, zodToConvexInternal2) {
     if (options.length === 1) {
       return zodToConvexInternal2(options[0], visited);
     } else {
-      const convexOptions = options.map(
-        (opt) => zodToConvexInternal2(opt, visited)
-      );
+      const convexOptions = options.map((opt) => {
+        const branchVisited = new Set(visited);
+        return zodToConvexInternal2(opt, branchVisited);
+      });
       if (convexOptions.length >= 2) {
         const [first, second, ...rest] = convexOptions;
         return values.v.union(
@@ -724,7 +728,11 @@ function customFnBuilder(builder, customization) {
               handleZodValidationError(e, "returns");
             }
             if (added?.onSuccess) {
-              await added.onSuccess({ ctx, args: parsed.data, result: validated });
+              await added.onSuccess({
+                ctx,
+                args: parsed.data,
+                result: validated
+              });
             }
             return toConvexJS(returns, validated);
           }