React Technical Documentation

📋 Executive Summary

Problem: React Counter component had critical state management bugs caused by stale closures

Solution: Functional state updates pattern: setState(prev => ...)

Result: 5 bugs fixed, 40+ tests passing (100%)

What is a Stale Closure?

❌ Problem: Stale Closure

const handleIncrement = () => {
  setCount(count + 1);  // 'count' is captured at render time
  console.log('Count:', count);  // Always logs OLD value
};

// If user clicks button:
// Render 1: count = 0 (captured)
// Click handler: uses count = 0 (STALE!)
// After render: count = 1
// Click handler again: still has count = 0 (STALE!)

✅ Solution: Functional Update

const handleIncrement = () => {
  setCount((prevCount) => {
    // prevCount is ALWAYS the current state
    console.log('Count:', prevCount + 1);  // Logs CURRENT value
    return prevCount + 1;
  });
};

// Now each call gets the latest state!

🔍 Root Cause Analysis

The Problem: JavaScript Closures

When you create a function, it captures variables from its scope. These captured values don't update—they're frozen at capture time.

1

Component Renders
count = 0 (captured in closure)

→

2

User Clicks
Handler still sees count = 0

→

3

State Updates
count becomes 1

→

4

Click Again
Handler STILL sees count = 0 ❌

The 3 Core Issues

1. Direct State Capture

Using state variable directly captures its value at closure creation

setCount(count + 1)

2. React Batching

Multiple updates in same handler all use the same stale value

setCount(count + 1); setCount(count + 1);

3. Async Callbacks

setTimeout/Promise callbacks capture state at creation, not execution

setTimeout(() => setCount(count + 1), 1000)

React's Batching (The Hidden Issue)

❌ Without Functional Updates

setCount(count + 1) // 0 → 1

Final: count = 1 (Should be 3!)

✅ With Functional Updates

setCount(p => p + 1) // 0 → 1

setCount(p => p + 1) // 1 → 2

setCount(p => p + 1) // 2 → 3

Final: count = 3 ✅

💥 System Impact

User-Facing Symptoms

🔴 Lost Updates

Rapid button clicks register as single click

Click 5 times → Shows 1 instead of 5

🔴 Delayed Operations Fail

setTimeout increments don't work

Click "Delayed" → Nothing happens

🟠 Batch Operations Broken

"Increment x3" only increments by 1

Click "x3" button → Shows 1 instead of 3

🟠 Unreliable State

Counter shows unpredictable values

State appears to revert to old values

Real Scenario: Lost Update

t=0ms: Component renders, count = 0 (captured)

t=50ms: User clicks +5 button
setCount(count + 5) → setCount(0 + 5)

t=100ms: User clicks +5 button AGAIN
setCount(count + 5) → setCount(0 + 5) ❌ Still uses old closure!

t=150ms: User clicks +5 button AGAIN
setCount(count + 5) → setCount(0 + 5) ❌ Still uses old closure!

Expected: 0 + 5 + 5 + 5 = 15
Actual: 5 (Lost 2 updates!)
Lost Data: 10 points! 🔴

✅ Bug Fixes Explained

Bug #1: Stale Closure in Event Handlers

❌ Before (Buggy)

const handleIncrement = () => {
  setCount(count + 1);
  console.log('Count:', count);  // Logs OLD
};

// First click: count=0 → sets to 1, logs 0
// Second click: count=1 but handler logs 0 ❌

✅ After (Fixed)

const handleIncrement = () => {
  setCount((prevCount) => {
    const newCount = prevCount + 1;
    console.log('Count:', newCount);  // Logs CURRENT
    return newCount;
  });
};

// Any click: gets current count, logs correct value ✅

Why it works: The parameter prevCount is evaluated when setState runs, giving the actual current state, not a captured value.

Bug #2: Stale Closure in setTimeout

❌ Before (Buggy)

const handleDelay = () => {
  setTimeout(() => {
    setCount(count + 1);  // Captures count NOW
  }, 1000);
};

// t=0: handleDelay() called, count=0 captured
// t=500: User clicks, count becomes 5
// t=1000: timeout fires, uses count=0 ❌
// Result: 1 (should be 6!)

