add helper for convex validators

Author: ianmacartney

packages/convex-helpers/server/validators.test.ts

@@ -16,6 +16,7 @@ import {
   object,
   optional,
   union as or,
+  parse,
   pretend,
   pretendRequired,
   string,
@@ -498,4 +499,102 @@ describe("validate", () => {
     expect(validate(any, null)).toBe(true);
     expect(validate(any, { complex: "object" })).toBe(true);
   });
+
+  test("parse strips unknown fields", () => {
+    const validator = object({
+      name: string,
+      age: number,
+    });
+
+    const result = parse(validator, {
+      name: "Alice",
+      age: 30,
+      unknown: "field",
+    });
+    expect(result).toEqual({ name: "Alice", age: 30 });
+  });
+
+  test("parse strips unknown fields from unions", () => {
+    const validator = or(object({ name: string }), object({ age: number }));
+    const result = parse(validator, {
+      name: "Alice",
+      age: 30,
+      unknown: "field",
+    });
+    expect(result).toEqual({ name: "Alice" });
+  });
+
+  test("parse strips unknown fields from arrays", () => {
+    const validator = array(object({ name: string }));
+    const result = parse(validator, [
+      { name: "Alice" },
+      { name: "Bob", unknown: "field" },
+    ]);
+    expect(result[0]).toMatchObject({ name: "Alice" });
+    expect(result[1]).toMatchObject({ name: "Bob" });
+  });
+
+  test("parse strips unknown fields from records", () => {
+    const validator = vv.record(string, object({ name: string }));
+    const result = parse(validator, {
+      a: { name: "Alice" },
+      b: { name: "Bob", unknown: "field" },
+    });
+    expect(result).toEqual({ a: { name: "Alice" }, b: { name: "Bob" } });
+  });
+
+  test("parse strips unknown fields from nested objects", () => {
+    const validator = object({
+      name: string,
+      age: number,
+      details: object({
+        name: string,
+        age: number,
+      }),
+      union: or(object({ name: string }), object({ age: number })),
+      array: array(object({ name: string })),
+      record: vv.record(string, object({ name: string })),
+    });
+    const result = parse(validator, {
+      name: "Alice",
+      age: 30,
+      details: { name: "Alice", age: 30 },
+      union: { name: "Alice", foo: "bar" },
+      array: [{ name: "Alice", foo: "bar" }],
+      record: { a: { name: "Alice", foo: "bar" } },
+    });
+    expect(result).toEqual({
+      name: "Alice",
+      age: 30,
+      details: { name: "Alice", age: 30 },
+      union: { name: "Alice" },
+      array: [{ name: "Alice" }],
+      record: { a: { name: "Alice" } },
+    });
+  });
+
+  test("union matches first member with unknown fields", () => {
+    const validator = or(
+      object({ name: string }),
+      object({ name: string, age: number }),
+    );
+    const result = parse(validator, {
+      name: "Alice",
+      age: 30,
+      unknown: "field",
+    });
+    expect(result).toEqual({ name: "Alice" });
+  });
+
+  test("union matches second member if matches second strictly", () => {
+    const validator = or(
+      object({ name: string }),
+      object({ name: string, age: number }),
+    );
+    const result = parse(validator, {
+      name: "Alice",
+      age: 30,
+    });
+    expect(result).toEqual({ name: "Alice", age: 30 });
+  });
 });

packages/convex-helpers/validators.ts

@@ -1,5 +1,6 @@
 import type {
   GenericValidator,
+  Infer,
   ObjectType,
   PropertyValidators,
   VObject,
@@ -363,6 +364,8 @@ export function validate<T extends Validator<any, any, any>>(
     throw?: boolean;
     /* If provided, v.id validation will check that the id is for the table. */
     db?: GenericDatabaseReader<GenericDataModel>;
+    /* If true, allow fields that are not in an object validator. */
+    allowUnknownFields?: boolean;
     /* A prefix for the path of the value being validated, for error reporting.
     This is used for recursive calls, do not set it manually. */
     _pathPrefix?: string;
@@ -480,17 +483,19 @@ export function validate<T extends Validator<any, any, any>>(
             break;
           }
         }
-        for (const k of Object.keys(value)) {
-          if (validator.fields[k] === undefined) {
-            if (opts?.throw) {
-              throw new ValidationError(
-                "nothing",
-                typeof (value as any)[k],
-                appendPath(opts, k),
-              );
+        if (!opts?.allowUnknownFields) {
+          for (const k of Object.keys(value)) {
+            if (validator.fields[k] === undefined) {
+              if (opts?.throw) {
+                throw new ValidationError(
+                  "nothing",
+                  typeof (value as any)[k],
+                  appendPath(opts, k),
+                );
+              }
+              valid = false;
+              break;
             }
-            valid = false;
-            break;
           }
         }
         break;
@@ -538,6 +543,61 @@ export function validate<T extends Validator<any, any, any>>(
   return valid;
 }
 
+export function parse<T extends Validator<any, any, any>>(
+  validator: T,
+  value: unknown,
+): Infer<T> {
+  validate(validator, value, { allowUnknownFields: true, throw: true });
+  return stripUnknownFields(validator, value);
+}
+
+function stripUnknownFields<T extends Validator<any, any, any>>(
+  validator: T,
+  value: Infer<T>,
+): Infer<T> {
+  switch (validator.kind) {
+    case "object": {
+      const result: Infer<T> = {};
+      for (const [k, v] of Object.entries(value)) {
+        if (validator.fields[k] !== undefined) {
+          result[k] = stripUnknownFields(validator.fields[k], v);
+        }
+      }
+      return result;
+    }
+    case "record": {
+      const result: Infer<T> = {};
+      for (const [k, v] of Object.entries(value)) {
+        result[k] = stripUnknownFields(validator.value, v);
+      }
+      return result;
+    }
+    case "array": {
+      return (value as any[]).map((e) =>
+        stripUnknownFields(validator.element, e),
+      );
+    }
+    case "union": {
+      // First try a strict match
+      for (const member of validator.members) {
+        if (validate(member, value, { allowUnknownFields: false })) {
+          return stripUnknownFields(member, value);
+        }
+      }
+      // Then try a permissive match
+      for (const member of validator.members) {
+        if (validate(member, value, { allowUnknownFields: true })) {
+          return stripUnknownFields(member, value);
+        }
+      }
+      throw new Error("No matching member in union");
+    }
+    default: {
+      return value as Infer<T>;
+    }
+  }
+}
+
 function appendPath(opts: { _pathPrefix?: string } | undefined, path: string) {
   return opts?._pathPrefix ? `${opts._pathPrefix}.${path}` : path;
 }