8000 chore(Root): Alpha release · svnrnns/aurora-vue3@6fb85d9 · GitHub
[go: up one dir, main page]
Skip to content
8000

Commit 6fb85d9

Browse files
svnrnnssvnrnns
committed
chore(Root): Alpha release
0 parents  commit 6fb85d9

File tree

7 files changed

+3845
-0
lines changed

7 files changed

+3845
-0
lines changed

‎.gitignore

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
pnpm-debug.log*
8+
lerna-debug.log*
9+
10+
# Dependency directories
11+
node_modules
12+
13+
# Generated output
14+
dist
15+
dist-ssr
16+
17+
# Local files
18+
*.local
19+
20+
# Editor directories and files
21+
.vscode/*
22+
!.vscode/extensions.json
23+
.idea
24+
.DS_Store
25+
*.suo
26+
*.ntvs*
27+
*.njsproj
28+
*.sln
29+
*.sw?

‎.vscode/extensions.json

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"recommendations": ["Vue.volar", "Vue.vscode-typescript-vue-plugin"]
3+
}

‎README.md

+350
Original file line numberDiff line numberDiff line change
< 6D40 code class="diff-text-cell hunk">
@@ -0,0 +1,350 @@
1+
# Aurora
2+
3+
Aurora is a package that enhances the Axios experience in **Vue 3**, offering advanced features like automatic loading state management, limit max ongoing calls, request cancellation, authentication support, call timeouts, call intervals, and more.
4+
5+
## Table of Contents
6+
7+
- [Features](#features)
8+
- [Installation](#installation)
9+
- [Usage](#usage)
10+
- [Making a simple request](#make-a-request)
11+
- [Instance configuration](#instance-configuration)
12+
- [Advanced Usage](#advanced-usage)
13+
- [API](#api)
14+
15+
## Features
16+
17+
### Enhanced Axios Integration
18+
19+
- Seamless integration with Axios, leveraging its powerful features.
20+
21+
### Loading State
22+
23+
- Automatic handling of loading indicators for asynchronous requests.
24+
- Simplifies state management during data fetching.
25+
26+
### Error Handling:
27+
28+
- Improved error handling with customizable error messages and formats.
29+
- Support for handling specific HTTP error codes. (not yet implemented)
30+
31+
### Request Cancellation:
32+
33+
- Mechanism to cancel requests, especially useful in scenarios like navigating away from a component while a request is still pending.
34+
- Utilizes the modern AbortController for request cancellation.
35+
36+
### Authentication Support:
37+
38+
- Support for handling authentication tokens and headers.
39+
- Easy configuration for adding authentication tokens to requests.
40+
41+
### Custom Headers and Params:
42+
43+
- Ability to add custom headers and query parameters to HTTP requests.
44+
- Easy-to-use functions for adding and removing headers.
45+
46+
### Timeouts:
47+
48+
- Implement timeout options for requests to prevent long-running requests from impacting the user experience.
49+
- Easily add and remove timeout configurations.
50+
51+
### Concurrency Control:
52+
53+
- Efficiently manage concurrent requests to avoid race conditions.
54+
- Option to limit the number of simultaneous requests.
55+
56+
### Recall Functionality:
57+
58+
- Introduces a "recall" feature allowing users to re-trigger Axios calls and update computed data.
59+
60+
## Installation
61+
62+
```bash
63+
$ npm install @svnrnns/aurora --save-dev
64+
```
65+
66+
## Usage
67+
68+
[Install](#Installation) the Aurora package. <br>
69+
70+
Create an instance of Aurora with an optional URL. This instance is bounded by default to an AbortController and set to a maximum number of concurrent requests of Infinite.
71+
72+
```js
73+
import Aurora from "@svnrnns/aurora";
74+
75+
const auroraInstance = new Aurora();
76+
const auroraInstance = new Aurora("https://api.example.com"); // Link a default url to the instance
77+
const auroraInstance = new Aurora("https://api.example.com", 5); // Set the max concurrent requests to 5
78+
const auroraInstance = new Aurora(
79+
"https://api.example.com",
80+
5,
81+
abortController
82+
); // Use a custom AbortController
83+
```
84+
85+
### Make a Request
86+
87+
Any Aurora request returns a computed variable with the following properties:
88+
89+
- **isLoading**: Indicates whether or not the request has received a response.
90+
- **response**: The request response.
91+
- **abortController**: The linked AbortController of this call. Aurora uses the instance AbortController by default in every request.
92+
- **recall( )**: A callable function that repeats the same request.
93+
- **stop( )**: If the request is under an interval, use this function to clear it.
94+
95+
```js
96+
// Make a simple GET request
97+
const computedResponse = auroraInstance.get("/api/data");
98+
99+
// Access the computed properties
100+
console.log(computedResponse.value.isLoading);
101+
console.log(computedResponse.value.response);
102+
```
103+
104+
There are 5 available methods to make a call, being **GET, POST, PUT, PATCH and DELETE**. <br>
105+
106+
> See futher information in [API](#api)
107+
108+
### Instance Configuration
109+
110+
Aurora offers several tools to customize the instance, such as default url, headers, params, custom AbortController for handling request cancellation, and setting a maximum of ongoing requests.
111+
112+
- To add a **default url**, use the Aurora constructor. This url will be used by default when making a request using this instance.
113+
114+
```js
115+
new Aurora("https://api.example.com");
116+
```
117+
118+
- To set a max concurrent request limit, use the Aurora constructor or the following function. If the Aurora instance exceeds the limit of unresolved requests, every further request will fail.
119+
120+
```js
121+
new Aurora(null, 5);
122+
// or
123+
auroraInstance.setMaxConcurrentRequestsLimit(5); // Pass no params to reset the max limit to Infinite
124+
```
125+
126+
- To use a custom **AbortController**, address it to the Aurora constructor.
127+
128+
```js
129+
customAbortController = new AbortController();
130+
new Aurora(null, null, customAbortController);
131+
```
132+
133+
- To add **default headers** to the Aurora instance, use the following functions.
134+
135+
```js
136+
// Adding default headers
137+
auroraInstance.addHeaders({
138+
Authorization: "Bearer YOUR_ACCESS_TOKEN",
139+
"Content-Type": "application/json",
140+
"Custom-Header": "CustomValue",
141+
});
142+
143+
// Removing specific headers
144+
auroraInstance.removeHeaders(["Authorization", "Custom-Header"]);
145+
146+
// Removing all headers
147+
auroraInstance.removeHeaders();
148+
```
149+
150+
- Follow the same structure above to add **default query params**.
151+
152+
```js
153+
// Add default query parameters
154+
auroraInstance.addParams({ page: 1, limit: 10 });
155+
156+
// Remove specific query parameters
157+
auroraInstance.removeParams(["page"]);
158+
159+
// Remove all query parameters
160+
auroraInstance.removeParams();
161+
```
162+
163+
- Finally, it is possible to add a **default timeout** for all the requests of an Aurora instance.
164+
165+
```js
166+
// Add a default timeout of 1s
167+
auroraInstance.addTimeout(1000);
168+
169+
// Remove it
170+
auroraInstance.removeTimeout();
171+
```
172+
173+
## Advanced Usage
174+
175+
The existing functions **get( )**, **post( )**, **put( )**, **patch( )** and **delete( )** are alias of the main function **call( )**. <br>
176+
A get( ) function simply uses the method call( ) passing "get" as a param.
177+
178+
```js
179+
auroraInstance.get("https://api.example.com");
180+
auroraInstance.call("get", "https://api.example.com");
181+
```
182+
183+
This is the main method of Aurora and has a lot of configuration and features.
184+
185+
### Additional headers & params
186+
187+
Headers and params can be added to the Aurora instance as we saw in [configuration](#instance-configuration), but can also be added to a specific call.
188+
189+
```js
190+
// Make a GET request with custom headers
191+
const customHeadersRequest = auroraInstance.get("/api/data", {
192+
Authorization: "Bearer YOUR_ACCESS_TOKEN",
193+
"Custom-Header": "CustomValue",
194+
});
195+
196+
// Make a GET request with query parameters
197+
const queryParamsRequest = auroraInstance.get(
198+
"/api/data",
199+
{},
200+
{
201+
page: 1,
202+
pageSize: 10,
203+
sortBy: "date",
204+
}
205+
);
206+
207+
// Make a POST request with custom headers and data
208+
const customHeadersAndParamsRequest = auroraInstance.post(
209+
"/api/create",
210+
{
211+
Authorization: "Bearer YOUR_ACCESS_TOKEN",
212+
"Content-Type": "application/json",
213+
},
214+
{
215+
name: "John Doe",
216+
email: "john@example.com",
217+
age: 30,
218+
}
219+
);
220+
```
221+
222+
### Intervals
223+
224+
Make repeated requests at a specified interval. Useful for real-time data updates.
225+
226+
```js
227+
// Make repeated requests every 10 seconds
228+
const intervalResponse = auroraInstance.get("/api/data", { interval: 10000 });
229+
230+
// Stop the interval-based requests after 30 seconds
231+
setTimeout(() => {
232+
intervalResponse.stop();
233+
}, 30000);
234+
```
235+
236+
### Timeouts
237+
238+
Set a custom timeout for the request to ensure it doesn't run indefinitely, even if it does not receive a response.
239+
240+
```js
241+
// Make a request that will expire after 5 seconds
242+
const timeoutResponse = auroraInstance.get("/api/data", { timeout: 5000 });
243+
```
244+
245+
### The Recall function
246+
247+
Use the recall function to trigger the Axios request again and update the computed properties. <br>
248+
This is useful to make the same call once again without creating a new Aurora instance or a new computed variable.
249+
250+
```js
251+
// Make a request
252+
const initialRequest = auroraInstance.get("/api/data");
253+
254+
// Recall the request after 10 seconds
255+
setTimeout(() => {
256+
initialRequest.recall();
257+
}, 10000);
258+
```
259+
260+
## API
261+
262+
### Constructor
263+
264+
| Param | Type | Nullable | Desc |
265+
| --------------------- | --------------- | -------- | --------------------------------------------- |
266+
| url | String | &check; | Base URL |
267+
| maxConcurrentRequests | Number | &check; | Maximum number of ongoing unresolved requests |
268+
| abortController | AbortController | &check; | Linked AbortController |
269+
270+
### setMaxConcurrentRequestsLimit
271+
272+
Sets the maximum concurrent requests limit for the Aurora instance. <br>
273+
Throws an **Error** if the parameter is not a number or is an infinite number.
274+
| Param | Type | Nullable | Desc |
275+
|-----------------------|-----------------|----------|--------------------------------------------------------------------------------------------------------------------------------------|
276+
| limit | Number | &check; | 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. |
277+
278+
### addHeaders
279+
280+
Adds common headers to the Aurora instance.<br>
281+
Throws an **Error** if the parameter is not of type 'object' or is null.
282+
| Param | Type | Nullable | Desc |
283+
|-----------------------|-----------------|----------|------------------------------------------------------------------------|
284+
| headers | Object | &cross; | An object containin key-paired values representing headers to be added |
285+
286+
### removeHeaders
287+
288+
Removes specified headers from the common headers Aurora instance. If no parameters are provided, removes all headers.
289+
Throws an **Error** if the parameter is not an array when provided.
290+
| Param | Type | Nullable | Desc |
291+
|-----------------------|-----------------|----------|--------------------------------------------------------------------------------------------------|
292+
| headerNames | Array<String> | &check; | An optional array containing the header names to be removed. If not provided, remove all headers |
293+
294+
### addParams
295+
296+
Adds common query parameters to the Aurora instance. <br>
297+
Throws an **Error** if the parameter is not of type 'object' or is null.
298+
| Param | Type | Nullable | Desc |
299+
|-----------------------|-----------------|----------|------------------------------------------------------------------------|
300+
| params | Object | &cross; | An object containin key-paired values representing query params to be added |
301+
302+
### removeParams
303+
304+
Removes specified query params from the common parameters Aurora instance. If no parameters are provided, removes all headers.<br>
305+
Throws an **Error** if the parameter is not an array when provided.
306+
| Param | Type | Nullable | Desc |
307+
|-----------------------|-----------------|----------|--------------------------------------------------------------------------------------------------|
308+
| paramNames | Array<String> | &check; | An optional array containing the param names to be removed. If not provided, remove all parameters |
309+
310+
### addTimeout
311+
312+
Adds a timeout configuration to the Aurora instance defaults.<br>
313+
Throws an **Error** if the parameter is not a Number.
314+
| Param | Type | Nullable | Desc |
315+
|---------|--------|----------|---------------------|
316+
| timeout | Number | &check; | Timeout value in ms |
317+
318+
### removeTimeout
319+
320+
Removes the timeout configuration from the Aurora instance defaults.
321+
322+
### abortAll
323+
324+
Simply cancells all ongonig requests that are using the instance AbortController's signal.
325+
326+
### call
327+
328+
Makes an HTTP request.<br>
329+
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.<br>
330+
Throws an **Error** if the URL is either empty or null.<br>
331+
Throws an **Error** if the method is not of type String.
332+
333+
| Param | Type | Nullable | Desc |
334+
| --------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
335+
| method | String | &cross; | The HTTP method. (get/post/put/patch/delete) |
336+
| url | String | &cross; | The endpoint.url |
337+
| headers | Object | &check; | Additional headers to include in the request. |
338+
| params | Object | &check; | Additional query params to include in the request. |
339+
| interval | Number | &check; | The endpoint will be called repeatedly if this number is greater than 0. (Expressed in ms) |
340+
| timeout | Number | &check; | 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) |
341+
| AbortController | AbortController | &check; | 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. |
342+
343+
### get post put patch delete
344+
345+
Alias for the **call( )** function that replace the **method** param for the function name.
346+
347+
```js
348+
auroraInstance.call("get", "/api/data");
349+
auroraInstance.get("/api/data");
350+
```

0 commit comments

Comments
 (0)
0