zodvex 0.2.0 → 0.2.2

package/src/builders.ts

@@ -0,0 +1,310 @@
+import type {
+  FunctionVisibility,
+  RegisteredAction,
+  RegisteredMutation,
+  RegisteredQuery
+} from 'convex/server'
+import type { PropertyValidators } from 'convex/values'
+import type { Customization } from 'convex-helpers/server/customFunctions'
+import { z } from 'zod'
+import { type CustomBuilder, customFnBuilder } from './custom'
+import type {
+  ExtractCtx,
+  ExtractVisibility,
+  InferHandlerReturns,
+  InferReturns,
+  ZodToConvexArgs
+} from './types'
+import { zAction, zMutation, zQuery } from './wrappers'
+
+/**
+ * Creates a reusable query builder from a Convex query builder.
+ * Returns a builder function that accepts Convex-style config objects with args, handler, and returns.
+ *
+ * @example
+ * ```ts
+ * import { query } from './_generated/server'
+ * import { zQueryBuilder } from 'zodvex'
+ *
+ * // Create a reusable builder
+ * export const zq = zQueryBuilder(query)
+ *
+ * // Use it with Convex-style object syntax
+ * export const getUser = zq({
+ *   args: { id: z.string() },
+ *   handler: async (ctx, { id }) => {
+ *     return ctx.db.get(id)
+ *   }
+ * })
+ * ```
+ */
+export function zQueryBuilder<Builder extends (fn: any) => any>(builder: Builder) {
+  return <
+    A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>,
+    R extends z.ZodTypeAny | undefined = undefined,
+    Visibility extends FunctionVisibility = ExtractVisibility<Builder>
+  >(config: {
+    args?: A
+    handler: (
+      ctx: ExtractCtx<Builder>,
+      args: ZodToConvexArgs<A extends undefined ? Record<string, never> : A>
+    ) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>
+    returns?: R
+  }): RegisteredQuery<
+    Visibility,
+    ZodToConvexArgs<A extends undefined ? Record<string, never> : A>,
+    Promise<InferReturns<R>>
+  > => {
+    return zQuery(builder, config.args ?? ({} as any), config.handler, {
+      returns: config.returns
+    }) as any
+  }
+}
+
+/**
+ * Creates a reusable mutation builder from a Convex mutation builder.
+ * Returns a builder function that accepts Convex-style config objects with args, handler, and returns.
+ *
+ * @example
+ * ```ts
+ * import { mutation } from './_generated/server'
+ * import { zMutationBuilder } from 'zodvex'
+ *
+ * // Create a reusable builder
+ * export const zm = zMutationBuilder(mutation)
+ *
+ * // Use it with Convex-style object syntax
+ * export const updateUser = zm({
+ *   args: { id: z.string(), name: z.string() },
+ *   handler: async (ctx, { id, name }) => {
+ *     return ctx.db.patch(id, { name })
+ *   }
+ * })
+ * ```
+ */
+export function zMutationBuilder<Builder extends (fn: any) => any>(builder: Builder) {
+  return <
+    A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>,
+    R extends z.ZodTypeAny | undefined = undefined,
+    Visibility extends FunctionVisibility = ExtractVisibility<Builder>
+  >(config: {
+    args?: A
+    handler: (
+      ctx: ExtractCtx<Builder>,
+      args: ZodToConvexArgs<A extends undefined ? Record<string, never> : A>
+    ) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>
+    returns?: R
+  }): RegisteredMutation<
+    Visibility,
+    ZodToConvexArgs<A extends undefined ? Record<string, never> : A>,
+    Promise<InferReturns<R>>
+  > => {
+    return zMutation(builder, config.args ?? ({} as any), config.handler, {
+      returns: config.returns
+    }) as any
+  }
+}
+
+/**
+ * Creates a reusable action builder from a Convex action builder.
+ * Returns a builder function that accepts Convex-style config objects with args, handler, and returns.
+ *
+ * @example
+ * ```ts
+ * import { action } from './_generated/server'
+ * import { zActionBuilder } from 'zodvex'
+ *
+ * // Create a reusable builder
+ * export const za = zActionBuilder(action)
+ *
+ * // Use it with Convex-style object syntax
+ * export const sendEmail = za({
+ *   args: { to: z.string().email(), subject: z.string() },
+ *   handler: async (ctx, { to, subject }) => {
+ *     // Send email
+ *   }
+ * })
+ * ```
+ */
+export function zActionBuilder<Builder extends (fn: any) => any>(builder: Builder) {
+  return <
+    A extends z.ZodTypeAny | Record<string, z.ZodTypeAny>,
+    R extends z.ZodTypeAny | undefined = undefined,
+    Visibility extends FunctionVisibility = ExtractVisibility<Builder>
+  >(config: {
+    args?: A
+    handler: (
+      ctx: ExtractCtx<Builder>,
+      args: ZodToConvexArgs<A extends undefined ? Record<string, never> : A>
+    ) => InferHandlerReturns<R> | Promise<InferHandlerReturns<R>>
+    returns?: R
+  }): RegisteredAction<
+    Visibility,
+    ZodToConvexArgs<A extends undefined ? Record<string, never> : A>,
+    Promise<InferReturns<R>>
+  > => {
+    return zAction(builder, config.args ?? ({} as any), config.handler, {
+      returns: config.returns
+    }) as any
+  }
+}
+
+/**
+ * Creates a custom query builder with context injection from a Convex query builder.
+ * Allows you to add custom context (like auth, permissions, etc.) to your queries.
+ *
+ * @example
+ * ```ts
+ * import { query } from './_generated/server'
+ * import { zCustomQueryBuilder, customCtx } from 'zodvex'
+ *
+ * // Create a builder with auth context
+ * export const authQuery = zCustomQueryBuilder(
+ *   query,
+ *   customCtx(async (ctx) => {
+ *     const user = await getUserOrThrow(ctx)
+ *     return { user }
+ *   })
+ * )
+ *
+ * // Use it with automatic user injection
+ * export const getMyProfile = authQuery({
+ *   args: {},
+ *   handler: async (ctx) => {
+ *     // ctx.user is automatically available
+ *     return ctx.db.get(ctx.user._id)
+ *   }
+ * })
+ * ```
+ */
+export function zCustomQueryBuilder<
+  Builder extends (fn: any) => any,
+  CustomArgsValidator extends PropertyValidators,
+  CustomCtx extends Record<string, any>,
+  CustomMadeArgs extends Record<string, any>,
+  Visibility extends FunctionVisibility = ExtractVisibility<Builder>,
+  ExtraArgs extends Record<string, any> = Record<string, any>
+>(
+  query: Builder,
+  customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
+): CustomBuilder<
+  'query',
+  CustomArgsValidator,
+  CustomCtx,
+  CustomMadeArgs,
+  ExtractCtx<Builder>,
+  Visibility,
+  ExtraArgs
+> {
+  return customFnBuilder<any, Builder, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>(
+    query as any,
+    customization as any
+  ) as any
+}
+
+/**
+ * Creates a custom mutation builder with context injection from a Convex mutation builder.
+ * Allows you to add custom context (like auth, permissions, etc.) to your mutations.
+ *
+ * @example
+ * ```ts
+ * import { mutation } from './_generated/server'
+ * import { zCustomMutationBuilder, customCtx } from 'zodvex'
+ *
+ * // Create a builder with auth context
+ * export const authMutation = zCustomMutationBuilder(
+ *   mutation,
+ *   customCtx(async (ctx) => {
+ *     const user = await getUserOrThrow(ctx)
+ *     return { user }
+ *   })
+ * )
+ *
+ * // Use it with automatic user injection
+ * export const updateProfile = authMutation({
+ *   args: { name: z.string() },
+ *   handler: async (ctx, { name }) => {
+ *     // ctx.user is automatically available
+ *     await ctx.db.patch(ctx.user._id, { name })
+ *   }
+ * })
+ * ```
+ */
+export function zCustomMutationBuilder<
+  Builder extends (fn: any) => any,
+  CustomArgsValidator extends PropertyValidators,
+  CustomCtx extends Record<string, any>,
+  CustomMadeArgs extends Record<string, any>,
+  Visibility extends FunctionVisibility = ExtractVisibility<Builder>,
+  ExtraArgs extends Record<string, any> = Record<string, any>
+>(
+  mutation: Builder,
+  customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
+): CustomBuilder<
+  'mutation',
+  CustomArgsValidator,
+  CustomCtx,
+  CustomMadeArgs,
+  ExtractCtx<Builder>,
+  Visibility,
+  ExtraArgs
+> {
+  return customFnBuilder<any, Builder, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>(
+    mutation as any,
+    customization as any
+  ) as any
+}
+
+/**
+ * Creates a custom action builder with context injection from a Convex action builder.
+ * Allows you to add custom context (like auth, permissions, etc.) to your actions.
+ *
+ * @example
+ * ```ts
+ * import { action } from './_generated/server'
+ * import { zCustomActionBuilder, customCtx } from 'zodvex'
+ *
+ * // Create a builder with auth context
+ * export const authAction = zCustomActionBuilder(
+ *   action,
+ *   customCtx(async (ctx) => {
+ *     const identity = await ctx.auth.getUserIdentity()
+ *     if (!identity) throw new Error('Unauthorized')
+ *     return { userId: identity.subject }
+ *   })
+ * )
+ *
+ * // Use it with automatic auth injection
+ * export const sendEmail = authAction({
+ *   args: { to: z.string().email() },
+ *   handler: async (ctx, { to }) => {
+ *     // ctx.userId is automatically available
+ *     await sendEmailService(to, ctx.userId)
+ *   }
+ * })
+ * ```
+ */
+export function zCustomActionBuilder<
+  Builder extends (fn: any) => any,
+  CustomArgsValidator extends PropertyValidators,
+  CustomCtx extends Record<string, any>,
+  CustomMadeArgs extends Record<string, any>,
+  Visibility extends FunctionVisibility = ExtractVisibility<Builder>,
+  ExtraArgs extends Record<string, any> = Record<string, any>
+>(
+  action: Builder,
+  customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
+): CustomBuilder<
+  'action',
+  CustomArgsValidator,
+  CustomCtx,
+  CustomMadeArgs,
+  ExtractCtx<Builder>,
+  Visibility,
+  ExtraArgs
+> {
+  return customFnBuilder<any, Builder, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>(
+    action as any,
+    customization as any
+  ) as any
+}

