@arrai-innovations/reactive-helpers 21.0.1 → 21.1.2

package/use/loading.js

@@ -6,14 +6,22 @@ import { readonly, ref } from "vue";
  */
 
 /**
- * The loading state API.
- *
- * @typedef {object} LoadingStatus
+ * @typedef {object} LoadingProperties
  * @property {LoadingReadonlyRef} loading - Whether the component is loading.
+ */
+
+/**
+ * @typedef {object} LoadingFunctions
  * @property {() => void} setLoading - Set the loading state to true.
  * @property {() => void} clearLoading - Set the loading state to false.
  */
 
+/**
+ * The loading state API.
+ *
+ * @typedef {LoadingProperties & LoadingFunctions} LoadingStatus
+ */
+
 /**
  * A composable function for managing loading state.
  *

package/use/loadingError.js

@@ -2,7 +2,9 @@ import { useLoading } from "./loading.js";
 import { useError } from "./error.js";
 
 /**
- * @typedef {import('./loading.js').LoadingStatus & import('./error.js').ErrorStatus} LoadingErrorStatus
+ * @typedef {import('./loading.js').LoadingProperties & import('./error.js').ErrorProperties} LoadingErrorProperties
+ * @typedef {import('./loading.js').LoadingFunctions & import('./error.js').ErrorFunctions} LoadingErrorFunctions
+ * @typedef {LoadingErrorProperties & LoadingErrorFunctions} LoadingErrorStatus
  */
 
 /**

package/use/objectInstance.js

@@ -3,10 +3,10 @@ import { assignReactiveObject } from "../utils/assignReactiveObject.js";
 import { useLoadingError } from "./loadingError.js";
 import { reactive, readonly, ref } from "vue";
 import { CancellablePromise, wrapMaybeCancellable } from "../utils/cancellablePromise.js";
-import { refIfReactive } from "../utils/refIfReactive.js";
+import { pkRefIfReactive, refIfReactive } from "../utils/refIfReactive.js";
 
 /**
- * A composition function to manage create, retrieve, update, delete, and patch operations.
+ * A composition function to manage create, retrieve, update, delete, patch, and executeAction operations.
  *
  * @module use/objectInstance.js
  */
@@ -40,7 +40,7 @@ import { refIfReactive } from "../utils/refIfReactive.js";
  * Reactive arguments to be passed to the object instance.
  *
  * @typedef {object} ObjectInstanceRawProps
- * @property {string} [pk] - The pk of the object, optional to support creating new objects.
+ * @property {import('../config/commonCrud.js').PkInput} [pk] - The pk of the object, optional to support creating new objects.
  * @property {string} pkKey - The pk key of the object.
  * @property {object} params - The arguments to be passed to the retrieve function.
  * @property {import('../config/objectCrud.js').ObjectTarget} target - The arguments to be passed to the crud handlers.
@@ -55,6 +55,7 @@ import { refIfReactive } from "../utils/refIfReactive.js";
  * @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').CrudObjectSubscribeFn} subscribe - The subscribe function.
+ * @property {import('../config/objectCrud.js').CrudObjectExecuteActionFn} executeAction - The executeAction function.
  */
 
 /**
@@ -62,7 +63,7 @@ import { refIfReactive } from "../utils/refIfReactive.js";
  *
  * @typedef {object} ObjectInstanceRawMyState
  * @property {import('vue').Reactive<ObjectInstanceRawStateCrud>} crud - The crud handlers.
- * @property {import('vue').Ref<string|undefined>} pk - The pk of the object.
+ * @property {import('vue').Ref<import('../config/commonCrud.js').Pk|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}>} params - The arguments to be passed to the retrieve function.
  * @property {import('vue').Reactive<CrudObject>} object - The object.
@@ -72,7 +73,7 @@ import { refIfReactive } from "../utils/refIfReactive.js";
 /**
  * The raw state of the object instance.
  *
- * @typedef {ObjectInstanceRawMyState & Pick<import('./loadingError.js').LoadingErrorStatus, "loading" | "error" | "errored">} ObjectInstanceRawState
+ * @typedef {ObjectInstanceRawMyState & import('./loadingError.js').LoadingErrorProperties} ObjectInstanceRawState
  */
 
 /**
@@ -86,15 +87,20 @@ import { refIfReactive } from "../utils/refIfReactive.js";
 /** @typedef {{ object: ExistingCrudObject }} ObjectInstanceUpdateArgs */
 /** @typedef {{ partialObject: ExistingCrudObject }} ObjectInstancePatchArgs */
 
