Make validator types shorter and more readable (#27144)

The goal is having the types on hover for stuff like `v.object({ a: v.string(), b: v.number() })` look reasonable.

I shortened `FooValidator` to `VFoo`, which looks a little better, and avoids confusion with built in types like `Array` or `Object`.

I also switched `IsOptional extends boolean` to `IsOptional extends "required" | "optional"` for readability (but serialized format is the same).

I dropped a few type params that didn't seem necessary (e.g. only using `FieldPaths` on object and union types, since I think this is used to represent all indexable fields, eliminating the TableName type param on `VId`)

GitOrigin-RevId: 743c026572c27c6f282dee51822476cec21c1005

Author: sshader

crates/isolate/src/tests/args_validation.rs

@@ -132,20 +132,23 @@ async fn test_correct_arg(rt: TestRuntime) -> anyhow::Result<()> {
 #[convex_macro::test_runtime]
 async fn test_record(rt: TestRuntime) -> anyhow::Result<()> {
     UdfTest::run_test_with_isolate2(rt, async move |t: UdfTestType| {
-        let args_obj = assert_obj!(
-            "foo" => 0.,
-            "bar" => 1.,
-            "baz" => 2.,
+        must_let!(
+            let ConvexValue::Object(record) = t
+                .mutation(
+                    "args_validation:returnRecord",
+                    assert_obj!(),
+                )
+                .await?
         );
         must_let!(
             let ConvexValue::Object(result) = t
                 .query(
                     "args_validation:recordArg",
-                    assert_obj!("arg" => args_obj.clone()),
+                    assert_obj!("arg" => record.clone()),
                 )
                 .await?
         );
-        assert_eq!(result, args_obj);
+        assert_eq!(result, record);
         Ok(())
     })
     .await

npm-packages/convex/scripts/postpack.mjs

@@ -120,9 +120,9 @@ function rewriteDtsToRemoveInternal(dirname) {
     dirname,
     "values/validator.d.ts",
     `/** @internal */
-    record<Key extends Validator<any, boolean, any>, Value extends Validator<any, boolean, any>>(keys: Key, values: Value): RecordValidator<Value["isOptional"] extends true ? { [key in Infer<Key>]?: Value["type"] | undefined; } : Record<Infer<Key>, Value["type"]>, Key, Value, false, never>;`,
+    record<Key extends Validator<any, "required", any>, Value extends Validator<any, "required", any>>(keys: Key, values: Value): VRecord<Value["isOptional"] extends true ? { [key in Infer<Key>]?: Value["type"] | undefined; } : Record<Infer<Key>, Value["type"]>, Key, Value, "required", string>;`,
     `/* @internal
-    record<Key extends Validator<any, boolean, any>, Value extends Validator<any, boolean, any>>(keys: Key, values: Value): RecordValidator<Value["isOptional"] extends true ? { [key in Infer<Key>]?: Value["type"] | undefined; } : Record<Infer<Key>, Value["type"]>, Key, Value, false, never>; */`,
+    record<Key extends Validator<any, "required", any>, Value extends Validator<any, "required", any>>(keys: Key, values: Value): VRecord<Value["isOptional"] extends true ? { [key in Infer<Key>]?: Value["type"] | undefined; } : Record<Infer<Key>, Value["type"]>, Key, Value, "required", string>; */`,
   );
   auditForInternal(path.join(dirname, "dist", "cjs-types"));
   auditForInternal(path.join(dirname, "dist", "esm-types"));

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

@@ -1,6 +1,7 @@
 import {
   ConvexError,
   convexToJson,
+  GenericValidator,
   jsonToConvex,
   v,
   Validator,
@@ -126,14 +127,14 @@ function assertNotBrowser() {
 type FunctionDefinition =
   | ((ctx: any, args: DefaultFunctionArgs) => any)
   | {
-      args?: Record<string, Validator<any, boolean>>;
-      returns?: Validator<any, boolean>;
+      args?: Record<string, GenericValidator>;
+      returns?: GenericValidator;
       handler: (ctx: any, args: DefaultFunctionArgs) => any;
     };
 
 function exportArgs(functionDefinition: FunctionDefinition) {
   return () => {
-    let args: Validator<any, boolean, any> = v.any();
+    let args: GenericValidator = v.any();
     if (
       typeof functionDefinition === "object" &&
       functionDefinition.args !== undefined

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

@@ -53,7 +53,8 @@ describe("DataModelFromSchemaDefinition", () => {
       | "string"
       | "bytes"
       | "array"
-      | "record";
+      | "record"
+      | `record.${string}`;
 
     type ExpectedDataModel = {
       table: {
@@ -287,7 +288,11 @@ describe("DataModelFromSchemaDefinition", () => {
       _creationTime: number;
       property: Record<GenericId<"reference">, string>;
     };
-    type ExpectedFieldPaths = "_id" | "_creationTime" | "property";
+    type ExpectedFieldPaths =
+      | "_id"
+      | "_creationTime"
+      | "property"
+      | `property.${string}`;
     type ExpectedDataModel = {
       table: {
         document: ExpectedDocument;
@@ -303,22 +308,20 @@ describe("DataModelFromSchemaDefinition", () => {
   test("defineSchema handles records with type unions", () => {
     const schema = defineSchema({
       table: defineTable({
-        property: v.record(
-          v.union(v.literal("foo"), v.literal("bla")),
-          v.optional(v.string()),
-        ),
+        property: v.record(v.union(v.id("foo"), v.id("bla")), v.string()),
       }),
     });
     type DataModel = DataModelFromSchemaDefinition<typeof schema>;
     type ExpectedDocument = {
       _id: GenericId<"table">;
       _creationTime: number;
-      property: {
-        foo?: string;
-        bla?: string;
-      };
+      property: Record<GenericId<"foo"> | GenericId<"bla">, string>;
     };
-    type ExpectedFieldPaths = "_id" | "_creationTime" | "property";
+    type ExpectedFieldPaths =
+      | "_id"
+      | "_creationTime"
+      | "property"
+      | `property.${string}`;
     type ExpectedDataModel = {
       table: {
         document: ExpectedDocument;

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

@@ -42,8 +42,13 @@ import {
   SystemIndexes,
 } from "../server/system_fields.js";
 import { Expand } from "../type_utils.js";
-import { ObjectType, isValidator, v } from "../values/validator.js";
-import { ObjectValidator, Validator } from "../values/validators.js";
+import {
+  GenericValidator,
+  ObjectType,
+  isValidator,
+  v,
+} from "../values/validator.js";
+import { VObject, Validator } from "../values/validators.js";
 
 /**
  * Extract all of the index field paths within a {@link Validator}.
@@ -343,7 +348,7 @@ export class TableDefinition<
  * @public
  */
 export function defineTable<
-  DocumentSchema extends Validator<Record<string, any>, false, any>,
+  DocumentSchema extends Validator<Record<string, any>, "required", any>,
 >(documentSchema: DocumentSchema): TableDefinition<DocumentSchema>;
 /**
  * Define a table in a schema.
@@ -371,14 +376,14 @@ export function defineTable<
  * @public
  */
 export function defineTable<
-  DocumentSchema extends Record<string, Validator<any, any, any>>,
+  DocumentSchema extends Record<string, GenericValidator>,
 >(
   documentSchema: DocumentSchema,
-): TableDefinition<ObjectValidator<ObjectType<DocumentSchema>, DocumentSchema>>;
+): TableDefinition<VObject<ObjectType<DocumentSchema>, DocumentSchema>>;
 export function defineTable<
   DocumentSchema extends
-    | Validator<Record<string, any>, false, any>
-    | Record<string, Validator<any, any, any>>,
+    | Validator<Record<string, any>, "required", any>
+    | Record<string, GenericValidator>,
 >(documentSchema: DocumentSchema): TableDefinition<any, any, any> {
   if (isValidator(documentSchema)) {
     return new TableDefinition(documentSchema);

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

@@ -14,11 +14,16 @@ export type {
   NumericValue,
 } from "./value.js";
 export { v } from "./validator.js";
-export type { PropertyValidators, ObjectType } from "./validator.js";
+export type {
+  PropertyValidators,
+  ObjectType,
+  GenericValidator,
+} from "./validator.js";
 export type {
   ValidatorJSON,
   ObjectFieldType,
   Validator,
+  OptionalProperty,
 } from "./validators.js";
 import * as Base64 from "./base64.js";
 export { Base64 };

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

@@ -1,26 +1,32 @@
 import { Expand } from "../type_utils.js";
 import { GenericId } from "./index.js";
-
-// Binding this module to `V` makes autocompletion pretty crummy in this file.
 import {
-  AnyValidator,
-  ArrayValidator,
-  BooleanValidator,
-  BytesValidator,
-  Float64Validator,
-  IdValidator,
-  Int64Validator,
-  LiteralValidator,
-  NullValidator,
-  ObjectValidator,
-  OptionalValidator,
-  RecordValidator,
-  StringValidator,
-  UnionValidator,
+  OptionalProperty,
+  VAny,
+  VArray,
+  VBoolean,
+  VBytes,
+  VFloat64,
+  VId,
+  VInt64,
+  VLiteral,
+  VNull,
+  VObject,
+  VOptional,
+  VRecord,
+  VString,
+  VUnion,
   Validator,
 } from "./validators.js";
 
-export function isValidator(v: any): v is Validator<any, boolean, any> {
+/**
+ * The type that all validators must extend.
+ *
+ * @public
+ */
+export type GenericValidator = Validator<any, any, any>;
+
+export function isValidator(v: any): v is GenericValidator {
   return !!v.isValidator;
 }
 
@@ -36,82 +42,81 @@ export function isValidator(v: any): v is Validator<any, boolean, any> {
  */
 export const v = {
   id<TableName extends string>(tableName: TableName) {
-    return new IdValidator<GenericId<TableName>, TableName>({
-      isOptional: false,
+    return new VId<GenericId<TableName>>({
+      isOptional: "required",
       tableName,
     });
   },
   null() {
-    return new NullValidator({ isOptional: false });
+    return new VNull({ isOptional: "required" });
   },
   /**
    * Alias for `v.float64()`
    */
   number() {
-    return new Float64Validator({ isOptional: false });
+    return new VFloat64({ isOptional: "required" });
   },
   float64() {
-    return new Float64Validator({ isOptional: false });
+    return new VFloat64({ isOptional: "required" });
   },
   /**
    * @deprecated Use `v.int64()` instead
    */
   bigint() {
-    return new Int64Validator({ isOptional: false });
+    return new VInt64({ isOptional: "required" });
   },
   int64() {
-    return new Int64Validator({ isOptional: false });
+    return new VInt64({ isOptional: "required" });
   },
   boolean() {
-    return new BooleanValidator({ isOptional: false });
+    return new VBoolean({ isOptional: "required" });
   },
   string() {
-    return new StringValidator({ isOptional: false });
+    return new VString({ isOptional: "required" });
   },
   bytes() {
-    return new BytesValidator({ isOptional: false });
+    return new VBytes({ isOptional: "required" });
   },
-  // this could be expanded for more kinds of literals
   literal<T extends string | number | bigint | boolean>(literal: T) {
-    return new LiteralValidator<T, T>({ isOptional: false, value: literal });
+    return new VLiteral<T>({ isOptional: "required", value: literal });
   },
-  array<T extends Validator<any, false, any>>(element: T) {
-    return new ArrayValidator<T["type"][], T>({ isOptional: false, element });
+  array<T extends Validator<any, "required", any>>(element: T) {
+    return new VArray<T["type"][], T>({ isOptional: "required", element });
   },
   object<T extends PropertyValidators>(fields: T) {
-    return new ObjectValidator<ObjectType<T>, T>({ isOptional: false, fields });
+    return new VObject<ObjectType<T>, T>({ isOptional: "required", fields });
   },
 
   /** @internal */
   record<
-    Key extends Validator<any, boolean, any>,
-    Value extends Validator<any, boolean, any>,
+    Key extends Validator<any, "required", any>,
+    Value extends Validator<any, "required", any>,
   >(keys: Key, values: Value) {
     // TODO enforce that Infer<key> extends string
-    return new RecordValidator<
+    return new VRecord<
       Value["isOptional"] extends true
         ? { [key in Infer<Key>]?: Value["type"] }
         : Record<Infer<Key>, Value["type"]>,
       Key,
       Value
     >({
-      isOptional: false,
+      isOptional: "required",
       key: keys,
       value: values,
     });
   },
 
-  union<T extends Validator<any, false, any>[]>(...members: T) {
-    return new UnionValidator<T[number]["type"], T>({
-      isOptional: false,
+  union<T extends Validator<any, "required", any>[]>(...members: T) {
+    return new VUnion<T[number]["type"], T>({
+      isOptional: "required",
       members,
     });
   },
   any() {
-    return new AnyValidator({ isOptional: false });
+    return new VAny({ isOptional: "required" });
   },
-  optional<T extends Validator<any, boolean, any>>(value: T) {
-    return value.optional() as OptionalValidator<T>;
+  optional<T extends GenericValidator>(value: T) {
+    return value.optional() as VOptional<T>;
   },
 };
 
@@ -123,7 +128,10 @@ export const v = {
  *
  * @public
  */
-export type PropertyValidators = Record<string, Validator<any, boolean, any>>;
+export type PropertyValidators = Record<
+  string,
+  Validator<any, OptionalProperty, any>
+>;
 
 /**
  * Compute the type of an object from {@link PropertyValidators}.
@@ -140,17 +148,15 @@ export type ObjectType<Fields extends PropertyValidators> = Expand<
   }
 >;
 
-type OptionalKeys<
-  PropertyValidators extends Record<string, Validator<any, boolean, any>>,
-> = {
-  [Property in keyof PropertyValidators]: PropertyValidators[Property]["isOptional"] extends true
-    ? Property
-    : never;
-}[keyof PropertyValidators];
+type OptionalKeys<PropertyValidators extends Record<string, GenericValidator>> =
+  {
+    [Property in keyof PropertyValidators]: PropertyValidators[Property]["isOptional"] extends "optional"
+      ? Property
+      : never;
+  }[keyof PropertyValidators];
 
-type RequiredKeys<
-  PropertyValidators extends Record<string, Validator<any, boolean, any>>,
-> = Exclude<keyof PropertyValidators, OptionalKeys<PropertyValidators>>;
+type RequiredKeys<PropertyValidators extends Record<string, GenericValidator>> =
+  Exclude<keyof PropertyValidators, OptionalKeys<PropertyValidators>>;
 
 /**
  * Extract a TypeScript type from a validator.
@@ -166,4 +172,4 @@ type RequiredKeys<
  *
  * @public
  */
-export type Infer<T extends Validator<any, boolean, any>> = T["type"];
+export type Infer<T extends Validator<any, OptionalProperty, any>> = T["type"];