convex
Version:
Client for the Convex Cloud
340 lines • 12.4 kB
TypeScript
/**
* 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 "../values/index.js";
import { AnyDataModel, DocumentByInfo, GenericDataModel, GenericDocument, GenericTableIndexes, GenericTableInfo, GenericTableSearchIndexes, Indexes, SearchIndexes } from "../server/data_model.js";
import { IdField, IndexTiebreakerField, 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.
* - Whether this field should be optional if it's included in an object.
* - 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, IsOptional extends boolean = false, FieldPaths extends string = never> {
readonly type: TypeScriptType;
readonly isOptional: IsOptional;
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>, false, never>;
null(): SchemaType<null>;
number(): SchemaType<number>;
bigint(): SchemaType<bigint>;
boolean(): SchemaType<boolean>;
string(): SchemaType<string>;
bytes(): SchemaType<ArrayBuffer>;
literal<T extends string | number | bigint | boolean>(literal: T): SchemaType<T, false, never>;
array<T_1>(values: SchemaType<T_1, false, any>): SchemaType<T_1[], false, never>;
set<T_2>(values: SchemaType<T_2, false, any>): SchemaType<Set<T_2>, false, never>;
map<K, V>(keys: SchemaType<K, false, any>, values: SchemaType<V, false, any>): SchemaType<Map<K, V>, false, never>;
object<T_3 extends Record<string, SchemaType<any, any, any>>>(schema: T_3): ObjectSchemaType<T_3>;
union<T_4 extends [SchemaType<any, false, any>, SchemaType<any, false, any>, ...SchemaType<any, false, any>[]]>(...schemaTypes: T_4): SchemaType<T_4[number]["type"], false, T_4[number]["fieldPaths"]>;
any(): SchemaType<any, false, string>;
optional<T_5 extends SchemaType<any, false, any>>(inner: T_5): SchemaType<T_5["type"], true, T_5["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, any>>> = SchemaType<Expand<{
[Property in OptionalKeys<SchemaValueType>]?: SchemaValueType[Property]["type"];
} & {
[Property in RequiredKeys<SchemaValueType>]: SchemaValueType[Property]["type"];
}>, false, {
[Property in keyof SchemaValueType]: JoinFieldPaths<Property & string, SchemaValueType[Property]["fieldPaths"]> | Property;
}[keyof SchemaValueType] & string>;
declare type OptionalKeys<SchemaValueType extends Record<string, SchemaType<any, any, any>>> = {
[Property in keyof SchemaValueType]: SchemaValueType[Property]["isOptional"] extends true ? Property : never;
}[keyof SchemaValueType];
declare type RequiredKeys<SchemaValueType extends Record<string, SchemaType<any, any, any>>> = Exclude<keyof SchemaValueType, OptionalKeys<SchemaValueType>>;
/**
* 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, any>> = T["fieldPaths"] | keyof SystemFields;
/**
* 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, any>> = Expand<SystemFields & T["type"]>;
/**
* The configuration for a search index.
*
* @internal
*/
export interface SearchIndexConfig<SearchField extends string, FilterFields extends string> {
/**
* The field to index for full text search.
*
* This must be a field of type `string`.
*/
searchField: SearchField;
/**
* Additional fields to index for fast filtering when running search queries.
*/
filterFields?: FilterFields[];
}
/**
* 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, Indexes extends GenericTableIndexes = {}, SearchIndexes extends GenericTableSearchIndexes = {}> {
private indexes;
private searchIndexes;
private documentType;
/**
* @internal
*/
constructor(documentType: SchemaType<any, 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<Indexes & Record<IndexName, [
FirstFieldPath,
...RestFieldPaths,
IndexTiebreakerField
]>>, SearchIndexes>;
/**
* Define a search index on this table.
*
* @param name - The name of the index.
* @param indexConfig - The search index configuration object.
* @returns A {@link TableDefinition} with this search index included.
* @internal
*/
searchIndex<IndexName extends string, SearchField extends FieldPaths, FilterFields extends FieldPaths = never>(name: IndexName, indexConfig: Expand<SearchIndexConfig<SearchField, FilterFields>>): TableDefinition<Document, FieldPaths, Indexes, Expand<SearchIndexes & Record<IndexName, {
searchField: SearchField;
filterFields: FilterFields;
}>>>;
/**
* Export the contents of this definition.
*
* This is called internally by the Convex framework.
* @internal
*/
export(): {
indexes: {
indexDescriptor: string;
fields: string[];
}[];
searchIndexes: {
indexDescriptor: string;
searchField: string;
filterFields: 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.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>, false, 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, 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, IsStrict extends boolean> {
tables: Schema;
isStrict: IsStrict;
/**
* @internal
*/
constructor(tables: Schema, options?: DefineSchemaOptions<IsStrict>);
/**
* Export the contents of this definition.
*
* This is called internally by the Convex framework.
* @internal
*/
export(): string;
}
/**
* Options for {@link defineSchema}.
*
* @public
*/
export interface DefineSchemaOptions<IsStrict extends boolean> {
/**
* Whether to strictly enforce this schema.
*
* If this schema is not strictly enforced, its type will permit:
* 1. Using additional tables not explicitly listed in the schema.
* 2. Using additional properties not explicitly listed in the tables.
*
* Loose schemas are useful for rapid prototyping.
*
* By default the schema is considered strict.
*/
strict?: IsStrict;
}
/**
* 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.
* @param options - Optional configuration. See {@link DefineSchemaOptions} for
* a full description.
* @returns The schema.
*
* @public
*/
export declare function defineSchema<Schema extends GenericSchema, IsStrict extends boolean = true>(schema: Schema, options?: DefineSchemaOptions<IsStrict>): SchemaDefinition<Schema, IsStrict>;
/**
* 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, boolean>> = MaybeMakeLooseDataModel<{
[TableName in keyof SchemaDef["tables"] & string]: SchemaDef["tables"][TableName] extends TableDefinition<infer Document, infer FieldPaths, infer Indexes, infer SearchIndexes> ? MaybeMakeLooseTableInfo<{
document: Expand<IdField<TableName> & Document>;
fieldPaths: keyof IdField<TableName> | FieldPaths;
indexes: Expand<Indexes & SystemIndexes>;
searchIndexes: SearchIndexes;
}, SchemaDef["isStrict"]> : never;
}, SchemaDef["isStrict"]>;
declare type MaybeMakeLooseDataModel<DataModel extends GenericDataModel, IsStrict extends boolean> = IsStrict extends true ? DataModel : Expand<DataModel & AnyDataModel>;
declare type MaybeMakeLooseTableInfo<TableInfo extends GenericTableInfo, IsStrict extends boolean> = IsStrict extends true ? TableInfo : {
document: Expand<DocumentByInfo<TableInfo> & {
[propertyName: string]: any;
}>;
fieldPaths: string;
indexes: Indexes<TableInfo>;
searchIndexes: SearchIndexes<TableInfo>;
};
export {};
//# sourceMappingURL=index.d.ts.map