❤
npm
Sign UpSign In

catberry-uhr

5.0.1 • Public • Published

Universal/Isomorphic HTTP(S) Request for Catberry Framework

Build Status codecov.io

Installation

npm install catberry-uhr

Description

Catberry's modules run both at the server and in a browser and it's very important to have a Universal/Isomorphic HTTP(S) Request implementation.

It has the same interface and different implementations at the server and in a browser.

At the server it uses node's http.request or https.request (depends on the specified protocol in URL). In a browser it uses a native XmlHttpRequest.

This module has been developed using HTTP/1.1v2 RFC 2616.

It supports:

  • gzip and deflate request/response content encodings
  • application/json and application/x-www-form-urlencoded request/response content types
  • Request timeout
  • Auto stringify/parse request/response data
  • HTTP/HTTPS
  • Any additional HTTP headers you set

UHR has following methods:

class UHRBase {
    /**
     * Does a GET request to the HTTP server.
     * @param {string} url URL to request.
     * @param {Object?} parameters The request parameters.
     * @param {Object?} parameters.headers The HTTP headers to send.
     * @param {(string|Object)?} parameters.data The data to send.
     * @param {number?} parameters.timeout The request timeout.
     * @param {boolean?} parameters.unsafeHTTPS If true then requests to servers with
     * invalid HTTPS certificates are allowed.
     * @returns {Promise<Object>} The promise for a result with the status object and content.
     */
    get(url, parameters) {}
 
    /**
     * Does a POST request to the HTTP server.
     * @param {string} url URL to request.
     * @param {Object?} parameters The request parameters.
     * @param {Object?} parameters.headers The HTTP headers to send.
     * @param {(string|Object)?} parameters.data The data to send.
     * @param {number?} parameters.timeout The request timeout.
     * @param {boolean?} parameters.unsafeHTTPS If true then requests to servers with
     * invalid HTTPS certificates are allowed.
     * @returns {Promise<Object>} The promise for a result with the status object and content.
     */
    post(url, parameters) {}
 
    /**
     * Does a PUT request to the HTTP server.
     * @param {string} url URL to request.
     * @param {Object?} parameters The request parameters.
     * @param {Object?} parameters.headers The HTTP headers to send.
     * @param {(string|Object)?} parameters.data The data to send.
     * @param {number?} parameters.timeout The request timeout.
     * @param {boolean?} parameters.unsafeHTTPS If true then requests to servers with
     * invalid HTTPS certificates are allowed.
     * @returns {Promise<Object>} The promise for a result with the status object and content.
     */
    put(url, parameters) {}
 
    /**
     * Does a PATCH request to the HTTP server.
     * @param {string} url URL to request.
     * @param {Object?} parameters The request parameters.
     * @param {Object?} parameters.headers The HTTP headers to send.
     * @param {(string|Object)?} parameters.data The data to send.
     * @param {number?} parameters.timeout The request timeout.
     * @param {boolean?} parameters.unsafeHTTPS If true then requests to servers with
     * invalid HTTPS certificates are allowed.
     * @returns {Promise<Object>} The promise for a result with the status object and content.
     */
    patch(url, parameters) {}
 
    /**
     * Does a DELETE request to the HTTP server.
     * @param {string} url URL to request.
     * @param {Object?} parameters The request parameters.
     * @param {Object?} parameters.headers The HTTP headers to send.
     * @param {(string|Object)?} parameters.data The data to send.
     * @param {number?} parameters.timeout The request timeout.
     * @param {boolean?} parameters.unsafeHTTPS If true then requests to servers with
     * invalid HTTPS certificates are allowed.
     * @returns {Promise<Object>} The promise for a result with the status object and content.
     */
    delete(url, parameters) {}
 
    /**
     * Does a request to the HTTP server.
     * @param {string} url URL to request.
     * @param {Object?} parameters The request parameters.
     * @param {string?} parameters.method The HTTP method for the request.
     * @param {string?} parameters.url The URL for the request.
     * @param {Object?} parameters.headers The HTTP headers to send.
     * @param {(string|Object)?} parameters.data The data to send.
     * @param {number?} parameters.timeout The request timeout.
     * @param {boolean?} parameters.unsafeHTTPS If true then requests to servers with
     * invalid HTTPS certificates are allowed.
     * @returns {Promise<Object>} The promise for a result with the status object and content.
     */
    request(parameters) {}
}

Request options example

{
    method: 'GET',
    timeout: 30000,
    // sets value to XMLHttpRequest.withCredentials, works only in a browser
    withCredentials: false,
    unsafeHTTPS: false, // requires valid certificate by default
    headers: {
        Cookie: 'name=value'
    },
    data: {
        parameter: 'value' // all parameters will be URL encoded
    }
}

In case you're doing POST/PUT/PATCH requests, data object will be passed as application/x-www-form-urlencoded via request stream. If you set a Content-Type header to application/json then object will be sent as JSON.

If data value is not an object then its string representation will be sent as text/plain to the server.

Also, if you put anything to data object and use application/x-www-form-urlencoded then this data will be automatically percent-encoded.

Returns a promise

All UHR requests return a Promise for request result. Any error during request will reject the promise or it will be rejected by the request timeout.

Request result consists of following:

  • The status object with HTTP status code, status text and response headers
  • Response content as a plain text or an object (depends on Content-Type in response headers)

For example, request result can be an object like this:

{
    status: {
        code: 200,
        text: 'OK',
        headers: {
            'cache-control': 'no-cache',
            'content-length': '1',
            'content-type': 'text/html; charset=utf-8',
            'date': 'Tue, 08 Apr 2014 05:16:19 GMT'
        }
   },
   content: 'some content from server'
}

All header names are always in a lower-case like they are in node.js.

Usage

If you are using Catberry Framework you have to register UHR into Service Locator.

const cat = catberry.create();
const uhr = require('catberry-uhr');
 
uhr.register(cat.locator);

Then you can just resolve uhr from the locator:

class Store {
    constructor(locator) {
        this._uhr = locator.resolve('uhr');
    }
    load() {
        const options = {
            timeout: 3000,
            data: {
                username: 'some'
            },
            headers: {
                Authorization: 'Bearer somecrazytoken'
            }
        };
        return this._uhr.get('http://localhost/api/user', options)
            .then(result => result.content);
    }
}

Contributing

There are a lot of ways to contribute:

Denis Rechkunov denis.rechkunov@gmail.com

Readme

Keywords

Package Sidebar

Install

npm i catberry-uhr

Repository

github.com/catberry/catberry-uhr

Homepage

github.com/catberry/catberry-uhr

Weekly Downloads

9

Version

5.0.1

License

MIT

Last publish

Collaborators

  • rdner
Try on RunKit
Report malware