Node.js Performance

Use this workflow to turn Node.js performance/resource investigations into safe, reviewable PRs.

Goals

• Improve execution time first: reduce p50/p95/p99 latency and increase throughput without changing intended behavior.
• Reduce CPU, memory, event-loop lag, I/O pressure, or lock contention when it supports execution-time gains.
• Ship small, isolated changes with measurable impact.

Operating Rules

• Work on one optimization per PR.
• Always choose the highest expected-impact task first.
• Confirm and respect intentional behaviors before changing them.
• Prefer low-risk changes in high-frequency paths.
• Prioritize request/job execution-path work over bootstrap/startup micro-optimizations unless startup is on the critical path at scale.
• Include evidence: targeted tests + before/after benchmark.

Impact-First Selection

Before coding, rank candidates using this score:

priority = (frequency x blast_radius x expected_gain) / (risk x effort)

Use 1-5 for each factor:

• frequency: how often the path runs in production.
• blast_radius: how many requests/jobs/users are affected.
• expected_gain: estimated latency/resource improvement.
• risk: probability of behavior regression.
• effort: engineering time and change surface area.

Pick the top-ranked candidate, then validate with a baseline measurement.

If two candidates have similar score, pick the one with clearer end-to-end execution-time impact.

Prioritization Targets

Start with code that runs on every request/job/task:

• Request/job wrappers and middleware.
• Retry/timeout/circuit-breaker code.
• Connection pools (DB/Redis/HTTP) and socket reuse.
• Stream/pipeline transformations and buffering.
• Serialization/deserialization hot paths (JSON, parsers, schema validation).
• Queue consumers, schedulers, and worker dispatch.
• Event listener attach/detach lifecycle and cleanup logic.

Deprioritize unless justified by production profile:

• One-time startup/bootstrap code.
• Rare admin/debug-only flows.
• Teardown paths that are not on the steady-state critical path.

Common Hot-Path Smells

• Recomputing invariant values per invocation.
• Re-parsing code/AST repeatedly.
• Duplicate async lookups returning the same value.
• Per-call heavy object allocation in common-case parsing.
• Unnecessary awaits in teardown/close/dispose paths.
• Missing fast paths for dominant input shapes.
• Unbounded retries or retry storms under degraded dependencies.
• Excessive concurrency causing memory spikes or downstream saturation.
• Work done for logging/telemetry/metrics formatting even when disabled.

Execution Workflow

1. Pick one candidate

• Rank candidates and pick the highest priority score.
• Explain the issue in one sentence.
• State expected impact (CPU, latency, memory, event-loop lag, I/O, contention).

2. Prove it is hot

• Add a focused micro-benchmark or scenario benchmark.
• Capture baseline numbers before editing.
• Prefer scenario benchmarks that include real request/job flow when the goal is execution-time improvement.
• For resource issues, capture process metrics (rss, heap, FD count, event-loop delay).

3. Design minimal fix

• Keep behavior-compatible defaults.
• Add fallback path for edge cases.
• Avoid broad refactors in the same PR.

4. Implement

• Make the smallest patch that removes repeated work.
• Keep interfaces stable unless change is necessary.

5. Test

• Add/adjust targeted tests for new behavior and regressions.
• Run relevant package tests (not only whole-monorepo by default).
• Add concurrency/degradation tests when the bug appears only under load.

6. Benchmark again

• Re-run the same benchmark with same parameters.
• Report absolute and relative deltas.
• Include latency deltas first (p50/p95/p99, throughput), then resource deltas when applicable.

7. Package PR

• Branch naming: codex/perf-<area>-<change>.
• Commit message: perf(<package>): <what changed>.
• Include risk notes and rollback simplicity.

8. Iterate

• Wait for review, then move to next isolated improvement.

Benchmarking Guidance

• Keep benchmark scope narrow to isolate one change.
• Use warmup iterations.
• Measure both:
• micro: operation-level overhead.
• scenario: request/job flow, concurrency, and degraded dependency condition.
• For execution-time work, scenario numbers are the decision-maker; micro numbers are supporting evidence.
• Always print:
• total time
• per-op time
• p50/p95/p99 latency when applicable
• speedup ratio
• iterations and workload shape
• resource counters (rss, heap, handles, event-loop delay) when relevant

Resource Exhaustion Checklist

• Cap concurrency at each boundary (ingress, queue, downstream clients).
• Ensure timeout + cancellation are wired end-to-end.
• Ensure retries are bounded and jittered.
• Confirm listeners/timers/intervals are always cleaned up.
• Confirm streams are closed/destroyed on success and error paths.
• Confirm object caches have size/TTL controls.

CI / Flake Handling

• If CI-only failures appear, add temporary diagnostic payloads in tests.
• Serialize only affected flaky tests when resource contention is the cause.
• Keep determinism improvements in test code, not production code, unless required.

Output Template

For each PR, report:

1. Issue being fixed.
2. Why it matters under load.
3. Code locations changed.
4. Tests run and results.
5. Benchmark before/after numbers (execution first: p50/p95/p99 and throughput).
6. Risk assessment.
7. Next candidate optimization.