Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท util, assert and the Test Runner

Node.js util.promisify() function

Reference for util.promisify() in Node.js: turn error-first callback functions into promise-returning ones, custom promisify symbols, multiple results and pitfalls.

util.promisify(fn) takes a function that expects an error-first callback as its last argument and returns a new function that returns a promise instead. Call the new function with the same arguments, minus the callback, and await the result.

It exists for the large amount of older code, in Node's own core modules and in libraries, that was written before promises were common. Many core modules now also ship a promise API directly (fs/promises, timers/promises), and you should prefer those when they exist.

NODE
import { promisify } from "node:util";
import { readFile } from "node:fs";

const readFileAsync = promisify(readFile);
const text = await readFileAsync("notes.txt", "utf8");

Try it

Node.js Wrapping a callback function

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Custom promisify and methods

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
util.promisify(original: Function): Function
util.promisify.custom: symbol
Name Description
original A function whose last parameter is a callback (err, value) => void.
util.promisify.custom A well-known symbol (Symbol.for("nodejs.util.promisify.custom")). If original[util.promisify.custom] is a function, promisify() returns that function instead of wrapping.

Returns: a function that takes the original arguments (without the callback) and returns a Promise. The promise fulfills with the callback's second argument, or rejects with its first argument when that is truthy.

Errors / edge cases: promisify() throws ERR_INVALID_ARG_TYPE immediately if original is not a function. Errors thrown synchronously by the original function become rejections of the returned promise, not synchronous throws.

Usage notes

  • Only the first result survives. If the callback gets (err, a, b), the promise fulfills with a. To keep several values, define util.promisify.custom (Node does this for child_process.exec(), where the promise fulfills with { stdout, stderr }).
  • this is preserved from the call, not from where you took the function. promisify(obj.method) loses obj; bind first or wrap in an arrow function.
  • The callback must be last and must follow the (err, value) convention. Functions with different shapes, such as fs.exists() (which passes a single boolean) or APIs with separate success and failure callbacks, need a hand-written wrapper or a custom symbol.
  • Not for event-based or repeated callbacks. A promise settles once; a function that calls its callback many times is a poor fit.
  • Prefer built-in promise APIs. fs/promises, timers/promises, dns/promises and stream/promises are faster and better documented than promisified copies. util.promisify(setTimeout) works because setTimeout has a custom symbol, but timers/promises is the clearer choice.
  • Opposite direction: util.callbackify() turns a promise-returning function into a callback one.