convex/dist/types/react/react.d.ts

Client for the Convex Cloud

import { default as React_2 } from 'react';

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

/**
 * 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;
}

/**
 * State describing the client's connection with the Convex backend.
 *
 * @public
 */
declare type ConnectionState = {
    hasInflightMutation: boolean;
    hasInflightAction: boolean;
    isWebSocketConnected: boolean;
};

/**
 * 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.
     * @param journal - An (optional) {@link browser.QueryJournal} to use while
     * executing this query. Note that if this query function with these arguments
     * has already been requested, the journal will have no effect.
     * @returns The {@link Watch} object.
     */
    watchQuery<Name extends QueryNames<API>>(name: Name, args: Parameters<NamedQuery<API, Name>>, journal?: QueryJournal): Watch<ReturnType<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>;
    /**
     * Construct a new {@link ReactAction}
     *
     * @param name - The name of the Action.
     * @returns The {@link ReactAction} object with that name.
     */
    action<Name extends ActionNames<API>>(name: Name): ReactAction<API, Name>;
    /**
     * Get the current {@link ConnectionState} between the client and the Convex
     * backend.
     *
     * @returns The {@link ConnectionState} with the Convex backend.
     */
    connectionState(): ConnectionState;
    /**
     * 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;
}

/**
 * An opaque identifier used for paginating a database query.
 *
 * Cursors are returned from {@link OrderedQuery.paginate} and represent the
 * point of the query where the page of results ended.
 *
 * To continue paginating, pass the cursor back into
 * {@link OrderedQuery.paginate} in the {@link PaginationOptions} object to
 * fetch another page of results.
 *
 * Note: Cursors can only be passed to _exactly_ the same database query that
 * they were generated from. You may not reuse a cursor between different
 * database queries.
 *
 * @public
 */
declare type Cursor = string;

/**
 * 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>;
    actions: Record<string, (...args: any[]) => any>;
};

/**
 * An identifier for a document in Convex.
 *
 * Convex documents are uniquely identified by their `GenericId`, which is accessible
 * on the `_id` field. To learn more, see [Data Modeling](https://docs.convex.dev/using/data-modeling).
 *
 * Documents can be loaded using `db.get(id)` in query and mutation functions.
 *
 * **Important**: Use `myId.equals(otherId)` to check for equality.
 * Using `===` will not work because two different instances of `GenericId` can refer
 * to the same document.
 *
 * `GenericId`s are 17 bytes long and consist of:
 * - A 15-byte random value.
 * - A 2-byte timestamp representing the document's creation, in days since the Unix epoch.
 * This is encoded in base 62 ([0-9A-Za-z]).
 *
 * If you're using code generation, use the `Id` class typed for your data model in
 * `convex/_generated/dataModel.js`.
 *
 * @typeParam TableName - A string literal type of the table name (like "users").
 *
 * @public
 */
declare class GenericId<TableName extends string> {
    /**
     * The table name this {@link GenericId} references.
     */
    readonly tableName: TableName;
    /**
     * The identifier string.
     *
     * This contains the characters `[0-9A-Za-z]`.
     */
    readonly id: string;
    constructor(tableName: TableName, id: string);
    /**
     * Check if this {@link GenericId} refers to the same document as another {@link GenericId}.
     *
     * @param other - The other {@link GenericId} to compare to.
     * @returns `true` if the objects refer to the same document.
     */
    equals(other: unknown): boolean;
    /**
     * Parse a {@link GenericId} from its JSON representation.
     */
    static fromJSON(obj: any): GenericId<string>;
    /**
     * Convert a {@link GenericId} into its JSON representation.
     */
    toJSON(): JSONValue;
    /**
     * Convert a {@link GenericId} into its string representation.
     *
     * This includes the identifier but not the table name.
     */
    toString(): string;
    /**
     * Pretty-print this {@link GenericId} for debugging.
     */
    inspect(): string;
}

/**
 * The type of JavaScript values serializable to JSON.
 *
 * @public
 */
declare type JSONValue = null | boolean | number | string | JSONValue[] | {
    [key: string]: JSONValue;
};

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

/**
 * The type of an action in a Convex API.
 *
 * @public
 */
declare type NamedAction<API extends GenericAPI, Name extends MutationNames<API>> = API["actions"][Name];

