request-promise

What is request-promise?

The request-promise npm package is a popular HTTP client for making HTTP requests from Node.js. It is built on top of the 'request' package, providing a simplified way to make HTTP calls and process responses using promises instead of callbacks.

What are request-promise's main functionalities?

Simple HTTP GET requests

This feature allows you to perform simple HTTP GET requests and process the response as a string.

const rp = require('request-promise');

rp('http://example.com')
  .then(function (htmlString) {
    // Process html...
  })
  .catch(function (err) {
    // Handle error...
  });

HTTP requests with options

This feature allows you to perform HTTP requests with a full set of options, including query strings, headers, and automatic JSON parsing.

const rp = require('request-promise');

const options = {
  uri: 'http://api.example.com',
  qs: {
    access_token: 'my-token' // -> uri + '?access_token=my-token'
  },
  headers: {
    'User-Agent': 'Request-Promise'
  },
  json: true // Automatically parses the JSON string in the response
};

rp(options)
  .then(function (repos) {
    // Process repos...
  })
  .catch(function (err) {
    // Handle error...
  });

POST requests with form data

This feature allows you to perform HTTP POST requests with form data.

const rp = require('request-promise');

const options = {
  method: 'POST',
  uri: 'http://api.example.com/form',
  form: {
    key: 'value',
    another_key: 'another_value'
  },
  headers: {
    /* 'content-type': 'application/x-www-form-urlencoded' */ // Is set automatically
  }
};

rp(options)
  .then(function (parsedBody) {
    // POST succeeded...
  })
  .catch(function (err) {
    // POST failed...
  });

Other packages similar to request-promise

axios

Axios is a promise-based HTTP client for the browser and Node.js. It provides an easy-to-use API for making HTTP requests and can be used in both the front-end and back-end. It supports interceptors, request and response transformations, and automatic JSON data transformation, making it more feature-rich compared to request-promise.

got

Got is a human-friendly and powerful HTTP request library for Node.js. It is designed to be a simpler and more lightweight alternative to request-promise, with support for streams and promises. Got also provides a more modern API with built-in support for JSON and better error handling.

node-fetch

node-fetch is a light-weight module that brings the Fetch API to Node.js. It is a minimalistic and straightforward API that closely resembles the browser's fetch API, making it ideal for developers who prefer the fetch syntax and are looking for a simple way to make HTTP requests in Node.js.

superagent

Superagent is a small progressive client-side HTTP request library. It has a flexible and chainable API that allows for easy construction of complex queries. It is often compared to request-promise for its simplicity and ease of use but is more focused on being used in web browsers, although it works in Node.js as well.

README

Request-Promise

A Promises/A XHR wrapper for Bluebird and Request

Bluebird and Request are pretty awesome, but I found myself using the same design pattern. This is a simple wrapper that takes in a request options object (or URI string), and returns a chainable promise. By default, http response codes other than 2xx will cause the promise to be rejected. This can be over-ridden by setting options.simple to false.

Note: As of version 0.1, reject now passes an object containing the following:

    reject({
      error: body,
      options: c,
      response: response,
      statusCode: response.statusCode
    });

Installation

npm install request-promise

Examples

var rp = require('request-promise');

rp('http://www.google.com')
    .then(console.dir)
    .catch(console.error);

//'GET's and displays google.com

var options = {
    uri : 'http://posttestserver.com/post.php',
    method : 'POST'
}; 

rp(options)
    .then(console.dir)
    .catch(console.error);

//displays response from server after post

options.transform = function (data) { return data.length ;};

rp(options)
    .then(console.dir)
    .catch(console.error);

//transform is called just before promise is fulfilled
//displays length of response from server after post


// get full response after DELETE
options = {
  method: 'DELETE',
  uri: 'http://my-server/path/to/resource/1234',
  resolveWithFullResponse: true
};
rp(options)
  .then(function(response) {
    console.log("DELETE succeeded with status %d", response.statusCode);
  })
  .catch(console.error);

Debugging

The ways to debug the operation of request-promise are the same as described for request. However, there are small differences:

1. Launch the node process like NODE_DEBUG=request node script.js (lib,request,otherlib works too).
2. Set require('request-promise').request.debug = true at any time (this does the same thing as #1).
3. Use the request-debug module to view request and response headers and bodies. Instrument request-promise with require('request-debug')(rp.request);.

Contributing

To set up your development environment:

1. clone the repo to your desktop,
2. in the shell cd to the main folder,
3. hit npm install,
4. hit npm install gulp -g if you haven't installed gulp globally yet, and
5. run gulp dev. (Or run node ./node_modules/.bin/gulp dev if you don't want to install gulp globally.)

gulp dev watches all source files and if you save some changes it will lint the code and execute all tests. The test coverage report can be viewed from ./coverage/lcov-report/index.html.

If you want to debug a test you should use gulp test-without-coverage to run all tests without obscuring the code by the test coverage instrumentation.

MIT Licenced