Yea... an immutable-style AJAX library for the browser.
Requests are configured via method calls and each method always returns a fresh request instance, with no references to past instances.
- Immutable API, Promise-based, throws meaningful errors
- No external dependencies, quite small (<2.4KB minified and gzipped)
- Understands Content-Type (decodes JSON responses by default)
- TypeScript support
- Bring your own Promise-implementation
- Works on modern browsers and some older ones
- Fully tested (see e.g. requests.spec.js) in real browsers, thanks to Sauce Labs
Why not use fetch, axios, jQuery, etc..? See COMPARISON.md.
<script src="https://cdn.jsdelivr.net/npm/es6-promise@4/dist/es6-promise.auto.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/yea@1.5.0/build/yea.min.js"></script>
<script>
yea.get('https://reqres.in/api/users').then(response => {
console.log(response.status);
console.log(response.body); // string (original JSON)
console.log(response.data); // object
});
</script>Install via npm or yarn:
npm install yea
# or
yarn add yeaImport in a project:
import request from 'yea';
// or
const request = require('yea');See these basic examples or the full API below.
// Make a GET request
request
.baseUrl('https://example.com/api')
.headers({
'X-API-KEY': 'secret123'
})
.get('/accounts/:accountId/info')
.urlParams({ accountId: 123 })
.query({ foo: 'bar' })
.timeout(2000)
.then(response => {
console.log(response.status);
console.log(response.body);
})
.catch(error => {
if (error.response) {
console.error(error.response.status);
} else {
// ...
}
})
// POST requests
request.post('https://example.com/accounts').body('raw data')
request.post('https://example.com/accounts').json({ foo: 'bar' })
request.post('https://example.com/accounts').urlencoded({ foo: 'bar' })
// Helper method to return a nested value from the request
// JSON response is decoded automatically based on Content-Type (configurable)
const account = await request.get('/accounts.json').prop('data.accounts[0]')Yea comes with built-in type declarations. See index.d.ts.
Each method of YeaAjaxRequest returns a new instance of YeaAjaxRequest. This is demonstrated in the example below.
The example uses toObject which returns a copy of all configuration of that specific instance at that moment in time.
const req1 = request
.get('https://example.com')
.query({ foo: 'bar' });
// Extend from previous request
const req2 = req1.query({ something: 'different' });
console.log(req2 === req1); // => false
console.log(req1.toObject().query); // => 'foo=bar'
console.log(req2.toObject().query); // => 'something=different'Practical example of how to create a base request with some defaults and later utilize it for requests:
// API-specific defaults for all requests
const api = request
.baseUrl('https://example.com/api/v1')
.headers({
'X-API-KEY': 'secret123'
});
// Extend to endpoints
const accountEndpoint = api.url('/accounts/:accountId');
const invoiceEndpoint = api.url('/invoices/:invoiceId');
// Usage
const { data } = await accountEndpoint.urlParams({ accountId: 123 });
await invoiceEndpoint.method('post').urlParams({ invoiceId: 9000 }).sendJson({ ... });The following methods are available.
.get(url).post(url).put(url).delete(url).method(method).url(url).urlParams(object).baseUrl(url).query(object | string).headers(object).amendHeaders(object).header(key, value).unsetHeader(name).body(data).json(value).urlencoded(value).timeout(milliseconds).unsetTimeout().prop(path).send([body]).sendUrlencoded(data).sendJson(data).then().setResponseTransformers([]).setAllowedStatusCode(allowed).polyfills(polyfills).toObject()/.config()/.debug()
See API.md.
For local development, run yarn dev. It starts a web server with a Mocha UI and watches for changes. You can view the UI in the browser at http://localhost:9876.
$ yarn dev
Test server is running!
Open http://localhost:9876/ in your browserFor a one-time full test suite execution, run yarn test. It runs all tests in a suite of browsers (powered by Karma).
yarn testSee CONTRIBUTING.md.
Chrome, Firefox, IE 10+, Edge, Safari 11+
Cross-browser Testing Platform Provided by Sauce Labs.
See CHANGELOG.md.
MIT