catberry-uhr
v5.0.1
Published
Universal/Isomorphic HTTP(S) Request for Catberry Framework
Downloads
289
Maintainers
Readme
Universal/Isomorphic HTTP(S) Request for Catberry Framework
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
anddeflate
request/response content encodingsapplication/json
andapplication/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
, statustext
and responseheaders
- Response
content
as a plain text or an object (depends onContent-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:
- Give it a star
- Join the Gitter room and leave a feedback or help with answering users' questions
- Submit a bug or a feature request
- Submit a PR
Denis Rechkunov [email protected]