zodvex 0.7.2 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zodvex",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Codec-first Zod v4 integration for Convex -- type-safe validation, encoding, DB wrapping, and codegen.",
   "keywords": ["zod", "convex", "validators", "codec", "mapping", "schema", "validation"],
   "homepage": "https://github.com/panzacoder/zodvex#readme",

package/src/internal/custom.ts

@@ -118,7 +118,11 @@ type Registration<
  */
 export type CustomBuilder<
   FuncType extends 'query' | 'mutation' | 'action',
-  CustomArgsValidator extends PropertyValidators,
+  // The customization's caller-facing args as a resolved object type (the args
+  // the caller must supply so the customization's `input` can consume them).
+  // Resolved rather than a `PropertyValidators` slot so zodvex customizations
+  // (`.withContext({ args: <zod> })`) can express decoded-runtime arg types. #72
+  CustomArgs extends Record<string, any>,
   CustomCtx extends Record<string, any>,
   CustomMadeArgs extends Record<string, any>,
   InputCtx,
@@ -170,11 +174,11 @@ export type CustomBuilder<
     FuncType,
     Visibility,
     ArgsArrayToObject<
-      CustomArgsValidator extends Record<string, never>
+      CustomArgs extends Record<string, never>
         ? ArgsInput<ArgsValidator>
         : ArgsInput<ArgsValidator> extends [infer A]
-          ? [Expand<A & import('convex/values').ObjectType<CustomArgsValidator>>]
-          : [import('convex/values').ObjectType<CustomArgsValidator>]
+          ? [Expand<A & CustomArgs>]
+          : [CustomArgs]
     >,
     ReturnsZodValidator extends void ? ReturnValue : ReturnValueOutput<ReturnsZodValidator>
   >
@@ -192,7 +196,22 @@ export function customFnBuilder<
   customization: Customization<Ctx, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
 ) {
   const customInput = customization.input ?? NoOp.input
-  const inputArgs = customization.args ?? NoOp.args
+  const rawInputArgs = customization.args ?? NoOp.args
+
+  // #72: a customization may declare its args as zod (e.g. a codec-typed arg in
+  // `.withContext({ args: { token: myCodec } })`). Those must enter the same
+  // pipeline as consumer args — converted to Convex validators for registration
+  // and codec-decoded before `input` runs. Pre-built Convex validators (the
+  // legacy shape) are passed through unchanged for back-compat.
+  const customArgEntries = Object.entries(rawInputArgs)
+  const customArgsAreZod =
+    customArgEntries.length > 0 && customArgEntries.every(([, v]) => v instanceof $ZodType)
+  const inputArgs = customArgsAreZod
+    ? zodToConvexFields(rawInputArgs as unknown as ZodValidator)
+    : rawInputArgs
+  const customArgsSchema = customArgsAreZod
+    ? (z.object(rawInputArgs as any) as unknown as $ZodObject)
+    : undefined
 
   return function customBuilder(fn: any): any {
     const { args, handler = fn, returns: maybeObject, ...extra } = fn
@@ -227,7 +246,8 @@ export function customFnBuilder<
             ctx,
             allArgs,
             inputArgs,
-            extra
+            extra,
+            customArgsSchema
           )
           const argKeys = Object.keys(argsValidator)
           const rawArgs = pick(allArgs, argKeys)
@@ -251,7 +271,8 @@ export function customFnBuilder<
           ctx,
           allArgs,
           inputArgs,
-          extra
+          extra,
+          customArgsSchema
         )
         const { finalCtx, finalArgs } = applyCustomizationResult(ctx as any, baseArgs, added)
 
@@ -293,7 +314,7 @@ export function zCustomQuery<
   customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
 ): CustomBuilder<
   'query',
-  CustomArgsValidator,
+  import('convex/values').ObjectType<CustomArgsValidator>,
   CustomCtx,
   CustomMadeArgs,
   GenericQueryCtx<DataModel>,
@@ -313,7 +334,7 @@ export function zCustomQuery<
   customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
 ): CustomBuilder<
   'query',
-  CustomArgsValidator,
+  import('convex/values').ObjectType<CustomArgsValidator>,
   CustomCtx,
   CustomMadeArgs,
   any,
@@ -358,7 +379,7 @@ export function zCustomMutation<
   customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
 ): CustomBuilder<
   'mutation',
-  CustomArgsValidator,
+  import('convex/values').ObjectType<CustomArgsValidator>,
   CustomCtx,
   CustomMadeArgs,
   ExtractCtx<Builder>,
@@ -396,7 +417,7 @@ export function zCustomAction<
   customization: Customization<any, CustomArgsValidator, CustomCtx, CustomMadeArgs, ExtraArgs>
 ): CustomBuilder<
   'action',