✅ After (Fixed)

const handleDelay = () => {
  setTimeout(() => {
    setCount((prevCount) => prevCount + 1);  // Evaluated at t=1000
  }, 1000);
};

// t=0: handleDelay() called, function scheduled
// t=500: User clicks, count becomes 5
// t=1000: timeout fires, gets current count=5
// Result: 6 ✅

Why it works: The functional update is evaluated WHEN the timeout fires, not when setTimeout is called. Gets the latest state at execution time.

Bug #3: Multiple Updates (React Batching)

❌ Before (Buggy)

const handleTriple = () => {
  setCount(count + 1);  // count=0, schedules 0+1=1
  setCount(count + 1);  // count=0, schedules 0+1=1
  setCount(count + 1);  // count=0, schedules 0+1=1
};
// React batches: all 3 are queued, all see count=0
// Result: 1 (should be 3!) ❌

✅ After (Fixed)

const handleTriple = () => {
  setCount((p) => p + 1);  // Queue: 0 → 1
  setCount((p) => p + 1);  // Queue: 1 → 2
  setCount((p) => p + 1);  // Queue: 2 → 3
};
// Each update reads result of previous
// Result: 3 ✅

Why it works: When you use functional updates, React queues them in order and each one is evaluated with the result of the previous one. Creates a proper state update chain.

📖 Implementation Guidelines

The Golden Rule

Always use functional updates when new state depends on previous state

setState(prev => newValue)

When to Use Functional Updates

✅ New state depends on previous state

✅ State might be updated rapidly

✅ Update is in a callback (setTimeout, Promise)

✅ Multiple state updates in same handler

✅ Using async/await

✅ Event handlers that might fire in quick succession

Pattern Comparison

❌ Don't Do This

setCount(count + 1);
setValue(value.toUpperCase());
setList([...list, item]);
setUser({...user, name: newName});

✅ Do This Instead

setCount(prev => prev + 1);
setValue(prev => prev.toUpperCase());
setList(prev => [...prev, item]);
setUser(prev => ({...prev, name: newName}));

useCallback: The Wrong Solution

❌ Doesn't Fix Stale Closures

const handleIncrement = useCallback(() => {
  setCount(count + 1);  // Still stale! useCallback doesn't help
}, [count]);  // Must add count to deps = unstable reference

✅ Functional Updates + useCallback

const handleIncrement = useCallback(() => {
  setCount(prev => prev + 1);  // Always current!
}, []);  // Empty deps! Reference is stable AND no stale state

Complex State with useReducer

✅ For Very Complex State

const [state, dispatch] = useReducer(reducer, initialState);

const handleIncrement = () => {
  dispatch({ type: 'INCREMENT' });
};

// In reducer (always has access to current state)
function reducer(state, action) {
  switch(action.type) {
    case 'INCREMENT':
      return { ...state, count: state.count + 1 };
    default:
      return state;
  }
}

❓ FAQ

Q: Should I always use functional updates?

A: YES. It's the safest pattern. Even if code works now, it's future-proof and handles edge cases automatically. No performance downside.

Q: Why not just use useCallback?

A: useCallback only stabilizes references. It doesn't solve stale closures. You still need functional updates. Use both: functional updates ALWAYS, add useCallback if needed for performance.

Q: What's the performance impact?

A: Negligible. The function runs immediately during batching. No performance downside whatsoever. Safe for high-frequency updates.

Q: Can I mix direct and functional updates?

A: NO. Mixing creates bugs. Always use functional updates throughout for consistency.

Q: What about async/await?

A: Use functional updates inside async functions too. They work with Promise chains, fetch calls, etc.

Q: How do I migrate existing code?

A:

Find all setState calls
Check if they use current state value
If yes, wrap in functional update: setState(prev => ...)
Test thoroughly

Q: useState vs useReducer?

A:

useState + functional updates: Good for simple state (use this)
useReducer: Better for complex state with multiple fields or dependencies
Both solve stale closures - pick based on complexity

Q: What about TypeScript?

A: Fully compatible. TypeScript infers types correctly:

setCount((prev: number): number => prev + 1);
// Or with inference (recommended):
setCount(prev => prev + 1);