xhttp: A JavaScript repository from kuuup

Description

Functional wrapper around XMLHttpRequest. Assumes JSON. Treats non-2** codes as errors. Doesn't force promises, easy to wrap for a promise-based API. Should be compatible with IE9+.

Installation

npm i --save xhttp
# or
npm i --save-dev xhttp

xhttp is published as a CommonJS-style module. It assumes you're using a module-oriented build system such as Webpack or browserify.

import {xhttp} from 'xhttp'
// or
const {xhttp} = require('xhttp')

xhttp(
  {url: '/api/some-resource'},
  (res, xhr) => {/* ... */},
  (err, xhr) => {/* ... */}
)

API

xhttp(
  params :: Object,
  onSuccess :: Function,
  onError :: Function
)

xhttp returns a XMLHttpRequest. It can be used for low level stuff (i.e. to cancel a request).

// This request runs for a long time
const handle = xhttp(/* ... */)

// It can be canceled (if still running) 
handle.abort()

`params`

url :: String

  required

method :: String

  optional
  default = 'GET'

body :: Object

  optional
  when method is GET, HEAD or OPTIONS, body is converted
  into a query string and appended to the URL
  otherwise it's JSON-encoded

headers :: Object

  optional
  default = {
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }

async :: Boolean

  optional
  default = true

username :: String

  optional

password :: String

  optional

Success

xhttp(_, onSuccess, _)

function onSuccess (response, xhr) {/* ... */}

Success callback. Receives response (parsed from JSON) and XHR object.

Error

xhttp(_, _, onError)

function onError (response, xhr) {/* ... */}

Error callback. Receives response (parsed from JSON) and XHR object.

Promises

To get a promise-based API, wrap xhttp with your own Promise variant:

function ajax (params) {
  return new Promise((resolve, reject) => {
    xhttp(params, resolve, reject)
  })
}

kuuup/xhttp