yea
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.
Principles
- 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
- 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.
Contents
- Installation
- Usage
- Usage with TypeScript
- API
- Inspect request config
- Extending (instances)
- Development
- Browser support
- Changelog
- License
Installation
Via CDN
Via npm
Install via npm or yarn:
npm install yea# or yarn add yea
Import in a project:
;// orconst request = ;
Usage
See these basic examples or the full API below.
// Make a GET requestrequest // ... with URL parametersrequest // Make a POST requestrequest body'raw data' // Make a POST request (json)request // Make a POST request (urlencoded)request // Set a base URLrequest // Set headersrequest headers 'X-Random': 1 // Set a timeoutrequest // JSON responses decoded automatically based on Content-Type header (can be turned off)request // Bring your own Promiserequest // You can use async/await of courseconst status body = await request // Helper method to return a nested value from the requestconst status = await requestconst contentType = await requestconst data = await requestconst account = await request
Usage with TypeScript
Yea comes with built-in type declarations.
;request.get'https://example.com'.then.catch;
API
The following methods are available.
- .get(url)
- .post(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)
- .setResponseTransformers([])
- .setAllowedStatusCode(allowed)
- .polyfills(polyfills)
- .then()
- .toObject() / .config() / .debug()
get
Where url
is a string. Shorthand for request.method('get').url(url)
.
post
Where url
is a string. Shorthand for request.method('post').url(url)
.
put
Where url
is a string. Shorthand for request.method('put').url(url)
.
delete
Where url
is a string. Shorthand for request.method('delete').url(url)
.
method
Sets the HTTP method.
methodmethod
Where method
is a string, e.g. 'get'
or 'GET'
.
url
Sets the full URL of the request. If a query-string is present, it will override any previously set query parameters.
Where url
is a string, e.g. 'https://example.com/accounts'
.
urlParams
Sets URL parameters which will be replaced from the URL when the request is sent.
Where object
is an object.
Example:
// Will make request to "/api/accounts/123/info"request
baseUrl
Sets the base URL to which all subsequent request URLs will be appended.
Where url
is a string, e.g. 'https://example.com'
.
A few examples of practical usage:
request // => https://example.com/accountsrequest // => https://example.com/accountsrequest // => https://example.com/nested/accountsrequest // => https://example.com/nested/foo/accounts
query
Sets query parameters from an object or a string. Overwrites existing query.
Where object
is key-value object of query parameters to set, or a valid query string.
Example:
requestrequest
headers
Sets request headers from an object. Overwrites existing headers.
headersobject
Where object
is key-value object of headers to set.
Example:
const req = requestheaders 'x-example': 'foo' ;console // => { 'x-example': 'foo' }// Overwrites all previous headers:const req2 = reqheaders 'x-token': 'secret123' ;console // => { 'x-token': 'secret123' }
amendHeaders
Sets request headers from an object. Only overwrites headers present in the given object.
Where object
is key-value object of headers to set.
Example:
const req = requestheaders 'x-example': 'foo' ;console // => { 'x-example': 'foo', 'x-token': 'secret123' }
header
Adds or updates a header value.
Where key
is a string and value
is a string.
Example:
const req = request;console // => { 'x-example': 'foo', 'x-token': 'secret123' }
unsetHeader
Removes a header from the request.
Where name
is a string.
Example:
const req = requestheaders 'x-example': 'foo' 'x-token': 'secret123' ;console // => { 'x-token': 'secret123' }
body
Set the raw body of the request.
bodydata
Where data
is a string.
See also json
and urlencoded
.
json
Sets a JSON-encoded body and sets the Content-Type
header to 'application/json'
.
Where value
is mixed.
Shorthand for request.header('Content-Type', 'application/json').body(JSON.stringify(value))
.
urlencoded
Sets a URL-encoded body and sets the Content-Type
header to 'application/urlencoded'
.
Where value
is an object.
Shorthand for request.header('content-type', 'application/x-www-form-urlencoded').body(_valueUrlEncoded_)
.
timeout
Sets a timeout after which the request will be aborted and the Promise rejected.
Where milliseconds
is an integer.
See also unsetTimeout
.
unsetTimeout
Removes the timeout-value previously set with timeout
.
prop
Sets a path (similar to lodash.get
) which will be resolved once the response is returned.
Where path
is a string or an array.
Example:
const account = await request;const contentType = await request;
send
Dispatches the request and returns a Promise
.
Where the optional argument body
is a string. If it is set, it will be set as the request body. Also see sendJson
and sendUrlencoded
.
The Promise resolves with a response
object.
request
A new Promise
is always returned, and the YeaAjaxRequest
is not mutated, so you can send the same request multiple times.
const req = request;req;req;
See polyfills
for switching away from global Promise
(e.g. bluebird).
Note that calling .send()
is not always necessary. You can usually directly call .then()
.
sendUrlencoded
Shorthand for .urlencoded(data).send()
.
sendJson
Shorthand for .json(data).send()
.
setResponseTransformers
Sets a list of response transformers which are called when a response is received. By default the list contains one transformer which decodes JSON bodies based on the response Content-Type
header.
Using this method you can remove the default transformer:
If you need to add it back, just set it again:
request;
Transformer functions are executed sequentially in the order they are in the list, and they receive response
as the only parameter. Whatever value they return is passed onto the next transformer and eventually back to the Promise-chain.
request;
Reference to the original array is lost:
const array = ;const req = request;array;reqresponseTransformers; // not affected by the push, still []
setAllowedStatusCode
By default any 2XX status code resolves the Promise and other status codes will reject it. This can be customized using setAllowedStatusCode
.
Where allowed
is an integer, a RegExp
or a function.
polyfills
Override global dependencies which are used internally. Most useful for adding polyfills or a custom Promise-implementation.
Where polyfills
is an object. See example for the possible dependencies you can override:
request
Links to polyfills for older browsers if you need to support them (these can automatically patch window.Promise
; no need to use request.polyfills
):
then
Sends the request and resolves like a normal Promise.
Where arguments are what you would submit to a then-handler of a Promise.
The following examples are basically equivalent:
const responseHandler = { /* ... */ }; // using .then()yea // using .send()yea
toObject
Returns the request configuration as an object.
// alias // alias
Example:
const req = requestconst config = req; // or req.config() or req.debug()// =>// {// method: 'GET',// url: 'http://example.com/info',// body: '',// headers: {// 'x-random': 'foo'// },// allowedStatusCode: /^2[0-9]{2}$/,// timeout: null,// responseTransformers: [// req.jsonResponseTransformer// ],// }
Inspect request config
Use the API methods toObject
, config
or debug
to inspect the configuration of an YeaAjaxRequest
instance.
const req = request;console;
Extending (instances)
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 ; // Extend from previous requestconst req2 = req1; console; // => falseconsole; // => 'foo=bar'console; // => 'something=different'
Practical example of how to create a base request with some defaults and later utilize it for requests:
const api = request headers 'X-API-KEY': 'secret123' ; // The following requests will use the base URL and headers set aboveapi;apibodydata;
Development
Tests
For local development, run yarn dev
. It starts a web server and watches for changes. You can view the tests in the browser at http://localhost:9876.
$ yarn devTest server is running!Open http://localhost:9876/ in your browser
For a one-time full test suite execution, run yarn test
. It runs all tests in a suite of browsers (powered by Karma).
yarn test
Browser support
Chrome, Firefox, IE 10+, Edge, Safari 11+
Cross-browser Testing Platform Provided by Sauce Labs.
Changelog
See CHANGELOG.md.
License
MIT