convex/dist/types/schema/schema.d.ts

Client for the Convex Cloud

/**
 * Internal type used in Convex code generation!
 *
 * Convert a {@link SchemaDefinition} into a {@link server.GenericDataModel}.
 *
 * @public
 */
export declare type DataModelFromSchemaDefinition<SchemaDef extends SchemaDefinition<any>> = SchemaDef extends SchemaDefinition<infer Schema> ? {
    [TableName in keyof Schema & string]: Schema[TableName] extends TableDefinition<infer Document, infer FieldPaths, infer TableIndexes> ? {
        document: Expand<IdField<TableName> & Document>;
        fieldPaths: keyof IdField<TableName> | FieldPaths;
        indexes: Expand<TableIndexes & SystemIndexes>;
    } : never;
} : never;

/**
 * Define the schema of this Convex project.
 *
 * This should be exported from a `schema.ts` file in your `convex/` directory
 * like:
 *
 * ```ts
 * export default defineSchema({
 *   ...
 * });
 * ```
 *
 * @param schema - A map from table name to {@link TableDefinition} for all of
 * the tables in this project.
 * @returns The schema.
 *
 * @public
 */
export declare function defineSchema<Schema extends GenericSchema>(schema: Schema): SchemaDefinition<Schema>;

/**
 * Define a table in a schema.
 *
 * You can either specify the schema of your documents as an object like
 * ```ts
 * defineTable({
 *   field: s.string()
 * });
 * ```
 *
 * or as a schema type like
 * ```ts
 * defineTable(
 *  s.union(
 *    s.object({...}),
 *    s.object({...})
 *  )
 * );
 * ```
 *
 * @param documentSchema - The type of documents stored in this table.
 * @returns A {@link TableDefinition} for the table.
 *
 * @public
 */
export declare function defineTable<DocumentSchema extends SchemaType<Record<string, any>, any>>(documentSchema: DocumentSchema): TableDefinition<ExtractDocument<DocumentSchema>, ExtractFieldPaths<DocumentSchema>>;

/**
 * Define a table in a schema.
 *
 * You can either specify the schema of your documents as an object like
 * ```ts
 * defineTable({
 *   field: s.string()
 * });
 * ```
 *
 * or as a schema type like
 * ```ts
 * defineTable(
 *  s.union(
 *    s.object({...}),
 *    s.object({...})
 *  )
 * );
 * ```
 *
 * @param documentSchema - The type of documents stored in this table.
 * @returns A {@link TableDefinition} for the table.
 *
 * @public
 */
export declare function defineTable<DocumentSchema extends Record<string, SchemaType<any, any>>>(documentSchema: DocumentSchema): TableDefinition<ExtractDocument<ObjectSchemaType<DocumentSchema>>, ExtractFieldPaths<ObjectSchemaType<DocumentSchema>>>;

/**
 * Internal type used in Convex code generation!
 *
 * Convert a {@link SchemaDefinition} into an object type that maps table names
 * to their document types.
 *
 * This is similar to {@link server.GenericDataModel} but it doesn't contain
 * index information. This is nice for making some types appear simpler in
 * VSCode.
 *
 * @public
 */
export declare type DocumentMapFromSchemaDefinition<SchemaDef extends SchemaDefinition<any>> = SchemaDef extends SchemaDefinition<infer Schema> ? {
    [TableName in keyof Schema & string]: Schema[TableName] extends TableDefinition<infer Document, any, any> ? Expand<IdField<TableName> & Document> : never;
} : never;

/**
 * Common utilities for manipulating TypeScript types.
 * @module
 */
/**
 * Hack! This type causes TypeScript to simplify how it renders object types.
 *
 * It is functionally the identity for object types, but in practice it can
 * simplify expressions like `A & B`.
 */
declare type Expand<ObjectType extends Record<any, any>> = ObjectType extends Record<any, any> ? {
    [Key in keyof ObjectType]: ObjectType[Key];
} : never;

/**
 * Extract the {@link GenericDocument} within a {@link SchemaType} and
 * add on the system fields.
 *
 * This is used within {@link defineTable}.
 * @public
 */
