@openmrs/esm-react-utils 3.3.2-pre.1184 → 3.3.2-pre.1193

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openmrs/esm-react-utils",
-  "version": "3.3.2-pre.1184",
+  "version": "3.3.2-pre.1193",
   "license": "MPL-2.0",
   "description": "React utilities for OpenMRS.",
   "browser": "dist/openmrs-esm-react-utils.js",
@@ -55,11 +55,11 @@
     "react-i18next": "11.x"
   },
   "devDependencies": {
-    "@openmrs/esm-api": "^3.3.2-pre.1184",
-    "@openmrs/esm-config": "^3.3.2-pre.1184",
-    "@openmrs/esm-error-handling": "^3.3.2-pre.1184",
-    "@openmrs/esm-extensions": "^3.3.2-pre.1184",
-    "@openmrs/esm-globals": "^3.3.2-pre.1184",
+    "@openmrs/esm-api": "^3.3.2-pre.1193",
+    "@openmrs/esm-config": "^3.3.2-pre.1193",
+    "@openmrs/esm-error-handling": "^3.3.2-pre.1193",
+    "@openmrs/esm-extensions": "^3.3.2-pre.1193",
+    "@openmrs/esm-globals": "^3.3.2-pre.1193",
     "dayjs": "^1.10.8",
     "i18next": "^19.6.0",
     "react": "^16.13.1",
@@ -68,5 +68,5 @@
     "rxjs": "^6.5.3",
     "unistore": "^3.5.2"
   },
-  "gitHead": "e111f79dfae61386b2f738291787310f8fc93f9d"
+  "gitHead": "8a30755ac68941f2b6d70373ef98126410608d24"
 }

package/src/index.ts

@@ -22,7 +22,7 @@ export * from "./useLayoutType";
 export * from "./useLocations";
 export * from "./useOnClickOutside";
 export * from "./UserHasAccess";
-export * from "./useSessionUser";
+export { useSession } from "./useSession";
 export * from "./useStore";
 export * from "./useVisit";
 export * from "./useVisitTypes";

package/src/public.ts

@@ -19,7 +19,7 @@ export * from "./useLayoutType";
 export * from "./useLocations";
 export * from "./useOnClickOutside";
 export * from "./UserHasAccess";
-export * from "./useSessionUser";
+export { useSession } from "./useSession";
 export * from "./useStore";
 export * from "./useVisit";
 export * from "./useVisitTypes";

package/src/useSession.test.tsx

@@ -0,0 +1,84 @@
+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 { createGlobalStore } from "@openmrs/esm-state";
+import { SessionStore } from "@openmrs/esm-api";
+
+const mockSessionStore = createGlobalStore<SessionStore>("mockSessionStore", {
+  loaded: false,
+  session: null,
+});
+
+jest.mock("@openmrs/esm-api", () => ({
+  getSessionStore: jest.fn(() => mockSessionStore),
+}));
+
+function Component() {
+  const session = useSession();
+  return <div>{JSON.stringify(session)}</div>;
+}
+
+describe("useSession", () => {
+  beforeEach(() => {
+    __cleanup();
+    mockSessionStore.setState({ loaded: false, session: null });
+  });
+
+  it("should suspend and then resolve to the session", async () => {
+    render(
+      <Suspense fallback={"suspended"}>
+        <Component />
+      </Suspense>
+    );
+
+    expect(screen.getByText("suspended")).toBeInTheDocument();
+    act(() => {
+      mockSessionStore.setState({
+        loaded: true,
+        session: { authenticated: false, sessionId: "test1" },
+      });
+    });
+    await screen.findByText(/"authenticated":false/);
+  });
+
+  it("should resolve immediately when the session is present", async () => {
+    mockSessionStore.setState({
+      loaded: true,
+      session: { authenticated: false, sessionId: "test2" },
+    });
+    render(
+      <Suspense fallback={"suspended"}>
+        <Component />
+      </Suspense>
+    );
+    expect(screen.getByText(/"authenticated":false/)).toBeInTheDocument();
+  });
+
+  it("should not return stale data when re-created", async () => {
+    const { unmount } = render(
+      <Suspense fallback={"suspended"}>
+        <Component />
+      </Suspense>
+    );
+    expect(screen.getByText("suspended")).toBeInTheDocument();
+    act(() => {
+      mockSessionStore.setState({
+        loaded: true,
+        session: { authenticated: true, sessionId: "test3" },
+      });
+    });
+    await screen.findByText(/"authenticated":true/);
+    unmount();
+    mockSessionStore.setState({
+      loaded: true,
+      session: { authenticated: false, sessionId: "test3" },
+    });
+    render(
+      <Suspense fallback={"suspended"}>
+        <Component />
+      </Suspense>
+    );
+    expect(screen.getByText(/"authenticated":false/)).toBeInTheDocument();
+  });
+});

