@arrai-innovations/reactive-helpers 22.1.0 → 23.0.1

package/README.md

@@ -1,10 +1,11 @@
 # reactive-helpers
 
-![Tests](https://docs.arrai.dev/reactive-helpers/artifacts/main/tests.svg)
-[![Coverage](https://docs.arrai.dev/reactive-helpers/artifacts/main/tests.coverage.svg)](https://docs.arrai.dev/reactive-helpers/artifacts/main/coverage_tests/)
-![ESLint](https://docs.arrai.dev/reactive-helpers/artifacts/main/eslint.svg)
-![Prettier](https://docs.arrai.dev/reactive-helpers/artifacts/main/prettier.svg)
-![Audit](https://docs.arrai.dev/reactive-helpers/artifacts/main/pnpm-audit.svg)
+[![npm](https://img.shields.io/npm/v/%40arrai-innovations%2Freactive-helpers.svg?style=for-the-badge)](https://www.npmjs.com/package/@arrai-innovations/reactive-helpers)
+![Tests](https://reactive-helpers.arrai.dev/artifacts/main/tests.svg)
+[![Coverage](https://reactive-helpers.arrai.dev/artifacts/main/tests.coverage.svg)](https://reactive-helpers.arrai.dev/artifacts/main/coverage_tests/)
+![ESLint](https://reactive-helpers.arrai.dev/artifacts/main/eslint.svg)
+![Prettier](https://reactive-helpers.arrai.dev/artifacts/main/prettier.svg)
+![Audit](https://reactive-helpers.arrai.dev/artifacts/main/pnpm-audit.svg)
 [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg?style=for-the-badge)](./LICENSE)
 
 Vue.js 3 composition utilities to manage reactive lists, objects, loading and error state, and the small helpers that
@@ -18,12 +19,11 @@ reaches your backend), so the package stays transport agnostic.
 - [Features](#features)
 - [Requirements](#requirements)
 - [Install](#install)
-- [Usage](#usage)
-  - [Quick start](#quick-start)
-  - [Wiring a data layer](#wiring-a-data-layer)
+- [Documentation](#documentation)
 - [Changelog](#changelog)
 - [Contributing](#contributing)
 - [Development](#development)
+  - [Deploy documentation](#deploy-documentation)
 - [License](#license)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -31,25 +31,18 @@ reaches your backend), so the package stays transport agnostic.
 
 ## Features
 
-- **List composables** for managing collections of objects: `useListInstance`, `useList`, `useListFilter`,
-  `useListSort`, `useListSearch`, `useListCalculated`, `useListRelated`, and `useListSubscription`.
-- **Object composables** for managing single objects: `useObjectInstance`, `useObject`, `useObjectCalculated`,
-  `useObjectRelated`, and `useObjectSubscription`.
-- **Loading and error state** as small, composable primitives: `useLoading`, `useError`, `useLoadingError`, and their
-  read-only proxy variants `useProxyLoading`, `useProxyError`, `useProxyLoadingError`.
-- **Standalone helpers** such as `useSearch` (FlexSearch-backed), `useCancellableIntent`, and `useCombineClasses`.
-- **Pluggable CRUD configuration** via `setListCrud` / `setObjectCrud`, so the same composables can drive any backend.
-- **Reactive and object utilities**: `deepUnref`, `assignReactiveObject`, `refIfReactive`, `toRefsIfReactive`,
-  `isReactiveTyped`, `set`, `deleteKey`, `keyDiff`, `flattenPaths`, `cancellablePromise`, `cancellableFetch`, and more.
-
-Most list and object composables also ship a plural batch variant (for example `useListInstances`,
-`useObjectInstances`) for creating several keyed instances at once. See the full API in
-[docs/reference/api/index.md](./docs/reference/api/index.md).
+- **Reactive lists** with stable identity, ordering, filtering, sorting, searching, related data, calculated values, and
+  subscriptions.
+- **Reactive objects** that retrieve, edit, create, delete, and subscribe through transport-neutral handlers.
+- **Loading and error state** as small primitives that can be composed across asynchronous work.
+- **Pluggable CRUD configuration** so instances can share app-wide handlers for any backend.
+- **Focused utilities** for reactive data, cancellable work, object paths, classes, and search.
 
 ## Requirements
 
 - **Vue** `^3.5.13` (peer dependency).
-- **Node.js** with ES module support. This package is ESM only (`"type": "module"`); there is no CommonJS build.
+- **Node.js** `>=22`. Node 20 reached end of life in April 2026, so the supported lines are 22 and 24. This package is
+  ESM only (`"type": "module"`); there is no CommonJS build.
 - Peer dependencies you install alongside it: [`vue`](https://www.npmjs.com/package/vue),
   [`@vueuse/core`](https://www.npmjs.com/package/@vueuse/core), and
   [`lodash-es`](https://www.npmjs.com/package/lodash-es).
@@ -60,67 +53,17 @@ Most list and object composables also ship a plural batch variant (for example `
 $ npm install @arrai-innovations/reactive-helpers vue @vueuse/core lodash-es
 ```
 
-## Usage
+## Documentation
 
-### Quick start
+The [reactive-helpers documentation](https://reactive-helpers.arrai.dev/v23/) is versioned by package major.
 
-The loading and error composables are self contained and need no configuration. They return readonly reactive state
-plus actions to drive it, which is handy for wiring UI to any asynchronous work:
-
-```javascript
-import { useLoadingError } from "@arrai-innovations/reactive-helpers";
-
-const { loading, error, errored, setLoading, clearLoading, setError, clearError } = useLoadingError();
-
-async function save() {
-    setLoading();
-    try {
-        await doWork();
-        clearError();
-    } catch (e) {
-        setError(e);
-    } finally {
-        clearLoading();
-    }
-}
-
-// `loading`, `error`, and `errored` are readonly refs you can render or watch.
-```
-
-### Wiring a data layer
-
-The list and object instance composables manage reactive collections but stay transport agnostic: you provide the CRUD
-handlers that reach your backend. A list handler receives a `pushObjects` callback to feed results (one or more pages)
-into the reactive state and resolves when it is done:
-
-```javascript
-import { useListInstance } from "@arrai-innovations/reactive-helpers";
-import { reactive } from "vue";
-
-const contacts = useListInstance({
-    props: {
-        pkKey: "id",
-        params: reactive({ fields: ["id", "name"] }),
-        target: { stream: "contacts" }, // implementation-specific args passed through to your handlers
-    },
-    handlers: {
-        list: async ({ pushObjects }) => {
-            const rows = await fetch("/api/contacts").then((r) => r.json());
-            pushObjects(rows);
-            return true;
-        },
-    },
-});
-
-await contacts.list();
-console.log(contacts.state.objects);
-```
-
-To share one data layer across every instance instead of passing `handlers` each time, register defaults once with
-`setListCrud` (and `setObjectCrud` for object instances).
-
-See [docs/reference/api/index.md](./docs/reference/api/index.md) for the full list of modules, composables, and
-utilities, along with their arguments and properties.
+- [Get started](https://reactive-helpers.arrai.dev/v23/guide/) with installation and a complete reactive list.
+- [Build a reactive list](https://reactive-helpers.arrai.dev/v23/tutorials/build-a-reactive-list) step by step.
+- [Pass backend arguments](https://reactive-helpers.arrai.dev/v23/guide/data-layer) or
+  [register app-wide CRUD defaults](https://reactive-helpers.arrai.dev/v23/guide/register-crud-defaults).
+- Read about [instances and transport](https://reactive-helpers.arrai.dev/v23/concepts/instances-and-transport) to
+  understand the library's core boundary.
+- Use the [API reference](https://reactive-helpers.arrai.dev/v23/reference/api/) for exact signatures and return values.
 
 ## Changelog
 
@@ -133,8 +76,9 @@ Issues and pull requests are welcome. A few things to know before you start:
 - Commits follow [Conventional Commits](https://www.conventionalcommits.org/) and are validated by commitlint through a
   git hook (installed automatically by `pnpm install`).
 - Run the tests, linters, and formatter before opening a pull request (see [Development](#development)).
-- Generated output under `docs/` and `types/` is committed and checked in CI; regenerate it with `pnpm run docs` and
-  `pnpm run types` when you change public APIs or their JSDoc.
+- Generated output under `types/` and `docs/reference/api/` is committed and checked in CI. Regenerate it with
+  `pnpm run docs` when you change public APIs or their JSDoc. Everything else under `docs/` is hand-authored; see
+  [`docs/README.md`](./docs/README.md) before editing it.
 
 ## Development
 
@@ -144,16 +88,17 @@ Issues and pull requests are welcome. A few things to know before you start:
     $ git clone git@github.com:arrai-innovations/reactive-helpers.git
     ```
 
-2. Install dependencies:
+2. Install dependencies. Development needs Node `>=22.13`, above the `>=22` the package itself declares, because
+   `eslint-plugin-jsdoc` and `vite` require it:
 
     ```bash
     $ pnpm install
     ```
 
-3. Run tests via vitest:
+3. Run tests via vitest. Pass `run` for a single pass; `pnpm test` on its own starts watch mode:
 
     ```bash
-    $ pnpm test
+    $ pnpm test run
     ```
 
 4. Run tests with coverage output:
@@ -162,13 +107,21 @@ Issues and pull requests are welcome. A few things to know before you start:
     $ pnpm coverage
     ```
 
-5. Generate types and typedocs:
+5. Lint and format. Both rewrite files in place, and a git hook runs them on staged files:
+
+    ```bash
+    $ pnpm eslint
+    $ pnpm prettier
+    ```
+
+6. Generate types and typedocs, then confirm the committed output matches:
 
     ```bash
     $ pnpm run docs
+    $ pnpm run docs:check
     ```
 
-6. Type-only workflows:
+7. Type-only workflows:
 
     - Generate types without docs:
         ```bash
@@ -179,6 +132,30 @@ Issues and pull requests are welcome. A few things to know before you start:
         $ pnpm run types:check -- --skip-gen
         ```
 
+8. Preview the documentation site. The build fails on dead links, so run it before proposing documentation changes:
+
+    ```bash
+    $ pnpm run docs:site:dev
+    $ pnpm run docs:site:build
+    ```
+
+### Deploy documentation
+
+Tagging a release publishes the documentation. The `docs-site` CircleCI job runs after the npm publish succeeds, takes
+the major from the tag, and deploys to `https://reactive-helpers.arrai.dev/v<major>/`. Releasing needs no separate
+documentation step.
+
+Publishing between releases is the out-of-band case: a correction or a new page that should not wait for the next tag.
+Authenticate the CircleCI CLI with `circleci setup`, then run:
+
+```bash
+$ pnpm run docs:site:deploy
+```
+
+This triggers a docs-only pipeline against `main`. It derives the major from `package.json`, deploys to that same
+per-major path, and does not publish the npm package. The script reuses the CLI's authentication. `CIRCLECI_TOKEN`
+remains available as an override for automation.
+
 ## License
 
 [BSD-3-Clause](./LICENSE) © Arrai Innovations Inc.

package/config/listCrud.js

@@ -45,6 +45,8 @@ import { readonly } from "vue";
  * @property {import('../config/objectCrud.js').TargetArgs} target - The arguments to be passed to the crud handlers.
  * @property {import('./commonCrud.js').Pk[]} pks - The pks of the objects to be deleted.
  * @property {string} pkKey - The key name of the primary key.
+ * @property {{[key:string]: any}} params - Your listing arguments, passed through to the crud handlers.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 
 /**
@@ -77,6 +79,8 @@ import { readonly } from "vue";
  * @property {import('./commonCrud.js').Pk[]} pks - The pks of the objects to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
  * @property {string} action - The action to execute.
+ * @property {{[key:string]: any}} params - Your listing arguments, passed through to the crud handlers.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 
 /**
@@ -94,8 +98,9 @@ import { readonly } from "vue";
 /**
  * @callback CrudBulkDeleteFn - Signature for the handler that bulk-deletes objects from the backing store.
  * @param {BulkDeleteArgs} args - The arguments to be passed to the crud handlers.
- * @returns {Promise<boolean>} - A promise whose resolution means the bulk delete succeeded; the resolved value is not
- *  inspected, and the instance then empties the list.
+ * @returns {import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean>} - A promise whose resolution
+ *  means the bulk delete succeeded; the resolved value is not inspected, and the instance then empties the list.
+ *  Carry a `cancel` method to let the caller abandon the run.
  */
 
 /**
@@ -107,8 +112,9 @@ import { readonly } from "vue";
 /**
  * @callback CrudExecuteActionFn - Signature for the handler that executes an action on a list of objects in the backing store.
  * @param {ExecuteActionArgs} args - The arguments to be passed to the crud handlers.
- * @returns {Promise<object|string|null>} - A promise resolving the action's result, which `listInstance.executeAction`
- *  passes through to its caller.
+ * @returns {import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string|null>} - A promise
+ *  resolving the action's result, which `listInstance.executeAction` passes through to its caller. Carry a `cancel`
+ *  method to let the caller abandon the run.
  */
 
 /**

package/config/objectCrud.js

@@ -133,9 +133,10 @@ import { readonly } from "vue";
 
 /**
  * @typedef {import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string|void>} CrudCompletionResponse -
- *  The value returned by an object CRUD handler whose resolved value is ignored: delete, and executeAction. A
- *  possibly-cancellable promise whose resolution signals success and nothing more, so it may resolve a record, a
- *  primary key string, or nothing at all.
+ *  The value returned by an object CRUD handler that does not populate the managed record: delete, and
+ *  executeAction. A possibly-cancellable promise that may resolve a record, a primary key string, or nothing at
+ *  all. `delete` ignores the resolved value, treating resolution alone as success. `executeAction` passes the
+ *  resolved value through to its caller, and resolves `null` instead when the action failed.
  */
 
 /**
@@ -169,10 +170,11 @@ import { readonly } from "vue";
  */
 
 /**
- * @callback CrudObjectExecuteActionFn - Signature for the handler that executes an action on a single object in the backing store.
+ * @callback CrudObjectExecuteActionFn - Signature for the handler that executes an action on a single object in the
+ *  backing store. Its resolved value is passed through to the caller of `objectInstance.executeAction`.
  * @param {ObjectExecuteActionArgs} args - The arguments to be passed to the executeAction function.
- * @returns {CrudCompletionResponse} - A promise whose resolution means the action succeeded; its value is ignored, and
- *  `objectInstance.executeAction` resolves `true`.
+ * @returns {CrudCompletionResponse} - A promise resolving the action's result, which
+ *  `objectInstance.executeAction` passes through to its caller. A stored failure resolves `null` instead.
  */
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arrai-innovations/reactive-helpers",
-  "version": "22.1.0",
+  "version": "23.0.1",
   "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
   "main": "index.js",
   "type": "module",
@@ -37,10 +37,15 @@
   "bugs": {
     "url": "https://github.com/arrai-innovations/reactive-helpers/issues"
   },
-  "homepage": "https://github.com/arrai-innovations/reactive-helpers#readme",
+  "homepage": "https://reactive-helpers.arrai.dev/v23/",
+  "engines": {
+    "node": ">=22"
+  },
   "devDependencies": {
-    "@arrai-innovations/commitlint-config": "^2.1.0",
-    "@commitlint/cli": "^19.8.1",
+    "@arrai-innovations/commitlint-config": "^3.0.0",
+    "@arrai-innovations/diction-md": "^1.0.0",
+    "@arrai-innovations/vitepress-theme": "1.0.1",
+    "@commitlint/cli": "^21.2.1",
     "@eslint/js": "9.39.4",
     "@godaddy/dmd": "^1.0.4",
     "@trivago/prettier-plugin-sort-imports": "^5.2.2",
@@ -60,9 +65,9 @@
     "eslint-plugin-vue": "^10.9.2",
     "flush-promises": "^1.0.2",
     "globals": "^16.5.0",
-    "jsdom": "^26.1.0",
+    "jsdom": "^30.0.1",
     "lefthook": "^1.13.6",
-    "prettier": "^3.8.4",
+    "prettier": "^3.9.6",
     "typedoc": "^0.28.19",
     "typedoc-plugin-markdown": "^4.12.0",
     "typescript": "^5.9.3",
@@ -84,11 +89,16 @@
   },
   "scripts": {
     "benchmark": "vitest bench --run",
+    "benchmark:ci": "pnpm benchmark:list:ci && pnpm benchmark:stream:ci && pnpm benchmark:layers:ci && pnpm benchmark:observed:ci",
     "benchmark:list": "vitest bench --run tests/benchmarks/listPush.bench.js",
     "benchmark:list:ci": "vitest bench --run tests/benchmarks/listPush.bench.js --outputJson benchmark-results/list-push.json",
     "benchmark:check": "node check_benchmark.js",
     "benchmark:layers": "vitest bench --run tests/benchmarks/listLayers.bench.js",
+    "benchmark:layers:ci": "vitest bench --run tests/benchmarks/listLayers.bench.js --outputJson benchmark-results/list-layers.json",
+    "benchmark:observed": "vitest bench --run tests/benchmarks/listObserved.bench.js",
+    "benchmark:observed:ci": "vitest bench --run tests/benchmarks/listObserved.bench.js --outputJson benchmark-results/list-observed.json",
     "benchmark:stream": "vitest bench --run tests/benchmarks/listStream.bench.js",
+    "benchmark:stream:ci": "vitest bench --run tests/benchmarks/listStream.bench.js --outputJson benchmark-results/list-stream.json",
     "test": "vitest",
     "eslint": "eslint --fix index.js config/**/*.js tests/**/*.js use/**/*.js utils/**/*.js",
     "prettier": "prettier --write .",
@@ -98,6 +108,7 @@
     "docs:clean": "node clean_type_doc.js",
     "docs:site:dev": "vitepress dev docs",
     "docs:site:build": "vitepress build docs",
+    "docs:site:deploy": "node scripts/deploy-docs.mjs",
     "docs:site:preview": "vitepress preview docs",
     "types": "node make_types.js",
     "types:check": "node check_types.js"

package/types/config/listCrud.d.ts

@@ -84,6 +84,16 @@ export type BulkDeleteArgsRaw = {
      * The key name of the primary key.
      */
     pkKey: string;
+    /**
+     * Your listing arguments, passed through to the crud handlers.
+     */
+    params: {
+        [key: string]: any;
+    };
+    /**
+     * A readonly ref that becomes true once the request is cancelled.
+     */
+    isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
 /**
  * Arguments for a bulk-delete operation, combining the raw arguments with any additional list CRUD arguments.
@@ -142,6 +152,16 @@ export type ExecuteActionArgsRaw = {
      * The action to execute.
      */
     action: string;
+    /**
+     * Your listing arguments, passed through to the crud handlers.
+     */
+    params: {
+        [key: string]: any;
+    };
+    /**
+     * A readonly ref that becomes true once the request is cancelled.
+     */
+    isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
 /**
  * Arguments for a list execute-action operation, combining the raw arguments with any additional list CRUD arguments.
@@ -154,7 +174,7 @@ export type CrudListFn = (args: ListArgs) => import("../utils/cancellablePromise
 /**
  * Signature for the handler that bulk-deletes objects from the backing store.
  */
-export type CrudBulkDeleteFn = (args: BulkDeleteArgs) => Promise<boolean>;
+export type CrudBulkDeleteFn = (args: BulkDeleteArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean>;
 /**
  * Signature for the handler that subscribes to list changes in the backing store.
  */
@@ -162,7 +182,7 @@ export type CrudListSubscribeFn = (args: ListSubscribeArgs) => import("../utils/
 /**
  * Signature for the handler that executes an action on a list of objects in the backing store.
  */
-export type CrudExecuteActionFn = (args: ExecuteActionArgs) => Promise<object | string | null>;
+export type CrudExecuteActionFn = (args: ExecuteActionArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<object | string | null>;
 /**
  * The set of optional CRUD handler functions (list, bulkDelete, executeAction, subscribe) for a list.
  */

package/types/config/objectCrud.d.ts

@@ -274,9 +274,10 @@ export type ObjectSubscribeArgs = ObjectSubscribeArgsRaw & import("../use/cancel
 export type CrudResponse = import("../utils/cancellablePromise.js").MaybeCancellablePromise<object>;
 /**
  * -
- *  The value returned by an object CRUD handler whose resolved value is ignored: delete, and executeAction. A
- *  possibly-cancellable promise whose resolution signals success and nothing more, so it may resolve a record, a
- *  primary key string, or nothing at all.
+ *  The value returned by an object CRUD handler that does not populate the managed record: delete, and
+ *  executeAction. A possibly-cancellable promise that may resolve a record, a primary key string, or nothing at
+ *  all. `delete` ignores the resolved value, treating resolution alone as success. `executeAction` passes the
+ *  resolved value through to its caller, and resolves `null` instead when the action failed.
  */
 export type CrudCompletionResponse = import("../utils/cancellablePromise.js").MaybeCancellablePromise<object | string | void>;
 /**
@@ -300,7 +301,8 @@ export type CrudPatchFn = (args: PartialArgs) => CrudResponse;
  */
 export type CrudDeleteFn = (args: DeleteArgs) => CrudCompletionResponse;
 /**
- * Signature for the handler that executes an action on a single object in the backing store.
+ * Signature for the handler that executes an action on a single object in the
+ *  backing store. Its resolved value is passed through to the caller of `objectInstance.executeAction`.
  */
 export type CrudObjectExecuteActionFn = (args: ObjectExecuteActionArgs) => CrudCompletionResponse;
 /**

package/types/tests/benchmarks/fixtures.d.ts

@@ -46,7 +46,7 @@ export namespace populatedRules {
     export { orderByRules_1 as orderByRules };
     export namespace relatedObjectsRules_1 {
         namespace org {
-            export let pkKey: string;
+            export let fkKey: string;
             export { relatedOrganizations as objects };
         }
     }

package/types/tests/benchmarks/listObserved.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/benchmarks/reviewFixtures.d.ts

@@ -0,0 +1,102 @@
+/** How many entries each generated lookup collection holds. */
+export const lookupSize: 13;
+export function makeLookup(index: number): import("../../use/listInstance.js").ObjectsByPk;
+/** Lookup collection for the array-valued rule, which resolves a list of foreign keys per record. */
+export const tagLookup: import("../../use/listInstance.js").ObjectsByPk;
+/** The order the array-valued rule sorts its resolved tags into. */
+export const tagOrder: string[];
+export function makeRelatedRules(ruleCount: number, includeArrayRule?: boolean): import("../../use/listRelated.js").ListRelatedRules;
+export function makeCalculatedRules(ruleCount: number, relatedRuleCount: number): {
+    [rule: string]: (object: object, related: object, calculated: object) => any;
+};
+export function makeReviewRows(count: number, start?: number, fkCount?: number): object[];
+export function makeOrderByRules(sortOn: "none" | "plain" | "related" | "calculated"): import("../../use/listSort.js").OrderByRule[];
+export function makeReviewList({ relatedRuleCount, calculatedRuleCount, sortOn, includeArrayRule, filter, sortThrottleWait, }?: ReviewListOptions): ReturnType<typeof useList>;
+export function composeReviewStack({ relatedRuleCount, calculatedRuleCount, sortOn, includeArrayRule, filter, sortThrottleWait, }?: ReviewListOptions): {
+    states: {
+        [layer: string]: object;
+    };
+    push: (objects: object[]) => void;
+    stop: () => void;
+};
+export namespace readChannels {
+    let collection: {
+        [channel: string]: (state: object) => void;
+    };
+    let record: {
+        [channel: string]: (state: object, pk: string) => void;
+    };
+}
+export function attachRenderObservers(state: object, { collectionChannels, recordChannels }?: RenderObserverOptions): {
+    sync: () => void;
+    stop: () => void;
+    counts: {
+        [channel: string]: ChannelCounts;
+    };
+    totals: () => {
+        effects: number;
+        runs: number;
+        triggers: number;
+    };
+    reset: () => void;
+};
+/**
+ * The shape of the review list to build.
+ */
+export type ReviewListOptions = {
+    /**
+     * How many related rules the list carries.
+     */
+    relatedRuleCount?: number;
+    /**
+     * How many calculated rules the list carries.
+     */
+    calculatedRuleCount?: number;
+    /**
+     * Which value the sort orders on.
+     */
+    sortOn?: "none" | "plain" | "related" | "calculated";
+    /**
+     * Whether the related rules include an array-valued rule.
+     */
+    includeArrayRule?: boolean;
+    /**
+     * Whether an allowed filter is active.
+     */
+    filter?: boolean;
+    /**
+     * The sort throttle, in milliseconds.
+     */
+    sortThrottleWait?: number;
+};
+/**
+ * Which channels observe the list.
+ */
+export type RenderObserverOptions = {
+    /**
+     * Names from `readChannels.collection` to attach once.
+     */
+    collectionChannels?: string[];
+    /**
+     * Names from `readChannels.record` to attach per record.
+     */
+    recordChannels?: string[];
+};
+/**
+ * What one channel's effects have done.
+ */
+export type ChannelCounts = {
+    /**
+     * How many effects the channel has attached.
+     */
+    effects: number;
+    /**
+     * How many times those effects have evaluated.
+     */
+    runs: number;
+    /**
+     * How many times those effects have been notified.
+     */
+    triggers: number;
+};
+import { useList } from "../../use/list.js";

package/types/tests/unit/matchers.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/use/listLoadingPropagation.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/use/listMembershipWatch.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/use/listNotifications.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/use/listObjectsVersion.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/use/ruleOptionNames.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/use/cancellableIntent.d.ts

@@ -60,11 +60,10 @@
  *
  * If the watch arguments change again before the promise resolves, the in-flight promise is cancelled only when it
  * carries a `cancel` method (a `MaybeCancellablePromise`); a plain promise is left to run to completion. That
- * distinction is visible through the composables built on this one. `useObjectSubscription` calls
- * `objectInstance.retrieve()` again for the new key, and that call returns the promise already in flight for the
- * previous key, so the stale record is assigned and the new key is never fetched. `useListSubscription` guards its
- * list intent on the list's own loading state, so the superseded run is left to finish and the list is then listed
- * again with the current arguments.
+ * distinction is visible through the composables built on this one. Both `useObjectSubscription` and
+ * `useListSubscription` guard their intents on the instance's own loading state, so a superseded run is left to
+ * finish and the intent then re-runs with the current arguments. The stale result is assigned first, and the
+ * re-run replaces it.
  *
  * @example
  * ```vue

package/types/use/listCalculated.d.ts

@@ -64,6 +64,7 @@
  * @typedef {object} ListCalculatedProperties - The properties for the list computed composition function.
  * @property {ListCalculatedState} state - The state for the list calculated property.
  * @property {ListCalculatedParentState} parentState - The parent state object.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  * @property {() => void} stop - Stops composition's effects and cleans up resources.
  */
 /**
@@ -138,7 +139,7 @@ export function useListCalculateds(listCalculatedArgs: {
  * @returns {ListCalculated} - A reactive instance that manages and provides access to calculated properties within the
  *  list, facilitating real-time updates and complex dependency management across multiple components.
  */
-export function useListCalculated({ parentState, calculatedObjectsRules }: ListCalculatedOptions): ListCalculated;
+export function useListCalculated(options: ListCalculatedOptions): ListCalculated;
 /**
  * Defines rules for dynamically calculating new properties for objects in a list. Each rule is a function that takes an object from the list, optionally its related objects, and previously calculated properties to compute a new property. These functions are reactive and re-evaluate when underlying dependencies change. Each entry of the third argument is backed by a computed, but it is read through a reactive proxy that unwraps it, so a rule reads `calculatedObjects.otherRule` directly and never `.value`.
  */
@@ -221,6 +222,10 @@ export type ListCalculatedProperties = {
      * The parent state object.
      */
     parentState: ListCalculatedParentState;
+    /**
+     * Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
+     */
+    watchMembershipChanged: import("../utils/watches.js").WatchMembershipChanged;
     /**
      * Stops composition's effects and cleans up resources.
      */

package/types/use/listFilter.d.ts

@@ -51,6 +51,7 @@
  * @typedef {object} ListFilterProperties - The properties of a list filter, including its state and associated Vue composition API utilities.
  * @property {ListFilterState} state - The reactive state managing the filter logic and results.
  * @property {ListFilterParentState} parentState - The state of the list being filtered.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  * @property {() => void} stop - A function to stop the effect scope and clean up resources.
  */
 /**
@@ -166,6 +167,10 @@ export type ListFilterProperties = {
      * The state of the list being filtered.
      */
     parentState: ListFilterParentState;
+    /**
+     * Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
+     */
+    watchMembershipChanged: import("../utils/watches.js").WatchMembershipChanged;
     /**
      * A function to stop the effect scope and clean up resources.
      */