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

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.