Refactor

src/graph.luau

@@ -3,7 +3,7 @@ if not game then script = require "test/relative-string" end
 local throw = require(script.Parent.throw)
 local flags = require(script.Parent.flags)
 
-export type StartNode<T> = {
+export type SourceNode<T> = {
     cache: T,
     [number]: Node<T>
 }
@@ -16,12 +16,11 @@ export type Node<T> =  {
     owned: { Node<T> } | false,
     owner: Node<T> | false,
 
-    parents: { StartNode<T> },
+    parents: { SourceNode<T> },
     [number]: Node<T> -- children
 }
 
--- reactive scope stack
-local scopes = { n = 0 } :: { [number]: Node<any>, n: number }
+local scopes = { n = 0 } :: { [number]: Node<any>, n: number } -- scopes stack
 
 local function ycall<T, U>(fn: (T) -> U, arg: T): (boolean, string|U)
     local thread = coroutine.create(pcall)
@@ -40,46 +39,37 @@ local function get_scope(): Node<unknown>?
     return scopes[scopes.n]
 end
 
-local function assert_owning_scope(): Node<unknown>
+local function assert_stable_scope(): Node<unknown>
     local scope = get_scope()
 
     if not scope then
         local caller_name = debug.info(2, "n")
-        return throw(`cannot use {caller_name}() in a non-reactive scope`)
+        return throw(`cannot use {caller_name}() outside a stable or reactive scope`)
     elseif scope.effect then
-        throw("cannot create new reactive scope in a tracking reactive scope")
+        throw("cannot create a new reactive scope inside another reactive scope")
     end
 
     return scope
 end
 
-local function add_child<T>(parent: StartNode<any>, child: Node<any>)
+local function push_child<T>(parent: SourceNode<any>, child: Node<any>)
     table.insert(parent, child)
     table.insert(child.parents, parent)
 end
 
-local function set_owner(node: Node<any>, owner: Node<any>)
-    node.owner = owner
-    if owner.owned then
-        table.insert(owner.owned, node)
-    else
-        owner.owned = { node }
-    end
-end
-
-local function open_scope<T>(node: Node<T>)
+local function push_scope<T>(node: Node<T>)
     local n = scopes.n + 1
     scopes.n = n
     scopes[n] = node
 end
 
-local function close_scope()
+local function pop_scope()
     local n = scopes.n
     scopes.n = n - 1
     scopes[n] = nil
 end
 
-local function add_cleanup<T>(node: Node<T>, cleanup: () -> ())
+local function push_cleanup<T>(node: Node<T>, cleanup: () -> ())
     if node.cleanups then
         table.insert(node.cleanups, cleanup)
     else
@@ -87,34 +77,35 @@ local function add_cleanup<T>(node: Node<T>, cleanup: () -> ())
     end
 end
 
-local function run_cleanups<T>(node: Node<T>)
+local function flush_cleanups<T>(node: Node<T>)
     if node.cleanups then
         for _, fn in next, node.cleanups do
             local ok, err: string? = pcall(fn)
             if not ok then throw(`cleanup error: {err}`) end
         end
+
         table.clear(node.cleanups)
     end
 end
 
 local function find_and_swap_pop<T>(t: { T }, v: T)
-    local idx = table.find(t, v) :: number
+    local i = table.find(t, v) :: number
     local n = #t
-    t[idx] = t[n]
+    t[i] = t[n]
     t[n] = nil
 end
 
 local function unparent<T>(node: Node<T>)
     local parents = node.parents
 
-    for i, parent in next, parents do
+    for i, parent in parents do
         find_and_swap_pop(parent, node)
         parents[i] = nil
     end
 end
 
 local function destroy<T>(node: Node<T>)
-    run_cleanups(node)
+    flush_cleanups(node)
     unparent(node)
     
     if node.owner then
@@ -141,28 +132,28 @@ local function evaluate_node<T>(node: Node<T>)
     local cur_value = node.cache
 
     if flags.strict then
-        run_cleanups(node)
+        flush_cleanups(node)
         destroy_owned(node)
 
-        open_scope(node)
+        push_scope(node)
 
         local ok, new_value = ycall(node.effect :: (T) -> T, cur_value)
         
-        close_scope()
+        pop_scope()
         
         if not ok then throw(new_value :: string) end
 
         node.cache = new_value :: T
     end
 
-    run_cleanups(node)
+    flush_cleanups(node)
     destroy_owned(node)
 
-    open_scope(node)
+    push_scope(node)
 
     local ok, new_value = pcall(node.effect :: (T) -> T, node.cache)
 
-    close_scope()
+    pop_scope()
 
     if not ok then
         table.clear(update_queue)
@@ -175,7 +166,7 @@ local function evaluate_node<T>(node: Node<T>)
     return cur_value ~= new_value
 end
 
-local function queue_children<T>(node: StartNode<T>)
+local function queue_children_for_update<T>(node: SourceNode<T>)
     local i = update_queue.n
     while node[1] do
         i += 1
@@ -198,7 +189,7 @@ local function flush_update_queue()
         --assert(node.effect)
 
         if node.owner and evaluate_node(node) then
-            queue_children(node)
+            queue_children_for_update(node)
         end
 
         update_queue[i] = false :: any
@@ -210,9 +201,9 @@ local function flush_update_queue()
     _flushing = false
 end
 
-local function update<T>(root: StartNode<T>)
+local function update_descendants<T>(root: SourceNode<T>)
     local n0 = update_queue.n
-    queue_children(root)
+    queue_children_for_update(root)
 
     if flags.batch then return end
 
@@ -223,7 +214,7 @@ local function update<T>(root: StartNode<T>)
 
         -- check if node is still owned in case destroyed after queued
         if node.owner and evaluate_node(node) then
-            queue_children(node)
+            queue_children_for_update(node)
         end
 
         update_queue[i] = false :: any -- false instead of nil to avoid sparse
@@ -233,27 +224,37 @@ local function update<T>(root: StartNode<T>)
     update_queue.n = n0
 end
 
-local function track<T>(node: StartNode<T>)
+local function push_child_to_scope<T>(node: SourceNode<T>)
     local scope = get_scope()
     if scope and scope.effect then -- do not track nodes with no effect
-        add_child(node, scope)
+        push_child(node, scope)
     end
 end
 
-local function create_node<T>(value: T, effect: false | (T) -> T): Node<T>
-    return {
+local function create_node<T>(owner: false | Node<any>, effect: false | (T) -> T, value: T): Node<T>
+    local node: Node<T> = {
         cache = value,
         effect = effect,
         cleanups = false,
 
-        owner = false,
+        owner = owner,
         owned = false,
 
         parents = {},
     }
+
+    if owner then
+        if owner.owned then
+            table.insert(owner.owned, node)
+        else
+            owner.owned = { node }
+        end
+    end
+
+    return node
 end
 
-local function create_start_node<T>(value: T): StartNode<T>
+local function create_source_node<T>(value: T): SourceNode<T>
     return { cache = value }
 end
 
@@ -262,20 +263,19 @@ local function get_children<T>(node: Node<T>): { Node<unknown> }
 end
 
 return table.freeze {
-    open_scope = open_scope,
-    close_scope = close_scope,
+    push_scope = push_scope,
+    pop_scope = pop_scope,
     evaluate_node = evaluate_node,
     get_scope = get_scope,
-    assert_owning_scope = assert_owning_scope,
-    add_cleanup = add_cleanup,
-    set_owner = set_owner,
+    assert_stable_scope = assert_stable_scope,
+    push_cleanup = push_cleanup,
     destroy = destroy,
-    run_cleanups = run_cleanups,
-    track = track,
-    update = update,
-    add_child = add_child,
+    flush_cleanups = flush_cleanups,
+    push_child_to_scope = push_child_to_scope,
+    update_descendants = update_descendants,
+    push_child = push_child,
     create_node = create_node,
-    create_start_node = create_start_node,
+    create_source_node = create_source_node,
     get_children = get_children,
     flush_update_queue = flush_update_queue,
     scopes = scopes