README

Req

Make Ajax calls correctly with a thin wrapper around XMLHttpRequest and Node’s HTTP module.

Ideal for small requests and responses - especially JSON. Perfect for microservices.

Why?

We make ajax calls often but the mechanism (XMLHttpRequest) is not very intuitive to use. It is surprisingly hard to get it right across all browsers with proper error handling.

Even if we work out XMLHttpRequest, the event management for the backend Node’s HTTP module means we have to solve all the tricky bits there too.

Req wraps XMLHttpRequest and Node’s HTTP so that both use the same simple API in the most efficient manner possible.

Usage

Install:

$ npm install @tpp/req

Use:

const req = require("@tpp/req")

req.get(url, cb)
req.get(url, data, cb)

req.post(url, cb)
req.post(url, data, cb)

req.send({
  method: 'GET' | 'POST' | 'PUT' | ...
  url: ...,
  data: ...,
  timeout: ...,
  headers: ...,
}, cb)

Content-Type

If you don’t set a Content-Type header, Req will set:

application/json if the ‘data’ is a JSON object
application/x-www-form-urlencoded or multipart/form-data for FormData
text/plain for everything else (strings etc)

Callback

Req checks the response codes and error cases for you so the callback doesn’t have to. So the callback can be treated like a ‘normal’ async callback.

cb(err, resp)

The response contains the the http status code, the body of the response with data, and the HTTP response headers.

{
  status: 200,
  headers: headerMapFn(),
  body: {data: 1234}
}

For the response body itself, Req will try it's best to parse it as JSON. If it is unable to do so it will return an object with a single response field.

{
  response: <response string>
}

Note that resp can also be null if no response data was sent back.

Use the headers() method to parse and retrieve the header map:

function onResp(err, resp) {
  ...
  let headers = resp.headers()
  if(headers['content-type'] == "text/plain") {
    ...
  }
}

FAQ

Why not use the `fetch` api?

You can! It’s a great replacement for XMLHttpRequest on the browser. Req is if you want a tight, clean and simple callback that works well with JSON request/responses.

Plus it works both on the browser and in the backend which makes code sharing easier.

Why not use `request`, `axis`, `superagent` etc?

They are great libraries with support for a lot of stuff which we mostly don’t need. Req is tiny, focused and fast. For comparison:

Library	Size
request	684.2kB
axios	13.4kB
superagent	32.8kB
`Req`	2.9kB

What happens when the Server responds with a HTML error?

Sometimes servers are configured to send back full HTML pages as error responses (remember the “fail-whale”?). Many servers do this because they expect the requester to be a browser and so sending back HTML makes sense.

However, in a Microservice environment, we have found it is better to be able to see/log text rather than HTML. For this reason, when there are error HTML documents sent back, Req will parse them and extract out the message as a text.

Usage no npm install needed!