@openmrs/esm-react-utils 5.2.1-pre.1094 → 5.2.1-pre.1101

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-react-utils",
-  "version": "5.2.1-pre.1094",
+  "version": "5.2.1-pre.1101",
   "license": "MPL-2.0",
   "description": "React utilities for OpenMRS.",
   "browser": "dist/openmrs-esm-react-utils.js",
@@ -56,12 +56,12 @@
     "swr": "2.x"
   },
   "devDependencies": {
-    "@openmrs/esm-api": "^5.2.1-pre.1094",
-    "@openmrs/esm-config": "^5.2.1-pre.1094",
-    "@openmrs/esm-error-handling": "^5.2.1-pre.1094",
-    "@openmrs/esm-extensions": "^5.2.1-pre.1094",
-    "@openmrs/esm-feature-flags": "^5.2.1-pre.1094",
-    "@openmrs/esm-globals": "^5.2.1-pre.1094",
+    "@openmrs/esm-api": "^5.2.1-pre.1101",
+    "@openmrs/esm-config": "^5.2.1-pre.1101",
+    "@openmrs/esm-error-handling": "^5.2.1-pre.1101",
+    "@openmrs/esm-extensions": "^5.2.1-pre.1101",
+    "@openmrs/esm-feature-flags": "^5.2.1-pre.1101",
+    "@openmrs/esm-globals": "^5.2.1-pre.1101",
     "dayjs": "^1.10.8",
     "i18next": "^21.10.0",
     "react": "^18.1.0",
@@ -71,5 +71,5 @@
     "swr": "^2.2.2",
     "webpack": "^5.88.0"
   },
-  "gitHead": "f6f860231a56910c3b5259b0954bbfa043f76602"
+  "gitHead": "db76586824c390393c7cacffc288d22160e5a54b"
 }

package/src/index.ts

@@ -2,15 +2,17 @@ export * from "./ComponentContext";
 export * from "./ConfigurableLink";
 export * from "./Extension";
 export * from "./ExtensionSlot";
+export * from "./UserHasAccess";
 export * from "./getLifecycle";
 export * from "./openmrsComponentDecorator";
+export * from "./useAbortController";
 export * from "./useAssignedExtensions";
 export * from "./useAssignedExtensionIds";
 export * from "./useBodyScrollLock";
 export * from "./useConfig";
 export * from "./useConnectedExtensions";
 export * from "./useConnectivity";
-export * from "./usePatient";
+export * from "./useDebounce";
 export * from "./useExtensionInternalStore";
 export * from "./useExtensionSlot";
 export * from "./useExtensionSlotMeta";
@@ -20,10 +22,10 @@ export * from "./useForceUpdate";
 export * from "./useLayoutType";
 export * from "./useLocations";
 export * from "./useOnClickOutside";
-export * from "./UserHasAccess";
+export * from "./useOpenmrsSWR";
+export * from "./usePatient";
 export { useSession } from "./useSession";
 export * from "./useStore";
 export * from "./useVisit";
 export * from "./useVisitTypes";
 export * from "./usePagination";
-export * from "./useDebounce";

package/src/public.ts

@@ -2,24 +2,26 @@ export { type ExtensionData } from "./ComponentContext";
 export * from "./ConfigurableLink";
 export * from "./Extension";
 export * from "./ExtensionSlot";
+export * from "./UserHasAccess";
 export * from "./getLifecycle";
+export * from "./useAbortController";
 export * from "./useAssignedExtensions";
 export * from "./useAssignedExtensionIds";
 export * from "./useBodyScrollLock";
 export * from "./useConfig";
 export * from "./useConnectedExtensions";
 export * from "./useConnectivity";
-export * from "./usePatient";
+export * from "./useDebounce";
 export * from "./useExtensionSlotMeta";
 export * from "./useExtensionStore";
 export * from "./useFeatureFlag";
 export * from "./useLayoutType";
 export * from "./useLocations";
 export * from "./useOnClickOutside";
-export * from "./UserHasAccess";
+export * from "./useOpenmrsSWR";
+export * from "./usePatient";
 export { useSession } from "./useSession";
 export * from "./useStore";
 export * from "./useVisit";
 export * from "./useVisitTypes";
 export * from "./usePagination";
-export * from "./useDebounce";

package/src/useAbortController.test.tsx

