@arrai-innovations/reactive-helpers 18.0.2 → 18.1.0

package/use/objectInstance.js

@@ -1,7 +1,8 @@
-import { getObjectCrud } from "../config/objectCrud.js";
+import { defaultCrud, getObjectCrud } from "../config/objectCrud.js";
 import { assignReactiveObject } from "../utils/assignReactiveObject.js";
 import { useLoadingError } from "./loadingError.js";
-import { reactive, toRef } from "vue";
+import { reactive, readonly, ref, shallowReactive, toRef } from "vue";
+import { wrapMaybeCancellable } from "../utils/cancellablePromise.js";
 
 /**
  * A composition function to manage create, retrieve, update, delete, and patch operations.
@@ -12,7 +13,15 @@ import { reactive, toRef } from "vue";
 /**
  * The object being managed by the instance. Empty object is the default.
  *
- * @typedef {{pkKey: string, [key: string]: any}|{}} CrudObject
+ * @typedef {{pkKey: string, [key: string]: any}} ExistingCrudObject
+ */
+
+/**
+ * @typedef {{[key: string]: any}} NewCrudObject
+ */
+
+/**
+ * @typedef {ExistingCrudObject|NewCrudObject} CrudObject
  */
 
 /**
@@ -20,7 +29,7 @@ import { reactive, toRef } from "vue";
  *
  * @typedef {object} ObjectInstanceOptions
  * @property {import('vue').UnwrapNestedRefs<ObjectInstanceRawProps>} props - The reactive configuration object.
- * @property {import('../config/objectCrud.js').ObjectCrudFunctions} functions - An object of custom crud functions to use instead of the defaults.
+ * @property {import('../config/objectCrud.js').ObjectCrudFunctions} [functions] - An object of custom crud functions to use instead of the defaults.
  */
 
 /**
@@ -33,37 +42,48 @@ import { reactive, toRef } from "vue";
  * @property {import('../config/objectCrud.js').ObjectCrudArgs} crudArgs - The arguments to be passed to the crud functions.
  */
 
+/**
+ * @typedef {object} ObjectInstanceRawStateCrud
+ * @property {import('vue').Reactive<import('../config/objectCrud.js').ObjectCrudArgsArgs|{}>} args - The arguments to be passed to the crud functions.
+ * @property {import('../config/objectCrud.js').CrudCreateFn} create - The create function.
+ * @property {import('../config/objectCrud.js').CrudRetrieveFn} retrieve - The retrieve function.
+ * @property {import('../config/objectCrud.js').CrudUpdateFn} update - The update function.
+ * @property {import('../config/objectCrud.js').CrudPatchFn} patch - The patch function.
+ * @property {import('../config/objectCrud.js').CrudDeleteFn} delete - The delete function.
+ * @property {import('../config/objectCrud.js').CrudSubscribeFn} subscribe - The subscribe function.
+ */
+
 /**
  * The raw state of the object instance.
  *
  * @typedef {object} ObjectInstanceRawState
- * @property {import('../config/objectCrud.js').ObjectCrudArgs} crud - The crud functions.
- * @property {string} pk - The pk of the object.
- * @property {string} pkKey - The pk key of the object.
- * @property {object} retrieveArgs - The arguments to be passed to the retrieve function.
- * @property {CrudObject} object - The object.
+ * @property {import('vue').ShallowReactive<ObjectInstanceRawStateCrud>} crud - The crud functions.
+ * @property {import('vue').Ref<string|undefined>} pk - The pk of the object.
+ * @property {import('vue').Ref<string|undefined>} pkKey - The pk key of the object.
+ * @property {import('vue').Ref<{[key:string]: any}>} retrieveArgs - The arguments to be passed to the retrieve function.
+ * @property {import('vue').Reactive<CrudObject>} object - The object.
  * @property {Readonly<import('vue').Ref<boolean>>} loading - Whether the object is loading.
  * @property {Readonly<import('vue').Ref<boolean>>} errored - Whether the object errored.
  * @property {Readonly<import('vue').Ref<Error|null>>} error - The error.
- * @property {Readonly<import('vue').Ref<boolean>>} deleted - Whether the object is deleted.
+ * @property {boolean} deleted - Whether the object is deleted.
  */
 
 /**
  * Manages a reactive state of an object including its CRUD status, loading states, and any operational errors.
  * Reactivity ensures that any changes in state immediately reflect in the UI components that depend on this state.
  *
- * @typedef {import('vue').UnwrapNestedRefs<ObjectInstanceRawState>} ObjectInstanceState
+ * @typedef {import('vue').Reactive<ObjectInstanceRawState>} ObjectInstanceState
  */
 
 /**
  * The functions available on the object instance.
  *
  * @typedef {object} ObjectInstanceFunctions
- * @property {(args: { object: object }) => Promise<boolean>} create - Called to turn the current object into a new object on the server.
- * @property {() => Promise<boolean>} retrieve - Called to retrieve the current object by pk from the server.
- * @property {(args: { object: CrudObject }) => Promise<boolean>} update - Called to update the current object on the server.
- * @property {() => Promise<boolean>} delete - Called to delete the current object on the server.
- * @property {(args: { partialObject: CrudObject }) => Promise<boolean>} patch - Called to patch the current object on the server.
+ * @property {(args: { object: object }) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean>} create - Called to turn the current object into a new object on the server.
+ * @property {() => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean>} retrieve - Called to retrieve the current object by pk from the server.
+ * @property {(args: { object: ExistingCrudObject }) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean>} update - Called to update the current object on the server.
+ * @property {() => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean>} delete - Called to delete the current object on the server.
+ * @property {(args: { partialObject: ExistingCrudObject }) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean>} patch - Called to patch the current object on the server.
  * @property {import('./loadingError.js').ClearErrorFn} clearError - Called to clear the error state.
  * @property {() => void} clear - Called to clear the object state.
  */
