Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Concepts and Pitfalls

Callback, promise and sync APIs in Node.js

Node.js core modules often offer three flavors of the same function: callback, promise and synchronous. Learn how they differ, when to use each and how to convert.

Many Node.js core functions come in up to three flavors that do the same job. Reading a file is the classic example: fs.readFile() takes a callback, fs.promises.readFile() (also available as node:fs/promises) returns a promise, and fs.readFileSync() blocks and returns the data directly.

The flavors differ in how they report errors, what they do to the event loop, and how they compose. Picking the right one is mostly a question of context: use promises with async/await for ordinary application code, synchronous calls for startup and scripts, and callbacks where an API only offers them.

NODE
import { readFile } from 'node:fs/promises';
const text = await readFile('notes.txt', 'utf8');

Try it

Node.js One job, three flavors

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 Converting between flavors

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.

How the flavors differ

Aspect Synchronous Callback Promise
Names readFileSync readFile fsPromises.readFile
Result Return value Second callback argument Promise value
Errors throw (use try/catch) First argument Rejection (use catch or try/await)
Event loop Blocked for the duration Free (pool or kernel does the work) Free
Ordering Immediate Later, from the loop Later, as a microtask after the work
Composition Plain code Nesting await, Promise.all, race

Where the promise versions live

  • node:fs/promises (and fs.promises), node:dns/promises, node:timers/promises, node:stream/promises, node:readline/promises, node:stream/consumers.
  • Selected modules return promises from specific functions: crypto.subtle.*, fetch(), events.once(), child_process through util.promisify(execFile).
  • Some modules have no promise flavor (http.get, sockets); they use events. Wrap them with once() or a small promise.

Usage notes

  • Same name, same arguments, different return. A promise function takes the same arguments as the callback function minus the callback, but a few differ (for example fs.promises.open returns a FileHandle you must close).
  • Do not mix styles in one function. Returning a promise and also accepting a callback invites double handling.
  • Sync calls are fine in startup code, CLI scripts and build tools, and wrong in request handlers.
  • await does not make work parallel. Start several promises first and then await Promise.all([...]) when the jobs are independent.
  • Unhandled rejections end the process by default in current Node versions. Every promise chain needs a catch or an await inside try.
  • Error shape is the same across flavors: an Error with code, errno, syscall and path for system failures.
  • Prefer util.promisify over hand-written wrappers for callbacks that follow the error-first convention.
  • Performance: promise versions add small overhead per call but make no difference for I/O-bound work; avoid sync versions when many requests are in flight.