/**
 * 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];

/**
 * Optimistically update the values in a paginated list.
 *
 * This optimistic update is designed to be used to update data loaded with
 * {@link usePaginatedQueryGeneric}. It updates the list by applying
 * `updateValue` to each element of the list across all of the loaded pages.
 *
 * This will only apply to queries with a matching names and arguments.
 *
 * Example usage:
 * ```ts
 * const myMutation = useMutation("myMutationName")
 * .withOptimisticUpdate((localStore, mutationArg) => {
 *
 *   // Optimistically update the document with ID `mutationArg`
 *   // to have an additional property.
 *
 *   optimisticallyUpdateValueInPaginatedQuery(
 *     localStore,
 *     "paginatedQueryName",
 *     [],
 *     currentValue => {
 *       if (mutationArg.equals(currentValue._id)) {
 *         return {
 *           ...currentValue,
 *           "newProperty": "newValue",
 *         };
 *       }
 *       return currentValue;
 *     }
 *   );
 *
 * });
 * ```
 *
 * @param name - The name of the paginated query function.
 * @param args - The arguments to the query function, excluding the first.
 * @param updateValue - A function to produce the new values.
 *
 * @public
 */
export declare function optimisticallyUpdateValueInPaginatedQuery<API extends GenericAPI, Name extends PaginatedQueryNames<API>>(localStore: OptimisticLocalStore<API>, name: Name, args: PaginatedQueryArgs<NamedQuery<API, Name>>, updateValue: (currentValue: PaginatedQueryReturnType<NamedQuery<API, Name>>) => PaginatedQueryReturnType<NamedQuery<API, Name>>): void;

/**
 * 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>>;
    /**
     * Retrieve the results are arguments of all queries with a given name.
     *
     * This is useful for complex optimistic updates that need to inspect and
     * update many query results (for example updating a paginated list).
     *
     * 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.
     * @returns An array of objects, one for each query of the given name.
     * Each object includes:
     *   - `args` - An array of the arguments to the query.
     *   - `value` The query result or `undefined` if the query is loading.
     */
    getAllQueries<Name extends QueryNames<API>>(name: Name): {
        args: Parameters<NamedQuery<API, Name>>;
        value: 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 Value[]> = (localQueryStore: OptimisticLocalStore<API>, ...args: Arguments) => void;

/**
 * The type of the arguments to a {@link PaginatedQueryFunction}.
 *
 * This type includes all the arguments after the initial
 * {@link server.PaginationOptions} argument.
 *
 * @public
 */
export declare type PaginatedQueryArgs<Query extends PaginatedQueryFunction<any, any>> = Query extends PaginatedQueryFunction<infer Args, any> ? Args : never;

/**
 * A query function that is usable with {@link usePaginatedQueryGeneric}.
 *
 * The function's first argument must be a {@link server.PaginationOptions} object.
 * The function must return a {@link server.PaginationResult}.
 *
 * @public
 */
export declare type PaginatedQueryFunction<Args extends Value[], ReturnType extends Value> = (paginationOptions: PaginationOptions, ...args: Args) => PaginationResult<ReturnType>;

/**
 * The names of the paginated query functions in a Convex API.
 *
 * These are normal query functions that match {@link PaginatedQueryFunction}.
 *
 * @public
 */
export declare type PaginatedQueryNames<API extends GenericAPI> = keyof PickByValue<API["queries"], PaginatedQueryFunction<any, any>> & string;

/**
 * The return type of a {@link PaginatedQueryFunction}.
 *
 * This is the type of the inner document or object within the
 * {@link server.PaginationResult} that a paginated query function returns.
 *
 * @public
 */
export declare type PaginatedQueryReturnType<Query extends PaginatedQueryFunction<any, any>> = Query extends PaginatedQueryFunction<any, infer ReturnType> ? ReturnType : never;

/**
 * The options passed to {@link OrderedQuery.paginate}.
 *
 * @public
 */
declare interface PaginationOptions {
    /**
     * Number of items to load in this page of results.
     *
     * Note: This is only an initial value!
     *
     * If you are running this paginated query in a reactive query function, you
     * may receive more or less items than this if items were added to or removed
     * from the query range.
     */
    numItems: number;
    /**
     * A {@link Cursor} representing the start of this page or `null` to start
     * at the beginning of the query results.
     */
    cursor: Cursor | null;
    /* Excluded from this release type: maximumRowsRead */
}

/**
 * The result of paginating using {@link OrderedQuery.paginate}.
 *
 * @public
 */
declare interface PaginationResult<T> {
    /**
     * The page of results.
     */
    page: T[];
    /**
     * Have we reached the end of the results?
     */
    isDone: boolean;
    /**
     * A {@link Cursor} to continue loading more results.
     */
    continueCursor: Cursor;
}

/**
 * From ObjectType, pick the properties that are assignable to T.
 */
declare type PickByValue<ObjectType, T> = Pick<ObjectType, {
    [Key in keyof ObjectType]: ObjectType[Key] extends T ? Key : never;
}[keyof ObjectType]>;

/**
 * A serialized representation of decisions made during a query's execution.
 *
 * A journal is produced when a query function first executes and is re-used
 * when a query is re-executed.
 *
 * Currently this is used to store pagination end cursors to ensure
 * that pages of paginated queries will always end at the same cursor. This
 * enables gapless, reactive pagination.
 *
 * `null` is used to represent empty journals.
 * @public
 */
declare type QueryJournal = string | null;

/**
 * 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;

/**
 * An interface to execute a Convex action on the server.
 *
 * @public
 */
export declare interface ReactAction<API extends GenericAPI, Name extends ActionNames<API>> {
    /**
     * Execute the function on the server, returning a `Promise` of its return value.
     *
     * @param args - Arguments for the function to pass up to the server.
     * @returns The return value of the server-side function call.
     * @public
     */
    (...args: Parameters<NamedAction<API, Name>>): Promise<ReturnType<NamedAction<API, Name>>>;
}

/**
 * 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>;
}

/**
 * An object representing a request to load multiple queries.
 *
 * The keys of this object are identifiers and the values are objects containing
 * the name of the query function and the arguments to pass to it.
 *
 * This is used as an argument to {@link useQueriesGeneric}.
 * @public
 */
export declare type RequestForQueries = Record<string, {
    name: string;
    args: Value[];
}>;

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

/**
 * Construct a new {@link ReactAction}.
 *
 * Action objects can be called like functions to request execution of the
 * corresponding Convex function.
 *
 * 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 `useAction` 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 action.
 * @returns The {@link ReactAction} object with that name.
 *
 * @public
 */
export declare function useActionGeneric<API extends GenericAPI, Name extends ActionNames<API>>(name: Name): ReactAction<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 usePaginatedQueryGeneric} a type specific to your API.
 *
 * @public
 */
