@isograph/react-disposable-state 0.0.4

package/README.md

@@ -0,0 +1,144 @@
+# `@isograph/react-disposable-state`
+
+> Primitives for managing disposable items in React state.
+
+This library's purpose is to enable safely storing disposable items in React state. These hooks seek to guarantee that **each disposable item is eventually destroyed when it is no longer used** and that **no disposable item is returned from a library hook after it has been disposed**.
+
+This library's goals **do not include** being ergonomic. A library built on top of `react-disposable-state` should expose easier-to-use hooks for common cases. Application developers can use the hooks exposed in `react-disposable-state` when more complicated cases arise.
+
+This is unstable, alpha software. The API is likely to change.
+
+## Conceptual overview
+
+### What is a disposable item?
+
+A disposable item is anything that is either explicitly created or must be explicitly cleaned up. That is, it is an item with a lifecycle.
+
+A disposable item is safe to use as long as its destructor has not been called.
+
+Code that manages disposable items (such as the `useDisposableState` hook) should also ensure that each destructor is eventually called, and should not provide access to the underlying item once the destructor has been called.
+
+Disposable items are allowed to have side effects when created or when destroyed.
+
+### What is disposable state?
+
+Disposable state is React state that contains a disposable item.
+
+### Examples of disposable items
+
+- A subscription that periodically updates a displayed stock price. When the component where the stock price is displayed is unmounted, the subscription should be disposed, so as to avoid doing unproductive work.
+- References to items that are stored externally. For example, consider a centralized store of profile photos. Photos are stored centrally to ensure consistency, meaning that every component displaying a given profile photo displays the same photo. In order to avoid the situation where no profile photo is ever garbage collected, individual components' "claims" to profile photos must be explicitly created and disposed.
+- Items which you want to create **exactly once** when a functional React component is first rendered, such as a network request.
+  - Due to how React behaves, this state must be stored externally. Hence, this can be thought of as an example of the previous bullet point.
+  - Other frameworks make different choices. For example, a SolidJS component function is called exactly once. In these cases, the network request can easily be executed once, without being stored in external state.
+
+### How does disposable state differ from regular React state?
+
+Disposable state stands in contrast to "regular" React state (e.g. if `{isVisible: boolean, currentlySelectedItem: Item}` was stored in state), where
+
+- creating the JavaScript object is the only work done when creating the regular state, and therefore it is okay to create the state multiple times; and
+- the only necessary cleanup work is [garbage collection](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_Management) of the underlying memory.
+
+In particular, it is unobservable to the outside world if a piece of "regular" state is created multiple times.
+
+### Can React primitives handle disposable state?
+
+The primitives provided by React are a poor fit for storing disposable items in state. An upcoming blog post will explore this in more detail.
+
+## This library
+
+### Guarantees
+
+This library guarantees that:
+
+- First, each disposable item that is created is eventually disposed.
+
+  > React and suspense prevent this library from ensuring that each disposable item is disposed immediately when the hook unmounts. Instead, the best we can do if a component suspends is often dispose after a configurable timeout.
+
+- Second, no disposable item is returned from a library hook after it has been disposed.
+- Third, if a component has committed, no disposable item returned from a library hook will be disposed while it is accessible from a mounted component.
+
+  > Colloquially, this means that disposable items returned from library hooks are safe to use in event callbacks.
+
+  > This guarantee is not upheld if an item returned from a library hook is re-stored in another state hook. So, don't do that!
+
+### Supported behaviors
+
+The hooks in this library enable the following behavior:
+
+- Lazily creating a disposable item. In this context, "lazily" means creating the item during the render phase of a component, before that component has committed. The item is then available in the functional component.
+
+  > Note that this is how [Relay](relay.dev) uses the term lazy. Libraries like [react-query](...) use the word lazy differently.
+
+- Creating a disposable item outside of the render phase and after a hook's initial commit and storing the item in React state, making it available during the next render of that functional component.
+
+## API Overview
+
+### `useLazyDisposableState`
+
+A hook that:
+
+- Takes a mutable parent cache and a loader function, and returns a `{ state: T }`.
+- The returned `T` is guaranteed to not be disposed during the tick of the render.
+- If this hook commits, the returned `T` will not be disposed until the component unmounts.
+
+```typescript
+const { state }: { state: T } = useLazyDisposableState<T>(
+  parentCache: ParentCache<T>,
+  factory: Loader<T>,
+  options: ?Options,
+);
+```
+
+### `useUpdatableDisposableState`
+
+A hook that:
+
+- Returns a `{ state, setState }` object.
+- `setState` throws if called before the initial commit.
+- The `state` (a disposable item) is guaranteed to be undisposed during the tick in which it is returned from the hook. It will not be disposed until after it can no longer be returned from this hook, even in the presence of concurrent rendering.
+- Every time the hook commits, a given disposable item is currently exposed in the state. All items previously passed to `setState` are guaranteed to never be returned from the hook, so they are disposed at that time.
+- When the hook unmounts, all disposable items passed to `setState` are disposed.
+
+```typescript
+const {
+  state,
+  setState,
+}: {
+  state: T | null,
+  setState: (ItemCleanupPair<T>) => void,
+} = useUpdatableDisposableState<T>(
+  options: ?Options,
+);
+```
+
+### `useDisposableState`
+
+> This could properly be called `useLazyUpdatableDisposableState`, but that's quite long!
+
+A hook that combines the behavior of the previous two hooks:
+
+```typescript
+const {
+  state,
+  setState,
+}: {
+  state: T,
+  setState: (ItemCleanupPair<T>) => void,
+} = useDisposableState<T>(
+  parentCache: ParentCache<T>,
+  factory: Loader<T>,
+  options: ?Options,
+);
+```
+
+## Miscellaneous notes
+
+### Runtime overhead
+
+- The hooks in this library are generic, and the type of the disposable items `T` is mostly as unconstrained as possible.
+  - The only constraint we impose on `T` is to disallow `T` from including the value `UNASSIGNED_STATE`. This is for primarily for ergonomic purposes. However, it does prevent some runtime overhead.
+- This incurs some runtime overhead. In particular, it means we need to keep track of an index (and create a new short-lived object) to distinguish items that can overthise be `===` to each other. Consider, a component that uses `useDisposableState` or `useUpdatableDiposableState`. If we execute `setState([1, cleanup1])` followed by `setState([1, cleanup2])`, we would expect `cleanup1` to be called when the hook commits. This index is required to distinguish those two, otherwise indistinguishable items.
+  - This problem also occurs if disposable items are re-used, but their cleanup functions are distinct. That can occur if items are shared references held in a reference counted wrapper!
+- However, client libraries may not require this flexbility! For example, if every disposable item is a newly-created object, then all disposable items are `!==` to each other!
+- A future version of this library should expose alternative hooks that disallow `null` and do away with the above check. They may be

