zodvex 0.2.4 → 0.3.1

package/src/tables.ts

@@ -1,8 +1,50 @@
+import { defineTable } from 'convex/server'
 import type { GenericId } from 'convex/values'
 import { Table } from 'convex-helpers/server'
 import { z } from 'zod'
 import { zid } from './ids'
-import { type ConvexValidatorFromZodFieldsAuto, zodToConvexFields } from './mapping'
+import { type ConvexValidatorFromZodFieldsAuto, zodToConvex, zodToConvexFields } from './mapping'
+
+/**
+ * Adds Convex system fields (_id, _creationTime) to a Zod schema.
+ *
+ * For object schemas: extends with system fields
+ * For union schemas: adds system fields to each variant
+ *
+ * @param tableName - The Convex table name
+ * @param schema - The Zod schema (object or union)
+ * @returns Schema with system fields added
+ */
+export function addSystemFields<T extends string, S extends z.ZodTypeAny>(
+  tableName: T,
+  schema: S
+): z.ZodTypeAny {
+  // Handle union schemas - add system fields to each variant
+  if (schema instanceof z.ZodUnion || schema instanceof z.ZodDiscriminatedUnion) {
+    const options = (schema as z.ZodUnion<any>).options.map((variant: z.ZodTypeAny) => {
+      if (variant instanceof z.ZodObject) {
+        return variant.extend({
+          _id: zid(tableName),
+          _creationTime: z.number()
+        })
+      }
+      // Non-object variants are returned as-is (shouldn't happen in practice)
+      return variant
+    })
+    return z.union(options as any)
+  }
+
+  // Handle object schemas
+  if (schema instanceof z.ZodObject) {
+    return schema.extend({
+      _id: zid(tableName),
+      _creationTime: z.number()
+    })
+  }
+
+  // Fallback: return schema as-is
+  return schema
+}
 
 // Helper to create a Zod schema for a Convex document
 export function zodDoc<
@@ -35,21 +77,43 @@ export function zodDocOrNull<
 }
 
 /**
- * Defines a Convex table using a raw Zod shape (an object mapping field names to Zod types).
+ * Helper to detect if input is an object shape (plain object with Zod validators)
+ */
+function isObjectShape(input: any): input is Record<string, z.ZodTypeAny> {
+  // Check if it's a plain object (not a Zod instance)
+  if (!input || typeof input !== 'object') return false
+
+  // If it's a Zod instance, it's not an object shape
+  if (input instanceof z.ZodType) return false
+
+  // Check if all values are Zod types
+  for (const key in input) {
+    if (!(input[key] instanceof z.ZodType)) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * Defines a Convex table using either:
+ * - A raw Zod shape (an object mapping field names to Zod types)
+ * - A Zod union schema (for polymorphic tables)
  *
- * This function intentionally accepts a raw shape instead of a ZodObject instance.
+ * For object shapes, this function intentionally accepts a raw shape instead of a ZodObject instance.
  * Accepting raw shapes allows TypeScript to infer field types more accurately and efficiently,
  * leading to better type inference and performance throughout the codebase.
- * 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.
+ *
+ * For union schemas, this enables polymorphic tables with discriminated unions.
  *
  * 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
+ * @param schemaOrShape - Either a raw object shape or a Zod union schema
+ * @returns A Table with attached helpers (shape, schema, zDoc, docArray, withSystemFields)
  *
- * @example
+ * @example Object shape
  * ```ts
  * const Users = zodTable('users', {
  *   name: z.string(),
@@ -66,36 +130,115 @@ export function zodDocOrNull<
  *   { returns: Users.docArray }
  * )
  * ```
+ *
+ * @example Union schema (polymorphic table)
+ * ```ts
+ * const shapeSchema = z.union([
+ *   z.object({ kind: z.literal('circle'), r: z.number() }),
+ *   z.object({ kind: z.literal('rectangle'), width: z.number() })
+ * ])
+ *
+ * const Shapes = zodTable('shapes', shapeSchema)
+ *
+ * // Use in schema
+ * export default defineSchema({ shapes: Shapes.table })
+ *
+ * // Use for return types with system fields
+ * export const getShapes = zQuery(query, {},
+ *   async (ctx) => ctx.db.query('shapes').collect(),
+ *   { returns: Shapes.docArray }
+ * )
+ * ```
  */
 export function zodTable<TableName extends string, Shape extends Record<string, z.ZodTypeAny>>(
   name: TableName,
   shape: Shape
-) {
-  // Convert fields with proper types
-  const convexFields = zodToConvexFields(shape) as ConvexValidatorFromZodFieldsAuto<Shape>
-
-  // Create the Table from convex-helpers with explicit type
-  const table = Table<ConvexValidatorFromZodFieldsAuto<Shape>, TableName>(name, convexFields)
-
-  // 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,
-    docArray
-  }) as typeof table & {
-    shape: Shape
-    zDoc: z.ZodObject<
+): ReturnType<typeof Table<any, TableName>> & {
+  shape: Shape
+  zDoc: z.ZodObject<
+    Shape & {
+      _id: ReturnType<typeof zid<TableName>>
+      _creationTime: z.ZodNumber
+    }
+  >
+  docArray: z.ZodArray<
+    z.ZodObject<
       Shape & {
         _id: ReturnType<typeof zid<TableName>>
         _creationTime: z.ZodNumber
       }
     >
-    docArray: z.ZodArray<typeof zDoc>
+  >
+}
+
+export function zodTable<TableName extends string, Schema extends z.ZodTypeAny>(
+  name: TableName,
+  schema: Schema
+): {
+  table: ReturnType<typeof defineTable>
+  tableName: TableName
+  validator: ReturnType<typeof zodToConvex<Schema>>
+  schema: Schema
+  docArray: z.ZodArray<ReturnType<typeof addSystemFields<TableName, Schema>>>
+  withSystemFields: () => ReturnType<typeof addSystemFields<TableName, Schema>>
+}
+
+export function zodTable<
+  TableName extends string,
+  SchemaOrShape extends z.ZodTypeAny | Record<string, z.ZodTypeAny>
+>(name: TableName, schemaOrShape: SchemaOrShape): any {
+  // Detect if it's an object shape or a schema
+  if (isObjectShape(schemaOrShape)) {
+    // Original object shape logic
+    const shape = schemaOrShape as Record<string, z.ZodTypeAny>
+
+    // Convert fields with proper types
+    const convexFields = zodToConvexFields(shape) as ConvexValidatorFromZodFieldsAuto<typeof shape>
+
+    // Create the Table from convex-helpers with explicit type
+    const table = Table<ConvexValidatorFromZodFieldsAuto<typeof shape>, TableName>(
+      name,
+      convexFields
+    )
+
+    // 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,
+      docArray
+    })
+  } else {
+    // Union or other schema type logic
+    const schema = schemaOrShape as z.ZodTypeAny
+
+    // Convert schema to Convex validator
+    const convexValidator = zodToConvex(schema)
+
+    // For unions, use defineTable directly (not Table helper which expects object fields)
+    // Note: TypeScript types don't reflect it, but Convex supports union validators in tables
+    const table = defineTable(convexValidator as any)
+
+    // Create document schema with system fields
+    const withFields = addSystemFields(name, schema)
+
+    // Create docArray helper
+    const docArray = z.array(withFields)
+
+    // Attach helpers for union tables
+    // Return structure similar to Table() but without fields-based helpers
+    return {
+      table,
+      tableName: name,
+      validator: convexValidator,
+      schema,
+      docArray,
+      withSystemFields: () => addSystemFields(name, schema)
+    }
   }
 }