@@ -189,17 +209,22 @@ export function useObjectInstance({ props, functions = {} }) {
     const loadingError = useLoadingError();
     /** @type {ObjectInstanceState} */
     const state = reactive(
-        /** @type {ObjectInstanceRawState} */ {
-            crud: {
-                args: {},
-                create: undefined,
-                retrieve: undefined,
-                update: undefined,
-                delete: undefined,
-                patch: undefined,
-                subscribe: undefined,
-            },
-            object: {},
+        /** @type {ObjectInstanceRawState} */
+        {
+            // function typing support is a lot nicer with shallow reactive
+            crud: shallowReactive(
+                /** @type {ObjectInstanceRawStateCrud} */
+                {
+                    args: reactive({}),
+                    create: defaultCrud.create,
+                    retrieve: defaultCrud.retrieve,
+                    update: defaultCrud.update,
+                    delete: defaultCrud.delete,
+                    patch: defaultCrud.patch,
+                    subscribe: defaultCrud.subscribe,
+                }
+            ),
+            object: reactive({}),
             pk: toRef(props, "pk"),
             pkKey: toRef(props, "pkKey"),
             retrieveArgs: toRef(props, "retrieveArgs"),
@@ -218,6 +243,9 @@ export function useObjectInstance({ props, functions = {} }) {
         retrieve: null,
     };
 
+    /**
+     * @returns {import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} - A promise that resolves to true if the object was retrieved successfully, or false if there was an error.
+     */
     function retrieve() {
         // this function cannot be async, or the resulting promise will lose its .cancel() method
         if (promises.retrieve) {
@@ -225,136 +253,208 @@ export function useObjectInstance({ props, functions = {} }) {
             return promises.retrieve;
         }
         if (state.loading) {
-            // if another operation is already in progress, return a rejected promise
-            return Promise.reject(new ObjectError("already loading.", "already-loading"));
+            // if another operation is already in progress, throw an error
+            // 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 ObjectError("already loading.", "already-loading");
         }
         loadingError.setLoading();
         loadingError.clearError();
-        promises.retrieve = state.crud
-            .retrieve({
-                crudArgs: state.crud.args,
-                pk: state.pk,
-                retrieveArgs: state.retrieveArgs,
-                pkKey: state.pkKey,
-            })
-            .then((object) => {
-                assignReactiveObject(state.object, object);
-                return Promise.resolve(true);
-            })
-            .catch((error) => {
-                loadingError.setError(error);
-                return Promise.resolve(false);
-            })
-            .finally(() => {
-                loadingError.clearLoading();
-                promises.retrieve = null;
-            });
+        const isCancelled = ref(false);
+        const retrievePromise = state.crud.retrieve({
+            crudArgs: state.crud.args,
+            pk: state.pk,
+            retrieveArgs: state.retrieveArgs,
+            pkKey: state.pkKey,
+            isCancelled: readonly(isCancelled),
+        });
+
+        promises.retrieve = wrapMaybeCancellable(
+            retrievePromise
+                .then((/** @type {ExistingCrudObject} */ object) => {
+                    assignReactiveObject(state.object, object);
+                    return true;
+                })
+                .catch((/** @type {Error} */ error) => {
+                    loadingError.setError(error);
+                    return false;
+                })
+                .finally(() => {
+                    loadingError.clearLoading();
+                    promises.retrieve = null;
+                }),
+            retrievePromise.cancel
+                ? async (/** @type {any} */ reason) => {
+                      isCancelled.value = true;
+                      await retrievePromise.cancel?.(reason);
+                      loadingError.clearLoading();
+                  }
+                : undefined
+        );
+
         return promises.retrieve;
     }
 
-    async function create({ object }) {
+    function create({ object }) {
+        // this function cannot be async, or the resulting promise will lose its .cancel() method
         if (state.loading) {
+            // 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 ObjectError("already loading.", "already-loading");
         }
         loadingError.setLoading();
         loadingError.clearError();
-        return state.crud
-            .create({
-                crudArgs: state.crud.args,
-                object,
-                retrieveArgs: state.retrieveArgs,
-                pkKey: state.pkKey,
-            })
-            .then((object) => {
-                assignReactiveObject(state.object, object);
-                return Promise.resolve(true);
-            })
-            .catch((error) => {
-                loadingError.setError(error);
-                return Promise.resolve(false);
-            })
-            .finally(() => {
-                loadingError.clearLoading();
-            });
+        const isCancelled = ref(false);
+        const createPromise = state.crud.create({
+            crudArgs: state.crud.args,
+            object,
+            retrieveArgs: state.retrieveArgs,
+            pkKey: state.pkKey,
+            isCancelled: readonly(isCancelled),
+        });
+
+        return wrapMaybeCancellable(
+            createPromise
+                .then((/** @type {ExistingCrudObject} */ object) => {
+                    assignReactiveObject(state.object, object);
+                    return true;
+                })
+                .catch((/** @type {Error} */ error) => {
+                    loadingError.setError(error);
+                    return false;
+                })
+                .finally(() => {
+                    loadingError.clearLoading();
+                }),
+            createPromise.cancel
+                ? async (/** @type {any} */ reason) => {
+                      isCancelled.value = true;
+                      await createPromise.cancel?.(reason);
+                      loadingError.clearLoading();
+                  }
+                : undefined
+        );
     }
 
-    async function update({ object }) {
+    function update({ object }) {
+        // this function cannot be async, or the resulting promise will lose its .cancel() method
         if (state.loading) {
+            // 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 ObjectError("already loading.", "already-loading");
         }
         loadingError.setLoading();
         loadingError.clearError();
-        return state.crud
-            .update({
-                crudArgs: state.crud.args,
-                object,
-                retrieveArgs: state.retrieveArgs,
-                pkKey: state.pkKey,
-            })
-            .then((object) => {
-                assignReactiveObject(state.object, object);
-                return Promise.resolve(true);
-            })
-            .catch((error) => {
-                loadingError.setError(error);
-                return Promise.resolve(false);
-            })
-            .finally(() => {
-                loadingError.clearLoading();
-            });
+        const isCancelled = ref(false);
+        const updatePromise = state.crud.update({
+            crudArgs: state.crud.args,
+            object,
+            retrieveArgs: state.retrieveArgs,
+            pkKey: state.pkKey,
+            isCancelled: readonly(isCancelled),
+        });
+        return wrapMaybeCancellable(
+            updatePromise
+                .then((/** @type {ExistingCrudObject} */ object) => {
+                    assignReactiveObject(state.object, object);
+                    return true;
+                })
+                .catch((/** @type {Error} */ error) => {
+                    loadingError.setError(error);
+                    return false;
+                })
+                .finally(() => {
+                    loadingError.clearLoading();
+                }),
+            updatePromise.cancel
+                ? async (/** @type {any} */ reason) => {
+                      isCancelled.value = true;
+                      await updatePromise.cancel?.(reason);
+                      loadingError.clearLoading();
+                  }
+                : undefined
+        );
     }
 
-    async function patch({ partialObject }) {
+    function patch({ partialObject }) {
+        // this function cannot be async, or the resulting promise will lose its .cancel() method
         if (state.loading) {
+            // 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 ObjectError("already loading.", "already-loading");
         }
         loadingError.setLoading();
         loadingError.clearError();
-        return state.crud
-            .patch({
-                crudArgs: state.crud.args,
-                pk: state.pk,
-                pkKey: state.pkKey,
-                partialObject,
-                retrieveArgs: state.retrieveArgs,
-            })
-            .then((object) => {
-                assignReactiveObject(state.object, object);
-                return Promise.resolve(true);
-            })
-            .catch((error) => {
-                loadingError.setError(error);
-                return Promise.resolve(false);
-            })
-            .finally(() => {
-                loadingError.clearLoading();
-            });
+        const isCancelled = ref(false);
+        const patchPromise = state.crud.patch({
+            crudArgs: state.crud.args,
+            pk: state.pk,
+            pkKey: state.pkKey,
+            partialObject,
+            retrieveArgs: state.retrieveArgs,
+            isCancelled: readonly(isCancelled),
+        });
+        return wrapMaybeCancellable(
+            patchPromise
+                .then((/** @type {ExistingCrudObject} */ object) => {
+                    assignReactiveObject(state.object, object);
+                    return true;
+                })
+                .catch((/** @type {Error} */ error) => {
+                    loadingError.setError(error);
+                    return false;
+                })
+                .finally(() => {
+                    loadingError.clearLoading();
+                }),
+            patchPromise.cancel
+                ? async (/** @type {any} */ reason) => {
+                      isCancelled.value = true;
+                      await patchPromise.cancel?.(reason);
+                      loadingError.clearLoading();
+                  }
+                : undefined
+        );
     }
 
-    async function deleteFn() {
+    function deleteFn() {
+        // this function cannot be async, or the resulting promise will lose its .cancel() method
         if (state.loading) {
+            // 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 ObjectError("already loading.", "already-loading");
         }
         loadingError.setLoading();
         loadingError.clearError();
-        return state.crud
-            .delete({
-                crudArgs: state.crud.args,
-                pk: state.pk,
-                pkKey: state.pkKey,
-            })
-            .then(() => {
-                state.deleted = true;
-                assignReactiveObject(state.object, {});
-                return Promise.resolve(true);
-            })
-            .catch((error) => {
-                loadingError.setError(error);
-                return Promise.resolve(false);
-            })
-            .finally(() => {
-                loadingError.clearLoading();
-            });
+        const isCancelled = ref(false);
+        const deletePromise = state.crud.delete({
+            crudArgs: state.crud.args,
+            pk: state.pk,
+            pkKey: state.pkKey,
+            isCancelled: readonly(isCancelled),
+        });
+        return wrapMaybeCancellable(
+            deletePromise
+                .then(() => {
+                    state.deleted = true;
+                    assignReactiveObject(state.object, {});
+                    return true;
+                })
+                .catch((/** @type {Error} */ error) => {
+                    loadingError.setError(error);
+                    return false;
+                })
+                .finally(() => {
+                    loadingError.clearLoading();
+                }),
+            deletePromise.cancel
+                ? async (/** @type {any} */ reason) => {
+                      isCancelled.value = true;
+                      await deletePromise.cancel?.(reason);
+                      loadingError.clearLoading();
+                  }
+                : undefined
+        );
     }
 
     function clear() {