Skip to main content

Class: ConvexClient

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

NameType
addressstring
optionsConvexClientOptions

Defined in

browser/simple_client.ts:101

Accessors

closed

get closed(): boolean

Once closed no registered callbacks will fire again.

Returns

boolean

Defined in

browser/simple_client.ts:85


client

get client(): BaseConvexClient

Returns

BaseConvexClient

Defined in

browser/simple_client.ts:88


disabled

get disabled(): boolean

Returns

boolean

Defined in

browser/simple_client.ts:92

Methods

onUpdate

onUpdate<Query>(query, args, callback, onError?): Unsubscribe<Query["_returnType"]>

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

NameType
Queryextends FunctionReference<"query">

Parameters

NameTypeDescription
queryQueryA FunctionReference for the public query to run.
argsFunctionArgs<Query>The arguments to run the query with.
callback(result: FunctionReturnType<Query>) => unknownFunction to call when the query result updates.
onError?(e: Error) => unknownFunction to call when the query result updates with an error. If not provided, errors will be thrown instead of calling the callback.

Returns

Unsubscribe<Query["_returnType"]>

an Unsubscribe function to stop calling the onUpdate function.

Defined in

browser/simple_client.ts:163


close

close(): Promise<void>

Returns

Promise<void>

Defined in

browser/simple_client.ts:247


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

NameTypeDescription
fetchTokenAuthTokenFetcheran async function returning the JWT (typically an OpenID Connect Identity Token)
onChange?(isAuthenticated: boolean) => voida callback that will be called when the authentication status changes

Returns

void

Defined in

browser/simple_client.ts:263


mutation

mutation<Mutation>(mutation, args): Promise<Awaited<FunctionReturnType<Mutation>>>

Execute a mutation function.

Type parameters

NameType
Mutationextends FunctionReference<"mutation">

Parameters

NameTypeDescription
mutationMutationA FunctionReference for the public mutation to run.
argsFunctionArgs<Mutation>An arguments object for the mutation.

Returns

Promise<Awaited<FunctionReturnType<Mutation>>>

A promise of the mutation's result.

Defined in

browser/simple_client.ts:337


action

action<Action>(action, args): Promise<Awaited<FunctionReturnType<Action>>>

Execute an action function.

Type parameters

NameType
Actionextends FunctionReference<"action">

Parameters

NameTypeDescription
actionActionA FunctionReference for the public action to run.
argsFunctionArgs<Action>An arguments object for the action.

Returns

Promise<Awaited<FunctionReturnType<Action>>>

A promise of the action's result.

Defined in

browser/simple_client.ts:353


query

query<Query>(query, args): Promise<Awaited<Query["_returnType"]>>

Fetch a query result once.

Type parameters

NameType
Queryextends FunctionReference<"query">

Parameters

NameTypeDescription
queryQueryA FunctionReference for the public query to run.
argsQuery["_args"]An arguments object for the query.

Returns

Promise<Awaited<Query["_returnType"]>>

A promise of the query's result.

Defined in

browser/simple_client.ts:369