convex/dist/esm/react/react.d.ts

Client for the Convex Cloud

import { default as React_2 } from 'react';

/**
 * The configuration needed to construct a Convex client like the
 * {@link ConvexHttpClient} and {@link react.ConvexReactClient}.
 *
 * This configuration is automatically generated by `npx convex dev` and
 * `npx convex deploy`. You can find the generated version at
 * `convex/_generated/clientConfig.js`.
 *
 * @public
 */
declare interface ClientConfiguration {
    /**
     * The URL of the Convex deployment.
     */
    address: string;
}

/**
 * Provides an active Convex {@link ConvexReactClient} to descendants of this component.
 *
 * Wrap your app in this component to use Convex hooks `useQuery`,
 * `useMutation`, and `useConvex`.
 *
 * @param props - an object with a `client` property that refers to a {@link ConvexReactClient}.
 *
 * @public
 */
export declare const ConvexProvider: React_2.FC<{
    client: ConvexReactClient<any>;
    children?: React_2.ReactNode;
}>;

/**
 * A Convex client for use within React.
 *
 * This loads reactive queries and executes mutations over a WebSocket.
 *
 * @typeParam API - The API of your application, composed of all Convex queries
 * and mutations. `npx convex codegen` [generates this type](/generated-api/react#convexapi)
 * in `convex/_generated/react.d.ts`.
 * @public
 */
export declare class ConvexReactClient<API extends GenericAPI> {
    private clientConfig;
    private cachedSync?;
    private listeners;
    private options;
    private closed;
    private adminAuth?;
    /**
     * @param clientConfig - The generated client configuration for your project.
     * You can find this in `convex/_generated/clientConfig.js`.
     * @param options - See {@link ReactClientOptions} for a full description.
     */
    constructor(clientConfig: ClientConfiguration, options?: ReactClientOptions);
    /**
     * Lazily instantiate the `InternalConvexClient` so we don't create the WebSocket
     * when server-side rendering.
     */
    private get sync();
    /**
     * Set the authentication token to be used for subsequent queries and mutations.
     * Should be called whenever the token changes (i.e. due to expiration and refresh)
     * @param token - JWT-encoded OpenID Connect Identity Token
     */
    setAuth(token: string): void;
    /**
     * Clear the current authentication token if set.
     */
    clearAuth(): void;
    /* Excluded from this release type: setAdminAuth */
    /**
     * Construct a new {@link Watch} on a Convex query function.
     *
     * **Most application code should not call this method directly. Instead use
     * the `useQuery` hook generated by `npx convex codegen`.**
     *
     * @param name - The name of the query function.
     * @param args - The arguments to the query.
     * @returns The {@link Watch} object.
     */
    watchQuery<Name extends QueryNames<API>>(name: Name, ...args: Parameters<NamedQuery<API, Name>>): Watch<NamedQuery<API, Name>>;
    /**
     * Construct a new {@link ReactMutation}.
     *
     * @param name - The name of the Mutation.
     * @returns The {@link ReactMutation} object with that name.
     */
    mutation<Name extends MutationNames<API>>(name: Name): ReactMutation<API, Name>;
    /**
     * Close any network handles associated with this client and stop all subscriptions.
     *
     * Call this method when you're done with a {@link ConvexReactClient} to
     * dispose of its sockets and resources.
     *
     * @returns A `Promise` fulfilled when the connection has been completely closed.
     */
    close(): Promise<void>;
    private transition;
}

/**
 * Description of the Convex functions available to an application.
 *
 * This is a generic type that expresses the shape of API types created by
 * `npx convex codegen`. It's used to make the Convex clients type-safe.
 *
 * @public
 */
declare type GenericAPI = {
    queries: Record<string, (...args: any[]) => any>;
    mutations: Record<string, (...args: any[]) => any>;
};

/**
 * The names of mutation functions in a Convex API.
 *
 * @public
 */
declare type MutationNames<API extends GenericAPI> = keyof API["mutations"] & string;

/**
 * The type of a mutation function in a Convex API.
 *
 * @public
 */
