@arrai-innovations/reactive-helpers 18.0.2 → 19.0.0

package/use/listInstance.js

@@ -1,9 +1,11 @@
-import { getListCrud } from "../config/listCrud.js";
+import { defaultListCrud, getListCrud } from "../config/listCrud.js";
 import { assignReactiveObject } from "../utils/assignReactiveObject.js";
 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 { computed, effectScope, nextTick, reactive, readonly, ref, shallowReactive, toRef, unref, watch } from "vue";
+import { CancellablePromise, wrapMaybeCancellable } from "../utils/cancellablePromise.js";
+import { refIfReactive } from "../utils/refIfReactive.js";
 
 /**
  * A composable function for managing a list of objects.
@@ -52,13 +54,13 @@ export class ListInstanceError extends Error {
  * @typedef {object} ListInstanceOptions
  * @property {import('vue').UnwrapNestedRefs<ListInstanceProps>} props - The props for the list instance.
  * @property {object} [functions] - Default implementation are used as set by `setListCrud`.
- * @property {import('../config/listCrud.js').ListFn} [functions.list] - Provide the implementation for the list
+ * @property {import('../config/listCrud.js').CrudListFn} [functions.list] - Provide the implementation for the list
  *  function.
- *  @property {import('../config/listCrud.js').BulkDeleteFn} [functions.bulkDelete] - Provide the implementation for the bulkDelete
+ *  @property {import('../config/listCrud.js').CrudBulkDeleteFn} [functions.bulkDelete] - Provide the implementation for the bulkDelete
  *  function.
- *   @property {import('../config/listCrud.js').ExecuteActionFn} [functions.executeAction] - Provide the implementation for the executeAction
+ *   @property {import('../config/listCrud.js').CrudExecuteActionFn} [functions.executeAction] - Provide the implementation for the executeAction
  *  function.
- * @property {import('../config/listCrud.js').SubscribeFn} [functions.subscribe] - Provide the implementation for the
+ * @property {import('../config/listCrud.js').CrudListSubscribeFn} [functions.subscribe] - Provide the implementation for the
  *  subscribe function.
  * @property {boolean} keepOldPages - If true, pages will not be cleared when defaultPageCallback is called.
  */
@@ -117,7 +119,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.
  */
@@ -206,16 +208,22 @@ export function useListInstances(listInstanceArgs) {
  */
 export function useListInstance({ props, functions = {}, keepOldPages }) {
     if (!props) {
-        throw new ListInstanceError(`useListInstance requires props`, "missing-props");
+        throw new ListInstanceError("useListInstance requires props", "missing-props");
     }
     if (keepOldPages === undefined) {
-        throw new ListInstanceError(`useListInstance requires keepOldPages`, "missing-keepOldPages");
+        throw new ListInstanceError("useListInstance requires keepOldPages", "missing-keepOldPages");
     }
+    if (!props.pkKey) {
+        throw new ListInstanceError("useListInstance requires pkKey.", "missing-pkKey");
+    }
+
+    const es = effectScope();
 
     // ### touching the _objectsMap or _objectsProxy directly will not trigger reactivity ###
     const _objectsMap = new Map(); // maps are ordered, if you don't clear lists, you need to insert pages in order.
 
     // ### touching the _objectsMap or _objectsProxy directly will not trigger reactivity ###
+    // noinspection JSValidateTypes
     /** @type {{[key: string]: ListObject}} */
     // @ts-ignore - we are using a proxy to make this map behave like an object for reactivity
     const _objectsProxy = new Proxy(_objectsMap, {
@@ -250,7 +258,7 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
                   }
                 : Reflect.getOwnPropertyDescriptor(target, p); // we can't report target properties as non-existent re: proxy invariants
         },
-        // things introspect us thing we are a map, we need to pretend to be a object
+        // things introspect us thing we are a map, we need to pretend to be an object
         getPrototypeOf() {
             return Object.prototype;
         },
@@ -262,31 +270,28 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
 
     // ### touching the _objectsMap or _objectsProxy directly will not trigger reactivity ###
     const state = reactive({
-        crud: {
-            args: {},
-            list: undefined,
-            bulkDelete: undefined,
-            executeAction: undefined,
-        },
-        pkKey: toRef(props, "pkKey"),
-        retrieveArgs: toRef(props, "retrieveArgs"),
-        listArgs: toRef(props, "listArgs"),
+        crud: shallowReactive({
+            args: reactive({}),
+            list: defaultListCrud.list,
+            bulkDelete: defaultListCrud.bulkDelete,
+            executeAction: defaultListCrud.executeAction,
+        }),
+        pkKey: refIfReactive(props, "pkKey"),
+        retrieveArgs: refIfReactive(props, "retrieveArgs", {}),
+        listArgs: refIfReactive(props, "listArgs", {}),
         /** @type {{[key: string]: ListObject}} */
         objects: /** @type {{[key: string]: ListObject}} */ _objectsProxy,
         running: false,
         loading: loadingError.loading,
         errored: loadingError.errored,
         error: loadingError.error,
-        /** @type {import('vue').ComputedRef<string[]>|undefined} */
-        order: undefined,
-        /** @type {import('vue').ComputedRef<ListObject[]>|undefined} */
-        objectsInOrder: undefined,
+        order: es.run(() => computed(() => Object.keys(state.objects))),
+        objectsInOrder: es.run(() => computed(() => objectsInOrderRefs.value.map((ref) => unref(ref)))),
     });
-    const es = effectScope();
 
     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 +306,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 +328,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,19 +349,25 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
                 pks: Object.keys(state.objects).map(Number),
                 pkKey: state.pkKey,
             })
-            .then((responseData) => {
+            .then((/** @type {object|string} */ responseData) => {
                 loadingError.clearError();
                 return Promise.resolve(responseData);
             })
-            .catch((error) => {
+            .catch((/** @type {Error} */ error) => {
                 loadingError.setError(error);
-                return Promise.resolve(false);
+                return Promise.resolve(null);
             })
             .finally(() => {
                 loadingError.clearLoading();
             });
     }
 
+    /**
+     * 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 +375,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 +388,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 +431,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 +450,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 +481,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;
@@ -490,10 +493,6 @@ export function useListInstance({ props, functions = {}, keepOldPages }) {
                 deep: true,
             }
         );
-        // @ts-ignore - we want the computed in the explicit effect scope, tsc is mad that we are 'changing' the type
-        state.objectsInOrder = computed(() => objectsInOrderRefs.value.map((ref) => unref(ref)));
-        // @ts-ignore - we want the computed in the explicit effect scope, tsc is mad that we are 'changing' the type
-        state.order = computed(() => Object.keys(state.objects));
     });
 
     // This isn't a direct return because we want the live returnedObject.pageCallback in list()

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 {