@arrai-innovations/reactive-helpers 11.4.2 → 13.0.0

package/use/listRelated.js

@@ -20,6 +20,83 @@ import isEmpty from "lodash-es/isEmpty.js";
 import isUndefined from "lodash-es/isUndefined.js";
 import { computed, effectScope, onScopeDispose, reactive, ref, toRef, unref, watch } from "vue";
 
+/**
+ * Vue Composition API composable function for managing relationships among objects in a list.
+ * It enables linking objects based on predefined rules and dynamically adjusts as the underlying data changes.
+ *
+ * @module use/listRelated.js
+ */
+
+// todo: pkKey is misnamed, it should be fkKey... this will be a major breaking change
+/**
+ * The rule for defining relationships for objects in a list.
+ *
+ * @typedef {object} ListRelatedRule
+ * @property {string} pkKey - Specifies the foreign key used to link objects across lists. Planned to be renamed to
+ *  'fkKey' to better reflect its usage.
+ * @property {string[]} order - Specifies the order in which related objects should be sorted, if applicable.
+ * @property {import('./listInstance.js').ObjectsById} objects - The objects that can be related based on the foreign key.
+ */
+
+/**
+ * The rules for defining relationships among objects in a list.
+ *
+ * @typedef {import('vue').UnwrapNestedRefs<{
+ *     [rule: string]: ListRelatedRule,
+ * }>} ListRelatedRules
+ */
+
+/**
+ * Represents the internal state used by the list related composition function. It manages and computes the relationships
+ * between objects based on specified rules, providing real-time updates to related objects as the parent state changes.
+ *
+ * @typedef {object} ListRelatedRawState
+ * @property {{
+ *     [id: string]: {
+ *         [rule: string]: import('vue').ComputedRef<any>,
+ *     },
+ * }} relatedObjects - Stores computed references to related objects, allowing for dynamic access based on object ID and specific rules.
+ * @property {ListRelatedRules} relatedObjectsRules - Defines the rules for establishing relationships, such as foreign key links and sorting orders.
+ * @property {{
+ *     [id: string]: {
+ *         [rule: string]: import('vue').ComputedRef<[object, string]>,
+ *     },
+ * }} objAndKeyForIdAndRule - Maps each object ID and rule to a tuple consisting of the related object and its respective key, facilitating direct data manipulation.
+ * @property {{
+ *     [id: string]: {
+ *         [rule: string]: import('vue').ComputedRef<any>,
+ *     },
+ * }} fkForIdAndRule - Maintains computed references to the foreign keys for each object ID and rule, crucial for navigating complex data relationships.
+ * @property {boolean} relatedObjectsParentStateObjectsWatchRunning - Flags whether the watch on parent state objects is currently active, ensuring updates trigger as needed.
+ * @property {boolean} relatedObjectsWatchRunning - Indicates if watches on the related objects themselves are active, managing updates efficiently.
+ * @property {boolean} relatedRunning - Signals whether any computations related to object relationships are currently in progress.
+ * @property {import('vue').Ref<boolean>} running - General flag that indicates if the list-related logic is processing, used to manage UI feedback or prevent concurrent operations.
+ */
+
+/**
+ * The raw state properties for a parent of a list related property.
+ *
+ * @typedef {(
+ *     import('./listInstance.js').ListInstanceRawState &
+ *     Partial<import('./listSubscription.js').ListSubscriptionRawState>
+ * )} ListRelatedParentRawState
+ */
+
+/**
+ * The type for a parentState object.
+ *
+ * @typedef {import('vue').UnwrapNestedRefs<ListRelatedParentRawState>} ListRelatedParentState
+ */
+
+/**
+ * The state for a list related property.
+ *
+ * @typedef {import('vue').UnwrapNestedRefs<
+ *     ListRelatedParentRawState &
+ *     ListRelatedRawState
+ * >} ListRelatedState
+ */
+
 const parentStateKeys = difference(
     new Set([
         ...listInstanceStateKeys,
@@ -32,39 +109,140 @@ const parentStateKeys = difference(
     new Set(listRelatedStateKeys)
 );
 
-export function useListRelateds(instances, args) {
-    for (const [key, value] of Object.entries(args)) {
-        useListRelated({
-            parentState: instances[key].state,
-            ...value,
-        });
+/**
+ * The options for the list related composition function.
+ *
+ * @typedef {object} ListRelatedOptions
+ * @property {ListRelatedParentState} parentState - The parent state object.
+ * @property {import('vue').Ref<ListRelatedRules>} relatedObjectsRules - The rules for the related objects.
+ */
+
+/**
+ * The properties for the list related composition function.
+ *
+ * @typedef {object} ListRelatedProperties
+ * @property {ListRelatedState} state - The state for the list related property.
+ * @property {ListRelatedParentState} parentState - The parent state object.
+ * @property {import('./watchesRunning.js').WatchesRunning} watchesRunning - The watches running instance.
+ * @property {import('vue').EffectScope} effectScope - The effect scope for the list related property.
+ */
+
+// if we provided functions, we would add a typedef and mix them into ListRelated
+
+/**
+ * An instance of `useListRelated`.
+ *
+ * @typedef {ListRelatedProperties} ListRelated
+ */
+
+/**
+ * Creates and manages multiple instances of list-related properties, linking each to corresponding parent instances
+ * based on provided configuration.
+ *
+ * @param {{
+ *     [key: string]: ListRelatedOptions
+ * }} listRelatedArgs - The options for the list related properties.
+ * @returns {{[key: string]: ListRelated}} - The instances of the list related properties.
+ */
+export function useListRelateds(listRelatedArgs) {
+    /** @type {{[key: string]: ListRelated}} */
+    const relateds = {};
+    for (const [key, value] of Object.entries(listRelatedArgs)) {
+        relateds[key] = useListRelated(value);
     }
+    return relateds;
 }
 
+/**
+ * Initializes and returns an instance of a related objects manager. This function sets up reactive states
+ * and computations that dynamically adjust as the parent list's state changes. It uses defined rules
+ * for object relationships to compute and update related objects in real-time, ensuring that changes in the parent
+ * state are reflected in the relationships defined by the rules.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useListInstance, useListRelated } from "@arrai-innovations/reactive-helpers";
+ * import { reactive, toRef } from "vue";
+ *
+ * const props = defineProps({
+ *     someListFilter: {
+ *         type: String,
+ *         default: "",
+ *         description: "The filter to apply to the list.",
+ *     },
+ *     objects: {
+ *         type: Object,
+ *         default: () => ({}),
+ *         description: "The objects to relate to.",
+ *     },
+ *     order: {
+ *          type: Array,
+ *          default: () => [],
+ *          description: "The order of the list.",
+ *     },
+ * });
+ *
+ * const listInstanceProps = reactive({
+ *     crudArgs: {
+ *         // whatever arguments are required for your configured list crud function to get the right endpoint
+ *     },
+ *     listArgs: {
+ *         // whatever arguments are required for your configured list function to get the right list
+ *         someListFilter: toRef(props, "someListFilter"),
+ *     },
+ *     retrieveArgs: {
+ *         // whatever arguments are required for your configured list function to get items back looking as expected
+ *     },
+ *     intendToList: false,
+ * });
+ * listInstanceProps.intendToList = computed(()=> !!props.someListFilter);
+ * const listInstance = useListInstance({ props: listInstanceProps });
+ * const listRelatedProps = reactive({
+ *     parentState: listInstance.state, // reactive-to-reactive so no need for toRef
+ *     relatedObjectsRules: {
+ *         someRule: {
+ *             // this can point to a key or an array of keys to relate to
+ *             pkKey: "dot.separated.key.to.id.on.an.listInstance.object",
+ *             objects: toRef(props, "objects"),
+ *             order: toRef(props, "order"),
+ *         },
+ *     },
+ * });
+ * const listRelated = useListRelated(listRelatedProps);
+ * </script>
+ * <template>
+ *     <ul>
+ *         <!-- reactive list of objects, re-retrieving the list as someListFilter changes. -->
+ *         <li v-for="obj in listInstance.state.objectsInOrder">
+ *             {{ obj }}
+ *             <div>
+ *                 <!-- the related object or objects based on the rule -->
+ *                 {{ listRelated.state.relatedObjects[obj.id].someRule }}
+ *             </div>
+ *         </li>
+ *     </ul>
+ * </template>
+ * ```
+ *
+ * @param {ListRelatedOptions} options -  The configuration options including the parent state and rules for related
+ *  objects.
+ * @returns {ListRelated} - A reactive instance that manages related objects, providing real-time updates and
+ * maintaining the integrity of object relationships as per the specified rules.
+ */
 export function useListRelated({ parentState, relatedObjectsRules }) {
-    const state = reactive({
-        relatedObjectsRules: relatedObjectsRules,
-        relatedObjects: {
-            // id: {
-            //     rule: list of objects or single object,
-            // },
-        },
-        objAndKeyForIdAndRule: {
-            // id: {
-            //     rule: {
-            //         obj: object,
-            //         key: string,
-            //     },
-            // },
-        },
-        fkForIdAndRule: {
-            // id: {
-            //     rule: list of ids or single id,
-            // },
-        },
-        relatedObjectsParentStateObjectsWatchRunning: false,
-        relatedObjectsWatchRunning: false,
-    });
+    /** @type {ListRelatedState} */
+    // @ts-ignore - we'll add the missing properties later, taking refs from parentState
+    const state = reactive(
+        /** @type {ListRelatedRawState} */ {
+            relatedObjectsRules,
+            relatedObjects: {},
+            objAndKeyForIdAndRule: {},
+            fkForIdAndRule: {},
+            relatedObjectsParentStateObjectsWatchRunning: false,
+            relatedObjectsWatchRunning: false,
+        }
+    );
     const relatedObjectsEffectScopes = {};
 
     function parentStateObjectsWatch() {
@@ -89,6 +267,55 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
         state.relatedObjectsParentStateObjectsWatchRunning = false;
     }
 
+    function applyRuleToObject(objectKey, ruleKey, originalObjectRef, relatedObjectRef) {
+        const rule = toRef(state.relatedObjectsRules, ruleKey);
+        state.objAndKeyForIdAndRule[objectKey][ruleKey] = computed(() => {
+            const rulePkKey = unref(rule).pkKey || ruleKey;
+            const object = unref(originalObjectRef);
+            const relatedObject = unref(relatedObjectRef);
+            return getObjectRelatedByKey(object, relatedObject, rulePkKey);
+        });
+
+        state.fkForIdAndRule[objectKey][ruleKey] = computed(() =>
+            computeForeignKey(ruleKey, objectKey, rule, relatedObjectRef)
+        );
+
+        state.relatedObjects[objectKey][ruleKey] = computed(() => {
+            const value = unref(state.fkForIdAndRule[objectKey][ruleKey]);
+            const objects = unref(rule).objects;
+            if (isArray(value)) {
+                return value.map((e) => objects[e]).filter(identity);
+            }
+            return objects[value];
+        });
+    }
+
+    function computeForeignKey(ruleKey, objectKey, rule, relatedObjectRef) {
+        const ruleOrder = unref(rule).order;
+        const relatedObject = unref(relatedObjectRef);
+        const [objectForGet, key] = unref(state.objAndKeyForIdAndRule[objectKey][ruleKey]);
+        let value = get(objectForGet, key);
+        if (objectForGet === relatedObject && isUndefined(value)) {
+            // Handle nested arrays
+            const firstLevelKey = key.split(".")[0];
+            const firstLevelItem = get(relatedObject, firstLevelKey);
+            if (isArray(firstLevelItem)) {
+                const restOfKey = key.slice(firstLevelKey.length + 1);
+                value = firstLevelItem.map((e) => get(e, restOfKey)).flat();
+            }
+        }
+        if (isArray(value) && 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;
+            });
+        }
+        return value;
+    }
+
     function relatedObjectsWatch() {
         const relatedObjectsRulesIsEmpty = !state.relatedObjectsRules || isEmpty(state.relatedObjectsRules);
         for (const objectKey of Object.keys(state.relatedObjects)) {
@@ -100,7 +327,7 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
                 ));
             } else {
                 if (isEmpty(state.relatedObjects[objectKey])) {
-                    return;
+                    continue;
                 }
                 removedRuleKeys = new Set(Object.keys(state.relatedObjects[objectKey]));
                 addedRuleKeys = new Set();
@@ -121,48 +348,7 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
                 const relatedObjectRef = toRef(state.relatedObjects, objectKey);
                 relatedObjectsEffectScopes[objectKey].run(() => {
                     for (const addedRuleKey of addedRuleKeys) {
-                        const rules = toRef(state.relatedObjectsRules, addedRuleKey);
-                        state.objAndKeyForIdAndRule[objectKey][addedRuleKey] = computed(() => {
-                            const rulePkKey = unref(rules).pkKey || addedRuleKey;
-                            const object = unref(originalObjectRef);
-                            const relatedObject = unref(relatedObjectRef);
-                            return getObjectRelatedByKey(object, relatedObject, rulePkKey);
-                        });
-
-                        state.fkForIdAndRule[objectKey][addedRuleKey] = computed(() => {
-                            const ruleOrder = unref(rules).order;
-                            const relatedObject = unref(relatedObjectRef);
-                            const [objectForGet, key] = unref(state.objAndKeyForIdAndRule[objectKey][addedRuleKey]);
-                            let value = get(objectForGet, key);
-                            if (objectForGet === relatedObject && isUndefined(value)) {
-                                // is the first level an array?
-                                const firstLevelKey = key.split(".")[0];
-                                const firstLevelItem = get(relatedObject, firstLevelKey);
-                                if (isArray(firstLevelItem)) {
-                                    const restOfKey = key.slice(firstLevelKey.length + 1);
-                                    value = firstLevelItem.map((e) => get(e, restOfKey)).flat();
-                                }
-                            }
-                            if (isArray(value) && 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;
-                                });
-                            }
-                            return value;
-                        });
-
-                        state.relatedObjects[objectKey][addedRuleKey] = computed(() => {
-                            const value = unref(state.fkForIdAndRule[objectKey][addedRuleKey]);
-                            const objects = unref(rules).objects;
-                            if (isArray(value)) {
-                                return value.map((e) => objects[e]).filter(identity);
-                            }
-                            return objects[value];
-                        });
+                        applyRuleToObject(objectKey, addedRuleKey, originalObjectRef, relatedObjectRef);
                     }
                 });
             }
@@ -198,9 +384,11 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
             ],
         });
 
+        // @ts-ignore - proxy the running property
         state.relatedRunning = toRef(watchesRunning.state, "running");
         const parentRunning = ref(undefined);
         proxyRunning(parentState, "running", parentRunning);
+        // @ts-ignore - combine the running properties
         state.running = computed(() => loadingCombine(watchesRunning.state.running, parentRunning.value));
 
         onScopeDispose(() => {