declare type ExtractDocument<T extends SchemaType<any, any>> = T extends SchemaType<infer Value, any> ? Value extends GenericDocument ? Expand<SystemFields & Value> : never : never;

/**
 * Extract all of the index field paths within a {@link SchemaType}.
 *
 * This is used within {@link defineTable}.
 * @public
 */
declare type ExtractFieldPaths<T extends SchemaType<any, any>> = T extends SchemaType<any, infer FieldPaths> ? // Add in the system fields available in index definitions.
FieldPaths | keyof SystemFields : never;

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

/**
 * An identifier for a document in Convex.
 *
 * Convex documents are uniquely identified by their `GenericId`, which is accessible
 * on the `_id` field. To learn more, see [Data Modeling](https://docs.convex.dev/using/data-modeling).
 *
 * Documents can be loaded using `db.get(id)` in query and mutation functions.
 *
 * **Important**: Use `myId.equals(otherId)` to check for equality.
 * Using `===` will not work because two different instances of `GenericId` can refer
 * to the same document.
 *
 * `GenericId`s are 17 bytes long and consist of:
 * - A 15-byte random value.
 * - A 2-byte timestamp representing the document's creation, in days since the Unix epoch.
 * This is encoded in base 62 ([0-9A-Za-z]).
 *
 * If you're using code generation, use the `Id` class typed for your data model in
 * `convex/_generated/dataModel.js`.
 *
 * @typeParam TableName - A string literal type of the table name (like "users").
 *
 * @public
 */
declare class GenericId<TableName extends string> {
    /**
     * The table name this {@link GenericId} references.
     */
    readonly tableName: TableName;
    /**
     * The identifier string.
     *
     * This contains the characters `[0-9A-Za-z]`.
     */
    readonly id: string;
    constructor(tableName: TableName, id: string);
    /**
     * Check if this {@link GenericId} refers to the same document as another {@link GenericId}.
     *
     * @param other - The other {@link GenericId} to compare to.
     * @returns `true` if the objects refer to the same document.
     */
    equals(other: unknown): boolean;
    /**
     * Parse a {@link GenericId} from its JSON representation.
     */
    static fromJSON(obj: any): GenericId<string>;
    /**
     * Convert a {@link GenericId} into its JSON representation.
     */
    toJSON(): JSONValue;
    /**
     * Convert a {@link GenericId} into its string representation.
     *
     * This includes the identifier but not the table name.
     */
    toString(): string;
    /**
     * Pretty-print this {@link GenericId} for debugging.
     */
    inspect(): string;
}

/**
 * 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
 */
declare type GenericIndexFields = string[];

/**
 * A type describing the schema of a Convex project.
 *
 * This should be constructed using {@link defineSchema}, {@link defineTable},
 * and {@link s}.
 * @public
 */
export declare type GenericSchema = Record<string, TableDefinition>;

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

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

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

/**
 * Join together two index field paths.
 *
 * This is used within the SchemaBuilder {@link s}.
 * @public
 */
declare type JoinFieldPaths<Start extends string, End extends string> = `${Start}.${End}`;

/**
 * The type of JavaScript values serializable to JSON.
 *
 * @public
 */
declare type JSONValue = null | boolean | number | string | JSONValue[] | {
    [key: string]: JSONValue;
};

/**
 * Calculate the {@link SchemaType} for an object.
 *
 * This is used within the SchemaBuilder {@link s}.
 * @public
 */
declare type ObjectSchemaType<SchemaValueType extends Record<string, SchemaType<any, any>>> = SchemaType<{
    [Property in keyof SchemaValueType]: SchemaValueType[Property] extends SchemaType<infer InnerType, any> ? InnerType : never;
}, {
    [Property in keyof SchemaValueType]: SchemaValueType[Property] extends SchemaType<any, infer FieldPaths> ? JoinFieldPaths<Property & string, FieldPaths> | Property : never;
}[keyof SchemaValueType] & string>;

/**
 * The schema builder.
 *
 * This builder allows you to define the types of documents stored in Convex.
 * @public
 */
