@arrai-innovations/reactive-helpers 21.1.2 → 22.1.0

package/types/use/objectRelated.d.ts

@@ -1,29 +1,24 @@
 /**
- * @typedef {object} ObjectRelatedProperties
+ * @typedef {object} ObjectRelatedProperties - The members (state, parentState, stop) contributed by the object related composable.
  * @property {ObjectRelatedState} state - The state of the object related instance.
  * @property {ObjectRelatedParentState} parentState - The parent state.
  * @property {() => void} stop - Stops all effects of the object related instance.
  *
  */
 /**
- * An instance of an object related reactive object.
- *
- * @typedef {ObjectRelatedProperties} ObjectRelated
+ * @typedef {ObjectRelatedProperties} ObjectRelated - An instance of an object related reactive object.
  */
 /**
- * Non-parent state options for useObjectRelated.
- *
- * @typedef {object} ObjectRelatedRawProps
+ * @typedef {object} ObjectRelatedRawProps - Non-parent state options for useObjectRelated.
  * @property {import('vue').Ref<ObjectRelatedRawRules>} relatedObjectRules - The rules for defining relationships for the managed object to other collections of objects.
  */
 /**
- * Options for useObjectRelated.
- *
  * @typedef {{
  *     parentState: ObjectRelatedParentState,
- * } & ObjectRelatedRawProps} ObjectRelatedOptions
+ * } & ObjectRelatedRawProps} ObjectRelatedOptions - Options for useObjectRelated.
  */
 /**
+ * Creates multiple object related instances keyed by name from a map of options.
  *
  * @param {{
  *     [key: string]: ObjectRelatedOptions
@@ -88,7 +83,7 @@ export function useObjectRelateds(objectRelatedArgs: {
  *             order: ['3','1','2'],
  *         },
  *         secondOrder: {
- *             pkKey: 'relatedObject.secondOrderId',
+ *             pkKey: 'relatedItem.firstOrder.secondOrderId',
  *             objects: someOtherObjectsSource.objects,
  *         },
  *     },
@@ -119,28 +114,25 @@ export function useObjectRelated({ parentState, relatedObjectRules }: ObjectRela
  * @module use/objectRelated.js
  */
 /**
- * The rule for defining relationships for the managed object to other collections of objects.
- *
- * @typedef {object} ObjectRelatedRule
- * @property {string} pkKey - The key in the managed object that corresponds to the key in the related object.
+ * @typedef {object} ObjectRelatedRule - The rule for defining relationships for the managed object to other collections of objects.
+ * @property {string} [pkKey] - The key in the managed object that corresponds to the key in the related object.
+ *  Defaults to the rule's own key when omitted.
  * @property {import('./listInstance.js').ObjectsByPk} objects - The related objects, indexed by the key in the related object.
- * @property {string[]} order - The order of the related objects, if the related objects are an array.
+ * @property {string[]} [order] - The order of the related objects, if the related objects are an array.
  */
 /**
- * The rules for defining relationships for the managed object to other collections of objects.
- *
  * @typedef {{
  *     [rule: string]: ObjectRelatedRule,
- * }} ObjectRelatedRawRules
+ * }} ObjectRelatedRawRules - The rules for defining relationships for the managed object to other collections of objects.
  */
 /**
  *
  *
- * @typedef {object} ObjectRelatedRawState
+ * @typedef {object} ObjectRelatedRawState - The raw reactive state of the object related composable, holding its rules, computed relations, and running flags.
  * @property {ObjectRelatedRawRules} relatedObjectRules - The rules for defining relationships for the managed object to other collections of objects.
  * @property {{
- *     [rule: string]: import('vue').ComputedRef<any>,
- * }} relatedObject - The related objects, indexed by the key in the related object.
+ *     [rule: string]: any,
+ * }} relatedObject - The related objects, by rule name. Each entry is backed by a computed, but it is read through a reactive proxy that unwraps it, so reads yield the related object (or array of related objects) and never carry a `.value`.
  * @property {boolean} relatedObjectWatchRunning - Whether the related object watch is running.
  * @property {boolean} parentStateObjectWatchRunning - Whether the parent state object watch is running.
  * @property {boolean} relatedRunning - Whether the related objects are loading.
@@ -152,12 +144,12 @@ export function useObjectRelated({ parentState, relatedObjectRules }: ObjectRela
  * @typedef {(
  *    import('./objectInstance.js').ObjectInstanceRawState &
  *    Partial<import('./objectSubscription.js').ObjectSubscriptionRawState>
- * )} ObjectRelatedParentRawState
+ * )} ObjectRelatedParentRawState - The raw, pre-unwrapped parent state consumed by the object related mixin (object instance plus optional subscription state).
  */
 /**
  *
  *
- * @typedef {import('vue').UnwrapNestedRefs<ObjectRelatedParentRawState>} ObjectRelatedParentState
+ * @typedef {import('vue').UnwrapNestedRefs<ObjectRelatedParentRawState>} ObjectRelatedParentState - The unwrapped reactive parent state consumed by the object related mixin.
  */
 /**
  *
@@ -165,21 +157,26 @@ export function useObjectRelated({ parentState, relatedObjectRules }: ObjectRela
  * @typedef {import('vue').UnwrapNestedRefs<(
  *     ObjectRelatedParentRawState &
  *     ObjectRelatedRawState
- * )>} ObjectRelatedState
+ * )>} ObjectRelatedState - The unwrapped reactive state of the object related composable, combining the parent state with its own related state.
  */
