@arrai-innovations/reactive-helpers 22.0.0 → 22.1.0

package/README.md

@@ -44,7 +44,7 @@ reaches your backend), so the package stays transport agnostic.
 
 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).
+[docs/reference/api/index.md](./docs/reference/api/index.md).
 
 ## Requirements
 
@@ -119,8 +119,8 @@ 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.
+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
 

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,7 +43,7 @@ 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.
  */
 
@@ -63,10 +62,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,7 +74,7 @@ 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.
  */
@@ -88,13 +86,16 @@ 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 {Promise<boolean>} - A promise whose resolution means the bulk delete succeeded; the resolved value is not
+ *  inspected, and the instance then empties the list.
  */
 
 /**
@@ -106,7 +107,8 @@ 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 {Promise<object|string|null>} - A promise resolving the action's result, which `listInstance.executeAction`
+ *  passes through to its caller.
  */
 
 /**

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,55 @@ 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 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.
  */
 
 /**
  * @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.
  * @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 whose resolution means the action succeeded; its value is ignored, and
+ *  `objectInstance.executeAction` resolves `true`.
  */
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arrai-innovations/reactive-helpers",
-  "version": "22.0.0",
+  "version": "22.1.0",
   "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
   "main": "index.js",
   "type": "module",
@@ -67,6 +67,7 @@
     "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 +83,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 +96,9 @@
     "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:preview": "vitepress preview docs",
     "types": "node make_types.js",
     "types:check": "node check_types.js"
   }

package/types/config/listCrud.d.ts