export declare const s: {
    id<TableName extends string>(tableName: TableName): SchemaType<GenericId<TableName>, never>;
    null(): SchemaType<null, never>;
    number(): SchemaType<number, never>;
    bigint(): SchemaType<bigint, never>;
    boolean(): SchemaType<boolean, never>;
    string(): SchemaType<string, never>;
    bytes(): SchemaType<ArrayBuffer, never>;
    literal<T extends string | number | bigint | boolean>(literal: T): SchemaType<T, never>;
    array<T_1>(values: SchemaType<T_1, any>): SchemaType<T_1[], never>;
    set<T_2>(values: SchemaType<T_2, any>): SchemaType<Set<T_2>, never>;
    map<K, V>(keys: SchemaType<K, any>, values: SchemaType<V, any>): SchemaType<Map<K, V>, never>;
    object<T_3 extends Record<string, SchemaType<any, any>>>(schema: T_3): ObjectSchemaType<T_3>;
    union<T_4 extends [SchemaType<any, any>, SchemaType<any, any>, ...SchemaType<any, any>[]]>(...schemaTypes: T_4): SchemaType<T_4[number]["type"], T_4[number]["fieldPaths"]>;
    any(): SchemaType<any, string>;
};

/**
 *
 * The definition of a Convex project schema.
 *
 * This should be produced by using {@link defineSchema}.
 * @public
 */
export declare class SchemaDefinition<Schema extends GenericSchema> {
    private tables;
    /* Excluded from this release type: __constructor */
    /* Excluded from this release type: export */
}

/**
 * A Convex type defined in a schema.
 *
 * These should be constructed using {@link s}.
 *
 * This class encapsulates:
 * - The TypeScript type of this Convex type.
 * - The TypeScript type for the set of index field paths that can be used to
 * build indexes on this type.
 * - The table names referenced in `s.id` usages in this type.
 * @public
 */
export declare class SchemaType<TypeScriptType, FieldPaths extends string> {
    readonly type: TypeScriptType;
    readonly fieldPaths: FieldPaths;
    private _isSchemaType;
    readonly referencedTableNames: Set<string>;
    constructor(referencedTableNames?: Set<string>);
}

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

/**
 * The indexes that Convex automatically adds to every table.
 *
 * This is an object mapping index names to index field paths.
 * @public
 */
declare type SystemIndexes = {
    by_creation_time: ["_creationTime"];
};

/**
 * The definition of a table within a schema.
 *
 * This should be produced by using {@link defineTable}.
 * @public
 */
export declare class TableDefinition<Document extends GenericDocument = GenericDocument, FieldPaths extends string = string, TableIndexes extends GenericTableIndexes = {}> {
    private indexes;
    private documentType;
    /* Excluded from this release type: __constructor */
    /**
     * Define an index on this table.
     *
     * To learn about indexes, see [Defining Indexes](https://docs.convex.dev/using/indexes).
     *
     * @param name - The name of the index.
     * @param fields - The fields to index, in order. Must specify at least one
     * field.
     * @returns A {@link TableDefinition} with this index included.
     */
    index<IndexName extends string, FirstFieldPath extends FieldPaths, RestFieldPaths extends FieldPaths[]>(name: IndexName, fields: [FirstFieldPath, ...RestFieldPaths]): TableDefinition<Document, FieldPaths, Expand<TableIndexes & Record<IndexName, [
    FirstFieldPath,
    ...RestFieldPaths,
    IndexTiebreakerField
    ]>>>;
    /* Excluded from this release type: export */
}

/**
 * A value supported by Convex.
 *
 * Values can be:
 * - stored inside of documents.
 * - used as arguments and return types to queries and mutation functions.
 *
 * You can see the full set of supported types at
 * [Types](https://docs.convex.dev/using/types).
 *
 * @public
 */
declare type Value = GenericId<string> | null | bigint | number | boolean | string | ArrayBuffer | Value[] | Set<Value> | Map<Value, Value> | {
    [key: string]: Value;
};

export { }