@isograph/react-disposable-state 0.0.0-main-4ef7c123

package/src/useCachedPrecommitValue.test.tsx

@@ -0,0 +1,587 @@
+import { describe, test, vi, expect, assert } from "vitest";
+import { ParentCache } from "./ParentCache";
+import { ItemCleanupPair } from "@isograph/disposable-types";
+import { useCachedPrecommitValue } from "./useCachedPrecommitValue";
+import React from "react";
+import { create } from "react-test-renderer";
+import { CacheItem, CacheItemState } from "./CacheItem";
+
+function getItem<T>(cache: ParentCache<T>): CacheItem<T> | null {
+  return (cache as any).__item;
+}
+
+function getState<T>(cacheItem: CacheItem<T>): CacheItemState<T> {
+  return (cacheItem as any).__state;
+}
+
+function Suspender({ promise, isResolvedRef }) {
+  if (!isResolvedRef.current) {
+    throw promise;
+  }
+  return null;
+}
+
+function shortPromise() {
+  let resolve;
+  const promise = new Promise((_resolve) => {
+    resolve = _resolve;
+  });
+
+  setTimeout(resolve, 1);
+  return promise;
+}
+
+function promiseAndResolver() {
+  let resolve;
+  const isResolvedRef = {
+    current: false,
+  };
+  const promise = new Promise((r) => {
+    resolve = r;
+  });
+  return {
+    promise,
+    resolve: () => {
+      isResolvedRef.current = true;
+      resolve();
+    },
+    isResolvedRef,
+  };
+}
+
+// The fact that sometimes we need to render in concurrent mode and sometimes
+// not is a bit worrisome.
+async function awaitableCreate(Component, isConcurrent) {
+  const element = create(
+    Component,
+    isConcurrent ? { unstable_isConcurrent: true } : undefined
+  );
+  await shortPromise();
+  return element;
+}
+
+describe("useCachedPrecommitValue", () => {
+  test("on initial render, it should call getOrPopulateAndTemporaryRetain", async () => {
+    const disposeItem = vi.fn();
+    const factory = vi.fn(() => {
+      const pair: ItemCleanupPair<number> = [1, disposeItem];
+      return pair;
+    });
+    const cache = new ParentCache(factory);
+    const getOrPopulateAndTemporaryRetain = vi.spyOn(
+      cache,
+      "getOrPopulateAndTemporaryRetain"
+    );
+
+    const componentCommits = vi.fn();
+    const hookOnCommit = vi.fn();
+    const render = vi.fn();
+    function TestComponent() {
+      render();
+      React.useEffect(componentCommits);
+
+      const data = useCachedPrecommitValue(cache, hookOnCommit);
+
+      expect(render).toBeCalledTimes(1);
+      expect(componentCommits).not.toBeCalled();
+      expect(hookOnCommit).not.toBeCalled();
+      expect(data).toEqual({ state: 1 });
+      expect(factory).toBeCalledTimes(1);
+      expect(disposeItem).not.toBeCalled();
+      expect(getOrPopulateAndTemporaryRetain).toBeCalledTimes(1);
+
+      // TODO we should assert that permanentRetainIfNotDisposed was called
+      // on the cache item.
+
+      return <div />;
+    }
+
+    await awaitableCreate(<TestComponent />, false);
+
+    expect(componentCommits).toBeCalledTimes(1);
+    expect(hookOnCommit).toBeCalledTimes(1);
+    expect(render).toHaveBeenCalledTimes(1);
+  });
+
+  test("on commit, it should call the provided callback and empty the parent cache", async () => {
+    const disposeItem = vi.fn();
+    const factory = vi.fn(() => {
+      const pair: ItemCleanupPair<number> = [1, disposeItem];
+      return pair;
+    });
+    const cache = new ParentCache(factory);
+
+    const componentCommits = vi.fn();
+    const hookOnCommit = vi.fn();
+    const render = vi.fn();
+    function TestComponent() {
+      render();
+      expect(render).toHaveBeenCalledTimes(1);
+      const data = useCachedPrecommitValue(cache, hookOnCommit);
+
+      React.useEffect(() => {
+        componentCommits();
+        expect(componentCommits).toHaveBeenCalledTimes(1);
+        expect(hookOnCommit).toBeCalledTimes(1);
+        expect(hookOnCommit.mock.calls[0][0][0]).toBe(1);
+        expect(typeof hookOnCommit.mock.calls[0][0][1]).toBe("function");
+        expect(factory).toBeCalledTimes(1);
+        expect(disposeItem).not.toBeCalled();
+        expect(cache.isEmpty()).toBe(true);
+      }, []);
+
+      expect(factory).toBeCalledTimes(1);
+      expect(disposeItem).not.toBeCalled();
+      return <div />;
+    }
+
+    await awaitableCreate(<TestComponent />, false);
+    expect(componentCommits).toBeCalledTimes(1);
+    expect(render).toHaveBeenCalledTimes(1);
+  });
+
+  test("after commit, on subsequent renders it should return null", async () => {
+    const disposeItem = vi.fn();
+    const factory = vi.fn(() => {
+      const pair: ItemCleanupPair<number> = [1, disposeItem];
+      return pair;
+    });
+    const cache = new ParentCache(factory);
+
+    const componentCommits = vi.fn();
+    const hookOnCommit = vi.fn();
+    let setState;
+    let initialRender = true;
+    function TestComponent() {
+      const [, _setState] = React.useState(null);
+      setState = _setState;
+      const value = useCachedPrecommitValue(cache, hookOnCommit);
+
+      if (initialRender && value !== null) {
+        initialRender = false;
+        expect(value).toEqual({ state: 1 });
+      } else {
+        expect(value).toEqual(null);
+      }
+
+      React.useEffect(() => {
+        componentCommits();
+        expect(componentCommits).toHaveBeenCalledTimes(1);
+        expect(hookOnCommit).toBeCalledTimes(1);
+        expect(factory).toBeCalledTimes(1);
+        expect(disposeItem).not.toBeCalled();
+      }, []);
+
+      return <div />;
+    }
+
+    await awaitableCreate(<TestComponent />, false);
+
+    expect(componentCommits).toHaveBeenCalledTimes(1);
+
+    // Trigger a re-render
+    setState({});
+    await shortPromise();
+    expect(initialRender).toBe(false);
+  });
+
+  test(
+    "on repeated pre-commit renders, if the temporary retain is not disposed, " +
+      "it should re-call getOrPopulateAndTemporaryRetain but not call factory again",
+    async () => {
+      const disposeItem = vi.fn();
+      const factory = vi.fn(() => {
+        const pair: ItemCleanupPair<number> = [1, disposeItem];
+        return pair;
+      });
+      const cache = new ParentCache(factory);
+      const getOrPopulateAndTemporaryRetain = vi.spyOn(
+        cache,
+        "getOrPopulateAndTemporaryRetain"
+      );
+
+      const componentCommits = vi.fn();
+      const hookOnCommit = vi.fn();
+      const render = vi.fn();
+      let renderCount = 0;
+      function TestComponent() {
+        render();
+        const value = useCachedPrecommitValue(cache, hookOnCommit);
+
+        expect(value).toEqual({ state: 1 });
+        expect(factory).toHaveBeenCalledTimes(1);
+
+        renderCount++;
+        expect(getOrPopulateAndTemporaryRetain).toHaveBeenCalledTimes(
+          renderCount
+        );
+
+        React.useEffect(() => {
+          componentCommits();
+          expect(componentCommits).toHaveBeenCalledTimes(1);
+          expect(hookOnCommit).toBeCalledTimes(1);
+          expect(factory).toBeCalledTimes(1);
+          expect(disposeItem).not.toBeCalled();
+        }, []);
+
+        return <div />;
+      }
+
+      const { promise, isResolvedRef, resolve } = promiseAndResolver();
+      await awaitableCreate(
+        <React.Suspense fallback={<div />}>
+          <TestComponent />
+          <Suspender promise={promise} isResolvedRef={isResolvedRef} />
+        </React.Suspense>,
+        true
+      );
+
+      expect(componentCommits).toHaveBeenCalledTimes(0);
+      expect(render).toHaveBeenCalledTimes(1);
+
+      resolve();
+      await shortPromise();
+
+      expect(componentCommits).toHaveBeenCalledTimes(1);
+      expect(render).toHaveBeenCalledTimes(2);
+    }
+  );
+
+  test(
+    "on repeated pre-commit renders, if the temporary retain is disposed, " +
+      "it should re-call getOrPopulateAndTemporaryRetain and factory",
+    async () => {
+      const disposeItem = vi.fn();
+      let factoryValue = 0;
+      const factory = vi.fn(() => {
+        factoryValue++;
+        const pair: ItemCleanupPair<number> = [factoryValue, disposeItem];
+        return pair;
+      });
+      const cache = new ParentCache(factory);
+
+      const getOrPopulateAndTemporaryRetain = vi.spyOn(
+        cache,
+        "getOrPopulateAndTemporaryRetain"
+      );
+
+      const componentCommits = vi.fn();
+      const hookOnCommit = vi.fn();
+      const render = vi.fn();
+      function TestComponent() {
+        render();
+        const value = useCachedPrecommitValue(cache, hookOnCommit);
+
+        expect(value).toEqual({ state: factoryValue });
+
+        React.useEffect(() => {
+          componentCommits();
+          expect(cache.isEmpty()).toBe(true);
+          expect(componentCommits).toHaveBeenCalledTimes(1);
+          expect(hookOnCommit).toBeCalledTimes(1);
+          expect(hookOnCommit.mock.calls[0][0][0]).toBe(2);
+          expect(factory).toBeCalledTimes(2);
+          expect(disposeItem).toBeCalledTimes(1);
+        }, []);
+
+        if (render.mock.calls.length === 1) {
+          expect(factory).toHaveBeenCalledTimes(1);
+          // First render, dispose the temporary retain
+          expect(disposeItem).toBeCalledTimes(0);
+          getOrPopulateAndTemporaryRetain.mock.results[0].value[2]();
+          expect(disposeItem).toBeCalledTimes(1);
+          expect(getOrPopulateAndTemporaryRetain).toHaveBeenCalledTimes(1);
+        } else {
+          expect(factory).toHaveBeenCalledTimes(2);
+          expect(getOrPopulateAndTemporaryRetain).toHaveBeenCalledTimes(2);
+        }
+
+        return <div />;
+      }
+
+      const { promise, isResolvedRef, resolve } = promiseAndResolver();
+      await awaitableCreate(
+        <React.Suspense fallback={<div />}>
+          <TestComponent />
+          <Suspender promise={promise} isResolvedRef={isResolvedRef} />
+        </React.Suspense>,
+        true
+      );
+
+      expect(componentCommits).toHaveBeenCalledTimes(0);
+      expect(render).toHaveBeenCalledTimes(1);
+
+      resolve();
+      await shortPromise();
+
+      expect(componentCommits).toHaveBeenCalledTimes(1);
+      expect(render).toHaveBeenCalledTimes(2);
+    }
+  );
+
+  test(
+    "if the item has been disposed between the render and the commit, " +
+      "and the parent cache is empty, it will call factory again, re-render an " +
+      "additional time and called onCommit with the newly generated item",
+    async () => {
+      const disposeItem = vi.fn();
+      let factoryCount = 0;
+      const factory = vi.fn(() => {
+        factoryCount++;
+        const pair: ItemCleanupPair<number> = [factoryCount, disposeItem];
+        return pair;
+      });
+      const cache = new ParentCache(factory);
+      const getOrPopulateAndTemporaryRetain = vi.spyOn(
+        cache,
+        "getOrPopulateAndTemporaryRetain"
+      );
+      const getAndPermanentRetainIfPresent = vi.spyOn(
+        cache,
+        "getAndPermanentRetainIfPresent"
+      );
+
+      const componentCommits = vi.fn();
+      const hookOnCommit = vi.fn();
+      const render = vi.fn();
+      function TestComponent() {
+        render();
+
+        useCachedPrecommitValue(cache, hookOnCommit);
+
+        React.useEffect(() => {
+          componentCommits();
+          expect(getOrPopulateAndTemporaryRetain).toHaveBeenCalledTimes(1);
+          expect(getAndPermanentRetainIfPresent).toHaveBeenCalledTimes(1);
+          expect(getAndPermanentRetainIfPresent.mock.results[0].value).toBe(
+            null
+          );
+          expect(factory).toHaveBeenCalledTimes(2);
+          expect(cache.isEmpty()).toBe(true);
+          expect(hookOnCommit).toHaveBeenCalledTimes(1);
+          expect(hookOnCommit.mock.calls[0][0][0]).toBe(2);
+        }, []);
+
+        return <div />;
+      }
+
+      // wat is going on?
+      //
+      // We want to test a scenario where the item is disposed between the render and
+      // the commit.
+      //
+      // The subcomponents are rendered in order: TestComponent followed by CodeExecutor.
+      //
+      // - During TestComponent's render, it will populate the cache.
+      // - Then, CodeExecutor will render, and dispose the temporary retain,
+      //   disposing the cache item. The parent cache will be empty as well.
+      // - Then, TestComponent commits.
+      let initialRender = true;
+      function CodeExecutor() {
+        if (initialRender) {
+          // This code executes after the initial render of TestComponent, but before
+          // it commits.
+          expect(disposeItem).not.toHaveBeenCalled();
+          getOrPopulateAndTemporaryRetain.mock.results[0].value[2]();
+          expect(disposeItem).toHaveBeenCalledTimes(1);
+          expect(cache.isEmpty()).toBe(true);
+
+          expect(render).toHaveBeenCalledTimes(1);
+          expect(hookOnCommit).toBeCalledTimes(0);
+          expect(componentCommits).toBeCalledTimes(0);
+          expect(factory).toHaveBeenCalledTimes(1);
+
+          initialRender = false;
+        }
+
+        return null;
+      }
+
+      const element = await awaitableCreate(
+        <>
+          <TestComponent />
+          <CodeExecutor />
+        </>,
+        false
+      );
+
+      // This code executes after the commit and re-render of TestComponent.
+      // The commit triggers a re-render, because the item was disposed.
+      expect(render).toHaveBeenCalledTimes(2);
+      expect(factory).toBeCalledTimes(2);
+    }
+  );
+
+  test(
+    "if, between the render and the commit, the item has been disposed, " +
+      "and the parent cache is not empty, it will not call factory again, will re-render " +
+      "an additional time and will call onCommit with the value in the parent cache",
+    async () => {
+      const disposeItem = vi.fn();
+      let factoryCount = 0;
+      const factory = vi.fn(() => {
+        factoryCount++;
+        const pair: ItemCleanupPair<number> = [factoryCount, disposeItem];
+        return pair;
+      });
+      const cache = new ParentCache(factory);
+      const getAndPermanentRetainIfPresent = vi.spyOn(
+        cache,
+        "getAndPermanentRetainIfPresent"
+      );
+
+      const componentCommits = vi.fn();
+      const hookOnCommit = vi.fn();
+      const render = vi.fn();
+      function TestComponent() {
+        render();
+        useCachedPrecommitValue(cache, hookOnCommit);
+
+        React.useEffect(() => {
+          componentCommits();
+          // Note that we called getOrPopulateAndTemporaryRetain during CodeExecutor, hence 2
+          expect(getOrPopulateAndTemporaryRetain).toHaveBeenCalledTimes(2);
+          expect(getAndPermanentRetainIfPresent).toHaveBeenCalledTimes(1);
+          expect(getAndPermanentRetainIfPresent.mock.results[0].value[0]).toBe(
+            2
+          );
+          expect(factory).toHaveBeenCalledTimes(2);
+          expect(hookOnCommit).toHaveBeenCalledTimes(1);
+          expect(hookOnCommit.mock.calls[0][0][0]).toBe(2);
+        }, []);
+
+        return <div />;
+      }
+
+      const getOrPopulateAndTemporaryRetain = vi.spyOn(
+        cache,
+        "getOrPopulateAndTemporaryRetain"
+      );
+
+      // wat is going on?
+      //
+      // We want to test a scenario where the item is disposed between the render and
+      // the commit.
+      //
+      // The subcomponents are rendered in order: TestComponent followed by CodeExecutor.
+      //
+      // - During TestComponent's render, it will populate the cache.
+      // - Then, CodeExecutor will render, and dispose the temporary retain,
+      //   disposing the cache item. It will then repopulate the parent cache.
+      // - Then, TestComponent commits.
+      let initialRender = true;
+      function CodeExecutor() {
+        if (initialRender) {
+          // This code executes after the initial render of TestComponent, but before
+          // it commits.
+          expect(disposeItem).not.toHaveBeenCalled();
+          getOrPopulateAndTemporaryRetain.mock.results[0].value[2]();
+          expect(disposeItem).toHaveBeenCalledTimes(1);
+          expect(cache.isEmpty()).toBe(true);
+
+          cache.getOrPopulateAndTemporaryRetain();
+          expect(cache.isEmpty()).toBe(false);
+          // The factory function was called when we called getOrPopulateAndTemporaryRetain
+          expect(factory).toHaveBeenCalledTimes(2);
+
+          expect(render).toHaveBeenCalledTimes(1);
+          expect(hookOnCommit).toBeCalledTimes(0);
+          expect(componentCommits).toBeCalledTimes(0);
+
+          initialRender = false;
+        }
+
+        return null;
+      }
+
+      const element = await awaitableCreate(
+        <React.Suspense fallback="fallback">
+          <TestComponent />
+          <CodeExecutor />
+        </React.Suspense>,
+        false
+      );
+
+      // This code executes after the commit and re-render of TestComponent.
+      // The commit triggers a re-render, because the item was disposed.
+      expect(render).toHaveBeenCalledTimes(2);
+      // Note that this is the same number of calls as inside of CodeExecutor,
+      // implying that the factory function was not called again.
+      expect(factory).toBeCalledTimes(2);
+    }
+  );
+
+  test(
+    "If the component unmounts before committing, " +
+      "the item will remain in the parent cache, " +
+      "temporarily retained",
+    async () => {
+      const disposeItem = vi.fn();
+      const factory = vi.fn(() => {
+        const pair: ItemCleanupPair<number> = [1, disposeItem];
+        return pair;
+      });
+      const cache = new ParentCache(factory);
+
+      const componentCommits = vi.fn();
+      const hookOnCommit = vi.fn();
+      const render = vi.fn();
+      function TestComponent() {
+        render();
+
+        useCachedPrecommitValue(cache, hookOnCommit);
+
+        React.useEffect(() => {
+          componentCommits();
+        }, []);
+
+        return <div />;
+      }
+
+      // wat is going on?
+      //
+      // We want to test a scenario where the component unmounts before committing.
+      //
+      // The subcomponents are rendered in order: TestComponent followed by CodeExecutor.
+      // So, during CodeExecutor, we trigger a state update that causes the ParentComponent
+      // to not render the children.
+      function CodeExecutor() {
+        setShowChildren(false);
+        return null;
+      }
+
+      let setShowChildren;
+      function ParentComponent({ children }) {
+        const [showChildren, _setShowChildren] = React.useState(true);
+        setShowChildren = _setShowChildren;
+
+        if (showChildren) {
+          return children;
+        } else {
+          return null;
+        }
+      }
+
+      const element = await awaitableCreate(
+        <ParentComponent>
+          <TestComponent />
+          <CodeExecutor />
+        </ParentComponent>,
+        // If we're not in concurrent mode, TestComponent will mount before
+        // unmounting. This perhaps is a bug in react-test-renderer. Regardless,
+        // we're not interested in that scenario.
+        true
+      );
+
+      // This code executes after the commit and re-render of TestComponent.
+      // The commit triggers a re-render, because the item was disposed.
+      expect(render).toHaveBeenCalledTimes(1);
+      expect(componentCommits).toHaveBeenCalledTimes(0);
+      const item = getItem(cache)!;
+      const state = getState(item);
+      assert(state.kind === "InParentCacheAndNotDisposed");
+      expect(state.permanentRetainCount).toBe(0);
+      expect(state.temporaryRetainCount).toBe(1);
+    }
+  );
+});

