skip to content

Filesystem and Network I/O

The core modules that talk to the outside world: files and paths, TCP and UDP sockets, and the built-in HTTP server and client every framework sits on. Asked to see if you could work without one.

on this pageshow

explore

questions

24

In Node.js, how do you choose between the node:fs/promises, callback and Sync forms of a file operation, and when is a Sync call acceptable?

level: juniorimportance: must knowfreq 68%

answer

  1. three forms of one operation
  2. who waits: the thread or a callback
  3. threadpool behind the async forms
  4. startup and CLIs tolerate blocking

basics

~20 s

Node's fs offers its file operations in promise, callback and Sync forms. Default to node:fs/promises with await, keep callbacks for measured hot paths, and confine Sync calls to startup code and CLIs, because they block the event loop.

solid answer

~40 s

All three forms do the same system call; they differ in who waits. The promise form (`node:fs/promises`) and the callback form hand the work to libuv's threadpool and let the event loop keep serving other requests; the promise form reads best with `await` and `try/catch`, and the docs say the callback form is the one to prefer when maximal performance in time and memory is required. A Sync form such as `readFileSync` runs on the main thread and blocks the event loop until the disk answers, so every other request waits. That is fine where nothing else is waiting: reading config once before `server.listen()`, a build script, a CLI. It is never fine inside a request handler, however small the file.

code

javascript · 17 lines
javascript
import { readFileSync } from 'node:fs';
import { readFile } from 'node:fs/promises';
import { createServer } from 'node:http';

// Startup: nothing else is running yet, so blocking is harmless.
const config = JSON.parse(readFileSync(new URL('./config.json', import.meta.url), 'utf8'));

createServer(async (req, res) => {
  try {
    // Request time: never block the event loop.
    const body = await readFile(new URL('./banner.txt', import.meta.url), 'utf8');
    res.end(body);
  } catch (err) {
    res.statusCode = err.code === 'ENOENT' ? 404 : 500;
    res.end();
  }
}).listen(config.port);

go deeper

for a junior

Recall the three forms, how each reports errors, and the one rule: Sync calls block the event loop, so they belong at startup and in CLIs only.

for a middle

Explain that the promise and callback forms both run on libuv's threadpool, why that pool can still become a bottleneck, and why concurrent writes to one file need serialising.

for a senior

Show the judgment: spot a Sync call hiding in request-time code, explain why disk latency rather than file size sets its cost, and bound file concurrency under load.

for a principal

Frame it as a team default: fs/promises everywhere, callbacks only where a profile justifies them, and a lint or review rule that keeps Sync calls out of request paths.

