convex
Version:
Client for the Convex Cloud
135 lines • 5.12 kB
TypeScript
import { GenericAPI } from "../../api/index.js";
import { Value } from "../../values/index.js";
import { OptimisticUpdate } from "./optimistic_updates.js";
import { QueryJournal } from "./protocol.js";
import { QueryToken } from "./udf_path_utils.js";
/**
* Options for {@link InternalConvexClient}.
*
* @public
*/
export interface ClientOptions {
/**
* Whether to prompt the user if they have unsaved changes pending
* when navigating away or closing a web page.
*
* This is only possible when the `window` object exists, i.e. in a browser.
*
* The default value is `true`.
*/
unsavedChangesWarning?: boolean;
/**
* Specifies an alternate
* [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
* constructor to use for client communication with the Convex cloud.
* The default behavior is to use `WebSocket` from the global environment.
*/
webSocketConstructor?: typeof WebSocket;
}
/**
* State describing the client's connection with the Convex backend.
*
* @public
*/
export declare type ConnectionState = {
hasInflightRequests: boolean;
isWebSocketConnected: boolean;
};
/**
* An async function returning the JWT-encoded OpenID Connect Identity Token
* if available.
* See {@link ConvexReactClient.setAuth}.
*
* @public
*/
export declare type AuthTokenFetcher = () => Promise<string | null | undefined>;
/**
* Low-level client for directly integrating state management libraries
* with Convex.
*
* Most developers should use higher level clients, like
* the {@link ConvexHttpClient} or the React hook based {@link react.ConvexReactClient}.
*
* @public
*/
export declare class InternalConvexClient {
private readonly state;
private readonly requestManager;
private readonly actionManager;
private readonly webSocketManager;
private remoteQuerySet;
private readonly optimisticQueryResults;
private readonly onTransition;
private nextRequestId;
private readonly sessionId;
private fetchToken;
/**
* @param address - The url of your Convex deployment, often provided
* by an environment variable. E.g. `https://small-mouse-123.convex.cloud`.
* @param onTransition - A callback receiving an array of query tokens
* corresponding to query results that have changed.
* @param options - See {@link ClientOptions} for a full description.
*/
constructor(address: string, onTransition: (updatedQueries: QueryToken[]) => void, options?: ClientOptions);
/**
* Compute the current query results based on the remoteQuerySet and the
* current optimistic updates and call `onTransition` for all the changed
* queries.
*
* @param completedMutations - A set of mutation IDs whose optimistic updates
* are no longer needed.
*/
private notifyOnQueryResultChanges;
setAuth(fetchToken: AuthTokenFetcher): Promise<void>;
private tryToReauthenticate;
private authenticate;
/** @internal */
setAdminAuth(value: string): void;
clearAuth(): void;
/**
* Subscribe to a query function.
*
* Whenever this query's result changes, the `onTransition` callback
* passed into the constructor will be called.
*
* @param name - The name of the query.
* @param args - An array of the arguments to the query.
* @param journal - An (optional) journal produced from a previous
* execution of this query function. Note that if this query function with
* these arguments has already been requested the journal will have no effect.
* @returns An object containing a {@link QueryToken} corresponding to this
* query and an `unsubscribe` callback.
*/
subscribe(name: string, args: any[], journal?: QueryJournal): {
queryToken: QueryToken;
unsubscribe: () => void;
};
/**
* 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.
*/
localQueryResult(udfPath: string, args: any[]): Value | undefined;
/**
* Retrieve the current {@link QueryJournal} for this query function.
*
* If we have not yet received a result for this query, this will be `undefined`.
*
* @param name - The name of the query.
* @param args - An array of arguments to this query.
* @returns The query's {@link QueryJournal} or `undefined`.
*/
queryJournal(name: string, args: any[]): QueryJournal | undefined;
/**
* Get the current {@link ConnectionState} between the client and the Convex
* backend.
*
* @returns The {@link ConnectionState} with the Convex backend.
*/
connectionState(): ConnectionState;
mutate<Args extends any[]>(udfPath: string, args: Args, optimisticUpdate?: OptimisticUpdate<GenericAPI, Args> | null): Promise<any>;
action<Args extends any[]>(udfPath: string, args: Args): Promise<any>;
close(): Promise<void>;
}
//# sourceMappingURL=client.d.ts.map