Add untrack()

docs/api/reactivity-utility.md

@@ -50,3 +50,35 @@ Runs a callback anytime a function scope is re-ran.
         return label
     end)
     ```
+
+## untrack()
+
+Gets the value of a source without reactively tracking it.
+
+- **Type**
+
+    ```lua
+    function untrack<T>(source: () -> T): T
+    ```
+
+- **Details**
+
+    Updates made to a source passed to `untrack()` will not cause updates to
+    anything depending on that source.
+
+- **Example**
+
+    ```lua
+    local a = source(0)
+    local b = source(0)
+
+    local sum = derive(function()
+        return a() + untrack(b)
+    end)
+
+    print(sum()) -- 0
+    b(1)
+    print(sum()) -- 0
+    a(1)
+    print(sum()) -- 2
+    ```

src/graph.luau

@@ -159,4 +159,5 @@ return table.freeze {
     capture = capture,
     capture_and_link = capture_and_link,
     create = create :: (<T>(value: T) -> (Node<T>, () -> T)) & (<T>() -> (Node<T>, () -> T)),
+    refs = refs
 }

src/init.luau

@@ -9,6 +9,7 @@ local create = require(script.create)
 local source = require(script.source)
 local watch = require(script.watch)
 local cleanup, clean_garbage = require(script.cleanup)()
+local untrack = require(script.untrack)
 local derive = require(script.derive)
 local indexes, values = require(script.maps)()
 local spring, update_springs = require(script.spring)()
@@ -23,11 +24,14 @@ local vide = {
     create = create,
     source = source,
     watch = watch,
-    cleanup = cleanup,
     derive = derive,
     indexes = indexes,
     values = values,
 
+    -- util
+    cleanup = cleanup,
+    untrack = untrack,
+
     -- animations
     spring = spring,
 

src/untrack.luau

@@ -0,0 +1,16 @@
+if not game then script = require "test/relative-string" end
+
+local graph = require(script.Parent.graph)
+type Node<T> = graph.Node<T>
+local refs = graph.refs
+
+local function untrack<T>(source: () -> T): T
+    local initial = #refs
+    local value = source()
+    for i = initial, #refs do
+        refs[i] = nil
+    end
+    return value
+end
+
+return untrack

test/tests.luau

@@ -1260,6 +1260,58 @@ TEST("spring()", function()
     end
 end)
 
+TEST("untrack()", function()
+    local source = vide.source
+    local watch = vide.watch
+    local untrack = vide.untrack
+
+    do CASE "does not register dependency"
+        local a = source(0)
+        local b = source(0)
+
+        local count = -1
+
+        watch(function()
+            count += 1
+            untrack(a)
+            b()
+        end)
+
+        b(1)
+        CHECK(count == 1)
+
+        a(1)
+        CHECK(count == 1)
+
+        CHECK(a() == untrack(a))
+    end
+
+    do CASE "derived state"
+        local a = source(0)
+        local b = source(0)
+        local c = source(0)
+
+        local d = function()
+            return a() + b()
+        end
+
+        local count = -1
+
+        watch(function()
+            count += 1
+            untrack(d)
+            c()
+        end)
+
+        c(1)
+        CHECK(count == 1)
+
+        a(1)
+        b(1)
+        CHECK(count == 1)
+    end
+end)
+
 TEST("events", function()
     local create = vide.create
 

todo.md

@@ -8,7 +8,7 @@
   - [x] onCleanup > `cleanup()`
   - [x] Index > `indexes()`
   - [x] For > `values()`
-  - [ ] untrack
+  - [x] untrack
   - [ ] batch
   - [ ] async/resource/loading/suspense
   - [ ] stores