export declare type UsePaginatedQueryForAPI<API extends GenericAPI> = <Name extends PaginatedQueryNames<API>>(name: Name, options: {
    initialNumItems: number;
}, ...args: PaginatedQueryArgs<NamedQuery<API, Name>>) => UsePaginatedQueryResult<PaginatedQueryReturnType<NamedQuery<API, Name>>>;

/**
 * Load data reactively from a paginated query to a create a growing list.
 *
 * This can be used to power "infinite scroll" UIs.
 *
 * This hook must be used with Convex query functions that match
 * {@link PaginatedQueryFunction}. This means they must:
 * 1. Have a first argument must be an object containing `numItems` and `cursor`.
 * 2. Return a {@link server.PaginationResult}.
 *
 * `usePaginatedQueryGeneric` concatenates all the pages
 * of results into a single list and manages the continuation cursors when
 * requesting more items.
 *
 * Example usage:
 * ```typescript
 * const { results, status, loadMore } = usePaginatedQueryGeneric(
 *   "listMessages",
 *   { initialNumItems: 5 },
 *   "#general"
 * );
 * ```
 *
 * If the query `name` or `args` change, the pagination state will be reset
 * to the first page. Similarly, if any of the pages result in an InvalidCursor
 * or QueryScannedTooManyDocuments error, the pagination state will also reset
 * to the first page.
 *
 * To learn more about pagination, see [Paginated Queries](https://docs.convex.dev/using/pagination).
 *
 * If you're using code generation, use the `usePaginatedQuery` function in
 * `convex/_generated/react.js` which is typed for your API.
 *
 * @param name - The name of the query function.
 * @param options - An object specifying the `initialNumItems` to be loaded in
 * the first page.
 * @param args - The arguments to the query function, excluding the first.
 * @returns A {@link UsePaginatedQueryResult} that includes the currently loaded
 * items, the status of the pagination, and a `loadMore` function.
 *
 * @public
 */
