minimal-request-promise

#Minimal Promise version of HTTPS request

This is a wrapper for the standard HTTPS Node Request object, that provides an A+ Promise interface to request execution and automates the process of assembling the response body as a string. It can handle posting body contents, and automatically rejects the promise if the response code is not between 200 and 399.

The intent of this library is to wrap requests into a promise interface with minimal overhead, with no dependencies, and just expose the standard Node.js arguments. It's not trying to be a fully-featured replacement for complex workflows, streaming etc. For more complex libraries that can provide all kind of workflows like that, see request-promise and got.

##Installation

Install using NPM:

npm install minimal-request-promise

##Usage

You can use the standard Node HTTPS Request Options, with the following additional options:

• body: string, the content to include in the request body when posting
• resolveErrors: boolean, if true, HTTP error response codes will result in a resolved promise (instead of rejected). Only network errors will result in a rejected promise. If false (default), network errors and successful HTTP requests with an error response code will cause the promise to be rejected.

If you want to execute a FORM POST, remember to add the Content-Length header as well. This library intentionally does not automatically add that, to keep the interface in line with standard Node.JS requests.

##Example

var requestPromise = require('minimal-request-promise'),
  options = {
    method: 'POST',
    hostname: 'graph.facebook.com',
    path: '/v2.6/me/messages?access_token=' + fbAccessToken,
    port: 443,
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      recipient: {
        id: recipient
      },
      message: message
    })
  };

requestPromise(options).then(
  function (response) {
    console.log('got response', response.body, response.headers);
  },
  function (response) {
    console.log('got error', response.body, response.headers, response.statusCode, response.statusMessage);
  }
);

##GET and POST method shortcuts

In addition to using the standard Node.js request parameters, you can also generate basic parameters from URLS for GET and POST using the helper methods. The helper methods are .get and .post, and they expect the following arguments:

• url: string, a URL to GET or POST to
• options: (optional) object, key-value map of additional options, described in the Usage section
• Promise: (optional) Function, an alternate Promise implementation. See Using with a different Promise library.

Example:

var requestPromise = require('minimal-request-promise'),
  options = {
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      recipient: {
        id: recipient
      },
      message: message
    })
  };

requestPromise.post('https://graph.facebook.com/v2.6/me/messages?access_token=' + fbAccessToken, options).then(
  function (response) {
    console.log('got response', response.body, response.headers);
  },
  function (response) {
    console.log('got error', response.body, response.headers, response.statusCode, response.statusMessage);
  }
);

##Using with a different Promise library

By default, this library uses the built-in Promise from Node.js. If you'd like to use a different A+ Promise library, just pass it in as the second argument. For example:

var bluebird = require('bluebird'),
  requestPromise = require('minimal-request-promise'),
  options = {  
   // some options here ...
  };
requestPromise(options, bluebird).then(report);

##License

MIT