Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/udivankin/pico-ajax
Very tiny (~ 1kb uncompressed) yet fully functional AJAX library with zero dependencies
https://github.com/udivankin/pico-ajax
ajax axios fetch superagent xmlhttprequest
Last synced: about 2 months ago
JSON representation
Very tiny (~ 1kb uncompressed) yet fully functional AJAX library with zero dependencies
- Host: GitHub
- URL: https://github.com/udivankin/pico-ajax
- Owner: udivankin
- License: mit
- Created: 2017-05-10T07:54:21.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T16:20:52.000Z (almost 2 years ago)
- Last Synced: 2024-10-06T06:53:36.322Z (3 months ago)
- Topics: ajax, axios, fetch, superagent, xmlhttprequest
- Language: TypeScript
- Homepage:
- Size: 371 KB
- Stars: 5
- Watchers: 4
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PicoAjax
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.
## Motivation
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.
## Limitations
Since server implementation is mostly synchronous it's not recommended to use PicoAjax in loaded projects.
## Install
Via npm:
```
npm install --save pico-ajax
```
then import pico-ajax module
```javascript
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):
```html
```
## API
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:
```javascript
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:
```javascript
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:
```javascript
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:
```javascript
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
}
```
## Usage
You may start right now with a simple GET request:
```javascript
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**
```javascript
// 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**
```javascript
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**
```javascript
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);
});
```
## Advanced use
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.
## License
MIT found in `LICENSE` file.