package/src/custom.ts

@@ -162,7 +162,7 @@ export type CustomBuilder<
   >
 }
 
-function customFnBuilder<
+export function customFnBuilder<
   Ctx extends Record<string, any>,
   Builder extends (fn: any) => any,
   CustomArgsValidator extends PropertyValidators,
@@ -220,10 +220,9 @@ function customFnBuilder<
             handleZodValidationError(parsed.error, 'args')
           }
           const finalCtx = { ...ctx, ...(added?.ctx ?? {}) }
-          const finalArgs = {
-            ...(parsed.data as Record<string, unknown>),
-            ...((added?.args as Record<string, unknown>) ?? {})
-          }
+          const baseArgs = parsed.data as Record<string, unknown>
+          const addedArgs = (added?.args as Record<string, unknown>) ?? {}
+          const finalArgs = { ...baseArgs, ...addedArgs }
           const ret = await handler(finalCtx, finalArgs)
           if (returns && !fn.skipConvexValidation) {
             let validated: any
@@ -343,85 +342,6 @@ export function zCustomQuery<
   >(query as any, customization as any) as any
 }
 
-// Strict variants: infer ctx directly from builder for precise db typing
-export function zStrictQuery<
-  Builder extends (fn: any) => any,
-  CustomArgsValidator extends PropertyValidators,
-  CustomCtx extends Record<string, any>,
-  CustomMadeArgs extends Record<string, any>,
-  Visibility extends FunctionVisibility = ExtractVisibility<Builder>,
-  ExtraArgs extends Record<string, any> = Record<string, any>
->(
-  query: Builder,
-  // Note: Customization from convex-helpers requires Ctx extends Record<string, any>.
-  // We accept `any` here to avoid overly constraining Convex Ctx types while
-  // still threading the precise ctx type to the resulting builder.
-  customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
-): CustomBuilder<
-  'query',
-  CustomArgsValidator,
-  CustomCtx,
-  CustomMadeArgs,
-  ExtractCtx<Builder>,
-  Visibility,
-  ExtraArgs
-> {
-  return customFnBuilder<any, Builder, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>(
-    query as any,
-    customization as any
-  ) as any
-}
-
-export function zStrictMutation<
-  Builder extends (fn: any) => any,
-  CustomArgsValidator extends PropertyValidators,
-  CustomCtx extends Record<string, any>,
-  CustomMadeArgs extends Record<string, any>,
-  Visibility extends FunctionVisibility = ExtractVisibility<Builder>,
-  ExtraArgs extends Record<string, any> = Record<string, any>
->(
-  mutation: Builder,
-  customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
-): CustomBuilder<
-  'mutation',
-  CustomArgsValidator,
-  CustomCtx,
-  CustomMadeArgs,
-  ExtractCtx<Builder>,
-  Visibility,
-  ExtraArgs
-> {
-  return customFnBuilder<any, Builder, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>(
-    mutation as any,
-    customization as any
-  ) as any
-}
-
-export function zStrictAction<
-  Builder extends (fn: any) => any,
-  CustomArgsValidator extends PropertyValidators,
-  CustomCtx extends Record<string, any>,
-  CustomMadeArgs extends Record<string, any>,
-  Visibility extends FunctionVisibility = ExtractVisibility<Builder>,
-  ExtraArgs extends Record<string, any> = Record<string, any>
->(
-  action: Builder,
-  customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
-): CustomBuilder<
-  'action',
-  CustomArgsValidator,
-  CustomCtx,
-  CustomMadeArgs,
-  ExtractCtx<Builder>,
-  Visibility,
-  ExtraArgs
-> {
-  return customFnBuilder<any, Builder, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>(
-    action as any,
-    customization as any
-  ) as any
-}
-
 // Overload 1: With constraint - preferred to preserve DataModel types
 export function zCustomMutation<
   CustomArgsValidator extends PropertyValidators,

