Performance At Scale

---
name: performance-at-scale
description: Use when writing code that runs per item, per frame, or per event, or building a cache or lookup over a collection that can grow large.
---

## The rule

Hot-path code meets your data at production scale, not at the handful of rows in your test fixture. A linear scan that's instant on ten items freezes the UI on a hundred thousand. The cost is invisible in the test and brutal in the field. Design the hot path for the largest realistic input before you write it, not after a user reports a freeze.

## Fires when

Writing code that runs per item, per frame, or per event. Building a cache or a lookup. Iterating a collection that could grow large. Rebuilding a whole list when one entry changed.

## How to apply

Before writing data-path code, ask "does this hold at the largest realistic input?"

Use O(1) lookups with an early exit — a map keyed by the thing you're asking about, so 99% of queries return immediately. Prefer incremental point updates (remove one, add one) over rebuilding the whole structure. Keep allocations and copies out of tight loops. Verbose logging in a hot loop is fine, but only after the early exit, never before it.

If the answer is "no, it won't scale", redesign before you write it, not after.

## Worked example

A handler runs once per tile and scans a flat list of issues linearly to find the ones that match. With a dozen issues in the test, it's instant. In a real project the list holds four thousand issues, and every tile now costs a one-to-two second freeze. Keyed into a map by tile, each query early-exits in O(1) and the freeze is gone. The scan looked fine because the test never had enough data to make it hurt.

## Red flags

| Thought | Reality |
|---|---|
| "It's fast enough" | Fast on the fixture, frozen at scale. |
| "I'll rebuild the whole list, it's simpler" | Simpler to write, O(N) to run every time. |
| "Just loop and find it" | A linear scan on a hot path is a freeze waiting for data. |