convex/src/values/validator.ts

Client for the Convex Cloud

import { Expand } from "../type_utils.js";
import { GenericId } from "./index.js";
import {
  OptionalProperty,
  VAny,
  VArray,
  VBoolean,
  VBytes,
  VFloat64,
  VId,
  VInt64,
  VLiteral,
  VNull,
  VObject,
  VOptional,
  VRecord,
  VString,
  VUnion,
  Validator,
} from "./validators.js";

/**
 * 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.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.
 *
 * This builder allows you to build validators for Convex values. Validators
 * are used in two places:
 *
 * 1. **Schema definitions** - to define the shape of documents in your tables.
 * 2. **Function arguments and return values** - to validate inputs and outputs
 *    of your Convex queries, mutations, and actions.
 *
 * Always include `args` and `returns` validators on all Convex functions. If a
 * function doesn't return a value, use `returns: v.null()`.
 *
 * **Convex type reference:**
 *
 * | Convex Type | JS/TS Type    | Validator                      |
 * |-------------|---------------|--------------------------------|
 * | Id          | `string`      | `v.id("tableName")`            |
 * | Null        | `null`        | `v.null()`                     |
 * | Float64     | `number`      | `v.number()`                   |
 * | Int64       | `bigint`      | `v.int64()`                    |
 * | Boolean     | `boolean`     | `v.boolean()`                  |
 * | String      | `string`      | `v.string()`                   |
 * | Bytes       | `ArrayBuffer` | `v.bytes()`                    |
 * | Array       | `Array`       | `v.array(element)`             |
 * | Object      | `Object`      | `v.object({ field: value })`   |
 * | Record      | `Record`      | `v.record(keys, values)`       |
 *
 * **Modifiers and meta-types:**
 * - `v.union(member1, member2)` - a value matching at least one validator
 * - `v.literal("value")` - a specific literal string, number, bigint, or boolean
 * - `v.optional(validator)` - makes a property optional in an object (`T | undefined`)
 *
 * **Important notes:**
 * - JavaScript's `undefined` is **not** a valid Convex value. Functions that
 *   return `undefined` or have no return will return `null` to the client.
 *   Objects with `undefined` values will strip those keys during serialization.
 *   For arrays, use an explicit `null` instead.
 * - `v.bigint()` is deprecated, use `v.int64()` instead.
 * - `v.map()` and `v.set()` are not supported. Use `v.array()` of tuples or
 *   `v.record()` as alternatives.
 *
 * @example
 * ```typescript
 * import { v } from "convex/values";
 *
 * // Use in function definition:
 * export const createUser = mutation({
 *   args: {
 *     name: v.string(),
 *     email: v.string(),
 *     age: v.optional(v.number()),
 *   },
 *   returns: v.id("users"),
 *   handler: async (ctx, args) => {
 *     return await ctx.db.insert("users", args);
 *   },
 * });
 * ```
 *
 * @see https://docs.convex.dev/database/types
 * @see https://docs.convex.dev/functions/validation
 * @public
 */
