[Feature Request]: distinguish "what" and "when" dependencies in useEffect

[jsamr]

Feature

A new overloading for useEffect (Typescript syntax):

interface useEffect {
  /**
   * @param what - what this side effect does?
   * @param whatDeps - which variables modify “what” the side effect does?
   * These dependencies must match all live variables explicitly referenced
   * in the body of the “what” callback.
   * @param whenDeps - which variables modify “when” the side effect takes place?
   * When and only when at least one of those dependencies change, the “what”
   * callback should be executed.
   */
  (what: (...args: any[]) => any, whatDeps: any[], whenDeps: any[]): void;
  /**
   * @param what - what this side effect does?
   * @param deps - an array of values that the effect depends on.
   *
   */
  (what: (...args: any[]) => any, deps?: any[]): void;
}

Motivations

In the current implementation, the second argument of useEffect, “deps”, is described as such:

The array of values that the effect depends on.

This definition does not account for an important nuance between two kind of dependencies:

• what dependencies, those which require the effect callback to be recomputed updated;
• when dependencies, those which require the effect callback to be rerun executed.

The community seems to be in need of a solution, see https://stackoverflow.com/q/55724642/2779871.

Use case

I want to scroll to top of a component when the content changes (first dependency), but this effect also depends on a variable padding top (second dependency).

With the current implementation of useEffect, this is what I would do:

function MyComponent(props) {
  const { paddingTop, content } = props;
  const ref = React.useRef();
  React.useEffect(() => {
    // scroll to paddingTop when content changes?
    ref.current.scrollTo(0, paddingTop);
  }, [paddingTop, content]);
 return <div ref={ref}>...</div>
}

There is an undesired behavior: the hook is executed on paddingTop changes. Moreover, content is not, semantically, a dependency of the callback, but rather a dependency of when this side effect should take place. So I could use a ref, store the previous value of paddingTop, and compare the two. But that is cumbersome.

What I would like to do, is express the when this side-effect should take place dependencies declaratively:

function MyComponent(props) {
  const { paddingTop, content } = props;
  const ref = React.useRef();
  React.useEffect(() => {
    // scroll to paddingTop when content changes.
    ref.current.scrollTo(0, paddingTop);
  }, [paddingTop], [content]);
 return <div ref={ref}>...</div>
}

Detailed behavior

My understanding is that this proposal would not be a breaking change and is 100% retrocompatible with current implementation.

One argument

useEffect(what);

The behavior is identical to current implementation. The effect is executed after each render cycle.

Two arguments

useEffect(what, deps);

The behavior is identical to current implementation. The second argument conflates whatDeps and whenDeps.

Empty second argument

useEffect(what, []);

The behavior is identical to current implementation. The callback is executed only once.

Empty third argument

useEffect(what, whatDeps, []);

The callback is executed only once, regardless of the changes in whatDeps.

Three arguments

useEffect(what, whatDeps, whenDeps);

The callback is executed when and only when at least one variable in whenDeps array changes, regardless of the changes in whatDeps.

[vkurchatkin]

Am I missing something, or whatDeps doesn't actually affect anything?

[jsamr]

@vkurchatkin I should do a better job at describing the proposal. whatDeps changes will trigger a recomputation of the callback with up-to-date variables, but the callback won't be re-executed before whenDeps changes. So yes, whatDeps does something!

[bvaughn]

• what dependencies, those which require the effect callback to be recomputed;
• when dependencies, those which require the effect callback to be rerun.

What does it mean to "recompute" a callback?

[bvaughn]

An effect callback is just a JavaScript function that closes over variables in scope.

If I'm understanding you correctly, what you're suggesting seems fragile to me. It would make it possible for the function to be invoked with stale (closed over) values. I guess that wouldn't be a concern since– if the values had changed again, we'd update again before calling. But I feel like the mental model you propose is much harder to think about than the single deps array.

[bvaughn]

A change to built-in hooks APIs is really the sort of proposal that should go through our RFC process:
https://github.com/reactjs/rfcs#react-rfcs

[bvaughn]

You could build this hook in user space for what it's worth. At least if I'm understanding you correctly, something like?

function useWhateverYourEffect(callback, whatDeps, whenDeps) {
  const prevWhenValuesRef = useRef([]);

  useEffect(() => {
    // This callback will be called whenever any of the "what" or "when" deps change

    const prevWhenDeps = prevWhenValuesRef.current;
    prevWhenValuesRef.current = whenDeps;

    let changed = false;

    for (let i = 0; i < whenDeps.length; i++) {
      if (prevWhenDeps[i] != whenDeps[i]) {
        // The user callback will be called only when one of the "when" deps change
        callback();
        return;
      }
    }
  }, [...whatDeps, ...whenDeps]);
}

[vkurchatkin]

whatDeps changes will trigger a recomputation of the callback with up-to-date variables, but the callback won't be re-executed before whenDeps changes

What's the point of recomputing the callback if you are not going to run it?

[bvaughn]

I think the main thing being asked for here (if I'm understanding) has nothing to do with "recomputing" really. (I think that's a confusing term to use to refer to a function.)

I think the real request is to only run a callback when certain, specific dependencies change.

[vkurchatkin]

I think the real request is to only run a callback when certain, specific dependencies change.

But that's what useEffect already does

[bvaughn]

Yes and no. It invokes a callback any time any dependency changes. I think @jsamr is saying that he doesn't want the callback to be re-run unless a subset of the dependencies change.

[bvaughn]

I find the proposed API a little confusing. (I think it's easier to reason about a single dependencies array.) But I have heard the question (how to implement this) come up a few times in the past.

[vkurchatkin]

I think @jsamr is saying that he doesn't want the callback to be re-run unless a subset of the dependencies change.

Then you only need to list this subset as dependencies.

[bvaughn]

No, that's not true. You have to specify everything you reference inside of the effect as a dependency– or your callback may close over stale values.

[jsamr]

@bvaughn There must be a better wording for this. For example:

const callback = useCallback(() => {
  //
}, [prop1])

Each time prop1 changes, the callback is "recomputed" (its reference gets updated, obviously I need to change the description).

A change to built-in hooks APIs is really the sort of proposal that should go through our RFC process:

Yes, I'm well aware! But I wanted some help with the phrasing which obviously was required, and basic feedback on the feature itself.

I think the real request is to only run a callback when certain, specific dependencies change.

Absolutely. Any dependency that is not referenced in the body of the callback is, per my definitions, a "whenDep".