# How to Make a JavaScript Library Fast

A playbook extracted by diffing a from-scratch reimplementation of a mature JS library
against the original. The reimplementation kept the same public API and passes the
original's vendored test suite, while reporting 5–30× throughput on hot operations and
1.2–2.7× on primitives.

Nothing here is domain-specific. The techniques are the transferable part.

---

## 0. The meta-lesson: where the wins actually came from

The speedups are **not** uniformly distributed. Ranked by multiplier:

| Tier | Technique | Typical gain | Cost |
|---|---|---|---|
| 1 | **Skip the work entirely** (tiered fast lanes) | 5–30× | High correctness risk; needs parity tests |
| 2 | **Move work to setup time** (compile, precompute tables) | 2–10× | Memory; staleness if config mutates |
| 3 | **Cache at the right layer** (whole results, not intermediates) | 2–60× | Cache-invalidation bugs; unbounded growth |
| 4 | **Delete async** (sync lanes, no promises when nothing is pending) | 2–10× | Two code paths to keep in sync |
| 5 | **Delete allocations** (no intermediate arrays/objects/closures) | 1.5–3× | Readability |
| 6 | **Micro-optimize primitives** (charCodeAt over regex) | 1.2–2.7× | Readability; low ceiling |

Most engineers start at tier 6 and stop. **The 30× rows all came from tiers 1–4.** Tier 6
is where you go *after* the structure is right, and its main value is that it makes the
fast lanes' guard checks nearly free.

Second meta-lesson, equally important: **the correctness harness is not optional overhead —
it's what makes tiers 1–4 possible at all.** Every aggressive shortcut in this codebase is
backed by a test that pins the observable behaviour it's allowed to skip. Without that,
you cannot ship a fast lane; you can only ship a bug.

---

## Tier 1 — Don't do the work

### 1.1 Build a dispatch ladder, cheapest check first

The single highest-leverage pattern. Instead of one general algorithm, stack progressively
more expensive strategies and return at the first hit:

```js
function resolve(input) {
  // (1) identity memo: two === compares, zero hashing
  if (input === hotKey && context === hotContext) return hotResult

  // (2) per-instance one-slot memo
  if (instance.lastKey === input) return instance.lastResult

  // (3) precomputed exact-answer table (built at setup time)
  const exact = instance.exactTable[input]
  if (exact !== undefined) return remember(input, exact)

  // (4) bounded result cache
  const cached = instance.cache.get(input)
  if (cached !== undefined) return remember(input, cached)

  // (5) specialized walker for the common input class
  const simple = trySimpleStrategy(input)
  if (simple !== undefined) return remember(input, simple)

  // (6) the general algorithm
  return remember(input, generalStrategy(input))
}
```

Each rung must be strictly cheaper than the one below it. Rung (1) costs two pointer
compares; rung (6) may cost a full tree walk. On a workload with any temporal locality you
almost never reach the bottom.

### 1.2 Fast lanes need a *narrowing* gate, not an approximation

The rule that keeps this honest: **a fast lane must either produce the exact same result as
the general path, or refuse to run.** It never approximates.

Express that as an explicit blacklist of everything the lane can't handle:

```js
function canUseFastLane(item) {
  const cached = item._fastLane          // 0 | 1 | undefined
  if (cached === 1) return true
  if (cached === 0) return false

  const opts = item.options
  const ok = !(
    opts.beforeHook || opts.afterHook || opts.transform ||
    opts.errorHandler || opts.customSerializer || opts.middleware
  )
  item._fastLane = ok ? 1 : 0            // memoize on the object, computed once
  return ok
}
```

Two things to copy:
- **Blacklist, not whitelist.** New features are automatically excluded from the fast lane
  until someone deliberately handles them. A whitelist silently breaks on the next feature.
- **Memoize the gate itself** as a `0 | 1` integer field on the object. The gate runs on
  every call; the predicate runs once per object. Using `0/1` instead of `true/false/undefined`
  keeps the field a Smi and the compare monomorphic.

### 1.3 Tri-state returns: "hit", "miss", "not my job"

A specialized strategy needs to distinguish *"I definitively determined there's no result"*
from *"this input is outside my competence, ask someone else"*. Collapsing those forces the
caller to re-run the expensive path on every negative.

```js
// undefined = ineligible, fall through to the general path
// null      = definitively no result, stop
// value     = hit
function trySimpleStrategy(input) {
  if (hasComplexFeature(node)) return undefined   // not my job
  const child = node.children[key]
  if (!child) return null                         // definitive miss
  return buildResult(child)
}
```

The same idea at a coarser grain, for lanes that may complete synchronously, go async
mid-flight, or bail out:

```js
// true          = completed synchronously
// Promise       = went async mid-lane
// false         = ineligible, caller should use the general path
function tryFastLane(input) { ... }
```

### 1.4 Precompute the answer table for the enumerable cases

If the set of "simple" inputs is finite and derivable from config, compute all the answers
at setup and serve them from a dictionary:

```js
function buildExactTable(config) {
  const table = Object.create(null)
  for (const item of config.items) {
    if (!isSimple(item.key)) continue           // only inputs with no dynamic parts
    if (needsRuntimeHook(item)) continue        // guard: anything user-observable is excluded
    table[item.key] = computeResult(config, item.key)
    if (caseInsensitive) table[item.key.toLowerCase()] = table[item.key]  // pre-fold aliases
  }
  return table
}
```

At call time this is one property load returning a **shared, frozen** result — no walk, no
allocation, no parameter object. This was the biggest single structural win in the codebase.

Note the guards. Anything that could invoke user code, mutate, or vary per call disqualifies
an entry from precomputation. Precompute only pure, config-derived answers.

### 1.5 Skip the whole operation when the state is already correct

```js
function refresh(opts) {
  if (!opts?.force && isAlreadySettled()) {
    return RESOLVED          // shared singleton, zero allocation, zero microtasks
  }
  return doTheWork(opts)
}
```

The general path in the original always allocated a promise and burned at least one tick
even when everything was already up to date. Checking for "nothing to do" is often the
cheapest big win in a library, and it's usually missing because the code was written
async-first.