@@ -0,0 +1,42 @@
+import { renderHook, cleanup } from "@testing-library/react";
+import "@testing-library/jest-dom/extend-expect";
+import useAbortController from "./useAbortController";
+
+describe("useAbortController", () => {
+  afterEach(cleanup);
+
+  it("returns an AbortController", () => {
+    const { result } = renderHook(() => useAbortController());
+    expect(result.current).not.toBeNull();
+  });
+
+  it("returns a consistent AbortController across re-renders", () => {
+    const { result, rerender } = renderHook(() => useAbortController());
+    const firstAc = result.current;
+
+    rerender();
+
+    expect(result.current).toBe(firstAc);
+  });
+
+  it("returns a new AbortController after the previous controller has been aborted", () => {
+    const { result, rerender } = renderHook(() => useAbortController());
+    const firstAc = result.current;
+
+    firstAc.abort();
+
+    rerender();
+
+    expect(result.current).not.toBe(firstAc);
+  });
+
+  it("aborts the AbortController when the component is unmounted", () => {
+    const { result, unmount } = renderHook(() => useAbortController());
+
+    expect(result.current.signal.aborted).toBe(false);
+
+    unmount();
+
+    expect(result.current.signal.aborted).toBe(true);
+  });
+});

package/src/useAbortController.ts

@@ -0,0 +1,40 @@
+/** @module @category Utility */
+import { useEffect, useRef } from "react";
+
+/**
+ * @beta
+ *
+ * This hook creates an AbortController that lasts either until the previous AbortController
+ * is aborted or until the component unmounts. This can be used to ensure that all fetch requests
+ * are cancelled when a component is unmounted.
+ *
+ * @example
+ * ```tsx
+ * import { useAbortController } from "@openmrs/esm-framework";
+ *
+ * function MyComponent() {
+ *  const abortController = useAbortController();
+ *  const { data } = useSWR(key, (key) => openmrsFetch(key, { signal: abortController.signal }));
+ *
+ *  return (
+ *    // render something with data
+ *  );
+ * }
+ * ```
+ */
+export function useAbortController() {
+  const abortController = useRef<AbortController>();
+
+  if (!abortController.current || abortController.current.signal.aborted) {
+    abortController.current = new AbortController();
+  }
+
+  useEffect(() => {
+    const ac = abortController.current;
+    return () => ac?.abort();
+  }, []);
+
+  return abortController.current;
+}
+
+export default useAbortController;

package/src/useDebounce.ts