export declare function usePaginatedQueryGeneric(name: string, options: {
    initialNumItems: number;
}, ...args: Value[]): UsePaginatedQueryResult<any>;

/**
 * The result of calling the {@link usePaginatedQueryGeneric} hook.
 *
 * This includes:
 * 1. `results` - An array of the currently loaded results.
 * 2. `status` - The status of the pagination. The possible statuses are:
 *   - "CanLoadMore": This query may have more items to fetch. Call `loadMore` to
 *   fetch another page.
 *   - "LoadingMore": We're currently loading another page of results.
 *   - "Exhausted": We've paginated to the end of the list.
 * 3. `loadMore` A callback to fetch more results. This will be `undefined`
 * unless the status is "CanLoadMore".
 *
 * @public
 */
export declare type UsePaginatedQueryResult<T> = {
    results: T[];
} & ({
    status: "CanLoadMore";
    loadMore: (numItems: number) => void;
} | {
    status: "LoadingMore";
    loadMore: undefined;
} | {
    status: "Exhausted";
    loadMore: undefined;
});

/**
 * Internal type helper used by Convex code generation.
 *
 * Used to give {@link useQueriesGeneric} a type specific to your API.
 *
 * @public
 */
export declare type UseQueriesForAPI<API extends GenericAPI> = <QueryNameMap extends Record<string, QueryNames<API>>>(queries: {
    [Identifier in keyof QueryNameMap]: {
        name: QueryNameMap[Identifier];
        args: Parameters<NamedQuery<API, QueryNameMap[Identifier]>>;
    };
}) => {
    [Identifier in keyof QueryNameMap]: ReturnType<NamedQuery<API, QueryNameMap[Identifier]>> | undefined | Error;
};

/**
 * Load a variable number of reactive Convex queries.
 *
 * `useQueriesGeneric` is similar to {@link useQueryGeneric} but it allows
 * loading multiple queries which can be useful for loading a dynamic number
 * of queries without violating the rules of React hooks.
 *
 * This hook accepts an object whose keys are identifiers for each query and the
 * values are objects of `{ name: string, args: Value[] }`. The `name` is the
 * name of the Convex query function to load, and the `args` are the arguments to
 * that function.
 *
 * The hook returns an object that maps each identifier to the result of the query,
 * `undefined` if the query is still loading, or an instance of `Error` if the query
 * threw an exception.
 *
 * For example if you loaded a query like:
 * ```typescript
 * const results = useQueriesGeneric({
 *   messagesInGeneral: {
 *     name: "listMessages",
 *     args: ["#general"]
 *   }
 * });
 * ```
 * then the result would look like:
 * ```typescript
 * {
 *   messagesInGeneral: [{
 *     channel: "#general",
 *     body: "hello"
 *     _id: ...,
 *     _creationTime: ...
 *   }]
 * }
 * ```
 *
 * This React hook contains internal state that will cause a rerender
 * whenever any of the query results change.
 *
 * Throws an error if not used under {@link ConvexProvider}.
 *
 * If you're using code generation, use the `useQueries` function in
 * `convex/_generated/react.js` which is typed for your API.
 *
 * @param queries - An object mapping identifiers to objects of
 * `{name: string, args: Value[] }` describing which query functions to fetch.
 * @returns An object with the same keys as the input. The values are the result
 * of the query function, `undefined` if it's still loading, or an `Error` if
 * it threw an exception.
 *
 * @public
 */
export declare function useQueriesGeneric(queries: RequestForQueries): Record<string, any | undefined | Error>;

/**
 * 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 value supported by Convex.
 *
 * Values can be:
 * - stored inside of documents.
 * - used as arguments and return types to queries and mutation functions.
 *
 * You can see the full set of supported types at
 * [Types](https://docs.convex.dev/using/types).
 *
 * @public
 */
declare type Value = GenericId<string> | null | bigint | number | boolean | string | ArrayBuffer | Value[] | Set<Value> | Map<Value, Value> | {
    [key: string]: Value;
};

/**
 * A watch on the output of a Convex query function.
 *
 * @public
 */
export declare interface Watch<T> {
    /**
     * 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(): T | undefined;
    /**
     * Get the current {@link browser.QueryJournal} for this query.
     *
     * If we have not yet received a result for this query, this will be `undefined`.
     */
    journal(): QueryJournal | undefined;
}

export { }