
I have been saying the words "we'll just fire an event" in design reviews for years. The words come out cleanly. The underlying picture in my head, if I am honest, has always been a little blurry. Is the event fired inside the database transaction, or after? Who consumes it? If the broker is down for thirty seconds, does anything actually break?

This week I stumbled on a [ByteByteGo infographic](https://blog.bytebytego.com/) that lined up five of these patterns side by side - Transactional Outbox, CQRS, CQRS with Event Sourcing, Saga, Competing Consumers - and I realized I could recite all of them and confidently describe maybe two.

So I did the thing that always works for me when I half-understand something. I sat down and drew each one until I could explain, in plain language, what it is, what it is for, and when I would actually reach for it. This article is that exercise, written out.

## Why These Patterns Exist At All

Message brokers - Kafka, RabbitMQ, SQS, NATS, Pulsar, pick your favorite - are plumbing. They move messages from producers to consumers without either side having to know about the other. That is the whole value proposition, and it is a big one.

But the moment you put a broker in the middle of a system, new questions appear that a single-database design never had to answer:

- What if my database commit succeeds but the broker publish fails?
- What if two services need the same data but want completely different shapes of it?
- What if a "transaction" has to span four services that each own their own database?
- What if one producer emits faster than a single consumer can process?

Each of the five patterns below is a specific answer to one of those questions. None of them are new. All of them show up in real architectures under different names. What helped me was seeing them as *answers to questions* rather than as architectural vocabulary to namedrop.

## 1. Transactional Outbox - Stop Losing Events Between the DB and the Broker

The first time I shipped a service that fired events, my code looked something like this:

```typescript
await db.orders.insert(newOrder);
await broker.publish("order.created", newOrder);
```

It works. Most of the time. The problem is the tiny window between those two lines. If the process crashes after the insert but before the publish, the row exists and the event does not. If the publish succeeds but the commit fails, the event exists for an order that was never created. There is no way to make both lines atomic, because the database and the broker do not share a transaction.

The fix is to stop trying to publish inside the request path at all. Write the event to an **outbox table** in the *same database transaction* as the business row. A separate relay process reads the outbox and publishes to the broker afterwards.

```mermaid caption="Transactional Outbox - the broker publish is moved out of the request path and into a relay that reads from a table written in the same transaction as the business row."
flowchart LR
  S[Order Service]
  subgraph DB[Application Database]
    T[(Order Table)]
    O[(Outbox Table)]
  end
  R[Relay / CDC]
  B[(Message Broker)]
  C[Consumers]
  S -- "single transaction" --> T
  S -- "single transaction" --> O
  R -- "poll or CDC" --> O
  R --> B
  B --> C
```

**Use case I actually hit.** Order service writes an order, publishes `order.created`, and the email service sends a confirmation. Before the outbox: the broker had a thirty-second blip during a rolling restart and we dropped roughly two hundred confirmation emails. After the outbox: the blip became latency instead of loss - the events piled up in the table and the relay drained them once the broker came back.

The pattern already has its own deep-dive in the [pattern library](/patterns/outbox) if you want the schema and the tradeoff between polling and CDC. The thing I want to flag here is cultural rather than technical: once a team has the outbox, `await broker.publish(...)` inside a request handler stops being acceptable. The guarantee the pattern gives you only holds if everybody uses it.

## 2. CQRS - Reads and Writes Shouldn't Share a Model

CQRS stands for Command Query Responsibility Segregation, which is a long way of saying: the thing you use to change data should not be the same thing you use to read data.

In a traditional app, one model and one database serve both. You write `Order`, you read `Order`, both through the same schema. That works until your reads get complicated enough that they start deforming your writes. You add denormalized columns to make a dashboard fast. You add indexes that slow down inserts. You cache. The write model becomes a compromise between two jobs.

CQRS separates them. Writes go through a **command** side that models business operations and lands them in a write-optimized store. Reads go through a **query** side that pulls from a store shaped for the reads your product actually does. The two sides stay synchronized asynchronously - usually via events flowing through the broker.

```mermaid caption="CQRS - the command side owns state changes, the query side owns read shapes, and events on the broker keep the two eventually consistent."
flowchart LR
  Client[Client]
  Cmd[Command Handler]
  Q[Query Handler]
  W[(Write DB)]
  R[(Read DB)]
  B[(Broker)]
  Client -- "write" --> Cmd
  Cmd --> W
  W -- "change events" --> B
  B --> R
  Client -- "read" --> Q
  Q --> R
```

**Use case I actually hit.** A product catalog where the write model was Postgres (authoritative, relational, transactional) and the read model was Elasticsearch (great at fuzzy product search, typo tolerance, faceted filters). Every catalog update was a write against Postgres. A stream of events replayed the updates into Elasticsearch. The write side never had to care about search. The read side never had to care about business rules.

The trap to name out loud: CQRS gives you **eventual consistency** between the two sides. A user who updates a product and immediately lists products may see the old record. For most domains that is fine. For domains where it is not fine - a seller who needs to confirm their price change took effect - you need to either read-after-write from the write side, or make the query-side update synchronous, which defeats most of the point.

## 3. CQRS With Event Sourcing - Store What Happened, Not Just What Is

Regular CQRS keeps the current state on the write side. Event Sourcing goes one step further: it throws away the idea of storing the current state at all. What you store is the sequence of events that produced the state. Current state is a function of replaying those events.

Instead of a row saying "order 42: status=shipped, total=$99," you have an append-only log of events: `OrderCreated`, `OrderPaid`, `OrderShipped`. The current state is whatever you get by folding those events in order. Your read models are projections over the same event log.

```mermaid caption="CQRS with Event Sourcing - the event log is the source of truth. Read models are projections that can be rebuilt from the log at any time."
flowchart LR
  Client[Client]
  Cmd[Command Handler]
  ES[(Event Store)]
  B[(Broker)]
  P1[Projection A]
  P2[Projection B]
  R1[(Read DB - Orders)]
  R2[(Read DB - Analytics)]
  Client -- "command" --> Cmd
  Cmd -- "append event" --> ES
  ES --> B
  B --> P1 --> R1
  B --> P2 --> R2
  Client -- "read" --> R1
```

**Use case where it clearly earns its keep.** A banking ledger. You do not want to store "current balance" as a number that someone can `UPDATE`. You want an append-only log of every debit and credit, and the balance is whatever that log folds to. When an auditor shows up and asks "why was this account at $412.73 on March 2nd?", you have an answer more precise than any state table can give you.

**When I would not reach for it.** A CRUD app. A settings screen. A user profile. The value of event sourcing scales with how much you care about the *history* of the data, not the current value. If nobody will ever ask "how did we get here?", storing events is a lot of operational weight for benefits you will never consume.

The other honest caveat: event sourcing changes how you think about schema migrations, projections, and deployment. You need to be able to rebuild read models from the log. Events become part of your versioned API to your future self. I have only seen it go well in teams that deliberately invested in the tooling for it.

## 4. Saga - Distributed Transactions Without a Distributed Transaction

Sagas answer a specific question: how do you keep a multi-step business operation consistent when each step runs in a different service with its own database?

Take a checkout: reserve inventory, charge the customer, arrange shipping, send a confirmation. In a monolith this is one database transaction. In a microservice architecture, each step is a different service with its own database and no shared transaction. If the charge succeeds but shipping fails, you have a customer who paid for something that will never arrive - and no automatic rollback.

A saga decomposes the business operation into a sequence of local transactions, each of which emits an event that triggers the next step. If any step fails, **compensating transactions** run in reverse to undo the completed steps. There is no global lock; there is a protocol.

```mermaid caption="Saga (choreography style) - each service completes its local transaction and emits an event. Failure at any step triggers compensation events running in reverse."
sequenceDiagram
  participant User
  participant Order as Order Service
  participant Payment as Payment Service
  participant Ship as Shipping Service
  User->>Order: Place order
  Order->>Order: Create order (local tx)
  Order-->>Payment: order.created
  Payment->>Payment: Charge card (local tx)
  Payment-->>Ship: payment.charged
  Ship->>Ship: Arrange shipment (local tx)
  Ship-->>Order: shipment.arranged
  Note over Order,Ship: Any failure emits a compensation event<br/>that walks the saga backwards.
```

There are two flavors of saga. **Choreography** (shown above) has each service listen for events and decide what to do next - no central coordinator. **Orchestration** has a dedicated saga orchestrator that issues commands to each service and owns the state machine. Choreography is simpler to deploy but harder to observe. Orchestration is easier to reason about but introduces a coupling point. My rule of thumb: fewer than four steps, choreography. Four or more, orchestration, because the debuggability is worth it.

**Use case I actually hit.** An e-commerce checkout with five services. We started choreographed. By step four we could not answer the question "where did saga X get stuck?" without stitching logs from five systems by hand. We moved to an orchestrator with a state table. The code got slightly more boring and the on-call pages got dramatically shorter.

The pattern library has a [longer saga entry](/patterns/saga) with both styles in code. The thing worth repeating here: sagas give you **eventual consistency**, not atomicity. For a moment, the order exists and the payment does not. Your product, your dashboards, and your customer service team need to understand that.

## 5. Competing Consumers - One Queue, Many Workers

This is the most mechanically simple pattern of the five, and the one I reach for most often. It is also the one that needs the least explanation, so I will keep this short.

Producers drop messages onto a queue. Multiple consumer instances pull from the same queue. Each message is delivered to exactly one consumer. Load balances itself - faster consumers pull more, slower ones pull less. Add more consumers to go faster. Remove some to save cost.

```mermaid caption="Competing Consumers - a single queue, many worker instances. The broker load-balances messages across whichever consumers are currently pulling."
flowchart LR
  P1[Producer 1] --> Q
  P2[Producer 2] --> Q
  P3[Producer 3] --> Q
  Q[[Message Queue]]
  Q --> C1[Consumer A]
  Q --> C2[Consumer B]
  Q --> C3[Consumer C]
```

**Use case I actually hit.** Image processing pipeline. Users upload photos, a queue holds "process this photo" jobs, a fleet of worker containers pulls from the queue. On a slow day, three workers. On a campaign spike, forty. The queue absorbs the bursts so the upload endpoint never blocks.

**Two things I wish I had internalized earlier.** First, **messages must be processable in any order** - the broker load-balances across workers, so ordering per-message is not preserved across the fleet. If you need per-entity ordering (all events for user 42 processed in order), use a partitioned queue keyed on entity id, where each partition is its own competing-consumers pool of one. Second, **consumers must be idempotent**. Queues almost universally give at-least-once delivery. A worker that crashes after processing but before acknowledging will see the same message again. If running the handler twice produces the wrong answer, your pattern is broken - not the broker.

## How I Decide Which One I Actually Need

Drawing them side by side made the decision tree obvious in a way that reading the names never did:

- **I need to atomically record a state change and notify others?** → **Outbox.** Almost always. It is the default, not the exotic choice.
- **My reads and writes have genuinely different shapes and my write model is suffering for it?** → **CQRS.** Accept eventual consistency on the read side.
- **The history of changes is a first-class product concern (audit, debugging, rebuildable projections)?** → **CQRS with Event Sourcing.** Pay the tooling cost deliberately.
- **A business operation spans multiple services and must either all succeed or all compensate?** → **Saga.** Orchestrated if it has more than three steps.
- **I have a stream of independent tasks and I want to scale processing horizontally?** → **Competing Consumers.** Bake in idempotency from day one.

Most real systems use more than one of these at the same time. The checkout flow I mentioned earlier uses four of the five: the outbox to publish events atomically with the write, a saga to coordinate the flow, competing consumers on each step to scale, and a small CQRS slice for the order-lookup read model the customer service team uses. None of them felt clever in isolation. Together they made the system boring, which is the highest compliment I can give a distributed design.

{/* subscribe-cta */}

## The Quiet Lesson

The thing that surprised me most, drawing these out, is how much of "distributed systems design" is not really about algorithms or consensus or exotic infrastructure. It is about naming the *kind of inconsistency* you are willing to tolerate - across a transaction boundary, across two databases, across five services - and then picking the pattern that turns that inconsistency into something your system recovers from on its own.

The broker is the plumbing. These patterns are the plumbing conventions that keep the water going the right direction when one of the pipes shakes.

If you only take one thing from this article: the next time you write `await broker.publish(...)` directly after a database write, pause. That line is a micro-decision about consistency, availability, and what you owe the next engineer who has to debug this at 3am. The patterns above are the menu of better answers.


Five Message Broker Patterns


The first time a senior engineer stopped me mid-dashboard and said "I don't care about the average, show me P99," I thought he was being fussy. The average looked great. The system was handling traffic. What else did he want?

What he wanted, I figured out later, was the shape of the distribution - not its center of gravity. Averages lie in a very specific way for distributed systems. P99 is how engineers force the lie to show itself.

This is my attempt to write down *why* P99 is the number that ends up carved on every serious latency dashboard I have ever seen, even though most engineers encounter it as an unexamined default.

## The Median Is A Comforting Fiction

Here is the thing the P50 will not tell you.

Imagine a service where 99 out of 100 requests take 50ms, and one request takes 10 seconds. The median is 50ms. The average is around 150ms. Both numbers tell you the service is "fast." Neither of them tells you that 1% of your users just watched a progress spinner for 10 seconds.

At a hundred requests per second, that is one angry user every second. At a thousand requests per second, it is ten. At the scale of an actual product, the users at the tail are not a rounding error - they are a population large enough to notice, complain, and leave.

```mermaid A healthy-looking distribution with a long right tail. The P50 lives on the left; P99 lives in the territory on the right that averages smooth over.
xychart-beta
    title "Request Latency Distribution"
    x-axis ["0-50ms", "50-100ms", "100-200ms", "200-500ms", "500ms-1s", "1s-3s", "3s-10s"]
    y-axis "Requests (log)" 1 --> 10000
    bar [6000, 2500, 900, 400, 150, 40, 10]
```

This is the shape almost every real-world latency distribution has: a fat body on the left, a long tail on the right. The tail is where the interesting stories live. The body is where metrics go to look fine.

## The Tail At Scale

The academic argument for P99 - and the one that reframed how I think about system performance - comes from a 2013 paper by Jeff Dean and Luiz Barroso called *The Tail at Scale*. The paper is short, cited thousands of times, and worth reading on its own. Here is the part that matters.

Modern systems are not monoliths. A single user request, say a search or a product page, fans out into dozens or hundreds of internal sub-requests. The gateway calls auth. Auth calls a user service. The user service calls a feature flag service. Everything calls caches. Everything calls databases. The page cannot render until *all* of those calls return.

```mermaid A single user request fans out across a dozen services, caches, and databases. The user only sees the slowest path.
flowchart TD
    U[User Request] --> G[API Gateway]
    G --> A[Auth Service]
    G --> P[Product Service]
    G --> R[Recommendations]
    G --> I[Inventory]
    A --> C1[(Session Cache)]
    A --> D1[(User DB)]
    P --> C2[(Product Cache)]
    P --> D2[(Catalog DB)]
    R --> M[ML Ranker]
    R --> D3[(User Events)]
    I --> D4[(Stock DB)]
    M --> F[Feature Store]
```

Now do the math. Suppose every service on that path has a healthy P99 of one second - meaning 99% of calls are faster than a second. You might reasonably say each service is performing well.

If the user-facing request depends on 100 independent sub-requests, the probability that *none* of them land in their slow tail is $0.99^{100}$, which is roughly 0.37. In other words, there is a **63% chance** that the user waits at least a second on a sub-request, even though every single service individually meets its SLO.

That number is the entire argument for P99.

```mermaid Even when every individual service meets its P99 SLO, the probability of a tail hit climbs steeply with fan-out depth. At 100 sub-requests the composite response is more likely than not to catch a slow one.
xychart-beta
    title "Probability of a Tail Hit vs Fan-Out Depth (P99 per service)"
    x-axis ["1 svc", "5 svcs", "10 svcs", "25 svcs", "50 svcs", "100 svcs"]
    y-axis "P(at least one slow sub-request) %" 0 --> 100
    bar [1, 5, 10, 22, 40, 63]
```

The individual P99s look fine. The *composition* of them is catastrophic. As soon as you fan out, rare events stop being rare — they become the dominant user experience. A tail that you could ignore at the component level becomes the median experience at the system level.

This is the phenomenon Dean and Barroso called "the tail at scale." It is the uncomfortable reason averages lie. Averages smooth; composition amplifies.

## The Money Follows The Tail

The other reason engineers fixate on P99 is that the people paying for the system care about it even when they do not know the acronym.

The numbers from industry have been cited so often they are almost folklore at this point, but the folklore happens to be true:

- Amazon's internal studies have reported that every additional 100ms of latency costs about **1% of sales**.
- Google has reported that a 400ms increase in search latency produces about a **0.59% drop in searches per user**.
- User research has consistently found that once page load times exceed a few seconds, abandonment climbs sharply.

Notice what these numbers are actually measuring. They are not measuring the average response time. They are measuring what happens when a user's request lands in the slow part of the distribution. The users who feel "the internet is slow today" are the users whose requests took 2 seconds instead of 200ms. That is a P99 problem, not a P50 problem.

When the business tells you "the site feels slow," they are telling you about the tail, even if they are looking at a graph of averages. If you chase the average down from 300ms to 250ms but leave the P99 at 4 seconds, your users will not notice the improvement. The users who cared were the ones in the tail, and they are still there.

## P99 Is An Early Warning

There is a second reason to watch P99 that has nothing to do with user experience: it is often the first place failures announce themselves.

A healthy system runs with spare capacity. When capacity is comfortable, a slow GC pause here or a head-of-line blocking moment there gets absorbed. The median does not move. The P99 twitches, briefly, and settles.

As the system creeps closer to its saturation point, the twitches get bigger and more frequent. Queues build up behind transient slowdowns. Threads that would have freed quickly now stay held. The *body* of the distribution still looks fine - most requests are completing - but the tail is getting longer. P99 starts drifting up while P50 stays flat.

```mermaid The path from a benign P99 twitch to a full outage. You see it on the P99 graph minutes or hours before it shows up on the P50.
flowchart LR
    A[Minor GC pause] --> B[Request slows]
    B --> C[Thread held longer]
    C --> D[Queue builds]
    D --> E[More requests slow]
    E --> F[More retries]
    F --> G[Queue saturates]
    G --> H[Cascading failure]
    style H fill:#3a1a1a,stroke:#7a2a2a
```

```mermaid P50 holds flat for most of the degradation window while P99 climbs steadily. The widening gap is the early warning signal. By the time P50 moves, the incident has already started.
xychart-beta
    title "P50 vs P99 as System Approaches Saturation"
    x-axis ["t-60m", "t-45m", "t-30m", "t-15m", "t-5m", "now"]
    y-axis "Latency (ms)" 0 --> 2000
    line [55, 52, 58, 60, 62, 65]
    line [130, 140, 280, 650, 1300, 1900]
```

By the time the median moves, you are past warning and into incident. By the time the average moves, you are in the post-mortem.

This is the operational case for watching P99 even when the business case is not obvious. The 99th percentile is the canary. The median is the corpse.

## Why Not P95? Why Not P999?

A fair question at this point is: if we are chasing the tail, why stop at P99? Why not P99.9, or P99.99?

The honest answer is: it depends on scale, and on what you can afford to care about.

At low traffic, P99 is already measuring something rare. At a thousand requests per second, P99 is ten requests a second in the slow bucket. P99.9 is one. P99.99 is one every ten seconds. You cannot meaningfully alert on a percentile that fires once per hour.

At high traffic - the Googles, Metas, Cloudflares of the world - the math flips. A thousand requests per second is a slow minute. Their user-facing systems operate at millions of requests per second, and P99.9 or P99.99 becomes the right level of resolution, because "one in a thousand" is still thousands of users per minute.

P95 exists for the opposite reason. At small scales, or for systems where 5% of slow requests is acceptable, P95 is a cheaper number to keep green. It is forgiving in a way P99 is not.

My rule of thumb is: the percentile you should target is the one where the count of "slow requests per unit time" is high enough to notice and low enough to fix. For most services I have worked on, that has landed on P99. For systems operating at web scale, it is usually P99.9. The principle is the same either way: *you are targeting the tail, not the center.*

```mermaid At 10,000 requests per second, P95 fires 500 times a second -- too noisy to act on. P99.99 fires once every ten seconds -- too rare to alert on. P99 sits in the actionable middle.
xychart-beta
    title "Slow Requests per Second at 10K rps by Percentile"
    x-axis ["P95", "P99", "P99.9", "P99.99"]
    y-axis "Slow req/sec" 0 --> 550
    bar [500, 100, 10, 1]
```

{/* subscribe-cta */}

## What Watching P99 Actually Changes

Once you take P99 seriously, several engineering practices stop looking optional.

**Timeouts become budgets, not upper bounds.** If the user-facing request budget is 1 second and you fan out to five sub-requests, each sub-request gets a fraction of that budget - not the full second. Sub-request timeouts that equal the full user budget are a way of guaranteeing that P99 at the leaf becomes P99 at the root.

**Hedged requests and request duplication become real tools.** The Dean and Barroso paper's most practical advice is to send a duplicate request if the first one has not returned by, say, P95. The second request gives you another independent chance to avoid the slow tail. The cost is a small amount of extra load; the benefit is that your user-visible P99 becomes close to your server-side P95.

**Load shedding starts to make sense.** If slow requests are the enemy, a service that rejects 1% of requests cleanly under overload is better than a service that queues them and serves all of them slowly. The first service has a controlled error rate and a healthy P99. The second has a beautiful success rate and a terrifying one.

**Observability shifts from averages to histograms.** An average cannot be decomposed. A histogram can. Once you store full latency histograms - not just means and maxes - you can compute any percentile you want, slice by endpoint, and compare tail behavior across deploys. Most reliability work I have done in the last few years started with "can we actually see the distribution?" and the answer was uncomfortably often "no."

## The Mental Model That Stuck

The shift that took me a long time to make is this: I used to think of a service as having a single "speed." The average, the typical response, the thing I would quote if someone asked. A service was "fast" or "slow."

A service does not have a single speed. It has a distribution. Every single request samples from that distribution independently. At the scale of one user, the sample is the experience. At the scale of many users fanning out across many services, the joint probability of every sample avoiding the tail collapses fast.

P99 is a shorthand for reasoning about the distribution's right edge - the place where the business loses money, where the operator loses sleep, and where the system shows you what is about to break before it actually breaks.

## The Short Version

Averages are a story about a system that does not exist. P50 is a story about the user who did not have a problem. P99 is a story about the users who did.

Once you fan out, the tail eats you. Once you are at scale, the tail is the product. Once you are in an incident, the tail told you first.

That is why every serious latency dashboard, at every company I have ever respected the engineering of, has P99 on it in large type. Not because it is a best practice. Because everything else, sooner or later, lies.

## References

- Dean, J., & Barroso, L. A. (2013). [The Tail at Scale](https://doi.org/10.1145/2408776.2408794). *Communications of the ACM*, 56(2), 74–80.
- Puzhavakath Narayanan, S., et al. (2016). Reducing latency through page-aware management of web objects by content delivery networks. *ACM SIGMETRICS Performance Evaluation Review*, 44(1), 89–100.
- Google Research. (2015). [User Preference and Search Engine Latency](https://research.google.com/pubs/archive/34439.pdf).
- Zhao, Z., et al. (2025). SLOpt: Serving real-time inference pipeline with strict latency constraint. *IEEE Transactions on Computers*.


Why Engineers Are Obsessed With P99


There's a failure mode that will ruin your week. Not because it's loud, it won't be. Your services stay up. Metrics look mostly reasonable. Alerts don't fire immediately. And yet your system is producing no useful output. Users are getting errors. Revenue is going to zero. And your dashboards are telling you everything is fine.

This is a **meta-stable failure**. It's the failure mode that keeps distributed systems engineers up at night precisely because it doesn't look like a failure.

This is first time i heard the term "**meta-stable failure**.", it spark curiosity in me and dig down deeper.

## Up, But Down

The formal definition, from a 2021 HotOS paper co-authored by engineers at AWS, Meta, and others: *"Metastable failures occur in open systems with an uncontrolled source of load where a trigger causes the system to enter a bad state that persists even when the trigger is removed."*

Read that last clause again. *Even when the trigger is removed.*

This is what separates meta-stable failures from ordinary outages. In a normal incident, you find the cause, fix it, and the system recovers. In a meta-stable failure, you fix the cause and the system stays broken. The failure has become self-sustaining. You're not fighting the original trigger anymore, you're fighting the system's own behavior.

## The Sustaining Loop

To understand why, you need to understand what's actually happening mechanically.

Imagine a backend service under normal load. A routine deployment causes a brief latency spike. Clients, following best practices, retry their failed requests. But those retries arrive while the service is already struggling, which increases load further. The higher load causes more failures. More failures cause more retries. More retries cause more load.

The original trigger, the deployment, is long gone. The latency spike from the deploy resolved in 30 seconds. But the feedback loop it kicked off is still running, hours later, at full intensity. Your service is extremely busy processing retries for requests it will never successfully complete. It has high throughput. It has near-zero *goodput*, useful work delivered to users.

The system is "up." In a meaningful sense, it's completely down.

## Why Good Engineering Made It Worse

Here's the uncomfortable part. Every mechanism in that loop was put there deliberately, by thoughtful engineers, for good reasons.

**Retries** exist because transient failures are real. Networks drop packets. A request that fails once often succeeds on the second attempt. Without retries, users see errors from hiccups that the system would have handled fine with one more chance.

**Timeouts** exist because hanging requests are worse than failed ones. A request that waits forever holds resources, threads, connections, memory, that block other requests. Timeouts free those resources so the system can keep serving other traffic.

**Backoff** is supposed to prevent retry storms, and in mild overload scenarios it works well. But in deep overload, even exponential backoff with jitter doesn't reduce enough load to allow recovery. The system is so far from its recovery threshold that even well-behaved clients can't get it there.

Each of these was the right decision in isolation. The meta-stable failure emerges from their interaction under specific conditions.

## The Trigger Is Not The Problem

This is the key insight that changes how you think about these failures, and the one that gets buried when teams do post-mortems.

A meta-stable failure has two distinct phases: a **trigger** that pushes the system into the bad state, and a **sustaining mechanism** that keeps it there. Engineers almost always focus their post-mortem on the trigger, the deployment, the traffic spike, the upstream timeout. They fix it and declare the incident closed.

But the trigger is almost incidental. A different trigger, a thundering herd, a cache invalidation, a brief network partition, would have caused exactly the same outcome. The system has a stability property that makes it vulnerable: under certain load conditions, a feedback loop can lock it into a degraded state it cannot escape from on its own.

Fix the trigger and you've prevented *this* incident. Fix the sustaining mechanism and you've changed the system's fundamental failure behavior.

## Four Places Sustaining Loops Hide

The HotOS paper identifies common sources. These aren't exotic, they're patterns you've almost certainly shipped.

**Retry logic without load shedding.** Retries increase load during overload. If your service doesn't have a mechanism to start rejecting work, actively, deliberately, with a 503, it has no way to reduce its own load. The retry traffic fills every available slot. The only escape is an operator manually cutting traffic.

**Caching with thundering herds.** A cache miss causes a backend query. Under normal load, this is fine, misses are occasional and the backend handles them. But a cache eviction or flush can cause every node to miss simultaneously, sending a spike to the backend that exceeds its capacity, causing timeouts, causing retries, filling the queue. The cache can't repopulate if the backend can't respond, so the thundering herd sustains itself.

**Slow error paths.** Your fast path is highly optimized. Your error path, the code that runs when something goes wrong, was written once and never touched again. If error handling is significantly slower than normal processing, failures consume more resources per request than successes. At high error rates, this means the system is burning capacity on work that produces no value. The more it fails, the less capacity it has to succeed.

**Autoscaling with lag.** Cloud autoscaling is not instantaneous. There's a window, sometimes several minutes, between when load exceeds capacity and when new instances are ready. During that window, if the load is sustained by a feedback loop, the existing instances may saturate before help arrives. New instances that join an already-overloaded cluster can get immediately hammered and fail to start up successfully at all.

## What Recovery Actually Looks Like

If you're in a meta-stable failure and you remove the trigger, the system won't recover. It's locked in the bad state. You need to do something that breaks the sustaining loop.

The most common effective interventions:

**Reduce load below the recovery threshold.** If retries are sustaining the loop, stop the retries. Cut client traffic at the load balancer. Drop the offered load far enough that the service can start clearing its backlog. This feels wrong, you're making the user-visible failure more severe, but it's the only way to let the system breathe.

**Restart the sustaining mechanism.** If cache state is part of the loop, a controlled warm-up sequence (where you rebuild cache before allowing full traffic) can break the cycle. If connection pool exhaustion is sustaining the failure, recycling connections on the server side can free the system.

**Emergency throttling.** A hard rate limit, not a soft one, that doesn't grow under retry pressure. Circuit breakers that stay open long enough for backend queues to drain, not just long enough to let one request through.

{/* subscribe-cta */}

## How to Build Systems That Don't Get Trapped

The sustaining loop is the target, not the trigger. That reframes what resilience engineering actually means for this failure mode.

**Give your services a way to shed load.** Every service that accepts open-loop traffic needs a pressure valve. This means returning 503 when load exceeds a threshold, not queueing indefinitely. Queues that grow without bound under load are a meta-stable failure waiting to happen. They accept work the service will never complete, holding capacity that could be freed.

**Treat your error paths with the same care as your fast paths.** Profile them. Load test them. If your error handling is two orders of magnitude slower than normal processing, it will become a resource sink at exactly the wrong time.

**Design for controlled recovery.** The hardest operational moment in a meta-stable failure is the transition back to normal. Load needs to ramp up slowly, too fast, and the recovering system re-enters the bad state. Traffic ramp-up procedures, caching warm-up sequences, and connection pre-warming aren't nice-to-haves; they're the mechanism that prevents re-entry.

**Think in feedback loops, not component failures.** Most distributed systems reliability work treats failure as: component X failed, what is our tolerance for X failing? Meta-stable failures are a different animal. They emerge from the *interaction* of functioning components. The question isn't "what happens when X fails" but "what happens to the system's dynamics when load pushes past a threshold." Control theory, not traditional reliability engineering, is the right mental model.

## The Honest Thing About Post-Mortems

When you've been through a meta-stable failure and you're writing the post-mortem, the trigger makes for a satisfying story. There was a deploy. There was a traffic spike. Here's what we did wrong, here's the fix, here's the test to prevent it next time.

But if you stop there, you've documented a specific trigger while leaving the underlying failure mode intact. The next time, different trigger, same catastrophic loop, same hours of degradation.

The meta-stable failure asks a harder question: not "what went wrong" but "what property of this system makes it capable of getting trapped like this?" That question doesn't have a clean action item. It has architectural answers that take quarters to implement. It requires reasoning about your system's dynamics under load, not just its behavior under component failure.

That's the harder work. And it's the only work that actually changes the failure mode.

reference video:
https://www.youtube.com/watch?v=u3GjIXP9N0s

Meta-Stable Failure: When Your System Is Up But Completely Down


The smallest complete JavaScript program prints a message to the console - proving the runtime is wired up and your code runs.

<ExamplePair>
  <ExampleProse>

  `console.log` prints its argument to stdout. Every JavaScript runtime - Node.js, browser devtools, Deno, and Bun - honors it.

  </ExampleProse>

  <ExampleCode>

  ```js
  console.log("Hello, World!");
  ```

  </ExampleCode>

</ExamplePair>


<ExamplePair>
  <ExampleProse>

Running this prints:

  </ExampleProse>

  <ExampleCode>

  ```shell
  Hello, World!
  ```
  </ExampleCode>

</ExamplePair>



<InProduction>
`console.log` is fine for scripts and CLI tools. In services, replace it with a structured logger like [pino](https://getpino.io) or [winston](https://github.com/winstonjs/winston) that writes JSON - plain text logs are difficult to query in Datadog or Grafana Loki, and `console.log` bypasses log levels and request-ID serialization entirely.
</InProduction>


The simplest JavaScript program - print a message to the console.

Hello, World


JavaScript has eight value types: seven primitives (`string`, `number`, `bigint`, `boolean`, `undefined`, `symbol`, and `null`) and `object`. The `typeof` operator reveals a value's type - with one infamous exception.

<ExamplePair>
<ExampleProse>

Numbers, strings, and booleans are the most common primitives. `typeof` returns their type as a lowercase string.

</ExampleProse>
<ExampleCode>

```js
typeof 42;         // "number"
typeof "hello";    // "string"
typeof true;       // "boolean"
typeof undefined;  // "undefined"
typeof Symbol();   // "symbol"
typeof 9007199254740993n; // "bigint"
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`null` is technically a primitive, but `typeof null` returns `"object"` - a legacy bug in the language that [can never be fixed without breaking existing code](https://www.wirfs-brock.com/allen/jshopl.pdf). Check for null explicitly.

</ExampleProse>
<ExampleCode>

```js
typeof null;        // "object" - legacy quirk, not a real object
null === null;      // true  - use this instead
null !== undefined; // true  - null and undefined are distinct
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Always use strict equality (`===`) for comparisons. The loose equality operator (`==`) coerces types before comparing, producing results that are rarely what you want.

</ExampleProse>
<ExampleCode>

```js
0 == false;         // true  (type coercion)
0 === false;        // false (strict - different types)

"" == false;        // true  (coercion)
"" === false;       // false

null == undefined;  // true  (special case)
null === undefined; // false
```

</ExampleCode>
</ExamplePair>

<InProduction>
The `typeof null === "object"` quirk bites null checks written as `if (typeof x === "object")` - that check passes for `null`. Always combine it with an explicit `x !== null` guard, or just check `x === null` directly. Prefer strict equality (`===`) everywhere; the loose `==` operator has over a dozen coercion rules that produce surprises in feature-flag defaults, counter comparisons, and conditional rendering.
</InProduction>


JavaScript has seven primitive types plus the object type - and one infamous typeof quirk.

Values


JavaScript has three variable declaration keywords: `var`, `let`, and `const`. They differ in scope, hoisting, and reassignability. Modern code uses `const` and `let` exclusively.

<ExamplePair>
<ExampleProse>

`const` declares a block-scoped binding that cannot be reassigned. It is the right choice for most declarations - it signals that the value won't change, which makes code easier to reason about.

</ExampleProse>
<ExampleCode>

```js
const name = "Ada";
name = "Grace"; // TypeError: Assignment to constant variable.
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`let` is block-scoped and allows reassignment. Use it only when a variable genuinely needs to change - a loop counter, an accumulator, a flag that flips once.

</ExampleProse>
<ExampleCode>

```js
let count = 0;
count = count + 1;
console.log(count); // 1

for (let i = 0; i < 3; i++) {
  console.log(i); // 0, 1, 2
}
// i is not accessible here
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`var` is function-scoped and hoisted to the top of its function. A `var` declared inside an `if` block leaks into the surrounding function - a frequent source of bugs in older code.

</ExampleProse>
<ExampleCode>

```js
function demo() {
  if (true) {
    var x = 1; // hoisted to function scope
  }
  console.log(x); // 1 - leaks out of the if block

  let y = 2;
  // y stays block-scoped - won't leak
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
The modern convention is `const` by default, `let` only when reassignment is genuinely required, and `var` never. ESLint's `prefer-const` and `no-var` rules enforce this automatically. Teams that skip these rules accumulate subtle bugs in async code: a `var` in a loop body captured by a closure resolves to the final loop value, not the value at the iteration where the closure was created - a class of bug that `let` eliminates entirely.
</InProduction>


Three ways to declare variables in JavaScript - var, let, and const - each with different scoping and hoisting rules.

Variables


`const` locks a variable's _binding_ - you cannot reassign the name. It does not make the value immutable.

<ExamplePair>
<ExampleProse>

Attempting to reassign a `const` binding throws a `TypeError` at runtime and is caught at parse time by TypeScript and most linters.

</ExampleProse>
<ExampleCode>

```js
const x = 1;
x = 2; // TypeError: Assignment to constant variable.
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

An object bound by `const` is still mutable. Its properties can be changed freely because the binding (the pointer) is fixed, not the data it points to.

</ExampleProse>
<ExampleCode>

```js
const config = { retries: 3 };
config.retries = 5; // fine - mutating the object, not the binding
console.log(config.retries); // 5
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`Object.freeze` prevents property mutation. Writes fail silently in sloppy mode and throw a `TypeError` in strict mode. Note that `freeze` is shallow - nested objects remain mutable.

</ExampleProse>
<ExampleCode>

```js
"use strict";

const settings = Object.freeze({ timeout: 5000 });
settings.timeout = 1000; // TypeError: Cannot assign to read only property
```

</ExampleCode>
</ExamplePair>

<InProduction>
Teams that read `const` as "immutable" and treat a shared config object as safe to pass around are in for a surprise when two call sites mutate it concurrently. Deep immutability is a library concern - [Immer](https://immerjs.github.io/immer/) for update workflows, `structuredClone` for a quick deep copy - or a TypeScript type concern (`as const`, `Readonly<T>`). The language keyword alone doesn't buy it.
</InProduction>


const locks the binding, not the value - objects and arrays declared with const are still mutable.

Constants


Every JavaScript number is a 64-bit IEEE 754 floating-point value. There is no separate integer type - which means integers above 2⁵³ lose precision, and decimal arithmetic has well-known rounding quirks.

<ExamplePair>
<ExampleProse>

The classic float trap: `0.1 + 0.2` does not equal `0.3`. Compare floating-point numbers using a tolerance instead of strict equality.

</ExampleProse>
<ExampleCode>

```js
console.log(0.1 + 0.2 === 0.3); // false
console.log(0.1 + 0.2); // 0.30000000000000004

// Safe float comparison
const a = 0.1 + 0.2;
const b = 0.3;
console.log(Math.abs(a - b) < Number.EPSILON); // true
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`Number.MAX_SAFE_INTEGER` is the largest integer that can be represented exactly. Beyond it, incrementing no longer works reliably.

</ExampleProse>
<ExampleCode>

```js
console.log(Number.MAX_SAFE_INTEGER); // 9007199254740991

const n = Number.MAX_SAFE_INTEGER;
console.log(n + 1 === n + 2); // true - precision lost
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`BigInt` handles arbitrarily large integers exactly. Use the `n` suffix for literals. BigInt and Number cannot be mixed in arithmetic - you must convert explicitly.

</ExampleProse>
<ExampleCode>

```js
const big = 9007199254740991n + 1n;
console.log(big); // 9007199254740992n

console.log(10n * 2n); // 20n
// console.log(10n + 1); // TypeError: Cannot mix BigInt and other types
```

</ExampleCode>
</ExamplePair>

<InProduction>
Never store monetary values as `Number`. Representing $19.99 as `19.99` and doing arithmetic on it will produce rounding errors that compound across transactions. Store money as integer cents (`1999`) or use a decimal library like [decimal.js](https://mikemcl.github.io/decimal.js/). Payment systems that let floats drift ship silent bugs that accounting finds months later.
</InProduction>


Every non-BigInt number in JavaScript is a 64-bit float - understanding the precision limits prevents hard-to-debug arithmetic bugs.

Numbers


JavaScript strings are sequences of UTF-16 code units, not characters. For most ASCII text this distinction is invisible, but it surfaces immediately when you handle emoji, accented letters, or any character outside the Basic Multilingual Plane.

<ExamplePair>
<ExampleProse>

Template literals use backticks and `${expression}` interpolation. They support multi-line strings and embed any expression - no concatenation required.

</ExampleProse>
<ExampleCode>

```js
const name = "world";
const greeting = `Hello, ${name}!`;
console.log(greeting); // Hello, world!

const multiline = `Line one
Line two`;
console.log(multiline);
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

An emoji like `"😀"` is encoded as a surrogate pair - two UTF-16 code units. The `.length` property counts code units, not visible characters, so it returns `2` for a single emoji.

</ExampleProse>
<ExampleCode>

```js
const emoji = "😀";
console.log(emoji.length); // 2 - two UTF-16 code units

// Spread iterates code points, not code units
console.log([...emoji].length); // 1 - one code point
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`String.prototype.normalize` converts between Unicode normalization forms (NFC, NFD, NFKC, NFKD). Two strings that look identical can compare unequal if one uses a precomposed character and the other uses a base + combining mark.

</ExampleProse>
<ExampleCode>

```js
const a = "é"; // é - precomposed
const b = "é"; // é - e + combining acute accent

console.log(a === b); // false
console.log(a.normalize() === b.normalize()); // true
```

</ExampleCode>
</ExamplePair>

<InProduction>
Any string you truncate for a UI label, store in a database with a character-limit column, or split on "characters" needs [`Intl.Segmenter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Segmenter) or a grapheme-cluster library. A naive `.slice(0, 10)` on a user's display name can cut a surrogate pair in half, writing a lone surrogate to the database and producing mojibake on read-back. Family emoji (`👨‍👩‍👧`) can be 8+ code units - `.length` will not tell you what you think.
</InProduction>


JavaScript strings are sequences of UTF-16 code units - template literals, surrogate pairs, and grapheme clusters each have important implications.

Strings


Conditionals branch execution based on whether an expression is truthy or falsy.

<ExamplePair>
<ExampleProse>

`if/else` is the fundamental branch. The `else if` chain handles multiple cases.

</ExampleProse>
<ExampleCode>

```js
const score = 72;

if (score >= 90) {
  console.log("A");
} else if (score >= 80) {
  console.log("B");
} else {
  console.log("C or below");
}
// C or below
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The ternary operator `condition ? a : b` is a compact inline branch - appropriate for simple value selection, not for nesting logic.

</ExampleProse>
<ExampleCode>

```js
const age = 20;
const label = age >= 18 ? "adult" : "minor";
console.log(label); // adult
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`||` returns the first truthy operand (or the last value if all are falsy); `&&` returns the first falsy operand (or the last value if all are truthy). `??` (nullish coalescing) returns the right side only when the left is `null` or `undefined` - unlike `||`, it does not treat `0` or `""` as missing.

</ExampleProse>
<ExampleCode>

```js
const requestedLimit = 0;

const withOr  = requestedLimit || 100;  // 100 - wrong! 0 is falsy
const withNull = requestedLimit ?? 100; // 0   - correct

console.log(withOr);   // 100
console.log(withNull); // 0
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`switch` matches by strict equality. Without a `break`, execution falls through into the next case - a common source of bugs.

</ExampleProse>
<ExampleCode>

```js
const status = "pending";

switch (status) {
  case "pending":
    console.log("queued");
    // no break - falls through to "active"!
  case "active":
    console.log("running");
    break;
  case "done":
    console.log("finished");
    break;
  default:
    console.log("unknown");
}
// queued
// running
```

</ExampleCode>
</ExamplePair>

<InProduction>
The `||` defaulting pattern - `const host = config.host || "localhost"` - silently swallows legitimate falsy values like `0`, `""`, and `false`. This bites feature-flag evaluations, counter initializations, and port numbers. Default to `??` for optional config and only reach for `||` when you genuinely want to treat all falsy inputs as absent.
</InProduction>


if/else, ternary, logical operators as control flow, and switch's non-obvious fallthrough.

Conditionals


JavaScript offers several loop constructs. Picking the right one matters for correctness, readability, and async behavior.

<ExamplePair>
<ExampleProse>

A classic `for` loop gives full control over the index - useful when you need the position, not just the value.

</ExampleProse>
<ExampleCode>

```js
const items = ["a", "b", "c"];

for (let i = 0; i < items.length; i++) {
  console.log(i, items[i]);
}
// 0 a
// 1 b
// 2 c
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`for-of` iterates over the _values_ of any iterable - arrays, strings, Sets, Maps, and generators. It's the modern default for sequential iteration.

</ExampleProse>
<ExampleCode>

```js
const colors = ["red", "green", "blue"];

for (const color of colors) {
  console.log(color);
}
// red
// green
// blue
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`for-in` iterates over the _keys_ of an object - including enumerable inherited properties. Avoid it on arrays; it can surface unexpected prototype keys and the order is not guaranteed.

</ExampleProse>
<ExampleCode>

```js
const user = { name: "Ana", role: "admin" };

for (const key in user) {
  console.log(key, user[key]);
}
// name Ana
// role admin
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`.forEach` passes each value to a callback but cannot be `break`-ed out of and cannot be awaited. `for-of` is safer in both situations.

</ExampleProse>
<ExampleCode>

```js
const ids = [1, 2, 3];

// WRONG - forEach does not await the async callback
ids.forEach(async (id) => {
  await saveToDb(id); // runs fire-and-forget
});

// CORRECT - sequential async iteration
for (const id of ids) {
  await saveToDb(id);
}

// CORRECT - parallel with bounded result collection
await Promise.all(ids.map((id) => saveToDb(id)));
```

</ExampleCode>
</ExamplePair>

<InProduction>
The `forEach` + `async` trap is one of the most common async bugs in Node.js codebases: the function returns immediately while the callbacks run in the background, so callers believe the work is done before it is. Use `for-of` with `await` for serial processing, or `Promise.all` with `.map` for parallel - and be explicit about which concurrency model you want. Unbounded `Promise.all` across 500 records can saturate a database connection pool just as effectively as a bug.
</InProduction>


for, for-of, for-in, forEach - which to use and why forEach can't be awaited.

Loops


Functions are the primary unit of reuse in JavaScript. How you declare them affects hoisting, `this` binding, and readability.

<ExamplePair>
<ExampleProse>

A **function declaration** is hoisted - the name and body are available before the line they appear on. A **function expression** is only available after the assignment is evaluated.

</ExampleProse>
<ExampleCode>

```js
// declaration - works before its definition line
greet("World"); // Hello, World

function greet(name) {
  console.log("Hello, " + name);
}

// expression - not hoisted; calling it before this line throws
const farewell = function (name) {
  console.log("Goodbye, " + name);
};
farewell("World"); // Goodbye, World
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Default parameters provide fallback values when an argument is `undefined`. They are evaluated at call time, not definition time.

</ExampleProse>
<ExampleCode>

```js
function connect(host = "localhost", port = 5432) {
  console.log(`${host}:${port}`);
}

connect();               // localhost:5432
connect("db.prod", 5433); // db.prod:5433
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The rest parameter (`...args`) collects all remaining arguments into a real array. It must be the last parameter.

</ExampleProse>
<ExampleCode>

```js
function sum(first, ...rest) {
  return rest.reduce((acc, n) => acc + n, first);
}

console.log(sum(1, 2, 3, 4)); // 10
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`this` inside a regular function is determined at call time - it is the object the function is called on, not where it was defined.

</ExampleProse>
<ExampleCode>

```js
const counter = {
  count: 0,
  increment() {
    this.count++;
    console.log(this.count);
  },
};

counter.increment(); // 1

const fn = counter.increment;
fn(); // TypeError in strict mode (this is undefined); NaN in sloppy mode (this is globalThis)
```

</ExampleCode>
</ExamplePair>

<InProduction>
Positional parameters past two or three make call-sites unreadable: `createUser("Ana", true, false, null, 3)` - what does each boolean mean? Destructure an options object instead: `createUser({ name, admin, verified, role, retries })`. It survives parameter reordering, makes call-sites self-documenting, and lets callers omit optional fields cleanly. Flag it in code review when you see more than three positional args.
</InProduction>


Declaration vs expression, hoisting, default params, rest params, and dynamic `this`.

Functions


Arrow functions are a compact function syntax that captures `this` from the surrounding scope instead of binding it dynamically.

<ExamplePair>
<ExampleProse>

The basic arrow syntax removes the `function` keyword. Parentheses around a single parameter are optional; a single-expression body can omit braces and `return`.

</ExampleProse>
<ExampleCode>

```js
// Traditional expression
const double = function (n) {
  return n * 2;
};

// Arrow - equivalent
const triple = (n) => n * 3;

// Multi-statement body still needs braces and return
const clamp = (n, min, max) => {
  if (n < min) return min;
  if (n > max) return max;
  return n;
};

console.log(double(5));       // 10
console.log(triple(5));       // 15
console.log(clamp(12, 0, 10)); // 10
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Arrow functions capture `this` lexically - from the enclosing scope at definition time, not from the caller. This makes them ideal as callbacks inside methods.

</ExampleProse>
<ExampleCode>

```js
class Timer {
  constructor() {
    this.seconds = 0;
  }

  start() {
    // Arrow function: `this` is the Timer instance
    setInterval(() => {
      this.seconds++;
      console.log(this.seconds);
    }, 1000);
  }
}

// With a regular function, `this` would be undefined (strict mode)
// or the global object - the classic setTimeout/setInterval trap.
const t = new Timer();
t.start(); // 1, 2, 3 ...
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Arrow functions cannot be used as constructors, and they have no `arguments` object. They also cannot be generator functions.

</ExampleProse>
<ExampleCode>

```js
const Foo = () => {};
// new Foo(); // TypeError: Foo is not a constructor

// Arrow functions have no `arguments` - use rest params instead
const sum = (...nums) => nums.reduce((a, b) => a + b, 0);
console.log(sum(1, 2, 3)); // 6
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Object method shorthand (or a regular `function`) is the right choice when the method needs to reference the owning object via `this`. An arrow method silently captures the wrong `this`.

</ExampleProse>
<ExampleCode>

```js
const counter = {
  count: 0,

  // WRONG - arrow captures `this` from module scope, not the object
  badIncrement: () => {
    counter.count++; // forced to reference by name - fragile
  },

  // CORRECT - method shorthand binds `this` to the receiver
  increment() {
    this.count++;
  },
};

counter.increment();
console.log(counter.count); // 1
```

</ExampleCode>
</ExamplePair>

<InProduction>
Arrow functions cannot be used as object methods when the method needs dynamic `this` (the owning object), cannot be constructors, and cannot be generators. Use arrow functions for callbacks, array method predicates, and any inner function that should inherit `this` from the surrounding method. Use the `function` keyword (or method shorthand) for anything that defines its own `this` - class methods, Express route handlers that rely on `this`, and generator functions. Mixing the two up is one of the quietest sources of `undefined is not an object` errors in production.
</InProduction>


Shorter syntax and lexical `this` - plus when arrow functions are the wrong choice.

Arrow Functions


A closure is a function bundled together with the variables from its surrounding lexical scope. Every function in JavaScript is a closure - the interesting cases are when that function outlives its defining scope.

<ExamplePair>
<ExampleProse>

A counter factory returns a function that captures a private `count` variable. Each call to `makeCounter` creates an independent `count` - callers cannot access or reset it directly.

</ExampleProse>
<ExampleCode>

```js
function makeCounter(start = 0) {
  let count = start;
  return function () {
    count++;
    return count;
  };
}

const a = makeCounter();
const b = makeCounter(10);

console.log(a()); // 1
console.log(a()); // 2
console.log(b()); // 11
console.log(a()); // 3 - independent of b
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Closures are the natural fit for memoization: a wrapper function closes over a `Map` to cache expensive results without exposing the cache to callers.

</ExampleProse>
<ExampleCode>

```js
function memoize(fn) {
  const cache = new Map();
  return function (...args) {
    const key = JSON.stringify(args);
    if (cache.has(key)) return cache.get(key);
    const result = fn(...args);
    cache.set(key, result);
    return result;
  };
}

function slowSquare(n) {
  // simulate expensive work
  return n * n;
}

const fastSquare = memoize(slowSquare);
console.log(fastSquare(4));  // 16 (computed)
console.log(fastSquare(4));  // 16 (cached)
console.log(fastSquare(5));  // 25 (computed)
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The module pattern uses an IIFE to create a private scope and return only the public API - a lightweight alternative to ES modules when you need to hide implementation details in a single file.

</ExampleProse>
<ExampleCode>

```js
const cart = (() => {
  const items = [];

  return {
    add(item) {
      items.push(item);
    },
    remove(name) {
      const idx = items.findIndex((i) => i.name === name);
      if (idx !== -1) items.splice(idx, 1);
    },
    total() {
      return items.reduce((sum, i) => sum + i.price, 0);
    },
  };
})();

cart.add({ name: "book", price: 12 });
cart.add({ name: "pen", price: 2 });
console.log(cart.total()); // 14
// `items` is not accessible from outside
```

</ExampleCode>
</ExamplePair>

<InProduction>
Closures that capture large objects keep those objects alive in memory for as long as the closure itself is reachable. In SPAs, this is a common leak source: an event handler attached to a button captures the entire component state or a large API response, and it stays in memory until the handler is explicitly removed. The fix is to copy only the field you need - `const id = user.id` - rather than closing over `user`. The same principle applies to Node.js request handlers that capture `req` inside a callback that persists beyond the request lifecycle.
</InProduction>


Functions that remember the variables from their defining scope - the backbone of private state, memoization, and the module pattern.

Closures


Arrays are ordered, zero-indexed lists. JavaScript's array methods let you transform, filter, and aggregate them without mutation - most of the time.

<ExamplePair>
<ExampleProse>

`map` transforms each element into a new value and returns a new array. `filter` keeps elements that pass a predicate. Neither mutates the original.

</ExampleProse>
<ExampleCode>

```js
const prices = [10, 25, 8, 40, 15];

const doubled = prices.map((p) => p * 2);
console.log(doubled); // [20, 50, 16, 80, 30]

const affordable = prices.filter((p) => p < 20);
console.log(affordable); // [10, 8, 15]

// original is unchanged
console.log(prices); // [10, 25, 8, 40, 15]
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`reduce` accumulates elements into a single value - a sum, an object, another array. Always provide the initial accumulator to avoid surprising behavior on empty arrays.

</ExampleProse>
<ExampleCode>

```js
const orders = [
  { product: "book", qty: 2, price: 12 },
  { product: "pen", qty: 5, price: 1.5 },
  { product: "desk", qty: 1, price: 200 },
];

const total = orders.reduce((sum, o) => sum + o.qty * o.price, 0);
console.log(total); // 231.5

// Group by first letter - reduce into an object
const byLetter = ["apple", "avocado", "banana", "blueberry"].reduce(
  (acc, fruit) => {
    const key = fruit[0];
    acc[key] = acc[key] ?? [];
    acc[key].push(fruit);
    return acc;
  },
  {}
);
console.log(byLetter);
// { a: ['apple', 'avocado'], b: ['banana', 'blueberry'] }
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`find` returns the first matching element (or `undefined`). `some` and `every` return booleans. All three short-circuit on the first result.

</ExampleProse>
<ExampleCode>

```js
const users = [
  { id: 1, name: "Ana", admin: true },
  { id: 2, name: "Bo", admin: false },
  { id: 3, name: "Cal", admin: true },
];

const ana = users.find((u) => u.id === 1);
console.log(ana?.name); // Ana

console.log(users.some((u) => u.admin));  // true
console.log(users.every((u) => u.admin)); // false
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`.sort()` mutates the array in place and defaults to **lexicographic** (string) comparison - even for numbers. Always pass a comparator for numeric sorts.

</ExampleProse>
<ExampleCode>

```js
const nums = [10, 9, 2, 100, 21];

// WRONG - lexicographic sort
console.log([...nums].sort());
// [10, 100, 2, 21, 9]

// CORRECT - numeric comparator
console.log([...nums].sort((a, b) => a - b));
// [2, 9, 10, 21, 100]

// Sort mutates - spread first if you need the original
const sorted = [...nums].sort((a, b) => a - b);
console.log(nums);   // [10, 9, 2, 100, 21] - untouched
console.log(sorted); // [2, 9, 10, 21, 100]
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`flat` and `flatMap` handle nested arrays. `flat(depth)` flattens to the given depth; `flatMap` is equivalent to `map` followed by `flat(1)` and is more efficient.

</ExampleProse>
<ExampleCode>

```js
const matrix = [[1, 2], [3, 4], [5, 6]];
console.log(matrix.flat()); // [1, 2, 3, 4, 5, 6]

const sentences = ["hello world", "foo bar"];
const words = sentences.flatMap((s) => s.split(" "));
console.log(words); // ['hello', 'world', 'foo', 'bar']
```

</ExampleCode>
</ExamplePair>

<InProduction>
The default `.sort()` comparator converts elements to strings before comparing, so `[10, 9, 2, 100].sort()` produces `[10, 100, 2, 9]` - a bug that staging almost never catches because test data is usually small and already sorted. Always supply `(a, b) => a - b` for numbers. And because `.sort()` mutates the original array, teams that want the unsorted original must spread first: `[...arr].sort(...)`. Missing that spread is the second most common `.sort` bug, and it shows up in search and pagination code where the display order changes the underlying state.
</InProduction>


map, filter, reduce, and the rest of the essential array API - plus the sort default that bites everyone once.

Arrays


Objects are JavaScript's primary data structure: unordered key-value pairs where keys are strings (or symbols) and values can be anything.

<ExamplePair>
<ExampleProse>

Object literals support shorthand property names, computed keys, and method shorthand. These are purely syntactic - the runtime result is identical to the verbose form.

</ExampleProse>
<ExampleCode>

```js
const name = "Ada";
const score = 98;

// Shorthand: { name: name, score: score }
const user = { name, score };
console.log(user); // { name: 'Ada', score: 98 }

// Computed key
const field = "role";
const record = { [field]: "admin" };
console.log(record); // { role: 'admin' }

// Method shorthand
const counter = {
  count: 0,
  increment() {
    this.count++;
  },
};
counter.increment();
console.log(counter.count); // 1
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Destructuring extracts named properties into local variables. Nested destructuring and defaults work too. The spread operator copies enumerable own properties into a new object.

</ExampleProse>
<ExampleCode>

```js
const config = { host: "localhost", port: 5432, db: "main" };

// Destructure with rename and default
const { host, port: dbPort, ssl = false } = config;
console.log(host);   // localhost
console.log(dbPort); // 5432
console.log(ssl);    // false

// Spread: shallow copy with overrides
const devConfig = { ...config, port: 5433, db: "dev" };
console.log(devConfig);
// { host: 'localhost', port: 5433, db: 'dev' }

// Original untouched
console.log(config.port); // 5432
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`JSON.stringify` has three silent surprises: it drops `undefined` values and function properties, it throws on circular references, and `Date` objects become ISO strings (not re-parsed by `JSON.parse`).

</ExampleProse>
<ExampleCode>

```js
const data = {
  id: 1,
  name: "Alice",
  password: undefined,  // dropped
  greet() { return "hi"; }, // dropped
  created: new Date("2024-01-01"),
};

const json = JSON.stringify(data);
console.log(json);
// {"id":1,"name":"Alice","created":"2024-01-01T00:00:00.000Z"}

// Circular reference throws
const a = {};
a.self = a;
try {
  JSON.stringify(a);
} catch (e) {
  console.log(e.message); // Converting circular structure to JSON
}

// JSON.parse does NOT restore Date objects - you get a string
const parsed = JSON.parse(json);
console.log(typeof parsed.created); // string
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`Object.freeze` makes an object non-configurable and non-writable - but only one level deep. Nested objects are still mutable. `structuredClone` creates a true deep copy of most serializable values.

</ExampleProse>
<ExampleCode>

```js
const settings = Object.freeze({ theme: "dark", limits: { max: 10 } });

settings.theme = "light"; // silently ignored (strict mode throws)
console.log(settings.theme); // dark - unchanged

settings.limits.max = 999; // nested object is NOT frozen
console.log(settings.limits.max); // 999

// Deep copy with structuredClone (Node 17+, modern browsers)
const original = { user: { name: "Bo", tags: ["a", "b"] } };
const copy = structuredClone(original);
copy.user.name = "Cal";
console.log(original.user.name); // Bo - truly independent
```

</ExampleCode>
</ExamplePair>

<InProduction>
The spread operator `{...obj}` copies only the top-level properties - nested objects are still shared by reference. Teams that treat spread as a deep clone and then mutate a nested field discover the bug when two callers observe each other's changes. For truly independent copies, use `structuredClone` (available in Node 17+ and modern browsers) or a library like Immer for immutable update patterns. TypeScript's `Readonly<T>` and `as const` give compile-time protection but do nothing at runtime - they catch the mistake in code review, not in production.
</InProduction>


Literals, shorthand, computed keys, spread, destructuring, and JSON serialization quirks.

Objects


A `Promise` represents a value that will be available in the future. `async`/`await` is syntactic sugar over promises - every `async` function returns a `Promise` and `await` unwraps one.

<ExamplePair>
<ExampleProse>

`async`/`await` lets you write asynchronous code that reads like synchronous code. Wrap `await` calls in `try/catch` to handle rejections - unhandled rejections terminate the process in Node 15+.

</ExampleProse>
<ExampleCode>

```js
async function fetchUser(id) {
  const res = await fetch(`https://api.example.com/users/${id}`);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

async function main() {
  try {
    const user = await fetchUser(1);
    console.log(user.name);
  } catch (err) {
    console.error("Failed:", err.message);
  }
}

main();
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`Promise.all` runs promises in parallel and resolves when all fulfill - or rejects immediately on the first rejection. `Promise.allSettled` waits for every promise regardless of outcome, which is safer when you need all results and partial failure is acceptable.

</ExampleProse>
<ExampleCode>

```js
async function parallel() {
  // All three fetch concurrently - total time ≈ slowest individual request
  const [users, posts, tags] = await Promise.all([
    fetch("/api/users").then((r) => r.json()),
    fetch("/api/posts").then((r) => r.json()),
    fetch("/api/tags").then((r) => r.json()),
  ]);
  console.log(users.length, posts.length, tags.length);
}

// allSettled: never short-circuits, gives you {status, value/reason} per promise
async function safeParallel(ids) {
  const results = await Promise.allSettled(ids.map((id) => fetchUser(id)));
  const succeeded = results
    .filter((r) => r.status === "fulfilled")
    .map((r) => r.value);
  const failed = results.filter((r) => r.status === "rejected");
  console.log(`${succeeded.length} ok, ${failed.length} failed`);
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`await` inside a `for-of` loop runs iterations **serially** - each waits for the previous to finish. `Promise.all` with `.map` runs them in **parallel**. Know which you want.

</ExampleProse>
<ExampleCode>

```js
const ids = [1, 2, 3, 4, 5];

// SERIAL - each request waits for the previous one
// Total time ≈ sum of all request times
async function serial() {
  for (const id of ids) {
    const user = await fetchUser(id);
    console.log(user.name);
  }
}

// PARALLEL - all requests in flight at once
// Total time ≈ slowest single request
async function parallel() {
  const users = await Promise.all(ids.map((id) => fetchUser(id)));
  users.forEach((u) => console.log(u.name));
}

// forEach CANNOT be awaited - the async callbacks fire and are ignored
async function broken() {
  ids.forEach(async (id) => {
    const user = await fetchUser(id); // awaited inside, but forEach doesn't wait
    console.log(user.name);
  });
  // this line runs before any user is fetched
  console.log("done?"); // prints immediately
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`Promise.race` resolves or rejects as soon as **any** promise settles. It's commonly used to implement timeouts. `Promise.any` resolves on the first **fulfilled** promise (ignoring rejections), useful for racing redundant requests.

</ExampleProse>
<ExampleCode>

```js
function withTimeout(promise, ms) {
  const timeout = new Promise((_, reject) =>
    setTimeout(() => reject(new Error(`Timed out after ${ms}ms`)), ms)
  );
  return Promise.race([promise, timeout]);
}

async function main() {
  try {
    const user = await withTimeout(fetchUser(1), 3000);
    console.log(user.name);
  } catch (err) {
    console.error(err.message); // "Timed out after 3000ms" if slow
  }
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
`Promise.all` with an unbounded array is parallelism-by-accident. A service that maps over 500 IDs and fires all requests at once can exhaust a database connection pool or trigger rate limiting before the first response lands. The fix is bounded concurrency: libraries like [`p-limit`](https://github.com/sindresorhus/p-limit) let you specify a max-in-flight count, or you can implement a manual semaphore. The same applies to writes - a batch import that fans out 1 000 parallel inserts is a self-inflicted DoS. Always ask whether you need serial, bounded-parallel, or fully-parallel, and set an explicit limit for the latter two. See also the [idempotency key](/patterns/idempotency-key) pattern when retrying failed async operations is in scope.
</InProduction>


Async control flow with Promise combinators and async/await - plus the concurrency trap that knocks over databases.

Promises and async/await


ES modules give JavaScript first-class support for splitting code across files. Each file is its own module with a private scope - only what you explicitly export is visible to importers.

<ExamplePair>
<ExampleProse>

**Named exports** are the workhorse of ES modules. A file can export any number of named bindings; importers pick what they need. Names are fixed - renaming at the import site uses `as`.

</ExampleProse>
<ExampleCode>

```js
// math.js
export function add(a, b) { return a + b; }
export function multiply(a, b) { return a * b; }
export const PI = 3.14159;

// main.js
import { add, PI } from "./math.js";
import { multiply as mul } from "./math.js";

console.log(add(2, 3));  // 5
console.log(PI);         // 3.14159
console.log(mul(4, 5));  // 20

// Import everything under a namespace
import * as math from "./math.js";
console.log(math.add(1, 1)); // 2
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

**Default exports** let a module export one primary value. Importers choose the local name freely - no braces required. A module can have both a default export and named exports.

</ExampleProse>
<ExampleCode>

```js
// logger.js
export default function log(msg) {
  console.log(`[LOG] ${msg}`);
}
export const LOG_LEVEL = "info";

// app.js
import log, { LOG_LEVEL } from "./logger.js";
// The importer chose "log" - could have been "writeLog", "print", anything

log("server started");     // [LOG] server started
console.log(LOG_LEVEL);    // info
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Circular imports - where A imports B and B imports A - are allowed by the spec but produce `undefined` for bindings that haven't been initialised yet at the point of import. The fix is to extract the shared code into a third module.

</ExampleProse>
<ExampleCode>

```js
// a.js
import { b } from "./b.js";
export const a = "a";
console.log("in a, b is:", b); // "b" - b.js finished evaluating before this line

// b.js
import { a } from "./a.js";
export const b = "b";
console.log("in b, a is:", a); // undefined - a.js hasn't finished evaluating yet

// The order matters and is hard to predict at scale.
// Solution: move shared exports to shared.js and import from there.
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

**CJS/ESM interop**: Node.js defaults to CommonJS (`require`). To use ES modules, either name the file `.mjs` or add `"type": "module"` to `package.json`. Dynamic `import()` works in both module systems and is the bridge when you need to load an ESM module from CJS code.

</ExampleProse>
<ExampleCode>

```js
// package.json: { "type": "module" } - all .js files are ESM

// Static import - resolved at parse time, hoisted, cannot be conditional
import { add } from "./math.js";

// Dynamic import - returns a Promise, works anywhere, can be conditional
async function loadPlugin(name) {
  if (name === "math") {
    const { add } = await import("./math.js");
    return add;
  }
}

// In a CJS file (.cjs or without "type":"module"), use dynamic import
// to load ESM-only packages
async function main() {
  const { default: chalk } = await import("chalk"); // chalk v5+ is ESM-only
  console.log(chalk.green("hello"));
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Default exports look convenient but they hurt refactor safety in shared code: the import name is chosen by the importer, not the author, so automated renames don't propagate and static analysis tools can't reliably track usage. A library that exports `default function process()` will be imported as `doThing`, `handleIt`, and `runProcess` across a large codebase - you lose the single source of truth that named exports provide. Reserve default exports for app-level files where one file represents one feature or page; use named exports everywhere else. Most team style guides (Airbnb, Google) enforce this and so do many ESLint rules.
</InProduction>


ES module import/export, default vs named exports, circular imports, and CJS interop.

Modules


A boolean is one of two values: `true` or `false`. Comparisons (`===`, `<`, `>=`) and logical operators (`&&`, `||`, `!`) produce booleans, so they show up everywhere even when you don't declare them explicitly.

<ExamplePair>
<ExampleProse>

Boolean literals are `true` and `false`. `typeof` confirms the type. Comparison expressions evaluate to a boolean you can store or pass like any other value.

</ExampleProse>
<ExampleCode>

```js
const isLoggedIn = true;
const hasErrors = false;

console.log(typeof isLoggedIn); // "boolean"

const age = 20;
const isAdult = age >= 18;
console.log(isAdult); // true

const name = "Alice";
const isEmpty = name === "";
console.log(isEmpty); // false
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

JavaScript has exactly eight falsy values: `false`, `0`, `-0`, `0n`, `""`, `null`, `undefined`, and `NaN`. Everything else is truthy. `Boolean(x)` converts any value to its boolean equivalent, which is what an `if` statement does internally.

</ExampleProse>
<ExampleCode>

```js
// All eight falsy values
console.log(Boolean(false));     // false
console.log(Boolean(0));         // false
console.log(Boolean(-0));        // false
console.log(Boolean(0n));        // false
console.log(Boolean(""));        // false
console.log(Boolean(null));      // false
console.log(Boolean(undefined)); // false
console.log(Boolean(NaN));       // false

// Everything else is truthy
console.log(Boolean("0"));   // true  - non-empty string
console.log(Boolean([]));    // true  - empty array
console.log(Boolean({}));    // true  - empty object
console.log(Boolean(-1));    // true  - non-zero number
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`==` (loose equality) coerces both sides to the same type before comparing, producing results that surprise almost everyone. `===` (strict equality) never coerces: different types are never equal. Prefer `===` everywhere.

</ExampleProse>
<ExampleCode>

```js
// Loose equality surprises
console.log(0 == false);         // true  (0 coerces to false)
console.log("" == false);        // true  ("" coerces to 0, false to 0)
console.log(null == undefined);  // true  (special case in the spec)
console.log("1" == 1);           // true  (string coerced to number)

// Strict equality - type must match
console.log(0 === false);        // false
console.log("" === false);       // false
console.log(null === undefined); // false
console.log("1" === 1);          // false
```

</ExampleCode>
</ExamplePair>

<InProduction>
Always use `===` and `!==`. The loose equality coercion table (`0 == false`, `"" == false`, `null == undefined`) is not intuitive and produces bugs that are hard to spot in code review. Most ESLint configs include the `eqeqeq` rule that bans `==` outright. Teams that skip it eventually ship a bug where an empty string or zero is treated as falsy in a place that should only treat `null`/`undefined` that way.
</InProduction>


The true/false type - including the eight falsy values, truthy coercion, and why == is a trap you should never step in.

Booleans


A higher-order function is a function that takes another function as an argument, returns one, or both. JavaScript treats functions as values that can be stored, passed, and returned like numbers or strings. That's the whole feature.

<ExamplePair>
<ExampleProse>

Passing a callback to a higher-order function is the most common pattern. Array methods like `map`, `filter`, and `forEach` are built-in higher-order functions. The callback you pass is just a value.

</ExampleProse>
<ExampleCode>

```js
const numbers = [1, 2, 3, 4, 5];

// Passing an arrow function as a callback
const doubled = numbers.map((n) => n * 2);
console.log(doubled); // [2, 4, 6, 8, 10]

// The callback is a value - you can store it first
const isEven = (n) => n % 2 === 0;
const evens = numbers.filter(isEven);
console.log(evens); // [2, 4]

// setTimeout is a higher-order function too
setTimeout(() => console.log("done"), 0);
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A function can return another function. This pattern is called a factory or a closure. Each call to the outer function produces an independent inner function with its own captured variables.

</ExampleProse>
<ExampleCode>

```js
function multiplier(factor) {
  return (x) => x * factor;
}

const double = multiplier(2);
const triple = multiplier(3);

console.log(double(5));  // 10
console.log(triple(5));  // 15
console.log(double(10)); // 20

// Each function independently remembers its factor
const taxes = [100, 250, 80].map(multiplier(1.2));
console.log(taxes); // [120, 300, 96]
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Array methods pass three arguments to every callback: the current element, its index, and the full array. Passing a function directly as a callback works fine when it only uses the first argument. Problems appear when it reads more.

</ExampleProse>
<ExampleCode>

```js
// This looks fine but breaks
const result = ["1", "2", "3"].map(parseInt);
console.log(result); // [1, NaN, NaN]

// Why: map calls parseInt(element, index, array)
// parseInt("1", 0) = 1   (radix 0 treated as 10)
// parseInt("2", 1) = NaN (radix 1 is invalid)
// parseInt("3", 2) = NaN (radix 2, "3" is not binary)

// Fix: wrap so only the element is forwarded
const correct = ["1", "2", "3"].map((s) => parseInt(s, 10));
console.log(correct); // [1, 2, 3]

// Same issue with Number - but Number ignores extra args, so it's safe
const nums = ["1", "2", "3"].map(Number);
console.log(nums); // [1, 2, 3]
```

</ExampleCode>
</ExamplePair>

<InProduction>
Callback signatures are a contract. When an array method passes `(value, index, array)` and your callback reads more arguments than intended, you get silent misbehavior rather than an error. The `parseInt` example above is the classic case, but the same bug can appear with any multi-parameter function. Wrapping in an arrow (`(s) => fn(s)`) makes the intent explicit and breaks the coupling. TypeScript makes this class of bug impossible: it will flag a signature mismatch at compile time.
</InProduction>


Functions that accept or return other functions - the pattern behind map, filter, and every event listener you've ever written.

Higher-Order Functions and Callbacks


A recursive function is one that calls itself. Every recursion needs a base case (the condition where the function stops calling itself) and a recursive step that shrinks the problem toward that base case.

<ExamplePair>
<ExampleProse>

Factorial is the textbook example. The base case is `n <= 1` (return 1). The recursive step multiplies `n` by the factorial of `n - 1`, which is a smaller version of the same problem.

</ExampleProse>
<ExampleCode>

```js
function factorial(n) {
  if (n <= 1) return 1;       // base case: stop here
  return n * factorial(n - 1); // recursive step: smaller problem
}

console.log(factorial(1)); // 1
console.log(factorial(4)); // 24  (4 * 3 * 2 * 1)
console.log(factorial(6)); // 720

// Call stack for factorial(4):
// factorial(4) -> 4 * factorial(3)
//                     -> 3 * factorial(2)
//                            -> 2 * factorial(1)
//                                   -> 1  (base case)
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Recursion is the natural shape for traversing nested structures like trees or deeply nested objects. Each level of nesting becomes one level of recursion. An iterative loop would need to track depth manually.

</ExampleProse>
<ExampleCode>

```js
const fileTree = {
  name: "src",
  children: [
    { name: "index.js", children: [] },
    {
      name: "utils",
      children: [
        { name: "math.js", children: [] },
        { name: "string.js", children: [] },
      ],
    },
  ],
};

function printTree(node, depth = 0) {
  const indent = "  ".repeat(depth);
  console.log(indent + node.name);
  for (const child of node.children) {
    printTree(child, depth + 1); // same function, smaller problem
  }
}

printTree(fileTree);
// src
//   index.js
//   utils
//     math.js
//     string.js
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

For bounded inputs, an iterative loop and a recursive function are equally readable. The loop version avoids function call overhead and is sometimes clearer when the problem is simply counting down.

</ExampleProse>
<ExampleCode>

```js
// Recursive factorial
function factorialRecursive(n) {
  if (n <= 1) return 1;
  return n * factorialRecursive(n - 1);
}

// Iterative equivalent - no stack frames, same result
function factorialIterative(n) {
  let result = 1;
  for (let i = 2; i <= n; i++) {
    result *= i;
  }
  return result;
}

console.log(factorialRecursive(6));  // 720
console.log(factorialIterative(6));  // 720
```

</ExampleCode>
</ExamplePair>

<InProduction>
V8 does not optimize tail calls, so every recursive call adds a stack frame. In practice, Node.js and most browsers throw a `RangeError: Maximum call stack size exceeded` at around 10,000 to 15,000 frames. If the input comes from a user (a deeply nested JSON document, a large file tree, user-submitted HTML), recursion will blow the stack. Convert to an iterative approach using an explicit stack (`const stack = [root]; while (stack.length) { ... }`) whenever depth is unbounded. Recursion is safe for compile-time-bounded structures like AST visitors over a grammar you control.
</InProduction>


Functions that call themselves - the natural fit for tree traversal, with a hard stack limit that matters on user-supplied data.

Recursion


`Map` is a keyed collection where keys can be any value, not just strings. `Set` is a collection of unique values where duplicates are ignored automatically. Plain objects coerce all keys to strings; arrays don't deduplicate. Both are built into modern JavaScript.

<ExamplePair>
<ExampleProse>

`Map` works like a dictionary. You add entries with `.set(key, value)`, retrieve them with `.get(key)`, and check for a key with `.has(key)`. Iteration follows insertion order, which plain objects don't guarantee on all runtimes.

</ExampleProse>
<ExampleCode>

```js
const scores = new Map();

scores.set("alice", 95);
scores.set("bob", 87);
scores.set("carol", 92);

console.log(scores.get("alice")); // 95
console.log(scores.has("bob"));   // true
console.log(scores.has("dave"));  // false
console.log(scores.size);         // 3

// Iteration order matches insertion order
for (const [name, score] of scores) {
  console.log(`${name}: ${score}`);
}
// alice: 95
// bob: 87
// carol: 92
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`Map` accepts any value as a key, including objects, functions, and even `NaN`. A plain object coerces every key to a string, so using an object as a key silently collapses all such keys to `"[object Object]"`.

</ExampleProse>
<ExampleCode>

```js
const userCache = new Map();

const user1 = { id: 1, name: "Alice" };
const user2 = { id: 2, name: "Bob" };

userCache.set(user1, { lastSeen: "2026-04-27" });
userCache.set(user2, { lastSeen: "2026-04-26" });

console.log(userCache.get(user1)); // { lastSeen: "2026-04-27" }
console.log(userCache.get(user2)); // { lastSeen: "2026-04-26" }

// The same attempt on a plain object
const plainObj = {};
plainObj[user1] = "alice data";
plainObj[user2] = "bob data";

// Both keys stringify to "[object Object]" and clobber each other
console.log(Object.keys(plainObj)); // ["[object Object]"]
console.log(plainObj[user1]);       // "bob data" - wrong
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`Set` stores unique values in insertion order. Adding a duplicate is silently ignored. Spreading a `Set` back into an array (`[...new Set(arr)]`) is the shortest idiom for deduplicating.

</ExampleProse>
<ExampleCode>

```js
const tags = new Set();

tags.add("javascript");
tags.add("web");
tags.add("javascript"); // duplicate - ignored
tags.add("node");

console.log(tags.size);              // 3
console.log(tags.has("javascript")); // true
console.log(tags.has("python"));     // false

tags.delete("web");
console.log([...tags]); // ["javascript", "node"]

// One-liner dedup of an array
const nums = [1, 2, 3, 2, 1, 4];
const unique = [...new Set(nums)];
console.log(unique); // [1, 2, 3, 4]
```

</ExampleCode>
</ExamplePair>

<InProduction>
Reach for `Map` whenever keys aren't string literals or insertion order matters, and reach for `Set` whenever you'd otherwise write `arr.includes(x)` inside a loop (a linear scan each call). A `Set.has()` check is O(1). Plain objects also walk the prototype chain, so keys like `toString` or `constructor` collide with inherited properties - `Map` has no such issue.
</InProduction>


Keyed collections that accept any value as a key (Map) and deduplicated collections (Set) - when to reach for them instead of plain objects and arrays.

Maps and Sets


`Date` represents a single moment in time as the number of milliseconds since January 1, 1970 UTC (the Unix epoch). The object itself carries no timezone. The browser or runtime locale is only applied when you format the date as human-readable text.

<ExamplePair>
<ExampleProse>

You create a `Date` with `new Date()` for the current moment, `new Date(milliseconds)` for a specific instant, or `new Date("YYYY-MM-DD")` for an ISO date string. ISO 8601 strings are safe to parse across environments. Locale-formatted strings like `"April 27, 2026"` are not. `.getTime()` returns the raw epoch millisecond value.

</ExampleProse>
<ExampleCode>

```js
const now = new Date();
console.log(now);              // e.g. 2026-04-27T12:34:56.789Z

const fromMs = new Date(0);
console.log(fromMs);           // 1970-01-01T00:00:00.000Z

const fromISO = new Date("2026-04-27");
console.log(fromISO.getTime()); // epoch milliseconds for that date

// Avoid locale-formatted strings - parsing varies by runtime
const risky = new Date("April 27, 2026"); // not reliable everywhere
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`<` and `>` work between two `Date` objects because JavaScript coerces them to numbers (epoch ms) for the comparison. `===` does not work for equality because it compares object identity. Two separate `Date` objects representing the same moment are never `===` each other.

</ExampleProse>
<ExampleCode>

```js
const a = new Date("2026-04-27");
const b = new Date("2026-04-27");

console.log(a === b); // false - different objects in memory
console.log(a < b);   // false
console.log(a > b);   // false

// Compare for equality using epoch milliseconds
console.log(a.getTime() === b.getTime()); // true

const later = new Date("2026-12-31");
console.log(a < later); // true
console.log(a > later); // false
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`Intl.DateTimeFormat` formats a date for a specific locale and timezone - use it for what users read. `.toISOString()` produces a UTC string that is safe for storage, logs, and APIs. The two serve different purposes: one for humans, one for machines.

</ExampleProse>
<ExampleCode>

```js
const date = new Date("2026-04-27T15:30:00Z");

// For users: locale-aware output
const formatter = new Intl.DateTimeFormat("en-US", {
  year: "numeric",
  month: "long",
  day: "numeric",
  timeZone: "America/New_York",
});
console.log(formatter.format(date)); // "April 27, 2026"

// Short form
console.log(date.toLocaleDateString("en-US")); // "4/27/2026"

// For storage and APIs: UTC, always consistent
console.log(date.toISOString()); // "2026-04-27T15:30:00.000Z"
```

</ExampleCode>
</ExamplePair>

<InProduction>
Store epoch milliseconds or ISO strings in databases and APIs, never wall-clock strings like `"April 27, 2026"` - those are ambiguous outside the locale that produced them. `Date` is mutable, and `===` between two instances is always `false`, so treat dates as values you compare with `.getTime()`. For anything beyond rendering today's date (date arithmetic, relative formatting, timezone logic) reach for date-fns or Luxon, or wait for the `Temporal` API once your runtime ships it.
</InProduction>


Creating, comparing, and formatting dates with the built-in Date object, and why you should store epoch milliseconds or ISO strings and format at the edge.

Dates


`class` is syntactic sugar over JavaScript's prototype system. Each instance gets methods shared on the prototype, and `this` inside a method refers to whatever object the method was called on - not where the method was defined. That distinction is the source of most class-related bugs.

<ExamplePair>
<ExampleProse>

A class groups related state and behavior. The `constructor` runs when you call `new` and sets up instance properties. Methods are defined in the class body and are available on every instance through the shared prototype.

</ExampleProse>
<ExampleCode>

```js
class Counter {
  constructor(start = 0) {
    this.count = start;
  }

  increment() {
    this.count += 1;
  }

  decrement() {
    this.count -= 1;
  }

  value() {
    return this.count;
  }
}

const c = new Counter();
c.increment();
c.increment();
c.increment();
c.decrement();
console.log(c.value()); // 2

const c2 = new Counter(10);
c2.increment();
console.log(c2.value()); // 11
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`this` is bound at the call site. Pulling a method off an instance and calling it as a plain function loses the binding. Classes always run in strict mode, so `this` becomes `undefined` (not `window`) and the call throws.

</ExampleProse>
<ExampleCode>

```js
class Counter {
  constructor() {
    this.count = 0;
  }

  increment() {
    this.count += 1; // 'this' depends on how this function is called
  }
}

const c = new Counter();
c.increment();        // works - this === c
console.log(c.count); // 1

// Detach the method from its object
const inc = c.increment;
inc(); // TypeError: Cannot set properties of undefined

// The same problem arises when passing a method as a callback
setTimeout(c.increment, 100); // this is undefined inside increment
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Three patterns fix the lost binding. Each has a different trade-off: binding in the constructor is compatible everywhere; class-field arrows are the modern default; wrapping at the call site is a one-off fix when you don't control the class.

</ExampleProse>
<ExampleCode>

```js
// Fix 1: bind in the constructor (works in all environments)
class Counter1 {
  constructor() {
    this.count = 0;
    this.increment = this.increment.bind(this);
  }
  increment() { this.count += 1; }
}

// Fix 2: class field arrow (modern - arrow captures this at construction)
class Counter2 {
  count = 0;
  increment = () => { this.count += 1; };
}

// Fix 3: wrap at the call site (one-off, doesn't fix the class itself)
class Counter3 {
  constructor() { this.count = 0; }
  increment() { this.count += 1; }
}

const c1 = new Counter1();
const inc1 = c1.increment;
inc1(); // works
console.log(c1.count); // 1

const c2 = new Counter2();
const inc2 = c2.increment;
inc2(); // works
console.log(c2.count); // 1

const c3 = new Counter3();
setTimeout(() => c3.increment(), 100); // works - arrow at call site
```

</ExampleCode>
</ExamplePair>

<InProduction>
`this` is bound at the call site, not the definition site. The moment a method is passed as a callback the binding is gone. The class-field arrow (`increment = () => { ... }`) is the modern fix and requires no extra thought at every call site. Use `.bind(this)` in the constructor for environments or codebases that avoid class fields. Wrapping in an arrow at the call site patches the symptom without fixing the class.
</InProduction>


The class syntax, prototype-based inheritance under the hood, and the this-rebinding bug that breaks methods the moment they are passed as callbacks.

Classes and `this`


The DOM (Document Object Model) is the live object representation of the HTML page that the browser builds when it parses HTML. JavaScript reads and mutates that tree to update the UI. This lesson runs in a browser; the earlier lessons run anywhere JavaScript runs.

<ExamplePair>
<ExampleProse>

`document.querySelector` finds the first element that matches a CSS selector. `querySelectorAll` returns a NodeList (not a true Array) of all matching elements. Convert a NodeList to an Array with `Array.from` when you need array methods like `.map` or `.filter`.

</ExampleProse>
<ExampleCode>

```js
// Select a single element
const heading = document.querySelector("h1");
console.log(heading.textContent); // "Hello, world"

// Select multiple elements
const items = document.querySelectorAll("ul li");
console.log(items.length); // 3 (a NodeList)

// Convert to Array to use array methods
const texts = Array.from(items).map((li) => li.textContent);
console.log(texts); // ["Item 1", "Item 2", "Item 3"]
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`textContent` reads or replaces all text inside an element. `classList` lets you add, remove, and toggle CSS classes without touching the full `className` string. `dataset` exposes `data-*` attributes as a plain object.

</ExampleProse>
<ExampleCode>

```js
const card = document.querySelector(".card");

// Read and write text
console.log(card.textContent); // "Original text"
card.textContent = "Updated text";

// Toggle a CSS class
card.classList.add("is-active");
card.classList.remove("is-hidden");
card.classList.toggle("is-highlighted"); // adds if absent, removes if present
console.log(card.classList.contains("is-active")); // true

// Access data attributes (data-user-id="42" in HTML)
console.log(card.dataset.userId); // "42"
card.dataset.userId = "99"; // sets data-user-id="99"
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`document.createElement` creates a new element in memory. `.append` inserts it into the DOM. `.remove` takes an element out. This is the safe way to add dynamic content - unlike `innerHTML`, it never interprets the content as markup.

</ExampleProse>
<ExampleCode>

```js
const list = document.querySelector("ul");

// Create a new list item and insert it
const newItem = document.createElement("li");
newItem.textContent = "New item";  // safe: treated as text, not HTML
list.append(newItem);

// Insert before an existing element
const firstItem = list.querySelector("li");
list.insertBefore(newItem, firstItem);

// Remove an element
firstItem.remove();

// DANGER: innerHTML with user data is XSS
// list.innerHTML = userInput; // never do this
// SAFE alternative:
const safe = document.createElement("li");
safe.textContent = userInput; // treated as plain text
list.append(safe);
```

</ExampleCode>
</ExamplePair>

<InProduction>
`innerHTML` with any user-supplied data is XSS (cross-site scripting) by default. A string like `<img src=x onerror="stealCookies()">` becomes a live script the moment it hits `innerHTML`. Prefer `textContent` for plain text and `createElement` + `append` for structure. In hot loops (like rendering a long list on scroll), cache the node reference outside the loop. `querySelector` runs a full CSS-selector match every call and is not free.
</InProduction>


How JavaScript reads and mutates the live HTML tree - selecting nodes, changing content and classes, and creating elements safely without opening an XSS hole.

DOM Manipulation


Events are how the browser tells your code that something happened: a click, a key press, a form submission, a window resize. You attach a listener function with `addEventListener` and the browser calls it with an `event` object that describes what happened. This lesson runs in a browser; the earlier lessons run anywhere JavaScript runs.

<ExamplePair>
<ExampleProse>

`addEventListener` takes an event name and a handler function. The handler receives an `event` object. `event.target` is the element that was interacted with. `event.preventDefault()` stops the browser's default behavior - useful for links you want to handle in JavaScript without a page navigation.

</ExampleProse>
<ExampleCode>

```js
const button = document.querySelector("button");

button.addEventListener("click", (event) => {
  console.log("clicked:", event.target.textContent);
  // event.target is the element that was clicked
});

// Prevent default behavior (e.g. stop a link from navigating)
const link = document.querySelector("a.ajax-link");
link.addEventListener("click", (event) => {
  event.preventDefault();
  console.log("link click intercepted, no navigation");
  // handle it yourself instead
});
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The `input` event fires on every keystroke as the user types. The `change` event fires when the element loses focus (blur) after its value changed. Use `input` for live feedback and `change` for "finished editing" behavior.

</ExampleProse>
<ExampleCode>

```js
const field = document.querySelector("input[type='text']");

// Fires on every keystroke
field.addEventListener("input", (event) => {
  console.log("current value:", event.target.value);
});

// Fires once when the field loses focus and the value changed
field.addEventListener("change", (event) => {
  console.log("committed value:", event.target.value);
});
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`AbortController` is the modern way to remove a group of listeners at once. Pass the controller's `signal` to each `addEventListener` call, then call `controller.abort()` to remove them all. This is cleaner than tracking and calling `removeEventListener` for every single handler.

</ExampleProse>
<ExampleCode>

```js
function setupListeners(element) {
  const controller = new AbortController();
  const { signal } = controller;

  element.addEventListener("click", () => {
    console.log("clicked");
  }, { signal });

  element.addEventListener("keydown", (event) => {
    console.log("key pressed:", event.key);
  }, { signal });

  window.addEventListener("resize", () => {
    console.log("window resized");
  }, { signal });

  // Later: remove ALL listeners above with a single call
  function cleanup() {
    controller.abort();
  }

  return cleanup;
}

const removeAll = setupListeners(document.querySelector(".widget"));
// When the component is destroyed:
removeAll();
```

</ExampleCode>
</ExamplePair>

<InProduction>
A forgotten `removeEventListener` keeps the handler closure alive - along with everything the closure captures, including DOM nodes. This is one of the most common memory leak sources in single-page applications. Use an `AbortController` per component or lifecycle scope and call `.abort()` on teardown. The pattern pairs cleanly with framework cleanup hooks (React's `useEffect` return, Vue's `onUnmounted`).
</InProduction>


Attaching listeners, reading the event object, and cleaning up with AbortController to avoid the memory leaks that forgotten removeEventListener leaves behind.

Events


Form validation checks that user input meets your requirements before it is submitted. The browser handles common cases through HTML attributes alone; JavaScript steps in for cross-field rules, custom error messages, and live feedback. This lesson runs in a browser; the earlier lessons run anywhere JavaScript runs.

<ExamplePair>
<ExampleProse>

HTML provides built-in constraints through attributes like `required`, `type`, `minlength`, and `pattern`. The browser enforces them automatically when the form submits, shows native error bubbles, and exposes them via the `:invalid` CSS pseudo-class for styling.

</ExampleProse>
<ExampleCode>

```html
<form id="signup">
  <input
    type="email"
    name="email"
    required
    placeholder="you@example.com"
  />
  <input
    type="password"
    name="password"
    required
    minlength="8"
  />
  <button type="submit">Sign up</button>
</form>
```

```js
const form = document.querySelector("#signup");

// Check validity programmatically without submitting
console.log(form.checkValidity()); // false if any constraint fails

// Access individual field validity state
const emailField = form.querySelector("input[type='email']");
console.log(emailField.validity.valueMissing);   // true if empty
console.log(emailField.validity.typeMismatch);   // true if not a valid email
```

```css
/* Style invalid fields after the user interacts (not on page load) */
input:user-invalid {
  border-color: red;
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`setCustomValidity` lets you inject your own error message into the browser's built-in validity system. Call it with a non-empty string to mark a field invalid, then call `reportValidity()` to show the error to the user. Clear it with an empty string once the field is valid again.

</ExampleProse>
<ExampleCode>

```js
const form = document.querySelector("#signup");
const password = form.querySelector("input[name='password']");
const confirm = form.querySelector("input[name='confirm']");

form.addEventListener("submit", (event) => {
  // Cross-field rule: passwords must match
  if (password.value !== confirm.value) {
    confirm.setCustomValidity("Passwords do not match.");
    confirm.reportValidity(); // shows the native error bubble
    event.preventDefault();   // stop the form from submitting
    return;
  }

  // Clear any previous custom error before submitting
  confirm.setCustomValidity("");
});
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Live validation gives instant feedback as the user types. Running it on every `input` event can feel aggressive, especially for fields like email where the address isn't complete mid-type. A short debounce (waiting for a pause in typing) avoids false errors.

</ExampleProse>
<ExampleCode>

```js
const emailField = document.querySelector("input[type='email']");
const errorEl = document.querySelector("#email-error");

let debounceTimer;

emailField.addEventListener("input", () => {
  clearTimeout(debounceTimer);

  debounceTimer = setTimeout(() => {
    if (emailField.validity.typeMismatch || emailField.validity.valueMissing) {
      errorEl.textContent = "Enter a valid email address.";
      emailField.setAttribute("aria-describedby", "email-error");
    } else {
      errorEl.textContent = "";
      emailField.removeAttribute("aria-describedby");
    }
  }, 400); // wait 400 ms after the user stops typing
});
```

</ExampleCode>
</ExamplePair>

<InProduction>
Client-side validation is a UX feature, not a security control. Any user can open the browser console, remove the `required` attribute, and submit whatever they want. The server must re-validate every input before acting on it. When displaying errors, place the message next to the failing field and connect it with `aria-describedby` so screen readers announce the error context. Never use `alert()` for validation feedback - it blocks the UI and is inaccessible.
</InProduction>


Checking user input before submission - HTML-native constraints, JavaScript custom messages, and the server-must-re-validate rule that client validation never replaces.

Form Validation

Accessibility (abbreviated "a11y") means a feature works for users who are blind, can't use a mouse, or navigate with a keyboard or screen reader. The web platform handles most of this automatically when you use semantic HTML and leave keyboard behavior intact. This lesson runs in a browser; the earlier lessons run anywhere JavaScript runs.

<ExamplePair>
<ExampleProse>

Semantic elements like `<button>`, `<a>`, and `<input>` are focusable by default, respond to keyboard events (Enter, Space), and are announced correctly by screen readers. A clickable `<div>` has none of that - you would have to re-implement all of it yourself, imperfectly.

</ExampleProse>
<ExampleCode>

```html

<button type="button" onclick="deleteItem()">Delete</button>


<div onclick="deleteItem()">Delete</div>
```

```js
// A keyboard user presses Tab to reach the button, then Enter or Space to activate it.
// The <div> version is never reachable via Tab and Enter does nothing.
// You would need tabindex="0", a keydown listener, and a role="button" to match
// what <button> gives you for free.
document.querySelector("div").addEventListener("keydown", (event) => {
  if (event.key === "Enter" || event.key === " ") {
    deleteItem(); // manually re-implementing what <button> already does
  }
});
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

When a DOM node is removed - say, deleting a list item - the keyboard focus disappears and jumps to `<body>`. The user loses their place in the page. Moving focus to the next logical target after the deletion keeps the experience coherent.

</ExampleProse>
<ExampleCode>

```js
function deleteItem(itemEl) {
  const list = itemEl.parentElement;
  const next = itemEl.nextElementSibling || itemEl.previousElementSibling;

  itemEl.remove();

  if (next) {
    // Move focus to the adjacent item so the user doesn't lose their place
    next.focus();
  } else {
    // List is empty - move focus to the list's container or a nearby heading
    list.closest("section")?.querySelector("h2")?.focus();
  }
}
```

```html

<ul>
  <li tabindex="-1">
    Task one <button onclick="deleteItem(this.parentElement)">Delete</button>
  </li>
  <li tabindex="-1">
    Task two <button onclick="deleteItem(this.parentElement)">Delete</button>
  </li>
</ul>
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Icon-only controls have no visible text for screen readers to announce. `aria-label` gives the control a name. `aria-describedby` points to a separate element that provides a longer description - useful for fields that need hint text or error messages.

</ExampleProse>
<ExampleCode>

```html

<button type="button" aria-label="Close dialog">
  <svg aria-hidden="true" focusable="false"></svg>
</button>


<label for="username">Username</label>
<input
  id="username"
  type="text"
  aria-describedby="username-hint"
/>
<p id="username-hint">3-20 characters; letters, numbers, and underscores only.</p>
```

```js
// Adding aria-describedby dynamically when a validation error appears
const input = document.querySelector("#username");
const errorEl = document.querySelector("#username-error");

function showError(message) {
  errorEl.textContent = message;
  input.setAttribute("aria-describedby", "username-error");
  input.setAttribute("aria-invalid", "true");
}

function clearError() {
  errorEl.textContent = "";
  input.removeAttribute("aria-describedby");
  input.removeAttribute("aria-invalid");
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
If a feature only works with a mouse, it ships broken - keyboard support is not optional, it is a legal requirement in many jurisdictions (WCAG 2.1 AA). Visible focus rings and semantic HTML solve 90% of accessibility problems; ARIA is the patch layer for cases where native semantics don't reach (custom dropdowns, date pickers). Reach for ARIA only after native elements fail you, because incorrect ARIA is worse than no ARIA.
</InProduction>

Making pages work for keyboard users and screen readers - semantic HTML first, focus management for dynamic changes, and ARIA as the patch layer when native elements fall short.

Accessibility Basics


`localStorage` and `sessionStorage` are key-value stores built into every browser. They let you persist data across page loads without a server. Both accept only strings as keys and values, and both are scoped to the current origin (the combination of protocol, hostname, and port). The difference: `localStorage` persists until you clear it; `sessionStorage` is wiped when the tab closes. This lesson runs in a browser; the earlier lessons run anywhere JavaScript runs.

<ExamplePair>
<ExampleProse>

The API is four methods: `setItem` to write, `getItem` to read, `removeItem` to delete one key, and `clear` to delete everything in that storage for the origin. Because both APIs only store strings, a number or boolean you write comes back as a string.

</ExampleProse>
<ExampleCode>

```js
// Write
localStorage.setItem("theme", "dark");
localStorage.setItem("fontSize", "16");

// Read
console.log(localStorage.getItem("theme"));    // "dark"
console.log(localStorage.getItem("fontSize")); // "16" (string, not number)
console.log(localStorage.getItem("missing"));  // null

// Delete one key
localStorage.removeItem("fontSize");

// Delete everything for this origin
localStorage.clear();

// sessionStorage has the identical API but only lasts for the tab session
sessionStorage.setItem("draftTitle", "Untitled post");
console.log(sessionStorage.getItem("draftTitle")); // "Untitled post"
// Cleared automatically when the tab closes
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

To store objects or arrays, serialize them to a JSON string with `JSON.stringify` before writing, and deserialize with `JSON.parse` after reading. `JSON.parse` throws if the stored string is not valid JSON - which can happen if a previous version of your app wrote something else - so always wrap it in `try/catch`.

</ExampleProse>
<ExampleCode>

```js
const settings = { theme: "dark", fontSize: 16, compact: true };

// Write: serialize to JSON first
localStorage.setItem("settings", JSON.stringify(settings));

// Read: parse back to an object
function loadSettings() {
  try {
    const raw = localStorage.getItem("settings");
    return raw ? JSON.parse(raw) : null;
  } catch {
    // The stored string was not valid JSON - fall back to a default
    return null;
  }
}

const loaded = loadSettings();
console.log(loaded?.theme); // "dark"
console.log(typeof loaded?.fontSize); // "number" (JSON.parse restores the type)
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The `storage` event fires on all other tabs and windows that share the same origin whenever `localStorage` changes. This lets separate tabs stay in sync without a server connection. The event does not fire in the tab that made the change.

</ExampleProse>
<ExampleCode>

```js
// In Tab A: listen for changes made by other tabs
window.addEventListener("storage", (event) => {
  console.log("key changed:", event.key);
  console.log("old value:", event.oldValue);
  console.log("new value:", event.newValue);

  if (event.key === "theme") {
    document.body.dataset.theme = event.newValue ?? "light";
  }
});

// In Tab B: making this change fires the event in Tab A (not in Tab B itself)
localStorage.setItem("theme", "light");
```

</ExampleCode>
</ExamplePair>

<InProduction>
Both APIs are synchronous and run on the main thread - large reads and writes show up as long tasks in a performance profile. Quota is around 5 MB per origin; exceeding it throws a `QuotaExceededError`. Any JavaScript on the page can read everything in `localStorage`, so never store auth tokens, session cookies, or personally identifiable information here. Use HttpOnly cookies for secrets - the browser keeps them out of JavaScript entirely.
</InProduction>


Browser key-value storage that survives page reloads - what it stores, what it doesn't, and why auth tokens and PII must never go near it.

localStorage and sessionStorage


CRUD stands for Create, Read, Update, Delete - the four operations every persistent data store supports. With `localStorage` you can back a small list with a single JSON-encoded key: load it into memory, mutate the in-memory array, then write it back. The pattern is simple but requires careful error handling because `JSON.parse` throws when the stored data doesn't match what you expect.

<ExamplePair>
<ExampleProse>

Reading (the R in CRUD) means loading the JSON string from storage and parsing it. When the key doesn't exist yet `getItem` returns `null`, so you default to an empty array. Wrap `JSON.parse` in `try/catch` so a corrupted or schema-mismatched value doesn't crash the app.

</ExampleProse>
<ExampleCode>

```js
const STORAGE_KEY = "tasks-v1";

function loadTasks() {
  try {
    const raw = localStorage.getItem(STORAGE_KEY);
    if (!raw) return [];
    return JSON.parse(raw);
  } catch {
    // Stored data is not valid JSON or doesn't match the expected shape.
    // Return an empty list rather than crashing.
    console.warn("Could not parse stored tasks; starting fresh.");
    return [];
  }
}

function saveTasks(tasks) {
  localStorage.setItem(STORAGE_KEY, JSON.stringify(tasks));
}

const tasks = loadTasks();
console.log(tasks); // [] on first run
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Creating a task means pushing a new object onto the array and saving. Updating a task means mapping over the array, replacing the item whose `id` matches, and saving. Both operations work on the in-memory copy and then persist it.

</ExampleProse>
<ExampleCode>

```js
function createTask(text) {
  const tasks = loadTasks();
  const newTask = {
    id: crypto.randomUUID(), // unique ID that won't collide
    text,
    done: false,
    createdAt: new Date().toISOString(),
  };
  tasks.push(newTask);
  saveTasks(tasks);
  return newTask;
}

function updateTask(id, patch) {
  const tasks = loadTasks();
  const updated = tasks.map((task) =>
    task.id === id ? { ...task, ...patch } : task
  );
  saveTasks(updated);
}

// Usage
const task = createTask("Buy groceries");
console.log(task.id); // "550e8400-e29b-41d4-a716-446655440000" (random UUID)

updateTask(task.id, { done: true });
console.log(loadTasks().find((t) => t.id === task.id)?.done); // true
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Deleting a task means filtering it out of the array and saving the result. Clearing everything means writing an empty array (or removing the key entirely). The in-memory array never mutates in place - you always produce a new array and save it.

</ExampleProse>
<ExampleCode>

```js
function deleteTask(id) {
  const tasks = loadTasks();
  const remaining = tasks.filter((task) => task.id !== id);
  saveTasks(remaining);
}

function clearAllTasks() {
  localStorage.removeItem(STORAGE_KEY);
}

// Usage
const t = createTask("Write tests");
console.log(loadTasks().length); // 1

deleteTask(t.id);
console.log(loadTasks().length); // 0

// Add a few, then wipe everything
createTask("Alpha");
createTask("Beta");
clearAllTasks();
console.log(loadTasks().length); // 0
```

</ExampleCode>
</ExamplePair>

<InProduction>
`JSON.parse` on stored data can throw if a previous version of the app wrote a different shape - a renamed field, a changed type, a removed key. Always wrap it in `try/catch` and version your storage key (`tasks-v1`, `tasks-v2`) so a schema change starts fresh rather than corrupting every existing user's data. Two tabs open to the same page can clobber each other's writes because each tab loads, mutates, and saves without knowing about the other; for anything that needs concurrent writes, use IndexedDB or a server-side store instead.
</InProduction>


CRUD on a JSON-encoded list stored in a single localStorage key - including try/catch on parse and versioned keys to survive schema changes between app deploys.

CRUD with localStorage


A regular expression is a small pattern language for matching text. JavaScript has it built in: you can write a pattern as a literal between slashes (`/foo/`) or construct one at runtime with `new RegExp("foo")`. Methods on strings and RegExp objects let you test, search, capture, and replace using those patterns.

<ExamplePair>
<ExampleProse>

`test` checks whether a pattern appears anywhere in a string and returns a boolean. `match` returns the matched text (and capture groups) or `null`. The `g` flag makes `match` return every occurrence instead of just the first.

</ExampleProse>
<ExampleCode>

```js
// test - returns true or false
console.log(/cat/.test("concatenate")); // true
console.log(/cat/.test("dog"));         // false

// match without g - first occurrence + index
const result = "hello world".match(/\w+/);
console.log(result[0]);     // "hello"
console.log(result.index);  // 0

// match with g - all occurrences as an array
const all = "hello world".match(/\w+/g);
console.log(all); // ["hello", "world"]
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Capture groups, written as `(...)`, let you extract specific parts of a match. `exec` returns a single match with its groups as array slots. Named groups (`(?<name>...)`) make the captured values accessible by name instead of by index, which keeps regex code readable when there are several groups.

</ExampleProse>
<ExampleCode>

```js
// Numbered capture groups
const numbered = /(\w+)@(\w+)/.exec("user@example");
console.log(numbered[1]); // "user"
console.log(numbered[2]); // "example"

// Named capture groups - much easier to read
const named = /(?<user>\w+)@(?<host>\w+)/.exec("user@example");
console.log(named.groups.user); // "user"
console.log(named.groups.host); // "example"

// matchAll iterates all matches including their groups
const emails = "a@b.com c@d.com";
for (const match of emails.matchAll(/(?<user>\w+)@(?<host>[\w.]+)/g)) {
  console.log(match.groups.user, match.groups.host);
}
// "a" "b.com"
// "c" "d.com"
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`replace` swaps matched text with a string or the return value of a function. Passing a function replacer is the most flexible form: it receives the full match plus any capture groups, so you can transform each match individually.

</ExampleProse>
<ExampleCode>

```js
// Simple string replacement (g flag replaces all)
const dashes = "2026-04-27".replace(/-/g, "/");
console.log(dashes); // "2026/04/27"

// Function replacer - called once per match
const words = "hello world";
const titled = words.replace(/\b\w/g, (char) => char.toUpperCase());
console.log(titled); // "Hello World"

// Function replacer with named groups
const date = "2026-04-27";
const reordered = date.replace(
  /(?<y>\d{4})-(?<m>\d{2})-(?<d>\d{2})/,
  (_, y, m, d) => `${d}/${m}/${y}`
);
console.log(reordered); // "27/04/2026"
```

</ExampleCode>
</ExamplePair>

<InProduction>
Catastrophic backtracking - where the regex engine exhausts every possible combination before giving up - can hang the event loop on user-supplied input. The classic trap is nested quantifiers like `(a+)+` applied to a string that nearly matches: the engine tries exponentially many paths. Anchor your patterns (`^` and `$`) where you can, keep quantifiers flat, and run any regex that touches untrusted strings through a static analyzer like `safe-regex` or the `eslint-plugin-security` rule `detect-unsafe-regex`.
</InProduction>


Regular expressions match and transform text using patterns built into JS - write them as /foo/ literals or new RegExp("foo"), with flags like g (global) and i (case-insensitive).

Regular Expressions


A stack is a last-in-first-out (LIFO) collection: the last item you push in is the first one you get back, like a pile of plates. A queue is first-in-first-out (FIFO): items leave in the order they arrived, like a line at a coffee shop. Both are abstract interfaces, not specific data structures - JavaScript arrays can implement either.

<ExamplePair>
<ExampleProse>

A stack on top of an array uses `push` to add to the top and `pop` to remove from the top. Both are O(1): they touch only the last element, so the array never has to shift anything around. A classic use case is an undo history: each action goes on the stack; pressing undo pops the most recent one off.

</ExampleProse>
<ExampleCode>

```js
const undoStack = [];

function doAction(action) {
  undoStack.push(action);
  console.log("Did:", action);
}

function undo() {
  const last = undoStack.pop();
  if (last) {
    console.log("Undid:", last);
  } else {
    console.log("Nothing to undo");
  }
}

doAction("type 'hello'");  // Did: type 'hello'
doAction("bold selection"); // Did: bold selection
undo();                     // Undid: bold selection
undo();                     // Undid: type 'hello'
undo();                     // Nothing to undo
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A queue on top of an array uses `push` to add to the back and `shift` to remove from the front. The `shift` operation is O(n) because the browser has to move every remaining element one index earlier. For small queues that's fine; for a hot queue (many items, high throughput) the cost adds up.

</ExampleProse>
<ExampleCode>

```js
const printQueue = [];

function enqueue(job) {
  printQueue.push(job);
}

function dequeue() {
  return printQueue.shift(); // O(n) - the whole array slides left
}

enqueue("page-1.pdf");
enqueue("page-2.pdf");
enqueue("page-3.pdf");

console.log(dequeue()); // "page-1.pdf"
console.log(dequeue()); // "page-2.pdf"
console.log(dequeue()); // "page-3.pdf"

// Checking length and front without removing
const taskQueue = ["alpha", "beta", "gamma"];
console.log(taskQueue.length);  // 3
console.log(taskQueue[0]);      // "alpha" (peek at front without shift)
```

</ExampleCode>
</ExamplePair>

<InProduction>
Arrays make great stacks (`push` and `pop` are O(1)) but lousy queues: `shift` has to slide every element one position forward, so it's O(n). The regression is easy to miss in a benchmark that uses 100 items - it only shows up around 100,000. For a hot queue, reach for a linked-list-backed queue or a circular buffer where both enqueue and dequeue are O(1). Most job-queue and event-loop implementations inside Node.js internals use a circular buffer exactly for this reason.
</InProduction>


Stack (LIFO: push/pop) and queue (FIFO: push/shift). Arrays are great stacks but poor queues because shift is O(n); use a linked-list queue when throughput matters.

Stacks and Queues


A linked list is a chain of nodes; each node holds a value and a reference (pointer) to the next node. There is no underlying contiguous block of memory, which means inserting or removing a node at a known position is O(1) - you just rewire two pointers. The trade-off is that there is no index: to get item number 50 you have to follow the chain 50 times.

<ExamplePair>
<ExampleProse>

A minimal singly-linked list needs a `Node` class and a `LinkedList` class. `prepend` adds to the front in O(1). `append` walks to the last node and attaches there - O(n). An iteration helper (or a standard `[Symbol.iterator]`) lets you loop over the values with a `for...of` loop.

</ExampleProse>
<ExampleCode>

```js
class Node {
  constructor(value) {
    this.value = value;
    this.next = null;
  }
}

class LinkedList {
  constructor() {
    this.head = null;
    this.size = 0;
  }

  prepend(value) {
    const node = new Node(value);
    node.next = this.head;
    this.head = node;
    this.size++;
  }

  append(value) {
    const node = new Node(value);
    if (!this.head) {
      this.head = node;
    } else {
      let current = this.head;
      while (current.next) {
        current = current.next; // walk to the last node
      }
      current.next = node;
    }
    this.size++;
  }

  [Symbol.iterator]() {
    let current = this.head;
    return {
      next() {
        if (!current) return { done: true, value: undefined };
        const value = current.value;
        current = current.next;
        return { done: false, value };
      },
    };
  }
}

const list = new LinkedList();
list.append("a");
list.append("b");
list.append("c");

for (const val of list) {
  console.log(val); // "a", "b", "c"
}

console.log(list.size); // 3
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The key limitation of a linked list is the absence of random access. Getting the item at index `i` requires starting at the head and following `i` pointers. With an array the same operation returns instantly because the runtime can compute the memory address directly from the index.

</ExampleProse>
<ExampleCode>

```js
class LinkedList {
  // ... (same as above)
  get(index) {
    let current = this.head;
    let i = 0;
    while (current) {
      if (i === index) return current.value;
      current = current.next;
      i++;
    }
    return undefined; // index out of bounds
  }
}

// Linked list: O(n) - must walk from the head
const list = new LinkedList();
for (let i = 0; i < 1000; i++) list.append(i);
console.log(list.get(999)); // 999 - walked 1000 nodes

// Array: O(1) - computed from base address + offset
const arr = Array.from({ length: 1000 }, (_, i) => i);
console.log(arr[999]); // 999 - instant lookup
```

</ExampleCode>
</ExamplePair>

<InProduction>
Pointer chasing (following a chain of references scattered across the heap) destroys CPU cache locality: each node read is likely a cache miss, which is far slower than reading a contiguous array. In V8, arrays win for almost every application-code use case. The real production scenario where a linked list earns its keep is a doubly-linked list inside an LRU cache: you need O(1) insertion and O(1) removal at arbitrary positions, and you always have a direct reference to the node you want to move, so you never have to scan.
</InProduction>


Linked list: nodes chained via pointers. O(1) insert/remove at known positions, but no random access - walking n nodes to reach index i means arrays win for most application code.

Linked Lists


A tree is a hierarchy: each node has a value and zero or more children, and there is exactly one root. There are no cycles and no second path to the same node. The DOM, a file system, and a JSON document are all trees.

<ExamplePair>
<ExampleProse>

The simplest representation is a plain object with a `value` field and a `children` array. A recursive `walk` function visits the root, then calls itself on each child. Tracking `depth` lets you add indentation so the printed output mirrors the hierarchy visually.

</ExampleProse>
<ExampleCode>

```js
const fileSystem = {
  value: "root",
  children: [
    {
      value: "src",
      children: [
        { value: "index.js", children: [] },
        { value: "utils.js", children: [] },
      ],
    },
    {
      value: "public",
      children: [
        { value: "index.html", children: [] },
        { value: "logo.svg",   children: [] },
      ],
    },
    { value: "package.json", children: [] },
  ],
};

function walk(node, depth = 0) {
  console.log(" ".repeat(depth * 2) + node.value);
  for (const child of node.children) {
    walk(child, depth + 1); // recurse into each child
  }
}

walk(fileSystem);
// root
//   src
//     index.js
//     utils.js
//   public
//     index.html
//     logo.svg
//   package.json
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Recursive traversal has an implicit stack living in the call stack. When the tree comes from user input it can be arbitrarily deep, and deep recursion throws a `RangeError: Maximum call stack size exceeded`. An iterative DFS replaces the call stack with an explicit array used as a stack: push the root, then loop - pop a node, process it, push its children.

</ExampleProse>
<ExampleCode>

```js
function walkIterative(root) {
  const stack = [{ node: root, depth: 0 }];

  while (stack.length > 0) {
    const { node, depth } = stack.pop(); // take from the top
    console.log(" ".repeat(depth * 2) + node.value);

    // push children in reverse order so the first child is processed first
    for (let i = node.children.length - 1; i >= 0; i--) {
      stack.push({ node: node.children[i], depth: depth + 1 });
    }
  }
}

// same output as the recursive version, but safe on deep trees
walkIterative(fileSystem);
// root
//   src
//     index.js
//     utils.js
//   public
//     index.html
//     logo.svg
//   package.json

// the recursive version would throw on deeply nested user data:
// RangeError: Maximum call stack size exceeded
```

</ExampleCode>
</ExamplePair>

<InProduction>
Recursive traversal blows the call stack on deep user-supplied trees - HTML pasted from a document editor or badly nested JSON can easily exceed the default stack depth in V8 (~10,000 frames). Iterative DFS with an explicit stack is the safe default whenever depth is unbounded. For the DOM specifically, `TreeWalker` (`document.createTreeWalker`) is purpose-built, iterative, and faster than any hand-rolled traversal.
</InProduction>


Tree: a hierarchy with one root where each node has a value and children. Recursive traversal is elegant but unsafe on deep user data; use iterative DFS with an explicit stack.

Trees


A graph is a set of nodes connected by edges. Unlike a tree, a graph can have cycles (a chain of edges that loops back to a node you already visited) and more than one path between any two nodes. Social networks, package dependency graphs, and route maps are all graphs.

<ExamplePair>
<ExampleProse>

An adjacency list represents a graph as a `Map` where each key is a node and its value is the array of nodes it connects to. For an undirected graph you add an entry in both directions. This representation uses space proportional to the number of edges, which makes it efficient for sparse graphs where most nodes are not directly connected to each other.

</ExampleProse>
<ExampleCode>

```js
const graph = new Map();

function addEdge(a, b) {
  if (!graph.has(a)) graph.set(a, []);
  if (!graph.has(b)) graph.set(b, []);
  graph.get(a).push(b); // undirected: add both directions
  graph.get(b).push(a);
}

addEdge("alice",   "bob");
addEdge("alice",   "carol");
addEdge("bob",     "dave");
addEdge("carol",   "dave");

// graph:
//  alice  ->  bob, carol
//  bob    ->  alice, dave
//  carol  ->  alice, dave
//  dave   ->  bob, carol

for (const [node, neighbors] of graph) {
  console.log(`${node}: ${neighbors.join(", ")}`);
}
// alice: bob, carol
// bob: alice, dave
// carol: alice, dave
// dave: bob, carol
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Breadth-first search (BFS) explores nodes level by level using a queue. A `visited` Set prevents revisiting nodes; without it, any cycle in the graph turns the traversal into an infinite loop. Removing the Set from this example and adding an edge that creates a cycle shows the problem immediately.

</ExampleProse>
<ExampleCode>

```js
function bfs(graph, start) {
  const visited = new Set();
  const queue = [start];
  visited.add(start);

  while (queue.length > 0) {
    const node = queue.shift(); // take from the front (FIFO)
    console.log("visited:", node);

    for (const neighbor of graph.get(node) ?? []) {
      if (!visited.has(neighbor)) {
        visited.add(neighbor);   // mark before enqueue to avoid duplicates
        queue.push(neighbor);
      }
    }
  }
}

bfs(graph, "alice");
// visited: alice
// visited: bob
// visited: carol
// visited: dave

// WITHOUT the visited Set, alice -> bob -> alice -> bob -> ...
// => infinite loop because the graph has a cycle (alice <-> bob)
```

</ExampleCode>
</ExamplePair>

<InProduction>
Any graph traversal needs cycle detection via a `visited` Set or it will infinite-loop on real data - production graphs (dependency trees, social graphs, route networks) nearly always contain cycles. Adjacency lists are the right default: they use O(nodes + edges) space, which is efficient for sparse graphs where most pairs of nodes are not directly connected. Adjacency matrices use O(nodes²) space and only beat adjacency lists when the graph is dense and you need constant-time edge lookup between arbitrary node pairs.
</InProduction>


Graph: nodes connected by edges, with cycles and multiple paths. Always carry a visited Set or a cycle will infinite-loop your traversal. Adjacency lists are the right default.

Graphs


## Problem

Many features produce work that can be done *eventually* but should not be done *synchronously*: image processing, email sending, invoice generation, ML feature computation, report rendering. Running these inside the HTTP request that triggered them ties user-perceived latency to whichever background task happens to be slow that day, and collapses under load when hundreds of users hit the same endpoint simultaneously.

Moving the work to a single background worker helps - the request returns instantly and the worker processes in the background - but shifts the bottleneck downstream. One worker has a fixed throughput ceiling. A traffic spike that produces ten thousand jobs in a minute will take the worker hours to drain. During that time the queue grows unboundedly, users wait longer and longer for their image to process, and the application owner has no lever to pull except "deploy more." The single-worker design does not scale with demand; it only delays the collapse.

## Forces

- **Throughput must scale with demand.** A fixed-capacity worker cannot absorb spikes that exceed its processing rate. Something must grow horizontally.
- **Job cost is non-uniform.** Some jobs finish in 50ms; some take 30 seconds. A design that routes work to a specific worker (affinity, sharding) will underuse fast workers while slow workers accumulate backlog.
- **Workers fail.** Instances crash, get deployed over, run out of memory. A design that loses in-flight work when a worker dies is unacceptable for anything business-critical.
- **Delivery semantics matter.** Brokers that guarantee delivery must do so even across worker crashes, which means messages get redelivered. Workers therefore cannot assume they see each message exactly once.

## Solution

Producers drop messages onto a **single queue**. Multiple consumer instances pull from that same queue concurrently. The broker hands each message to exactly one consumer, but which consumer gets which message is determined dynamically - whichever worker is currently free pulls the next message. Faster workers naturally pull more; slower ones pull less. Throughput scales by adding consumer instances.

```typescript
// Producer - drops jobs onto the queue
await sqs.sendMessage({
  QueueUrl: IMAGE_QUEUE,
  MessageBody: JSON.stringify({ jobId, imageUrl, ops }),
});

// Consumer - many instances of this run in parallel
async function workerLoop() {
  while (running) {
    const { Messages } = await sqs.receiveMessage({
      QueueUrl: IMAGE_QUEUE,
      MaxNumberOfMessages: 10,
      WaitTimeSeconds: 20, // long polling
    });

    await Promise.all(
      (Messages ?? []).map(async (msg) => {
        const job = JSON.parse(msg.Body);
        try {
          await processImage(job);
          await sqs.deleteMessage({ QueueUrl: IMAGE_QUEUE, ReceiptHandle: msg.ReceiptHandle });
        } catch (err) {
          // Leave the message; it becomes visible again and another worker retries.
          log.error({ err, jobId: job.jobId }, 'processing failed');
        }
      })
    );
  }
}
```

The broker handles the hard part: exclusive delivery (only one consumer sees a message at a time), visibility timeouts (if a consumer doesn't ack in N seconds, the message becomes available again for a different consumer), and backpressure (slow consumers naturally pull less work).

<PullQuote>
  Competing consumers is the smallest scalability pattern that actually scales. Add more workers, go faster. Remove workers, save money. The queue absorbs the mismatch.
</PullQuote>

**Idempotency is mandatory.** Queues almost universally provide at-least-once delivery. A worker that processes a message and then crashes before acknowledging will see that message again - possibly on a different worker. If running the handler twice produces the wrong answer (double-charging a card, double-sending an email), the pattern is broken. Pair this pattern with the [Idempotency Key](/patterns/idempotency-key) pattern so duplicates are safe.

**Ordering is not preserved across the fleet.** Because any worker may pull any message, two messages about the same entity may be processed out of order or in parallel on different workers. If you need per-entity ordering (all events for user 42 processed in order), use a **partitioned queue** keyed on entity id - Kafka consumer groups, SQS FIFO with message groups, RabbitMQ consistent-hash exchange. Each partition is its own competing-consumers pool, typically of one, which trades horizontal scale for ordering within a partition.

**Tune the consumer count.** The right number of consumers is determined by the external resources the job touches - database connections, third-party rate limits, CPU per job - not by the queue. Scaling consumers past what downstream systems can absorb simply moves the bottleneck to a worse place.

**Dead-letter queues.** Messages that fail repeatedly should move to a DLQ after N attempts. Without this, a poison message can consume a worker's capacity indefinitely as it fails, times out, and is redelivered forever.

## When NOT to Use

- **Strict total ordering is required.** If every message must be processed in the exact global order it was produced - financial tape reconstruction, serialized event logs - competing consumers is the wrong pattern. Use a single consumer or a partitioned design with one consumer per partition.
- **Jobs are sub-millisecond and extremely high volume.** The broker round-trip overhead (network latency + ack) is often larger than the job itself. Batch them into coarser work items or process them synchronously.
- **Consumers cannot be made idempotent.** If the downstream operation is fundamentally non-idempotent and cannot be made so, at-least-once delivery will cause duplicates the business cannot tolerate. Either move to a broker with exactly-once semantics (Kafka EOS within its constraints) or redesign the operation.
- **The queue replaces a trivial fire-and-forget.** Not every async task needs a broker. An in-process job runner with a persistent table is often enough for low-volume, single-server workloads. Reach for competing consumers when horizontal scaling of the workers is a real requirement.

## Related Patterns

**Outbox** is the reliable source of the events that feed the queue - a producer that loses events before they reach the queue defeats the entire fleet behind it. **Idempotency Key** makes at-least-once delivery safe at the consumer: every job carries an identifier, each consumer records keys it has processed, and duplicates become no-ops. In production systems, the three patterns almost always appear together - Outbox to publish, queue with competing consumers to scale, Idempotency Key to tolerate the redeliveries that the queue inevitably produces.

## References

- Hohpe, G. and Woolf, B. *Enterprise Integration Patterns*. Addison-Wesley, 2003. "Competing Consumers" pattern.
- AWS documentation. "Amazon SQS best practices." docs.aws.amazon.com/AWSSimpleQueueService
- Kreps, Jay. "The Log: What every software engineer should know about real-time data's unifying abstraction." engineering.linkedin.com, 2013.
- Kleppmann, Martin. *Designing Data-Intensive Applications*. O'Reilly, 2017. Chapter 11 (Stream Processing).


Competing Consumers


## Problem

Most applications begin with one model used for everything. The same `Order` class handles a checkout submission, a seller's dashboard, and a warehouse picking screen. The same database table backs all three. This works until the read and write workloads start pulling the schema in opposite directions. The dashboard wants a denormalized projection with precomputed totals. The warehouse wants full-text search over SKUs. The checkout wants a tight transactional boundary with minimal columns touched. Adding indexes, materialized views, and denormalized columns into one table slowly turns the schema into a compromise that serves no workload well.

The underlying mismatch is that **commands** (operations that change state) and **queries** (operations that read state) have fundamentally different requirements - different consistency guarantees, different shapes, different performance characteristics. Forcing them through the same model means every change is a tug-of-war between two stakeholders.

## Forces

- **Read and write workloads diverge.** Writes need small, validated, transactional touchpoints. Reads need wide, denormalized, query-optimized shapes. A shared schema has to pick a side.
- **Scaling characteristics differ.** Reads typically outnumber writes by 10× to 1000×. A model that optimizes both equally wastes capacity on whichever side is the minority.
- **Consistency requirements differ.** Writes are usually the authoritative source of truth and need strong consistency. Reads are often tolerant of millisecond-to-second staleness if the trade is faster, richer queries.
- **Team ownership differs.** The team building a seller-analytics dashboard has different priorities from the team enforcing checkout invariants. A shared model couples their roadmaps.

## Solution

**Command Query Responsibility Segregation (CQRS)** splits the model in two. Commands flow through a write model optimized for state changes; queries flow through one or more read models optimized for the shapes the product actually asks for. The two sides stay synchronized asynchronously - typically by the write side publishing events that read-side projectors consume and apply to their own stores.

**Typical shape:**

```typescript
// Write side - normalized, transactional, small
class CreateOrderHandler {
  async handle(cmd: CreateOrderCommand): Promise<void> {
    await db.transaction(async (tx) => {
      const order = await tx.insert(orders).values(cmd.toRow());
      await tx.insert(outboxEvents).values({
        eventType: 'order.created',
        payload: order,
      });
    });
  }
}

// Read side - denormalized, query-optimized, eventually consistent
class OrderListProjection {
  async on(event: OrderCreated): Promise<void> {
    await elastic.index({
      index: 'orders-read',
      id: event.orderId,
      body: {
        orderId: event.orderId,
        customerName: event.customer.name,
        totalCents: event.total,
        itemSkus: event.items.map((i) => i.sku),
        createdAt: event.createdAt,
      },
    });
  }
}
```

The write side owns business rules and invariants. The read side owns query ergonomics. Neither side has to compromise for the other.

<PullQuote>
  CQRS is not about databases. It is about admitting that "change what is true" and "describe what is true" are different jobs that deserve different tools.
</PullQuote>

**Read-model choices.** The read store does not have to be the same engine as the write store. Common pairings: Postgres writes with Elasticsearch reads (text search); Postgres writes with Redis reads (hot-path lookups); Postgres writes with a warehouse like BigQuery (analytics). Each read model is built for one use case and can be rebuilt by replaying events.

**Event transport.** The write side must publish change events reliably. Pair CQRS with the [Outbox](/patterns/outbox) pattern so events are atomic with the write, then have projectors consume them through a broker.

**Consistency delay.** The lag between write and read visibility is the defining trade of CQRS. In practice it is usually 50ms–2s. The application must be designed to tolerate it - either by reading from the write side for "just-did-this" cases, or by explicitly showing pending state in the UI.

## When NOT to Use

- **Simple CRUD applications.** If your reads and writes have nearly identical shapes and modest volume, one model serves both cheaply. CQRS adds a broker, projectors, two stores, and an eventual-consistency semantic your product does not need.
- **Strong read-after-write consistency is required.** In domains where a user updating a value must immediately see that value in a list (regulated settings screens, admin consoles, seller price confirmation), CQRS's eventual consistency is a UX hazard. You either read back from the write side (partially defeating the point) or keep a single model.
- **Small teams without event-streaming operational maturity.** Running projectors reliably - rebuilding them on schema changes, handling poison messages, monitoring lag - is a meaningful operational surface. If the team cannot own it, a single well-indexed database is better.
- **Low-volume internal tools.** A three-person internal dashboard with a hundred records does not benefit from the complexity. Reach for CQRS when the read workload justifies its own shape, not because the pattern is interesting.

## Related Patterns

**Outbox** is the reliable transport for change events between the write side and read-side projectors - CQRS without Outbox eventually loses events during broker hiccups and drifts out of sync. **Event Sourcing** is CQRS taken one step further: instead of storing current state on the write side, store the sequence of events that produced it, and treat every read model as a projection over that log. CQRS can be adopted without Event Sourcing; Event Sourcing almost always implies CQRS.

## References

- Young, Greg. "CQRS Documents." cqrs.files.wordpress.com/2010/11/cqrs_documents.pdf
- Fowler, Martin. "CQRS." martinfowler.com/bliki/CQRS.html
- Vernon, Vaughn. *Implementing Domain-Driven Design*. Addison-Wesley, 2013. Chapter 4 (Architecture).
- Kleppmann, Martin. *Designing Data-Intensive Applications*. O'Reilly, 2017. Chapter 11 (Stream Processing).


CQRS


## Problem

A normal database stores the *current* value of every field. When a row changes, the previous value is overwritten and gone. For many applications this is fine - nobody needs to know the former shipping address for an order that was delivered a year ago. But for a growing class of domains, the history *is* the product: financial ledgers, medical records, inventory counts, compliance-regulated workflows, anything where an auditor may someday ask "why did this number look different on March 2nd?"

State-only storage cannot answer that question. Adding audit tables after the fact is fragile (someone always forgets to log a mutation), incomplete (side effects escape the audit trail), and schema-coupled (a log that mirrors the current schema drifts out of date with it). Every team that has tried to add "full history" to a state-only system has discovered that you cannot bolt a time machine onto a design that threw away the past.

## Forces

- **History has business value.** Regulators, support engineers, and fraud investigators frequently need to reconstruct past states. A system that cannot produce them at arbitrary points in time imposes manual reconstruction work forever.
- **Projections have a short half-life.** Product teams repeatedly want to slice the same data in new ways - new dashboards, new reports, new search indices. If the source of truth is a log of events, new projections can be built from it. If the source of truth is the current state, only the shapes you anticipated can be derived.
- **Concurrency on state is hard.** Two processes updating the same row race. Two processes appending to a log do not - append-only logs have simple concurrency semantics (optimistic concurrency by version, or partition-level ordering).
- **Storage is cheap; truth is expensive.** The storage cost of keeping every event forever is trivial compared to the engineering cost of recovering lost history.

## Solution

**Event Sourcing** makes the sequence of events the source of truth. Instead of a row saying "account 42: balance=$412.73," there is an append-only log: `AccountOpened(42)`, `Deposited(42, $500)`, `Withdrawn(42, $87.27)`. The current balance is a *function* of folding those events in order. Nothing else needs to be persisted for the balance to be authoritative.

**Writing:**

```typescript
async function withdraw(accountId: string, amount: number): Promise<void> {
  const events = await eventStore.readStream(accountId);
  const state = events.reduce(applyEvent, initialState);

  if (state.balance < amount) {
    throw new InsufficientFunds();
  }

  await eventStore.append(accountId, {
    type: 'Withdrawn',
    payload: { amount },
    expectedVersion: state.version, // optimistic concurrency
  });
}
```

The write path is: load the stream, fold it into state, validate the command against that state, and append a new event. No row is ever updated in place.

**Reading:**

Reads go through projections. A projection subscribes to the event log and maintains a read model shaped for a specific query. The *same* log can feed many projections - a balance table for the banking app, a daily-summary table for statements, a suspicious-activity index for fraud detection. If a new query shape is needed, a new projection is built and replayed from the log.

<PullQuote>
  Current state is a cache of the event log. Treat it as such - disposable, rebuildable, and never the source of truth.
</PullQuote>

**Snapshotting.** Replaying a stream of thousands of events on every command gets slow. Periodically write a snapshot of the folded state at version N; load the snapshot plus events newer than N. Snapshots are performance optimizations, not truth - they can be deleted and rebuilt.

**Event versioning.** Events are immutable, but their schemas evolve. When a new field is added to `Deposited`, the fold function must handle both old and new shapes. Treat events as a versioned API to your future self: additive changes only, with explicit upcasters when the shape truly has to change.

**Operational weight.** Event sourcing changes deployment in real ways. Projection rebuilds must be routine and fast. The event store becomes the most critical piece of infrastructure in the system. Disaster recovery is different - restore the log, replay the projections, resume.

## When NOT to Use

- **CRUD applications.** A user profile, a settings screen, a content management system - domains where nobody will ever ask "what was this last Tuesday?" - do not benefit. The ceremony of event-sourcing pays back only when history is consumed.
- **Teams without the tooling maturity.** Event sourcing requires disciplined schema evolution, snapshotting, projection rebuild automation, and operational visibility into the event store. Teams that cannot invest in this will regret the choice.
- **Reporting-only systems.** If you need history for analytics but not for authoritative state, a change-data-capture stream into a warehouse is simpler and cheaper than making the operational system event-sourced.
- **Compliance domains where events cannot be retained.** GDPR's right-to-erasure conflicts with an append-only, immutable log. Solutions exist (cryptographic shredding, tombstone events, per-user encryption keys), but they add real complexity. If the domain forbids retention, event sourcing is a poor fit.

## Related Patterns

**CQRS** is the natural pairing: in an event-sourced system, write operations append events and read operations go through projections - which is exactly CQRS. You can adopt CQRS without event sourcing, but event sourcing almost always implies CQRS. **Outbox** is less relevant when the event log *is* the store (the log itself serves the role of reliable publication), but systems that use event sourcing for a subset of aggregates and state storage for the rest still benefit from an outbox at the integration boundary.

## References

- Young, Greg. "Event Sourcing." Presentations and writings collected at eventstore.com
- Fowler, Martin. "Event Sourcing." martinfowler.com/eaaDev/EventSourcing.html
- Vernon, Vaughn. *Implementing Domain-Driven Design*. Addison-Wesley, 2013. Chapter 8 (Domain Events).
- Kleppmann, Martin. *Designing Data-Intensive Applications*. O'Reilly, 2017. Chapter 11 (Stream Processing).


Rickvian Aldi

Latest essays

Five Message Broker Patterns

Why Engineers Are Obsessed With P99

Meta-Stable Failure: When Your System Is Up But Completely Down

Pattern library

Competing Consumers

CQRS

Event Sourcing

By example

By Example

The kit

Cron Explainer

JWT Decoder

What I write about

Get essays in your inbox