feat(watch): accept watch callback return cleanup function

[Mini-ghost]

In the current version, we can clear the callback side effects using watch as follows:

watch(id, async (newId, oldId, onCleanup) => {
  const { response, cancel } = doAsyncWork(newId)
  // `cancel` will be called if `id` changes, cancelling
  // the previous request if it hasn't completed yet
  onCleanup(cancel)
  data.value = await response
})

After version 3.5.0-beta.3, we can use onWatcherCleanup to clear side effects:

watch(id, async (newId, oldId) => {
  const { response, cancel } = doAsyncWork(newId)
  // `cancel` will be called if `id` changes, cancelling
  // the previous request if it hasn't completed yet
  onWatcherCleanup(cancel)
  data.value = await response
})

This pull request proposes discussing the possibility of introducing a method to support returning a function as one way of cleanup.

watch(id, (newId, oldId) => {
  const { response, cancel } = doAsyncWork(newId)
  response.then(result => data.value = result)
  // `cancel` will be called if `id` changes, cancelling
  // the previous request if it hasn't completed yet
  return cancel
})

The inspiration for this approach comes from React’s useEffect:

useEffect(() => {
  const connection = createConnection(serverUrl, roomId);
  connection.connect();
  return () => {
    connection.disconnect();
  };
}, [serverUrl, roomId]);

I believe this could be particularly friendly for developers transitioning from React to Vue, hence my initiative to introduce it here.

However, this might introduce some migration costs, such as when using arrow functions:

watch(value, (newValue) => array.push(newValue))

Here, the callback returns a number, which clearly isn't a cleanup function. Therefore, in implementation, it would only collect as a cleanup function if the return is a function. From my personal experience, it is uncommon to return a function in this context, so the impact should be minimal.

I would be most grateful for any feedback on this approach. If there are any concerns or alternative suggestions, please do not hesitate to share them. I am eager to make any necessary adjustments to accommodate community insights.

[github-actions]

Size Report

Bundles

File	Size	Gzip	Brotli
runtime-dom.global.prod.js	101 kB (+99 B)	38 kB (+41 B)	34.1 kB
vue.global.prod.js	159 kB (+99 B)	57.9 kB (+42 B)	51.4 kB (-7 B)

Usages

Name	Size	Gzip	Brotli
createApp (CAPI only)	48.8 kB	18.8 kB	17.2 kB
createApp	55.5 kB (+99 B)	21.3 kB (+38 B)	19.5 kB (+81 B)
createSSRApp	59.5 kB (+99 B)	23 kB (+33 B)	20.9 kB (-13 B)
defineCustomElement	60.3 kB (+99 B)	22.9 kB (+40 B)	20.9 kB (+33 B)
overall	69.2 kB (+99 B)	26.4 kB (+43 B)	24 kB (+39 B)

[pkg-pr-new]

Open in Stackblitz

@vue/compiler-dom

pnpm add https://pkg.pr.new/@vue/compiler-dom@11664

@vue/compiler-core

pnpm add https://pkg.pr.new/@vue/compiler-core@11664

@vue/compiler-ssr

pnpm add https://pkg.pr.new/@vue/compiler-ssr@11664

@vue/compiler-sfc

pnpm add https://pkg.pr.new/@vue/compiler-sfc@11664

@vue/reactivity

pnpm add https://pkg.pr.new/@vue/reactivity@11664

@vue/runtime-dom

pnpm add https://pkg.pr.new/@vue/runtime-dom@11664

@vue/runtime-core

pnpm add https://pkg.pr.new/@vue/runtime-core@11664

@vue/server-renderer

pnpm add https://pkg.pr.new/@vue/server-renderer@11664

@vue/shared

pnpm add https://pkg.pr.new/@vue/shared@11664

vue

pnpm add https://pkg.pr.new/vue@11664

@vue/compat

pnpm add https://pkg.pr.new/@vue/compat@11664

commit: 65e6a10

[yyx990803]

The problem with this is the behavior is inconsistent between async and non-async functions (This can be enforced via types, i.e. there should be a type error if the callback is an async function and returns a function).

We also need to think about the consistency between effect (watch(() => {})) and watcher with callback.

[Mini-ghost]

To ensure the return value behaves consistently with onCleanup, may I suggest that when the return value is Promise<() => any>, we also consider collecting the returned function as cleanup?

The implementation might look like this:

const cleanup = call
  ? call(cb!, WatchErrorCodes.WATCH_CALLBACK, args)
  : // @ts-expect-error
  cb!(...args)

if (isFunction(cleanup)) {
  boundCleanup(cleanup)
} else if (isPromise(cleanup)) {
  cleanup.then(result => {
    if (isFunction(result)) boundCleanup(result)
  })
}

This approach would make its effect consistent with onCleanup when used after await.