Update hooks documentation

Author: ABWalters

generate-reference.js

@@ -14,3 +14,4 @@ function generateReferenceDoc(inputFl, outputFl) {
 
 generateReferenceDoc('src/useAPI.js', 'website/reference/use-api.md');
 generateReferenceDoc('src/useParams.js', 'website/reference/use-params.md');
+generateReferenceDoc('src/useInfAPI.js', 'website/reference/use-inf-api.md');

src/index.js

@@ -1,2 +1,3 @@
 export { default as useAPI } from './useAPI';
 export { default as useParams } from './useParams';
+export { default as useInfAPI } from './useInfAPI';

src/useAPI.js

@@ -2,14 +2,14 @@ import { useEffect, useState } from 'react';
 import axios from 'axios';
 import hash from 'hash-object';
 
-const CancelToken = axios.CancelToken;
+const { CancelToken } = axios;
 
 /**
  * The object returned by the useAPI hook.
  * @typedef {Object} useAPIOutput
  * @property {Object|undefined} data - The data attribute from the axios response.
  * @property {Object|undefined} response - The axios response.
- * @property {Object|undefined} error - The axios error object is an error occurs.
+ * @property {Object|undefined} error - The axios error object if an error occurs.
  * @property {boolean} isLoading - Indicates if their is a pending API call.
  * @property {setDataFunc} setData - Set the response data object.
  */

src/useInfAPI.js

@@ -5,6 +5,21 @@ import { offsetPaginator, responseToData } from './utils';
 
 const { CancelToken } = axios;
 
+/**
+ * Paginator function used to alter the axios config object, in order to fetch the next page.
+ * @typedef {function} paginatorFunc
+ * @param config {Object} - Axios config object
+ * @param paginationState {Object} - Object kept internally to keep track of pagination
+ * @return output {Object[]} - Return tuple \[updatedConfig: Object, updatedPaginationState: Object\]
+ */
+
+/**
+ * Function used to extract items from the API response.
+ * @typedef {function} responseToItemsFunc
+ * @param response {Object} - Axios response object
+ * @return output {Object} - Return tuple \[items: Object[], hasMore: boolean\]
+ */
+
 /**
  * The object returned by the useInfAPI hook.
  * @typedef {Object} useInfAPIOutput
@@ -13,7 +28,7 @@ const { CancelToken } = axios;
  * @property {boolean} isLoading - Indicates if their is a pending API call for the **first** page of items.
  * @property {boolean} isPaging - Indicates if their is a pending API call for the **any** page of items.
  * @property {setItemsFunc} setItems - Set the items being kept in state
- * @property {function} fetchMore - Function called from the component in order to fetch the next page
+ * @property {responseToItemsFunc} fetchPage - Function called from the component in order to fetch the next page
  */
 
 /**
@@ -27,10 +42,14 @@ const { CancelToken } = axios;
  *
  * Allows you to pass an [axios config object](https://github.com/axios/axios#request-config), for complete control of the request being sent.
  *
+ * By default it will paginate using a query param `offset`, and assumes that the API returns an array of items.
+ *
+ * If this is not appropriate for your API, then you will need to provide your own `paginator` and `responseToItems` functions.
+ *
  * @param {string} url - URL that the API call is made to.
  * @param {Object} config={} - Axios config object passed to the axios.request method.
- * @param {function} paginator= - Function used to update the config object in order to paginate
- * @param {function} responseToItems= - Function used to extract an array of items from response object.
+ * @param {paginatorFunc} paginator=offsetPaginator - Function used to update the config object in order to paginate
+ * @param {function} responseToItems=responseToData - Function used to extract an array of items from response object.
  * @returns {useInfAPIOutput} output
  */
 function useInfAPI(
@@ -45,33 +64,42 @@ function useInfAPI(
     error: undefined,
     isLoading: true,
     isPaging: true,
-    hasMore: false
+    hasMore: false,
+    source: CancelToken.source()
   });
 
   const configHash = hash(config);
 
   const { items, paginationState } = state;
 
-  function callAPI(cancelToken, isLoading) {
+  function callAPI(isLoading) {
     const activePaginationState = isLoading ? {} : paginationState; // Reset pagination when config object changes.
     const [updatedConfig, updatedPaginationState] = paginator(config, activePaginationState);
 
-    setState({ ...state, isLoading, isPaging: true, paginationState: updatedPaginationState });
+    setState({
+      ...state,
+      isLoading,
+      isPaging: true,
+      paginationState: updatedPaginationState
+    });
     axios(url, {
       ...updatedConfig,
-      cancelToken
+      cancelToken: state.source.token
     })
       .then(response => {
         const [pageItems, hasMore] = responseToItems(response);
-        if (pageItems instanceof []) {
+        if (typeof pageItems === typeof []) {
           setState({
             ...state,
             items: items.concat(pageItems),
             error: undefined,
             isLoading: false,
             isPaging: false,
-            hasMore
+            hasMore,
+            paginationState: updatedPaginationState
           });
+        } else {
+          console.log("Warning: responseToItems didn't return an array.");
         }
       })
       .catch(error => {
@@ -83,25 +111,23 @@ function useInfAPI(
       });
   }
 
-  let source;
   useEffect(() => {
-    source = CancelToken.source();
-    callAPI(source.token, true);
+    setState({ ...state, source: CancelToken.source() });
+    callAPI(true);
     return () => {
-      source.cancel('useEffect cleanup.');
+      state.source.cancel('useEffect cleanup.');
     };
   }, [url, configHash]);
 
   const { error, isPaging, isLoading, hasMore } = state;
-
   return {
     items,
     error,
     isPaging,
     isLoading,
     hasMore,
     setItems: newItems => setState({ ...state, items: newItems }),
-    fetchPage: () => callAPI(source.token, false)
+    fetchPage: () => callAPI(false)
   };
 }
 

src/useParams.js

@@ -27,7 +27,7 @@ import debounce from 'lodash.debounce';
 /**
  * React hook to keep query parameters in state.
  *
- * Used in conjunction with the other hooks to filter and pagination API calls.
+ * Used in conjunction with the other hooks to filter and paginate APIs.
  *
  * Includes the ability the debounce an update, which is useful for delaying API calls while the user is typing.
  *