Skip to content

Latest commit

 

History

History
130 lines (93 loc) · 5.92 KB

README.md

File metadata and controls

130 lines (93 loc) · 5.92 KB
Raw

Cowl

Request cowl for making requests from NodeJS/Browser/React-Native

npm version Build Status

About

Cowl is a wrapper for HTTP/S requests for use in NodeJS and the browser. React-Native is a work-in-progress. It's designed to be useable from 1 script, support bundling (via Webpack) and support sending and receiving data. It provides a simple API that uses a configuration object to make requests.

Cowl can return ArrayBuffers in the browser by specifying arraybuffer as the responseType. Specifying a responseType of buffer in the browser will still result in an ArrayBuffer being returned. Cowl can return both ArrayBuffers and Buffers when running on NodeJS.

Usage

Install it by running npm install cowl.

GET requests can be made by using the configuration object or by simply passing a URL:

const { request } = require("cowl");

request("https://server.com/api").then(/* ... */);

request({
    url: "https://server.com/api"
}).then(/* ... */);

request({
    url: "https://server.com/api",
    method: "GET",
    headers: {
        "Authorization": "Bearer ..."
    }
}).then(/* ... */);

Cowl will automatically assume that JSON is being sent if the body is an Object and no Content-Type header is overridden. Cowl will read the response headers to automatically discern the type if responseType is set to "auto".

Cowl will return a Buffer instance for application/octet-stream binary responses, even if in a browser (ArrayBuffers are converted to Buffer instances).

You can set responseType to be any of the following:

  • auto - Automatically detect the response type (default) (ideal for text/JSON)
  • text - Treat the response as text
  • json - Treat the response as JSON
  • arraybuffer - Treat the response as an Array Buffer. Supported on NodeJS and in the browser.
  • buffer - Treat the response as a Buffer. Supported on NodeJS only. Specifying buffer in the browser will automatically default to requesting as arraybuffer.

NB: The response type is provided to the XHR mechanism, and the output is largely dependent on the server's response. The type you specify as responseType should match what you expect to receive, not what you wish to.

const { request } = require("cowl");

request({
    url: "https://server.com/res/item",
    method: "GET",
    responseType: "buffer"
}).then(resp => {
    // resp.data will be a Buffer under NodeJS, and an ArrayBuffer in the browser
});

request({
    url: "https://server.com/res/item",
    method: "GET",
    responseType: "arraybuffer"
}).then(resp => {
    // resp.data will be an ArrayBuffer
});

Request objects form the following structure:

Property Required Type Description
url Yes String The request URL
method No String The HTTP request method (default: GET)
headers No Object Headers for the request
query No String / Object Query object/string
responseType No String The response type (default: auto)
body No Object / String / Buffer / ArrayBuffer Data to upload

Response objects have the following structure:

Property Type Description
url String The resulting URL that the request was made against
method String The request method used
headers Object The response headers received
data Object Buffer
status Number The status code
statusText String The status code text

Response headers

Headers sent by the server are parsed and all keys converted to lower-case for easier handling.

Request failures

If a request fails or returns a status code outside the allowed range (200-399), an error is thrown. This particular error will contain some properties to help deal with the failure, accessible by using the Layerr Node library. The properties are as follows:

Property Type Description
status Number The status code
statusText String The status text
code Number Usually ERR_REQUEST_FAILED
responseHeaders Object Response headers
responseBody String / * Response body data (unprocessed)

Note that not all the properties will be available for all errors.

Early versions of this project set these properties directly to the Error instance itself, but this method is deprecated. Use Layerr or VError to fetch the info (via Layerr.info(err) or VError.info(err)) instead.

You can specify a new validation method for status codes by providing a validateStatus method in the request options.

Packaging

If you're using webpack to bundle this library, make sure to check out the example in this repo. Specifically, make sure to stub fs and net:

{
    node: {
        fs: "empty",
        net: "empty"
    }
}

Compatibility

Cowl works on NodeJS version 10 and above. Compiling it via Babel or Webpack may allow it to function on earlier versions, but this is not officially supported.