feat: docs and API finalization

Author: simoneb

README.md

@@ -6,7 +6,7 @@
 [![bundlephobia](https://badgen.net/bundlephobia/minzip/token-pagination-hooks)](https://bundlephobia.com/result?p=token-pagination-hooks)
 [![bundlephobia](https://badgen.net/bundlephobia/dependency-count/token-pagination-hooks)](https://bundlephobia.com/result?p=token-pagination-hooks)
 
-React Hooks library to use classic pagination in the frontend with a token-based paginatiom backend
+React Hooks library to use classic pagination in a frontend, based on page number and page size, with a token-based paginatiom backend.
 
 <!-- toc -->
 
@@ -19,19 +19,26 @@ React Hooks library to use classic pagination in the frontend with a token-based
 
 ## Setup
 
-`npm i token-pagination-hooks`
+```bash
+npm i token-pagination-hooks
+```
 
 ## Quickstart
 
-### API
+The hook can work in `controlled` and `uncontrolled` modes, as is the React convention. See more details in the [usage](#usage) section. This example uses the controlled mode.
 
-See example API: 
+### Backend
 
 [![Edit server](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/server-0wmht?fontsize=14&hidenavigation=1&theme=dark)
 
 Assiming you're using an API which:
 
 - accepts a `pageToken` query string parameter to do pagination
+
+```bash
+GET /api?pageSize=2&pageToken=some-opaque-string
+```
+
 - returns data in the format:
 
 ```json
@@ -40,33 +47,33 @@ Assiming you're using an API which:
     "id": 1, 
     "value": "some value" 
   }],
-  "nextPage": "some opaque string"
+  "nextPage": "some-opaque-string"
 }
 ```
 
-### Client
-
-See example client:
+### Frontend
 
 [![Edit with axios-hooks](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/with-axios-hooks-u035y?fontsize=14&hidenavigation=1&theme=dark)
 
 Assuming you're using a library like [axios-hooks](https://github.com/simoneb/axios-hooks/) to interact with the API:
 
-```js
-import React, { useState } from 'react'
-import useAxios from 'axios-hooks'
-import useTokenPagination from 'token-pagination-hooks'
-
+```jsx
 function Pagination() {
+  // store pagination state
   const [pageNumber, setPageNumber] = useState(1)
+
+  // use the hook and provide the current page number
   const { currentToken, useUpdateToken, hasToken } = useTokenPagination(
     pageNumber
   )
+
+  // invoke the paginated api
   const [{ data }] = useAxios({
     url: '/api',
     params: { pageSize: 3, pageToken: currentToken }
   })
 
+  // update the token for the next page
   useUpdateToken(data?.nextPage)
 
   return (
@@ -93,3 +100,202 @@ function Pagination() {
   )
 }
 ```
+
+## Running the examples
+
+The repository contains several examples showing different usage scenarios. To run the examples:
+
+- clone the repository and cd into it
+- `npm i`
+- `npm run examples`
+- browse to `http://localhost:4000`
+
+## API
+
+```jsx
+import useTokenPagination, { 
+  localPersister, 
+  sessionPersister 
+} from 'token-pagination-hooks'
+
+const persister = localPersister('key') // OR sessionPersister('key')
+
+function Component() {
+  const result = useTokenPagination(options, persister?)
+}
+```
+
+- `options` - `number` | `object` - **Required**
+  - `number`
+  
+    Represents a page number and implies the `controlled` mode. The page number must be provided and its value reflect the current page.
+
+  - `object` 
+   
+    Implies the `uncontrolled` mode.
+
+    - `options.defaultPageNumber` - `number` - **Default: 1**
+          
+      The initial page number. The Hook will then keep its internal state.
+
+    - `options.defaultPageSize` - `number` - **Required**
+
+      The initial page size. The Hook will then keep its internal state.
+
+    - `options.resetPageNumberOnPageSizeChange` -`bool` - **Default: true**
+
+      Whether to reset the page number when the page size changes.
+
+- `persister` - `object` - **Optional**
+  
+  An optional persister to store the pagination state for later retrieval. Some persisters are provided with the library and others can be implemented by providing an object (or an instance of a class) adhering to the following interface:
+
+    - `persister.hydrate` - `() => object`
+      
+      Method that is called to read the pagination data from the persistent store.
+
+    - `persister.persist` - `object => void`
+
+      Method that is called with an object representing the pagination state and which should persist it to the persistent store for later retrieval.
+
+- `result` - `object`
+  
+  The return value of the Hook, its properties change depending on whether `controlled` or `uncontrolled` mode is used.
+
+  **Both controlled and uncontrolled**
+
+  - `result.currentToken` - `any`
+   
+    The pagination token for the requested page to provide to the API.
+  
+  - `result.useUpdateToken` - `token: any => void` 
+  
+    The Hook to invoke with the pagination token as returned by the API for declarative storage of the mapping between page numbers and tokens.
+
+  - `result.updateToken` - `token: any => void`
+
+    The function to invoke with the pagination token as returned by the API for imperative storage of the mapping between page numbers and tokens.
+
+  - `hasToken` - `pageNumber: number => bool`
+  
+    A function which can be invoked with a page number to check if there is a pagination token for that page. Useful to conditionally enable pagination buttons (see examples).
+
+  **Uncontrolled only**
+
+  - `result.pageNumber` - `number`
+  
+    The current page number.
+
+  - `result.pageSize` - `number`
+  
+    The current page size.
+
+  - `result.changePageNumber(changer)`
+
+    A function to change the page number. Changer is either a number, which will be the new page number, or a function, which gets the current page number as its first argument and returns the new page number.
+
+    `changer`:
+
+    - `pageNumber: number`
+    - `(previousPageNumber: number) => newPageNumber: number`
+
+  - `result.changePageSize(changer)`
+
+    A function to change the page size. Changer is either a number, which will be the new page size, or a function, which gets the current page size as its first argument and returns the new page size.
+
+    `changer`:
+
+    - `pageNumber: number`
+    - `(previousPageSize: number) => newPageSize: number`
+  
+    
+## Usage
+
+### Token update
+
+The Hook provides two ways to update the mapping between a page number and the token used to paginate from the current page to the next: a declarative one based on a React Hook and an imperative one based on a plain function.
+
+#### Declarative
+
+The declarative approach is based on React Hooks and it's useful when you're invoking an API via a React Hook, as when using [`axios-hooks`](https://github.com/simoneb/axios-hooks/), [`graphql-hooks`](https://github.com/nearform/graphql-hooks) or one of the many other Hook-based libraries available.
+
+```jsx
+const { useUpdateToken } = useTokenPagination(...)
+
+// invoke your API which returns the token for the next page, e.g.
+const { data, nextPage } = useYourApi()
+
+// update the token for the next page using the Hook
+useUpdateToken(nextPage)
+```
+
+#### Imperative
+
+The imperative approach is useful when you invoke your API imperatively, for instance using `fetch` in a `useEffect` Hook:
+
+```jsx
+const { currentToken, updateToken } = useTokenPagination(...)
+
+useEffect(() => {
+  async function fetchData() {
+    const params = new URLSearchParams({ pageToken: currentToken })
+
+    const res = await fetch(`/api?${params.toString()}`)
+    const data = await res.json()
+
+    // update the token imperatively when the API responds
+    updateToken(data.nextPage)
+  }
+
+  fetchData()
+}, [currentToken, updateToken])
+```
+
+### Modes
+
+The hook can be used in `controlled` and `uncontrolled` mode. 
+
+#### Controlled
+
+When in controlled mode, you are responsible for keeping the pagination state (page number, page size) and providing the necessary data to the Hook.
+
+To work in controlled mode, you provide a numeric page number as the first argument to the Hook:
+
+```js
+// you are responsible for storing the pagination state
+const [pageNumber, setPageNumber] = useState(1)
+
+// you provide the current page number to the hook
+const { useUpdateToken } = useTokenPagination(pageNumber)
+
+// invoke your API which returns the token for the next page, e.g.
+const { data, nextPage } = useYourApi()
+
+// inform the hook of the token to take you from the current page to the next
+useUpdateToken(nextPage)
+```
+
+#### Uncontrolled
+
+When in uncontrolled mode, the hook keeps its internal pagination state and provides way to read and modify it.
+
+To work in uncontrolled mode, you provide an object containing a default page number and a default page size:
+
+```jsx
+// you provide default values and the hook keeps its internal state
+const {
+  useUpdateToken,
+  pageNumber,
+  pageSize,
+} = useTokenPagination({ defaultPageNumber: 1, defaultPageSize: 5 })
+
+
+// invoke your API which returns the token for the next page, e.g.
+const { data, nextPage } = useYourApi()
+
+// inform  the hook of the token to take you from the current page to the next
+useUpdateToken(nextPage)
+```
+
+
+

examples/components/Persistence.js

@@ -9,11 +9,13 @@ function Persistence() {
     changePageSize,
     pageNumber,
     pageSize,
-  } = useTokenPagination({
-    defaultPageNumber: 1,
-    defaultPageSize: 5,
-    persister: useTokenPagination.localPersister('persistence'),
-  })
+  } = useTokenPagination(
+    {
+      defaultPageNumber: 1,
+      defaultPageSize: 5,
+    },
+    useTokenPagination.sessionPersister('persistence')
+  )
   const [data, setData] = useState()
 
   useEffect(() => {

examples/index.html

@@ -2,7 +2,7 @@
 <html>
   <head>
     <meta charset="utf-8" />
-    <title>Example</title>
+    <title>Examples - token-pagination-hooks</title>
     <script src="https://unpkg.com/react@17/umd/react.development.js"></script>
     <script src="https://unpkg.com/react-dom@17/umd/react-dom.development.js"></script>
     <script src="https://unpkg.com/prop-types@15/prop-types.js"></script>

src/controlled.js

@@ -2,17 +2,14 @@ import { useCallback, useEffect, useState, useMemo } from 'react'
 import { NULL_PERSISTER } from './persisters'
 import { assertNumber } from './utils'
 
-const DEFAULTS = {
-  persister: NULL_PERSISTER,
-}
-
-export default function useControlledTokenPagination(pageNumber, options) {
-  options = { ...DEFAULTS, ...options }
-
+export default function useControlledTokenPagination(
+  pageNumber,
+  persister = NULL_PERSISTER
+) {
   assertNumber('pageNumber', pageNumber)
 
   const [mapping, setMapping] = useState(() => {
-    const { mapping } = options.persister.hydrate()
+    const { mapping } = persister.hydrate()
     return mapping || {}
   })
 
@@ -34,8 +31,8 @@ export default function useControlledTokenPagination(pageNumber, options) {
   )
 
   useEffect(() => {
-    options.persister.persist({ mapping })
-  }, [options.persister, mapping])
+    persister.persist({ mapping })
+  }, [persister, mapping])
 
   return useMemo(
     () => ({

src/index.js

@@ -7,14 +7,14 @@ const variants = {
   object: useUncontrolledTokenPagination,
 }
 
-export default function useTokenPagination(options) {
+export default function useTokenPagination(options, persister) {
   const variant = variants[typeof options]
 
   if (!variant) {
     throw new Error(`Unsupported options ${options} of type ${typeof options}`)
   }
 
-  return variant(options)
+  return variant(options, persister)
 }
 
 Object.assign(useTokenPagination, persisters)

src/index.test.js

@@ -12,15 +12,15 @@ describe('useTokenPagination', () => {
     const { result } = renderHook(() => useTokenPagination(1))
 
     expect(result.current).toBe('controlled')
-    expect(controlled).toHaveBeenCalledWith(1)
+    expect(controlled).toHaveBeenCalledWith(1, undefined)
   })
 
   it('returns uncontrolled when an object is provided', async () => {
     const arg = {}
     const { result } = renderHook(() => useTokenPagination(arg))
 
     expect(result.current).toBe('uncontrolled')
-    expect(uncontrolled).toHaveBeenCalledWith(arg)
+    expect(uncontrolled).toHaveBeenCalledWith(arg, undefined)
   })
 
   it('throws when an unknown input type is provided', async () => {

src/uncontrolled.js

@@ -6,19 +6,21 @@ import { assertNumber } from './utils'
 const DEFAULTS = {
   defaultPageNumber: 1,
   resetPageNumberOnPageSizeChange: true,
-  persister: NULL_PERSISTER,
 }
 
 const changerTypes = ['function', 'number']
 
-export default function useUncontrolledTokenPagination(options) {
+export default function useUncontrolledTokenPagination(
+  options,
+  persister = NULL_PERSISTER
+) {
   options = { ...DEFAULTS, ...options }
 
   assertNumber('defaultPageNumber', options.defaultPageNumber)
   assertNumber('defaultPageSize', options.defaultPageSize)
 
   const [{ pageNumber, pageSize }, setPagination] = useState(() => {
-    const { pageNumber, pageSize } = options.persister.hydrate()
+    const { pageNumber, pageSize } = persister.hydrate()
 
     return {
       pageNumber: pageNumber || options.defaultPageNumber,
@@ -57,11 +59,11 @@ export default function useUncontrolledTokenPagination(options) {
     change,
   ])
 
-  const controlled = useControlledTokenPagination(pageNumber, options)
+  const controlled = useControlledTokenPagination(pageNumber, persister)
 
   useEffect(() => {
-    options.persister.persist({ pageNumber, pageSize })
-  }, [options.persister, pageNumber, pageSize])
+    persister.persist({ pageNumber, pageSize })
+  }, [persister, pageNumber, pageSize])
 
   return useMemo(
     () => ({