-  CustomArgsValidator,
+  import('convex/values').ObjectType<CustomArgsValidator>,
   CustomCtx,
   CustomMadeArgs,
   ExtractCtx<Builder>,

package/src/internal/functionContracts.ts

@@ -174,16 +174,18 @@ export async function runCustomizationInput(
   ctx: unknown,
   allArgs: Record<string, unknown>,
   inputArgs: Record<string, unknown>,
-  extra: Record<string, unknown>
+  extra: Record<string, unknown>,
+  argsSchema?: $ZodObject
 ): Promise<CustomInputResult | undefined> {
-  return (await customInput(
-    ctx,
-    // 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.
-    pick(allArgs, Object.keys(inputArgs)) as any,
-    extra
-  )) as CustomInputResult | undefined
+  // 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.
+  const picked = pick(allArgs, Object.keys(inputArgs)) as Record<string, unknown>
+  // #72: when the customization declared its args as zod, decode them (codec
+  // transforms applied) before the customization's `input` runs — symmetric
+  // with how consumer args are decoded via parseObjectArgsOrThrow.
+  const customArgs = argsSchema ? parseObjectArgsOrThrow(argsSchema, picked) : picked
+  return (await customInput(ctx, customArgs as any, extra)) as CustomInputResult | undefined
 }
 
 export function applyCustomizationResult(

package/src/internal/init.ts

@@ -8,8 +8,6 @@ import type {
   MutationBuilder,
   QueryBuilder
 } from 'convex/server'
-import type { PropertyValidators } from 'convex/values'
-import type { Customization } from 'convex-helpers/server/customFunctions'
 import { NoOp } from 'convex-helpers/server/customFunctions'
 import type { z } from 'zod'
 import { createZodvexActionCtx } from './actionCtx'
@@ -17,8 +15,10 @@ import type { CustomBuilder } from './custom'
 import { zCustomAction, zCustomMutation, zCustomQuery } from './custom'
 import { createZodvexCustomization } from './customization'
 import type { ZodvexDatabaseReader, ZodvexDatabaseWriter } from './db'
+import type { ZodValidator } from './mapping'
 import type { ZodTableMap } from './schema'
 import type { AnyRegistry, Overwrite } from './types'
+import type { $ZodObject } from './zod-core'
 
 /**
  * The context type received by query handlers when wrapDb: true.
@@ -71,6 +71,34 @@ type InitServerBuilders = {
   internalAction: ActionBuilder<any, 'internal'>
 }
 
+type MaybePromise<T> = T | Promise<T>
+
+/**
+ * A `.withContext()` customization for zodvex builders. Unlike convex-helpers'
+ * `Customization` (which types `args` as Convex `PropertyValidators`), the
+ * declared `args` are **zod** — they run through the same zod→Convex + codec
+ * pipeline as consumer args, so `input` receives the **decoded runtime** values
+ * (`z.output`), and the resulting function registers the wire validator. See #72.
+ */
+type ZodWithContextCustomization<
+  InputCtx,
+  ZArgs extends ZodValidator,
+  CustomCtx extends Record<string, any>,
+  CustomMadeArgs extends Record<string, any>,
+  ExtraArgs extends Record<string, any>
+> = {
+  args?: ZArgs
+  input?: (
+    ctx: InputCtx,
+    args: z.output<$ZodObject<ZArgs>>,
+    extra?: ExtraArgs
+  ) => MaybePromise<{
+    ctx: CustomCtx
+    args?: CustomMadeArgs
+    onSuccess?: (params: { ctx: unknown; args: unknown; result: unknown }) => unknown
+  }>
+}
+
 /**
  * A zodvex builder: callable CustomBuilder + .withContext() for composing
  * user customizations on top of the codec layer.
@@ -93,21 +121,21 @@ export type ZodvexBuilder<
   Record<string, any>
 > & {
   withContext: <
-    CustomArgsValidator extends PropertyValidators,
-    CustomCtx extends Record<string, any>,
-    CustomMadeArgs extends Record<string, any>,
+    ZArgs extends ZodValidator = Record<string, never>,
+    CustomCtx extends Record<string, any> = Record<string, never>,
+    CustomMadeArgs extends Record<string, any> = Record<string, never>,
     ExtraArgs extends Record<string, any> = Record<string, any>
   >(
-    customization: Customization<
+    customization: ZodWithContextCustomization<
       Overwrite<InputCtx, CodecCtx>,
-      CustomArgsValidator,
+      ZArgs,
       CustomCtx,
       CustomMadeArgs,
       ExtraArgs
     >
   ) => CustomBuilder<
     FuncType,
-    CustomArgsValidator,
+    z.output<$ZodObject<ZArgs>>,
     Overwrite<CodecCtx, CustomCtx>,
     CustomMadeArgs,
     InputCtx,