feat!: make Effect.run fire-and-forget

Change Effect.run to return unit (fire-and-forget) and
introduce Effect.runWithDisposer for cases where manual
disposal is needed.

- Effect.run now returns unit
- Effect.runWithDisposer returns disposer
- Update all tests to use runWithDisposer
- Update documentation and examples

BREAKING CHANGE: Effect.run now returns unit instead of
disposer. If you need to manually dispose an effect, use
Effect.runWithDisposer instead.

Migration guide:

Before:
```rescript
let disposer = Effect.run(() => {
  Console.log(Signal.get(count))
  None
})
disposer.dispose()
```

After:
```rescript
let disposer = Effect.runWithDisposer(() => {
  Console.log(Signal.get(count))
  None
})
disposer.dispose()
```

If you don't need the disposer, no changes are required:
```rescript
Effect.run(() => {
  Console.log(Signal.get(count))
  None
})
```

Author: brnrdog

README.md

@@ -44,16 +44,13 @@ let count = Signal.make(0)
 let doubled = Computed.make(() => Signal.get(count) * 2)
 
 // Run a side effect (executes when dependencies change)
-let disposer = Effect.run(() => {
+Effect.run(() => {
   Console.log(`Count: ${Int.toString(Signal.get(count))}, Doubled: ${Int.toString(Signal.get(doubled))}`)
   None
 })
 
 // Update the signal
 Signal.set(count, 5) // Logs: "Count: 5, Doubled: 10"
-
-// Clean up when done
-disposer.dispose()
 ```
 
 ## Usage
@@ -167,13 +164,29 @@ Effects run side effects in response to signal changes. They execute immediately
 ```rescript
 let count = Signal.make(0)
 
-let disposer = Effect.run(() => {
+// Fire-and-forget effect
+Effect.run(() => {
   Console.log(`Count is: ${Int.toString(Signal.get(count))}`)
   None
 })
 
 Signal.set(count, 1) // Logs: "Count is: 1"
-disposer.dispose()
+```
+
+#### Effect with Disposer
+
+Use `Effect.runWithDisposer` when you need to manually stop the effect:
+
+```rescript
+let count = Signal.make(0)
+
+let disposer = Effect.runWithDisposer(() => {
+  Console.log(`Count is: ${Int.toString(Signal.get(count))}`)
+  None
+})
+
+Signal.set(count, 1) // Logs: "Count is: 1"
+disposer.dispose() // Stop tracking
 ```
 
 #### Effect with Cleanup
@@ -183,7 +196,7 @@ Effects can return a cleanup function that runs before the next execution and on
 ```rescript
 let url = Signal.make("/api/data")
 
-let disposer = Effect.run(() => {
+let disposer = Effect.runWithDisposer(() => {
   let currentUrl = Signal.get(url)
 
   // Start async operation
@@ -203,7 +216,7 @@ disposer.dispose() // Final cleanup
 #### Named Effects for Debugging
 
 ```rescript
-let disposer = Effect.run(
+Effect.run(
   () => {
     Console.log(Signal.get(count))
     None
@@ -221,7 +234,7 @@ let showDetails = Signal.make(false)
 let userData = Signal.make({name: "John"})
 let adminData = Signal.make({role: "admin"})
 
-let disposer = Effect.run(() => {
+Effect.run(() => {
   if Signal.get(showDetails) {
     Console.log(Signal.get(userData)) // Tracked
   } else {
@@ -243,7 +256,7 @@ let firstName = Signal.make("John")
 let lastName = Signal.make("Doe")
 let runCount = ref(0)
 
-let disposer = Effect.run(() => {
+Effect.run(() => {
   Console.log(Signal.get(firstName) ++ " " ++ Signal.get(lastName))
   runCount := runCount.contents + 1
   None
@@ -275,7 +288,7 @@ Read signal values without creating dependencies. Useful when you need a value b
 let count = Signal.make(0)
 let threshold = Signal.make(10)
 
-let disposer = Effect.run(() => {
+Effect.run(() => {
   let current = Signal.get(count)
   let limit = Signal.untrack(() => Signal.get(threshold))
 
@@ -393,18 +406,26 @@ Run side effects in response to signal changes.
 ```rescript
 type disposer = {dispose: unit => unit}
 
-// Run an effect
+// Run a fire-and-forget effect
 let run: (
   unit => option<unit => unit>,
   ~name: option<string>=?
+) => unit
+
+// Run an effect with manual disposal
+let runWithDisposer: (
+  unit => option<unit => unit>,
+  ~name: option<string>=?
 ) => disposer
 ```
 
 **Parameters:**
 - `fn`: Effect function to execute. Can return `None` or `Some(cleanupFn)`
 - `~name`: Optional name for debugging
 
-**Returns:** A disposer object with a `dispose()` method
+**`Effect.run`**: Fire-and-forget effect. Returns `unit`.
+
+**`Effect.runWithDisposer`**: Returns a disposer object with a `dispose()` method for manual cleanup.
 
 **Note:** Effects run immediately and re-run whenever tracked dependencies change. Cleanup functions run before re-execution and on disposal.
 
@@ -428,7 +449,7 @@ let isValid = Computed.make(() => {
 })
 
 // Effect for auto-save
-let disposer = Effect.run(() => {
+Effect.run(() => {
   if Signal.get(isValid) {
     saveToLocalStorage(Signal.get(formData))
   }
@@ -443,7 +464,7 @@ let userId = Signal.make(1)
 let userData = Signal.make(None)
 let isLoading = Signal.make(false)
 
-let disposer = Effect.run(() => {
+Effect.run(() => {
   let id = Signal.get(userId)
 
   Signal.set(isLoading, true)
@@ -503,7 +524,7 @@ let movePoint = (dx, dy, dz) => {
 }
 
 // Effect only runs once per movePoint call
-let disposer = Effect.run(() => {
+Effect.run(() => {
   Console.log(
     `Position: (${Int.toString(Signal.get(x))}, ${Int.toString(Signal.get(y))}, ${Int.toString(Signal.get(z))})`
   )
@@ -520,7 +541,7 @@ let config = Signal.make({theme: "dark", locale: "en"})
 // Frequently changing data
 let data = Signal.make([])
 
-let disposer = Effect.run(() => {
+Effect.run(() => {
   let items = Signal.get(data)
 
   // Read config without tracking—we'll manually refresh when config changes

docs-website/src/pages/Pages__ApiEffect.res

@@ -20,20 +20,44 @@ let make = () => {
     </div>
     <Typography
       text={static(
-        "Creates and immediately runs an effect. The effect re-runs whenever any signal or computed it reads changes.",
+        "Creates and immediately runs a fire-and-forget effect. The effect re-runs whenever any signal or computed it reads changes.",
       )}
     />
     <CodeBlock
       language="rescript"
       code={`let count = Signal.make(0)
 
-let disposer = Effect.run(() => {
+Effect.run(() => {
   Console.log(\`Count is: \${Signal.get(count)->Int.toString}\`)
+  None
 })
 
 // Logs: "Count is: 0"
 Signal.set(count, 1)
 // Logs: "Count is: 1"`}
+    />
+    <div class="heading-anchor" id="effect-run-with-disposer">
+      <Typography text={static("Effect.runWithDisposer(fn)")} variant={H3} />
+      <a class="anchor-link" href="#effect-run-with-disposer"> {"#"->Component.text} </a>
+    </div>
+    <Typography
+      text={static(
+        "Creates an effect and returns a disposer for manual cleanup. Use this when you need to stop the effect later.",
+      )}
+    />
+    <CodeBlock
+      language="rescript"
+      code={`let count = Signal.make(0)
+
+let disposer = Effect.runWithDisposer(() => {
+  Console.log(\`Count is: \${Signal.get(count)->Int.toString}\`)
+  None
+})
+
+Signal.set(count, 1)
+// Logs: "Count is: 1"
+
+disposer.dispose() // Stop the effect`}
     />
     <div class="heading-anchor" id="effect-run-named">
       <Typography text={static("Effect.run(~name, fn)")} variant={H3} />
@@ -44,6 +68,7 @@ Signal.set(count, 1)
       language="rescript"
       code={`Effect.run(~name="logger", () => {
   Console.log(Signal.get(count))
+  None
 })`}
     />
     <Separator />
@@ -85,12 +110,12 @@ Signal.set(count, 1)
     </div>
     <Typography
       text={static(
-        "Effect.run returns a disposer object. Call dispose() to stop the effect and run any cleanup function.",
+        "Effect.runWithDisposer returns a disposer object. Call dispose() to stop the effect and run any cleanup function.",
       )}
     />
     <CodeBlock
       language="rescript"
-      code={`let disposer = Effect.run(() => {
+      code={`let disposer = Effect.runWithDisposer(() => {
   Console.log(Signal.get(count))
   Some(() => Console.log("Cleanup!"))
 })

docs-website/src/pages/Pages__GettingStarted.res

@@ -103,6 +103,7 @@ Computed.get(doubled) // 10`}
       code={`let count = Signal.make(0)
 Effect.run(() => {
   Console.log(\`Count changed to: \${Signal.get(count)->Int.toString}\`)
+  None
 })`}
     />
     <EditOnGitHub pageName="Pages__GettingStarted" />

src/signals/Signals__Effects.res

@@ -4,7 +4,7 @@ module Scheduler = Signals__Scheduler
 
 type disposer = {dispose: unit => unit}
 
-let run = (fn: unit => option<unit => unit>, ~name: option<string>=?): disposer => {
+let runWithDisposer = (fn: unit => option<unit => unit>, ~name: option<string>=?): disposer => {
   let observerId = Id.make()
   let cleanup: ref<option<unit => unit>> = ref(None)
 
@@ -59,3 +59,7 @@ let run = (fn: unit => option<unit => unit>, ~name: option<string>=?): disposer
 
   {dispose: dispose}
 }
+
+let run = (fn: unit => option<unit => unit>, ~name: option<string>=?): unit => {
+  let _ = runWithDisposer(fn, ~name?)
+}

tests/ComputedTests.res

@@ -133,7 +133,7 @@ let tests = suite(
       let show = Signal.make(true)
       let result = ref(0)
 
-      let disposer = Effect.run(() => {
+      let disposer = Effect.runWithDisposer(() => {
         if Signal.get(show) {
           result := Signal.get(doubled)
         }

tests/EffectTests.res

@@ -7,7 +7,7 @@ let tests = suite(
   [
     test("effect runs initially", () => {
       let runCount = ref(0)
-      let disposer = Effect.run(() => {
+      let disposer = Effect.runWithDisposer(() => {
         runCount := runCount.contents + 1
         None
       })
@@ -17,7 +17,7 @@ let tests = suite(
     test("effect runs when dependency changes", () => {
       let count = Signal.make(0)
       let runCount = ref(0)
-      let disposer = Effect.run(() => {
+      let disposer = Effect.runWithDisposer(() => {
         let _ = Signal.get(count)
         runCount := runCount.contents + 1
         None
@@ -30,7 +30,7 @@ let tests = suite(
       let a = Signal.make(1)
       let b = Signal.make(2)
       let sum = ref(0)
-      let disposer = Effect.run(() => {
+      let disposer = Effect.runWithDisposer(() => {
         sum := Signal.get(a) + Signal.get(b)
         None
       })
@@ -43,7 +43,7 @@ let tests = suite(
     test("effect cleanup runs on re-execution", () => {
       let count = Signal.make(0)
       let cleanupCount = ref(0)
-      let disposer = Effect.run(() => {
+      let disposer = Effect.runWithDisposer(() => {
         let _ = Signal.get(count)
         Some(() => cleanupCount := cleanupCount.contents + 1)
       })
@@ -54,7 +54,7 @@ let tests = suite(
     }),
     test("effect cleanup runs on disposal", () => {
       let cleaned = ref(false)
-      let disposer = Effect.run(() => Some(() => cleaned := true))
+      let disposer = Effect.runWithDisposer(() => Some(() => cleaned := true))
       disposer.dispose()
       assertTrue(cleaned.contents, ~message="Cleanup should run on disposal")
     }),
@@ -63,7 +63,7 @@ let tests = suite(
       let a = Signal.make(1)
       let b = Signal.make(2)
       let result = ref(0)
-      let disposer = Effect.run(() => {
+      let disposer = Effect.runWithDisposer(() => {
         result := if Signal.get(toggle) {
           Signal.get(a)
         } else {
@@ -81,12 +81,12 @@ let tests = suite(
       let outer = Signal.make(0)
       let outerRuns = ref(0)
       let innerRuns = ref(0)
-      let disposer1 = Effect.run(() => {
+      let disposer1 = Effect.runWithDisposer(() => {
         let _ = Signal.get(outer)
         outerRuns := outerRuns.contents + 1
         None
       })
-      let disposer2 = Effect.run(() => {
+      let disposer2 = Effect.runWithDisposer(() => {
         let _ = Signal.get(outer)
         innerRuns := innerRuns.contents + 1
         None
@@ -103,7 +103,7 @@ let tests = suite(
       let base = Signal.make(2)
       let doubled = Computed.make(() => Signal.get(base) * 2)
       let result = ref(0)
-      let disposer = Effect.run(() => {
+      let disposer = Effect.runWithDisposer(() => {
         result := Signal.get(doubled)
         None
       })
@@ -116,7 +116,7 @@ let tests = suite(
     test("effect disposal stops tracking", () => {
       let count = Signal.make(0)
       let runCount = ref(0)
-      let disposer = Effect.run(() => {
+      let disposer = Effect.runWithDisposer(() => {
         let _ = Signal.get(count)
         runCount := runCount.contents + 1
         None
@@ -134,7 +134,7 @@ let tests = suite(
     test("effect with array mutation tracking", () => {
       let items = Signal.make([1, 2, 3])
       let length = ref(0)
-      let disposer = Effect.run(() => {
+      let disposer = Effect.runWithDisposer(() => {
         length := Array.length(Signal.get(items))
         None
       })
@@ -148,7 +148,7 @@ let tests = suite(
       let tracked = Signal.make(1)
       let untracked = Signal.make(10)
       let runCount = ref(0)
-      let disposer = Effect.run(() => {
+      let disposer = Effect.runWithDisposer(() => {
         let _ = Signal.get(tracked)
         let _ = Signal.peek(untracked)
         runCount := runCount.contents + 1
@@ -165,7 +165,7 @@ let tests = suite(
       result
     }),
     test("multiple disposals are safe", () => {
-      let disposer = Effect.run(() => None)
+      let disposer = Effect.runWithDisposer(() => None)
       disposer.dispose()
       disposer.dispose()
       Pass