@arrai-innovations/reactive-helpers 21.1.2 → 22.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2021-2026, Arrai Innovations Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,57 +1,141 @@
 # reactive-helpers
 
-![Tests for 14.x](https://docs.arrai-dev.com/reactive-helpers/artifacts/main/tests.svg)
-[![Coverage for 14.x](https://docs.arrai-dev.com/reactive-helpers/artifacts/main/tests.coverage.svg)](https://docs.arrai-dev.com/reactive-helpers/artifacts/main/coverage_tests/)
-![ESLint](https://docs.arrai-dev.com/reactive-helpers/artifacts/main/eslint.svg)
-![Prettier](https://docs.arrai-dev.com/reactive-helpers/artifacts/main/prettier.svg)
-![Audit](https://docs.arrai.dev/reactive-helpers/artifacts/main/npm-audit.svg)
+![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)
+[![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 and other helpers.
+Vue.js 3 composition utilities to manage reactive lists, objects, loading and error state, and the small helpers that
+support them. The composables give you reactive state plus actions; you supply the data layer (how a list or object
+reaches your backend), so the package stays transport agnostic.
 
 <!-- prettier-ignore-start -->
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
+- [Features](#features)
+- [Requirements](#requirements)
 - [Install](#install)
 - [Usage](#usage)
+  - [Quick start](#quick-start)
+  - [Wiring a data layer](#wiring-a-data-layer)
 - [Changelog](#changelog)
+- [Contributing](#contributing)
 - [Development](#development)
+- [License](#license)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 <!-- prettier-ignore-end -->
 
+## 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).
+
+## 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.
+- 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).
+
 ## Install
 
 ```bash
-$ npm install @arrai-innovations/reactive-helpers
+$ npm install @arrai-innovations/reactive-helpers vue @vueuse/core lodash-es
 ```
 
 ## Usage
 
-The package exposes many composables and helper utilities. A minimal example of using a list instance is shown below.
+### Quick start
+
+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 props = reactive({
-    target: { stream: "contacts" },
-    pkKey: "id",
-    params: { fields: ["id", "name"] },
+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;
+        },
+    },
 });
 
-const contacts = useListInstance({ props });
 await contacts.list();
 console.log(contacts.state.objects);
 ```
 
-See [docs/README.md](./docs/README.md) for a full list of modules, composables, utilities, as well as, their arguments
-and properties.
+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.
 
 ## Changelog
 
 Since v21.0.0, the changelog is available in the [CHANGELOG.md](./CHANGELOG.md) file.
 
+## Contributing
+
+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.
+
 ## Development
 
 1. Checkout this repo:
@@ -63,34 +147,38 @@ Since v21.0.0, the changelog is available in the [CHANGELOG.md](./CHANGELOG.md)
 2. Install dependencies:
 
     ```bash
-    $ npm install --dev
+    $ pnpm install
     ```
 
 3. Run tests via vitest:
 
     ```bash
-    $ npm test
+    $ pnpm test
     ```
 
 4. Run tests with coverage output:
 
     ```bash
-    $ npm run coverage
+    $ pnpm coverage
     ```
 
 5. Generate types and typedocs:
 
     ```bash
-    $ npm run docs
+    $ pnpm run docs
     ```
 
 6. Type-only workflows:
 
     - Generate types without docs:
         ```bash
-        $ npm run types
+        $ pnpm run types
         ```
     - Smoke-check emitted types without regenerating:
         ```bash
-        $ npm run types:check -- --skip-gen
+        $ pnpm run types:check -- --skip-gen
         ```
+
+## License
+
+[BSD-3-Clause](./LICENSE) © Arrai Innovations Inc.

package/config/commonCrud.js

@@ -5,18 +5,15 @@ import isFunction from "lodash-es/isFunction.js";
 import { refIfReactive } from "../utils/refIfReactive.js";
 
 /**
- * Primary key type accepted as input (will be coerced to string).
- *
- * @typedef {string | number} PkInput
+ * @typedef {string | number} PkInput - Primary key type accepted as input (will be coerced to string).
  */
 
 /**
- * Primary key type used for storage and output (always a string).
- *
- * @typedef {string} Pk
+ * @typedef {string} Pk - Primary key type used for storage and output (always a string).
  */
 
 /**
+ * @internal
  * @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.
  */
@@ -26,6 +23,7 @@ export const missingMethod = (name) => () =>
 // HACK: eslint, tsc, webstorm all can't agree on how to do this right
 // noinspection JSValidateTypes,JSUnusedLocalSymbols
 /**
+ * @internal
  * @param {string} name - The name of the method.
  * @returns {(
  *     (..._args: any[]) => import('../utils/cancellablePromise.js').CancellablePromise<void>

package/config/listCrud.js

@@ -9,25 +9,23 @@ import { readonly } from "vue";
  */
 
 /**
- * @typedef {import("../use/listInstance.js").ClearListFn} ClearObjectsFn
+ * @typedef {import("../use/listInstance.js").ClearListFn} ClearObjectsFn - Signature for the handler that clears the objects held by the list.
  */
 
 /**
- * @typedef {import("../use/listInstance.js").SetPaginateInfoFn} SetPaginateInfo
+ * @typedef {import("../use/listInstance.js").SetPaginateInfoFn} SetPaginateInfo - Signature for the handler that updates the list's pagination information.
  */
 
 /**
- * @typedef {import("../use/listInstance.js").SetColumnTotalsFn} SetColumnTotals
+ * @typedef {import("../use/listInstance.js").SetColumnTotalsFn} SetColumnTotals - Signature for the handler that updates the list's column totals.
  */
 
 /**
- * Additional arguments that can be passed to list crud handlers.
- *
- * @typedef {{[key:string]: any}} AdditionalListArgs
+ * @typedef {{[key:string]: any}} AdditionalListArgs - Additional arguments that can be passed to list crud handlers.
  */
 
 /**
- * @typedef {object} ListArgsRaw
+ * @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.
@@ -40,29 +38,29 @@ import { readonly } from "vue";
  */
 
 /**
- * @typedef {ListArgsRaw & Partial<import('../use/cancellableIntent.js').CommonRunTracking> & AdditionalListArgs} ListArgs
+ * @typedef {ListArgsRaw & Partial<import('../use/cancellableIntent.js').CommonRunTracking> & AdditionalListArgs} ListArgs - Arguments for a list operation, combining the raw arguments with run-tracking and any additional list CRUD arguments.
  */
 
 /**
- * @typedef {object} BulkDeleteArgsRaw
+ * @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 {string} pkKey - The key name of the primary key.
  */
 
 /**
- * @typedef {BulkDeleteArgsRaw & AdditionalListArgs} BulkDeleteArgs
+ * @typedef {BulkDeleteArgsRaw & AdditionalListArgs} BulkDeleteArgs - Arguments for a bulk-delete operation, combining the raw arguments with any additional list CRUD arguments.
  */
 
 /**
  * @typedef {(
  *     newOrUpdatedOrDeleteObject:import('../use/objectInstance.js').ExistingCrudObject|string,
  *     action: 'create'|'update'|'delete'
- * )=>void} applyObjectEvent
+ * )=>void} applyObjectEvent - Callback that applies a created, updated, or deleted object event received from a subscription to the list.
  */
 
 /**
- * @typedef {object} ListSubscribeArgsRaw
+ * @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.
@@ -72,11 +70,11 @@ import { readonly } from "vue";
  */
 
 /**
- * @typedef {ListSubscribeArgsRaw & Partial<import('../use/cancellableIntent.js').CommonRunTracking> & AdditionalListArgs } ListSubscribeArgs
+ * @typedef {ListSubscribeArgsRaw & Partial<import('../use/cancellableIntent.js').CommonRunTracking> & AdditionalListArgs } ListSubscribeArgs - Arguments for a list subscribe operation, combining the raw arguments with run-tracking and any additional list CRUD arguments.
  */
 
 /**
- * @typedef {object} ExecuteActionArgsRaw
+ * @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 {string} pkKey - The key name of the primary key.
@@ -84,35 +82,35 @@ import { readonly } from "vue";
  */
 
 /**
- * @typedef {ExecuteActionArgsRaw  & AdditionalListArgs } ExecuteActionArgs
+ * @typedef {ExecuteActionArgsRaw  & AdditionalListArgs } ExecuteActionArgs - Arguments for a list execute-action operation, combining the raw arguments with any additional list CRUD arguments.
  */
 
 /**
- * @callback CrudListFn
+ * @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.
  */
 
 /**
- * @callback CrudBulkDeleteFn
+ * @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.
  */
 
 /**
- * @callback CrudListSubscribeFn
+ * @callback CrudListSubscribeFn - Signature for the handler that subscribes to list changes in the backing store.
  * @param {ListSubscribeArgs} args - The arguments to be passed to the crud handlers.
  * @returns {import('../utils/cancellablePromise.js').CancellablePromise<void>} - A cancellable promise for the subscription.
  */
 
 /**
- * @callback CrudExecuteActionFn
+ * @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.
  */
 
 /**
- * @typedef {object} ListCrudHandlers
+ * @typedef {object} ListCrudHandlers - The set of optional CRUD handler functions (list, bulkDelete, executeAction, subscribe) for a list.
  * @property {CrudListFn} [list] - The list function to get a list of items.
  * @property {CrudBulkDeleteFn} [bulkDelete] - The delete function to bulk delete a list of items.
  * @property {CrudExecuteActionFn} [executeAction] - The  function to execute a certain action on a list of items.
@@ -120,12 +118,12 @@ import { readonly } from "vue";
  */
 
 /**
- * @typedef {object} ListTarget
+ * @typedef {object} ListTarget - The default target arguments passed through to the list CRUD handlers.
  * @property {object} args - The default arguments for the crud handlers.
  */
 
 /**
- * @typedef {object} ListTargetOption
+ * @typedef {object} ListTargetOption - Optional target arguments passed through to the list CRUD handlers.
  * @property {object} [target={}] - The default arguments for the crud handlers.
  */
 

package/config/objectCrud.js

@@ -9,29 +9,25 @@ import { readonly } from "vue";
  */
 
 /**
- * @typedef {{[key:string]: any}} TargetArgs
+ * @typedef {{[key:string]: any}} TargetArgs - Implementation-specific arguments passed through to the CRUD handlers, such as endpoint identifiers.
  */
 
 /**
- * Additional arguments that can be passed to CRUD handlers.
- *
- * @typedef {{[key:string]: any}} AdditionalCrudArgs
+ * @typedef {{[key:string]: any}} AdditionalCrudArgs - Additional arguments that can be passed to CRUD handlers.
  */
 
 /**
- * Defines the CRUD-related handlers and additional utilities provided by the object instance.
- *
- * @typedef {object} ObjectTargetProperties
+ * @typedef {object} ObjectTargetProperties - Defines the CRUD-related handlers and additional utilities provided by the object instance.
  * @property {TargetArgs} args - The arguments to be passed to the crud handlers.
  */
 
 /**
- * @typedef {object} ObjectTargetOption
+ * @typedef {object} ObjectTargetOption - Optional target arguments passed through to the object CRUD handlers.
  * @property {TargetArgs} [target={}] - The arguments to be passed to the crud handlers.
  */
 
 /**
- * @typedef {object} CreateArgsRaw
+ * @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.
@@ -40,11 +36,11 @@ import { readonly } from "vue";
  */
 
 /**
- * @typedef {CreateArgsRaw & AdditionalCrudArgs} CreateArgs
+ * @typedef {CreateArgsRaw & AdditionalCrudArgs} CreateArgs - Arguments for an object create operation, combining the raw arguments with any additional CRUD arguments.
  */
 
 /**
- * @typedef {object} RetrieveArgsRaw
+ * @typedef {object} RetrieveArgsRaw - Raw arguments for an object retrieve operation before run-tracking and additional CRUD arguments are merged in.
  * @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.
@@ -53,11 +49,11 @@ import { readonly } from "vue";
  */
 
 /**
- * @typedef {RetrieveArgsRaw & Partial<import('../use/cancellableIntent.js').CommonRunTracking> & AdditionalCrudArgs} RetrieveArgs
+ * @typedef {RetrieveArgsRaw & Partial<import('../use/cancellableIntent.js').CommonRunTracking> & AdditionalCrudArgs} RetrieveArgs - Arguments for an object retrieve operation, combining the raw arguments with run-tracking and any additional CRUD arguments.
  */
 
 /**
- * @typedef {object} UpdateArgsRaw
+ * @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.
@@ -66,22 +62,23 @@ import { readonly } from "vue";
  */
 
 /**
- * @typedef {UpdateArgsRaw & AdditionalCrudArgs} UpdateArgs
+ * @typedef {UpdateArgsRaw & AdditionalCrudArgs} UpdateArgs - Arguments for an object update operation, combining the raw arguments with any additional CRUD arguments.
  */
 
 /**
- * @typedef {object} DeleteArgsRaw
+ * @typedef {object} DeleteArgsRaw - Raw arguments for an object delete operation before additional CRUD arguments are merged in.
  * @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.
  */
 
 /**
- * @typedef {DeleteArgsRaw & AdditionalCrudArgs} DeleteArgs
+ * @typedef {DeleteArgsRaw & AdditionalCrudArgs} DeleteArgs - Arguments for an object delete operation, combining the raw arguments with any additional CRUD arguments.
  */
 
 /**
- * @typedef {object} PartialArgsRaw
+ * @typedef {object} PartialArgsRaw - Raw arguments for an object patch (partial update) operation before additional CRUD arguments are merged in.
  * @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.
@@ -90,11 +87,11 @@ import { readonly } from "vue";
  * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
  */
 /**
- * @typedef {PartialArgsRaw & AdditionalCrudArgs} PartialArgs
+ * @typedef {PartialArgsRaw & AdditionalCrudArgs} PartialArgs - Arguments for an object patch (partial update) operation, combining the raw arguments with any additional CRUD arguments.
  */
 
 /**
- * @typedef {object} ObjectExecuteActionArgsRaw
+ * @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 {string} pkKey - The key name of the primary key.
@@ -103,17 +100,17 @@ import { readonly } from "vue";
  */
 
 /**
- * @typedef {ObjectExecuteActionArgsRaw & AdditionalCrudArgs} ObjectExecuteActionArgs
+ * @typedef {ObjectExecuteActionArgsRaw & AdditionalCrudArgs} ObjectExecuteActionArgs - Arguments for a single-object execute-action operation, combining the raw arguments with any additional CRUD arguments.
  */
 
 /**
- * @callback CrudSubscribeCallback
+ * @callback CrudSubscribeCallback - Callback invoked with the changed object and the action (create, update, or delete) when a subscribed object changes.
  * @param {import('../use/objectInstance.js').ExistingCrudObject} data - The data to be passed to the callback.
  * @param {"delete"|"update"|"create"} action - The action that was performed.
  */
 
 /**
- * @typedef {object} ObjectSubscribeArgsRaw
+ * @typedef {object} ObjectSubscribeArgsRaw - Raw arguments for a single-object subscribe operation before run-tracking and additional CRUD arguments are merged in.
  * @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.
@@ -123,59 +120,57 @@ import { readonly } from "vue";
  */
 
 /**
- * @typedef {ObjectSubscribeArgsRaw & import('../use/cancellableIntent.js').CommonRunTracking & AdditionalCrudArgs} ObjectSubscribeArgs
+ * @typedef {ObjectSubscribeArgsRaw & import('../use/cancellableIntent.js').CommonRunTracking & AdditionalCrudArgs} ObjectSubscribeArgs - Arguments for a single-object subscribe operation, combining the raw arguments with run-tracking and any additional CRUD arguments.
  */
 
 /**
- * @typedef {import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string>} CrudResponse
+ * @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.
  */
 
 /**
- * @callback CrudCreateFn
+ * @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.
  */
 
 /**
- * @callback CrudRetrieveFn
+ * @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.
  */
 
 /**
- * @callback CrudUpdateFn
+ * @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.
  */
 
 /**
- * @callback CrudPatchFn
+ * @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.
  */
 
 /**
- * @callback CrudDeleteFn
+ * @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.
  */
 
 /**
- * @callback CrudObjectExecuteActionFn
+ * @callback CrudObjectExecuteActionFn - Signature for the handler that executes an action on a single object in the backing store.
  * @param {ObjectExecuteActionArgs} args - The arguments to be passed to the executeAction function.
  * @returns {CrudResponse} - The response data from the delete function.
  */
 
 /**
- * @callback CrudObjectSubscribeFn
+ * @callback CrudObjectSubscribeFn - Signature for the handler that subscribes to changes on a single object in the backing store.
  * @param {ObjectSubscribeArgs} args - The arguments to be passed to the subscribe function.
  * @returns {import('../utils/cancellablePromise.js').CancellablePromise<void>} - The cancellable promise.
  */
 
 /**
- * Defines the CRUD-related handlers and additional utilities provided by the object instance.
- *
- * @typedef {object} ObjectCrudHandlers
+ * @typedef {object} ObjectCrudHandlers - Defines the CRUD-related handlers and additional utilities provided by the object instance.
  * @property {CrudCreateFn} [create] - A function to be used instead of the default crud create function.
  * @property {CrudRetrieveFn} [retrieve] - A function to be used instead of the default crud retrieve function.
  * @property {CrudUpdateFn} [update] - A function to be used instead of the default crud update function.
@@ -187,9 +182,7 @@ import { readonly } from "vue";
  */
 
 /**
- * The CRUD arguments.
- *
- * @typedef {ObjectTargetProperties & ObjectCrudHandlers} ObjectTarget
+ * @typedef {ObjectTargetProperties & ObjectCrudHandlers} ObjectTarget - The CRUD arguments.
  *
  */