src/bind.luau

@@ -5,11 +5,11 @@ local throw = require(script.Parent.throw)
 local flags = require(script.Parent.flags)
 local graph = require(script.Parent.graph)
 type Node<T> = graph.Node<T>
-local create = graph.create
-local init_scope = graph.init_scope
+local create_node = graph.create_node
+local open_scope = graph.open_scope
 local close_scope = graph.close_scope
 local add_child = graph.add_child
-local capture = graph.capture
+local capture_parents = graph.capture_parents
 
 --[[
 
@@ -67,21 +67,14 @@ function bind(instance: Instance, property: string, setter: (Instance) -> ())
         end
     end
 
-    local binding = create(instance)
-
-    init_scope(binding)
-
-    -- run setter to capture any nodes being depended on
-    local nodes = (capture(setter :: () -> unknown, instance))
-
-    close_scope()
-
+    local binding = create_node(instance)
     binding.effect = setter
 
-    -- register the setter as a side-effect of each node
-    for _, node in next, nodes do
-        add_child(node, binding)
-    end
+    open_scope(binding.scope)
+
+    capture_parents(binding, setter :: () -> any, instance)
+
+    close_scope()
 end
 
 local function bind_property(instance: Instance, property: string, fn: () -> unknown)

src/derive.luau

@@ -1,34 +1,29 @@
 if not game then script = require "test/relative-string" end
 
 local graph = require(script.Parent.graph)
-local create = graph.create
-local capture = graph.capture
+local create_node = graph.create_node
+local capture_parents = graph.capture_parents
 local add_child = graph.add_child
-local set_effect = graph.set_effect
 local update = graph.update
 local track = graph.track
-local init_scope = graph.init_scope
+local get_scope = graph.get_scope
+local open_scope = graph.open_scope
 local close_scope = graph.close_scope
 
 local function derive<T>(fn: () -> T): () -> T
-    local node = create((false :: any) :: T)
+    assert(get_scope())
 
-    init_scope(node)
-
-    local nodes, value = capture(fn)
-
-    close_scope()
-
-    for _, parent in next, nodes do
-        add_child(parent, node)
-    end
-
-    set_effect(node, function()
+    local node = create_node((false :: any) :: T)
+    node.effect = function()
         node.cache = fn()
         update(node)
-    end)
+    end
 
-    node.cache = value
+    open_scope(node.scope)
+
+    node.cache = capture_parents(node, fn)
+
+    close_scope()
 
     return function()
         track(node)

src/graph.luau

@@ -2,14 +2,18 @@ if not game then script = require "test/relative-string" end
 
 local throw = require(script.Parent.throw)
 local flags = require(script.Parent.flags)
-local on_gc = require(script.Parent.on_gc)()
+
+export type Scope = {
+    parent: Scope | false,
+    cleanups: { () -> () } | false,
+    [number]: Scope -- children
+}
 
 export type Node<T> = {
+    scope: Scope,
     cache: T,
-    effect:  (unknown) -> (),
-    parents: { Node<T> } | false,
-    children: { Node<T> } | false, -- weak values
-    cleanups: { () -> () } | false
+    effect:  (T) -> (),
+    [number]: Node<T> -- children
 }
 
 -- flag used to detect when node reference capturing is active
@@ -17,7 +21,7 @@ local reff = false
 -- array of all nodes referenced since above flag was set
 local refs = {} :: { Node<unknown> }
 
-local scopes = { n = 0 } :: { [number]: Node<unknown>, n: number }
+local scopes = { n = 0 } :: { [number]: Scope, n: number }
 
 local WEAK_VALUES = { __mode = "v" }
 local EVALUATION_ERR = "error while evaluating source:\n\n"
@@ -50,14 +54,14 @@ local check_for_yield: <T...>(fn: (T...) -> unknown, T...) -> () do
     end
 end
 
-local function get_scope(): Node<unknown>
+local function get_scope(): Scope
     return scopes[scopes.n]
 end
 
-local function open_scope(node: Node<unknown>)
+local function open_scope(scope: Scope)
     local n = scopes.n + 1
     scopes.n = n
-    scopes[n] = node
+    scopes[n] = scope
 end
 
 local function close_scope()
@@ -66,20 +70,20 @@ local function close_scope()
     scopes[n] = nil
 end
 
-local function add_cleanup(node: Node<unknown>, cleanup: () -> ())
-    if node.cleanups then
-        table.insert(node.cleanups, cleanup)
+local function add_cleanup(scope: Scope, cleanup: () -> ())
+    if scope.cleanups then
+        table.insert(scope.cleanups, cleanup)
     else
-        node.cleanups = { cleanup }
+        scope.cleanups = { cleanup }
     end
 end
 
-local function run_cleanups(node: { cleanups: { () -> () } | false})
-    if node.cleanups then
-        for _, fn in next, node.cleanups do
+local function run_cleanups(scope: Scope)
+    if scope.cleanups then
+        for _, fn in next, scope.cleanups do
             fn()
         end
-        table.clear(node.cleanups)
+        table.clear(scope.cleanups)
     end
 end
 
@@ -94,87 +98,40 @@ The weak key is passed as an argument to its side-effect callback.
 
 ]]
 
