Blog

The basic rules of Node.js

The event loop, async code, errors and modules: the basic rules of Node.js, and the problems they cause when nobody explains them early.

This post is the written version of “Kickoff to Node.js”, my talk at Uszanowanko Programowanko #32 on 10 October 2018: the basic rules of Node.js, and the problems people meet in their first months with it.

One thread runs your JavaScript

Node runs your code on a single thread, driven by an event loop. Input and output, such as files, network calls and timers, happen in the background, and the loop runs your callbacks when the results are ready. That is why one process can hold thousands of open connections, and also why slow synchronous work stalls every one of them at once.

What blocks the loop:

  • synchronous APIs in a request path, such as readFileSync or execSync;
  • CPU-heavy work, such as resizing images or hashing with the synchronous functions;
  • JSON.parse and JSON.stringify on very large payloads.

Use the asynchronous APIs while serving requests, and move heavy work to a child process, a job queue or a separate service. Node 10 also brought worker_threads for this, though it is still experimental and behind a flag.

The missing await

async function saveUser(user) {
  db.users.insert(user); // no await
  return 'saved';
}

The function reports success before the insert has finished, and if the insert fails, the error has nowhere to go. For now Node only prints a warning about an unhandled rejection, and the warning itself says that future versions will stop the process instead. TSLint’s no-floating-promises rule flags promises that nothing awaits.

Waiting in turn by accident

// One after another: the total is the sum of all the requests
for (const id of ids) {
  users.push(await fetchUser(id));
}

// At the same time: the total is about the slowest request
const users = await Promise.all(ids.map((id) => fetchUser(id)));

Sometimes one after another is right, because of a rate limit or because order matters. Make it a decision, not an accident, and for long lists cap how many requests run at once instead of starting them all.

Errors have three shapes

  • In async functions, a throw becomes a rejected promise. Catch it with try and catch where the work is awaited.
  • Callback APIs pass the error as the first argument. Check it before anything else.
  • Event emitters, such as streams and sockets, emit 'error'. If nothing listens for it, the process crashes.

Two module systems

require and module.exports are CommonJS, and that is what Node runs. import and export are ES modules: Babel and TypeScript compile them to require for you, while Node’s own support is still experimental, behind the --experimental-modules flag and the .mjs extension. Mixing the two up is behind a lot of confusing syntax errors. For now, write CommonJS for Node, or let TypeScript or Babel compile your imports, and stay consistent.

Tools to set up on day one

  • nodemon restarts the app when a file changes.
  • dotenv loads environment variables from a .env file.
  • npm ci, new in npm 5.7, installs exactly what package-lock.json lists, which is what a CI server should run.
  • Even-numbered Node.js releases become long-term support versions, and Node 10 becomes one at the end of this month. Pin a version with .nvmrc or the engines field.

Written by Szymon Piecuch