@isograph/react-disposable-state 0.0.4

package/dist/useCachedPrecommitValue.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCachedPrecommitValue = void 0;
+const react_1 = require("react");
+const useHasCommittedRef_1 = require("./useHasCommittedRef");
+/**
+ * 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.
+ */
+function useCachedPrecommitValue(parentCache, onCommit) {
+    // 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] = (0, react_1.useState)(null);
+    (0, react_1.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 = (0, useHasCommittedRef_1.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 };
+}
+exports.useCachedPrecommitValue = useCachedPrecommitValue;

package/dist/useDisposableState.d.ts

@@ -0,0 +1,9 @@
+import { ParentCache } from "./ParentCache";
+import { ItemCleanupPair } from "@isograph/disposable-types";
+import { UnassignedState } from "./useUpdatableDisposableState";
+type UseUpdatableDisposableStateReturnValue<T> = {
+    state: T;
+    setState: (pair: ItemCleanupPair<Exclude<T, UnassignedState>>) => void;
+};
+export declare function useDisposableState<T = never>(parentCache: ParentCache<T>): UseUpdatableDisposableStateReturnValue<T>;
+export {};

package/dist/useDisposableState.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDisposableState = void 0;
+const react_1 = require("react");
+const useCachedPrecommitValue_1 = require("./useCachedPrecommitValue");
+const useUpdatableDisposableState_1 = require("./useUpdatableDisposableState");
+function useDisposableState(parentCache) {
+    var _a, _b, _c;
+    const itemCleanupPairRef = (0, react_1.useRef)(null);
+    const preCommitItem = (0, useCachedPrecommitValue_1.useCachedPrecommitValue)(parentCache, (pair) => {
+        itemCleanupPairRef.current = pair;
+    });
+    const { state: stateFromDisposableStateHook, setState } = (0, useUpdatableDisposableState_1.useUpdatableDisposableState)();
+    (0, react_1.useEffect)(function cleanupItemCleanupPairRefAfterSetState() {
+        if (stateFromDisposableStateHook !== useUpdatableDisposableState_1.UNASSIGNED_STATE) {
+            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]);
+    (0, react_1.useEffect)(function cleanupItemCleanupPairRefIfSetStateNotCalled() {
+        return () => {
+            if (itemCleanupPairRef.current !== null) {
+                itemCleanupPairRef.current[1]();
+                itemCleanupPairRef.current = null;
+            }
+        };
+    }, []);
+    // 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
+    // after setState has been called, in which case
+    // stateFromDisposableStateHook is assigned.
+    //
+    // Therefore, the type of state is T, not T | undefined. But the fact
+    // that we are in one of the three states is not reflected in the types.
+    // So we have to cast to T.
+    //
+    // Note that in the post-commit post-setState state, itemCleanupPairRef
+    // can still be assigned, during the render before the
+    // cleanupItemCleanupPairRefAfterSetState effect is called.
+    const state = (_c = (_a = (stateFromDisposableStateHook != useUpdatableDisposableState_1.UNASSIGNED_STATE
+        ? stateFromDisposableStateHook
+        : null)) !== null && _a !== void 0 ? _a : (_b = itemCleanupPairRef.current) === null || _b === void 0 ? void 0 : _b[0]) !== null && _c !== void 0 ? _c : preCommitItem === null || preCommitItem === void 0 ? void 0 : preCommitItem.state;
+    return {
+        state: state,
+        setState,
+    };
+}
+exports.useDisposableState = useDisposableState;
+// @ts-ignore
+function tsTests() {
+    let x;
+    const a = useDisposableState(x);
+    // @ts-expect-error
+    a.setState(["asdf", () => { }]);
+    // @ts-expect-error
+    a.setState([useUpdatableDisposableState_1.UNASSIGNED_STATE, () => { }]);
+    const b = useDisposableState(x);
+    // @ts-expect-error
+    b.setState([useUpdatableDisposableState_1.UNASSIGNED_STATE, () => { }]);
+    b.setState(["asdf", () => { }]);
+}

package/dist/useHasCommittedRef.d.ts

@@ -0,0 +1,5 @@
+import { MutableRefObject } from "react";
+/**
+ * Returns true if the component has committed, false otherwise.
+ */
+export declare function useHasCommittedRef(): MutableRefObject<boolean>;

package/dist/useHasCommittedRef.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useHasCommittedRef = void 0;
+const react_1 = require("react");
+/**
+ * Returns true if the component has committed, false otherwise.
+ */
+function useHasCommittedRef() {
+    const hasCommittedRef = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        hasCommittedRef.current = true;
+    }, []);
+    return hasCommittedRef;
+}
+exports.useHasCommittedRef = useHasCommittedRef;