@@ -1,4 +1,4 @@
-/** @module @category API */
+/** @module @category Utility */
 import { useEffect, useState } from "react";
 
 /**
@@ -8,7 +8,7 @@ import { useEffect, useState } from "react";
  *
  * @example
  * ```tsx
- * import { useDebounce } from "@openmrs/esm-react-utils";
+ * import { useDebounce } from "@openmrs/esm-framework";
  *
  * function MyComponent() {
  *   const [searchTerm, setSearchTerm] = useState('');
@@ -35,6 +35,7 @@ export function useDebounce<T>(value: T, delay: number = 300) {
     const timer = setTimeout(() => {
       setDebounceValue(value);
     }, delay);
+
     return () => {
       clearTimeout(timer);
     };

package/src/useOnClickOutside.test.tsx

@@ -1,4 +1,4 @@
-import React from "react";
+import React, { PropsWithChildren } from "react";
 import { render, fireEvent } from "@testing-library/react";
 import { useOnClickOutside } from "./useOnClickOutside";
 
@@ -8,7 +8,7 @@ describe("useOnClickOutside", () => {
 
   it("should call the handler when clicking outside", () => {
     // setup
-    const Component: React.FC = ({ children }) => {
+    const Component: React.FC<PropsWithChildren> = ({ children }) => {
       const ref = useOnClickOutside<HTMLDivElement>(handler);
       return <div ref={ref}>{children}</div>;
     };
@@ -23,11 +23,11 @@ describe("useOnClickOutside", () => {
 
   it("should not call the handler when clicking on the element", () => {
     // setup
-    const Component: React.FC = ({ children }) => {
+    const Component: React.FC<PropsWithChildren> = ({ children }) => {
       const ref = useOnClickOutside<HTMLDivElement>(handler);
       return <div ref={ref}>{children}</div>;
     };
-    const mutableRef: { current: HTMLDivElement } = { current: undefined };
+    const mutableRef: { current: HTMLDivElement | null } = { current: null };
     render(
       <Component>
         <div ref={mutableRef}></div>
@@ -35,7 +35,9 @@ describe("useOnClickOutside", () => {
     );
 
     // act
-    fireEvent.click(mutableRef.current);
+    if (mutableRef.current) {
+      fireEvent.click(mutableRef.current);
+    }
 
     // verify
     expect(handler).not.toHaveBeenCalled();
@@ -43,7 +45,7 @@ describe("useOnClickOutside", () => {
 
   it("should unregister the event listener when unmounted", () => {
     // setup
-    const Component: React.FC = ({ children }) => {
+    const Component: React.FC<PropsWithChildren> = ({ children }) => {
       const ref = useOnClickOutside<HTMLDivElement>(handler);
       return <div ref={ref}>{children}</div>;
     };

package/src/useOpenmrsSWR.ts

@@ -0,0 +1,86 @@
+/** @module @category Utility */
+import { useCallback, useMemo } from "react";
+import useSWR, { SWRConfiguration } from "swr";
+import { type FetchConfig, openmrsFetch } from "@openmrs/esm-api";
+import useAbortController from "./useAbortController";
+
+export type ArgumentsTuple = [any, ...unknown[]];
+export type Key = string | ArgumentsTuple | undefined | null;
+export type UseOpenmrsSWROptions = {
+  abortController?: AbortController;
+  fetchInit?: FetchConfig;
+  url?: string | ((key: Key) => string);
+  swrConfig?: SWRConfiguration;
+};
+
+function getUrl(key: Key, url?: string | ((key: Key) => string)): string {
+  if (url) {
+    return typeof url === "function" ? url(key) : url;
+  }
+
+  if (typeof key === "string") {
+    return key;
+  }
+
+  throw new Error(
+    `When using useOpenmrsSWR with a key that is not a string, you must provide a url() function that converts the key to a valid url. The key for this hook is ${key}.`
+  );
+}
+
+/**
+ * @beta
+ *
+ * This hook is intended to simplify using openmrsFetch in useSWR, while also ensuring that
+ * all useSWR usages properly use an abort controller, so that fetch requests are cancelled
+ * if the React component unmounts.
+ *
+ * @example
+ * ```tsx
+ * import { useOpenmrsSWR } from "@openmrs/esm-framework";
+ *
+ * function MyComponent() {
+ *  const { data } = useOpenmrsSWR(key);
+ *
+ *  return (
+ *    // render something with data
+ *  );
+ * }
+ * ```
+ *
+ * Note that if you are using a complex SWR key you must provide a url function to the options parameter,
+ * which translates the key into a URL to be sent to `openmrsFetch()`
+ *
+ * @example
+ * ```tsx
+ * import { useOpenmrsSWR } from "@openmrs/esm-framework";
+ *
+ * function MyComponent() {
+ *  const { data } = useOpenmrsSWR(['key', 'url'], { url: (key) => key[1] });
+ *
+ *  return (
+ *    // render something with data
+ *  );
+ * }
+ * ```
+ * @param key The SWR key to use
+ * @param options An object of optional parameters to provide, including a {@link FetchConfig} object
+ *   to pass to {@link openmrsFetch} or options to pass to SWR
+ */
+export function useOpenmrsSWR(key: Key, options: UseOpenmrsSWROptions = {}) {
+  const { abortController, fetchInit, url, swrConfig } = options;
+  const ac = useAbortController();
+  const abortSignal = useMemo<AbortSignal>(
+    () => fetchInit?.signal ?? abortController?.signal ?? ac.signal,
+    [abortController?.signal, fetchInit?.signal, ac.signal]
+  );
+
+  const fetcher = useCallback(
+    (key: Key) => {
+      const url_ = getUrl(key, url);
+      return openmrsFetch(url_, { ...fetchInit, signal: abortSignal });
+    },
+    [abortSignal, fetchInit, url]
+  );
+
+  return useSWR(key, fetcher, swrConfig);
+}

package/src/useSession.test.tsx

@@ -1,7 +1,7 @@
 import React, { Suspense } from "react";
 import { act, render, screen } from "@testing-library/react";
 import "@testing-library/jest-dom";
-import { useSession, __cleanup } from "./useSession.tsx";
+import { useSession, __cleanup } from "./useSession";
 import { createGlobalStore } from "@openmrs/esm-state";
 import { SessionStore } from "@openmrs/esm-api";