@arrai-innovations/reactive-helpers 18.0.2 → 19.0.0

package/use/objectSubscription.js

@@ -2,8 +2,9 @@ import { assignReactiveObject } from "../utils/assignReactiveObject.js";
 import { loadingCombine } from "../utils/loadingCombine.js";
 import { useCancellableIntent } from "./cancellableIntent.js";
 import { useLoadingError } from "./loadingError.js";
-import { useObjectInstance, objectInstanceStateKeys } from "./objectInstance.js";
-import { computed, effectScope, reactive, toRef } from "vue";
+import { useObjectInstance } from "./objectInstance.js";
+import { computed, effectScope, reactive, ref, toRef, toRefs } from "vue";
+import { CancellablePromise } from "../utils/cancellablePromise.js";
 
 /**
  * A composition function for managing object subscriptions, including subscription status, errors, and reactivity.
@@ -49,38 +50,39 @@ export const objectSubscriptionFunctions = [
  * The raw state of the object subscription.
  *
  * @typedef {object} ObjectSubscriptionRawState
- * @property {Readonly<import('vue').Ref<boolean>>} subscriptionLoading - Whether the subscription is loading.
- * @property {Readonly<import('vue').Ref<boolean>>} subscriptionErrored - Whether the subscription has errored.
- * @property {Readonly<import('vue').Ref<Error>>} subscriptionError - The error that occurred.
- * @property {boolean} intendToRetrieve - Whether the object intends to retrieve.
- * @property {boolean} intendToSubscribe - Whether the object intends to subscribe.
- * @property {boolean} subscribed - Whether the object is subscribed.
+ * @property {import('./loadingError.js').LoadingReadonlyRef} subscriptionLoading - Whether the subscription is loading.
+ * @property {import('./loadingError.js').ErroredReadonlyRef} subscriptionErrored - Whether the subscription has errored.
+ * @property {import('./loadingError.js').ErrorReadonlyRef} subscriptionError - The error that occurred.
+ * @property {import('vue').Ref<boolean>} intendToRetrieve - Whether the object intends to retrieve.
+ * @property {import('vue').Ref<boolean>} intendToSubscribe - Whether the object intends to subscribe.
+ * @property {import('vue').Ref<boolean|undefined>} subscribed - Whether the object is subscribed.
  */
 
 /**
  * The state of the object subscription, including both subscription and object instance states.
  *
- * @typedef {import('vue').UnwrapNestedRefs<
+ * @typedef {import('vue').Reactive<
  *     ObjectSubscriptionRawState &
  *     import('./objectInstance.js').ObjectInstanceRawState
  * >} ObjectSubscriptionState
  */
 
-/* eslint-disable jsdoc/valid-types -- the subscribe function signature is valid typescript that irks eslint-plugin-jsdoc */
 /**
  * Functions available for object subscription management.
  *
  * @typedef {object} ObjectSubscriptionFunctions
- * @property {({ retrieve }?: { retrieve?: boolean }) => boolean} subscribe - Subscribes to updates from an object, managing subscription state and
- *  handling errors internally. Ensures that only one active subscription can exist at a time to prevent duplicate
- *  calls. Returns a promise that resolves to true if the subscription was successful, and false if it failed.
+ * @property {(
+ *     (options?: { retrieve?: boolean }) => boolean
+ * )} subscribe - Subscribes to updates from an object, managing subscription state and handling errors internally.
+ *  Ensures that only one active subscription can exist at a time to prevent duplicate calls. Returns a promise that
+ *  resolves to true if the subscription was successful, and false if it failed.
  * @property {() => boolean} unsubscribe - Unsubscribes from the object, resetting related state flags. Returns
  *  true if the object was unsubscribed, and false if it was not subscribed.
- * @property {(data: import('./objectInstance.js').CrudObject) => void} updateFromSubscription - Update the object from a subscription.
+ * @property {(data: import('./objectInstance.js').ExistingCrudObject) => void} updateFromSubscription - Update the
+ *  object from a subscription.
  * @property {() => void} deleteFromSubscription - Delete the object from a subscription.
  * @property {() => void} clearError - Clears any errors related to the subscription, and resets the loading state.
  */