export const v = {
  /**
   * Validates that the value is a document ID for the given table.
   *
   * IDs are strings at runtime but are typed as `Id<"tableName">` in
   * TypeScript for type safety.
   *
   * @example
   * ```typescript
   * args: { userId: v.id("users") }
   * ```
   *
   * @param tableName The name of the table.
   */
  id: <TableName extends string>(tableName: TableName) => {
    return new VId<GenericId<TableName>>({
      isOptional: "required",
      tableName,
    });
  },

  /**
   * Validates that the value is `null`.
   *
   * Use `returns: v.null()` for functions that don't return a meaningful value.
   * JavaScript `undefined` is not a valid Convex value, it is automatically
   * converted to `null`.
   */
  null: () => {
    return new VNull({ isOptional: "required" });
  },

  /**
   * Validates that the value is a JavaScript `number` (Convex Float64).
   *
   * Supports all IEEE-754 double-precision floating point numbers including
   * NaN and Infinity.
   *
   * Alias for `v.float64()`.
   */
  number: () => {
    return new VFloat64({ isOptional: "required" });
  },

  /**
   * Validates that the value is a JavaScript `number` (Convex Float64).
   *
   * Supports all IEEE-754 double-precision floating point numbers.
   */
  float64: () => {
    return new VFloat64({ isOptional: "required" });
  },

  /**
   * @deprecated Use `v.int64()` instead.
   */
  bigint: () => {
    return new VInt64({ isOptional: "required" });
  },

  /**
   * Validates that the value is a JavaScript `bigint` (Convex Int64).
   *
   * Supports BigInts between -2^63 and 2^63-1.
   *
   * @example
   * ```typescript
   * args: { timestamp: v.int64() }
   * // Usage: createDoc({ timestamp: 1234567890n })
   * ```
   */
  int64: () => {
    return new VInt64({ isOptional: "required" });
  },

  /**
   * Validates that the value is a `boolean`.
   */
  boolean: () => {
    return new VBoolean({ isOptional: "required" });
  },

  /**
   * Validates that the value is a `string`.
   *
   * Strings are stored as UTF-8 and their storage size is calculated as their
   * UTF-8 encoded size.
   */
  string: () => {
    return new VString({ isOptional: "required" });
  },

  /**
   * Validates that the value is an `ArrayBuffer` (Convex Bytes).
   *
   * Use for binary data.
   */
  bytes: () => {
    return new VBytes({ isOptional: "required" });
  },

  /**
   * Validates that the value is exactly equal to the given literal.
   *
   * Useful for discriminated unions and enum-like patterns.
   *
   * @example
   * ```typescript
   * // Discriminated union pattern:
   * v.union(
   *   v.object({ kind: v.literal("error"), message: v.string() }),
   *   v.object({ kind: v.literal("success"), value: v.number() }),
   * )
   * ```
   *
   * @param literal The literal value to compare against.
   */
  literal: <T extends string | number | bigint | boolean>(literal: T) => {
    return new VLiteral<T>({ isOptional: "required", value: literal });
  },

  /**
   * Validates that the value is an `Array` where every element matches the
   * given validator.
   *
   * Arrays can have at most 8192 elements.
   *
   * @example
   * ```typescript
   * args: { tags: v.array(v.string()) }
   * args: { coordinates: v.array(v.number()) }
   * args: { items: v.array(v.object({ name: v.string(), qty: v.number() })) }
   * ```
   *
   * @param element The validator for the elements of the array.
   */
  array: <T extends Validator<any, "required", any>>(element: T) => {
    return new VArray<T["type"][], T>({ isOptional: "required", element });
  },

  /**
   * Validates that the value is an `Object` with the specified properties.
   *
   * Objects can have at most 1024 entries. Field names must be non-empty and
   * must not start with `"$"` or `"_"` (`_` is reserved for system fields
   * like `_id` and `_creationTime`; `$` is reserved for Convex internal use).
   *
   * @example
   * ```typescript
   * args: {
   *   user: v.object({
   *     name: v.string(),
   *     email: v.string(),
   *     age: v.optional(v.number()),
   *   })
   * }
   * ```
   *
   * @param fields An object mapping property names to their validators.
   */
  object: <T extends PropertyValidators>(fields: T) => {
    return new VObject<ObjectType<T>, T>({ isOptional: "required", fields });
  },

  /**
   * Validates that the value is a `Record` (object with dynamic keys).
   *
   * Records are objects at runtime but allow dynamic keys, unlike `v.object()`
   * which requires known property names. Keys must be ASCII characters only,
   * non-empty, and not start with `"$"` or `"_"`.
   *
   * @example
   * ```typescript
   * // Map of user IDs to scores:
   * args: { scores: v.record(v.id("users"), v.number()) }
   *
   * // Map of string keys to string values:
   * args: { metadata: v.record(v.string(), v.string()) }
   * ```
   *
   * @param keys The validator for the keys of the record.
   * @param values The validator for the values of the record.
   */
  record: <
    Key extends Validator<string, "required", any>,
    Value extends Validator<any, "required", any>,
  >(
    keys: Key,
    values: Value,
  ) => {
    return new VRecord<Record<Infer<Key>, Value["type"]>, Key, Value>({
      isOptional: "required",
      key: keys,
      value: values,
    });
  },

  /**
   * Validates that the value matches at least one of the given validators.
   *
   * @example
   * ```typescript
   * // Allow string or number:
   * args: { value: v.union(v.string(), v.number()) }
   *
   * // Discriminated union (recommended pattern):
   * v.union(
   *   v.object({ kind: v.literal("text"), body: v.string() }),
   *   v.object({ kind: v.literal("image"), url: v.string() }),
   * )
   *
   * // Nullable value:
   * returns: v.union(v.object({ ... }), v.null())
   * ```
   *
   * @param members The validators to match against.
   */
  union: <T extends Validator<any, "required", any>[]>(...members: T) => {
    return new VUnion<T[number]["type"], T>({
      isOptional: "required",
      members,
    });
  },

  /**
   * A validator that accepts any Convex value without validation.
   *
   * Prefer using specific validators when possible for better type safety
   * and runtime validation.
   */
  any: () => {
    return new VAny({ isOptional: "required" });
  },

  /**
   * Makes a property optional in an object validator.
   *
   * An optional property can be omitted entirely when creating a document or
   * calling a function. This is different from `v.nullable()` which requires
   * the property to be present but allows `null`.
   *
   * @example
   * ```typescript
   * v.object({
   *   name: v.string(),              // required
   *   nickname: v.optional(v.string()), // can be omitted
   * })
   *
   * // Valid: { name: "Alice" }
   * // Valid: { name: "Alice", nickname: "Ali" }
   * // Invalid: { name: "Alice", nickname: null }  - use v.nullable() for this
   * ```
   *
   * @param value The property value validator to make optional.
   */
  optional: <T extends GenericValidator>(value: T) => {
    return value.asOptional() as VOptional<T>;
  },

  /**
   * Allows a value to be either the given type or `null`.
   *
   * This is shorthand for `v.union(value, v.null())`. Unlike `v.optional()`,
   * the property must still be present, but may be `null`.
   *
   * @example
   * ```typescript
   * v.object({
   *   name: v.string(),
   *   deletedAt: v.nullable(v.number()), // must be present, can be null
   * })
   *
   * // Valid: { name: "Alice", deletedAt: null }
   * // Valid: { name: "Alice", deletedAt: 1234567890 }
   * // Invalid: { name: "Alice" }  - deletedAt is required
   * ```
   */
  nullable: <T extends Validator<any, "required", any>>(value: T) => {
    return v.union(value, v.null());
  },
};

