@arrai-innovations/reactive-helpers 10.4.2 → 11.0.1

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;

package/use/search.js

@@ -1,105 +1,195 @@
 import { assignReactiveObject } from "../utils/assignReactiveObject.js";
+import asyncThrottle from "@jcoreio/async-throttle";
 import FlexSearch from "flexsearch";
-import fromPairs from "lodash-es/fromPairs.js";
-import throttle from "lodash-es/throttle.js";
-import { effectScope, reactive, toRef, watch } from "vue";
+import cloneDeep from "lodash-es/cloneDeep.js";
+import isEqual from "lodash-es/isEqual.js";
+import { effectScope, reactive, toRef, watch, computed } from "vue";
+import { deepUnref } from "vue-deepunref";
 
-const indexOptions = {
-    tokenize: "forward",
+/* minimize new Set() allocations */
+const unionReduce = (accumulator, currentValue) => {
+    for (const elem of currentValue) {
+        accumulator.add(elem);
+    }
+    return accumulator;
 };
 
-const searchOptions = {
-    throttle: 500,
-    limit: 1000,
-};
+/**
+ * FlexSearch.Document search options
+ * @typedef {object} SearchOptions
+ * @property {number} limit - limit of results
+ */
 
-export function setDefaultIndexOptions(newDefaultIndexOptions = {}) {
-    Object.assign(indexOptions, newDefaultIndexOptions);
-}
+// eslint-disable-next-line jsdoc/require-property
+/**
+ * FlexSearch.Document options
+ * @typedef {object} DocumentOptions
+ */
 
-export function setDefaultSearchOptions(newDefaultSearchOptions = {}) {
-    Object.assign(searchOptions, newDefaultSearchOptions);
-}
+/**
+ * @typedef {object} SearchState
+ * @property {string} search - the search string
+ * @property {object} results - the results, where the keys are the ids of the objects that match, and the values are true
+ * @property {boolean} searched - whether the search has been performed
+ * @property {boolean} searching - whether the search is currently running
+ */
 
-export function useSearch(
-    customIndexOptions = {}, // custom index options are not reactive.
-    customSearchOptions = {} // custom search options are reactive.
-) {
-    let searchIndex = new FlexSearch.Index({
-        ...indexOptions,
-        ...customIndexOptions,
-    });
-    const mySearchOptions = {
-        ...searchOptions,
-        ...customSearchOptions,
-    };
+/**
+ * @typedef {object} SearchInstance
+ * @property {SearchState} state - the state
+ * @property {function} addIndex - add an index
+ * @property {function} updateIndex - update an index
+ * @property {function} removeIndex - remove an index
+ * @property {function} clearIndex - clear the index
+ * @property {object} effectScope - a Vue effect scope
+ */
+
+const defaultDocumentOptions = {
+    tokenize: "forward",
+    document: {
+        id: "id",
+        index: ["name"],
+    },
+};
+
+/**
+ * A reactive object for passing document options or search options to useSearch
+ * @typedef {object} SearchProps
+ * @property {DocumentOptions} customDocumentOptions - FlexSearch.Document options
+ * @property {SearchOptions} customSearchOptions - search options
+ */
+
+/**
+ * A reactive wrapper around FlexSearch.Index
+ * @param {object} options - options
+ * @param {SearchProps} options.props - props
+ * @param {number} [options.throttle] - throttle wait time
+ * @returns {SearchInstance} - the instance
+ */
+export function useSearch({ props, throttle = 500 }) {
+    let searchIndex;
+    const events = new EventTarget();
     const state = reactive({
         search: "",
         results: {},
         searched: false,
         searching: false,
+        customDocumentOptions: toRef(props, "customDocumentOptions"),
+        customSearchOptions: toRef(props, "customSearchOptions"),
+        called: 0,
+        pending: 0,
+        running: computed(() => state.searching || state.pending > state.called),
     });
-    const addIndex = (id, indexValue) => {
-        // numeric ids consume less memory in flexsearch.
-        const numericId = +id;
-        const numericIfPossible = isNaN(numericId) ? id : numericId;
-        searchIndex.add(numericIfPossible, indexValue);
+    const es = effectScope();
+    const addIndex = async (indexValue) => {
+        ++state.pending;
+        const unrefedIndexValue = deepUnref(indexValue);
+        try {
+            await searchIndex.addAsync(unrefedIndexValue);
+        } catch (e) {
+            ++state.called;
+            throw e;
+        }
         throttledDoSearch();
     };
-    const updateIndex = (id, indexValue) => {
-        // numeric ids consume less memory in flexsearch.
-        const numericId = +id;
-        const numericIfPossible = isNaN(numericId) ? id : numericId;
-        searchIndex.update(numericIfPossible, indexValue);
+    const updateIndex = async (indexValue) => {
+        ++state.pending;
+        try {
+            await searchIndex.updateAsync(deepUnref(indexValue));
+        } catch (e) {
+            ++state.called;
+            throw e;
+        }
         throttledDoSearch();
     };
-    const removeIndex = (id) => {
-        // numeric ids consume less memory in flexsearch.
-        const numericId = +id;
-        const numericIfPossible = isNaN(numericId) ? id : numericId;
-        searchIndex.remove(numericIfPossible);
+    const removeIndex = async (id) => {
+        ++state.pending;
+        try {
+            await searchIndex.removeAsync(id);
+        } catch (e) {
+            ++state.called;
+            throw e;
+        }
         throttledDoSearch();
     };
+
+    let previousCustomDocumentOptions = null;
+
+    const customDocumentOptionsWatchHandler = () => {
+        const unrefCustomDocumentOptions = deepUnref(state.customDocumentOptions);
+        if (!isEqual(previousCustomDocumentOptions, unrefCustomDocumentOptions)) {
+            clearIndex();
+        }
+    };
+
+    const makeIndex = () => {
+        const unrefCustomDocumentOptions = deepUnref(state.customDocumentOptions) || cloneDeep(defaultDocumentOptions);
+        previousCustomDocumentOptions = unrefCustomDocumentOptions;
+        searchIndex = new FlexSearch.Document(unrefCustomDocumentOptions);
+    };
+
     const clearIndex = () => {
-        searchIndex = new FlexSearch.Index(indexOptions);
+        makeIndex();
         assignReactiveObject(state.results, {});
-        state.searched = false;
+        events.dispatchEvent(new Event("newIndex"));
     };
 
     async function doSearch() {
-        if (!state.search) {
+        if (
+            !state.search ||
+            (state.customDocumentOptions?.minlength && state.search.length < state.customDocumentOptions.minlength)
+        ) {
             assignReactiveObject(state.results, {});
             state.searched = false;
-            return;
+            // if there was nothing to do the first time, changing from undefined to false will still let
+            //  users know that we are done.
+        } else {
+            const results = searchIndex.search(state.search, {
+                limit: state.customSearchOptions?.limit || 1000,
+            });
+            const resultsSet = results.map((r) => r.result).reduce(unionReduce, new Set());
+            if (!state.searched) {
+                state.searched = true;
+            }
+            assignReactiveObject(state.results, Object.fromEntries(Array.from(resultsSet).map((e) => [e, true])) || {});
+        }
+        if (state.pending - state.called <= 0) {
+            state.searching = false;
         }
-        state.searching = true;
-        const results = await searchIndex.searchAsync(state.search, {
-            limit: mySearchOptions.limit,
-        });
-        state.searched = true;
-        assignReactiveObject(state.results, fromPairs(results.map((e) => [e, true])) || {});
-        state.searching = false;
     }
 
-    const throttledDoSearch = throttle(doSearch, mySearchOptions.throttle);
-
-    const es = effectScope();
+    const _throttledDoSearch = asyncThrottle(doSearch, throttle);
+    const throttledDoSearch = () => {
+        ++state.called;
+        if (!state.searching) {
+            state.searching = true;
+        }
+        return _throttledDoSearch();
+    };
 
     es.run(() => {
+        watch(toRef(state, "customDocumentOptions"), customDocumentOptionsWatchHandler, {
+            deep: true,
+        });
+        makeIndex();
         watch(
             toRef(state, "search"),
-            function () {
-                if (!indexOptions.minlength || state.search.length >= indexOptions.minlength) {
-                    throttledDoSearch();
-                } else {
-                    assignReactiveObject(state.results, {});
-                    state.searched = false;
-                }
+            () => {
+                ++state.pending;
+                throttledDoSearch();
             },
             {
                 immediate: true,
             }
         );
     });
-    return { state, addIndex, updateIndex, removeIndex, clearIndex, effectScope: es };
+    return {
+        state,
+        addIndex,
+        updateIndex,
+        removeIndex,
+        clearIndex,
+        events,
+        effectScope: es,
+    };
 }

package/use/watchesRunning.js

@@ -22,7 +22,7 @@ export function useWatchesRunning({ triggerRefs, watchSentinelRefs }) {
             }
         );
         state.running = computed(() => {
-            const values = watchSentinelRefs.map((ref) => ref.value);
+            const values = watchSentinelRefs.map((ref) => unref(ref));
             return loadingCombine(values);
         });
     });

package/utils/assignReactiveObject.js

@@ -83,12 +83,12 @@ function validateTargetAndSource(target, source) {
  * @returns {boolean} True if any keys were replaced, false otherwise.
  * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
  */
-function reactiveReplaceKeys(target, source, keys, exclude = []) {
+function reactiveReplaceKeys(target, source, keys, exclude) {
     const targetIsReactive = isReactive(target);
     const sourceIsReactive = isReactive(source);
     let didAnything = false;
     for (const key of keys) {
-        if (!exclude.includes(key)) {
+        if (!exclude?.includes(key)) {
             if (targetIsReactive && sourceIsReactive) {
                 const targetPropRaw = unref(toRef(target, key));
                 // if they are object like  we can see if the values are the same
@@ -122,7 +122,7 @@ function reactiveReplaceKeys(target, source, keys, exclude = []) {
  * @returns {boolean} True if any keys were added, false otherwise.
  * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
  */
-export function addReactiveObject(target, source, exclude = [], addedKeys = null) {
+export function addReactiveObject(target, source, exclude, addedKeys = null) {
     if (!addedKeys) {
         if (target === source) {
             return false;
@@ -144,7 +144,7 @@ export function addReactiveObject(target, source, exclude = [], addedKeys = null
  * @returns {boolean} True if any keys were updated, false otherwise.
  * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
  */
-export function updateReactiveObject(target, source, exclude = [], sameKeys = null) {
+export function updateReactiveObject(target, source, exclude, sameKeys = null) {
     if (!sameKeys) {
         if (target === source) {
             return false;
@@ -167,7 +167,7 @@ export function updateReactiveObject(target, source, exclude = [], sameKeys = nu
  * keys will be calculated.
  * @returns {boolean} True if any keys were added or updated, false otherwise.
  */
-export function addOrUpdateReactiveObject(target, source, exclude = [], addedKeys = null, sameKeys = null) {
+export function addOrUpdateReactiveObject(target, source, exclude, addedKeys = null, sameKeys = null) {
     if (!addedKeys && !sameKeys) {
         if (target === source) {
             return false;
@@ -191,7 +191,7 @@ export function addOrUpdateReactiveObject(target, source, exclude = [], addedKey
  * @returns {boolean} True if any keys were removed, false otherwise.
  * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
  */
-export function trimReactiveObject(target, source, exclude = [], removedKeys = null) {
+export function trimReactiveObject(target, source, exclude, removedKeys = null) {
     if (!removedKeys) {
         if (target === source) {
             return false;
@@ -204,14 +204,14 @@ export function trimReactiveObject(target, source, exclude = [], removedKeys = n
     if (targetIsArray) {
         // Remove indices in reverse (descending) order to keep them stable
         for (const removedKey of [...removedKeys].map((key) => parseInt(key, 10)).sort((a, b) => b - a)) {
-            if (!exclude.includes(removedKey)) {
+            if (!exclude?.includes(removedKey)) {
                 target.splice(removedKey, 1);
                 didAnything = true;
             }
         }
     } else {
         for (const removedKey of removedKeys) {
-            if (!exclude.includes(removedKey)) {
+            if (!exclude?.includes(removedKey)) {
                 delete target[removedKey];
                 didAnything = true;
             }
@@ -220,6 +220,44 @@ export function trimReactiveObject(target, source, exclude = [], removedKeys = n
     return didAnything;
 }
 
+function checkIfReversed(target, source) {
+    if (target.length !== source.length || target.length === 0) {
+        return false;
+    }
+    let t = target.length - 1,
+        s = 0,
+        slen = source.length;
+    while (t >= 0 && s < slen) {
+        const targetValue = target[t];
+        const sourceValue = source[s];
+        if (targetValue === sourceValue) {
+            t--;
+            s++;
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+
+export function assignReactiveArray(target, source) {
+    if (target === source) {
+        return false;
+    }
+    ({ target, source } = validateTargetAndSource(target, source));
+    let didAnything = false;
+    if (checkIfReversed(target, source)) {
+        // reverse the target
+        target.reverse();
+        didAnything = true;
+    } else {
+        const { addedKeys, sameKeys, removedKeys } = keyDiff(Object.keys(source) || [], Object.keys(target) || []);
+        didAnything |= trimReactiveObject(target, source, null, removedKeys);
+        didAnything |= addOrUpdateReactiveObject(target, source, null, addedKeys, sameKeys);
+    }
+    return didAnything;
+}
+
 /**
  * Change a target to match a source, where keys missing from the source are removed from the target,
  * keys present in the source are added to the target, and keys present in both are updated in the target.
@@ -230,7 +268,13 @@ export function trimReactiveObject(target, source, exclude = [], removedKeys = n
  * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
  * @returns {boolean} True if any keys were added, updated, or removed, false otherwise.
  */
-export function assignReactiveObject(target, source, exclude = []) {
+export function assignReactiveObject(target, source, exclude) {
+    if (Array.isArray(target) && Array.isArray(source)) {
+        if (exclude?.length) {
+            console.warn(`assignReactiveObject: exclude doesn't make sense for array assignment`);
+        }
+        return assignReactiveArray(target, source);
+    }
     if (target === source) {
         return false;
     }
@@ -277,7 +321,7 @@ function recursiveInner(target, source, exclude, addedKeys, sameKeys, path, fn)
     for (const key of keysForRecurse) {
         // scope exclude for this next level, remove keys that don't start with the current path, trim keys that do to remove the current path
         const nextLevelExclude = exclude
-            .filter((excludeKey) => !excludeKey.startsWith(path))
+            ?.filter((excludeKey) => !excludeKey.startsWith(path))
             .map((excludeKey) => excludeKey.replace(path, ""));
         const nextPath = isArray(source[key]) ? `${path}[${key}]` : `${path}.${key}`;
         fn(target[key], source[key], nextLevelExclude, nextPath);
@@ -298,7 +342,7 @@ function recursiveInner(target, source, exclude, addedKeys, sameKeys, path, fn)
  * @returns {boolean} True if any keys were added, updated, or removed, false otherwise.
  * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
  */
-function assignReactiveObjectRecursive(target, source, exclude = [], path = "") {
+function assignReactiveObjectRecursive(target, source, exclude, path = "") {
     let { addedKeys, sameKeys, removedKeys } = keyDiff(Object.keys(source) || [], Object.keys(target) || []);
     let didAnything = false;
     didAnything |= trimReactiveObject(target, source, exclude, removedKeys);
@@ -316,7 +360,7 @@ function assignReactiveObjectRecursive(target, source, exclude = [], path = "")
  * @returns {boolean} True if any keys were added, updated, or removed, false otherwise.
  * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
  */
-export function assignReactiveObjectDeep(target, source, exclude = []) {
+export function assignReactiveObjectDeep(target, source, exclude) {
     // exclude keys will need to be lodash get strings
     if (target === source) {
         return false;
@@ -337,7 +381,7 @@ export function assignReactiveObjectDeep(target, source, exclude = []) {
  * @param {string} [path] The current path, used to rescope exclude for the next level.
  * @returns {boolean} True if any keys were added or updated, false otherwise.
  */
-function addOrUpdateReactiveObjectRecursive(target, source, exclude = [], path = "") {
+function addOrUpdateReactiveObjectRecursive(target, source, exclude, path = "") {
     let addedKeys,
         sameKeys = keyDiff(Object.keys(source) || [], Object.keys(target) || []);
     return recursiveInner(target, source, exclude, addedKeys, sameKeys, path, addOrUpdateReactiveObjectRecursive);
@@ -353,7 +397,7 @@ function addOrUpdateReactiveObjectRecursive(target, source, exclude = [], path =
  * @returns {boolean} True if any keys were added or updated, false otherwise.
  * @throws {AssignReactiveObjectError} If either target or source are not ultimately objects or arrays.
  */
-export function addOrUpdateReactiveObjectDeep(target, source, exclude = []) {
+export function addOrUpdateReactiveObjectDeep(target, source, exclude) {
     // exclude keys will need to be lodash get strings
     if (target === source) {
         return false;

package/utils/index.js

@@ -8,6 +8,7 @@ export * from "./getFakeId.js";
 export * from "./keyDiff.js";
 export * from "./lifecycleDebug.js";
 export * from "./loadingCombine.js";
+export * from "./relatedCalculatedHelpers.js";
 export * from "./set.js";
 export * from "./transformWalk.js";
 export * from "./watches.js";

package/utils/keyDiff.js

@@ -18,23 +18,29 @@ import { difference, intersection } from "./set.js";
 /**
  * Result object of keyDiff and keyDiffDeep
  * @typedef {object} KeyDiffResult
- * @property {string[]} [sameKeys] - if sameKeys option is true, return keys that are the same
- * @property {string[]} [removedKeys] - if removedKeys option is true, return keys that are removed
- * @property {string[]} [addedKeys] - if addedKeys option is true, return keys that are added
+ * @property {Set} [sameKeys] - if sameKeys option is true, return keys that are the same
+ * @property {Set} [removedKeys] - if removedKeys option is true, return keys that are removed
+ * @property {Set} [addedKeys] - if addedKeys option is true, return keys that are added
  */
 
 /**
  * Calculate the difference between two arrays of keys, in terms of what keys
  * are the same, what keys are removed, and what keys are added.
  * @function keyDiff
- * @param {string[]} newKeys - keys to consider as new
- * @param {string[]} oldKeys - keys to consider as old
+ * @param {string[]|Set} newKeys - keys to consider as new
+ * @param {string[]|Set} oldKeys - keys to consider as old
  * @param {KeyDiffOptions} [options] - which differences are returned
  * @returns {KeyDiffResult} - the differences
  */
 export function keyDiff(newKeys, oldKeys, { sameKeys = true, removedKeys = true, addedKeys = true } = {}) {
-    const newKeysSet = new Set(newKeys);
-    const oldKeysSet = new Set(oldKeys);
+    let newKeysSet = newKeys;
+    let oldKeysSet = oldKeys;
+    if (!(newKeys instanceof Set)) {
+        newKeysSet = new Set(newKeys);
+    }
+    if (!(oldKeys instanceof Set)) {
+        oldKeysSet = new Set(oldKeys);
+    }
     const returnValue = {};
     if (sameKeys) {
         returnValue.sameKeys = intersection(newKeysSet, oldKeysSet);

package/utils/relatedCalculatedHelpers.js

@@ -0,0 +1,17 @@
+export const relatedItemRegex = /^relatedItem\./;
+export const calculatedItemRegex = /^calculatedItem\./;
+
+export const getObjectRelatedCalculatedByKey = (obj, relatedObj, calculatedObj, key) => {
+    let getObj = obj,
+        getKey = key.replace(relatedItemRegex, () => {
+            getObj = relatedObj;
+            return "";
+        });
+    if (getKey === key) {
+        getKey = key.replace(calculatedItemRegex, () => {
+            getObj = calculatedObj;
+            return "";
+        });
+    }
+    return [getObj, getKey];
+};

package/utils/watches.js

@@ -1,4 +1,4 @@
-import { watch } from "vue";
+import { watch, toRef } from "vue";
 
 // If you want an immediate watch, but you can't use immediate because you want to stop the watch in the function.
 export class ImmediateStopWatch {
@@ -85,7 +85,7 @@ export function doAwaitTimeout(timeout) {
 }
 
 export class AwaitNot {
-    constructor({ obj, prop, couldAlreadyBeFalse = false, timeout = 1000 }) {
+    constructor({ obj, prop, ref, couldAlreadyBeFalse = false, timeout = 1000 }) {
         if (timeout > 0) {
             this.timeout = new AwaitTimeout({ timeout });
         }
@@ -94,8 +94,11 @@ export class AwaitNot {
             this.reject = reject;
         });
         this.couldAlreadyBeFalse = couldAlreadyBeFalse;
-        this.obj = obj;
-        this.prop = prop;
+        if (ref) {
+            this.ref = ref;
+        } else {
+            this.ref = toRef(() => obj[prop]);
+        }
         this.trueISW = new ImmediateStopWatch();
         this.falseISW = new ImmediateStopWatch();
         // prebuild the exception for a more useful stack.
@@ -125,7 +128,7 @@ export class AwaitNot {
                 });
             this.timeout.start();
         }
-        if (this.obj[this.prop] === false && this.couldAlreadyBeFalse) {
+        if (this.ref.value === false && this.couldAlreadyBeFalse) {
             this.waitForTrue();
         } else {
             this.waitForFalse();
@@ -134,14 +137,14 @@ export class AwaitNot {
 
     waitForTrue() {
         this.trueISW.start(
-            () => this.obj[this.prop],
+            this.ref,
             (newValue) => {
                 if (newValue === true) {
                     this.stopTrue();
                     this.waitForFalse();
                 }
             },
-            [this.obj[this.prop]]
+            [this.ref.value]
         );
     }
 
@@ -154,7 +157,7 @@ export class AwaitNot {
 
     waitForFalse() {
         this.falseISW.start(
-            () => this.obj[this.prop],
+            this.ref,
             (newValue) => {
                 if (newValue === false) {
                     this.stop();
@@ -164,7 +167,7 @@ export class AwaitNot {
                     this.cleanPromise();
                 }
             },
-            [this.obj[this.prop]]
+            [this.ref.value]
         );
     }
 
@@ -193,8 +196,8 @@ export class AwaitNot {
     }
 }
 
-export function doAwaitNot({ obj, prop, couldAlreadyBeFalse = true, timeout = 1000 }) {
-    const awaitNot = new AwaitNot({ obj, prop, couldAlreadyBeFalse, timeout });
+export function doAwaitNot({ obj, prop, ref, couldAlreadyBeFalse = true, timeout = 1000 }) {
+    const awaitNot = new AwaitNot({ obj, prop, ref, couldAlreadyBeFalse, timeout });
     awaitNot.start();
     return awaitNot.promise;
 }