@arrai-innovations/reactive-helpers 10.4.2 → 11.0.0

package/use/listSearch.js

@@ -0,0 +1,358 @@
+import { difference, loadingCombine, assignReactiveObject, keyDiff } from "../utils/index.js";
+import { getObjectRelatedCalculatedByKey } from "../utils/relatedCalculatedHelpers.js";
+import {
+    listInstanceStateKeys,
+    listSubscriptionStateKeys,
+    listRelatedStateKeys,
+    listCalculatedStateKeys,
+    listSortStateKeys,
+    listFilterStateKeys,
+    listSearchStateKeys,
+} from "./listKeys.js";
+import { useSearch } from "./search.js";
+import get from "lodash-es/get.js";
+import isEqual from "lodash-es/isEqual.js";
+import { reactive, effectScope, toRef, computed, watch, unref, onScopeDispose } from "vue";
+import { deepUnref } from "vue-deepunref";
+
+const parentStateKeys = difference(
+    new Set([
+        ...listInstanceStateKeys,
+        ...listSubscriptionStateKeys,
+        ...listRelatedStateKeys,
+        ...listCalculatedStateKeys,
+        ...listSortStateKeys,
+        ...listFilterStateKeys,
+    ]),
+    new Set(listSearchStateKeys)
+);
+
+/* 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, ListSearchInstanceOptions>} listInstanceArgs - each desired list instance options, keyed by an instance name.
+ * @returns {Object.<string, ListSearchInstance>} - each list instance, keyed by the instance name.
+ */
+
+/* eslint-enable jsdoc/check-types */
+export function useListSearches(args, instances) {
+    const searches = {};
+    for (const [key, value] of Object.entries(args)) {
+        searches[key] = useListSearch({ parentState: instances[key].state, ...value });
+    }
+    return searches;
+}
+
+/**
+ * @typedef {object} ListSearchProps
+ * @property {array} textSearchRules - rules for what to search for. Keys are the keys to search for, values are functions that take the object and return the value to search for.
+ * @property {string} textSearchValue - the value to search for.
+ * @property {object} customDocumentOptions - FlexSearch.Document options
+ * @property {object} customSearchOptions - FlexSearch.Search options
+ * @property {object} [customSearchOptions.limit=1000] - FlexSearch.Search options
+ */
+
+/**
+ * @typedef {object} ListSearchInstance
+ * @property {object} state - the state
+ * @property {SearchInstance} textSearchIndex - the text search index
+ * @property {object} effectScope - a Vue effect scope
+ */
+
+/**
+ * @typedef {object} ListSearchInstanceOptions
+ * @property {object} parentState - the list being filtered
+ * @property {ListSearchProps} props - reactive properties
+ * @property {number} [throttle=500] - throttle wait time
+ * @property {boolean} [showAllWhenEmpty=true] - whether to show all items when the search is empty
+ */
+
+/**
+ * Text filter for list items. This will not be performant for large lists, as each item will be watched.
+ * However, the results will reactively update.
+ * @param {ListSearchInstanceOptions} options - the arguments
+ * @returns {ListSearchInstance} - the instance
+ */
+export function useListSearch({ parentState, props, throttle = 500, showAllWhenEmpty = true }) {
+    if (!parentState) {
+        throw new Error("parentState is required");
+    }
+    const state = reactive({
+        objects: {},
+        objectsInOrder: [],
+        order: [],
+        textSearchRules: toRef(props, "textSearchRules"),
+        textSearchValue: toRef(props, "textSearchValue"),
+        objectIndexes: {},
+        updateSearchIndexesRunning: undefined,
+        customDocumentOptions: toRef(props, "customDocumentOptions"),
+        customSearchOptions: toRef(props, "customSearchOptions"),
+        searched: undefined,
+        running: undefined,
+        newSearchComputeds: undefined,
+    });
+    if (!state.customDocumentOptions) {
+        state.customDocumentOptions = {};
+    }
+    if (!state.customSearchOptions) {
+        state.customSearchOptions = {};
+    }
+    const textSearchIndexProps = reactive({
+        customDocumentOptions: computed(() => {
+            const options = {
+                tokenize: "forward",
+                minlength: 2,
+                ...state.customDocumentOptions, // todo: not sure if this is ok inside a computed
+            };
+            if (!options.document) {
+                options.document = {
+                    id: "id",
+                };
+            }
+            options.document.index = state.textSearchRules;
+            return options;
+        }),
+        customSearchOptions: computed(() => ({
+            ...state.customSearchOptions, // todo: not sure if this is ok inside a computed
+            limit: state.customSearchOptions.limit ?? 1000,
+        })),
+    });
+
+    const es = effectScope();
+
+    let textSearchIndex;
+
+    const objectEffectScopes = {};
+    const objectComputeds = {};
+
+    const previousTextSearchRules = [];
+    const previousObjectIndexes = {};
+
+    const doPassthrough = (cleanComputed = false) => {
+        // pass through the objects if there are no rules.
+        assignReactiveObject(state.objects, showAllWhenEmpty ? parentState.objects : {});
+        if (!cleanComputed) {
+            return;
+        }
+        // if there were indexes or computeds, there is no point in keeping them.
+        for (const objectKey of Object.keys(objectEffectScopes)) {
+            objectEffectScopes[objectKey].stop();
+        }
+        assignReactiveObject(objectEffectScopes, {});
+        assignReactiveObject(objectComputeds, {});
+        assignReactiveObject(state.objectIndexes, {});
+    };
+
+    const makeComputeds = () => {
+        if (!state.textSearchRules?.length) {
+            doPassthrough(true);
+            return;
+        }
+        const {
+            addedKeys: addedObjectIds,
+            removedKeys: removedObjectIds,
+            sameKeys: sameObjectIds,
+        } = keyDiff(Object.keys(parentState.objects), Object.keys(state.objects));
+        const { addedKeys: addedTextSearchRules, removedKeys: removedTextSearchRules } = keyDiff(
+            state.textSearchRules,
+            previousTextSearchRules
+        );
+        for (const removedObjectId of removedObjectIds) {
+            delete state.objectIndexes[removedObjectId];
+            // the effect scope will be stopped when the object is removed.
+            delete objectComputeds[removedObjectId];
+            if (objectEffectScopes[removedObjectId]) {
+                objectEffectScopes[removedObjectId].stop();
+                delete objectEffectScopes[removedObjectId];
+            }
+        }
+        for (const addedObjectId of addedObjectIds) {
+            state.objectIndexes[addedObjectId] = { id: addedObjectId };
+            objectComputeds[addedObjectId] = {};
+            objectEffectScopes[addedObjectId] = effectScope();
+            const objectEffectScope = objectEffectScopes[addedObjectId];
+            const objectRef = toRef(parentState.objects, addedObjectId);
+            const relatedRef = parentState.relatedObjects
+                ? toRef(parentState.relatedObjects, addedObjectId)
+                : undefined;
+            const calculatedRef = parentState.calculatedObjects
+                ? toRef(parentState.calculatedObjects, addedObjectId)
+                : undefined;
+            objectEffectScope.run(() => {
+                for (const rule of state.textSearchRules || []) {
+                    const [obj, key] = getObjectRelatedCalculatedByKey(objectRef, relatedRef, calculatedRef, rule);
+                    state.newSearchComputeds = true;
+                    state.objectIndexes[addedObjectId][rule] = objectComputeds[addedObjectId][rule] = computed(() => {
+                        return get(unref(obj), key);
+                    });
+                }
+            });
+        }
+        for (const sameObjectId of sameObjectIds) {
+            const objectEffectScope = objectEffectScopes[sameObjectId];
+            const objectRef = toRef(parentState.objects, sameObjectId);
+            const relatedRef = parentState.relatedObjects ? toRef(parentState.relatedObjects, sameObjectId) : undefined;
+            const calculatedRef = parentState.calculatedObjects
+                ? toRef(parentState.calculatedObjects, sameObjectId)
+                : undefined;
+            for (const key of removedTextSearchRules) {
+                delete state.objectIndexes[sameObjectId][key];
+                // stop a computed earlier than the effect scope
+                objectComputeds[sameObjectId][key].effect.stop();
+                delete objectComputeds[sameObjectId][key];
+            }
+            objectEffectScope.run(() => {
+                for (const rule of addedTextSearchRules) {
+                    const [obj, key] = getObjectRelatedCalculatedByKey(objectRef, relatedRef, calculatedRef, rule);
+                    state.newSearchComputeds = true;
+                    state.objectIndexes[sameObjectId][rule] = objectComputeds[sameObjectId][rule] = computed(() => {
+                        return get(unref(obj), key);
+                    });
+                }
+            });
+        }
+        previousTextSearchRules.length = 0;
+        if (state.textSearchRules?.length) {
+            previousTextSearchRules.push(...state.textSearchRules);
+        }
+    };
+
+    const updateSearchIndexes = async () => {
+        if (state.updateSearchIndexesRunning === undefined) {
+            state.updateSearchIndexesRunning = 0;
+        }
+        state.updateSearchIndexesRunning++;
+        try {
+            const { addedKeys, removedKeys, sameKeys } = keyDiff(
+                Object.keys(state.objectIndexes),
+                Object.keys(previousObjectIndexes)
+            );
+            const promises = [];
+            for (const removedKey of removedKeys) {
+                promises.push(textSearchIndex.removeIndex(removedKey));
+                delete previousObjectIndexes[removedKey];
+            }
+            for (const addedKey of addedKeys) {
+                promises.push(textSearchIndex.addIndex(state.objectIndexes[addedKey]));
+                previousObjectIndexes[addedKey] = deepUnref(state.objectIndexes[addedKey]);
+            }
+            for (const sameKey of sameKeys) {
+                if (!isEqual(previousObjectIndexes[sameKey], state.objectIndexes[sameKey])) {
+                    promises.push(textSearchIndex.updateIndex(state.objectIndexes[sameKey]));
+                    previousObjectIndexes[sameKey] = deepUnref(state.objectIndexes[sameKey]);
+                }
+            }
+            if (promises.length) {
+                await Promise.all(promises);
+            }
+        } finally {
+            if (state.newSearchComputeds) {
+                state.newSearchComputeds = false;
+            }
+            state.updateSearchIndexesRunning--;
+        }
+    };
+
+    const updateObjectsForResults = () => {
+        if (!state.textSearchRules?.length || !state.textSearchValue?.length) {
+            doPassthrough();
+            return;
+        }
+        assignReactiveObject(
+            state.objects,
+            Object.fromEntries(
+                Object.entries(textSearchIndex.state.results)
+                    .filter(([, value]) => !!value)
+                    .map(([id]) => [id, toRef(parentState.objects, id)])
+            )
+        );
+    };
+
+    const updateOrder = () => {
+        assignReactiveObject(
+            state.objectsInOrder,
+            parentState.order.filter((id) => !!state.objects[id]).map((id) => toRef(state.objects, id))
+        );
+        assignReactiveObject(
+            state.order,
+            parentState.order.filter((id) => !!state.objects[id])
+        );
+    };
+
+    let firstIndexWasCleared = false;
+
+    const indexWasCleared = async () => {
+        // skip the first time, preventing clearing the index after makeComputeds already ran.
+        if (firstIndexWasCleared) {
+            return;
+        }
+        firstIndexWasCleared = true;
+        assignReactiveObject(previousObjectIndexes, {});
+        await makeComputeds();
+    };
+
+    let watchesRunning;
+
+    es.run(() => {
+        for (const key of parentStateKeys) {
+            state[key] = toRef(parentState, key);
+        }
+
+        textSearchIndex = useSearch({
+            props: textSearchIndexProps,
+            throttle,
+        });
+        textSearchIndex.state.search = toRef(state, "textSearchValue");
+        textSearchIndex.events.addEventListener("newIndex", indexWasCleared);
+        state.searched = toRef(() => textSearchIndex.state.searched);
+        state.running = computed(() => {
+            return loadingCombine(parentState.running, state.newSearchComputeds, textSearchIndex.state.running);
+        });
+
+        watch([() => Object.keys(parentState.objects), toRef(state.textSearchRules)], makeComputeds, {
+            immediate: true,
+        });
+
+        watch(
+            toRef(state, "objectIndexes"),
+            () => {
+                updateSearchIndexes();
+            },
+            {
+                deep: true,
+                immediate: true,
+            }
+        );
+
+        watch(
+            [
+                toRef(state, "textSearchValue"),
+                () => Object.keys(textSearchIndex.state.results),
+                toRef(textSearchIndex.state, "running"),
+            ],
+            updateObjectsForResults,
+            {
+                immediate: true,
+            }
+        );
+
+        watch(toRef(parentState, "order"), updateOrder, {
+            immediate: true,
+            deep: true,
+        });
+
+        onScopeDispose(() => {
+            for (const objectKey of Object.keys(objectEffectScopes)) {
+                objectEffectScopes[objectKey].stop();
+            }
+        });
+    });
+
+    return {
+        state,
+        effectScope: es,
+        textSearchIndex,
+        watchesRunning,
+    };
+}

