@arrai-innovations/reactive-helpers 22.0.0 → 22.1.0

package/use/listCalculated.js

@@ -21,17 +21,17 @@ import { computed, effectScope, nextTick, reactive, ref, toRef, toRefs, unref, w
  *             [rule: string]: any,
  *         },
  *         calculatedObjects: {
- *             [rule: string]: import('vue').ComputedRef<any>,
+ *             [rule: string]: any,
  *         }
  *     ) => any,
- * }}  ListCalculatedRules - Defines rules for dynamically calculating new properties for objects in a list. Each rule is a function that takes an object from the list, optionally its related objects, and previously calculated properties to compute a new property. These functions are reactive and re-evaluate when underlying dependencies change.
+ * }}  ListCalculatedRules - Defines rules for dynamically calculating new properties for objects in a list. Each rule is a function that takes an object from the list, optionally its related objects, and previously calculated properties to compute a new property. These functions are reactive and re-evaluate when underlying dependencies change. Each entry of the third argument is backed by a computed, but it is read through a reactive proxy that unwraps it, so a rule reads `calculatedObjects.otherRule` directly and never `.value`.
  */
 
 /**
  * The raw state for a list calculated.
  *
  * @typedef {object} ListCalculatedRawState - The raw state for a list calculated property.
- * @property {{[pk: import('../config/commonCrud.js').Pk]: {[rule: string]: import('vue').ComputedRef<any>}}} calculatedObjects - The calculated objects.
+ * @property {{[pk: import('../config/commonCrud.js').Pk]: {[rule: string]: any}}} calculatedObjects - The calculated objects, by object pk and then rule name. Each entry is backed by a computed, but it is read through a reactive proxy that unwraps it, so reads yield the calculated value and never carry a `.value`.
  * @property {ListCalculatedRules} calculatedObjectsRules - The rules for the calculated objects.
  * @property {boolean} calculatedObjectsParentStateObjectsWatchRunning - Whether the parent state objects watch is running.
  * @property {boolean} calculatedObjectsWatchRunning - Whether the calculated objects watch is running.
@@ -66,7 +66,7 @@ import { computed, effectScope, nextTick, reactive, ref, toRef, toRefs, unref, w
 /**
  * The options to create a list calculated composition function.
  *
- * @typedef {object} ListCalculatedOptions - Options to configure the behavior of the list calculated properties.
+ * @typedef {object} ListCalculatedOptions - Options to configure the behaviour of the list calculated properties.
  * @property {ListCalculatedParentState} parentState - The parent state that interacts with the calculated objects.
  * @property {import('vue').Ref<ListCalculatedRules>} calculatedObjectsRules - A reactive reference to rules used for dynamic calculations
  *  within list objects. Proper setup of this reference ensures that updates are managed reactively, including deep
@@ -114,7 +114,7 @@ export function useListCalculateds(listCalculatedArgs) {
  * ```vue
  * <script setup>
  * import { useListSubscription, useListCalculated } from "@arrai-innovations/reactive-helpers";
- * import { reactive, toRef } from "vue";
+ * import { reactive } from "vue";
  *
  * const listSubscriptionProps = reactive({
  *     // whatever props you need to get the list to work with your crud implementation
@@ -123,14 +123,15 @@ export function useListCalculateds(listCalculatedArgs) {
  *     pkKey: "pk",
  *     intendToList: true,
  * });
- * const listSubscription = useListSubscription(listSubscriptionProps);
+ * const listSubscription = useListSubscription({ props: listSubscriptionProps });
  * const listCalculatedProps = reactive({
  *     parentState: listSubscription.state,
- *     computedObjectsRules: {
- *         someRule: (object, relatedObjects, calculatedObjects) => {
- *            // some complex calculation, relatedObjects would be assuming there was a listRelated between the two
- *            // calculatedObjects would be the other calculated objects in the list
- *            // including yourself, so try not to create circular dependencies
+ *     calculatedObjectsRules: {
+ *         someRule: (object, relatedObject, calculatedObjects) => {
+ *            // some complex calculation. relatedObject holds this object's related objects, and is only
+ *            // populated when a useListRelated sits between the list and this composable.
+ *            // calculatedObjects holds the other calculated values for this same object,
+ *            // including this rule, so try not to create circular dependencies.
  *            // this is used as a computed body.
  *            return object.someProperty + object.someOtherProperty;
  *         }
@@ -140,12 +141,12 @@ export function useListCalculateds(listCalculatedArgs) {
  * </script>
  * <template>
  *     <ul>
- *         <!-- reactive list of objects, re-retrieving the list as someListFilter changes. -->
- *         <li v-for="obj in listInstance.state.objectsInOrder">
+ *         <!-- reactive list of objects, kept current by the configured subscription function. -->
+ *         <li v-for="obj in listSubscription.state.objectsInOrder">
  *             {{ obj }}
  *             <div>
- *                 <!-- the computed object or objects based on the rule -->
- *                 {{ listCalculated.state.computedObjects[obj.pk].someRule }}
+ *                 <!-- the calculated value for this object, based on the rule -->
+ *                 {{ listCalculated.state.calculatedObjects[obj.pk].someRule }}
  *             </div>
  *         </li>
  *     </ul>
@@ -256,7 +257,7 @@ export function useListCalculated({ parentState, calculatedObjectsRules }) {
     }
 
     watch(
-        () => Object.keys(parentState.objects),
+        () => parentState.objectsVersion,
         () => {
             state.calculatedObjectsParentStateObjectsWatchRunning = true;
         },
@@ -264,7 +265,11 @@ export function useListCalculated({ parentState, calculatedObjectsRules }) {
     );
     watch(() => Object.keys(parentState.objects), parentStateObjectsWatch, { immediate: true });
     watch(
-        () => Object.keys(state.calculatedObjects),
+        [
+            () => parentState.objectsVersion,
+            () =>
+                state.calculatedObjectsRules ? Object.keys(state.calculatedObjectsRules) : state.calculatedObjectsRules,
+        ],
         () => {
             state.calculatedObjectsWatchRunning = true;
         },

package/use/listFilter.js

@@ -170,8 +170,9 @@ export function useListFilter({ parentState, allowedFilter, excludedFilter }) {
 
     es.run(() => {
         watch(
-            () => Object.keys(parentState.objects),
-            (newVal) => {
+            () => parentState.objectsVersion,
+            () => {
+                const newVal = Object.keys(parentState.objects);
                 const { addedKeys, removedKeys } = keyDiff(newVal, Object.keys(includeMap));
                 for (const pk of removedKeys) {
                     disposeIncludeComputed(pk);
@@ -180,7 +181,7 @@ export function useListFilter({ parentState, allowedFilter, excludedFilter }) {
                     ensureIncludeComputed(pk);
                 }
             },
-            { deep: true, immediate: true, flush: "sync" }
+            { immediate: true, flush: "sync" }
         );
     });
 

package/use/listInstance.js

@@ -4,7 +4,7 @@ import { getFakePk } from "../utils/getFakePk.js";
 import { useLoadingError } from "./loadingError.js";
 import inspect from "browser-util-inspect";
 import { computed, effectScope, isReactive, reactive, readonly, ref, shallowReactive } from "vue";
-import { CancellablePromise, wrapMaybeCancellable } from "../utils/cancellablePromise.js";
+import { wrapMaybeCancellable } from "../utils/cancellablePromise.js";
 import { refIfReactive } from "../utils/refIfReactive.js";
 
 /**
@@ -96,6 +96,7 @@ export class ListInstanceError extends Error {
  * @property {object} params - Arguments passed to the server for listing operations.
  * @property {ObjectsMap} objectsMap - The map of objects stored by their pks.
  * @property {ObjectsByPk} objects - The list objects stored by their pks.
+ * @property {number} objectsVersion - Increments when the set of object keys changes.
  * @property {ListOrder} order - The order of objects in the list.
  * @property {ObjectsInOrder} objectsInOrder - The objects in the order specified by the list.
  * @property {import('vue').ShallowReactive<PaginateInfo>} paginateInfo - Pagination information for the list.
@@ -224,7 +225,7 @@ export function useListInstances(listInstanceArgs) {
  * ```
  *
  * @param {ListInstanceOptions} options - Specifies the configuration options for creating a list instance, including
- *  properties for CRUD operations and UI behaviors like page persistence.
+ *  properties for CRUD operations and UI behaviours like page persistence.
  * @returns {ListInstance} The list instance.
  * @throws {ListInstanceError} If the props are missing.
  */