+/** @internal */
 export const objectRelatedStateKeys: string[];
+/** @internal */
 export const objectRelatedFunctions: any[];
+/**
+ * The members (state, parentState, stop) contributed by the object related composable.
+ */
 export type ObjectRelatedProperties = {
     /**
-     * - The state of the object related instance.
+     * The state of the object related instance.
      */
     state: ObjectRelatedState;
     /**
-     * - The parent state.
+     * The parent state.
      */
     parentState: ObjectRelatedParentState;
     /**
-     * - Stops all effects of the object related instance.
+     * Stops all effects of the object related instance.
      */
     stop: () => void;
 };
@@ -192,7 +189,7 @@ export type ObjectRelated = ObjectRelatedProperties;
  */
 export type ObjectRelatedRawProps = {
     /**
-     * - The rules for defining relationships for the managed object to other collections of objects.
+     * The rules for defining relationships for the managed object to other collections of objects.
      */
     relatedObjectRules: import("vue").Ref<ObjectRelatedRawRules>;
 };
@@ -207,17 +204,18 @@ export type ObjectRelatedOptions = {
  */
 export type ObjectRelatedRule = {
     /**
-     * - The key in the managed object that corresponds to the key in the related object.
+     * The key in the managed object that corresponds to the key in the related object.
+     * Defaults to the rule's own key when omitted.
      */
-    pkKey: string;
+    pkKey?: string;
     /**
-     * - The related objects, indexed by the key in the related object.
+     * The related objects, indexed by the key in the related object.
      */
     objects: import("./listInstance.js").ObjectsByPk;
     /**
-     * - The order of the related objects, if the related objects are an array.
+     * The order of the related objects, if the related objects are an array.
      */
-    order: string[];
+    order?: string[];
 };
 /**
  * The rules for defining relationships for the managed object to other collections of objects.
@@ -225,34 +223,46 @@ export type ObjectRelatedRule = {
 export type ObjectRelatedRawRules = {
     [rule: string]: ObjectRelatedRule;
 };
+/**
+ * The raw reactive state of the object related composable, holding its rules, computed relations, and running flags.
+ */
 export type ObjectRelatedRawState = {
     /**
-     * - The rules for defining relationships for the managed object to other collections of objects.
+     * The rules for defining relationships for the managed object to other collections of objects.
      */
     relatedObjectRules: ObjectRelatedRawRules;
     /**
-     * - The related objects, indexed by the key in the related object.
+     * The related objects, by rule name. Each entry is backed by a computed, but it is read through a reactive proxy that unwraps it, so reads yield the related object (or array of related objects) and never carry a `.value`.
      */
     relatedObject: {
-        [rule: string]: import("vue").ComputedRef<any>;
+        [rule: string]: any;
     };
     /**
-     * - Whether the related object watch is running.
+     * Whether the related object watch is running.
      */
     relatedObjectWatchRunning: boolean;
     /**
-     * - Whether the parent state object watch is running.
+     * Whether the parent state object watch is running.
      */
     parentStateObjectWatchRunning: boolean;
     /**
-     * - Whether the related objects are loading.
+     * Whether the related objects are loading.
      */
     relatedRunning: boolean;
     /**
-     * - Whether the related objects are loading or the parent state is loading.
+     * Whether the related objects are loading or the parent state is loading.
      */
     running: boolean;
 };
+/**
+ * The raw, pre-unwrapped parent state consumed by the object related mixin (object instance plus optional subscription state).
+ */
 export type ObjectRelatedParentRawState = (import("./objectInstance.js").ObjectInstanceRawState & Partial<import("./objectSubscription.js").ObjectSubscriptionRawState>);
+/**
+ * The unwrapped reactive parent state consumed by the object related mixin.
+ */
 export type ObjectRelatedParentState = import("vue").UnwrapNestedRefs<ObjectRelatedParentRawState>;
+/**
+ * The unwrapped reactive state of the object related composable, combining the parent state with its own related state.
+ */
 export type ObjectRelatedState = import("vue").UnwrapNestedRefs<(ObjectRelatedParentRawState & ObjectRelatedRawState)>;

package/types/use/objectSubscription.d.ts

@@ -1,29 +1,21 @@
 /**
- * The raw state of the object subscription.
- *
- * @typedef {object} ObjectSubscriptionRawState
+ * @typedef {object} ObjectSubscriptionRawState - The raw state of the object subscription.
  * @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').Reactive<
  *     ObjectSubscriptionRawState &
  *     import('./objectInstance.js').ObjectInstanceRawState
- * >} ObjectSubscriptionState
+ * >} ObjectSubscriptionState - The state of the object subscription, including both subscription and object instance states.
  */
 /**
- * Functions available for object subscription management.
- *
- * @typedef {object} ObjectSubscriptionFunctions
+ * @typedef {object} ObjectSubscriptionFunctions - Functions available for object subscription management.
  * @property {() => void} clearError - Clears any errors related to the subscription, and resets the loading state.
  */
 /**
- * Properties of the object subscription.
- *
- * @typedef {object} ObjectSubscriptionProperties
+ * @typedef {object} ObjectSubscriptionProperties - Properties of the object subscription.
  * @property {ObjectSubscriptionState} state - The object instance properties.
  * @property {import('./objectInstance.js').ObjectInstance} objectInstance - The object instance.
  * @property {import('./cancellableIntent.js').CancellableIntent} subscribeIntent - The subscribe intent.
@@ -31,19 +23,15 @@
  * @property {() => void} stop - Stops the subscription reactive effects.
  */
 /**
- * The object subscription instance, combining state, properties, and functions.
- *
- * @typedef {ObjectSubscriptionProperties & ObjectSubscriptionFunctions} ObjectSubscription
+ * @typedef {ObjectSubscriptionProperties & ObjectSubscriptionFunctions} ObjectSubscription - The object subscription instance, combining state, properties, and functions.
  */
 /**
- * Raw props for the object subscription.
- *
- * @typedef {object} ObjectSubscriptionRawProps
+ * @typedef {object} ObjectSubscriptionRawProps - Raw props for the object subscription.
  * @property {boolean|undefined} intendToRetrieve - Whether the object intends to retrieve.
  * @property {boolean|undefined} intendToSubscribe - Whether the object intends to subscribe.
  */
 /**
- * @typedef {object} ObjectSubscriptionOwnOptions
+ * @typedef {object} ObjectSubscriptionOwnOptions - The options specific to an object subscription (reactive props, an optional instance to reuse, and handlers).
  * @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
@@ -51,9 +39,7 @@
  * @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
+ * @typedef {ObjectSubscriptionOwnOptions & import('./objectInstance.js').ObjectInstanceOptions} ObjectSubscriptionOptions - Options for initializing an object subscription, including reactive props and non-reactive handlers.
  */
 /**
  * Initializes multiple object subscriptions based on provided arguments.
@@ -67,9 +53,7 @@ export function useObjectSubscriptions(subscriptionArgs: {
     [key: string]: ObjectSubscription;
 };
 /**
- * The context bound to shared objectSubscription functions.
- *
- * @typedef {object} ObjectSubscriptionContext
+ * @typedef {object} ObjectSubscriptionContext - The context bound to shared objectSubscription functions.
  * @property {ObjectSubscriptionState} state - The object subscription state.
  * @property {import('./objectInstance.js').ObjectInstance} objectInstance - The object instance.
  * @property {import('./cancellableIntent.js').CancellableIntent} subscribeIntent - The subscribe intent.
@@ -82,7 +66,7 @@ export function useObjectSubscriptions(subscriptionArgs: {
  * ```
  * <script setup>
  * import { useObjectSubscription } from "@arrai-innovations/reactive-helpers";
- * import { reactive, ref, toRef } from "vue";
+ * import { reactive, toRef } from "vue";
  *
  * const pkKey = "id";
  * const props = defineProps({
@@ -101,11 +85,12 @@ export function useObjectSubscriptions(subscriptionArgs: {
  *     params: {
  *         fields: ['foo', 'bar'],
  *     },
- *     intendToRetrieve: false,
- *     intendToSubscribe: false,
+ *     intendToRetrieve: true,
+ *     intendToSubscribe: true,
+ * });
+ * const objectSubscription = useObjectSubscription({
+ *     props: objectSubscriptionProps,
  * });
- * objectSubscriptionProps.intendToRetrieve = objectSubscriptionProps.intendToSubscribe = computed(()=> !!props.pk);
- * const objectSubscription = useObjectSubscription(objectSubscriptionProps);
  * </script>
  * <template>
  *     <div v-if="objectSubscription.state.loading">Loading...</div>
@@ -137,22 +122,24 @@ export class ObjectSubscriptionError extends Error {
     constructor(message: string, code: string);
     code: string;
 }
+/** @internal */
 export const objectSubscriptionStateKeys: string[];
+/** @internal */
 export const objectSubscriptionFunctions: string[];
 /**
  * The raw state of the object subscription.
  */
 export type ObjectSubscriptionRawState = {
     /**
-     * - Whether the object intends to retrieve.
+     * Whether the object intends to retrieve.
      */
     intendToRetrieve: import("vue").Ref<boolean>;
     /**
-     * - Whether the object intends to subscribe.
+     * Whether the object intends to subscribe.
      */
     intendToSubscribe: import("vue").Ref<boolean>;
     /**
-     * - Whether the object is subscribed.
+     * Whether the object is subscribed.
      */
     subscribed: import("vue").Ref<boolean | undefined>;
 };
@@ -165,7 +152,7 @@ export type ObjectSubscriptionState = import("vue").Reactive<ObjectSubscriptionR
  */
 export type ObjectSubscriptionFunctions = {
     /**
-     * - Clears any errors related to the subscription, and resets the loading state.
+     * Clears any errors related to the subscription, and resets the loading state.
      */
     clearError: () => void;
 };
@@ -174,23 +161,23 @@ export type ObjectSubscriptionFunctions = {
  */
 export type ObjectSubscriptionProperties = {
     /**
-     * - The object instance properties.
+     * The object instance properties.
      */
     state: ObjectSubscriptionState;
     /**
-     * - The object instance.
+     * The object instance.
      */
     objectInstance: import("./objectInstance.js").ObjectInstance;
     /**
-     * - The subscribe intent.
+     * The subscribe intent.
      */
     subscribeIntent: import("./cancellableIntent.js").CancellableIntent;
     /**
-     * - The retrieve intent.
+     * The retrieve intent.
      */
     retrieveIntent: import("./cancellableIntent.js").CancellableIntent;
     /**
-     * - Stops the subscription reactive effects.
+     * Stops the subscription reactive effects.
      */
     stop: () => void;
 };
@@ -203,25 +190,28 @@ export type ObjectSubscription = ObjectSubscriptionProperties & ObjectSubscripti
  */
 export type ObjectSubscriptionRawProps = {
     /**
-     * - Whether the object intends to retrieve.
+     * Whether the object intends to retrieve.
      */
     intendToRetrieve: boolean | undefined;
     /**
-     * - Whether the object intends to subscribe.
+     * Whether the object intends to subscribe.
      */
     intendToSubscribe: boolean | undefined;
 };
+/**
+ * The options specific to an object subscription (reactive props, an optional instance to reuse, and handlers).
+ */
 export type ObjectSubscriptionOwnOptions = {
     /**
-     * - An object instance to use instead of creating a new one.
+     * An object instance to use instead of creating a new one.
      */
     objectInstance?: import("./objectInstance.js").ObjectInstance;
     /**
-     * - The reactive args to be passed to useObjectInstance.
+     * The reactive args to be passed to useObjectInstance.
      */
     props: import("vue").UnwrapNestedRefs<(ObjectSubscriptionRawProps & import("./objectInstance.js").ObjectInstanceRawProps)>;
     /**
-     * - The handlers to be passed to useObjectInstance.
+     * The handlers to be passed to useObjectInstance.
      */
     handlers?: import("../config/objectCrud.js").ObjectCrudHandlers;
 };
@@ -234,19 +224,19 @@ export type ObjectSubscriptionOptions = ObjectSubscriptionOwnOptions & import(".
  */
 export type ObjectSubscriptionContext = {
     /**
-     * - The object subscription state.
+     * The object subscription state.
      */
     state: ObjectSubscriptionState;
     /**
-     * - The object instance.
+     * The object instance.
      */
     objectInstance: import("./objectInstance.js").ObjectInstance;
     /**
-     * - The subscribe intent.
+     * The subscribe intent.
      */
     subscribeIntent: import("./cancellableIntent.js").CancellableIntent;
     /**
-     * - The retrieve intent.
+     * The retrieve intent.
      */
     retrieveIntent: import("./cancellableIntent.js").CancellableIntent;
 };

package/types/use/proxyError.d.ts

@@ -1,16 +1,16 @@
 /**
- * @typedef {import('./error.js').ReadonlyErrorStatus | import("vue").Reactive<import('./error.js').ReadonlyErrorStatus>} WatchableError
- * @typedef {import('vue').MaybeRef<WatchableError>} MaybeRefWatchableError
+ * @typedef {import('./error.js').ReadonlyErrorStatus | import("vue").Reactive<import('./error.js').ReadonlyErrorStatus>} WatchableError - An error source (a possibly-reactive readonly error status) that useProxyError can aggregate.
+ * @typedef {import('vue').MaybeRefOrGetter<WatchableError>} MaybeRefWatchableError - A watchable error source that may itself be wrapped in a ref or getter.
  */
 /**
  * A composable function for aggregating error state across multiple sources.
  *
- * @param {import('vue').MaybeRef<MaybeRefWatchableError[]>} errors - The error states to monitor.
+ * @param {import('vue').MaybeRefOrGetter<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: import("vue").MaybeRef<MaybeRefWatchableError[]>): import("./error.js").ReadonlyErrorStatus;
+export function useProxyError(errors: import("vue").MaybeRefOrGetter<MaybeRefWatchableError[]>): import("./error.js").ReadonlyErrorStatus;
 /**
- * @typedef {{ state: import('vue').Reactive<import('./error.js').ErrorProperties> } & import('./error.js').ErrorReadOnlyFunctions} SeparateStateError
+ * @typedef {{ state: import('vue').Reactive<import('./error.js').ErrorProperties> } & import('./error.js').ErrorReadOnlyFunctions} SeparateStateError - An error source whose reactive properties live under a state member, alongside its clearError action.
  */
 /**
  * Adapt an object with reactive error state into a WatchableError shape.
@@ -23,8 +23,17 @@ export function useProxyError(errors: import("vue").MaybeRef<MaybeRefWatchableEr
  * @returns {WatchableError} - The adapted WatchableError object.
  */
 export function asWatchableError(source: import("vue").MaybeRef<SeparateStateError | WatchableError>): WatchableError;
+/**
+ * An error source (a possibly-reactive readonly error status) that useProxyError can aggregate.
+ */
 export type WatchableError = import("./error.js").ReadonlyErrorStatus | import("vue").Reactive<import("./error.js").ReadonlyErrorStatus>;
-export type MaybeRefWatchableError = import("vue").MaybeRef<WatchableError>;
+/**
+ * A watchable error source that may itself be wrapped in a ref or getter.
+ */
+export type MaybeRefWatchableError = import("vue").MaybeRefOrGetter<WatchableError>;
+/**
+ * An error source whose reactive properties live under a state member, alongside its clearError action.
+ */
 export type SeparateStateError = {
     state: import("vue").Reactive<import("./error.js").ErrorProperties>;
 } & import("./error.js").ErrorReadOnlyFunctions;

package/types/use/proxyLoading.d.ts

@@ -1,15 +1,15 @@
 /**
- * @typedef {import('./loading.js').LoadingProperties | import("vue").Reactive<import('./loading.js').LoadingProperties>} WatchableLoading
- * @typedef {import('vue').MaybeRef<WatchableLoading>} MaybeRefWatchableLoading
+ * @typedef {import('./loading.js').LoadingProperties | import("vue").Reactive<import('./loading.js').LoadingProperties>} WatchableLoading - A loading source (possibly-reactive loading properties) that useProxyLoading can aggregate.
+ * @typedef {import('vue').MaybeRefOrGetter<WatchableLoading>} MaybeRefWatchableLoading - A watchable loading source that may itself be wrapped in a ref or getter.
  * @typedef {import('./loading.js').LoadingProperties} ReadonlyLoadingStatus
  */
 /**
  * A composable function for aggregating loading state across multiple sources.
  *
- * @param {import('vue').MaybeRef<MaybeRefWatchableLoading[]>} loadings - The loading states to monitor.
+ * @param {import('vue').MaybeRefOrGetter<MaybeRefWatchableLoading[]>} loadings - The loading states to monitor.
  * @returns {ReadonlyLoadingStatus} An object containing the aggregated loading field.
  */
-export function useProxyLoading(loadings: import("vue").MaybeRef<MaybeRefWatchableLoading[]>): ReadonlyLoadingStatus;
+export function useProxyLoading(loadings: import("vue").MaybeRefOrGetter<MaybeRefWatchableLoading[]>): ReadonlyLoadingStatus;
 /**
  * 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`.
@@ -20,6 +20,12 @@ export function useProxyLoading(loadings: import("vue").MaybeRef<MaybeRefWatchab
 export function asWatchableLoading(source: import("vue").MaybeRef<{
     state: WatchableLoading;
 } | WatchableLoading>): WatchableLoading;
+/**
+ * A loading source (possibly-reactive loading properties) that useProxyLoading can aggregate.
+ */
 export type WatchableLoading = import("./loading.js").LoadingProperties | import("vue").Reactive<import("./loading.js").LoadingProperties>;
-export type MaybeRefWatchableLoading = import("vue").MaybeRef<WatchableLoading>;
+/**
+ * A watchable loading source that may itself be wrapped in a ref or getter.
+ */
+export type MaybeRefWatchableLoading = import("vue").MaybeRefOrGetter<WatchableLoading>;
 export type ReadonlyLoadingStatus = import("./loading.js").LoadingProperties;

package/types/use/proxyLoadingError.d.ts

@@ -1,17 +1,17 @@
 /**
- * @typedef {import('./proxyLoading.js').WatchableLoading & import('./proxyError.js').WatchableError} WatchableLoadingError
- * @typedef {import('vue').MaybeRef<WatchableLoadingError>} MaybeRefWatchableLoadingError
- * @typedef {import('./loading.js').LoadingProperties & import('./error.js').ReadonlyErrorStatus} ProxyLoadingError
+ * @typedef {import('./proxyLoading.js').WatchableLoading & import('./proxyError.js').WatchableError} WatchableLoadingError - A combined loading-and-error source that useProxyLoadingError can aggregate.
+ * @typedef {import('vue').MaybeRefOrGetter<WatchableLoadingError>} MaybeRefWatchableLoadingError - A watchable combined loading-and-error source that may itself be wrapped in a ref or getter.
+ * @typedef {import('./loading.js').LoadingProperties & import('./error.js').ReadonlyErrorStatus} ProxyLoadingError - The aggregated loading and error state returned by useProxyLoadingError.
  */
 /**
  * A composable function combining aggregated loading and error state. Use `asWatchableLoadingError` to convert <List|Object><Instance|Subscription> to WatchableLoadingError.
  *
- * @param {import('vue').MaybeRef<MaybeRefWatchableLoadingError[]>} loadingErrors - The loading and error states to monitor.
+ * @param {import('vue').MaybeRefOrGetter<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: import("vue").MaybeRef<MaybeRefWatchableLoadingError[]>): ProxyLoadingError;
+export function useProxyLoadingError(loadingErrors: import("vue").MaybeRefOrGetter<MaybeRefWatchableLoadingError[]>): ProxyLoadingError;
 /**
- * @typedef {{ state: import('vue').Reactive<import('./error.js').ErrorProperties> } & import('./error.js').ErrorReadOnlyFunctions} SeparateStateLoadingError
+ * @typedef {{ state: import('vue').Reactive<import('./error.js').ErrorProperties> } & import('./error.js').ErrorReadOnlyFunctions} SeparateStateLoadingError - A combined loading-and-error source whose reactive properties live under a state member, alongside its clearError action.
  */
 /**
  * Adapt an object that exposes loading/error state and clearError into a WatchableLoadingError shape.
@@ -20,9 +20,21 @@ export function useProxyLoadingError(loadingErrors: import("vue").MaybeRef<Maybe
  * @returns {WatchableLoadingError} - The adapted WatchableLoadingError object.
  */
 export function asWatchableLoadingError(source: import("vue").MaybeRef<SeparateStateLoadingError | WatchableLoadingError>): WatchableLoadingError;
+/**
+ * A combined loading-and-error source that useProxyLoadingError can aggregate.
+ */
 export type WatchableLoadingError = import("./proxyLoading.js").WatchableLoading & import("./proxyError.js").WatchableError;
-export type MaybeRefWatchableLoadingError = import("vue").MaybeRef<WatchableLoadingError>;
+/**
+ * A watchable combined loading-and-error source that may itself be wrapped in a ref or getter.
+ */
+export type MaybeRefWatchableLoadingError = import("vue").MaybeRefOrGetter<WatchableLoadingError>;
+/**
+ * The aggregated loading and error state returned by useProxyLoadingError.
+ */
 export type ProxyLoadingError = import("./loading.js").LoadingProperties & import("./error.js").ReadonlyErrorStatus;
+/**
+ * A combined loading-and-error source whose reactive properties live under a state member, alongside its clearError action.
+ */
 export type SeparateStateLoadingError = {
     state: import("vue").Reactive<import("./error.js").ErrorProperties>;
 } & import("./error.js").ErrorReadOnlyFunctions;