zodvex 0.3.2 → 0.4.1

package/src/custom.ts

@@ -16,7 +16,133 @@ import { z } from 'zod'
 import { fromConvexJS, toConvexJS } from './codec'
 import { type ZodValidator, zodToConvex, zodToConvexFields } from './mapping'
 import type { ExtractCtx, ExtractVisibility } from './types'
-import { handleZodValidationError, pick } from './utils'
+import { handleZodValidationError, pick, validateReturns } from './utils'
+
+/**
+ * Hooks for observing the function execution (side effects, no return value).
+ */
+export type CustomizationHooks = {
+  /** Called after successful execution with access to ctx, args, and result */
+  onSuccess?: (info: {
+    ctx: unknown
+    args: Record<string, unknown>
+    result: unknown
+  }) => void | Promise<void>
+}
+
+/**
+ * Transforms for modifying data in the function flow.
+ */
+export type CustomizationTransforms = {
+  /** Transform args after validation but before handler receives them */
+  input?: (args: unknown, schema: z.ZodTypeAny) => unknown | Promise<unknown>
+  /** Transform the output after validation but before wire encoding */
+  output?: (result: unknown, schema: z.ZodTypeAny) => unknown | Promise<unknown>
+}
+
+/**
+ * Result returned from a customization input function.
+ * Separates Convex concepts (ctx, args) from hooks (side effects) and transforms (data modifications).
+ */
+export type CustomizationResult<
+  CustomCtx extends Record<string, any> = Record<string, any>,
+  CustomArgs extends Record<string, any> = Record<string, any>
+> = {
+  /** Custom context to merge with base context */
+  ctx?: CustomCtx
+  /** Custom args to merge with parsed args */
+  args?: CustomArgs
+  /** Hooks for observing execution (side effects) */
+  hooks?: CustomizationHooks
+  /** Transforms for modifying the data flow */
+  transforms?: CustomizationTransforms
+}
+
+/**
+ * Extended input result that includes hooks and transforms.
+ * This is what the input function returns internally.
+ */
+export type CustomizationInputResult<
+  OutCtx extends Record<string, any>,
+  OutArgs extends Record<string, any>
+> = {
+  ctx: OutCtx
+  args: OutArgs
+  hooks?: CustomizationHooks
+  transforms?: CustomizationTransforms
+}
+
+/**
+ * Customization type that supports hooks and transforms.
+ * This extends convex-helpers' Customization pattern to include
+ * hooks (side effects) and transforms (data modifications).
+ *
+ * Use customCtxWithHooks() to create instances of this type.
+ */
+export type CustomizationWithHooks<
+  InCtx extends Record<string, any>,
+  OutCtx extends Record<string, any> = Record<string, any>,
+  OutArgs extends Record<string, any> = Record<string, any>,
+  ExtraArgs extends Record<string, any> = Record<string, any>
+> = {
+  args: Record<string, never>
+  input: (
+    ctx: InCtx,
+    args?: Record<string, unknown>,
+    extra?: ExtraArgs
+  ) =>
+    | Promise<CustomizationInputResult<OutCtx, OutArgs>>
+    | CustomizationInputResult<OutCtx, OutArgs>
+}
+
+/**
+ * A helper for defining a Customization with full support for hooks and transforms.
+ * Use this instead of customCtx when you need onSuccess, transforms.input, transforms.output, etc.
+ *
+ * @example
+ * ```ts
+ * const secureMutation = zCustomMutationBuilder(
+ *   mutation,
+ *   customCtxWithHooks(async (ctx: MutationCtx) => {
+ *     const securityCtx = await getSecurityContext(ctx)
+ *     return {
+ *       ctx: { securityCtx },
+ *       hooks: {
+ *         onSuccess: ({ result }) => console.log('Mutation returned:', result),
+ *       },
+ *       transforms: {
+ *         // Transform incoming args (e.g., wire format → runtime objects)
+ *         input: (args, schema) => transformIncomingArgs(args, securityCtx),
+ *         // Transform outgoing result (e.g., runtime objects → wire format)
+ *         output: (result, schema) => transformOutgoingResult(result, securityCtx),
+ *       },
+ *     }
+ *   })
+ * )
+ * ```
+ */
+export function customCtxWithHooks<
+  InCtx extends Record<string, any>,
+  OutCtx extends Record<string, any> = Record<string, any>,
+  OutArgs extends Record<string, any> = Record<string, any>
+>(
+  fn: (
+    ctx: InCtx
+  ) => Promise<CustomizationResult<OutCtx, OutArgs>> | CustomizationResult<OutCtx, OutArgs>
+): CustomizationWithHooks<InCtx, OutCtx, OutArgs> {
+  return {
+    args: {},
+    input: async (ctx: InCtx): Promise<CustomizationInputResult<OutCtx, OutArgs>> => {
+      const result = await fn(ctx)
+      return {
+        ctx: result.ctx ?? ({} as OutCtx),
+        args: result.args ?? ({} as OutArgs),
+        hooks: result.hooks,
+        transforms: result.transforms
+      }
+    }
+  }
+}
 
 // Type helpers for args transformation (from zodV3 example)
 type OneArgArray<ArgsObject extends DefaultFunctionArgs = DefaultFunctionArgs> = [ArgsObject]
