feat: destroy a store with $dispose

Close #557

packages/pinia/__tests__/store.spec.ts

@@ -303,4 +303,27 @@ describe('Store', () => {
     expect(One.text()).toBe('1')
     expect(Two.text()).toBe('1')
   })
+
+  it('can be disposed', () => {
+    const pinia = createPinia()
+    const useStore = defineStore({
+      id: 'main',
+      state: () => ({ n: 0 }),
+    })
+
+    const store = useStore(pinia)
+    const spy = jest.fn()
+
+    store.$subscribe(spy)
+    pinia.state.value.main.n++
+    expect(spy).toHaveBeenCalledTimes(1)
+
+    expect(useStore()).toBe(store)
+    store.$dispose()
+    pinia.state.value.main.n++
+
+    expect(spy).toHaveBeenCalledTimes(1)
+
+    expect(useStore()).not.toBe(store)
+  })
 })

packages/pinia/src/devtools/plugin.ts

@@ -414,11 +414,20 @@ function addStoreToDevtools(app: App, store: StoreGeneric) {
         api.sendInspectorState(INSPECTOR_ID)
       })
 
+      const { $dispose } = store
+      store.$dispose = () => {
+        $dispose()
+        api.notifyComponentUpdate()
+        api.sendInspectorTree(INSPECTOR_ID)
+        api.sendInspectorState(INSPECTOR_ID)
+        toastMessage(`Disposed "${store.$id}" store 🗑`)
+      }
+
       // trigger an update so it can display new registered stores
       api.notifyComponentUpdate()
       api.sendInspectorTree(INSPECTOR_ID)
       api.sendInspectorState(INSPECTOR_ID)
-      toastMessage(`"${store.$id}" store installed`)
+      toastMessage(`"${store.$id}" store installed 🆕`)
     }
   )
 }

packages/pinia/src/store.ts

@@ -269,6 +269,13 @@ function createSetupStore<
       }
     : noop
 
+  function $dispose() {
+    scope.stop()
+    subscriptions = []
+    actionSubscriptions = []
+    pinia._s.delete($id)
+  }
+
   /**
    * Wraps an action to handle subscriptions.
    *
@@ -448,6 +455,7 @@ function createSetupStore<
 
       return removeSubscription
     },
+    $dispose,
   } as StoreWithState<Id, S, G, A>
 
   const store: Store<Id, S, G, A> = reactive(

packages/pinia/src/types.ts

@@ -414,6 +414,14 @@ export interface StoreWithState<
     callback: StoreOnActionListener<Id, S, G, A>,
     detached?: boolean
   ): () => void
+
+  /**
+   * Stops the associated effect scope of the store and remove it from the store
+   * registry. Plugins can override this method to cleanup any added effects.
+   * e.g. devtools plugin remove its listeners and stops displaying it from
+   * devtools.
+   */
+  $dispose(): void
 }
 
 /**