-local function set_effect<T>(node: Node<unknown>, fn: () -> ())
-    node.effect = fn
-end
-
-local function run_effect(node: Node<unknown>)
+local function run_effect<T>(node: Node<T>)
     node.effect(node.cache)
 end
 
--- links two nodes as parent-child
-local function add_child(parent: Node<unknown>, child: Node<unknown>)
-    if parent.children then
-        table.insert(parent.children, child)    
-    else
-        parent.children = { child }
-        setmetatable(parent.children :: any, {})
+local function add_child(parent: Node<any>, child: Node<any>)
+    table.insert(parent, child)
+end
+
+local function add_children(parent: Node<any>, children: { Node<any> })
+    for _, child in next, children do
+        table.insert(parent, child)
     end
 end
 
-local function add_children(parent: Node<unknown>, children: { Node<unknown> })
-    if parent.children then
-        for _, child in next, children do
-            table.insert(parent.children, child)
-        end
-    else
-        parent.children = table.clone(children)
+local function destroy(scope: Scope)
+    run_cleanups(scope)
+    for _, child in ipairs(scope) do
+        destroy(child)
     end
 end
 
-local function add_parent(child: Node<unknown>, parent: Node<unknown>)
-    child.parents = { parent }
-end
-
-local function rec(node: { effect: any, children: { Node<unknown> }, cleanups: { () -> () }})
-    run_cleanups(node)
-    node.effect = function() assert(false) end
-    if node.children then
-        for _, child in node.children do
-            rec(child)
-        end
-    end
-end
-
-local function destroy(node: Node<unknown>)
-    if node.parents then
-        for _, parent in node.parents do
-            parent.children[table.find(parent.children, node)] = nil -- todo: can iter invalidation occur here?
-        end
-    end
-    rec(node)
-end
-
-local function init_scope(node: Node<unknown>)
-    local parent = scopes[scopes.n]
-    if parent then
-        add_child(parent, node)
-        add_parent(node, parent)
-    end
-    open_scope(node)
-end
-
 -- runs node effects, recalculates descendants and runs descendant effects
-local function update(node: Node<unknown>)
-    if node.children then
-        for _, child in node.children do
-            open_scope(child)
-            run_cleanups(child)
-            run_effect(child)
-            update(child)
-            close_scope()
-        end
+local function update<T>(node: Node<T>)
+    for _, child in ipairs(node) do
+        local scope = child.scope
+        assert(scope)
+        open_scope(scope :: Scope)
+        run_cleanups(scope :: Scope)
+        run_effect(child)
+        update(child)
+        close_scope()
     end
 end
 
