@openmrs/esm-react-utils 5.8.1-pre.2249 → 5.8.1-pre.2255

package/mock.tsx

@@ -6,8 +6,12 @@ import { createGlobalStore } from '@openmrs/esm-state/mock';
 import {
   isDesktop as realIsDesktop,
   usePagination as realUsePagination,
-  useServerPagination as realUseServerPagination,
-  useServerInfinite as realUseServerInfinite,
+  useOpenmrsPagination as realUseOpenmrsrPagination,
+  useOpenmrsInfinite as realUseOpenmrsInfinite,
+  useOpenmrsFetchAll as realUseOpenmrsFetchAll,
+  useFhirPagination as realUseFhirPagination,
+  useFhirInfinite as realUseFhirInfinite,
+  useFhirFetchAll as realUseFhirFetchAll,
 } from './src/index';
 export { ConfigurableLink, useStore, useStoreWithActions, createUseStore } from './src/index';
 import * as utils from '@openmrs/esm-utils';
@@ -71,9 +75,12 @@ export const useFeatureFlag = jest.fn().mockReturnValue(true);
 
 export const usePagination = jest.fn(realUsePagination);
 
-export const useServerPagination = jest.fn(realUseServerPagination);
-
-export const useServerInfinite = jest.fn(realUseServerInfinite);
+export const useOpenmrsPagination = jest.fn(realUseOpenmrsrPagination);
+export const useOpenmrsInfinite = jest.fn(realUseOpenmrsInfinite);
+export const useOpenmrsFetchAll = jest.fn(realUseOpenmrsFetchAll);
+export const useFhirPagination = jest.fn(realUseFhirPagination);
+export const useFhirInfinite = jest.fn(realUseFhirInfinite);
+export const useFhirFetchAll = jest.fn(realUseFhirFetchAll);
 
 export const useVisit = jest.fn().mockReturnValue({
   error: null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-react-utils",
-  "version": "5.8.1-pre.2249",
+  "version": "5.8.1-pre.2255",
   "license": "MPL-2.0",
   "description": "React utilities for OpenMRS.",
   "browser": "dist/openmrs-esm-react-utils.js",
@@ -61,15 +61,15 @@
     "swr": "2.x"
   },
   "devDependencies": {
-    "@openmrs/esm-api": "5.8.1-pre.2249",
-    "@openmrs/esm-config": "5.8.1-pre.2249",
-    "@openmrs/esm-context": "5.8.1-pre.2249",
-    "@openmrs/esm-error-handling": "5.8.1-pre.2249",
-    "@openmrs/esm-extensions": "5.8.1-pre.2249",
-    "@openmrs/esm-feature-flags": "5.8.1-pre.2249",
-    "@openmrs/esm-globals": "5.8.1-pre.2249",
-    "@openmrs/esm-navigation": "5.8.1-pre.2249",
-    "@openmrs/esm-utils": "5.8.1-pre.2249",
+    "@openmrs/esm-api": "5.8.1-pre.2255",
+    "@openmrs/esm-config": "5.8.1-pre.2255",
+    "@openmrs/esm-context": "5.8.1-pre.2255",
+    "@openmrs/esm-error-handling": "5.8.1-pre.2255",
+    "@openmrs/esm-extensions": "5.8.1-pre.2255",
+    "@openmrs/esm-feature-flags": "5.8.1-pre.2255",
+    "@openmrs/esm-globals": "5.8.1-pre.2255",
+    "@openmrs/esm-navigation": "5.8.1-pre.2255",
+    "@openmrs/esm-utils": "5.8.1-pre.2255",
     "dayjs": "^1.10.8",
     "i18next": "^21.10.0",
     "react": "^18.1.0",

package/src/index.ts

@@ -35,5 +35,9 @@ export * from './useVisit';
 export * from './useVisitTypes';
 export * from './usePagination';
 export * from './usePrimaryIdentifierResource';
-export * from './useServerPagination';
-export * from './useServerInfinite';
+export * from './useFhirPagination';
+export * from './useFhirInfinite';
+export * from './useFhirFetchAll';
+export { useOpenmrsPagination, type UseServerPaginationOptions } from './useOpenmrsPagination';
+export { useOpenmrsInfinite, type UseServerInfiniteOptions } from './useOpenmrsInfinite';
+export { useOpenmrsFetchAll, type UseServerFetchAllOptions } from './useOpenmrsFetchAll';

package/src/public.ts

@@ -31,5 +31,9 @@ export * from './useVisit';
 export * from './useVisitTypes';
 export * from './usePagination';
 export * from './usePrimaryIdentifierResource';
-export * from './useServerPagination';
-export * from './useServerInfinite';
+export * from './useFhirPagination';
+export * from './useFhirInfinite';
+export * from './useFhirFetchAll';
+export { useOpenmrsPagination, type UseServerPaginationOptions } from './useOpenmrsPagination';
+export { useOpenmrsInfinite, type UseServerInfiniteOptions } from './useOpenmrsInfinite';
+export { useOpenmrsFetchAll, type UseServerFetchAllOptions } from './useOpenmrsFetchAll';

package/src/useFhirFetchAll.ts

@@ -0,0 +1,24 @@
+import { type UseServerInfiniteReturnObject } from './useOpenmrsInfinite';
+import { getFhirServerPaginationHandlers } from './useFhirPagination';
+import { useServerFetchAll, type UseServerFetchAllOptions } from './useOpenmrsFetchAll';
+
+/**
+ * This hook handles fetching results from *all* pages of a paginated FHIR REST endpoint, making multiple requests
+ * as needed.
+ * This function is the FHIR counterpart of `useOpenmrsPagination`.
+ *
+ * @see `useFhirPagination`
+ * @see `useFhirInfinite`
+ * @see `useOpenmrsFetchAll``
+ *
+ * @param url The URL of the paginated rest endpoint.
+ *            Similar to useSWRInfinite, this param can be null to disable fetching.
+ * @param options The options object
+ * @returns a UseFhirInfiniteReturnObject object
+ */
+export function useFhirFetchAll<T extends fhir.ResourceBase>(
+  url,
+  options: UseServerFetchAllOptions<fhir.Bundle> = {},
+): UseServerInfiniteReturnObject<T, fhir.Bundle> {
+  return useServerFetchAll<T, fhir.Bundle>(url, getFhirServerPaginationHandlers(), options);
+}

package/src/useFhirInfinite.ts

@@ -0,0 +1,29 @@
+import { getFhirServerPaginationHandlers } from './useFhirPagination';
+import {
+  useServerInfinite,
+  type UseServerInfiniteOptions,
+  type UseServerInfiniteReturnObject,
+} from './useOpenmrsInfinite';
+
+/**
+ * Fhir REST endpoints that return a list of objects, are server-side paginated.
+ * The server limits the max number of results being returned, and multiple requests are needed to get the full data set
+ * if its size exceeds this limit.
+ *
+ * This function is the FHIR counterpart of `useOpenmrsInfinite`.
+ *
+ * @see `useFhirPagination`
+ * @see `useFhirFetchAll`
+ * @see `useOpenmrsInfinite`
+ *
+ * @param url The URL of the paginated rest endpoint.
+ *            Similar to useSWRInfinite, this param can be null to disable fetching.
+ * @param options The options object
+ * @returns a UseServerInfiniteReturnObject object
+ */
+export function useFhirInfinite<T extends fhir.ResourceBase>(
+  url: string | URL,
+  options: UseServerInfiniteOptions<fhir.Bundle> = {},
+): UseServerInfiniteReturnObject<T, fhir.Bundle> {
+  return useServerInfinite<T, fhir.Bundle>(url, getFhirServerPaginationHandlers(), options);
+}

package/src/useFhirPagination.ts

@@ -0,0 +1,66 @@
+/** @module @category UI */
+import { type FetchResponse, makeUrl, openmrsFetch } from '@openmrs/esm-api';
+import {
+  type ServerPaginationHandlers,
+  useServerPagination,
+  type UseServerPaginationOptions,
+} from './useOpenmrsPagination';
+
+/**
+ * Fhir REST endpoints that return a list of objects, are server-side paginated.
+ * The server limits the max number of results being returned, and multiple requests are needed to get the full data set
+ * if its size exceeds this limit.
+ *
+ * This function is the FHIR counterpart of `useOpenmrsPagination`.
+ *
+ * @see `useOpenmrsPagination
+ * @see `useFhirInfinite`
+ * @see `useFhirFetchAll`
+ * @see `usePagination` for pagination of client-side data`
+ *
+ * @param url The URL of the paginated rest endpoint.
+ *            which will be overridden and manipulated by the `goTo*` callbacks
+ * @param pageSize The number of results to return per page / fetch.
+ * @param options The options object
+ * @returns
+ */
+export function useFhirPagination<T extends fhir.ResourceBase>(
+  url: string | URL,
+  pageSize: number,
+  options: UseServerPaginationOptions<fhir.Bundle> = {},
+) {
+  return useServerPagination<T, fhir.Bundle>(url, pageSize, getFhirServerPaginationHandlers<T>(), options);
+}
+
+type FhirServerPaginationHandlers<T> = ServerPaginationHandlers<T, fhir.Bundle>;
+export function getFhirServerPaginationHandlers<T>(): FhirServerPaginationHandlers<T> {
+  return {
+    getPaginatedUrl: (url: string | URL, limit: number, startIndex: number) => {
+      if (url) {
+        const urlUrl = new URL(makeUrl(url.toString()), window.location.toString());
+        urlUrl.searchParams.set('_count', '' + limit);
+        urlUrl.searchParams.set('_getpagesoffset', '' + startIndex);
+        return urlUrl.toString();
+      } else {
+        return null;
+      }
+    },
+    getNextUrl: (response) => {
+      const uri = response?.link?.find((link) => link.relation == 'next')?.url;
+      if (uri) {
+        const url = new URL(uri);
+
+        // allows frontend proxies to work
+        url.host = window.location.host;
+        url.protocol = window.location.protocol;
+
+        return url.toString();
+      } else {
+        return null;
+      }
+    },
+    getTotalCount: (response) => response?.total ?? Number.NaN,
+    getCurrentPageSize: (response) => response?.entry?.length ?? Number.NaN,
+    getData: (response) => response?.entry?.map((entry) => entry.resource) as T[],
+  };
+}

package/src/useOpenmrsFetchAll.test.tsx

@@ -0,0 +1,55 @@
+import { renderHook, cleanup, waitFor, act } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { useOpenmrsFetchAll } from './useOpenmrsFetchAll';
+import { type OpenMRSPaginatedResponse } from './useOpenmrsPagination';
+
+// returns an sequentially increasing int array of specified length starting at the specified start integer.
+export function getIntArray(start: number, length: number) {
+  return new Array(length).fill(0).map((_, i) => start + i);
+}
+
+// This function mocks the return value of a server-side paginated API.
+// It returns a slice (page) of the array of integers [0...totalCount-1],
+// with the page defined  by the limit and startIndex in the url params.
+export async function getTestData(url: string, totalCount: number): Promise<OpenMRSPaginatedResponse<number>> {
+  const urlUrl = new URL(url, window.location.toString());
+  const limit = Number.parseInt(urlUrl.searchParams.get('limit') ?? '50');
+  const startIndex = Number.parseInt(urlUrl.searchParams.get('startIndex') ?? '0');
+
+  const length = Math.max(0, Math.min(totalCount - startIndex, limit));
+  const results = new Array(length).fill(0).map((_, i) => i + startIndex);
+  const hasNext = startIndex + limit < totalCount;
+  if (hasNext) {
+    urlUrl.searchParams.set('startIndex', startIndex + limit + '');
+  }
+  const links = hasNext ? [{ rel: 'next', uri: urlUrl.toString() }] : [];
+  return { results, links, totalCount } as OpenMRSPaginatedResponse<number>;
+}
+
+describe('useOpenmrsFetchAll', () => {
+  afterEach(cleanup);
+
+  it('should render all rows on if number of rows < pageSize', async () => {
+    const expectedRowCount = 17;
+    const { result } = renderHook(() =>
+      useOpenmrsFetchAll(`http://localhost/1`, {
+        fetcher: (url) => getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
+      }),
+    );
+    await waitFor(() => expect(result.current.isLoading).toBeFalsy());
+    expect(result.current.totalCount).toEqual(expectedRowCount);
+    expect(result.current.data).toEqual(getIntArray(0, 17));
+  });
+
+  it('should render all rows on if number of rows > pageSize with no partialData', async () => {
+    const expectedRowCount = 75;
+    const { result } = renderHook(() =>
+      useOpenmrsFetchAll(`http://localhost/2`, {
+        fetcher: (url) => getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
+      }),
+    );
+    await waitFor(() => expect(result.current.isLoading).toBeFalsy());
+    expect(result.current.totalCount).toEqual(expectedRowCount);
+    expect(result.current.data).toEqual(getIntArray(0, 75));
+  });
+});

package/src/useOpenmrsFetchAll.ts

@@ -0,0 +1,70 @@
+/** @module @category UI */
+import { useEffect } from 'react';
+import {
+  useServerInfinite,
+  type UseServerInfiniteOptions,
+  type UseServerInfiniteReturnObject,
+} from './useOpenmrsInfinite';
+import {
+  type OpenMRSPaginatedResponse,
+  openmrsServerPaginationHandlers,
+  type ServerPaginationHandlers,
+} from './useOpenmrsPagination';
+
+export interface UseServerFetchAllOptions<R> extends UseServerInfiniteOptions<R> {
+  /**
+   * If true, the data of any page is returned as soon as they are fetched.
+   * This is useful when you want to display data as soon as possible, even if not all pages are fetched.
+   * If false, the returned data will be undefined until all pages are fetched. This is useful when you want to
+   * display all data at once or reduce the number of re-renders (to avoid confusing users).
+   */
+  partialData?: boolean;
+}
+
+/**
+ * Most OpenMRS REST endpoints that return a list of objects, such as getAll or search, are server-side paginated.
+ * This hook handles fetching results from *all* pages of a paginated OpenMRS REST endpoint, making multiple requests
+ * as needed.
+ *
+ * @see `useOpenmrsPagination`
+ * @see `useOpenmrsInfinite`
+ * @see `useFhirFetchAll`
+ *
+ * @param url The URL of the paginated OpenMRS REST endpoint. Note that the `limit` GET param can be set to specify
+ *            the page size; if not set, the page size defaults to the `webservices.rest.maxResultsDefault` value defined
+ *            server-side.
+ *            Similar to useSWRInfinite, this param can be null to disable fetching.
+ * @param options The options object
+ * @returns a UseOpenmrsInfiniteReturnObject object
+ */
+export function useOpenmrsFetchAll<T>(
+  url: string | URL,
+  options: UseServerFetchAllOptions<OpenMRSPaginatedResponse<T>> = {},
+): UseServerInfiniteReturnObject<T, OpenMRSPaginatedResponse<T>> {
+  return useServerFetchAll<T, OpenMRSPaginatedResponse<T>>(url, openmrsServerPaginationHandlers, options);
+}
+
+export function useServerFetchAll<T, R>(
+  url: string | URL,
+  serverPaginationHandlers: ServerPaginationHandlers<T, R>,
+  options: UseServerFetchAllOptions<R> = {},
+): UseServerInfiniteReturnObject<T, R> {
+  const response = useServerInfinite<T, R>(url, serverPaginationHandlers, options);
+  const { hasMore, error, data, loadMore, isLoading } = response;
+
+  useEffect(() => {
+    if (hasMore && !error) {
+      loadMore();
+    }
+  });
+
+  if (options.partialData) {
+    return response;
+  } else {
+    return {
+      ...response,
+      data: hasMore || error ? undefined : data,
+      isLoading: isLoading || hasMore,
+    };
+  }
+}

package/src/{useServerInfinite.test.tsx → useOpenmrsInfinite.test.tsx}

@@ -1,19 +1,20 @@
 import '@testing-library/jest-dom';
 import { act, cleanup, renderHook, waitFor } from '@testing-library/react';
-import { useServerInfinite } from './useServerInfinite';
-import { getIntArray, getTestData } from './useServerPagination.test';
+import { useOpenmrsInfinite } from './useOpenmrsInfinite';
+import { getIntArray, getTestData } from './useOpenmrsPagination.test';
 
-describe('useServerInfinite', () => {
+describe('useOpenmrsInfinite', () => {
   afterEach(cleanup);
 
   it('should load all rows with 1 fetch if number of rows < pageSize', async () => {
     const pageSize = 20;
     const expectedRowCount = 17;
     const { result } = renderHook(() =>
-      useServerInfinite(`/1?limit=${pageSize}`, (url) =>
-        getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
-      ),
+      useOpenmrsInfinite(`http://localhost/1?limit=${pageSize}`, {
+        fetcher: (url) => getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
+      }),
     );
+
     await waitFor(() => expect(result.current.isLoading).toBeFalsy());
 
     expect(result.current.data?.length).toBe(expectedRowCount);
@@ -26,9 +27,9 @@ describe('useServerInfinite', () => {
     const pageSize = 20;
     const expectedRowCount = 40;
     const { result } = renderHook(() =>
-      useServerInfinite(`/2?limit=${pageSize}`, (url) =>
-        getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
-      ),
+      useOpenmrsInfinite(`http://localhost/2?limit=${pageSize}`, {
+        fetcher: (url) => getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
+      }),
     );
 
     await waitFor(() => expect(result.current.isLoading).toBeFalsy());
@@ -51,9 +52,9 @@ describe('useServerInfinite', () => {
     const pageSize = 100;
     const expectedRowCount = 1337;
     const { result } = renderHook(() =>
-      useServerInfinite(`/3?limit=${pageSize}`, (url) =>
-        getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
-      ),
+      useOpenmrsInfinite(`http://localhost/3?limit=${pageSize}`, {
+        fetcher: (url) => getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
+      }),
     );
     await waitFor(() => expect(result.current.isLoading).toBeFalsy());
 

package/src/useOpenmrsInfinite.ts

@@ -0,0 +1,152 @@
+/** @module @category UI */
+import { type FetchResponse, openmrsFetch } from '@openmrs/esm-api';
+import { useCallback } from 'react';
+import { type KeyedMutator } from 'swr';
+import useSWRInfinite, { type SWRInfiniteConfiguration, type SWRInfiniteResponse } from 'swr/infinite';
+import {
+  openmrsServerPaginationHandlers,
+  type ServerPaginationHandlers,
+  type OpenMRSPaginatedResponse,
+} from './useOpenmrsPagination';
+
+// "swr/infinite" doesn't export InfiniteKeyedMutator directly
+type InfiniteKeyedMutator<T> = SWRInfiniteResponse<T extends (infer I)[] ? I : T>['mutate'];
+
+export interface UseServerInfiniteOptions<R> {
+  /**
+   * The fetcher to use. Defaults to openmrsFetch
+   */
+  fetcher?: (key: string) => Promise<FetchResponse<R>>;
+
+  /**
+   * If true, sets these options in swrInfintieConfig to false:
+   * revalidateIfStale, revalidateOnFocus, revalidateOnReconnect
+   * This should be the counterpart of using useSWRImmutable` for `useSWRInfinite`
+   */
+  immutable?: boolean;
+
+  swrInfiniteConfig?: SWRInfiniteConfiguration;
+}
+
+export interface UseServerInfiniteReturnObject<T, R> {
+  /**
+   * The data fetched from the server so far. Note that this array contains
+   * the aggregate of data from all fetched pages. Unless hasMore == false,
+   * this array does not contain the complete data set.
+   */
+  data: T[] | undefined;
+
+  /**
+   * The total number of rows in the data set.
+   */
+  totalCount: number | undefined;
+
+  /**
+   * Whether there are more results in the data set that have not been fetched yet.
+   */
+  hasMore: boolean;
+
+  /**
+   * callback function to make another fetch of next page's data set.
+   */
+  loadMore: () => void;
+
+  /**
+   * from useSWRInfinite
+   */
+  error: any;
+
+  /**
+   * from useSWRInfinite
+   */
+  mutate: InfiniteKeyedMutator<FetchResponse<R>[]>;
+
+  /**
+   * from useSWRInfinite
+   */
+  isValidating: boolean;
+
+  /**
+   * from useSWRInfinite
+   */
+  isLoading: boolean;
+}
+
+/**
+ * Most REST endpoints that return a list of objects, such as getAll or search, are server-side paginated.
+ * The server limits the max number of results being returned, and multiple requests are needed to get the full data set
+ * if its size exceeds this limit.
+ * The max number of results per request is configurable server-side
+ * with the key "webservices.rest.maxResultsDefault". See: https://openmrs.atlassian.net/wiki/spaces/docs/pages/25469882/REST+Module
+ *
+ * This hook fetches data from a paginated rest endpoint, initially by fetching the first page of the results.
+ * It provides a callback to load data from subsequent pages as needed. This hook is intended to serve UIs that
+ * provide infinite loading / scrolling of results. Unlike `useOpenmrsPagination`, this hook does not allow random access
+ * (and lazy-loading) of any arbitrary page; rather, it fetches pages sequentially starting form the initial page, and the next page
+ * is fetched by calling `loadMore`. See: https://swr.vercel.app/docs/pagination#useswrinfinite
+ *
+ * @see `useOpenmrsPagination`
+ * @see `useOpenmrsFetchAll`
+ * @see `useFhirInfinite`
+ *
+ * @param url The URL of the paginated rest endpoint. Note that the `limit` GET param can be set to specify
+ *            the page size; if not set, the page size defaults to the `webservices.rest.maxResultsDefault` value defined
+ *            server-side.
+ *            Similar to useSWRInfinite, this param can be null to disable fetching.
+ * @param options The options object
+ * @returns a UseServerInfiniteReturnObject object
+ */
+export function useOpenmrsInfinite<T>(
+  url: string | URL,
+  options: UseServerInfiniteOptions<OpenMRSPaginatedResponse<T>> = {},
+): UseServerInfiniteReturnObject<T, OpenMRSPaginatedResponse<T>> {
+  return useServerInfinite<T, OpenMRSPaginatedResponse<T>>(url, openmrsServerPaginationHandlers, options);
+}
+
+export function useServerInfinite<T, R>(
+  url: string | URL,
+  serverPaginationHandlers: ServerPaginationHandlers<T, R>,
+  options: UseServerInfiniteOptions<R> = {},
+): UseServerInfiniteReturnObject<T, R> {
+  const { swrInfiniteConfig, immutable } = options;
+  const { getNextUrl, getTotalCount, getData } = serverPaginationHandlers;
+  const fetcher: (key: string) => Promise<FetchResponse<R>> = options.fetcher ?? openmrsFetch;
+  const getKey = useCallback(
+    (pageIndex: number, previousPageData: FetchResponse<R>) => {
+      if (pageIndex == 0) {
+        return url;
+      } else {
+        return serverPaginationHandlers.getNextUrl(previousPageData.data);
+      }
+    },
+    [url],
+  );
+
+  const { data, size, setSize, ...rest } = useSWRInfinite<FetchResponse<R>>(getKey, fetcher, {
+    ...swrInfiniteConfig,
+    // `useSWR` has a useSWRImmutable counterpart, but `useSWRInfinite` does not seem to.
+    // Setting the revalidate params manually if immutable is true, see: https://swr.vercel.app/docs/revalidation
+    ...(immutable
+      ? {
+          revalidateIfStale: false,
+          revalidateOnFocus: false,
+          revalidateOnReconnect: false,
+        }
+      : {}),
+  });
+  const nextUri = getNextUrl(data?.[data.length - 1].data);
+
+  const hasMore = nextUri != null;
+  const loadMore = () => {
+    setSize((data?.length ?? 0) + 1);
+  };
+  const totalCount = getTotalCount(data?.[0]?.data);
+
+  return {
+    data: data?.flatMap((d) => getData(d.data) as T[]),
+    totalCount,
+    hasMore,
+    loadMore,
+    ...rest,
+  };
+}

package/src/{useServerPagination.test.tsx → useOpenmrsPagination.test.tsx}

@@ -1,6 +1,6 @@
 import { renderHook, cleanup, waitFor, act } from '@testing-library/react';
 import '@testing-library/jest-dom';
-import { useServerPagination, type OpenMRSPaginatedResponse } from './useServerPagination';
+import { useOpenmrsPagination, type OpenMRSPaginatedResponse } from './useOpenmrsPagination';
 
 // returns an sequentially increasing int array of specified length starting at the specified start integer.
 export function getIntArray(start: number, length: number) {
@@ -25,16 +25,26 @@ export async function getTestData(url: string, totalCount: number): Promise<Open
   return { results, links, totalCount } as OpenMRSPaginatedResponse<number>;
 }
 
-describe('useServerPagination', () => {
+describe('useOpenmrsPagination', () => {
   afterEach(cleanup);
 
-  it('should render all rows on 1 page if number of rows < pageSize', async () => {
+  it('should not fetch anything if url is null', async () => {
+    const { result } = renderHook(() =>
+      useOpenmrsPagination(null as any, 50, {
+        fetcher: (url) => getTestData(url, 100).then((data) => ({ data }) as any),
+      }),
+    );
+    expect(result.current.isLoading).toBeFalsy();
+    expect(result.current.data).toBeUndefined();
+  });
+
+  it('should fetch all rows on 1 page if number of rows < pageSize', async () => {
     const pageSize = 20;
     const expectedRowCount = 17;
     const { result } = renderHook(() =>
-      useServerPagination('/1', pageSize, (url) =>
-        getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
-      ),
+      useOpenmrsPagination('http://localhost/1', pageSize, {
+        fetcher: (url) => getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
+      }),
     );
     await waitFor(() => expect(result.current.isLoading).toBeFalsy());
     expect(result.current.totalPages).toEqual(1);
@@ -45,13 +55,13 @@ describe('useServerPagination', () => {
     expect(result.current.data).toEqual(getIntArray(0, 17));
   });
 
-  it('should render 2 pages if pageSize < number of rows <= 2 * pageSize', async () => {
+  it('should fetch 2 pages if pageSize < number of rows <= 2 * pageSize', async () => {
     const pageSize = 20;
     const expectedRowCount = 40;
     const { result } = renderHook(() =>
-      useServerPagination('/2', pageSize, (url) =>
-        getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
-      ),
+      useOpenmrsPagination('http://localhost/2', pageSize, {
+        fetcher: (url) => getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
+      }),
     );
 
     await waitFor(() => expect(result.current.isLoading).toBeFalsy());
@@ -81,14 +91,14 @@ describe('useServerPagination', () => {
     expect(result.current.data).toEqual(getIntArray(0, 20));
   });
 
-  it('should render n pages for n >> 1', async () => {
+  it('should fetch n pages for n >> 1', async () => {
     const pageSize = 20;
     const expectedRowCount = 1337;
     const expectedTotalPages = Math.ceil(expectedRowCount / pageSize);
     const { result } = renderHook(() =>
-      useServerPagination('/3', pageSize, (url) =>
-        getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
-      ),
+      useOpenmrsPagination('http://localhost/3', pageSize, {
+        fetcher: (url) => getTestData(url, expectedRowCount).then((data) => ({ data }) as any),
+      }),
     );
 
     await waitFor(() => expect(result.current.isLoading).toBeFalsy());