@arrai-innovations/reactive-helpers 22.1.0 → 23.0.0

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.0",
   "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",
@@ -98,6 +103,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/unit/matchers.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

@@ -138,7 +138,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`.
  */

package/types/use/listInstance.d.ts

@@ -18,13 +18,13 @@
  *  subscribe function.
  */
 /**
- * @typedef {{[pk: import('../config/commonCrud.js').Pk]: import('../use/objectInstance.js').ExistingCrudObject}} ObjectsByPk - The objects by pk.
+ * @typedef {{readonly [pk: import('../config/commonCrud.js').Pk]: import('../use/objectInstance.js').ExistingCrudObject}} ObjectsByPk - The objects by pk. The collection itself is read-only; mutate it through the list's own methods. Each object it holds stays reactive and writable.
  */
 /**
- * @typedef {import('vue').ComputedRef<import('../use/objectInstance.js').ExistingCrudObject[]>} ObjectsInOrder - The objects in order, based on .order & .objects.
+ * @typedef {import('vue').ComputedRef<readonly import('../use/objectInstance.js').ExistingCrudObject[]>} ObjectsInOrder - The objects in order, based on .order & .objects. The array is read-only; each object in it stays reactive and writable.
  */
 /**
- * @typedef {import('vue').ComputedRef<import('../config/commonCrud.js').Pk[]>} ListOrder - The order of the objects in the list.
+ * @typedef {import('vue').ComputedRef<readonly import('../config/commonCrud.js').Pk[]>} ListOrder - The read-only order of the objects in the list. Change presentation order through `useListSort` rather than by writing to it.
  */
 /**
  * @typedef {object} ListInstanceRawStateCrud - The raw CRUD handlers and target args stored in a list instance's reactive state.
@@ -35,7 +35,7 @@
  * @property {import('../config/listCrud.js').CrudExecuteActionFn} executeAction - The execute action function.
  */
 /**
- * @typedef {Map<import('../config/commonCrud.js').Pk, import('vue').Reactive<import('../use/objectInstance.js').ExistingCrudObject>>} ObjectsMap - A Map of primary keys to the list's reactive existing objects.
+ * @typedef {ReadonlyMap<import('../config/commonCrud.js').Pk, import('vue').Reactive<import('../use/objectInstance.js').ExistingCrudObject>>} ObjectsMap - A read-only Map of primary keys to the list's reactive existing objects. Mutate it through the list's own methods. Each object it holds stays reactive and writable.
  */
 /**
  * @typedef {object} PaginateInfo - Pagination details for a list, including total records, total pages, per-page count, and current page.
@@ -94,8 +94,8 @@
  *  or error state.
  * @property {() => import('../config/commonCrud.js').Pk} getFakePk - Generates a unique fake pk for use within the list.
  * @property {(args?: import('../config/listCrud.js').AdditionalListArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} list - Initiates a fetch to retrieve objects according to the CRUD configuration, returning a promise to a boolean indicating success.
- * @property {(args?: {pks?: import('../config/commonCrud.js').Pk[]} & import('../config/listCrud.js').AdditionalListArgs) => Promise<boolean>} bulkDelete - Deletes objects from the list by pk, returning a promise to a boolean indicating success.
- * @property {(args: {action: string, pks?: import('../config/commonCrud.js').Pk[]} & import('../config/listCrud.js').AdditionalListArgs) => Promise<object|string|boolean|null>} executeAction - Initiates an action on all objects in the list, returning the response, or null if the action failed.
+ * @property {(args?: {pks?: import('../config/commonCrud.js').Pk[]} & import('../config/listCrud.js').AdditionalListArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean>} bulkDelete - Deletes objects from the list by pk, returning a promise to a boolean indicating success. The promise carries a `cancel` method when the handler's promise did.
+ * @property {(args: {action: string, pks?: import('../config/commonCrud.js').Pk[]} & import('../config/listCrud.js').AdditionalListArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string|boolean|null>} executeAction - Initiates an action on all objects in the list, returning the response, or null if the action failed. The promise carries a `cancel` method when the handler's promise did.
  * @property {(info: PaginateInfo) => void} setPaginateInfo - The method to update pagination information.
  * @property {(total: ColumnTotals) => void} setColumnTotals - The method to update column totals.
  */
@@ -227,19 +227,19 @@ export type ListInstanceOptions = {
     };
 };
 /**
- * The objects by pk.
+ * The objects by pk. The collection itself is read-only; mutate it through the list's own methods. Each object it holds stays reactive and writable.
  */
 export type ObjectsByPk = {
-    [pk: import("../config/commonCrud.js").Pk]: import("../use/objectInstance.js").ExistingCrudObject;
+    readonly [pk: import("../config/commonCrud.js").Pk]: import("../use/objectInstance.js").ExistingCrudObject;
 };
 /**
- * The objects in order, based on .order & .objects.
+ * The objects in order, based on .order & .objects. The array is read-only; each object in it stays reactive and writable.
  */
-export type ObjectsInOrder = import("vue").ComputedRef<import("../use/objectInstance.js").ExistingCrudObject[]>;
+export type ObjectsInOrder = import("vue").ComputedRef<readonly import("../use/objectInstance.js").ExistingCrudObject[]>;
 /**
- * The order of the objects in the list.
+ * The read-only order of the objects in the list. Change presentation order through `useListSort` rather than by writing to it.
  */
-export type ListOrder = import("vue").ComputedRef<import("../config/commonCrud.js").Pk[]>;
+export type ListOrder = import("vue").ComputedRef<readonly import("../config/commonCrud.js").Pk[]>;
 /**
  * The raw CRUD handlers and target args stored in a list instance's reactive state.
  */
@@ -266,9 +266,9 @@ export type ListInstanceRawStateCrud = {
     executeAction: import("../config/listCrud.js").CrudExecuteActionFn;
 };
 /**
- * A Map of primary keys to the list's reactive existing objects.
+ * A read-only Map of primary keys to the list's reactive existing objects. Mutate it through the list's own methods. Each object it holds stays reactive and writable.
  */
-export type ObjectsMap = Map<import("../config/commonCrud.js").Pk, import("vue").Reactive<import("../use/objectInstance.js").ExistingCrudObject>>;
+export type ObjectsMap = ReadonlyMap<import("../config/commonCrud.js").Pk, import("vue").Reactive<import("../use/objectInstance.js").ExistingCrudObject>>;
 /**
  * Pagination details for a list, including total records, total pages, per-page count, and current page.
  */
@@ -416,18 +416,18 @@ export type ListInstanceMyFunctions = {
      */
     list: (args?: import("../config/listCrud.js").AdditionalListArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
     /**
-     * Deletes objects from the list by pk, returning a promise to a boolean indicating success.
+     * Deletes objects from the list by pk, returning a promise to a boolean indicating success. The promise carries a `cancel` method when the handler's promise did.
      */
     bulkDelete: (args?: {
         pks?: import("../config/commonCrud.js").Pk[];
-    } & import("../config/listCrud.js").AdditionalListArgs) => Promise<boolean>;
+    } & import("../config/listCrud.js").AdditionalListArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean>;
     /**
-     * Initiates an action on all objects in the list, returning the response, or null if the action failed.
+     * Initiates an action on all objects in the list, returning the response, or null if the action failed. The promise carries a `cancel` method when the handler's promise did.
      */
     executeAction: (args: {
         action: string;
         pks?: import("../config/commonCrud.js").Pk[];
-    } & import("../config/listCrud.js").AdditionalListArgs) => Promise<object | string | boolean | null>;
+    } & import("../config/listCrud.js").AdditionalListArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<object | string | boolean | null>;
     /**
      * The method to update pagination information.
      */

package/types/use/listRelated.d.ts

@@ -1,13 +1,9 @@
-/**
- * Vue Composition API composable function for managing relationships among objects in a list.
- * It enables linking objects based on predefined rules and dynamically adjusts as the underlying data changes.
- *
- * @module use/listRelated.js
- */
 /**
  * @typedef {object} ListRelatedRule - The rule for defining relationships for objects in a list.
- * @property {string} [pkKey] - Specifies the foreign key used to link objects across lists. Defaults to the rule's
- *  own key when omitted. Planned to be renamed to 'fkKey' to better reflect its usage.
+ * @property {string} [fkKey] - Specifies the foreign key on each row used to link objects across lists. Defaults to
+ *  the rule's own key when omitted.
+ * @property {string} [pkKey] - Deprecated alias for `fkKey`, removed in v24. The option never named a primary key.
+ *  A rule setting both uses `fkKey`.
  * @property {string[]} [order] - Specifies the order in which related objects should be sorted, if applicable.
  * @property {import('./listInstance.js').ObjectsByPk} objects - The objects that can be related based on the foreign key.
  */
@@ -130,7 +126,7 @@ export function useListRelateds(listRelatedArgs: {
  *     relatedObjectsRules: {
  *         someRule: {
  *             // this can point to a key or an array of keys to relate to
- *             pkKey: "dot.separated.key.to.pk.on.an.listInstance.object",
+ *             fkKey: "dot.separated.key.to.the.foreign.key.on.a.listInstance.object",
  *             objects: toRef(props, "objects"),
  *             order: toRef(props, "order"),
  *         },
@@ -157,14 +153,39 @@ export function useListRelateds(listRelatedArgs: {
  * @returns {ListRelated} - A reactive instance that manages related objects, providing real-time updates and
  * maintaining the integrity of object relationships as per the specified rules.
  */
-export function useListRelated({ parentState, relatedObjectsRules }: ListRelatedOptions): ListRelated;
+export function useListRelated(options: ListRelatedOptions): ListRelated;
+/**
+ * Vue Composition API composable function for managing relationships among objects in a list.
+ * It enables linking objects based on predefined rules and dynamically adjusts as the underlying data changes.
+ *
+ * @module use/listRelated.js
+ */
+/**
+ * Defines a custom error class specific to list related rules, encapsulating details about rules that cannot be
+ *  resolved as configured.
+ */
+export class ListRelatedError extends Error {
+    /**
+     * Creates an instance of ListRelatedError.
+     *
+     * @param {string} message - The error message.
+     * @param {string} code - The error code.
+     */
+    constructor(message: string, code: string);
+    code: string;
+}
 /**
  * The rule for defining relationships for objects in a list.
  */
 export type ListRelatedRule = {
     /**
-     * Specifies the foreign key used to link objects across lists. Defaults to the rule's
-     * own key when omitted. Planned to be renamed to 'fkKey' to better reflect its usage.
+     * Specifies the foreign key on each row used to link objects across lists. Defaults to
+     * the rule's own key when omitted.
+     */
+    fkKey?: string;
+    /**
+     * Deprecated alias for `fkKey`, removed in v24. The option never named a primary key.
+     * A rule setting both uses `fkKey`.
      */
     pkKey?: string;
     /**