zodvex 0.3.2 → 0.4.1

package/src/transform/traverse.ts

@@ -0,0 +1,320 @@
+/**
+ * Schema traversal utilities.
+ *
+ * General-purpose utilities for walking and inspecting Zod schemas.
+ */
+
+import type { z } from 'zod'
+import type { FieldInfo, SchemaVisitor, WalkSchemaOptions } from './types'
+
+const METADATA_CACHE = new WeakMap<z.ZodTypeAny, Record<string, unknown> | undefined>()
+
+/**
+ * Metadata key for ZodSensitive wrappers.
+ */
+const SENSITIVE_META_KEY = 'zodvex:sensitive'
+
+/**
+ * Duck-type check for ZodSensitive wrapper.
+ */
+function isZodSensitiveDef(schema: any): boolean {
+  return schema?._def?.type === 'sensitive' && typeof schema?.unwrap === 'function'
+}
+
+/**
+ * Get metadata from a Zod schema.
+ *
+ * Handles both Zod's native .meta() and ZodSensitive wrappers.
+ *
+ * @example
+ * ```ts
+ * const schema = z.string().meta({ encrypted: true })
+ * const meta = getMetadata(schema)
+ * // => { encrypted: true }
+ * ```
+ */
+export function getMetadata(schema: z.ZodTypeAny): Record<string, unknown> | undefined {
+  if (METADATA_CACHE.has(schema)) {
+    return METADATA_CACHE.get(schema)
+  }
+
+  const visited = new Set<z.ZodTypeAny>()
+  let current: z.ZodTypeAny | undefined = schema
+
+  while (current) {
+    if (visited.has(current)) return undefined
+    visited.add(current)
+
+    // Fast path: ZodSensitive wrapper stores metadata directly
+    if (isZodSensitiveDef(current)) {
+      const sensitiveMeta = (current as any)._def.sensitiveMetadata
+      const meta = { [SENSITIVE_META_KEY]: sensitiveMeta }
+      METADATA_CACHE.set(schema, meta)
+      return meta
+    }
+
+    const meta = current.meta?.() as Record<string, unknown> | undefined
+    if (meta !== undefined) {
+      METADATA_CACHE.set(schema, meta)
+      return meta
+    }
+
+    current = unwrapOnce(current)
+  }
+
+  METADATA_CACHE.set(schema, undefined)
+  return undefined
+}
+
+function unwrapOnce(schema: z.ZodTypeAny): z.ZodTypeAny | undefined {
+  const defType = (schema as any)._def?.type as string | undefined
+
+  switch (defType) {
+    case 'sensitive': {
+      // ZodSensitive wrapper - unwrap to inner schema
+      if (typeof (schema as any).unwrap === 'function') {
+        return (schema as any).unwrap()
+      }
+      return (schema as any)._def?.innerType
+    }
+
+    case 'optional':
+    case 'nullable': {
+      if (typeof (schema as any).unwrap === 'function') {
+        return (schema as any).unwrap()
+      }
+      return (schema as any)._def?.innerType
+    }
+
+    case 'lazy': {
+      const getter = (schema as any)._def?.getter
+      if (typeof getter === 'function') {
+        return getter()
+      }
+      return undefined
+    }
+
+    case 'default':
+    case 'catch':
+    case 'readonly':
+    case 'prefault':
+    case 'nonoptional': {
+      return (schema as any)._def?.innerType
+    }
+
+    case 'pipe': {
+      return (schema as any)._def?.in
+    }
+
+    default:
+      return undefined
+  }
+}
+
+/**
+ * Check if a schema has metadata matching a predicate.
+ *
+ * @example
+ * ```ts
+ * const schema = z.string().meta({ sensitive: true })
+ * hasMetadata(schema, meta => meta.sensitive === true)
+ * // => true
+ * ```
+ */
+export function hasMetadata(
+  schema: z.ZodTypeAny,
+  predicate: (meta: Record<string, unknown>) => boolean
+): boolean {
+  const meta = getMetadata(schema)
+  return meta !== undefined && predicate(meta)
+}
+
+/**
+ * Walk a Zod schema, calling visitor functions for each node.
+ *
+ * Handles: objects, arrays, optionals, nullables, unions, discriminated unions.
+ * Prevents infinite recursion on circular schema references.
+ *
+ * @example
+ * ```ts
+ * walkSchema(userSchema, {
+ *   onField: (info) => {
+ *     if (info.meta?.encrypted) {
+ *       console.log(`Encrypted field: ${info.path}`)
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export function walkSchema(
+  schema: z.ZodTypeAny,
+  visitor: SchemaVisitor,
+  options?: WalkSchemaOptions
+): void {
+  const recursionStack = new Set<z.ZodTypeAny>()
+  const basePath = options?.path ?? ''
+
+  function traverse(sch: z.ZodTypeAny, currentPath: string, isOptional: boolean): void {
+    // Prevent infinite recursion on circular schema references
+    if (recursionStack.has(sch)) return
+    recursionStack.add(sch)
+
+    try {
+      const defType = (sch as any)._def?.type as string | undefined
+      const meta = getMetadata(sch)
+      const info: FieldInfo = { path: currentPath, schema: sch, meta, isOptional }
+
+      // Call onField for every schema node
+      if (visitor.onField) {
+        const result = visitor.onField(info)
+        if (result === 'skip') return
+      }
+
+      // Dispatch based on schema type
+      switch (defType) {
+        case 'sensitive': {
+          // ZodSensitive wrapper - already reported via onField, now traverse inner
+          const inner = (sch as any).unwrap?.() ?? (sch as any)._def?.innerType
+          if (inner) {
+            traverse(inner, currentPath, isOptional)
+          }
+          return
+        }
+
+        case 'optional': {
+          const inner = (sch as any).unwrap()
+          traverse(inner, currentPath, true)
+          return
+        }
+
+        case 'nullable': {
+          const inner = (sch as any).unwrap()
+          traverse(inner, currentPath, isOptional)
+          return
+        }
+
+        case 'lazy': {
+          const getter = (sch as any)._def?.getter
+          if (typeof getter === 'function') {
+            const inner = getter()
+            traverse(inner, currentPath, isOptional)
+          }
+          return
+        }
+
+        case 'default':
+        case 'catch':
+        case 'readonly':
+        case 'prefault':
+        case 'nonoptional': {
+          const inner = (sch as any)._def?.innerType as z.ZodTypeAny | undefined
+          if (inner) {
+            traverse(inner, currentPath, isOptional)
+          }
+          return
+        }
+
+        case 'pipe': {
+          const inner = (sch as any)._def?.in as z.ZodTypeAny | undefined
+          if (inner) {
+            traverse(inner, currentPath, isOptional)
+          }
+          return
+        }
+
+        case 'object': {
+          visitor.onObject?.(info)
+          const shape = (sch as any).shape
+          if (shape) {
+            for (const [key, fieldSchema] of Object.entries(shape)) {
+              const fieldPath = currentPath ? `${currentPath}.${key}` : key
+              traverse(fieldSchema as z.ZodTypeAny, fieldPath, false)
+            }
+          }
+          return
+        }
+
+        case 'array': {
+          visitor.onArray?.(info)
+          const element = (sch as any).element
+          if (element) {
+            const arrayPath = currentPath ? `${currentPath}[]` : '[]'
+            traverse(element, arrayPath, false)
+          }
+          return
+        }
+
+        case 'union': {
+          const unionOptions = (sch as any)._def.options as z.ZodTypeAny[] | undefined
+
+          // Get options from either _def.options or _def.optionsMap
+          const variantOptions =
+            unionOptions ||
+            ((sch as any)._def.optionsMap ? Array.from((sch as any)._def.optionsMap.values()) : [])
+
+          visitor.onUnion?.(info, variantOptions as z.ZodTypeAny[])
+
+          for (const variant of variantOptions as z.ZodTypeAny[]) {
+            traverse(variant, currentPath, isOptional)
+          }
+          return
+        }
+      }
+
+      // Primitives and other types are leaf nodes - nothing more to traverse
+    } finally {
+      recursionStack.delete(sch)
+    }
+  }
+
+  traverse(schema, basePath, false)
+}
+
+/**
+ * Find all fields in a schema where metadata matches a predicate.
+ *
+ * @overload Type guard version - returns narrowed meta type
+ */
+export function findFieldsWithMeta<TMeta extends Record<string, unknown>>(
+  schema: z.ZodTypeAny,
+  predicate: (meta: Record<string, unknown> | undefined) => meta is TMeta
+): Array<FieldInfo & { meta: TMeta }>
+
+/**
+ * @overload Boolean predicate version
+ */
+export function findFieldsWithMeta(
+  schema: z.ZodTypeAny,
+  predicate: (meta: Record<string, unknown> | undefined) => boolean
+): FieldInfo[]
+
+/**
+ * Find all fields in a schema where metadata matches a predicate.
+ *
+ * @example
+ * ```ts
+ * // Find all fields with 'sensitive' metadata
+ * const sensitiveFields = findFieldsWithMeta(
+ *   userSchema,
+ *   (meta) => meta?.sensitive === true
+ * )
+ * // => [{ path: 'email', schema: z.string(), meta: { sensitive: true } }, ...]
+ * ```
+ */
+export function findFieldsWithMeta(
+  schema: z.ZodTypeAny,
+  predicate: (meta: Record<string, unknown> | undefined) => boolean
+): FieldInfo[] {
+  const results: FieldInfo[] = []
+
+  walkSchema(schema, {
+    onField: info => {
+      if (predicate(info.meta)) {
+        results.push(info)
+        return 'skip' // Don't recurse into matching fields
+      }
+    }
+  })
+
+  return results
+}

