[RFC] Control watch observation depth

[Alfred-Skyblue]

Start Date: 2023-11-08
Target Major Version: 3.x
Implementation PR: vuejs/core#9572

Summary

Support passing watch deep option as a number type, allowing control over the depth of the watch. This helps prevent unnecessary monitoring, especially when dealing with large arrays or objects.

Basic example

• Object

const state = reactive({
  a: {
    b: {
      c: {
        d: {
          e: 1
        }
      }
    }
  }
})

watch(
  state,
  () => {
    console.log('state changed')
  },
  { deep: 2, flush: 'sync' }
)

state.a.b = { c: { d: { e: 2 } } } // state changed

state.a.b.c = { d: { e: 3 } } // no console

state.a.b = { c: { d: { e: 4 } } } // state changed

• Array

const array = ref([])
watch(
  array,
  () => {
    console.log('array changed')
  },
  { deep: 1 }
)

array.value[0] = { foo: 'foo' } // array changed
array.value[0].foo = 'bar' // watch will not be triggered

• watching reactive with deep: false

const state = reactive({
      foo: {
        a: 2,
      },
      bar: 'bar',
    })

    watch(
      state,
      () => {
        console.log('state changed')
      },
      { deep: false },
    )

    state.foo.a++ // watch will not be triggered

    state.bar = 'bar2' // state changed

Result playground

Motivation

When using the watch function to observe arrays or objects, enabling the deep option is necessary for monitoring deeper levels of the object. However, this approach can lead to performance issues since it requires recursive access to all properties of the object. In such cases, the depth option can be employed to control the monitoring depth, thereby avoiding unnecessary observations.

Unresolved questions

Welcome to discussion

[skirtles-code]

This is a feature idea I've pondered previously.

I think the core idea of supporting depth is a good one. It'd be particularly useful for watching changes to an array without watching objects inside the array.

Initially, I also thought that having deep: 1, etc. would be a good way to implement it. But on reflection I think it might be better to have a separate depth: 1 setting.

For example:

watch(..., {
  depth: 1
})

The above would be equivalent to:

watch(..., {
  deep: true,
  depth: 1
})

If the user explicitly passes deep: false, that would take priority over the depth:

watch(..., {
  deep: false,
  depth: 1     // The depth will be ignored as deep is false
})

I'm unclear whether depth: 0 should be allowed and what it should mean. Initially, I thought that it would be equivalent to deep: false, but there's some subtlety around equality checking. A watcher with deep: true doesn't perform equality checking on the old and new values. It's not immediately clear to me whether depth: 0 should be consistent with deep: false and perform the equality check, or consistent with other depths and skip the equality check. I can see arguments for either approach.

There are a few reasons why I think a separate setting might be better:

1. It'd be a bit jarring from an English perspective to have deep: 1.
2. The existing implementation uses a truthy/falsey check for deep. While TS users do get forced to use an explicit boolean, JS users don't. There's potential to introduce subtle bugs into codebases when they upgrade, if they are (perhaps inadventently) already passing a number to deep.
3. If we just use deep for this, I think it'd be too easy for someone to accidentally pass a number for deep when they wanted to pass true. There'd be no hint of a problem from the types and the code would appear to work, up to a certain depth, and then would mysteriously stop working beyond that depth. Having a separate setting makes it more difficult to make a mistake.

For points 2 and 3 above, I'm not imagining somebody passing a literal number like deep: 2, that'd be obvious. I'm imagining something like deep: foo, where it might not be so obvious that foo is a number.

[Alfred-Skyblue]

I agree with you. In previous versions, the user may pass deep as 1, but it will be considered true. I initially considered adding a property depth, but this will undoubtedly increase the logical complexity of watch options.

[hubdidub]

Maybe calling the additional option maxDepth instead of depth could help a little, because it makes it clear that it's not determining whether it's a deep watcher or not, it just sets a limit. Which would also mean it has no effect unless deep: true is also set.

[hubdidub]

Alternatively, how about this:

watch(..., {
  deep: { limit: 1 } // go up to 1 level deep
})
watch(..., {
  deep: { limit: 0 } // NOT the same as deep: false, but would catch array mutations when watching an array-ref
})
watch(..., {
  deep: true // limitless, like before
})

Not sure if I like it because it's a nested option, but I thought I'd bring it up because I think that would also solve the complexity issue and isn't likely to break existing code.

[Alfred-Skyblue]

Thank you for the discussion. A new option, depth, has been added to control the depth of monitored objects.

[Alfred-Skyblue]

Temporarily decided to support passing deep as a number type to control the depth of the listening object. In response to the incorrect usage of deep as a number type in previous versions, a warning message has been added in version 3.4.

vuejs/core#9572 (comment)

[Alfred-Skyblue]

After discussion, a new option, depth, has been introduced to control the depth of monitored objects.

[hubdidub]

I'm looking forward to this.
Controlling the observation depth for objects is really nice!

But my use case no.1 for this would be to watch for array mutations. Because we have to use deep watchers for that, and it always felt wrong to watch the entire thing when the elements are very complex objects.
Will we be able to watch the array itself but not the elements with this change?

I imagine it would be watch-level 0, like so:

const array = ref([]);
watch(array, callback, { deep: true, depth: 0 });

Will this trigger the callback when I do the following operations?

array.value.push({ foo: 'test' });
array.value[0] = { foo: 'test2' };
array.value.splice(0, 1);

And this:

array.value[0].foo = 'test3';

will not trigger it, unless I set it to depth: 1 or higher, right?

[Alfred-Skyblue]

When depth = 0, it is ineffective, equivalent to recursing through all properties. If you need to listen to arrays, use the following:

const array = ref([])
watch(
  array,
  () => {
    console.log('array changed')
  },
  { deep: true, depth: 1 }
)

array.value[0] = { foo: 'foo' } // array changed
array.value[0].foo = 'bar' // watch will not be triggered

or

const array = ref([])
watch(
  array,
  () => {
    console.log('array changed')
  },
  { deep: true, depth: 2 }
)

array.value[0] = { foo: 'foo' } // array changed
array.value[0].foo = 'bar' // array changed