Categories
Node.js Quick Tips Quick Tips

Take advantage of promise-based APIs in Node.js

2 min read

Last updated: March 29, 2022

This blog post is part of the series What’s new in Node.js core?

You can use util.promisify() to wrap callback-based APIs in Node.js core. But did you know that Node.js provides several promise-based APIs too? You can use them with async / await, no wrapping needed!

There are some newer promise-based APIs in Node.js core:

To see which Node.js Core APIs might have promise-based alternatives developed in future, take a look at the Core Promise Initiative status GitHub issue.

There are two other promise-based APIs that you’ll find in Node.js core (they’ve been there since v10.x):

timers/promises module

/**
 * `timers/promises` module
 *
 * Added: v15.0.0
 * Graduated from experimental: v16.0.0
 * 
 * Can also be loaded with `require()`.
 */

import { setTimeout } from "timers/promises";

const delayedValue = await setTimeout(5000, "some value");

console.log(delayedValue);

Support in Node.js

stream/promises module

/**
 * `stream/promises` module
 *
 * Added: v15.0.0
 *
 * Can also be loaded with `require()`.
 */

import { pipeline } from "stream/promises";

import fs from "fs";
import zlib from "zlib";

try {
	await pipeline(
		fs.createReadStream("archive.tar"),
		zlib.createGzip(),
		fs.createWriteStream("archive.tar.gz")
	);

	console.log("tarred and gzipped file created from tar file");
} catch (error) {
	console.error(error);
}

Support in Node.js

readline/promises module

This API is the candidate to replace the callback-based readline API. It’s been added as part of the Node.js Core Promise Initiative.

Contributed by Antoine du Hamel

import * as readline from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";

const rl = readline.createInterface({ input, output });

const answer = await rl.question("What is the meaning of life? ");

console.log(`Alright, the meaning of life is ${answer}!`);

rl.close();

View code example on GitHub

Support in Node.js

When can you use it in production?

Will be in v18 — initial release 19 Apr 2022, Active LTS starts 25 Oct 2022.

Note: The readline/promises API currently has an Experimental stability status, so the API may change.

Related links

fs/promises module

/**
 * `fs/promises` module
 *
 * Added: v10.0.0 (changed to `fs.promises` in v10.1.0)
 * Exposed as `fs/promises`: v14.0.0
 * 
 * Can also be loaded with `require()`.
 */

import fs from "fs/promises";

const fileContents = await fs.readFile("file.txt", { encoding: "utf-8" });

console.log(fileContents);

Support in Node.js

dns/promises module

/**
 * `dns/promises` module
 *
 * Added: v10.6.0 (as `dns.promises`)
 * Exposed as `dns/promises`: v15.0.0
 * 
 * Can also be loaded with `require()`.
 */

 import dns from "dns/promises";

 const resolver = new dns.Resolver();
 
 const addresses = await resolver.resolve4("nodejs.org");
 
 console.log(addresses);

Support in Node.js