package/use/listSort.js

@@ -1,9 +1,13 @@
-import { assignReactiveObject, keyDiff, loadingCombine } from "../utils/index.js";
-import { listCalculatedStateKeys } from "./listCalculated.js";
-import { listFilterStateKeys } from "./listFilter.js";
-import { listInstanceStateKeys } from "./listInstance.js";
-import { listRelatedStateKeys } from "./listRelated.js";
-import { listSubscriptionStateKeys } from "./listSubscription.js";
+import { assignReactiveObject, keyDiff, loadingCombine, difference } from "../utils/index.js";
+import {
+    listSortStateKeys,
+    listFilterStateKeys,
+    listRelatedStateKeys,
+    listCalculatedStateKeys,
+    listSubscriptionStateKeys,
+    listInstanceStateKeys,
+    listSearchStateKeys,
+} from "./listKeys.js";
 import { useWatchesRunning } from "./watchesRunning.js";
 import cloneDeep from "lodash-es/cloneDeep.js";
 import get from "lodash-es/get.js";
@@ -16,21 +20,6 @@ import throttle from "lodash-es/throttle.js";
 import zip from "lodash-es/zip.js";
 import { effectScope, reactive, toRef, unref, watch, computed } from "vue";
 
-export const listSortStateKeys = [
-    "orderByRules",
-    // "order",
-    // "objectsInOrder",
-    "sortCriteria",
-    "sortCriteriaEffectScopes",
-    "orderByDesc",
-    "sortCriteriaWatchRunning",
-    "sortWatchRunning",
-    "outstandingEffects",
-    // "running",
-];
-
-export const listSortFunctions = [];
-
 const collator = new Intl.Collator(undefined, { numeric: true });
 
 const defaultSortThrottleWait = Symbol("defaultSortThrottleWait");
