Merge pull request #574 from get-convex/tom/useSessionPaginatedQuery

useSessionPaginatedQuery

Author: ianmacartney

convex/sessionsExample.ts

@@ -16,6 +16,7 @@ import {
   runSessionFunctions,
   vSessionId,
 } from "convex-helpers/server/sessions";
+import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
 
 /** -----------------------------------------------------------------
@@ -193,3 +194,14 @@ export const joinRoom = mutationWithSession({
     }
   },
 });
+
+export const paginatedQueryWithSession = query({
+  args: { paginationOpts: paginationOptsValidator, ...SessionIdArg },
+  handler: async (ctx, args) => {
+    const foo = await ctx.db
+      .query("presence")
+      .order("desc")
+      .paginate(args.paginationOpts);
+    return foo;
+  },
+});

packages/convex-helpers/react/sessions.ts

@@ -28,6 +28,8 @@ import type {
   FunctionReference,
   FunctionReturnType,
   OptionalRestArgs,
+  PaginationOptions,
+  PaginationResult,
 } from "convex/server";
 import {
   useQuery,
@@ -38,6 +40,9 @@ import {
   type MutationOptions,
   useConvex,
   type ReactMutation,
+  usePaginatedQuery,
+  type PaginatedQueryArgs,
+  type UsePaginatedQueryReturnType,
 } from "convex/react";
 import type { SessionId } from "../server/sessions.js";
 import type { EmptyObject, BetterOmit } from "../index.js";
@@ -86,6 +91,21 @@ export type SessionArgsAndOptions<
   ? [args?: EmptyObject, options?: Options]
   : [args: BetterOmit<FunctionArgs<Fn>, "sessionId">, options?: Options];
 
+type SessionPaginatedQueryFunction<
+  Args extends { paginationOpts: PaginationOptions } = {
+    paginationOpts: PaginationOptions;
+  },
+> = FunctionReference<
+  "query",
+  "public",
+  { sessionId: SessionId } & Args,
+  PaginationResult<any>
+>;
+
+export type SessionPaginatedQueryArgs<
+  Fn extends SessionPaginatedQueryFunction,
+> = BetterOmit<PaginatedQueryArgs<Fn>, "sessionId"> | "skip";
+
 /**
  * Context for a Convex session, creating a server session and providing the id.
  *
@@ -203,6 +223,37 @@ export function useSessionQuery<Query extends SessionFunction<"query">>(
   return useQuery(query, ...([newArgs] as OptionalRestArgs<Query>));
 }
 
+/**
+ * Use this in place of {@link usePaginatedQuery} to run a query, passing a sessionId.
+ *
+ * @param query Query that takes in a sessionId parameter. Like `api.foo.bar`.
+ * @param args Args for that query, without the sessionId.
+ * @param options - An object specifying the `initialNumItems` to be loaded in
+ * the first page.
+ * @returns A {@link UsePaginatedQueryRes} that includes the currently loaded
+ * items, the status of the pagination, and a `loadMore` function.
+ * For SSR, it will skip the query until the second render.
+ */
+export function useSessionPaginatedQuery<
+  Query extends SessionPaginatedQueryFunction,
+>(
+  query: Query,
+  args: SessionPaginatedQueryArgs<Query>,
+  options: { initialNumItems: number },
+): UsePaginatedQueryReturnType<Query> | undefined {
+  const [sessionId] = useSessionId();
+  const skip = args === "skip" || !sessionId;
+  const originalArgs = args === "skip" ? {} : (args ?? {});
+
+  const newArgs = skip ? "skip" : { ...originalArgs, sessionId };
+
+  return usePaginatedQuery(
+    query,
+    newArgs as PaginatedQueryArgs<Query> | "skip",
+    options,
+  );
+}
+
 type SessionMutation<Mutation extends FunctionReference<"mutation">> = (
   ...args: SessionArgsArray<Mutation>
 ) => Promise<FunctionReturnType<Mutation>>;

src/components/SessionsExample.tsx

@@ -2,6 +2,7 @@ import {
   useSessionId,
   useSessionIdArg,
   useSessionMutation,
+  useSessionPaginatedQuery,
   useSessionQuery,
 } from "convex-helpers/react/sessions";
 import { api } from "../../convex/_generated/api";
@@ -14,6 +15,11 @@ export default () => {
   const login = useSessionMutation(api.sessionsExample.logIn);
   const logout = useSessionMutation(api.sessionsExample.logOut);
   const myPresence = useSessionQuery(api.sessionsExample.myPresence);
+  const paginatedPresence = useSessionPaginatedQuery(
+    api.sessionsExample.paginatedQueryWithSession,
+    {},
+    { initialNumItems: 2 },
+  )!;
   const joinRoom = useSessionMutation(
     api.sessionsExample.joinRoom,
   ).withOptimisticUpdate((store, args) => {
@@ -60,6 +66,17 @@ export default () => {
       </form>
       <p>{JSON.stringify(roomData)}</p>
       <ul>{myPresence && myPresence.map((room) => <li>{room}</li>)}</ul>
+      <ul>
+        {paginatedPresence.results.map((room) => (
+          <li>{room.room}</li>
+        ))}
+      </ul>
+      <button
+        disabled={paginatedPresence.status !== "CanLoadMore"}
+        onClick={() => paginatedPresence.loadMore(2)}
+      >
+        load more
+      </button>
 
       <button onClick={() => refreshSessionId((newSessionId) => logout())}>
         Delete Session Data on Log Out