/**
 * Validators for each property of an object.
 *
 * This is represented as an object mapping the property name to its
 * {@link Validator}.
 *
 * @public
 */
export type PropertyValidators = Record<
  string,
  Validator<any, OptionalProperty, any>
>;

/**
 * Compute the type of an object from {@link PropertyValidators}.
 *
 * @public
 */
export type ObjectType<Fields extends PropertyValidators> = Expand<
  // Map each key to the corresponding property validator's type making
  // the optional ones optional.
  {
    // This `Exclude<..., undefined>` does nothing unless
    // the tsconfig.json option `"exactOptionalPropertyTypes": true,`
    // is used. When it is it results in a more accurate type.
    // When it is not the `Exclude` removes `undefined` but it is
    // added again by the optional property.
    [Property in OptionalKeys<Fields>]?: Exclude<
      Infer<Fields[Property]>,
      undefined
    >;
  } & {
    [Property in RequiredKeys<Fields>]: Infer<Fields[Property]>;
  }
>;

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, GenericValidator>> =
  Exclude<keyof PropertyValidators, OptionalKeys<PropertyValidators>>;

/**
 * Extract a TypeScript type from a validator.
 *
 * Example usage:
 * ```ts
 * const objectSchema = v.object({
 *   property: v.string(),
 * });
 * type MyObject = Infer<typeof objectSchema>; // { property: string }
 * ```
 * @typeParam V - The type of a {@link Validator} constructed with {@link v}.
 *
 * @public
 */
export type Infer<T extends Validator<any, OptionalProperty, any>> = T["type"];