convex/src/server/system_fields.ts

Client for the Convex Cloud

import { GenericId } from "../values/index.js";
import { DistributiveOmit, Expand } from "../type_utils";
import { GenericDocument } from "./data_model";

/**
 * The fields that Convex automatically adds to documents, not including `_id`.
 *
 * This is an object type mapping field name to field type.
 * @public
 */
export type SystemFields = {
  _creationTime: number;
};

/**
 * The `_id` field that Convex automatically adds to documents.
 * @public
 */
export type IdField<TableName extends string> = {
  _id: GenericId<TableName>;
};

/**
 * A Convex document with the system fields like `_id` and `_creationTime` omitted.
 *
 * @public
 */
export type WithoutSystemFields<Document extends GenericDocument> = Expand<
  DistributiveOmit<Document, keyof SystemFields | "_id">
>;

/**
 * A Convex document with the system fields like `_id` and `_creationTime` optional.
 *
 * @public
 */
export type WithOptionalSystemFields<Document extends GenericDocument> = Expand<
  WithoutSystemFields<Document> &
    Partial<Pick<Document, keyof SystemFields | "_id">>
>;

/**
 * The indexes that Convex automatically adds to every table.
 *
 * This is an object mapping index names to index field paths.
 * @public
 */
export type SystemIndexes = {
  // We have a system index `by_id` but developers should never have a use
  // for querying it (`db.get(id)` is always simpler).
  // by_id: ["_id"];

  by_creation_time: ["_creationTime"];
};

/**
 * Convex automatically appends "_creationTime" to the end of every index to
 * break ties if all of the other fields are identical.
 * @public
 */
export type IndexTiebreakerField = "_creationTime";