@arrai-innovations/reactive-helpers 21.1.2 → 22.1.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/reference/api/index.md](./docs/reference/api/index.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/reference/api/index.md](./docs/reference/api/index.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

@@ -1,31 +1,28 @@
-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";
 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.
  */
-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
 /**
+ * @internal
  * @param {string} name - The name of the method.
  * @returns {(
  *     (..._args: any[]) => import('../utils/cancellablePromise.js').CancellablePromise<void>
@@ -36,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

@@ -9,110 +9,110 @@ 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.
+ * @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.
  */
 
 /**
- * @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 {import('./commonCrud.js').Pk[]} pks - The pks 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.
+ * @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.
  */
 
 /**
- * @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 {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.
  */
 
 /**
- * @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.
+ * @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
+ * @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 {Promise<boolean>} - A promise whose resolution means the bulk delete succeeded; the resolved value is not
+ *  inspected, and the instance then empties the list.
  */
 
 /**
- * @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.
+ * @returns {Promise<object|string|null>} - A promise resolving the action's result, which `listInstance.executeAction`
+ *  passes through to its caller.
  */
 
 /**
- * @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 +120,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.
  */