package/dist/CacheItem.d.ts

@@ -0,0 +1,54 @@
+import { CleanupFn, Factory, ItemCleanupPair } from "@isograph/disposable-types";
+export type NotInParentCacheAndDisposed = {
+    kind: "NotInParentCacheAndDisposed";
+};
+export type NotInParentCacheAndNotDisposed<T> = {
+    kind: "NotInParentCacheAndNotDisposed";
+    value: T;
+    disposeValue: () => void;
+    permanentRetainCount: number;
+};
+export type InParentCacheAndNotDisposed<T> = {
+    kind: "InParentCacheAndNotDisposed";
+    value: T;
+    disposeValue: () => void;
+    removeFromParentCache: () => void;
+    temporaryRetainCount: number;
+    permanentRetainCount: number;
+};
+export type CacheItemState<T> = InParentCacheAndNotDisposed<T> | NotInParentCacheAndNotDisposed<T> | NotInParentCacheAndDisposed;
+export type CacheItemOptions = {
+    temporaryRetainTime: number;
+};
+/**
+ * - TRC = Temporary Retain Count
+ * - PRC = Permanent Retain Count
+ *
+ * Rules:
+ * - In parent cache <=> TRC > 0
+ * - Removed from parent cache <=> TRC === 0
+ * - In parent cache => not disposed
+ * - Disposed => removed from parent cache + PRC === 0
+ *
+ * A CacheItem<T> can be in three states:
+ * - Removed from the parent cache, item disposed, TRC === 0, PRC === 0
+ * - Removed from the parent cache, item not disposed, PRC > 0, TRC === 0
+ * - In parent cache, item not disposed, TRC > 0, PRC >= 0
+ *
+ * Valid transitions are:
+ * - InParentCacheAndNotDisposed => NotInParentCacheAndNotDisposed
+ * - InParentCacheAndNotDisposed => NotInParentCacheAndDisposed
+ * - NotInParentCacheAndNotDisposed => NotInParentCacheAndDisposed
+ */
+export declare class CacheItem<T> {
+    private __state;
+    private __options;
+    constructor(factory: Factory<T>, removeFromParentCache: CleanupFn, options: CacheItemOptions | void);
+    getValue(): T;
+    permanentRetainIfNotDisposed(disposeOfTemporaryRetain: CleanupFn): ItemCleanupPair<T> | null;
+    temporaryRetain(): CleanupFn;
+    permanentRetain(): CleanupFn;
+    private __maybeExitInParentCacheAndNotDisposedState;
+    private __maybeExitNotInParentCacheAndNotDisposedState;
+}
+export declare function createTemporarilyRetainedCacheItem<T>(factory: Factory<T>, removeFromParentCache: CleanupFn, options: CacheItemOptions | void): [CacheItem<T>, CleanupFn];

