@arrai-innovations/reactive-helpers 22.0.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/README.md](./docs/README.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/README.md](./docs/README.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/commonCrud.js

@@ -1,4 +1,4 @@
-import { CancellablePromise } from "../utils/cancellablePromise.js";
+import { makeCancellable } from "../utils/cancellablePromise.js";
 import cloneDeep from "lodash-es/cloneDeep.js";
 import { addOrUpdateReactiveObject } from "../utils/assignReactiveObject.js";
 import isFunction from "lodash-es/isFunction.js";
@@ -17,8 +17,7 @@ import { refIfReactive } from "../utils/refIfReactive.js";
  * @param {string} name - The name of the method.
  * @returns {(...args: any[]) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<any>} - A function that returns a rejected promise with an error message.
  */
-export const missingMethod = (name) => () =>
-    CancellablePromise.reject(new Error(`Crud method "${name}" is not implemented.`));
+export const missingMethod = (name) => () => Promise.reject(new Error(`Crud method "${name}" is not implemented.`));
 
 // HACK: eslint, tsc, webstorm all can't agree on how to do this right
 // noinspection JSValidateTypes,JSUnusedLocalSymbols
@@ -34,7 +33,7 @@ export const requiredCancelMissingMethod =
     /* eslint-disable no-unused-vars */
     // @ts-ignore - refuses to accept returned CancellablePromise<void> = imported CancellablePromise<void>
     (..._args) =>
-        CancellablePromise(Promise.reject(new Error(`Crud method "${name}" is not implemented.`)), () => {});
+        makeCancellable(Promise.reject(new Error(`Crud method "${name}" is not implemented.`)), () => {});
 /* eslint-enable no-unused-vars */
 
 /**

package/config/listCrud.js

@@ -28,11 +28,10 @@ import { readonly } from "vue";
  * @typedef {object} ListArgsRaw - Raw arguments for a list operation before run-tracking and additional list CRUD arguments are merged in.
  * @property {import('../config/objectCrud.js').TargetArgs} target - The arguments to be passed to the crud handlers.
  * @property {string} pkKey - The key name of the primary key.
- * @property {object} params - The arguments to be passed for list crud handlers.
+ * @property {object} params - Your listing or retrieval arguments, passed through to the crud handlers.
  * @property {import("../use/listInstance.js").PushObjectsFn} pushObjects - The method to call with new page(s) of data received.
  * @property {ClearObjectsFn} clearObjects - The method to call to clear the objects.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to a boolean indicating whether the request has
- *  been cancelled.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  * @property {SetPaginateInfo} setPaginateInfo - The method to update pagination information.
  * @property {SetColumnTotals} setColumnTotals - The method to update column totals.
  */
@@ -44,8 +43,10 @@ import { readonly } from "vue";
 /**
  * @typedef {object} BulkDeleteArgsRaw - Raw arguments for a bulk-delete operation before additional list CRUD arguments are merged in.
  * @property {import('../config/objectCrud.js').TargetArgs} target - The arguments to be passed to the crud handlers.
- * @property {import('./commonCrud.js').Pk[]} pks - The ids of the objects to be deleted.
+ * @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.
  */
 
 /**
@@ -63,10 +64,9 @@ import { readonly } from "vue";
  * @typedef {object} ListSubscribeArgsRaw - Raw arguments for a list subscribe operation before run-tracking and additional list CRUD arguments are merged in.
  * @property {import('../config/objectCrud.js').TargetArgs} target - The arguments to be passed to the crud handlers.
  * @property {string} pkKey - The key name of the primary key.
- * @property {object} params - The arguments to be passed for list crud handlers.
+ * @property {object} params - Your listing or retrieval arguments, passed through to the crud handlers.
  * @property {applyObjectEvent} applyObjectEvent - The method to call when new data is received.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to a boolean indicating whether the request has
- *  been cancelled.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 
 /**
@@ -76,9 +76,11 @@ import { readonly } from "vue";
 /**
  * @typedef {object} ExecuteActionArgsRaw - Raw arguments for a list execute-action operation before additional list CRUD arguments are merged in.
  * @property {import('../config/objectCrud.js').TargetArgs} target - The arguments to be passed to the crud handlers.
- * @property {import('./commonCrud.js').Pk[]} pks - The ids of the objects to be acted upon.
+ * @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.
  */
 
 /**
@@ -88,13 +90,17 @@ import { readonly } from "vue";
 /**
  * @callback CrudListFn - Signature for the handler that lists objects from the backing store.
  * @param {ListArgs} args - The arguments to be passed to the crud handlers.
- * @returns {import('../utils/cancellablePromise.js').MaybeCancellablePromise<void>} - A cancellable promise for the list request.
+ * @returns {import('../utils/cancellablePromise.js').MaybeCancellablePromise<void>} - A promise whose resolution means
+ *  the fetch is complete. Rows reach the list only through `pushObjects`, so the resolved value is ignored. Carry a
+ *  `cancel` method to let the library abandon a superseded run.
  */
 
 /**
  * @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 that resolves to a boolean indicating success.
+ * @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.
  */
 
 /**
@@ -106,7 +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 that resolves the result of the action, returned to the executor.
+ * @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

@@ -29,10 +29,10 @@ import { readonly } from "vue";
 /**
  * @typedef {object} CreateArgsRaw - Raw arguments for an object create operation before additional CRUD arguments are merged in.
  * @property {TargetArgs} target - The arguments to be passed to the crud handlers.
- * @property {{[key:string]: any}} object - The data to be acted upon.
- * @property {{[key:string]: any}} params - The arguments to be passed to the retrieve function.
+ * @property {{[key:string]: any}} object - The new object to create; it carries no primary key yet.
+ * @property {{[key:string]: any}} params - Your listing or retrieval arguments, passed through to the crud handlers.
  * @property {string} pkKey - The key name of the primary key.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 
 /**
@@ -44,8 +44,8 @@ import { readonly } from "vue";
  * @property {TargetArgs} target - The arguments to be passed to the crud handlers.
  * @property {import('./commonCrud.js').Pk} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
- * @property {{[key:string]: any}} params - The arguments to be passed to the retrieve function.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ * @property {{[key:string]: any}} params - Your listing or retrieval 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.
  */
 
 /**
@@ -55,10 +55,10 @@ import { readonly } from "vue";
 /**
  * @typedef {object} UpdateArgsRaw - Raw arguments for an object update operation before additional CRUD arguments are merged in.
  * @property {TargetArgs} target - The arguments to be passed to the crud handlers.
- * @property {import('../use/objectInstance.js').ExistingCrudObject} object - The data to be acted upon.
- * @property {{[key:string]: any}} params - The arguments to be passed to the retrieve function.
+ * @property {import('../use/objectInstance.js').ExistingCrudObject} object - The complete object to update; its primary key rides inside it, at `object[pkKey]`.
+ * @property {{[key:string]: any}} params - Your listing or retrieval arguments, passed through to the crud handlers.
  * @property {string} pkKey - The key name of the primary key.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 
 /**
@@ -70,7 +70,7 @@ import { readonly } from "vue";
  * @property {TargetArgs} target - The arguments to be passed to the crud handlers.
  * @property {import('./commonCrud.js').Pk} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 
 /**
@@ -82,9 +82,9 @@ import { readonly } from "vue";
  * @property {TargetArgs} target - The arguments to be passed to the crud handlers.
  * @property {import('./commonCrud.js').Pk} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
- * @property {{[key:string]: any}} partialObject - The data to be acted upon.
- * @property {{[key:string]: any}} params - The arguments to be passed to the retrieve function.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ * @property {{[key:string]: any}} partialObject - The changed fields only.
+ * @property {{[key:string]: any}} params - Your listing or retrieval 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.
  */
 /**
  * @typedef {PartialArgsRaw & AdditionalCrudArgs} PartialArgs - Arguments for an object patch (partial update) operation, combining the raw arguments with any additional CRUD arguments.
@@ -92,11 +92,11 @@ import { readonly } from "vue";
 
 /**
  * @typedef {object} ObjectExecuteActionArgsRaw - Raw arguments for a single-object execute-action operation before additional CRUD arguments are merged in.
- * @property {import('../config/objectCrud.js').TargetArgs} target - The arguments to be passed to the crud handlers.
- * @property {string} pk - The id of the objects to be acted upon.
+ * @property {TargetArgs} target - The arguments to be passed to the crud handlers.
+ * @property {import('./commonCrud.js').Pk} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
  * @property {string} action - The action to execute.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 
 /**
@@ -114,9 +114,9 @@ import { readonly } from "vue";
  * @property {TargetArgs} target - The arguments to be passed to the crud handlers.
  * @property {import('./commonCrud.js').Pk} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
- * @property {{[key:string]: any}} params - The arguments to be passed to the retrieve function.
+ * @property {{[key:string]: any}} params - Your listing or retrieval arguments, passed through to the crud handlers.
  * @property {CrudSubscribeCallback} callback - The callback to be called when the object is updated.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 
 /**
@@ -124,43 +124,57 @@ import { readonly } from "vue";
  */
 
 /**
- * @typedef {import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string>} CrudResponse - The value returned by an object CRUD handler, a possibly-cancellable promise resolving to an object or string.
+ * @typedef {import('../utils/cancellablePromise.js').MaybeCancellablePromise<object>} CrudResponse -
+ *  The value returned by an object CRUD handler whose resolved value becomes the record: create, retrieve, update, and
+ *  patch. A possibly-cancellable promise resolving to the complete record. The instance mirrors the resolved value
+ *  into `state.object`, so a partial record drops the fields it omits, and a resolved value that is not an object (a
+ *  bare primary key string, for instance) fails the assignment and is stored in `state.error`.
+ */
+
+/**
+ * @typedef {import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string|void>} CrudCompletionResponse -
+ *  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.
  */
 
 /**
  * @callback CrudCreateFn - Signature for the handler that creates an object in the backing store.
  * @param {CreateArgs} args - The arguments to be passed to the create function.
- * @returns {CrudResponse} - The response data from the create function.
+ * @returns {CrudResponse} - A promise resolving the created record in full.
  */
 
 /**
  * @callback CrudRetrieveFn - Signature for the handler that retrieves an object from the backing store.
  * @param {RetrieveArgs} args - The arguments to be passed to the retrieve function.
- * @returns {CrudResponse} - The response data from the retrieve function.
+ * @returns {CrudResponse} - A promise resolving the retrieved record in full.
  */
 
 /**
  * @callback CrudUpdateFn - Signature for the handler that updates an object in the backing store.
  * @param {UpdateArgs} args - The arguments to be passed to the update function.
- * @returns {CrudResponse} - The response data from the update function.
+ * @returns {CrudResponse} - A promise resolving the updated record in full.
  */
 
 /**
  * @callback CrudPatchFn - Signature for the handler that partially updates (patches) an object in the backing store.
  * @param {PartialArgs} args - The arguments to be passed to the patch function.
- * @returns {CrudResponse} - The response data from the patch function.
+ * @returns {CrudResponse} - A promise resolving the patched record in full, not just the changed fields.
  */
 
 /**
  * @callback CrudDeleteFn - Signature for the handler that deletes an object from the backing store.
  * @param {DeleteArgs} args - The arguments to be passed to the delete function.
- * @returns {CrudResponse} - The response data from the delete function.
+ * @returns {CrudCompletionResponse} - A promise whose resolution means the delete succeeded; its value is ignored.
  */
 
 /**
- * @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 {CrudResponse} - The response data from the delete function.
+ * @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.0.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,13 +65,14 @@
     "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",
     "vite": "^8.0.16",
+    "vitepress": "^1.6.4",
     "vitest": "^4.1.9",
     "vue-eslint-parser": "^10.4.1"
   },
@@ -82,6 +88,12 @@
     "vue": "^3.5.13"
   },
   "scripts": {
+    "benchmark": "vitest bench --run",
+    "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:stream": "vitest bench --run tests/benchmarks/listStream.bench.js",
     "test": "vitest",
     "eslint": "eslint --fix index.js config/**/*.js tests/**/*.js use/**/*.js utils/**/*.js",
     "prettier": "prettier --write .",
@@ -89,6 +101,10 @@
     "docs": "node make_type_doc.js",
     "docs:check": "node check_type_doc.js",
     "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"
   }