package/src/transform/types.ts

@@ -0,0 +1,128 @@
+/**
+ * Transform layer type definitions.
+ *
+ * General-purpose types for schema traversal and value transformation.
+ */
+
+import type { z } from 'zod'
+
+/**
+ * Information about a field during schema traversal.
+ */
+export type FieldInfo = {
+  /** Dot-notation path (e.g., 'profile.email', 'contacts[].email') */
+  path: string
+  /** The Zod schema for this field */
+  schema: z.ZodTypeAny
+  /** Metadata from schema.meta() if present */
+  meta: Record<string, unknown> | undefined
+  /** Whether the field is wrapped in optional/nullable */
+  isOptional: boolean
+}
+
+/**
+ * Visitor functions for walkSchema().
+ */
+export type SchemaVisitor = {
+  /** Called for every field. Return 'skip' to skip children. */
+  onField?: (info: FieldInfo) => void | 'skip'
+  /** Called when entering an object schema */
+  onObject?: (info: FieldInfo) => void
+  /** Called when entering an array schema */
+  onArray?: (info: FieldInfo) => void
+  /** Called when entering a union schema */
+  onUnion?: (info: FieldInfo, variants: z.ZodTypeAny[]) => void
+}
+
+/**
+ * Options for walkSchema().
+ */
+export type WalkSchemaOptions = {
+  /** Starting path prefix */
+  path?: string
+}
+
+/**
+ * Context passed to transform functions.
+ */
+export type TransformContext<TCtx = unknown> = {
+  /** Current field path */
+  path: string
+  /** The Zod schema for this field */
+  schema: z.ZodTypeAny
+  /** Metadata from schema.meta() if present */
+  meta: Record<string, unknown> | undefined
+  /** User-provided context */
+  ctx: TCtx
+}
+
+/**
+ * Synchronous transform function signature.
+ */
+export type TransformFn<TCtx = unknown> = (
+  value: unknown,
+  context: TransformContext<TCtx>
+) => unknown
+
+/**
+ * Async transform function signature.
+ */
+export type AsyncTransformFn<TCtx = unknown> = (
+  value: unknown,
+  context: TransformContext<TCtx>
+) => unknown | Promise<unknown>
+
+/**
+ * Options for transformBySchema().
+ */
+export type TransformOptions = {
+  /** Starting path prefix */
+  path?: string
+  /**
+   * How to handle values that don't match any union variant.
+   * - 'passthrough': Return value unchanged (default)
+   * - 'error': Throw an error
+   * - 'null': Replace with null (fail-closed for security)
+   */
+  unmatchedUnion?: 'passthrough' | 'error' | 'null'
+  /** Callback when a union doesn't match */
+  onUnmatchedUnion?: (path: string) => void
+  /**
+   * Fast predicate to check if a schema needs transformation.
+   *
+   * When provided, this predicate is called before the transform callback.
+   * If it returns false, the transform callback is skipped for this schema
+   * (but recursion into children continues).
+   *
+   * This optimization avoids callback overhead for schemas that don't need
+   * transformation, which is useful when only a small subset of fields
+   * require processing (e.g., only sensitive fields).
+   *
+   * @example
+   * ```ts
+   * // Only call transform for schemas with sensitive metadata
+   * transformBySchema(value, schema, ctx, transform, {
+   *   shouldTransform: (sch) => getSensitiveMetadata(sch) !== undefined
+   * })
+   * ```
+   */
+  shouldTransform?: (schema: z.ZodTypeAny) => boolean
+  /**
+   * Process array elements in parallel (async only).
+   *
+   * When true, array elements are processed with Promise.all() instead of
+   * sequentially. This can significantly improve performance for large arrays
+   * when transforms involve async operations like entitlement checks.
+   *
+   * Default: false (sequential processing for backwards compatibility)
+   *
+   * @example
+   * ```ts
+   * // Process user entitlements for all items in parallel
+   * const result = await transformBySchemaAsync(docs, schema, ctx, transform, {
+   *   parallel: true
+   * })
+   * ```
+   */
+  parallel?: boolean
+}

