Allow objects to be used as args and return type validators (#27145)

Allow objects with validator properties to be used as argument and return value validators.

Now these two both work:
```
export const oldSyntax = mutation({
  args: { arg: v.string() },
  handler: (_, args) => ...
});
export const newSyntax = mutation({
  args: v.object({ arg: v.string() }),
  handler: (_, args) => ...
});
```
This is a change some types of middleware will need to deal with: when adding or removing fields from args it is now necessary to check whether `args` is a validator or an object and use different logic accordingly. The recommended path here is to use the new `asObjectValidator` function which accepts either a record of string to validator or a validator and always returns a validator.

GitOrigin-RevId: 610d1251d4321697b9e7e75081a403c4cd3e3026

Author: thomasballinger

npm-packages/convex/src/server/impl/registration_impl.ts

@@ -39,6 +39,7 @@ import { functionName } from "../api.js";
 import { extractReferencePath } from "../components/index.js";
 import { parseArgs } from "../../common/index.js";
 import { performAsyncSyscall } from "./syscall.js";
+import { asObjectValidator } from "../../values/validator.js";
 
 async function invokeMutation<
   F extends (ctx: GenericMutationCtx<GenericDataModel>, ...args: any) => any,
@@ -127,8 +128,8 @@ function assertNotBrowser() {
 type FunctionDefinition =
   | ((ctx: any, args: DefaultFunctionArgs) => any)
   | {
-      args?: Record<string, GenericValidator>;
-      returns?: GenericValidator;
+      args?: GenericValidator | Record<string, GenericValidator>;
+      returns?: GenericValidator | Record<string, GenericValidator>;
       handler: (ctx: any, args: DefaultFunctionArgs) => any;
     };
 
@@ -139,7 +140,7 @@ function exportArgs(functionDefinition: FunctionDefinition) {
       typeof functionDefinition === "object" &&
       functionDefinition.args !== undefined
     ) {
-      args = v.object(functionDefinition.args);
+      args = asObjectValidator(functionDefinition.args);
     }
     return JSON.stringify(args.json);
   };
@@ -152,7 +153,7 @@ function exportReturns(functionDefinition: FunctionDefinition) {
       typeof functionDefinition === "object" &&
       functionDefinition.returns !== undefined
     ) {
-      returns = functionDefinition.returns;
+      returns = asObjectValidator(functionDefinition.returns);
     }
     return JSON.stringify(returns ? returns.json : null);
   };

npm-packages/convex/src/server/registration.test.ts

@@ -1,7 +1,11 @@
 import { test } from "@jest/globals";
 import { assert, Equals } from "../test/type_testing.js";
 import { v } from "../values/validator.js";
-import { ApiFromModules, DefaultFunctionArgs } from "./index.js";
+import {
+  ApiFromModules,
+  DefaultFunctionArgs,
+  mutationGeneric,
+} from "./index.js";
 import { EmptyObject, MutationBuilder } from "./registration.js";
 
 describe("argument inference", () => {
@@ -270,3 +274,102 @@ describe("argument inference", () => {
     assert<Equals<Args, ExpectedArgs>>;
   });
 });
+
+describe("argument and return value validators can be objects or validators", () => {
+  // Test with mutation, but all the wrappers work the same way.
+  const mutation: MutationBuilder<any, "public"> = mutationGeneric;
+
+  const module = {
+    configArgsObject: mutation({
+      args: {
+        arg: v.string(),
+      },
+      handler: (_, args) => {
+        assert<Equals<(typeof args)["arg"], string>>;
+        return "result";
+      },
+    }),
+    configArgsValidatorIsNotSupported: mutation({
+      args: v.object({
+        arg: v.string(),
+      }),
+      handler: (_, args) => {
+        assert<Equals<(typeof args)["arg"], string>>;
+        return "result";
+      },
+    }),
+    configOutputObject: mutation({
+      returns: {
+        arg: v.string(),
+      },
+      handler: () => {
+        return { arg: "result" };
+      },
+    }),
+    configOutputValidator: mutation({
+      returns: v.object({
+        arg: v.string(),
+      }),
+      handler: () => {
+        return { arg: "result" };
+      },
+    }),
+  };
+  type API = ApiFromModules<{ module: typeof module }>;
+
+  const expectedArgsExport = {
+    type: "object",
+    value: {
+      arg: {
+        fieldType: {
+          type: "string",
+        },
+        optional: false,
+      },
+    },
+  };
+
+  const expectedReturnsExport = {
+    type: "object",
+    value: {
+      arg: {
+        fieldType: {
+          type: "string",
+        },
+        optional: false,
+      },
+    },
+  };
+
+  test("config with args validator", () => {
+    type Args = API["module"]["configArgsObject"]["_args"];
+    type ExpectedArgs = { arg: string };
+    assert<Equals<Args, ExpectedArgs>>;
+    const argsString = module.configArgsObject.exportArgs();
+    expect(JSON.parse(argsString)).toEqual(expectedArgsExport);
+  });
+
+  test("config with args object", () => {
+    type Args = API["module"]["configArgsValidatorIsNotSupported"]["_args"];
+    type ExpectedArgs = { arg: string };
+    assert<Equals<Args, ExpectedArgs>>;
+    const argsString = module.configArgsObject.exportArgs();
+    expect(JSON.parse(argsString)).toEqual(expectedArgsExport);
+  });
+
+  test("config with output validator", () => {
+    type ReturnType = API["module"]["configOutputObject"]["_returnType"];
+    type Expected = { arg: string };
+    assert<Equals<ReturnType, Expected>>;
+    const returnString = module.configOutputObject.exportReturns();
+    expect(JSON.parse(returnString)).toEqual(expectedReturnsExport);
+  });
+
+  test("config with output object", () => {
+    type ReturnType = API["module"]["configOutputValidator"]["_returnType"];
+    type Expected = { arg: string };
+    assert<Equals<ReturnType, Expected>>;
+    const returnString = module.configOutputValidator.exportReturns();
+    expect(JSON.parse(returnString)).toEqual(expectedReturnsExport);
+  });
+});

