Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 133 ยท File System

Sync, Callback and Promise APIs

Compare the three Node.js fs API styles - synchronous, callback and promise - learn when readFileSync is fine, how promisify bridges them, and why fs.existsSync followed by an action is a race condition.

Open the Node.js documentation for fs and you will find every operation three times. fs.readFileSync(path) blocks and returns the result. fs.readFile(path, callback) returns immediately and calls you back later. fs.promises.readFile(path), also importable as node:fs/promises, returns a promise. All three do the same work on the file system. They differ in how they hand you the result and, more importantly, in what they do to the rest of your program while the work happens.

This lesson explains the difference using the event loop, shows all three side by side, gives rules for choosing one, shows how util.promisify converts old callback code, and finishes with a classic mistake: checking whether a file exists before using it. If you want a refresher on the single-threaded model first, read How Node.js Works and The Event Loop.

The same job, three styles

Here is one task, "read a file and print it", written in all three styles. The file is created first so the example is self-contained.

Node.js Three ways to read one file

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.

Look at the order of the lines. The synchronous result prints first, because the call does not return until the file is read. The promise result comes after the await. The callback result arrives some time later, and whether it prints before or after the promise line depends on how quickly each read finishes, so the order of those two lines is not guaranteed. The key observations:

  • Sync gives you an ordinary value (or throws). The code reads top to bottom, but the whole process is stuck during the call.
  • Callback style follows Node.js's error-first convention: the first argument is null on success or an Error, the rest are results. You must check it.
  • Promise style gives you async/await, try/catch and Promise.all, and is the recommended style for new code.

What "blocking" means