@@ -39,6 +28,18 @@ const defaultOptions = {
     sortThrottleWait: 100,
 };
 
+const parentStateKeys = difference(
+    new Set([
+        ...listInstanceStateKeys,
+        ...listSubscriptionStateKeys,
+        ...listRelatedStateKeys,
+        ...listCalculatedStateKeys,
+        ...listFilterStateKeys,
+        ...listSearchStateKeys,
+    ]),
+    new Set(listSortStateKeys)
+);
+
 export function setListSortDefaultOptions({ sortThrottleWait }) {
     defaultOptions.sortThrottleWait = sortThrottleWait;
 }
@@ -55,12 +56,14 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
     if (sortThrottleWait === defaultSortThrottleWait) {
         sortThrottleWait = defaultOptions.sortThrottleWait;
     }
+
+    const sortCriteriaEffectScopes = {};
+
     const state = reactive({
         orderByRules,
         order: [],
         objectsInOrder: [],
         sortCriteria: {},
-        sortCriteriaEffectScopes: {},
         orderByDesc: [],
         sortCriteriaWatchRunning: false,
         sortWatchRunning: false,
@@ -69,16 +72,16 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
     const es = effectScope();
 
     function removeSortCriteria(removedKey) {
-        const oldScope = state.sortCriteriaEffectScopes[removedKey];
+        const oldScope = sortCriteriaEffectScopes[removedKey];
         if (oldScope) {
             oldScope.stop();
-            delete state.sortCriteriaEffectScopes[removedKey];
+            delete sortCriteriaEffectScopes[removedKey];
         }
         delete state.sortCriteria[removedKey];
     }
 
     function addSortCriteria(object, relatedObject, calculatedObject, key) {
-        const oldScope = state.sortCriteriaEffectScopes[key];
+        const oldScope = sortCriteriaEffectScopes[key];
         if (oldScope) {
             oldScope.stop();
         }
@@ -123,7 +126,7 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
                 }
             );
         });
