convex-helpers 0.1.69 → 0.1.70

package/README.md

@@ -600,20 +600,23 @@ await ctx.runMutation(internal.users.update, {
 When using validators for defining database schema or function arguments,
 these validators help:
 
-1. Add a `Table` utility that defines a table and keeps references to the fields
-   to avoid re-defining validators. To learn more about sharing validators, read
-   [this article](https://stack.convex.dev/argument-validation-without-repetition),
-   an extension of [this article](https://stack.convex.dev/types-cookbook).
-2. Add utilties for `partial`, `pick` and `omit` to match the TypeScript type
-   utilities.
-3. Add shorthand for a union of `literals`, a `nullable` field, a `deprecated`
-   field, and `brandedString`. To learn more about branded strings see
+1. Add shorthand for a union of `literals`, a `nullable` field, a `deprecated`
+   field, a `partial` object, and `brandedString`.
+   To learn more about branded strings see
    [this article](https://stack.convex.dev/using-branded-types-in-validators).
+2. A `validate(validator, data)` function validates a value against a validator.
+   Warning: this does not validate that the value of v.id is an ID for the given table.
+3. Add utilties for `partial`, `pick` and `omit` to match the TypeScript type
+   utilities.
 4. Add a `doc(schema, "tableName")` helper to validate a document with system
    fields included.
 5. Add a `typedV(schema)` helper that is a `v` replacement that also has:
    - `doc("tableName")` that works like `doc` above.
    - `id("tableName")` that is typed to tables in your schema.
+6. Add a `Table` utility that defines a table and keeps references to the fields
+   to avoid re-defining validators. To learn more about sharing validators, read
+   [this article](https://stack.convex.dev/argument-validation-without-repetition),
+   an extension of [this article](https://stack.convex.dev/types-cookbook).
 
 Example:
 
@@ -666,6 +669,11 @@ const balanceAndEmail = pick(vv.doc("accounts").fields, ["balance", "email"]);
 
 // A validator for all the fields except balance.
 const accountWithoutBalance = omit(vv.doc("accounts").fields, ["balance"]);
+
+// Validate against a validator. Can optionally throw on error.
+validate(balanceAndEmail, { balance: 123n, email: "test@example.com" });
+// Warning: this only validates that `accountId` is a string.
+validate(vv.id("accounts"), accountId);
 ```
 
 ## Filter

package/package.json

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

package/validators.d.ts

@@ -55,7 +55,7 @@ export declare const null_: import("convex/values").VNull<null, "required">;
 /** Re-export values from v without having to do v.* */
 export declare const id: <TableName extends string>(tableName: TableName) => import("convex/values").VId<import("convex/values").GenericId<TableName>, "required">, object: <T_2 extends PropertyValidators>(fields: T_2) => VObject<import("convex/server").Expand<{ [Property in { [Property_1 in keyof T_2]: T_2[Property_1]["isOptional"] extends "optional" ? Property_1 : never; }[keyof T_2]]?: Exclude<import("convex/values").Infer<T_2[Property]>, undefined> | undefined; } & { [Property_1 in Exclude<keyof T_2, { [Property in keyof T_2]: T_2[Property]["isOptional"] extends "optional" ? Property : never; }[keyof T_2]>]: import("convex/values").Infer<T_2[Property_1]>; }>, T_2, "required", { [Property_2 in keyof T_2]: Property_2 | `${Property_2 & string}.${T_2[Property_2]["fieldPaths"]}`; }[keyof T_2] & string>, array: <T_1 extends Validator<any, "required", any>>(element: T_1) => import("convex/values").VArray<T_1["type"][], T_1, "required">, bytes: () => import("convex/values").VBytes<ArrayBuffer, "required">, literal: <T extends string | number | bigint | boolean>(literal: T) => import("convex/values").VLiteral<T, "required">, optional: <T_4 extends GenericValidator>(value: T_4) => VOptional<T_4>, union: <T_3 extends Validator<any, "required", any>[]>(...members: T_3) => VUnion<T_3[number]["type"], T_3, "required", T_3[number]["fieldPaths"]>;
 /** ArrayBuffer validator. */
-export declare const arrayBuffer: () => import("convex/values").VBytes<ArrayBuffer, "required">;
+export declare const arrayBuffer: import("convex/values").VBytes<ArrayBuffer, "required">;
 /**
  * Utility to get the validators for fields associated with a table.
  * e.g. for systemFields("users") it would return:
@@ -215,4 +215,25 @@ export declare const pretend: <T extends GenericValidator>(_typeToImmitate: T) =
  * });
  */
 export declare const pretendRequired: <T extends Validator<any, "required", any>>(optionalType: T) => T;
+export declare class ValidationError extends Error {
+    expected: string;
+    got: string;
+    path?: string | undefined;
+    constructor(expected: string, got: string, path?: string | undefined);
+}
+/**
+ * Validate a value against a validator.
+ *
+ * WARNING: This does not validate that v.id is an ID for the given table.
+ * It only validates that the ID is a string. Function `args`, `returns` and
+ * schema definitions will validate that the ID is an ID for the given table.
+ *
+ * @param validator The validator to validate against.
+ * @param value The value to validate.
+ * @returns Whether the value is valid against the validator.
+ */
+export declare function validate<T extends Validator<any, any, any>>(validator: T, value: unknown, opts?: {
+    throw?: boolean;
+    pathPrefix?: string;
+}): value is T["type"];
 //# sourceMappingURL=validators.d.ts.map

package/validators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["validators.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["validators.ts"],"names":[],"mappings":"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"}

package/validators.js

@@ -64,7 +64,7 @@ export const null_ = v.null();
 /** Re-export values from v without having to do v.* */
 export const { id, object, array, bytes, literal, optional, union } = v;
 /** ArrayBuffer validator. */
-export const arrayBuffer = bytes;
+export const arrayBuffer = bytes();
 /**
  * Utility to get the validators for fields associated with a table.
  * e.g. for systemFields("users") it would return:
@@ -223,3 +223,187 @@ export const pretend = (_typeToImmitate) => v.optional(v.any());
  * });
  */
 export const pretendRequired = (optionalType) => v.optional(optionalType);
+export class ValidationError extends Error {
+    expected;
+    got;
+    path;
+    constructor(expected, got, path) {
+        const message = `Validator error${path ? ` for ${path}` : ""}: Expected \`${expected}\`, got \`${got}\``;
+        super(message);
+        this.expected = expected;
+        this.got = got;
+        this.path = path;
+        this.name = "ValidationError";
+    }
+}
+/**
+ * Validate a value against a validator.
+ *
+ * WARNING: This does not validate that v.id is an ID for the given table.
+ * It only validates that the ID is a string. Function `args`, `returns` and
+ * schema definitions will validate that the ID is an ID for the given table.
+ *
+ * @param validator The validator to validate against.
+ * @param value The value to validate.
+ * @returns Whether the value is valid against the validator.
+ */
+export function validate(validator, value, opts) {
+    let valid = true;
+    let expected = validator.kind;
+    if (value === undefined) {
+        if (validator.isOptional !== "optional") {
+            valid = false;
+        }
+    }
+    else {
+        switch (validator.kind) {
+            case "null": {
+                if (value !== null) {
+                    valid = false;
+                }
+                break;
+            }
+            case "float64": {
+                if (typeof value !== "number") {
+                    expected = "number";
+                    valid = false;
+                }
+                break;
+            }
+            case "int64": {
+                if (typeof value !== "bigint") {
+                    expected = "bigint";
+                    valid = false;
+                }
+                break;
+            }
+            case "boolean": {
+                if (typeof value !== "boolean") {
+                    valid = false;
+                }
+                break;
+            }
+            case "string": {
+                if (typeof value !== "string") {
+                    valid = false;
+                }
+                break;
+            }
+            case "bytes": {
+                if (!(value instanceof ArrayBuffer)) {
+                    valid = false;
+                }
+                break;
+            }
+            case "any": {
+                break;
+            }
+            case "literal": {
+                if (value !== validator.value) {
+                    valid = false;
+                }
+                break;
+            }
+            case "id": {
+                if (typeof value !== "string") {
+                    valid = false;
+                }
+                break;
+            }
+            case "array": {
+                if (!Array.isArray(value)) {
+                    valid = false;
+                    break;
+                }
+                for (const [index, v] of value.entries()) {
+                    const path = `${opts?.pathPrefix ?? ""}[${index}]`;
+                    valid = validate(validator.element, v, { ...opts, pathPrefix: path });
+                    if (!valid) {
+                        expected = validator.element.kind;
+                        break;
+                    }
+                }
+                break;
+            }
+            case "object": {
+                if (typeof value !== "object" || value === null) {
+                    valid = false;
+                    break;
+                }
+                const prototype = Object.getPrototypeOf(value);
+                const isSimple = prototype === null ||
+                    prototype === Object.prototype ||
+                    // Objects generated from other contexts (e.g. across Node.js `vm` modules) will not satisfy the previous
+                    // conditions but are still simple objects.
+                    prototype?.constructor?.name === "Object";
+                if (!isSimple) {
+                    expected =
+                        prototype?.constructor?.name ?? typeof prototype ?? "object";
+                    valid = false;
+                    break;
+                }
+                for (const [k, fieldValidator] of Object.entries(validator.fields)) {
+                    valid = validate(fieldValidator, value[k], {
+                        ...opts,
+                        pathPrefix: appendPath(opts, k),
+                    });
+                    if (!valid) {
+                        break;
+                    }
+                }
+                for (const k of Object.keys(value)) {
+                    if (validator.fields[k] === undefined) {
+                        if (opts?.throw) {
+                            throw new ValidationError("nothing", typeof value[k], appendPath(opts, k));
+                        }
+                        valid = false;
+                        break;
+                    }
+                }
+                break;
+            }
+            case "union": {
+                valid = false;
+                for (const member of validator.members) {
+                    if (validate(member, value, opts)) {
+                        valid = true;
+                        break;
+                    }
+                }
+                break;
+            }
+            case "record": {
+                if (typeof value !== "object" || value === null) {
+                    valid = false;
+                    break;
+                }
+                for (const [k, fieldValue] of Object.entries(value)) {
+                    valid = validate(validator.key, k, {
+                        ...opts,
+                        pathPrefix: appendPath(opts, k),
+                    });
+                    if (!valid) {
+                        expected = validator.key.kind;
+                        break;
+                    }
+                    valid = validate(validator.value, fieldValue, {
+                        ...opts,
+                        pathPrefix: appendPath(opts, k),
+                    });
+                    if (!valid) {
+                        expected = validator.value.kind;
+                        break;
+                    }
+                }
+                break;
+            }
+        }
+    }
+    if (!valid && opts?.throw) {
+        throw new ValidationError(expected, typeof value, opts?.pathPrefix);
+    }
+    return valid;
+}
+function appendPath(opts, path) {
+    return opts?.pathPrefix ? `${opts.pathPrefix}.${path}` : path;
+}

package/validators.ts

@@ -96,7 +96,7 @@ export const null_ = v.null();
 /** Re-export values from v without having to do v.* */
 export const { id, object, array, bytes, literal, optional, union } = v;
 /** ArrayBuffer validator. */
-export const arrayBuffer = bytes;
+export const arrayBuffer = bytes();
 
 /**
  * Utility to get the validators for fields associated with a table.
@@ -329,3 +329,200 @@ export const pretend = <T extends GenericValidator>(_typeToImmitate: T): T =>
 export const pretendRequired = <T extends Validator<any, "required", any>>(
   optionalType: T,
 ): T => v.optional(optionalType) as unknown as T;
+
+export class ValidationError extends Error {
+  constructor(
+    public expected: string,
+    public got: string,
+    public path?: string,
+  ) {
+    const message = `Validator error${path ? ` for ${path}` : ""}: Expected \`${expected}\`, got \`${got}\``;
+    super(message);
+    this.name = "ValidationError";
+  }
+}
+
+/**
+ * Validate a value against a validator.
+ *
+ * WARNING: This does not validate that v.id is an ID for the given table.
+ * It only validates that the ID is a string. Function `args`, `returns` and
+ * schema definitions will validate that the ID is an ID for the given table.
+ *
+ * @param validator The validator to validate against.
+ * @param value The value to validate.
+ * @returns Whether the value is valid against the validator.
+ */
+export function validate<T extends Validator<any, any, any>>(
+  validator: T,
+  value: unknown,
+  opts?: {
+    throw?: boolean;
+    pathPrefix?: string;
+  },
+): value is T["type"] {
+  let valid = true;
+  let expected: string = validator.kind;
+  if (value === undefined) {
+    if (validator.isOptional !== "optional") {
+      valid = false;
+    }
+  } else {
+    switch (validator.kind) {
+      case "null": {
+        if (value !== null) {
+          valid = false;
+        }
+        break;
+      }
+      case "float64": {
+        if (typeof value !== "number") {
+          expected = "number";
+          valid = false;
+        }
+        break;
+      }
+      case "int64": {
+        if (typeof value !== "bigint") {
+          expected = "bigint";
+          valid = false;
+        }
+        break;
+      }
+      case "boolean": {
+        if (typeof value !== "boolean") {
+          valid = false;
+        }
+        break;
+      }
+      case "string": {
+        if (typeof value !== "string") {
+          valid = false;
+        }
+        break;
+      }
+      case "bytes": {
+        if (!(value instanceof ArrayBuffer)) {
+          valid = false;
+        }
+        break;
+      }
+      case "any": {
+        break;
+      }
+      case "literal": {
+        if (value !== validator.value) {
+          valid = false;
+        }
+        break;
+      }
+      case "id": {
+        if (typeof value !== "string") {
+          valid = false;
+        }
+        break;
+      }
+      case "array": {
+        if (!Array.isArray(value)) {
+          valid = false;
+          break;
+        }
+        for (const [index, v] of value.entries()) {
+          const path = `${opts?.pathPrefix ?? ""}[${index}]`;
+          valid = validate(validator.element, v, { ...opts, pathPrefix: path });
+          if (!valid) {
+            expected = validator.element.kind;
+            break;
+          }
+        }
+        break;
+      }
+      case "object": {
+        if (typeof value !== "object" || value === null) {
+          valid = false;
+          break;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        const isSimple =
+          prototype === null ||
+          prototype === Object.prototype ||
+          // Objects generated from other contexts (e.g. across Node.js `vm` modules) will not satisfy the previous
+          // conditions but are still simple objects.
+          prototype?.constructor?.name === "Object";
+
+        if (!isSimple) {
+          expected =
+            prototype?.constructor?.name ?? typeof prototype ?? "object";
+          valid = false;
+          break;
+        }
+        for (const [k, fieldValidator] of Object.entries(validator.fields)) {
+          valid = validate(fieldValidator, (value as any)[k], {
+            ...opts,
+            pathPrefix: appendPath(opts, k),
+          });
+          if (!valid) {
+            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),
+              );
+            }
+            valid = false;
+            break;
+          }
+        }
+        break;
+      }
+      case "union": {
+        valid = false;
+        for (const member of validator.members) {
+          if (validate(member, value, opts)) {
+            valid = true;
+            break;
+          }
+        }
+        break;
+      }
+      case "record": {
+        if (typeof value !== "object" || value === null) {
+          valid = false;
+          break;
+        }
+        for (const [k, fieldValue] of Object.entries(value)) {
+          valid = validate(validator.key, k, {
+            ...opts,
+            pathPrefix: appendPath(opts, k),
+          });
+          if (!valid) {
+            expected = validator.key.kind;
+            break;
+          }
+          valid = validate(validator.value, fieldValue, {
+            ...opts,
+            pathPrefix: appendPath(opts, k),
+          });
+          if (!valid) {
+            expected = validator.value.kind;
+            break;
+          }
+        }
+        break;
+      }
+    }
+  }
+  if (!valid && opts?.throw) {
+    throw new ValidationError(expected, typeof value, opts?.pathPrefix);
+  }
+  return valid;
+}
+
+function appendPath(opts: { pathPrefix?: string } | undefined, path: string) {
+  return opts?.pathPrefix ? `${opts.pathPrefix}.${path}` : path;
+}