convex/dist/esm/schema/index.d.ts

Client for the Convex Cloud

/**
 * Utilities for defining the schema of your Convex project.
 *
 * ## Usage
 *
 * Schemas should be placed in a `schema.ts` file in your `convex/` directory.
 *
 * Schema definitions should be built using {@link defineSchema},
 * {@link defineTable}, and {@link s}. Make sure to export the schema as the
 * default export.
 *
 * ```ts
 * import { defineSchema, defineTable, s } from "convex/schema";
 *
 *  export default defineSchema({
 *    messages: defineTable({
 *      body: s.string(),
 *      user: s.id("users"),
 *    }),
 *    users: defineTable({
 *      name: s.string(),
 *    }),
 *  });
 * ```
 *
 * To learn more about schemas, see [Defining a Schema](https://docs.convex.dev/using/schemas).
 * @module
 */
import { GenericId } from "@convex-dev/common";
import { GenericDocument, GenericTableIndexes } from "../server/data_model.js";
import { IdField, SystemFields, SystemIndexes } from "../server/system_fields.js";
import { Expand } from "../type_utils.js";
/**
 * 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 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"]>;
};
/**
 * 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>;
/**
 * 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}`;
/**
 * 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;
/**
 * 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;
/**
 * 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;
    /**
     * @internal
     */
    constructor(documentType: SchemaType<any, any>);
    /**
     * 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]>>>;
    /**
     * Export the contents of this definition.
     *
     * This is called internally by the Convex framework.
     * @internal
     */
    export(): {
        indexes: {
            indexDescriptor: string;
            fields: string[];
        }[];
        referencedTableNames: Set<string>;
    };
}
/**
 * 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.object({
 *   field: s.string()
 * }));
 * ```
 *
 * @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.object({
 *   field: s.string()
 * }));
 * ```
 *
 * @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>>>;
/**
 * 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>;
/**
 *
 * 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;
    /**
     * @internal
     */
    constructor(tables: Schema);
    /**
     * Export the contents of this definition.
     *
     * This is called internally by the Convex framework.
     * @internal
     */
    export(): string;
}
/**
 * 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>;
/**
 * 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;
/**
 * 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;
export {};
//# sourceMappingURL=index.d.ts.map