@arrai-innovations/reactive-helpers 9.0.3 → 10.0.1

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

@@ -1,4 +1,4 @@
-import { useCancellableIntent } from "../../../use/index.js";
+import { useCancellableIntent } from "../../../use/cancellableIntent.js";
 import { CancellableResolvable } from "../crudPromise.js";
 import flushPromises from "flush-promises";
 import { nextTick, reactive, ref } from "vue";

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

@@ -9,12 +9,13 @@ afterAll(() => {
 });
 
 const fields = ["id", "__str__", "name"];
-describe.skip("use/listInstance.spec.js", function () {
+describe("use/listInstance.spec.js", function () {
     let useListInstance, ListError, useListInstances, globalList;
     beforeEach(async () => {
+        const listCrud = await import("../../../config/listCrud.js");
         const imported = await import("../../../use/listInstance");
         globalList = vi.fn();
-        imported.setListInstanceCrud({
+        listCrud.setListCrud({
             list: globalList,
             args: { stream: "test_stream" },
         });
@@ -143,8 +144,8 @@ describe.skip("use/listInstance.spec.js", function () {
             expect({ ...listInstance.state.objects }).toEqual({});
             globalList.mockImplementation(() => new Promise(() => {}));
 
-            listInstance.list();
-            await expect(listInstance.list()).rejects.toThrow(ListError);
+            const firstPromise = listInstance.list();
+            expect(listInstance.list()).toBe(firstPromise);
 
             expect(globalList).toHaveBeenCalledWith({
                 crudArgs: { stream: "test_stream" },

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/use/listSubscription.spec.js

@@ -21,6 +21,7 @@ describe("use/listSubscription.spec.js", function () {
         crudSubscribeResolvable = [];
         crudListResolvable.push(new CancellableResolvable());
         crudSubscribeResolvable.push(new CancellableResolvable());
+        const listCrudModule = await import("../../../config/listCrud.js");
         const listInstanceModule = await import("../../../use/listInstance");
         crudList = vi
             .fn()
@@ -30,8 +31,9 @@ describe("use/listSubscription.spec.js", function () {
                 crudListResolvable.push(newResolvable);
                 return newResolvable.promise;
             });
-        listInstanceModule.setListInstanceCrud({
+        listCrudModule.setListCrud({
             list: crudList,
+            subscribe: crudSubscribe,
             args: { stream: "test_stream" },
         });
         const listSubscriptionModule = await import("../../../use/listSubscription");
@@ -49,10 +51,6 @@ describe("use/listSubscription.spec.js", function () {
                 passedSubscriptionEventCallback = subscriptionEventCallback;
                 return newResolvable.promise;
             });
-        listSubscriptionModule.setListSubscriptionCrud({
-            subscribe: crudSubscribe,
-            args: { stream: "test_stream" },
-        });
 
         useListInstance = listInstanceModule.useListInstance;
         useListInstances = listInstanceModule.useListInstances;

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

@@ -1,7 +1,9 @@
-import { useListCalculated } from "./listCalculated.js";
-import { useListInstance } from "./listInstance.js";
-import { useListRelated } from "./listRelated.js";
-import { useListSubscription } from "./listSubscription.js";
+import { useListCalculated, listCalculatedFunctions } from "./listCalculated.js";
+import { useListFilter, listFilterFunctions } from "./listFilter.js";
+import { useListInstance, listInstanceFunctions } from "./listInstance.js";
+import { useListRelated, listRelatedFunctions } from "./listRelated.js";
+import { useListSort, listSortFunctions } from "./listSort.js";
+import { useListSubscription, listSubscriptionFunctions } from "./listSubscription.js";
 import { usePagedListInstance } from "./paginatedListInstance.js";
 import { effectScope, reactive, shallowReactive, shallowReadonly, toRef } from "vue";
 
@@ -14,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,
@@ -42,6 +44,7 @@ export const useList = ({ props, functions, paged = false, keepOldPages = false
             listInstance: managed.listInstance,
         });
         managed.listSubscription.state.intendToList = toRef(props, "intendToList");
+        managed.listSubscription.state.intendToSubscribe = toRef(props, "intendToSubscribe");
 
         managed.listRelated = useListRelated({
             parentState: managed.listSubscription.state,
@@ -52,6 +55,23 @@ export const useList = ({ props, functions, paged = false, keepOldPages = false
             parentState: managed.listRelated.state,
             calculatedObjectsRules: toRef(props, "calculatedObjectsRules"),
         });
+
+        managed.listFilter = useListFilter({
+            parentState: managed.listCalculated.state,
+            useTextSearch,
+            textSearchRules: toRef(props, "textSearchRules"),
+            textSearchValue: toRef(props, "textSearchValue"),
+            allowedValues: toRef(props, "allowedValues"),
+            excludedValues: toRef(props, "excludedValues"),
+            allowedFilter: toRef(props, "allowedFilter"),
+            excludedFilter: toRef(props, "excludedFilter"),
+        });
+
+        managed.listSort = useListSort({
+            parentState: managed.listFilter.state,
+            orderByRules: toRef(props, "orderByRules"),
+            sortThrottleWait: functions.sortThrottleWait,
+        });
     });
 
     const clearError = (error) => {
@@ -59,18 +79,32 @@ export const useList = ({ props, functions, paged = false, keepOldPages = false
         managed.listInstance.clearError(error);
     };
 
-    return reactive({
+    const returnObject = reactive({
         // we manage the keys on both of these, so hands off the root.
         managed: shallowReadonly(managed),
-        state: managed.listCalculated.state,
-        list: managed.listInstance.list,
-        addListObject: managed.listInstance.addListObject,
-        updateListObject: managed.listInstance.updateListObject,
-        deleteListObject: managed.listInstance.deleteListObject,
-        clearList: managed.listInstance.clearList,
-        clearError,
-        getFakeId: managed.listInstance.getFakeId,
-        defaultPageCallback: managed.listInstance.defaultPageCallback,
+        state: managed.listSort.state,
         effectScope: es,
     });
+    const handledDuplicateFunctions = {
+        clearError,
+    };
+    for (const [source, fnNames] of [
+        [managed.listInstance, listInstanceFunctions],
+        [managed.listSubscription, listSubscriptionFunctions],
+        [managed.listRelated, listRelatedFunctions],
+        [managed.listCalculated, listCalculatedFunctions],
+        [managed.listFilter, listFilterFunctions],
+        [managed.listSort, listSortFunctions],
+    ]) {
+        for (const fnName of fnNames) {
+            if (handledDuplicateFunctions[fnName]) {
+                continue;
+            }
+            returnObject[fnName] = source[fnName];
+        }
+    }
+    for (const [fnName, fn] of Object.entries(handledDuplicateFunctions)) {
+        returnObject[fnName] = fn;
+    }
+    return returnObject;
 };

package/use/listCalculated.js

@@ -13,6 +13,8 @@ export const listCalculatedStateKeys = [
     "calculatedObjectsWatchRunning",
 ];
 
+export const listCalculatedFunctions = [];
+
 export function useListCalculateds(instances, args) {
     for (const [key, value] of Object.entries(args)) {
         useListCalculated({
@@ -130,6 +132,7 @@ export function useListCalculated({ parentState, calculatedObjectsRules }) {
             ],
         });
 
+        state.calculatedRunning = toRef(watchesRunning.state, "running");
         state.running = computed(() => loadingCombine(watchesRunning.state.running, parentState.running));
 
         onScopeDispose(() => {

package/use/listFilter.js

@@ -1,10 +1,30 @@
 import { keyDiff } from "../utils/keyDiff.js";
+import { listCalculatedStateKeys } from "./listCalculated.js";
+import { listInstanceStateKeys } from "./listInstance.js";
+import { listRelatedStateKeys } from "./listRelated.js";
+import { listSubscriptionStateKeys } from "./listSubscription.js";
 import { useSearch } from "./search.js";
 import get from "lodash-es/get.js";
 import identity from "lodash-es/identity.js";
 import isEmpty from "lodash-es/isEmpty.js";
 import { computed, effectScope, onScopeDispose, reactive, toRef, watch, watchEffect } from "vue";
 
+export const listFilterStateKeys = [
+    "objectIndexes",
+    // override but not ours
+    // "objects",
+    "textSearchRules",
+    "textSearchValue",
+    "allowedValues",
+    "excludedValues",
+    "allowedFilter",
+    "excludedFilter",
+    "searched",
+    "searching",
+];
+
+export const listFilterFunctions = [];
+
 export function useListFilters(listFilterArgs, parentInstances) {
     const filters = {};
     for (const [key, value] of Object.entries(listFilterArgs)) {
@@ -32,6 +52,8 @@ export function useListFilter({
         excludedValues,
         allowedFilter,
         excludedFilter,
+        searched: undefined,
+        searching: undefined,
     });
 
     const es = effectScope();
@@ -39,6 +61,21 @@ export function useListFilter({
     let textSearchIndex;
 
     es.run(() => {
+        for (const key of listInstanceStateKeys) {
+            if (key === "objects") {
+                continue;
+            }
+            state[key] = toRef(parentState, key);
+        }
+        for (const key of listSubscriptionStateKeys) {
+            state[key] = toRef(parentState, key);
+        }
+        for (const key of listRelatedStateKeys) {
+            state[key] = toRef(parentState, key);
+        }
+        for (const key of listCalculatedStateKeys) {
+            state[key] = toRef(parentState, key);
+        }
         if (useTextSearch) {
             textSearchIndex = useSearch();
             textSearchIndex.state.search = toRef(state, "textSearchValue");
@@ -46,9 +83,11 @@ export function useListFilter({
             state.searching = toRef(textSearchIndex.state, "searching");
         }
 
+        // todo: computed is not the solution here for deep reactions
         state.objectsInOrder = computed(() => parentState.order.map((id) => state.objects[id]).filter(identity));
         state.order = computed(() => state.objectsInOrder.map((object) => `${object.id}`));
 
+        // todo: this huge watchEffect is fairly gross, but also doesn't watch deep similarly to computed
         watchEffect(() => {
             const allowedValuesEmpty = !state.allowedValues || isEmpty(state.allowedValues);
             const excludedValuesEmpty = !state.excludedValues || isEmpty(state.excludedValues);
@@ -104,6 +143,7 @@ export function useListFilter({
         if (useTextSearch) {
             const stopIndexWatch = {};
 
+            // todo: this huge watchEffect is fairly gross, but also doesn't watch deep similarly to computed
             watchEffect(() => {
                 const { removedKeys, addedKeys } = keyDiff(
                     Object.keys(parentState.objects),

package/use/listInstance.js

@@ -1,9 +1,8 @@
-import { addOrUpdateReactiveObject, assignReactiveObject } from "../utils/assignReactiveObject.js";
+import { getListCrud } from "../config/listCrud.js";
+import { assignReactiveObject } from "../utils/assignReactiveObject.js";
 import { getFakeId } from "../utils/getFakeId.js";
 import inspect from "browser-util-inspect";
-import cloneDeep from "lodash-es/cloneDeep.js";
-import isFunction from "lodash-es/isFunction.js";
-import { computed, effectScope, reactive, toRef, watchEffect } from "vue";
+import { computed, effectScope, reactive, toRef } from "vue";
 
 export class ListError extends Error {
     constructor(message, code) {
@@ -13,11 +12,6 @@ export class ListError extends Error {
     }
 }
 
-const defaultCrud = {
-    args: {},
-    list: undefined,
-};
-
 export const listInstanceStateKeys = [
     "crud",
     "retrieveArgs",
@@ -34,11 +28,39 @@ export const listInstanceStateKeys = [
     "perPage",
 ];
 
-export function setListInstanceCrud({ list, args = {} } = {}) {
-    defaultCrud.list = list;
-    Object.assign(defaultCrud.args, args);
-}
+export const listInstanceFunctions = [
+    "list",
+    "addListObject",
+    "updateListObject",
+    "deleteListObject",
+    "clearList",
+    "clearError",
+    "getFakeId",
+    "defaultPageCallback",
+    "pageCallback",
+];
 
+/**
+ * The configuration options used to create a list instance.
+ * @typedef {object} ListInstanceOptions
+ * @property {object} props - props passed to the component
+ * @property {object} props.retrieveArgs - the arguments passed to the server
+ * @property {object} props.listArgs - the arguments passed to the server
+ * @property {object} props.crudArgs - implementation specific arguments
+ * @property {object} functions - optional. default implementation are used as set by `setListCrud`.
+ * @property {Function} functions.list - provide the implementation for the list function
+ * @property {Function} functions.subscribe - provide the implementation for the subscribe function
+ * @property {boolean} keepOldPages - if true, pages will not be cleared when defaultPageCallback is called. default is false.
+ */
+
+/* eslint-disable jsdoc/check-types */
+// types valid for jsdoc-to-markdown, which uses the strict jsdoc.app. Object shorthand syntax doesn't work.
+/**
+ * A Vue composition function that creates multiple list instances, and returns them as an object.
+ * @param {Object.<string, ListInstanceOptions>} listInstanceArgs - each desired list instance options, keyed by an instance name.
+ * @returns {Object.<string, ListInstance>} - each list instance, keyed by the instance name.
+ */
+/* eslint-enable jsdoc/check-types */
 export function useListInstances(listInstanceArgs) {
     const instances = {};
     for (const [key, value] of Object.entries(listInstanceArgs)) {
@@ -47,6 +69,48 @@ export function useListInstances(listInstanceArgs) {
     return instances;
 }
 
+/**
+ * A reactive object that manages a list of objects, as returned by `useListInstance`.
+ * @typedef {object} ListInstanceState
+ * @property {object} crud - the crud functions
+ * @property {object} crud.args - the arguments passed to the crud functions
+ * @property {Function} crud.list - the list function
+ * @property {Function} crud.subscribe - the subscribe function
+ * @property {object} retrieveArgs - the arguments passed to the server
+ * @property {object} listArgs - the arguments passed to the server
+ * @property {Map} objects - the objects in the list
+ * @property {boolean} loading - true if the list is loading
+ * @property {boolean} errored - true if the list has errored
+ * @property {object} error - the error object
+ * @property {Array} objectsInOrder - the objects in the list in order
+ * @property {Array} order - the order of the objects in the list
+ * @property {number} totalRecords - the total number of records
+ * @property {number} totalPages - the total number of pages
+ * @property {number} perPage - the number of records per page
+ */
+
+/**
+ * @typedef {object} ListInstance
+ * @property {Function} list - subscribe to updates from the implementation
+ * @property {Function} addListObject - add an object to the list
+ * @property {Function} updateListObject - update an object in the list
+ * @property {Function} deleteListObject - delete an object from the list
+ * @property {Function} clearList - clear the list
+ * @property {Function} clearError - clear the error
+ * @property {Function} getFakeId - get a fake id
+ * @property {Function} defaultPageCallback - the default page callback
+ * @property {Function} pageCallback - the page callback
+ * @property {ListInstanceState} state - the list instance state
+ * @property {object} effectScope - a Vue effect scope
+ */
+
+/**
+ * `useListInstance` is a Vue composition function that manages a list of objects.
+ * It has the ability to retrieve the list from an implementation, or subscribe to updates from an implementation.
+ * It tracks the objects in the list, and their added order.
+ * @param {ListInstanceOptions} options - the options used to create the list instance
+ * @returns {ListInstance} - the list instance
+ */
 export function useListInstance({ props, functions = {}, keepOldPages = false }) {
     if (!props) {
         throw new ListError(`useListInstance requires props`);
@@ -98,20 +162,8 @@ export function useListInstance({ props, functions = {}, keepOldPages = false })
         error: null,
     });
     const es = effectScope();
-    watchEffect(() => {
-        // prevent linking of all instances to the same default .args object
-        Object.assign(state.crud, cloneDeep(defaultCrud));
-        if (props.crudArgs) {
-            addOrUpdateReactiveObject(state.crud.args, props.crudArgs);
-        }
-        for (const [key, value] of Object.entries(functions)) {
-            if (isFunction(value) && key in state.crud) {
-                state.crud[key] = value;
-            } else {
-                throw ListError(`Invalid function "${key}" for useListInstance: invalid key or not a function.`);
-            }
-        }
-    });
+
+    getListCrud(state.crud, { props, functions });
 
     const defaultPageCallback = (newObjects) => {
         // with keepOldPages, you are responsible for clearing the list as needed

package/use/listRelated.js

@@ -1,10 +1,13 @@
-import { keyDiff, loadingCombine } from "../utils/index.js";
+import { keyDiff } from "../utils/keyDiff.js";
+import { loadingCombine } from "../utils/loadingCombine.js";
 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";
 
@@ -15,6 +18,8 @@ export const listRelatedStateKeys = [
     "relatedObjectsParentStateObjectsWatchRunning",
 ];
 
+export const listRelatedFunctions = [];
+
 export function useListRelateds(instances, args) {
     for (const [key, value] of Object.entries(args)) {
         useListRelated({
@@ -52,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(
@@ -74,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];
+                        }
+                        if (!isEqual(value, relatedObjectsObject[addedRuleKey])) {
+                            relatedObjectsObject[addedRuleKey] = value;
+                        }
+                    };
+                    watch(
+                        [toRef(state.relatedObjectsRules, addedRuleKey), originalObjectRef],
+                        relatedObjectsObjectWatchFn,
+                        {
+                            deep: true,
+                            immediate: true,
                         }
-                        return ruleObjects[value];
-                    });
+                    );
                 }
             });
         }
@@ -130,6 +161,7 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
             ],
         });
 
+        state.relatedRunning = toRef(watchesRunning.state, "running");
         state.running = computed(() => loadingCombine(watchesRunning.state.running, parentState.running));
 
         onScopeDispose(() => {