-        state.sortCriteriaEffectScopes[key] = newScope;
+        sortCriteriaEffectScopes[key] = newScope;
     }
 
     function sortCriteriaWatch() {
@@ -220,22 +223,7 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
     let watchesRunning = null;
 
     es.run(() => {
-        for (const key of listInstanceStateKeys) {
-            if (["order", "objectsInOrder"].includes(key)) {
-                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);
-        }
-        for (const key of listFilterStateKeys) {
+        for (const key of parentStateKeys) {
             state[key] = toRef(parentState, key);
         }
         // this watch must come first or be immediate.

package/use/listSubscription.js

@@ -1,6 +1,7 @@
 import { loadingCombine } from "../utils/loadingCombine.js";
 import { useCancellableIntent } from "./cancellableIntent.js";
-import { listInstanceStateKeys, useListInstance } from "./listInstance.js";
+import { useListInstance } from "./listInstance.js";
+import { listInstanceStateKeys } from "./listKeys.js";
 import inspect from "browser-util-inspect";
 import cloneDeep from "lodash-es/cloneDeep.js";
 import isEmpty from "lodash-es/isEmpty.js";
@@ -14,17 +15,6 @@ export class ListSubscriptionError extends Error {
     }
 }
 
-export const listSubscriptionStateKeys = [
-    "subscriptionLoading",
-    "subscriptionErrored",
-    "subscriptionError",
-    "intendToList",
-    "intendToSubscribe",
-    "subscribed",
-];
-
-export const listSubscriptionFunctions = ["subscribe", "unsubscribe", "clearError"];
-
 /**
  * The configuration options used to create a list subscription.
  * @typedef {object} ListSubscriptionOptions
@@ -190,7 +180,7 @@ export function useListSubscription({ listInstance, props, functions, keepOldPag
             listInstance.deleteListObject(id);
         } catch (err) {
             if (err.name === "ListError" && err.code === "missing-object") {
-                console.warn(`deleteFromSubscription: delete for id not in objects (${id}).`);
+                console.warn(`deleteFromSubscription: delete for id not in objects (${inspect(id)}).`);
                 return;
             }
             throw err;