**Ethics note:** the reimplementation's benchmark harness *deliberately excludes* this row
from its published table, because "we can skip the call entirely" isn't a comparison of
equivalent work. Do the same. Optimize it, don't brag about it.

---

## Tier 2 — Move work from call time to setup time

### 2.1 Compile patterns into op arrays

Instead of re-parsing a template string on every call, parse once into a flat array of ops
and cache it — **including the failure**, so complex templates aren't rescanned forever:

```js
const compiled = Object.create(null)   // key -> ops[] | null (null = "not compilable")

function compile(template) {
  const hit = compiled[template]
  if (hit !== undefined) return hit    // `undefined` = miss, `null` = negative cache hit

  const ops = []
  // ...scan once...
  if (tooComplex) return (compiled[template] = null)
  return (compiled[template] = ops)
}

function apply(template, values) {
  const ops = compile(template)
  if (!ops) return null                // caller falls back to the general path
  let out = ''
  for (let i = 0; i < ops.length; i++) {
    const op = ops[i]
    out += op.t === 0 ? op.s : values[op.k]
  }
  return out
}
```

Note `undefined` vs `null` doing double duty as miss-vs-negative-hit. Negative caching
matters: without it, every uncompilable input pays a full scan forever.

### 2.2 Specialize a closure for the common arity

One step further than op arrays — compile straight to a closure, with a hand-written
monomorphic case for the overwhelmingly common shape:

```js
function compileToClosure(template, keys) {
  if (keys.length === 1) {                     // the ~90% case
    const key = keys[0]
    const idx = template.indexOf('$' + key)
    const pre = template.slice(0, idx)
    const post = template.slice(idx + key.length + 1)
    return (values) => pre + values[key] + post   // one concat, zero scanning
  }
  const parts = buildParts(template)
  return (values) => { /* generic loop */ }
}
```

The one-param closure has no loop, no array indexing, no branch. V8 inlines it.

### 2.3 Precompute capability flags on the config object

Walk the whole configuration once at setup and hoist "does anything anywhere use feature X"
into booleans. Then gate entire subsystems at call time with one property load:

```js
// setup
let hasValidation = false
let hasMiddleware = false
for (const id in registry) {
  const o = registry[id].options
  if (o?.middleware?.length) { hasMiddleware = true; hasValidation = true; break }
  if (o?.validate) hasValidation = true
}
processed.hasValidation = hasValidation
processed.hasMiddleware = hasMiddleware

// call time
if (processed.hasValidation) { /* the entire validation pipeline */ }
```

**Caveat found in the wild:** one such flag was computed with a full recursive tree walk at
setup and then *never read on any hot path* — only by a unit test. Audit your precomputation
for dead work. Setup cost isn't free just because it's not in the hot loop.

### 2.4 Fold case/normalization into the key at build time

If lookups are case-insensitive, don't lowercase the input on every call and don't keep two
lookup tables. Normalize the *keys* once at setup and store pre-folded aliases. This is only
possible if you scope the feature at the container level rather than per-item — see §9.2,
where deleting a feature enabled a strictly better data structure.

---

## Tier 3 — Cache at the right layer

### 3.1 The cache hierarchy, cheapest first

| Layer | Cost per hit | When to use |
|---|---|---|
| Module-level 1-slot identity memo | 2× `===` | The exact same call repeats back-to-back |
| Per-instance 1-slot memo | 1 field load + `===` | Same, but instances interleave |
| Null-prototype dictionary | 1 keyed load | Small bounded key space |
| `Map` | hash + call | Non-string keys, or you need real LRU |
| Linked-list LRU | hash + 3–6 pointer writes | Large key space, real eviction pressure |

A one-slot memo is *dramatically* cheaper than a `Map` and is often enough:

```js
let lastA = '', lastB = '', lastResult = ''
function expensive(a, b) {
  if (a === lastA && b === lastB) return lastResult
  const result = compute(a, b)
  lastA = a; lastB = b; lastResult = result
  return result
}
```

Initialize sentinels to a value **no real input can equal** (`'\0'`, not `''`) so the
comparison IC never sees a degenerate shape and the guard never accidentally hits.

### 3.2 Cache the whole downstream result, not the intermediate

The biggest cache win wasn't caching the core algorithm — it was caching the **entire
derived tuple** the caller actually wanted, returned **by reference**:

```js
function getDerived(key) {
  const hit = cache[key]
  if (hit) return hit              // returns the SAME array/tuple, zero allocation

  const base = coreAlgorithm(key)
  const result = [buildChain(base), base.params, base.leaf]
  cache[key] = result
  return result
}
```

The original cached the core algorithm's output but then rebuilt the tuple, copied a params
object, and allocated an array on every call — so the cache saved the cheap part and paid
for the expensive part every time. **Profile where the allocations are, not where the
algorithm is.**

### 3.3 Template + clone for objects that are mostly identical

When results are expensive to construct but differ only in a few mutable fields, snapshot a
sanitized template and clone it:

```js
// on the way out: strip everything user-mutable / request-specific
function toTemplate(obj) {
  return { ...obj, data: undefined, error: undefined, context: {}, controller: undefined }
}

// on the way in: preallocated array, spread the template, patch the volatile fields
function cloneTemplate(template) {
  const now = Date.now()
  const out = new Array(template.length)
  for (let i = 0; i < template.length; i++) {
    out[i] = { ...toTemplate(template[i]), updatedAt: now, isPending: false }
  }
  return out
}
```

Gate this hard: the snapshot is only taken (and only used) when no feature that could make
two results differ is active. Spread-cloning also preserves key order, so the clones share a
hidden class with the source.

### 3.4 Returning the *same reference* is itself an optimization

Every transform function should return its input unchanged when there's nothing to do:

```js
function normalize(str) {
  const i = str.indexOf(BAD)
  if (i === -1) return str        // same reference — downstream === checks now hit
  return doTransform(str, i)
}
```

This compounds. Downstream one-slot memos, `Object.is` bailouts, and change-detection all
key on identity. A function that returns a fresh equal string invalidates every cache above
it.

### 3.5 Cache hazards — every one of these was found in the shipped code

- **Identity-keyed memos on mutable inputs.** `if (obj === lastObj) return lastResult` is
  wrong the moment someone mutates `obj` in place. It only works under a documented
  immutability invariant. Write the invariant down.