package/dist/useLazyDisposableState.d.ts

@@ -0,0 +1,13 @@
+import { ParentCache } from "./ParentCache";
+/**
+ * useLazyDisposableState<T>
+ * - Takes a mutable parent cache and a factory function
+ * - Returns { state: T }
+ *
+ * This lazily loads the disposable item using useCachedPrecommitValue, then
+ * (on commit) sets it in state. The item continues to be returned after
+ * commit and is disposed when the hook unmounts.
+ */
+export declare function useLazyDisposableState<T>(parentCache: ParentCache<T>): {
+    state: T;
+};

package/dist/useLazyDisposableState.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useLazyDisposableState = void 0;
+const react_1 = require("react");
+const useCachedPrecommitValue_1 = require("./useCachedPrecommitValue");
+/**
+ * useLazyDisposableState<T>
+ * - Takes a mutable parent cache and a factory function
+ * - Returns { state: T }
+ *
+ * This lazily loads the disposable item using useCachedPrecommitValue, then
+ * (on commit) sets it in state. The item continues to be returned after
+ * commit and is disposed when the hook unmounts.
+ */
+function useLazyDisposableState(parentCache) {
+    var _a, _b;
+    const itemCleanupPairRef = (0, react_1.useRef)(null);
+    const preCommitItem = (0, useCachedPrecommitValue_1.useCachedPrecommitValue)(parentCache, (pair) => {
+        itemCleanupPairRef.current = pair;
+    });
+    (0, react_1.useEffect)(() => {
+        var _a;
+        const cleanupFn = (_a = itemCleanupPairRef.current) === null || _a === void 0 ? void 0 : _a[1];
+        // TODO confirm useEffect is called in order.
+        if (cleanupFn == null) {
+            throw new Error("cleanupFn unexpectedly null. This indicates a bug in react-disposable-state.");
+        }
+        return cleanupFn;
+    }, []);
+    const returnedItem = (_a = preCommitItem === null || preCommitItem === void 0 ? void 0 : preCommitItem.state) !== null && _a !== void 0 ? _a : (_b = itemCleanupPairRef.current) === null || _b === void 0 ? void 0 : _b[0];
+    if (returnedItem != null) {
+        return { state: returnedItem };
+    }
+    // Safety: This can't happen. For renders before the initial commit, preCommitItem
+    // is non-null. During the initial commit, we assign itemCleanupPairRef.current,
+    // so during subsequent renders, itemCleanupPairRef.current is non-null.
+    throw new Error("returnedItem was unexpectedly null. This indicates a bug in react-disposable-state.");
+}
+exports.useLazyDisposableState = useLazyDisposableState;

package/dist/useUpdatableDisposableState.d.ts

@@ -0,0 +1,39 @@
+import { ItemCleanupPair } from "@isograph/disposable-types";
+export declare const UNASSIGNED_STATE: unique symbol;
+export type UnassignedState = typeof UNASSIGNED_STATE;
+type UseUpdatableDisposableStateReturnValue<T> = {
+    state: T | UnassignedState;
+    setState: (pair: ItemCleanupPair<Exclude<T, UnassignedState>>) => void;
+};
+/**
+ * useUpdatableDisposableState
+ * - Returns a { state, setItem } object.
+ * - setItem accepts an ItemCleanupPair<T>, and throws if called before commit.
+ * - setItem sets the T in state and adds it to a set.
+ * - React's behavior is that when the hook commits, whatever item is currently
+ *   returned from the useState hook is the oldest item which will ever be returned
+ *   from that useState hook. (More newly created ones can later be returned with
+ *   concurrent mode.)
+ * - When this hook commits, all items up to, but not including, the item currently
+ *   returned from the useState hook are disposed and removed from the set.
+ *
+ * Calling setState before the hook commits:
+ * - Calling setState before the hook commits is disallowed because until the hook
+ *   commits, React will not schedule any unmount callbacks, meaning that if this
+ *   hook never commits, any disposable items passed to setState will never be
+ *   disposed.
+ * - We also cannot store them in some cache, because multiple components can share
+ *   the same cache location (for example, if they are loading the same query from
+ *   multiple components), so updating the cache with the disposable item will cause
+ *   both components to show the updated data, which is almost certainly a bug.
+ * - Note that calling setState before commit is probably an anti-pattern! Consider
+ *   not doing it.
+ * - If you must, the workaround is to lazily load the disposable item with
+ *   useDisposableState or useLazyDisposableState, and update the cache location
+ *   instead of calling setState before commit. One can update the cache location
+ *   by calling setState on some parent component that has already mounted, and
+ *   therefore passing in different props.
+ *   - This may only work in concurrent mode, though.
+ */
+export declare function useUpdatableDisposableState<T = never>(): UseUpdatableDisposableStateReturnValue<T>;
+export {};