-/* eslint-enable jsdoc/valid-types */
 
 /**
  * Properties of the object subscription.
@@ -103,8 +105,8 @@ export const objectSubscriptionFunctions = [
  * Raw props for the object subscription.
  *
  * @typedef {object} ObjectSubscriptionRawProps
- * @property {boolean} [intendToRetrieve] - Whether the object intends to retrieve.
- * @property {boolean} [intendToSubscribe] - Whether the object intends to subscribe.
+ * @property {boolean|undefined} intendToRetrieve - Whether the object intends to retrieve.
+ * @property {boolean|undefined} intendToSubscribe - Whether the object intends to subscribe.
  */
 
 /**
@@ -204,33 +206,42 @@ export function useObjectSubscription({ objectInstance, props, functions }) {
             );
         }
     }
+
+    const es = effectScope();
     const parentState = objectInstance.state;
     const loadingError = useLoadingError();
+    const {
+        crud: parentCrud,
+        pk: parentPk,
+        pkKey: parentPkKey,
+        retrieveArgs: parentRetrieveArgs,
+        object: parentObject,
+        deleted: parentDeleted,
+    } = toRefs(parentState);
     /** @type {ObjectSubscriptionState} */
-    // @ts-ignore - we're going to assign all the keys later, and in the effect scope
     const state = reactive({
+        crud: parentCrud,
+        pk: parentPk,
+        pkKey: parentPkKey,
+        retrieveArgs: parentRetrieveArgs,
+        object: parentObject,
+        deleted: parentDeleted,
         subscriptionLoading: loadingError.loading,
         subscriptionErrored: loadingError.errored,
         subscriptionError: loadingError.error,
-        subscribed: undefined,
-        intendToSubscribe: false,
-        intendToRetrieve: false,
+        subscribed: ref(undefined),
+        intendToSubscribe: "intendToSubscribe" in props ? toRef(props, "intendToSubscribe") : ref(false),
+        intendToRetrieve: "intendToRetrieve" in props ? toRef(props, "intendToRetrieve") : ref(false),
+        loading: es.run(() => computed(() => loadingCombine(parentState.loading, state.subscriptionLoading))),
+        errored: es.run(() => computed(() => parentState.errored || state.subscriptionErrored)),
+        error: es.run(() => computed(() => parentState.error || state.subscriptionError)),
     });
-    if ("intendToRetrieve" in props) {
-        // @ts-ignore - passing Ref<boolean> to boolean in an UnwrapNestedRefs is fine
-        state.intendToRetrieve = toRef(props, "intendToRetrieve");
-    }
-    if ("intendToSubscribe" in props) {
-        // @ts-ignore - passing Ref<boolean> to boolean in an UnwrapNestedRefs is fine
-        state.intendToSubscribe = toRef(props, "intendToSubscribe");
-    }
-
     /** @type {import('./cancellableIntent.js').CancellableIntent} */
     let subscribeIntent;
     /** @type {import('./cancellableIntent.js').CancellableIntent} */
     let retrieveIntent;
 