package/src/useCachedPrecommitValue.ts

@@ -0,0 +1,104 @@
+"use strict";
+
+import { useEffect, useState } from "react";
+import { ParentCache } from "./ParentCache";
+import { useHasCommittedRef } from "./useHasCommittedRef";
+import { ItemCleanupPair } from "@isograph/isograph-disposable-types/dist";
+
+/**
+ * usePrecommitValue<T>
+ * - Takes a mutable parent cache, a factory function, and an onCommit callback.
+ * - Returns T before the initial commit, and null afterward.
+ * - Calls onCommit with the ItemCleanupPair during the first commit.
+ * - The T from the render phase is only temporarily retained. It may have been
+ *   disposed by the time of the commit. If so, this hook checks the parent cache
+ *   for another T or creates one, and passes this T to onCommit.
+ * - If the T returned during the last render is not the same as the one that
+ *   is passed to onCommit, during the commit phase, will schedule another render.
+ *
+ * Invariant: the returned T has not been disposed during the tick of the render.
+ * The T passed to the onCommit callback has not been disposed when the onCommit
+ * callback is called.
+ *
+ * Passing a different parentCache:
+ * - Pre-commit, passing a different parentCache has the effect of "resetting" this
+ *   hook's state to the new cache's state. For example, if you have a cache associated
+ *   with a set of variables (e.g. {name: "Matthew"}), and pass in another cache
+ *   (e.g. associated with {name: "James"}), which is empty, the hook will fill that
+ *   new cache with the factory function.
+ *
+ * Passing a different factory:
+ * - Passing a different factory has no effect, except when factory is called,
+ *   which is when the parent cache is being filled, or during the initial commit.
+ *
+ * Passing a different onCommit:
+ * - Passing a different onCommit has no effect, except for during the initial commit.
+ *
+ * Post-commit, all parameters are ignored and the hook returns null.
+ */
+export function useCachedPrecommitValue<T>(
+  parentCache: ParentCache<T>,
+  onCommit: (pair: ItemCleanupPair<T>) => void
+): { state: T } | null {
+  // TODO: there should be two APIs. One in which we always re-render if the
+  // committed item was not returned during the last render, and one in which
+  // we do not. The latter is useful for cases where every disposable item
+  // behaves identically, but must be loaded.
+  //
+  // This hook is the former, i.e. re-renders if the committed item has changed.
+  const [, rerender] = useState<{} | null>(null);
+
+  useEffect(() => {
+    // On first commit, cacheItem may be disposed, because during the render phase,
+    // we only temporarily retained the item, and the temporary retain could have
+    // expired by the time of the commit.
+    //
+    // So, we can be in one of two states:
+    // - the item is not disposed. In that case, permanently retain and use that item.
+    // - the item is disposed. In that case, we can be in two states:
+    //   - the parent cache is not empty (due to another component rendering, or
+    //     another render of the same component.) In that case, permanently retain and
+    //     use the item from the parent cache. (Note: any item present in the parent
+    //     cache is not disposed.)
+    //   - the parent cache is empty. In that case, call factory, getting a new item
+    //     and a cleanup function.
+    //
+    // After the above, we have a non-disposed item and a cleanup function, which we
+    // can pass to onCommit.
+    const undisposedPair = cacheItem.permanentRetainIfNotDisposed(
+      disposeOfTemporaryRetain
+    );
+    if (undisposedPair !== null) {
+      onCommit(undisposedPair);
+    } else {
+      // The cache item we created during render has been disposed. Check if the parent
+      // cache is populated.
+      const existingCacheItemCleanupPair =
+        parentCache.getAndPermanentRetainIfPresent();
+      if (existingCacheItemCleanupPair !== null) {
+        onCommit(existingCacheItemCleanupPair);
+      } else {
+        // We did not find an item in the parent cache, create a new one.
+        onCommit(parentCache.factory());
+      }
+
+      // TODO: Consider whether we always want to rerender if the committed item
+      // was not returned during the last render, or whether some callers will
+      // prefer opting out of this behavior (e.g. if every disposable item behaves
+      // identically, but must be loaded.)
+      rerender({});
+    }
+  }, []);
+
+  const hasCommittedRef = useHasCommittedRef();
+  if (hasCommittedRef.current) {
+    return null;
+  }
+
+  // Safety: item is only safe to use (i.e. guaranteed not to have disposed)
+  // during this tick.
+  const [cacheItem, item, disposeOfTemporaryRetain] =
+    parentCache.getOrPopulateAndTemporaryRetain();
+
+  return { state: item };
+}