@arrai-innovations/reactive-helpers 18.0.2 → 18.1.0

package/types/utils/deepUnref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepUnref.d.ts","sourceRoot":"","sources":["../../utils/deepUnref.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAIH;;;;;;GAMG;AACH,4BAAoC;;;;8BAnBvB,GAAC,SAAS,OAAO,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GAC1C,UAAU,CAAC,CAAC,CAAC,GACb,GAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GACtB,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GACpB,GAAC,SAAS,MAAM,GACd,GAAG,CAAC,IAAI,MAAM,GAAC,GAAG,UAAU,CAAC,GAAC,CAAC,CAAC,CAAC,CAAC,GAAE,GACpC,GAAC"}

package/use/cancellableIntent.js

@@ -2,19 +2,13 @@ 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 "vue-deepunref";
+import { deepUnref } from "../utils/deepUnref.js";
 import { tryOnActivated, tryOnDeactivated } from "../utils/keepAliveTry.js";
 
 /**
  * @module use/cancellableIntent.js - A composable function for handling cancellable intents.
  */
 
-/**
- * A Promise that can be cancelled.
- *
- * @typedef {Promise<any> & { cancel: () => Promise<void>|void }} CancellablePromise
- */
-
 /**
  * @typedef {import("vue").UnwrapNestedRefs<object>} CancellableIntentState - The state of the cancellable intent.
  * @property {number} activeCount - The number of active intents.
@@ -28,7 +22,7 @@ import { tryOnActivated, tryOnDeactivated } from "../utils/keepAliveTry.js";
 
 /**
  * @typedef {object} CancellableIntentOptions - The options for the cancellable intent.
- * @property {() => CancellablePromise} awaitableWithCancel - The function that returns a promise that can be cancelled.
+ * @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 {boolean} [clearActiveOnResolved=true] - Whether to clear the active state when the promise resolves.
@@ -112,9 +106,9 @@ export function useCancellableIntent({
         es.stop();
     }
 
-    async function cancel() {
+    async function cancel(reason) {
         if (cancelFunction) {
-            return cancelFunction()
+            return cancelFunction(reason)
                 .catch(console.error)
                 .finally(() => {
                     if (!state.clearActiveOnResolved) {
@@ -145,7 +139,7 @@ export function useCancellableIntent({
         // we don't want to await this, because we want to be able to cancel it
         awaitablePromise
             .catch(async (err) => {
-                await cancel();
+                await cancel("Error in awaitableWithCancel");
                 console.error(err);
                 state.errored = true;
                 state.error = err;
@@ -174,7 +168,7 @@ export function useCancellableIntent({
             if (isEqual(newWatchValues, previousWatchValues)) {
                 return;
             }
-            await cancel(); // this can take time so guards and watches can change!
+            await cancel("Intent watch cancelled"); // this can take time so guards and watches can change!
             newWatchValues = deepUnref(Object.values(watchArguments));
             if (isEqual(newWatchValues, previousWatchValues)) {
                 return;
@@ -212,7 +206,8 @@ export function useCancellableIntent({
 
     const cleanup = () => {
         // cancel the intent when the component is deactivated
-        cancel();
+        // noinspection JSIgnoredPromiseFromCall
+        cancel("Component deactivated");
         if (state.clearActiveOnResolved) {
             // otherwise it clears when resolved
             cancelFunction = null;

package/use/listInstance.js

@@ -4,6 +4,7 @@ import { getFakePk } from "../utils/getFakePk.js";
 import { useLoadingError } from "./loadingError.js";
 import inspect from "browser-util-inspect";
 import { computed, effectScope, nextTick, reactive, readonly, ref, toRef, unref, watch } from "vue";
+import { CancellablePromise, wrapMaybeCancellable } from "../utils/cancellablePromise.js";
 
 /**
  * A composable function for managing a list of objects.
@@ -117,7 +118,7 @@ export class ListInstanceError extends Error {
  * @property {(objectId: string) => void} deleteListObject - Deletes an object from the list by pk.
  * @property {() => void} clearList - Clears all objects and errors from the list.
  * @property {() => string} getFakePk - Generates a unique fake pk for use within the list.
- * @property {() => Promise<boolean>} list - Initiates a fetch to retrieve objects according to the CRUD configuration, returning a promise to a boolean indicating success.
+ * @property {() => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} list - Initiates a fetch to retrieve objects according to the CRUD configuration, returning a promise to a boolean indicating success.
  * @property {() => Promise<boolean>} bulkDelete - Initiates a bulk delete operation on all objects in the list, returning a promise to a boolean indicating success.
  * @property {() => Promise<object|string|false>} executeAction - Initiates an action on all objects in the list, returning the response, or false if the action failed.
  */
