feat: switch to cursor pagination (#1884)

* add cursor pagination function

* support custom order modifier
* refactor returned object

* feat(db): migrate paginated endpoints to cursor-based pagination

* sync

* support hasPrevPage boolean

* feat(client): migrate pagination from offset to cursor-based

* support beforeCursor/prevCursor

* wrap search results in items array for API consistency

apps/client/src/features/group/components/group-list.tsx

@@ -1,26 +1,25 @@
 import { Table, Group, Text, Anchor } from "@mantine/core";
 import { useGetGroupsQuery } from "@/features/group/queries/group-query";
-import { useState } from "react";
 import { Link } from "react-router-dom";
+import { useCursorPaginate } from "@/hooks/use-cursor-paginate";
 import { IconGroupCircle } from "@/components/icons/icon-people-circle.tsx";
 import { useTranslation } from "react-i18next";
 import { formatMemberCount } from "@/lib";
 import { IGroup } from "@/features/group/types/group.types.ts";
 import Paginate from "@/components/common/paginate.tsx";
 import { queryClient } from "@/main.tsx";
-import { getSpaces } from "@/features/space/services/space-service.ts";
 import { getGroupMembers } from "@/features/group/services/group-service.ts";
 import { AutoTooltipText } from "@/components/ui/auto-tooltip-text.tsx";
 
 export default function GroupList() {
   const { t } = useTranslation();
-  const [page, setPage] = useState(1);
-  const { data, isLoading } = useGetGroupsQuery({ page });
+  const { cursor, goNext, goPrev } = useCursorPaginate();
+  const { data, isLoading } = useGetGroupsQuery({ cursor });
 
   const prefetchGroupMembers = (groupId: string) => {
     queryClient.prefetchQuery({
-      queryKey: ["groupMembers", groupId, { page: 1 }],
-      queryFn: () => getGroupMembers(groupId, { page: 1 }),
+      queryKey: ["groupMembers", groupId, {}],
+      queryFn: () => getGroupMembers(groupId, {}),
     });
   };
 
@@ -85,10 +84,10 @@ export default function GroupList() {
 
       {data?.items.length > 0 && (
         <Paginate
-          currentPage={page}
-          hasPrevPage={data?.meta.hasPrevPage}
-          hasNextPage={data?.meta.hasNextPage}
-          onPageChange={setPage}
+          hasPrevPage={data?.meta?.hasPrevPage}
+          hasNextPage={data?.meta?.hasNextPage}
+          onNext={() => goNext(data?.meta?.nextCursor)}
+          onPrev={goPrev}
         />
       )}
     </>

apps/client/src/features/group/components/group-members.tsx

@@ -4,7 +4,7 @@ import {
   useRemoveGroupMemberMutation,
 } from "@/features/group/queries/group-query";
 import { useParams } from "react-router-dom";
-import React, { useState } from "react";
+import React from "react";
 import { IconDots } from "@tabler/icons-react";
 import { modals } from "@mantine/modals";
 import { CustomAvatar } from "@/components/ui/custom-avatar.tsx";
@@ -12,12 +12,13 @@ import useUserRole from "@/hooks/use-user-role.tsx";
 import { useTranslation } from "react-i18next";
 import { IUser } from "@/features/user/types/user.types.ts";
 import Paginate from "@/components/common/paginate.tsx";
+import { useCursorPaginate } from "@/hooks/use-cursor-paginate";
 
 export default function GroupMembersList() {
   const { t } = useTranslation();
   const { groupId } = useParams();
-  const [page, setPage] = useState(1);
-  const { data, isLoading } = useGroupMembersQuery(groupId, { page });
+  const { cursor, goNext, goPrev } = useCursorPaginate();
+  const { data, isLoading } = useGroupMembersQuery(groupId, { cursor });
   const removeGroupMember = useRemoveGroupMemberMutation();
   const { isAdmin } = useUserRole();
 
@@ -107,10 +108,10 @@ export default function GroupMembersList() {
 
       {data?.items.length > 0 && (
         <Paginate
-          currentPage={page}
-          hasPrevPage={data?.meta.hasPrevPage}
-          hasNextPage={data?.meta.hasNextPage}
-          onPageChange={setPage}
+          hasPrevPage={data?.meta?.hasPrevPage}
+          hasNextPage={data?.meta?.hasNextPage}
+          onNext={() => goNext(data?.meta?.nextCursor)}
+          onPrev={goPrev}
         />
       )}
     </>

apps/client/src/features/page/queries/page-query.ts

@@ -250,12 +250,10 @@ export function useGetSidebarPagesQuery(
   return useInfiniteQuery({
     queryKey: ["sidebar-pages", data],
     enabled: !!data?.pageId || !!data?.spaceId,
-    queryFn: ({ pageParam }) => getSidebarPages({ ...data, page: pageParam }),
-    initialPageParam: 1,
-    getPreviousPageParam: (firstPage) =>
-      firstPage.meta.hasPrevPage ? firstPage.meta.page - 1 : undefined,
+    queryFn: ({ pageParam }) => getSidebarPages({ ...data, cursor: pageParam }),
+    initialPageParam: undefined,
     getNextPageParam: (lastPage) =>
-      lastPage.meta.hasNextPage ? lastPage.meta.page + 1 : undefined,
+      lastPage.meta?.nextCursor ?? undefined,
   });
 }
 
@@ -263,13 +261,11 @@ export function useGetRootSidebarPagesQuery(data: SidebarPagesParams) {
   return useInfiniteQuery({
     queryKey: ["root-sidebar-pages", data.spaceId],
     queryFn: async ({ pageParam }) => {
-      return getSidebarPages({ spaceId: data.spaceId, page: pageParam });
+      return getSidebarPages({ spaceId: data.spaceId, cursor: pageParam });
     },
-    initialPageParam: 1,
-    getPreviousPageParam: (firstPage) =>
-      firstPage.meta.hasPrevPage ? firstPage.meta.page - 1 : undefined,
+    initialPageParam: undefined,
     getNextPageParam: (lastPage) =>
-      lastPage.meta.hasNextPage ? lastPage.meta.page + 1 : undefined,
+      lastPage.meta?.nextCursor ?? undefined,
   });
 }
 

apps/client/src/features/page/services/page-service.ts

@@ -72,22 +72,19 @@ export async function getSidebarPages(
 export async function getAllSidebarPages(
   params: SidebarPagesParams,
 ): Promise<InfiniteData<IPagination<IPage>, unknown>> {
-  let page = 1;
-  let hasNextPage = false;
+  let cursor: string | undefined = undefined;
   const pages: IPagination<IPage>[] = [];
-  const pageParams: number[] = [];
+  const pageParams: (string | undefined)[] = [];
 
   do {
-    const req = await api.post("/pages/sidebar-pages", { ...params, page: page });
+    const req = await api.post("/pages/sidebar-pages", { ...params, cursor });
 
     const data: IPagination<IPage> = req.data;
     pages.push(data);
-    pageParams.push(page);
+    pageParams.push(cursor);
 
-    hasNextPage = data.meta.hasNextPage;
-
-    page += 1;
-  } while (hasNextPage);
+    cursor = data.meta.nextCursor ?? undefined;
+  } while (cursor);
 
   return {
     pageParams,

apps/client/src/features/page/trash/components/trash.tsx

@@ -30,15 +30,15 @@ import { useState } from "react";
 import TrashPageContentModal from "@/features/page/trash/components/trash-page-content-modal";
 import { UserInfo } from "@/components/common/user-info.tsx";
 import Paginate from "@/components/common/paginate.tsx";
-import { usePaginateAndSearch } from "@/hooks/use-paginate-and-search";
+import { useCursorPaginate } from "@/hooks/use-cursor-paginate";
 
 export default function Trash() {
   const { t } = useTranslation();
   const { spaceSlug } = useParams();
-  const { page, setPage } = usePaginateAndSearch();
+  const { cursor, goNext, goPrev } = useCursorPaginate();
   const { data: space } = useGetSpaceBySlugQuery(spaceSlug);
   const { data: deletedPages, isLoading } = useDeletedPagesQuery(space?.id, {
-    page, limit: 50
+    cursor, limit: 50
   });
   const restorePageMutation = useRestorePageMutation();
   const deletePageMutation = useDeletePageMutation();
@@ -206,10 +206,10 @@ export default function Trash() {
 
         {deletedPages && deletedPages.items.length > 0 && (
           <Paginate
-            currentPage={page}
-            hasPrevPage={deletedPages.meta.hasPrevPage}
-            hasNextPage={deletedPages.meta.hasNextPage}
-            onPageChange={setPage}
+            hasPrevPage={deletedPages.meta?.hasPrevPage}
+            hasNextPage={deletedPages.meta?.hasNextPage}
+            onNext={() => goNext(deletedPages.meta?.nextCursor)}
+            onPrev={goPrev}
           />
         )}
       </Stack>

apps/client/src/features/page/types/page.types.ts

@@ -62,7 +62,7 @@ export interface ICopyPageToSpace {
 export interface SidebarPagesParams {
   spaceId?: string;
   pageId?: string;
-  page?: number; // pagination
+  cursor?: string;
 }
 
 export interface IPageInput {

apps/client/src/features/search/components/search-spotlight-filters.tsx

@@ -18,7 +18,6 @@ import {
   IconFileDescription,
   IconSearch,
   IconCheck,
-  IconSparkles,
 } from "@tabler/icons-react";
 import { useTranslation } from "react-i18next";
 import { useDebouncedValue } from "@mantine/hooks";
@@ -26,7 +25,7 @@ import { useGetSpacesQuery } from "@/features/space/queries/space-query";
 import { useLicense } from "@/ee/hooks/use-license";
 import classes from "./search-spotlight-filters.module.css";
 import { isCloud } from "@/lib/config.ts";
-import { useAtom } from "jotai/index";
+import { useAtom } from "jotai";
 import { workspaceAtom } from "@/features/user/atoms/current-user-atom.ts";
 
 interface SearchSpotlightFiltersProps {
@@ -53,7 +52,6 @@ export function SearchSpotlightFilters({
   const [workspace] = useAtom(workspaceAtom);
 
   const { data: spacesData } = useGetSpacesQuery({
-    page: 1,
     limit: 100,
     query: debouncedSpaceQuery,
   });
@@ -265,7 +263,9 @@ export function SearchSpotlightFilters({
                 contentType !== option.value &&
                 handleFilterChange("contentType", option.value)
               }
-              disabled={option.disabled || (isAiMode && option.value === "attachment")}
+              disabled={
+                option.disabled || (isAiMode && option.value === "attachment")
+              }
             >
               <Group flex="1" gap="xs">
                 <div>
@@ -275,11 +275,13 @@ export function SearchSpotlightFilters({
                       {t("Enterprise")}
                     </Badge>
                   )}
-                  {!option.disabled && isAiMode && option.value === "attachment" && (
-                    <Text size="xs" mt={4}>
-                      {t("Ask AI not available for attachments")}
-                    </Text>
-                  )}
+                  {!option.disabled &&
+                    isAiMode &&
+                    option.value === "attachment" && (
+                      <Text size="xs" mt={4}>
+                        {t("Ask AI not available for attachments")}
+                      </Text>
+                    )}
                 </div>
                 {contentType === option.value && <IconCheck size={20} />}
               </Group>

apps/client/src/features/search/services/search-service.ts

@@ -10,8 +10,8 @@ import {
 export async function searchPage(
   params: IPageSearchParams,
 ): Promise<IPageSearch[]> {
-  const req = await api.post<IPageSearch[]>("/search", params);
-  return req.data;
+  const req = await api.post<{ items: IPageSearch[] }>("/search", params);
+  return req.data.items;
 }
 
 export async function searchSuggestions(
@@ -24,13 +24,13 @@ export async function searchSuggestions(
 export async function searchShare(
   params: IPageSearchParams,
 ): Promise<IPageSearch[]> {
-  const req = await api.post<IPageSearch[]>("/search/share-search", params);
-  return req.data;
+  const req = await api.post<{ items: IPageSearch[] }>("/search/share-search", params);
+  return req.data.items;
 }
 
 export async function searchAttachments(
   params: IPageSearchParams,
 ): Promise<IAttachmentSearch[]> {
-  const req = await api.post<IAttachmentSearch[]>("/search-attachments", params);
-  return req.data;
+  const req = await api.post<{ items: IAttachmentSearch[] }>("/search-attachments", params);
+  return req.data.items;
 }

apps/client/src/features/share/components/share-list.tsx

@@ -1,8 +1,9 @@
 import { Table, Group, Text, Anchor } from "@mantine/core";
-import React, { useState } from "react";
+import React from "react";
 import { Link } from "react-router-dom";
 import { useTranslation } from "react-i18next";
 import Paginate from "@/components/common/paginate.tsx";
+import { useCursorPaginate } from "@/hooks/use-cursor-paginate";
 import { useGetSharesQuery } from "@/features/share/queries/share-query.ts";
 import { ISharedItem } from "@/features/share/types/share.types.ts";
 import { format } from "date-fns";
@@ -14,8 +15,8 @@ import classes from "./share.module.css";
 
 export default function ShareList() {
   const { t } = useTranslation();
-  const [page, setPage] = useState(1);
-  const { data, isLoading } = useGetSharesQuery({ page });
+  const { cursor, goNext, goPrev } = useCursorPaginate();
+  const { data, isLoading } = useGetSharesQuery({ cursor });
 
   return (
     <>
@@ -86,10 +87,10 @@ export default function ShareList() {
 
       {data?.items.length > 0 && (
         <Paginate
-          currentPage={page}
-          hasPrevPage={data?.meta.hasPrevPage}
-          hasNextPage={data?.meta.hasNextPage}
-          onPageChange={setPage}
+          hasPrevPage={data?.meta?.hasPrevPage}
+          hasNextPage={data?.meta?.hasNextPage}
+          onNext={() => goNext(data?.meta?.nextCursor)}
+          onPrev={goPrev}
         />
       )}
     </>

apps/client/src/features/share/queries/share-query.ts

@@ -33,7 +33,7 @@ export function useGetSharesQuery(
   params?: QueryParams,
 ): UseQueryResult<IPagination<ISharedItem>, Error> {
   return useQuery({
-    queryKey: ["share-list"],
+    queryKey: ["share-list", params],
     queryFn: () => getShares(params),
     placeholderData: keepPreviousData,
   });

apps/client/src/features/space/components/space-grid.tsx

@@ -15,7 +15,7 @@ import { AvatarIconType } from "@/features/attachments/types/attachment.types.ts
 
 export default function SpaceGrid() {
   const { t } = useTranslation();
-  const { data, isLoading } = useGetSpacesQuery({ page: 1, limit: 10 });
+  const { data, isLoading } = useGetSpacesQuery({ limit: 10 });
 
   const cards = data?.items.slice(0, 9).map((space, index) => (
     <Card

apps/client/src/features/space/components/space-list.tsx

@@ -1,5 +1,6 @@
 import { Group, Table, Text } from "@mantine/core";
 import React, { useState } from "react";
+import { useCursorPaginate } from "@/hooks/use-cursor-paginate";
 import { useGetSpacesQuery } from "@/features/space/queries/space-query.ts";
 import SpaceSettingsModal from "@/features/space/components/settings-modal.tsx";
 import { useDisclosure } from "@mantine/hooks";
@@ -12,8 +13,8 @@ import { AutoTooltipText } from "@/components/ui/auto-tooltip-text.tsx";
 
 export default function SpaceList() {
   const { t } = useTranslation();
-  const [page, setPage] = useState(1);
-  const { data, isLoading } = useGetSpacesQuery({ page });
+  const { cursor, goNext, goPrev } = useCursorPaginate();
+  const { data, isLoading } = useGetSpacesQuery({ cursor });
   const [opened, { open, close }] = useDisclosure(false);
   const [selectedSpaceId, setSelectedSpaceId] = useState<string>(null);
 
@@ -72,10 +73,10 @@ export default function SpaceList() {
 
       {data?.items.length > 0 && (
         <Paginate
-          currentPage={page}
-          hasPrevPage={data?.meta.hasPrevPage}
-          hasNextPage={data?.meta.hasNextPage}
-          onPageChange={setPage}
+          hasPrevPage={data?.meta?.hasPrevPage}
+          hasNextPage={data?.meta?.hasNextPage}
+          onNext={() => goNext(data?.meta?.nextCursor)}
+          onPrev={goPrev}
         />
       )}
 

apps/client/src/features/space/components/space-members.tsx

@@ -41,9 +41,9 @@ export default function SpaceMembersList({
   readOnly,
 }: SpaceMembersProps) {
   const { t } = useTranslation();
-  const { search, page, setPage, handleSearch } = usePaginateAndSearch();
+  const { search, cursor, goNext, goPrev, handleSearch } = usePaginateAndSearch();
   const { data, isLoading } = useSpaceMembersQuery(spaceId, {
-    page,
+    cursor,
     limit: 100,
     query: search,
   });
@@ -206,10 +206,10 @@ export default function SpaceMembersList({
 
       {data?.items.length > 0 && (
         <Paginate
-          currentPage={page}
-          hasPrevPage={data?.meta.hasPrevPage}
-          hasNextPage={data?.meta.hasNextPage}
-          onPageChange={setPage}
+          hasPrevPage={data?.meta?.hasPrevPage}
+          hasNextPage={data?.meta?.hasNextPage}
+          onNext={() => goNext(data?.meta?.nextCursor)}
+          onPrev={goPrev}
         />
       )}
     </>

apps/client/src/features/space/components/spaces-page/all-spaces-list.tsx

@@ -28,19 +28,19 @@ import { AutoTooltipText } from "@/components/ui/auto-tooltip-text.tsx";
 interface AllSpacesListProps {
   spaces: any[];
   onSearch: (query: string) => void;
-  page: number;
   hasPrevPage?: boolean;
   hasNextPage?: boolean;
-  onPageChange: (page: number) => void;
+  onNext: () => void;
+  onPrev: () => void;
 }
 
 export default function AllSpacesList({
   spaces,
   onSearch,
-  page,
   hasPrevPage,
   hasNextPage,
-  onPageChange,
+  onNext,
+  onPrev,
 }: AllSpacesListProps) {
   const { t } = useTranslation();
   const [settingsOpened, { open: openSettings, close: closeSettings }] =
@@ -145,10 +145,10 @@ export default function AllSpacesList({
 
       {spaces.length > 0 && (
         <Paginate
-          currentPage={page}
           hasPrevPage={hasPrevPage}
           hasNextPage={hasNextPage}
-          onPageChange={onPageChange}
+          onNext={onNext}
+          onPrev={onPrev}
         />
       )}
 

apps/client/src/features/workspace/components/members/components/workspace-invites-table.tsx

@@ -1,6 +1,6 @@
 import { Group, Table, Avatar, Text, Alert } from "@mantine/core";
 import { useWorkspaceInvitationsQuery } from "@/features/workspace/queries/workspace-query.ts";
-import React, { useState } from "react";
+import React from "react";
 import { getUserRoleLabel } from "@/features/workspace/types/user-role-data.ts";
 import InviteActionMenu from "@/features/workspace/components/members/components/invite-action-menu.tsx";
 import { IconInfoCircle } from "@tabler/icons-react";
@@ -8,12 +8,13 @@ import { timeAgo } from "@/lib/time.ts";
 import useUserRole from "@/hooks/use-user-role.tsx";
 import { useTranslation } from "react-i18next";
 import Paginate from "@/components/common/paginate.tsx";
+import { useCursorPaginate } from "@/hooks/use-cursor-paginate";
 
 export default function WorkspaceInvitesTable() {
   const { t } = useTranslation();
-  const [page, setPage] = useState(1);
+  const { cursor, goNext, goPrev } = useCursorPaginate();
   const { data, isLoading } = useWorkspaceInvitationsQuery({
-    page,
+    cursor,
     limit: 100,
   });
   const { isAdmin } = useUserRole();
@@ -65,10 +66,10 @@ export default function WorkspaceInvitesTable() {
 
       {data?.items.length > 0 && (
         <Paginate
-          currentPage={page}
-          hasPrevPage={data?.meta.hasPrevPage}
-          hasNextPage={data?.meta.hasNextPage}
-          onPageChange={setPage}
+          hasPrevPage={data?.meta?.hasPrevPage}
+          hasNextPage={data?.meta?.hasNextPage}
+          onNext={() => goNext(data?.meta?.nextCursor)}
+          onPrev={goPrev}
         />
       )}
     </>

apps/client/src/features/workspace/components/members/components/workspace-members-table.tsx

@@ -21,9 +21,9 @@ import MemberActionMenu from "@/features/workspace/components/members/components
 
 export default function WorkspaceMembersTable() {
   const { t } = useTranslation();
-  const { search, page, setPage, handleSearch } = usePaginateAndSearch();
+  const { search, cursor, goNext, goPrev, handleSearch } = usePaginateAndSearch();
   const { data, isLoading } = useWorkspaceMembersQuery({
-    page,
+    cursor,
     limit: 100,
     query: search,
   });
@@ -111,10 +111,10 @@ export default function WorkspaceMembersTable() {
 
       {data?.items.length > 0 && (
         <Paginate
-          currentPage={page}
-          hasPrevPage={data?.meta.hasPrevPage}
-          hasNextPage={data?.meta.hasNextPage}
-          onPageChange={setPage}
+          hasPrevPage={data?.meta?.hasPrevPage}
+          hasNextPage={data?.meta?.hasNextPage}
+          onNext={() => goNext(data?.meta?.nextCursor)}
+          onPrev={goPrev}
         />
       )}
     </>