## Three forms of the same operation Almost every operation in Node's `node:fs` module comes in three shapes (a few, such as `fs.watch`, have no Sync form). They reach the same operating-system call; the difference is **who waits for it** and **how errors arrive**. | Form | Import | How it reports | Where the work runs | |---|---|---|---| | Promise | `import { readFile } from 'node:fs/promises'` | returns a promise; rejects on error | libuv's threadpool | | Callback | `import { readFile } from 'node:fs'` | calls `(err, result)` last | libuv's threadpool | | Sync | `import { readFileSync } from 'node:fs'` | returns the value; **throws** on error | the main JavaScript thread | The **event loop** is the single thread that runs your JavaScript and dispatches every callback, timer and incoming request. Anything that occupies that thread delays everything else in the process. ## What the async forms actually do Both the callback API and the promise API hand the file operation to **libuv's threadpool**, a small set of background threads (four unless `UV_THREADPOOL_SIZE` says otherwise). The event loop carries on; when the thread finishes, the callback runs or the promise settles. - The two async forms differ in ergonomics more than in mechanism. `fs/promises` composes with `await`, `Promise.all` and `try/catch`; the callback form costs a little less per call, which is why the fs documentation recommends it when maximal performance is required. - Neither form serialises access. The docs warn that these operations are **not synchronized or threadsafe**: two concurrent writes to the same file can interleave and corrupt it, so serialise writes per file yourself. - "Off the main thread" does not mean free. The threadpool is shared with `dns.lookup`, `crypto` and `zlib`, so a burst of large reads can queue behind other work. How that pool is scheduled is covered with the event loop's phases. - Whole-file reads are deliberately polite. The docs describe `fs.readFile()` reading one chunk at a time (512 KiB per read for a regular file, 64 KiB when the size is unknown) so the event loop turns between chunks; that makes a single read slower, and the docs point to `fs.read()` when raw speed matters. Large files belong in a stream instead, which the streams material covers. ## What a Sync call costs a server A Sync form does the system call on the main thread. While it waits for the disk: - no other request is parsed or answered, - no timer fires and no promise callback runs, - the latency of every request in flight grows by the duration of the call. The duration depends on the disk, the page cache and the file system, not only on the file size. A small file on a network mount or a cold cache can take far longer than it did on a laptop. Measuring that delay is covered with event-loop blocking; the point here is choosing the right form in the first place. ## When a Sync call is the right call Blocking is only harmful when something else is waiting. Sync forms are reasonable when: 1. **Startup, before the server listens.** Reading a config file or a TLS certificate before `server.listen()` blocks nobody, and failing fast with a thrown error is what you want. 2. **Command-line tools and build scripts.** A CLI that does one thing at a time gains nothing from async plumbing; `readdirSync` and `writeFileSync` keep the code linear. 3. **Places where async work cannot finish**, such as a `process.on('exit')` listener, which the process documentation says must only perform synchronous operations. They are wrong in request handlers, message consumers, timers and anything else that runs while the service is taking traffic. Even the startup exception is a convenience rather than a necessity. In an ES module, top-level `await` lets `const config = JSON.parse(await readFile(file, 'utf8'))` read as linearly as the Sync form, so many teams simply use `fs/promises` everywhere and never have to argue about where the line falls. ## Errors in each form - **Promise:** the promise rejects with an `Error` carrying `code` (`'ENOENT'`, `'EACCES'`); catch it with `try/catch` around `await`. - **Callback:** the first argument is the error, `null` or `undefined` on success; an unchecked `err` is silently ignored. - **Sync:** the call throws; an uncaught throw in a handler propagates like any exception. Wrapping `readFileSync` in an `async` function changes none of this: the function still runs the blocking call on the main thread before its promise settles. ## Picking in practice 1. Write new service code against `node:fs/promises` with `await`. 2. Keep the callback form for a hot path you have profiled, or for code already written in that style. 3. Use Sync forms at startup and in CLIs, and make a Sync call inside request-time code a review blocker. 4. When reading many files, bound the concurrency so a burst does not monopolise the threadpool.

  • Is the callback form of node:fs faster than node:fs/promises, and should that change your default?
    Slightly. The fs documentation says the callback APIs are preferable when maximal performance, in both execution time and memory allocation, is required, because they skip promise allocation. Both run on the same threadpool, so the disk dominates. Default to `fs/promises` for readability and reach for callbacks only on a hot path a profile has pointed at.
  • If fs/promises never blocks the event loop, can a burst of readFile calls still slow a Node server down?
    Yes. Every async fs call takes a threadpool thread, four by default, shared with `dns.lookup`, `crypto` and `zlib`. A thousand concurrent `readFile` calls queue there and delay unrelated work, and each one holds the whole file in memory. Bound the concurrency, or stream large files.

  • fs/promises runs the file I/O on the main thread, just later
  • The callback and promise forms use different I/O mechanisms underneath
  • Wrapping readFileSync in an async function makes it non-blocking
  • A Sync call in a request handler is harmless when the file is small
  • Sync forms report failure through a returned error value instead of throwing
open as a page

In a Node.js http.createServer handler, what are the req and res objects, and how do you read a JSON request body without a framework?

level: juniorimportance: must knowfreq 62%

basics

~10 s

req is an http.IncomingMessage: parsed headers plus a Readable stream of body bytes. res is an http.ServerResponse, a Writable. You collect the body chunks yourself, parse them, and must call res.end().

open as a page

In Node.js, what do http.Agent's keepAlive and maxSockets options control, and what does http.globalAgent use by default?

level: middleimportance: must knowfreq 60%

basics

~20 s

keepAlive decides whether an http.Agent pools idle sockets for reuse; maxSockets caps concurrent sockets per origin and queues the rest. new http.Agent() defaults to keepAlive false and maxSockets Infinity; http.globalAgent enables keep-alive with a 5-second timeout.

open as a page

In Node.js 24, how does the global fetch() differ from http.request() in its implementation, connection pooling and configuration?

level: middleimportance: must knowfreq 65%

basics

~20 s

Node 24's global fetch() runs on the bundled undici client, not on node:http, so it pools connections in undici's global dispatcher and ignores http.Agent and http.globalAgent; http.request() is the lower-level, stream-based client those agents configure.

