Add vRequired / VRequired utils in validators.ts (#866)

devin-ai-integration[bot] · Nicolapps · web-flow · commit 7bde00b5cffe · 2025-11-30T17:36:43.000-08:00
Co-authored-by: Devin AI &lt;158243242+devin-ai-integration[bot]@users.noreply.github.com&gt;
Co-authored-by: nicolas@convex.dev &lt;nicolas@convex.dev&gt;
diff --git a/packages/convex-helpers/server/zod4.ts b/packages/convex-helpers/server/zod4.ts
@@ -40,7 +40,11 @@ import type {
 import { pick, type Expand } from "../index.js";
 import type { Customization, Registration } from "./customFunctions.js";
 import { NoOp } from "./customFunctions.js";
-import { addFieldsToValidator } from "../validators.js";
+import {
+  addFieldsToValidator,
+  vRequired,
+  type VRequired,
+} from "../validators.js";
 
 // #region Convex function definition with Zod
 
@@ -1882,110 +1886,6 @@ const _zidRegistry = zCore.registry<{ tableName: string }>();
 
 type NotUndefined<T> = Exclude<T, undefined>;
 
-type VRequired<T extends Validator<any, OptionalProperty, any>> =
-  T extends VId<infer Type, OptionalProperty>
-    ? VId<NotUndefined<Type>, "required">
-    : T extends VString<infer Type, OptionalProperty>
-      ? VString<NotUndefined<Type>, "required">
-      : T extends VFloat64<infer Type, OptionalProperty>
-        ? VFloat64<NotUndefined<Type>, "required">
-        : T extends VInt64<infer Type, OptionalProperty>
-          ? VInt64<NotUndefined<Type>, "required">
-          : T extends VBoolean<infer Type, OptionalProperty>
-            ? VBoolean<NotUndefined<Type>, "required">
-            : T extends VNull<infer Type, OptionalProperty>
-              ? VNull<NotUndefined<Type>, "required">
-              : T extends VAny<infer Type, OptionalProperty>
-                ? VAny<NotUndefined<Type>, "required">
-                : T extends VLiteral<infer Type, OptionalProperty>
-                  ? VLiteral<NotUndefined<Type>, "required">
-                  : T extends VBytes<infer Type, OptionalProperty>
-                    ? VBytes<NotUndefined<Type>, "required">
-                    : T extends VObject<
-                          infer Type,
-                          infer Fields,
-                          OptionalProperty,
-                          infer FieldPaths
-                        >
-                      ? VObject<
-                          NotUndefined<Type>,
-                          Fields,
-                          "required",
-                          FieldPaths
-                        >
-                      : T extends VArray<
-                            infer Type,
-                            infer Element,
-                            OptionalProperty
-                          >
-                        ? VArray<NotUndefined<Type>, Element, "required">
-                        : T extends VRecord<
-                              infer Type,
-                              infer Key,
-                              infer Value,
-                              OptionalProperty,
-                              infer FieldPaths
-                            >
-                          ? VRecord<
-                              NotUndefined<Type>,
-                              Key,
-                              Value,
-                              "required",
-                              FieldPaths
-                            >
-                          : T extends VUnion<
-                                infer Type,
-                                infer Members,
-                                OptionalProperty,
-                                infer FieldPaths
-                              >
-                            ? VUnion<
-                                NotUndefined<Type>,
-                                Members,
-                                "required",
-                                FieldPaths
-                              >
-                            : never;
-
-function vRequired(validator: GenericValidator) {
-  const { kind, isOptional } = validator;
-  if (isOptional === "required") {
-    return validator;
-  }
-
-  switch (kind) {
-    case "id":
-      return v.id(validator.tableName);
-    case "string":
-      return v.string();
-    case "float64":
-      return v.float64();
-    case "int64":
-      return v.int64();
-    case "boolean":
-      return v.boolean();
-    case "null":
-      return v.null();
-    case "any":
-      return v.any();
-    case "literal":
-      return v.literal(validator.value);
-    case "bytes":
-      return v.bytes();
-    case "object":
-      return v.object(validator.fields);
-    case "array":
-      return v.array(validator.element);
-    case "record":
-      return v.record(validator.key, validator.value);
-    case "union":
-      return v.union(...validator.members);
-    default:
-      kind satisfies never;
-      throw new Error("Unknown Convex validator type: " + kind);
-  }
-}
-
 type TableNameFromType<T> =
   T extends GenericId<infer TableName> ? TableName : string;
 
diff --git a/packages/convex-helpers/validators.test.ts b/packages/convex-helpers/validators.test.ts
@@ -0,0 +1,90 @@
+import { v } from "convex/values";
+import { describe, expect, test, expectTypeOf } from "vitest";
+import { vRequired, type VRequired } from "./validators.js";
+import type { Equals } from "./index.js";
+import type { Validator } from "convex/values";
+
+describe("vRequired", () => {
+  test("returns required validator unchanged", () => {
+    testVRequired(v.string(), v.string());
+  });
+
+  test("converts optional string to required", () => {
+    testVRequired(v.optional(v.string()), v.string());
+  });
+
+  test("converts optional number to required", () => {
+    testVRequired(v.optional(v.float64()), v.float64());
+  });
+
+  test("converts optional boolean to required", () => {
+    testVRequired(v.optional(v.boolean()), v.boolean());
+  });
+
+  test("converts optional int64 to required", () => {
+    testVRequired(v.optional(v.int64()), v.int64());
+  });
+
+  test("converts optional null to required", () => {
+    testVRequired(v.optional(v.null()), v.null());
+  });
+
+  test("converts optional any to required", () => {
+    testVRequired(v.optional(v.any()), v.any());
+  });
+
+  test("converts optional literal to required", () => {
+    testVRequired(v.optional(v.literal("test")), v.literal("test"));
+  });
+
+  test("converts optional bytes to required", () => {
+    testVRequired(v.optional(v.bytes()), v.bytes());
+  });
+
+  test("converts optional object to required", () => {
+    testVRequired(
+      v.optional(v.object({ name: v.string() })),
+      v.object({ name: v.string() }),
+    );
+  });
+
+  test("converts optional array to required", () => {
+    testVRequired(v.optional(v.array(v.string())), v.array(v.string()));
+  });
+
+  test("converts optional record to required", () => {
+    testVRequired(
+      v.optional(v.record(v.string(), v.number())),
+      v.record(v.string(), v.number()),
+    );
+  });
+
+  test("converts optional union to required", () => {
+    testVRequired(
+      v.optional(v.union(v.string(), v.number())),
+      v.union(v.string(), v.number()),
+    );
+  });
+
+  test("converts optional id to required", () => {
+    testVRequired(v.optional(v.id("users")), v.id("users"));
+  });
+});
+
+function testVRequired<
+  T extends Validator<any, any, any>,
+  Expected extends Validator<any, "required", any>,
+>(
+  input: T,
+  expected: Expected &
+    (Equals<Expected, VRequired<T>> extends true
+      ? // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+        {}
+      : "Expected type must match VRequired<Input>"),
+) {
+  const result = vRequired(input);
+  expect(result).toEqual(expected);
+  expect(result.isOptional).toBe("required");
+  // This is redundant with the type check in the argument, but good for sanity
+  expectTypeOf(result).toEqualTypeOf(expected as any);
+}
diff --git a/packages/convex-helpers/validators.ts b/packages/convex-helpers/validators.ts
@@ -14,10 +14,18 @@ import type {
   OptionalProperty,
   PropertyValidators,
   Validator,
+  VAny,
+  VArray,
+  VBoolean,
+  VBytes,
+  VFloat64,
   VId,
+  VInt64,
   VLiteral,
+  VNull,
   VObject,
   VOptional,
+  VRecord,
   VString,
   VUnion,
 } from "convex/values";
@@ -889,3 +897,142 @@ function stripUnknownFields<T extends Validator<any, any, any>>(
 function appendPath(opts: { _pathPrefix?: string } | undefined, path: string) {
   return opts?._pathPrefix ? `${opts._pathPrefix}.${path}` : path;
 }
+
+type NotUndefined<T> = Exclude<T, undefined>;
+
+/**
+ * A type that converts an optional validator to a required validator.
+ *
+ * This is the inverse of `VOptional`. It takes a validator that may be optional
+ * and returns the equivalent required validator type.
+ *
+ * @example
+ * ```ts
+ * type OptionalString = VOptional<VString<string, "required">>;
+ * type RequiredString = VRequired<OptionalString>; // VString<string, "required">
+ * ```
+ */
+export type VRequired<T extends Validator<any, OptionalProperty, any>> =
+  T extends VId<infer Type, OptionalProperty>
+    ? VId<NotUndefined<Type>, "required">
+    : T extends VString<infer Type, OptionalProperty>
+      ? VString<NotUndefined<Type>, "required">
+      : T extends VFloat64<infer Type, OptionalProperty>
+        ? VFloat64<NotUndefined<Type>, "required">
+        : T extends VInt64<infer Type, OptionalProperty>
+          ? VInt64<NotUndefined<Type>, "required">
+          : T extends VBoolean<infer Type, OptionalProperty>
+            ? VBoolean<NotUndefined<Type>, "required">
+            : T extends VNull<infer Type, OptionalProperty>
+              ? VNull<NotUndefined<Type>, "required">
+              : T extends VAny<infer Type, OptionalProperty>
+                ? VAny<NotUndefined<Type>, "required">
+                : T extends VLiteral<infer Type, OptionalProperty>
+                  ? VLiteral<NotUndefined<Type>, "required">
+                  : T extends VBytes<infer Type, OptionalProperty>
+                    ? VBytes<NotUndefined<Type>, "required">
+                    : T extends VObject<
+                          infer Type,
+                          infer Fields,
+                          OptionalProperty,
+                          infer FieldPaths
+                        >
+                      ? VObject<
+                          NotUndefined<Type>,
+                          Fields,
+                          "required",
+                          FieldPaths
+                        >
+                      : T extends VArray<
+                            infer Type,
+                            infer Element,
+                            OptionalProperty
+                          >
+                        ? VArray<NotUndefined<Type>, Element, "required">
+                        : T extends VRecord<
+                              infer Type,
+                              infer Key,
+                              infer Value,
+                              OptionalProperty,
+                              infer FieldPaths
+                            >
+                          ? VRecord<
+                              NotUndefined<Type>,
+                              Key,
+                              Value,
+                              "required",
+                              FieldPaths
+                            >
+                          : T extends VUnion<
+                                infer Type,
+                                infer Members,
+                                OptionalProperty,
+                                infer FieldPaths
+                              >
+                            ? VUnion<
+                                NotUndefined<Type>,
+                                Members,
+                                "required",
+                                FieldPaths
+                              >
+                            : never;
+
+/**
+ * Converts an optional validator to a required validator.
+ *
+ * This is the inverse of `v.optional()`. It takes a validator that may be optional
+ * and returns the equivalent required validator.
+ *
+ * ```ts
+ * const optionalString = v.optional(v.string());
+ * const requiredString = vRequired(optionalString); // v.string()
+ *
+ * // Already required validators are returned as-is
+ * const alreadyRequired = v.string();
+ * const stillRequired = vRequired(alreadyRequired); // v.string()
+ * ```
+ *
+ * @param validator The validator to make required.
+ * @returns A required version of the validator.
+ */
+export function vRequired<T extends Validator<any, OptionalProperty, any>>(
+  validator: T,
+): VRequired<T> {
+  const { kind, isOptional } = validator;
+  if (isOptional === "required") {
+    // TypeScript can't prove T is already VRequired<T>, so we go via unknown.
+    return validator as unknown as VRequired<T>;
+  }
+
+  switch (kind) {
+    case "id":
+      return v.id(validator.tableName) as VRequired<T>;
+    case "string":
+      return v.string() as VRequired<T>;
+    case "float64":
+      return v.float64() as VRequired<T>;
+    case "int64":
+      return v.int64() as VRequired<T>;
+    case "boolean":
+      return v.boolean() as VRequired<T>;
+    case "null":
+      return v.null() as VRequired<T>;
+    case "any":
+      return v.any() as VRequired<T>;
+    case "literal":
+      return v.literal(validator.value) as VRequired<T>;
+    case "bytes":
+      return v.bytes() as VRequired<T>;
+    case "object":
+      return v.object(validator.fields) as VRequired<T>;
+    case "array":
+      return v.array(validator.element) as VRequired<T>;
+    case "record":
+      return v.record(validator.key, validator.value) as VRequired<T>;
+    case "union":
+      return v.union(...validator.members) as VRequired<T>;
+    default:
+      kind satisfies never;
+      throw new Error("Unknown Convex validator type: " + kind);
+  }
+}
