@arrai-innovations/reactive-helpers 13.0.4 → 13.1.0

package/docs/README.md

@@ -26,6 +26,7 @@
 - [use/objectRelated](use/objectRelated.md)
 - [use/objectSubscription](use/objectSubscription.md)
 - [use/paginatedListInstance](use/paginatedListInstance.md)
+- [use/proxyLoadingError](use/proxyLoadingError.md)
 - [use/search](use/search.md)
 - [use/watchesRunning](use/watchesRunning.md)
 - [utils/assignReactiveObject](utils/assignReactiveObject.md)

package/docs/config/listCrud.md

@@ -289,6 +289,8 @@ The props to set for the crud.
 
 > **setListCrud**(`options`): `void`
 
+Set the list and subscribe functions for the default crud.
+
 #### Parameters
 
 • **options**: [`ListCrudFunctions`](listCrud.md#listcrudfunctions) & `Partial`\<[`ListCrudArgs`](listCrud.md#listcrudargs)\>
@@ -298,3 +300,7 @@ The options for the default crud.
 #### Returns
 
 `void`
+
+#### Throws
+
+- If unknown keys are passed.

package/docs/config/objectCrud.md

@@ -326,6 +326,10 @@ The arguments to be passed to the crud functions.
 
 `void`
 
+#### Throws
+
+- If an invalid function is passed, or if the function is not a function.
+
 ***
 
 ### setObjectCrud()
@@ -343,3 +347,7 @@ The options for the object crud functions.
 #### Returns
 
 `void`
+
+#### Throws
+
+- if unknown keys are passed.

package/docs/use/list.md

@@ -254,6 +254,9 @@ Current text query used for filtering the list.
 
 > **useList**(`options`): [`ListManager`](list.md#listmanager)
 
+Creates and manages an enhanced list instance by orchestrating various list-related composables.
+It ensures seamless integration of all list functionalities such as sorting, searching, filtering, and advanced state management.
+
 #### Parameters
 
 • **options**: [`ListOptions`](list.md#listoptions)
@@ -266,12 +269,19 @@ The options for the list./.
 
 - The managed stack of list-related composable functions.
 
+#### Example
+
+```vue
+```
+
 ***
 
 ### useLists()
 
 > **useLists**(`listOptions`): `object`
 
+Initializes multiple list management instances with provided configurations.
+
 #### Parameters
 
 • **listOptions**

package/docs/use/loadingError.md

@@ -8,25 +8,55 @@
 
 ## Interfaces
 
-### LoadingError
+### LoadingErrorMutations
 
 #### Properties
 
-##### clearError()
+##### clearLoading()
 
-> **clearError**: () => `void`
+> **clearLoading**: () => `void`
 
-Clear the error state.
+Clear the loading state.
 
 ###### Returns
 
 `void`
 
-##### clearLoading()
+##### setError()
 
-> **clearLoading**: () => `void`
+> **setError**: (`error`) => `void`
 
-Clear the loading state.
+Set the error state.
+
+###### Parameters
+
+• **error**: `any`
+
+###### Returns
+
+`void`
+
+##### setLoading()
+
+> **setLoading**: () => `void`
+
+Set the loading state.
+
+###### Returns
+
+`void`
+
+***
+
+### LoadingErrorStatus
+
+#### Properties
+
+##### clearError()
+
+> **clearError**: () => `void`
+
+Clear the error state.
 
 ###### Returns
 
@@ -50,29 +80,13 @@ Whether an error has occurred.
 
 Whether the component is loading.
 
-##### setError()
-
-> **setError**: (`error`) => `void`
-
-Set the error state.
+## Type Aliases
 
-###### Parameters
-
-• **error**: `any`
-
-###### Returns
-
-`void`
-
-##### setLoading()
-
-> **setLoading**: () => `void`
-
-Set the loading state.
+### LoadingError
 
-###### Returns
+> **LoadingError**\<\>: [`LoadingErrorStatus`](loadingError.md#loadingerrorstatus) & [`LoadingErrorMutations`](loadingError.md#loadingerrormutations)
 
-`void`
+#### Type Parameters
 
 ## Functions
 

package/docs/use/object.md

@@ -502,6 +502,8 @@ Whether the subscription is loading.
 
 > **useObject**(`options`): [`ObjectManager`](object.md#objectmanager)
 
+Initializes a chain of useObject* functions, returning an object of them.
+
 #### Parameters
 
 • **options**: [`ObjectManagerOptions`](object.md#objectmanageroptions)
@@ -514,12 +516,105 @@ The options to be passed to useObjectInstance, useObjectSubscription, useObjectR
 
 - An object managing a chain of useObject* instances.
 
+#### Example
+
+```
+<script setup>
+import { useObject } from "@arrai-innovations/reactive-helpers";
+import { reactive, ref, toRef } from "vue";
+
+const someObjectsSource = reactive({
+    objects: {
+        '1': { id: 1, name: 'one', secondOrderId: 15 },
+        '2': { id: 2, name: 'two', secondOrderId: 10 },
+        '3': { id: 3, name: 'three', secondOrderId: 5 },
+    },
+});
+const someOtherObjectsSource = reactive({
+    objects: {
+        '5': { id: 5, name: 'five' },
+        '10': { id: 10, name: 'ten' },
+        '15': { id: 15, name: 'fifteen' },
+    },
+});
+const props = defineProps({
+    app: { type: String, required: true },
+    model: { type: String, required: true },
+    id: { type: String, default: "" },
+});
+
+const objectProps = reactive({
+    crudArgs: {
+        app: toRef(props, "app"),
+        model: toRef(props, "model"),
+    },
+    retrieveArgs: {
+        fields: ['foo', 'bar'],
+    },
+    relatedObjectRules: {
+        firstOrder: {
+            pkKey: 'some_objects_id',
+            objects: someObjectsSource.objects,
+        },
+        some_objects_list_ids: {
+            // pkKey defaults to match rule name
+            objects: someObjectsSource.objects,
+            order: ['3','1','2'],
+        },
+        secondOrder: {
+            pkKey: 'relatedObject.secondOrderId',
+            objects: someOtherObjectsSource.objects,
+        },
+    },
+    calculatedObjectRules: {
+        someRule: (object, relatedObject, calculatedObjects) => {
+            // some complex calculation, relatedObjects would be assuming there was a listRelated between the two
+            // calculatedObjects would be the other calculated objects in the list
+            // including yourself, so try not to create circular dependencies
+            // this is used as a computed body.
+            return object.foo + object.name;
+        },
+        ...
+    },
+    intendToRetrieve: false,
+    intendToSubscribe: false,
+});
+objectProps.intendToRetrieve = objectProps.intendToSubscribe = computed(()=> !!props.id);
+const objectManager = useObject(objectProps);
+// objectManager.state.object comes back from the server (via configured crud retrieve function)
+// { id: 2, name: 'two', foo: 'bar', some_objects_id: 2, some_objects_list_ids: ['1','2','3'] }
+</script>
+<template>
+<div v-if="objectManager.state.loading">Loading...</div>
+<div v-else-if="objectManager.state.errored">Error: {{ objectManager.state.error.message }}</div>
+<div v-else-if="objectManager.state.object.id">
+    <p>Foo: {{ objectManager.state.object.foo }}</p>
+    <!-- 'bar' -->
+
+    <p>{{ objectManager.state.relatedObject.firstOrder }}</p>
+     <!-- { id: 2, name: 'two', secondOrderId: 10 } -->
+
+     <p>{{ objectManager.state.relatedObject.some_objects_list_ids }}</p>
+     <!-- [{ id: 3, name: 'three', secondOrderId: 5 }, { id: 1, name: 'one', secondOrderId: 15 }, { id: 2, name: 'two', secondOrderId: 10 }] -->
+
+     <p>{{ objectManager.state.relatedObject.secondOrder }}</p>
+     <!-- { id: 10, name: 'ten' } -->
+
+     <p>{{ objectManager.state.calculatedObject.someRule }}</p>
+     <!-- 'bartwo' -->
+</div>
+<div v-else>Object not found.</div>
+</template>
+```
+
 ***
 
 ### useObjects()
 
 > **useObjects**(`objectArgs`): `object`
 
+Initializes multiple useObject instances, returning an object of them based on the keys of the objectArgs.
+
 #### Parameters
 
 • **objectArgs**

package/docs/use/proxyLoadingError.md

@@ -0,0 +1,49 @@
+[**@arrai-innovations/reactive-helpers**](../README.md) • **Docs**
+
+***
+
+[@arrai-innovations/reactive-helpers](../README.md) / use/proxyLoadingError
+
+# use/proxyLoadingError
+
+## References
+
+### ProxyLoadingError
+
+Renames and re-exports [LoadingErrorStatus](loadingError.md#loadingerrorstatus)
+
+## Type Aliases
+
+### WatchableLoadingErrors
+
+> **WatchableLoadingErrors**\<\>: `UnwrapNestedRefs` \| `Ref` \| [`WatchableLoadingErrorsRaw`](proxyLoadingError.md#watchableloadingerrorsraw)
+
+#### Type Parameters
+
+***
+
+### WatchableLoadingErrorsRaw
+
+> **WatchableLoadingErrorsRaw**\<\>: [`use/loadingError`](loadingError.md)[]
+
+#### Type Parameters
+
+## Functions
+
+### useProxyLoadingError()
+
+> **useProxyLoadingError**(`loadingErrors`): [`LoadingErrorStatus`](loadingError.md#loadingerrorstatus)
+
+A composable function for managing aggregated loading and error states across multiple sources.
+
+#### Parameters
+
+• **loadingErrors**: [`WatchableLoadingErrors`](proxyLoadingError.md#watchableloadingerrors)
+
+A collection of loading error statuses to monitor and aggregate.
+
+#### Returns
+
+[`LoadingErrorStatus`](loadingError.md#loadingerrorstatus)
+
+An object containing aggregated reactive fields and actions for loading and error states.

package/docs/utils/classes.md

@@ -30,6 +30,11 @@ The normalized form of the CSS classes, either as a string of space-separated cl
 
 > **combineClasses**(...`classes`): [`CombinedClasses`](classes.md#combinedclasses)
 
+Combines and normalizes different formats of CSS class specifications into a single format suitable for Vue.js
+ components. If objects are in the mix, objects are returned. Otherwise, a string is returned.
+
+We unref your refs, so probably want a computed around this.
+
 #### Parameters
 
 • ...**classes**: ([`CombinedClassesArgument`](classes.md#combinedclassesargument) \| [`CombinedClassesArgument`](classes.md#combinedclassesargument)[])[]
@@ -50,6 +55,8 @@ A variable list of class specifications in
 
 > **objectifyClasses**(...`classes`): `object` \| `object`[]
 
+Normalize various ways of specifying CSS classes into an object for use in Vue.js.
+
 #### Parameters
 
 • ...**classes**: (`string` \| `string`[] \| `string`[][] \| `object` \| `Ref`\<`string` \| `string`[] \| `string`[][]\>)[]
@@ -69,6 +76,8 @@ An object or array of objects containing CSS classes. Arrays are used if refs ar
 
 > **stringifyClass**(`cls`): `string`
 
+Normalizes various ways of specifying CSS classes into a space-separated list of CSS classes.
+
 #### Parameters
 
 • **cls**: `string` \| `string`[] \| `object`
@@ -87,6 +96,8 @@ A space-separated list of CSS classes.
 
 > **stringifyClasses**(...`classes`): `string`
 
+Normalizes various ways of specifying CSS classes into a space-separated list of CSS classes.
+
 #### Parameters
 
 • ...**classes**: (`string` \| `string`[] \| `object`)[]

package/docs/utils/compact.md

@@ -30,6 +30,8 @@ The object or array to compact sparse arrays in.
 
 > **removeEmptyObjects**(`obj`): `void`
 
+Remove empty objects from a mixed object array tree. Mutates the object.
+
 #### Parameters
 
 • **obj**: `any`
@@ -46,6 +48,8 @@ The object or array to remove empty objects from.
 
 > **removeEmptyObjectsAndCompactSparseArrays**(`obj`): `void`
 
+Remove empty objects and undefined values from arrays in a mixed object array tree. Mutates the object.
+
 #### Parameters
 
 • **obj**: `any`

package/docs/utils/relatedCalculatedHelpers.md

@@ -24,6 +24,8 @@
 
 > **getObjectRelatedByKey**(`obj`, `relatedObj`, `key`): [`any`, `string`]
 
+Get the object and key of a related item.
+
 #### Parameters
 
 • **obj**: `any`
@@ -50,6 +52,8 @@ The object and key of the related item.
 
 > **getObjectRelatedCalculatedByKey**(`obj`, `relatedObj`, `calculatedObj`, `key`): [`any`, `string`]
 
+Get the object and key of a calculated item.
+
 #### Parameters
 
 • **obj**: `any`

package/docs/utils/set.md

@@ -12,6 +12,8 @@
 
 > **difference**(`setA`, `setB`): `Set`\<`any`\>
 
+Returns the difference of two sets, containing elements present only in the first set but not in the second.
+
 #### Parameters
 
 • **setA**: `Set`\<`any`\>
@@ -28,12 +30,22 @@ The second set.
 
 A new Set containing elements from the first set that are not in the second set.
 
+#### Example
+
+```ts
+const a = new Set([1, 2, 3]);
+const b = new Set([3, 4]);
+console.log(difference(a, b)); // Set(1, 2)
+```
+
 ***
 
 ### equals()
 
 > **equals**(`setA`, `setB`): `boolean`
 
+Tests if two sets are equal, meaning they contain exactly the same elements.
+
 #### Parameters
 
 • **setA**: `Set`\<`any`\>
@@ -50,12 +62,22 @@ The second set.
 
 Returns true if both sets are equal in size and content, otherwise false.
 
+#### Example
+
+```ts
+const a = new Set([1, 2, 3]);
+const b = new Set([1, 2, 3]);
+console.log(equals(a, b)); // true
+```
+
 ***
 
 ### intersection()
 
 > **intersection**(`setA`, `setB`): `Set`\<`any`\>
 
+Returns the intersection of two sets, containing only elements that are present in both sets.
+
 #### Parameters
 
 • **setA**: `Set`\<`any`\>
@@ -72,12 +94,22 @@ The second set.
 
 A new Set containing common elements from both input sets.
 
+#### Example
+
+```ts
+const a = new Set([1, 2, 3]);
+const b = new Set([2, 3, 4]);
+console.log(intersection(a, b)); // Set(2, 3)
+```
+
 ***
 
 ### isSuperset()
 
 > **isSuperset**(`set`, `subset`): `boolean`
 
+Checks if one set is a superset of another set, meaning all elements of the subset are contained within the set.
+
 #### Parameters
 
 • **set**: `Set`\<`any`\>
@@ -94,12 +126,22 @@ The candidate subset.
 
 Returns true if the set contains all elements of the subset, otherwise false.
 
+#### Example
+
+```ts
+const a = new Set([1, 2, 3]);
+const b = new Set([2, 3]);
+console.log(isSuperset(a, b)); // true
+```
+
 ***
 
 ### symmetricDifference()
 
 > **symmetricDifference**(`setA`, `setB`): `Set`\<`any`\>
 
+Returns the symmetric difference of two sets, containing elements present in only one of the sets.
+
 #### Parameters
 
 • **setA**: `Set`\<`any`\>
@@ -116,12 +158,22 @@ The second set.
 
 A new Set containing elements that are only in one of the input sets.
 
+#### Example
+
+```ts
+const a = new Set([1, 2, 3]);
+const b = new Set([3, 4, 5]);
+console.log(symmetricDifference(a, b)); // Set(1, 2, 4, 5)
+```
+
 ***
 
 ### union()
 
 > **union**(`setA`, `setB`): `Set`\<`any`\>
 
+Returns the union of two sets, containing all unique elements from both sets.
+
 #### Parameters
 
 • **setA**: `Set`\<`any`\>
@@ -137,3 +189,11 @@ The second set.
 `Set`\<`any`\>
 
 A new Set containing all elements from both input sets.
+
+#### Example
+
+```ts
+const a = new Set([1, 2, 3]);
+const b = new Set([3, 4, 5]);
+console.log(union(a, b)); // Set(1, 2, 3, 4, 5)
+```

package/docs/utils/transformWalk.md

@@ -12,6 +12,9 @@
 
 > **transformWalk**(`obj`, `transformFn`, `path`): `any`
 
+Recursively walks through an object's values and applies a transformation function to each value.
+The value recursed into is the transformed value, not the original value.
+
 #### Parameters
 
 • **obj**: `any`
@@ -31,3 +34,29 @@ The path to the current value.
 `any`
 
 The transformed object.
+
+#### Example
+
+```ts
+const obj = {
+  a: 1,
+  b: {
+    c: 2,
+    d: [3, 4, { e: 5 }]
+  }
+};
+
+const transformed = transformWalk(obj, (key, value, path) => {
+  if (key === "e") {
+    return value * 2;
+  }
+  return value;
+});
+// transformed = {
+//   a: 1,
+//   b: {
+//     c: 2,
+//     d: [3, 4, { e: 10 }]
+//   }
+// }
+```

package/index.js

@@ -19,6 +19,7 @@ export * from "./use/objectInstance.js";
 export * from "./use/objectRelated.js";
 export * from "./use/objectSubscription.js";
 export * from "./use/paginatedListInstance.js";
+export * from "./use/proxyLoadingError.js";
 export * from "./use/search.js";
 export * from "./use/watchesRunning.js";
 export * from "./utils/assignReactiveObject.js";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arrai-innovations/reactive-helpers",
-    "version": "13.0.4",
+    "version": "13.1.0",
     "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
     "main": "index.js",
     "type": "module",
@@ -30,31 +30,31 @@
     "homepage": "https://github.com/arrai-innovations/reactive-helpers#readme",
     "devDependencies": {
         "@arrai-innovations/commitlint-config": "^1.1.0",
-        "@commitlint/cli": "^19.3.0",
+        "@commitlint/cli": "^19.4.0",
         "@godaddy/dmd": "^1.0.4",
         "@trivago/prettier-plugin-sort-imports": "^4.3.0",
         "@types/browser-util-inspect": "^0.2.4",
         "@types/lodash-es": "^4.17.12",
-        "@typescript-eslint/eslint-plugin": "^7.14.1",
-        "@typescript-eslint/parser": "^7.14.1",
+        "@typescript-eslint/eslint-plugin": "^7.18.0",
+        "@typescript-eslint/parser": "^7.18.0",
         "@vitest/coverage-v8": "^1.6.0",
-        "@vue/compiler-sfc": "^3.3.4",
+        "@vue/compiler-sfc": "^3.4.37",
         "@vue/eslint-config-prettier": "^9.0.0",
         "@vue/test-utils": "^2.3.2",
         "doctoc": "^2.1.0",
         "eslint": "^8.56.0",
-        "eslint-plugin-jsdoc": "^48.5.0",
+        "eslint-plugin-jsdoc": "^48.11.0",
         "eslint-plugin-vitest": "~0.5.4",
         "eslint-plugin-vitest-globals": "^1.3.1",
-        "eslint-plugin-vue": "^9.26.0",
+        "eslint-plugin-vue": "^9.27.0",
         "flush-promises": "^1.0.2",
-        "globals": "^15.6.0",
-        "jsdom": "^24.1.0",
-        "lint-staged": "^15.2.7",
-        "prettier": "^3.3.2",
-        "typedoc": "^0.26.1",
-        "typedoc-plugin-markdown": "^4.1.0",
-        "typescript": "^5.5.2",
+        "globals": "^15.9.0",
+        "jsdom": "^24.1.1",
+        "lint-staged": "^15.2.8",
+        "prettier": "^3.3.3",
+        "typedoc": "^0.26.5",
+        "typedoc-plugin-markdown": "^4.2.3",
+        "typescript": "^5.5.4",
         "vitest": "^1.6.0"
     },
     "dependencies": {

package/tests/unit/use/loadingError.spec.js

@@ -0,0 +1,43 @@
+import { useLoadingError } from "../../../use/loadingError.js";
+import { ref } from "vue";
+import { describe, it, expect } from "vitest";
+
+describe("useLoadingError", () => {
+    let loadingError;
+
+    beforeEach(() => {
+        loadingError = useLoadingError();
+    });
+
+    it("should initialize with default states", () => {
+        expect(loadingError.loading.value).toBe(undefined);
+        expect(loadingError.error.value).toBe(null);
+        expect(loadingError.errored.value).toBe(false);
+    });
+
+    it("should set loading state", () => {
+        loadingError.setLoading();
+        expect(loadingError.loading.value).toBe(true);
+    });
+
+    it("should clear loading state", () => {
+        loadingError.setLoading();
+        loadingError.clearLoading();
+        expect(loadingError.loading.value).toBe(false);
+    });
+
+    it("should set error state and mark as errored", () => {
+        const error = new Error("Test Error");
+        loadingError.setError(error);
+        expect(loadingError.error.value).toBe(error);
+        expect(loadingError.errored.value).toBe(true);
+    });
+
+    it("should clear error state", () => {
+        const error = new Error("Test Error");
+        loadingError.setError(error);
+        loadingError.clearError();
+        expect(loadingError.error.value).toBe(null);
+        expect(loadingError.errored.value).toBe(false);
+    });
+});

package/tests/unit/use/proxyLoadingError.spec.js

@@ -0,0 +1,64 @@
+import { useProxyLoadingError } from "../../../use/proxyLoadingError.js";
+import { ref } from "vue";
+import { describe, it, expect } from "vitest";
+
+describe("useProxyLoadingError", () => {
+    let loadingError1, loadingError2;
+
+    beforeEach(() => {
+        loadingError1 = {
+            loading: ref(false),
+            error: ref(null),
+            errored: ref(false),
+            clearError: vi.fn(),
+        };
+        loadingError2 = {
+            loading: ref(false),
+            error: ref(null),
+            errored: ref(false),
+            clearError: vi.fn(),
+        };
+    });
+
+    it("should initialize with default states when no errors", () => {
+        const proxyLoadingError = useProxyLoadingError([loadingError1, loadingError2]);
+        expect(proxyLoadingError.loading.value).toBe(false);
+        expect(proxyLoadingError.error.value).toBe(null);
+        expect(proxyLoadingError.errored.value).toBe(false);
+    });
+
+    it("should reflect loading state when one source is loading", () => {
+        loadingError1.loading.value = true;
+        const proxyLoadingError = useProxyLoadingError([loadingError1, loadingError2]);
+        expect(proxyLoadingError.loading.value).toBe(true);
+    });
+
+    it("should reflect error state when one source has an error", () => {
+        const error = new Error("Test Error");
+        loadingError2.error.value = error;
+        loadingError2.errored.value = true;
+        const proxyLoadingError = useProxyLoadingError([loadingError1, loadingError2]);
+        expect(proxyLoadingError.error.value).toBe(error);
+        expect(proxyLoadingError.errored.value).toBe(true);
+    });
+
+    it("should clear all errors when clearError is called", () => {
+        const proxyLoadingError = useProxyLoadingError([loadingError1, loadingError2]);
+        proxyLoadingError.clearError();
+        expect(loadingError1.clearError).toHaveBeenCalled();
+        expect(loadingError2.clearError).toHaveBeenCalled();
+    });
+
+    it("should reflect correct aggregate state when combining multiple sources", () => {
+        loadingError1.loading.value = true;
+        loadingError2.errored.value = true;
+        const error = new Error("Another Error");
+        loadingError2.error.value = error;
+
+        const proxyLoadingError = useProxyLoadingError([loadingError1, loadingError2]);
+
+        expect(proxyLoadingError.loading.value).toBe(true); // One source is loading
+        expect(proxyLoadingError.errored.value).toBe(true); // One source has an error
+        expect(proxyLoadingError.error.value).toBe(error); // Error is aggregated
+    });
+});

package/use/listRelated.js

@@ -34,7 +34,7 @@ import { computed, effectScope, onScopeDispose, reactive, ref, toRef, unref, wat
  * @typedef {object} ListRelatedRule
  * @property {string} pkKey - Specifies the foreign key used to link objects across lists. Planned to be renamed to
  *  'fkKey' to better reflect its usage.
- * @property {string[]} order - Specifies the order in which related objects should be sorted, if applicable.
+ * @property {string[]} [order] - Specifies the order in which related objects should be sorted, if applicable.
  * @property {import('./listInstance.js').ObjectsById} objects - The objects that can be related based on the foreign key.
  */
 

package/use/loadingError.js

@@ -5,14 +5,28 @@ import { readonly, ref } from "vue";
  */
 
 /**
- * @typedef {object} LoadingError
+ * 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 {() => void} clearError - Clear the error state.
+ */
+
+/**
+ * The writable API for loading and error states.
+ *
+ * @typedef {object} LoadingErrorMutations
  * @property {() => void} setLoading - Set the loading state.
  * @property {() => void} clearLoading - Clear the loading state.
  * @property {(error) => void} setError - Set the error state.
- * @property {() => void} clearError - Clear the error state.
+ */
+
+/**
+ * The instance of useLoadingError.
+ *
+ * @typedef {LoadingErrorStatus & LoadingErrorMutations} LoadingError
  */
 
 /**

package/use/proxyLoadingError.js

@@ -0,0 +1,59 @@
+import { computed, readonly, unref } from "vue";
+import { loadingCombine } from "../utils/loadingCombine.js";
+
+/**
+ * @typedef {(
+ *     import('./loadingError.js').LoadingErrorStatus[]
+ * )} WatchableLoadingErrorsRaw
+ */
+
+/**
+ * A watchable collection of loading errors.
+ *
+ * @typedef {(
+ *     import('vue').UnwrapNestedRefs<WatchableLoadingErrorsRaw> |
+ *     import('vue').Ref<WatchableLoadingErrorsRaw> |
+ *     WatchableLoadingErrorsRaw
+ * )} WatchableLoadingErrors
+ */
+
+/**
+ * The instance of useProxyLoadingError.
+ *
+ * @typedef {import('./loadingError.js').LoadingErrorStatus} ProxyLoadingError
+ */
+
+/**
+ * A composable function for managing aggregated loading and error states across multiple sources.
+ *
+ * @param {WatchableLoadingErrors} loadingErrors - A collection of loading error statuses to monitor and aggregate.
+ * @returns {ProxyLoadingError} An object containing aggregated reactive fields and actions for loading and error states.
+ */
+export function useProxyLoadingError(loadingErrors) {
+    /** @type {import("vue").ComputedRef<boolean|undefined>} */
+    const loading = computed(() =>
+        loadingCombine(...unref(loadingErrors).map((loadingError) => unref(loadingError.loading)))
+    );
+    /** @type {import("vue").ComputedRef<Error|null>} */
+    const error = computed(
+        () =>
+            unref(loadingErrors)
+                .map((loadingError) => unref(loadingError.error))
+                .find((error) => error) || null
+    );
+    /** @type {import("vue").ComputedRef<boolean>} */
+    const errored = computed(() =>
+        unref(loadingErrors)
+            .map((loadingError) => unref(loadingError.errored))
+            .some((errored) => errored)
+    );
+
+    return {
+        loading: readonly(loading),
+        error: readonly(error),
+        errored: readonly(errored),
+        clearError: () => {
+            unref(loadingErrors).forEach((loadingError) => loadingError.clearError());
+        },
+    };
+}