@arrai-innovations/reactive-helpers 10.2.0 → 10.4.0

package/.circleci/config.yml

@@ -1,7 +1,7 @@
 version: 2.1
 orbs:
     eslint: arrai/eslint@7.4.0
-    prettier: arrai/prettier@5.1.1
+    prettier: arrai/prettier@5.4.0
     npm: arrai/npm@2.4.1
     github: arrai/github@1.1.0
 workflows:
@@ -75,14 +75,12 @@ workflows:
             - prettier/code_style:
                   name: prettier
                   context: arrai-global
-                  version: 2.6.2
                   filters:
                       branches:
                           only:
                               - main
             - prettier/code_style:
                   name: prettier-no-badge
-                  version: 2.6.2
                   create_badges: false
                   filters:
                       branches:

package/docs.md

@@ -494,11 +494,11 @@ It tracks the objects in the list, and their added order.
 causing the list to be re-fetched as needed and listening for updates to the list.
 
 **Kind**: global function  
-**Returns**: ListSubscription
+**Returns**: [`ListSubscription`] - - the list subscription
 
-| Param   | Type                        |
-| ------- | --------------------------- |
-| options | [`ListSubscriptionOptions`] |
+| Param   | Type                        | Description                                         |
+| ------- | --------------------------- | --------------------------------------------------- |
+| options | [`ListSubscriptionOptions`] | the configuration options for the list subscription |
 
 ## useObjectInstances(instanceArgs)
 
@@ -832,6 +832,7 @@ A CSS object or a space-separated list of CSS classes.
 [`cssclasseswithrefs`]: #cssclasseswithrefs
 [`listinstance`]: #listinstance
 [`listinstanceoptions`]: #listinstanceoptions
+[`listsubscription`]: #listsubscription
 [`listsubscriptionoptions`]: #listsubscriptionoptions
 [`objectinstanceinstance`]: #objectinstanceinstance
 [`listinstancestate`]: #listinstancestate

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arrai-innovations/reactive-helpers",
-    "version": "10.2.0",
+    "version": "10.4.0",
     "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
     "main": "index.js",
     "type": "module",

package/tests/unit/use/listCalculated.spec.js

@@ -2,12 +2,16 @@ import { nextTick } from "vue";
 import { deepUnref } from "vue-deepunref";
 
 describe("use/listCalculated", () => {
-    let useListInstance, useListCalculated;
+    let useListInstance, useListCalculated, useListRelated, AwaitNot;
     beforeEach(async () => {
         const listInstanceModule = await import("../../../use/listInstance");
         useListInstance = listInstanceModule.useListInstance;
         const listCalculatedModule = await import("../../../use/listCalculated");
         useListCalculated = listCalculatedModule.useListCalculated;
+        const listRelatedModule = await import("../../../use/listRelated");
+        useListRelated = listRelatedModule.useListRelated;
+        const watchesModule = await import("../../../utils/watches.js");
+        AwaitNot = watchesModule.AwaitNot;
     });
     it("should return a list of calculated items", async () => {
         const mainListInstance = useListInstance({ props: {} });
@@ -71,4 +75,60 @@ describe("use/listCalculated", () => {
             },
         });
     });
+    it("should allow calculated objects to return results based on related objects", async () => {
+        const mainListInstance = useListInstance({ props: {} });
+        const relatedListInstance = useListInstance({ props: {} });
+        mainListInstance.addListObject({
+            id: "1",
+            name: "main",
+            related_items: ["2", "3"],
+            related_id: "4",
+            calculated_items: ["2", "3"],
+            calculated_id: "4",
+        });
+        relatedListInstance.addListObject({
+            id: "2",
+            name: "related1",
+        });
+        relatedListInstance.addListObject({
+            id: "3",
+            name: "related2",
+        });
+        relatedListInstance.addListObject({
+            id: "4",
+            name: "related3",
+        });
+        const listRelated = useListRelated({
+            parentState: mainListInstance.state,
+            relatedObjectsRules: {
+                relatedItems: {
+                    objects: relatedListInstance.state.objects,
+                    pkKey: "related_items",
+                },
+                relatedItem: {
+                    objects: relatedListInstance.state.objects,
+                    pkKey: "related_id",
+                },
+            },
+        });
+        const listCalculated = useListCalculated({
+            parentState: listRelated.state,
+            calculatedObjectsRules: {
+                calculatedItems: (obj, relatedObj) => relatedObj.relatedItems?.map((x) => x.name + "-modified"),
+                calculatedItem: (obj, relatedObj) => relatedObj.relatedItem?.name + "-modified",
+            },
+        });
+        const anr = new AwaitNot({
+            obj: listCalculated.state,
+            prop: "running",
+        });
+        anr.start();
+        await anr.promise;
+        expect(deepUnref(listCalculated.state.calculatedObjects)).toEqual({
+            1: {
+                calculatedItems: ["related1-modified", "related2-modified"],
+                calculatedItem: "related3-modified",
+            },
+        });
+    });
 });

