README.md

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
• 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.

Contents

• Installation
• Usage
  • Usage with TypeScript
• Extending (instances)
• API
• Development
• Browser support
• Changelog
• License

Installation

Via CDN

<script src="https://cdn.jsdelivr.net/npm/es6-promise@4/dist/es6-promise.auto.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/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>

View example in JSFiddle

Via npm

Install via npm or yarn:

npm install yea
# or
yarn add yea

Import in a project:

import request from 'yea';
// or
const request = require('yea');

Usage

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]')

Usage with TypeScript

Yea comes with built-in type declarations. See index.d.ts.

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
  .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'

Example

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({ ... });

API

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.

Development

Tests

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 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

Contributing

See CONTRIBUTING.md.

Browser support

Chrome, Firefox, IE 10+, Edge, Safari 11+

Cross-browser Testing Platform Provided by Sauce Labs.

Changelog

See CHANGELOG.md.

License

MIT