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:98

Properties

disabled

disabled: boolean

Defined in

browser/simple_client.ts:81

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

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:160


close

close(): Promise<void>

Returns

Promise<void>

Defined in

browser/simple_client.ts:244


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-encoded 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:260


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:333


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:349


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:365