README.md

Frest

Browser REST client wrapper of Fetch API with XHR fallback and interceptor support

Features

• HTTP methods shortcut and CRUD aliases
• XMLHttpRequest fallback, for file download/upload (with progress event) and when Fetch API is not available
• Interceptors to manipulate request/response/error:
  • Before request, add additional config for all/some operation before firing the request
  • After response, transform response before returning for all/some operation
  • Error, catch all error / request retry possibility
• Include UMD build for direct usage in html script tag
• Include TypeScript definition

Usage

Install the package using npm or yarn

npm install --save frest
# or
yarn add frest

Or include the UMD build directly in a script tag

<script type="text/javascript" src="https://unpkg.com/frest"></script>

Basic examples.

import frest from 'frest';
// in UMD build, frest, Frest and FrestError are included in Window object

// with default instance
// call HTTP method
frest
  // request config will override the default config of Frest instance
  .get('foo', { headers: new Headers({ 'X-Foo': 'foo' }) })
  .then(res => {
    // res is an object containing Fetch's response and the body
    console.log('origin', res.origin);
    // by default, without any interceptors, the body is undefined
    console.log('body', res.body);
    if (res.origin.ok) {
      return res.origin.json();
    }
    Promise.reject('uh oh');
  })
  .then(body => {
    console.log('body', body);
  })
  .catch(err => {
    // err is an instance of FrestError
    console.error('err', err);
  });

// available methods
api.post(...) // HTTP POST
api.put(...) // HTTP PUT
api.delete(...) // HTTP DELETE
api.patch(...) // HTTP PATCH
api.option(...) // HTTP OPTION
api.download(...) // Download file, support onDownloadProgress event
api.upload(...) // Upload file, support onUploadProgress event

// Use with async-await style
async function makeRequest() {
  try {
    const res = await api.post('blah');
    if (res.ok) {
      const body = await res.origin.json();
      console.log('body', body);
    }
  } catch (err) {
    console.error('request failed', err);
  }
}

// With custom instance
const api = frest.create('https://api.example.com');

// config extends Fetch's init option
const api = frest.create({
  base: 'https://api.example.com',
  headers: new Headers({
    'X-Foo': 'bar',
  }),
});