fix: prevent duplicate watcher when same callback subscribed twice (#3144)

Close #3143

Author: JSap0914

packages/pinia/__tests__/subscriptions.spec.ts

@@ -2,8 +2,11 @@ import { beforeEach, describe, it, expect, vi } from 'vitest'
 import { createPinia, defineStore, MutationType, setActivePinia } from '../src'
 import { mount } from '@vue/test-utils'
 import { nextTick, ref } from 'vue'
+import { mockWarn } from './vitest-mock-warn'
 
 describe('Subscriptions', () => {
+  mockWarn()
+
   const useOptionsStore = defineStore('main', {
     state: () => ({
       user: 'Eduardo',
@@ -375,5 +378,30 @@ describe('Subscriptions', () => {
       expect(preSpy).toHaveBeenCalledTimes(1)
       expect(postSpy).toHaveBeenCalledTimes(1)
     })
+
+    it('ignores a callback subscribed twice and warns', () => {
+      const spy = vi.fn()
+      const store = useStore()
+      const unsub1 = store.$subscribe(spy, { flush: 'sync' })
+      const unsub2 = store.$subscribe(spy, { flush: 'sync' })
+
+      expect('passed to "$subscribe()"').toHaveBeenWarnedTimes(1)
+
+      store.$state.user = 'once'
+      expect(spy).toHaveBeenCalledTimes(1)
+
+      store.$patch({ user: 'twice' })
+      expect(spy).toHaveBeenCalledTimes(2)
+
+      // the second call returned a noop, so it does not unsubscribe anything
+      unsub2()
+      store.$state.user = 'after-unsub2'
+      expect(spy).toHaveBeenCalledTimes(3)
+
+      // unsubscribing the original removes the single subscription
+      unsub1()
+      store.$state.user = 'after-unsub1'
+      expect(spy).toHaveBeenCalledTimes(3)
+    })
   })
 })

packages/pinia/src/diagnostics.ts

@@ -41,5 +41,11 @@ export const diagnostics = /*#__PURE__*/ defineDiagnostics({
       fix: 'If it should be reactive state, wrap it with ref(), reactive(), or shallowRef(). If it is an intentional non-reactive property, wrap it with markRaw() so storeToRefs() skips it explicitly.',
       docs: 'https://pinia.vuejs.org/core-concepts/plugins.html#Adding-new-external-properties',
     },
+    PINIA_R1007: {
+      why: (p: { id: string }) =>
+        `The same callback was passed to "$subscribe()" of store "${p.id}" more than once. Subscriptions are deduplicated, so the duplicate is ignored.`,
+      fix: 'Subscribe each callback only once. If you need to resubscribe, call the returned function to remove the previous subscription first, or create a new function.',
+      docs: 'https://pinia.vuejs.org/core-concepts/state.html#Subscribing-to-the-state',
+    },
   },
 })

packages/pinia/src/store.ts

@@ -436,6 +436,15 @@ function createSetupStore<
     $patch,
     $reset,
     $subscribe(callback, options = {}) {
+      // avoid setting up multiple watchers for the same callback
+      // https://github.com/vuejs/pinia/issues/3143
+      if (subscriptions.has(callback)) {
+        if (__DEV__) {
+          diagnostics.PINIA_R1007({ id: $id })
+        }
+        return noop
+      }
+
       const removeSubscription = addSubscription(
         subscriptions,
         callback,