convex/src/server/data_model.ts

Client for the Convex Cloud

import { Value } from "../values/index.js";

// Document Types  /////////////////////////////////////////////////////////////

/**
 * A document stored in Convex.
 * @public
 */
export type GenericDocument = Record<string, Value>;

/**
 * A type describing all of the document fields in a table.
 *
 * These can either be field names (like "name") or references to fields on
 * nested objects (like "properties.name").
 * @public
 */
export type GenericFieldPaths = string;

// Index Types  ///////////////////////////////////////////////////////////////

/**
 * A type describing the ordered fields in an index.
 *
 * These can either be field names (like "name") or references to fields on
 * nested objects (like "properties.name").
 * @public
 */
export type GenericIndexFields = string[];

/**
 * A type describing the indexes in a table.
 *
 * It's a map from index name to fields in the index.
 * @public
 */
export type GenericTableIndexes = Record<string, GenericIndexFields>;

/**
 * The type of a field in a document.
 *
 * Note that this supports both simple fields like "name" and nested fields like
 * "properties.name".
 *
 * If the field is not present in the document it is considered to be `null`.
 *
 * @public
 */
export type FieldTypeFromFieldPath<
  Document extends GenericDocument,
  FieldPath extends string
> = FieldPath extends `${infer First}.${infer Second}`
  ? First extends keyof Document
    ? // This is slightly incorrect because `GenericDocument` includes some Convex
      // values that aren't objects like Array and Id.
      Document[First] extends GenericDocument
      ? FieldTypeFromFieldPath<Document[First], Second>
      : null
    : null
  : FieldPath extends keyof Document
  ? Document[FieldPath]
  : null;

// Table Types /////////////////////////////////////////////////////////////////

/**
 * A type describing the document type and indexes in a table.
 * @public
 */
export type GenericTableInfo = {
  document: GenericDocument;
  fieldPaths: GenericFieldPaths;
  indexes: GenericTableIndexes;
};

/**
 * The type of a document in a table for a given {@link GenericTableInfo}.
 * @public
 */
export type DocumentByInfo<TableInfo extends GenericTableInfo> =
  TableInfo["document"];

/**
 * The field paths in a table for a given {@link GenericTableInfo}.
 *
 * These can either be field names (like "name") or references to fields on
 * nested objects (like "properties.name").
 * @public
 */
export type FieldPaths<TableInfo extends GenericTableInfo> =
  TableInfo["fieldPaths"];

/**
 * The names of indexes in a table for a given {@link GenericTableInfo}.
 * @public
 */
export type IndexNames<TableInfo extends GenericTableInfo> =
  keyof TableInfo["indexes"];

/**
 * Extract the fields of an index from a {@link GenericTableInfo} by name.
 * @public
 */
export type NamedIndex<
  TableInfo extends GenericTableInfo,
  IndexName extends IndexNames<TableInfo>
> = TableInfo["indexes"][IndexName];

// Data Model Types ////////////////////////////////////////////////////////////

/**
 * A type describing the tables in a Convex project.
 *
 * This is designed to be code generated with `npx convex codegen`.
 * @public
 */
export type GenericDataModel = Record<string, GenericTableInfo>;

/**
 * A {@link GenericDataModel} that considers documents to be `any` and does not
 * support indexes.
 *
 * This is the default before a schema is defined.
 * @public
 */
export type AnyDataModel = Record<
  string,
  {
    document: any;
    fieldPaths: GenericFieldPaths;
    // eslint-disable-next-line @typescript-eslint/ban-types
    indexes: {};
  }
>;

/**
 * A type of all of the table names defined in a {@link GenericDataModel}.
 * @public
 */
export type TableNamesInDataModel<DataModel extends GenericDataModel> =
  keyof DataModel & string;

/**
 * Extract the `TableInfo` for a table in a {@link GenericDataModel} by table
 * name.
 *
 * @public
 */
export type NamedTableInfo<
  DataModel extends GenericDataModel,
  TableName extends keyof DataModel
> = DataModel[TableName];

/**
 * The type of a document in a {@link GenericDataModel} by table name.
 * @public
 */
export type DocumentByName<
  DataModel extends GenericDataModel,
  TableName extends TableNamesInDataModel<DataModel>
> = DataModel[TableName]["document"];