cowl

    1.0.1 • Public • Published

    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:

    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)

    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.

    Install

    npm i cowl

    DownloadsWeekly Downloads

    124

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    56.4 kB

    Total Files

    23

    Last publish

    Collaborators

    • perrymitchell