How do I convert an existing callback API to promises?
Solution 1
Promises have state, they start as pending and can settle to:
- fulfilled meaning that the computation completed successfully.
- rejected meaning that the computation failed.
Promise returning functions should never throw, they should return rejections instead. Throwing from a promise returning function will force you to use both a } catch {
and a .catch
. People using promisified APIs do not expect promises to throw. If you're not sure how async APIs work in JS - please see this answer first.
1. DOM load or other one time event:
So, creating promises generally means specifying when they settle - that means when they move to the fulfilled or rejected phase to indicate the data is available (and can be accessed with .then
).
With modern promise implementations that support the Promise
constructor like native ES6 promises:
function load() {
return new Promise(function(resolve, reject) {
window.onload = resolve;
});
}
You would then use the resulting promise like so:
load().then(function() {
// Do things after onload
});
With libraries that support deferred (Let's use $q for this example here, but we'll also use jQuery later):
function load() {
var d = $q.defer();
window.onload = function() { d.resolve(); };
return d.promise;
}
Or with a jQuery like API, hooking on an event happening once:
function done() {
var d = $.Deferred();
$("#myObject").once("click",function() {
d.resolve();
});
return d.promise();
}
2. Plain callback:
These APIs are rather common since well… callbacks are common in JS. Let's look at the common case of having onSuccess
and onFail
:
function getUserData(userId, onLoad, onFail) { …
With modern promise implementations that support the Promise
constructor like native ES6 promises:
function getUserDataAsync(userId) {
return new Promise(function(resolve, reject) {
getUserData(userId, resolve, reject);
});
}
With libraries that support deferred (Let's use jQuery for this example here, but we've also used $q above):
function getUserDataAsync(userId) {
var d = $.Deferred();
getUserData(userId, function(res){ d.resolve(res); }, function(err){ d.reject(err); });
return d.promise();
}
jQuery also offers a $.Deferred(fn)
form, which has the advantage of allowing us to write an expression that emulates very closely the new Promise(fn)
form, as follows:
function getUserDataAsync(userId) {
return $.Deferred(function(dfrd) {
getUserData(userId, dfrd.resolve, dfrd.reject);
}).promise();
}
Note: Here we exploit the fact that a jQuery deferred's resolve
and reject
methods are "detachable"; ie. they are bound to the instance of a jQuery.Deferred(). Not all libs offer this feature.
3. Node style callback ("nodeback"):
Node style callbacks (nodebacks) have a particular format where the callbacks is always the last argument and its first parameter is an error. Let's first promisify one manually:
getStuff("dataParam", function(err, data) { …
To:
function getStuffAsync(param) {
return new Promise(function(resolve, reject) {
getStuff(param, function(err, data) {
if (err !== null) reject(err);
else resolve(data);
});
});
}
With deferreds you can do the following (let's use Q for this example, although Q now supports the new syntax which you should prefer):
function getStuffAsync(param) {
var d = Q.defer();
getStuff(param, function(err, data) {
if (err !== null) d.reject(err);
else d.resolve(data);
});
return d.promise;
}
In general, you should not promisify things manually too much, most promise libraries that were designed with Node in mind as well as native promises in Node 8+ have a built in method for promisifying nodebacks. For example
var getStuffAsync = Promise.promisify(getStuff); // Bluebird
var getStuffAsync = Q.denodeify(getStuff); // Q
var getStuffAsync = util.promisify(getStuff); // Native promises, node only
4. A whole library with node style callbacks:
There is no golden rule here, you promisify them one by one. However, some promise implementations allow you to do this in bulk, for example in Bluebird, converting a nodeback API to a promise API is as simple as:
Promise.promisifyAll(API);
Or with native promises in Node:
const { promisify } = require('util');
const promiseAPI = Object.entries(API).map(([key, v]) => ({key, fn: promisify(v)}))
.reduce((o, p) => Object.assign(o, {[p.key]: p.fn}), {});
Notes:
- Of course, when you are in a
.then
handler you do not need to promisify things. Returning a promise from a.then
handler will resolve or reject with that promise's value. Throwing from a.then
handler is also good practice and will reject the promise - this is the famous promise throw safety. - In an actual
onload
case, you should useaddEventListener
rather thanonX
.
Solution 2
Today, I can use Promise
in Node.js
as a plain Javascript method.
A simple and basic example to Promise
(with KISS way):
Plain Javascript Async API code:
function divisionAPI (number, divider, successCallback, errorCallback) {
if (divider == 0) {
return errorCallback( new Error("Division by zero") )
}
successCallback( number / divider )
}
Promise
Javascript Async API code:
function divisionAPI (number, divider) {
return new Promise(function (fulfilled, rejected) {
if (divider == 0) {
return rejected( new Error("Division by zero") )
}
fulfilled( number / divider )
})
}
(I recommend visiting this beautiful source)
Also Promise
can be used with together async\await
in ES7
to make the program flow wait for a fullfiled
result like the following:
function getName () {
return new Promise(function (fulfilled, rejected) {
var name = "John Doe";
// wait 3000 milliseconds before calling fulfilled() method
setTimeout (
function() {
fulfilled( name )
},
3000
)
})
}
async function foo () {
var name = await getName(); // awaits for a fulfilled result!
console.log(name); // the console writes "John Doe" after 3000 milliseconds
}
foo() // calling the foo() method to run the code
Another usage with the same code by using .then()
method
function getName () {
return new Promise(function (fulfilled, rejected) {
var name = "John Doe";
// wait 3000 milliseconds before calling fulfilled() method
setTimeout (
function() {
fulfilled( name )
},
3000
)
})
}
// the console writes "John Doe" after 3000 milliseconds
getName().then(function(name){ console.log(name) })
Promise
can also be used on any platform that is based on Node.js like react-native
.
Bonus: An hybrid method
(The callback method is assumed to have two parameters as error and result)
function divisionAPI (number, divider, callback) {
return new Promise(function (fulfilled, rejected) {
if (divider == 0) {
let error = new Error("Division by zero")
callback && callback( error )
return rejected( error )
}
let result = number / divider
callback && callback( null, result )
fulfilled( result )
})
}
The above method can respond result for old fashion callback and Promise usages.
Hope this helps.
Solution 3
Before converting a function as promise In Node.JS
var request = require('request'); //http wrapped module
function requestWrapper(url, callback) {
request.get(url, function (err, response) {
if (err) {
callback(err);
}else{
callback(null, response);
}
})
}
requestWrapper(url, function (err, response) {
console.log(err, response)
})
After Converting It
var request = require('request');
function requestWrapper(url) {
return new Promise(function (resolve, reject) { //returning promise
request.get(url, function (err, response) {
if (err) {
reject(err); //promise reject
}else{
resolve(response); //promise resolve
}
})
})
}
requestWrapper('http://localhost:8080/promise_request/1').then(function(response){
console.log(response) //resolve callback(success)
}).catch(function(error){
console.log(error) //reject callback(failure)
})
Incase you need to handle multiple request
var allRequests = [];
allRequests.push(requestWrapper('http://localhost:8080/promise_request/1'))
allRequests.push(requestWrapper('http://localhost:8080/promise_request/2'))
allRequests.push(requestWrapper('http://localhost:8080/promise_request/5'))
Promise.all(allRequests).then(function (results) {
console.log(results);//result will be array which contains each promise response
}).catch(function (err) {
console.log(err)
});
Solution 4
I don't think the window.onload
suggestion by @Benjamin will work all the time, as it doesn't detect whether it is called after the load. I have been bitten by that many times. Here is a version which should always work:
function promiseDOMready() {
return new Promise(function(resolve) {
if (document.readyState === "complete") return resolve();
document.addEventListener("DOMContentLoaded", resolve);
});
}
promiseDOMready().then(initOnLoad);
Solution 5
Node.js 8.0.0 includes a new util.promisify()
API that allows standard Node.js callback style APIs to be wrapped in a function that returns a Promise. An example use of util.promisify()
is shown below.
const fs = require('fs');
const util = require('util');
const readFile = util.promisify(fs.readFile);
readFile('/some/file')
.then((data) => { /* ... */ })
.catch((err) => { /* ... */ });
Benjamin Gruenbaum
Hi, I'm Benjamin 👋 You can find me here or if you need to reach me. At my day job I work at Microsoft on JavaScript development infrastructure in WiCD. Before that I was in Testim.io working on automating test automation and empowering QA developers Before that I worked on distributed algorithms and platforms for the webrtc based Peer5 P2P CDN, before that I wrote ran the core dev team at TipRanks writing csharp and javascript. I also do a bit of open source, here are some projects I am involved with: Node.js node.js platform - core collaborator. Bluebird bluebird core team member and maintainer. MobX mobx core team. Sinon.JS sinon.js team member. If you want to get involved in Node.js (at any capacity, no experience required) please do reach out. I promise you don't need perfect English, l33t coding skills or to be a "bro" to fit in (but those are welcome too). My email is written in the node home page. If you have an interesting use case for async-iterators/generators in Node.js - we're interested in talking in particular :) I have gold tags in promise javascript and a few others because I've spent a year answering as many promises questions as I could back then. If you're building something cool with promises please don't hesitate to reach out. I hereby release any code, test or multimedia content written in any answer and/or question by me in StackOverflow and anywhere else in the Stack Exchange network as public domain. No acknowledgement is required (although it is appreciated).
Updated on July 08, 2022Comments
-
Benjamin Gruenbaum almost 2 years
I want to work with promises but I have a callback API in a format like:
1. DOM load or other one time event:
window.onload; // set to callback ... window.onload = function() { };
2. Plain callback:
function request(onChangeHandler) { ... } request(function() { // change happened ... });
3. Node style callback ("nodeback"):
function getStuff(dat, callback) { ... } getStuff("dataParam", function(err, data) { ... })
4. A whole library with node style callbacks:
API; API.one(function(err, data) { API.two(function(err, data2) { API.three(function(err, data3) { ... }); }); });
How do I work with the API in promises, how do I "promisify" it?
-
Roamer-1888 about 10 yearsBenjamin, I accepted your invitation to edit and added a further jQuery example to case 2. It will need peer reviewing before it appears. Hope you like it.
-
Benjamin Gruenbaum about 10 years@Roamer-1888 it got rejected since I didn't see and accept it in time. For what it's worth I don't think the addition is too relevant although useful.
-
Roamer-1888 about 10 yearsBenjamin, whether or not
resolve()
andreject()
are written to be reusable, I venture that my suggested edit is relevant because it offers a jQuery example of the form$.Deferred(fn)
, which is otherwise lacking. If only one jQuery example is included, then I suggest that it should be of this form rather thanvar d = $.Deferred();
etc. as people should be encouraged to use the oft neglected$.Deferred(fn)
form, plus, in an answer like this, it puts jQuery more on a par with libs that use the Revealing Constructor Pattern. -
Benjamin Gruenbaum about 10 yearsHeh, to be 100% fair I didn't know jQuery let you do
$.Deferred(fn)
, if you edit that in instead of the existing example in the next 15 minutes I'm sure I can try to approve it on time :) -
Roamer-1888 about 10 yearsBenjamin, sorry I missed your 15 minute deadline but will try to catch you online soon. I'm sort of pleased my earlier edit wasn't accepted as I've had a chance to amend it to something better. It will need to be an addition, not a replacement.
-
fraxture over 9 yearsWhat are you referring to when you write "modern promise implementation"? What are you including to be able to use the
Promise
constructor? -
Benjamin Gruenbaum over 9 years@fraxture pretty much every implementation written after the Promises/A+ spec and the consteuctor spec was born or was altered because of it to match it - these are most promises we know : Q, Bluebird, When, RSVP, $q (since 1.3), native promises, jQuery starting with the next version and so on.
-
fraxture over 9 years@BenjaminGruenbaum: got ya. But what do I need to include to use the Promise constructor? Installing Q with npm and then requring it did not work...
-
Benjamin Gruenbaum over 9 yearsWith Q it's called Q.Promise - the API docs of Q are good and cover this.
-
fraxture over 9 yearsThe answer was that I needed to
npm install promise --save
and thenvar Promise = require('promise')
in order to be able tonew Promise
. -
Benjamin Gruenbaum over 9 yearsDon't use that library - use Bluebied instead.
-
Bergi about 9 yearsThe canonical answer already mentions
Q.denodeify
. Do we need to emphasize library helpers? -
Alnitak over 8 yearsshouldn't the "already complete" branch use
setTimeout(resolve, 0)
(orsetImmediate
, if available) to ensure that it's called asynchronously? -
Ed Sykes over 8 yearsi found this useful as a google about promisifying in Q leads here
-
velop about 8 yearsWhat happens if my onX event can happen multiple times. Can this also promisified?
-
Benjamin Gruenbaum about 8 yearsNo, if a callback happens multiple times it should not be promisified, promises are for one time things. For things that happen multiple times the easiest thing would be to use an event emitter - more advanced patterns like async iterators (iterators of promises) or observables (push object streams) exist. Promises are only for one time things.
-
user1164937 over 7 yearsI have a question about number 3 with nested callbacks. How come I can't simply call
reject/resolve
? It seems that at least in my case, I have to return them. -
Jeff Bowman over 7 years@Alnitak Calling
resolve
synchronously is fine. The Promise'sthen
handlers are guaranteed by the framework to be called asynchronously, regardless of whetherresolve
is called synchronously. -
Akansh over 7 years@BenjaminGruenbaum I want to ask regarding the 3rd heading promisify method, though it converts a callback to promise but is it possible to handle error exactly where I am making it a promise?
-
hitautodestruct over 7 yearsIt seems that this answer included everything except the actual usage of a promisified function. I added an example of the load functions use after it was promisified.
-
Bruno almost 7 yearsThis is a great answer. You may want to update it by mentioning also
util.promisify
, that Node.js is going to add to its core starting from RC 8.0.0. Its working it's not much different from BluebirdPromise.promisify
, but has the advantage of not requiring additional dependencies, in case you just want native Promise. I've written a blog post about util.promisify for anyone who want read more on the topic. -
Benjamin Gruenbaum almost 7 yearsHey, I (OP) actually suggested
util.promisify
twice (back in 2014 when this question was written, and a few months ago - which I pushed for as a core member of Node and is the current version we have in Node). Since it is not yet publicly available - I did not add it to this answer yet. We would deeply appreciate usage feedback though and getting to know what some pitfalls are in order to have better docs for the release :) -
Benjamin Gruenbaum almost 7 yearsIn addition, you might want to discuss the custom flag for promisifying with
util.promisify
in your blog post :) -
Bruno almost 7 years@BenjaminGruenbaum Do you mean the fact that using the
util.promisify.custom
symbol it is possible to override the result of util.promisify? To be honest this was an intentional miss, cause I'm not yet able to find a useful use case. Perhaps you can give me some inputs? -
Benjamin Gruenbaum almost 7 yearsSure, consider APIs like
fs.exists
or APIs that do not follow the Node convention - a bluebirdPromise.promisify
would get them wrong, bututil.promisify
gets them right. -
Benjamin Gruenbaum almost 7 yearsThere are already two answers describing this, why post a third one?
-
Gian Marco almost 7 yearsJust because that version of node is now released, and I've reported "official" feature description and link.
-
Benjamin Gruenbaum over 6 yearsWhat advantage does this have over native promisify or over the answers above?
-
loretoparisi over 6 yearsWhat do you mean for native promisify?
-
Benjamin Gruenbaum over 6 years
-
loretoparisi over 6 yearsah yes of course :). Just and example to show the basic idea. In fact you can see how even the native one requires that the function signature must some defined like
(err, value) => ...
or you must define a custom one (see Custom promisified functions). Thank you good catcha. -
Dmitri Zaitsev about 6 yearsThese do not seem to show how to convert to promises.
-
robe007 almost 6 years@BenjaminGruenbaum A few days ago, I sent an edit propose to you last code:
const promiseAPI = Object.keys(API).map(key => {return {key, fn:util.promisify(API[key])} }).reduce((o, p) => Object.assign(o, {[p.key] : p.fn}), {});
Why did you rejected? -
Benjamin Gruenbaum almost 6 years@robe007 probably just butter fingers - sorry! I edited it in now.
-
robe007 almost 6 years@BenjaminGruenbaum Please, see it again, your code still wrong. Look on my edit proposal few days ago.
-
Benjamin Gruenbaum almost 6 years@robe007 I did - I think the way I fixed it works - there are two ways to return objects from arrow functions: either adding a return to the block body
x => { return {}}
or to mark it as an expressionx => ({})
- both are valid and work. Maybe I'm still missing your point? -
robe007 almost 6 years@BenjaminGruenbaum Yes I know my friend, but you are missing to close the curly bracket in the returned object
{key, fn: util.promisify(API[key])}
from yourmap
. You see it? -
robe007 almost 6 years@BenjaminGruenbaum I have sent another edit proposal again to your last modification.
-
Benjamin Gruenbaum over 5 yearsHey, I'm not sure what this adds to existing answers (maybe clarify?). Also, there is no need for the try/catch inside the promise constructor (it does this automatically for you). It's also unclear what functions this works for (that call the callback with a single argument on success? How are errors handled?)
-
Benjamin Gruenbaum about 5 yearsThat's not a promise, it doesn't chain, deal with errors thrown in the callback or accept a second parameter in then...
-
Patrick Roberts almost 5 years@loretoparisi FYI,
var P = function (fn, ...args) { return new Promise((resolve, reject) => fn.call(this, ...args, (error, result) => error ? reject(error) : resolve(result))); };
would do the same thing as yours and it's a lot simpler. -
jameshfisher over 3 yearsThat
load
implementation looks unreliable: (1) it overridesonload
instead of usingaddEventListener
; (2) it will never resolve if theload
event has already happened -
Benjamin Gruenbaum over 3 yearsYes that has been discussed see stackoverflow.com/a/27935772/1348195 :)
-
Lucio Mollinedo over 2 years@BenjaminGruenbaum I upvoted this because it was the less 'cluttered' and effective one. The one at the top has so many other things that the answer gets lost.
-
Philip Stratford over 2 yearsI'm trying to use this, but if I call
promisify(fn, arg1, arg2).then(() => { alert("Done!"); });
the alert is never fired. Would you expect this to work? -
Josiah Nyarega over 2 yearsThanks, @Philip Stratford for the question. The
promisify
is used to convert a function with a callback into a promise. I will update my answer to explain this. -
Josiah Nyarega over 2 yearsI will be happy to hear any suggestions on this solution, cc @Philip Stratford. Thank you