@isograph/react-disposable-state 0.5.1 → 0.5.4

package/package.json

@@ -1,20 +1,23 @@
 {
   "name": "@isograph/react-disposable-state",
-  "version": "0.5.1",
+  "version": "0.5.4",
   "description": "Primitives for managing disposable state in React",
   "homepage": "https://isograph.dev",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.cts",
   "author": "Isograph Labs",
   "license": "MIT",
   "dependencies": {
-    "@isograph/disposable-types": "0.5.1"
+    "@isograph/disposable-types": "0.5.4"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
+    "@testing-library/react": "16.3.2",
     "@types/react": "18.3.1",
+    "@types/react-test-renderer": "^18.3.0",
+    "happy-dom": "20.4.0",
     "react-test-renderer": "^18.2.0",
     "typescript": "5.6.3"
   },
@@ -27,8 +30,8 @@
   "module": "./dist/index.mjs",
   "exports": {
     ".": {
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs"
     },
     "./package.json": "./package.json"
   },

package/src/CacheItem.test.ts

@@ -153,7 +153,45 @@ describe('CacheItem', () => {
 
       expect(() => {
         disposeTemporaryRetain();
-      }).toThrow();
+      }).toThrow('A temporary retain should only be cleared once.');
+    });
+  });
+
+  describe('Item that is temporarily retained twice', () => {
+    // A second clear of one temporary retain while the other still holds the
+    // item: without the status transition the count is decremented twice, the
+    // item leaves the parent cache, and the other holder's clear finds it in an
+    // invalid state.
+    test('Clearing the same temporary retain twice throws and leaves the other retain intact', () => {
+      const removeFromParentCache = vi.fn();
+      const disposeItem = vi.fn();
+
+      const factory = vi.fn(() => {
+        const ret: ItemCleanupPair<number> = [1, disposeItem];
+        return ret;
+      });
+      const [cacheItem, disposeTemporaryRetain1] =
+        createTemporarilyRetainedCacheItem<number>(
+          factory,
+          removeFromParentCache,
+        );
+      const disposeTemporaryRetain2 = cacheItem.temporaryRetain();
+
+      disposeTemporaryRetain1();
+      expect(() => {
+        disposeTemporaryRetain1();
+      }).toThrow('A temporary retain should only be cleared once.');
+
+      const state = getState(cacheItem);
+      assert(state.kind === 'InParentCacheAndNotDisposed');
+      expect(state.temporaryRetainCount).toEqual(1);
+      expect(removeFromParentCache).not.toHaveBeenCalled();
+      expect(disposeItem).not.toHaveBeenCalled();
+
+      disposeTemporaryRetain2();
+      expect(getState(cacheItem).kind).toEqual('NotInParentCacheAndDisposed');
+      expect(removeFromParentCache).toHaveBeenCalledOnce();
+      expect(disposeItem).toHaveBeenCalledOnce();
     });
   });
 