- **FIFO masquerading as LRU.** A bounded dictionary that evicts the first-inserted key is
  FIFO. A hot key inserted early gets evicted while cold keys survive. Fine at size 32,
  pathological at scale.
- **Object insertion order as a recency list.** Exploiting JS string-key insertion order to
  avoid a linked list works — until a key is integer-like (`"0"`, `"12"`), which JS orders
  *before* all string keys, silently corrupting recency. Also, `delete` + re-insert on every
  `get` pushes the object into dictionary mode.
- **`Object.keys(store)[0]` to find the oldest key.** Allocates the entire key array to read
  element 0. Only on the eviction path, but it's a real allocation at exactly the wrong time.
- **Unbounded caches.** Two of the highest-value caches had no eviction at all. Keyed by
  user-controlled input, that's a memory leak and a DoS vector.
- **Module-global caches shared across instances and across tests.** Fine for pure functions
  of their key. Not fine for anything else.

---

## Tier 4 — Delete the async

An `async` function that never actually suspends still costs: a promise allocation, a
coroutine frame, and a microtask tick per `await`. Across a pipeline that's 15–25 promises
and 25–40 ticks for work that could be zero.

### 4.1 Type your hot functions as "sync or async"

```js
/** @returns {void | Promise<void>} */
function run(input) {
  const result = step1(input)
  if (result instanceof Promise) return result.then(step2)
  return step2(result)                 // returns undefined — no promise at all
}
```

Callers join with an explicit check rather than `await`. Yes, it's two paths. That's the
price.

### 4.2 A shared resolved singleton

```js
export const RESOLVED = Promise.resolve()
```

Return it from every "nothing to do" path. Then callers can identity-check it and skip even
the thenable test:

```js
const out = run(input)
if (out !== RESOLVED && isThenable(out)) return out.then(next)
return next()
```

### 4.3 `instanceof Promise` vs `isThenable` — pick deliberately

```js
// hot internal joins: monomorphic, no property load, no call
if (value instanceof Promise) { ... }

// API boundaries (user callbacks, cross-realm values): correct but costlier
const isThenable = (v) => v != null && typeof v.then === 'function'
```

Use `instanceof` where you control both sides; use duck-typing where you don't.

### 4.4 Continuation-passing instead of `async`/`await`

