@arrai-innovations/reactive-helpers 10.0.0 → 10.0.2

package/docs.md

@@ -221,7 +221,7 @@ Logs debug messages based on the specified categories and logging rules.
 
 Get all paths from an array or object.
 
-### utils/flattenPaths~flattenPaths(arrayOrObject, currentPath)
+### utils/flattenPaths~flattenPaths(arrayOrObject, options)
 
 Turn an array or object into an array of path strings. Recurses for any found arrays or objects.
 
@@ -230,10 +230,13 @@ Array indexes are wrapped in square brackets and object keys are prefixed with a
 **Kind**: inner method of [`utils/flattenPaths`]  
 **Returns**: `Array.<string>` - paths
 
-| Param         | Type                | Description                                        |
-| ------------- | ------------------- | -------------------------------------------------- |
-| arrayOrObject | `Array` \| `object` | array or object to flatten                         |
-| currentPath   | `string`            | current path, for recursion or as a starting point |
+| Param               | Type                | Description                                        |
+| ------------------- | ------------------- | -------------------------------------------------- |
+| arrayOrObject       | `Array` \| `object` | array or object to flatten                         |
+| options             | `object`            | options                                            |
+| options.currentPath | `string`            | current path, for recursion or as a starting point |
+| options.depth       | `number`            | current depth, for recursion                       |
+| options.limit       | `number`            | limit the depth of recursion                       |
 
 ## utils/keyDiff
 
@@ -268,11 +271,15 @@ what keys are removed, and what keys are added. Keys are sourced deeply in the o
 **Kind**: inner method of [`utils/keyDiff`]  
 **Returns**: `KeyDiffResult` - - the differences
 
-| Param       | Type             | Description                    |
-| ----------- | ---------------- | ------------------------------ |
-| newObj      | `object`         | the new version of the object  |
-| oldObj      | `object`         | the old version of the object  |
-| \[options\] | `KeyDiffOptions` | which differences are returned |
+| Param                   | Type             | Description                            |
+| ----------------------- | ---------------- | -------------------------------------- |
+| newObj                  | `object`         | the new version of the object          |
+| oldObj                  | `object`         | the old version of the object          |
+| \[options\]             | `KeyDiffOptions` | which differences are returned         |
+| \[options.sameKeys\]    | `boolean`        | if true, return keys that are the same |
+| \[options.removedKeys\] | `boolean`        | if true, return keys that are removed  |
+| \[options.addedKeys\]   | `boolean`        | if true, return keys that are added    |
+| \[options.limit\]       | `number`         | limit the depth of recursion           |
 
 ### utils/keyDiff~KeyDiffOptions
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arrai-innovations/reactive-helpers",
-    "version": "10.0.0",
+    "version": "10.0.2",
     "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
     "main": "index.js",
     "type": "module",
@@ -45,7 +45,7 @@
         "jsdoc-to-markdown": "^8.0.0",
         "lint-staged": "^13.2.2",
         "prettier": "2.6.2",
