Universal, very tiny (browser version is ~1kb uncompressed) yet fully functional AJAX library with zero dependencies. It implements browser XMLHttpRequest and Node.js http/https module returning Promise.
What makes Pico-Ajax different is that it's unaware on how data is passed. That requires a few more bytes of code to make a request, but gives much more control and (more important) better understanding of HTTP requests in exchange. This also makes it perfect for building your own DIY API module.
Since server implementation is mostly synchronous it's not recommended to use PicoAjax in loaded projects.
Via npm:
npm install --save pico-ajax
then import pico-ajax module
import PicoAjax from 'pico-ajax';
// or if you use CommonJS imports:
const PicoAjax = require('pico-ajax');
Or use as a legacy module (will be available as PicoAjax in a global scope):
<script src="/scripts/picoajax.min.js"></script>
PicoAjax exposes all known http methods (connect, delete, get, head, options, patch, post and put) with two arguments: 'url' and 'options'.
First argument is url of type string. Note that you should compose GET parameters by yourself:
const params = new URLSearchParams({ foo: "bar", page: 2 }).toString();
const url = `https://example.com?${params}`;
PicoAjax
.get(url)
.then(response => console.log('response received'));
Second argument (options) is a plain object, whose keys override defaults below:
options: {
body: undefined, // Request body, see details below
headers: {}, // Request headers, see details below
password: undefined, // HTTP auth password
user: undefined, // HTTP auth user
timeout: undefined, // Request timeout
responseType: '', // [Browser-only] Could be 'json|arraybuffer|blob|document|text',
async: true, // [Browser-only] Could be helpful since e.g. workers lack async support
onProgress: undefined, // [Browser-only] XMLHttpRequest onprogress callback
withCredentials: false, // [Browser-only] Whether should send cookies with cross-origin requests
}
PicoAjax http methods return Promises which are resolved with Response object:
response: {
body: any, // Response body, PicoAjax always tries to JSON.parse response body
headers: Object, // Response headers
statusCode: number, // Response status code, e.g. 200
statusMessage: string, // Response status message, e.g. OK
}
In case http didn't succeed (response code other than 2xx, or another error), Promise is rejected with an Error instance with reponse fields added:
error: {
name: string, // Error name, e.g. NetworkError
message: string, // Error message, e.g. 500 Server Error
body: any, // Response body, PicoAjax always tries to JSON.parse response body
headers: Object, // Response headers
statusCode: number, // Response status code, e.g. 200
statusMessage: string, // Response status message, e.g. OK
}
You may start right now with a simple GET request:
PicoAjax
.get('/some/api/?foo=bar&baz=qux')
.then(({ headers, body }) => {
console.log(headers, body);
})
.catch((error) => {
console.error(error.message, error.statusCode);
});
// or if you prefer async/await
try {
const { headers, body } = await PicoAjax.get('/some/api/?foo=bar&baz=qux');
console.log(headers, body);
} catch (e) {
console.error(e.message, e.statusCode);
}
Multipart/form-data
// Prepare form data using DOM form (Browser only)
const formData = new FormData(document.querySelector('form'));
// Or with a plain object
const foo = { bar: 'baz' };
const formData = new FormData();
Object.keys(foo).forEach(key => {
formData.append(key, foo[key]);
});
// Perform POST request
PicoAjax
.post('/some/api/', { body: formData })
.then(({ headers, body, statusCode }) => {
console.log(statusCode, headers, body);
})
.catch((error) => {
console.error(error.message, error.statusCode);
});
JSON
const body = JSON.stringify({ foo: 'bar', baz: 'qux' });
const headers = { 'Content-Type': 'application/json' };
PicoAjax
.post('/some/api/', { body, headers })
.then(({ headers, body, statusCode }) => {
console.log(statusCode, headers, body);
})
.catch((error) => {
console.error(error.message, error.statusCode);
});
File upload
const formData = new FormData();
formData.append('userfile', fileInputElement.files[0]);
PicoAjax
.post('/some/api/', { body: formData })
.then(({ headers, body, statusCode }) => {
console.log(statusCode, headers, body);
})
.catch((error) => {
console.error(error.message, error.statusCode);
});
If you are going to make quite a few similar requests in your project, you probably may want to make one more layer of abstraction over Pico-Ajax. Please refer to api-example.js module in examples directory.
MIT found in LICENSE
file.