npm-packages/convex/src/server/registration.ts

@@ -12,7 +12,12 @@ import {
   OptionalRestArgs,
   ValidatorTypeToReturnType,
 } from "../server/api.js";
-import { Infer, ObjectType, PropertyValidators } from "../values/validator.js";
+import {
+  GenericValidator,
+  Infer,
+  ObjectType,
+  PropertyValidators,
+} from "../values/validator.js";
 import { Id } from "../values/value.js";
 import {
   GenericDataModel,
@@ -514,22 +519,28 @@ export interface ValidatedFunction<
  */
 
 export type ReturnValueForOptionalValidator<
-  ReturnsValidator extends Validator<any, any, any> | void,
+  ReturnsValidator extends Validator<any, any, any> | PropertyValidators | void,
 > = [ReturnsValidator] extends [Validator<any, any, any>]
   ? ValidatorTypeToReturnType<Infer<ReturnsValidator>>
-  : any;
+  : [ReturnsValidator] extends [PropertyValidators]
+    ? ObjectType<ReturnsValidator>
+    : any;
 
 export type ArgsArrayForOptionalValidator<
-  ArgsValidator extends PropertyValidators | void,
-> = [ArgsValidator] extends [PropertyValidators]
-  ? OneArgArray<ObjectType<ArgsValidator>>
-  : ArgsArray;
+  ArgsValidator extends GenericValidator | PropertyValidators | void,
+> = [ArgsValidator] extends [Validator<any, any, any>]
+  ? OneArgArray<Infer<ArgsValidator>>
+  : [ArgsValidator] extends [PropertyValidators]
+    ? OneArgArray<ObjectType<ArgsValidator>>
+    : ArgsArray;
 
 export type DefaultArgsForOptionalValidator<
-  ArgsValidator extends PropertyValidators | void,
-> = [ArgsValidator] extends [PropertyValidators]
-  ? [ObjectType<ArgsValidator>]
-  : OneArgArray;
+  ArgsValidator extends GenericValidator | PropertyValidators | void,
+> = [ArgsValidator] extends [Validator<any, any, any>]
+  ? [Infer<ArgsValidator>]
+  : [ArgsValidator] extends [PropertyValidators]
+    ? [ObjectType<ArgsValidator>]
+    : OneArgArray;
 
 /**
  * Internal type helper used by Convex code generation.
@@ -542,8 +553,11 @@ export type MutationBuilder<
   Visibility extends FunctionVisibility,
 > = {
   <
-    ArgsValidator extends PropertyValidators | void,
-    ReturnsValidator extends Validator<any, any, any> | void,
+    ArgsValidator extends PropertyValidators | Validator<any, any, any> | void,
+    ReturnsValidator extends
+      | PropertyValidators
+      | Validator<any, any, any>
+      | void,
     ReturnValue extends ReturnValueForOptionalValidator<ReturnsValidator> = any,
     OneOrZeroArgs extends
       ArgsArrayForOptionalValidator<ArgsValidator> = DefaultArgsForOptionalValidator<ArgsValidator>,

npm-packages/convex/src/values/index.ts

@@ -13,11 +13,12 @@ export type {
   Value,
   NumericValue,
 } from "./value.js";
-export { v } from "./validator.js";
+export { v, asObjectValidator } from "./validator.js";
 export type {
-  PropertyValidators,
-  ObjectType,
+  AsObjectValidator,
   GenericValidator,
+  ObjectType,
+  PropertyValidators,
 } from "./validator.js";
 export type {
   ValidatorJSON,

npm-packages/convex/src/values/validator.ts

@@ -27,9 +27,46 @@ import {
 export type GenericValidator = Validator<any, any, any>;
 
 export function isValidator(v: any): v is GenericValidator {
-  return !!v.isValidator;
+  return !!v.isConvexValidator;
 }
 
+/**
+ * Coerce an object with validators as properties to a validator.
+ * If a validator is passed, return it.
+ *
+ * @public
+ */
+export function asObjectValidator<
+  V extends Validator<any, any, any> | PropertyValidators,
+>(
+  obj: V,
+): V extends Validator<any, any, any>
+  ? V
+  : V extends PropertyValidators
+    ? Validator<ObjectType<V>>
+    : never {
+  if (isValidator(obj)) {
+    return obj as any;
+  } else {
+    return v.object(obj as PropertyValidators) as any;
+  }
+}
+
+/**
+ * Coerce an object with validators as properties to a validator.
+ * If a validator is passed, return it.
+ *
+ * @public
+ */
+export type AsObjectValidator<
+  V extends Validator<any, any, any> | PropertyValidators,
+> =
+  V extends Validator<any, any, any>
+    ? V
+    : V extends PropertyValidators
+      ? Validator<ObjectType<V>>
+      : never;
+
 /**
  * The validator builder.
  *