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.
import { promisify } from "node:util"; import { readFile } from "node:fs"; const readFileAsync = promisify(readFile); const text = await readFileAsync("notes.txt", "utf8");
Try it
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.
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
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 witha. To keep several values, defineutil.promisify.custom(Node does this forchild_process.exec(), where the promise fulfills with{ stdout, stderr }). thisis preserved from the call, not from where you took the function.promisify(obj.method)losesobj; 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 asfs.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/promisesandstream/promisesare faster and better documented than promisified copies.util.promisify(setTimeout)works becausesetTimeouthas a custom symbol, buttimers/promisesis the clearer choice. - Opposite direction:
util.callbackify()turns a promise-returning function into a callback one.