feat: add event queue (#1201)

Author: anusha-c18

src/components/EventQueue/EventQueue.tsx

@@ -0,0 +1,83 @@
+import { createContext, FC, ReactNode, useContext } from "react";
+import React from "react";
+
+export interface EventCallback<T> {
+  onSuccess: (event: T) => void;
+  onFailure: (msg: string) => void;
+  onFinish?: () => void;
+}
+
+export interface EventQueue<T> {
+  get: (operationId: string) => EventCallback<T> | undefined;
+  set: (
+    operationId: string,
+    onSuccess: (event: T) => void,
+    onFailure: (msg: string) => void,
+    onFinish?: () => void,
+  ) => void;
+  remove: (operationId: string) => void;
+}
+
+/**
+ * This provides an event queue system for managing callbacks associated with
+ * asynchronous operations (e.g., API calls) in an application.
+ *
+ * It allows components to register success, failure,
+ * and optional finish handlers for a given operation ID, and later retrieve or remove them.
+ *
+ * This is useful for handling side effects when dealing
+ * with multiple operations that need to be tracked and updated independently.
+ *
+ * The `createEventQueue` function should be used to create a single provider and context that are shared throughout your application.
+ * The returned `EventQueueProvider` and `useEventQueue` hook should be exported
+ * from a shared module and reused across the app to ensure a single
+ * context instance is used.
+ *
+ * Usage pattern:
+ * // eventQueue.ts
+ * export const { EventQueueProvider, useEventQueue } = createEventQueue<EventType>();
+ *
+ * // App.tsx
+ * import { EventQueueProvider } from "./eventQueue";
+ * ...
+ * <EventQueueProvider>
+ *   <App />
+ * </EventQueueProvider>
+ *
+ * // In any other component
+ * import { useEventQueue } from "./eventQueue";
+ * ...
+ * const eventQueue = useEventQueue();
+ * eventQueue.set(operationId, onSuccess, onFailure);
+ */
+
+export function createEventQueue<T>() {
+  const EventQueueContext = createContext<EventQueue<T> | undefined>(undefined);
+
+  const eventQueue = new Map<string, EventCallback<T>>();
+
+  const EventQueueProvider: FC<{ children: ReactNode }> = ({ children }) => (
+    <EventQueueContext.Provider
+      value={{
+        get: (operationId) => eventQueue.get(operationId),
+        set: (operationId, onSuccess, onFailure, onFinish) =>
+          eventQueue.set(operationId, { onSuccess, onFailure, onFinish }),
+        remove: (operationId) => eventQueue.delete(operationId),
+      }}
+    >
+      {children}
+    </EventQueueContext.Provider>
+  );
+
+  const useEventQueue = () => {
+    const context = useContext(EventQueueContext);
+    if (!context) {
+      throw new Error(
+        "useEventQueue must be used within an EventQueueProvider",
+      );
+    }
+    return context;
+  };
+
+  return { EventQueueProvider, useEventQueue, EventQueueContext };
+}

src/components/EventQueue/EventQueueProvider.test.tsx

@@ -0,0 +1,93 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { createEventQueue } from "./EventQueue";
+import Button from "../Button";
+
+type Event = { message: string };
+
+const { EventQueueProvider, useEventQueue } = createEventQueue<Event>();
+
+describe("EventQueue", () => {
+  const operationId = "test-operation-id";
+
+  let user: ReturnType<typeof userEvent.setup>;
+  let successSpy: jest.Mock;
+  let failureSpy: jest.Mock;
+  let finishSpy: jest.Mock;
+
+  beforeEach(() => {
+    user = userEvent.setup();
+    successSpy = jest.fn();
+    failureSpy = jest.fn();
+    finishSpy = jest.fn();
+  });
+
+  const TriggerComponent = () => {
+    const queue = useEventQueue();
+
+    const handleRegister = () => {
+      queue.set(operationId, successSpy, failureSpy, finishSpy);
+    };
+
+    const triggerSuccess = () => {
+      const event = queue.get(operationId);
+      event?.onSuccess({ message: "Success!" });
+      event?.onFinish?.();
+      queue.remove(operationId);
+    };
+
+    const triggerFailure = () => {
+      const event = queue.get(operationId);
+      event?.onFailure("Something went wrong.");
+      event?.onFinish?.();
+      queue.remove(operationId);
+    };
+
+    return (
+      <div>
+        <Button onClick={handleRegister} data-testid="register-btn" />
+        <Button onClick={triggerSuccess} data-testid="success-btn" />
+        <Button onClick={triggerFailure} data-testid="failure-btn" />
+      </div>
+    );
+  };
+
+  const renderQueue = () =>
+    render(
+      <EventQueueProvider>
+        <TriggerComponent />
+      </EventQueueProvider>,
+    );
+
+  it("calls onSuccess and onFinish when success is triggered", async () => {
+    renderQueue();
+    await user.click(screen.getByTestId("register-btn"));
+    await user.click(screen.getByTestId("success-btn"));
+
+    expect(successSpy).toHaveBeenCalledWith({ message: "Success!" });
+    expect(failureSpy).not.toHaveBeenCalled();
+    expect(finishSpy).toHaveBeenCalled();
+  });
+
+  it("calls onFailure and onFinish when failure is triggered", async () => {
+    renderQueue();
+    await user.click(screen.getByTestId("register-btn"));
+    await user.click(screen.getByTestId("failure-btn"));
+
+    expect(failureSpy).toHaveBeenCalledWith("Something went wrong.");
+    expect(successSpy).not.toHaveBeenCalled();
+    expect(finishSpy).toHaveBeenCalled();
+  });
+
+  it("does nothing if callback is not registered", async () => {
+    renderQueue();
+    await user.click(screen.getByTestId("success-btn"));
+    await user.click(screen.getByTestId("failure-btn"));
+
+    expect(successSpy).not.toHaveBeenCalled();
+    expect(failureSpy).not.toHaveBeenCalled();
+    expect(finishSpy).not.toHaveBeenCalled();
+  });
+});

src/components/EventQueue/index.ts

@@ -0,0 +1,2 @@
+export { createEventQueue } from "./EventQueue";
+export type { EventCallback, EventQueue } from "./EventQueue";

src/index.test.ts

@@ -6,7 +6,8 @@ it("exports all public hooks and components from the index file", () => {
   const componentsPath = "./src/components/";
 
   const isNotHidden = (name: string) => !name.startsWith(".");
-  const ignoreDir = ["Notifications"];
+  // exclude directories that are not meant to be components
+  const ignoreDir = ["Notifications", "EventQueue"];
 
   const hooks = fs
     .readdirSync(hooksPath)

src/index.ts

@@ -24,6 +24,7 @@ export { default as ConfirmationModal } from "./components/ConfirmationModal";
 export { default as ContextualMenu } from "./components/ContextualMenu";
 export { default as DoughnutChart } from "./components/DoughnutChart";
 export { default as EmptyState } from "./components/EmptyState";
+export { createEventQueue } from "./components/EventQueue";
 export { default as Field } from "./components/Field";
 export { default as Form } from "./components/Form";
 export { default as FormikField } from "./components/FormikField";
@@ -124,6 +125,7 @@ export type {
 } from "./components/ContextualMenu";
 export type { DoughnutChartProps, Segment } from "./components/DoughnutChart";
 export type { EmptyStateProps } from "./components/EmptyState";
+export type { EventCallback, EventQueue } from "./components/EventQueue";
 export type { FieldProps } from "./components/Field";
 export type { FormProps } from "./components/Form";
 export type { FormikFieldProps } from "./components/FormikField";