Merge pull request #63 from commitd/sh/pagination

feat(usepagination): adds query callback to simplify usePagination use

Author: stuarthendren

src/usePagination/usePagination.stories.tsx

@@ -10,17 +10,19 @@ import {
   Slider,
 } from '@committed/components'
 import { Meta, Story } from '@storybook/react'
-import React, { useEffect, useMemo } from 'react'
+import React, { useEffect, useMemo, useState } from 'react'
 import useSwr from 'swr'
-import { usePagination } from '.'
+import { PaginationData, usePagination } from '.'
 
-export interface UsePaginationDocsProps {
+export interface UsePaginationDocsProps<T = void> {
   /** The total number of items, if know when initializing, use setTotalItems if not */
-  totalItems: number
+  totalItems?: number
   /** The page to start on */
-  startPage: number
+  startPage?: number
   /** The size of each page */
-  pageSize: number
+  pageSize?: number
+  /** A function called with the pagination data on data change to prepare the returned `query` object, this is memoed for you */
+  queryCallback?: (data: PaginationData) => T
 }
 
 /**
@@ -120,17 +122,26 @@ type User = {
 }
 
 export const ServerSide: Story = () => {
-  const { page, pageSize, totalPages, setPage, setTotalItems, setPageSize } =
-    usePagination()
+  const {
+    page,
+    pageSize,
+    totalPages,
+    query,
+    setPage,
+    setTotalItems,
+    setPageSize,
+  } = usePagination({
+    queryCallback: ({ page, pageSize }) => `page=${page}&per_page=${pageSize}`,
+  })
 
   const { data } = useSwr(
-    ['https://gorest.co.in/public/v2/users', page, pageSize],
-    async ([url, page, pageSize]) => {
-      const res = await fetch(`${url}?page=${page - 1}&per_page=${pageSize}`)
+    ['https://gorest.co.in/public/v2/users', query],
+    async ([url, query]) => {
+      const res = await fetch(`${url}?${query}`)
 
       const users = (await res.json()) as User[]
       const totalItems = Number(res.headers.get('x-pagination-total'))
-
+      setTotalItems(totalItems)
       return {
         users,
         totalItems,
@@ -139,16 +150,6 @@ export const ServerSide: Story = () => {
     { refreshInterval: 0, shouldRetryOnError: false }
   )
 
-  const users = useMemo(() => {
-    return data?.users ?? []
-  }, [data])
-
-  useEffect(() => {
-    if (data?.totalItems) {
-      setTotalItems(data.totalItems)
-    }
-  }, [data])
-
   return (
     <Column css={{ gap: '$3' }}>
       <Pagination page={page} onPageChange={setPage} count={totalPages} />
@@ -158,7 +159,7 @@ export const ServerSide: Story = () => {
         onValueChange={(value) => setPageSize(value[0])}
       />
       <div>
-        {users.map((item) => (
+        {(data?.users ?? []).map((item) => (
           <div>{item.name}</div>
         ))}
       </div>

src/usePagination/usePagination.test.ts

@@ -1,5 +1,5 @@
 import { act, renderHook } from '@testing-library/react-hooks'
-import { usePagination } from './usePagination'
+import { PaginationData, usePagination } from './usePagination'
 
 test('should start in given state', () => {
   const { result } = renderHook(() => usePagination())
@@ -132,3 +132,35 @@ test('can set total items', () => {
   expect(result.current.page).toBe(10)
   expect(result.current.totalPages).toBe(20)
 })
+
+test('can update query', () => {
+  const queryCallback = ({ pageSize, startIndex }: PaginationData) => ({
+    take: pageSize,
+    skip: startIndex,
+  })
+  const { result, rerender } = renderHook(() =>
+    usePagination({
+      totalItems: 100,
+      pageSize: 10,
+      queryCallback,
+    })
+  )
+
+  expect(result.current.query).toStrictEqual({ take: 10, skip: 0 })
+
+  act(() => {
+    result.current.setPage(3)
+  })
+
+  const previous = result.current.query
+  expect(previous).toStrictEqual({ take: 10, skip: 20 })
+
+  // check rerender does not change the query
+  rerender({
+    totalItems: 100,
+    pageSize: 10,
+    queryCallback,
+  })
+
+  expect(result.current.query).toBe(previous)
+})

src/usePagination/usePagination.ts

@@ -1,20 +1,6 @@
 import { useCallback, useEffect, useMemo, useState } from 'react'
 
-/**
- * Utility hook for handling pagination state
- *
- * returns the current page and functions to manipulate.
- *
- */
-export function usePagination({
-  totalItems: startTotalItems = 0,
-  page: startPage = 1,
-  pageSize: startPageSize = 20,
-}: Partial<{
-  totalItems: number
-  page: number
-  pageSize: number
-}> = {}): {
+export interface PaginationData {
   /** The current page */
   page: number
   /** The total number of pages */
@@ -29,6 +15,26 @@ export function usePagination({
   isPreviousDisabled: boolean
   /** The page size */
   pageSize: number
+}
+
+/**
+ * Utility hook for handling pagination state
+ *
+ * returns the current page and functions to manipulate.
+ *
+ */
+export function usePagination<T = void>({
+  totalItems: startTotalItems = 0,
+  pageSize: startPageSize = 20,
+  page: startPage = 1,
+  queryCallback = () => undefined as T,
+}: Partial<{
+  totalItems: number
+  pageSize: number
+  page: number
+  queryCallback: (data: PaginationData) => T
+}> = {}): PaginationData & {
+  query: T
   /** Set the page */
   setPage: (page: number) => void
   /** Move to the next page */
@@ -78,10 +84,43 @@ export function usePagination({
     setPage(page - 1)
   }, [page, setPage])
 
+  useEffect(() => {
+    return () => {
+      setTotalItems(startTotalItems)
+    }
+  }, [startTotalItems, setTotalItems])
+
+  useEffect(() => {
+    return () => {
+      setPageSize(startPageSize)
+    }
+  }, [startPageSize, setPageSize])
+
   useEffect(() => {
     setPageInternal((page) => Math.max(1, Math.min(page, totalPages)))
   }, [totalPages])
 
+  const query = useMemo(() => {
+    return queryCallback({
+      page,
+      pageSize,
+      totalPages,
+      startIndex,
+      endIndex,
+      isNextDisabled,
+      isPreviousDisabled,
+    })
+  }, [
+    queryCallback,
+    page,
+    pageSize,
+    totalPages,
+    startIndex,
+    endIndex,
+    isNextDisabled,
+    isPreviousDisabled,
+  ])
+
   return {
     page,
     pageSize,
@@ -90,13 +129,15 @@ export function usePagination({
     endIndex,
     isNextDisabled,
     isPreviousDisabled,
+    query,
     setPage,
     setNextPage,
     setPreviousPage,
     setPageSize,
     setTotalItems,
   }
 }
+
 function getDerivedData(totalItems: number, pageSize: number, page: number) {
   const totalPages = Math.ceil(totalItems / pageSize)
   const startIndex = pageSize * (page - 1)