zodvex 0.2.4 → 0.3.1

package/package.json

@@ -1,16 +1,8 @@
 {
   "name": "zodvex",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "description": "Zod <=> Convex integration, supporting Zod 4",
-  "keywords": [
-    "zod",
-    "convex",
-    "validators",
-    "codec",
-    "mapping",
-    "schema",
-    "validation"
-  ],
+  "keywords": ["zod", "convex", "validators", "codec", "mapping", "schema", "validation"],
   "homepage": "https://github.com/panzacoder/zodvex#readme",
   "bugs": {
     "url": "https://github.com/panzacoder/zodvex/issues"
@@ -21,24 +13,22 @@
   },
   "license": "MIT",
   "author": "Jake Hebert",
+  "type": "module",
   "main": "./dist/index.js",
-  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": [
-    "dist",
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src", "README.md", "LICENSE"],
   "scripts": {
     "build": "tsup",
     "dev": "bun run tsup --watch",
     "type-check": "bun run tsc --noEmit",
     "test": "bun test",
-    "test:vitest": "bun run vitest",
-    "test:types": "bun run vitest --typecheck.only",
-    "test:all": "bun test && bun run test:types",
-    "test:coverage": "bun run vitest run --coverage",
     "lint": "bun x biome check src __tests__",
     "lint:fix": "bun x biome check --write src __tests__",
     "format": "bun x biome format --write src __tests__",
@@ -54,10 +44,9 @@
     "@biomejs/biome": "^2.2.6",
     "@types/bun": "^1.3.0",
     "@types/node": "^24.8.0",
-    "@vitest/coverage-v8": "^3.2.4",
+    "ai": "^6.0.6",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "typescript": "^5.9.3"
   },
   "engines": {
     "node": ">=20",

package/src/__type-tests__/infer-returns.ts

@@ -0,0 +1,154 @@
+/**
+ * Compile-time type tests for InferReturns (Issue #19)
+ *
+ * These assertions cause TypeScript errors if types don't match expectations.
+ * This file is type-checked but not included in the bundle.
+ */
+import { z } from 'zod'
+import type { InferReturns } from '../types'
+
+// Test helper: causes TS error if assigned `any`
+declare function expectNotAny<T>(value: 0 extends 1 & T ? never : T): void
+
+// --- Simple schemas should infer correctly ---
+
+declare const stringResult: InferReturns<z.ZodString>
+expectNotAny(stringResult)
+
+declare const objectResult: InferReturns<ReturnType<typeof z.object<{ name: z.ZodString }>>>
+expectNotAny(objectResult)
+
+// --- Union schemas: this is the Issue #19 bug ---
+// If InferReturns bails to `any` for unions, these will fail
+
+declare const unionSchema: z.ZodUnion<[z.ZodString, z.ZodNumber]>
+declare const unionResult: InferReturns<typeof unionSchema>
+// @ts-expect-error - If this errors with "unused directive", Result is `any` (the bug)
+const _unionInvalid: typeof unionResult = { notStringOrNumber: true }
+
+declare const literalUnionSchema: z.ZodUnion<[z.ZodLiteral<'a'>, z.ZodLiteral<'b'>]>
+declare const literalUnionResult: InferReturns<typeof literalUnionSchema>
+// @ts-expect-error - If this errors with "unused directive", Result is `any` (the bug)
+const _literalInvalid: typeof literalUnionResult = { notAOrB: true }
+
+// --- Complex/deeply nested schemas (stress tests for TS depth limits) ---
+// These tests ensure removing bailouts doesn't cause "Type instantiation is
+// excessively deep and possibly infinite" errors.
+
+// Deeply nested object (5 levels)
+const deeplyNestedSchema = z.object({
+  level1: z.object({
+    level2: z.object({
+      level3: z.object({
+        level4: z.object({
+          level5: z.object({
+            value: z.string()
+          })
+        })
+      })
+    })
+  })
+})
+declare const deeplyNestedResult: InferReturns<typeof deeplyNestedSchema>
+expectNotAny(deeplyNestedResult)
+
+// Large discriminated union (10 variants) - common in real apps
+const largeDiscriminatedUnion = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('variant1'), data: z.string() }),
+  z.object({ type: z.literal('variant2'), count: z.number() }),
+  z.object({ type: z.literal('variant3'), flag: z.boolean() }),
+  z.object({ type: z.literal('variant4'), items: z.array(z.string()) }),
+  z.object({ type: z.literal('variant5'), nested: z.object({ a: z.number() }) }),
+  z.object({ type: z.literal('variant6'), opt: z.string().optional() }),
+  z.object({ type: z.literal('variant7'), nullable: z.string().nullable() }),
+  z.object({ type: z.literal('variant8'), tuple: z.tuple([z.string(), z.number()]) }),
+  z.object({ type: z.literal('variant9'), record: z.record(z.string(), z.number()) }),
+  z.object({ type: z.literal('variant10'), union: z.union([z.string(), z.number()]) })
+])
+declare const largeUnionResult: InferReturns<typeof largeDiscriminatedUnion>
+expectNotAny(largeUnionResult)
+
+// Nested unions (union containing objects with union fields)
+const nestedUnionSchema = z.object({
+  outer: z.union([
+    z.object({
+      kind: z.literal('a'),
+      inner: z.union([z.literal('x'), z.literal('y')])
+    }),
+    z.object({
+      kind: z.literal('b'),
+      inner: z.union([z.literal('p'), z.literal('q')])
+    })
+  ])
+})
+declare const nestedUnionResult: InferReturns<typeof nestedUnionSchema>
+expectNotAny(nestedUnionResult)
+
+// Array of unions
+const arrayOfUnionsSchema = z.array(
+  z.union([
+    z.object({ type: z.literal('item'), value: z.string() }),
+    z.object({ type: z.literal('group'), children: z.array(z.string()) })
+  ])
+)
+declare const arrayOfUnionsResult: InferReturns<typeof arrayOfUnionsSchema>
+expectNotAny(arrayOfUnionsResult)
+
+// Real-world pattern: API response with polymorphic data
+const apiResponseSchema = z.object({
+  success: z.boolean(),
+  data: z
+    .union([
+      z.object({
+        type: z.literal('user'),
+        id: z.string(),
+        name: z.string(),
+        email: z.string().email(),
+        roles: z.array(z.enum(['admin', 'user', 'guest']))
+      }),
+      z.object({
+        type: z.literal('organization'),
+        id: z.string(),
+        name: z.string(),
+        members: z.array(
+          z.object({
+            userId: z.string(),
+            role: z.enum(['owner', 'admin', 'member'])
+          })
+        )
+      }),
+      z.object({
+        type: z.literal('error'),
+        code: z.number(),
+        message: z.string(),
+        details: z.record(z.string(), z.unknown()).optional()
+      })
+    ])
+    .nullable(),
+  meta: z.object({
+    timestamp: z.number(),
+    requestId: z.string()
+  })
+})
+declare const apiResponseResult: InferReturns<typeof apiResponseSchema>
+expectNotAny(apiResponseResult)
+
+// Recursive-like pattern (not truly recursive, but deep)
+const treeNodeSchema = z.object({
+  id: z.string(),
+  value: z.union([z.string(), z.number(), z.boolean()]),
+  children: z.array(
+    z.object({
+      id: z.string(),
+      value: z.union([z.string(), z.number(), z.boolean()]),
+      children: z.array(
+        z.object({
+          id: z.string(),
+          value: z.union([z.string(), z.number(), z.boolean()])
+        })
+      )
+    })
+  )
+})
+declare const treeNodeResult: InferReturns<typeof treeNodeSchema>
+expectNotAny(treeNodeResult)