+/**
+ * @typedef {{[key:string]: any}} AdditionalArgs
+ */
+
 /**
  * The functions available on the object instance.
  *
  * @typedef {object} ObjectInstanceMyFunctions
- * @property {(args: ObjectInstanceCreateArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} create - Called to turn the current object into a new object on the server.
- * @property {(args?: import('./cancellableIntent.js').CommonRunTracking) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} retrieve - Called to retrieve the current object by pk from the server.
- * @property {(args: ObjectInstanceUpdateArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} update - Called to update the current object on the server.
- * @property {() => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} delete - Called to delete the current object on the server.
- * @property {(args: ObjectInstancePatchArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} patch - Called to patch the current object on the server.
+ * @property {(args: ObjectInstanceCreateArgs & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} create - Called to turn the current object into a new object on the server.
+ * @property {(args?: Partial<import('./cancellableIntent.js').CommonRunTracking> & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} retrieve - Called to retrieve the current object by pk from the server.
+ * @property {(args: ObjectInstanceUpdateArgs & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} update - Called to update the current object on the server.
+ * @property {(args?: AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} delete - Called to delete the current object on the server.
+ * @property {(args: ObjectInstancePatchArgs & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} patch - Called to patch the current object on the server.
+ * @property {(args: {action: string} & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} executeAction - Called to execute certain action on the current object.
  * @property {() => void} clear - Called to clear the object state.
  */
 
@@ -102,7 +108,7 @@ import { refIfReactive } from "../utils/refIfReactive.js";
  * The functions available on the object instance, including the ability to clear LoadingError errors.
  *
  * @typedef {(
- *     Pick<import('./loadingError.js').LoadingErrorStatus, "clearError"> &
+ *     import('./error.js').ErrorReadOnlyFunctions &
  *     ObjectInstanceMyFunctions
  * )} ObjectInstanceFunctions
  */
@@ -150,7 +156,16 @@ export const objectInstanceStateKeys = [
     "deleted",
 ];
 