@@ -26,12 +152,14 @@ type NullToUndefinedOrNull<T> = T extends null ? T | undefined | void : T
 type Returns<T> = Promise<NullToUndefinedOrNull<T>> | NullToUndefinedOrNull<T>
 
 // The return value before it's been validated: returned by the handler
+// 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
 type ReturnValueInput<ReturnsValidator extends z.ZodTypeAny | ZodValidator | void> = [
   ReturnsValidator
 ] extends [z.ZodTypeAny]
-  ? Returns<z.input<ReturnsValidator>>
+  ? Returns<z.output<ReturnsValidator>>
   : [ReturnsValidator] extends [ZodValidator]
-    ? Returns<z.input<z.ZodObject<ReturnsValidator>>>
+    ? Returns<z.output<z.ZodObject<ReturnsValidator>>>
     : any
 
 // The return value after it's been validated: returned to the client
@@ -171,7 +299,9 @@ export function customFnBuilder<
   ExtraArgs extends Record<string, any> = Record<string, any>
 >(
   builder: Builder,
-  customization: Customization<Ctx, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
+  customization:
+    | Customization<Ctx, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
+    | CustomizationWithHooks<Ctx, CustomCtx, CustomMadeArgs, ExtraArgs>
 ) {
   const customInput = customization.input ?? NoOp.input
   const inputArgs = customization.args ?? NoOp.args
@@ -213,6 +343,13 @@ export function customFnBuilder<
         args: convexArgs,
         ...returnValidator,
         handler: async (ctx: Ctx, allArgs: any) => {
+          // Cast justification: customInput expects ObjectType<CustomArgsValidator>, but pick()
+          // returns Partial<T>. The cast is safe because inputArgs keys are derived from
+          // CustomArgsValidator at the type level. The 'added' result is typed as 'any' because
+          // it may include hooks/transforms from CustomizationWithHooks which aren't in the
+          // convex-helpers Customization type.
+          // TODO: Create a type-safe pickArgs<T>() helper that preserves the ObjectType<T>
+          // return type when the keys are statically known from the validator.
           const added: any = await customInput(
             ctx,
             pick(allArgs, Object.keys(inputArgs)) as any,
@@ -229,18 +366,30 @@ export function customFnBuilder<
           const finalCtx = { ...ctx, ...(added?.ctx ?? {}) }
           const baseArgs = parsed.data as Record<string, unknown>
           const addedArgs = (added?.args as Record<string, unknown>) ?? {}
-          const finalArgs = { ...baseArgs, ...addedArgs }
+          let finalArgs = { ...baseArgs, ...addedArgs }
+
+          // Apply input transform if provided (after validation, before handler)
+          if (added?.transforms?.input) {
+            finalArgs = (await added.transforms.input(finalArgs, argsSchema)) as Record<
+              string,
+              unknown
+            >
+          }
+
           const ret = await handler(finalCtx, finalArgs)
           // Always run Zod return validation when returns schema is provided
           if (returns) {
-            let validated: any
-            try {
-              validated = (returns as z.ZodTypeAny).parse(ret)
-            } catch (e) {
-              handleZodValidationError(e, 'returns')
-            }
-            if (added?.onSuccess) {
-              await added.onSuccess({
+            // Apply output transform BEFORE validation (converts internal format → wire format)
+            // This allows class instances (e.g., SensitiveField) to be converted to plain objects
+            // before validation processes them
+            const preTransformed = added?.transforms?.output
+              ? await added.transforms.output(ret, returns as z.ZodTypeAny)
+              : ret
+
+            // Validate using encode (for codecs) with fallback to parse (for transforms)
+            const validated = validateReturns(returns as z.ZodTypeAny, preTransformed)
+            if (added?.hooks?.onSuccess) {
+              await added.hooks.onSuccess({
                 ctx,
                 args: parsed.data,
                 result: validated
@@ -248,8 +397,8 @@ export function customFnBuilder<
             }
             return toConvexJS(returns as z.ZodTypeAny, validated)
           }
-          if (added?.onSuccess) {
-            await added.onSuccess({ ctx, args: parsed.data, result: ret })
+          if (added?.hooks?.onSuccess) {
+            await added.hooks.onSuccess({ ctx, args: parsed.data, result: ret })
           }
           return ret
         }
@@ -259,6 +408,9 @@ export function customFnBuilder<
       args: inputArgs,
       ...returnValidator,
       handler: async (ctx: Ctx, allArgs: any) => {
+        // Cast justification: Same as above - customInput expects ObjectType<CustomArgsValidator>
+        // but pick() returns Partial<T>. Safe because inputArgs keys match CustomArgsValidator.
+        // TODO: Create a type-safe pickArgs<T>() helper (see comment in with-args path above).
         const added: any = await customInput(
           ctx,
           pick(allArgs, Object.keys(inputArgs)) as any,
@@ -267,23 +419,36 @@ export function customFnBuilder<
         const finalCtx = { ...ctx, ...(added?.ctx ?? {}) }
         const baseArgs = allArgs as Record<string, unknown>
         const addedArgs = (added?.args as Record<string, unknown>) ?? {}
-        const finalArgs = { ...baseArgs, ...addedArgs }
+        let finalArgs = { ...baseArgs, ...addedArgs }
+
+        // Apply input transform if provided (even without args schema)
+        // Note: schema is z.unknown() in no-args path, transform should handle this
+        if (added?.transforms?.input) {
+          finalArgs = (await added.transforms.input(finalArgs, z.unknown())) as Record<
+            string,
+            unknown
+          >
+        }
+
         const ret = await handler(finalCtx, finalArgs)
         // Always run Zod return validation when returns schema is provided
         if (returns) {
-          let validated: any
-          try {
-            validated = (returns as z.ZodTypeAny).parse(ret)
-          } catch (e) {
-            handleZodValidationError(e, 'returns')
-          }
-          if (added?.onSuccess) {
-            await added.onSuccess({ ctx, args: allArgs, result: validated })
+          // Apply output transform BEFORE validation (converts internal format → wire format)
+          // This allows class instances (e.g., SensitiveField) to be converted to plain objects
+          // before validation processes them
+          const preTransformed = added?.transforms?.output
+            ? await added.transforms.output(ret, returns as z.ZodTypeAny)
+            : ret
+
+          // Validate using encode (for codecs) with fallback to parse (for transforms)
+          const validated = validateReturns(returns as z.ZodTypeAny, preTransformed)
+          if (added?.hooks?.onSuccess) {
+            await added.hooks.onSuccess({ ctx, args: allArgs, result: validated })
           }
           return toConvexJS(returns as z.ZodTypeAny, validated)
         }
-        if (added?.onSuccess) {
-          await added.onSuccess({ ctx, args: allArgs, result: ret })
+        if (added?.hooks?.onSuccess) {
+          await added.hooks.onSuccess({ ctx, args: allArgs, result: ret })
         }
         return ret
       }
@@ -343,8 +508,16 @@ export function zCustomQuery<
   query: QueryBuilder<any, Visibility>,
   customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
 ) {
-  // Implementation deliberately uses 'any' ctx to preserve overload behavior
-  // while avoiding a GenericDataModel constraint at the implementation level.
+  // Cast justification: This is the TypeScript overload implementation pattern. The function
+  // has two overloads (with/without DataModel constraint) that provide precise types to callers.
+  // The implementation must satisfy both overloads, which requires a broader signature.
+  // The 'as any' casts allow the implementation to delegate to customFnBuilder without
+  // TypeScript complaining about the generic parameter differences between overloads.
+  // This is type-safe because: (1) callers only see the overload signatures which are strict,
+  // (2) the runtime behavior is identical regardless of which overload matched.
+  // TODO: Consider using a conditional type or branded types to create a single signature
+  // that satisfies both overloads without casts. Alternatively, accept this as idiomatic
+  // TypeScript for overloaded functions and keep the casts.
   return customFnBuilder<
     any,
     typeof query,
@@ -388,6 +561,8 @@ export function zCustomMutation<
   mutation: Builder,
   customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
 ) {
+  // Cast justification: Same overload implementation pattern as zCustomQuery.
+  // See detailed comment there. Type safety is enforced by the overload signature above.
   return customFnBuilder<any, Builder, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>(
     mutation as any,
     customization as any
@@ -427,6 +602,8 @@ export function zCustomAction<
   action: Builder,
   customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
 ) {
+  // Cast justification: Same overload implementation pattern as zCustomQuery.
+  // See detailed comment there. Type safety is enforced by the overload signature above.
   return customFnBuilder<any, Builder, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>(
     action as any,
     customization as any

package/src/index.ts

@@ -6,6 +6,7 @@ export * from './custom'
 export * from './ids'
 export * from './mapping'
 export * from './registry'
+export * from './results'
 export * from './tables'
 export * from './types'
 export * from './utils'

package/src/mapping/core.ts

@@ -184,20 +184,32 @@ function zodToConvexInternal<Z extends z.ZodTypeAny>(
       }
       case 'transform':
       case 'pipe': {
-        // Check for registered codec first
-        const codec = findBaseCodec(actualValidator)
-        if (codec) {
-          convexValidator = codec.toValidator(actualValidator)
-        } else {
-          // Check for brand metadata
-          const metadata = registryHelpers.getMetadata(actualValidator)
-          if (metadata?.brand && metadata?.originalSchema) {
-            // For branded types created by our zBrand function, use the original schema
-            convexValidator = zodToConvexInternal(metadata.originalSchema, visited)
+        // Check for native Zod v4 codec first (z.codec())
+        // Codecs have def.type='pipe' but are specifically for bidirectional transforms
+        // Use the input schema (wire format) for Convex validation
+        if (actualValidator instanceof z.ZodCodec) {
+          const inputSchema = (actualValidator as any).def?.in
+          if (inputSchema && inputSchema instanceof z.ZodType) {
+            convexValidator = zodToConvexInternal(inputSchema, visited)
           } else {
-            // For non-registered transforms, return v.any()
             convexValidator = v.any()
           }
+        } else {
+          // Check for registered codec from the registry
+          const codec = findBaseCodec(actualValidator)
+          if (codec) {
+            convexValidator = codec.toValidator(actualValidator)
+          } else {
+            // Check for brand metadata
+            const metadata = registryHelpers.getMetadata(actualValidator)
+            if (metadata?.brand && metadata?.originalSchema) {
+              // For branded types created by our zBrand function, use the original schema
+              convexValidator = zodToConvexInternal(metadata.originalSchema, visited)
+            } else {
+              // For non-registered transforms, return v.any()
+              convexValidator = v.any()
+            }
+          }
         }
         break
       }

package/src/mapping/types.ts

@@ -129,7 +129,9 @@ type ConvexValidatorFromZodBase<Z extends z.ZodTypeAny> =
                                 ? VAny<'required'>
                                 : Z extends z.ZodUnknown
                                   ? VAny<'required'>
-                                  : VAny<'required'>
+                                  : Z extends z.ZodCodec<infer A extends z.ZodTypeAny, any>
+                                    ? ConvexValidatorFromZodBase<A> // Use input schema (wire format) for Convex
+                                    : VAny<'required'>
 
 // Main type mapper with constraint system
 export type ConvexValidatorFromZod<
@@ -216,7 +218,9 @@ export type ConvexValidatorFromZod<
                                         Constraint,
                                         string
                                       >
-                                    : VAny<'required'>
+                                    : Z extends z.ZodCodec<infer A extends z.ZodTypeAny, any>
+                                      ? ConvexValidatorFromZod<A, Constraint> // Use input schema (wire format) for Convex
+                                      : VAny<'required'>
 
 type ConvexValidatorFromZodFields<
   T extends { [key: string]: any },

package/src/results.ts

@@ -0,0 +1,110 @@
+import { z } from 'zod'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Result type for mutations that return data on success.
+ */
+export type MutationResult<T> = { success: true; data: T } | { success: false; error: string }
+
+/**
+ * Result type for mutations that don't return data (void operations).
+ */
+export type VoidMutationResult = { success: true } | { success: false; error: string }
+
+/**
+ * Error structure for form validation results.
+ */
+export type FormError = {
+  formErrors: string[]
+  fieldErrors: Record<string, string[]>
+}
+
+/**
+ * Result type for form submissions with field-level error support.
+ * Preserves submitted data on failure for form re-population.
+ */
+export type FormResult<TData> =
+  | { success: true; data: TData }
+  | { success: false; data: TData; error: FormError }
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Create a success result with data.
+ * @example success({ id: '123' })
+ */
+export const success = <T>(data: T) => ({ success: true, data }) as const
+
+/**
+ * Create a failure result with an error message.
+ * @example failure('Not found')
+ */
+export const failure = (error: string) => ({ success: false, error }) as const
+
+/**
+ * Create a void success result (no data).
+ * @example ok()
+ */
+export const ok = () => ({ success: true }) as const
+
+/**
+ * Create a form success result with data.
+ * @example formSuccess({ email: 'user@example.com' })
+ */
+export const formSuccess = <T>(data: T) => ({ success: true, data }) as const
+
+/**
+ * Create a form failure result with data and errors.
+ * @example formFailure({ email: 'bad' }, { formErrors: [], fieldErrors: { email: ['Invalid'] } })
+ */
+export const formFailure = <T>(data: T, error: FormError) =>
+  ({ success: false, data, error }) as const
+
+// ============================================================================
+// Zod Schemas for `returns` validation
+// ============================================================================
+
+/**
+ * Zod schema for MutationResult<T>.
+ * Use in `returns` option to validate mutation responses.
+ * @example zMutationResult(z.object({ id: zid('users') }))
+ */
+export const zMutationResult = <T extends z.ZodTypeAny>(dataSchema: T) =>
+  z.discriminatedUnion('success', [
+    z.object({ success: z.literal(true), data: dataSchema }),
+    z.object({ success: z.literal(false), error: z.string() })
+  ])
+
+/**
+ * Zod schema for VoidMutationResult.
+ * Use in `returns` option for void mutations.
+ * @example returns: zVoidMutationResult
+ */
+export const zVoidMutationResult = z.discriminatedUnion('success', [
+  z.object({ success: z.literal(true) }),
+  z.object({ success: z.literal(false), error: z.string() })
+])
+
+/**
+ * Zod schema for FormError.
+ */
+export const zFormError = z.object({
+  formErrors: z.array(z.string()),
+  fieldErrors: z.record(z.string(), z.array(z.string()))
+})
+
+/**
+ * Zod schema for FormResult<T>.
+ * Use in `returns` option for form submissions.
+ * @example zFormResult(z.object({ email: z.string() }))
+ */
+export const zFormResult = <T extends z.ZodTypeAny>(dataSchema: T) =>
+  z.discriminatedUnion('success', [
+    z.object({ success: z.literal(true), data: dataSchema }),
+    z.object({ success: z.literal(false), data: dataSchema, error: zFormError })
+  ])