open as a page

In Node.js node:http, how do res.setHeader and res.writeHead differ, and what causes the ERR_HTTP_HEADERS_SENT error?

level: middleimportance: must knowfreq 64%

basics

~20 s

res.setHeader stages one header that Node sends with the first write; res.writeHead sends the status and headers at once and wins over staged ones. Once headers are rendered, any further setHeader or writeHead throws ERR_HTTP_HEADERS_SENT.

open as a page

Why does a Node.js net.Socket 'data' handler sometimes receive half a device message or two messages at once, and how should you frame them?

level: middleimportance: must knowfreq 55%

basics

~20 s

A net.Socket delivers a TCP byte stream, and each 'data' chunk is whatever one read returned, not one write. Frame messages yourself: buffer bytes, split on a delimiter or length prefix, and keep the incomplete tail.

open as a page

A Node 24 service's calls to a slow payment API sometimes hang for minutes; what does each built-in client timeout bound, and how do you cap the whole call?

level: seniorimportance: must knowfreq 55%

basics

~20 s

Node's built-in client timeouts are idle timers: http.request's timeout only emits 'timeout', and fetch's undici defaults allow 300 seconds for headers and between body chunks. Cap the whole call with signal: AbortSignal.timeout(ms), which covers connect, headers and body.

open as a page

In Node.js, why can slow name resolution stall unrelated fs and crypto calls, and how do dns.lookup() and dns.resolve4() differ?

level: seniorimportance: must knowfreq 55%

basics

~20 s

dns.lookup() runs the OS resolver getaddrinfo(3) on libuv's threadpool, shared with fs, crypto and zlib, so slow lookups queue that work. dns.resolve4() sends DNS queries over the network asynchronously, never uses the threadpool, and ignores /etc/hosts.

open as a page

In Node.js, when a net.createServer TCP server accepts a connection, what do the Socket's 'data', 'end', 'error' and 'close' events each tell you?

level: juniorimportance: should knowfreq 40%

basics

~20 s

Each connection arrives as a net.Socket: 'data' delivers a chunk of received bytes, 'end' means the peer stopped sending, 'error' reports a failure and is followed by 'close', and 'close' fires when the socket is fully shut.

open as a page

In Node's fs/promises API, why must every FileHandle be closed explicitly, and what happens in Node 24 when one is left for garbage collection?

level: middleimportance: should knowfreq 35%

basics

~20 s

A FileHandle owns an operating-system file descriptor, and descriptors run out. Node 24 tries to close a forgotten handle on garbage collection, with a warning and no guarantee; from v25.0.0 it throws. Close it in finally, or use await using.

open as a page

In Node.js, how do path.join, path.resolve and path.normalize differ, and how do you check that a computed path stays inside a base directory?

level: middleimportance: should knowfreq 48%

basics

~20 s

path.join glues segments and normalises; path.resolve builds an absolute path, restarting at any absolute segment and falling back to process.cwd(); path.normalize only tidies one string. None checks containment: resolve both paths and test path.relative(base, target).

open as a page

A Node.js CLI walks a project tree: what do readdir's withFileTypes and recursive options give you, and where do they fall short?

level: middleimportance: should knowfreq 30%

basics

~20 s

withFileTypes returns fs.Dirent objects that carry each entry's type without a stat call; recursive lists the whole tree in one array. Recursive cannot prune node_modules and does not follow directory links, so walk manually or use fs.glob with exclude.

open as a page

How do you make a Node 24 service send its fetch() and http.request() calls through the proxy named in HTTP_PROXY and HTTPS_PROXY?

level: middleimportance: should knowfreq 30%

basics

~20 s

Node ignores HTTP_PROXY and HTTPS_PROXY unless you opt in with NODE_USE_ENV_PROXY=1 or --use-env-proxy. Node 24 then routes fetch() and the global http and https agents through the proxy, honouring NO_PROXY; custom agents need a proxyEnv option.

open as a page

In a Node 24 http.Server, what do headersTimeout, requestTimeout, keepAliveTimeout and server.timeout each limit, and which of them stop slow clients?

level: middleimportance: should knowfreq 45%

basics

~20 s

headersTimeout caps the time to receive request headers (60 s), requestTimeout the whole request (300 s), keepAliveTimeout the idle gap after a response (5 s), and server.timeout socket inactivity (off). The first two stop slow clients with a 408.

