@building-block/xhr-fetch

xhr-fetch

XHR-powered fetch implementation with extras

Although fetch is a relatively low-level API and in most cases more complete than XMLHttpRequest, it does not provide an API for request progression. A proposal for FetchObserver is being worked on but currently it is not possible to implement request progression using just fetch.

xhr-fetch provides a fetch-like interface, enough to make it a viable replacement for XMLHttpRequest, that also implements a non-standard request and response progression API.

If response progression is all you need, fetch does provide a low-level API for response progression. In that case we recommend that you stick with the standards unless you prefer a higher level abstraction.

Installation

Using npm:

$ npm install --save @building-block/xhr-fetch

Using yarn:

$ yarn add @building-block/xhr-fetch

Usage

import xhrFetch from '@building-block/xhr-fetch';

xhrFetch('https://postman-echo.com/put', {
  method: 'PUT',
  headers: { /* headers */ },
  body: { /* body */ },
  onDownloadProgress = (xhrEvent) => {
    console.log('Upload progression', xhrEvent);
  },
  onUploadProgress = (xhrEvent) => {
    console.log('Download progression', xhrEvent);
  },
});

Try with Runkit

Tracking progress

To provide a better user experience, you might want to display progression over time such as bitrate (speed), remaining time, transferred bytes, and overall transfer progress, you can use @building-block/track-progress.

Caveats

Aborting requests

xhr-fetch supports the abortable fetch API. This feature requires that you include additional polyfills for AbortController, AbortSignal and DOMException.

import xhrFetch from '@building-block/xhr-fetch';

const abortController = new AbortController();

xhrFetch('/endpoint', {
  signal: abortController.signal,
}).catch((error) => {
  if (error.name === 'AbortError') {
    console.log('Aborted');
  }
});

abortController.abort();

Looking for a fetch polyfill?

This package is not meant to replace fetch. If you're looking for a fetch polyfill, you should use whatwg-fetch. If you are looking to use fetch in Node.js, you can with node-fetch. In universal environments, you can replace whatwg-fetch and node-fetch with just cross-fetch.