fix skipConvexValidation - still do zod validation (#874)

<!-- Describe your PR here. -->

Fixes #865 

<!--
  The following applies to third-party contributors.
  Convex employees and contractors can delete or ignore.
-->

----

By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Option to skip automatic Convex validation for custom function
builders retained.

* **Improvements**
* Centralized input/output validation for consistent behavior and
clearer error messages.
* When skipping Convex validation, argument and return validation
behavior is now predictable for Zod-backed custom functions.

* **Tests**
* Added tests for skip-validation scenarios: extra-arg handling,
input-type errors, and invalid return-data errors.

* **Chores**
  * Package version bumped.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: ianmacartney

package-lock.json

@@ -3,6 +3,7 @@
 ## Unreleased
 
 - Zod support: branded object types are now supported (credit: gari-ix)
+- Fixes `skipConvexValidation` for zod custom functions to still do zod validation.
 
 ## 0.1.106
 

packages/convex-helpers/CHANGELOG.md

@@ -1,6 +1,6 @@
 {
   "name": "convex-helpers",
-  "version": "0.1.106",
+  "version": "0.1.107-alpha.0",
   "description": "A collection of useful code to complement the official convex package.",
   "type": "module",
   "bin": {

packages/convex-helpers/package.json

@@ -345,19 +345,25 @@ function customFnBuilder(
     customization.input ?? NoOp.input;
   const inputArgs = customization.args ?? NoOp.args;
   return function customBuilder(fn: any): any {
-    const { args, handler = fn, returns: maybeObject, ...extra } = fn;
+    const {
+      args,
+      handler = fn,
+      skipConvexValidation = false,
+      returns: maybeObject,
+      ...extra
+    } = fn;
 
     const returns =
       maybeObject && !(maybeObject instanceof z.ZodType)
         ? z.object(maybeObject)
         : maybeObject;
 
     const returnValidator =
-      returns && !fn.skipConvexValidation
+      returns && !skipConvexValidation
         ? { returns: zodOutputToConvex(returns) }
         : null;
 
-    if (args && !fn.skipConvexValidation) {
+    if (args) {
       let argsValidator = args;
       if (argsValidator instanceof z.ZodType) {
         if (argsValidator instanceof z.ZodObject) {
@@ -371,7 +377,9 @@ function customFnBuilder(
       }
       const convexValidator = zodToConvexFields(argsValidator);
       return builder({
-        args: addFieldsToValidator(convexValidator, inputArgs),
+        args: skipConvexValidation
+          ? undefined
+          : addFieldsToValidator(convexValidator, inputArgs),
         ...returnValidator,
         handler: async (ctx: any, allArgs: any) => {
           const added = await customInput(
@@ -404,10 +412,10 @@ function customFnBuilder(
         },
       });
     }
-    if (Object.keys(inputArgs).length > 0 && !fn.skipConvexValidation) {
+    if (skipConvexValidation && Object.keys(inputArgs).length > 0) {
       throw new Error(
         "If you're using a custom function with arguments for the input " +
-          "customization, you must declare the arguments for the function too.",
+          "customization, you cannot skip convex validation.",
       );
     }
     return builder({

packages/convex-helpers/server/zod3.ts

@@ -182,6 +182,37 @@ export const transformAsync = zQuery({
   }),
 });
 
+export const testQueryWithSkipConvexValidation = zQuery({
+  args: {
+    name: z.string(),
+    age: z.number(),
+    returnBadData: z.boolean().default(false),
+  },
+  handler: async (_ctx, args) => {
+    assertType<{ name: string; age: number }>(args);
+    const { name, age, returnBadData, ...rest } = args;
+    if (Object.keys(rest).length > 0) {
+      throw new Error("extraArg should be dropped");
+    }
+    if (returnBadData) {
+      return {
+        message: "bad data",
+        doubledAge: 0n as any,
+      };
+    }
+    return {
+      message: `Hello ${name}, you are ${age} years old`,
+      doubledAge: age * 2,
+      extraArg: "extraArg",
+    };
+  },
+  returns: z.object({
+    message: z.string(),
+    doubledAge: z.number(),
+  }),
+  skipConvexValidation: true,
+});
+
 /**
  * Test codec in query args and return value
  */
@@ -264,6 +295,7 @@ const testApi: ApiFromModules<{
     testQueryNoArgs: typeof testQueryNoArgs;
     testMutation: typeof testMutation;
     testAction: typeof testAction;
+    testQueryWithSkipConvexValidation: typeof testQueryWithSkipConvexValidation;
     returnsNothing: typeof returnsNothing;
     transform: typeof transform;
     transformAsync: typeof transformAsync;
@@ -398,6 +430,39 @@ describe("zCustomQuery, zCustomMutation, zCustomAction", () => {
     });
   });
 
+  describe("skipConvexValidation", () => {
+    test("zCustomQuery with skipConvexValidation", async () => {
+      const t = convexTest(schema, modules);
+      const args = {
+        name: "Alice",
+        age: 30,
+        // Should get dropped
+        extraArg: "extraArg",
+      };
+      const response = await t.query(
+        testApi.testQueryWithSkipConvexValidation,
+        args,
+      );
+      expect(response).toMatchObject({
+        message: "Hello Alice, you are 30 years old",
+        doubledAge: 60,
+      });
+    });
+    test("throwing ConvexError on zod arg validation", async () => {
+      const t = convexTest(schema, modules);
+      await expect(
+        t.query(testApi.testQueryWithSkipConvexValidation, {
+          name: 123,
+        } as any),
+      ).rejects.toThrowError(
+        expect.objectContaining({
+          data: expect.stringMatching(
+            /(?=.*"ZodError")(?=.*"name")(?=.*"invalid_type")(?=.*"expected")(?=.*"string")/s,
+          ),
+        }),
+      );
+    });
+  });
   describe("transform", () => {
     test("calling a function with synchronous transforms in arguments and return values", async () => {
       const t = convexTest(schema, modules);

packages/convex-helpers/server/zod4.functions.test.ts

@@ -849,19 +849,25 @@ function customFnBuilder(
     customization.input ?? NoOp.input;
   const inputArgs = customization.args ?? NoOp.args;
   return function customBuilder(fn: any): any {
-    const { args, handler = fn, returns: maybeObject, ...extra } = fn;
+    const {
+      args,
+      handler = fn,
+      skipConvexValidation = false,
+      returns: maybeObject,
+      ...extra
+    } = fn;
 
     const returns =
       maybeObject && !(maybeObject instanceof zCore.$ZodType)
         ? z.object(maybeObject)
         : maybeObject;
 
     const returnValidator =
-      returns && !fn.skipConvexValidation
+      returns && !skipConvexValidation
         ? { returns: zodOutputToConvex(returns) }
         : null;
 
-    if (args && !fn.skipConvexValidation) {
+    if (args) {
       let argsValidator = args;
       if (argsValidator instanceof zCore.$ZodType) {
         if (argsValidator instanceof zCore.$ZodObject) {
@@ -875,7 +881,9 @@ function customFnBuilder(
       }
       const convexValidator = zodToConvexFields(argsValidator);
       return builder({
-        args: addFieldsToValidator(convexValidator, inputArgs),
+        args: skipConvexValidation
+          ? undefined
+          : addFieldsToValidator(convexValidator, inputArgs),
         ...returnValidator,
         handler: async (ctx: any, allArgs: any) => {
           const added = await customInput(
@@ -908,10 +916,10 @@ function customFnBuilder(
         },
       });
     }
-    if (Object.keys(inputArgs).length > 0 && !fn.skipConvexValidation) {
+    if (skipConvexValidation && Object.keys(inputArgs).length > 0) {
       throw new Error(
         "If you're using a custom function with arguments for the input " +
-          "customization, you must declare the arguments for the function too.",
+          "customization, you cannot skip convex validation.",
       );
     }
     return builder({