package/dist/useUpdatableDisposableState.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useUpdatableDisposableState = exports.UNASSIGNED_STATE = void 0;
+const react_1 = require("react");
+const useHasCommittedRef_1 = require("./useHasCommittedRef");
+exports.UNASSIGNED_STATE = Symbol();
+/**
+ * useUpdatableDisposableState
+ * - Returns a { state, setItem } object.
+ * - setItem accepts an ItemCleanupPair<T>, and throws if called before commit.
+ * - setItem sets the T in state and adds it to a set.
+ * - React's behavior is that when the hook commits, whatever item is currently
+ *   returned from the useState hook is the oldest item which will ever be returned
+ *   from that useState hook. (More newly created ones can later be returned with
+ *   concurrent mode.)
+ * - When this hook commits, all items up to, but not including, the item currently
+ *   returned from the useState hook are disposed and removed from the set.
+ *
+ * Calling setState before the hook commits:
+ * - Calling setState before the hook commits is disallowed because until the hook
+ *   commits, React will not schedule any unmount callbacks, meaning that if this
+ *   hook never commits, any disposable items passed to setState will never be
+ *   disposed.
+ * - We also cannot store them in some cache, because multiple components can share
+ *   the same cache location (for example, if they are loading the same query from
+ *   multiple components), so updating the cache with the disposable item will cause
+ *   both components to show the updated data, which is almost certainly a bug.
+ * - Note that calling setState before commit is probably an anti-pattern! Consider
+ *   not doing it.
+ * - If you must, the workaround is to lazily load the disposable item with
+ *   useDisposableState or useLazyDisposableState, and update the cache location
+ *   instead of calling setState before commit. One can update the cache location
+ *   by calling setState on some parent component that has already mounted, and
+ *   therefore passing in different props.
+ *   - This may only work in concurrent mode, though.
+ */
+function useUpdatableDisposableState() {
+    const hasCommittedRef = (0, useHasCommittedRef_1.useHasCommittedRef)();
+    const undisposedICIs = (0, react_1.useRef)(new Set());
+    const setStateCountRef = (0, react_1.useRef)(0);
+    const [stateICI, setStateICI] = (0, react_1.useState)(exports.UNASSIGNED_STATE);
+    const setStateAfterCommit = (0, react_1.useCallback)((itemCleanupPair) => {
+        if (!hasCommittedRef.current) {
+            throw new Error("Calling setState before the component has committed is unsafe and disallowed.");
+        }
+        const ici = {
+            item: itemCleanupPair[0],
+            cleanup: itemCleanupPair[1],
+            index: setStateCountRef.current,
+        };
+        setStateCountRef.current++;
+        undisposedICIs.current.add(ici);
+        setStateICI(ici);
+    }, [setStateICI]);
+    (0, react_1.useEffect)(function cleanupUnreachableItems() {
+        const indexInState = stateICI !== exports.UNASSIGNED_STATE ? stateICI.index : 0;
+        if (indexInState === 0) {
+            return;
+        }
+        for (const undisposedICI of undisposedICIs.current) {
+            if (undisposedICI.index === indexInState) {
+                break;
+            }
+            undisposedICIs.current.delete(undisposedICI);
+            undisposedICI.cleanup();
+        }
+    });
+    (0, react_1.useEffect)(() => {
+        return function disposeAllRemainingItems() {
+            for (const undisposedICI of undisposedICIs.current) {
+                undisposedICI.cleanup();
+            }
+        };
+    }, []);
+    return {
+        setState: setStateAfterCommit,
+        state: stateICI !== exports.UNASSIGNED_STATE ? stateICI.item : exports.UNASSIGNED_STATE,
+    };
+}
+exports.useUpdatableDisposableState = useUpdatableDisposableState;
+// @ts-ignore
+function tsTests() {
+    const a = useUpdatableDisposableState();
+    // @ts-expect-error
+    a.setState([exports.UNASSIGNED_STATE, () => { }]);
+    // @ts-expect-error
+    a.setState(["asdf", () => { }]);
+    const b = useUpdatableDisposableState();
+    // @ts-expect-error
+    b.setState([exports.UNASSIGNED_STATE, () => { }]);
+    b.setState(["asdf", () => { }]);
+}

