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

Name	Type
address	string
options	ConvexClientOptions

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

Name	Type
Query	extends FunctionReference<"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<Query["_returnType"]>

an Unsubscribe function to stop calling the onUpdate function.

Defined in

browser/simple_client.ts:158

---

close

▸ close(): Promise<void>

Returns

Promise<void>

Defined in

browser/simple_client.ts:242

---

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-encoded OpenID Connect Identity Token
onChange?	(isAuthenticated: boolean) => void	a callback that will be called when the authentication status changes

Returns

void

Defined in

browser/simple_client.ts:258

---

mutation

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

Execute a mutation function.

Type parameters

Name	Type
Mutation	extends FunctionReference<"mutation">

Parameters

Name	Type	Description
mutation	Mutation	A FunctionReference for the public mutation to run.
args	FunctionArgs<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:331

---

action

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

Execute an action function.

Type parameters

Name	Type
Action	extends FunctionReference<"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

browser/simple_client.ts:347

---

query

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

Fetch a query result once.

Type parameters

Name	Type
Query	extends FunctionReference<"query">

Parameters

Name	Type	Description
query	Query	A FunctionReference for the public query to run.
args	Query["_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:363