declare type NamedMutation<API extends GenericAPI, Name extends MutationNames<API>> = API["mutations"][Name];

/**
 * The type of a query function in a Convex API.
 *
 * @public
 */
declare type NamedQuery<API extends GenericAPI, Name extends QueryNames<API>> = API["queries"][Name];

/**
 * A view of the query results currently in the Convex client for use within
 * optimistic updates.
 *
 * @public
 */
declare interface OptimisticLocalStore<API extends GenericAPI = GenericAPI> {
    /**
     * Retrieve the result of a query from the client.
     *
     * Important: Query results should be treated as immutable!
     * Always make new copies of structures within query results to avoid
     * corrupting data within the client.
     *
     * @param name - The name of the query.
     * @param args - An array of the arguments for this query.
     * @returns The query result or `undefined` if the query is not currently
     * in the client.
     */
    getQuery<Name extends QueryNames<API>>(name: Name, args: Parameters<NamedQuery<API, Name>>): undefined | ReturnType<NamedQuery<API, Name>>;
    /**
     * Optimistically update the result of a query.
     *
     * This can either be a new value (perhaps derived from the old value from
     * {@link OptimisticLocalStore.getQuery}) or `undefined` to remove the query.
     * Removing a query is useful to create loading states while Convex recomputes
     * the query results.
     *
     * @param name - The name of the query.
     * @param args - An array of the arguments for this query.
     * @param value - The new value to set the query to or `undefined` to remove
     * it from the client.
     */
    setQuery<Name extends QueryNames<API>>(name: Name, args: Parameters<NamedQuery<API, Name>>, value: undefined | ReturnType<NamedQuery<API, Name>>): void;
}

/**
 * A temporary, local update to query results within this client.
 *
 * This update will always be executed when a mutation is synced to the Convex
 * server and rolled back when the mutation completes.
 *
 * Note that optimistic updates can be called multiple times! If the client
 * loads new data while the mutation is in progress, the update will be replayed
 * again.
 *
 * @param localQueryStore - An interface to read and edit local query results.
 * @param args - The arguments to the mutation.
 *
 * @public
 */
declare type OptimisticUpdate<API extends GenericAPI, Arguments extends any[]> = (localQueryStore: OptimisticLocalStore<API>, ...args: Arguments) => void;

/**
 * Helper types for interacting with the overall API type
 */
/**
 * The names of query functions in a Convex API.
 *
 * @public
 */
declare type QueryNames<API extends GenericAPI> = keyof API["queries"] & string;

/**
 * Options for {@link ConvexReactClient}.
 *
 * @public
 */