package/docs/managing-complex-state.md

@@ -0,0 +1,151 @@
+# Using `react-disposable-state` and `reference-counted-pointer` to manage complicated state.
+
+When managing more complicated state, such as an array of disposable items, we often do not want to dispose all of the previous state when creating new state.
+
+For example, if our state goes from `[item1]` to `[item1, item2]`, it would be inefficient to dispose `item1` and re-create it. If the disposable item represents something like a network request, this may not even be possible!
+
+In situations like this, we can wrap each item in a reference counted pointer. Then, when the state changes to `[item1, item2]` (actually from `[activeReferenceToItem1]` to `[activeReferenceToItem1, activeReferenceToItem2]`), then because there is always at least one undisposed active reference to `item1`, the underlying item is not disposed, and we do not need to recreate the item from scratch.
+
+## Example
+
+Consider using `useUpdatableDisposableState` state to manage an array of disposable items.
+
+The behavior of `useUpdatableDisposableState` is to entirely dispose of all previously-held items after a new item is set in state. So, if we had
+
+```js
+const { state, setState } = useUpdatableDisposableState();
+// assume state === [item1], and the cleanup function will dispose item1
+
+const addItem2ToState = () => {
+  setState([item1, item2], () => {
+    disposeItem1();
+    disposeItem2();
+  });
+};
+
+return makePrettyJSX(state[0]);
+```
+
+In the above, `item1` would be disposed after the state was updated to be `[item1, item2]`. Meaning, the hook returns an item that has already been disposed. Clearly, this will not do.
+
+## Alternatives
+
+- We can re-create `item1` in `addItem2ToState`. This is costly, and not possible in all cases.
+- We can store a mutable array in state, and dispose all items when the component unmounts. This is inefficient or unergonomic. Either:
+  - we never remove items from the array, meaning we inefficiently only clean up items when the component unmounts, or
+  - we dispose the items ourselves when we remove them. This is not ergonomic, and also means that the hook will likely misbehave in concurrent mode.
+- Or, we can wrap each item in a reference counted pointer.
+
+## Reference counted pointers
+
+A reference counted pointer is an object that wraps a disposable item, and keeps track of all active references to that item. When all active references have been removed, the item itself is disposed.
+
+Given an undisposed active reference `r1`, one can get a new active reference `r2` and a cleanup function `cleanupR2` by cloning `r1`. If `r1`'s cleanup function is called, it will appear disposed, but the underlying item will not be disposed until all remaining cleanup functions are called. In particular, this means that `cleanupR2` must be called before the underlying item is disposed.
+
+> `CacheItem<T>` is form of a reference counted pointer! Though, it's behavior is slightly different than what is described here.
+
+> Note that in practice, you will never actually access the "original reference counted pointer". Instead, a properly designed API will simply return an active reference.
+
+## Using reference counted pointers in the example
+
+Let's use reference counted pointers in the example.
+
+```js
+const { state, setState } = useUpdatableDisposableState();
+// assume state === [item1activeReference], and the cleanup function will dispose that active reference
+
+const addItem2ToState = () => {
+  const [item2, disposeItem2] = createDisposeItem2();
+  const [item2ActiveReference, disposeItem2ActiveReference] =
+    createReferenceCountedPointer([item2, disposeItem2]);
+
+  // get a new active reference to the existing item1
+  const [item1ActiveReference, disposeItem1ActiveReference] = nullthrows(
+    state[0].cloneIfNotDisposed()
+  );
+  setState([item1ActiveReference, item2ActiveReference], () => {
+    disposeItem1ActiveReference();
+    disposeItem2ActiveReference();
+  });
+};
+
+return makePrettyJSX(nullthrows(state[0].getItemIfNotDisposed()));
+```
+
+Not the most ergonomic, but it does the job.
+
+### When `item2` is added to state:
+
+Let's discuss what happens with `item1` when we call `addItem2ToState`:
+
+- First, a new active reference is created from the previous active reference to `item1`.
+- Next, this item is set in state.
+- When that state commits, the previous state's dispose function is called. This cleans up the first active reference to `item1`. However, because there is an undisposed active reference to `item1` (created during `addItem2ToState`), the item itself is not disposed.
+- On subsequent renders, `item1` is still safe to access.
+- When the component unmounts, the item in state is disposed. At this point, all remaining active references to `item1` will be disposed, and the item itself will be disposed.
+
+### When `item2` is removed from state:
+
+Let's discuss what happens to `item2` if we removed `item2` from state with the following:
+
+```js
+const removeItem2FromState = () => {
+  // assume state === [activeReferenceToItem1, activeReferenceToItem2]
+
+  // get a new active reference to the existing item1
+  const [item1ActiveReference, disposeItem1ActiveReference] = nullthrows(
+    state[0].cloneIfNotDisposed()
+  );
+  setState([item1ActiveReference], () => {
+    disposeItem1ActiveReference();
+  });
+};
+```
+
+- First, the new item is set in state.
+- When the hook commits, it runs the previous dispose function. This disposes the active reference to `item2` created in `addItem2ToState`. Since there are no undisposed active references to `item2`, the underlying item is disposed.
+
+Awesome!
+
+## Does this work with concurrent mode?
+
+Yes! `useDisposableState` and `useUpdatableDisposableState` are compatible with concurrent mode.
+
+## Ergonomics
+
+Unfortunately, reference counted pointers have worse DevEx than hooks.
+
+Libraries built off of `react-disposable-state` and `reference-counted-pointers` may choose to expose more ergonomic hooks for application developers to use.
+
+(In particular, it would probably be a hook's responsibility to call `nullthrows`, improving DevEx slighly. A properly written hook will not expose disposed items.)
+
+Though, developers that want to precisely and correctly model application state may need to reach for the lower-level hooks.
+
+## When should you use reference counted pointers to manage disposable state?
+
+Reference counted pointers are useful when you want structural sharing. Strutural sharing means that when your component transitions from `state1` to `state2`, the part of the states that is in common should not be disposed.
+
+For example:
+
+- Adding and removing items from an array or an object
+- Re-using the same disposable item, but modifying other parts of state. Consider the state:
+
+  ```ts
+  type MyState =
+    | {
+        kind: "ConnectedToDatabase";
+        connectionToDatabase: ConnectionToDatabase;
+        currentUserId: number;
+      }
+    | {
+        kind: "DisconnectedFromDatabase";
+      };
+  ```
+
+  When we change the `currentUserId`, we should not dispose and re-create the database connection! So, the database connection should be managed by a reference counted pointer.
+
+  However, we also should not model this state as two pieces of state: an optional `ConnectionToDatabase` and an optional `currentUserId`, as that would allow us to have a user id but no connection, or a connection and no user id. (We are following the canonical rule: _Make impossible states unrepresentable_.)
+
+- An external cache. Consider a cache that might cache the results of network requests, and a user who navigates to an item detail page, navigates away, and navigates back. If the item is still in the cache when the user navigates back, we can avoid an expensive network request.
+  - For this to work, the external cache might, instead of disposing the results of the network request, create a reference-counted pointer that is disposed after five minutes. If the user navigates back before the five minutes, they will be able to re-use the results.
+  - This is similar to how `CacheItem` works!

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@isograph/react-disposable-state",
+  "version": "0.0.4",
+  "description": "Primitives for managing disposable state in React",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "author": "Isograph Labs",
+  "license": "MIT",
+  "scripts": {
+    "compile": "rm -rf dist/* && tsc -p tsconfig.pkg.json",
+    "compile-watch": "tsc -p tsconfig.pkg.json --watch",
+    "test": "vitest run",
+    "test-watch": "vitest watch",
+    "coverage": "vitest run --coverage",
+    "note": "WE SHOULD ALSO TEST HERE",
+    "prepack": "yarn run compile"
+  },
+  "dependencies": {
+    "@isograph/disposable-types": "0.0.4",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.31",
+    "react-test-renderer": "^18.2.0",
+    "vitest": "^0.29.8",
+    "typescript": "^5.0.3"
+  }
+}