@arrai-innovations/reactive-helpers 20.1.2 → 21.0.0

package/use/list.js

@@ -1,21 +1,11 @@
 import { useListCalculated } from "./listCalculated.js";
 import { useListFilter } from "./listFilter.js";
 import { useListInstance } from "./listInstance.js";
-import {
-    listSortFunctions,
-    listFilterFunctions,
-    listRelatedFunctions,
-    listCalculatedFunctions,
-    listSubscriptionFunctions,
-    listInstanceFunctions,
-    listSearchFunctions,
-} from "./listKeys.js";
 import { useListRelated } from "./listRelated.js";
 import { useListSearch } from "./listSearch.js";
 import { useListSort } from "./listSort.js";
 import { useListSubscription } from "./listSubscription.js";
-import { usePagedListInstance } from "./paginatedListInstance.js";
-import { effectScope, reactive, shallowReactive, shallowReadonly, toRef } from "vue";
+import { effectScope, shallowReactive, shallowReadonly, toRef } from "vue";
 
 /**
  * Provides a comprehensive Vue 3 composable function for managing a list of objects. This module orchestrates several
@@ -66,45 +56,17 @@ export class ListError extends Error {
 /**
  * @typedef {object} ListOptions
  * @property {ListRawProps} props - The properties for configuring the list.
- * @property {import('../config/listCrud.js').ListCrudHandlers} handlers - Additional handlers to be included in the list manager.
- * @property {boolean} paged - Indicates whether the list should be paginated.
- * @property {import('vue').Ref<boolean>|boolean} keepOldPages - Indicates whether old pages should be kept when paginating.
- * @property {boolean} clearListOnListIntentTriggered - Indicates whether the list should be cleared when the list intent is triggered.
- * @property {number} searchThrottle - The throttle time for text search.
- * @property {number} sortThrottleWait - The throttle time for sorting.
- * @property {boolean} searchShowAllWhenEmpty - Indicates whether all items should be shown when the search query is empty.
- */
-
-/**
- * Represents the combined state definitions for all list-related components.
- * This interface aggregates the raw state from multiple list management functionalities.
- *
- * @typedef {(
- *     (
- *         import('./listInstance.js').ListInstanceRawState |
- *         import('./paginatedListInstance.js').PagedListInstanceRawState
- *     ) &
- *     import('./listSubscription.js').ListSubscriptionRawState &
- *     import('./listRelated.js').ListRelatedRawState &
- *     import('./listCalculated.js').ListCalculatedRawState &
- *     import('./listFilter.js').ListFilterRawState &
- *     import('./listSearch.js').ListSearchRawState &
- *     import('./listSort.js').ListSortRawState
- * )} ListRawState
- */
-
-/**
- * Represents the reactive state derived from aggregating states of various list-related components.
- * This state is typically used within Vue components for reactivity and access to updated list properties.
- *
- * @typedef {import('vue').UnwrapNestedRefs<ListRawState>} ListState
+ * @property {import('../config/listCrud.js').ListCrudHandlers} [handlers] - Additional handlers to be included in the list manager.
+ * @property {number} [searchThrottle] - The throttle time for text search.
+ * @property {number} [sortThrottleWait] - The throttle time for sorting.
+ * @property {boolean} [searchShowAllWhenEmpty] - Indicates whether all items should be shown when the search query is empty.
  */
 
 /**
  * Holds references to instances of all list-related composables, facilitating direct access and management.
  *
  * @typedef {{
- *     listInstance: import('./listInstance.js').ListInstance | import('./paginatedListInstance.js').PagedListInstance,
+ *     listInstance: import('./listInstance.js').ListInstance,
  *     listSubscription: import('./listSubscription.js').ListSubscription,
  *     listRelated: import('./listRelated.js').ListRelated,
  *     listCalculated: import('./listCalculated.js').ListCalculated,
@@ -123,20 +85,14 @@ export class ListError extends Error {
  * )} ListFunctions
  */
 
