feat(reactivity): add 'equals' option to watch for custom equality checks

packages/reactivity/src/watch.ts

@@ -50,6 +50,7 @@ export interface WatchOptions<Immediate = boolean> extends DebuggerOptions {
   immediate?: Immediate
   deep?: boolean | number
   once?: boolean
+  equals?: (a: any, b: any) => boolean
   scheduler?: WatchScheduler
   onWarn?: (msg: string, ...args: any[]) => void
   /**
@@ -240,14 +241,31 @@ export function watch(
     if (cb) {
       // watch(source, cb)
       const newValue = effect.run()
-      if (
-        deep ||
-        forceTrigger ||
-        (isMultiSource
-          ? (newValue as any[]).some((v, i) => hasChanged(v, oldValue[i]))
-          : hasChanged(newValue, oldValue))
-      ) {
-        // cleanup before running cb again
+      const areEqual = (a: any, b: any): boolean => {
+        if (options.equals) {
+          try {
+            return !!options.equals(a, b)
+          } catch (e) {
+            if (call) {
+              call(() => {
+                throw e
+              }, WatchErrorCodes.WATCH_CALLBACK)
+            }
+            return false
+          }
+        }
+        return !hasChanged(a, b)
+      }
+      const isChanged = isMultiSource
+        ? (newValue as any[]).some((v, i) => !areEqual(v, oldValue[i]))
+        : !areEqual(newValue, oldValue)
+      // If equals is provided, it fully controls the trigger decision,
+      // bypassing deep and forceTrigger logic.
+      const shouldTrigger = options.equals
+        ? isChanged
+        : deep || forceTrigger || isChanged
+
+      if (shouldTrigger) {
         if (cleanup) {
           cleanup()
         }

packages/runtime-core/__tests__/apiWatch.spec.ts

@@ -2061,4 +2061,71 @@ describe('api: watch', () => {
     createApp(App).mount(root)
     expect(onCleanup).toBeCalledTimes(0)
   })
+  it('watch: should trigger cleanup even if manually skipped in callback (current behavior)', async () => {
+    const state = ref({ id: 1 })
+    let cleanupCount = 0
+    let effectCount = 0
+
+    watch(
+      state,
+      (newVal, oldVal, onCleanup) => {
+        // Even if we skip the logic here, the scheduler has already fired the cleanup
+        if (JSON.stringify(newVal) === JSON.stringify(oldVal)) {
+          return
+        }
+
+        effectCount++
+        onCleanup(() => {
+          cleanupCount++
+        })
+      },
+      { deep: true },
+    )
+
+    state.value = { id: 2 }
+    await nextTick()
+    expect(effectCount).toBe(1)
+    expect(cleanupCount).toBe(0)
+
+    // Trigger with semantically identical value
+    state.value = { id: 2 }
+    await nextTick()
+
+    // Assert current behavior: cleanup fires even if we return early in the callback
+    expect(cleanupCount).toBe(1)
+    expect(effectCount).toBe(1)
+  })
+
+  it('watch: should respect custom equality check via "equals" option', async () => {
+    const state = ref({ id: 1 })
+    let cleanupCount = 0
+    let callbackCount = 0
+
+    watch(
+      state,
+      (newVal, oldVal, onCleanup) => {
+        callbackCount++
+        onCleanup(() => {
+          cleanupCount++
+        })
+      },
+      {
+        deep: true,
+        equals: (a, b) => JSON.stringify(a) === JSON.stringify(b),
+      },
+    )
+
+    state.value = { id: 2 }
+    await nextTick()
+    expect(callbackCount).toBe(1)
+    expect(cleanupCount).toBe(0)
+
+    // Trigger with semantically identical value
+    state.value = { id: 2 }
+    await nextTick()
+
+    // With the fix, these should remain unchanged
+    expect(callbackCount).toBe(1)
+    expect(cleanupCount).toBe(0)
+  })
 })

packages/runtime-core/src/apiWatch.ts

@@ -50,6 +50,12 @@ export interface WatchOptions<Immediate = boolean> extends WatchEffectOptions {
   immediate?: Immediate
   deep?: boolean | number
   once?: boolean
+  /**
+   * Custom equality function to determine if the value has changed.
+   * If provided, it takes precedence over the default equality check,
+   * `deep` watches, and `forceTrigger`.
+   */
+  equals?: (a: any, b: any) => boolean
 }
 
 // Simple effect.