@@ -213,7 +251,7 @@ describe('CacheItem', () => {
 
       expect(() => {
         disposeTemporaryRetain();
-      }).toThrow();
+      }).toThrow('A temporary retain should only be cleared once.');
     });
 
     test('Item is disposed when the permanently retain is disposed', () => {

package/src/CacheItem.ts

@@ -209,6 +209,7 @@ export class CacheItem<T> {
                 'This indicates a bug in react-disposable-state.',
             );
           } else if (status === 'Uncleared') {
+            status = 'ClearedByCallback';
             switch (this.__state.kind) {
               case 'InParentCacheAndNotDisposed': {
                 this.__state.temporaryRetainCount--;

package/src/ParentCache.ts

@@ -3,11 +3,10 @@ import type {
   Factory,
   ItemCleanupPair,
 } from '@isograph/disposable-types';
-import type { CacheItem } from './CacheItem';
+import type { CacheItem, CacheItemOptions } from './CacheItem';
 import { createTemporarilyRetainedCacheItem } from './CacheItem';
 
 // TODO convert cache impl to a getter and setter and free functions
-// TODO accept options that get passed to CacheItem
 
 /**
  * ParentCache
@@ -28,11 +27,13 @@ import { createTemporarilyRetainedCacheItem } from './CacheItem';
 export class ParentCache<T> {
   private __cacheItem: CacheItem<T> | null = null;
   private readonly __factory: Factory<T>;
+  private readonly __options: CacheItemOptions | void;
 
   // TODO pass an onEmpty function, which can e.g. remove this ParentCache
   // from some parent object.
-  constructor(factory: Factory<T>) {
+  constructor(factory: Factory<T>, options?: CacheItemOptions) {
     this.__factory = factory;
+    this.__options = options;
   }
 
   /**
@@ -59,24 +60,28 @@ export class ParentCache<T> {
 
   private __populateAndTemporaryRetain(): [CacheItem<T>, T, CleanupFn] {
     const pair: ItemCleanupPair<CacheItem<T>> =
-      createTemporarilyRetainedCacheItem(this.__factory, () => {
-        // We are doing this check because we don't want to remove the cache item
-        // if it is not the one that was created when the temporary retain was created.
-        //
-        // Consider the following scenario:
-        // - we populate the cache with CacheItem A,
-        // - then manually delete CacheItem A (e.g. to force a refetch)
-        // - then, we re-populate the parent cache with CacheItem B
-        // - then, the temporary retain of CacheItem A is disposed or expires.
-        //
-        // At this point, we don't want to delete CacheItem B from the cache.
-        //
-        // TODO consider what happens if items are === comparable to each other,
-        // e.g. the item is a number!
-        if (this.__cacheItem === pair[0]) {
-          this.empty();
-        }
-      });
+      createTemporarilyRetainedCacheItem(
+        this.__factory,
+        () => {
+          // We are doing this check because we don't want to remove the cache item
+          // if it is not the one that was created when the temporary retain was created.
+          //
+          // Consider the following scenario:
+          // - we populate the cache with CacheItem A,
+          // - then manually delete CacheItem A (e.g. to force a refetch)
+          // - then, we re-populate the parent cache with CacheItem B
+          // - then, the temporary retain of CacheItem A is disposed or expires.
+          //
+          // At this point, we don't want to delete CacheItem B from the cache.
+          //
+          // TODO consider what happens if items are === comparable to each other,
+          // e.g. the item is a number!
+          if (this.__cacheItem === pair[0]) {
+            this.empty();
+          }
+        },
+        this.__options,
+      );
 
     // We deconstruct this here instead of at the definition site because otherwise,
     // typescript thinks that cacheItem is any, because it's referenced in the closure.

package/src/index.ts

@@ -4,6 +4,8 @@ export * from './CacheItem';
 export * from './ParentCache';
 export * from './useCachedResponsivePrecommitValue';
 export * from './useDisposableState';
+export * from './useEffectsRerunWithoutRender';
 export * from './useHasCommittedRef';
 export * from './useLazyDisposableState';
+export * from './useUpdatableDisposableClearableState';
 export * from './useUpdatableDisposableState';

package/src/useCachedResponsivePrecommitValue.test.tsx

@@ -1,5 +1,9 @@
 import type { ItemCleanupPair } from '@isograph/disposable-types';
-import React, { type MutableRefObject } from 'react';
+import React, {
+  StrictMode,
+  type MutableRefObject,
+  type ReactElement,
+} from 'react';
 import { create } from 'react-test-renderer';
 import { assert, describe, expect, test, vi } from 'vitest';
 import type { CacheItem, CacheItemState } from './CacheItem';
@@ -52,9 +56,10 @@ function promiseAndResolver() {
 
 // The fact that sometimes we need to render in concurrent mode and sometimes
 // not is a bit worrisome.
-async function awaitableCreate(Component, isConcurrent: boolean) {
+async function awaitableCreate(Component: ReactElement, isConcurrent: boolean) {
   const element = create(
-    Component,
+    <StrictMode>{Component}</StrictMode>,
+    // @ts-expect-error
     isConcurrent ? { unstable_isConcurrent: true } : undefined,
   );
   await shortPromise();

package/src/useCachedResponsivePrecommitValue.ts

@@ -3,6 +3,7 @@
 import type { ItemCleanupPair } from '@isograph/disposable-types';
 import { useEffect, useRef, useState } from 'react';
 import type { ParentCache } from './ParentCache';
+import { useEffectsRerunWithoutRenderRef } from './useEffectsRerunWithoutRender';
 
 /**
  * useCachedResponsivePrecommitValue<T>
@@ -49,6 +50,8 @@ export function useCachedResponsivePrecommitValue<T>(
   const [, rerender] = useState<{} | null>(null);
   const lastCommittedParentCache = useRef<ParentCache<T> | null>(null);
 
+  const effectsRerunWithoutRenderRef = useEffectsRerunWithoutRenderRef();
+
   useEffect(() => {
     lastCommittedParentCache.current = parentCache;
     // On commit, cacheItem may be disposed, because during the render phase,
@@ -67,28 +70,37 @@ export function useCachedResponsivePrecommitValue<T>(
     //
     // 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());
+    //
+    // When this effect runs again without a render (StrictMode's simulated
+    // remount, Fast Refresh, Activity), the render's temporary retain was
+    // already converted by the first run and released by the cleanup, so the
+    // item is re-acquired from the parent cache below instead.
+    if (!effectsRerunWithoutRenderRef.current) {
+      const undisposedPair = cacheItem.permanentRetainIfNotDisposed(
+        disposeOfTemporaryRetain,
+      );
+      if (undisposedPair != null) {
+        onCommit(undisposedPair);
+        return;
       }
-      // 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({});
     }
+    effectsRerunWithoutRenderRef.current = false;
+
+    // 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({});
   }, [parentCache]);
 
   if (lastCommittedParentCache.current === parentCache) {

package/src/useDisposableState.ts

@@ -21,7 +21,6 @@ export function useDisposableState<T = never>(
   const preCommitItem = useCachedResponsivePrecommitValue(
     parentCache,
     (pair) => {
-      itemCleanupPairRef.current?.[1]();
       itemCleanupPairRef.current = pair;
     },
   );
@@ -35,25 +34,25 @@ export function useDisposableState<T = never>(
         if (itemCleanupPairRef.current != null) {
           itemCleanupPairRef.current[1]();
           itemCleanupPairRef.current = null;
-        } else {
-          throw new Error(
-            'itemCleanupPairRef.current is unexpectedly null. ' +
-              'This indicates a bug in react-disposable-state.',
-          );
         }
       }
     },
     [stateFromDisposableStateHook],
   );
 
-  useEffect(function cleanupItemCleanupPairRefIfSetStateNotCalled() {
-    return () => {
-      if (itemCleanupPairRef.current != null) {
-        itemCleanupPairRef.current[1]();
-        itemCleanupPairRef.current = null;
-      }
-    };
-  }, []);
+  useEffect(
+    function cleanupItemCleanupPairRefIfSetStateNotCalled() {
+      return () => {
+        if (itemCleanupPairRef.current != null) {
+          itemCleanupPairRef.current[1]();
+          // Forgotten so that nothing can release this pair a second time
+          // before an effect re-run (StrictMode, Fast Refresh) stores a new one.
+          itemCleanupPairRef.current = null;
+        }
+      };
+    },
+    [parentCache],
+  );
   const state: T | undefined =
     (stateFromDisposableStateHook !== UNASSIGNED_STATE
       ? stateFromDisposableStateHook
@@ -67,7 +66,6 @@ export function useDisposableState<T = never>(
       setState,
     };
   }
-
   // Safety: we can be in one of three states. Pre-commit, in which case
   // preCommitItem is assigned, post-commit but before setState has been
   // called, in which case itemCleanupPairRef.current is assigned, or

package/src/useEffectsRerunWithoutRender.test.tsx

@@ -0,0 +1,54 @@
+import { render } from '@testing-library/react';
+import React, { useEffect } from 'react';
+import { describe, expect, test } from 'vitest';
+import { useEffectsRerunWithoutRenderRef } from './useEffectsRerunWithoutRender';
+
+function Probe({ dep, reports }: { dep: number; reports: boolean[] }) {
+  const effectsRerunWithoutRenderRef = useEffectsRerunWithoutRenderRef();
+  useEffect(() => {
+    reports.push(effectsRerunWithoutRenderRef.current);
+    effectsRerunWithoutRenderRef.current = false;
+  }, [dep, effectsRerunWithoutRenderRef]);
+  return null;
+}
+
+describe('useEffectsRerunWithoutRenderRef', () => {
+  test('under StrictMode, the first mount reads false and the simulated remount reads true', () => {
+    const reports: boolean[] = [];
+    render(<Probe dep={0} reports={reports} />, { reactStrictMode: true });
+
+    expect(reports).toEqual([false, true]);
+  });
+
+  test('without StrictMode, the mount reads false', () => {
+    const reports: boolean[] = [];
+    render(<Probe dep={0} reports={reports} />, { reactStrictMode: false });
+
+    expect(reports).toEqual([false]);
+  });
+
+  test('an effect run caused by a render reads false, once the remount has reset the ref', () => {
+    const reports: boolean[] = [];
+    const { rerender } = render(<Probe dep={0} reports={reports} />, {
+      reactStrictMode: true,
+    });
+    rerender(<Probe dep={1} reports={reports} />);
+
+    expect(reports).toEqual([false, true, false]);
+  });
+
+  test('the ref stays true until the caller resets it', () => {
+    const reads: boolean[] = [];
+    function NeverResets() {
+      const effectsRerunWithoutRenderRef = useEffectsRerunWithoutRenderRef();
+      useEffect(() => {
+        reads.push(effectsRerunWithoutRenderRef.current);
+      });
+      return null;
+    }
+    const { rerender } = render(<NeverResets />, { reactStrictMode: true });
+    rerender(<NeverResets />);
+
+    expect(reads).toEqual([false, true, true]);
+  });
+});

package/src/useEffectsRerunWithoutRender.ts

@@ -0,0 +1,23 @@
+import { type MutableRefObject, useEffect, useRef } from 'react';
+
+/**
+ * Detects that React is running this component's effects again without a
+ * render in between. That happens on StrictMode's simulated unmount and
+ * remount on the first commit, on Fast Refresh, and when an `Activity`
+ * boundary hides and then shows the component. In each case React runs every
+ * effect's cleanup and then its mount, so a cleanup that sets a flag is
+ * observable from the mounts that follow.
+ *
+ * Returns a ref whose `current` is `true` from the moment the cleanup ran until
+ * the caller resets it. The effect that must tell a re-run apart from a first
+ * mount reads it and sets it back to `false`; nothing else clears it.
+ */
+export function useEffectsRerunWithoutRenderRef(): MutableRefObject<boolean> {
+  const effectsRerunWithoutRenderRef = useRef(false);
+  useEffect(() => {
+    return () => {
+      effectsRerunWithoutRenderRef.current = true;
+    };
+  }, []);
+  return effectsRerunWithoutRenderRef;
+}

package/src/useLazyDisposableState.test.tsx

@@ -1,9 +1,9 @@
 import type { ItemCleanupPair } from '@isograph/disposable-types';
-import React, { useEffect, useState } from 'react';
-import { create } from 'react-test-renderer';
-import { describe, expect, test, vi } from 'vitest';
+import { configure, renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
 import { ParentCache } from './ParentCache';
 import { useLazyDisposableState } from './useLazyDisposableState';
+configure({ reactStrictMode: true });
 
 function createCache<T>(value: T) {
   const disposeItem = vi.fn();
@@ -26,46 +26,85 @@ function promiseWithResolvers() {
 }
 
 describe('useLazyDisposableState', async () => {
-  test('on cache change, it should dispose previous cache', async () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test('on render it should read the cache', async () => {
     const cache1 = createCache(1);
-    const cache2 = createCache(2);
-    const renders = vi.fn();
 
-    let unmounted = promiseWithResolvers();
-    let committed = promiseWithResolvers();
+    const { result } = renderHook(
+      (props) => useLazyDisposableState(props.parentCache),
+      {
+        initialProps: {
+          parentCache: cache1.cache,
+        },
+      },
+    );
 
-    function TestComponent() {
-      const [cache, setCache] = useState(cache1.cache);
-      const { state } = useLazyDisposableState(cache);
+    expect(result.current.state).toEqual(1);
+    expect(cache1.cache.factory).toHaveBeenCalledOnce();
+  });
 
-      useEffect(() => {
-        setCache(cache2.cache);
+  test('on unmount it should dispose the cache', async () => {
+    const cache1 = createCache(1);
 
-        return () => {
-          unmounted.resolve();
-        };
-      }, []);
+    const { unmount } = renderHook(
+      (props) => useLazyDisposableState(props.parentCache),
+      {
+        initialProps: {
+          parentCache: cache1.cache,
+        },
+      },
+    );
 
-      useEffect(() => {
-        if (state === 1) return;
-        committed.resolve();
-      }, [state]);
+    unmount();
+    vi.runAllTimers();
+    expect(cache1.disposeItem).toHaveBeenCalledOnce();
+  });
 
-      renders(state);
+  test('on cache change, it should read new cache', async () => {
+    const cache1 = createCache(1);
+    const cache2 = createCache(2);
 
-      return null;
-    }
+    const { result, rerender, unmount } = renderHook(
+      (props) => useLazyDisposableState(props.parentCache),
+      {
+        initialProps: {
+          parentCache: cache1.cache,
+        },
+      },
+    );
 
-    const root = create(<TestComponent />, { unstable_isConcurrent: true });
-    await committed.promise;
-    expect(cache1.disposeItem).toHaveBeenCalled();
-    expect(cache1.cache.factory).toHaveBeenCalledOnce();
-    root.unmount();
-    await unmounted.promise;
-    expect(cache2.disposeItem).toHaveBeenCalled();
+    rerender({
+      parentCache: cache2.cache,
+    });
+
+    expect(result.current.state).toEqual(2);
     expect(cache2.cache.factory).toHaveBeenCalledOnce();
-    expect(renders).toHaveBeenNthCalledWith(1, 1);
-    expect(renders).toHaveBeenNthCalledWith(2, 2);
-    expect(renders).toHaveBeenCalledTimes(2);
+  });
+
+  test('on cache change, it should dispose previous cache', async () => {
+    const cache1 = createCache(1);
+    const cache2 = createCache(2);
+
+    const { rerender } = renderHook(
+      (props) => useLazyDisposableState(props.parentCache),
+      {
+        initialProps: {
+          parentCache: cache1.cache,
+        },
+      },
+    );
+
+    rerender({
+      parentCache: cache2.cache,
+    });
+
+    vi.runAllTimers();
+    expect(cache1.disposeItem).toHaveBeenCalledOnce();
   });
 });

package/src/useLazyDisposableState.ts

@@ -1,6 +1,6 @@
 'use strict';
 
-import type { ItemCleanupPair } from '@isograph/isograph-disposable-types';
+import type { ItemCleanupPair } from '@isograph/disposable-types';
 import { useEffect, useRef } from 'react';
 import type { ParentCache } from './ParentCache';
 import { useCachedResponsivePrecommitValue } from './useCachedResponsivePrecommitValue';
@@ -21,11 +21,9 @@ export function useLazyDisposableState<T>(
   state: T;
 } {
   const itemCleanupPairRef = useRef<ItemCleanupPair<T> | null>(null);
-
   const preCommitItem = useCachedResponsivePrecommitValue(
     parentCache,
     (pair) => {
-      itemCleanupPairRef.current?.[1]();
       itemCleanupPairRef.current = pair;
     },
   );
@@ -39,9 +37,10 @@ export function useLazyDisposableState<T>(
           'cleanupFn unexpectedly null. This indicates a bug in react-disposable-state.',
         );
       }
-      return cleanupFn();
+      cleanupFn();
+      itemCleanupPairRef.current = null;
     };
-  }, []);
+  }, [parentCache]);
 
   const returnedItem = preCommitItem?.state ?? itemCleanupPairRef.current?.[0];
 

package/src/useUpdatableDisposableClearableState.ts

@@ -0,0 +1,67 @@
+import type { ItemCleanupPair } from '@isograph/disposable-types';
+import { useCallback } from 'react';
+import {
+  UNASSIGNED_STATE,
+  type UnassignedState,
+  useUpdatableDisposableState,
+} from './useUpdatableDisposableState';
+
+type UseUpdatableDisposableClearableStateReturnValue<T> = {
+  state: T | UnassignedState;
+  setState: (pair: ItemCleanupPair<Exclude<T, UnassignedState>>) => void;
+  clearState: () => void;
+};
+
+/**
+ * The item that `clearState` puts in the underlying state. It is never returned
+ * from this hook; the hook reports UNASSIGNED_STATE while it is current.
+ */
+const CLEARED_STATE: unique symbol = Symbol();
+type ClearedState = typeof CLEARED_STATE;
+
+function noop() {}
+
+/**
+ * useUpdatableDisposableClearableState
+ * - useUpdatableDisposableState, plus clearState.
+ * - clearState returns the state to UNASSIGNED_STATE. The item that was in state
+ *   is disposed on the next commit, exactly as if it had been superseded by
+ *   setState.
+ * - Like setState, clearState throws if called before the initial commit.
+ *
+ * This is a wrapper around useUpdatableDisposableState: clearing sets a sentinel
+ * item with no cleanup, so the underlying hook's commit-time disposal of
+ * superseded items disposes the cleared item, and the sentinel is mapped back to
+ * UNASSIGNED_STATE on the way out.
+ */
+export function useUpdatableDisposableClearableState<
+  T = never,
+>(): UseUpdatableDisposableClearableStateReturnValue<T> {
+  const { state, setState } = useUpdatableDisposableState<T | ClearedState>();
+
+  const clearState = useCallback(() => {
+    setState([CLEARED_STATE, noop]);
+  }, [setState]);
+
+  return {
+    clearState,
+    setState,
+    state: state === CLEARED_STATE ? UNASSIGNED_STATE : state,
+  };
+}
+
+// @ts-ignore
+function tsTests() {
+  const a = useUpdatableDisposableClearableState();
+  // @ts-expect-error
+  a.setState([UNASSIGNED_STATE, () => {}]);
+  // @ts-expect-error
+  a.setState(['asdf', () => {}]);
+  const b = useUpdatableDisposableClearableState<string | UnassignedState>();
+  // @ts-expect-error
+  b.setState([UNASSIGNED_STATE, () => {}]);
+  b.setState(['asdf', () => {}]);
+  // The cleared sentinel is not part of T, so it cannot be set from outside.
+  // @ts-expect-error
+  b.setState([CLEARED_STATE, () => {}]);
+}