open as a page

In Node.js, what does tls.connect() verify by default, and why can it fail with ERR_TLS_CERT_ALTNAME_INVALID when https.get() to the same host succeeds?

level: middleimportance: should knowfreq 30%

basics

~20 s

tls.connect() refuses the connection unless the certificate chains to a trusted CA and matches the host name. Unlike https, it sends no SNI without servername, so a server hosting many names may present its default certificate, failing the name check.

open as a page

Node's fs docs warn against calling fs.access() before fs.open(); in an upload service, what replaces that check, and which error codes do you handle?

level: seniorimportance: should knowfreq 40%

basics

~10 s

Between an fs.access() or stat check and the open, another process can change the file. Open directly instead: 'wx' to create only if absent (EEXIST), 'r' to read (ENOENT), then stat the opened FileHandle.

open as a page

A Node 24 service calls an inventory API with fetch(), checks res.ok and never reads error bodies; sockets climb and calls slow down. Why, and what fixes it?

level: seniorimportance: should knowfreq 45%

basics

~20 s

An unread fetch() body can keep its connection busy until the Response is garbage-collected, so new calls open extra sockets or queue behind a cap. Consume every body or call res.body.cancel(); with http.request(), call res.resume().

open as a page

A Node 24 HTTP service behind a load balancer returns intermittent 502s that never appear in its own request logs; which server timeout usually explains this, and how do you fix it?

level: seniorimportance: should knowfreq 50%

basics

~10 s

Node's keepAliveTimeout (5 s) is shorter than the balancer's idle timeout, so Node closes reused idle connections just as the balancer sends a request on one. Set server.keepAliveTimeout above the balancer's idle timeout.

open as a page

On a Node.js TCP server that calls socket.setTimeout(60000) on every net.Socket, why do connections from powered-off devices stay open for hours, and what fixes it?

level: seniorimportance: should knowfreq 40%

basics

~20 s

socket.setTimeout() only emits 'timeout' after idle time and never closes the socket, so the handler must call socket.destroy(). A powered-off device sends nothing at all, so also enable socket.setKeepAlive() to let the kernel detect the dead peer.

open as a page

As the lead for Node 24 services that call payment and inventory APIs, which outbound HTTP client defaults would you standardise, and which built-in defaults would you refuse to inherit?

level: principalimportance: should knowfreq 25%

basics

~10 s

Standardise one client, explicit per-upstream connection caps, a mandatory per-call AbortSignal.timeout, a settle-every-body rule and environment-driven proxying. Refuse Node 24's unlimited per-origin pools and undici's 300-second header and body timers.

open as a page

Should a Node 24 service terminate TLS itself with node:https or node:http2, or leave TLS to a proxy in front, and what does each choice commit the team to?

level: principalimportance: should knowfreq 30%

basics

~20 s

Terminating in Node means owning certificates, rotation (server.setSecureContext), TLS settings and the slow-client limits. A proxy centralises those but leaves a plaintext hop unless it re-encrypts. Choose by who operates certificates and whether traffic must stay encrypted end to end.

open as a page

How does a Node.js node:http2 server differ from a node:http server in its objects and events, and when do you need createSecureServer and allowHTTP1?

level: middleimportance: nice to knowfreq 25%

basics

~20 s

node:http2 gives each connection an Http2Session carrying many Http2Streams; the core API answers a 'stream' event with stream.respond(), while a compatibility API offers req and res. Browsers need createSecureServer; allowHTTP1 lets HTTP/1.1 clients share the port.

open as a page

In Node.js, what does a node:dgram socket.send() callback tell a UDP metrics sender, and why connect the socket to the collector once?

level: middleimportance: nice to knowfreq 20%

basics

~20 s

A dgram send() callback only says the datagram reached the operating system, or why it failed; nothing confirms delivery. Calling socket.connect() once resolves the collector's name once, whereas an unconnected send() to a host name runs dns.lookup() on every call.

open as a page

A Node.js dev tool calls fs.watch(dir, { recursive: true }); why does it behave differently on Linux, macOS and in containers, and what do you design around?

level: seniorimportance: nice to knowfreq 22%

basics

~20 s

fs.watch wraps each OS's notification API, so behaviour differs. On Linux Node emulates recursive watching with one watcher per file and directory; filenames can be null, replaced files go silent, and mounted volumes may report nothing. Treat events as hints.

open as a page