In this guide you will learn how to use Node’s to promisify your own functions. This utility function was included in NodeJS version 8. If you plan to follow along with this guide you’ll need to install the latest version. As an added bonus I also show you how to use with and . util.promisify promisify await async TLDR; converts a regular function into an async function, i.e. a function that returns a promise util.promisify The function passed to must follow the NodeJS callback style. The function must pass a callback as the last parameter, and the callback must be the take the following parameters in the following order: util.promisify (err, value) => { /* … */ } Promisified functions can be used with and to help avoid messy promise chains and introduce a cleaner, saner, way to do asynchronous programming. await async What does util.promisify do? The official node documentation says: Takes a function following the common Node.js callback style, i.e. taking a callback as the last argument, and returns a version that returns promises. (err, value) => ... And … assumes that is a function taking a callback as its final argument in all cases, and the returned function will result in undefined behaviour if it does not. promisify(original) original So basically it’s a utility function that takes a regular function and converts it to a function that returns a promise/s. The function passed to has to follow a couple of conventions: util.promisify The final parameter of the function passed to must be a callback. promisify The callback must follow Node’s callback style. Here is an example of a valid function: For anyone unfamiliar with the syntax I’m using . I also use the . Note: ES6 Airbnb style guide To demonstrate how works lets start by creating a regular function that performs a task over a long period of time. We will then convert this function to a promise. util.promisify Creating a Regular Function Below I have a function called . Its purpose is to make you wait for an unknown period of time: wait For demonstration purposes I’ve wrote the function to wait for an unknown period of time. It does this by using to call an anonymous function every number of seconds and compares the number to a set of values to decide whether to continue waiting, or to stop: setInterval x If the number is above the function will stop running and the callback function will be called. 0.95 If the number is less than an error will be passed to the callback function. 0.01 And finally, if the random number is within range a message will be printed to STDOUT. NodeJS Callback Style expects a function that conforms to NodeJS’s callback style. To learn more about Node’s callback style read this article: util.promisify The Node.js Way — Understanding Error-First Callbacks In the function you will notice I used the callback is used in 2 different ways. When the random number was greater than this is considered a success and the wait is over. Thus we can call the callback like so: wait 0.95 callback(null, ‘Congratulations, you have finished waiting.’); Here I passed to the first parameter. No error occurred. Nothing to report. Using the second parameter I pass some data that is made available in the callback, or promise chain. null When the function failed (in this case when the random number is below ) an error message is passed to the first parameter. The second parameter is set to . wait 0.01 null callback(‘Could not wait any longer!’, null); This follows Node’s callback style. Usage The function is called like so: the function expects 2 parameters. The first is the number of milliseconds to wait before calls the callback function. The second parameter is a callback. setInterval Notice how I’m checking for an error: … if is the callback continues. Otherwise an exception is thrown. if (err) throw new Error(err) err null Test Running Running the above code produces the following output on success: … and the following output on error: We confirm the function does as expected. Next we will turn it into a promise. Promisify Regular Functions Here’s where the magic happens. Now we have an ordinary function I can demonstrate how to turn into a function that returns a promise. This is surprisingly easy … That’s it. In 2 lines of code I converted the function to a promise. Line 7 to 9 show how to use the new promise. You will agree it’s much cleaner and easier to read. Introducing Async and Await Wait, we’re not finished yet. I’ve got some more juicy goodness to share with you. Node 8 also comes with and support. How freakin’ cool! async await Instead of using promise chaining (which can get very messy very quickly) you can write your code in a normal procedural style like so: No more promise chains :) For more information on async/await I highly recommend the following article: https://blog.risingstack.com/mastering-async-await-in-nodejs/ 😊 P.S. If you’re on Twitter give me a follow. I often write articles on software development, and security: https://twitter.com/JamesJefferyUK
