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.
import { readFile } from 'node:fs/promises'; const text = await readFile('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.
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(andfs.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_processthroughutil.promisify(execFile). - Some modules have no promise flavor (
http.get, sockets); they use events. Wrap them withonce()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.openreturns aFileHandleyou 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.
awaitdoes not make work parallel. Start several promises first and thenawait Promise.all([...])when the jobs are independent.- Unhandled rejections end the process by default in current Node versions. Every promise chain needs a
catchor anawaitinsidetry. - Error shape is the same across flavors: an
Errorwithcode,errno,syscallandpathfor system failures. - Prefer
util.promisifyover 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.