Notoriously Pedantic Magistrate


    1.1.0 • Public • Published


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

    npm version Build Status


    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.


    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("").then(/* ... */);
        url: ""
    }).then(/* ... */);
        url: "",
        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");
        url: "",
        method: "GET",
        responseType: "buffer"
    }).then(resp => {
        // will be a Buffer under NodeJS, and an ArrayBuffer in the browser
        url: "",
        method: "GET",
        responseType: "arraybuffer"
    }).then(resp => {
        // 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 or instead.

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


    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"


    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.


    npm i cowl

    DownloadsWeekly Downloads






    Unpacked Size

    57.8 kB

    Total Files


    Last publish


    • perrymitchell