package/tests/unit/use/listRelated.spec.js

@@ -1,14 +1,15 @@
-// import { useListInstance, useListRelated } from "../../../use/listRelated.js";
 import { nextTick } from "vue";
 import { deepUnref } from "vue-deepunref";
 
 describe("use/listRelated", () => {
-    let useListInstance, useListRelated;
+    let useListInstance, useListRelated, AwaitNot;
     beforeEach(async () => {
         const listInstanceModule = await import("../../../use/listInstance");
         useListInstance = listInstanceModule.useListInstance;
         const listRelatedModule = await import("../../../use/listRelated");
         useListRelated = listRelatedModule.useListRelated;
+        const watchesModule = await import("../../../utils/watches.js");
+        AwaitNot = watchesModule.AwaitNot;
     });
     it("should return a list of related items", async () => {
         const mainListInstance = useListInstance({ props: {} });
@@ -78,4 +79,117 @@ describe("use/listRelated", () => {
             },
         });
     });
+    it('should allow related objects pkKey to be prefixed with "relatedItem." to reference previously related objects', async () => {
+        //
+        const mainListInstance = useListInstance({ props: {} });
+        const intermediateListInstance = useListInstance({ props: {} });
+        const relatedListInstance = useListInstance({ props: {} });
+        mainListInstance.addListObject({
+            id: "1",
+            name: "main",
+            intermediate_ids: ["2", "3"],
+            intermediate_id: "2",
+        });
+        intermediateListInstance.addListObject({
+            id: "2",
+            name: "intermediate1",
+            related_ids: ["4", "5"],
+            related_id: "4",
+        });
+        intermediateListInstance.addListObject({
+            id: "3",
+            name: "intermediate2",
+            related_ids: ["6", "7"],
+            related_id: "6",
+        });
+        relatedListInstance.addListObject({
+            id: "4",
+            name: "related1",
+        });
+        relatedListInstance.addListObject({
+            id: "5",
+            name: "related2",
+        });
+        relatedListInstance.addListObject({
+            id: "6",
+            name: "related3",
+        });
+        relatedListInstance.addListObject({
+            id: "7",
+            name: "related4",
+        });
+        const listRelated = useListRelated({
+            parentState: mainListInstance.state,
+            relatedObjectsRules: {
+                intermediateItems: {
+                    objects: intermediateListInstance.state.objects,
+                    pkKey: "intermediate_ids",
+                },
+                intermediateItem: {
+                    objects: intermediateListInstance.state.objects,
+                    pkKey: "intermediate_id",
+                },
+                relatedItems: {
+                    objects: relatedListInstance.state.objects,
+                    pkKey: "relatedItem.intermediateItems.related_ids",
+                },
+                relatedItem: {
+                    objects: relatedListInstance.state.objects,
+                    pkKey: "relatedItem.intermediateItem.related_id",
+                },
+            },
+        });
+        const anr = new AwaitNot({
+            obj: listRelated.state,
+            prop: "running",
+        });
+        anr.start();
+        await anr.promise;
+        expect(deepUnref(listRelated.state.relatedObjects)).toEqual({
+            1: {
+                intermediateItems: [
+                    {
+                        id: "2",
+                        name: "intermediate1",
+                        related_ids: ["4", "5"],
+                        related_id: "4",
+                    },
+                    {
+                        id: "3",
+                        name: "intermediate2",
+                        related_ids: ["6", "7"],
+                        related_id: "6",
+                    },
+                ],
+                intermediateItem: {
+                    id: "2",
+                    name: "intermediate1",
+                    related_ids: ["4", "5"],
+                    related_id: "4",
+                },
+                relatedItems: [
+                    {
+                        id: "4",
+                        name: "related1",
+                    },
+                    {
+                        id: "5",
+                        name: "related2",
+                    },
+                    {
+                        id: "6",
+                        name: "related3",
+                    },
+                    {
+                        id: "7",
+                        name: "related4",
+                    },
+                ],
+                relatedItem: {
+                    id: "4",
+                    name: "related1",
+                },
+            },
+        });
+    });
 });

