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

Client for the Convex Cloud

import { Value } from "../values/index.js";
import { GenericAPI, NamedQuery } from "../api/index.js";
import { OptimisticLocalStore } from "../browser/index.js";
import { PaginationOptions, PaginationResult } from "../server/index.js";
import { PickByValue } from "../type_utils.js";
/**
 * 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;
});
/**
 * 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 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;
/**
 * 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;
/**
 * 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>>>;
/**
 * 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;
//# sourceMappingURL=use_paginated_query.d.ts.map