feat: Explicit Resource Management support in reactions (#4558)

Author: vkrol

.changeset/tiny-rice-walk.md

@@ -0,0 +1,5 @@
+---
+"mobx": minor
+---
+
+Add Explicit Resource Management support in reactions

docs/reactions.md

@@ -329,6 +329,54 @@ class OrderLine {
 
 </details>
 
+In environments that support [Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management),
+the disposer function includes a `[Symbol.dispose]` method that can be used to
+dispose of the reaction. This can be useful when disposing of several reactions
+simultaneously or when disposing of reactions alongside other Disposables.
+
+<details id="disposable-stack"><summary>**Example:** using DisposableStack<a href="#disposable-stack" class="tip-anchor"></a></summary>
+
+```javascript
+function createSomeDisposableResource() {}
+
+class Vat {
+    value = 1.2
+
+    constructor() {
+        makeAutoObservable(this)
+    }
+}
+
+const vat = new Vat()
+
+class OrderLine {
+    price = 10
+    amount = 1
+    disposableStack = new DisposableStack()
+    someDisposableResource
+
+    constructor() {
+        makeAutoObservable(this)
+
+        this.disposableStack.use(autorun(() => {
+            doSomethingWith(this.price * this.amount)
+        }))
+
+        this.disposableStack.use(autorun(() => {
+            doSomethingWith(this.price * this.amount * vat.value)
+        }))
+
+        this.someDisposableResource = this.disposableStack.use(createSomeDisposableResource())
+    }
+
+    [Symbol.dispose]() {
+        this.disposableStack[Symbol.dispose]();
+    }
+}
+```
+
+</details>
+
 ## Use reactions sparingly!
 
 As it was already said, you won't create reactions very often.

packages/mobx/__tests__/v5/base/reaction.js

@@ -3,6 +3,7 @@
  */
 const mobx = require("../../../src/mobx.ts")
 const reaction = mobx.reaction
+const $mobx = mobx.$mobx
 const utils = require("../../v5/utils/test-utils")
 
 test("basic", () => {
@@ -704,3 +705,27 @@ describe("reaction opts requiresObservable", () => {
         expect(messages.length).toBe(0)
     })
 })
+
+describe("explicit resource management", () => {
+    Symbol.dispose ??= Symbol("Symbol.dispose")
+
+    test("reaction has [Symbol.dispose] and calling it disposes of reaction", () => {
+        const a = mobx.observable.box(1)
+        const values = []
+
+        const disposeReaction = reaction(
+            () => a.get(),
+            newValue => {
+                values.push(newValue)
+            }
+        )
+
+        expect(disposeReaction[Symbol.dispose]).toBeInstanceOf(Function)
+
+        disposeReaction[Symbol.dispose]()
+        a.set(2)
+
+        expect(values).toEqual([])
+        expect(disposeReaction[$mobx].isDisposed).toBe(true)
+    })
+})

packages/mobx/src/core/reaction.ts

@@ -240,6 +240,10 @@ export class Reaction implements IDerivation, IReactionPublic {
         abortSignal?.addEventListener?.("abort", dispose)
         dispose[$mobx] = this
 
+        if ("dispose" in Symbol && typeof Symbol.dispose === "symbol") {
+            dispose[Symbol.dispose] = dispose
+        }
+
         return dispose
     }