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

Client for the Convex Cloud

/**
 * A {@link GenericDataModel} that considers documents to be `any` and does not
 * support indexes.
 *
 * This is the default before a schema is defined.
 * @public
 */
declare type AnyDataModel = {
    [tableName: string]: {
        document: any;
        fieldPaths: GenericFieldPaths;
        indexes: {};
        searchIndexes: {};
    };
};

/**
 * 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"]>;

/**
 * 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>;

/**
 * Options for {@link defineSchema}.
 *
 * @public
 */
export declare 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 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>>>;

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

/**
 * 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, any>> = Expand<SystemFields & T["type"]>;

/**
 * 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;

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

/**
 * A document stored in Convex.
 * @public
 */
declare 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
 */
declare type GenericFieldPaths = 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 configuration of a search index.
 * @public
 */
declare type GenericSearchIndexConfig = {
    searchField: string;
    filterFields: string;
};

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

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

/**
 * A type describing all of the search indexes in a table.
 *
 * This is an object mapping each index name to the config for the index.
 * @public
 */
declare type GenericTableSearchIndexes = Record<string, GenericSearchIndexConfig>;

/**
 * An identifier for a document in Convex.
 *
 * Convex documents are uniquely identified by their `Id`, 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 `Id` can refer
 * to the same document.
 *
 * `Id`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 Id<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): Id<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;
}

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

/**
 * The database indexes in a table for a given {@link GenericTableInfo}.
 *
 * This will be an object mapping index names to the fields in the index.
 * @public
 */
declare type Indexes<TableInfo extends GenericTableInfo> = TableInfo["indexes"];

/**
 * 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;
};

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>;
};

/**
 * 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>>;

/**
 * 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<Id<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"]>;
};

/**
 *
 * 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;
    /* 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.
 * - 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>);
}

/* Excluded from this release type: SearchIndexConfig */

/**
 * The search indexes in a table for a given {@link GenericTableInfo}.
 *
 * This will be an object mapping index names to the search index config.
 * @public
 */
declare type SearchIndexes<TableInfo extends GenericTableInfo> = TableInfo["searchIndexes"];

/**
 * 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, Indexes extends GenericTableIndexes = {}, SearchIndexes extends GenericTableSearchIndexes = {}> {
    private indexes;
    private searchIndexes;
    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<Indexes & Record<IndexName, [
    FirstFieldPath,
    ...RestFieldPaths,
    IndexTiebreakerField
    ]>>, SearchIndexes>;
    /* Excluded from this release type: searchIndex */
    /* 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 = Id<string> | null | bigint | number | boolean | string | ArrayBuffer | Value[] | Set<Value> | Map<Value, Value> | {
    [key: string]: Value;
};

export { }