Class: BaseConvexClient
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.BaseConvexClient
Low-level client for directly integrating state management libraries with Convex.
Most developers should use higher level clients, like the ConvexHttpClient or the React hook based ConvexReactClient.
Constructors
constructor
• new BaseConvexClient(address, onTransition, options?)
Parameters
| Name | Type | Description |
|---|---|---|
address | string | The url of your Convex deployment, often provided by an environment variable. E.g. https://small-mouse-123.convex.cloud. |
onTransition | (updatedQueries: QueryToken[]) => void | A callback receiving an array of query tokens corresponding to query results that have changed -- additional handlers can be added via addOnTransitionHandler. |
options? | BaseConvexClientOptions | See BaseConvexClientOptions for a full description. |
Defined in
Accessors
url
• get url(): string
Return the address for this client, useful for creating a new client.
Not guaranteed to match the address with which this client was constructed: it may be canonicalized.
Returns
string
Defined in
Methods
getMaxObservedTimestamp
▸ getMaxObservedTimestamp(): undefined | Long
Returns
undefined | Long
Defined in
addOnTransitionHandler
▸ addOnTransitionHandler(fn): () => boolean
Add a handler that will be called on a transition.
Any external side effects (e.g. setting React state) should be handled here.
Parameters
| Name | Type |
|---|---|
fn | (transition: Transition) => void |
Returns
fn
▸ (): boolean
Returns
boolean
Defined in
getCurrentAuthClaims
▸ getCurrentAuthClaims(): 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, onRefreshChange?): 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 |
onRefreshChange? | (isRefreshing: boolean) => void | a callback called with true when the socket is paused to fetch a replacement token after a server rejection, and false when refresh completes |
Returns
void
Defined in
hasAuth
▸ hasAuth(): boolean
Returns
boolean
Defined in
clearAuth
▸ clearAuth(): void
Returns
void
Defined in
subscribe
▸ subscribe(name, args?, options?): Object
Subscribe to a query function.
Whenever this query's result changes, the onTransition callback
passed into the constructor will be called.
Parameters
| Name | Type | Description |
|---|---|---|
name | string | The name of the query. |
args? | Record<string, Value> | An arguments object for the query. If this is omitted, the arguments will be {}. |
options? | SubscribeOptions | A SubscribeOptions options object for this query. |
Returns
Object
An object containing a QueryToken corresponding to this
query and an unsubscribe callback.
| Name | Type |
|---|---|
queryToken | QueryToken |
unsubscribe | () => void |
Defined in
localQueryResult
▸ localQueryResult(udfPath, args?): undefined | Value
A query result based only on the current, local state.
The only way this will return a value is if we're already subscribed to the query or its value has been set optimistically.
Parameters
| Name | Type |
|---|---|
udfPath | string |
args? | Record<string, Value> |
Returns
undefined | Value
Defined in
queryJournal
▸ queryJournal(name, args?): undefined | QueryJournal
Retrieve the current QueryJournal for this query function.
If we have not yet received a result for this query, this will be undefined.
Parameters
| Name | Type | Description |
|---|---|---|
name | string | The name of the query. |
args? | Record<string, Value> | The arguments object for this query. |
Returns
undefined | QueryJournal
The query's QueryJournal or undefined.
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.
Defined in
mutation
▸ mutation(name, args?, options?): Promise<any>
Execute a mutation function.
Parameters
| Name | Type | Description |
|---|---|---|
name | string | The name of the mutation. |
args? | Record<string, Value> | An arguments object for the mutation. If this is omitted, the arguments will be {}. |
options? | MutationOptions | A MutationOptions options object for this mutation. |
Returns
Promise<any>
- A promise of the mutation's result.
Defined in
action
▸ action(name, args?): Promise<any>
Execute an action function.
Parameters
| Name | Type | Description |
|---|---|---|
name | string | The name of the action. |
args? | Record<string, Value> | An arguments object for the action. If this is omitted, the arguments will be {}. |
Returns
Promise<any>
A promise of the action's result.
Defined in
close
▸ close(): Promise<void>
Close any network handles associated with this client and stop all subscriptions.
Call this method when you're done with an BaseConvexClient to dispose of its sockets and resources.
Returns
Promise<void>
A Promise fulfilled when the connection has been completely closed.