Request-Promise
Deprecated!
As of Feb 11th 2020, request
is fully deprecated. No new changes are expected to land. In fact, none have landed for some time. This package is also deprecated because it depends on request
.
Fyi, here is the reasoning of request
's deprecation and a list of alternative libraries.
The simplified HTTP request client 'request' with Promise support. Powered by Bluebird.
Request and Bluebird are pretty awesome, but I found myself using the same design pattern. Request-Promise adds a Bluebird-powered .then(...)
method to Request call objects. By default, http response codes other than 2xx will cause the promise to be rejected. This can be overwritten by setting options.simple = false
.
Also check out the new libraries that are very similar to request-promise
v4:
request-promise-native
v1 – Does not depend on Bluebird and uses native ES6 promises instead.request-promise-any
v1 – Allows you to register any Promise library supported byany-promise
.
Migration from v3 to v4
request
became a peer dependency. Thus make sure thatrequest
is installed into your project as a direct dependency. (npm install --save request
)- Continuation Local Storage is no longer supported. However, you can get back the support by using
request-promise-any
. - When you migrated your
transform
function to v3 and had to addif (!(/^2/.test('' + response.statusCode))) { return resolveWithFullResponse ? response : body; }
you may now set the optiontransform2xxOnly = true
instead.
Migration from v2 to v3
-
The handling of the
transform
function got overhauled. This has two effects:StatusCodeError.response
is the transformed instead of the original response now. This error is thrown for non-2xx responses whenoptions.simple
istrue
(default). Please update yourtransform
functions to also cover the transformation of non-2xx responses. To get the old behavior you may addif (!(/^2/.test('' + response.statusCode))) { return resolveWithFullResponse ? response : body; }
to the first line of yourtransform
functions that are used for requests withoptions.simple === true
. However, you may prefer updating yourtransform
functions to being able to transform 2xx as well as non-2xx responses because this decouples their implementation from the use of thesimple
option when doing requests.- If a transform operation throws an error, the request will be rejected with a
TransformError
. Itscause
attribute contains the error thrown by the transform operation. Previously, the request was rejected directly with the error thrown by the transform operation. Wrapping it into aTransformError
makes the error handling easier.
-
Bluebird got updated from v2 to v3. This won't make a difference for most use cases. However, if you use advanced Promise chains starting with the Promise returned by Request-Promise, please check Bluebird's new features and changes.
Installation
This module is installed via npm:
npm install --save request
npm install --save request-promise
request
is defined as a peer-dependency and thus has to be installed separately.
Cheat Sheet
var rp = ;
Since request-promise
wraps around request
everything that works with request
also works with request-promise
. Also check out the request
docs for more examples.
Crawl a webpage
;
Crawl a webpage better
var cheerio = ; // Basically jQuery for node.jsvar options =uri: 'http://www.google.com'{return cheerio;};;
GET something from a JSON REST API
var options =uri: 'https://api.github.com/user/repos'qs:access_token: 'xxxxx xxxxx' // -> uri + '?access_token=xxxxx%20xxxxx'headers:'User-Agent': 'Request-Promise'json: true // Automatically parses the JSON string in the response;;
POST data to a JSON REST API
Set option.body
to your data and json: true
to encode the body as JSON. See below for HTML forms.
var options =method: 'POST'uri: 'http://api.posttestserver.com/post'body:some: 'payload'json: true // Automatically stringifies the body to JSON;;
POST like HTML forms do
Pass your data to options.form
to encode the body the same way as HTML forms do:
var options =method: 'POST'uri: 'http://posttestserver.com/post.php'form:// Like <input type="text" name="name">name: 'Josh'headers:/* 'content-type': 'application/x-www-form-urlencoded' */ // Is set automatically;;
If you want to include a file upload then use options.formData
:
var options =method: 'POST'uri: 'http://posttestserver.com/post.php'formData:// Like <input type="text" name="name">name: 'Jenn'// Like <input type="file" name="file">file:value: fsoptions:filename: 'test.jpg'contentType: 'image/jpg'headers:/* 'content-type': 'multipart/form-data' */ // Is set automatically;;
Include a cookie
var tough = ;// Easy creation of the cookie - see tough-cookie docs for detailslet cookie =key: "some_key"value: "some_value"domain: 'api.mydomain.com'httpOnly: truemaxAge: 31536000;// Put cookie in an jar which can be used across multiple requestsvar cookiejar = rp;cookiejar;// ...all requests to https://api.mydomain.com will include the cookievar options =uri: 'https://api.mydomain.com/...'jar: cookiejar // Tells rp to include cookies in jar that match uri;;
Get the full response instead of just the body
var options =method: 'DELETE'uri: 'http://my-server/path/to/resource/1234'resolveWithFullResponse: true // <--- <--- <--- <---;;
Get a rejection only if the request failed for technical reasons
var options =uri: 'http://www.google.com/this-page-does-not-exist.html'simple: false // <--- <--- <--- <---;;
For more options checkout the Request docs.
API in Detail
Consider Request-Promise being:
- A Request object
- With an identical API:
require('request-promise') == require('request')
so to say - However, STREAMING THE RESPONSE (e.g.
.pipe(...)
) is DISCOURAGED because Request-Promise would grow the memory footprint for large requests unnecessarily high. Use the original Request library for that. You can use both libraries in the same project.
- With an identical API:
- Plus some methods on a request call object:
rp(...).then(...)
or e.g.rp.post(...).then(...)
which turnrp(...)
andrp.post(...)
into promisesrp(...).catch(...)
or e.g.rp.del(...).catch(...)
which is the same method as provided by Bluebird promises- Errors that the
request
library would pass to the callback are wrapped byrequest-promise
and then passed to the catch handler. See code example below.
- Errors that the
rp(...).finally(...)
or e.g.rp.put(...).finally(...)
which is the same method as provided by Bluebird promisesrp(...).cancel()
or e.g.rp.get(...).cancel()
which cancels the requestrp(...).promise()
or e.g.rp.head(...).promise()
which returns the underlying promise so you can access the full Bluebird API
- Plus some additional options:
simple = true
which is a boolean to set whether status codes other than 2xx should also reject the promiseresolveWithFullResponse = false
which is a boolean to set whether the promise should be resolved with the full response or just the response bodytransform
which takes a function to transform the response into a custom value with which the promise is resolvedtransform2xxOnly = false
which is a boolean to set whether the transform function is applied to all responses or only to those with a 2xx status code
The objects returned by request calls like rp(...)
or e.g. rp.post(...)
are regular Promises/A+ compliant promises and can be assimilated by any compatible promise library.
The methods .then(...)
, .catch(...)
, and .finally(...)
- which you can call on the request call objects - return a full-fledged Bluebird promise. That means you have the full Bluebird API available for further chaining. E.g.: rp(...).then(...).spread(...)
If, however, you need a method other than .then(...)
, .catch(...)
, or .finally(...)
to be FIRST in the chain, use .promise()
: rp(...).promise().bind(...).then(...)
.then(onFulfilled, onRejected)
// As a Request user you would write:var request = ;;// As a Request-Promise user you can now write the equivalent code:var rp = ;;
// The same is available for all http method shortcuts:request;rp;
.catch(onRejected)
;// ... is syntactical sugar for:;// However, this:;// ... is safer than:;
For more info on .then(process).catch(handleError)
versus .then(process, handleError)
, see Bluebird docs on promise anti-patterns.
.finally(onFinished)
;
.cancel()
This method cancels the request using Bluebird's cancellation feature.
When .cancel()
is called:
- the promise will neither be resolved nor rejected and
- the request is aborted.
.promise() - For advanced use cases
In order to not pollute the Request call objects with the methods of the underlying Bluebird promise, only .then(...)
, .catch(...)
, and .finally(...)
were exposed to cover most use cases. The effect is that any methods of a Bluebird promise other than .then(...)
, .catch(...)
, or .finally(...)
cannot be used as the FIRST method in the promise chain:
// This works:;;// This works as well since additional methods are only used AFTER the FIRST call in the chain:;;// Using additional methods as the FIRST call in the chain does not work:// rp('http://google.com').bind(this).then(function () { ... });// Use .promise() in these cases:;
resolveWithFullResponse
option
Fulfilled promises and the // Per default the body is passed to the fulfillment handler:;// The resolveWithFullResponse options allows to pass the full response:;
simple
option
Rejected promises and the // The rejection handler is called with a reason object...;// ... and would be equivalent to this Request-only implementation:var options = uri: 'http://google.com' ;;// If you pass the simple option as false...;// ... the equivalent Request-only code would be:;// E.g. a 404 would now fulfill the promise.// Combine it with resolveWithFullResponse = true to check the status code in the fulfillment handler.
With version 0.4 the reason objects became Error objects with identical properties to ensure backwards compatibility. These new Error types allow targeted catch blocks:
var errors = ;;
transform
function
The You can pass a function to options.transform
to generate a custom fulfillment value when the promise gets resolved.
// Just for fun you could reverse the response body:var options =uri: 'http://google.com'{return body;};;// However, you could also do something useful:var $ = ; // Basically jQuery for node.js{// FIXME: The content type string could contain additional values like the charset.// Consider using the `content-type` library for a robust comparison.if responseheaders'content-type' === 'application/json'return JSON;else if responseheaders'content-type' === 'text/html'return $;elsereturn body;}optionstransform = autoParse;;// You can go one step further and set the transform as the default:var rpap = rp;;;
The third resolveWithFullResponse
parameter of the transform function is equivalent to the option passed with the request. This allows to distinguish whether just the transformed body or the whole response shall be returned by the transform function:
{responsebody = responsebody;return resolveWithFullResponse ? response : responsebody;}
As of Request-Promise v3 the transform function is ALWAYS executed for non-2xx responses. When options.simple
is set to true
(default) then non-2xx responses are rejected with a StatusCodeError
. In this case the error contains the transformed response:
var options =uri: 'http://the-server.com/will-return/404'simple: true{ /* ... */ };;
You may set options.transform2xxOnly = true
to only execute the transform function for responses with a 2xx status code. For other status codes – independent of any other settings, e.g. options.simple
– the transform function is not executed.
Error handling
If the transform operation fails (throws an error) the request will be rejected with a TransformError
:
var errors = ;var options =uri: 'http://google.com'{throw 'Transform failed!';};;
Experimental Support for Continuation Local Storage
Continuation Local Storage is no longer supported. However, you can get back the support by using request-promise-any
.
Debugging
The ways to debug the operation of Request-Promise are the same as described for Request. These are:
- Launch the node process like
NODE_DEBUG=request node script.js
(lib,request,otherlib
works too). - Set
require('request-promise').debug = true
at any time (this does the same thing as #1). - Use the request-debug module to view request and response headers and bodies. Instrument Request-Promise with
require('request-debug')(rp);
.
Mocking Request-Promise
Usually you want to mock the whole request function which is returned by require('request-promise')
. This is not possible by using a mocking library like sinon.js alone. What you need is a library that ties into the module loader and makes sure that your mock is returned whenever the tested code is calling require('request-promise')
. Mockery is one of such libraries.
@florianschmidt1994 kindly shared his solution:
; ; ;
Based on that you may now build a more sophisticated mock. Sinon.js may be of help as well.
Contributing
To set up your development environment:
- clone the repo to your desktop,
- in the shell
cd
to the main folder, - hit
npm install
, - hit
npm install gulp -g
if you haven't installed gulp globally yet, and - run
gulp dev
. (Or runnode ./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
- v4.2.6 (2020-07-21)
- Security fix: bumped
request-promise-core
which bumpslodash
to^4.17.19
following this advisory.
- Security fix: bumped
- v4.2.5 (2019-11-03)
- Security fix: bumped
request-promise-core
which bumpslodash
to^4.17.15
. See vulnerabilty reports. (Thanks to @rishabh-chowdhary for reporting this in pull request #326.)
- Security fix: bumped
- v4.2.4 (2019-02-14)
- Corrected mistakenly set
tough-cookie
version, now^2.3.3
(Thanks to @evocateur for pointing this out.) - If you installed
request-promise@4.2.3
please make sure after the upgrade thatrequest
andrequest-promise
use the same physical copy oftough-cookie
.
- Corrected mistakenly set
- v4.2.3 (2019-02-14)
- Using stricter
tough-cookie@~2.3.3
to avoid installingtough-cookie@3
which introduces breaking changes (Thanks to @aomdoa for pull request #299) - Security fix: bumped
lodash
to^4.17.11
, see vulnerabilty reports
- Using stricter
- v4.2.2 (2017-09-22)
- Upgraded
tough-cookie
to a version without regex DoS vulnerability (Thanks to @rouanw for pull request #226)
- Upgraded
- v4.2.1 (2017-05-07)
- Fix that allows to use
tough-cookie
for cookie creation (Thanks to @ScottyMJacobson for reporting issue #183) - Added cookie handling example to the cheat sheet (Thanks to @chovy and @ProfessorTom for asking for it)
- Fix that allows to use
- v4.2.0 (2017-03-16)
- Updated
bluebird
to v3.5 (Thanks to @acinader for pull request #181)
- Updated
- v4.1.1 (2016-08-08)
- v4.1.0 (2016-07-30)
- Added cancellation support (Thanks to @not-an-aardvark for pull request #123)
- v4.0.2 (2016-07-18)
- Fix for using with module bundlers like Webpack and Browserify
- v4.0.1 (2016-07-17)
- Fixed
@request/promise-core
version for safer versioning
- Fixed
- v4.0.0 (2016-07-15)
- Breaking Change:
request
is declared as a peer dependency which has to be installed separately by the user now - Breaking Change: Dropped support for Continuation Local Storage since
request-promise-any
can be used for that now - Introduced the
transform2xxOnly
option to ease the breaking change regarding the newtransform
handling in v3.0.0 (Thanks to @stevage for pointing out the effect of the breaking change in issue #131) - Resolved issues #65 and #71 by publishing nearly identical libraries to support other Promise implementations:
request-promise-native
andrequest-promise-any
(Thanks to @benjamingr, @eilgin, @gillesdemey, @hildjj, @iggycoloma, @jonathanong, @knpwrs, @MarkHerhold, @massimocode, @mikeal, @niftylettuce, @raitucarp, @sherdeadlock, @tonylukasavage, and @vgoloviznin for the valuable discussions!) - Relicensed this library with the ISC license
- Breaking Change:
- v3.0.0 (2016-04-16)
- Breaking Change: Overhauled the handling of the
transform
function (Thanks to @Limess for explaining the need in issue #86) - Breaking Change: Updated
bluebird
to v3 (Thanks to @BrandonSmith for pull request #103) - Improved
StatusCodeError.message
- Updated
lodash
to v4.6 - Improved README in regard to
.catch(...)
best practice (Thanks to @RebootJeff for pull request #98)
- Breaking Change: Overhauled the handling of the
- v2.0.1 (2016-02-17)
- Updated
lodash
to v4 (Thanks to @ratson for pull request #94)
- Updated
- v2.0.0 (2016-01-12)
- Breaking Change: Removed explicit
cls-bluebird
dependency which has to be installed by the user now (Thanks to @hildjj for his pull request #75) npm shrinkwrap
now works fornpm@3
users who don't usecontinuation-local-storage
(Thanks to @toboid and @rstacruz for reporting the issue in issue #70 and issue #82)
- Breaking Change: Removed explicit
- v1.0.2 (2015-10-22)
- Removed
continuation-local-storage
from peer dependencies as it was unnecessary (Thanks to @mrhyde for working on a better solution discussed in issue #70)
- Removed
- v1.0.1 (2015-10-14)
- Fixed a npm warning by marking
continuation-local-storage
as a peer dependency
- Fixed a npm warning by marking
- v1.0.0 (2015-10-11)
- Breaking Change: Some errors that were previously thrown synchronously - e.g. for wrong input parameters - are now passed to the rejected promise instead (Thanks to @josnidhin for suggesting that in issue #43)
- Breaking Change: Request-Promise does not load its own Bluebird prototype anymore. If you use Bluebird in your project and altered the prototype then Request-Promise may use your altered Bluebird prototype internally.
- For HEAD requests the headers instead of an empty body is returned (unless
resolveWithFullResponse = true
is used) (Thanks to @zcei for proposing the change in issue #58) - Extended
transform
function by a thirdresolveWithFullResponse
parameter - Added experimental support for continuation local storage (Thanks to @silverbp preparing this in issue #64)
- Added node.js 4 to the Travis CI build
- Updated the README (Thanks to many people for their feedback in issues #55 and #59)
- v0.4.3 (2015-07-27)
- Reduced overhead by just requiring used lodash functions instead of the whole lodash library (Thanks to @luanmuniz for pull request #54)
- Updated dependencies
- v0.4.2 (2015-04-12)
- Updated dependencies
- v0.4.1 (2015-03-20)
- Improved Error types to work in browsers without v8 engine (Thanks to @nodiis for pull request #40)
- v0.4.0 (2015-02-08)
- Introduced Error types used for the reject reasons (See last part this section) (Thanks to @jakecraige for starting the discussion in issue #38)
- Minor Breaking Change: The reject reason objects became actual Error objects. However,
typeof reason === 'object'
still holds true and the error objects have the same properties as the previous reason objects. If the reject handler only accesses the properties on the reason object - which is usually the case - no migration is required. - Added io.js and node.js 0.12 to the Travis CI build
- v0.3.3 (2015-01-19)
- Fixed handling possibly unhandled rejections to work with the latest version of Bluebird (Thanks to @slang800 for reporting this in issue #36)
- v0.3.2 (2014-11-17)
- Exposed
.finally(...)
to allow using it as the first method in the promise chain (Thanks to @hjpbarcelos for his pull request #28)
- Exposed
- v0.3.1 (2014-11-11)
- Added the
.promise()
method for advanced Bluebird API usage (Thanks to @devo-tox for his feedback in issue #27)
- Added the
- v0.3.0 (2014-11-10)
- Carefully rewritten from scratch to make Request-Promise a drop-in replacement for Request
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.