package/src/index.ts

@@ -1,3 +1,6 @@
+// Re-export customCtx from convex-helpers for convenience
+export { customCtx } from 'convex-helpers/server/customFunctions'
+export * from './builders'
 export * from './codec'
 export * from './custom'
 export * from './ids'
@@ -6,4 +9,4 @@ export * from './registry'
 export * from './tables'
 export * from './types'
 export * from './utils'
-export * from './wrappers'
+// wrappers are internal-only - use builders instead

package/src/mapping/core.ts

@@ -22,6 +22,11 @@ function zodToConvexInternal<Z extends z.ZodTypeAny>(
   zodValidator: Z,
   visited: Set<z.ZodTypeAny> = new Set()
 ): ConvexValidatorFromZod<Z, 'required'> {
+  // Guard against undefined/null validators (can happen with { field: undefined } in args)
+  if (!zodValidator) {
+    return v.any() as ConvexValidatorFromZod<Z, 'required'>
+  }
+
   // Detect circular references to prevent infinite recursion
   if (visited.has(zodValidator)) {
     return v.any() as ConvexValidatorFromZod<Z, 'required'>
@@ -72,6 +77,10 @@ function zodToConvexInternal<Z extends z.ZodTypeAny>(
     // 3. Future-proof: Zod's internal structure is stable; instanceof checks can miss custom types
     // 4. Precision: def.type distinguishes between semantically different types (date vs number)
     // This private API access is intentional and necessary for comprehensive type coverage.
+    //
+    // Compatibility: This code relies on the internal `.def.type` property of ZodType.
+    // This structure has been stable across Zod v3.x and v4.x. If upgrading Zod major versions,
+    // verify that `.def.type` is still present and unchanged.
     const defType = (actualValidator as any).def?.type
 
     switch (defType) {
@@ -268,6 +277,13 @@ function zodToConvexInternal<Z extends z.ZodTypeAny>(
       default:
         // For any unrecognized def.type, return v.any()
         // No instanceof fallbacks - keep it simple and performant
+        if (process.env.NODE_ENV !== 'production') {
+          console.warn(
+            `[zodvex] Unrecognized Zod type "${defType}" encountered. Falling back to v.any().`,
+            'Schema:',
+            actualValidator
+          )
+        }
         convexValidator = v.any()
         break
     }

package/src/tables.ts

@@ -2,8 +2,7 @@ import type { GenericId } from 'convex/values'
 import { Table } from 'convex-helpers/server'
 import { z } from 'zod'
 import { zid } from './ids'
-import { type ConvexValidatorFromZodFieldsAuto, getObjectShape, zodToConvexFields } from './mapping'
-import { mapDateFieldToNumber } from './utils'
+import { type ConvexValidatorFromZodFieldsAuto, zodToConvexFields } from './mapping'
 
 // Helper to create a Zod schema for a Convex document
 export function zodDoc<
@@ -44,7 +43,29 @@ export function zodDocOrNull<
  * This architectural decision is important for projects that rely heavily on type safety and
  * developer experience, as it avoids the type erasure that can occur when using ZodObject directly.
  *
- * Returns both the Table and the shape for use with zCrud.
+ * Returns the Table definition along with Zod schemas for documents and arrays.
+ *
+ * @param name - The table name
+ * @param shape - A raw object mapping field names to Zod validators
+ * @returns A Table with attached shape, zDoc schema, and docArray helper
+ *
+ * @example
+ * ```ts
+ * const Users = zodTable('users', {
+ *   name: z.string(),
+ *   email: z.string().email(),
+ *   age: z.number().optional()
+ * })
+ *
+ * // Use in schema
+ * export default defineSchema({ users: Users.table })
+ *
+ * // Use for return types
+ * export const getUsers = zQuery(query, {},
+ *   async (ctx) => ctx.db.query('users').collect(),
+ *   { returns: Users.docArray }
+ * )
+ * ```
  */
 export function zodTable<TableName extends string, Shape extends Record<string, z.ZodTypeAny>>(
   name: TableName,
@@ -56,10 +77,17 @@ export function zodTable<TableName extends string, Shape extends Record<string,
   // Create the Table from convex-helpers with explicit type
   const table = Table<ConvexValidatorFromZodFieldsAuto<Shape>, TableName>(name, convexFields)
 
-  // Attach the shape for zCrud usage
+  // Create zDoc schema with system fields
+  const zDoc = zodDoc(name, z.object(shape))
+
+  // Create docArray helper for return types
+  const docArray = z.array(zDoc)
+
+  // Attach everything for comprehensive usage
   return Object.assign(table, {
     shape,
-    zDoc: zodDoc(name, z.object(shape))
+    zDoc,
+    docArray
   }) as typeof table & {
     shape: Shape
     zDoc: z.ZodObject<
@@ -68,32 +96,6 @@ export function zodTable<TableName extends string, Shape extends Record<string,
         _creationTime: z.ZodNumber
       }
     >
+    docArray: z.ZodArray<typeof zDoc>
   }
 }
-
-// Keep the old implementation available for backward compatibility
-export function zodTableWithDocs<T extends z.ZodObject<any>, TableName extends string>(
-  name: TableName,
-  schema: T
-) {
-  // Use zodToConvexFields with proper types - pass the shape for type preservation
-  const convexFields = zodToConvexFields(schema.shape)
-
-  // Simplified: only convert dates at top level to avoid deep recursion
-  const shape = getObjectShape(schema)
-  const mapped: Record<string, any> = {}
-
-  for (const [k, field] of Object.entries(shape)) {
-    mapped[k] = mapDateFieldToNumber(field as z.ZodTypeAny)
-  }
-  const docSchema = z.object({
-    ...mapped,
-    _id: zid(name),
-    _creationTime: z.number()
-  })
-  const docArray = z.array(docSchema)
-
-  const base = Table(name, convexFields)
-  // Return with docSchema and docArray for backward compatibility
-  return { ...base, schema, docSchema, docArray }
-}

package/src/utils.ts

@@ -1,5 +1,6 @@
 import { ConvexError } from 'convex/values'
 import { z } from 'zod'
+import { getObjectShape } from './mapping'
 
 export function pick<T extends Record<string, any>, K extends keyof T>(
   obj: T,
@@ -97,15 +98,15 @@ function toKeys(mask: Mask): string[] {
   return Object.keys(mask).filter(k => !!(mask as any)[k])
 }
 
-// Returns a plain shape object containing only the selected fields.
-// Accepts either a ZodObject or a raw shape object.
+/**
+ * Returns a plain shape object containing only the selected fields.
+ * Accepts either a ZodObject or a raw shape object.
+ */
 export function pickShape(
   schemaOrShape: z.ZodObject<any> | Record<string, any>,
   mask: Mask
 ): Record<string, any> {
   const keys = toKeys(mask)
-  // Import getObjectShape lazily to avoid circular dependency
-  const { getObjectShape } = require('./mapping')
   const shape =
     schemaOrShape instanceof z.ZodObject ? getObjectShape(schemaOrShape) : schemaOrShape || {}
 
@@ -121,9 +122,11 @@ export function safePick(schema: z.ZodObject<any>, mask: Mask): z.ZodObject<any>
   return z.object(pickShape(schema, mask))
 }
 
-// Convenience: omit a set of keys by building the complement
+/**
+ * Convenience: omit a set of keys by building the complement.
+ * Avoids using Zod's .omit() which can cause type depth issues.
+ */
 export function safeOmit(schema: z.ZodObject<any>, mask: Mask): z.ZodObject<any> {
-  const { getObjectShape } = require('./mapping')
   const shape = getObjectShape(schema)
   const omit = new Set(toKeys(mask))
   const keep = Object.keys(shape).filter(k => !omit.has(k))