chain-xhr

Chain XHR aims to make creating XHR requests as simple as possible through a chainable API.

Note: chain-xhr is not final yet and I plan on implementing more features including simplifying the process of sending different types of data such as form data.

Table of contents

• Install
• Usage
• Properties
• API
• Examples
• Tests

Install

To install chain-xhr, you can use

$ npm install chain-xhr

Usage

To use chain-xhr in your application, simply import it as an ES6 module like so:

// Webpack
import ChainXHR from 'chain-xhr';

// Browser
import ChainXHR from './path/to/chain-xhr.js';

const request = new ChainXHR();

Properties

METHODS

The methods property exposes the different http request types that can be used with ChainXHR. While these are not required to be used, they can be used instead of the string representations if you want to be safe.

const requost = new ChainXHR();

console.log(request.METHODS.GET);     // 'GET'
console.log(request.METHODS.POST);    // 'POST'
console.log(request.METHODS.PUT);     // 'PUT'
console.log(request.METHODS.DELETE);  // 'DELETE'

API

url

Sets the URL that this request should be sent to.

| Param | Type | Description | Default | |-------|--------|----------------------------------|---------| | url | string | The url to send this request to. | |

const request = new ChainXHR();

const res = await request
  .url('https://jsonplaceholder.typicode.com/todos/1')
  .send();

method

Sets the http request moethod to be used by this request.

This is set to 'GET' by default. When setting this, you can choose to type in a string directly such as 'GET' or 'get' or you can use the REQUEST constant of ChainXHR to set this.

| Param | Type | Description | Default | |--------|--------|------------------------------------------------------|---------| | method | string | The http request method to use for this XHR request. | |

Using the METHODS property:

const request = new ChainXHR();

const res = await request
  .url('https://jsonplaceholder.typicode.com/todos/1')
  .method(request.METHODS.GET)
  .send();

Using a string:

const request = new ChainXHR();

const res = await request
  .url('https://jsonplaceholder.typicode.com/todos/1')
  .method('GET')
  .send();

withCredentials

Sets this request to be made with credentials such as cookies, authorization headers, or TLS certificates.

By default this is set to false and it also has no effect on same-site requests.

const request = new ChainXHR();

const res = await request
  .url('https://jsonplaceholder.typicode.com/todos/1')
  .withCredentials()
  .send();

contentType

Sets the content type header which indicates what type of content is being send to the endpoint.

By default this is set to 'application/json'.

| Param | Type | Description | Default | |-------------|--------|-------------------------------------------------------|---------| | contentType | string | The type of content that is being sent to the server. | |

const request = new ChainXHR();

const res = await request
  .url('https://jsonplaceholder.typicode.com/posts')
  .contentType('multipart/form-data')
  .send();

queryParam

Adds a query parameter to send with the request.

This should be chained multiple times to add multiple query parameters.

| Param | Type | Description | Default | |-------|--------|----------------------------------------|---------| | key | string | The key of the query parameter to add. | | | value | string | The value of the key added. | |

const request = new ChainXHR();

const res = await request
  .url('https://jsonplaceholder.typicode.com/posts')
  .queryParam('hello', 'world')
  .queryParam('count', 5)
  .send();

data

Sets the data to send through with the request.

| Param | Type | Description | Default | |-------|------|-------------------------------------------|---------| | data | * | The data to send through with the request | |

Sending an Object:

const request = new ChainXHR();

const obj = { hello: 'world', year: 2019 };

const res = await request
  .url('https://jsonplaceholder.typicode.com/posts')
  .data(obj)
  .send();

Sending key value pairs individually:

const request = new ChainXHR();

const res = await request
  .url('https://jsonplaceholder.typicode.com/posts')
  .data('hello', 'world')
  .data('year', 2019)
  .send();

json

Specifies that the data returned should be JSON parsed.

const request = new ChainXHR();

const res = await request
  .url('https://jsonplaceholder.typicode.com/posts')
  .json()
  .send();

abort

Aborts the request if it already has been sent.

When a request is aborted, its readystate is changed to 0 and the status code is set to 0 also.

const request = new ChainXHR();

const res = await request
  .url('https://jsonplaceholder.typicode.com/posts')
  .json()
  .send()
  .abort();

send

Indicates that the XHR request is finished being built and is ready to be sent.

This should always be the final method used in all requests.

const request = new ChainXHR();

const res = await request
  .url('https://jsonplaceholder.typicode.com/posts')
  .send();

Examples

Sending a GET request and returning JSON data:

const request = new ChainXHR();

const res = await request
  .method(request.METHODS.GET)
  .url('https://jsonplaceholder.typicode.com/todos/1')
  .json()
  .send();

Sending a GET request with a query parameter:

const request = new ChainXHR();

const res = await request
  .method(request.METHODS.GET)
  .url('https://jsonplaceholder.typicode.com/posts')
  .queryParam('userId', 1)
  .json()
  .send();

Sending a POST request with JSON data:

const request = new ChainXHR();

const res = await request
  .method(request.METHODS.POST)
  .url('https://jsonplaceholder.typicode.com/posts')
  .data({
    title: 'foo',
    body: 'bar',
    userId: 1
  })
  .json()
  .send()
  .catch(err => { throw new Error(err) });

Sending a POST request with form data:

const request = new ChainXHR();

const formData = new FormData();

formData.append('title', 'foo');
formData.append('body', 'bar');
formData.append('userId', 1);

const res = await request
  .method(request.METHODS.POST)
  .url('https://jsonplaceholder.typicode.com/posts')
  .contentType('multipart/form-data')
  .data(formData)
  .json()
  .send()
  .catch(err => { throw new Error(err) });

Tests

To run all of the available tests use:

$ npm run test

License

MIT