Class: ConvexClient
For AI agents: see llms.txt for the complete documentation index. Markdown versions are available by adding .md to a page URL or requesting Accept: text/markdown.
browser.ConvexClient
Subscribes to Convex query functions and executes mutations and actions over a WebSocket.
Optimistic updates for mutations are not provided for this client. Third party clients may choose to wrap BaseConvexClient for additional control.
const client = new ConvexClient("https://happy-otter-123.convex.cloud");
const unsubscribe = client.onUpdate(api.messages.list, {}, (messages) => {
console.log(messages[0].body);
});
Constructors
constructor
• new ConvexClient(address, options?)
Construct a client and immediately initiate a WebSocket connection to the passed address.
Parameters
| Name | Type |
|---|---|
address | string |
options | ConvexClientOptions |
Defined in
Accessors
closed
• get closed(): boolean
Once closed no registered callbacks will fire again.
Returns
boolean
Defined in
client
• get client(): BaseConvexClient
Returns
Defined in
disabled
• get disabled(): boolean
Returns
boolean
Defined in
Methods
onUpdate
▸ onUpdate<Query>(query, args, callback, onError?): Unsubscribe<FunctionReturnType<Query>>
Call a callback whenever a new result for a query is received. The callback will run soon after being registered if a result for the query is already in memory.
The return value is an Unsubscribe object which is both a function an an object with properties. Both of the patterns below work with this object:
// call the return value as a function
const unsubscribe = client.onUpdate(api.messages.list, {}, (messages) => {
console.log(messages);
});
unsubscribe();
// unpack the return value into its properties
const {
getCurrentValue,
unsubscribe,
} = client.onUpdate(api.messages.list, {}, (messages) => {
console.log(messages);
});
Type parameters
| Name | Type |
|---|---|
Query | extends FunctionReference<"query"> | FunctionReference_future<"query"> |
Parameters
| Name | Type | Description |
|---|---|---|
query | Query | A FunctionReference for the public query to run. |
args | FunctionArgs<Query> | The arguments to run the query with. |
callback | (result: FunctionReturnType<Query>) => unknown | Function to call when the query result updates. |
onError? | (e: Error) => unknown | Function to call when the query result updates with an error. If not provided, errors will be thrown instead of calling the callback. |
Returns
Unsubscribe<FunctionReturnType<Query>>
an Unsubscribe function to stop calling the onUpdate function.
Defined in
onPaginatedUpdate_experimental
▸ onPaginatedUpdate_experimental<Query>(query, args, options, callback, onError?): Unsubscribe<PaginatedQueryResult<FunctionReturnType<Query>[]>>
Call a callback whenever a new result for a paginated query is received.
This is an experimental preview: the final API may change. In particular, caching behavior, page splitting, and required paginated query options may change.
Type parameters
| Name | Type |
|---|---|
Query | extends FunctionReference<"query"> | FunctionReference_future<"query"> |
Parameters
| Name | Type | Description |
|---|---|---|
query | Query | A FunctionReference for the public query to run. |
args | FunctionArgs<Query> | The arguments to run the query with. |
options | Object | Options for the paginated query including initialNumItems and id. |
options.initialNumItems | number | - |
callback | (result: PaginationResult<FunctionReturnType<Query>>) => unknown | Function to call when the query result updates. |
onError? | (e: Error) => unknown | Function to call when the query result updates with an error. |
Returns
Unsubscribe<PaginatedQueryResult<FunctionReturnType<Query>[]>>
an Unsubscribe function to stop calling the callback.
Defined in
close
▸ close(): Promise<void>
Returns
Promise<void>
Defined in
getAuth
▸ getAuth(): undefined | { token: string ; decoded: Record<string, any> }
Get the current JWT auth token and decoded claims.
Returns
undefined | { token: string ; decoded: Record<string, any> }
Defined in
setAuth
▸ setAuth(fetchToken, onChange?): void
Set the authentication token to be used for subsequent queries and mutations.
fetchToken will be called automatically again if a token expires.
fetchToken should return null if the token cannot be retrieved, for example
when the user's rights were permanently revoked.
Parameters
| Name | Type | Description |
|---|---|---|
fetchToken | AuthTokenFetcher | an async function returning the JWT (typically an OpenID Connect Identity Token) |
onChange? | (isAuthenticated: boolean) => void | a callback that will be called when the authentication status changes |
Returns
void
Defined in
mutation
▸ mutation<Mutation>(mutation, args, options?): Promise<Awaited<FunctionReturnType<Mutation>>>
Execute a mutation function.
Type parameters
| Name | Type |
|---|---|
Mutation | extends FunctionReference<"mutation"> | FunctionReference_future<"mutation"> |
Parameters
| Name | Type | Description |
|---|---|---|
mutation | Mutation | A FunctionReference for the public mutation to run. |
args | FunctionArgs<Mutation> | An arguments object for the mutation. |
options? | MutationOptions | A MutationOptions options object for the mutation. |
Returns
Promise<Awaited<FunctionReturnType<Mutation>>>
A promise of the mutation's result.
Defined in
action
▸ action<Action>(action, args): Promise<Awaited<FunctionReturnType<Action>>>
Execute an action function.
Type parameters
| Name | Type |
|---|---|
Action | extends FunctionReference<"action"> | FunctionReference_future<"action"> |
Parameters
| Name | Type | Description |
|---|---|---|
action | Action | A FunctionReference for the public action to run. |
args | FunctionArgs<Action> | An arguments object for the action. |
Returns
Promise<Awaited<FunctionReturnType<Action>>>
A promise of the action's result.
Defined in
query
▸ query<Query>(query, args): Promise<Awaited<FunctionReturnType<Query>>>
Fetch a query result once.
Type parameters
| Name | Type |
|---|---|
Query | extends FunctionReference<"query"> | FunctionReference_future<"query"> |
Parameters
| Name | Type | Description |
|---|---|---|
query | Query | A FunctionReference for the public query to run. |
args | FunctionArgs<Query> | An arguments object for the query. |
Returns
Promise<Awaited<FunctionReturnType<Query>>>
A promise of the query's result.
Defined in
connectionState
▸ connectionState(): ConnectionState
Get the current ConnectionState between the client and the Convex backend.
Returns
The ConnectionState with the Convex backend.
Defined in
subscribeToConnectionState
▸ subscribeToConnectionState(cb): () => void
Subscribe to the ConnectionState between the client and the Convex backend, calling a callback each time it changes.
Subscribed callbacks will be called when any part of ConnectionState changes. ConnectionState may grow in future versions (e.g. to provide a array of inflight requests) in which case callbacks would be called more frequently.
Parameters
| Name | Type |
|---|---|
cb | (connectionState: ConnectionState) => void |
Returns
fn
An unsubscribe function to stop listening.
▸ (): void
Subscribe to the ConnectionState between the client and the Convex backend, calling a callback each time it changes.
Subscribed callbacks will be called when any part of ConnectionState changes. ConnectionState may grow in future versions (e.g. to provide a array of inflight requests) in which case callbacks would be called more frequently.
Returns
void
An unsubscribe function to stop listening.