--- links two nodes as parent-child with a function to compute a new value for child
-local function link<T>(parent: Node<unknown>, child: Node<T>, derive: () -> T)
-    child.effect = function()
-        child.cache = derive()
-    end
-    add_child(parent, child)
-end
-
 -- detect what nodes were referenced in the given callback and returns them in an array
 local function capture<T, U>(fn: (U?) -> T, arg: U?): ({ Node<unknown> }, T)
     if reff then throw("recursive capture detected") end
@@ -197,53 +154,51 @@ local function capture<T, U>(fn: (U?) -> T, arg: U?): ({ Node<unknown> }, T)
     return refs, result :: T
 end
 
--- captures and links any detected nodes
-local function capture_and_link<T>(child: Node<T>, derive: () -> T): T
-    local nodes, value = capture(derive, nil)
+local function capture_parents<T, U>(child: Node<T>, fn: (U?) -> T, arg: U?): T
+    local refs, result = capture(fn, arg)
 
-    child.effect = function()
-        child.cache = derive()
-    end
-    for _, parent: Node<unknown> in next, nodes do
+    for _, parent in next, refs do
         add_child(parent, child)
     end
 
-    return value :: T
+    return result
 end
 
-local function track(node: Node<unknown>)
-    if reff then table.insert(refs, node) end
+local function track<T>(node: Node<T>)
+    if reff then table.insert(refs, node :: Node<any>) end
 end
 
-local function create<T>(value: T): Node<T>
+local function create_scope(): Scope
+    return {
+        parent = get_scope() or false,
+        cleanups = false
+    }
+end
+
+local function create_node<T>(value: T): Node<T>
     local node = {
+        scope = create_scope(),
         cache = value,
         effect = function() end,
-        parents = false :: false,
-        children = false :: false,
-        cleanups = false :: false
     }
 
     return node
 end
 
 return table.freeze {
-    init_scope = init_scope,
     open_scope = open_scope,
     close_scope = close_scope,
     get_scope = get_scope,
     add_cleanup = add_cleanup,
     destroy = destroy,
     run_cleanups = run_cleanups,
-    set_effect = set_effect,
     track = track,
     update = update,
-    link = link,
-    add_parent = add_parent,
     add_child = add_child,
     add_children = add_children,
     capture = capture,
-    capture_and_link = capture_and_link,
-    create = create :: (<T>(value: T) -> (Node<T>, () -> T)) & (<T>() -> (Node<T>, () -> T)),
+    capture_parents = capture_parents,
+    create_node = create_node,
+    create_scope = create_scope,
     refs = refs
 }

src/init.luau

@@ -5,6 +5,7 @@
 
 if not game then script = require "test/relative-string" end
 
+local root = require(script.root)
 local create = require(script.create)
 local apply = require(script.apply)
 local source = require(script.source)
