Module: server
Utilities for implementing server-side Convex query and mutation functions.
Usage
Code Generation
This module is typically used alongside generated server code.
To generate the server code, run npx convex codegen in your Convex project.
This will create a convex/_generated/server.ts file with the following
functions, typed for your schema:
If you aren't using TypeScript and code generation, you can use these untyped functions instead:
Example
Convex functions are defined by using either the query or
mutation wrappers.
Queries receive a db that implements the DatabaseReader interface.
import { query } from "./_generated/server";
export default query(async ({ db }, ...args: any[]): Promise<any> => {
// Your (read-only) code here!
});
If your function needs to write to the database, such as inserting, updating,
or deleting documents, use mutation instead which provides a db that
implements the DatabaseWriter interface.
import { mutation } from "./_generated/server";
export default mutation(async ({ db }, ...args: any[]): Promise<any> => {
// Your mutation code here!
});
Interfaces
- UserIdentity
- Auth
- DatabaseReader
- DatabaseWriter
- FilterBuilder
- IndexRangeBuilder
- Table
- IndexedQuery
- Query
- OrderedQuery
Classes
Type Aliases
GenericDocument
Ƭ GenericDocument: Record<string, Value>
A document stored in Convex.
GenericFieldPaths
Ƭ GenericFieldPaths: string
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").
GenericIndexFields
Ƭ GenericIndexFields: 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").
GenericTableIndexes
Ƭ GenericTableIndexes: Record<string, GenericIndexFields>
A type describing the indexes in a table.
It's a map from index name to fields in the index.
FieldTypeFromFieldPath
Ƭ FieldTypeFromFieldPath<Document, FieldPath>: FieldPath extends `${infer First}.${infer Second}` ? First extends keyof Document ? Document[First] extends GenericDocument ? FieldTypeFromFieldPath<Document[First], Second> : null : null : FieldPath extends keyof Document ? Document[FieldPath] : null
The type of a field in a document.
Note that this supports both simple fields like "name" and nested fields like "properties.name".
If the field is not present in the document it is considered to be null.
Type parameters
| Name | Type |
|---|---|
Document | extends GenericDocument |
FieldPath | extends string |
GenericTableInfo
Ƭ GenericTableInfo: Object
A type describing the document type and indexes in a table.
Type declaration
| Name | Type |
|---|---|
document | GenericDocument |
fieldPaths | GenericFieldPaths |
indexes | GenericTableIndexes |
DocumentByInfo
Ƭ DocumentByInfo<TableInfo>: TableInfo["document"]
The type of a document in a table for a given GenericTableInfo.
Type parameters
| Name | Type |
|---|---|
TableInfo | extends GenericTableInfo |
FieldPaths
Ƭ FieldPaths<TableInfo>: TableInfo["fieldPaths"]
The field paths in a table for a given GenericTableInfo.
These can either be field names (like "name") or references to fields on nested objects (like "properties.name").
Type parameters
| Name | Type |
|---|---|
TableInfo | extends GenericTableInfo |
IndexNames
Ƭ IndexNames<TableInfo>: keyof TableInfo["indexes"]
The names of indexes in a table for a given GenericTableInfo.
Type parameters
| Name | Type |
|---|---|
TableInfo | extends GenericTableInfo |
NamedIndex
Ƭ NamedIndex<TableInfo, IndexName>: TableInfo["indexes"][`IndexName`]
Extract the fields of an index from a GenericTableInfo by name.
Type parameters
| Name | Type |
|---|---|
TableInfo | extends GenericTableInfo |
IndexName | extends IndexNames<TableInfo> |
GenericDataModel
Ƭ GenericDataModel: Record<string, GenericTableInfo>
A type describing the tables in a Convex deployment.
This is designed to be code generated with npx convex codegen.
AnyDataModel
Ƭ AnyDataModel: Record<string, { document: any ; fieldPaths: GenericFieldPaths ; indexes: {} }>
A GenericDataModel that considers documents to be any and does not
support indexes.
This is the default before a schema is defined.
TableNamesInDataModel
Ƭ TableNamesInDataModel<DataModel>: keyof DataModel & string
A type of all of the table names defined in a GenericDataModel.
Type parameters
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
NamedTableInfo
Ƭ NamedTableInfo<DataModel, TableName>: DataModel[TableName]
Extract the TableInfo for a table in a GenericDataModel by table
name.
Type parameters
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
TableName | extends keyof DataModel |
DocumentByName
Ƭ DocumentByName<DataModel, TableName>: DataModel[TableName][``"document"``]
The type of a document in a GenericDataModel by table name.
Type parameters
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
TableName | extends TableNamesInDataModel<DataModel> |
ExpressionOrValue
Ƭ ExpressionOrValue<T>: Expression<T> | T
An Expression or a constant Value
Type parameters
| Name | Type |
|---|---|
T | extends Value |
MutationCtx
Ƭ MutationCtx<DataModel>: Object
A set of services for use within Convex mutation functions.
The mutation context is passed as the first argument to any Convex mutation function run on the server.
If you're using TypeScript, use the MutationCtx type in
convex/_generated/server.ts which is typed for your data model.
Type parameters
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Type declaration
| Name | Type |
|---|---|
db | DatabaseWriter<DataModel> |
auth | Auth |
QueryCtx
Ƭ QueryCtx<DataModel>: Object
A set of services for use within Convex query functions.
The query context is passed as the first argument to any Convex query function run on the server.
This differs from the MutationCtx because all of the services are read-only.
If you're using TypeScript, use the QueryCtx type in
convex/_generated/server.ts which is typed for your data model.
Type parameters
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Type declaration
| Name | Type |
|---|---|
db | DatabaseReader<DataModel> |
auth | Auth |
PublicMutation
Ƭ PublicMutation<DataModel, Args, Output>: Object
Type parameters
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Args | extends any[] |
Output | Output |
Call signature
▸ (ctx, ...args): Output
A mutation function that is part of this app's public API.
You can create public mutations by wrapping your function in mutationGeneric and exporting it.
Parameters
| Name | Type |
|---|---|
ctx | MutationCtx<DataModel> |
...args | Args |
Returns
Output
Type declaration
| Name | Type |
|---|---|
isMutation | true |
isRegistered? | true |
PublicQuery
Ƭ PublicQuery<DataModel, Args, Output>: Object
Type parameters
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Args | extends any[] |
Output | Output |
Call signature
▸ (ctx, ...args): Output
A query function that is part of this app's public API.
You can create public queries by wrapping your function in queryGeneric and exporting it.
Parameters
| Name | Type |
|---|---|
ctx | QueryCtx<DataModel> |
...args | Args |
Returns
Output
Type declaration
| Name | Type |
|---|---|
isQuery | true |
isRegistered? | true |
ClientMutation
Ƭ ClientMutation<Mutation>: Mutation extends PublicMutation<any, infer Args, infer Output> ? (...args: Args) => UndefinedToNull<Awaited<Output>> : never
Internal type helper used by Convex code generation.
Used to convert from PublicMutation to the type exposed to the client.
Type parameters
| Name | Type |
|---|---|
Mutation | extends PublicMutation<any, any, any> |
ClientQuery
Ƭ ClientQuery<Query>: Query extends PublicQuery<any, infer Args, infer Output> ? (...args: Args) => UndefinedToNull<Awaited<Output>> : never
Internal type helper used by Convex code generation.
Used to convert from PublicQuery to the type exposed to the client.
Type parameters
| Name | Type |
|---|---|
Query | extends PublicQuery<any, any, any> |
WithoutSystemFields
Ƭ WithoutSystemFields<Document>: Expand<Omit<Document, keyof SystemFields | "_id">>
A Convex document with the system fields like _id and _creationTime omitted.
Type parameters
| Name | Type |
|---|---|
Document | extends GenericDocument |
Functions
mutationGeneric
▸ mutationGeneric<DataModel, Args, Output>(func): PublicMutation<DataModel, Args, Output>
Define a mutation in this Convex app's public API.
This function will be allowed to modify your Convex database and will be accessible from the client.
If you're using TypeScript, use the mutation function in
convex/_generated/server.ts which is typed for your data model.
Type parameters
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Args | extends any[] |
Output | Output |
Parameters
| Name | Type | Description |
|---|---|---|
func | (ctx: MutationCtx<DataModel>, ...args: Args) => Output | The mutation function. It receives a MutationCtx as its first argument. |
Returns
PublicMutation<DataModel, Args, Output>
The wrapped mutation. Include this as an export to name it and make it accessible.
makeMutation
▸ makeMutation<DataModel>(): <Args, Output>(func: (ctx: MutationCtx<DataModel>, ...args: Args) => Output) => PublicMutation<DataModel, Args, Output>
Internal method used by Convex code generation.
Type parameters
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Returns
fn
▸ <Args, Output>(func): PublicMutation<DataModel, Args, Output>
Type parameters
| Name | Type |
|---|---|
Args | extends any[] |
Output | Output |
Parameters
| Name | Type |
|---|---|
func | (ctx: MutationCtx<DataModel>, ...args: Args) => Output |
Returns
PublicMutation<DataModel, Args, Output>
queryGeneric
▸ queryGeneric<DataModel, Args, Output>(func): PublicQuery<DataModel, Args, Output>
Define a query in this Convex app's public API.
This function will be allowed to read your Convex database and will be accessible from the client.
If you're using TypeScript, use the query function in
convex/_generated/server.ts which is typed for your data model.
Type parameters
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Args | extends any[] |
Output | Output |
Parameters
| Name | Type | Description |
|---|---|---|
func | (ctx: QueryCtx<DataModel>, ...args: Args) => Output | The query function. It receives a QueryCtx as its first argument. |
Returns
PublicQuery<DataModel, Args, Output>
The wrapped query. Include this as an export to name it and make it accessible.
makeQuery
▸ makeQuery<DataModel>(): <Args, Output>(func: (ctx: QueryCtx<DataModel>, ...args: Args) => Output) => PublicQuery<DataModel, Args, Output>
Internal method used by Convex code generation.
Type parameters
| Name | Type |
|---|---|
DataModel | extends GenericDataModel |
Returns
fn
▸ <Args, Output>(func): PublicQuery<DataModel, Args, Output>
Type parameters
| Name | Type |
|---|---|
Args | extends any[] |
Output | Output |
Parameters
| Name | Type |
|---|---|
func | (ctx: QueryCtx<DataModel>, ...args: Args) => Output |
Returns
PublicQuery<DataModel, Args, Output>