@convex-dev/agent 0.1.8-alpha.0 → 0.1.8-alpha.2

package/dist/commonjs/react/usePaginatedQuery.d.ts

@@ -1,241 +0,0 @@
-import type { OptimisticLocalStore } from "convex/browser";
-import type { FunctionReturnType, PaginationOptions, PaginationResult } from "convex/server";
-import { type Value } from "convex/values";
-import { type FunctionArgs, type FunctionReference } from "convex/server";
-import type { BetterOmit, Expand } from "convex/server";
-/**
- * A {@link server.FunctionReference} that is usable with {@link usePaginatedQuery}.
- *
- * This function reference must:
- * - Refer to a public query
- * - Have an argument named "paginationOpts" of type {@link server.PaginationOptions}
- * - Have a return type of {@link server.PaginationResult}.
- *
- * @public
- */
-export type PaginatedQueryReference = FunctionReference<"query", "public", {
-    paginationOpts: PaginationOptions;
-}, PaginationResult<any>>;
-/**
- * This is a clone of the `usePaginatedQuery` hook from `convex-helpers`.
- * The difference is that we lazily pin the end cursor on loading a new page.
- * This will be standard behavior in a future version of `convex/react`, but
- * for now it allows the agent to have correct behavior when loading a new page
- * where new items are still coming in.
- */
-export declare function usePaginatedQuery<Query extends PaginatedQueryReference>(query: Query, args: PaginatedQueryArgs<Query> | "skip", options: {
-    initialNumItems: number;
-}): UsePaginatedQueryReturnType<Query>;
-/**
- * Reset pagination id for tests only, so tests know what it is.
- */
-export declare function resetPaginationId(): void;
-/**
- * The result of calling the {@link usePaginatedQuery} hook.
- *
- * This includes:
- * - `results` - An array of the currently loaded results.
- * - `isLoading` - Whether the hook is currently loading results.
- * - `status` - The status of the pagination. The possible statuses are:
- *   - "LoadingFirstPage": The hook is loading the first page of results.
- *   - "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.
- * - `loadMore(n)` A callback to fetch more results. This will only fetch more
- * results if the status is "CanLoadMore".
- *
- * @public
- */
-export type UsePaginatedQueryResult<Item> = {
-    results: Item[];
-    loadMore: (numItems: number) => void;
-} & ({
-    status: "LoadingFirstPage";
-    isLoading: true;
-} | {
-    status: "CanLoadMore";
-    isLoading: false;
-} | {
-    status: "LoadingMore";
-    isLoading: true;
-} | {
-    status: "Exhausted";
-    isLoading: false;
-});
-/**
- * The possible pagination statuses in {@link UsePaginatedQueryResult}.
- *
- * This is a union of string literal types.
- * @public
- */
-export type PaginationStatus = UsePaginatedQueryResult<any>["status"];
-/**
- * Given a {@link PaginatedQueryReference}, get the type of the arguments
- * object for the query, excluding the `paginationOpts` argument.
- *
- * @public
- */
-export type PaginatedQueryArgs<Query extends PaginatedQueryReference> = Expand<BetterOmit<FunctionArgs<Query>, "paginationOpts">>;
-/**
- * Given a {@link PaginatedQueryReference}, get the type of the item being
- * paginated over.
- * @public
- */
-export type PaginatedQueryItem<Query extends PaginatedQueryReference> = FunctionReturnType<Query>["page"][number];
-/**
- * The return type of {@link usePaginatedQuery}.
- *
- * @public
- */
-export type UsePaginatedQueryReturnType<Query extends PaginatedQueryReference> = UsePaginatedQueryResult<PaginatedQueryItem<Query>>;
-/**
- * Optimistically update the values in a paginated list.
- *
- * This optimistic update is designed to be used to update data loaded with
- * {@link usePaginatedQuery}. 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(api.myModule.myMutation)
- * .withOptimisticUpdate((localStore, mutationArg) => {
- *
- *   // Optimistically update the document with ID `mutationArg`
- *   // to have an additional property.
- *
- *   optimisticallyUpdateValueInPaginatedQuery(
- *     localStore,
- *     api.myModule.paginatedQuery
- *     {},
- *     currentValue => {
- *       if (mutationArg === currentValue._id) {
- *         return {
- *           ...currentValue,
- *           "newProperty": "newValue",
- *         };
- *       }
- *       return currentValue;
- *     }
- *   );
- *
- * });
- * ```
- *
- * @param localStore - An {@link OptimisticLocalStore} to update.
- * @param query - A {@link FunctionReference} for the paginated query to update.
- * @param args - The arguments object to the query function, excluding the
- * `paginationOpts` property.
- * @param updateValue - A function to produce the new values.
- *
- * @public
- */
-export declare function optimisticallyUpdateValueInPaginatedQuery<Query extends PaginatedQueryReference>(localStore: OptimisticLocalStore, query: Query, args: PaginatedQueryArgs<Query>, updateValue: (currentValue: PaginatedQueryItem<Query>) => PaginatedQueryItem<Query>): void;
-/**
- * Updates a paginated query to insert an element at the top of the list.
- *
- * This is regardless of the sort order, so if the list is in descending order,
- * the inserted element will be treated as the "biggest" element, but if it's
- * ascending, it'll be treated as the "smallest".
- *
- * Example:
- * ```ts
- * const createTask = useMutation(api.tasks.create)
- *   .withOptimisticUpdate((localStore, mutationArgs) => {
- *   insertAtTop({
- *     paginatedQuery: api.tasks.list,
- *     argsToMatch: { listId: mutationArgs.listId },
- *     localQueryStore: localStore,
- *     item: { _id: crypto.randomUUID() as Id<"tasks">, title: mutationArgs.title, completed: false },
- *   });
- * });
- * ```
- *
- * @param options.paginatedQuery - A function reference to the paginated query.
- * @param options.argsToMatch - Optional arguments that must be in each relevant paginated query.
- * This is useful if you use the same query function with different arguments to load
- * different lists.
- * @param options.localQueryStore
- * @param options.item The item to insert.
- * @returns
- */
-export declare function insertAtTop<Query extends PaginatedQueryReference>(options: {
-    paginatedQuery: Query;
-    argsToMatch?: Partial<PaginatedQueryArgs<Query>>;
-    localQueryStore: OptimisticLocalStore;
-    item: PaginatedQueryItem<Query>;
-}): void;
-/**
- * Updates a paginated query to insert an element at the bottom of the list.
- *
- * This is regardless of the sort order, so if the list is in descending order,
- * the inserted element will be treated as the "smallest" element, but if it's
- * ascending, it'll be treated as the "biggest".
- *
- * This only has an effect if the last page is loaded, since otherwise it would result
- * in the element being inserted at the end of whatever is loaded (which is the middle of the list)
- * and then popping out once the optimistic update is over.
- *
- * @param options.paginatedQuery - A function reference to the paginated query.
- * @param options.argsToMatch - Optional arguments that must be in each relevant paginated query.
- * This is useful if you use the same query function with different arguments to load
- * different lists.
- * @param options.localQueryStore
- * @param options.element The element to insert.
- * @returns
- */
-export declare function insertAtBottomIfLoaded<Query extends PaginatedQueryReference>(options: {
-    paginatedQuery: Query;
-    argsToMatch?: Partial<PaginatedQueryArgs<Query>>;
-    localQueryStore: OptimisticLocalStore;
-    item: PaginatedQueryItem<Query>;
-}): void;
-/**
- * This is a helper function for inserting an item at a specific position in a paginated query.
- *
- * You must provide the sortOrder and a function for deriving the sort key (an array of values) from an item in the list.
- *
- * This will only work if the server query uses the same sort order and sort key as the optimistic update.
- *
- * Example:
- * ```ts
- * const createTask = useMutation(api.tasks.create)
- *   .withOptimisticUpdate((localStore, mutationArgs) => {
- *   insertAtPosition({
- *     paginatedQuery: api.tasks.listByPriority,
- *     argsToMatch: { listId: mutationArgs.listId },
- *     sortOrder: "asc",
- *     sortKeyFromItem: (item) => [item.priority, item._creationTime],
- *     localQueryStore: localStore,
- *     item: {
- *       _id: crypto.randomUUID() as Id<"tasks">,
- *       _creationTime: Date.now(),
- *       title: mutationArgs.title,
- *       completed: false,
- *       priority: mutationArgs.priority,
- *     },
- *   });
- * });
- * ```
- * @param options.paginatedQuery - A function reference to the paginated query.
- * @param options.argsToMatch - Optional arguments that must be in each relevant paginated query.
- * This is useful if you use the same query function with different arguments to load
- * different lists.
- * @param options.sortOrder - The sort order of the paginated query ("asc" or "desc").
- * @param options.sortKeyFromItem - A function for deriving the sort key (an array of values) from an element in the list.
- * Including a tie-breaker field like `_creationTime` is recommended.
- * @param options.localQueryStore
- * @param options.item - The item to insert.
- * @returns
- */
-export declare function insertAtPosition<Query extends PaginatedQueryReference>(options: {
-    paginatedQuery: Query;
-    argsToMatch?: Partial<PaginatedQueryArgs<Query>>;
-    sortOrder: "asc" | "desc";
-    sortKeyFromItem: (element: PaginatedQueryItem<Query>) => Value | Value[];
-    localQueryStore: OptimisticLocalStore;
-    item: PaginatedQueryItem<Query>;
-}): void;
-//# sourceMappingURL=usePaginatedQuery.d.ts.map

package/dist/commonjs/react/usePaginatedQuery.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"usePaginatedQuery.d.ts","sourceRoot":"","sources":["../../../src/react/usePaginatedQuery.ts"],"names":[],"mappings":"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"}