RFC: [Feature Request] Inject structural change metadata (`ChangePayload`) as an argument into the `useEffect` callback

[Feature Request] Inject structural change metadata (ChangePayload) as an argument into the useEffect callback

Summary

I propose extending the signature of the useEffect callback function to optionally accept a single argument: a ChangePayload object. This metadata object provides explicit access to current values, previous values, and an array of indices representing exactly which dependencies triggered the current effect execution pass.

Motivation

In legacy class components, developers had granular, imperative control over side-effect execution branching via the componentDidUpdate(prevProps, prevState) lifecycle method. This allowed developers to easily evaluate the precise delta between frames (e.g., if (this.props.id !== prevProps.id)).

With functional components and useEffect, this diagnostic visibility was fully abstracted away. If an effect relies on multiple cohesive dependencies, the callback executes blindly without knowing the specific trigger vector.

The Analogy to useReducer:
Much like a reducer function receives a discrete action object with a type/payload to determine how state should mutate, a multi-dependency useEffect callback should be able to receive a change payload to determine how side-effect execution should branch. Currently, developers are forced to choose between splitting code across multiple disconnected effects (fragmenting logic) or managing complex useRef snapshots to diff properties manually.

Detailed Design

We propose modifying the execution lifecycle so that the reconciler injects a structured payload directly into the effect callback:

interface ChangePayload<T extends ReadonlyArray<unknown>> {
  currentDepValues: T;
  previousDepValues: T;
  updatedDepIndex: number[]; // Array of dependency indices that failed equality checks
}

Code Implementation Example:

Instead of managing tracking refs, developers can treat dependency mutations as distinct event triggers within a single, cohesive side-effect block:

import { useEffect, useState } from 'react';

export function CoreDataEngine() {
  const [authHeader, setAuthHeader] = useState('Bearer xyz');
  const [streamPayload, setStreamPayload] = useState({ coordinates: [] });
  const [circuitBreaker, setCircuitBreaker] = useState(false);

  useEffect((changePayload) => {
    // If changePayload is undefined, it is the initial mount pass
    if (!changePayload) return;

    const { updatedDepIndex, currentDepValues, previousDepValues } = changePayload;

    // Direct branching reminiscent of action-handling in useReducer
    if (updatedDepIndex.includes(0)) {
      console.log(`Auth token updated from ${previousDepValues[0]} to ${currentDepValues[0]}. Re-signing sockets.`);
      // execTokenRotation();
    }

    if (updatedDepIndex.includes(1)) {
      console.log('Telemetry coordinate payload arrived. Re-rendering stream vectors.');
      // execVectorRender();
    }

    if (updatedDepIndex.includes(2)) {
      console.log('System critical circuit breaker tripped. Terminating pipelines.');
      // execEmergencyTeardown();
    }
  }, [authHeader, streamPayload, circuitBreaker]); // Index 0, 1, 2
}

Key Advantages

1. Unifies Contextual Logic: Eliminates the anti-pattern of splitting highly cohesive dependencies into 3 or 4 separate useEffect declarations simply because their runtime execution logic differs slightly based on what changed.
2. Deterministic Control Over Batching: When React batches multiple state setters together, updatedDepIndex provides an array of all indices that mutated in that specific batch, giving developers a clear execution map of the transaction.
3. Ergonomic Parity with class lifecycles: Brings back the missing granular diffing power of componentDidUpdate without introducing stateful lifecycle clutter to functional components.

Alternatives Considered

The primary alternative is user-land implementation via custom hooks wrapping useRef. However, this requires continuous overhead, duplicate shallow/deep equality evaluation outside the Fiber loop, and forces every enterprise engineering team to repeatedly implement custom snapshot logic to solve a standard primitive constraint.

The issue names no repository files, tests, or entry points. Start by reviewing the proposed useEffect signature and ChangePayload design, then determine whether the work belongs in react.dev or the React reconciler. A usable starting point would require an agreed design plus identified implementation and test locations.