-        "vitest": "^0.32.2"
+        "vitest": "^0.34.1"
     },
     "dependencies": {
         "browser-util-inspect": "^0.2.0",

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

@@ -68,7 +68,7 @@ describe("use/useListSort", () => {
         expect(listSort.state.order).toEqual([]);
         expect(listSort.state.objectsInOrder).toEqual([]);
         expect(listSort.state.sortCriteria).toEqual({});
-        expect(listSort.state.sortCriteriaWatches).toEqual({});
+        expect(listSort.state.sortCriteriaEffectScopes).toEqual({});
         expect(listSort.state.orderByDesc).toEqual([true, false]);
     });
     describe("addSortCriteria and removeSortCriteria", () => {

package/tests/unit/utils/flattenPaths.spec.js

@@ -15,6 +15,10 @@ describe("utils/flattenPaths", () => {
             it("with a single level and a nested object and array", () => {
                 expect(flattenPaths({ a: 1, b: { c: [2] } })).toEqual(["a", "b.c[0]"]);
             });
+            it("should limit to a specific depth", () => {
+                expect(flattenPaths({ a: 1, b: { c: [2] } }, { limit: 1 })).toEqual(["a"]);
+                expect(flattenPaths({ a: 1, b: { c: 1, d: [2], e: { f: 3 } } }, { limit: 2 })).toEqual(["a", "b.c"]);
+            });
         });
         describe("should work on arrays as the base", () => {
             it("with a single level", () => {
@@ -29,6 +33,10 @@ describe("utils/flattenPaths", () => {
             it("with a single level and a nested object and array", () => {
                 expect(flattenPaths([1, { c: [2] }])).toEqual(["[0]", "[1].c[0]"]);
             });
+            it("should limit to a specific depth", () => {
+                expect(flattenPaths([1, { c: [2] }], { limit: 1 })).toEqual(["[0]"]);
+                expect(flattenPaths([1, [1, [2, [3], 4], 5]], { limit: 2 })).toEqual(["[0]", "[1][0]", "[1][2]"]);
+            });
         });
         it("should work on a real world example", () => {
             const toBeFlattened = {

package/tests/unit/utils/keyDiff.spec.js

@@ -1,4 +1,4 @@
-import { keyDiff } from "../../../utils/keyDiff.js";
+import { keyDiff, keyDiffDeep } from "../../../utils/keyDiff.js";
 
 describe("keyDiff", function () {
     describe("should return the difference between two arrays of object keys", function () {
@@ -64,4 +64,47 @@ describe("keyDiff", function () {
         expect(removedKeys).toEqual(new Set(["c"]));
         expect(sameKeys).toEqual(new Set(["a"]));
     });
+    describe("keyDiffDeep", function () {
+        it("should return the difference between two objects", function () {
+            const newObj = {
+                a: 1,
+                b: {
+                    c: 2,
+                },
+                c: 3,
+            };
+            const oldObj = {
+                a: 1,
+                b: 2,
+                c: 3,
+            };
+            // if using to patch, be sure to remove keys before adding them
+            expect(keyDiffDeep(newObj, oldObj)).toEqual({
+                addedKeys: new Set(["b.c"]),
+                removedKeys: new Set(["b"]),
+                sameKeys: new Set(["a", "c"]),
+            });
+        });
+        it("should be able to limit the depth", function () {
+            const newObj = {
+                a: 1,
+                b: {
+                    c: { d: 1, e: 2, f: 3 },
+                },
+                g: 3,
+            };
+            const oldObj = {
+                a: 1,
+                b: {
+                    c: {},
+                },
+                g: 3,
+            };
+            expect(keyDiffDeep(newObj, oldObj, { limit: 1 })).toEqual({
+                addedKeys: new Set(),
+                removedKeys: new Set(),
+                sameKeys: new Set(["a", "g"]),
+            });
+        });
+    });
 });

package/use/list.js

@@ -16,7 +16,7 @@ export const useLists = (listArgs) => {
 };
 
 // the big brother of useObject, managing a chain of useList* instances.
-export const useList = ({ props, functions, paged = false, keepOldPages = false }) => {
+export const useList = ({ props, functions = {}, paged = false, keepOldPages = false, useTextSearch = false }) => {
     const managed = shallowReactive({
         listInstance: null,
         listSubscription: null,
@@ -58,7 +58,7 @@ export const useList = ({ props, functions, paged = false, keepOldPages = false
 
         managed.listFilter = useListFilter({
             parentState: managed.listCalculated.state,
-            useTextSearch: toRef(props, "useTextSearch"),
+            useTextSearch,
             textSearchRules: toRef(props, "textSearchRules"),
             textSearchValue: toRef(props, "textSearchValue"),
             allowedValues: toRef(props, "allowedValues"),

package/use/listRelated.js

@@ -4,8 +4,10 @@ import { listInstanceStateKeys } from "./listInstance.js";
 import { listSubscriptionStateKeys } from "./listSubscription.js";
 import { useWatchesRunning } from "./watchesRunning.js";
 import get from "lodash-es/get.js";
+import identity from "lodash-es/identity.js";
 import isArray from "lodash-es/isArray.js";
 import isEmpty from "lodash-es/isEmpty.js";
+import isEqual from "lodash-es/isEqual.js";
 import isUndefined from "lodash-es/isUndefined.js";
 import { computed, effectScope, onScopeDispose, reactive, toRef, unref, watch } from "vue";
 
@@ -55,7 +57,7 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
         const relatedObjectsRulesIsEmpty = !state.relatedObjectsRules || isEmpty(state.relatedObjectsRules);
         for (const objectKey of Object.keys(state.relatedObjects)) {
             const relatedObjectsObject = state.relatedObjects[objectKey];
-            const originalObject = parentState.objects[objectKey];
+            const originalObjectRef = toRef(parentState.objects, objectKey);
             let removedRuleKeys, addedRuleKeys;
             if (!relatedObjectsRulesIsEmpty) {
                 ({ removedKeys: removedRuleKeys, addedKeys: addedRuleKeys } = keyDiff(
@@ -77,22 +79,48 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
             }
             relatedObjectsEffectScopes[objectKey].run(() => {
                 for (const addedRuleKey of addedRuleKeys) {
-                    relatedObjectsObject[addedRuleKey] = computed(() => {
+                    relatedObjectsObject[addedRuleKey] = undefined;
+                    const relatedObjectsObjectWatchFn = () => {
                         // deal with computed objects being passed.
                         const ruleObjects = unref(state.relatedObjectsRules?.[addedRuleKey]?.objects);
                         const rulePkKey = state.relatedObjectsRules?.[addedRuleKey]?.pkKey || addedRuleKey;
+                        const ruleOrder = unref(state.relatedObjectsRules?.[addedRuleKey]?.order);
                         if (!ruleObjects || !rulePkKey) {
-                            return undefined;
+                            relatedObjectsObject[addedRuleKey] = undefined;
+                            return;
                         }
-                        const value = get(originalObject, rulePkKey);
+                        let value = get(unref(originalObjectRef), rulePkKey);
                         if (isUndefined(value)) {
-                            return undefined;
+                            relatedObjectsObject[addedRuleKey] = undefined;
+                            return;
                         }
                         if (isArray(value)) {
-                            return value.map((e) => ruleObjects[e]);
+                            // the related list could be sorted differently than the original list.
+                            if (ruleOrder?.length) {
+                                value = value.filter(identity);
+                                const indexById = Object.fromEntries(ruleOrder.map((e, i) => [e, i]));
+                                value.sort((a, b) => {
+                                    const aIndex = indexById[a];
+                                    const bIndex = indexById[b];
+                                    return aIndex - bIndex;
+                                });
+                            }
+                            value = value.map((e) => ruleObjects[e]).filter(identity);
+                        } else {
+                            value = ruleObjects[value];
                         }
-                        return ruleObjects[value];
-                    });
+                        if (!isEqual(value, relatedObjectsObject[addedRuleKey])) {
+                            relatedObjectsObject[addedRuleKey] = value;
+                        }
+                    };
+                    watch(
+                        [toRef(state.relatedObjectsRules, addedRuleKey), originalObjectRef],
+                        relatedObjectsObjectWatchFn,
+                        {
+                            deep: true,
+                            immediate: true,
+                        }
+                    );
                 }
             });
         }

package/use/listSort.js

@@ -10,17 +10,16 @@ import identity from "lodash-es/identity.js";
 import isEmpty from "lodash-es/isEmpty.js";
 import isNull from "lodash-es/isNull.js";
 import isUndefined from "lodash-es/isUndefined.js";
-import partial from "lodash-es/partial.js";
 import throttle from "lodash-es/throttle.js";
 import zip from "lodash-es/zip.js";
-import { effectScope, onScopeDispose, reactive, toRef, unref, watch } from "vue";
+import { effectScope, reactive, toRef, unref, watch } from "vue";
 
 export const listSortStateKeys = [
     "orderByRules",
     // "order",
     // "objectsInOrder",
     "sortCriteria",
-    "sortCriteriaWatches",
+    "sortCriteriaEffectScopes",
     "orderByDesc",
 ];
 
@@ -55,42 +54,43 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
         order: [],
         objectsInOrder: [],
         sortCriteria: {},
-        sortCriteriaWatches: {},
+        sortCriteriaEffectScopes: {},
         orderByDesc: [],
     });
     const es = effectScope();
 
     function removeSortCriteria(removedKey) {
-        const stopWatches = state.sortCriteriaWatches[removedKey] || [];
-        let stopWatch = stopWatches.pop();
-        while (stopWatch) {
-            stopWatch();
-            stopWatch = stopWatches.pop();
+        const oldScope = state.sortCriteriaEffectScopes[removedKey];
+        if (oldScope) {
+            oldScope.stop();
+            delete state.sortCriteriaEffectScopes[removedKey];
         }
-        delete state.sortCriteriaWatches[removedKey];
         delete state.sortCriteria[removedKey];
     }
 
     function addSortCriteria(object, key) {
-        const oldStopWatches = state.sortCriteriaWatches[key] || [];
-        let stopWatch = oldStopWatches.pop();
-        while (stopWatch) {
-            stopWatch();
-            stopWatch = oldStopWatches.pop();
+        const oldScope = state.sortCriteriaEffectScopes[key];
+        if (oldScope) {
+            oldScope.stop();
         }
-        const stopWatches = [];
-        if (!state.sortCriteria[key]) {
-            state.sortCriteria[key] = [];
-        }
-        stopWatches.push(
+        const newScope = effectScope();
+        newScope.run(() => {
+            if (!state.sortCriteria[key]) {
+                state.sortCriteria[key] = [];
+            }
             watch(
-                [object, state.orderByRules],
+                [object, toRef(state, "orderByRules")],
                 () => {
+                    const obj = unref(object);
                     const newSearchCriteria = [];
                     for (const orderByObj of state.orderByRules.filter(identity)) {
-                        const obo = unref(orderByObj);
-                        const getter = obo.keyFn ? obo.keyFn : partial(get, partial.placeholder, obo.key);
-                        newSearchCriteria.push(getter(object));
+                        let newItem;
+                        if (orderByObj.keyFn) {
+                            newItem = orderByObj.keyFn(obj, state);
+                        } else {
+                            newItem = get(obj, orderByObj.key);
+                        }
+                        newSearchCriteria.push(newItem);
                     }
                     assignReactiveObject(state.sortCriteria[key], newSearchCriteria);
                 },
@@ -98,9 +98,9 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
                     deep: true,
                     immediate: true,
                 }
-            )
-        );
-        state.sortCriteriaWatches[key] = stopWatches;
+            );
+        });
+        state.sortCriteriaEffectScopes[key] = newScope;
     }
 
     function sortCriteriaWatch() {
@@ -110,6 +110,8 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
                     removeSortCriteria(removedKey);
                 }
             }
+            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));
@@ -117,10 +119,12 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
             removeSortCriteria(removedKey);
         }
 
-        for (const addedKey of addedKeys) {
-            const object = parentState.objects[addedKey];
-            addSortCriteria(object, addedKey);
-        }
+        es.run(() => {
+            for (const addedKey of addedKeys) {
+                const object = toRef(() => parentState.objects[addedKey]);
+                addSortCriteria(object, addedKey);
+            }
+        });
         assignReactiveObject(
             state.orderByDesc,
             state.orderByRules.filter(identity).map((e) => e.desc || false)
@@ -129,8 +133,8 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
 
     function sortWatch() {
         if (!state.orderByRules || !state.orderByRules.length) {
-            assignReactiveObject(state.order, Object.keys(parentState.objects));
-            assignReactiveObject(state.objectsInOrder, Object.values(parentState.objects));
+            assignReactiveObject(state.order, cloneDeep(parentState.order));
+            assignReactiveObject(state.objectsInOrder, cloneDeep(parentState.objectsInOrder));
             return;
         }
 
@@ -197,20 +201,14 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
         }
         // we do not need two immediate watches to the same function.
         watch(() => Object.keys(parentState.objects), sortCriteriaWatch);
-        watch(() => cloneDeep(state.orderByRules), sortCriteriaWatch, {
+        watch(toRef(state, "orderByRules"), sortCriteriaWatch, {
             deep: true,
             immediate: true,
         });
 
-        // watching parentState.order triggers some out of order `computed`s, now that listInstance.order is a computed.
-        watch([toRef(state, "orderByDesc"), () => state.sortCriteria], throttledSortWatch, {
+        watch([toRef(state, "orderByDesc"), toRef(state, "sortCriteria")], throttledSortWatch, {
             deep: true,
         });
-        onScopeDispose(() => {
-            Object.keys(state.sortCriteriaWatches).forEach((key) => {
-                removeSortCriteria(key);
-            });
-        });
     });
 
     return {

package/use/listSubscription.js

@@ -230,7 +230,7 @@ export function useListSubscription({ listInstance, props, functions, keepOldPag
                     state.subscriptionErrored = true;
                     state.subscriptionError = err;
                 });
-                catchPromise.cancel = subscribePromise.cancel;
+                catchPromise.cancel = subscribePromise.cancel.bind(subscribePromise);
                 return catchPromise;
             },
             watchArguments: reactive({

package/utils/flattenPaths.js

@@ -12,10 +12,13 @@ import isObject from "lodash-es/isObject.js";
  * Array indexes are wrapped in square brackets and object keys are prefixed with a period.
  * @function flattenPaths
  * @param {Array | object} arrayOrObject array or object to flatten
- * @param {string} currentPath current path, for recursion or as a starting point
+ * @param {object} options options
+ * @param {string} options.currentPath current path, for recursion or as a starting point
+ * @param {number} options.depth current depth, for recursion
+ * @param {number} options.limit limit the depth of recursion
  * @returns {string[]} paths
  */
-export function flattenPaths(arrayOrObject, currentPath = "") {
+export function flattenPaths(arrayOrObject, { currentPath = "", depth = 0, limit = 0 } = {}) {
     // arrayOrObject keys or indexes values can be objects or arrays.
     // find all paths you could use lodash to "get()" to.
     // indexes use `[${index}]`, keys use `.${key}`
@@ -23,11 +26,16 @@ export function flattenPaths(arrayOrObject, currentPath = "") {
     const paths = [];
     const keysOrIndexes = isArray(arrayOrObject);
     const dotOrNot = currentPath ? "." : "";
+    if (limit && depth >= limit) {
+        return paths;
+    }
     if (isObject(arrayOrObject)) {
         for (const [key, value] of Object.entries(arrayOrObject)) {
             const keyPath = keysOrIndexes ? `[${key}]` : `${dotOrNot}${key}`;
             if (isObject(value) || isArray(value)) {
-                paths.push(...flattenPaths(value, `${currentPath}${keyPath}`));
+                paths.push(
+                    ...flattenPaths(value, { currentPath: `${currentPath}${keyPath}`, depth: depth + 1, limit })
+                );
             } else {
                 paths.push(`${currentPath}${keyPath}`);
             }

package/utils/keyDiff.js

@@ -55,11 +55,18 @@ export function keyDiff(newKeys, oldKeys, { sameKeys = true, removedKeys = true,
  * @param {object} newObj - the new version of the object
  * @param {object} oldObj - the old version of the object
  * @param {KeyDiffOptions} [options] - which differences are returned
+ * @param {boolean} [options.sameKeys] - if true, return keys that are the same
+ * @param {boolean} [options.removedKeys] - if true, return keys that are removed
+ * @param {boolean} [options.addedKeys] - if true, return keys that are added
+ * @param {number} [options.limit] - limit the depth of recursion
  * @returns {KeyDiffResult} - the differences
  */
 export function keyDiffDeep(newObj, oldObj, options = {}) {
-    const newPaths = flattenPaths(newObj);
-    const oldPaths = flattenPaths(oldObj);
-    const result = keyDiff(newPaths, oldPaths, options);
-    return result;
+    const additionalFlattenArgs = [];
+    if (options.limit) {
+        additionalFlattenArgs.push({ limit: options.limit });
+    }
+    const newPaths = flattenPaths(newObj, ...additionalFlattenArgs);
+    const oldPaths = flattenPaths(oldObj, ...additionalFlattenArgs);
+    return keyDiff(newPaths, oldPaths, options);
 }