package/dist/CacheItem.js

@@ -0,0 +1,265 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTemporarilyRetainedCacheItem = exports.CacheItem = void 0;
+const DEFAULT_TEMPORARY_RETAIN_TIME = 5000;
+// TODO don't export this class, only export type (interface) instead
+// TODO convert cacheitem impl to a getter and setter and free functions
+/**
+ * - TRC = Temporary Retain Count
+ * - PRC = Permanent Retain Count
+ *
+ * Rules:
+ * - In parent cache <=> TRC > 0
+ * - Removed from parent cache <=> TRC === 0
+ * - In parent cache => not disposed
+ * - Disposed => removed from parent cache + PRC === 0
+ *
+ * A CacheItem<T> can be in three states:
+ * - Removed from the parent cache, item disposed, TRC === 0, PRC === 0
+ * - Removed from the parent cache, item not disposed, PRC > 0, TRC === 0
+ * - In parent cache, item not disposed, TRC > 0, PRC >= 0
+ *
+ * Valid transitions are:
+ * - InParentCacheAndNotDisposed => NotInParentCacheAndNotDisposed
+ * - InParentCacheAndNotDisposed => NotInParentCacheAndDisposed
+ * - NotInParentCacheAndNotDisposed => NotInParentCacheAndDisposed
+ */
+class CacheItem {
+    // Private. Do not call this constructor directly. Use
+    // createTemporarilyRetainedCacheItem instead. This is because this
+    // constructor creates a CacheItem in an invalid state. It must be
+    // temporarily retained to enter a valid state, and JavaScript doesn't
+    // let you return a tuple from a constructor.
+    constructor(factory, removeFromParentCache, options) {
+        this.__options = options !== null && options !== void 0 ? options : null;
+        const [value, disposeValue] = factory();
+        this.__state = {
+            kind: "InParentCacheAndNotDisposed",
+            value,
+            disposeValue,
+            removeFromParentCache,
+            // NOTE: we are creating the CacheItem in an invalid state. This is okay, because
+            // we are immediately calling .temporaryRetain.
+            temporaryRetainCount: 0,
+            permanentRetainCount: 0,
+        };
+    }
+    getValue() {
+        switch (this.__state.kind) {
+            case "InParentCacheAndNotDisposed": {
+                return this.__state.value;
+            }
+            case "NotInParentCacheAndNotDisposed": {
+                return this.__state.value;
+            }
+            default: {
+                throw new Error("Attempted to access disposed value from CacheItem. " +
+                    "This indicates a bug in react-disposable-state.");
+            }
+        }
+    }
+    permanentRetainIfNotDisposed(disposeOfTemporaryRetain) {
+        switch (this.__state.kind) {
+            case "InParentCacheAndNotDisposed": {
+                let cleared = false;
+                this.__state.permanentRetainCount++;
+                disposeOfTemporaryRetain();
+                return [
+                    this.__state.value,
+                    () => {
+                        if (cleared) {
+                            throw new Error("A permanent retain should only be cleared once. " +
+                                "This indicates a bug in react-disposable-state.");
+                        }
+                        cleared = true;
+                        switch (this.__state.kind) {
+                            case "InParentCacheAndNotDisposed": {
+                                this.__state.permanentRetainCount--;
+                                this.__maybeExitInParentCacheAndNotDisposedState(this.__state);
+                                return;
+                            }
+                            case "NotInParentCacheAndNotDisposed": {
+                                this.__state.permanentRetainCount--;
+                                this.__maybeExitNotInParentCacheAndNotDisposedState(this.__state);
+                                return;
+                            }
+                            default: {
+                                throw new Error("CacheItem was in a disposed state, but there existed a permanent retain. " +
+                                    "This indicates a bug in react-disposable-state.");
+                            }
+                        }
+                    },
+                ];
+            }
+            case "NotInParentCacheAndNotDisposed": {
+                let cleared = false;
+                this.__state.permanentRetainCount++;
+                disposeOfTemporaryRetain();
+                return [
+                    this.__state.value,
+                    () => {
+                        if (cleared) {
+                            throw new Error("A permanent retain should only be cleared once. " +
+                                "This indicates a bug in react-disposable-state.");
+                        }
+                        cleared = true;
+                        switch (this.__state.kind) {
+                            case "NotInParentCacheAndNotDisposed": {
+                                this.__state.permanentRetainCount--;
+                                this.__maybeExitNotInParentCacheAndNotDisposedState(this.__state);
+                                return;
+                            }
+                            default: {
+                                throw new Error("CacheItem was in an unexpected state. " +
+                                    "This indicates a bug in react-disposable-state.");
+                            }
+                        }
+                    },
+                ];
+            }
+            default: {
+                // The CacheItem is disposed, so disposeOfTemporaryRetain is a no-op
+                return null;
+            }
+        }
+    }
+    temporaryRetain() {
+        var _a, _b;
+        switch (this.__state.kind) {
+            case "InParentCacheAndNotDisposed": {
+                let status = "Uncleared";
+                this.__state.temporaryRetainCount++;
+                const clearTemporaryRetainByCallack = () => {
+                    if (status === "ClearedByCallback") {
+                        throw new Error("A temporary retain should only be cleared once. " +
+                            "This indicates a bug in react-disposable-state.");
+                    }
+                    else if (status === "Uncleared") {
+                        switch (this.__state.kind) {
+                            case "InParentCacheAndNotDisposed": {
+                                this.__state.temporaryRetainCount--;
+                                this.__maybeExitInParentCacheAndNotDisposedState(this.__state);
+                                clearTimeout(timeoutId);
+                                return;
+                            }
+                            default: {
+                                throw new Error("A temporary retain was cleared, for which the CacheItem is in an invalid state. " +
+                                    "This indicates a bug in react-disposable-state.");
+                            }
+                        }
+                    }
+                };
+                const clearTemporaryRetainByTimeout = () => {
+                    status = "ClearedByTimeout";
+                    switch (this.__state.kind) {
+                        case "InParentCacheAndNotDisposed": {
+                            this.__state.temporaryRetainCount--;
+                            this.__maybeExitInParentCacheAndNotDisposedState(this.__state);
+                            return;
+                        }
+                        default: {
+                            throw new Error("A temporary retain was cleared, for which the CacheItem is in an invalid state. " +
+                                "This indicates a bug in react-disposable-state.");
+                        }
+                    }
+                };
+                const timeoutId = setTimeout(clearTemporaryRetainByTimeout, (_b = (_a = this.__options) === null || _a === void 0 ? void 0 : _a.temporaryRetainTime) !== null && _b !== void 0 ? _b : DEFAULT_TEMPORARY_RETAIN_TIME);
+                return clearTemporaryRetainByCallack;
+            }
+            default: {
+                throw new Error("temporaryRetain was called, for which the CacheItem is in an invalid state. " +
+                    "This indicates a bug in react-disposable-state.");
+            }
+        }
+    }
+    permanentRetain() {
+        switch (this.__state.kind) {
+            case "InParentCacheAndNotDisposed": {
+                let cleared = false;
+                this.__state.permanentRetainCount++;
+                return () => {
+                    if (cleared) {
+                        throw new Error("A permanent retain should only be cleared once. " +
+                            "This indicates a bug in react-disposable-state.");
+                    }
+                    cleared = true;
+                    switch (this.__state.kind) {
+                        case "InParentCacheAndNotDisposed": {
+                            this.__state.permanentRetainCount--;
+                            this.__maybeExitInParentCacheAndNotDisposedState(this.__state);
+                            return;
+                        }
+                        case "NotInParentCacheAndNotDisposed": {
+                            this.__state.permanentRetainCount--;
+                            this.__maybeExitNotInParentCacheAndNotDisposedState(this.__state);
+                            return;
+                        }
+                        default: {
+                            throw new Error("CacheItem was in a disposed state, but there existed a permanent retain. " +
+                                "This indicates a bug in react-disposable-state.");
+                        }
+                    }
+                };
+            }
+            case "NotInParentCacheAndNotDisposed": {
+                let cleared = false;
+                this.__state.permanentRetainCount++;
+                return () => {
+                    if (cleared) {
+                        throw new Error("A permanent retain should only be cleared once. " +
+                            "This indicates a bug in react-disposable-state.");
+                    }
+                    cleared = true;
+                    switch (this.__state.kind) {
+                        case "NotInParentCacheAndNotDisposed": {
+                            this.__state.permanentRetainCount--;
+                            this.__maybeExitNotInParentCacheAndNotDisposedState(this.__state);
+                            return;
+                        }
+                        default: {
+                            throw new Error("CacheItem was in an unexpected state. " +
+                                "This indicates a bug in react-disposable-state.");
+                        }
+                    }
+                };
+            }
+            default: {
+                throw new Error("permanentRetain was called, but the CacheItem is in an invalid state. " +
+                    "This indicates a bug in react-disposable-state.");
+            }
+        }
+    }
+    __maybeExitInParentCacheAndNotDisposedState(state) {
+        if (state.temporaryRetainCount === 0 && state.permanentRetainCount === 0) {
+            state.removeFromParentCache();
+            state.disposeValue();
+            this.__state = {
+                kind: "NotInParentCacheAndDisposed",
+            };
+        }
+        else if (state.temporaryRetainCount === 0) {
+            state.removeFromParentCache();
+            this.__state = {
+                kind: "NotInParentCacheAndNotDisposed",
+                value: state.value,
+                disposeValue: state.disposeValue,
+                permanentRetainCount: state.permanentRetainCount,
+            };
+        }
+    }
+    __maybeExitNotInParentCacheAndNotDisposedState(state) {
+        if (state.permanentRetainCount === 0) {
+            state.disposeValue();
+            this.__state = {
+                kind: "NotInParentCacheAndDisposed",
+            };
+        }
+    }
+}
+exports.CacheItem = CacheItem;
+function createTemporarilyRetainedCacheItem(factory, removeFromParentCache, options) {
+    const cacheItem = new CacheItem(factory, removeFromParentCache, options);
+    const disposeTemporaryRetain = cacheItem.temporaryRetain();
+    return [cacheItem, disposeTemporaryRetain];
+}
+exports.createTemporarilyRetainedCacheItem = createTemporarilyRetainedCacheItem;

