@arrai-innovations/reactive-helpers 20.1.2 → 21.0.0

package/types/utils/flattenPathsWithValues.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Get all primitive paths and their corresponding values from an array or object.
+ *
+ * @module utils/flattenPathsWithValues.js
+ */
+/**
+ * Turn an array or object into an array of `[path, value]` pairs (for primitives)
+ * and a list of container paths (for arrays and objects).
+ *
+ * Array indexes are wrapped in square brackets and object keys are prefixed with a period.
+ *
+ * @param {any[] | object} arrayOrObject - Array or object to flatten.
+ * @param {object} [options] - Options.
+ * @param {string} [options.currentPath=""] - Current path, for recursion or as a starting point.
+ * @param {number} [options.depth=0] - Current depth, for recursion.
+ * @param {number} [options.limit=0] - Limit the depth of recursion.
+ * @returns {{
+ *   pathValues: [string, any][],
+ *   containerPaths: string[]
+ * }} - Paths and their corresponding values.
+ */
+export function flattenPathsWithValues(arrayOrObject: any[] | object, { currentPath, depth, limit }?: {
+    currentPath?: string;
+    depth?: number;
+    limit?: number;
+}): {
+    pathValues: [string, any][];
+    containerPaths: string[];
+};

package/types/utils/getFakePk.d.ts

@@ -10,4 +10,3 @@
  * @returns {string} - The fake pk.
  */
 export function getFakePk(arraySetMapOrObject: any[] | Set<any> | Map<any, any> | object, key?: string): string;
-//# sourceMappingURL=getFakePk.d.ts.map

package/types/utils/keepAliveTry.d.ts

@@ -12,4 +12,3 @@ export function tryOnActivated(fn: Function, target?: any): void;
  * @param {any} [target] - The target to call the function on.
  */
 export function tryOnDeactivated(fn: Function, target?: any): void;
-//# sourceMappingURL=keepAliveTry.d.ts.map

package/types/utils/keyDiff.d.ts

@@ -8,23 +8,23 @@
  * Result object of keyDiff and keyDiffDeep.
  *
  * @typedef {object} KeyDiffResult