@@ -40,7 +40,7 @@ export type ListArgsRaw = {
      */
     pkKey: string;
     /**
-     * The arguments to be passed for list crud handlers.
+     * Your listing or retrieval arguments, passed through to the crud handlers.
      */
     params: object;
     /**
@@ -52,8 +52,7 @@ export type ListArgsRaw = {
      */
     clearObjects: ClearObjectsFn;
     /**
-     * A ref to a boolean indicating whether the request has
-     * been cancelled.
+     * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
     /**
@@ -78,7 +77,7 @@ export type BulkDeleteArgsRaw = {
      */
     target: import("../config/objectCrud.js").TargetArgs;
     /**
-     * The ids of the objects to be deleted.
+     * The pks of the objects to be deleted.
      */
     pks: import("./commonCrud.js").Pk[];
     /**
@@ -107,7 +106,7 @@ export type ListSubscribeArgsRaw = {
      */
     pkKey: string;
     /**
-     * The arguments to be passed for list crud handlers.
+     * Your listing or retrieval arguments, passed through to the crud handlers.
      */
     params: object;
     /**
@@ -115,8 +114,7 @@ export type ListSubscribeArgsRaw = {
      */
     applyObjectEvent: applyObjectEvent;
     /**
-     * A ref to a boolean indicating whether the request has
-     * been cancelled.
+     * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
@@ -133,7 +131,7 @@ export type ExecuteActionArgsRaw = {
      */
     target: import("../config/objectCrud.js").TargetArgs;
     /**
-     * The ids of the objects to be acted upon.
+     * The pks of the objects to be acted upon.
      */
     pks: import("./commonCrud.js").Pk[];
     /**

package/types/config/objectCrud.d.ts

@@ -48,13 +48,13 @@ export type CreateArgsRaw = {
      */
     target: TargetArgs;
     /**
-     * The data to be acted upon.
+     * The new object to create; it carries no primary key yet.
      */
     object: {
         [key: string]: any;
     };
     /**
-     * The arguments to be passed to the retrieve function.
+     * Your listing or retrieval arguments, passed through to the crud handlers.
      */
     params: {
         [key: string]: any;
@@ -64,7 +64,7 @@ export type CreateArgsRaw = {
      */
     pkKey: string;
     /**
-     * A ref to indicate if the request was cancelled.
+     * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
@@ -89,13 +89,13 @@ export type RetrieveArgsRaw = {
      */
     pkKey: string;
     /**
-     * The arguments to be passed to the retrieve function.
+     * Your listing or retrieval arguments, passed through to the crud handlers.
      */
     params: {
         [key: string]: any;
     };
     /**
-     * A ref to indicate if the request was cancelled.
+     * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
@@ -112,11 +112,11 @@ export type UpdateArgsRaw = {
      */
     target: TargetArgs;
     /**
-     * The data to be acted upon.
+     * The complete object to update; its primary key rides inside it, at `object[pkKey]`.
      */
     object: import("../use/objectInstance.js").ExistingCrudObject;
     /**
-     * The arguments to be passed to the retrieve function.
+     * Your listing or retrieval arguments, passed through to the crud handlers.
      */
     params: {
         [key: string]: any;
@@ -126,7 +126,7 @@ export type UpdateArgsRaw = {
      */
     pkKey: string;
     /**
-     * A ref to indicate if the request was cancelled.
+     * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
@@ -151,7 +151,7 @@ export type DeleteArgsRaw = {
      */
     pkKey: string;
     /**
-     * A ref to indicate if the request was cancelled.
+     * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
@@ -176,19 +176,19 @@ export type PartialArgsRaw = {
      */
     pkKey: string;
     /**
-     * The data to be acted upon.
+     * The changed fields only.
      */
     partialObject: {
         [key: string]: any;
     };
     /**
-     * The arguments to be passed to the retrieve function.
+     * Your listing or retrieval arguments, passed through to the crud handlers.
      */
     params: {
         [key: string]: any;
     };
     /**
-     * A ref to indicate if the request was cancelled.
+     * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
@@ -203,11 +203,11 @@ export type ObjectExecuteActionArgsRaw = {
     /**
      * The arguments to be passed to the crud handlers.
      */
-    target: import("../config/objectCrud.js").TargetArgs;
+    target: TargetArgs;
     /**
-     * The id of the objects to be acted upon.
+     * The pk of the object to be acted upon.
      */
-    pk: string;
+    pk: import("./commonCrud.js").Pk;
     /**
      * The key name of the primary key.
      */
@@ -217,7 +217,7 @@ export type ObjectExecuteActionArgsRaw = {
      */
     action: string;
     /**
-     * A ref to indicate if the request was cancelled.
+     * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
@@ -246,7 +246,7 @@ export type ObjectSubscribeArgsRaw = {
      */
     pkKey: string;
     /**
-     * The arguments to be passed to the retrieve function.
+     * Your listing or retrieval arguments, passed through to the crud handlers.
      */
     params: {
         [key: string]: any;
@@ -256,7 +256,7 @@ export type ObjectSubscribeArgsRaw = {
      */
     callback: CrudSubscribeCallback;
     /**
-     * A ref to indicate if the request was cancelled.
+     * A readonly ref that becomes true once the request is cancelled.
      */
     isCancelled: Readonly<import("vue").Ref<boolean>>;
 };
@@ -265,9 +265,20 @@ export type ObjectSubscribeArgsRaw = {
  */
 export type ObjectSubscribeArgs = ObjectSubscribeArgsRaw & import("../use/cancellableIntent.js").CommonRunTracking & AdditionalCrudArgs;
 /**
- * The value returned by an object CRUD handler, a possibly-cancellable promise resolving to an object or string.
+ * -
+ *  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`.
+ */
+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.
  */
-export type CrudResponse = import("../utils/cancellablePromise.js").MaybeCancellablePromise<object | string>;
+export type CrudCompletionResponse = import("../utils/cancellablePromise.js").MaybeCancellablePromise<object | string | void>;
 /**
  * Signature for the handler that creates an object in the backing store.
  */
@@ -287,11 +298,11 @@ export type CrudPatchFn = (args: PartialArgs) => CrudResponse;
 /**
  * Signature for the handler that deletes an object from the backing store.
  */
-export type CrudDeleteFn = (args: DeleteArgs) => CrudResponse;
+export type CrudDeleteFn = (args: DeleteArgs) => CrudCompletionResponse;
 /**
  * Signature for the handler that executes an action on a single object in the backing store.
  */
-export type CrudObjectExecuteActionFn = (args: ObjectExecuteActionArgs) => CrudResponse;
+export type CrudObjectExecuteActionFn = (args: ObjectExecuteActionArgs) => CrudCompletionResponse;
 /**
  * Signature for the handler that subscribes to changes on a single object in the backing store.
  */

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

@@ -0,0 +1,60 @@
+export namespace benchmarkOptions {
+    let iterations: number;
+    let time: number;
+    let warmupIterations: number;
+    let warmupTime: number;
+}
+export function makeRows(count: number, start?: number): {
+    id: number;
+    name: string;
+}[];
+export function makeRichRows(count: number, start?: number): {
+    id: number;
+    name: string;
+    organization: number;
+}[];
+/** Related objects the populated related rule resolves against. */
+export const relatedOrganizations: {
+    [k: string]: {
+        id: number;
+        name: string;
+    };
+};
+export namespace emptyRules {
+    let allowedFilter: any;
+    let calculatedObjectsRules: {};
+    let excludedFilter: any;
+    let orderByRules: any[];
+    let relatedObjectsRules: {};
+    let textSearchRules: any[];
+    let textSearchValue: string;
+}
+export namespace populatedRules {
+    export function allowedFilter_1(object: any): boolean;
+    export { allowedFilter_1 as allowedFilter };
+    export namespace calculatedObjectsRules_1 {
+        function doubled(object: any): number;
+    }
+    export { calculatedObjectsRules_1 as calculatedObjectsRules };
+    let excludedFilter_1: any;
+    export { excludedFilter_1 as excludedFilter };
+    let orderByRules_1: {
+        key: string;
+        desc: boolean;
+        localeCompare: boolean;
+    }[];
+    export { orderByRules_1 as orderByRules };
+    export namespace relatedObjectsRules_1 {
+        namespace org {
+            export let pkKey: string;
+            export { relatedOrganizations as objects };
+        }
+    }
+    export { relatedObjectsRules_1 as relatedObjectsRules };
+    let textSearchRules_1: any[];
+    export { textSearchRules_1 as textSearchRules };
+    let textSearchValue_1: string;
+    export { textSearchValue_1 as textSearchValue };
+}
+export function makeList(rules?: object): ReturnType<typeof useList>;
+import { useList } from "../../use/list.js";

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

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

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

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

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

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

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

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

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

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

package/types/tests/unit/utils/cancellablePromise.spec.d.ts

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

package/types/use/cancellableIntent.d.ts

@@ -57,12 +57,19 @@
 /**
  * Calls your awaitable function with the arguments you pass in when the watch arguments change and are all truthy.
  * Watch arguments should be a reactive object.
- * If the promise is not resolved before the watch arguments change again, the previous promise is cancelled.
+ *
+ * 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.
  *
  * @example
  * ```vue
  * <script setup>
- * import { useCancellableIntent } from "@vueda/use/cancellableIntent.js";
+ * import { useCancellableIntent } from "@arrai-innovations/reactive-helpers";
  * import { ref, computed, onMounted, onUnmounted } from "vue";
  *
  * const myValue = ref(0);