Cowl

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

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.