- * @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.
+ * @property {Set<string>} [sameKeys] - If sameKeys option is true, return keys that are the same.
+ * @property {Set<string>} [removedKeys] - If removedKeys option is true, return keys that are removed.
+ * @property {Set<string>} [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.
  *
- * @param {string[]|Set} newKeys - Keys to consider as new.
- * @param {string[]|Set} oldKeys - Keys to consider as old.
+ * @param {string[]|Set<string>} newKeys - Keys to consider as new.
+ * @param {string[]|Set<string>} oldKeys - Keys to consider as old.
  * @param {object} [options] - Which differences are returned.
  * @param {boolean} [options.sameKeys=true] - If true, return keys that are the same.
  * @param {boolean} [options.removedKeys=true] - If true, return keys that are removed.
  * @param {boolean} [options.addedKeys=true] - If true, return keys that are added.
  * @returns {KeyDiffResult} - The differences.
  */
-export function keyDiff(newKeys: string[] | Set<any>, oldKeys: string[] | Set<any>, { sameKeys, removedKeys, addedKeys }?: {
+export function keyDiff(newKeys: string[] | Set<string>, oldKeys: string[] | Set<string>, { sameKeys, removedKeys, addedKeys }?: {
     sameKeys?: boolean;
     removedKeys?: boolean;
     addedKeys?: boolean;
@@ -50,14 +50,13 @@ export type KeyDiffResult = {
     /**
      * - If sameKeys option is true, return keys that are the same.
      */
-    sameKeys?: Set<any>;
+    sameKeys?: Set<string>;
     /**
      * - If removedKeys option is true, return keys that are removed.
      */
-    removedKeys?: Set<any>;
+    removedKeys?: Set<string>;
     /**
      * - If addedKeys option is true, return keys that are added.
      */
-    addedKeys?: Set<any>;
+    addedKeys?: Set<string>;
 };
-//# sourceMappingURL=keyDiff.d.ts.map

package/types/utils/loadingCombine.d.ts

@@ -6,4 +6,3 @@
  * @returns {boolean | undefined} The combined loading state.
  */
 export function loadingCombine(...loadingStates: (boolean | undefined)[]): boolean | undefined;
-//# sourceMappingURL=loadingCombine.d.ts.map

package/types/utils/proxyRunning.d.ts

@@ -3,7 +3,6 @@
  *
  * @param {import("vue").UnwrapNestedRefs<object>} parentState - The parent state.
  * @param {string} parentStateProp - The parent state property.
- * @param {import("vue").Ref<boolean>} ref - The ref to proxy to.
+ * @param {import("vue").Ref<boolean>} childRef - The ref to proxy to.
  */
-export function proxyRunning(parentState: import("vue").UnwrapNestedRefs<object>, parentStateProp: string, ref: import("vue").Ref<boolean>): void;
-//# sourceMappingURL=proxyRunning.d.ts.map
+export function proxyRunning(parentState: import("vue").UnwrapNestedRefs<object>, parentStateProp: string, childRef: import("vue").Ref<boolean>): void;

package/types/utils/refIfReactive.d.ts

@@ -1,2 +1 @@
 export function refIfReactive<T, K extends keyof T>(source: (T & object) | undefined | null, property: K, defaultValue?: T[K]): import("vue").ComputedRef<T[K]> | import("vue").Ref<T[K]>;
-//# sourceMappingURL=refIfReactive.d.ts.map

package/types/utils/relatedCalculatedHelpers.d.ts

@@ -2,4 +2,3 @@ export const relatedItemRegex: RegExp;
 export const calculatedItemRegex: RegExp;
 export function getObjectRelatedCalculatedByKey(obj: object, relatedObj: object, calculatedObj: object, key: string): [object, string];
 export function getObjectRelatedByKey(obj: object, relatedObj: object, key: string): [object, string];
-//# sourceMappingURL=relatedCalculatedHelpers.d.ts.map

package/types/utils/set.d.ts

@@ -4,4 +4,3 @@ export function intersection(setA: Set<any>, setB: Set<any>): Set<any>;
 export function symmetricDifference(setA: Set<any>, setB: Set<any>): Set<any>;
 export function difference(setA: Set<any>, setB: Set<any>): Set<any>;
 export function equals(setA: Set<any>, setB: Set<any>): boolean;
-//# sourceMappingURL=set.d.ts.map

package/types/utils/transformWalk.d.ts

@@ -1,2 +1 @@
 export function transformWalk(obj: object, transformFn: Function, path?: string): object;
-//# sourceMappingURL=transformWalk.d.ts.map

package/types/utils/unwrapNested.d.ts

@@ -1,2 +1 @@
 export function unwrapNested<T>(arg: T): import("vue").UnwrapRef<T>;
-//# sourceMappingURL=unwrapNested.d.ts.map

package/types/utils/watches.d.ts

@@ -152,4 +152,3 @@ export class AwaitNot {
      */
     stop(): void;
 }
-//# sourceMappingURL=watches.d.ts.map

package/use/cancellableIntent.js

@@ -1,44 +1,101 @@
 import identity from "lodash-es/identity.js";
 import isEmpty from "lodash-es/isEmpty.js";
 import isEqual from "lodash-es/isEqual.js";
-import { computed, effectScope, nextTick, onScopeDispose, reactive, readonly, watch } from "vue";
-import { deepUnref } from "../utils/deepUnref.js";
+import { computed, effectScope, nextTick, onScopeDispose, reactive, readonly, toRef, watch } from "vue";
 import { tryOnActivated, tryOnDeactivated } from "../utils/keepAliveTry.js";
+import { deepUnref } from "vue-deepunref";
+import { useLoadingError } from "./loadingError.js";
 
 /**
  * @module use/cancellableIntent.js - A composable function for handling cancellable intents.
  */
 
+/**
+ * Custom error class for list subscription errors.
+ */
+export class CancellableIntentError extends Error {
+    /**
+     * Creates a new CancellableIntentError.
+     *
+     * @param {string} message - The error message.
+     * @param {string} code - The error code.
+     */
+    constructor(message, code) {
+        super(message);
+        this.name = "CancellableIntentError";
+        this.code = code;
+    }
+}
+
+/**
+ * @typedef {number} RunId - A unique identifier for a single execution ("run") of an intent.
+ * This is incremented each time `watchArguments` change and the intent re-triggers.
+ * Enables distinguishing results or effects from overlapping async runs.
+ */
+
 /**
  * @typedef {object} CancellableIntentRawState - The raw state of the cancellable intent.
- * @property {number|undefined} activeCount - The number of active intents.
- * @property {boolean|undefined} active - Whether there are active intents.
- * @property {number|undefined} resolvingCount - The number of resolving intents.
- * @property {boolean|undefined} resolving - Whether there are resolving intents.
- * @property {boolean} errored - Whether there was an error.
- * @property {Error|null} error - The error that occurred.
+ * @property {import('vue').ComputedRef<boolean>|undefined} active - Whether there are active intents.
+ * @property {import('vue').ComputedRef<boolean>|undefined} resolving - Whether there are resolving intents.
  * @property {boolean} clearActiveOnResolved - Whether to clear the active state when the promise resolves.
+ * @property {RunId|null} lastRunId - The most recent run ID issued for a triggered intent. Useful for associating async results with their originating trigger.
+ * @property {import('vue').DeepReadonly<object>} watchArguments - The watch arguments.
+ * @property {import('vue').DeepReadonly<object>} guardArguments - The guard arguments.
+ */
+
+/**
+ * @typedef {import("vue").Reactive<
+ *     CancellableIntentRawState &
+ *     Pick<import('./error.js').ErrorStatus, 'error' | 'errored'>
+ * >} CancellableIntentState - The state of the cancellable intent.
+ */
+
+/**
+ * @typedef {() => boolean} IsCurrentRunFn - A function that checks if the current run ID matches the last run ID.
+ */
+
+/**
+ * The common run tracking arguments.
+ *
+ * @typedef {object} CommonRunTracking
+ * @property {RunId} runId - The unique identifier for your run.
+ * @property {IsCurrentRunFn} isCurrentRun - A function that checks if the current run ID matches your run ID.
  */
 
 /**
- * @typedef {import("vue").UnwrapNestedRefs<CancellableIntentRawState>} CancellableIntentState - The state of the cancellable intent.
+ * @typedef {(runTracking: CommonRunTracking) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<void>} AwaitableWithCancel - A function that returns a promise that can be cancelled.
+ */
+
+/**
+ * @typedef {import("vue").UnwrapNestedRefs<object>|{[key: string]: import('vue').Ref<any>}} WatchGuardArguments - The reactive object to watch for changes.
  */
 
 /**
  * @typedef {object} CancellableIntentOptions - The options for the cancellable intent.
- * @property {() => import('../utils/cancellablePromise.js').MaybeCancellablePromise<void>} awaitableWithCancel - The function that returns a promise that can be cancelled.
- * @property {import("vue").UnwrapNestedRefs<object>} [watchArguments={}] - The reactive object to watch for changes.
- * @property {import("vue").UnwrapNestedRefs<object>} [guardArguments={}] - The reactive object to watch for truthiness before running the intent.
+ * @property {AwaitableWithCancel} awaitableWithCancel - The function that returns a promise that can be cancelled. Receives the run ID as an argument.
+ * @property {WatchGuardArguments} [watchArguments={}] - The reactive object to watch for changes.
+ * @property {WatchGuardArguments} [guardArguments={}] - The reactive object to watch for truthiness before running the intent.
  * @property {boolean} [clearActiveOnResolved=true] - Whether to clear the active state when the promise resolves.
  */
 
 /**
- * @typedef {object} CancellableIntent - The instance of the cancellable intent.
+ * Cancel function signature for cancellable intent.
+ *
+ * @typedef {Function} CancelFn
+ * @param {any} reason - The reason for cancellation.
+ * @param {boolean} [forceClearActive=false] - Whether to force clear the active state.
+ * @returns {Promise<void>} - A promise that resolves when the cancellation is complete.
+ */
+
+/**
+ * @typedef {object} MyCancellableIntent - The instance of the cancellable intent.
  * @property {CancellableIntentState} state - The state of the cancellable intent.
- * @property {import('vue').UnwrapNestedRefs<object>} watchArguments - The watch arguments.
- * @property {import('vue').UnwrapNestedRefs<object>} guardArguments - The guard arguments.
- * @property {Function} stop - Stop the cancellable intent.
- * @property {Function} cancel - Cancel the cancellable intent.
+ * @property {() => void} stop - Stop the cancellable intent.
+ * @property {CancelFn} cancel - Cancel the cancellable intent.
+ */
+
+/**
+ * @typedef {MyCancellableIntent & Pick<import('./error.js').ErrorStatus, "clearError">} CancellableIntent - The instance of the cancellable intent.
  */
 
 /**
@@ -91,73 +148,100 @@ export function useCancellableIntent({
     if (typeof awaitableWithCancel !== "function") {
         throw new Error("awaitableWithCancel must be a function");
     }
-    const state = reactive(
-        /** @type {CancellableIntentRawState} */
-        {
-            activeCount: undefined, // the active count doesn't mean much when not using clearActiveOnResolved
-            active: undefined,
-            resolvingCount: undefined,
-            resolving: undefined,
-            errored: false,
-            error: null,
-            clearActiveOnResolved,
-        }
-    );
+    const es = effectScope();
+    let myRunId = 0; // each intent has its own namespace of intention session ids
+    const internalState = reactive({
+        watchArguments,
+        guardArguments,
+        activeCount: undefined, // the active count doesn't mean much when not using clearActiveOnResolved
+        resolvingCount: undefined,
+    });
+    const loadingError = es.run(() => useLoadingError());
+    /** @type {CancellableIntentState} */
+    const state = reactive({
+        active: es.run(() =>
+            computed(() => {
+                if (internalState.activeCount === undefined) {
+                    return undefined;
+                }
+                return internalState.activeCount > 0;
+            })
+        ),
+        resolving: es.run(() =>
+            computed(() => {
+                if (internalState.resolvingCount === undefined) {
+                    return undefined;
+                }
+                return internalState.resolvingCount > 0;
+            })
+        ),
+        errored: loadingError.errored,
+        error: loadingError.error,
+        clearActiveOnResolved,
+        lastRunId: null,
+        watchArguments: readonly(internalState.watchArguments),
+        guardArguments: readonly(internalState.guardArguments),
+    });
     let previousWatchValues = null,
         cancelFunction = null;
 
-    const es = effectScope();
-
-    function stop() {
-        // effect scopes are stopped automatically in onUnmounted / a parent onScopeDispose; this is for other use cases
-        es.stop();
-    }
-
-    async function cancel(/** @type {any} */ reason) {
-        if (cancelFunction) {
-            return cancelFunction(reason)
-                .catch(console.error)
-                .finally(() => {
-                    if (!state.clearActiveOnResolved) {
-                        cancelFunction = null;
-                        state.activeCount--;
-                    }
-                });
-        }
-        return false;
-    }
-
     const doIntentWatch = () => {
-        state.errored = false;
-        state.error = null;
-        if (state.activeCount === undefined) {
-            state.activeCount = 0;
+        loadingError.clearError();
+        if (internalState.activeCount === undefined) {
+            internalState.activeCount = 0;
+        }
+        internalState.activeCount += 1;
+        if (internalState.resolvingCount === undefined) {
+            internalState.resolvingCount = 0;
         }
-        state.activeCount += 1;
-        if (state.resolvingCount === undefined) {
-            state.resolvingCount = 0;
+        internalState.resolvingCount += 1;
+        let thisRunId = ++myRunId;
+        state.lastRunId = thisRunId;
+        let awaitablePromise;
+        try {
+            awaitablePromise = awaitableWithCancel({
+                runId: thisRunId,
+                isCurrentRun: () => thisRunId === state.lastRunId,
+            });
+        } catch (error) {
+            // no need to cancel if we throw even before we get a promise
+            loadingError.setError(error);
+            internalState.resolvingCount--;
+            // even if you don't clear active on resolved, we didn't resolve
+            internalState.activeCount--;
+            return;
+        }
+
+        if (!awaitablePromise || typeof awaitablePromise.then !== "function") {
+            loadingError.setError(
+                new CancellableIntentError(
+                    "awaitableWithCancel must return a thenable (Promise-like) object",
+                    "invalid-promise"
+                )
+            );
+            return;
         }
-        state.resolvingCount += 1;
-        let awaitablePromise = awaitableWithCancel();
 
         if (awaitablePromise.cancel) {
             cancelFunction = awaitablePromise.cancel.bind(awaitablePromise);
+        } else {
+            cancelFunction = null;
         }
         // we don't want to await this, because we want to be able to cancel it
         awaitablePromise
-            .catch(async (err) => {
-                await cancel("Error in awaitableWithCancel");
-                console.error(err);
-                state.errored = true;
-                state.error = err;
-                throw err;
-            })
-            .finally(() => {
-                state.resolvingCount--;
+            .then(() => {
                 if (state.clearActiveOnResolved) {
                     cancelFunction = null;
-                    state.activeCount--;
+                    internalState.activeCount--;
                 }
+            })
+            .catch(async (err) => {
+                const cancelPromise = instance.cancel("Error in awaitableWithCancel", true);
+                loadingError.setError(err);
+                await cancelPromise;
+            })
+            .finally(() => {
+                internalState.resolvingCount--;
             });
     };
 
@@ -171,18 +255,18 @@ export function useCancellableIntent({
         runningIntentWatch = true;
         // this locked section is to deal with multiple intentWatches running while waiting for cancel to resolve
         try {
-            let newWatchValues = deepUnref(Object.values(watchArguments));
+            let newWatchValues = Object.values(deepUnref(internalState.watchArguments));
             if (isEqual(newWatchValues, previousWatchValues)) {
                 return;
             }
-            await cancel("Intent watch cancelled"); // this can take time so guards and watches can change!
-            newWatchValues = deepUnref(Object.values(watchArguments));
+            await instance.cancel("Intent watch cancelled"); // this can take time so guards and watches can change!
+            newWatchValues = Object.values(deepUnref(internalState.watchArguments));
             if (isEqual(newWatchValues, previousWatchValues)) {
                 return;
             }
             previousWatchValues = newWatchValues;
-            const guardValues = deepUnref(Object.values(guardArguments));
-            if (Object.values(newWatchValues).every(identity)) {
+            const guardValues = Object.values(deepUnref(internalState.guardArguments));
+            if (newWatchValues.every(identity)) {
                 // if any guards are true, delay the watch.
                 if (guardValues && !isEmpty(guardValues) && guardValues.some(identity)) {
                     delayedWatch = doIntentWatch;
@@ -203,7 +287,7 @@ export function useCancellableIntent({
     const guardWatch = () => {
         if (delayedWatch) {
             // if all guards are false, run the watch
-            if (Object.values(guardArguments).every((x) => !x)) {
+            if (!Object.values(deepUnref(guardArguments)).some(identity)) {
                 const myDelayedWatch = delayedWatch;
                 delayedWatch = null;
                 myDelayedWatch();
@@ -214,7 +298,7 @@ export function useCancellableIntent({
     const cleanup = () => {
         // cancel the intent when the component is deactivated
         // noinspection JSIgnoredPromiseFromCall
-        cancel("Component deactivated");
+        instance.cancel("Component deactivated");
         if (state.clearActiveOnResolved) {
             // otherwise it clears when resolved
             cancelFunction = null;
@@ -223,33 +307,38 @@ export function useCancellableIntent({
         previousWatchValues = null;
     };
 
-    es.run(() => {
-        state.active = computed(() => {
-            if (state.activeCount === undefined) {
-                return undefined;
-            }
-            return state.activeCount > 0;
-        });
-        state.resolving = computed(() => {
-            if (state.resolvingCount === undefined) {
-                return undefined;
+    /** @type {CancellableIntent} */
+    const instance = {
+        state,
+        // effect scopes are stopped automatically in onUnmounted / a parent onScopeDispose; this is for other use cases
+        stop: () => es.stop(),
+        cancel: async (/** @type {any} */ reason, forceClearActive = false) => {
+            if (cancelFunction) {
+                const toCancel = cancelFunction;
+                cancelFunction = null;
+                if (!state.clearActiveOnResolved || forceClearActive) {
+                    internalState.activeCount--;
+                }
+                return toCancel(reason).catch(console.error);
             }
-            return state.resolvingCount > 0;
-        });
-
-        watch(() => Object.values(watchArguments), intentWatch, {
+            return false;
+        },
+        clearError: loadingError.clearError,
+    };
+    es.run(() => {
+        watch(toRef(internalState, "watchArguments"), intentWatch, {
             // this can't be immediate because subscribe wants to look at our state, which won't exist yet.
             deep: true,
         });
 
-        watch(() => Object.values(guardArguments), guardWatch, {
+        watch(toRef(internalState, "guardArguments"), guardWatch, {
             // we can't possibly have a delayed watch immediately
             deep: true,
         });
 
         tryOnActivated(() => {
-            state.activeCount = 0;
-            state.resolvingCount = 0;
+            internalState.activeCount = 0;
+            internalState.resolvingCount = 0;
             // trigger the intent watch manually to get current watch values
             // noinspection JSIgnoredPromiseFromCall
             intentWatch();
@@ -257,13 +346,9 @@ export function useCancellableIntent({
         tryOnDeactivated(cleanup);
         onScopeDispose(cleanup);
 
+        // intentWatch can't be immediate because subscribe wants to look at our state, which won't exist yet.
+        // but we do want to run immediately-ish
         nextTick().then(intentWatch);
     });
-    return {
-        state,
-        watchArguments: readonly(watchArguments),
-        guardArguments: readonly(guardArguments),
-        stop,
-        cancel,
-    };
+    return instance;
 }

package/use/error.js

@@ -0,0 +1,44 @@
+import { readonly, ref } from "vue";
+
+/**
+ * @typedef {() => void} ClearErrorFn
+ * @typedef {import("vue").Ref<Error|null>} ErrorRef
+ * @typedef {import("vue").Ref<boolean>} ErroredRef
+ * @typedef {Readonly<ErrorRef>} ErrorReadonlyRef
+ * @typedef {Readonly<ErroredRef>} ErroredReadonlyRef
+ */
+
+/**
+ * The error state API.
+ *
+ * @typedef {object} ErrorStatus
+ * @property {ErrorReadonlyRef} error - The error that occurred.
+ * @property {ErroredReadonlyRef} errored - Whether an error has occurred.
+ * @property {(error: Error) => void} setError - Set the error state.
+ * @property {ClearErrorFn} clearError - Clear the error state.
+ */
+
+/**
+ * A composable function for managing error state.
+ *
+ * @returns {ErrorStatus} - An object containing reactive fields and actions for error state.
+ */
+export function useError() {
+    /** @type {ErrorRef} */
+    const error = ref(null);
+    /** @type {ErroredRef} */
+    const errored = ref(false);
+
+    return {
+        error: readonly(error),
+        errored: readonly(errored),
+        setError: (e) => {
+            error.value = e;
+            errored.value = true;
+        },
+        clearError: () => {
+            error.value = null;
+            errored.value = false;
+        },
+    };
+}