@arrai-innovations/reactive-helpers 4.2.1 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arrai-innovations/reactive-helpers",
-    "version": "4.2.1",
+    "version": "5.0.0",
     "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
     "main": "index.js",
     "directories": {
@@ -12,9 +12,7 @@
         "test": "jest",
         "coverage": "npm run coverage:clean; npm test -- --coverage=true",
         "coverage:clean": "rm -rf coverage",
-        "_postinstall": "if [ \"$NODE_ENV\" != \"production\" ] && [ ./node_modules/.bin/is-ci ]; then ./node_modules/.bin/husky install; fi",
-        "prepublishOnly": "pinst --disable",
-        "postpublish": "pinst --enable"
+        "prepare": "husky install"
     },
     "repository": {
         "type": "git",
@@ -50,7 +48,6 @@
         "browser-util-inspect": "^0.2.0",
         "flexsearch": "^0.7.21",
         "husky": "^7.0.4",
-        "is-ci": "^3.0.1",
         "jest": "^27.5.1",
         "pinst": "^3.0.0",
         "vue-deepunref": "^1.0.1"

package/use/list.js

@@ -6,7 +6,7 @@ import { usePagedListInstance } from "./paginatedListInstance";
 import { effectScope, reactive, shallowReactive, shallowReadonly, toRef, watch } from "vue";
 
 // the big brother of useObject, managing a chain of useList* instances.
-export const useList = ({ props, functions, paged = false, passThroughPropertyNames = [] }) => {
+export const useList = ({ props, functions, paged = false, keepOldPages = false, passThroughPropertyNames = [] }) => {
     const managed = shallowReactive({
         listInstance: null,
         listSubscription: null,
@@ -20,6 +20,7 @@ export const useList = ({ props, functions, paged = false, passThroughPropertyNa
         functions,
         retrieveArgs: toRef(props, "retrieveArgs"),
         listArgs: toRef(props, "listArgs"),
+        keepOldPages,
     });
 
     const intentPropsWatch = () => {

package/use/listInstance.js

@@ -33,7 +33,7 @@ export function useListInstances(listInstanceArgs) {
 
 export function useListInstance({ crudArgs, listArgs = {}, retrieveArgs = {}, functions = {} }) {
     // ### touching the _objectsMap or _objectsProxy directly will not trigger reactivity ###
-    const _objectsMap = new Map();
+    const _objectsMap = new Map(); // maps are ordered, if you don't clear lists, you need to insert pages in order.
     // ### touching the _objectsMap or _objectsProxy directly will not trigger reactivity ###
     const _objectsProxy = new Proxy(_objectsMap, {
         get(target, prop) {

package/use/object.js

@@ -2,9 +2,9 @@ import { useObjectCalculated } from "./objectCalculated";
 import { useObjectInstance } from "./objectInstance";
 import { useObjectRelated } from "./objectRelated";
 import { useObjectSubscription } from "./objectSubscription";
-import { effectScope, reactive, shallowReactive, shallowReadonly, toRef, watch } from "vue";
+import { reactive, shallowReactive, shallowReadonly, toRef } from "vue";
 
-// Manages a chain of useObject functions, based on existence of keys in props: intendToRetrieve, relatedObjectRules, calculatedObjectRules
+// Manages a chain of useObject* functions
 export const useObject = ({ props, functions }) => {
     const managed = shallowReactive({
         objectInstance: null,
@@ -12,99 +12,28 @@ export const useObject = ({ props, functions }) => {
         objectRelated: null,
         objectCalculated: null,
     });
-    const es = effectScope();
 
     managed.objectInstance = useObjectInstance({
-        crudArgs: toRef(props, "crudArgs"),
-        id: toRef(props, "id"),
-        retrieveArgs: toRef(props, "retrieveArgs"),
+        props,
         functions,
     });
-
-    const intentPropsWatch = () => {
-        es.run(() => {
-            let nextState = managed.objectInstance?.state;
-            // true or false, having a key is intent to use
-            const hasIntendToRetrieve = "intendToRetrieve" in props;
-            if (hasIntendToRetrieve && !managed.objectSubscription) {
-                managed.objectSubscription = useObjectSubscription({
-                    objectInstance: managed.objectInstance,
-                });
-                managed.objectSubscription.state.intendToRetrieve = toRef(props, "intendToRetrieve");
-            } else if (!hasIntendToRetrieve && managed.objectSubscription) {
-                managed.objectSubscription.effectScope.stop();
-                managed.objectSubscription = null;
-            }
-            const hasRelatedObjectRules = "relatedObjectRules" in props;
-            if (hasRelatedObjectRules && !managed.objectRelated) {
-                nextState = managed.objectSubscription?.state || nextState;
-                managed.objectRelated = useObjectRelated({
-                    parentState: nextState,
-                    relatedObjectRules: toRef(props, "relatedObjectRules"),
-                });
-            } else if (!hasRelatedObjectRules && managed.objectRelated) {
-                managed.objectRelated.effectScope.stop();
-                managed.objectRelated = null;
-            }
-            const hasCalculatedObjectRules = "calculatedObjectRules" in props;
-            if (hasCalculatedObjectRules && !managed.objectCalculated) {
-                nextState = managed.objectRelated?.state || nextState;
-                managed.objectCalculated = useObjectCalculated({
-                    parentState: nextState,
-                    calculatedObjectRules: toRef(props, "calculatedObjectRules"),
-                });
-            } else if (!hasCalculatedObjectRules && managed.objectCalculated) {
-                managed.objectCalculated.effectScope.stop();
-                managed.objectCalculated = null;
-            }
-        });
-    };
-
-    const exposedState = reactive({});
-
-    es.run(() => {
-        watch(
-            [
-                toRef(props, "intendToRetrieve"),
-                toRef(props, "relatedObjectRules"),
-                toRef(props, "calculatedObjectRules"),
-            ],
-            intentPropsWatch,
-            { immediate: true }
-        );
-
-        const propertiesToRelay = [
-            "loading",
-            "error",
-            "errored",
-            "object",
-            "running",
-            "relatedObject",
-            "calculatedObject",
-        ];
-        watch(
-            () =>
-                managed.objectCalculated?.state ||
-                managed.objectRelated?.state ||
-                managed.objectSubscription?.state ||
-                managed.objectInstance.state,
-            (newState, oldState) => {
-                if (newState !== oldState && newState) {
-                    propertiesToRelay.forEach((x) => {
-                        exposedState[x] = toRef(newState, x);
-                    });
-                }
-            },
-            {
-                immediate: true,
-            }
-        );
+    managed.objectSubscription = useObjectSubscription({
+        objectInstance: managed.objectInstance,
+        props: reactive({
+            intendToSubscribe: toRef(props, "intendToSubscribe"),
+            intendToRetrieve: toRef(props, "intendToRetrieve"),
+        }),
     });
-
-    return {
-        // we manage the keys on both of these, so hands off the root.
+    managed.objectRelated = useObjectRelated({
+        parentState: managed.objectSubscription.state,
+        relatedObjectRules: toRef(props, "relatedObjectRules"),
+    });
+    managed.objectCalculated = useObjectCalculated({
+        parentState: managed.objectRelated.state,
+        calculatedObjectRules: toRef(props, "calculatedObjectRules"),
+    });
+    return shallowReactive({
         managed: shallowReadonly(managed),
-        state: shallowReadonly(exposedState),
-        effectScope: es,
-    };
+        state: reactive(managed.objectCalculated.state),
+    });
 };

package/use/objectCalculated.js

@@ -17,7 +17,30 @@ export function useObjectCalculated({
     parentState,
     calculatedObjectRules,
     calculatedObjectPropertyName = "calculatedObject", // NOT REACTIVE
-    passThroughPropertyNames = ["relatedObject"], // NOT REACTIVE
+    passThroughPropertyNames = [
+        // instance
+        "crud",
+        "deleted",
+        "error",
+        "errored",
+        "id",
+        "loading",
+        "object",
+        "retrieveArgs",
+        // subscription
+        "intendToRetrieve",
+        "intendToSubscribe",
+        "subscribed",
+        "subscriptionError",
+        "subscriptionErrored",
+        "subscriptionLoading",
+        // related
+        "relatedObject",
+        "relatedObjectObjects",
+        "relatedObjectRules",
+        "relatedObjectWatchRunning",
+        "relatedRunning",
+    ], // NOT REACTIVE
 }) {
     const state = reactive({
         calculatedObjectRules,
@@ -36,11 +59,6 @@ export function useObjectCalculated({
     const es = effectScope();
 
     es.run(() => {
-        state.loading = toRef(parentState, "loading");
-        state.error = toRef(parentState, "error");
-        state.errored = toRef(parentState, "errored");
-        state.deleted = toRef(parentState, "deleted");
-        state.object = toRef(parentState, "object");
         state[copn] = toRef(state, "calculatedObjectObjects");
         for (let key of passThroughPropertyNames) {
             state[key] = toRef(parentState, key);
@@ -91,7 +109,8 @@ export function useObjectCalculated({
             ],
         });
 
-        state.running = computed(() => loadingCombine(watchesRunning.state.running, parentState.running));
+        state.calculatedRunning = toRef(watchesRunning.state, "running");
+        state.running = computed(() => loadingCombine(watchesRunning.state.running, parentState.relatedRunning));
 
         onScopeDispose(() => {
             for (const key in calculatedObjectEffectScopes) {

package/use/objectInstance.js

@@ -1,7 +1,7 @@
-import { addOrUpdateReactiveObject, assignReactiveObject } from "../utils/assignReactiveObject";
+import { addOrUpdateReactiveObject, assignReactiveObject } from "../utils";
 import cloneDeep from "lodash-es/cloneDeep";
 import isFunction from "lodash-es/isFunction";
-import { effectScope, reactive } from "vue";
+import { reactive, shallowReactive, toRef } from "vue";
 
 export class ObjectError extends Error {
     constructor(message) {
@@ -36,7 +36,7 @@ export function useObjectInstances(instanceArgs) {
     return instances;
 }
 
-export function useObjectInstance({ crudArgs, id, retrieveArgs, functions = {} }) {
+export function useObjectInstance({ props, functions = {} }) {
     const state = reactive({
         crud: {
             args: {},
@@ -47,8 +47,8 @@ export function useObjectInstance({ crudArgs, id, retrieveArgs, functions = {} }
             delete: undefined,
         },
         object: {},
-        id,
-        retrieveArgs,
+        id: toRef(props, "id"),
+        retrieveArgs: toRef(props, "retrieveArgs"),
         loading: undefined,
         errored: false,
         error: null,
@@ -56,8 +56,8 @@ export function useObjectInstance({ crudArgs, id, retrieveArgs, functions = {} }
     });
     // prevent linking of all instances to the same default .args object
     Object.assign(state.crud, cloneDeep(defaultCrud));
-    if (crudArgs) {
-        addOrUpdateReactiveObject(state.crud.args, crudArgs);
+    if (props.crudArgs) {
+        addOrUpdateReactiveObject(state.crud.args, props.crudArgs);
     }
     for (const [key, value] of Object.entries(functions)) {
         if (isFunction(value) && key in state.crud) {
@@ -222,12 +222,7 @@ export function useObjectInstance({ crudArgs, id, retrieveArgs, functions = {} }
         state.error = null;
     }
 
-    const es = effectScope();
-
-    // we could have effects? let's keep the interface to keep our options open to add without major changes.
-    es.run(() => {});
-
-    return {
+    return shallowReactive({
         state,
         retrieve,
         create,
@@ -235,6 +230,5 @@ export function useObjectInstance({ crudArgs, id, retrieveArgs, functions = {} }
         patch,
         delete: deleteFn,
         clearError,
-        effectScope: es,
-    };
+    });
 }

package/use/objectRelated.js

@@ -1,4 +1,4 @@
-import { keyDiff, loadingCombine } from "../utils";
+import { keyDiff } from "../utils";
 import { useWatchesRunning } from "./watchesRunning";
 import get from "lodash-es/get";
 import isArray from "lodash-es/isArray";
@@ -20,7 +20,24 @@ export function useObjectRelated({
     parentState,
     relatedObjectRules,
     relatedObjectPropertyName = "relatedObject", // NOT REACTIVE
-    passThroughPropertyNames = ["calculatedObject"], // NOT REACTIVE
+    passThroughPropertyNames = [
+        // instance
+        "crud",
+        "deleted",
+        "error",
+        "errored",
+        "id",
+        "loading",
+        "object",
+        "retrieveArgs",
+        // subscription
+        "intendToRetrieve",
+        "intendToSubscribe",
+        "subscribed",
+        "subscriptionError",
+        "subscriptionErrored",
+        "subscriptionLoading",
+    ], // NOT REACTIVE
 }) {
     const state = reactive({
         relatedObjectRules,
@@ -38,11 +55,6 @@ export function useObjectRelated({
     const es = effectScope();
 
     es.run(() => {
-        state.loading = toRef(parentState, "loading");
-        state.error = toRef(parentState, "error");
-        state.errored = toRef(parentState, "errored");
-        state.deleted = toRef(parentState, "deleted");
-        state.object = toRef(parentState, "object");
         state[ropn] = toRef(state, "relatedObjectObjects");
         for (let key of passThroughPropertyNames) {
             state[key] = toRef(parentState, key);
@@ -98,7 +110,7 @@ export function useObjectRelated({
             ],
         });
 
-        state.running = computed(() => loadingCombine(watchesRunning.state.running, parentState.running));
+        state.relatedRunning = toRef(watchesRunning.state, "running");
 
         onScopeDispose(() => {
             for (const key in relatedObjectEffectScopes) {

package/use/objectSubscription.js

@@ -1,7 +1,7 @@
 import { assignReactiveObject, loadingCombine } from "../utils";
 import { useCancellableIntent } from "./cancellableIntent";
 import { useObjectInstance } from "./objectInstance";
-import { computed, effectScope, reactive, toRef } from "vue";
+import { computed, effectScope, reactive, shallowReactive, toRef } from "vue";
 
 export class ObjectSubscriptionError extends Error {
     constructor(message) {
@@ -26,18 +26,33 @@ export function useObjectSubscriptions(subscriptionArgs) {
     return subscriptions;
 }
 
-export function useObjectSubscription({ objectInstance, crudArgs, id, retrieveArgs }) {
-    if (retrieveArgs && objectInstance) {
+export function useObjectSubscription({
+    objectInstance,
+    props,
+    passThroughPropertyNames = [
+        // instance
+        "crud",
+        "deleted",
+        // "error",
+        // "errored",
+        "id",
+        // "loading",
+        "object",
+        "retrieveArgs",
+    ],
+}) {
+    if (props?.retrieveArgs && objectInstance) {
         throw new ObjectSubscriptionError(
             "Cannot use retrieveArgs and objectInstance together, set retrieveArgs on objectInstance instead"
         );
     }
     if (!objectInstance) {
-        objectInstance = useObjectInstance({ crudArgs, id, retrieveArgs });
+        objectInstance = useObjectInstance({ props });
     }
     if (!objectInstance.state.crud.subscribe) {
         objectInstance.state.crud.subscribe = defaultCrud.subscribe;
     }
+    const parentState = objectInstance.state;
     const state = reactive({
         subscriptionLoading: undefined,
         subscriptionErrored: false,
@@ -46,16 +61,19 @@ export function useObjectSubscription({ objectInstance, crudArgs, id, retrieveAr
         intendToSubscribe: false,
         intendToRetrieve: false,
     });
+    if ("intendToRetrieve" in props) {
+        state.intendToRetrieve = toRef(props, "intendToRetrieve");
+    }
 
     let subscribeIntent, retrieveIntent;
 
     function updateFromSubscription(data) {
-        assignReactiveObject(state.object, data);
+        assignReactiveObject(parentState.object, data);
     }
 
     function deleteFromSubscription() {
         state.deleted = true;
-        assignReactiveObject(state.object, {});
+        assignReactiveObject(parentState.object, {});
     }
 
     function publicSubscribe({ retrieve = true } = {}) {
@@ -82,9 +100,9 @@ export function useObjectSubscription({ objectInstance, crudArgs, id, retrieveAr
         state.subscriptionErrored = false;
         state.subscriptionError = null;
         let subscribePromise;
-        subscribePromise = objectInstance.state.crud.subscribe({
-            crudArgs: objectInstance.state.crud.args,
-            id: objectInstance.state.id,
+        subscribePromise = parentState.crud.subscribe({
+            crudArgs: parentState.crud.args,
+            id: parentState.id,
             retrieveArgs: state.retrieveArgs,
             callback: (data, action) => {
                 if (action === "delete") {
@@ -145,20 +163,20 @@ export function useObjectSubscription({ objectInstance, crudArgs, id, retrieveAr
     const es = effectScope();
 
     es.run(() => {
-        state.loading = computed(() => loadingCombine(objectInstance.state.loading, state.subscriptionLoading));
-        state.errored = computed(() => objectInstance.state.errored || state.subscriptionErrored);
-        state.error = computed(() => objectInstance.state.error || state.subscriptionError);
+        state.loading = computed(() => loadingCombine(parentState.loading, state.subscriptionLoading));
+        state.errored = computed(() => parentState.errored || state.subscriptionErrored);
+        state.error = computed(() => parentState.error || state.subscriptionError);
 
-        state.retrieveArgs = computed(() => objectInstance.state.retrieveArgs);
-        state.object = toRef(objectInstance.state, "object");
-        state.deleted = toRef(objectInstance.state, "deleted");
+        for (const key of passThroughPropertyNames) {
+            state[key] = toRef(parentState, key);
+        }
 
         subscribeIntent = useCancellableIntent({
             awaitableWithCancel: subscribe,
             watchArguments: reactive({
                 intendToSubscribe: toRef(state, "intendToSubscribe"),
-                listArgs: toRef(objectInstance.state, "id"),
-                retrieveArgs: toRef(objectInstance.state, "retrieveArgs"),
+                listArgs: toRef(parentState, "id"),
+                retrieveArgs: toRef(parentState, "retrieveArgs"),
             }),
             clearActiveOnResolved: false,
         });
@@ -167,13 +185,13 @@ export function useObjectSubscription({ objectInstance, crudArgs, id, retrieveAr
             awaitableWithCancel: objectInstance.retrieve,
             watchArguments: reactive({
                 intendToSubscribe: toRef(state, "intendToRetrieve"),
-                listArgs: toRef(objectInstance.state, "id"),
-                retrieveArgs: toRef(objectInstance.state, "retrieveArgs"),
+                listArgs: toRef(parentState, "id"),
+                retrieveArgs: toRef(parentState, "retrieveArgs"),
             }),
         });
     });
 
-    return {
+    return shallowReactive({
         state,
         objectInstance,
         subscribeIntent,
@@ -184,5 +202,5 @@ export function useObjectSubscription({ objectInstance, crudArgs, id, retrieveAr
         deleteFromSubscription,
         clearError,
         effectScope: es,
-    };
+    });
 }

package/use/paginatedListInstance.js

@@ -1,6 +1,6 @@
 import { useListInstance } from "./listInstance";
 
-export function usePagedListInstance(useListInstanceArgs) {
+export function usePagedListInstance({ keepOldPages = false, ...useListInstanceArgs }) {
     const listInstance = useListInstance(useListInstanceArgs);
 
     listInstance.state.totalRecords = 0;
@@ -8,8 +8,11 @@ export function usePagedListInstance(useListInstanceArgs) {
     listInstance.state.perPage = 0;
 
     listInstance.pageCallback = (newObjects, { totalRecords, totalPages, perPage }) => {
-        // display one page at a time, clear the list
-        listInstance.clearList();
+        // with keepOldPages, you are responsible for clearing the list as needed
+        if (!keepOldPages) {
+            // display one page at a time, clear the list
+            listInstance.clearList();
+        }
 
         listInstance.defaultPageCallback(newObjects);
         if (totalRecords !== undefined) {

package/utils/debugWatch.js

@@ -0,0 +1,29 @@
+import { keyDiff } from "./keyDiff";
+import isEqual from "lodash-es/isEqual";
+import { watch } from "vue";
+import { deepUnref } from "vue-deepunref";
+
+export const debugWatch = (target, name) => {
+    return watch(
+        target,
+        (newState, oldState) => {
+            console.log(`Watch triggered ${name}`);
+            const diff = keyDiff(Object.keys(newState || {}), Object.keys(oldState || {}));
+            for (const addedKey of Array.from(diff.addedKeys)) {
+                console.log(`${name} added key ${addedKey}`, deepUnref(newState[addedKey]));
+            }
+            for (const removedKey of Array.from(diff.removedKeys)) {
+                console.log(`${name} removed key ${removedKey}`, deepUnref(oldState[removedKey]));
+            }
+            for (const sameKey of Array.from(diff.sameKeys)) {
+                if (!isEqual(deepUnref(newState[sameKey]), deepUnref(oldState[sameKey]))) {
+                    console.log(`${name} same key ${sameKey}`, newState[sameKey], oldState[sameKey]);
+                }
+            }
+        },
+        {
+            deep: true,
+            immediate: true,
+        }
+    );
+};

package/utils/index.js

@@ -1,4 +1,5 @@
 export * from "./assignReactiveObject";
+export * from "./debugWatch";
 export * from "./flattenPaths";
 export * from "./getFakeId";
 export * from "./keyDiff";