Node.js runs your JavaScript on a single thread. A synchronous file call keeps that thread busy until the operating system answers. Nothing else can run during that time: no timers fire, no incoming HTTP requests are accepted, no other callbacks run. The callback and promise versions hand the file work to a pool of background threads (libuv's thread pool), and your thread continues with other work until the result is ready.

We can prove the ordering without measuring any time. A timer scheduled with setTimeout(..., 0) can only fire when the main thread is free:

Node.js Sync blocks the loop, async does not

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.

In round 1 the line after readFileSync prints before the timer, because the timer had to wait until the script yielded. In round 2 the main thread stays free while the file is read in the background, so the zero-delay timer usually fires before file read is printed; the exact interleaving of a timer and a file read depends on how fast the disk answers, so never write code that relies on it.

For a single read on a developer's laptop the blocking time is microseconds. It becomes a problem in a server, where "stuck for 5 ms" is multiplied by every request and every slow disk (network drives and busy hosts can take far longer). That leads to the rules of thumb below.

When is sync fine?

Synchronous file APIs are not evil. They are the right tool when nothing else needs the thread:

  • Startup code. Reading configuration, certificates, templates or a schema before the server begins listening. Nobody is waiting, and the code is simpler. (In ES modules you could also use top-level await with the promise API.)
  • Command-line tools and scripts. A script that reads a file, transforms it and writes the result gains nothing from concurrency.
  • Tests and build tooling.
  • Inside process.on('exit'). Only synchronous work is possible in an exit handler.

Avoid them in request handlers, event handlers and anything that runs repeatedly in a server. A rule professionals use: sync calls are allowed before the app starts serving, forbidden after.

Style Blocks the loop Error handling Best for
fs.xxxSync Yes try/catch Startup, scripts, exit handlers
fs.xxx(โ€ฆ, callback) No First callback argument Legacy code, simple event-style code
fs.promises.xxx No try/catch with await Almost everything else

The promise API is not "faster" than the callback API. Both use the same thread pool underneath. The promise version just gives you better code. The synchronous version is often the fastest for a single call (no thread hand-off), but only because it ignores everybody else.

Error handling in each style

The three styles report the same errors, with the same code property, in three different ways. Notice what happens when you forget to handle them.

Node.js The same ENOENT in three styles

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.

The nested callbacks at the end are the famous "callback pyramid". The same logic with promises is a flat list of three await lines. The history of that problem and the ways around it are in Callbacks and Error-First Style.

A thrown error inside a callback is not caught by a try/catch around the call that registered it, because by the time the callback runs, the try block has long finished. This is the most common mistake when mixing styles.

Node.js try/catch cannot catch callback errors (fails on purpose)

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.

The output shows the try block finished without any error, and then the process dies with the uncaught error [Error: ENOENT: no such file or directory, open 'missing.txt'] (printed with the throw error; line of main.mjs above it) and exit code 1. With callbacks, you must deal with errors inside the callback; with promises and await, an ordinary try/catch works again.

Converting with util.promisify

Older libraries and your own older code may still use callbacks. util.promisify takes a function whose last parameter is an error-first callback and returns a version that gives a promise. Most built-in callback functions are already set up so this works.

Node.js promisify and callbackify

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.

You rarely need promisify for fs, because node:fs/promises already exists. It is still useful for third-party callback code. The module is described in The util Module.

The existsSync trap (TOCTOU)

A very common line of code looks sensible:

NODE
if (fs.existsSync('config.json')) {
  const text = fs.readFileSync('config.json', 'utf8'); // can still fail!
}

The check and the read are two separate steps. Between them, another process (or another part of your own program, or a user) can delete, rename or lock the file. This class of bug has a name: TOCTOU, "time of check to time of use". The check can only tell you that the file existed a moment ago, not that the next call will succeed. And you still need a try/catch for permission errors, a directory with that name, and so on, so the check adds nothing.

We can make the race visible by deleting the file ourselves between the check and the use:

Node.js A check that is already outdated

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.

The same race exists for "create the file if it is missing". Use the exclusive flag from the previous lesson ('wx') so the operating system does check-and-create in one atomic step. For directories, mkdir with { recursive: true } succeeds if the directory already exists. This makes the pattern "ensure the folder exists" safe.

There are legitimate uses of existsSync, for example choosing between two default config locations at startup, or in a tool where races are impossible. If you do use it, never rely on it for correctness or security.

Related API: fs.access(path, mode) checks permissions. It has the same TOCTOU problem and the documentation itself discourages using it before opening. Open the file and handle EACCES.

Everything above used paths: you name a file and Node opens, reads and closes it for you. Underneath, the operating system works with file descriptors, small integers that stand for an open file. The fs module exposes that level too, and you need it when you want to read or write at an exact position, force data to disk, or inspect the file system itself (links, permissions, timestamps).

fs.openSync(path, flags) returns a descriptor. The flag 'w+' means "read and write, create or empty the file", 'r' is read-only and 'a' appends. writeSync(fd, data, position) and readSync(fd, buffer, offset, length, position) take an explicit position in the file, so you can overwrite a few bytes in the middle without touching the rest. Every descriptor must be closed with closeSync; leaking descriptors eventually fails with EMFILE ("too many open files"). The promise API gives you the same thing as a FileHandle from fsp.open(), which you close with await handle.close().

Writing is a two-step story. When write returns, the data is usually in the operating system's cache, not yet on the disk. fsync(fd) asks the OS to flush the file and its metadata to the storage device, and fdatasync(fd) flushes the data and only the metadata needed to read it back, which is a little cheaper. Databases and any program that must survive a power cut (write the file, fsync, then rename it into place) call these; ordinary scripts do not need them.

Links come in two kinds. A hard link (link) is a second name for the same file contents: both names show the same nlink count and the data is freed only when the last name is removed. A symbolic link (symlink) is a tiny file that stores a path; readlink shows that stored path, lstat describes the link itself while stat follows it to the target, and realpath resolves every link on a path to the final location. A relative symlink target is resolved from the folder that contains the link, not from your current directory.

Node.js Descriptors, positions, links, permissions and times

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.

Read the first lines carefully: the text was HELLO WORLD, we overwrote four bytes at position 6, so the five bytes starting at 6 are nodeD. After ftruncate(fd, 5) only HELLO is left. chmod takes an octal mode (0o640 means owner read and write, group read, others nothing); only the lowest nine bits are permissions, which is why the example masks with 0o777. On Windows most permission bits are ignored. utimes(path, atime, mtime) sets the access and modification times, which build tools and sync tools use to decide what changed. access tests whether the current user may read, write or execute, but never use it as a guard before opening (see the existsSync trap): just open the file and handle the error. chown(path, uid, gid) changes the owner and needs privileges; it is mostly used by installers and container entry points.

To react to changes, fs.watch uses the operating system's notifications and is fast but differs between platforms (Working with Directories lists its caveats). fs.watchFile is the older fallback: it polls the file's stat at an interval and calls you with the current and previous Stats.

Node.js watchFile: polling for changes

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.

Polling is slower and wasteful on many files but behaves the same everywhere, including network drives. Always call unwatchFile, or the polling timer keeps the process alive.

Choosing and mixing styles

Do not mix styles in one flow. A function that sometimes calls back synchronously and sometimes asynchronously is a well-known trap (nicknamed "releasing Zalgo"): the caller cannot know in which order things run. If a function is asynchronous, make it always asynchronous.

The next example combines the three APIs in a realistic job: a startup step loads settings synchronously, then a server-like loop uses promises, with a small helper that keeps the code uniform.

Node.js Startup sync, runtime async

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.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What happens to the rest of your program while fs.readFileSync runs?

    Your JavaScript runs on one thread. A synchronous call occupies it completely, so timers and incoming requests have to wait.
  2. 2. Where is it generally acceptable to use readFileSync?

    Before the app serves traffic nobody is waiting on the event loop, so blocking is harmless and the code is simpler.
  3. 3. Why does try/catch around fs.readFile(path, callback) not catch a failure to read?

    The call only registers the callback. The error is delivered to the callback afterwards, so you must handle it there (or use the promise API).
  4. 4. What is wrong with 'if (fs.existsSync(p)) { read(p) }'?

    Check and use are separate steps. Try the operation and handle ENOENT instead.
  5. 5. What does util.promisify(fs.readFile) return?

    promisify wraps an error-first callback function and returns a version that gives a promise.

Summary

  • Every fs operation exists in three styles: synchronous (readFileSync), callback (readFile) and promise (node:fs/promises). The underlying work is the same.
  • Synchronous calls block the single JavaScript thread; callbacks and promises run the file work in background threads.
  • Use sync for startup code, scripts and exit handlers; use promises everywhere else. Avoid new callback code.
  • Errors surface as a thrown exception (sync), a rejected promise, or the first callback argument; try/catch does not catch errors in a callback.
  • util.promisify converts error-first callback functions; callbackify goes the other way.
  • Do not check with existsSync and then act: it is a TOCTOU race. Try the operation, handle ENOENT, and use 'wx' or mkdir -p for atomic creation.
  • Never mix always-sync and sometimes-async behaviour in one function.

Next: Directories, Stats and Watching