@isograph/react-disposable-state 0.0.0-main-54f75b55 → 0.0.0-main-36b092bd

package/.turbo/turbo-compile-libs.log

@@ -1,11 +1,11 @@
 ../..                                    |  WARN  Unsupported engine: wanted: {"node":"24.12.0"} (current: {"node":"v24.21.0","pnpm":"10.15.0"})
 
-> @isograph/react-disposable-state@0.0.0-main-54f75b55 compile-libs /home/runner/work/isograph/isograph/libs/isograph-react-disposable-state
+> @isograph/react-disposable-state@0.0.0-main-36b092bd compile-libs /home/runner/work/isograph/isograph/libs/isograph-react-disposable-state
 > tsdown
 
 ℹ tsdown v0.20.1 powered by rolldown v1.0.0-rc.1
 ℹ config file: /home/runner/work/isograph/isograph/tsdown.config.ts 
-(node:2791) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///home/runner/work/isograph/isograph/tsdown.config.ts?no-cache=206d8011-1532-4f75-9b2e-174ab111541e is not specified and it doesn't parse as CommonJS.
+(node:2909) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///home/runner/work/isograph/isograph/tsdown.config.ts?no-cache=f0580075-e3d4-4057-84f0-b8678cf6a2ba is not specified and it doesn't parse as CommonJS.
 Reparsing as ES module because module syntax was detected. This incurs a performance overhead.
 To eliminate this warning, add "type": "module" to /home/runner/work/isograph/isograph/package.json.
 (Use `node --trace-warnings ...` to show where the warning was created)

package/.turbo/turbo-tsc.log

@@ -1,5 +1,5 @@
 ../..                                    |  WARN  Unsupported engine: wanted: {"node":"24.12.0"} (current: {"node":"v24.21.0","pnpm":"10.15.0"})
 
-> @isograph/react-disposable-state@0.0.0-main-54f75b55 tsc /home/runner/work/isograph/isograph/libs/isograph-react-disposable-state
+> @isograph/react-disposable-state@0.0.0-main-36b092bd tsc /home/runner/work/isograph/isograph/libs/isograph-react-disposable-state
 > tsc
 

package/README.md

