@arrai-innovations/reactive-helpers 3.2.0 → 3.3.0

package/package.json

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

package/use/index.js

@@ -1,4 +1,5 @@
 export * from "./cancellableIntent.js";
+export * from "./list.js";
 export * from "./listCalculated.js";
 export * from "./listFilter.js";
 export * from "./listInstance.js";

package/use/list.js

@@ -0,0 +1,103 @@
+import { effectScope, shallowReactive, shallowReadonly, toRef, watch } from "vue";
+import { useListCalculated } from "./listCalculated";
+import { useListInstance } from "./listInstance";
+import { useListRelated } from "./listRelated";
+import { useListSubscription } from "./listSubscription";
+
+// the big brother of useObject, managing a chain of useList* instances.
+export const useList = ({ props, functions }) => {
+    const managed = shallowReactive({
+        listInstance: null,
+        listSubscription: null,
+        listRelated: null,
+        listCalculated: null,
+    });
+    const es = effectScope();
+
+    managed.listInstance = useListInstance({
+        crudArgs: toRef(props, "crudArgs"),
+        functions,
+        retrieveArgs: toRef(props, "retrieveArgs"),
+        listArgs: toRef(props, "listArgs"),
+    });
+
+    const intentPropsWatch = () => {
+        es.run(() => {
+            let nextState = managed.listInstance?.state;
+            // true or false, having a key is intent to use
+            const hasIntendToList = "intendToList" in props;
+            if (hasIntendToList && !managed.listSubscription) {
+                managed.listSubscription = useListSubscription({
+                    listInstance: managed.listInstance,
+                });
+                managed.listSubscription.state.intendToList = toRef(props, "intendToList");
+            } else if (!hasIntendToList && managed.listSubscription) {
+                managed.listSubscription.effectScope.stop();
+                managed.listSubscription = null;
+            }
+            const hasRelatedObjectRules = "relatedObjectsRules" in props;
+            if (hasRelatedObjectRules && !managed.listRelated) {
+                nextState = managed.listSubscription?.state || nextState;
+                managed.listRelated = useListRelated({
+                    parentState: nextState,
+                    relatedObjectsRules: toRef(props, "relatedObjectsRules"),
+                });
+            } else if (!hasRelatedObjectRules && managed.listRelated) {
+                managed.listRelated.effectScope.stop();
+                managed.listRelated = null;
+            }
+            const hasCalculatedObjectRules = "calculatedObjectsRules" in props;
+            if (hasCalculatedObjectRules && !managed.listCalculated) {
+                nextState = managed.listRelated?.state || nextState;
+                managed.listCalculated = useListCalculated({
+                    parentState: nextState,
+                    calculatedObjectsRules: toRef(props, "calculatedObjectsRules"),
+                });
+            } else if (!hasCalculatedObjectRules && managed.listCalculated) {
+                managed.listCalculated.effectScope.stop();
+                managed.listCalculated = null;
+            }
+        });
+    };
+
+    let exposedState;
+
+    es.run(() => {
+        watch(
+            [
+                //
+                toRef(props, "intendToList"),
+                toRef(props, "relatedObjectsRules"),
+                toRef(props, "calculatedObjectsRules"),
+            ],
+            intentPropsWatch,
+            { immediate: true }
+        );
+        const getState = () =>
+            managed.listCalculated?.state ||
+            managed.listRelated?.state ||
+            managed.listSubscription?.state ||
+            managed.listInstance?.state;
+        // used as proxy to have the properties and not be settable, so we only have to override get
+        const proxyBase = shallowReadonly({
+            loading: null,
+            error: null,
+            errored: null,
+            objects: null,
+            order: null,
+            objectsInOrder: null,
+            running: null,
+        });
+        exposedState = new Proxy(proxyBase, {
+            get: (target, prop) => {
+                return Reflect.get(getState(), prop);
+            },
+        });
+    });
+
+    return {
+        managed: shallowReadonly(managed),
+        state: exposedState,
+        effectScope: es,
+    };
+};

package/use/listInstance.js

@@ -1,5 +1,6 @@
 import inspect from "browser-util-inspect";
 import { cloneDeep } from "lodash";
+import { isFunction } from "lodash";
 import { computed, effectScope, reactive } from "vue";
 import { addOrUpdateReactiveObject, assignReactiveObject } from "../utils/assignReactiveObject";
 import { getFakeId } from "../utils/getFakeId";
@@ -30,7 +31,7 @@ export function useListInstances(listInstanceArgs) {
     return instances;
 }
 
-export function useListInstance({ crudArgs, listArgs = {}, retrieveArgs = {} }) {
+export function useListInstance({ crudArgs, listArgs = {}, retrieveArgs = {}, functions = {} }) {
     // ### touching the _objectsMap or _objectsProxy directly will not trigger reactivity ###
     const _objectsMap = new Map();
     // ### touching the _objectsMap or _objectsProxy directly will not trigger reactivity ###
@@ -82,6 +83,13 @@ export function useListInstance({ crudArgs, listArgs = {}, retrieveArgs = {} })
     if (crudArgs) {
         addOrUpdateReactiveObject(state.crud.args, 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.`);
+        }
+    }
 
     const defaultPageCallback = (newObjects) => {
         newObjects.forEach((newObject) => {

package/use/object.js

@@ -5,7 +5,7 @@ import { useObjectRelated } from "./objectRelated";
 import { useObjectSubscription } from "./objectSubscription";
 
 // Manages a chain of useObject functions, based on existence of keys in props: intendToRetrieve, relatedObjectRules, calculatedObjectRules
-export const useObject = ({ props }) => {
+export const useObject = ({ props, functions }) => {
     const managed = shallowReactive({
         objectInstance: null,
         objectSubscription: null,
@@ -18,6 +18,7 @@ export const useObject = ({ props }) => {
         crudArgs: toRef(props, "crudArgs"),
         id: toRef(props, "id"),
         retrieveArgs: toRef(props, "retrieveArgs"),
+        functions,
     });
 
     const intentPropsWatch = () => {
@@ -86,8 +87,8 @@ export const useObject = ({ props }) => {
         });
         exposedState = new Proxy(proxyBase, {
             // get values from the current state
-            get(target, key) {
-                return Reflect.get(getState(), key);
+            get(target, prop) {
+                return Reflect.get(getState(), prop);
             },
         });
     });

package/use/objectInstance.js

@@ -1,4 +1,4 @@
-import { cloneDeep } from "lodash";
+import { cloneDeep, isFunction } from "lodash";
 import { effectScope, reactive } from "vue";
 import { addOrUpdateReactiveObject, assignReactiveObject } from "../utils/assignReactiveObject";
 
@@ -35,7 +35,7 @@ export function useObjectInstances(instanceArgs) {
     return instances;
 }
 
-export function useObjectInstance({ crudArgs, id, retrieveArgs }) {
+export function useObjectInstance({ crudArgs, id, retrieveArgs, functions = {} }) {
     const state = reactive({
         crud: {
             args: {},
@@ -58,6 +58,13 @@ export function useObjectInstance({ crudArgs, id, retrieveArgs }) {
     if (crudArgs) {
         addOrUpdateReactiveObject(state.crud.args, crudArgs);
     }
+    for (const [key, value] of Object.entries(functions)) {
+        if (isFunction(value) && key in state.crud) {
+            state[key] = value;
+        } else {
+            throw ObjectError(`Invalid function "${key}" for useObjectInstance: invalid key or not a function.`);
+        }
+    }
 
     // due to retrieve being called by `useCancelleableIntent`, if called manually then by the watch,
     //  it will run into the loading check. Instead, return the current retrieve promise if it exists.