Add Nova Scheduling Provider

change/@nova-react-03ccc792-9e47-40ce-a3b6-caa9d5f05c1e.json

@@ -0,0 +1,9 @@
+{
+  "type": "minor",
+  "comment": {
+    "title": "Adds Nova Scheduling Provider"
+  },
+  "packageName": "@nova/react",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@nova-types-6051ab01-fe7c-4df4-9422-1143550c1376.json

@@ -0,0 +1,9 @@
+{
+  "type": "minor",
+  "comment": {
+    "title": "Adds Nova Scheduling Provider"
+  },
+  "packageName": "@nova/types",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/nova-react/src/scheduling/nova-scheduling-provider.test.tsx

@@ -0,0 +1,62 @@
+/**
+ * @jest-environment jsdom
+ */
+import React from "react";
+import { render } from "@testing-library/react";
+import {
+  NovaSchedulingProvider,
+  useNovaScheduling,
+} from "./nova-scheduling-provider";
+import type { NovaScheduling } from "@nova/types";
+
+describe(useNovaScheduling, () => {
+  it("throws without a provider", () => {
+    expect.assertions(1);
+
+    const TestUndefinedContextComponent: React.FC = () => {
+      try {
+        useNovaScheduling();
+      } catch (e) {
+        expect((e as Error).message).toMatch(
+          "Nova Scheduling provider must be initialized prior to consumption!",
+        );
+      }
+      return null;
+    };
+
+    render(<TestUndefinedContextComponent />);
+  });
+
+  it("is able to access the scheduling instance provided by the provider", () => {
+    expect.assertions(3);
+
+    const scheduling = {
+      schedule: jest.fn(),
+      cancel: jest.fn(),
+    } as unknown as NovaScheduling;
+
+    const TestPassedContextComponent: React.FC = () => {
+      const facadeFromContext = useNovaScheduling();
+      expect(facadeFromContext).toBe(scheduling);
+
+      facadeFromContext.schedule(
+        () => {
+          return;
+        },
+        { priority: "background", scheduledById: "test", id: "test" },
+      );
+      expect(scheduling.schedule).toBeCalledTimes(1);
+
+      facadeFromContext.cancel(1);
+      expect(scheduling.cancel).toBeCalledTimes(1);
+
+      return null;
+    };
+
+    render(
+      <NovaSchedulingProvider scheduling={scheduling}>
+        <TestPassedContextComponent />
+      </NovaSchedulingProvider>,
+    );
+  });
+});

packages/nova-react/src/scheduling/nova-scheduling-provider.tsx

@@ -0,0 +1,32 @@
+import React from "react";
+import type { NovaScheduling } from "@nova/types";
+import invariant from "invariant";
+
+// Initializing default with null to make sure providers are correctly placed in the tree
+const NovaSchedulingContext = React.createContext<NovaScheduling | null>(null);
+
+interface NovaSchedulingProviderProps {
+  scheduling: NovaScheduling;
+}
+
+export const NovaSchedulingProvider: React.FunctionComponent<
+  NovaSchedulingProviderProps
+> = ({ children, scheduling }) => {
+  return (
+    <NovaSchedulingContext.Provider value={scheduling}>
+      {children}
+    </NovaSchedulingContext.Provider>
+  );
+};
+NovaSchedulingProvider.displayName = "NovaSchedulingProvider";
+
+export const useNovaScheduling = (): NovaScheduling => {
+  const scheduling = React.useContext<NovaScheduling | null>(
+    NovaSchedulingContext,
+  );
+  invariant(
+    scheduling,
+    "Nova Scheduling provider must be initialized prior to consumption!",
+  );
+  return scheduling;
+};

packages/nova-types/src/index.ts

@@ -2,3 +2,4 @@ export * from "./nova-commanding.interface";
 export * from "./nova-commanding-centralized.interface";
 export * from "./nova-graphql.interface";
 export * from "./nova-eventing.interface";
+export * from "./nova-scheduling.interface";

packages/nova-types/src/nova-scheduling.interface.ts

@@ -0,0 +1,43 @@
+/**
+ * Describes the scheduling contract UI components and their logical parent within a host application.
+ * Usage: Components should create an adapter to their scheduler of choice and provide it to the NovaSchedulingProvider.
+ * This interface out of the box is designed to work with the priorities of the Prioritized Task Scheduling API:
+ *   https://developer.mozilla.org/en-US/docs/Web/API/Prioritized_Task_Scheduling_API#task_priorities
+ * A scheduler implementation should be able to handle sending tasks to the browser's scheduler, or to a custom scheduler, and then cancelling those tasks as needed.
+ */
+export interface NovaScheduling {
+  /**
+   * Schedule a job to be run at some point in the future.
+   * @param job The job to be run.
+   * @param meta The metadata associated with the job.
+   * @returns A job identifier which can be used to cancel the job.
+   */
+  schedule(job: IJob<any>, meta: IJobMetaData): number;
+  /**
+   * Cancel a job which has been scheduled.
+   * @param jobId The identifier of the job to be cancelled.
+   * @returns void
+   */
+  cancel(jobId: number): void;
+}
+
+type IJob<TResult> = (() => Promise<TResult>) | (() => TResult);
+
+export interface IJobMetaData {
+  /**
+   * The requested priority of the job.
+   */
+  priority: JobPriority;
+  /**
+   * The identifier of the type of job. Note that this is not globally
+   * unique amongst all instances of a job type.
+   */
+  id: string;
+  /**
+   * The identifier of the type of code which scheduled the job. Note that this is
+   * not globally unique amongst all instances of calling code.
+   */
+  scheduledById: string;
+}
+
+export type JobPriority = "background" | "user-visible" | "user-blocking";