@@ -129,6 +129,53 @@ const {
 } = useUpdatableDisposableClearableState<T>();
 ```
 
+### `useDisposableArray`
+
+A hook that holds an array of disposable items, built on `useUpdatableDisposableState`.
+
+- Returns an `{ entries, setEntries }` object. `entries` is the array of `ItemCleanupPair`s the current render shows. It is empty until the first `setEntries` call commits. The hook owns each pair's cleanup, so do not call it.
+- `setEntries(nextEntries)` stores `nextEntries`. Older arrays are released when a newer array commits, and the rest on unmount. Releasing an array calls the cleanup of each of its pairs once.
+- Every pair in `nextEntries` must be acquired by the caller for that call, and the hook owns it from then on. To keep an item of `entries`, take a new reference to it, for example with `cloneIfNotDisposed()` on a `ReferenceCountedPointer` from `@isograph/reference-counted-pointer`. Never pass a pair of `entries` itself.
+- Build `nextEntries` from the `entries` of the same render. If that render is stale, because its `entries` were released after a newer array committed, `cloneIfNotDisposed()` returns `null`. Release what you acquired and do not call `setEntries`.
+- Two `setEntries` calls before a commit both build on the same `entries`, and the second replaces the first.
+- `setEntries` throws if called before the initial commit, as `setState` does. It stores nothing in that case, so the caller still owns `nextEntries`.
+
+```typescript
+const {
+  entries,
+  setEntries,
+}: {
+  entries: ReadonlyArray<ItemCleanupPair<T>>;
+  setEntries: (nextEntries: ReadonlyArray<ItemCleanupPair<T>>) => void;
+} = useDisposableArray<T>();
+```
+
+For example, to keep at most three items, store reference-counted pointers, take a new reference to each item that stays, and add the new one:
+
+```typescript
+const { entries, setEntries } =
+  useDisposableArray<ReferenceCountedPointer<Item>>();
+
+function addItem(pair: ItemCleanupPair<Item>) {
+  const kept: Array<ItemCleanupPair<ReferenceCountedPointer<Item>>> = [];
+  for (const entry of entries.slice(-2)) {
+    const clone = entry[0].cloneIfNotDisposed();
+    if (clone == null) {
+      // This render is stale.
+      for (const keptEntry of kept) {
+        keptEntry[1]();
+      }
+      pair[1]();
+      return;
+    }
+    kept.push(clone);
+  }
+  setEntries([...kept, createReferenceCountedPointer(pair)]);
+}
+
+// Read an item with entries[index][0].getItemIfNotDisposed().
+```
+
 ### `useDisposableState`
 
 > This could properly be called `useLazyUpdatableDisposableState`, but that's quite long!

package/dist/index.cjs

@@ -4,6 +4,7 @@ const require_useEffectsRerunWithoutRender = require('./useEffectsRerunWithoutRe
 const require_useCachedResponsivePrecommitValue = require('./useCachedResponsivePrecommitValue.cjs');
 const require_useHasCommittedRef = require('./useHasCommittedRef.cjs');
 const require_useUpdatableDisposableState = require('./useUpdatableDisposableState.cjs');
+const require_useDisposableArray = require('./useDisposableArray.cjs');
 const require_useDisposableState = require('./useDisposableState.cjs');
 const require_useLazyDisposableState = require('./useLazyDisposableState.cjs');
 const require_useUpdatableDisposableClearableState = require('./useUpdatableDisposableClearableState.cjs');
@@ -13,6 +14,7 @@ exports.ParentCache = require_ParentCache.ParentCache;
 exports.UNASSIGNED_STATE = require_useUpdatableDisposableState.UNASSIGNED_STATE;
 exports.createTemporarilyRetainedCacheItem = require_CacheItem.createTemporarilyRetainedCacheItem;
 exports.useCachedResponsivePrecommitValue = require_useCachedResponsivePrecommitValue.useCachedResponsivePrecommitValue;
+exports.useDisposableArray = require_useDisposableArray.useDisposableArray;
 exports.useDisposableState = require_useDisposableState.useDisposableState;
 exports.useEffectsRerunWithoutRenderRef = require_useEffectsRerunWithoutRender.useEffectsRerunWithoutRenderRef;
 exports.useHasCommittedRef = require_useHasCommittedRef.useHasCommittedRef;

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { CacheItem, CacheItemOptions, CacheItemState, InParentCacheAndNotDisposed, NotInParentCacheAndDisposed, NotInParentCacheAndNotDisposed, createTemporarilyRetainedCacheItem } from "./CacheItem.cjs";
 import { ParentCache } from "./ParentCache.cjs";
 import { useCachedResponsivePrecommitValue } from "./useCachedResponsivePrecommitValue.cjs";
+import { UseDisposableArrayReturn, useDisposableArray } from "./useDisposableArray.cjs";
 import { UNASSIGNED_STATE, UnassignedState, useUpdatableDisposableState } from "./useUpdatableDisposableState.cjs";
 import { useDisposableState } from "./useDisposableState.cjs";
 import { useEffectsRerunWithoutRenderRef } from "./useEffectsRerunWithoutRender.cjs";
@@ -8,4 +9,4 @@ import { useHasCommittedRef } from "./useHasCommittedRef.cjs";
 import { useLazyDisposableState } from "./useLazyDisposableState.cjs";
 import { useUpdatableDisposableClearableState } from "./useUpdatableDisposableClearableState.cjs";
 export * from "@isograph/disposable-types";
-export { CacheItem, CacheItemOptions, CacheItemState, InParentCacheAndNotDisposed, NotInParentCacheAndDisposed, NotInParentCacheAndNotDisposed, ParentCache, UNASSIGNED_STATE, UnassignedState, createTemporarilyRetainedCacheItem, useCachedResponsivePrecommitValue, useDisposableState, useEffectsRerunWithoutRenderRef, useHasCommittedRef, useLazyDisposableState, useUpdatableDisposableClearableState, useUpdatableDisposableState };
+export { CacheItem, CacheItemOptions, CacheItemState, InParentCacheAndNotDisposed, NotInParentCacheAndDisposed, NotInParentCacheAndNotDisposed, ParentCache, UNASSIGNED_STATE, UnassignedState, UseDisposableArrayReturn, createTemporarilyRetainedCacheItem, useCachedResponsivePrecommitValue, useDisposableArray, useDisposableState, useEffectsRerunWithoutRenderRef, useHasCommittedRef, useLazyDisposableState, useUpdatableDisposableClearableState, useUpdatableDisposableState };

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { CacheItem, CacheItemOptions, CacheItemState, InParentCacheAndNotDisposed, NotInParentCacheAndDisposed, NotInParentCacheAndNotDisposed, createTemporarilyRetainedCacheItem } from "./CacheItem.mjs";
 import { ParentCache } from "./ParentCache.mjs";
 import { useCachedResponsivePrecommitValue } from "./useCachedResponsivePrecommitValue.mjs";
+import { UseDisposableArrayReturn, useDisposableArray } from "./useDisposableArray.mjs";
 import { UNASSIGNED_STATE, UnassignedState, useUpdatableDisposableState } from "./useUpdatableDisposableState.mjs";
 import { useDisposableState } from "./useDisposableState.mjs";
 import { useEffectsRerunWithoutRenderRef } from "./useEffectsRerunWithoutRender.mjs";
@@ -8,4 +9,4 @@ import { useHasCommittedRef } from "./useHasCommittedRef.mjs";
 import { useLazyDisposableState } from "./useLazyDisposableState.mjs";
 import { useUpdatableDisposableClearableState } from "./useUpdatableDisposableClearableState.mjs";
 export * from "@isograph/disposable-types";
-export { CacheItem, CacheItemOptions, CacheItemState, InParentCacheAndNotDisposed, NotInParentCacheAndDisposed, NotInParentCacheAndNotDisposed, ParentCache, UNASSIGNED_STATE, UnassignedState, createTemporarilyRetainedCacheItem, useCachedResponsivePrecommitValue, useDisposableState, useEffectsRerunWithoutRenderRef, useHasCommittedRef, useLazyDisposableState, useUpdatableDisposableClearableState, useUpdatableDisposableState };
+export { CacheItem, CacheItemOptions, CacheItemState, InParentCacheAndNotDisposed, NotInParentCacheAndDisposed, NotInParentCacheAndNotDisposed, ParentCache, UNASSIGNED_STATE, UnassignedState, UseDisposableArrayReturn, createTemporarilyRetainedCacheItem, useCachedResponsivePrecommitValue, useDisposableArray, useDisposableState, useEffectsRerunWithoutRenderRef, useHasCommittedRef, useLazyDisposableState, useUpdatableDisposableClearableState, useUpdatableDisposableState };

package/dist/index.mjs

@@ -4,10 +4,11 @@ import { useEffectsRerunWithoutRenderRef } from "./useEffectsRerunWithoutRender.
 import { useCachedResponsivePrecommitValue } from "./useCachedResponsivePrecommitValue.mjs";
 import { useHasCommittedRef } from "./useHasCommittedRef.mjs";
 import { UNASSIGNED_STATE, useUpdatableDisposableState } from "./useUpdatableDisposableState.mjs";
+import { useDisposableArray } from "./useDisposableArray.mjs";
 import { useDisposableState } from "./useDisposableState.mjs";
 import { useLazyDisposableState } from "./useLazyDisposableState.mjs";
 import { useUpdatableDisposableClearableState } from "./useUpdatableDisposableClearableState.mjs";
 
 export * from "@isograph/disposable-types"
 
-export { CacheItem, ParentCache, UNASSIGNED_STATE, createTemporarilyRetainedCacheItem, useCachedResponsivePrecommitValue, useDisposableState, useEffectsRerunWithoutRenderRef, useHasCommittedRef, useLazyDisposableState, useUpdatableDisposableClearableState, useUpdatableDisposableState };
+export { CacheItem, ParentCache, UNASSIGNED_STATE, createTemporarilyRetainedCacheItem, useCachedResponsivePrecommitValue, useDisposableArray, useDisposableState, useEffectsRerunWithoutRenderRef, useHasCommittedRef, useLazyDisposableState, useUpdatableDisposableClearableState, useUpdatableDisposableState };

package/dist/useDisposableArray.cjs

@@ -0,0 +1,20 @@
+const require_useUpdatableDisposableState = require('./useUpdatableDisposableState.cjs');
+let react = require("react");
+
+//#region src/useDisposableArray.ts
+const NO_ENTRIES = Object.freeze([]);
+function useDisposableArray() {
+	const { state, setState } = require_useUpdatableDisposableState.useUpdatableDisposableState();
+	const setEntries = (0, react.useCallback)((nextEntries) => {
+		setState([nextEntries, () => {
+			for (const entry of nextEntries) entry[1]();
+		}]);
+	}, [setState]);
+	return {
+		entries: state === require_useUpdatableDisposableState.UNASSIGNED_STATE ? NO_ENTRIES : state,
+		setEntries
+	};
+}
+
+//#endregion
+exports.useDisposableArray = useDisposableArray;

package/dist/useDisposableArray.d.cts

@@ -0,0 +1,11 @@
+import { ItemCleanupPair } from "@isograph/disposable-types";
+
+//#region src/useDisposableArray.d.ts
+type UseDisposableArrayReturn<T> = {
+  readonly entries: ReadonlyArray<ItemCleanupPair<T>>;
+  readonly setEntries: (nextEntries: ReadonlyArray<ItemCleanupPair<T>>) => void;
+};
+declare function useDisposableArray<T>(): UseDisposableArrayReturn<T>;
+//#endregion
+export { UseDisposableArrayReturn, useDisposableArray };
+//# sourceMappingURL=useDisposableArray.d.cts.map

package/dist/useDisposableArray.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDisposableArray.d.cts","names":[],"sources":["../src/useDisposableArray.ts"],"mappings":";;;KAOY,wBAAA;EAAA,SAGD,OAAA,EAAS,aAAA,CAAc,eAAA,CAAgB,CAAA;EAAA,SAEvC,UAAA,GAAa,WAAA,EAAa,aAAA,CAAc,eAAA,CAAgB,CAAA;AAAA;AAAA,iBAoBnD,kBAAA,GAAA,CAAA,GAAyB,wBAAA,CAAyB,CAAA"}

package/dist/useDisposableArray.d.mts

@@ -0,0 +1,11 @@
+import { ItemCleanupPair } from "@isograph/disposable-types";
+
+//#region src/useDisposableArray.d.ts
+type UseDisposableArrayReturn<T> = {
+  readonly entries: ReadonlyArray<ItemCleanupPair<T>>;
+  readonly setEntries: (nextEntries: ReadonlyArray<ItemCleanupPair<T>>) => void;
+};
+declare function useDisposableArray<T>(): UseDisposableArrayReturn<T>;
+//#endregion
+export { UseDisposableArrayReturn, useDisposableArray };
+//# sourceMappingURL=useDisposableArray.d.mts.map

package/dist/useDisposableArray.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDisposableArray.d.mts","names":[],"sources":["../src/useDisposableArray.ts"],"mappings":";;;KAOY,wBAAA;EAAA,SAGD,OAAA,EAAS,aAAA,CAAc,eAAA,CAAgB,CAAA;EAAA,SAEvC,UAAA,GAAa,WAAA,EAAa,aAAA,CAAc,eAAA,CAAgB,CAAA;AAAA;AAAA,iBAoBnD,kBAAA,GAAA,CAAA,GAAyB,wBAAA,CAAyB,CAAA"}

package/dist/useDisposableArray.mjs

@@ -0,0 +1,21 @@
+import { UNASSIGNED_STATE, useUpdatableDisposableState } from "./useUpdatableDisposableState.mjs";
+import { useCallback } from "react";
+
+//#region src/useDisposableArray.ts
+const NO_ENTRIES = Object.freeze([]);
+function useDisposableArray() {
+	const { state, setState } = useUpdatableDisposableState();
+	const setEntries = useCallback((nextEntries) => {
+		setState([nextEntries, () => {
+			for (const entry of nextEntries) entry[1]();
+		}]);
+	}, [setState]);
+	return {
+		entries: state === UNASSIGNED_STATE ? NO_ENTRIES : state,
+		setEntries
+	};
+}
+
+//#endregion
+export { useDisposableArray };
+//# sourceMappingURL=useDisposableArray.mjs.map

package/dist/useDisposableArray.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDisposableArray.mjs","names":[],"sources":["../src/useDisposableArray.ts"],"sourcesContent":["import type { ItemCleanupPair } from '@isograph/disposable-types';\nimport { useCallback } from 'react';\nimport {\n  UNASSIGNED_STATE,\n  useUpdatableDisposableState,\n} from './useUpdatableDisposableState';\n\nexport type UseDisposableArrayReturn<T> = {\n  // The array this render shows. It is empty until the first setEntries call commits. The hook owns every pair in\n  // it, so callers read the items and never call the cleanups.\n  readonly entries: ReadonlyArray<ItemCleanupPair<T>>;\n  // Replaces the array. See useDisposableArray.\n  readonly setEntries: (nextEntries: ReadonlyArray<ItemCleanupPair<T>>) => void;\n};\n\nconst NO_ENTRIES: ReadonlyArray<never> = Object.freeze([]);\n\n// useDisposableArray\n// - Holds an array of disposable items in state, on top of useUpdatableDisposableState.\n// - setEntries(nextEntries) stores nextEntries. Releasing a stored array calls the cleanup of each of its pairs once.\n//   useUpdatableDisposableState releases every array that is older than the committed one after the commit, and the\n//   rest on unmount, including arrays that never committed.\n// - Every pair in nextEntries was acquired by the caller for this call, and the hook owns it from then on. To keep an\n//   item of entries, the caller takes a new reference to it, for example with cloneIfNotDisposed() on a\n//   ReferenceCountedPointer, and passes that new pair. The caller never passes a pair of entries itself and never\n//   calls a cleanup the hook owns.\n// - The caller builds nextEntries from the entries of its render. If that render is stale, because its entries were\n//   released after a newer array committed, taking a new reference fails (cloneIfNotDisposed() returns null). The\n//   caller then releases what it acquired and does not call setEntries.\n// - Two setEntries calls before a commit both build on the same entries, and the second replaces the first.\n// - Like useUpdatableDisposableState's setState, setEntries throws if called before the initial commit. It throws\n//   before storing anything, so the caller still owns nextEntries and must release them.\nexport function useDisposableArray<T>(): UseDisposableArrayReturn<T> {\n  const { state, setState } =\n    useUpdatableDisposableState<ReadonlyArray<ItemCleanupPair<T>>>();\n\n  const setEntries = useCallback(\n    (nextEntries: ReadonlyArray<ItemCleanupPair<T>>) => {\n      setState([\n        nextEntries,\n        () => {\n          for (const entry of nextEntries) {\n            entry[1]();\n          }\n        },\n      ]);\n    },\n    [setState],\n  );\n\n  return {\n    entries: state === UNASSIGNED_STATE ? NO_ENTRIES : state,\n    setEntries,\n  };\n}\n"],"mappings":";;;;AAeA,MAAM,aAAmC,OAAO,OAAO,EAAE,CAAC;AAiB1D,SAAgB,qBAAqD;CACnE,MAAM,EAAE,OAAO,aACb,6BAAgE;CAElE,MAAM,aAAa,aAChB,gBAAmD;AAClD,WAAS,CACP,mBACM;AACJ,QAAK,MAAM,SAAS,YAClB,OAAM,IAAI;IAGf,CAAC;IAEJ,CAAC,SAAS,CACX;AAED,QAAO;EACL,SAAS,UAAU,mBAAmB,aAAa;EACnD;EACD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isograph/react-disposable-state",
-  "version": "0.0.0-main-54f75b55",
+  "version": "0.0.0-main-36b092bd",
   "description": "Primitives for managing disposable state in React",
   "homepage": "https://isograph.dev",
   "main": "./dist/index.cjs",
@@ -8,7 +8,7 @@
   "author": "Isograph Labs",
   "license": "MIT",
   "dependencies": {
-    "@isograph/disposable-types": "0.0.0-main-54f75b55"
+    "@isograph/disposable-types": "0.0.0-main-36b092bd"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"
@@ -19,7 +19,8 @@
     "@types/react-test-renderer": "^18.3.0",
     "happy-dom": "20.4.0",
     "react-test-renderer": "^18.2.0",
-    "typescript": "5.6.3"
+    "typescript": "5.6.3",
+    "@isograph/reference-counted-pointer": "0.0.0-main-36b092bd"
   },
   "repository": {
     "type": "git",

package/src/index.ts

@@ -3,6 +3,7 @@ export * from '@isograph/disposable-types';
 export * from './CacheItem';
 export * from './ParentCache';
 export * from './useCachedResponsivePrecommitValue';
+export * from './useDisposableArray';
 export * from './useDisposableState';
 export * from './useEffectsRerunWithoutRender';
 export * from './useHasCommittedRef';

package/src/useDisposableArray.test.tsx

@@ -0,0 +1,259 @@
+import type { ItemCleanupPair } from '@isograph/disposable-types';
+import {
+  createReferenceCountedPointer,
+  type ReferenceCountedPointer,
+} from '@isograph/reference-counted-pointer';
+import { act, render, screen } from '@testing-library/react';
+import React, { startTransition, useLayoutEffect, useState } from 'react';
+import { describe, expect, test, vi } from 'vitest';
+import {
+  type UseDisposableArrayReturn,
+  useDisposableArray,
+} from './useDisposableArray';
+
+type Entry = ItemCleanupPair<ReferenceCountedPointer<string>>;
+
+function createItem(label: string) {
+  const cleanup = vi.fn();
+  return {
+    cleanup,
+    acquire: (): Entry => createReferenceCountedPointer([label, cleanup]),
+  };
+}
+
+type CommittedRender = UseDisposableArrayReturn<
+  ReferenceCountedPointer<string>
+>;
+
+// What a caller does: builds the next array from its render's entries by taking a new reference to each kept entry
+// and acquiring each added item, then calls setEntries. If a kept entry's reference was already released, the render
+// is stale, so it releases everything it acquired and does not call setEntries. Returns whether it called setEntries.
+function keepAndAdd(
+  committedRender: CommittedRender,
+  kept: ReadonlyArray<Entry>,
+  added: ReadonlyArray<ReturnType<typeof createItem>>,
+): boolean {
+  const addedEntries = added.map((item) => item.acquire());
+  const clones: Entry[] = [];
+  for (const entry of kept) {
+    const clone = entry[0].cloneIfNotDisposed();
+    if (clone == null) {
+      for (const acquired of [...clones, ...addedEntries]) {
+        acquired[1]();
+      }
+      return false;
+    }
+    clones.push(clone);
+  }
+  committedRender.setEntries([...clones, ...addedEntries]);
+  return true;
+}
+
+function labelsOf(entries: ReadonlyArray<Entry>) {
+  return entries.map((entry) => entry[0].getItemIfNotDisposed()).join(',');
+}
+
+// Renders, under StrictMode, a component that holds a useDisposableArray of reference-counted pointers to strings and
+// shows their labels. Every commit of a new array records the render's entries and setEntries in `renders`. After the
+// mount, it also appends the labels to `commits` and calls `onCommit`. Both run in a layout effect, which runs before
+// the passive effect in which useUpdatableDisposableState releases older arrays. Renders are recorded per commit,
+// because StrictMode discards the first of the two mount renders.
+function renderDisposableArray(onCommit: (labels: string) => void = () => {}) {
+  const renders: CommittedRender[] = [];
+  const commits: string[] = [];
+  const setMountedRef: { current: (mounted: boolean) => void } = {
+    current: () => {},
+  };
+
+  function Owner() {
+    const { entries, setEntries } =
+      useDisposableArray<ReferenceCountedPointer<string>>();
+    useLayoutEffect(() => {
+      renders.push({ entries, setEntries });
+      commits.push(labelsOf(entries));
+      onCommit(labelsOf(entries));
+    }, [entries, setEntries]);
+    return <>{`entries: ${labelsOf(entries)}`}</>;
+  }
+
+  function Parent() {
+    const [mounted, setMounted] = useState(true);
+    setMountedRef.current = setMounted;
+    return mounted ? <Owner /> : null;
+  }
+
+  render(<Parent />, { reactStrictMode: true });
+  // StrictMode runs the mount's layout effects twice.
+  commits.length = 0;
+
+  return {
+    commits,
+    latestRender: () => renders[renders.length - 1]!,
+    setMounted: (mounted: boolean) => setMountedRef.current(mounted),
+  };
+}
+
+describe('useDisposableArray', () => {
+  test('dropping the first of three entries and adding a fourth releases the first after the new array commits', () => {
+    const a = createItem('a');
+    const b = createItem('b');
+    const c = createItem('c');
+    const d = createItem('d');
+    let aCleanupCallsAtCommit: number | null = null;
+    const owner = renderDisposableArray((labels) => {
+      if (labels === 'b,c,d') {
+        aCleanupCallsAtCommit = a.cleanup.mock.calls.length;
+      }
+    });
+
+    act(() => {
+      keepAndAdd(owner.latestRender(), [], [a, b, c]);
+    });
+    expect(screen.getByText('entries: a,b,c')).toBeTruthy();
+
+    act(() => {
+      const committedRender = owner.latestRender();
+      keepAndAdd(committedRender, committedRender.entries.slice(-2), [d]);
+    });
+    expect(screen.getByText('entries: b,c,d')).toBeTruthy();
+    expect(aCleanupCallsAtCommit).toBe(0);
+    expect(a.cleanup).toHaveBeenCalledOnce();
+    expect(b.cleanup).not.toHaveBeenCalled();
+    expect(c.cleanup).not.toHaveBeenCalled();
+    expect(d.cleanup).not.toHaveBeenCalled();
+
+    act(() => owner.setMounted(false));
+    for (const item of [a, b, c, d]) {
+      expect(item.cleanup).toHaveBeenCalledOnce();
+    }
+  });
+
+  test('of two calls before a commit, the second is rendered and the first is released once', () => {
+    const a = createItem('a');
+    const x = createItem('x');
+    const y = createItem('y');
+    const owner = renderDisposableArray();
+    act(() => {
+      keepAndAdd(owner.latestRender(), [], [a]);
+    });
+
+    act(() => {
+      const committedRender = owner.latestRender();
+      keepAndAdd(committedRender, committedRender.entries, [x]);
+      keepAndAdd(committedRender, committedRender.entries, [y]);
+    });
+
+    expect(screen.getByText('entries: a,y')).toBeTruthy();
+    expect(owner.commits).not.toContain('a,x');
+    expect(x.cleanup).toHaveBeenCalledOnce();
+    expect(a.cleanup).not.toHaveBeenCalled();
+    expect(y.cleanup).not.toHaveBeenCalled();
+
+    act(() => owner.setMounted(false));
+    for (const item of [a, x, y]) {
+      expect(item.cleanup).toHaveBeenCalledOnce();
+    }
+  });
+
+  test('a caller from an older committed render finds its clones fail and stores nothing', () => {
+    const a = createItem('a');
+    const b = createItem('b');
+    const c = createItem('c');
+    const owner = renderDisposableArray();
+    act(() => {
+      keepAndAdd(owner.latestRender(), [], [a]);
+    });
+    const olderRender = owner.latestRender();
+    act(() => {
+      keepAndAdd(olderRender, olderRender.entries, [b]);
+    });
+    expect(screen.getByText('entries: a,b')).toBeTruthy();
+
+    // The older render's array was released after 'a,b' committed. Item a is still held by the newer array, but the
+    // older render's reference to it is released, so cloning it fails.
+    let calledSetEntries: boolean | null = null;
+    act(() => {
+      calledSetEntries = keepAndAdd(olderRender, olderRender.entries, [c]);
+    });
+
+    expect(calledSetEntries).toBe(false);
+    expect(owner.commits).toEqual(['a', 'a,b']);
+    expect(screen.getByText('entries: a,b')).toBeTruthy();
+    expect(c.cleanup).toHaveBeenCalledOnce();
+    expect(a.cleanup).not.toHaveBeenCalled();
+    expect(b.cleanup).not.toHaveBeenCalled();
+
+    act(() => owner.setMounted(false));
+    for (const item of [a, b, c]) {
+      expect(item.cleanup).toHaveBeenCalledOnce();
+    }
+  });
+
+  test('an urgent call and a transition call from the same committed array commit in turn and release every item once', () => {
+    const a = createItem('a');
+    const b = createItem('b');
+    const c = createItem('c');
+    const d = createItem('d');
+    const owner = renderDisposableArray();
+    act(() => {
+      keepAndAdd(owner.latestRender(), [], [a, b]);
+    });
+
+    act(() => {
+      const committedRender = owner.latestRender();
+      keepAndAdd(committedRender, committedRender.entries.slice(0, 1), [c]);
+      startTransition(() => {
+        keepAndAdd(committedRender, committedRender.entries, [d]);
+      });
+    });
+
+    expect(owner.commits).toEqual(['a,b', 'a,c', 'a,b,d']);
+    expect(screen.getByText('entries: a,b,d')).toBeTruthy();
+    expect(c.cleanup).toHaveBeenCalledOnce();
+    expect(a.cleanup).not.toHaveBeenCalled();
+    expect(b.cleanup).not.toHaveBeenCalled();
+    expect(d.cleanup).not.toHaveBeenCalled();
+
+    act(() => owner.setMounted(false));
+    for (const item of [a, b, c, d]) {
+      expect(item.cleanup).toHaveBeenCalledOnce();
+    }
+  });
+
+  test('unmount releases every entry once, including an array that never committed', () => {
+    const a = createItem('a');
+    const b = createItem('b');
+    const c = createItem('c');
+    const e = createItem('e');
+    const owner = renderDisposableArray();
+    act(() => {
+      keepAndAdd(owner.latestRender(), [], [a, b]);
+    });
+
+    act(() => {
+      const committedRender = owner.latestRender();
+      keepAndAdd(committedRender, committedRender.entries, [c]);
+      owner.setMounted(false);
+    });
+
+    expect(owner.commits).toEqual(['a,b']);
+    for (const item of [a, b, c]) {
+      expect(item.cleanup).toHaveBeenCalledOnce();
+    }
+
+    // After unmount, the last render's entries are released, so the caller cannot keep them. It releases the item it
+    // acquired and does not call setEntries.
+    let calledSetEntries: boolean | null = null;
+    act(() => {
+      const committedRender = owner.latestRender();
+      calledSetEntries = keepAndAdd(committedRender, committedRender.entries, [
+        e,
+      ]);
+    });
+    expect(calledSetEntries).toBe(false);
+    expect(e.cleanup).toHaveBeenCalledOnce();
+    for (const item of [a, b, c]) {
+      expect(item.cleanup).toHaveBeenCalledOnce();
+    }
+  });
+});

package/src/useDisposableArray.ts

@@ -0,0 +1,55 @@
+import type { ItemCleanupPair } from '@isograph/disposable-types';
+import { useCallback } from 'react';
+import {
+  UNASSIGNED_STATE,
+  useUpdatableDisposableState,
+} from './useUpdatableDisposableState';
+
+export type UseDisposableArrayReturn<T> = {
+  // The array this render shows. It is empty until the first setEntries call commits. The hook owns every pair in
+  // it, so callers read the items and never call the cleanups.
+  readonly entries: ReadonlyArray<ItemCleanupPair<T>>;
+  // Replaces the array. See useDisposableArray.
+  readonly setEntries: (nextEntries: ReadonlyArray<ItemCleanupPair<T>>) => void;
+};
+
+const NO_ENTRIES: ReadonlyArray<never> = Object.freeze([]);
+
+// useDisposableArray
+// - Holds an array of disposable items in state, on top of useUpdatableDisposableState.
+// - setEntries(nextEntries) stores nextEntries. Releasing a stored array calls the cleanup of each of its pairs once.
+//   useUpdatableDisposableState releases every array that is older than the committed one after the commit, and the
+//   rest on unmount, including arrays that never committed.
+// - Every pair in nextEntries was acquired by the caller for this call, and the hook owns it from then on. To keep an
+//   item of entries, the caller takes a new reference to it, for example with cloneIfNotDisposed() on a
+//   ReferenceCountedPointer, and passes that new pair. The caller never passes a pair of entries itself and never
+//   calls a cleanup the hook owns.
+// - The caller builds nextEntries from the entries of its render. If that render is stale, because its entries were
+//   released after a newer array committed, taking a new reference fails (cloneIfNotDisposed() returns null). The
+//   caller then releases what it acquired and does not call setEntries.
+// - Two setEntries calls before a commit both build on the same entries, and the second replaces the first.
+// - Like useUpdatableDisposableState's setState, setEntries throws if called before the initial commit. It throws
+//   before storing anything, so the caller still owns nextEntries and must release them.
+export function useDisposableArray<T>(): UseDisposableArrayReturn<T> {
+  const { state, setState } =
+    useUpdatableDisposableState<ReadonlyArray<ItemCleanupPair<T>>>();
+
+  const setEntries = useCallback(
+    (nextEntries: ReadonlyArray<ItemCleanupPair<T>>) => {
+      setState([
+        nextEntries,
+        () => {
+          for (const entry of nextEntries) {
+            entry[1]();
+          }
+        },
+      ]);
+    },
+    [setState],
+  );
+
+  return {
+    entries: state === UNASSIGNED_STATE ? NO_ENTRIES : state,
+    setEntries,
+  };
+}