-export const objectInstanceFunctions = ["create", "retrieve", "update", "delete", "patch", "clearError", "clear"];
+export const objectInstanceFunctions = [
+    "create",
+    "retrieve",
+    "update",
+    "delete",
+    "patch",
+    "executeAction",
+    "clearError",
+    "clear",
+];
 
 /**
  * Initializes multiple useObjectInstance instances, returning an object of them based on the keys of the instanceArgs.
@@ -217,7 +232,7 @@ export function useObjectInstances(instanceArgs) {
  * ```
  *
  * @param {ObjectInstanceOptions} options - The options to be passed to useObjectInstance.
- * @returns {ObjectInstance} - An object used to manage create, retrieve, update, delete, and patch operations.
+ * @returns {ObjectInstance} - An object used to manage create, retrieve, update, delete, patch, and executeAction operations.
  */
 export function useObjectInstance({ props, handlers = {} }) {
     // missing pk is fine, to support creating new objects
@@ -240,9 +255,10 @@ export function useObjectInstance({ props, handlers = {} }) {
                     delete: defaultObjectCrud.delete,
                     patch: defaultObjectCrud.patch,
                     subscribe: defaultObjectCrud.subscribe,
+                    executeAction: defaultObjectCrud.executeAction,
                 },
             object: {},
-            pk: refIfReactive(props, "pk", null),
+            pk: pkRefIfReactive(props, "pk", null),
             pkKey: refIfReactive(props, "pkKey"),
             params: refIfReactive(props, "params", {}),
             loading: loadingError.loading,
@@ -263,7 +279,7 @@ export function useObjectInstance({ props, handlers = {} }) {
     /** @type {ObjectInstance} */
     const instance = {
         state,
-        create: ({ object }) => {
+        create: ({ object, ...additionalArgs }) => {
             // 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
@@ -274,6 +290,7 @@ export function useObjectInstance({ props, handlers = {} }) {
             loadingError.clearError();
             const isCancelled = ref(false);
             const createPromise = state.crud.create({
+                ...additionalArgs,
                 target: state.crud.args,
                 object,
                 params: state.params,
@@ -303,8 +320,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                     : undefined
             );
         },
-        retrieve: (args) => {
-            const { runId, isCurrentRun } = args || {};
+        retrieve: (args = {}) => {
             // this function cannot be async, or the resulting promise will lose its .cancel() method
             if (promises.retrieve) {
                 // if a retrieve is already in progress, return the existing promise
@@ -322,8 +338,7 @@ export function useObjectInstance({ props, handlers = {} }) {
             let retrievePromise = null;
             try {
                 retrievePromise = state.crud.retrieve({
-                    runId,
-                    isCurrentRun,
+                    ...args,
                     target: state.crud.args,
                     pk: state.pk,
                     params: state.params,
@@ -361,7 +376,7 @@ export function useObjectInstance({ props, handlers = {} }) {
 
             return promises.retrieve;
         },
-        update: ({ object }) => {
+        update: ({ object, ...additionalArgs }) => {
             // 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
@@ -372,6 +387,7 @@ export function useObjectInstance({ props, handlers = {} }) {
             loadingError.clearError();
             const isCancelled = ref(false);
             const updatePromise = state.crud.update({
+                ...additionalArgs,
                 target: state.crud.args,
                 object,
                 params: state.params,
@@ -400,7 +416,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                     : undefined
             );
         },
-        delete: () => {
+        delete: (args = {}) => {
             // 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
@@ -410,6 +426,7 @@ export function useObjectInstance({ props, handlers = {} }) {
             loadingError.setLoading();
             loadingError.clearError();
             const deletePromise = state.crud.delete({
+                ...args,
                 target: state.crud.args,
                 pk: state.pk,
                 pkKey: state.pkKey,
@@ -436,7 +453,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                     : undefined
             );
         },
-        patch: ({ partialObject }) => {
+        patch: ({ partialObject, ...additionalArgs }) => {
             // 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
@@ -447,10 +464,11 @@ export function useObjectInstance({ props, handlers = {} }) {
             loadingError.clearError();
             const isCancelled = ref(false);
             const patchPromise = state.crud.patch({
+                ...additionalArgs,
                 target: state.crud.args,
+                partialObject,
                 pk: state.pk,
                 pkKey: state.pkKey,
-                partialObject,
                 params: state.params,
                 isCancelled: readonly(isCancelled),
             });
@@ -476,6 +494,42 @@ export function useObjectInstance({ props, handlers = {} }) {
                     : undefined
             );
         },
+        executeAction: ({ action, ...additionalArgs }) => {
+            if (state.loading) {
+                throw new ObjectError("already loading.", "already-loading");
+            }
+            loadingError.setLoading();
+            loadingError.clearError();
+            const isCancelled = ref(false);
+            const executeActionPromise = state.crud.executeAction({
+                ...additionalArgs,
+                target: state.crud.args,
+                action,
+                pk: state.pk,
+                pkKey: state.pkKey,
+                isCancelled: readonly(isCancelled),
+            });
+            return wrapMaybeCancellable(
+                executeActionPromise
+                    .then(() => {
+                        return true;
+                    })
+                    .catch((/** @type {Error} */ error) => {
+                        loadingError.setError(error);
+                        return false;
+                    })
+                    .finally(() => {
+                        loadingError.clearLoading();
+                    }),
+                executeActionPromise.cancel
+                    ? async (/** @type {any} */ reason) => {
+                          isCancelled.value = true;
+                          await executeActionPromise.cancel?.(reason);
+                          loadingError.clearLoading();
+                      }
+                    : undefined
+            );
+        },
         clearError: loadingError.clearError,
         clear: () => {
             loadingError.clearError();

package/use/objectSubscription.js

@@ -1,9 +1,9 @@
 import { assignReactiveObject } from "../utils/assignReactiveObject.js";
 import { useCancellableIntent } from "./cancellableIntent.js";
 import { useObjectInstance } from "./objectInstance.js";
-import { computed, reactive, ref, toRef, toRefs } from "vue";
+import { computed, reactive, readonly, ref, toRefs } from "vue";
 import { refIfReactive } from "../utils/refIfReactive.js";
-import { useProxyError } from "./proxyError.js";
+import { asWatchableError, useProxyError } from "./proxyError.js";
 import { loadingCombine } from "../utils/loadingCombine.js";
 
 /**
@@ -91,14 +91,18 @@ export const objectSubscriptionFunctions = ["clearError"];
  */
 
 /**
- * Options for initializing an object subscription, including reactive props and non-reactive handlers.
- *
- * @typedef {object & import('./objectInstance.js').ObjectInstanceOptions} ObjectSubscriptionOptions
+ * @typedef {object} ObjectSubscriptionOwnOptions
  * @property {import('./objectInstance.js').ObjectInstance} [objectInstance] - An object instance to use instead of creating a new one.
  * @property {import('vue').UnwrapNestedRefs<(
  *     ObjectSubscriptionRawProps & import('./objectInstance.js').ObjectInstanceRawProps
  * )>} props - The reactive args to be passed to useObjectInstance.
- * @property {import('./objectInstance.js').ObjectInstanceHandlers} [handlers] - The handlers to be passed to useObjectInstance.
+ * @property {import('../config/objectCrud.js').ObjectCrudHandlers} [handlers] - The handlers to be passed to useObjectInstance.
+ */
+
+/**
+ * Options for initializing an object subscription, including reactive props and non-reactive handlers.
+ *
+ * @typedef {ObjectSubscriptionOwnOptions & import('./objectInstance.js').ObjectInstanceOptions} ObjectSubscriptionOptions
  */
 
 /**
@@ -200,14 +204,8 @@ export function useObjectSubscription({ objectInstance, props, handlers }) {
     const intendToRetrieve = refIfReactive(props, "intendToRetrieve", false);
     const intendToSubscribe = refIfReactive(props, "intendToSubscribe", false);
     const parentState = objectInstance.state;
-    /** @type {import('./proxyError.js').WatchableErrors} */
-    const errorStates = ref([
-        {
-            error: toRef(parentState, "error"),
-            errored: toRef(parentState, "errored"),
-            clearError: objectInstance.clearError,
-        },
-    ]);
+    /** @type {import('vue').Ref<import('./proxyError.js').WatchableError[]>} */
+    const errorStates = ref([asWatchableError(objectInstance)]);
     const proxyError = useProxyError(errorStates);
     const {
         crud: parentCrud,
@@ -249,7 +247,7 @@ export function useObjectSubscription({ objectInstance, props, handlers }) {
                 }
             };
             const parentState = objectInstance.state;
-            return parentState.crud.subscribe({
+            const subscribePromise = parentState.crud.subscribe({
                 runId,
                 isCurrentRun,
                 target: parentState.crud.args,
@@ -257,8 +255,17 @@ export function useObjectSubscription({ objectInstance, props, handlers }) {
                 pkKey: parentState.pkKey,
                 params: state.params,
                 callback: subscribeCallback,
-                isCancelled,
+                isCancelled: readonly(isCancelled),
             });
+            if (subscribePromise?.cancel) {
+                const originalCancel = subscribePromise.cancel.bind(subscribePromise);
+                const cancelWithFlag = async (/** @type {any} */ reason) => {
+                    isCancelled.value = true;
+                    return originalCancel(reason);
+                };
+                subscribePromise.cancel = cancelWithFlag;
+            }
+            return subscribePromise;
         },
         watchArguments: {
             intendToSubscribe,
@@ -272,16 +279,8 @@ export function useObjectSubscription({ objectInstance, props, handlers }) {
         // subscriptions persist until cancelled
         clearActiveOnResolved: false,
     });
-    errorStates.value.push({
-        error: toRef(retrieveIntent.state, "error"),
-        errored: toRef(retrieveIntent.state, "errored"),
-        clearError: retrieveIntent.clearError,
-    });
-    errorStates.value.push({
-        error: toRef(subscribeIntent.state, "error"),
-        errored: toRef(subscribeIntent.state, "errored"),
-        clearError: subscribeIntent.clearError,
-    });
+    errorStates.value.push(asWatchableError(retrieveIntent));
+    errorStates.value.push(asWatchableError(subscribeIntent));
     /** @type {ObjectSubscriptionState} */
     const state = reactive({
         crud: parentCrud,

package/use/proxyError.js

@@ -1,27 +1,17 @@
 import { computed, readonly, unref } from "vue";
 import identity from "lodash-es/identity.js";
+import { toRefsIfReactive } from "../utils/toRefsIfReactive.js";
 
 /**
- * @typedef {Pick<import('./error.js').ErrorStatus, "error" | "errored" | "clearError">} ReadonlyErrorStatus
- */
-/**
- * @typedef {import("vue").Ref<ReadonlyErrorStatus>} RefErrorStatus
- */
-/**
- * @typedef {ReadonlyErrorStatus | RefErrorStatus} WatchableError
- */
-/**
- * @typedef {import('vue').Ref<WatchableError[]>} WatchableErrorRef
- */
-/**
- * @typedef {WatchableErrorRef|WatchableError[]} WatchableErrors
+ * @typedef {import('./error.js').ReadonlyErrorStatus | import("vue").Reactive<import('./error.js').ReadonlyErrorStatus>} WatchableError
+ * @typedef {import('vue').MaybeRef<WatchableError>} MaybeRefWatchableError
  */
 
 /**
  * A composable function for aggregating error state across multiple sources.
  *
- * @param {WatchableErrors} errors - The error states to monitor.
- * @returns {ReadonlyErrorStatus} An object containing aggregated reactive fields and actions for error state.
+ * @param {import('vue').MaybeRef<MaybeRefWatchableError[]>} errors - The error states to monitor.
+ * @returns {import('./error.js').ReadonlyErrorStatus} An object containing aggregated reactive fields and actions for error state.
  */
 export function useProxyError(errors) {
     const error = computed(
@@ -46,3 +36,26 @@ export function useProxyError(errors) {
         },
     };
 }
+
+/**
+ * @typedef {{ state: import('vue').Reactive<import('./error.js').ErrorProperties> } & import('./error.js').ErrorReadOnlyFunctions} SeparateStateError
+ */
+
+/**
+ * Adapt an object with reactive error state into a WatchableError shape.
+ * Accepts either an object with a `state` property or an object that already exposes error/errored/clearError.
+ *
+ * @param {import('vue').MaybeRef<
+ *     SeparateStateError |
+ *     WatchableError
+ * >} source - The source object to adapt.
+ * @returns {WatchableError} - The adapted WatchableError object.
+ */
+export function asWatchableError(source) {
+    const unwrapped = unref(source);
+    if ("state" in unwrapped) {
+        const stateRefs = toRefsIfReactive(unwrapped.state);
+        return { ...stateRefs, clearError: unwrapped.clearError };
+    }
+    return toRefsIfReactive(unwrapped);
+}

package/use/proxyLoading.js

@@ -1,22 +1,35 @@
-import { computed, readonly, unref } from "vue";
+import { computed, unref } from "vue";
 import { loadingCombine } from "../utils/loadingCombine.js";
 
 /**
- * @typedef {Pick<import('./loading.js').LoadingStatus, "loading">} ReadonlyLoadingStatus
- * @typedef {import("vue").Ref<ReadonlyLoadingStatus>} RefLoadingStatus
- * @typedef {ReadonlyLoadingStatus | RefLoadingStatus} WatchableLoading
+ * @typedef {import('./loading.js').LoadingProperties | import("vue").Reactive<import('./loading.js').LoadingProperties>} WatchableLoading
+ * @typedef {import('vue').MaybeRef<WatchableLoading>} MaybeRefWatchableLoading
+ * @typedef {import('./loading.js').LoadingProperties} ReadonlyLoadingStatus
  */
 
 /**
  * A composable function for aggregating loading state across multiple sources.
  *
- * @param {WatchableLoading[]} loadings - The loading states to monitor.
+ * @param {import('vue').MaybeRef<MaybeRefWatchableLoading[]>} loadings - The loading states to monitor.
  * @returns {ReadonlyLoadingStatus} An object containing the aggregated loading field.
  */
 export function useProxyLoading(loadings) {
-    const loading = computed(() => loadingCombine(...unref(loadings).map((l) => unref(unref(l).loading))));
-
     return {
-        loading: readonly(loading),
+        loading: computed(() => loadingCombine(...unref(loadings).map((l) => unref(unref(l).loading)))),
     };
 }
+
+/**
+ * Adapt an object with reactive loading state into a WatchableLoading shape.
+ * Accepts either an object with a `state` property or an object that already exposes `loading`.
+ *
+ * @param {import('vue').MaybeRef<{ state: WatchableLoading } | WatchableLoading>} source - The source object to adapt.
+ * @returns {WatchableLoading} - The adapted WatchableLoading object.
+ */
+export function asWatchableLoading(source) {
+    const unwrappedSource = unref(source);
+    return (
+        /** @type {WatchableLoading} */
+        "state" in unwrappedSource ? unwrappedSource.state : unwrappedSource
+    );
+}

package/use/proxyLoadingError.js

@@ -1,20 +1,46 @@
-import { useProxyLoading } from "./proxyLoading.js";
-import { useProxyError } from "./proxyError.js";
+import { asWatchableLoading, useProxyLoading } from "./proxyLoading.js";
+import { asWatchableError, useProxyError } from "./proxyError.js";
+import { toRefsIfReactive } from "../utils/toRefsIfReactive.js";
+import { unref } from "vue";
 
 /**
  * @typedef {import('./proxyLoading.js').WatchableLoading & import('./proxyError.js').WatchableError} WatchableLoadingError
- * @typedef {import('./proxyLoading.js').ReadonlyLoadingStatus & import('./proxyError.js').ReadonlyErrorStatus} ProxyLoadingError
+ * @typedef {import('vue').MaybeRef<WatchableLoadingError>} MaybeRefWatchableLoadingError
+ * @typedef {import('./loading.js').LoadingProperties & import('./error.js').ReadonlyErrorStatus} ProxyLoadingError
  */
 
 /**
- * A composable function combining aggregated loading and error state.
+ * A composable function combining aggregated loading and error state. Use `asWatchableLoadingError` to convert <List|Object><Instance|Subscription> to WatchableLoadingError.
  *
- * @param {WatchableLoadingError[]} loadingErrors - The loading and error states to monitor.
+ * @param {import('vue').MaybeRef<MaybeRefWatchableLoadingError[]>} loadingErrors - The loading and error states to monitor.
  * @returns {ProxyLoadingError} - An object containing aggregated reactive fields and actions for both loading and error state.
  */
 export function useProxyLoadingError(loadingErrors) {
+    const unwrappedLoadingErrors = unref(loadingErrors);
     return {
-        ...useProxyLoading(loadingErrors),
-        ...useProxyError(loadingErrors),
+        ...useProxyLoading(unwrappedLoadingErrors),
+        ...useProxyError(unwrappedLoadingErrors),
+    };
+}
+
+/**
+ * @typedef {{ state: import('vue').Reactive<import('./error.js').ErrorProperties> } & import('./error.js').ErrorReadOnlyFunctions} SeparateStateLoadingError
+ */
+/**
+ * Adapt an object that exposes loading/error state and clearError into a WatchableLoadingError shape.
+ *
+ * @param {import('vue').MaybeRef<SeparateStateLoadingError | WatchableLoadingError>} source - The source object to adapt.
+ * @returns {WatchableLoadingError} - The adapted WatchableLoadingError object.
+ */
+export function asWatchableLoadingError(source) {
+    const unwrappedSource = unref(source);
+    const isSeparateState = "state" in unwrappedSource;
+    const normalizedRefs = /** @type {WatchableLoadingError} */ (
+        isSeparateState ? unwrappedSource.state : unwrappedSource
+    );
+    const unwrappedRefs = toRefsIfReactive(normalizedRefs);
+    return {
+        ...asWatchableLoading(unwrappedRefs),
+        ...asWatchableError(unwrappedRefs),
     };
 }

package/utils/cancellableFetch.js

@@ -11,9 +11,29 @@ import { CancellablePromise } from "./cancellablePromise.js";
  */
 export function cancellableFetch(input, init, transform) {
     const controller = new AbortController();
+    const externalSignal = init?.signal;
     const signal = controller.signal;
+    let cleanupExternalSignal = () => {};
 
-    const basePromise = fetch(input, { ...init, signal }).then(transform);
+    if (externalSignal) {
+        if (externalSignal.aborted) {
+            controller.abort(externalSignal.reason);
+        } else {
+            const handleAbort = () => {
+                controller.abort(externalSignal.reason);
+            };
+            externalSignal.addEventListener("abort", handleAbort, { once: true });
+            cleanupExternalSignal = () => {
+                externalSignal.removeEventListener("abort", handleAbort);
+            };
+        }
+    }
+
+    const basePromise = fetch(input, { ...init, signal })
+        .then(transform)
+        .finally(() => {
+            cleanupExternalSignal();
+        });
 
     return CancellablePromise(basePromise, async (/** @type {any} */ reason) => {
         controller.abort(reason);

package/utils/isReactiveTyped.js

@@ -0,0 +1,10 @@
+import { isReactive } from "vue";
+
+/**
+ * @template {object} T
+ * @param {T | import('vue').Reactive<T>} v - The value to check.
+ * @returns {v is import('vue').Reactive<T>} - True if the value is reactive, false otherwise.
+ */
+export function isReactiveTyped(v) {
+    return !!v && isReactive(v);
+}

package/utils/refIfReactive.js

@@ -7,8 +7,8 @@ import { computed, isReactive, toRef, unref } from "vue";
  * @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').ComputedRef<T[K]> | import('vue').Ref<T[K]>} The ref to the property if the source is reactive, otherwise the unrefed value.
+ * @param {T[K] | undefined} [defaultValue] - The default value to use if source or property is missing.
+ * @returns {import('vue').ComputedRef<T[K] | undefined> | import('vue').Ref<T[K] | undefined>} The ref to the property if the source is reactive; otherwise a computed that can be undefined when missing.
  */
 export const refIfReactive = (source, property, defaultValue) => {
     if (source && isReactive(source)) {
@@ -16,3 +16,23 @@ export const refIfReactive = (source, property, defaultValue) => {
     }
     return computed(() => unref(source?.[property]) ?? defaultValue);
 };
+
+/**
+ * Returns a ref to a pk property, coercing string|number input to string output.
+ * Returns undefined if the source pk is null/undefined.
+ *
+ * @param {object | undefined | null} source - The source object containing the pk.
+ * @param {string} [property="pk"] - The property name to access.
+ * @param {import('../config/commonCrud.js').Pk | null} [defaultValue=null] - The default value if missing.
+ * @returns {import('vue').ComputedRef<import('../config/commonCrud.js').Pk | undefined>} A computed ref that coerces to string.
+ */
+export const pkRefIfReactive = (source, property = "pk", defaultValue = null) => {
+    const rawRef = refIfReactive(source, property, defaultValue);
+    return computed(() => {
+        const value = unref(rawRef);
+        if (value === null || value === undefined) {
+            return undefined;
+        }
+        return String(value);
+    });
+};

package/utils/toRefsIfReactive.js

@@ -0,0 +1,28 @@
+import { toRefs } from "vue";
+import { isReactiveTyped } from "./isReactiveTyped.js";
+
+/**
+ * @template {object} T
+ * @overload
+ * @param {import('vue').Reactive<T>} source - The source reactive object.
+ * @returns {import('vue').ToRefs<T>} - The refs of the reactive object.
+ */
+/**
+ * @template {object} T
+ * @overload
+ * @param {T} source - The source object.
+ * @returns {T} - The original object.
+ */
+/**
+ * Converts a reactive object to refs, or returns the original object if not reactive.
+ *
+ * @template {object} T
+ * @param {T | import('vue').Reactive<T>} source - The source object.
+ * @returns {T | import('vue').ToRefs<T>} - The refs of the reactive object or the original object.
+ */
+export function toRefsIfReactive(source) {
+    if (isReactiveTyped(source)) {
+        return toRefs(/** @type {import('vue').Reactive<object>} */ (source));
+    }
+    return source;
+}