Aurora is a powerful utility for enhancing HTTP requests in Vue 3 applications, providing an easy-to-use interface for making HTTP calls with advanced features like concurrency control, common headers, and reactive request handling.
- Hooks
- Automatic loading state management.
- Setting limits for unresolved ongoing calls.
- Request cancellation.
- Authentication support.
- Reactive calls.
- Call timeouts.
- Call intervals.
- Seamless integration with Axios, leveraging its powerful features.
- Use the package just by importing what you need.
- Automatic handling of loading indicators.
- Simplifies state management during data fetching.
- Introducing a "recall" feature allowing developers to re-trigger Axios calls and update computed data.
- Automatically trigger a call to update whenever there are changes or updates to the value of the endpoint, header, or parameter.
- Mechanism to cancel unresolved requests, specially useful in scenarios like navigating away from a component while a request is still pending.
- Utilizes the modern AbortController for request cancellation.
- Support for handling authentication tokens and headers.
- Easy configuration for adding authentication tokens to requests.
- Ability to add custom headers and query parameters to HTTP requests.
- Easy-to-use functions for adding and removing headers.
- Efficiently manage concurrent requests to avoid race conditions.
- Option to limit the number of simultaneous requests.
- Implement timeout options for requests to prevent long-running requests from impacting the user experience.
- Easily add and remove timeout configurations.
- Implement an interval to repeat the same call after a specified number of milliseconds.
- Utility function within the instance to clear the interval if necessary
- Improved error handling with customized error messages and formats for a better understanding and handling.
You can install Aurora Vue 3 using npm:
npm install aurora-vue3Or yarn:
yarn add aurora-vue3First, you need to import Aurora and the necessary hooks into your Vue components:
import Aurora, {
useCall,
useGet,
usePost,
usePut,
usePatch,
useDelete,
} from 'aurora-vue3';You can create an Aurora instance with the following options:
url: The base URL for all HTTP requests.maxConcurrentRequests: The maximum number of concurrent requests.abortController: An instance of AbortController for handling request cancellations.
const auroraInstance = new Aurora('https://api.example.com', 5, null);You can use the provided hooks to make HTTP requests. Each hook returns a Vue computed variable containing the loading state, response data, error information, and control methods.
const response = useGet('/endpoint', headers, params);
// or
const { isLoading, response, error, recall, stop } = useGet(
'/endpoint',
headers,
params
);const response = auroraInstance.get('/endpoint', headers, params);Aurora allows you to add common headers and parameters to be included in all requests:
auroraInstance.addHeaders({
Authorization: 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json',
'Custom-Header': 'CustomValue',
});
auroraInstance.addParams({ page: 1, limit: 10, lang 'en' });You can also remove specific headers or parameters by providing an array with the keys you want to remove:
auroraInstance.removeHeaders(['Authorization']);
auroraInstance.removeParams(['lang']);
// removing all headers or params
auroraInsance.removeHeaders();
auroraInstance.removeParams();Aurora allows you to set a timeout for all requests. Requests will expire if it are not resolved after the specified timeout:
auroraInstance.addTimeout(5000); // timeout in milliseconds
auroraInstance.removeTimeout(); // remove itTo add a default URL, use the Aurora constructor. This URL will be used when making a request using this instance.
const auroraInstance = new Aurora('https://api.example.com');Use the following functions t add default headers and params to the Aurora Instnance.
auroraInstance.addHeaders({ 'Custom-Header': 'CustomValue' });
auroraInstance.removeHeaders(['Custom-Header']);
auroraInstance.addParams({ page: 1, limit: 10 });
auroraInstance.removeParams(['page']);To set a max concurrent number of unresolved request, use the Aurora constructor or the following function. If the Aurora instance exceeds the limit of unresolved requests, every further request will fail.
const auroraInstance = new Aurora(null, 5);
// or
auroraInstance.setMaxConcurrentRequestsLimit(5);
// pass no params to reset the max limit to Infinite
auroraInstance.setMaxConcurrentRequestsLimit();To use a custom AbortController, address it to the Aurora constructor.
customAbortController = new AbortController();
const auroraInstance = new Aurora(null, null, customAbortController);The existing functions get( ), post( ), put( ), patch( ) and delete( ) are alias of the main function call( ).
A get( ) function simply uses the method call( ) passing "get" as a param.
Use the recall( ) function to trigger the Axios request again and update the computed properties.
This is useful to make the same call once again without creating a new Aurora instance or a new computed variable.
const initialRequest = auroraInstance.get('/api/data');
// Recall the request after 10 seconds
setTimeout(() => initialRequest.recall(), 10000);auroraInstance.get('/endpoint');
auroraInstance.call('get', '/endpoint');An Aurora instance call can receive a config object that indicates the behavior of the call.
In the current version of the package, the available options for the config object are interval, timeout and reactive.
Make repeated requests at a specified interval. Useful for real-time data updates.
// Make repeated requests every 10 seconds
const config = { interval: 10000 };
const response = auroraInstance.get('/api/data', null, null, config);
// Stop the interval-based requests after 30 seconds
setTimeout(() => response.stop(), 30000);Set a custom timeout for the request to ensure it doesn't run indefinitely, even if it does not receive a response.
// Make a request that will expire after 5 seconds
const config = { timeout: 5000 };
const timeoutResponse = auroraInstance.get('/api/data', null, null, config);In Aurora, you can make a call reactive, allowing it to automatically recall itself whenever there is a change in any value of the endpoint, headers, or parameters. For example, if a parameter initially has a value of page: 10, but later updates to page: 11, a reactive call will automatically repeat the API call using the updated parameter value.
This reactivity also applies to changes in endpoints and headers, as mentioned earlier.
To enable this feature, simply set the option reactive: true in the configuration parameter.
const config = { reactive: true };Ensure the usage of reactive objects in the call metod parameters.
Use ref/computed for a reactive endpoint and the reactive Vue object for the headers and params.
// Define reactive variables
const selectedLimit = ref(10);
const selectedPokemon = ref('ditto');
const baseURL = 'https://pokeapi.co/api/v2/pokemon/';
// Create a reactive reference to the base URL
const refURL = ref(baseURL);
// Compute the URL dynamically based on selectedPokemon value
const computedURL = computed(() => {
return baseURL + selectedPokemon.value;
});
// Define reactive parameters using Vue's reactive function
const reactiveParams = reactive({ limit: selectedLimit });
// Invoke the Aurora instance's get method
auroraInstance.get(computedURL, null, reactiveParams, config);To clarify, in the provided code snippet, any changes or updates to the values of
reactiveParamsorcomputedURLwill dynamically reflect in the computed response of the get( ) method. This is facilitated by setting the config option toreactive: trueand utilizing reactive Vue objects for both endpoint and parameters.
You can mix all the configurations in a single object.
const config = {
timeout: 10000,
interval: 100,
reactive: true,
};
const response = auroraInstance.get('/endpoint', null, null, config);Here is a full example of using Aurora in a Vue 3 component:
<template>
<div>
<div v-if="isLoading">Loading...</div>
<div v-else-if="error">{{ error.msg }}</div>
<div v-if="response">{{ response.data }}</div>
<button @click="recall">Retry</button>
</div>
</template>
<script>
import { ref } from 'vue';
import { useGet } from 'aurora-vue3';
export default {
setup() {
const { isLoading, response, error, recall } = useGet('/endpoint');
return { isLoading, response, error, recall };
}
}
</script>| Param | Type | Nullable | Desc |
|---|---|---|---|
| url | String | ✓ | Base URL |
| maxConcurrentRequests | Number | ✓ | Maximum number of ongoing unresolved requests |
| abortController | AbortController | ✓ | Linked AbortController |
Sets the maximum concurrent requests limit for the Aurora instance.
Throws an AuroraClassError if the parameter is not a number or is an infinite number.
| Param | Type | Nullable | Desc |
|---|---|---|---|
| limit | Number | ✓ | The maximum concurrent requests limit. If null or undefined (left empty), or if 0, concurrency control is effectively disabled. If a positive number, sets the maximum concurrent requests to that value. |
Adds common headers to the Aurora instance.
Throws an AuroraClassError if the parameter is not of type 'object' or is null.
| Param | Type | Nullable | Desc |
|---|---|---|---|
| headers | Object | ✗ | An object containin key-paired values representing headers to be added |
Removes specified headers from the common headers Aurora instance. If no parameters are provided, removes all headers. Throws an AuroraClassError if the parameter is not an array when provided.
| Param | Type | Nullable | Desc |
|---|---|---|---|
| headerNames | Array | ✓ | An optional array containing the header names to be removed. If not provided, remove all headers |
Adds common query parameters to the Aurora instance.
Throws an AuroraClassError if the parameter is not of type 'object' or is null.
| Param | Type | Nullable | Desc |
|---|---|---|---|
| params | Object | ✗ | An object containin key-paired values representing query params to be added |
Removes specified query params from the common parameters Aurora instance. If no parameters are provided, removes all headers.
Throws an AuroraClassError if the parameter is not an array when provided.
| Param | Type | Nullable | Desc |
|---|---|---|---|
| paramNames | Array | ✓ | An optional array containing the param names to be removed. If not provided, remove all parameters |
Adds a timeout configuration to the Aurora instance defaults.
Throws an AuroraClassError if the parameter is not a Number.
| Param | Type | Nullable | Desc |
|---|---|---|---|
| timeout | Number | ✓ | Timeout value in ms |
Removes the timeout configuration from the Aurora instance defaults.
Simply cancells all ongonig requests that are using the instance AbortController's signal.
Makes an HTTP request.
Returns a Vue computed variable which contains a loading indicator, the endpoint response if exists or has been successfully called and and the linked AbortController.
Throws an AuroraInstanceError if the endpoint is either empty or null.
Throws an AuroraInstanceError if the method is not of type String.
Throws an AuroraInstanceError if the params parameter is not of type object (if given).
Throws an AuroraInstanceError if the config parameter is not of type object (if given).
Throws an AuroraInstanceError if the abortController parameter is not of type AbortController (if given).
| Param | Type | Nullable | Desc |
|---|---|---|---|
| method | String | ✗ | The HTTP method. (get/post/put/patch/delete) |
| endpoint | String | ✗ | The endpoint url. |
| headers | Object | ✓ | Additional headers to include in the request. |
| params | Object | ✓ | Additional query params to include in the request. |
| config | Object | ✓ | The configuration variable to define the call behavior. It can contain timeout (number in ms), interval (number in ms) and reactive (boolean) |
| timeout | Number | ✓ | The call will expire after a certain timeout if is not resolved. Pass 0 or leave empty this param for no timeout. (Expressed in ms) |
| AbortController | AbortController | ✓ | The call with be linked to an AbortController signal. If this param is left empty, it will use the object AbortController, which is the default controller for all request. |
Alias for the call( ) function that replace the method param for the function name.
auroraInstance.call('get', '/api/data');
auroraInstance.get('/api/data');
useCall('get', '/api/data');
useGet('/api/data');