JavaScript AJAX request helper.
You can install the package via npm:
npm install @bjnstnkvc/ajax
You can install the package via jsDelivr CDN:
<script src="https://cdn.jsdelivr.net/npm/@bjnstnkvc/ajax/lib/AJAX.min.js"></script>
Once imported, you can make an AJAX request using the following methods:
Load data from the server using an HTTP GET request:
AJAX.get({ config })
Send data to the server using an HTTP POST request:
AJAX.post({ config })
Send data to the server using an HTTP PATCH request:
AJAX.patch({ config })
Send data to the server using an HTTP PUT request:
AJAX.put({ config })
Delete a resource from the server using an HTTP DELETE request:
AJAX.delete({ config })
In order to send an AJAX request using the methods listed above, you need to pass config
object. The Config object consists of the following properties:
A string representing the URL to send the request to:
AJAX.get({
url: 'posts',
})
An object used to parse and stringify URL parameters:
AJAX.get({
url: 'https://www.example.com/authors/{author}/posts/{post}',
params: {
author: 'bjnstnkvc',
post: 2
}
})
Example above would generate the following URL:
https://www.example.com/authors/bjnstnkvc/posts/2
An object used to parse and stringify URL query strings:
AJAX.get({
url: 'https://www.example.com/posts',
query: {
page: 2
}
})
Example above would generate the following URL:
https://www.example.com/posts?page=2
Sometimes you need to pass a query string as an array, in order to do so, use the following syntax:
AJAX.get({
url: 'https://www.example.com/posts',
query: {
tag: ['html', 'css'],
page: 2,
},
})
Example above would generate the following URL:
https://www.example.com/posts?tag[]=html&tag[]=css&page=2
A boolean value that indicates whether cross-site Access-Control requests should be made using credentials.
AJAX.get({
url: 'https://www.example.com/posts',
withCredentials: true,
})
In case you would like to add headers to AJAX request, you can pass them via headers
property:
AJAX.get({
url: 'https://www.example.com/posts',
headers: {
'Accept': 'application/json',
}
})
An object containing body of data to be sent in the XHR request.
AJAX.post({
url: 'https://www.example.com/posts',
data: {
title: 'A Post title',
description: 'A Post description',
}
})
Each AJAX request goes through 5 different states:
Value | State | Description |
---|---|---|
0 | UNSENT | Client has been created. open() not called yet. |
1 | OPENED | open() has been called. |
2 | HEADERS_RECEIVED | send() has been called, and headers and status are available. |
3 | LOADING | Downloading; responseText holds partial data. |
4 | DONE | The operation is complete. |
Additionally, 3 custom states have been added for more convenience when making AJAX requests:
State | Description |
---|---|
BEFORE | A state prior to request being sent. |
AFTER | A state after the response has been sent from the server. |
ERROR | A state when the request fails. |
In order to access each state, you can add states
property to AJAX config via following syntax:
AJAX.get({
url : 'https://www.example.com/posts',
states: {
before() {
//
},
unsent(xhr) {
//
},
opened(xhr) {
//
},
received(xhr) {
//
},
loading(xhr, response) {
//
},
done(xhr, response) {
//
},
error(xhr, response) {
//
},
after() {
//
}
}
})
Note:
loading
,done
anderror
states return xhr object as well as already parsed xhr response to JSON.
AJAX helper gives you an option to set config defaults using the following syntax:
AJAX.defaults({
url: 'https://www.example.com/posts',
withCredentials: true,
headers: {
'X-Requested-With': 'XMLHttpRequest',
'Accept' : 'application/json',
}
});
AJAX.post({
...
})
By doing so, every subsequent AJAX instance would use the config set above.
In case you need to overwrite previously set default config value, you simply need to set them :
AJAX.patch({
url: 'https://www.example.com/posts/2',
withCredentials: false,
...
});