package/src/types.ts

@@ -15,31 +15,19 @@ export type InferArgs<A> = A extends z.ZodObject<infer S>
       ? z.infer<A>
       : Record<string, never>
 
-// Return type inference with immediate bailout for unions/custom to avoid depth
-export type InferReturns<R> = R extends z.ZodUnion<any>
-  ? any
-  : // Bail immediately for unions
-    R extends z.ZodCustom<any>
+// Return type inference - uses z.output for Zod schemas
+// Previously had bailouts for unions/custom to avoid TypeScript depth errors,
+// but research (Issue #20) showed convex-helpers handles these without issues.
+// Removing bailouts fixes Issue #19 (Promise<any> return types).
+export type InferReturns<R> = R extends z.ZodType<any, any, any>
+  ? z.output<R>
+  : R extends undefined
     ? any
-    : // Bail immediately for custom
-      R extends z.ZodType<any, any, any>
-      ? z.output<R>
-      : // Use z.output for other schemas
-        R extends undefined
-        ? any
-        : R
+    : R
 
 // For handler authoring: what the handler returns before wrapper validation/encoding
-export type InferHandlerReturns<R> = R extends z.ZodUnion<any>
-  ? any
-  : // Bail immediately for unions
-    R extends z.ZodCustom<any>
-    ? any
-    : // Bail immediately for custom
-      R extends z.ZodType<any, any, any>
-      ? z.input<R>
-      : // Use z.input for other schemas
-        any
+// Uses z.input since this is what the handler produces before encoding
+export type InferHandlerReturns<R> = R extends z.ZodType<any, any, any> ? z.input<R> : any
 
 /**
  * Extract the visibility type from a Convex builder function

package/src/wrappers.ts

@@ -39,8 +39,8 @@ function containsCustom(schema: z.ZodTypeAny, maxDepth = 50, currentDepth = 0):
 
   let result = false
 
-  // Use _def.typeName instead of instanceof since ZodCustom is not exported in Zod v4
-  if ((schema as any)._def?.typeName === 'ZodCustom') {
+  // Zod v4 exports ZodCustom and instances expose `schema.type === "custom"`.
+  if (schema instanceof z.ZodCustom) {
     result = true
   } else if (schema instanceof z.ZodUnion) {
     result = (schema.options as z.ZodTypeAny[]).some(opt =>