feat: DH-16737 Add ObjectManager, useWidget hook

packages/app-utils/src/components/ConnectionBootstrap.tsx

@@ -1,7 +1,9 @@
-import React, { useCallback, useEffect, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
 import { LoadingOverlay } from '@deephaven/components';
 import {
   ObjectFetcherContext,
+  ObjectFetchManager,
+  ObjectFetchManagerContext,
   sanitizeVariableDescriptor,
   useApi,
   useClient,
@@ -31,6 +33,7 @@ export function ConnectionBootstrap({
   const client = useClient();
   const [error, setError] = useState<unknown>();
   const [connection, setConnection] = useState<dh.IdeConnection>();
+
   useEffect(
     function initConnection() {
       let isCanceled = false;
@@ -83,6 +86,24 @@ export function ConnectionBootstrap({
     [connection]
   );
 
+  /** We don't really need to do anything fancy in Core to manage an object, just fetch it  */
+  const objectManager: ObjectFetchManager = useMemo(
+    () => ({
+      subscribe: (descriptor, onUpdate) => {
+        // We send an update with the fetch right away
+        onUpdate({
+          fetch: () => objectFetcher(descriptor),
+          error: null,
+        });
+        return () => {
+          // no-op
+          // For Core, if the server dies then we can't reconnect anyway, so no need to bother listening for subscription or cleaning up
+        };
+      },
+    }),
+    [objectFetcher]
+  );
+
   if (connection == null || error != null) {
     return (
       <LoadingOverlay
@@ -96,7 +117,9 @@ export function ConnectionBootstrap({
   return (
     <ConnectionContext.Provider value={connection}>
       <ObjectFetcherContext.Provider value={objectFetcher}>
-        {children}
+        <ObjectFetchManagerContext.Provider value={objectManager}>
+          {children}
+        </ObjectFetchManagerContext.Provider>
       </ObjectFetcherContext.Provider>
     </ConnectionContext.Provider>
   );

packages/jsapi-bootstrap/package.json

@@ -25,7 +25,8 @@
     "@deephaven/components": "file:../components",
     "@deephaven/jsapi-types": "1.0.0-dev0.34.0",
     "@deephaven/log": "file:../log",
-    "@deephaven/react-hooks": "file:../react-hooks"
+    "@deephaven/react-hooks": "file:../react-hooks",
+    "@deephaven/utils": "file:../utils"
   },
   "devDependencies": {
     "react": "^17.x"

packages/jsapi-bootstrap/src/index.ts

@@ -4,4 +4,6 @@ export * from './DeferredApiBootstrap';
 export * from './useApi';
 export * from './useClient';
 export * from './useDeferredApi';
+export * from './useObjectFetch';
 export * from './useObjectFetcher';
+export * from './useWidget';

packages/jsapi-bootstrap/src/useObjectFetch.test.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { renderHook } from '@testing-library/react-hooks';
+import { ObjectFetchManagerContext, useObjectFetch } from './useObjectFetch';
+
+it('should resolve the objectFetch when in the context', async () => {
+  const objectFetch = jest.fn(async () => undefined);
+  const unsubscribe = jest.fn();
+  const descriptor = { type: 'type', name: 'name' };
+  const subscribe = jest.fn((subscribeDescriptor, onUpdate) => {
+    expect(subscribeDescriptor).toEqual(descriptor);
+    onUpdate({ fetch: objectFetch, error: null });
+    return unsubscribe;
+  });
+  const objectManager = { subscribe };
+  const wrapper = ({ children }) => (
+    <ObjectFetchManagerContext.Provider value={objectManager}>
+      {children}
+    </ObjectFetchManagerContext.Provider>
+  );
+
+  const { result } = renderHook(() => useObjectFetch(descriptor), { wrapper });
+  expect(result.current).toEqual({ fetch: objectFetch, error: null });
+  expect(result.error).toBeUndefined();
+  expect(objectFetch).not.toHaveBeenCalled();
+});
+
+it('should return an error, not throw if objectFetch not available in the context', async () => {
+  const descriptor = { type: 'type', name: 'name' };
+  const { result } = renderHook(() => useObjectFetch(descriptor));
+  expect(result.current).toEqual({
+    fetch: null,
+    error: expect.any(Error),
+  });
+  expect(result.error).toBeUndefined();
+});

packages/jsapi-bootstrap/src/useObjectFetch.ts

@@ -0,0 +1,93 @@
+import { createContext, useContext, useEffect, useState } from 'react';
+import type { dh } from '@deephaven/jsapi-types';
+import { ObjectFetcherContext } from './useObjectFetcher';
+
+/** Function for unsubscribing from a given subscription */
+export type UnsubscribeFunction = () => void;
+
+/**
+ * Update with the current `fetch` fuonction and status of the object.
+ * - If both `fetch` and `error` are `null`, it is still loading the fetcher
+ * - If `fetch` is not `null`, the object is ready to be fetched
+ * - If `error` is not `null`, there was an error loading the object
+ */
+export type ObjectFetchUpdate<T = unknown> = {
+  /**
+   * Function to fetch the object. If `null`, the object is still loading or there was an error.
+   */
+  fetch: (() => Promise<T>) | null;
+
+  /**
+   * Error that occurred while fetching the object. If `null`, there was no error.
+   * Will automatically retry when possible while the subscribed.
+   */
+  error: unknown | null;
+};
+
+export type ObjectFetchUpdateCallback<T = unknown> = (
+  update: ObjectFetchUpdate<T>
+) => void;
+
+/** ObjectFetchManager for managing a subscription to an object using a VariableDescriptor */
+export type ObjectFetchManager = {
+  /**
+   *
+   * @param descriptor Descriptor object to fetch the object from. Can be extended by a specific implementation to include more details necessary for the ObjectManager.
+   * @param onUpdate Callback function to be called when the object is updated.
+   * @returns An unsubscribe function to stop listening for updates and clean up the object.
+   */
+  subscribe: <T = unknown>(
+    descriptor: dh.ide.VariableDescriptor,
+    onUpdate: ObjectFetchUpdateCallback<T>
+  ) => UnsubscribeFunction;
+};
+
+/** Context for tracking an implementation of the ObjectFetchManager. */
+export const ObjectFetchManagerContext =
+  createContext<ObjectFetchManager | null>(null);
+
+/**
+ * Retrieve a `fetch` function for the given variable descriptor.
+ *
+ * @param descriptor Descriptor to get the `fetch` function for
+ * @returns An object with the current `fetch` function, OR an error status set if there was an issue fetching the object.
+ *          Retrying is left up to the ObjectManager implementation used from this context.
+ */
+export function useObjectFetch<T = unknown>(
+  descriptor: dh.ide.VariableDescriptor
+): ObjectFetchUpdate<T> {
+  const [currentUpdate, setCurrentUpdate] = useState<ObjectFetchUpdate<T>>(
+    () => ({
+      fetch: null,
+      error: null,
+    })
+  );
+
+  const objectFetcher = useContext(ObjectFetcherContext);
+  const objectFetchManager = useContext(ObjectFetchManagerContext);
+
+  useEffect(() => {
+    if (objectFetchManager == null) {
+      if (objectFetcher == null) {
+        setCurrentUpdate({
+          fetch: null,
+          error: new Error('No ObjectFetchManager available in context'),
+        });
+      } else {
+        setCurrentUpdate({
+          fetch: () => objectFetcher(descriptor),
+          error: null,
+        });
+      }
+      return;
+    }
+    // Signal that we're still loading
+    setCurrentUpdate({
+      fetch: null,
+      error: null,
+    });
+    return objectFetchManager.subscribe(descriptor, setCurrentUpdate);
+  }, [descriptor, objectFetcher, objectFetchManager]);
+
+  return currentUpdate;
+}

packages/jsapi-bootstrap/src/useWidget.test.tsx

@@ -0,0 +1,68 @@
+import React from 'react';
+import { act, renderHook } from '@testing-library/react-hooks';
+import { TestUtils } from '@deephaven/utils';
+import { useWidget } from './useWidget';
+import { ObjectFetchManagerContext } from './useObjectFetch';
+
+describe('useWidget', () => {
+  it('should return a widget when available', async () => {
+    const descriptor = { type: 'type', name: 'name' };
+    const widget = { close: jest.fn() };
+    const fetch = jest.fn(async () => widget);
+    const objectFetch = { fetch, error: null };
+    const subscribe = jest.fn((subscribeDescriptor, onUpdate) => {
+      expect(subscribeDescriptor).toEqual(descriptor);
+      onUpdate(objectFetch);
+      return jest.fn();
+    });
+    const objectManager = { subscribe };
+    const wrapper = ({ children }) => (
+      <ObjectFetchManagerContext.Provider value={objectManager}>
+        {children}
+      </ObjectFetchManagerContext.Provider>
+    );
+    const { result } = renderHook(() => useWidget(descriptor), { wrapper });
+    await act(TestUtils.flushPromises);
+    expect(result.current).toEqual({ widget, error: null });
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('should return an error when an error occurs', () => {
+    const descriptor = { type: 'type', name: 'name' };
+    const error = new Error('Error fetching widget');
+    const objectFetch = { fetch: null, error };
+    const subscribe = jest.fn((subscribeDescriptor, onUpdate) => {
+      expect(subscribeDescriptor).toEqual(descriptor);
+      onUpdate(objectFetch);
+      return jest.fn();
+    });
+    const objectManager = { subscribe };
+    const wrapper = ({ children }) => (
+      <ObjectFetchManagerContext.Provider value={objectManager}>
+        {children}
+      </ObjectFetchManagerContext.Provider>
+    );
+
+    const { result } = renderHook(() => useWidget(descriptor), { wrapper });
+
+    expect(result.current).toEqual({ widget: null, error });
+  });
+
+  it('should return null when still loading', () => {
+    const descriptor = { type: 'type', name: 'name' };
+    const objectFetch = { fetch: null, error: null };
+    const subscribe = jest.fn((_, onUpdate) => {
+      onUpdate(objectFetch);
+      return jest.fn();
+    });
+    const objectManager = { subscribe };
+    const wrapper = ({ children }) => (
+      <ObjectFetchManagerContext.Provider value={objectManager}>
+        {children}
+      </ObjectFetchManagerContext.Provider>
+    );
+    const { result } = renderHook(() => useWidget(descriptor), { wrapper });
+
+    expect(result.current).toEqual({ widget: null, error: null });
+  });
+});

packages/jsapi-bootstrap/src/useWidget.ts

@@ -0,0 +1,93 @@
+import { dh } from '@deephaven/jsapi-types';
+import Log from '@deephaven/log';
+import { assertNotNull } from '@deephaven/utils';
+import { useEffect, useState } from 'react';
+import { useObjectFetch } from './useObjectFetch';
+
+const log = Log.module('useWidget');
+
+/**
+ * Wrapper object for a widget and error status. Both widget and error will be `null` if it is still loading.
+ */
+type WidgetWrapper<T extends dh.Widget = dh.Widget> = {
+  /** Widget object to retrieve */
+  widget: T | null;
+
+  /** Error status if there was an issue fetching the widget */
+  error: unknown | null;
+};
+
+/**
+ * Retrieve a widget for the given variable descriptor. Note that if the widget is successfully fetched, ownership of the widget is passed to the consumer and will need to close the object as well.
+ * @param descriptor Descriptor to get the widget for
+ * @returns A WidgetWrapper object that contains the widget or an error status if there was an issue fetching the widget. Will contain nulls if still loading.
+ */
+export function useWidget<T extends dh.Widget = dh.Widget>(
+  descriptor: dh.ide.VariableDescriptor
+): WidgetWrapper<T> {
+  const [wrapper, setWrapper] = useState<WidgetWrapper<T>>(() => ({
+    widget: null,
+    error: null,
+  }));
+
+  const objectFetch = useObjectFetch<T>(descriptor);
+
+  useEffect(
+    function loadWidget() {
+      log.debug('loadWidget', descriptor);
+
+      const { fetch, error } = objectFetch;
+
+      if (error != null) {
+        // We can't fetch if there's an error getting the fetcher, just return an error
+        setWrapper({ widget: null, error });
+        return;
+      }
+
+      if (fetch == null) {
+        // Still loading
+        setWrapper({ widget: null, error: null });
+        return;
+      }
+
+      // We should be able to load the widget. Load it asynchronously, and set the widget when it's done.
+      // If we get cancelled before the fetch is done, we should close the widget and its exported objects.
+      // If not though, the consumer of the widget is expected to take ownership and close the widget appropriately.
+      let isCancelled = false;
+      async function loadWidgetInternal() {
+        try {
+          assertNotNull(fetch);
+          const newWidget = await fetch();
+          if (isCancelled) {
+            log.debug2('loadWidgetInternal cancelled', descriptor, newWidget);
+            newWidget.close();
+            newWidget.exportedObjects.forEach(
+              (exportedObject: dh.WidgetExportedObject) => {
+                exportedObject.close();
+              }
+            );
+            return;
+          }
+          log.debug('loadWidgetInternal done', descriptor, newWidget);
+
+          setWrapper({ widget: newWidget, error: null });
+        } catch (e) {
+          if (isCancelled) {
+            return;
+          }
+          log.error('loadWidgetInternal error', descriptor, e);
+          setWrapper({ widget: null, error: e });
+        }
+      }
+      loadWidgetInternal();
+      return () => {
+        isCancelled = true;
+      };
+    },
+    [descriptor, objectFetch]
+  );
+
+  return wrapper;
+}
+
+export default useWidget;

packages/jsapi-bootstrap/tsconfig.json

@@ -9,6 +9,7 @@
   "references": [
     { "path": "../components" },
     { "path": "../log" },
-    { "path": "../react-hooks" }
+    { "path": "../react-hooks" },
+    { "path": "../utils" }
   ]
 }