package/dist/ParentCache.d.ts

@@ -0,0 +1,39 @@
+import { CacheItem } from "./CacheItem";
+import { CleanupFn, Factory, ItemCleanupPair } from "@isograph/disposable-types";
+/**
+ * ParentCache
+ * - A ParentCache can be in two states: populated and unpopulated.
+ * - A ParentCache holds a CacheItem, which can choose to remove itself from
+ *   the parent ParentCache.
+ * - If the ParentCache is populated, the CacheItem (i.e. this.__value) must be
+ *   in the InParentCacheAndNotDisposed state, i.e. not disposed, so after we
+ *   null-check this.__value, this.__value.getValue(), this.__value.temporaryRetain()
+ *   and this.__value.permanentRetain() are safe to be called.
+ *
+ * - Though we do not do so, it is always safe to call parentCache.delete().
+ *
+ * Invariant:
+ * - A parent cache at a given "location" (conceptually, an ID) should always
+ *   be called
+ */
+export declare class ParentCache<T> {
+    private __cacheItem;
+    private readonly __factory;
+    constructor(factory: Factory<T>);
+    /**
+     * This is called from useCachedPrecommitValue, when the parent cache is populated
+     * and a previous temporary retain has been disposed. This can occur in scenarios like:
+     * - temporary retain A is created by component B rendering
+     * - temporary retain A expires, emptying the parent cache
+     * - another component renders, sharing the same parent cache, filling
+     *   by calling getOrPopulateAndTemporaryRetain
+     * - component B commits. We see that temporary retain A has been disposed,
+     *   and re-check the parent cache by calling this method.
+     */
+    getAndPermanentRetainIfPresent(): ItemCleanupPair<T> | null;
+    getOrPopulateAndTemporaryRetain(): [CacheItem<T>, T, CleanupFn];
+    private __populateAndTemporaryRetain;
+    empty(): void;
+    get factory(): Factory<T>;
+    isEmpty(): boolean;
+}