package/src/types.ts

@@ -26,8 +26,9 @@ export type InferReturns<R> = R extends z.ZodType<any, any, any>
     : R
 
 // For handler authoring: what the handler returns before wrapper validation/encoding
-// 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
+// Uses z.output since the handler produces the internal representation (e.g., Date),
+// which is then encoded to wire format (e.g., string) before sending to the client
+export type InferHandlerReturns<R> = R extends z.ZodType<any, any, any> ? z.output<R> : any
 
 /**
  * Extract the visibility type from a Convex builder function

package/src/utils.ts

@@ -48,6 +48,41 @@ export function handleZodValidationError(
   throw e
 }
 
+/**
+ * Validates a return value against a Zod schema, supporting both codecs and regular schemas.
+ *
+ * Tries z.encode() first (for codec support), then falls back to .parse() if the schema
+ * contains unidirectional transforms (which don't support encoding).
+ *
+ * For codecs: returns the encoded wire format (z.input<T>)
+ * For transforms: returns the transformed output (z.output<T>)
+ * For plain schemas: returns the validated value
+ *
+ * @param schema - The Zod schema to validate against
+ * @param value - The value to validate
+ * @returns The validated/encoded value
+ * @throws Calls handleZodValidationError on validation failure
+ */
+export function validateReturns(schema: z.ZodTypeAny, value: unknown): unknown {
+  try {
+    // Try encode first - works for codecs and plain schemas
+    return z.encode(schema, value)
+  } catch (e: any) {
+    // If it's a unidirectional transform error, fall back to parse
+    if (e?.message?.includes('unidirectional transform')) {
+      try {
+        return schema.parse(value)
+      } catch (parseError) {
+        handleZodValidationError(parseError, 'returns')
+      }
+    }
+    // For any other error, handle it normally
+    handleZodValidationError(e, 'returns')
+  }
+  // TypeScript can't infer that handleZodValidationError always throws
+  throw new Error('Unreachable')
+}
+
 // Helper: standard Convex paginate() result schema
 export function zPaginated<T extends z.ZodTypeAny>(item: T) {
   return z.object({

package/src/wrappers.ts

@@ -16,7 +16,7 @@ import type {
   InferReturns,
   ZodToConvexArgs
 } from './types'
-import { handleZodValidationError } from './utils'
+import { handleZodValidationError, validateReturns } from './utils'
 
 // Cache to avoid re-checking the same schema
 const customCheckCache = new WeakMap<z.ZodTypeAny, boolean>()
@@ -103,12 +103,9 @@ export function zQuery<
       }
       const raw = await handler(ctx, parsed)
       if (options?.returns) {
-        try {
-          const validated = (options.returns as z.ZodTypeAny).parse(raw)
-          return toConvexJS(options.returns as z.ZodTypeAny, validated)
-        } catch (e) {
-          handleZodValidationError(e, 'returns')
-        }
+        // Validate using encode (for codecs) with fallback to parse (for transforms)
+        const validated = validateReturns(options.returns as z.ZodTypeAny, raw)
+        return toConvexJS(options.returns as z.ZodTypeAny, validated)
       }
       // Fallback: ensure Convex-safe return values (e.g., Date → timestamp)
       return toConvexJS(raw) as any
@@ -177,12 +174,9 @@ export function zMutation<
       }
       const raw = await handler(ctx, parsed)
       if (options?.returns) {
-        try {
-          const validated = (options.returns as z.ZodTypeAny).parse(raw)
-          return toConvexJS(options.returns as z.ZodTypeAny, validated)
-        } catch (e) {
-          handleZodValidationError(e, 'returns')
-        }
+        // Validate using encode (for codecs) with fallback to parse (for transforms)
+        const validated = validateReturns(options.returns as z.ZodTypeAny, raw)
+        return toConvexJS(options.returns as z.ZodTypeAny, validated)
       }
       // Fallback: ensure Convex-safe return values (e.g., Date → timestamp)
       return toConvexJS(raw) as any
@@ -251,12 +245,9 @@ export function zAction<
       }
       const raw = await handler(ctx, parsed)
       if (options?.returns) {
-        try {
-          const validated = (options.returns as z.ZodTypeAny).parse(raw)
-          return toConvexJS(options.returns as z.ZodTypeAny, validated)
-        } catch (e) {
-          handleZodValidationError(e, 'returns')
-        }
+        // Validate using encode (for codecs) with fallback to parse (for transforms)
+        const validated = validateReturns(options.returns as z.ZodTypeAny, raw)
+        return toConvexJS(options.returns as z.ZodTypeAny, validated)
       }
       // Fallback: ensure Convex-safe return values (e.g., Date → timestamp)
       return toConvexJS(raw) as any