package/src/useSession.tsx

@@ -0,0 +1,117 @@
+/** @module @category API */
+import { getSessionStore, Session } from "@openmrs/esm-api";
+import { useState, useEffect } from "react";
+
+let promise: undefined | Promise<Session>;
+let unsubscribe: undefined | (() => void);
+
+/**
+ * Gets the current user session information. Returns an object with
+ * property `authenticated` == `false` if the user is not logged in.
+ *
+ * Uses Suspense. This hook will always either return a Session object
+ * or throw for Suspense. It will never return `null`/`undefined`.
+ *
+ * @returns Current user session information
+ */
+export function useSession(): Session {
+  // We have two separate variables for the session.
+  //
+  // `session` is a temporary variable, which starts as `null` every time this
+  // hook is executed. It is important that we can set and return this
+  // variable synchronously, because every time we `throw` for Suspense, this
+  // hook will unmount and a new instance will be created, destroying whatever
+  // state existed. Thus, if this hook were to try to always set and return
+  // `stateSession`, it would cause an infinite loop:
+  //   1. instance A mounts
+  //   2. instance A receives value, calls `setStateSession`
+  //   3. instance A throws
+  //   4. instance A unmounts
+  //   5. instance B mounts
+  //   ...
+  // What would happen if we moved `session` to the module scope, so that it
+  // could be re-used across instances of this hook? Then we would have no way
+  // to tell whether the session was fresh.
+  //
+  // `stateSession` is React state, which is needed to update components using
+  // this hook when the session changes.
+  const [stateSession, setStateSession] = useState<Session | null>(null);
+  let session: Session | null = null;
+
+  if (!stateSession) {
+    if (!promise) {
+      // If we haven't created a promise to throw yet, do that.
+      promise = new Promise<Session>((resolve) => {
+        const handleNewSession = ({ loaded, session: newSession }) => {
+          if (loaded) {
+            resolve(newSession);
+            session = newSession;
+            unsubscribe && unsubscribe();
+            unsubscribe = undefined;
+          }
+        };
+        handleNewSession(getSessionStore().getState());
+        if (!session) {
+          unsubscribe = getSessionStore().subscribe(handleNewSession);
+        }
+      });
+    } else {
+      // However, if we have created a promise to throw, but there's no `stateSession`
+      // yet, then it's probably just this hook's first render. Check to see if
+      // there's already a session that we can return.
+      const currentState = getSessionStore().getState();
+      if (currentState.loaded) {
+        session = currentState.session;
+      }
+    }
+
+    // If the session got set synchronously in the above block, then we can just
+    // return it rather than throwing. Otherwise, throw for Suspense.
+    if (session) {
+      setStateSession(session);
+    } else {
+      throw promise;
+    }
+  }
+
+  // Once this hook is established (no longer throwing and getting re-created)
+  // we need to set up a subscription that will update its value the good
+  // old-fashioned React way.
+  useEffect(() => {
+    if (!unsubscribe) {
+      unsubscribe = getSessionStore().subscribe(
+        ({ loaded, session: newSession }) => {
+          if (loaded) {
+            session = newSession;
+            setStateSession(newSession);
+          }
+        }
+      );
+    }
+    return () => {
+      unsubscribe && unsubscribe();
+      unsubscribe = undefined;
+    };
+  }, []);
+
+  const result = stateSession || session;
+  if (!result) {
+    if (promise) {
+      console.warn(
+        "useSessionUser is in an unexpected state. Attempting to recover."
+      );
+      throw promise;
+    } else {
+      throw Error("useSessionUser is in an invalid state.");
+    }
+  }
+  return result;
+}
+
+/**
+ * For testing.
+ */
+export function __cleanup() {
+  promise = undefined;
+  unsubscribe = undefined;
+}

package/src/useSessionUser.tsx

@@ -1,17 +0,0 @@
-/** @module @category API */
-import { getCurrentUser, Session } from "@openmrs/esm-api";
-import { useState, useEffect } from "react";
-
-export function useSession() {
-  const [session, setSession] = useState<Session | null>(null);
-
-  useEffect(() => {
-    const sub = getCurrentUser({ includeAuthStatus: true }).subscribe(
-      (session) => setSession(session)
-    );
-
-    return () => sub.unsubscribe();
-  }, [setSession]);
-
-  return session;
-}