@arrai-innovations/reactive-helpers 7.1.1 → 8.0.0

package/.vscode/extensions.json

@@ -1,3 +1,3 @@
 {
-    "recommendations": ["dbaeumer.vscode-eslint", "znck.vue"]
+    "recommendations": ["dbaeumer.vscode-eslint", "znck.vue", "galloween.jsdoc-highlight-code"]
 }

package/package.json

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

package/tests/unit/crudPromise.js

@@ -13,9 +13,7 @@ export class CancellableResolvable {
         const cancelResolvable = new Resolvable();
         newResolvable.promise.cancel = jest
             .fn()
-            .mockImplementationOnce(async () => {
-                return cancelResolvable.promise;
-            })
+            .mockImplementationOnce(async () => cancelResolvable.promise)
             .mockRejectedValue(new Error("cancel already called"));
         Object.assign(this, newResolvable);
         this.cancel = cancelResolvable;

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

@@ -24,9 +24,7 @@ describe("use/listSubscription.spec.js", function () {
         const listInstanceModule = await import("../../../use/listInstance");
         crudList = jest
             .fn()
-            .mockImplementationOnce(() => {
-                return crudListResolvable[0].promise;
-            })
+            .mockImplementationOnce(() => crudListResolvable[0].promise)
             .mockImplementation(() => {
                 const newResolvable = new CancellableResolvable();
                 crudListResolvable.push(newResolvable);

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

@@ -34,12 +34,8 @@ describe("use/objectSubscription.js", function () {
         });
         globalUnsubscribe = jest.fn();
         globalSubscribe = jest.fn();
-        globalSubscribe.mockImplementation(() => {
-            return Promise.resolve(globalUnsubscribe);
-        });
-        globalUnsubscribe.mockImplementation(() => {
-            return true;
-        });
+        globalSubscribe.mockImplementation(() => Promise.resolve(globalUnsubscribe));
+        globalUnsubscribe.mockImplementation(() => true);
         const imported = await import("../../../use/objectSubscription");
         imported.setObjectSubscriptionCrud({
             subscribe: globalSubscribe,

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

@@ -41,9 +41,7 @@ describe("utils/assignReactiveObject", function () {
                 const tes = effectScope();
                 let computedSum;
                 tes.run(() => {
-                    computedSum = computed(() => {
-                        return target.a + target.b + target.c;
-                    });
+                    computedSum = computed(() => target.a + target.b + target.c);
                 });
                 try {
                     expect(computedSum.value).toBe(6);

package/use/cancellableIntent.js

@@ -1,11 +1,8 @@
-import { useDebugMessage } from "../utils";
 import identity from "lodash-es/identity";
 import isEqual from "lodash-es/isEqual";
 import { effectScope, nextTick, onScopeDispose, reactive, readonly, watch } from "vue";
 import { deepUnref } from "vue-deepunref";
 
-const watchFnDebugMessage = useDebugMessage(["cancellableIntent", "watch"]);
-
 /*
  * 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.
@@ -47,7 +44,6 @@ export function useCancellableIntent({ awaitableWithCancel, watchArguments = {},
     }
 
     const watchFn = () => {
-        watchFnDebugMessage("watchFn called");
         let newWatchValues = deepUnref(Object.values(watchArguments));
         if (isEqual(newWatchValues, previousWatchValues)) {
             return;

package/use/listCalculated.js

@@ -1,4 +1,4 @@
-import { keyDiff, loadingCombine, useDebugMessage } from "../utils";
+import { keyDiff, loadingCombine } from "../utils";
 import { listInstanceStateKeys } from "./listInstance";
 import { listRelatedStateKeys } from "./listRelated";
 import { listSubscriptionStateKeys } from "./listSubscription";
@@ -6,9 +6,6 @@ import { useWatchesRunning } from "./watchesRunning";
 import isEmpty from "lodash-es/isEmpty";
 import { computed, effectScope, onScopeDispose, reactive, toRef, watch } from "vue";
 
-const computedDebugMessage = useDebugMessage(["listCalculated", "computed"]);
-const watchDebugMessage = useDebugMessage(["listCalculated", "watch"]);
-
 export const listCalculatedStateKeys = [
     "calculatedObjects",
     "calculatedObjectsParentStateObjectsWatchRunning",
@@ -38,7 +35,6 @@ export function useListCalculated({ parentState, calculatedObjectsRules }) {
     const calculatedObjectsEffectScopes = {};
 
     function parentStateObjectsWatch() {
-        watchDebugMessage("parentStateObjectsWatch called");
         const { addedKeys, removedKeys } = keyDiff(
             Object.keys(parentState.objects),
             Object.keys(state.calculatedObjects)
@@ -57,7 +53,6 @@ export function useListCalculated({ parentState, calculatedObjectsRules }) {
     }
 
     function calculatedObjectsWatch() {
-        watchDebugMessage("calculatedObjectsWatch called");
         const calculatedObjectsRulesIsEmpty = !state.calculatedObjectsRules || isEmpty(state.calculatedObjectsRules);
         for (const objectKey of Object.keys(state.calculatedObjects)) {
             if (!calculatedObjectsEffectScopes[objectKey]) {
@@ -86,9 +81,9 @@ export function useListCalculated({ parentState, calculatedObjectsRules }) {
             }
             calculatedObjectsEffectScopes[objectKey].run(() => {
                 for (const addedRuleKey of addedRuleKeys) {
-                    calculatedObjectsObject[addedRuleKey] = computed(() => {
-                        return state.calculatedObjectsRules?.[addedRuleKey]?.(originalObject);
-                    });
+                    calculatedObjectsObject[addedRuleKey] = computed(() =>
+                        state.calculatedObjectsRules?.[addedRuleKey]?.(originalObject)
+                    );
                 }
             });
         }
@@ -125,12 +120,9 @@ export function useListCalculated({ parentState, calculatedObjectsRules }) {
 
         watchesRunning = useWatchesRunning({
             triggerRefs: [
-                computed(() => {
-                    computedDebugMessage("listCalculated trigger");
-                    return state.calculatedObjectsRules && !isEmpty(state.calculatedObjectsRules)
-                        ? parentState.loading
-                        : false;
-                }),
+                computed(() =>
+                    state.calculatedObjectsRules && !isEmpty(state.calculatedObjectsRules) ? parentState.loading : false
+                ),
             ],
             watchSentinelRefs: [
                 toRef(state, "calculatedObjectsParentStateObjectsWatchRunning"),
@@ -138,10 +130,7 @@ export function useListCalculated({ parentState, calculatedObjectsRules }) {
             ],
         });
 
-        state.running = computed(() => {
-            computedDebugMessage("listCalculated running");
-            return loadingCombine(watchesRunning.state.running, parentState.running);
-        });
+        state.running = computed(() => loadingCombine(watchesRunning.state.running, parentState.running));
 
         onScopeDispose(() => {
             for (const objectKey of Object.keys(calculatedObjectsEffectScopes)) {

package/use/listInstance.js

@@ -129,9 +129,7 @@ export function useListInstance({ props, functions = {} }) {
             return Promise.reject(new ListError("already loading."));
         }
         let returnPromiseResolve;
-        const returnPromise = new Promise((resolve) => {
-            returnPromiseResolve = resolve;
-        });
+        const returnPromise = new Promise((resolve) => (returnPromiseResolve = resolve));
         state.loading = true;
         state.errored = false;
         state.error = null;

package/use/listRelated.js

@@ -1,4 +1,4 @@
-import { keyDiff, loadingCombine, useDebugMessage } from "../utils";
+import { keyDiff, loadingCombine } from "../utils";
 import { listInstanceStateKeys } from "./listInstance";
 import { listSubscriptionStateKeys } from "./listSubscription";
 import { useWatchesRunning } from "./watchesRunning";
@@ -8,9 +8,6 @@ import isEmpty from "lodash-es/isEmpty";
 import isUndefined from "lodash-es/isUndefined";
 import { computed, effectScope, onScopeDispose, reactive, toRef, unref, watch } from "vue";
 
-const computedDebugMessage = useDebugMessage(["listRelated", "computed"]);
-const watchDebugMessage = useDebugMessage(["listRelated", "watch"]);
-
 export const listRelatedStateKeys = [
     "relatedObjects",
     "relatedObjectsRules",
@@ -37,7 +34,6 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
     const relatedObjectsEffectScopes = {};
 
     function parentStateObjectsWatch() {
-        watchDebugMessage("parentStateObjectsWatch called");
         const { addedKeys, removedKeys } = keyDiff(Object.keys(parentState.objects), Object.keys(state.relatedObjects));
         for (const removedKey of removedKeys) {
             delete state.relatedObjects[removedKey];
@@ -53,7 +49,6 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
     }
 
     function relatedObjectsWatch() {
-        watchDebugMessage("relatedObjectsWatch called");
         const relatedObjectsRulesIsEmpty = !state.relatedObjectsRules || isEmpty(state.relatedObjectsRules);
         for (const objectKey of Object.keys(state.relatedObjects)) {
             const relatedObjectsObject = state.relatedObjects[objectKey];
@@ -125,12 +120,9 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
 
         watchesRunning = useWatchesRunning({
             triggerRefs: [
-                computed(() => {
-                    computedDebugMessage("listRelated triggerRefs");
-                    return state.relatedObjectsRules && !isEmpty(state.relatedObjectsRules)
-                        ? parentState.loading
-                        : false;
-                }),
+                computed(() =>
+                    state.relatedObjectsRules && !isEmpty(state.relatedObjectsRules) ? parentState.loading : false
+                ),
             ],
             watchSentinelRefs: [
                 toRef(state, "relatedObjectsParentStateObjectsWatchRunning"),
@@ -138,10 +130,7 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
             ],
         });
 
-        state.running = computed(() => {
-            computedDebugMessage("listRelated running");
-            return loadingCombine(watchesRunning.state.running, parentState.running);
-        });
+        state.running = computed(() => loadingCombine(watchesRunning.state.running, parentState.running));
 
         onScopeDispose(() => {
             for (const objectKey of Object.keys(relatedObjectsEffectScopes)) {

package/use/objectCalculated.js

@@ -1,11 +1,8 @@
-import { keyDiff, loadingCombine, useDebugMessage } from "../utils";
+import { keyDiff, loadingCombine } from "../utils";
 import { useWatchesRunning } from "./watchesRunning";
 import isEmpty from "lodash-es/isEmpty";
 import { computed, effectScope, onScopeDispose, reactive, toRef, watch } from "vue";
 
-const computedDebugMessage = useDebugMessage(["objectCalculated", "computed"]);
-const watchDebugMessage = useDebugMessage(["objectCalculated", "watch"]);
-
 export function useObjectCalculateds(instances, args) {
     for (const [key, value] of Object.entries(args)) {
         useObjectCalculated({
@@ -68,7 +65,6 @@ export function useObjectCalculated({
         }
 
         watch([() => state.calculatedObjectRules && Object.keys(state.calculatedObjectRules)], () => {
-            watchDebugMessage("calculatedObjectRules watch called");
             let addedKeys = [],
                 removedKeys = [],
                 sameKeys = [];
@@ -106,12 +102,7 @@ export function useObjectCalculated({
         });
 
         watchesRunning = useWatchesRunning({
-            triggerRefs: [
-                computed(() => {
-                    computedDebugMessage("watchesRunningTriggerRefs computed");
-                    return !isEmpty(state.calculatedObjectRules) ? parentState.loading : false;
-                }),
-            ],
+            triggerRefs: [computed(() => (!isEmpty(state.calculatedObjectRules) ? parentState.loading : false))],
             watchSentinelRefs: [
                 toRef(state, "parentStateObjectWatchRunning"),
                 toRef(state, "calculatedObjectWatchRunning"),
@@ -119,10 +110,7 @@ export function useObjectCalculated({
         });
 
         state.calculatedRunning = toRef(watchesRunning.state, "running");
-        state.running = computed(() => {
-            computedDebugMessage("running computed");
-            return loadingCombine(watchesRunning.state.running, parentState.relatedRunning);
-        });
+        state.running = computed(() => loadingCombine(watchesRunning.state.running, parentState.relatedRunning));
 
         onScopeDispose(() => {
             for (const key in calculatedObjectEffectScopes) {

package/use/objectRelated.js

@@ -1,4 +1,4 @@
-import { keyDiff, useDebugMessage } from "../utils";
+import { keyDiff } from "../utils";
 import { useWatchesRunning } from "./watchesRunning";
 import get from "lodash-es/get";
 import isArray from "lodash-es/isArray";
@@ -6,9 +6,6 @@ import isEmpty from "lodash-es/isEmpty";
 import isUndefined from "lodash-es/isUndefined";
 import { computed, effectScope, onScopeDispose, reactive, toRef, unref, watch } from "vue";
 
-const computedDebugMessage = useDebugMessage(["objectRelated", "computed"]);
-const watchDebugMessage = useDebugMessage(["objectRelated", "watch"]);
-
 export function useObjectRelateds(instances, args) {
     for (const [key, value] of Object.entries(args)) {
         useObjectRelated({
@@ -64,7 +61,6 @@ export function useObjectRelated({
         }
 
         watch([() => state.relatedObjectRules && Object.keys(state.relatedObjectRules)], () => {
-            watchDebugMessage("relatedObjectRules changed");
             let addedRuleKeys = [],
                 removedRuleKeys = [];
             if (!state.relatedObjectRules) {
@@ -87,7 +83,6 @@ export function useObjectRelated({
                 relatedObjectEffectScopes[addedRuleKey] = effectScope();
                 relatedObjectEffectScopes[addedRuleKey].run(() => {
                     state.relatedObjectObjects[addedRuleKey] = computed(() => {
-                        computedDebugMessage("relatedObjectObjects computed");
                         // deal with computed objects being passed.
                         const ruleObjects = unref(state.relatedObjectRules?.[addedRuleKey]?.objects);
                         const rulePkKey = state.relatedObjectRules?.[addedRuleKey]?.pkKey || addedRuleKey;
@@ -108,12 +103,7 @@ export function useObjectRelated({
         });
 
         watchesRunning = useWatchesRunning({
-            triggerRefs: [
-                computed(() => {
-                    watchDebugMessage("parentStateObjectWatchRunning");
-                    return !isEmpty(state.relatedObjectRules) ? parentState.loading : false;
-                }),
-            ],
+            triggerRefs: [computed(() => (!isEmpty(state.relatedObjectRules) ? parentState.loading : false))],
             watchSentinelRefs: [
                 toRef(state, "parentStateObjectWatchRunning"),
                 toRef(state, "relatedObjectWatchRunning"),

package/use/watchesRunning.js

@@ -1,9 +1,6 @@
-import { loadingCombine, useDebugMessage } from "../utils";
+import { loadingCombine } from "../utils";
 import { computed, effectScope, reactive, unref, watch } from "vue";
 
-const computedDebugMessage = useDebugMessage(["watchesRunning", "computed"]);
-const watchDebugMessage = useDebugMessage(["watchesRunning", "watch"]);
-
 export function useWatchesRunning({ triggerRefs, watchSentinelRefs }) {
     const state = reactive({});
 
@@ -13,7 +10,6 @@ export function useWatchesRunning({ triggerRefs, watchSentinelRefs }) {
         watch(
             triggerRefs,
             (values) => {
-                watchDebugMessage("useWatchesRunning triggerRefs");
                 if (values.every((value) => unref(value))) {
                     watchSentinelRefs.forEach((ref) => {
                         ref.value = true;
@@ -27,7 +23,6 @@ export function useWatchesRunning({ triggerRefs, watchSentinelRefs }) {
         );
         state.running = computed(() => {
             const values = watchSentinelRefs.map((ref) => ref.value);
-            computedDebugMessage("useWatchesRunning running");
             return loadingCombine(values);
         });
     });

package/utils/assignReactiveObject.js

@@ -11,12 +11,39 @@ export class AssignReactiveObjectError extends Error {
     }
 }
 
+/**
+ * @typedef {Ref|object|array} ValidTargetOrSource targets and sources must be refs, objects, or arrays
+ * and refs must ultimately resolve to objects or arrays
+ */
+
+/**
+ * Validates that a value is an array or an object, and throws an error if it is not.
+ *
+ * @param {string} key The key being validated.
+ * @param {*} value The value being validated.
+ * @throws {AssignReactiveObjectError} If the value is not an array or an object.
+ */
 function isArrayOrObject(key, value) {
     if (!(isArray(value) || isObject(value))) {
         throw new AssignReactiveObjectError(`${key} must be an object or an array, not ${inspect(value)}`);
     }
 }
 
+/**
+ * @typedef validateTargetAndSourceResult
+ * @property {ValidTargetOrSource} target The validated target value.
+ * @property {ValidTargetOrSource} source The validated source value.
+ */
+
+/**
+ * Validates that the target and source values are arrays or objects, and returns them.
+ * If either value is a ref, it is dereferenced before validation.
+ *
+ * @param {ValidTargetOrSource} target The target value to validate.
+ * @param {ValidTargetOrSource} source The source value to validate.
+ * @returns {validateTargetAndSourceResult} An object containing the validated target and source values.
+ * @throws {AssignReactiveObjectError} If either value is not an array or an object.
+ */
 function validateTargetAndSource(target, source) {
     isArrayOrObject("target", target);
     isArrayOrObject("source", source);
@@ -33,42 +60,90 @@ function validateTargetAndSource(target, source) {
     return { target, source };
 }
 
-function reactiveReplaceKeys(target, source, keys, exclude) {
+/**
+ * Replaces keys in a target object or array with reactive refs to the corresponding keys in a
+ * source object or array.
+ *
+ * @param {ValidTargetOrSource} target The object receiving values.
+ * @param {ValidTargetOrSource} source The object providing values.
+ * @param {array} keys The keys to replace.
+ * @param {array} {exclude} Keys to exclude from replacement.
+ * @returns {boolean} True if any keys were replaced, false otherwise.
+ * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
+ */
+function reactiveReplaceKeys(target, source, keys, exclude = []) {
     const targetIsReactive = isReactive(target);
     const sourceIsReactive = isReactive(source);
+    let didAnything = false;
     for (const key of keys) {
         if (!exclude.includes(key)) {
             if (targetIsReactive && sourceIsReactive) {
                 target[key] = toRef(source, key);
+                didAnything = true;
             } else if (target[key] !== source[key]) {
                 target[key] = source[key];
+                didAnything = true;
             }
         }
     }
+    return didAnything;
 }
 
+/**
+ * Adds to a target the missing keys from a source. `addedKeys` can be precalculated to avoid recalculation.
+ *
+ * @param {ValidTargetOrSource} target The object receiving values.
+ * @param {ValidTargetOrSource} source The object providing values.
+ * @param {array} {exclude} Keys to exclude from the addition.
+ * @param {array} {addedKeys} Precaulcated array of keys to add, if available. Otherwise, the
+ * keys will be calculated.
+ * @returns {boolean} True if any keys were added, false otherwise.
+ * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
+ */
 export function addReactiveObject(target, source, exclude = [], addedKeys = null) {
     if (!addedKeys) {
         if (target === source) {
-            return;
+            return false;
         }
         ({ target, source } = validateTargetAndSource(target, source));
         ({ addedKeys } = keyDiff(Object.keys(source) || [], Object.keys(target) || []));
     }
-    reactiveReplaceKeys(target, source, addedKeys, exclude);
+    return reactiveReplaceKeys(target, source, addedKeys, exclude);
 }
 
+/**
+ * Updates a target with mutually shared keys from a source. `sameKeys` can be precalculated to avoid recalculation.
+ *
+ * @param {ValidTargetOrSource} target The object receiving values.
+ * @param {ValidTargetOrSource} source The object providing values.
+ * @param {array} {exclude} Keys to exclude from the update.
+ * @param {array} {sameKeys} Precaulcated array of keys to update, if available. Otherwise, the
+ * keys will be calculated.
+ * @returns {boolean} True if any keys were updated, false otherwise.
+ * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
+ */
 export function updateReactiveObject(target, source, exclude = [], sameKeys = null) {
     if (!sameKeys) {
         if (target === source) {
-            return;
+            return false;
         }
         ({ target, source } = validateTargetAndSource(target, source));
         ({ sameKeys } = keyDiff(Object.keys(source) || [], Object.keys(target) || []));
     }
-    reactiveReplaceKeys(target, source, sameKeys, exclude);
+    return reactiveReplaceKeys(target, source, sameKeys, exclude);
 }
 
+/**
+ * Adds to a target the missing keys from a source, and updates a target with mutually shared keys from a source.
+ *
+ * @param {ValidTargetOrSource} target The object receiving values.
+ * @param {ValidTargetOrSource} source The object providing values.
+ * @param {array} {exclude} Keys to exclude from the addition or update.
+ * @param {array} {addedKeys} Precaulcated array of keys to add, if available. Otherwise, the
+ * keys will be calculated.
+ * @param {array} {sameKeys} Precaulcated array of keys to update, if available. Otherwise, the
+ * keys will be calculated.
+ */
 export function addOrUpdateReactiveObject(target, source, exclude = [], addedKeys = null, sameKeys = null) {
     if (!addedKeys && !sameKeys) {
         if (target === source) {
@@ -77,48 +152,91 @@ export function addOrUpdateReactiveObject(target, source, exclude = [], addedKey
         ({ target, source } = validateTargetAndSource(target, source));
         ({ addedKeys, sameKeys } = keyDiff(Object.keys(source) || [], Object.keys(target) || []));
     }
-    addReactiveObject(target, source, exclude, addedKeys);
-    updateReactiveObject(target, source, exclude, sameKeys);
+    let didAnything = false;
+    didAnything |= addReactiveObject(target, source, exclude, addedKeys);
+    didAnything |= updateReactiveObject(target, source, exclude, sameKeys);
+    return didAnything;
 }
 
-// there isn't much reactive about this I guess...
+/**
+ * Removes keys from a target that are not present in a source.
+ *
+ * @param {ValidTargetOrSource} target The object receiving trimming.
+ * @param {ValidTargetOrSource|null} source The object that provides the allowed set of keys for calculating `removedKeys`.
+ * @param {array} {exclude} Keys to exclude from removal.
+ * @param {array} {removedKeys} An array to store removed keys.
+ * @returns {boolean} True if any keys were removed, false otherwise.
+ * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
+ */
 export function trimReactiveObject(target, source, exclude = [], removedKeys = null) {
     if (!removedKeys) {
         if (target === source) {
-            return;
+            return false;
         }
         ({ target, source } = validateTargetAndSource(target, source));
         ({ removedKeys } = keyDiff(Object.keys(source) || [], Object.keys(target) || []));
     }
     const targetIsArray = isArray(target);
+    let didAnything = false;
     if (targetIsArray) {
         // Remove indices in reverse (descending) order to keep them stable
         for (const removedKey of [...removedKeys].map((key) => parseInt(key, 10)).sort((a, b) => b - a)) {
             if (!exclude.includes(removedKey)) {
                 target.splice(removedKey, 1);
+                didAnything = true;
             }
         }
     } else {
         for (const removedKey of removedKeys) {
             if (!exclude.includes(removedKey)) {
                 delete target[removedKey];
+                didAnything = true;
             }
         }
     }
+    return didAnything;
 }
 
+/**
+ * Change a target to match a source, where keys missing from the source are removed from the target,
+ * keys present in the source are added to the target, and keys present in both are updated in the target.
+ *
+ * @param {ValidTargetOrSource} target The target object or array.
+ * @param {ValidTargetOrSource} source The reactive object to assign.
+ * @param {array} {exclude} Keys to exclude from the assignment.
+ * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
+ */
 export function assignReactiveObject(target, source, exclude = []) {
     if (target === source) {
         return;
     }
     ({ target, source } = validateTargetAndSource(target, source));
     const { addedKeys, sameKeys, removedKeys } = keyDiff(Object.keys(source) || [], Object.keys(target) || []);
-    trimReactiveObject(target, removedKeys, exclude);
-    addOrUpdateReactiveObject(target, source, exclude, addedKeys, sameKeys);
+    let didAnything = false;
+    didAnything |= trimReactiveObject(target, removedKeys, exclude);
+    didAnything |= addOrUpdateReactiveObject(target, source, exclude, addedKeys, sameKeys);
+    return didAnything;
 }
 
+/**
+ * Recursively change a target to match a source, where keys missing from the source are removed from the target,
+ * keys present in the source are added to the target, and keys present in both are updated in the target.
+ *
+ * As an internal function, this function does not validate its arguments and has no optional arguments.
+ *
+ * @param {ValidTargetOrSource} target The object receiving updates.
+ * @param {ValidTargetOrSource} source The object providing updates.
+ * @param {array} exclude Keys to exclude from the update.
+ * @param {array} addedKeys Precaulcated array of keys to add, if available. Otherwise, the
+ * keys will be calculated.
+ * @param {array} sameKeys Precaulcated array of keys to update, if available. Otherwise, the
+ * keys will be calculated.
+ * @param {string} path The current path, used to rescope exclude for the next level.
+ * @param {function} fn The recursive function to call, likely the calling function itself.
+ */
 function recursiveInner(target, source, exclude, addedKeys, sameKeys, path, fn) {
-    addReactiveObject(target, source, exclude, addedKeys);
+    let didAnything = false;
+    didAnything |= addReactiveObject(target, source, exclude, addedKeys);
     const keysForRecurse = [];
     const keysForReplace = [];
     for (const key of sameKeys) {
@@ -130,7 +248,7 @@ function recursiveInner(target, source, exclude, addedKeys, sameKeys, path, fn)
             }
         }
     }
-    reactiveReplaceKeys(target, source, keysForReplace, exclude);
+    didAnything |= reactiveReplaceKeys(target, source, keysForReplace, exclude);
     for (const key of keysForRecurse) {
         // scope exclude for this next level, remove keys that don't start with the current path, trim keys that do to remove the current path
         const nextLevelExclude = exclude
@@ -139,29 +257,76 @@ function recursiveInner(target, source, exclude, addedKeys, sameKeys, path, fn)
         const nextPath = isArray(source[key]) ? `${path}[${key}]` : `${path}.${key}`;
         fn(target[key], source[key], nextLevelExclude, nextPath);
     }
+    return didAnything;
 }
 
+/**
+ * Recursively change a target to match a source, where keys missing from the source are removed from the target,
+ * keys present in the source are added to the target, and keys present in both are updated in the target.
+ *
+ * An internal function to avoid validating arguments repeatedly.
+ *
+ * @param {ValidTargetOrSource} target The object receiving updates.
+ * @param {ValidTargetOrSource} source The object providing updates.
+ * @param {array} {exclude} Keys to exclude from the assignment.
+ * @param {string} {path} The current path, used to rescope exclude for the next level.
+ * @returns {boolean} True if any keys were added, updated, or removed, false otherwise.
+ * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
+ */
 function assignReactiveObjectRecursive(target, source, exclude = [], path = "") {
     let { addedKeys, sameKeys, removedKeys } = keyDiff(Object.keys(source) || [], Object.keys(target) || []);
-    trimReactiveObject(target, removedKeys, exclude);
-    recursiveInner(target, source, exclude, addedKeys, sameKeys, path, assignReactiveObjectRecursive);
+    let didAnything = false;
+    didAnything |= trimReactiveObject(target, removedKeys, exclude);
+    didAnything |= recursiveInner(target, source, exclude, addedKeys, sameKeys, path, assignReactiveObjectRecursive);
+    return didAnything;
 }
 
+/**
+ * Recursively change a target to match a source, where keys missing from the source are removed from the target,
+ * keys present in the source are added to the target, and keys present in both are updated in the target.
+ *
+ * @param {ValidTargetOrSource} target The object receiving updates.
+ * @param {ValidTargetOrSource} source The object providing updates.
+ * @param {array} {exclude} Keys to exclude from the assignment.
+ * @returns {boolean} True if any keys were added, updated, or removed, false otherwise.
+ * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
+ */
 export function assignReactiveObjectDeep(target, source, exclude = []) {
     // exclude keys will need to be lodash get strings
     if (target === source) {
         return;
     }
     ({ target, source } = validateTargetAndSource(target, source));
-    assignReactiveObjectRecursive(target, source, exclude);
+    return assignReactiveObjectRecursive(target, source, exclude);
 }
 
+/**
+ * Recursively change a target to match a source, where keys present in the source are added to the target, and
+ * keys present in both are updated in the target. Missing keys are not removed.
+ *
+ * As an internal function, this function does not validate its argument.
+ *
+ * @param {ValidTargetOrSource} target The object receiving updates.
+ * @param {ValidTargetOrSource} source The object providing updates.
+ * @param {array} [exclude] Keys to exclude from the update.
+ * @param {string} [path] The current path, used to rescope exclude for the next level.
+ */
 function addOrUpdateReactiveObjectRecursive(target, source, exclude = [], path = "") {
     let addedKeys,
         sameKeys = keyDiff(Object.keys(source) || [], Object.keys(target) || []);
-    recursiveInner(target, source, exclude, addedKeys, sameKeys, path, addOrUpdateReactiveObjectRecursive);
+    return recursiveInner(target, source, exclude, addedKeys, sameKeys, path, addOrUpdateReactiveObjectRecursive);
 }
 
+/**
+ * Recursively change a target to match a source, where keys present in the source are added to the target, and
+ * keys present in both are updated in the target. Missing keys are not removed.
+ *
+ * @param {ValidTargetOrSource} target The object receiving updates.
+ * @param {ValidTargetOrSource} source The object providing updates.
+ * @param {array} [exclude] Keys to exclude from the update.
+ * @returns {boolean} True if any keys were added or updated, false otherwise.
+ * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
+ */
 export function addOrUpdateReactiveObjectDeep(target, source, exclude = []) {
     // exclude keys will need to be lodash get strings
     if (target === source) {

package/utils/debugMessage.js

@@ -1,54 +1,197 @@
-import inspect from "browser-util-inspect";
+import { isSuperset } from "./set";
+import { transformWalk } from "./transformWalk";
+import { isSet, partial, union } from "lodash-es";
+import debounce from "lodash-es/debounce";
 import { unref } from "vue";
 
+/**
+ * Whether debug messages are enabled or not. For deploying to production with debugging but not
+ * spamming everyone with debug messages.
+ *
+ * @type {boolean}
+ */
 window.RH_DEBUG = false;
-window.RH_DEBUG_ENABLED_CATEGORIES = {};
-window.RH_DEBUG_DISABLED_CATEGORIES = {};
 
+/**
+ * Map of categories to whether they are enabled or not. The order of the entries are important.
+ * All categories in the key must be present for the entry to match.
+ * The first matching entry with a value opf true will show the message.
+ * The first matching entry with a value of false will hide the message.
+ * The special category "*" will match all messages.
+ * Strings passed as keys will be treated as a single category.
+ * Sets can also be passed as keys, which is what the arrays get converted to.
+ *
+ * @type {Map<string[]|string|Set, boolean>}
+ * @example
+ * window.RH_DEBUG = true; // turn it on
+ * window.RH_DEBUG_CATEGORIES.set(["ofc-form-component", "lifecycle"], true); // show messages matching both categories
+ * window.RH_DEBUG_CATEGORIES.set(["lifecycle"], false); // turn off lifecycle messages not matching the above
+ * window.RH_DEBUG_CATEGORIES.set(["dropDown"], true); // show dropDown messages except where disabled by the above
+ * window.RH_DEBUG_CATEGORIES.set(["*"], false); // turn off all messages not matching the above
+ */
+window.RH_DEBUG_CATEGORIES = new Map();
+
+/**
+ * Group identical messages together and show a count of how many times they were logged.
+ * Messages are only shown on the trailing edge, so logging is delayed and somewhat out of order.
+ *
+ * @type {boolean}
+ */
+window.RH_DEBOUNCE_DEBUG = false;
+
+/**
+ * Whether to process arguments to be more friendly for console.log, with regard to circular references
+ * and not recursing into vue components.
+ *
+ * @type {boolean}
+ */
+window.RH_TRANSFORM_MESSAGES = true;
+
+const DEBOUNCE_WAIT = 50;
 const log = console.log;
-const messageHolder = [];
+const messageBounceFns = {};
+const counts = {};
 
 /**
- * @param {String} categoriesString
- * @param {(string|Function)[]} messages
+ * @param {Set} categoriesSet categories for the message log
+ * @param {string} categoriesKey key for debouncing
+ * @param {*[]} messages
  */
-const doLog = (categoriesString, messages) => {
+const doLog = (categoriesSet, categoriesKey, messages) => {
     if (messages.length > 0) {
-        for (const message of messages) {
-            messageHolder.push(inspect(unref(typeof message === "function" ? message() : message)));
+        const key = getKey(categoriesKey, messages);
+        const count = counts[key];
+        const logArgs = [Array.from(categoriesSet).join(","), ...messages];
+        if (count > 1) {
+            logArgs.push(`(${count})`);
         }
-        log(categoriesString, ...messageHolder);
-        messageHolder.length = 0;
+        log(...logArgs);
+        delete counts[key];
+        delete messageBounceFns[key];
     }
 };
 
 /**
+ * Process a value for logging, dealing with circular references and
+ * not recursing into vue components.
  *
- * @param {string[]} categories
- * @returns {function(...((string|Function)[]|string|Function)): void}
+ * @param {Map} seenObjects for circlular reference detection
+ * @param {string} key keys is an unused argument from walk
+ * @param {*} value value to process
+ * @param {string} path path to the value, used for display in circular references
+ * @returns {*} processed value
+ */
+export const inspectWalkFn = (seenObjects, key, value, path) => {
+    // return primatives as-is
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+    if (seenObjects.has(value)) {
+        return `「Dupe:${seenObjects.get(value)}」`;
+    }
+    seenObjects.set(value, path);
+    if (value?.type?.__name) {
+        // vue component instance
+        return `⧼ Component:${value.type.__name} ⧽`;
+    }
+    return value;
+};
+
+/**
+ * @param {(string|function)[]} messages messages to resolve
+ * @returns {*[]} resolved messages
+ */
+const resolveMessages = (messages) => {
+    const resolvedMessages = [];
+    for (const message of messages) {
+        let toPush = unref(typeof message === "function" ? message() : message);
+        if (window.RH_TRANSFORM_MESSAGES) {
+            const seenObjects = new Map();
+            toPush = transformWalk(toPush, partial(inspectWalkFn, seenObjects));
+        }
+        resolvedMessages.push(toPush);
+    }
+    return resolvedMessages;
+};
+
+/**
+ * @param {Set} categoriesSet categories for the message log
+ * @param {string} categoriesKey key for debouncing
+ * @param {*[]} messages messages to log
+ */
+const doDebouncedLog = (categoriesSet, categoriesKey, messages) => {
+    if (!window.RH_DEBOUNCE_DEBUG) {
+        return doLog(categoriesSet, categoriesKey, messages);
+    }
+    const key = getKey(categoriesKey, messages);
+    let debouncedLog = messageBounceFns[key];
+    if (!debouncedLog) {
+        debouncedLog = debounce(doLog, DEBOUNCE_WAIT, { leading: false, trailing: true });
+        messageBounceFns[key] = debouncedLog;
+    }
+    debouncedLog(categoriesSet, categoriesKey, messages);
+    counts[key] = (counts[key] || 0) + 1;
+};
+
+/**
+ * @param {string} categoriesKey categories for the message log
+ * @param {(string|function)[]} messages messages to log
+ * @returns {string} key
+ **/
+const getKey = (categoriesKey, messages) => `${categoriesKey}|${messages.join("-")}`;
+
+/**
+ * @typedef {Object} DebugMessageFunction
+ * @property {function(...((string|function)[]|string|function)): void} log log a message
+ */
+
+/**
+ * @param {string[]} categories categories for the message log
+ * @returns {DebugMessageFunction} debug message function
  */
 export function useDebugMessage(categories) {
-    const categoriesSet = new Set(categories);
-    const categoriesString = categoriesSet.size > 0 ? `[${Array.from(categoriesSet).join(", ")}]` : "";
-    return (...messages) => {
+    const categoriesSet = isSet(categories) ? categories : new Set(categories);
+    const sortedCategories = Array.from(categoriesSet).sort();
+    const categoriesKey = categoriesSet.size > 0 ? `[${sortedCategories.join(", ")}]` : "";
+
+    const debugMessage = (...messages) => {
         if (!window.RH_DEBUG) {
             return;
         }
-        if (categoriesSet.size > 0) {
-            for (const category of categoriesSet) {
-                if (window.RH_DEBUG_DISABLED_CATEGORIES[category]) {
-                    return;
-                }
+        for (const [rule, enabledOrDisabled] of window.RH_DEBUG_CATEGORIES.entries()) {
+            let ruleSet;
+            if (Array.isArray(rule)) {
+                ruleSet = new Set(rule);
+            } else if (typeof rule === "string") {
+                ruleSet = new Set(rule.split(","));
+            } else if (rule.toString() === "[object Set]") {
+                ruleSet = rule;
+            } else if (rule === "*") {
+                ruleSet = new Set(["*"]);
+            } else {
+                throw new Error(`Unexpected rule type: ${typeof rule}, ${rule}`);
             }
-            for (const category of categoriesSet) {
-                if (window.RH_DEBUG_ENABLED_CATEGORIES[category]) {
-                    doLog(categoriesString, messages);
+            // if categoriesSet is a superset of ruleSet, then apply the rule
+            // first applicable rule wins
+            if (isSuperset(categoriesSet, ruleSet) || ruleSet.has("*")) {
+                if (enabledOrDisabled === true) {
+                    doDebouncedLog(categoriesSet, categoriesKey, resolveMessages(messages));
+                    return;
+                } else if (enabledOrDisabled === false) {
                     return;
                 }
+                // ignore other values
             }
         }
-        if (categoriesSet.size === 0 || Object.keys(window.RH_DEBUG_ENABLED_CATEGORIES).length === 0) {
-            doLog(categoriesString, messages);
-        }
+        doDebouncedLog(categoriesSet, categoriesKey, resolveMessages(messages));
+    };
+    /**
+     * @param {string[]} moreCategories categories to add
+     * @returns {DebugMessageFunction} new debug message function
+     */
+    debugMessage.more = (moreCategories) => {
+        // return a new debugMessage so the added categories are only applied to the new debugMessage
+        return useDebugMessage(union(categoriesSet, isSet(moreCategories) ? moreCategories : new Set(moreCategories)));
     };
+    return debugMessage;
 }

package/utils/flattenPaths.js

@@ -1,6 +1,15 @@
 import isArray from "lodash-es/isArray";
 import isObject from "lodash-es/isObject";
 
+/**
+ * Turn an array or object into an array of path strings. Recurses for any found arrays or objects.
+ *
+ * Array indexes are wrapped in square brackets and object keys are prefixed with a period.
+ *
+ * @param {Array|Object} arrayOrObject array or object to flatten
+ * @param {string} currentPath current path, for recursion or as a starting point
+ * @returns {string[]} paths
+ */
 export function flattenPaths(arrayOrObject, currentPath = "") {
     // arrayOrObject keys or indexes values can be objects or arrays.
     // find all paths you could use lodash to "get()" to.
@@ -10,15 +19,14 @@ export function flattenPaths(arrayOrObject, currentPath = "") {
     const keysOrIndexes = isArray(arrayOrObject);
     const dotOrNot = currentPath ? "." : "";
     if (isObject(arrayOrObject)) {
-        Object.keys(arrayOrObject).forEach((key) => {
-            const value = arrayOrObject[key];
+        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}`));
             } else {
                 paths.push(`${currentPath}${keyPath}`);
             }
-        });
+        }
     } else {
         // values
         if (currentPath) {

package/utils/keyDiff.js

@@ -1,5 +1,29 @@
+import { flattenPaths } from "./flattenPaths.js";
 import { difference, intersection } from "./set.js";
 
+/**
+ * @typedef {object} KeyDiffOptions
+ * @property {boolean} [sameKeys=true]
+ * @property {boolean} [removedKeys=true]
+ * @property {boolean} [addedKeys=true]
+ */
+
+/**
+ * @typedef {object} KeyDiffResult
+ * @property {string[]} [sameKeys]
+ * @property {string[]} [removedKeys]
+ * @property {string[]} [addedKeys]
+ */
+
+/**
+ * Calculate the difference between two arrays of keys, in terms of what keys
+ *  are the same, what keys are removed, and what keys are added.
+ *
+ * @param {string[]} newKeys
+ * @param {string[]} oldKeys
+ * @param {KeyDiffOptions} [options]
+ * @returns {KeyDiffResult}
+ */
 export function keyDiff(newKeys, oldKeys, { sameKeys = true, removedKeys = true, addedKeys = true } = {}) {
     const newKeysSet = new Set(newKeys);
     const oldKeysSet = new Set(oldKeys);
@@ -15,3 +39,19 @@ export function keyDiff(newKeys, oldKeys, { sameKeys = true, removedKeys = true,
     }
     return returnValue;
 }
+
+/**
+ * Calculate the difference between two objects, in terms of what keys are the same,
+ * what keys are removed, and what keys are added. Keys are sourced deeply in the objects.
+ *
+ * @param {object} newObj
+ * @param {object} oldObj
+ * @param {KeyDiffOptions} [options]
+ * @returns {KeyDiffResult}
+ */
+export function keyDiffDeep(newObj, oldObj, options = {}) {
+    const newPaths = flattenPaths(newObj);
+    const oldPaths = flattenPaths(oldObj);
+    const result = keyDiff(newPaths, oldPaths, options);
+    return result;
+}

package/utils/lifecycleDebug.js

@@ -1,4 +1,7 @@
-import { useDebugMessage } from "./debugMessage";
+import { inspecttransformWalkFn, useDebugMessage } from "./debugMessage";
+import { keyDiffDeep } from "./keyDiff";
+import { transformWalk } from "./transformWalk";
+import { isEqual, partial } from "lodash-es";
 import {
     onActivated,
     onBeforeMount,
@@ -12,8 +15,71 @@ import {
     onServerPrefetch,
     onUnmounted,
     onUpdated,
+    unref,
 } from "vue";
 
+window.RH_DEBUG_SKIP_EMPTY_CHANGE_EFFECTS = true;
+
+export const customHandlers = {
+    onRenderTriggered: (debugMessage, e) => {
+        const newSeenObjects = new Map();
+        const newValue = transformWalk(e.newValue, partial(inspecttransformWalkFn, newSeenObjects));
+        const oldSeenObjects = new Map();
+        const oldValue = transformWalk(e.oldValue, partial(inspecttransformWalkFn, oldSeenObjects));
+        let keyDiffResults;
+        if (typeof newValue !== "object" || typeof oldValue !== "object") {
+            keyDiffResults = keyDiffDeep(newValue, oldValue);
+            keyDiffResults.changedKeys = new Set();
+            for (const key of keyDiffResults.sameKeys) {
+                // since it is a deep diff, object equality is fine to not trigger a change
+                if (newValue[key] !== oldValue[key]) {
+                    keyDiffResults.changedKeys.add(key);
+                }
+            }
+            delete keyDiffResults.sameKeys;
+            for (const key in keyDiffResults) {
+                if (keyDiffResults[key].size === 0) {
+                    delete keyDiffResults[key];
+                }
+            }
+            if (Object.keys(keyDiffResults).length === 0 && window.RH_DEBUG_SKIP_EMPTY_CHANGE_EFFECTS) {
+                return;
+            }
+        } else {
+            if (isEqual(newValue, oldValue)) {
+                return;
+            }
+        }
+        const debugArgs = [
+            {
+                effect: e.effect,
+                fn: e.effect.fn,
+                target: unref(e.target),
+                type: e.type,
+                key: e.key,
+                newValue,
+                oldValue,
+                oldTarget: unref(e.oldTarget),
+            },
+        ];
+        if (keyDiffResults) {
+            debugArgs.push(keyDiffResults);
+        }
+        debugMessage(...debugArgs);
+    },
+    onRenderTracked: (debugMessage, e) => {
+        debugMessage({
+            fn: e.effect.fn,
+            target: unref(e.target),
+            type: e.type,
+            key: e.key,
+        });
+    },
+};
+const defaultHandler = (debugMessage) => {
+    debugMessage();
+};
+
 /**
  * @param {string[]} categories
  */
@@ -44,10 +110,7 @@ export function useLifecycleDebug(categories, includes = [], excludes = []) {
         const myCategories = new Set(categories);
         myCategories.add("lifecycle");
         myCategories.add(key);
-        const eventString = `${key} called`;
         const debugMessage = useDebugMessage(myCategories);
-        lifeCycleFns[key](() => {
-            debugMessage(eventString);
-        });
+        lifeCycleFns[key](partial(customHandlers[key] || defaultHandler, debugMessage));
     }
 }

package/utils/transformWalk.js

@@ -0,0 +1,52 @@
+import { isSet } from "lodash-es";
+
+/**
+ * Recursively walks through an object's values and applies a transformation function to each value.
+ * The value recursed into is the transformed value, not the original value.
+ *
+ * @example
+ *
+ * const obj = {
+ *   a: 1,
+ *   b: {
+ *     c: 2,
+ *     d: [3, 4, { e: 5 }]
+ *   }
+ * };
+ *
+ * const transformed = transformWalk(obj, (key, value, path) => {
+ *   if (key === "e") {
+ *     return value * 2;
+ *   }
+ *   return value;
+ * });
+ * // transformed = {
+ * //   a: 1,
+ * //   b: {
+ * //     c: 2,
+ * //     d: [3, 4, { e: 10 }]
+ * //   }
+ * // }
+ *
+ * @param {*} obj The object to start walking from.
+ * @param {function} transformFn The function to transform each value.
+ * @param {string} path The path to the current value.
+ * @returns {*} The transformed initial value.
+ */
+export const transformWalk = (obj, transformFn, path = "") => {
+    if (typeof obj !== "object" || obj === null || isSet(obj)) {
+        // base case: obj is not an object or is null
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        // recursive case: obj is an array
+        return obj.map((item, index) => transformWalk(item, transformFn, path + `[${index}]`));
+    }
+    // recursive case: obj is an object
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const transformedValue = transformFn(key, value, path + `.${key}`);
+        result[key] = transformWalk(transformedValue, transformFn, path + `.${key}`);
+    }
+    return result;
+};