@@ -48,6 +49,7 @@ end)
 
 local vide = {
     -- core
+    root = root,
     create = create,
     source = source,
     watch = watch,

src/maps.luau

@@ -5,18 +5,19 @@ if not game then script = require "test/relative-string" end
 local throw = require(script.Parent.throw)
 local flags = require(script.Parent.flags)
 local graph = require(script.Parent.graph)
+type Scope = graph.Scope
 type Node<T> = graph.Node<T>
-local create = graph.create
-local set = graph.set
+local create_node = graph.create_node
+local create_scope = graph.create_scope
+local track = graph.track
+local update = graph.update
 local capture = graph.capture
-local run_cleanups = graph.run_cleanups
-local set_child = graph.set_child
-local open_new_scope = graph.open_new_scope
+local capture_parents = graph.capture_parents
+local add_child = graph.add_child
 local get_scope = graph.get_scope
 local open_scope = graph.open_scope
 local close_scope = graph.close_scope
-local link = graph.link
-local destroy_tree = graph.destroy_tree
+local destroy = graph.destroy
 
 type Map<K, V> = { [K]: V }
 
@@ -31,15 +32,19 @@ end
 
 -- todo: optimize output array
 local function indexes<K, VI, VO>(input: () -> Map<K, VI>, transform: (() -> VI, K) -> VO): () -> { VO }
+    assert(get_scope())
+
+    local root = create_scope()
+
     local input_cache = {} :: Map<K, VI>
     local output_cache = {} :: Map<K, VO>
     local input_nodes = {} :: Map<K, Node<VI>>
     local remove_queue = {} :: { K }
     local output_array = {} :: { VO }
 
-    local scopes = {} :: Map<K, Node<unknown>>
+    local scopes = {} :: Map<K, Scope>
 
-    local function recompute(data)
+    local function update_children(data)
         -- queue removed values
         for i in next, input_cache do
             if data[i] == nil then
@@ -49,8 +54,7 @@ local function indexes<K, VI, VO>(input: () -> Map<K, VI>, transform: (() -> VI,
 
         -- remove queued values
         for _, i in next, remove_queue do
-            destroy_tree(scopes[i])
-
+            destroy(scopes[i])
 
             input_cache[i] = nil
             output_cache[i] = nil
@@ -60,29 +64,38 @@ local function indexes<K, VI, VO>(input: () -> Map<K, VI>, transform: (() -> VI,
 
         table.clear(remove_queue)
 
+        open_scope(root)
+
         -- process new or changed values
         for i, v in next, data do
             local cv = input_cache[i]
 
             if cv ~= v then
                 if cv == nil then
-                    local scope = create(false)
+                    local scope = create_scope()
+                    scopes[i] = scope
 
-                    open_new_scope(scope)
+                    open_scope(scope)
 
-                    local node, get_value = create(v)
+                    local node = create_node(v)
                     input_nodes[i] = node
-                    output_cache[i] = transform(get_value, i)
                     input_cache[i] = v
+                    output_cache[i] = transform(function()
+                        track(node)
+                        return node.cache
+                    end, i)
 
                     close_scope()
                 else
-                    set(input_nodes[i], v)
+                    input_nodes[i].cache = v
+                    update(input_nodes[i])
                     input_cache[i] = v
                 end
             end
         end
 
+        close_scope()
+
         -- output elements
         table.clear(output_array)
         for _, v in next, output_cache do
@@ -93,34 +106,27 @@ local function indexes<K, VI, VO>(input: () -> Map<K, VI>, transform: (() -> VI,
         return output_array
     end
 
-    local output, read_output_value = create(nil :: any)
-
-    local scope = create(false)
-    
-    local function derive()
-        local _ = scope
-        return recompute(input())
+    local output = create_node(false :: any)
+    output.effect = function()
+        update_children(input())
     end
 
-    local nodes, value = capture(input)
+    local value = capture_parents(output, input)
 
-    for _, node in next, nodes do
-        link(node, output, derive)
+    output.cache = update_children(value)
+
+    return function()
+        track(output)
+        return output.cache
     end
-
-    output.cache = recompute(value)
-
-
-
-    local scope_parent = get_scope()
-
-    set_child(scope_parent, scope)
-
-    return read_output_value
 end
 
 -- todo: optimize output array
 local function values<K, VI, VO>(input: () -> Map<K, VI>, transform: (VI, () -> K) -> VO): () -> { VO }
+    assert(get_scope())
+
+    local root = create_scope()
+    
     local cur_input_cache_up = {} :: Map<VI, K>
     local new_input_cache_up = {} :: Map<VI, K>
 
@@ -128,9 +134,9 @@ local function values<K, VI, VO>(input: () -> Map<K, VI>, transform: (VI, () ->
     local input_nodes = {} :: Map<VI, Node<K>>
     local output_array = {} :: { VO }
 
-    local cleanups = {} :: Map<VI, { () -> () }>
+    local scopes = {} :: Map<VI, Scope>
 
-    local function recompute(data: Map<K, VI>)
+    local function update_children(data: Map<K, VI>)
         local cur_input_cache, new_input_cache = cur_input_cache_up, new_input_cache_up
 
         if flags.strict then
@@ -142,6 +148,8 @@ local function values<K, VI, VO>(input: () -> Map<K, VI>, transform: (VI, () ->
                 cache[v] = true
             end
         end
+
+        open_scope(root)
     
         -- process data
         for i, v in next, data do
@@ -150,30 +158,37 @@ local function values<K, VI, VO>(input: () -> Map<K, VI>, transform: (VI, () ->
             local cv = cur_input_cache[v]
             
             if cv == nil then
-                manual_cleanup_mode(transform)
+                local scope = create_scope()
+                scopes[v] = scope
 
-                local node, get_value = create(i)
+                open_scope(scope)
+
+                local node = create_node(i)
                 input_nodes[v] = node
-                output_cache[v] = transform(v, get_value)
+                output_cache[v] = transform(v, function()
+                    track(node)
+                    return node.cache
+                end)
 
-                cleanups[v] = manual_cleanup_mode(nil)
+                close_scope()
             else
                 if cv ~= i then
-                    set(input_nodes[v], i)
+                    input_nodes[v].cache = i
+                    update(input_nodes[v])
                 end
                 cur_input_cache[v] = nil
             end
         end
 
+        close_scope()
+
         -- remove old values
         for v in next, cur_input_cache do
-            for _, callback in next, cleanups[v] do
-                callback() -- todo: pcall
-            end
+            destroy(scopes[v])
 
             output_cache[v] = nil
             input_nodes[v] = nil
-            cleanups[v] = nil
+            scopes[v] = nil
         end
 
         -- update buffer cache
@@ -187,33 +202,24 @@ local function values<K, VI, VO>(input: () -> Map<K, VI>, transform: (VI, () ->
             table.insert(output_array, v)
         end
 
+        check_primitives(output_array)
+
         return output_array
     end
 
-    local output, read_output_value = create(nil :: any)
-
-    local function derive()
-        return recompute(input())
+    local output = create_node(false :: any)
+    output.effect = function()
+        update_children(input())
     end
 
-    local nodes, value = capture(input)
+    local value = capture_parents(output, input)
 
-    for _, node in next, nodes do
-        link(node, output, derive)
+    output.cache = update_children(value)
+
+    return function()
+        track(output)
+        return output.cache
     end
-    check_primitives(output_array)
-
-    output.cache = recompute(value)
-
-    cleanup_ref(tostring(output), output, function()
-        for _, callbacks in next, cleanups do
-            for _, callback in next, callbacks do
-                callback() -- todo: pcall
-            end
-        end
-    end)
-
-    return read_output_value
 end
 
 return function() return indexes, values end

src/root.luau

@@ -5,33 +5,25 @@ local throw = require(script.Parent.throw)
 local on_gc = require(script.Parent.on_gc)()
 local graph = require(script.Parent.graph)
 type Node<T> = graph.Node<T>
-local create = graph.create
-local init_scope = graph.init_scope
+local create_scope = graph.create_scope
+local open_scope = graph.open_scope
 local close_scope = graph.close_scope
 local get_scope = graph.get_scope
 local destroy = graph.destroy
 
-local refs = {} :: { [Node<unknown>]: unknown }
-setmetatable(refs :: any, { __mode = "v" })
-
-local function root<T>(fn: () -> T): T
+local function root<T>(fn: () -> T): (T, () -> ())
     assert(not get_scope())
+    local scope = create_scope()
 
-    local node = create(nil) -- todo: lifetime with return vaue from fn
-
-    init_scope(node)
+    open_scope(scope)
 
     local v = fn()
 
     close_scope()
 
-    refs[node] = v
-
-    on_gc(v, function()
-        destroy(node)
-    end)
-
-    return v
+    return v, function()
+        destroy(scope)
+    end
 end
 
 return root

src/source.luau

@@ -2,14 +2,17 @@ if not game then script = require "test/relative-string" end
 
 local graph = require(script.Parent.graph)
 type Node<T> = graph.Node<T>
-local create = graph.create
+local create_node = graph.create_node
+local get_scope = graph.get_scope
 local track = graph.track
 local update = graph.update
 
 export type Source<T> = (() -> T) & ((T) -> T)
 
 local function source<T>(initial_value: T): Source<T>
-    local node = create(initial_value)
+    assert(get_scope())
+
+    local node = create_node(initial_value)
 
     return function(...): T
         if select("#", ...) == 0 then -- no args were given

src/spring.luau

@@ -24,10 +24,11 @@ Unsupported datatypes:
 local throw = require(script.Parent.throw)
 local graph = require(script.Parent.graph)
 type Node<T> = graph.Node<T>
-local create = graph.create
-local set = graph.set
-local set_child = graph.set_child
+local create_node = graph.create_node
+local update = graph.update
 local capture = graph.capture
+local add_child = graph.add_child
+local track = graph.track
 
 local UPDATE_RATE = 120
 local TOLERANCE = 0.0001
@@ -146,7 +147,6 @@ setmetatable(springs, { __mode = "v" })
 
 local function spring<T>(source: () -> T, period: number?, damping_ratio: number?): () -> T
     local inputs, initial_value = capture(source)
-    local output, output_get = create(initial_value)
 
     local vtype = typeof(initial_value)
     
@@ -177,23 +177,25 @@ local function spring<T>(source: () -> T, period: number?, damping_ratio: number
         source_value = initial_value,
     }
 
-    -- reschedule spring for simulation on input update
-    local function input_updated()
+    local output = create_node(initial_value)
+
+
+    local updater = create_node(false)
+    updater.effect = function()
         local v = source()
         data.x1_123, data.x1_456 = type_to_vec6[typeof(v)](v)
         data.source_value = v
         springs[data] = output -- todo: investigate why insertion is not O(1) at ~20k springs
     end
 
-    -- unused field, use so output prevents gc of inputs
-    output.effect = input_updated
-
-    -- register above function as side-effect for all inputs
     for _, input in next, inputs do
-        set_child(input, output)
+        add_child(input, updater)
     end
 
-    return output_get, data
+    return function()
+        track(output)
+        return output.cache
+    end
 end
 
 local function step_springs(dt: number)
@@ -251,10 +253,11 @@ local function update_spring_sources()
         if (v_123 + v_456 + dx_123 + dx_456).Magnitude < TOLERANCE then
             -- close enough to target, unshedule spring and set value to target
             table.insert(remove_queue, data)
-            set(output, data.source_value)
+            output.cache = data.source_value
         else
-            set(output, vec6_to_type[typeof(data.source_value)](x0_123, x0_456))
+            output.cache = vec6_to_type[typeof(data.source_value)](x0_123, x0_456)
         end
+        update(output)
     end
 
     for _, data in next, remove_queue do

src/watch.luau

@@ -1,36 +1,23 @@
 if not game then script = require "test/relative-string" end
 
 local graph = require(script.Parent.graph)
-local create = graph.create
-local add_parent = graph.add_parent
-local add_child = graph.add_child
-local capture = graph.capture
-local init_scope = graph.init_scope
+local create_node = graph.create_node
+local capture_parents = graph.capture_parents
+local get_scope = graph.get_scope
+local open_scope = graph.open_scope
 local close_scope = graph.close_scope
-local destroy = graph.destroy
 
-local function watch(effect: () -> ()): () -> ()
-    local node = create(false)
-
-    init_scope(node)
-
-    local nodes = capture(effect :: () -> nil)
-
-    close_scope()
+local function watch(effect: () -> ())
+    assert(get_scope())
 
+    local node = create_node(false)
     node.effect = effect
 
-    for _, parent in next, nodes do
-        add_parent(node, parent)
-        add_child(parent, node)
-    end
+    open_scope(node.scope)
 
+    capture_parents(node, effect :: () -> any)
 
-    local function unwatch()
-        destroy(node)
-    end
-
-    return unwatch
+    close_scope()
 end
 
 return watch