@@ -286,7 +287,7 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
 
     getListCrud(state.crud, { props, functions });
 
-    const defaultPageCallback = (newObjects) => {
+    const defaultPageCallback = (/** @type {ListObject[]} */ newObjects) => {
         // with keepOldPages, you are responsible for clearing the list as needed
         if (!keepOldPages) {
             // display one page at a time, clear the list
@@ -301,7 +302,7 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
         });
     };
 
-    /** @type {{[key: string]: import('./cancellableIntent.js').CancellablePromise|null}} */
+    /** @type {{[key: string]: import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean>|null}} */
     const promises = {
         list: null,
     };
@@ -323,7 +324,7 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
                 loadingError.clearError();
                 return Promise.resolve(true);
             })
-            .catch((error) => {
+            .catch((/** @type {Error} */ error) => {
                 loadingError.setError(error);
                 return Promise.resolve(false);
             })
@@ -344,11 +345,11 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
                 pks: Object.keys(state.objects).map(Number),
                 pkKey: state.pkKey,
             })
-            .then((responseData) => {
+            .then((/** @type {any} */ responseData) => {
                 loadingError.clearError();
                 return Promise.resolve(responseData);
             })
-            .catch((error) => {
+            .catch((/** @type {Error} */ error) => {
                 loadingError.setError(error);
                 return Promise.resolve(false);
             })
@@ -357,6 +358,12 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
             });
     }
 
+    /**
+     * Fetches a list of objects from the server, using the configured CRUD operations and arguments.
+     *
+     * @throws {ListInstanceError} If the list is already loading.
+     * @returns {import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} A promise that resolves to true if the list was successfully retrieved, or false if an error occurred.
+     */
     function list() {
         // this function cannot be async, or the resulting promise will lose its .cancel() method
         if (promises.list) {
@@ -364,13 +371,8 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
             return promises.list;
         }
         if (state.loading) {
-            return Promise.reject(new ListInstanceError("already loading.", "already-loading"));
+            return CancellablePromise.reject(new ListInstanceError("already loading.", "already-loading"));
         }
-        let returnPromiseResolve;
-        // @ts-ignore - we are setting this in the promise
-        promises.list = /** @type {import('./cancellableIntent.js').CancellablePromise} */ new Promise(
-            (resolve) => (returnPromiseResolve = resolve)
-        );
         loadingError.clearError();
         loadingError.setLoading();
         const isCancelled = ref(false);
@@ -382,35 +384,31 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
             pageCallback: returnedObject.pageCallback,
             isCancelled: readonly(isCancelled),
         });
-
-        let resolveState = false;
-        if (listPromise.cancel) {
-            promises.list.cancel = async () => {
-                let promise = listPromise.cancel();
-                isCancelled.value = true;
-                if (promise) {
-                    await promise;
-                }
-                loadingError.clearLoading();
-            };
-        }
-        // the indirection of promises here is to allow us to do additional work on listPromise's cancel
-        listPromise
-            .then(() => {
-                resolveState = true;
-            })
-            .catch((error) => {
-                loadingError.setError(error);
-            })
-            .finally(() => {
-                loadingError.clearLoading();
-                returnPromiseResolve(resolveState);
-                promises.list = null;
-            });
+        promises.list = wrapMaybeCancellable(
+            listPromise
+                .then(() => {
+                    return true;
+                })
+                .catch((/** @type {Error} */ error) => {
+                    loadingError.setError(error);
+                    return false;
+                })
+                .finally(() => {
+                    loadingError.clearLoading();
+                    promises.list = null;
+                }),
+            listPromise.cancel
+                ? async (/** @type {any} */ reason) => {
+                      isCancelled.value = true;
+                      await listPromise.cancel?.(reason);
+                      loadingError.clearLoading();
+                  }
+                : undefined
+        );
         return promises.list;
     }
 