Rewriting a 4-`await` pipeline as chained continuations with a sync join at each step means
a fully-synchronous request allocates **one** promise (the API's return type) instead of ten:

```js
function handle(request) {
  const afterC = (c) => finish(c)
  const afterB = (b) => {
    const c = stepC(b)
    return isThenable(c) ? c.then(afterC) : afterC(c)
  }
  const afterA = (a) => {
    const b = stepB(a)
    return isThenable(b) ? b.then(afterB) : afterB(b)
  }
  const a = stepA(request)
  return isThenable(a) ? a.then(afterA) : afterA(a)
}
```

Critically: `await maybeUndefined()` suspends for a tick **even when the value is
`undefined`**. Guard it: `if (v != null) return wrap(v).then(next); return next()`.

### 4.5 Resume-at-`i+1` so one async item doesn't infect the rest

When iterating work items where most are synchronous, don't `await` in the loop. Recurse
into the same function at the next index only when you actually hit a promise:

```js
function processFrom(items, i) {
  for (; i < items.length; i++) {
    const result = items[i].run()
    if (result instanceof Promise) {
      return result.then((v) => {
        commit(items[i], v)
        return processFrom(items, i + 1)   // resume the sync loop
      })
    }
    commit(items[i], result)               // sync item: no promise, no tick
  }
}
```

### 4.6 `{ ok, value }` result objects instead of try/catch across await

```js
function callUser(fn, arg) {
  try { return { ok: true, value: fn(arg) } }
  catch (value) { return { ok: false, value } }
}
```

Keeps the try/catch in a tiny leaf function that V8 can handle well, and lets the caller
stay non-async.

### 4.7 Prototype methods, not async arrow properties

```js
class Thing {
  navigate = async (opts) => { ... }   // ✗ closure allocated PER INSTANCE
}
class Thing {
  navigate(opts) { ... }              // ✓ one function object on the prototype
}
```

For a library that constructs many short-lived instances (one per request, say), the arrow
form allocates a fresh closure for every method on every instance. It also makes it harder
for V8 to reuse optimized code across instances. The reimplementation ships a diagnostic
script that asserts `freshInstance.method === Prototype.method` — a structural precondition
for its cold-start numbers.

### 4.8 Don't make things async that don't need to be

The original's blocker system made every mutation `async` so it *could* await blockers, even
though blockers were almost never registered. The fix:

```js
push(value, opts) {
  const blockers = this.blockers
  if (blockers?.length && !opts?.ignore) {
    return this.runBlockersThen(value)   // async only when blockers exist
  }
  // straight-line synchronous commit
}
```

---

## Tier 5 — Delete the allocations

### 5.1 Never create garbage you then have to clean up

```js
// ✗ closure + filtered array + joined string that intentionally creates "//" + regex pass
paths.filter(v => v !== undefined).join('/').replace(/\/{2,}/g, '/')

// ✓ decide the separator at each boundary, produce the right string directly
let out = ''
for (let i = 0; i < paths.length; i++) {
  const v = paths[i]
  if (v === undefined) continue
  const needsSep = out.length && out.charCodeAt(out.length - 1) !== SLASH && v.charCodeAt(0) !== SLASH
  if (needsSep) out += '/'
  out += v
}
```

### 5.2 The `split`/`map`/`join` chain

```js
// ✗ 2 arrays + 1 closure
value.split('/').map(seg => encode(seg)).join('/')

// ✓ 1 array, mutated in place, no closure, no megamorphic callback dispatch
const parts = value.split('/')
for (let i = 0; i < parts.length; i++) parts[i] = encode(parts[i])
return parts.join('/')
```

### 5.3 Preallocate with known length; never `push` in a sized loop

```js
const out = new Array(items.length)
for (let i = 0; i < items.length; i++) out[i] = transform(items[i])
```

`.map()` allocates a closure and goes through a generic callback dispatch. `push` in a loop
means repeated capacity growth.

### 5.4 Mutate in place when the branch is provably impossible

```js
const canBranch = node.dynamicChild || node.optionalChildren?.length || node.wildcard
const chain = canBranch ? frame.chain.slice() : frame.chain   // share when nothing can fork
chain.push(node.value)
```

Copy-on-write, but only actually copy when a write could be observed by another path.

### 5.5 Frozen shared singletons for empty values

```js
const EMPTY_OBJ = Object.freeze(Object.create(null))
const EMPTY_PARAMS = Object.freeze(Object.create(null))
```

Return these instead of a fresh `{}`. Every static result in the system then shares one
object — no per-call allocation. Freeze so an accidental mutation fails loudly instead of
corrupting every other caller.

**But:** one parity test in this codebase specifically asserts that two results do **not**
share an empty-object singleton, because user code writes to that field. Know which of your
"empty" values are read-only.

### 5.6 Noop stand-ins for expensive host objects

```js
const noopController = {
  signal: {
    aborted: false, reason: undefined,
    throwIfAborted() {}, addEventListener() {}, removeEventListener() {},
    dispatchEvent() { return false },
  },
  abort() {},
}
// ...
controller: needsCancellation ? new AbortController() : noopController
```

`new AbortController()` per work item, when 90% of items never abort, is pure waste.

### 5.7 Lazy allocation with `??=`

```js
let listeners           // undefined until someone subscribes
subscribe(fn) { (listeners ??= new Set()).add(fn) }
notify() { listeners?.forEach(fn => fn()) }
```

The original eagerly allocated four listener arrays and a buffer object per request, then
called `.slice()` on each empty array on every emit. Lazy + `if (!listeners?.length) return`
removes all of it for the common case.

### 5.8 Don't allocate in the function signature

```js
// ✗ `...rest` builds a fresh object on EVERY call, just to read one field
function f({ a, b, ...rest }) { use(rest.c) }

// ✓ positional args, monomorphic call site
function f(a, b, c) { ... }
function fPublic({ a, b, c }) { return f(a, b, c) }   // thin destructuring wrapper
```

### 5.9 Null-prototype dictionaries instead of `Map` for string keys

```js
const store = Object.create(null)
store[key] = value          // keyed-load IC, no call, no prototype hop
```

Faster than `Map.get`/`Map.set` for string keys, and no `Map` entry overhead. Trade-offs:
no `.size` without bookkeeping, no iteration order guarantee for integer-like keys, and
`delete` pushes the object into dictionary mode. The codebase wraps this in a small
`StringMap` class to keep the `Map`-ish call sites unchanged.

### 5.10 Skip the whole call when the input is trivially handled

```js
// ✗ called unconditionally for every item
const { result, used } = interpolate(item.template, params)

// ✓ 90% of items have no placeholders at all
let result = item.template
if (item.template.indexOf('$') !== -1) {
  ({ result, used } = interpolate(item.template, params))
}
```

---

## Tier 6 — Primitive-level string and scan work

These are 1.2–2.7× each and they compound, but more importantly they make the tier-1 guard
checks cheap enough to always run.

### 6.1 `charCodeAt` instead of regex / `startsWith` / indexing

```js
s.startsWith('/')            →  s.charCodeAt(0) === 47
s[0] === '?'                 →  s.charCodeAt(0) === 63
s.endsWith('/')              →  s.charCodeAt(s.length - 1) === 47
/^\/{1,}/.test(s)            →  charCode loop
```

`s[0]` allocates a one-character string. `startsWith`/`endsWith` are method dispatches.
Regex entry has fixed setup cost per call.

Nearly every regex in the original had a hand-written scanner in the reimplementation:
slash collapsing, trimming, character-class validation, HTML escaping, percent-decoding,
whitespace detection, JSON sniffing.

### 6.2 The scan-first / slice-run-append idiom

The universal shape for "transform a string, cheaply, usually a no-op":

```js
function transform(src) {
  let out = ''
  let last = 0
  for (let i = 0; i < src.length; i++) {
    if (src.charCodeAt(i) !== TARGET) continue
    out += src.slice(last, i) + REPLACEMENT
    last = i + 1
  }
  return last === 0 ? src : out + src.slice(last)   // ← same reference when unchanged
}
```

Copies runs in bulk (rope concat), never char-by-char, and returns the original reference
when there's nothing to do.

### 6.3 Tiered encoding: no-op / single-pass / full

```js
function encode(str) {
  let needsSoftEscape = false
  for (let i = 0; i < str.length; i++) {
    const c = str.charCodeAt(i)
    if (isUnreserved(c)) continue
    if (c === SPACE) { needsSoftEscape = true; continue }
    return fullEncode(str)                       // tier 3: rare
  }
  if (!needsSoftEscape) return str               // tier 1: same reference, zero work
  return replaceCode(str, SPACE, '+')            // tier 2: one pass
}
```

For the dominant input class (already-safe strings) this does N integer compares and returns
the input. `encodeURIComponent` is a C++ call that always builds a new string.

Apply the same idea to decode:

```js
function decode(str) {
  const plus = str.indexOf('+'), pct = str.indexOf('%')
  if (plus === -1 && pct === -1) return str      // no work at all
  if (pct === -1) return replaceCode(str, PLUS, ' ')   // no decodeURIComponent, no try/catch
  try { return decodeURIComponent(prepped) } catch { return prepped }
}
```

### 6.4 First-character dispatch before full string comparison

```js
// ✗ two full string compares + three ToNumber coercions for a plain string
if (s === 'false') return false
if (s === 'true') return true
return +s * 0 === 0 && +s + '' === s ? +s : s

// ✓ one charCodeAt for the dominant case
const c = s.charCodeAt(0)
if (c === 116 && s === 'true') return true
if (c === 102 && s === 'false') return false
if (c === 45 || (c >= 48 && c <= 57)) { const n = +s; return n * 0 === 0 && n + '' === s ? n : s }
return s
```

### 6.5 `| 32` for case-insensitive ASCII compare

```js
const a = s.charCodeAt(i + 1) | 32   // folds A-Z to a-z
const b = s.charCodeAt(i + 2) | 32
if (a === 50 && b === 53) { /* matched "25" case-insensitively */ }
```

Avoids `toLowerCase()` (which allocates) and case-insensitive regex.

### 6.6 Conditional normalization

```js
let needsFold = false
for (let i = 0; i < key.length; i++) {
  const c = key.charCodeAt(i)
  if (c >= 65 && c <= 90) { needsFold = true; break }
}
if (needsFold) key = key.toLowerCase()   // otherwise keep the original reference
```

### 6.7 Avoid host objects on hot paths

`URLSearchParams` for query parsing costs: a C++-side parsed list, an iterator object per
loop, a two-element array per pair, plus destructuring. A hand-rolled `indexOf`/`slice`
scanner beat it 1.2–1.6× on both encode and decode.

Same category: prefer `URL.parse()` (returns `null`) over `new URL()` + `try/catch`. The
exception path for relative inputs was on the hot path of every link construction.

### 6.8 Avoid exceptions as control flow at high frequency

```js
// ✗ throws on every relative input
try { new URL(href); isAbsolute = true } catch {}

// ✓
isAbsolute = URL.canParse(href)
```

And guard even that with a cheap pre-check (`href.charCodeAt(0) === 47` → definitely
relative, skip the call).

### 6.9 Put `try/catch` in leaf functions

A `try` block in a function containing a hot loop is worse than a `try` in a tiny leaf the
loop calls. The original nested a `try/catch` *inside a `replaceAll` callback* — a closure
plus a handler frame per match.

### 6.10 Cheap monotonic IDs

```js
// ✗ RNG + float→string + substring, per call
(Math.random() + 1).toString(36).substring(7)

// ✓
let seq = 0
const nextKey = () => (++seq).toString(36)
```

Only valid if the ID doesn't need to be unguessable or globally unique. Check first.

---

## Tier 7 — Engine-level concerns (V8)

### 7.1 Hidden-class discipline

**Initialize every field in the constructor, in a fixed order.** Adding fields afterwards
creates divergent transition chains and turns every read site polymorphic.

```js
// ✓ one shape, always
function createNode() {
  return { a: null, b: null, c: null, prefix: '', suffix: '', priority: 0 }
}

// ✗ three shapes: base(4), base+prefix+suffix(6), base+parse+priority(6, different chain)
function createNode() { return { a: null, b: null, c: null, d: null } }
// ...later: node.prefix = x; node.suffix = y
```

The original was explicit about this, with a comment on its factory: *"Keys must be declared
in the same order as in the type, to ensure they are represented as the same object class in
the engine."* The reimplementation regressed here and ended up with 3+ node shapes.

**Keep key order identical across all return branches** of a function that produces one
logical type. Two `return { a, b, c }` / `return { b, a, c }` sites produce two hidden
classes for the same nominal type.

### 7.2 Tagged single shape beats a discriminated union of shapes

```js
// ✗ two maps at the load site
type Op = { t: 0, s: string } | { t: 1, k: string }

// ✓ one map; the unused field is a wasted word, which is cheaper than a polymorphic IC
type Op = { t: number, s: string, k: string }
```

### 7.3 Don't put accessors on hot objects

`Object.defineProperty(obj, 'x', { get })` converts a data property into an accessor and
poisons the load site. Lazy computation is worth it for genuinely cold, expensive things —
but install the getter on a *wrapper* object, never on the one in the hot loop.

### 7.4 Sentinels that don't degenerate

```js
const MISS = '\0'      // not '', not undefined
let hotKey = MISS
```

Comment from the source: *"starts as a value no real input can equal, so the compare never
runs against the empty sentinel (that deopts compare ICs)."*

### 7.5 Avoid `delete` on hot objects

`delete` transitions an object to dictionary mode permanently. Acceptable in a cache's
eviction path; not acceptable on a `get`.

### 7.6 Verify, don't assume

The codebase ships diagnostic scripts using `--allow-natives-syntax` to print
`%GetOptimizationStatus` for ~20 named hot functions, run the exact benchmark loops, then
force-optimize (`%PrepareFunctionForOptimization` → run → `%OptimizeFunctionOnNextCall` →
re-status) to distinguish "not hot enough" from "not optimizable". Bit flags on Node 24:

```
1 fn | 2 never-opt | 8 maybe-deopted | 16 optimized | 32 maglev | 64 turbofan
128 interpreted | 32768 baseline
```

If a hot function reports `never-opt`, no amount of micro-optimization will help; find out
why (usually: a deopt loop, `eval`, `with`, or a shape explosion).

---

## Tier 8 — Shrink the graph, not just the code

Bundle size is a *graph reachability* problem, not a minification problem.

### 8.1 Keep leaf modules leaf

The original's path utilities imported a helper from a 1300-line module that itself imported
three more. Every consumer of the small utility dragged in the whole matcher. Extracting the
helper into a 112-line leaf module fixed it.

**Rule:** if module X is imported by many things, X may only import other leaves.

### 8.2 Split cold paths into modules and `import()` them

```js
let cachedImpl
function coldPath(arg) {
  if (cachedImpl) return cachedImpl(arg)                  // memoize: only the FIRST call pays
  return import('./cold-impl').then(({ impl }) => {
    cachedImpl = impl
    return impl(arg)
  })
}
```

Server-only code, HMR code, and rarely-used subsystems each became separate modules reached
only by dynamic import. Guard dev-only code so it strips:

```js
if (process.env.NODE_ENV !== 'production') {
  Impl.prototype._devOnlyThing = async function () {
    const { helper } = await import('./dev-helper')
    ...
  }
}
```

### 8.3 Conditional exports vs runtime `import()` — a real trade-off

Two strategies for keeping server code out of client bundles:

**Conditional exports** (the original): map `"./env"` to `env/client.js` under the `browser`
condition, where `export const isServer = false`. Bundlers fold `if (isServer)` to a
constant and delete the block. Powerful — it makes *every* server branch in the codebase
disappear. Cost: an enormous exports map (that library had ~33 conditional entries with
`browser`/`node`/`worker`/`workerd`/`deno`/`bun`/`development` variants), and it only works
if the bundler honours your conditions.

**Runtime boolean + dynamic import** (the reimplementation): `export const isServer =
typeof document === 'undefined' ? true : undefined`. Simple, one module, works everywhere —
but `if (isServer ?? ...)` is a runtime check and **no server block is ever dropped**. This
is a direct contributor to the reimplementation *losing* on bundle size (1.21× larger gzip)
despite winning everywhere else.

If bundle size matters more than build simplicity, take the conditional-exports route.

### 8.4 A trap worth knowing

The reimplementation's own source comment:

> *"Boolean-only on purpose: re-exporting server loaders from here pulled the SSR graph into
> every `utils` import and blocked dead-code elimination."*

A widely-imported module that re-exports a heavy implementation defeats tree-shaking for
everyone. Environment flags should be **values only**, never re-export hubs.

### 8.5 Types-only subpath exports

Map a public subpath to a `.d.ts`-equivalent module containing only `import type`:

```json
"./serializer/transformer": "./src/serializer/transformer-types.ts"
```

Consumers get the types; the heavy runtime dependency behind it never enters the graph.

### 8.6 Delete dependencies

Each runtime dep is a subgraph you don't control. The reimplementation dropped:
- an external reactive-store library (~50 lines of hand-rolled code replaced it)
- a user-agent classification library (by deleting the feature that needed it — §9.3)
- and inlined a tiny assertion helper

The corresponding package went from 4 runtime deps to 2.

### 8.7 Assert DCE structurally, not numerically

Bundle-size numbers drift. Assert *what must not be reachable*:

```js
const serverMarkers = ['loadServerRoute', 'createRequestHandler', 'crossSerializeStream']

it('drops the server graph when only a leaf util is imported', async () => {
  const { entry } = await bundle(`import { util } from 'lib'; console.log(util({}))`)
  expect(entry).toContain('util')
  expect(entry).not.toContain('CoreClass')
  expect(serverMarkers.filter(m => entry.includes(m))).toEqual([])
})

it('keeps the cold path in an async chunk, not the entry', async () => {
  const { entry, chunks } = await bundle(`import { createThing } from 'lib'; ...`)
  expect(serverMarkers.filter(m => entry.includes(m))).toEqual([])
  const asyncCode = Object.entries(chunks).filter(([n]) => n !== 'entry.js').map(([, c]) => c).join('\n')
  expect(asyncCode).toContain('loadServerRoute')   // it must exist — just not here
})
```

This is a *test*, run in CI, that fails the moment someone adds a static import that
reconnects the graph. It's the single most valuable bundle-size safeguard, because it
catches the regression at the cause rather than at the symptom.

### 8.8 Measure the initial graph, not the entry chunk

Walk `chunk.imports` transitively from every entry chunk and sum min+gzip. Deliberately do
**not** follow `dynamicImports` — that's the point of splitting them out. Disclose that in
your published numbers.

---

## Tier 9 — Narrow the support matrix (this is an optimization)

### 9.1 Modern runtime targets delete compatibility code

Pinning to a recent Node and a single major of the peer framework unlocked, and the
reimplementation actually uses:

| API | Replaces |
|---|---|
| `URL.canParse()` / `URL.parse()` | `new URL()` in `try/catch` |
| `Object.hasOwn()` | `Object.prototype.hasOwnProperty.call()` |
| `Error.isError()` | `instanceof Error` (cross-realm-correct) |
| `String.prototype.toWellFormed()` | manual lone-surrogate handling / `try/catch` around `encodeURIComponent` |

Usage count: 19 call sites across those four APIs in the reimplementation, **zero** in the
original — which still supports older runtimes. The original also maintains a
multi-TypeScript-version type-test matrix (5 TS versions), which the reimplementation drops
entirely.

Config-level consequences: `target: ES2024` / `lib: ES2024` vs `target: ES2020` /
`lib: ES2022`. Higher targets mean the compiler stops downlevelling async/await, classes,
optional chaining, and spread into slower ES5 shims.

### 9.2 Deleting a feature can unlock a better data structure

The original supported per-item case sensitivity, which forced it to maintain **two** lookup
maps and probe both on every step. The reimplementation scoped case sensitivity to the
container instead, which allowed **one** dictionary with pre-folded keys — halving the
lookups and removing a `Map`.

That's not a micro-optimization. That's a feature-scope decision that changed the algorithm.
Look for these: a rarely-used per-item option is often what's blocking your best data
structure.

### 9.3 Deliberately changing behaviour, and documenting it

The original inspected a request header with a third-party classification library and, for
one class of client, buffered the entire output instead of streaming it. The reimplementation
deletes the branch: everything streams, always. That removed a dependency, a header parse,
and a conditional from every request.

This is a **behaviour change**, not an optimization. It's defensible only because it's stated
plainly in the README with the manual workaround. If you take this route, be that explicit.

### 9.4 Lint config as a performance policy

The reimplementation's linter runs 242 rules with a `"perf": "warn"` category, and — more
interestingly — **disables** rules that fight performance:

```jsonc
"unicorn/prefer-string-replace-all": "off",   // manual scan beats replaceAll
"unicorn/no-new-array": "off",                // new Array(n) preallocation is wanted
"unicorn/no-array-for-each": "off",
"typescript/prefer-for-of": "off"             // indexed for loops are faster
```

Your style guide encodes performance decisions whether you intend it to or not. Make the
exemptions explicit and commented.

---

## Tier 10 — The measurement discipline

This is the most transferable section. Without it, tiers 1–4 are not engineering.

### 10.1 Gate the benchmark on equal work

**Before printing a single number**, prove both implementations do the same amount of work.
Instrument the user-facing callback and count invocations across a fixed script:

```js
async function countWork(createSubject) {
  const counter = { calls: 0 }
  const subject = createSubject(counter)

  for (let i = 0; i < 100; i++) await subject.run(destinations[i % 5])
  const warmA = counter.calls

  for (let i = 0; i < 100; i++) await subject.run({ id: String(i % 50) })
  const warmB = counter.calls - warmA                       // warm subject, varied input

  const fresh = { calls: 0 }
  const freshSubject = createSubject(fresh)
  for (let i = 0; i < 100; i++) await freshSubject.run({ id: String(i % 50) })

  return { warmA, warmB, cold: fresh.calls }
}

const mine = await countWork(makeMine)
const theirs = await countWork(makeTheirs)
if (mine.warmA !== theirs.warmA || mine.warmB !== theirs.warmB || mine.cold !== theirs.cold) {
  throw new Error(`Work parity failed: ${JSON.stringify({ mine, theirs })}`)
}
```

Three counters — warm/repeated, warm/varied, and cold — because each catches a different
class of accidental cheating. Run it **in the parent process before spawning any timing
run**, and print the verified counts in the report header so the table carries its own
provenance.

Ship it as a standalone command too (`audit:work`), exiting nonzero on divergence.

### 10.2 Pin the same numbers as an offline unit test

```js
expect({ warmA, warmB, cold }).toEqual({ warmA: 40, warmB: 100, cold: 100 })
// and the contrast case that proves the caching claim isn't vacuous:
expect(callsWithCachingEnabled).toBe(2)
```

The `40/100/100` vs `2` contrast proves the library is neither over-caching (inflating
benchmarks) nor ignoring the caching option (making the feature a lie). This runs in CI with
no network and no competitor installed.

### 10.3 Rotate inputs to defeat *your own* caches

If you ship intern caches, a benchmark that reuses one input measures your `Map.get`. Build
fixture pools and advance a cursor on **both** sides:

```js
const samples = [/* 6 distinct */]
let cursor = 0
measure(() => mine(samples[cursor++ % samples.length]))
measure(() => theirs(samples[cursor++ % samples.length]))
```

For structured inputs, generate a cross-product (e.g. 64 distinct keys) and index with a
power-of-two mask: `needles[cursor++ & 63]`.

**Audit this honestly.** One row in the published table (a 61× win) rotated 100 inputs
against a 256-entry cache — so after the first iteration it was measuring a dictionary hit,
not the algorithm. The rotation must exceed the cache size.

### 10.4 Warm up inside the same closure you'll time

```js
function measure(fn, ms = 1500) {
  const warmupEnd = performance.now() + 200
  while (performance.now() < warmupEnd) fn()      // untimed: let V8 tier up + ICs stabilize

  let ops = 0
  const start = performance.now()
  const end = start + ms
  while (performance.now() < end) { fn(); ops++ }
  return ops / ((performance.now() - start) / 1000)   // re-read elapsed, don't assume `ms`
}
```

Duration-based throughput, not fixed-N latency: slow implementations aren't punished by
wall-clock blowup and fast ones get enough samples.

### 10.5 Isolate sections in separate processes

Re-exec the harness per section, keyed by an env var, and pass results back as one JSON
line on stdout:

```js
function runSection(name) {
  const r = spawnSync(process.execPath, [...process.execArgv, ...process.argv.slice(1)],
    { env: { ...process.env, BENCH_SECTION: name }, encoding: 'utf8' })
  const line = r.stdout.split('\n').find(l => l.startsWith('BENCH_JSON:'))
  if (!line) { process.stderr.write(r.stdout); throw new Error(`section ${name} produced no JSON`) }
  return JSON.parse(line.slice('BENCH_JSON:'.length))
}
```

Preserving `process.execArgv` keeps your `--expose-gc` etc. Heap state, megamorphic IC
pollution, and code-cache contents from section A can't contaminate section B. Call
`globalThis.gc?.()` at the top of each section.

### 10.6 Compare against the *published artifact*, not local source

Import the competitor from real `node_modules` (pinned versions, printed in the report
header), and deep-import its `dist/` file directly when a symbol isn't in its export map:

```js
import { x as mine } from '../packages/core/src/x.ts'
import { x as theirs } from '../node_modules/competitor/dist/esm/x.js'
```

Run this under plain `node`, **not** your test runner, so your test-time aliases (which
redirect the competitor's package name to your own source) aren't in effect.

Be aware of the asymmetry this creates: if you ship raw TS and they ship built ESM, you're
comparing different compilation pipelines. Disclose it.

### 10.7 Prove all candidates compute the same function *before* timing them

Any shootout between N implementations should assert equivalence at module load:

```js
for (const input of fixtures) {
  expect(decode(encode(input))).toBe(input)
}
// and for a multi-way shootout:
if (implA(x) !== implB(x)) throw new Error('Implementation mismatch!')
```

A bench file that throws is infinitely better than a bench file that reports a fast wrong
answer.

### 10.8 Defeat DCE of the benchmarked expression

```js
let sink = 0
function batch(input) {
  let size = 0
  for (let i = 0; i < N; i++) size += operation(input).length
  sink = size
}
// at module scope:
void sink
```

Consume the result into a module-level binding that is then referenced. Neither the bundler
nor V8 can prove the computation dead.

### 10.9 Publish your losing metric

The reimplementation's README reports its bundle size as **1.21× larger** than the
competitor, with an explanation of why and a pointer to re-run the measurement. It also
segregates rows that aren't strictly equal work into their own table, and **omits entirely**
a row where its implementation is allowed to skip the call.

A benchmark table that only contains wins is marketing. One that contains losses,
methodology, and exclusions is evidence.

### 10.10 Be honest about statistical rigour

The harness reports a single ops/s scalar per side — no stddev, no RME, no median-of-N, no
A/B interleaving, and it always runs "mine first". That's a real weakness. If you're
publishing ratios that people will make decisions on, add interleaving and dispersion.
At minimum, fence the environment in the report ("4-core X, Linux, Node 24, in-memory") and
explicitly forbid cross-environment comparison of your own numbers.

---

## Tier 11 — Testing a fast-path architecture

Once you have two paths, **the parity test is the most valuable test in the repo.**

### 11.1 Why the eligibility gate is not enough

The gate is a *negative* proof: "no exotic feature is present." It says nothing about
whether the fast lane produces the same results, the same call sequence, or the same error
semantics for the plain inputs it *does* accept.

### 11.2 What a fast-path parity suite must assert

From the real suite, generalized. Each of these is a bug class the fast lane invites:

1. **Derived keys recompute.** Navigate with input A, then input B; assert the second result
   reflects B and that the cache key includes the varying dimension.
   → *catches: fast-lane cache key omits a dimension.*
2. **Per-item mutable state is not shared.** `expect(a.ctx).not.toBe(b.ctx)` and
   `expect(Object.isFrozen(a.ctx)).toBe(false)`.
   → *catches: the most tempting fast-path allocation saving.*
3. **Synchronous user-code throw.** Assert: called exactly once, error handler fired exactly
   once with the *identical* error instance, the public promise **resolves** (doesn't
   reject), and the item is committed in an error state.
   → *catches: sync execution double-invoking, or leaking a throw through the public API.*
4. **Async rejection.** Same contract as (3) for the promise path.
5. **Identity fields survive object reuse.** Pin every field user code or devtools reads:
   index, id, parent linkage, static metadata, flags.
   → *catches: pooled/cloned objects losing fields.*
6. **Defaults survive cache reuse.** A→B→A, and the *cached* A must still carry its
   defaulted/validated values.
   → *catches: the template snapshot stripping too much.*
7. **Empty-value singletons are not shared where they're written.**
   `expect(a.field).not.toBe(b.field)` for fields user code mutates.
   → *catches: over-eager `EMPTY_OBJ` reuse (§5.5).*
8. **Mid-sequence abort unwinds correctly.** When item 1 of 3 fails, assert items 2–3 were
   never invoked **and** that item 1's in-flight flags were cleared.
   → *catches: the `resume-at-i+1` pattern (§4.5) leaving `isPending: true` forever. A
   throughput benchmark can never surface this — the UI just hangs.*

### 11.3 Run the upstream suite against your implementation, unmodified

If you're reimplementing a known API, don't write your own compatibility tests — **vendor
theirs and alias the module specifiers**:

```js
resolve: {
  alias: {
    'competitor-core': resolve(root, 'packages/core/src/index.ts'),
    'competitor-ui':   resolve(root, 'packages/ui/src/index.ts'),
  }
}
```

Add a resolver for subpath naming differences (their `camelCase` subpaths → your
`kebab-case` files), so vendored tests import *verbatim*:

```js
function resolveSubpath(baseDir, rest) {
  const kebab = rest.split('/').map(s => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()).join('/')
  for (const c of [`${baseDir}/${kebab}.ts`, `${baseDir}/${kebab}/index.ts`, `${baseDir}/${rest}.ts`]) {
    if (existsSync(c)) return c
  }
}
```

The reimplementation runs **163 vendored runtime specs + 26 vendored type-test files**,
including ~25 regression tests named after upstream issue numbers. It keeps first-party and
vendored suites in **separate configs with mutually exclusive `include`/`exclude`** so the
two classes of evidence never blur.

It also aliases the competitor's own *third-party dependency* to its hand-rolled replacement,
so vendored tests exercise the replacement rather than the original library.

### 11.4 Also vendor their benchmarks

Running the competitor's own micro-benchmarks against your implementation prevents the
failure mode of only inventing self-favourable benchmarks.

### 11.5 Batch heavy suites into isolated processes

```js
spawnSync('vitest', ['run', '--pool=forks', '--maxWorkers=1', ...batch],
  { stdio: 'inherit', env: { ...process.env, NODE_OPTIONS: '--max-old-space-size=4096' } })
```

Full isolation, serial, deterministic; any nonzero status aborts.

### 11.6 CI gates

Format → lint → unused-code detection (with config hints as errors) → unit tests (including
the DCE and parity suites) → type tests → each vendored suite as its own step. Four parallel
jobs, everything on the pinned runtime.

---

## Tier 12 — Risk register: what you actually buy the speed with

Every technique above has a failure mode. These were all found in the shipped code — they
are the price, not hypotheticals.

**Correctness / semantics**
- Hand-rolled encoders diverge from spec-compliant host implementations on edge cases
  (reserved-character sets, malformed input, exponent notation). Round-trips still work;
  produced strings, cache keys, and cross-boundary comparisons differ.
- Fast paths that skip normalization produce different output for malformed-but-accepted
  inputs.
- Identity-keyed memos on mutable objects return stale results under in-place mutation.

**Architecture**
- Replacing a fine-grained dependency-tracking system with a single broadcast channel makes
  each notification cheaper but wakes **every** subscriber, each running its selector. This
  can be a net loss at scale, and it was here: a single-field toggle went from one targeted
  write to a full snapshot copy + O(n) re-map + global broadcast.
- Removing a computed/memoized derivation layer means derived values recompute and reallocate
  on **every** read. The codebase has comments working around exactly this
  (*"prefer the stable snapshot; `.get()` maps a new array on every call"*).
- Precomputation that nothing reads is pure setup cost.
- Fast lanes that allocate more than the general path on their *slow* branch are a bet on the
  fast branch always winning. Verify the bet.

**The one that matters most**

> The headline 16×/14×/30× rows measure a fast lane gated on `subscribers.size === 0`. In the
> real deployment configuration, the library always installs a subscriber — so **the lane
> never engages in production.** The benchmark ran in an environment where it did.

Before publishing a number, assert that the fast lane you're measuring is actually taken
under the configuration your users run. Add a test that fails if the gate closes in the
default setup. This is the single most important lesson in this document.

---

## Appendix — Order of operations

1. **Build the harness first.** Equal-work gate, rotating inputs, process isolation,
   duration-based timing, comparison against the published artifact.
2. **Profile allocations, not just time.** The biggest wins came from removing allocations
   the profiler attributed to functions that "looked cheap."
3. **Find the dominant input class.** What do 90% of calls actually look like? That's your
   fast lane's target.
4. **Add tier-1 fast lanes with blacklist gates and full fallback.** Write the parity suite
   in the same commit.
5. **Move work to setup time.** Compile patterns, precompute tables, hoist capability flags.
6. **Add caches from the cheapest layer up.** One-slot memo → dictionary → LRU. Cache the
   whole downstream result. Bound every cache.
7. **Delete the async** on paths that usually don't suspend.
8. **Delete the allocations.**
9. **Micro-optimize the primitives** — now they're also the guard checks for step 4.
10. **Verify optimization tiers** with `%GetOptimizationStatus`. Fix shape explosions.
11. **Shrink the graph.** Split cold modules, dynamic-import them, assert with DCE tests.
12. **Re-run the equal-work gate.** Then publish, including your losses and exclusions.