package/tests/unit/use/listSort.spec.js

@@ -1,5 +1,5 @@
 import { doAwaitTimeout } from "../../../utils/index.js";
-import { nextTick } from "vue";
+import { reactive } from "vue";
 import { deepUnref } from "vue-deepunref";
 
 describe("use/useListSort", () => {
@@ -8,9 +8,12 @@ describe("use/useListSort", () => {
         sortThrottleWait,
         useListInstance,
         useListInstances,
+        useListRelated,
+        useListCalculated,
         useListSort,
         useListSorts,
-        setListSortDefaultOptions;
+        setListSortDefaultOptions,
+        AwaitNot;
     const contactsResolved = [
         {
             id: 15,
@@ -41,6 +44,8 @@ describe("use/useListSort", () => {
         const imported = await import("../../../use");
         useListInstance = imported.useListInstance;
         useListInstances = imported.useListInstances;
+        useListRelated = imported.useListRelated;
+        useListCalculated = imported.useListCalculated;
         orderByRules = [
             { key: "organization", desc: true, localeCompare: false },
             { key: "lexical_name", desc: false, localeCompare: true },
@@ -58,10 +63,22 @@ describe("use/useListSort", () => {
         setListSortDefaultOptions({
             sortThrottleWait: 0,
         });
+        const importedUtils = await import("../../../utils");
+        AwaitNot = importedUtils.AwaitNot;
     });
 
     afterEach(() => vi.resetAllMocks());
 
+    const waitForListSort = async (listSort) => {
+        const anr = new AwaitNot({
+            obj: listSort.state,
+            prop: "running",
+            timeout: 2000,
+        });
+        anr.start();
+        await anr.promise;
+    };
+
     it("generates initial values from inputs", () => {
         const listSort = useListSort({ parentState: listInstance.state, orderByRules, sortThrottleWait });
         expect(listSort.state.orderByRules).toEqual(orderByRules);
@@ -89,13 +106,14 @@ describe("use/useListSort", () => {
                 listInstance.addListObject(contact);
             }
             const listSort = useListSort({ parentState: listInstance.state, orderByRules });
-            await nextTick();
+            // sorts immediately
             expect(listSort.state.order).toEqual(testOrder1);
+            await waitForListSort(listSort);
             listInstance.addListObject(addObject);
-            await nextTick();
+            await waitForListSort(listSort);
             expect(listSort.state.order).toEqual(testOrder2);
             listInstance.deleteListObject(12);
-            await nextTick();
+            await waitForListSort(listSort);
             expect(listSort.state.order).toEqual(testOrder3);
         });
     });
@@ -115,17 +133,17 @@ describe("use/useListSort", () => {
             listSort.state.orderByRules.pop();
             listSort.state.orderByRules.push({ key: "lexical_name", desc: false, localeCompare: true });
             expect(listSort.state.order).toEqual(testOrder1);
-            await nextTick();
+            await waitForListSort(listSort);
             expect(listSort.state.order).toEqual(testOrder2);
             listSort.state.orderByRules.pop();
             listSort.state.orderByRules.push({ key: "organization", desc: true, localeCompare: true });
-            await nextTick();
+            await waitForListSort(listSort);
             expect(listSort.state.order).toEqual(testOrder3);
             listSort.state.orderByRules.pop();
-            await nextTick();
+            await waitForListSort(listSort);
             expect(listSort.state.order).toEqual(testOrder4);
             listSort.state.orderByRules.push({ key: "organization", desc: false, localeCompare: false });
-            await nextTick();
+            await waitForListSort(listSort);
             expect(listSort.state.order).toEqual(testOrder2);
         });
     });
@@ -194,6 +212,72 @@ describe("use/useListSort", () => {
         expect(deepUnref(listSorts.A.state)).toEqual(deepUnref(listSortA.state));
         expect(deepUnref(listSorts.B.state)).toEqual(deepUnref(listSortB.state));
     });
+    it("orderByRules can refer to relatedItem or calculatedItem", async () => {
+        const listInstance = useListInstance({
+            props: reactive({
+                crudArgs: { stream: "test_stream" },
+                listArgs: { user: 1 },
+                retrieveArgs: {
+                    fields: ["id", "__str__", "name", "relatedItem", "calculatedItem"],
+                },
+            }),
+        });
+        const relatedListInstance = useListInstance({
+            props: reactive({
+                crudArgs: { stream: "test_related_stream" },
+                listArgs: { user: 1 },
+                retrieveArgs: {
+                    fields: ["id", "__str__", "name"],
+                },
+            }),
+        });
+        const listRelated = useListRelated({
+            parentState: listInstance.state,
+            relatedObjectsRules: reactive({
+                relatedItemName: {
+                    objects: relatedListInstance.state.objects,
+                    pkKey: "relatedItem",
+                },
+            }),
+        });
+        const listCalculated = useListCalculated({
+            parentState: listRelated.state,
+            calculatedObjectsRules: reactive({
+                calculatedItemName: (obj, relatedObj) => {
+                    return obj.sameValue + ":" + relatedObj.relatedItemName?.oppositeOrder;
+                },
+            }),
+        });
+        const orderByRules = reactive([
+            { key: "calculatedItem.calculatedItemName", desc: false, localeCompare: false },
+        ]);
+        const listSort = useListSort({
+            parentState: listCalculated.state,
+            orderByRules,
+        });
+        for (let i = 1; i <= 4; i++) {
+            listInstance.addListObject({
+                id: i,
+                name: `item${i}`,
+                relatedItem: i,
+                sameValue: "sameValue",
+            });
+            relatedListInstance.addListObject({
+                id: i,
+                name: `relatedItem${i}`,
+                oppositeOrder: 5 - i,
+            });
+        }
+        await waitForListSort(listSort);
+        expect(listSort.state.order).toEqual(["4", "3", "2", "1"]);
+        orderByRules[0].key = "relatedItemName.name";
+        await waitForListSort(listSort);
+        expect(listSort.state.order).toEqual(["1", "2", "3", "4"]);
+        orderByRules[0].key = "relatedItemName.sameValue";
+        orderByRules[1] = { key: "calculatedItem.calculatedItemName", desc: false, localeCompare: false };
+        await waitForListSort(listSort);
+        expect(listSort.state.order).toEqual(["4", "3", "2", "1"]);
+    });
     describe("useListSort/sortThrottleWait", () => {
         it("respects throttle time prior to triggering", async () => {
             setListSortDefaultOptions({
@@ -212,20 +296,31 @@ describe("use/useListSort", () => {
             }
 
             const testOrder1 = [];
-            const testOrder2 = ["35", "12", "15", "9"];
-            const testOrder3 = ["35", "15", "9"];
+            const testOrder2 = ["12", "15", "9"];
+            const testOrder3 = ["35", "12", "15", "9"];
+            const testOrder4 = ["35", "15", "9"];
 
             const listSort = useListSort({ parentState: listInstance.state, orderByRules, sortThrottleWait });
-            await nextTick();
             expect(listSort.state.order).toEqual(testOrder1);
+
+            // wait for the original throttle to finish
+            await doAwaitTimeout(250);
+
+            expect(listSort.state.order).toEqual(testOrder2);
             listInstance.addListObject(addObject);
-            await nextTick();
             expect(listSort.state.order).toEqual(testOrder2);
+            // trigger the leading edge of the throttle
+            await doAwaitTimeout(10);
+            expect(listSort.state.order).toEqual(testOrder3);
+            // trigger again before the 200ms throttle
             listInstance.deleteListObject(12);
-            await nextTick();
-            expect(listSort.state.order).toEqual(testOrder2);
-            await doAwaitTimeout(200);
             expect(listSort.state.order).toEqual(testOrder3);
+            // this should trigger before the 200ms throttle
+            await doAwaitTimeout(100);
+            expect(listSort.state.order).toEqual(testOrder3);
+            // this should trigger after the 200ms throttle
+            await doAwaitTimeout(200);
+            expect(listSort.state.order).toEqual(testOrder4);
         });
     });
 });

package/use/listRelated.js

@@ -58,6 +58,7 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
         for (const objectKey of Object.keys(state.relatedObjects)) {
             const relatedObjectsObject = state.relatedObjects[objectKey];
             const originalObjectRef = toRef(parentState.objects, objectKey);
+            const relatedObjectRef = toRef(state.relatedObjects, objectKey);
             let removedRuleKeys, addedRuleKeys;
             if (!relatedObjectsRulesIsEmpty) {
                 ({ removedKeys: removedRuleKeys, addedKeys: addedRuleKeys } = keyDiff(
@@ -86,12 +87,30 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
                         const rulePkKey = state.relatedObjectsRules?.[addedRuleKey]?.pkKey || addedRuleKey;
                         const ruleOrder = unref(state.relatedObjectsRules?.[addedRuleKey]?.order);
                         if (!ruleObjects || !rulePkKey) {
-                            relatedObjectsObject[addedRuleKey] = undefined;
+                            if (!isUndefined(relatedObjectsObject[addedRuleKey])) {
+                                relatedObjectsObject[addedRuleKey] = undefined;
+                            }
                             return;
                         }
-                        let value = get(unref(originalObjectRef), rulePkKey);
+                        let value;
+                        if (rulePkKey.startsWith("relatedItem.")) {
+                            value = get(unref(relatedObjectRef), rulePkKey.slice(12));
+                            if (isUndefined(value)) {
+                                // is the first level an array?
+                                const firstLevelKey = rulePkKey.slice(12).split(".")[0];
+                                const firstLevelItem = get(unref(relatedObjectRef), firstLevelKey);
+                                if (isArray(firstLevelItem)) {
+                                    const restOfKey = rulePkKey.slice(12 + firstLevelKey.length + 1);
+                                    value = firstLevelItem.map((e) => get(e, restOfKey)).flat();
+                                }
+                            }
+                        } else {
+                            value = get(unref(originalObjectRef), rulePkKey);
+                        }
                         if (isUndefined(value)) {
-                            relatedObjectsObject[addedRuleKey] = undefined;
+                            if (!isUndefined(relatedObjectsObject[addedRuleKey])) {
+                                relatedObjectsObject[addedRuleKey] = undefined;
+                            }
                             return;
                         }
                         if (isArray(value)) {
@@ -114,7 +133,7 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
                         }
                     };
                     watch(
-                        [toRef(state.relatedObjectsRules, addedRuleKey), originalObjectRef],
+                        [toRef(state.relatedObjectsRules, addedRuleKey), originalObjectRef, relatedObjectRef],
                         relatedObjectsObjectWatchFn,
                         {
                             deep: true,

package/use/listSort.js

@@ -1,18 +1,20 @@
-import { assignReactiveObject, keyDiff } from "../utils/index.js";
+import { assignReactiveObject, keyDiff, loadingCombine } from "../utils/index.js";
 import { listCalculatedStateKeys } from "./listCalculated.js";
 import { listFilterStateKeys } from "./listFilter.js";
 import { listInstanceStateKeys } from "./listInstance.js";
 import { listRelatedStateKeys } from "./listRelated.js";
 import { listSubscriptionStateKeys } from "./listSubscription.js";
+import { useWatchesRunning } from "./watchesRunning.js";
 import cloneDeep from "lodash-es/cloneDeep.js";
 import get from "lodash-es/get.js";
 import identity from "lodash-es/identity.js";
 import isEmpty from "lodash-es/isEmpty.js";
+import isEqual from "lodash-es/isEqual.js";
 import isNull from "lodash-es/isNull.js";
 import isUndefined from "lodash-es/isUndefined.js";
 import throttle from "lodash-es/throttle.js";
 import zip from "lodash-es/zip.js";
-import { effectScope, reactive, toRef, unref, watch } from "vue";
+import { effectScope, reactive, toRef, unref, watch, computed } from "vue";
 
 export const listSortStateKeys = [
     "orderByRules",
@@ -21,6 +23,10 @@ export const listSortStateKeys = [
     "sortCriteria",
     "sortCriteriaEffectScopes",
     "orderByDesc",
+    "sortCriteriaWatchRunning",
+    "sortWatchRunning",
+    "outstandingEffects",
+    // "running",
 ];
 
 export const listSortFunctions = [];
@@ -56,6 +62,9 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
         sortCriteria: {},
         sortCriteriaEffectScopes: {},
         orderByDesc: [],
+        sortCriteriaWatchRunning: false,
+        sortWatchRunning: false,
+        outstandingEffects: false,
     });
     const es = effectScope();
 
@@ -68,7 +77,7 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
         delete state.sortCriteria[removedKey];
     }
 
-    function addSortCriteria(object, key) {
+    function addSortCriteria(object, relatedObject, calculatedObject, key) {
         const oldScope = state.sortCriteriaEffectScopes[key];
         if (oldScope) {
             oldScope.stop();
@@ -79,20 +88,34 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
                 state.sortCriteria[key] = [];
             }
             watch(
-                [object, toRef(state, "orderByRules")],
+                [object, relatedObject, calculatedObject, toRef(state, "orderByRules")],
                 () => {
                     const obj = unref(object);
+                    const relatedObj = unref(relatedObject);
+                    const calculatedObj = unref(calculatedObject);
                     const newSearchCriteria = [];
                     for (const orderByObj of state.orderByRules.filter(identity)) {
                         let newItem;
                         if (orderByObj.keyFn) {
                             newItem = orderByObj.keyFn(obj, state);
                         } else {
-                            newItem = get(obj, orderByObj.key);
+                            if (orderByObj.key.startsWith("relatedItem.")) {
+                                newItem = get(relatedObj, orderByObj.key.slice(12));
+                            } else if (orderByObj.key.startsWith("calculatedItem.")) {
+                                newItem = get(calculatedObj, orderByObj.key.slice(15));
+                            } else {
+                                newItem = get(obj, orderByObj.key);
+                            }
                         }
                         newSearchCriteria.push(newItem);
                     }
+                    if (isEqual(newSearchCriteria, state.sortCriteria[key])) {
+                        return;
+                    }
                     assignReactiveObject(state.sortCriteria[key], newSearchCriteria);
+                    if (!state.outstandingEffects) {
+                        state.outstandingEffects = true;
+                    }
                 },
                 {
                     deep: true,
@@ -104,82 +127,98 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
     }
 
     function sortCriteriaWatch() {
-        if (!state.orderByRules || !state.orderByRules.filter(identity).length) {
-            if (!isEmpty(state.sortCriteria)) {
-                for (const removedKey of Object.keys(state.sortCriteria)) {
-                    removeSortCriteria(removedKey);
+        try {
+            if (!state.orderByRules || !state.orderByRules.filter(identity).length) {
+                if (!isEmpty(state.sortCriteria)) {
+                    for (const removedKey of Object.keys(state.sortCriteria)) {
+                        removeSortCriteria(removedKey);
+                    }
                 }
+                assignReactiveObject(state.order, cloneDeep(parentState.order));
+                assignReactiveObject(state.objectsInOrder, cloneDeep(parentState.objectsInOrder));
+                return;
             }
-            assignReactiveObject(state.order, cloneDeep(parentState.order));
-            assignReactiveObject(state.objectsInOrder, cloneDeep(parentState.objectsInOrder));
-            return;
-        }
-        const { removedKeys, addedKeys } = keyDiff(Object.keys(parentState.objects), Object.keys(state.sortCriteria));
-        for (const removedKey of removedKeys) {
-            removeSortCriteria(removedKey);
-        }
-
-        es.run(() => {
-            for (const addedKey of addedKeys) {
-                const object = toRef(() => parentState.objects[addedKey]);
-                addSortCriteria(object, addedKey);
+            const { removedKeys, addedKeys } = keyDiff(
+                Object.keys(parentState.objects),
+                Object.keys(state.sortCriteria)
+            );
+            for (const removedKey of removedKeys) {
+                removeSortCriteria(removedKey);
             }
-        });
-        assignReactiveObject(
-            state.orderByDesc,
-            state.orderByRules.filter(identity).map((e) => e.desc || false)
-        );
+
+            es.run(() => {
+                for (const addedKey of addedKeys) {
+                    const object = toRef(() => parentState.objects[addedKey]);
+                    const relatedObj = toRef(() => parentState.relatedObjects?.[addedKey]);
+                    const calculatedObj = toRef(() => parentState.calculatedObjects?.[addedKey]);
+                    addSortCriteria(object, relatedObj, calculatedObj, addedKey);
+                }
+            });
+            assignReactiveObject(
+                state.orderByDesc,
+                state.orderByRules.filter(identity).map((e) => e.desc || false)
+            );
+        } finally {
+            state.sortCriteriaWatchRunning = false;
+        }
     }
 
     function sortWatch() {
-        if (!state.orderByRules || !state.orderByRules.length) {
-            assignReactiveObject(state.order, cloneDeep(parentState.order));
-            assignReactiveObject(state.objectsInOrder, cloneDeep(parentState.objectsInOrder));
-            return;
-        }
+        try {
+            if (!state.orderByRules || !state.orderByRules.length) {
+                assignReactiveObject(state.order, cloneDeep(parentState.order));
+                assignReactiveObject(state.objectsInOrder, cloneDeep(parentState.objectsInOrder));
+                return;
+            }
 
-        let idList = Object.keys(parentState.objects);
-        idList.sort((xKey, yKey) => {
-            const xCriteria = state.sortCriteria[xKey];
-            const yCriteria = state.sortCriteria[yKey];
-            for (let [x, y, orderByObj] of zip(xCriteria, yCriteria, state.orderByRules)) {
-                if (!orderByObj) {
-                    continue;
-                }
-                if (orderByObj.desc) {
-                    [x, y] = [y, x];
-                }
-                const isUndefinedX = isUndefined(x) || isNull(x);
-                const isUndefinedY = isUndefined(y) || isNull(y);
-                if (isUndefinedX && isUndefinedY) {
-                    continue;
-                } else if (isUndefinedX) {
-                    return -1;
-                } else if (isUndefinedY) {
-                    return 1;
-                }
-                if (orderByObj.localeCompare) {
-                    const strComp = collator.compare(x, y);
-                    if (strComp) {
-                        return strComp;
+            let idList = Object.keys(parentState.objects);
+            idList.sort((xKey, yKey) => {
+                const xCriteria = state.sortCriteria[xKey];
+                const yCriteria = state.sortCriteria[yKey];
+                for (let [x, y, orderByObj] of zip(xCriteria, yCriteria, state.orderByRules)) {
+                    if (!orderByObj) {
+                        continue;
                     }
-                } else {
-                    if (x < y) {
-                        return -1;
+                    if (orderByObj.desc) {
+                        [x, y] = [y, x];
                     }
-                    if (x > y) {
+                    const isUndefinedX = isUndefined(x) || isNull(x);
+                    const isUndefinedY = isUndefined(y) || isNull(y);
+                    if (isUndefinedX && isUndefinedY) {
+                        continue;
+                    } else if (isUndefinedX) {
+                        return -1;
+                    } else if (isUndefinedY) {
                         return 1;
                     }
+                    if (orderByObj.localeCompare) {
+                        const strComp = collator.compare(x, y);
+                        if (strComp) {
+                            return strComp;
+                        }
+                    } else {
+                        if (x < y) {
+                            return -1;
+                        }
+                        if (x > y) {
+                            return 1;
+                        }
+                    }
                 }
-            }
-            return 0;
-        });
-        assignReactiveObject(state.order, idList);
-        assignReactiveObject(state.objectsInOrder, idList.map((e) => parentState.objects[e]).filter(identity));
+                return 0;
+            });
+            assignReactiveObject(state.order, idList);
+            assignReactiveObject(state.objectsInOrder, idList.map((e) => parentState.objects[e]).filter(identity));
+        } finally {
+            state.sortWatchRunning = false;
+            state.outstandingEffects = false;
+        }
     }
 
     const throttledSortWatch = throttle(sortWatch, sortThrottleWait);
 
+    let watchesRunning = null;
+
     es.run(() => {
         for (const key of listInstanceStateKeys) {
             if (["order", "objectsInOrder"].includes(key)) {
@@ -209,11 +248,23 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
             deep: true,
             immediate: true,
         });
+        watchesRunning = useWatchesRunning({
+            triggerRefs: [
+                computed(() => (state.orderByRules && !isEmpty(state.orderByRules) ? parentState.loading : false)),
+            ],
+            watchSentinelRefs: [toRef(state, "sortCriteriaWatchRunning"), toRef(state, "sortWatchRunning")],
+        });
+
+        state.sortRunning = computed(() => loadingCombine(watchesRunning.state.running, state.outstandingEffects));
+        state.running = computed(() =>
+            loadingCombine(watchesRunning.state.running, state.outstandingEffects, parentState.running)
+        );
     });
 
     return {
         state,
         parentState,
         effectScope: es,
+        watchesRunning,
     };
 }

package/use/listSubscription.js

@@ -77,8 +77,8 @@ export function useListSubscriptions(args, listInstances = {}) {
 /**
  * `useListSubscription` creates a reactive object that manages a list of objects, as returned by `useListInstance`,
  *  causing the list to be re-fetched as needed and listening for updates to the list.
- * @param {ListSubscriptionOptions} options
- * @returns ListSubscription
+ * @param {ListSubscriptionOptions} options - the configuration options for the list subscription
+ * @returns {ListSubscription} - the list subscription
  */
 export function useListSubscription({ listInstance, props, functions, keepOldPages = false }) {
     if (!listInstance && !props) {

package/utils/watches.js

@@ -100,7 +100,7 @@ export class AwaitNot {
         this.falseISW = new ImmediateStopWatch();
         // prebuild the exception for a more useful stack.
         if (this.timeout) {
-            this.timeoutError = new AwaitTimeoutError("Timeout", "timeout");
+            this.timeoutError = new AwaitNotError("Timeout", "timeout");
         }
     }