Overview of Promise-Based APIs in Node.js

Node.js introduced async/await as a language feature in version 8.0.0. With async/await the development flow changed to use promises instead of callbacks. Since then, the Node.js team added promise-based APIs to Node’s core.

I’m continuously updating this overview of promise-based APIs in Node.js. New promise APIs in Node’s core will be added to the list.

last update: 3rd Nov 2021

Node.js Series Overview

  1. String Replace All Appearances
  2. Remove All Whitespace From a String in JavaScript
  3. Generate a Random ID or String in Node.js or JavaScript
  4. Remove Extra Spaces From a String in JavaScript or Node.js
  5. Remove Numbers From a String in JavaScript or Node.js
  6. Get the Part Before a Character in a String in JavaScript or Node.js
  7. Get the Part After a Character in a String in JavaScript or Node.js
  8. How to Check if a Value is a String in JavaScript or Node.js
  9. Check If a String Includes All Strings in JavaScript/Node.js/TypeScript
  10. Check if a Value is a String in JavaScript and Node.js
  11. Limit and Truncate a String to a Given Length in JavaScript and Node.js
  12. Split a String into a List of Characters in JavaScript and Node.js
  13. How to Generage a UUID in Node.js
  14. Reverse a String in JavaScript or Node.js
  15. Split a String into a List of Lines in JavaScript or Node.js
  16. Split a String into a List of Words in JavaScript or Node.js
  17. Detect if a String is in camelCase Format in Javascript or Node.js
  18. Check If a String Is in Lowercase in JavaScript or Node.js
  19. Check If a String is in Uppercase in JavaScript or Node.js
  20. Get the Part After First Occurrence in a String in JavaScript or Node.js
  21. Get the Part Before First Occurrence in a String in JavaScript or Node.js
  22. Get the Part Before Last Occurrence in a String in JavaScript or Node.js
  23. Get the Part After Last Occurrence in a String in JavaScript or Node.js
  24. How to Count Words in a File
  25. How to Shuffle the Characters of a String in JavaScript or Node.js
  26. Append Characters or Words to a String in JavaScript or Node.js
  27. Check if a String is Empty in JavaScript or Node.js
  28. Ensure a String Ends with a Given Character in JavaScript or Node.js
  29. Left-Trim Characters Off a String in JavaScript or Node.js
  30. Right-Trim Characters Off a String in JavaScript or Node.js
  31. Lowercase the First Character of a String in JavaScript or Node.js
  32. Uppercase the First Character of a String in JavaScript or Node.js
  33. Prepend Characters or Words to a String in JavaScript or Node.js
  34. Check if a String is a Number
  35. Convert a String to Buffer

Promise-APIs in Node.js

The Allrounder: util.promisify

When talking about promise APIs in Node.js we also need to mention util.promisify. The util.promisify function is available since Node.js v8.0.0 and creates an async function from a callback-based version.

util.promisify takes an error-first callback function (error, value) => {} as an argument and returns a function returning a promise:

import Fs from 'fs'  
import { promisify } from 'util'

const stat = promisify(Fs.stat)

try {  
  const stats = await stat(path)
  // do something with `stats`
} catch (error) {
  // handle the `error`
}

History

  • Added in Node.js v8.0.0

fs/promises

The fs/promise module in the Node.js core provides a comprehensive list of methods. Please find all promise-supporting methods of fs/promises in the table of contents of the Node.js docs. Here’s an example of how you can read a file using the promise-based readFile method:

import FS from 'fs/promise'  
// or use destructured imports
import { readFile } from 'fs/promises'

await FS.readFile(path)  
// or
await readFile(path)  

History

  • Node.js v14.0.0: also available as require('fs/promises')
  • Node.js v10.0.0: exposed as require('fs').promises

Alternatives

  • @supercharge/fs: an extended and async fs package providing a lot of convenience methods when interacting with the local file system

stream/promises

The stream/promises module provides two promise-supporting methods:
- finished: waits for a stream to finish reading, writing or an error occurs - pipeline: a method piping data between streams and also forwarding errors. It also cleans up properly (closing all streams) and throws any occurring error.

Here’s an example using both methods:

import Fs from 'fs'  
import Zlib from 'zlib'  
import { finished, pipeline } from 'stream/promises'

await pipeline(  
  Fs.createReadStream('archive.tar'),
  Zlib.createGzip(),
  Fs.createWriteStream('archive.tar.gz')
)

const rs = Fs.createReadStream('archive.tar')  
await finished(rs.resume())  

History

  • stream/promises was added in Node.js v15.0.0
  • v10.0.0: added pipeline and finished methods with callback support

timers/promises

The timers/promises was added in Node.js v15.0.0 as an experimental API. It graduated from experimental in Node.js v16.0.0. There are currently three promise-supporting methods available:
- setTimeout - setInterval - setImmediate

Here’s an example how to use the promise-based timers methods:

import {  
  setTimeout as delay,
  setInterval,
  setImmediate,
} from 'timers/promises'

await delay(500)

const res = await setImmediate('result')  
// 'result'

const interval = 100  
for await (const startTime of setInterval(interval, Date.now())) {  
  const now = Date.now()
  console.log(now)
  if ((now - startTime) > 1000)
    break
}

History

  • Node.js v16.0.0: graduated from experimental
  • timers/promises was added in Node.js v15.0.0

dns/promises

The promise-based APIs of the dns module was added in Node.js v10.6.0 and exposed via dns/promises in Node.js v15.0.0. The promise-based API of dns/promises has feature parity with the callback-based version of dns.

Please find all promise-supporting methods of dns/promises in the table of contents of the Node.js docs.

Here’s an example on how to use the promise-based DNS module:

const { Resolver } = require('dns/promises')

const resolver = new Resolver()  
resolver.setServers(['4.4.4.4'])

const addresses = await resolver.resolve4('example.org')  

History

  • Node.js v15.0.0: also available as require('dns/promises')
  • Node.js v10.6.0: added promise-based APIs exposed as require('dns').promises

Mentioned Resources

Explore the Library

Find interesting tutorials and solutions for your problems.