-// & import('./listRelated.js').ListRelatedFunctions
-// & import('./listCalculated.js').ListCalculatedFunctions
-// & import('./listFilter.js').ListFilterFunctions
-// & import('./listSearch.js').ListSearchFunctions
-// & import('./listSort.js').ListSortFunctions
-
 /**
  * Encapsulates properties relevant to the overall management of list-related hooks, including state, direct access to hooks,
  * and scoped effects.
  *
  * @typedef {object} ListManagerProperties
  * @property {ListManaged} managed - A readonly reference to the managed list hooks.
- * @property {ListState} state - Represents the final reactive state in the list processing chain.
- * @property {import('vue').EffectScope} effectScope - Encapsulates all reactive effects related to the list hooks.
+ * @property {import('./listSort.js').ListSortState} state - Represents the final reactive state in the list processing chain.
+ * @property {() => void} stop - A function to stop the effect scope and clean up resources.
  */
 
 /**
@@ -146,6 +102,31 @@ export class ListError extends Error {
  * @typedef {ListFunctions & ListManagerProperties} ListManager
  */
 
+/* eslint-disable jsdoc/valid-types */
+/**
+ * Extract function properties from a source object, excluding `stop`.
+ *
+ * @template {object} T
+ * @param {T} source - The source object from which to extract function properties.
+ * @returns {{
+ *   [K in keyof T as K extends "stop" ? never : T[K] extends (...args: any[]) => any ? K : never]: T[K]
+ * }} - An object containing only the function properties of the source object, excluding `stop`.
+ */
+function mergeFns(source) {
+    const returnedFns = {};
+    for (const key of Object.keys(source)) {
+        if (key !== "stop") {
+            const val = source[key];
+            if (typeof val === "function") {
+                returnedFns[key] = val;
+            }
+        }
+    }
+    // @ts-ignore
+    return returnedFns;
+}
+/* eslint-enable jsdoc/valid-types */
+
 /**
  * Initializes multiple list management instances with provided configurations.
  *
@@ -177,16 +158,8 @@ export const useLists = (listOptions) => {
  * @returns {ListManager} - The managed stack of list-related composable functions.
  * @throws {ListError} - If required options are not provided.
  */