package/src/custom.ts

@@ -178,13 +178,15 @@ export function customFnBuilder<
 
   return function customBuilder(fn: any): any {
     const { args, handler = fn, returns: maybeObject, ...extra } = fn
+    const skipConvexValidation = fn.skipConvexValidation ?? false
 
     const returns =
       maybeObject && !(maybeObject instanceof z.ZodType) ? z.object(maybeObject) : maybeObject
+    // Only generate Convex return validator when not skipping Convex validation
     const returnValidator =
-      returns && !fn.skipConvexValidation ? { returns: zodToConvex(returns) } : undefined
+      returns && !skipConvexValidation ? { returns: zodToConvex(returns) } : undefined
 
-    if (args && !fn.skipConvexValidation) {
+    if (args) {
       let argsValidator = args
       let argsSchema: z.ZodObject<any>
 
@@ -202,9 +204,13 @@ export function customFnBuilder<
         argsSchema = z.object(argsValidator)
       }
 
-      const convexValidator = zodToConvexFields(argsValidator)
+      // Only generate Convex args validator when not skipping Convex validation
+      const convexArgs = skipConvexValidation
+        ? inputArgs
+        : { ...zodToConvexFields(argsValidator), ...inputArgs }
+
       return builder({
-        args: { ...convexValidator, ...inputArgs },
+        args: convexArgs,
         ...returnValidator,
         handler: async (ctx: Ctx, allArgs: any) => {
           const added: any = await customInput(
@@ -215,6 +221,7 @@ export function customFnBuilder<
           const argKeys = Object.keys(argsValidator)
           const rawArgs = pick(allArgs, argKeys)
           const decoded = fromConvexJS(rawArgs, argsSchema)
+          // Always run Zod validation, regardless of skipConvexValidation
           const parsed = argsSchema.safeParse(decoded)
           if (!parsed.success) {
             handleZodValidationError(parsed.error, 'args')
@@ -224,7 +231,8 @@ export function customFnBuilder<
           const addedArgs = (added?.args as Record<string, unknown>) ?? {}
           const finalArgs = { ...baseArgs, ...addedArgs }
           const ret = await handler(finalCtx, finalArgs)
-          if (returns && !fn.skipConvexValidation) {
+          // Always run Zod return validation when returns schema is provided
+          if (returns) {
             let validated: any
             try {
               validated = (returns as z.ZodTypeAny).parse(ret)
@@ -261,7 +269,8 @@ export function customFnBuilder<
         const addedArgs = (added?.args as Record<string, unknown>) ?? {}
         const finalArgs = { ...baseArgs, ...addedArgs }
         const ret = await handler(finalCtx, finalArgs)
-        if (returns && !fn.skipConvexValidation) {
+        // Always run Zod return validation when returns schema is provided
+        if (returns) {
           let validated: any
           try {
             validated = (returns as z.ZodTypeAny).parse(ret)

package/src/ids.ts

@@ -16,23 +16,21 @@ export const registryHelpers = {
 /**
  * Create a Zod validator for a Convex Id
  *
- * Uses the string → transform → brand pattern for proper type narrowing with ctx.db.get()
- * This aligns with Zod v4 best practices and matches convex-helpers implementation
+ * Compatible with AI SDK and other tools that don't support transforms.
+ * Uses type-level branding instead of runtime transforms for GenericId<T> compatibility.
+ *
+ * @param tableName - The Convex table name for this ID
+ * @returns A Zod string validator typed as GenericId<TableName>
  */
 export function zid<TableName extends string>(
   tableName: TableName
 ): z.ZodType<GenericId<TableName>> & { _tableName: TableName } {
-  // Use the string → transform → brand pattern (aligned with Zod v4 best practices)
+  // Create base string validator with refinement (no transform or brand)
   const baseSchema = z
     .string()
     .refine(val => typeof val === 'string' && val.length > 0, {
       message: `Invalid ID for table "${tableName}"`
     })
-    .transform(val => {
-      // Cast to GenericId while keeping the string value
-      return val as string & GenericId<TableName>
-    })
-    .brand(`ConvexId_${tableName}`) // Use native Zod v4 .brand() method
     // Add a human-readable marker for client-side introspection utilities
     // used in apps/native (e.g., to detect relationship fields in dynamic forms).
     .describe(`convexId:${tableName}`)
@@ -47,6 +45,8 @@ export function zid<TableName extends string>(
   const branded = baseSchema as any
   branded._tableName = tableName
 
+  // Type assertion provides GenericId<TableName> typing without runtime transform
+  // This maintains type safety while being compatible with AI SDK and similar tools
   return branded as z.ZodType<GenericId<TableName>> & { _tableName: TableName }
 }
 

package/src/registry.ts

@@ -56,3 +56,174 @@ export function isDateSchema(schema: any): boolean {
 
   return false
 }
+
+// ============================================================================
+// JSON Schema Override Support
+// ============================================================================
+// Zod's toJSONSchema doesn't support transforms, brands, and other "unrepresentable"
+// types by default. This module provides overrides for zodvex-managed types
+// so they can be used with AI SDKs and other JSON Schema-based tools.
+
+/**
+ * Checks if a schema is a zid (Convex ID) schema by looking at its description.
+ * zid schemas are marked with "convexId:{tableName}" in their description.
+ */
+export function isZidSchema(schema: z.ZodTypeAny): boolean {
+  const description = schema.description
+  return typeof description === 'string' && description.startsWith('convexId:')
+}
+
+/**
+ * Extracts the table name from a zid schema's description.
+ * Returns undefined if not a zid schema.
+ */
+export function getZidTableName(schema: z.ZodTypeAny): string | undefined {
+  const description = schema.description
+  if (typeof description === 'string' && description.startsWith('convexId:')) {
+    return description.slice('convexId:'.length)
+  }
+  return undefined
+}
+
+/**
+ * Context object passed to the JSON Schema override function.
+ * Uses 'any' types for compatibility with Zod's internal types.
+ */
+export interface JSONSchemaOverrideContext {
+  zodSchema: any // Zod's internal $ZodTypes
+  jsonSchema: any // Zod's JSONSchema.BaseSchema
+}
+
+/**
+ * Override function for z.toJSONSchema that handles zodvex-managed types.
+ *
+ * Handles:
+ * - zid schemas: Converts to { type: "string" } with convexId format
+ * - z.date(): Converts to { type: "string", format: "date-time" }
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ * import { zid, zodvexJSONSchemaOverride } from 'zodvex'
+ *
+ * const schema = z.object({
+ *   userId: zid('users'),
+ *   name: z.string()
+ * })
+ *
+ * const jsonSchema = z.toJSONSchema(schema, {
+ *   unrepresentable: 'any',
+ *   override: zodvexJSONSchemaOverride
+ * })
+ * // => { type: "object", properties: { userId: { type: "string" }, name: { type: "string" } } }
+ * ```
+ */
+export function zodvexJSONSchemaOverride(ctx: JSONSchemaOverrideContext): void {
+  const { zodSchema, jsonSchema } = ctx
+
+  // Handle zid schemas (transforms with convexId description)
+  if (isZidSchema(zodSchema)) {
+    const tableName = getZidTableName(zodSchema)
+    // Set our properties - don't clear existing ones set by user overrides
+    // When unrepresentable: 'any', Zod already gives us {} so no clearing needed
+    jsonSchema.type = 'string'
+    if (tableName) {
+      jsonSchema.format = `convex-id:${tableName}`
+    }
+    // Preserve the description from .describe() - this is what the LLM sees
+    if (zodSchema.description) {
+      jsonSchema.description = zodSchema.description
+    }
+    return
+  }
+
+  // Handle z.date() - convert to ISO 8601 string format
+  // Zod v4 passes real schema instances here (ZodDate has `type === 'date'`).
+  if (zodSchema instanceof z.ZodDate || (zodSchema as any).type === 'date') {
+    jsonSchema.type = 'string'
+    jsonSchema.format = 'date-time'
+    return
+  }
+}
+
+/**
+ * Composes multiple JSON Schema override functions into one.
+ * Overrides run in order - first override runs first.
+ *
+ * @example
+ * ```ts
+ * import { composeOverrides, zodvexJSONSchemaOverride } from 'zodvex'
+ *
+ * const myOverride = (ctx) => {
+ *   if (ctx.zodSchema.description?.startsWith('myType:')) {
+ *     ctx.jsonSchema.type = 'string'
+ *     ctx.jsonSchema.format = 'my-format'
+ *   }
+ * }
+ *
+ * // User's override runs first, then zodvex's
+ * z.toJSONSchema(schema, {
+ *   unrepresentable: 'any',
+ *   override: composeOverrides(myOverride, zodvexJSONSchemaOverride)
+ * })
+ * ```
+ */
+export function composeOverrides(
+  ...overrides: Array<((ctx: JSONSchemaOverrideContext) => void) | undefined>
+): (ctx: JSONSchemaOverrideContext) => void {
+  return (ctx: JSONSchemaOverrideContext) => {
+    for (const override of overrides) {
+      override?.(ctx)
+    }
+  }
+}
+
+/**
+ * Options for toJSONSchema, matching Zod's interface.
+ */
+export interface ToJSONSchemaOptions {
+  target?: 'draft-4' | 'draft-7' | 'draft-2020-12' | 'openapi-3.0'
+  unrepresentable?: 'throw' | 'any'
+  cycles?: 'ref' | 'throw'
+  reused?: 'ref' | 'inline'
+  io?: 'input' | 'output'
+  override?: (ctx: JSONSchemaOverrideContext) => void
+}
+
+/**
+ * Converts a Zod schema to JSON Schema with zodvex-aware overrides.
+ *
+ * This is a convenience wrapper around z.toJSONSchema that automatically
+ * handles zodvex-managed types like zid and dates.
+ *
+ * @example
+ * ```ts
+ * import { zid, toJSONSchema } from 'zodvex'
+ *
+ * const schema = z.object({
+ *   userId: zid('users'),
+ *   createdAt: z.date(),
+ *   name: z.string()
+ * })
+ *
+ * const jsonSchema = toJSONSchema(schema)
+ * // Works with AI SDK's generateObject, etc.
+ * ```
+ */
+export function toJSONSchema<T extends z.ZodTypeAny>(
+  schema: T,
+  options?: ToJSONSchemaOptions
+): Record<string, any> {
+  const userOverride = options?.override
+
+  return z.toJSONSchema(schema, {
+    ...options,
+    // Default to 'any' so transforms don't throw
+    unrepresentable: options?.unrepresentable ?? 'any',
+    // Chain our override with user's override
+    override: ctx => {
+      zodvexJSONSchemaOverride(ctx)
+      userOverride?.(ctx)
+    }
+  })
+}