-    function addListObject(object) {
+    function addListObject(/** @type {ListObject} */ object) {
         if (!object[state.pkKey]) {
             throw new ListInstanceError(
                 `addListObject: object missing pk(${state.pkKey}).\n${inspect(object)}`,
@@ -429,7 +427,7 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
         }
     }
 
-    function updateListObject(object) {
+    function updateListObject(/** @type {ListObject} */ object) {
         if (!object[state.pkKey]) {
             throw new ListInstanceError(
                 `updateListObject: object missing pk(${state.pkKey}).\n${inspect(object)}`,
@@ -448,7 +446,7 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
         }
     }
 
-    function deleteListObject(pk) {
+    function deleteListObject(/** @type {string} */ pk) {
         if (!(pk in state.objects)) {
             throw new ListInstanceError(
                 `deleteListObject: list missing object for removal by pk(${state.pkKey}): ${inspect(pk)}`,
@@ -479,6 +477,7 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
             toRef(state, "objects"),
             () => {
                 objectsInOrderRefs.value = Object.values(state.objects).map((object) => ref(object));
+                // noinspection JSIgnoredPromiseFromCall
                 nextTick(() => {
                     if (state.running) {
                         state.running = false;

package/use/listSearch.js

@@ -15,7 +15,7 @@ import { useSearch } from "./search.js";
 import get from "lodash-es/get.js";
 import isEqual from "lodash-es/isEqual.js";
 import { computed, effectScope, onScopeDispose, reactive, readonly, ref, toRef, unref, watch } from "vue";
-import { deepUnref } from "vue-deepunref";
+import { deepUnref } from "../utils/deepUnref.js";
 import { assignReactiveObject } from "../utils/assignReactiveObject.js";
 import { loadingCombine } from "../utils/loadingCombine.js";
 

package/use/loadingError.js

@@ -8,13 +8,37 @@ import { readonly, ref } from "vue";
  * @typedef {() => void} ClearErrorFn - Clear the error state.
  */
 
+/**
+ * @typedef {import("vue").Ref<boolean|undefined>} LoadingRef
+ */
+
+/**
+ * @typedef {import("vue").Ref<Error|null>} ErrorRef
+ */
+
+/**
+ * @typedef {import("vue").Ref<boolean>} ErroredRef
+ */
+
+/**
+ * @typedef {Readonly<LoadingRef>} LoadingReadonlyRef
+ */
+
+/**
+ * @typedef {Readonly<ErrorRef>} ErrorReadonlyRef
+ */
+
+/**
+ * @typedef {Readonly<ErroredRef>} ErroredReadonlyRef
+ */
+
 /**
  * The common API for loading and error states.
  *
  * @typedef {object} LoadingErrorStatus
- * @property {Readonly<import("vue").Ref<boolean|undefined>>} loading - Whether the component is loading.
- * @property {Readonly<import("vue").Ref<Error|null>>} error - The error that occurred.
- * @property {Readonly<import("vue").Ref<boolean>>} errored - Whether an error has occurred.
+ * @property {LoadingReadonlyRef} loading - Whether the component is loading.
+ * @property {ErrorReadonlyRef} error - The error that occurred.
+ * @property {ErroredReadonlyRef} errored - Whether an error has occurred.
  * @property {ClearErrorFn} clearError - Clear the error state.
  */
 
@@ -39,11 +63,11 @@ import { readonly, ref } from "vue";
  * @returns {LoadingError} - An object containing reactive fields and actions for loading and error states.
  */
 export function useLoadingError() {
-    /** @type {import("vue").Ref<boolean|undefined>} */
+    /** @type {LoadingRef} */
     const loading = ref(undefined);
-    /** @type {import("vue").Ref<Error|null>} */
+    /** @type {ErrorRef} */
     const error = ref(null);
-    /** @type {import("vue").Ref<boolean>} */
+    /** @type {ErroredRef} */
     const errored = ref(false);
 
     return {