Node.js Fundamentals: The Runtime, the Event Loop, and Building Real APIs

Part 1 of 14 · ~1 min

Overview

Here's the incident that this whole reference is secretly about. Ines and Devon — two engineers at a small field-service scheduling company called Northbound — ship the first version of billhook, the Node service that listens for payment webhooks from Meridian Pay, in an afternoon. It works. Then, a week later, support pings them: a customer's card was charged, Meridian confirms the charge, but Northbound's own dashboard didn't show the order for almost eleven seconds. Not eleven seconds for that webhook — eleven seconds during which every other webhook, from completely unrelated customers, also just... waited. Nothing crashed. Nothing logged an error. The service was busy the entire time, and yet it was doing what looked like nothing.

That gap — between "the process is definitely alive" and "the process is definitely stuck" — is where almost everything worth knowing about Node actually lives. Not in any one API. In the machinery underneath fs, http, and every await you've ever written, and in the specific ways that machinery can surprise you once real traffic hits it.

This reference builds billhook from that first, quietly-broken version through to one that survives production: streaming a receipt image instead of loading the whole thing into memory, telling apart the one raw HMAC-verified byte stream from the parsed JSON everything else wants, handling three generations of the same async operation, and shutting down without losing a payment confirmation mid-flight. Every chapter is a fix to the same running service, in the order Ines and Devon actually hit these problems — work through it front to back, or jump to whatever you need from the sidebar; each chapter opens by naming which version of billhook it's picking up.