-    function updateFromSubscription(data) {
+    function updateFromSubscription(/** @type {import('./objectInstance.js').ExistingCrudObject} */ data) {
         assignReactiveObject(parentState.object, data);
     }
 
@@ -257,55 +268,56 @@ export function useObjectSubscription({ objectInstance, props, functions }) {
     function subscribe() {
         // this function cannot be async, or the resulting promise will lose its .cancel() method
         if (state.subscribed) {
-            return Promise.reject(
-                new ObjectSubscriptionError("already subscribed or subscribing.", "already-subscribed")
-            );
+            // we throw because we want devs to see this error in the console
+            // state.error should be for user facing errors, or unknown errors
+            throw new ObjectSubscriptionError("already subscribed or subscribing.", "already-subscribed");
         }
         loadingError.clearError();
         loadingError.setLoading();
-        let subscribePromise;
-        subscribePromise = parentState.crud.subscribe({
+        const isCancelled = ref(false);
+        /** @type {import('../config/objectCrud.js').CrudSubscribeCallback} */
+        const subscribeCallback = (data, action) => {
+            if (action === "delete") {
+                objectInstance.deleteFromSubscription();
+            } else {
+                objectInstance.updateFromSubscription(data);
+            }
+        };
+        const subscribePromise = parentState.crud.subscribe({
             crudArgs: parentState.crud.args,
             pk: parentState.pk,
             pkKey: parentState.pkKey,
             retrieveArgs: state.retrieveArgs,
-            callback: (data, action) => {
-                if (action === "delete") {
-                    objectInstance.deleteFromSubscription();
-                } else {
-                    objectInstance.updateFromSubscription(data);
-                }
-            },
+            callback: subscribeCallback,
+            isCancelled,
         });
-        let cancelSubscription = async () => {
-            let cancelPromise = subscribePromise.cancel();
+        let cancelSubscription = async (/** @type {any} */ reason) => {
+            let cancelPromise = subscribePromise.cancel(reason);
             cancelSubscription = null;
             state.subscribed = false;
             return cancelPromise;
         };
-        // then/catch/finally makes a new promise, we need to make sure the cancel method lives on.
-        const catchPromise = subscribePromise
-            .then(() => {
-                state.subscribed = true;
-                return Promise.resolve(true);
-            })
-            .catch((error) => {
-                loadingError.setError(error);
-                if (cancelSubscription) {
-                    cancelSubscription();
-                    cancelSubscription = null;
-                    state.subscribed = false;
-                }
-                return Promise.resolve(false);
-            })
-            .finally(() => {
-                loadingError.clearLoading();
-                if (!state.subscribed) {
-                    subscribePromise = null;
-                }
-            });
-        catchPromise.cancel = cancelSubscription;
-        return catchPromise;
+        return CancellablePromise(
+            subscribePromise
+                .then(() => {
+                    state.subscribed = true;
+                    return true;
+                })
+                .catch((/** @type {Error} */ error) => {
+                    loadingError.setError(error);
+                    if (cancelSubscription) {
+                        // noinspection JSIgnoredPromiseFromCall
+                        cancelSubscription("Subscription error cancellation");
+                        cancelSubscription = null;
+                        state.subscribed = false;
+                    }
+                    return false;
+                })
+                .finally(() => {
+                    loadingError.clearLoading();
+                }),
+            cancelSubscription
+        );
     }
 
     function publicUnsubscribe() {
@@ -326,20 +338,7 @@ export function useObjectSubscription({ objectInstance, props, functions }) {
         objectInstance.clearError();
     }
 
-    const es = effectScope();
-
     es.run(() => {
-        // @ts-ignore - loadingCombine returns a boolean|undefined, our state loading is a boolean|undefined... should be fine
-        state.loading = computed(() => loadingCombine(parentState.loading, state.subscriptionLoading));
-        // @ts-ignore - the computed value is a boolean, our state errored is a boolean... should be fine
-        state.errored = computed(() => parentState.errored || state.subscriptionErrored);
-        // @ts-ignore - the computed value is an Error|undefined, our state error is an Error|undefined... should be fine
-        state.error = computed(() => parentState.error || state.subscriptionError);
-
-        for (const key of objectInstanceStateKeys.filter((key) => !["loading", "errored", "error"].includes(key))) {
-            state[key] = toRef(parentState, key);
-        }
-
         subscribeIntent = useCancellableIntent({
             awaitableWithCancel: subscribe,
             watchArguments: reactive({
@@ -359,7 +358,7 @@ export function useObjectSubscription({ objectInstance, props, functions }) {
                 pkKey: toRef(parentState, "pkKey"),
                 retrieveArgs: toRef(parentState, "retrieveArgs"),
             }),
-            // delay triggering a retrieve until the last retrieve has finished/cancelled
+            // delay triggering a retrieve until the last retrieve has finished/cancelled.
             // cancel can still be triggered
             guardArguments: reactive({
                 loading: toRef(state, "loading"),

package/use/proxyLoadingError.js

@@ -1,51 +1,38 @@
 import { computed, readonly, unref } from "vue";
 import { loadingCombine } from "../utils/loadingCombine.js";
-
-/**
- * @typedef {(
- *     import('./loadingError.js').LoadingErrorStatus[]
- * )} WatchableLoadingErrorsRaw
- */
+import identity from "lodash-es/identity.js";
 
 /**
  * A watchable collection of loading errors.
  *
  * @typedef {(
- *     import('vue').UnwrapNestedRefs<WatchableLoadingErrorsRaw> |
- *     import('vue').Ref<WatchableLoadingErrorsRaw> |
- *     WatchableLoadingErrorsRaw
- * )} WatchableLoadingErrors
- */
-
-/**
- * The instance of useProxyLoadingError.
- *
- * @typedef {import('./loadingError.js').LoadingErrorStatus} ProxyLoadingError
+ *     import('vue').UnwrapNestedRefs<import('./loadingError.js').LoadingErrorStatus> |
+ *     import('vue').Ref<import('./loadingError.js').LoadingErrorStatus> |
+ *     import('./loadingError.js').LoadingErrorStatus
+ * )} WatchableLoadingError
  */
 
 /**
  * A composable function for managing aggregated loading and error states across multiple sources.
  *
- * @param {WatchableLoadingErrors} loadingErrors - A collection of loading error statuses to monitor and aggregate.
- * @returns {ProxyLoadingError} An object containing aggregated reactive fields and actions for loading and error states.
+ * @param {WatchableLoadingError[]} loadingErrors - A collection of loading error statuses to monitor and aggregate.
+ * @returns {import('./loadingError.js').LoadingErrorStatus} An object containing aggregated reactive fields and actions for loading and error states.
  */
 export function useProxyLoadingError(loadingErrors) {
-    /** @type {import("vue").ComputedRef<boolean|undefined>} */
     const loading = computed(() =>
-        loadingCombine(...unref(loadingErrors).map((loadingError) => unref(loadingError.loading)))
+        loadingCombine(...unref(loadingErrors).map((loadingError) => unref(unref(loadingError).loading)))
     );
-    /** @type {import("vue").ComputedRef<Error|null>} */
     const error = computed(
         () =>
+            /** @type {Error|null} */
             unref(loadingErrors)
-                .map((loadingError) => unref(loadingError.error))
-                .find((error) => error) || null
+                .map((loadingError) => unref(unref(loadingError).error))
+                .find(identity) || null
     );
-    /** @type {import("vue").ComputedRef<boolean>} */
     const errored = computed(() =>
         unref(loadingErrors)
-            .map((loadingError) => unref(loadingError.errored))
-            .some((errored) => errored)
+            .map((loadingError) => unref(unref(loadingError).errored))
+            .some(identity)
     );
 
     return {
@@ -53,7 +40,7 @@ export function useProxyLoadingError(loadingErrors) {
         error: readonly(error),
         errored: readonly(errored),
         clearError: () => {
-            unref(loadingErrors).forEach((loadingError) => loadingError.clearError());
+            unref(loadingErrors).forEach((loadingError) => unref(loadingError).clearError());
         },
     };
 }

package/use/search.js

@@ -4,7 +4,7 @@ import FlexSearch from "flexsearch";
 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";
+import { deepUnref } from "../utils/deepUnref.js";
 
 /* minimize new Set() allocations */
 const unionReduce = (accumulator, currentValue) => {

package/utils/cancellableFetch.js

@@ -0,0 +1,22 @@
+import { CancellablePromise } from "./cancellablePromise.js";
+
+/**
+ * A wrapper around fetch that adds cancellation via AbortController and returns a CancellablePromise.
+ *
+ * @template T
+ * @param {RequestInfo} input - The URL or Request object to fetch.
+ * @param {RequestInit} init - The options for the fetch request.
+ * @param {(response: Response) => Promise<T>} transform - A function to transform the response.
+ * @returns {CancellablePromise<T>} A cancellable promise that resolves to the transformed response.
+ */
+export function cancellableFetch(input, init, transform) {
+    const controller = new AbortController();
+    const signal = controller.signal;
+
+    const basePromise = fetch(input, { ...init, signal }).then(transform);
+
+    return CancellablePromise(basePromise, async (/** @type {any} */ reason) => {
+        controller.abort(reason);
+        await basePromise.catch(() => {});
+    });
+}

package/utils/cancellablePromise.js

@@ -0,0 +1,70 @@
+/**
+ * A Promise that can be cancelled.
+ *
+ * @template T
+ * @typedef {Promise<T> & { cancel: (reason?: any) => Promise<void> | void }} CancellablePromise
+ */
+
+/**
+ * A possibly cancellable promise.
+ *
+ * @template T
+ * @typedef {Promise<T> & { cancel?: (reason?: any) => Promise<void> | void }} MaybeCancellablePromise
+ */
+
+/**
+ * Creates a cancellable promise, mostly for easy of type checking.
+ *
+ * @template T
+ * @param {Promise<T>} promise - The promise to be cancellable.
+ * @param {() => (Promise<void>|void)} cancel - The function to cancel the promise.
+ * @returns {CancellablePromise<T>} The cancellable promise.
+ */
+export const CancellablePromise = (promise, cancel) => {
+    const cancellablePromise = /** @type {CancellablePromise<T>} */ (promise);
+    cancellablePromise.cancel = cancel;
+    return cancellablePromise;
+};
+
+/**
+ * Creates a rejected 'cancellable' promise.
+ *
+ * @param {any} reason - The reason for the rejection.
+ * @returns {MaybeCancellablePromise<never>} A rejected 'cancellable' promise.
+ */
+CancellablePromise.reject = (reason) => {
+    return Promise.reject(reason);
+};
+
+/**
+ * Creates a resolved 'cancellable' promise.
+ *
+ * @template T
+ * @param {T} value - The value to resolve the promise with.
+ * @returns {MaybeCancellablePromise<T>} A resolved 'cancellable' promise.
+ */
+CancellablePromise.resolve = (value) => {
+    return Promise.resolve(value);
+};
+
+/**
+ * Wraps a promise and optionally adds a cancel method if provided.
+ *
+ * @template T
+ * @param {Promise<T>} inner - The inner promise to wrap.
+ * @param {(() => Promise<void> | void)=} cancel - Optional cancel function.
+ * @returns {MaybeCancellablePromise<T>} The wrapped promise with an optional cancel method.
+ */
+export function wrapMaybeCancellable(inner, cancel) {
+    let resolve, reject;
+    /** @type {MaybeCancellablePromise<T>} */
+    const wrapped = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    if (cancel) {
+        wrapped.cancel = cancel;
+    }
+    inner.then(resolve).catch(reject);
+    return wrapped;
+}

package/utils/classes.js

@@ -122,12 +122,12 @@ export const objectifyClasses = (...classes) => {
  * @returns {CombinedClasses} - The normalized form of the CSS classes, either as a string or an object.
  */
 export const combineClasses = (...classes) => {
-    const rawClasses = deepUnrefFlatten(classes);
-    const flattenedClasses = rawClasses.flat(Infinity);
-    const filteredClasses = flattenedClasses.filter(identity);
-    const hasStrings = filteredClasses.some(isString);
+    const filteredClasses = deepUnrefFlatten(classes).flat(Infinity).filter(identity);
+    if (filteredClasses.every(isString)) {
+        return filteredClasses.join(" ");
+    }
     const hasObjects = filteredClasses.some(isObject);
-    if (hasStrings && !hasObjects) {
+    if (!hasObjects) {
         return stringifyClasses(...filteredClasses);
     }
     const result = objectifyClasses(...filteredClasses);

package/utils/deepUnref.js

@@ -0,0 +1,28 @@
+import { deepUnref as _deepUnref } from "vue-deepunref";
+
+/* eslint-disable jsdoc/valid-types */
+
+/**
+ * Recursively unwraps refs from a nested object, array, or primitive.
+ *
+ * @template T
+ * @typedef {T extends import('vue').Ref<infer U>
+ *   ? DeepUnwrap<U>
+ *   : T extends Array<infer V>
+ *     ? Array<DeepUnwrap<V>>
+ *     : T extends object
+ *       ? { [K in keyof T]: DeepUnwrap<T[K]> }
+ *       : T
+ * } DeepUnwrap
+ */
+
+/* eslint-enable jsdoc/valid-types */
+
+/**
+ * Safe, recursively-typed deep unref.
+ *
+ * @template T
+ * @param {T} val - The value to deeply unwrap.
+ * @returns {DeepUnwrap<T>} - The deeply unwrapped value.
+ */
+export const deepUnref = _deepUnref;

package/utils/refIfReactive.js

@@ -0,0 +1,18 @@
+import { isReactive, toRef, unref } from "vue";
+
+/**
+ * Returns a ref to a property if the source is reactive, otherwise returns the unrefed value.
+ *
+ * @template T
+ * @template {keyof T} K
+ * @param {T & object | undefined | null} source - The source object.
+ * @param {K} property - The property to access.
+ * @param {T[K]} [defaultValue] - The default value to use if source or property is missing.
+ * @returns {import('vue').Ref<T[K]> | T[K] | undefined} The ref to the property if the source is reactive, otherwise the unrefed value.
+ */
+export const refIfReactive = (source, property, defaultValue) => {
+    if (source && isReactive(source)) {
+        return toRef(source, property);
+    }
+    return unref(source?.[property]) ?? defaultValue;
+};

package/utils/unwrapNested.js

@@ -0,0 +1,25 @@
+import { isProxy, isReactive, isRef, toRaw, unref } from "vue";
+
+/**
+ * Unwraps Vue refs and proxies to get the raw value.
+ *
+ * @template T
+ * @param {T} arg - The argument to unwrap.
+ * @returns {import('vue').UnwrapRef<T>} The unwrapped value.
+ */
+export const unwrapNested = (arg) => {
+    /** @type {unknown} */
+    let key = arg;
+    let proxied = isProxy(arg) || isReactive(arg);
+    let refed = isRef(arg);
+    while (proxied || refed) {
+        if (proxied) {
+            key = toRaw(key);
+        } else if (refed) {
+            key = unref(key);
+        }
+        proxied = isProxy(key);
+        refed = isRef(key);
+    }
+    return /** @type {import('vue').UnwrapRef<T>} */ (key);
+};