export declare type ReactClientOptions = {
    /**
     * Whether to prompt the user that have unsaved changes pending
     * when navigating away or closing a web page with pending Convex mutations.
     * 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;
};

/**
 * An interface to execute a Convex mutation function on the server.
 *
 * @public
 */
export declare interface ReactMutation<API extends GenericAPI, Name extends MutationNames<API>> {
    /**
     * Execute the mutation on the server, returning a `Promise` of its return value.
     *
     * @param args - Arguments for the mutation to pass up to the server.
     * @returns The return value of the server-side function call.
     */
    (...args: Parameters<NamedMutation<API, Name>>): Promise<ReturnType<NamedMutation<API, Name>>>;
    /**
     * Define an optimistic update to apply as part of this mutation.
     *
     * This is a temporary update to the local query results to facilitate a
     * fast, interactive UI. It enables query results to update before a mutation
     * executed on the server.
     *
     * When the mutation is invoked, the optimistic update will be applied.
     *
     * Optimistic updates can also be used to temporarily remove queries from the
     * client and create loading experiences until a mutation completes and the
     * new query results are synced.
     *
     * The update will be automatically rolled back when the mutation is fully
     * completed and queries have been updated.
     *
     * @param optimisticUpdate - The optimistic update to apply.
     * @returns A new `ReactMutation` with the update configured.
     *
     * @public
     */
    withOptimisticUpdate(optimisticUpdate: OptimisticUpdate<API, Parameters<NamedMutation<API, Name>>>): ReactMutation<API, Name>;
}

/**
 * Internal type helper used by Convex code generation.
 *
 * Used to give {@link useConvexGeneric} a type specific to your API.
 * @public
 */
export declare type UseConvexForAPI<API extends GenericAPI> = () => ConvexReactClient<API>;

/**
 * Get the {@link ConvexReactClient} within a React component.
 *
 * This relies on the {@link ConvexProvider} being above in the React component tree.
 *
 * If you're using code generation, use the `useConvex` function in
 * `convex/_generated/react.js` which is typed for your API.
 *
 * @returns The active {@link ConvexReactClient} object, or `undefined`.
 *
 * @public
 */
export declare function useConvexGeneric<API extends GenericAPI>(): ConvexReactClient<API>;

/**
 * Internal type helper used by Convex code generation.
 *
 * Used to give {@link useMutationGeneric} a type specific to your API.
 * @public
 */
export declare type UseMutationForAPI<API extends GenericAPI> = <Name extends MutationNames<API>>(name: Name) => ReactMutation<API, Name>;

/**
 * Construct a new {@link ReactMutation}.
 *
 * Mutation objects can be called like functions to request execution of the
 * corresponding Convex function, or further configured with
 * [optimistic updates](https://docs.convex.dev/using/optimistic-updates).
 *
 * The value returned by this hook is stable across renders, so it can be used
 * by React dependency arrays and memoization logic relying on object identity
 * without causing rerenders.
 *
 * If you're using code generation, use the `useMutation` function in
 * `convex/_generated/react.js` which is typed for your API.
 *
 * Throws an error if not used under {@link ConvexProvider}.
 *
 * @param name - The name of the mutation.
 * @returns The {@link ReactMutation} object with that name.
 *
 * @public
 */
export declare function useMutationGeneric<API extends GenericAPI, Name extends MutationNames<API>>(name: Name): ReactMutation<API, Name>;

/**
 * Internal type helper used by Convex code generation.
 *
 * Used to give {@link useQueryGeneric} a type specific to your API.
 * @public
 */
export declare type UseQueryForAPI<API extends GenericAPI> = <Name extends QueryNames<API>>(name: Name, ...args: Parameters<NamedQuery<API, Name>>) => ReturnType<NamedQuery<API, Name>> | undefined;

/**
 * Load a reactive query within a React component.
 *
 * This React hook contains internal state that will cause a rerender
 * whenever the query result changes.
 *
 * Throws an error if not used under {@link ConvexProvider}.
 *
 * If you're using code generation, use the `useQuery` function in
 * `convex/_generated/react.js` which is typed for your API.
 *
 * @param name - The name of the query function.
 * @param args - The arguments to the query function.
 * @returns `undefined` if loading and the query's return value otherwise.
 *
 * @public
 */
export declare function useQueryGeneric<API extends GenericAPI, Name extends QueryNames<API>>(name: Name, ...args: Parameters<NamedQuery<API, Name>>): ReturnType<NamedQuery<API, Name>> | undefined;

/**
 * A watch on the output of a Convex query function.
 *
 * @public
 */
export declare interface Watch<F extends (...args: any[]) => any> {
    /**
     * Initiate a watch on the output of a query.
     *
     * This will subscribe to this query and call
     * the callback whenever the query result changes.
     *
     * **Important: If the query is already known on the client this watch will
     * never be invoked.** To get the current, local result call
     * {@link react.Watch.localQueryResult}.
     *
     * @param callback - Function that is called whenever the query result changes.
     * @returns - A function that disposes of the subscription.
     */
    onUpdate(callback: () => void): () => void;
    /**
     * Get the current result of a query.
     *
     * This will only return a result if we're already subscribed to the query
     * and have received a result from the server or the query value has been set
     * optimistically.
     *
     * @returns The result of the query or `undefined` if it isn't known.
     * @throws An error if the query encountered an error on the server.
     */
    localQueryResult(): ReturnType<F> | undefined;
}

export { }