@@ -237,6 +238,30 @@ export function useListInstance({ props, handlers = {} }) {
     }
 
     const es = effectScope();
+    const objectsVersion = ref(0);
+    let objectsBatchDepth = 0;
+    let objectsChangedDuringBatch = false;
+
+    function triggerObjectsChanged() {
+        if (objectsBatchDepth) {
+            objectsChangedDuringBatch = true;
+            return;
+        }
+        objectsVersion.value++;
+    }
+
+    function batchObjectChanges(fn) {
+        objectsBatchDepth++;
+        try {
+            return fn();
+        } finally {
+            objectsBatchDepth--;
+            if (!objectsBatchDepth && objectsChangedDuringBatch) {
+                objectsChangedDuringBatch = false;
+                objectsVersion.value++;
+            }
+        }
+    }
 
     const [_objectsProxy, _objectsMapProxy] = es.run(() => {
         // ### do not use this directly, because we proxy `set` to make sure that values are reactive ###
@@ -273,10 +298,14 @@ export function useListInstance({ props, handlers = {} }) {
                 if (typeof prop === "symbol") {
                     return Reflect.set(target, prop, value);
                 }
+                const hadKey = target.has(prop);
                 if (!isReactive(value)) {
                     value = reactive(value);
                 }
                 target.set(prop, value); // map.set() returns the map, we don't need that
+                if (!hadKey) {
+                    triggerObjectsChanged();
+                }
                 return true;
             },
             ownKeys(target) {
@@ -289,7 +318,11 @@ export function useListInstance({ props, handlers = {} }) {
                 if (typeof p === "symbol") {
                     return Reflect.deleteProperty(target, p);
                 }
-                return target.delete(p);
+                const deleted = target.delete(p);
+                if (deleted) {
+                    triggerObjectsChanged();
+                }
+                return deleted;
             },
             getOwnPropertyDescriptor(target, prop) {
                 if (prop === Symbol.toStringTag) {
@@ -331,17 +364,40 @@ export function useListInstance({ props, handlers = {} }) {
 
         // ### for deep reactivity on map items, we need to make sure each is reactive ###
         const _objectsMapWrappedSet = (key, value) => {
+            const hadKey = _objectsMap.has(key);
             const reactiveValue =
                 typeof value === "object" && value !== null && !isReactive(value) ? reactive(value) : value;
-            return _objectsMap.set(key, reactiveValue);
+            const result = _objectsMap.set(key, reactiveValue);
+            if (!hadKey) {
+                triggerObjectsChanged();
+            }
+            return result;
+        };
+        const _objectsMapWrappedDelete = (key) => {
+            const deleted = _objectsMap.delete(key);
+            if (deleted) {
+                triggerObjectsChanged();
+            }
+            return deleted;
+        };
+        const _objectsMapWrappedClear = () => {
+            if (!_objectsMap.size) {
+                return;
+            }
+            _objectsMap.clear();
+            triggerObjectsChanged();
         };
 
-        // ### wrapping the set method to make sure that values are reactive ###
+        // ### wrapping mutation methods to enforce reactive values and track structural changes ###
         const _objectsMapProxy = new Proxy(_objectsMap, {
             get(target, prop, receiver) {
                 switch (prop) {
                     case "set":
                         return _objectsMapWrappedSet;
+                    case "delete":
+                        return _objectsMapWrappedDelete;
+                    case "clear":
+                        return _objectsMapWrappedClear;
                 }
                 return Reflect.get(target, prop, receiver);
             },
@@ -367,10 +423,10 @@ export function useListInstance({ props, handlers = {} }) {
         // /** @type {{[key: string]: import('../use/objectInstance.js').ExistingCrudObject}} */
         // objects: /** @type {{[key: string]: import('../use/objectInstance.js').ExistingCrudObject}} */ _objectsProxy,
         objects: _objectsProxy,
+        objectsVersion,
         loading: loadingError.loading,
         errored: loadingError.errored,
         error: loadingError.error,
-        // order: es.run(() => computed(() => Array.from(state.objectsMap.keys()))),
         order: es.run(() =>
             computed(() => {
                 return [...state.objectsMap.keys()];
@@ -402,7 +458,7 @@ export function useListInstance({ props, handlers = {} }) {
                 return promises.list;
             }
             if (state.loading) {
-                return CancellablePromise.reject(new ListInstanceError("already loading.", "already-loading"));
+                return Promise.reject(new ListInstanceError("already loading.", "already-loading"));
             }
             loadingError.clearError();
             loadingError.setLoading();
@@ -424,7 +480,7 @@ export function useListInstance({ props, handlers = {} }) {
             } catch (e) {
                 loadingError.setError(e);
                 loadingError.clearLoading();
-                return CancellablePromise.resolve(false);
+                return Promise.resolve(false);
             }
             promises.list = wrapMaybeCancellable(
                 listPromise
@@ -469,7 +525,9 @@ export function useListInstance({ props, handlers = {} }) {
                     pkKey: state.pkKey,
                 })
                 .then(() => {
-                    assignReactiveObject(state.objects, {});
+                    batchObjectChanges(() => {
+                        assignReactiveObject(state.objects, {});
+                    });
                     loadingError.clearError();
                     return Promise.resolve(true);
                 })
@@ -569,13 +627,15 @@ export function useListInstance({ props, handlers = {} }) {
         clearError: loadingError.clearError,
         getFakePk: () => getFakePk(state.objects, state.pkKey),
         pushObjects: (newObjects) => {
-            newObjects.forEach((newObject) => {
-                const pk = String(newObject[state.pkKey]);
-                if (pk in state.objects) {
-                    self.updateListObject.call(this, newObject);
-                } else {
-                    self.addListObject.call(this, newObject);
-                }
+            batchObjectChanges(() => {
+                newObjects.forEach((newObject) => {
+                    const pk = String(newObject[state.pkKey]);
+                    if (pk in state.objects) {
+                        self.updateListObject.call(this, newObject);
+                    } else {
+                        self.addListObject.call(this, newObject);
+                    }
+                });
             });
         },
     };

package/use/listRelated.js

@@ -19,8 +19,8 @@ import { computed, effectScope, nextTick, onScopeDispose, reactive, ref, toRef,
 // todo: pkKey is misnamed, it should be fkKey... this will be a major breaking change
 /**
  * @typedef {object} ListRelatedRule - The rule for defining relationships for objects in a list.
- * @property {string} pkKey - Specifies the foreign key used to link objects across lists. Planned to be renamed to
- *  'fkKey' to better reflect its usage.
+ * @property {string} [pkKey] - Specifies the foreign key used to link objects across lists. Defaults to the rule's
+ *  own key when omitted. Planned to be renamed to 'fkKey' to better reflect its usage.
  * @property {string[]} [order] - Specifies the order in which related objects should be sorted, if applicable.
  * @property {import('./listInstance.js').ObjectsByPk} objects - The objects that can be related based on the foreign key.
  */
@@ -35,20 +35,20 @@ import { computed, effectScope, nextTick, onScopeDispose, reactive, ref, toRef,
  * @typedef {object} ListRelatedRawState - Represents the internal state used by the list related composition function. It manages and computes the relationships between objects based on specified rules, providing real-time updates to related objects as the parent state changes.
  * @property {{
  *     [pk: import('../config/commonCrud.js').Pk]: {
- *         [rule: string]: import('vue').ComputedRef<any>,
+ *         [rule: string]: any,
  *     },
- * }} relatedObjects - Stores computed references to related objects, allowing for dynamic access based on object pk and specific rules.
+ * }} relatedObjects - The related objects, by object pk and then rule name. Each entry is backed by a computed, but it is read through a reactive proxy that unwraps it, so reads yield the related object (or array of related objects) and never carry a `.value`.
  * @property {ListRelatedRules} relatedObjectsRules - Defines the rules for establishing relationships, such as foreign key links and sorting orders.
  * @property {{
  *     [pk: import('../config/commonCrud.js').Pk]: {
  *         [rule: string]: import('vue').ComputedRef<[object, string]>,
  *     },
- * }} objAndKeyForPkAndRule - Maps each object pk and rule to a tuple consisting of the related object and its respective key, facilitating direct data manipulation.
+ * }} objAndKeyForPkAndRule - Maps each object pk and rule to a tuple consisting of the related object and its respective key, facilitating direct data manipulation. Reads through the reactive state unwrap the computed to the tuple itself, so `.value` is not used.
  * @property {{
  *     [pk: import('../config/commonCrud.js').Pk]: {
- *         [rule: string]: import('vue').ComputedRef<any>,
+ *         [rule: string]: any,
  *     },
- * }} fkForPkAndRule - Maintains computed references to the foreign keys for each object pk and rule, crucial for navigating complex data relationships.
+ * }} fkForPkAndRule - The foreign key for each object pk and rule, crucial for navigating complex data relationships. Each entry is backed by a computed that the reactive proxy unwraps on read.
  * @property {boolean} relatedObjectsParentStateObjectsWatchRunning - Flags whether the watch on parent state objects is currently active, ensuring updates trigger as needed.
  * @property {boolean} relatedObjectsWatchRunning - Indicates if watches on the related objects themselves are active, managing updates efficiently.
  * @property {boolean} relatedRunning - Signals whether any computations related to object relationships are currently in progress.
@@ -329,7 +329,7 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
 
     es.run(() => {
         watch(
-            () => Object.keys(parentState.objects),
+            () => parentState.objectsVersion,
             () => {
                 state.relatedObjectsParentStateObjectsWatchRunning = true;
             },
@@ -337,7 +337,7 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
         );
         watch(() => Object.keys(parentState.objects), parentStateObjectsWatch, { immediate: true });
         watch(
-            [() => Object.keys(state.relatedObjects), () => Object.keys(state.relatedObjectsRules || {})],
+            [() => parentState.objectsVersion, () => Object.keys(state.relatedObjectsRules || {})],
             () => {
                 state.relatedObjectsWatchRunning = true;
             },

package/use/listSearch.js

@@ -262,7 +262,7 @@ export function useListSearch({ parentState, props, throttle = 500, showAllWhenE
             addedKeys: addedObjectPks,
             removedKeys: removedObjectPks,
             sameKeys: sameObjectPks,
-        } = keyDiff(Object.keys(parentState.objects), Object.keys(state.objects));
+        } = keyDiff(Object.keys(parentState.objects), Object.keys(objectEffectScopes));
         const { addedKeys: addedTextSearchRules, removedKeys: removedTextSearchRules } = keyDiff(
             state.textSearchRules,
             previousTextSearchRules

package/use/listSort.js

@@ -1,8 +1,10 @@
 import { keyDiff } from "../utils/keyDiff.js";
+import { loadingCombine } from "../utils/loadingCombine.js";
+import { proxyRunning } from "../utils/proxyRunning.js";
 import get from "lodash-es/get.js";
 import identity from "lodash-es/identity.js";
 import throttle from "lodash-es/throttle.js";
-import { computed, effectScope, reactive, ref, toRef, toRefs, unref, watch } from "vue";
+import { computed, effectScope, onScopeDispose, reactive, ref, toRef, toRefs, unref, watch } from "vue";
 
 /**
  * Provides a Vue 3 composable for sorting lists based on dynamic and customizable rules. This module integrates
@@ -23,7 +25,7 @@ const defaultOptions = {
 
 /**
  * Sets default configuration options for all list sorting operations within the application. This function allows
- * global settings to be specified that affect the behavior of sorting operations unless overridden by specific
+ * global settings to be specified that affect the behaviour of sorting operations unless overridden by specific
  * instance configurations.
  *
  * @param {object} options - Configuration options to set as defaults for list sorting.
@@ -47,6 +49,7 @@ export function setListSortDefaultOptions({ sortThrottleWait }) {
  * @typedef {object} ListSortRawState - Represents the raw state used by the list sorting functionality. Includes all configurations and state necessary to manage sorting operations within a Vue application.
  * @property {OrderByRule[]} orderByRules - Current sorting rules applied to the list.
  * @property {boolean[]} orderByDesc - Flags indicating whether each sort criterion is in descending order.
+ * @property {import('vue').ComputedRef<boolean|undefined>} running - Whether the sort is settling a pending reorder, combined with the upstream running state so it propagates through the composed list state. True from when a new order is computed until the throttled reorder lands.
  */
 
 /**
@@ -161,6 +164,13 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
     })();
     const es = effectScope();
 
+    /** @type {import('vue').Ref<boolean|undefined>} */
+    const parentRunning = ref(undefined);
+    proxyRunning(parentState, "running", parentRunning);
+    // True from the moment a new order is pending until the (possibly throttled) reorder lands.
+    const sortWatchRunning = ref(true);
+    const running = computed(() => loadingCombine(sortWatchRunning.value, parentRunning.value));
+
     const internalState = reactive({
         orderByRules,
         orderByDesc: computed(() =>
@@ -206,29 +216,34 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
         return crit;
     }
 
+    function syncCriteria(newKeys) {
+        const { addedKeys, removedKeys } = keyDiff(newKeys, Object.keys(criteriaMap));
+        for (const pk of removedKeys) {
+            criteriaMap[pk].scope.stop();
+            delete criteriaMap[pk];
+        }
+        for (const pk of addedKeys) {
+            ensureCriteria(pk);
+        }
+    }
+
     es.run(() => {
         watch(
-            () => Object.keys(parentState.objects),
-            (newKeys) => {
-                const { addedKeys, removedKeys } = keyDiff(newKeys, Object.keys(criteriaMap));
-                for (const pk of removedKeys) {
-                    criteriaMap[pk].scope.stop();
-                    delete criteriaMap[pk];
-                }
-                for (const pk of addedKeys) {
-                    ensureCriteria(pk);
-                }
+            () => parentState.objectsVersion,
+            () => {
+                syncCriteria(Object.keys(parentState.objects));
             },
             { immediate: true, flush: "sync" }
         );
+        watch(() => Object.keys(parentState.objects), syncCriteria);
     });
 
     const rawOrder = computed(() => {
         const arr = [...unref(toRef(parentState, "order"))];
         const rulesArr = internalState.orderByRules?.filter(identity) || [];
         return arr.sort((a, b) => {
-            const aCrit = criteriaMap[a].crit ?? [];
-            const bCrit = criteriaMap[b].crit ?? [];
+            const aCrit = criteriaMap[a]?.crit ?? [];
+            const bCrit = criteriaMap[b]?.crit ?? [];
             for (let i = 0; i < rulesArr.length; i++) {
                 const rule = rulesArr[i];
                 let x = aCrit[i],
@@ -271,16 +286,45 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
     });
 
     const order = ref([]);
-    const assignOrder =
-        sortThrottleWaitNumber > 0
-            ? throttle((v) => {
-                  order.value = v;
-              }, sortThrottleWaitNumber)
-            : (v) => {
-                  order.value = v;
-              };
+    const writeOrder = (v) => {
+        order.value = v;
+        // the pending reorder has landed; let running settle unless the parent is still running
+        sortWatchRunning.value = false;
+    };
+    // Held separately from assignOrder so the throttle's own cancel stays typed.
+    const throttledOrder = sortThrottleWaitNumber > 0 ? throttle(writeOrder, sortThrottleWaitNumber) : null;
+    const assignOrder = throttledOrder ?? writeOrder;
 
-    watch(rawOrder, (v) => assignOrder(v), { immediate: true });
+    es.run(() => {
+        // Raise running synchronously the moment a new order is pending, so a throttled reorder keeps
+        //  running true until it lands. This mirrors the related, calculated, and search layers, and
+        //  lets the composed manager's state.running reflect the final reorder settling. Watch cheap
+        //  signals rather than rawOrder itself: a sync watcher re-evaluates its source on every
+        //  invalidation, and rawOrder performs the full sort, so watching it synchronously re-sorts
+        //  the list once per reactive write while a page is being pushed. The batched objectsVersion
+        //  covers structural changes and the rule reads cover rule changes; reorders triggered another
+        //  way (a row edit, a parent subset change) raise running in the pre-flush watcher below.
+        watch(
+            () => [parentState.objectsVersion, internalState.orderByRules, internalState.orderByDesc],
+            () => {
+                sortWatchRunning.value = true;
+            },
+            { flush: "sync" }
+        );
+        watch(
+            rawOrder,
+            (v) => {
+                sortWatchRunning.value = true;
+                assignOrder(v);
+            },
+            { immediate: true }
+        );
+        // A throttled trailing reorder is a timer, not a reactive effect, so disposal would otherwise
+        //  leave it pending and let it write order after the layer stopped.
+        if (throttledOrder) {
+            onScopeDispose(() => throttledOrder.cancel());
+        }
+    });
 
     // 6) objectsInOrder just follows that
     const objectsInOrder = computed(() => order.value.map((pk) => parentState.objects[pk]));
@@ -293,6 +337,7 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
             objects,
             order,
             objectsInOrder,
+            running,
         }),
         parentState,
         stop: () => {

package/use/listSubscription.js

@@ -54,7 +54,9 @@ export class ListSubscriptionError extends Error {
  */
 
 /**
- * @typedef {Pick<import('./loadingError.js').LoadingErrorStatus, "clearError">} ListSubscriptionFunctions - The methods available on a list subscription.
+ * @typedef {Pick<import('./loadingError.js').LoadingErrorStatus, "clearError"> & {
+ *     stop: () => void
+ * }} ListSubscriptionFunctions - The methods available on a list subscription.
  */
 
 /**
@@ -337,5 +339,12 @@ export function useListSubscription({ listInstance, props, handlers }) {
         listIntent,
         subscribeIntent,
         clearError: proxyLoadingError.clearError,
+        // Stops both intents, mirroring useObjectSubscription, so a caller that owns this
+        // subscription's lifetime does not have to know its intent inventory. The wrapped
+        // instance keeps its state and still takes manual calls.
+        stop: () => {
+            listIntent.stop();
+            subscribeIntent.stop();
+        },
     };
 }

package/use/object.js

@@ -116,7 +116,7 @@ function mergeFns(source) {
  * ```
  * <script setup>
  * import { useObject } from "@arrai-innovations/reactive-helpers";
- * import { reactive, ref, toRef } from "vue";
+ * import { computed, reactive, toRef } from "vue";
  *
  * const someObjectsSource = reactive({
  *     objects: {
@@ -159,25 +159,24 @@ function mergeFns(source) {
  *             order: ['3','1','2'],
  *         },
  *         secondOrder: {
- *             pkKey: 'relatedObject.secondOrderId',
+ *             pkKey: 'relatedItem.firstOrder.secondOrderId',
  *             objects: someOtherObjectsSource.objects,
  *         },
  *     },
  *     calculatedObjectRules: {
- *         someRule: (object, relatedObject, calculatedObjects) => {
- *             // some complex calculation, relatedObjects would be assuming there was a listRelated between the two
- *             // calculatedObjects would be the other calculated objects in the list
- *             // including yourself, so try not to create circular dependencies
+ *         someRule: (object, relatedObject) => {
+ *             // some complex calculation. relatedObject holds the objects matched by relatedObjectRules above,
+ *             // keyed by rule name.
  *             // this is used as a computed body.
  *             return object.foo + object.name;
  *         },
- *         ...
+ *         // ...further rules
  *     },
  *     intendToRetrieve: false,
  *     intendToSubscribe: false,
  * });
  * objectProps.intendToRetrieve = objectProps.intendToSubscribe = computed(()=> !!props.pk);
- * const objectManager = useObject(objectProps);
+ * const objectManager = useObject({ props: objectProps });
  * // objectManager.state.object comes back from the server (via configured crud retrieve function)
  * // { id: 2, name: 'two', foo: 'bar', some_objects_id: 2, some_objects_list_ids: ['1','2','3'] }
  * </script>