package/dist/ParentCache.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParentCache = void 0;
+const CacheItem_1 = require("./CacheItem");
+// TODO convert cache impl to a getter and setter and free functions
+// TODO accept options that get passed to CacheItem
+/**
+ * ParentCache
+ * - A ParentCache can be in two states: populated and unpopulated.
+ * - A ParentCache holds a CacheItem, which can choose to remove itself from
+ *   the parent ParentCache.
+ * - If the ParentCache is populated, the CacheItem (i.e. this.__value) must be
+ *   in the InParentCacheAndNotDisposed state, i.e. not disposed, so after we
+ *   null-check this.__value, this.__value.getValue(), this.__value.temporaryRetain()
+ *   and this.__value.permanentRetain() are safe to be called.
+ *
+ * - Though we do not do so, it is always safe to call parentCache.delete().
+ *
+ * Invariant:
+ * - A parent cache at a given "location" (conceptually, an ID) should always
+ *   be called
+ */
+class ParentCache {
+    constructor(factory) {
+        this.__cacheItem = null;
+        this.__factory = factory;
+    }
+    /**
+     * This is called from useCachedPrecommitValue, when the parent cache is populated
+     * and a previous temporary retain has been disposed. This can occur in scenarios like:
+     * - temporary retain A is created by component B rendering
+     * - temporary retain A expires, emptying the parent cache
+     * - another component renders, sharing the same parent cache, filling
+     *   by calling getOrPopulateAndTemporaryRetain
+     * - component B commits. We see that temporary retain A has been disposed,
+     *   and re-check the parent cache by calling this method.
+     */
+    getAndPermanentRetainIfPresent() {
+        return this.__cacheItem != null
+            ? [this.__cacheItem.getValue(), this.__cacheItem.permanentRetain()]
+            : null;
+    }
+    getOrPopulateAndTemporaryRetain() {
+        return this.__cacheItem === null
+            ? this.__populateAndTemporaryRetain()
+            : temporaryRetain(this.__cacheItem);
+    }
+    __populateAndTemporaryRetain() {
+        const pair = (0, CacheItem_1.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();
+            }
+        });
+        // 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.
+        const [cacheItem, disposeTemporaryRetain] = pair;
+        this.__cacheItem = cacheItem;
+        return [cacheItem, this.__cacheItem.getValue(), disposeTemporaryRetain];
+    }
+    empty() {
+        this.__cacheItem = null;
+    }
+    get factory() {
+        return this.__factory;
+    }
+    isEmpty() {
+        return this.__cacheItem === null;
+    }
+}
+exports.ParentCache = ParentCache;
+function temporaryRetain(value) {
+    return [value, value.getValue(), value.temporaryRetain()];
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "@isograph/disposable-types";
+export * from "./CacheItem";
+export * from "./ParentCache";
+export * from "./useCachedPrecommitValue";
+export * from "./useDisposableState";
+export * from "./useHasCommittedRef";
+export * from "./useLazyDisposableState";
+export * from "./useUpdatableDisposableState";

package/dist/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("@isograph/disposable-types"), exports);
+__exportStar(require("./CacheItem"), exports);
+__exportStar(require("./ParentCache"), exports);
+__exportStar(require("./useCachedPrecommitValue"), exports);
+__exportStar(require("./useDisposableState"), exports);
+__exportStar(require("./useHasCommittedRef"), exports);
+__exportStar(require("./useLazyDisposableState"), exports);
+__exportStar(require("./useUpdatableDisposableState"), exports);

package/dist/useCachedPrecommitValue.d.ts

@@ -0,0 +1,36 @@
+import { ParentCache } from "./ParentCache";
+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 declare function useCachedPrecommitValue<T>(parentCache: ParentCache<T>, onCommit: (pair: ItemCleanupPair<T>) => void): {
+    state: T;
+} | null;