request-promise-core

What is request-promise-core?

The request-promise-core package is a foundational library for making HTTP requests in Node.js. It is designed to be a lightweight and flexible core for building HTTP request libraries with promise support. It provides the essential functionality for making HTTP requests and handling responses, and it can be extended or used as a base for more complex request libraries.

What are request-promise-core's main functionalities?

Basic HTTP Request

This feature allows you to make a basic HTTP GET request to a specified URI and handle the response using promises. The example demonstrates how to fetch a post from a placeholder API and log the response.

const request = require('request-promise-core');
const options = {
  method: 'GET',
  uri: 'https://jsonplaceholder.typicode.com/posts/1',
  json: true
};
request(options)
  .then(response => {
    console.log(response);
  })
  .catch(err => {
    console.error(err);
  });

Custom Request Options

This feature allows you to customize the HTTP request by specifying various options such as method, URI, and request body. The example demonstrates how to make a POST request to create a new post on a placeholder API.

const request = require('request-promise-core');
const options = {
  method: 'POST',
  uri: 'https://jsonplaceholder.typicode.com/posts',
  body: {
    title: 'foo',
    body: 'bar',
    userId: 1
  },
  json: true
};
request(options)
  .then(response => {
    console.log(response);
  })
  .catch(err => {
    console.error(err);
  });

Handling Errors

This feature demonstrates how to handle errors that occur during an HTTP request. The example shows how to catch and log errors when making a request to an invalid endpoint.

const request = require('request-promise-core');
const options = {
  method: 'GET',
  uri: 'https://jsonplaceholder.typicode.com/invalid-endpoint',
  json: true
};
request(options)
  .then(response => {
    console.log(response);
  })
  .catch(err => {
    console.error('Request failed:', err.message);
  });

Other packages similar to request-promise-core

axios

Axios is a popular promise-based HTTP client for the browser and Node.js. It provides a simple and easy-to-use API for making HTTP requests and handling responses. Compared to request-promise-core, Axios offers more built-in features such as request and response interceptors, automatic JSON data transformation, and support for canceling requests.

node-fetch

Node-fetch is a lightweight module that brings the Fetch API to Node.js. It is designed to be a minimalistic and efficient HTTP client. Compared to request-promise-core, node-fetch has a smaller footprint and is more aligned with the Fetch API standard used in browsers, making it a good choice for developers who prefer a consistent API across environments.

got

Got is a human-friendly and powerful HTTP request library for Node.js. It supports promises, streams, retries, and many other advanced features. Compared to request-promise-core, Got offers a more comprehensive set of features out of the box, including support for advanced request customization, hooks, and built-in retry mechanisms.

README

request-promise-core

This package is the core for the following packages:

• request-promise
• request-promise-any
• request-promise-bluebird
• request-promise-native

request-promise-core contains the core logic to add Promise support to request.

Please use one of the libraries above. It is only recommended to use this library directly, if you have very specific requirements.

Installation for request@^2.34

This module is installed via npm:

npm install --save request
npm install --save request-promise-core

request is defined as a peer-dependency and thus has to be installed separately.

Usage for request@^2.34

// 1. Load the request library

// Only use a direct require if you are 100% sure that:
// - Your project does not use request directly. That is without the Promise capabilities by calling require('request').
// - Any of the installed libraries use request.
// ...because Request's prototype will be patched in step 2.
/* var request = require('request'); */

// Instead use:
var stealthyRequire = require('stealthy-require');
var request = stealthyRequire(require.cache, function () {
    return require('request');
});


// 2. Add Promise support to request

var configure = require('request-promise-core/configure/request2');

configure({
    request: request,
	// Pass your favorite ES6-compatible promise implementation
    PromiseImpl: Promise,
	// Expose all methods of the promise instance you want to call on the request(...) call
    expose: [
        'then',   // Allows to use request(...).then(...)
        'catch',  // Allows to use request(...).catch(...)
        'promise' // Allows to use request(...).promise() which returns the promise instance
    ],
    // Optional: Pass a callback that is called within the Promise constructor
    constructorMixin: function (resolve, reject) {
        // `this` is the request object
        // Additional arguments may be passed depending on the PromiseImpl used
    }
});


// 3. Use request with its promise capabilities

// E.g. crawl a web page:
request('http://www.google.com')
    .then(function (htmlString) {
        // Process html...
    })
    .catch(function (err) {
        // Crawling failed...
    });

Installation and Usage for request@next

Request Next is still in alpha. However, request-promise-core is already designed to be compatible and ships with a configuration helper – require('request-promise-core/configure/request-next') – that is used by request-promise in its "next" branch.

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.

Change History

• 1.1.4 (2020-07-21)
  • Security fix: bumped lodash to ^4.17.19 following this advisory.
• 1.1.3 (2019-11-03)
  • Security fix: bumped lodash to ^4.17.15. See vulnerabilty reports. (Thanks to @daniel-nagy for pull request #20 and thanks to @quetzaluz for reporting this in issue #21.)
• 1.1.2 (2019-02-14)
  • Security fix: bumped lodash to ^4.17.11. See vulnerabilty reports. (Thanks to @lucaswillering and @sam-warren-finnair for reporting this in issues #12 and #13 and thanks to @Alec321 for pull request #14.)
• 1.1.1 (2016-08-08)
  • Renamed package to request-promise-core because there were too many issues with the scoped package name @request/promise-core
• 1.1.0 (2016-07-30)
  • Added constructorMixin option to enable request/request-promise#123
• 1.0.0 (2016-07-15)
  • All tests green, ready for prime time
• 1.0.0-rc.1 (2016-07-10)
  • Reimplementation of core logic based on request-promise@3.0.0
  • Plus transform2xxOnly option (fixes request/request-promise#131)

License (ISC)

In case you never heard about the ISC license it is functionally equivalent to the MIT license.

See the LICENSE file for details.