-export const useList = ({
-    props,
-    handlers = {},
-    paged,
-    keepOldPages,
-    clearListOnListIntentTriggered,
-    searchThrottle = 500,
-    sortThrottleWait,
-    searchShowAllWhenEmpty,
-}) => {
+export const useList = ({ props, handlers = {}, searchThrottle = 500, sortThrottleWait, searchShowAllWhenEmpty }) => {
+    /** @type {ListManaged} */
     const managed = shallowReactive({
         listInstance: null,
         listSubscription: null,
@@ -196,12 +169,6 @@ export const useList = ({
         listSearch: null,
         listSort: null,
     });
-    if (paged === undefined || keepOldPages === undefined || clearListOnListIntentTriggered === undefined) {
-        throw new ListError(
-            "useList requires paged, keepOldPages, and clearListOnListIntentTriggered to be all set.",
-            "missing-arguments"
-        );
-    }
 
     if (!("params" in props)) {
         console.error("params not set, must be true for intendToList or intendToSubscribe to work.");
@@ -210,18 +177,15 @@ export const useList = ({
     const es = effectScope();
 
     es.run(() => {
-        managed.listInstance = (paged ? usePagedListInstance : useListInstance)({
+        managed.listInstance = useListInstance({
             props,
             handlers,
-            keepOldPages,
         });
 
         managed.listSubscription = useListSubscription({
             listInstance: managed.listInstance,
-            clearListOnListIntentTriggered,
+            props,
         });
-        managed.listSubscription.state.intendToList = toRef(props, "intendToList");
-        managed.listSubscription.state.intendToSubscribe = toRef(props, "intendToSubscribe");
 
         managed.listRelated = useListRelated({
             parentState: managed.listSubscription.state,
@@ -241,12 +205,7 @@ export const useList = ({
 
         managed.listSearch = useListSearch({
             parentState: managed.listFilter.state,
-            props: reactive({
-                textSearchRules: toRef(props, "textSearchRules"),
-                textSearchValue: toRef(props, "textSearchValue"),
-                customDocumentOptions: toRef(props, "customDocumentOptions"),
-                customSearchOptions: toRef(props, "customSearchOptions"),
-            }),
+            props,
             throttle: searchThrottle,
             showAllWhenEmpty: searchShowAllWhenEmpty,
         });
@@ -258,40 +217,21 @@ export const useList = ({
         });
     });
 
-    const clearError = () => {
-        managed.listSubscription.clearError();
-        managed.listInstance.clearError();
-    };
-
+    // noinspection UnnecessaryLocalVariableJS
     /** @type {ListManager} */
-    // @ts-ignore - we're going to assign remaining properties below.
-    const returnObject = {
-        // we manage the keys on both of these, so hands off the root.
+    const manager = {
         managed: shallowReadonly(managed),
         state: managed.listSort.state,
-        effectScope: es,
+        stop: () => {
+            es.stop();
+        },
+        ...mergeFns(managed.listInstance),
+        ...mergeFns(managed.listSubscription),
+        ...mergeFns(managed.listRelated),
+        ...mergeFns(managed.listCalculated),
+        ...mergeFns(managed.listFilter),
+        ...mergeFns(managed.listSearch),
+        ...mergeFns(managed.listSort),
     };
-    const handledDuplicateFunctions = {
-        clearError,
-    };
-    for (const [source, fnNames] of [
-        [managed.listInstance, listInstanceFunctions],
-        [managed.listSubscription, listSubscriptionFunctions],
-        [managed.listRelated, listRelatedFunctions],
-        [managed.listCalculated, listCalculatedFunctions],
-        [managed.listFilter, listFilterFunctions],
-        [managed.listSearch, listSearchFunctions],
-        [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;
+    return manager;
 };

package/use/listCalculated.js

@@ -1,19 +1,8 @@
-import { difference } from "../utils/set.js";
 import { keyDiff } from "../utils/keyDiff.js";
 import { loadingCombine } from "../utils/loadingCombine.js";
 import { proxyRunning } from "../utils/proxyRunning.js";
-import {
-    listCalculatedStateKeys,
-    listFilterStateKeys,
-    listInstanceStateKeys,
-    listRelatedStateKeys,
-    listSearchStateKeys,
-    listSortStateKeys,
-    listSubscriptionStateKeys,
-} from "./listKeys.js";
-import { useWatchesRunning } from "./watchesRunning.js";
 import isEmpty from "lodash-es/isEmpty.js";
-import { computed, effectScope, onScopeDispose, reactive, ref, toRef, unref, watch } from "vue";
+import { computed, effectScope, nextTick, reactive, ref, toRef, toRefs, unref, watch } from "vue";
 
 /**
  * This module provides a Vue Composition API composable function for dynamically calculating properties in lists
@@ -29,9 +18,9 @@ import { computed, effectScope, onScopeDispose, reactive, ref, toRef, unref, wat
  *  object from the list, optionally its related objects, and previously calculated properties to compute a new
  *  property. These functions are reactive and re-evaluate when underlying dependencies change.
  *
- * @typedef {import('vue').Ref<{
+ * @typedef {{
  *     [rule: string]: (
- *         object: import('./listInstance.js').ListObject,
+ *         object: import('../use/objectInstance.js').ExistingCrudObject,
  *         relatedObject: {
  *             [rule: string]: any,
  *         },
@@ -39,8 +28,7 @@ import { computed, effectScope, onScopeDispose, reactive, ref, toRef, unref, wat
  *             [rule: string]: import('vue').ComputedRef<any>,
  *         }
  *     ) => any,
- * }>}  ListCalculatedRules
- *
+ * }}  ListCalculatedRules
  */
 
 /**
@@ -51,8 +39,8 @@ import { computed, effectScope, onScopeDispose, reactive, ref, toRef, unref, wat
  * @property {ListCalculatedRules} calculatedObjectsRules - The rules for the calculated objects.
  * @property {boolean} calculatedObjectsParentStateObjectsWatchRunning - Whether the parent state objects watch is running.
  * @property {boolean} calculatedObjectsWatchRunning - Whether the calculated objects watch is running.
- * @property {boolean} calculatedRunning - Whether the calculated properties are running.
- * @property {import('vue').Ref<boolean>} running - Whether the list is running.
+ * @property {import('vue').ComputedRef<boolean>} calculatedRunning - Whether the calculated properties are running.
+ * @property {import('vue').ComputedRef<boolean>} running - Whether the list is running.
  * @private
  */
 
@@ -86,24 +74,12 @@ import { computed, effectScope, onScopeDispose, reactive, ref, toRef, unref, wat
  * )>} ListCalculatedParentState
  */
 
-const parentStateKeys = difference(
-    new Set([
-        ...listInstanceStateKeys,
-        ...listSubscriptionStateKeys,
-        ...listRelatedStateKeys,
-        ...listFilterStateKeys,
-        ...listSortStateKeys,
-        ...listSearchStateKeys,
-    ]),
-    new Set(listCalculatedStateKeys)
-);
-
 /**
  * The options to create a list calculated composition function.
  *
  * @typedef {object} ListCalculatedOptions - Options to configure the behavior of the list calculated properties.
  * @property {ListCalculatedParentState} parentState - The parent state that interacts with the calculated objects.
- * @property {ListCalculatedRules} calculatedObjectsRules - A reactive reference to rules used for dynamic calculations
+ * @property {import('vue').Ref<ListCalculatedRules>} calculatedObjectsRules - A reactive reference to rules used for dynamic calculations
  *  within list objects. Proper setup of this reference ensures that updates are managed reactively, including deep
  *  property changes.
  */
@@ -114,8 +90,7 @@ const parentStateKeys = difference(
  * @typedef {object} ListCalculatedProperties
  * @property {ListCalculatedState} state - The state for the list calculated property.
  * @property {ListCalculatedParentState} parentState - The parent state object.
- * @property {import('./watchesRunning.js').WatchesRunning} watchesRunning - The watches running.
- * @property {import('vue').EffectScope} effectScope - The effect scope for the list calculated property.
+ * @property {() => void} stop - Stops composition's effects and cleans up resources.
  */
 
 // if we provided functions, we would add a typedef and mix them into ListCalculated
@@ -199,13 +174,22 @@ export function useListCalculateds(listCalculatedArgs) {
  *  list, facilitating real-time updates and complex dependency management across multiple components.
  */
 export function useListCalculated({ parentState, calculatedObjectsRules }) {
+    const es = effectScope();
+    const parentRefs = toRefs(parentState);
+    /** @type {import('vue').Ref<boolean|undefined>} */
+    const parentRunning = ref(undefined);
+    proxyRunning(parentState, "running", parentRunning);
     /** @type {ListCalculatedState} */
-    // @ts-ignore - The rest of the properties are added in the effect scope.
     const state = reactive({
+        ...parentRefs,
         calculatedObjectsRules,
         calculatedObjects: {},
-        calculatedObjectsParentStateObjectsWatchRunning: false,
-        calculatedObjectsWatchRunning: false,
+        calculatedObjectsParentStateObjectsWatchRunning: true,
+        calculatedObjectsWatchRunning: true,
+        calculatedRunning: computed(() =>
+            loadingCombine(state.calculatedObjectsParentStateObjectsWatchRunning, state.calculatedObjectsWatchRunning)
+        ),
+        running: computed(() => loadingCombine(state.calculatedRunning, parentRunning.value)),
     });
     const calculatedObjectsEffectScopes = {};
 
@@ -217,14 +201,16 @@ export function useListCalculated({ parentState, calculatedObjectsRules }) {
         for (const removedKey of removedKeys) {
             delete state.calculatedObjects[removedKey];
             if (calculatedObjectsEffectScopes[removedKey]) {
-                calculatedObjectsEffectScopes[removedKey].stop();
+                calculatedObjectsEffectScopes[removedKey].objectScope.stop();
                 delete calculatedObjectsEffectScopes[removedKey];
             }
         }
         for (const addedKey of addedKeys) {
             state.calculatedObjects[addedKey] = {};
         }
-        state.calculatedObjectsParentStateObjectsWatchRunning = false;
+        nextTick(() => {
+            state.calculatedObjectsParentStateObjectsWatchRunning = false;
+        });
     }
 
     function calculatedObjectsWatch() {
@@ -248,84 +234,75 @@ export function useListCalculated({ parentState, calculatedObjectsRules }) {
                 addedRuleKeys = [];
             }
             for (const removedRuleKey of removedRuleKeys) {
-                // @ts-ignore - this is an unofficial api, effect is internal
-                calculatedObjectsObject[removedRuleKey]?.effect?.stop?.();
-                delete calculatedObjectsObject[removedRuleKey];
+                if (calculatedObjectsEffectScopes[objectKey]?.ruleScopes?.[removedRuleKey]) {
+                    calculatedObjectsEffectScopes[objectKey].ruleScopes[removedRuleKey].stop();
+                    delete calculatedObjectsEffectScopes[objectKey].ruleScopes[removedRuleKey];
+                }
             }
             if (!calculatedObjectsEffectScopes[objectKey]) {
-                calculatedObjectsEffectScopes[objectKey] = effectScope();
+                calculatedObjectsEffectScopes[objectKey] = {
+                    objectScope: es.run(() => effectScope()),
+                    ruleScopes: {},
+                };
             }
             const originalObjectRef = toRef(parentState.objects, objectKey);
             const relatedObjectRef = parentState.relatedObjects
                 ? toRef(parentState.relatedObjects, objectKey)
                 : ref(undefined);
-            calculatedObjectsEffectScopes[objectKey].run(() => {
+            calculatedObjectsEffectScopes[objectKey].objectScope.run(() => {
                 for (const addedRuleKey of addedRuleKeys) {
-                    calculatedObjectsObject[addedRuleKey] = computed(() =>
-                        state.calculatedObjectsRules?.[addedRuleKey]?.(
-                            unref(originalObjectRef),
-                            unref(relatedObjectRef),
-                            calculatedObjectsObject
+                    const addedRuleScope = effectScope();
+                    calculatedObjectsObject[addedRuleKey] = addedRuleScope.run(() =>
+                        computed(() =>
+                            state.calculatedObjectsRules?.[addedRuleKey]?.(
+                                unref(originalObjectRef),
+                                unref(relatedObjectRef),
+                                calculatedObjectsObject
+                            )
                         )
                     );
+                    calculatedObjectsEffectScopes[objectKey].ruleScopes[addedRuleKey] = addedRuleScope;
                 }
             });
         }
-        state.calculatedObjectsWatchRunning = false;
-    }
-
-    let watchesRunning = null;
-
-    const es = effectScope();
-
-    es.run(() => {
-        for (const key of parentStateKeys) {
-            state[key] = toRef(parentState, key);
-        }
-
-        watch(() => Object.keys(parentState.objects), parentStateObjectsWatch, { immediate: true });
-        watch(
-            [
-                () => Object.keys(state.calculatedObjects),
-                () =>
-                    state.calculatedObjectsRules
-                        ? Object.keys(state.calculatedObjectsRules)
-                        : state.calculatedObjectsRules,
-            ],
-            calculatedObjectsWatch,
-            { immediate: true }
-        );
-
-        watchesRunning = useWatchesRunning({
-            triggerRefs: [
-                computed(() =>
-                    state.calculatedObjectsRules && !isEmpty(state.calculatedObjectsRules) ? parentState.loading : false
-                ),
-            ],
-            watchSentinelRefs: [
-                toRef(state, "calculatedObjectsParentStateObjectsWatchRunning"),
-                toRef(state, "calculatedObjectsWatchRunning"),
-            ],
+        nextTick(() => {
+            state.calculatedObjectsWatchRunning = false;
         });
+    }
 
-        // @ts-ignore - proxy the running property
-        state.calculatedRunning = 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(() => {
-            for (const objectKey of Object.keys(calculatedObjectsEffectScopes)) {
-                calculatedObjectsEffectScopes[objectKey].stop();
-            }
-        });
-    });
+    watch(
+        () => Object.keys(parentState.objects),
+        () => {
+            state.calculatedObjectsParentStateObjectsWatchRunning = true;
+        },
+        { flush: "sync" }
+    );
+    watch(() => Object.keys(parentState.objects), parentStateObjectsWatch, { immediate: true });
+    watch(
+        () => Object.keys(state.calculatedObjects),
+        () => {
+            state.calculatedObjectsWatchRunning = true;
+        },
+        { flush: "sync" }
+    );
+    watch(
+        [
+            () => Object.keys(state.calculatedObjects),
+            () =>
+                state.calculatedObjectsRules ? Object.keys(state.calculatedObjectsRules) : state.calculatedObjectsRules,
+        ],
+        calculatedObjectsWatch,
+        { immediate: true }
+    );
 
     return {
         state,
         parentState,
-        watchesRunning,
-        effectScope: es,
+        stop: () => {
+            es.stop();
+            for (const key of Object.keys(calculatedObjectsEffectScopes)) {
+                delete calculatedObjectsEffectScopes[key];
+            }
+        },
     };
 }