@trioforge/crucible 0.1.0 → 0.2.0

package/out/internal/reactive/graph.luau

@@ -0,0 +1,626 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local YIELDED = TS.import(script, script.Parent.Parent, "runner").YIELDED
+local _context = TS.import(script, script.Parent, "context")
+local boundary = _context.boundary
+local inBody = _context.inBody
+local pop = _context.pop
+local push = _context.push
+local top = _context.top
+--* @internal 
+--* @internal How far an observer is from trusting what it last read. 
+--* @internal 
+--* @internal 
+--* @internal 
+--* @internal 
+--* @internal 
+--* @internal The graph's view of an effect. The flush owns the rest of it. 
+--* @internal 
+--* @internal 
+local ids = 0
+--* @internal Creation order, shared by every node and effect in the realm. 
+local function nextId()
+	ids += 1
+	return ids
+end
+--* @internal Flush rounds sort by it, so an owner's effect runs before the effects its runs created. 
+local function createdBefore(a, b)
+	return a.id < b.id
+end
+local epoch = 0
+--* @internal Moves on every value-changing write in the realm. 
+local function currentEpoch()
+	return epoch
+end
+local schedule = function() end
+--* @internal The flush registers how a marked effect is queued. 
+local function useScheduler(scheduler)
+	schedule = scheduler
+end
+--* @internal 
+local function originOf(callback)
+	local source, line = debug.info(callback, "sl")
+	return `{source}:{line}`
+end
+local thrown
+local function capture(err)
+	thrown = {
+		reason = tostring(err),
+		message = debug.traceback(tostring(err), 2),
+	}
+	return nil
+end
+--* @internal Throws when the running thread is inside a computed, where `what` is not allowed. 
+local function guardPure(what)
+	local _pure = top()
+	if _pure ~= nil then
+		_pure = _pure.pure
+	end
+	local pure = _pure
+	if pure ~= nil then
+		error(`{pure} must not {what}`, 0)
+	end
+end
+local function track(source)
+	local frame = top()
+	local _observer = frame
+	if _observer ~= nil then
+		_observer = _observer.observer
+	end
+	local observer = _observer
+	if observer == nil or observer == source then
+		return nil
+	end
+	local reads = frame.reads
+	local _source = source
+	if reads[_source] ~= nil then
+		return nil
+	end
+	local _source_1 = source
+	reads[_source_1] = true
+	local _deps = frame.deps
+	local _arg0 = {
+		source = source,
+		seen = source.version,
+	}
+	table.insert(_deps, _arg0)
+end
+--* @internal 
+local function observerFrame(kind, observer, lifetime)
+	return {
+		kind = kind,
+		observer = observer,
+		lifetime = lifetime,
+		pure = if kind == 1 then "computed" else nil,
+		deps = {},
+		reads = {},
+	}
+end
+--* @internal Calls `read` with no tracking. Ownership and purity stay those of the frame below. 
+local function readUntracked(read, pure)
+	local below = top()
+	local _object = {
+		kind = 2,
+	}
+	local _left = "lifetime"
+	local _result = below
+	if _result ~= nil then
+		_result = _result.lifetime
+	end
+	_object[_left] = _result
+	local _left_1 = "pure"
+	local _condition = pure
+	if _condition == nil then
+		local _result_1 = below
+		if _result_1 ~= nil then
+			_result_1 = _result_1.pure
+		end
+		_condition = _result_1
+	end
+	_object[_left_1] = _condition
+	local frame = _object
+	push(frame)
+	local ok, result = pcall(read)
+	pop(frame)
+	if not ok then
+		error(result, 0)
+	end
+	return result
+end
+--* @internal 
+local function createStateNode(value)
+	return {
+		kind = 0,
+		id = nextId(),
+		version = 0,
+		observers = {},
+		value = value,
+	}
+end
+--* @internal 
+local function readState(node)
+	track(node)
+	return node.value
+end
+--* @internal The one write path. Stores, bumps versions and marks; never runs user code or an effect. 
+local markObservers
+local function write(node, value)
+	guardPure("write state")
+	if rawequal(value, node.value) then
+		return nil
+	end
+	node.value = value
+	node.version += 1
+	epoch += 1
+	markObservers(node)
+end
+--* @internal A node and the value it will hold. 
+--[[
+	*
+	 * @internal
+	 * Rule 62's write phase for client apply: assignments, version and epoch bumps, and marks that only enqueue. No
+	 * purity guard, no admission and no user code, so nothing here can fail between two writes of one frame.
+	 
+]]
+local function commitPrepared(writes)
+	for _, _binding in writes do
+		local node = _binding[1]
+		local value = _binding[2]
+		if rawequal(value, node.value) then
+			continue
+		end
+		node.value = value
+		node.version += 1
+		epoch += 1
+		markObservers(node)
+	end
+end
+--* @internal 
+local function update(node, change)
+	write(node, readUntracked(function()
+		return change(node.value)
+	end, "update's callback"))
+end
+function markObservers(source)
+	local pending = {}
+	local levels = {}
+	for o in source.observers do
+		table.insert(pending, o)
+		table.insert(levels, 2)
+	end
+	while #pending > 0 do
+		-- ▼ Array.pop ▼
+		local _length = #pending
+		local _result = pending[_length]
+		pending[_length] = nil
+		-- ▲ Array.pop ▲
+		local o = _result
+		-- ▼ Array.pop ▼
+		local _length_1 = #levels
+		local _result_1 = levels[_length_1]
+		levels[_length_1] = nil
+		-- ▲ Array.pop ▲
+		local level = _result_1
+		if o.mark >= level then
+			continue
+		end
+		local wasClean = o.mark == 0
+		o.mark = level
+		if o.kind == 2 then
+			schedule(o)
+		elseif wasClean then
+			for p in o.observers do
+				table.insert(pending, p)
+				table.insert(levels, 1)
+			end
+		end
+	end
+end
+--* @internal 
+local function createComputedNode(read)
+	return {
+		kind = 1,
+		id = nextId(),
+		version = 0,
+		observers = {},
+		dependencies = {},
+		mark = 2,
+		read = read,
+		origin = originOf(read),
+		cache = {
+			kind = 0,
+		},
+		validatedAt = -1,
+		evaluating = false,
+	}
+end
+--* @internal 
+local validate
+local function readComputed(node)
+	validate(node)
+	track(node)
+	local cache = node.cache
+	if cache.kind == 2 then
+		error(cache.message, 0)
+	end
+	return if cache.kind == 1 then cache.value else nil
+end
+local function cycle(node)
+	local message = `computed at {node.origin} reads itself`
+	node.cycle = message
+	error(message, 0)
+end
+--* @internal After it returns, `node.cache` and `node.version` are current. 
+local evaluate
+function validate(node)
+	if node.evaluating then
+		cycle(node)
+	end
+	if node.cache.kind == 0 then
+		return evaluate(node)
+	end
+	-- ▼ ReadonlySet.size ▼
+	local _size = 0
+	for _ in node.observers do
+		_size += 1
+	end
+	-- ▲ ReadonlySet.size ▲
+	if _size == 0 then
+		if node.mark == 0 and node.validatedAt == epoch then
+			return nil
+		end
+		if node.mark == 0 then
+			node.mark = 1
+		end
+	end
+	if node.mark == 0 then
+		return nil
+	end
+	if node.mark == 1 then
+		local at = epoch
+		local moved = false
+		for _, edge in node.dependencies do
+			local source = edge.source
+			if source.kind == 1 then
+				validate(source)
+			end
+			if source.version ~= edge.seen then
+				moved = true
+				break
+			end
+		end
+		-- A dependency evaluated in its own boundary can drain lifecycle work that writes; then recompute.
+		if not moved and epoch == at then
+			node.mark = 0
+			node.validatedAt = at
+			return nil
+		end
+	end
+	evaluate(node)
+end
+--* Runs `read` under a Pure frame on this thread. A yield suspends the thread; its boundary finishes the node. 
+local settle
+local function evaluateInline(evaluation)
+	local _binding = evaluation
+	local node = _binding.node
+	local frame = _binding.frame
+	push(frame)
+	node.evaluating = true
+	thrown = nil
+	local ok, result = xpcall(node.read, capture)
+	pop(frame)
+	local failure = if ok then nil else (thrown or {
+		reason = tostring(result),
+		message = tostring(result),
+	})
+	thrown = nil
+	settle(node, frame, result, failure)
+end
+local finishOpen
+function evaluate(node)
+	local evaluation = {
+		node = node,
+		frame = observerFrame(1, node),
+	}
+	if inBody() then
+		evaluateInline(evaluation)
+	else
+		boundary(nil, nil, evaluateInline, evaluation, finishOpen)
+	end
+end
+--* @internal Finishes every computed a body left open: its evaluation failed with the body's error. 
+function finishOpen(completion)
+	if #completion.open == 0 then
+		return nil
+	end
+	local message = tostring(completion.value)
+	local failure = {
+		reason = if completion.result == 2 then YIELDED else message,
+		message = message,
+	}
+	for _, frame in completion.open do
+		if frame.kind == 1 then
+			settle(frame.observer, frame, nil, failure)
+		end
+	end
+end
+local rewire
+function settle(node, frame, result, thrownFailure)
+	node.evaluating = false
+	local failure = thrownFailure
+	if node.cycle ~= nil then
+		failure = {
+			reason = node.cycle,
+			message = node.cycle,
+		}
+		node.cycle = nil
+	end
+	local reads = frame.deps
+	local kept = reads
+	if failure ~= nil then
+		local _array = {}
+		local _length = #_array
+		table.move(reads, 1, #reads, _length + 1, _array)
+		kept = _array
+		for _, edge in node.dependencies do
+			local _reads = frame.reads
+			local _source = edge.source
+			if not (_reads[_source] ~= nil) then
+				local _kept = kept
+				local _arg0 = {
+					source = edge.source,
+					seen = edge.source.version,
+				}
+				table.insert(_kept, _arg0)
+			end
+		end
+	end
+	-- ▼ ReadonlySet.size ▼
+	local _size = 0
+	for _ in node.observers do
+		_size += 1
+	end
+	-- ▲ ReadonlySet.size ▲
+	if _size > 0 then
+		rewire(node, node.dependencies, kept)
+	end
+	node.dependencies = kept
+	local cache = node.cache
+	if failure ~= nil then
+		if cache.kind ~= 2 or cache.reason ~= failure.reason then
+			node.cache = {
+				kind = 2,
+				reason = failure.reason,
+				message = failure.message,
+			}
+			node.version += 1
+		end
+	elseif cache.kind ~= 1 or not rawequal(cache.value, result) then
+		node.cache = {
+			kind = 1,
+			value = result,
+		}
+		node.version += 1
+	end
+	node.mark = 0
+	node.validatedAt = epoch
+end
+--* A computed that gains its first observer registers on its sources, transitively. 
+local function attach(root)
+	local pending = { root }
+	while #pending > 0 do
+		-- ▼ Array.pop ▼
+		local _length = #pending
+		local _result = pending[_length]
+		pending[_length] = nil
+		-- ▲ Array.pop ▲
+		local node = _result
+		if node.mark == 0 and node.validatedAt ~= epoch then
+			node.mark = 1
+		end
+		for _, edge in node.dependencies do
+			local source = edge.source
+			-- ▼ ReadonlySet.size ▼
+			local _size = 0
+			for _1 in source.observers do
+				_size += 1
+			end
+			-- ▲ ReadonlySet.size ▲
+			local first = _size == 0
+			source.observers[node] = true
+			if first and source.kind == 1 then
+				table.insert(pending, source)
+			end
+		end
+	end
+end
+--* A computed that loses its last observer leaves its sources, transitively, and keeps its dependency list. 
+local function detach(root)
+	local pending = { root }
+	while #pending > 0 do
+		-- ▼ Array.pop ▼
+		local _length = #pending
+		local _result = pending[_length]
+		pending[_length] = nil
+		-- ▲ Array.pop ▲
+		local node = _result
+		if node.mark == 0 then
+			node.validatedAt = epoch
+		end
+		for _, edge in node.dependencies do
+			local source = edge.source
+			if not (source.observers[node] ~= nil) then
+				continue
+			end
+			source.observers[node] = nil
+			local _condition = source.kind == 1
+			if _condition then
+				-- ▼ ReadonlySet.size ▼
+				local _size = 0
+				for _1 in source.observers do
+					_size += 1
+				end
+				-- ▲ ReadonlySet.size ▲
+				_condition = _size == 0
+			end
+			if _condition then
+				table.insert(pending, source)
+			end
+		end
+	end
+end
+local function link(observer, source)
+	-- ▼ ReadonlySet.size ▼
+	local _size = 0
+	for _ in source.observers do
+		_size += 1
+	end
+	-- ▲ ReadonlySet.size ▲
+	local first = _size == 0
+	local _observers = source.observers
+	local _observer = observer
+	_observers[_observer] = true
+	if first and source.kind == 1 then
+		attach(source)
+	end
+end
+local function unlink(observer, source)
+	local _observers = source.observers
+	local _observer = observer
+	if not (_observers[_observer] ~= nil) then
+		return nil
+	end
+	local _observers_1 = source.observers
+	local _observer_1 = observer
+	_observers_1[_observer_1] = nil
+	local _condition = source.kind == 1
+	if _condition then
+		-- ▼ ReadonlySet.size ▼
+		local _size = 0
+		for _ in source.observers do
+			_size += 1
+		end
+		-- ▲ ReadonlySet.size ▲
+		_condition = _size == 0
+	end
+	if _condition then
+		detach(source)
+	end
+end
+--* A rerun that read the same sources in the same order keeps every registration. 
+local function sameSources(previous, following)
+	local size = #previous
+	if #following ~= size then
+		return false
+	end
+	do
+		local i = 0
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				i += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (i < size) then
+				break
+			end
+			if previous[i + 1].source ~= following[i + 1].source then
+				return false
+			end
+		end
+	end
+	return true
+end
+--* @internal Moves an attached observer's registrations from `previous` to `following`. 
+function rewire(observer, previous, following)
+	if sameSources(previous, following) then
+		return nil
+	end
+	local had = {}
+	for _, edge in previous do
+		local _source = edge.source
+		had[_source] = true
+	end
+	local keep = {}
+	for _, edge in following do
+		local _source = edge.source
+		keep[_source] = true
+		local _source_1 = edge.source
+		if not (had[_source_1] ~= nil) then
+			link(observer, edge.source)
+		end
+	end
+	for _, edge in previous do
+		local _source = edge.source
+		if not (keep[_source] ~= nil) then
+			unlink(observer, edge.source)
+		end
+	end
+end
+--* @internal Leaves every source. Used when an effect stops. 
+local function releaseEdges(observer)
+	for _, edge in observer.dependencies do
+		unlink(observer, edge.source)
+	end
+	observer.dependencies = {}
+end
+--* @internal How far an effect is from current after a run: a source it read may have moved during the run. 
+local function staleAfterRun(effect)
+	local level = 0
+	for _, edge in effect.dependencies do
+		local source = edge.source
+		if source.version ~= edge.seen then
+			return 2
+		end
+		if source.kind == 1 and source.mark ~= 0 then
+			level = 1
+		end
+	end
+	return level
+end
+--* @internal Raises an effect's mark and queues it. 
+local function markEffect(effect, level)
+	if effect.mark >= level then
+		return nil
+	end
+	effect.mark = level
+	schedule(effect)
+end
+--* @internal Pulls an effect's computed dependencies current in read order. True when any of them moved. 
+local function dependenciesMoved(effect)
+	for _, edge in effect.dependencies do
+		local source = edge.source
+		if source.kind == 1 then
+			validate(source)
+		end
+		if source.version ~= edge.seen then
+			return true
+		end
+	end
+	return false
+end
+return {
+	nextId = nextId,
+	createdBefore = createdBefore,
+	currentEpoch = currentEpoch,
+	useScheduler = useScheduler,
+	originOf = originOf,
+	guardPure = guardPure,
+	observerFrame = observerFrame,
+	readUntracked = readUntracked,
+	createStateNode = createStateNode,
+	readState = readState,
+	write = write,
+	commitPrepared = commitPrepared,
+	update = update,
+	createComputedNode = createComputedNode,
+	readComputed = readComputed,
+	validate = validate,
+	finishOpen = finishOpen,
+	rewire = rewire,
+	releaseEdges = releaseEdges,
+	staleAfterRun = staleAfterRun,
+	markEffect = markEffect,
+	dependenciesMoved = dependenciesMoved,
+}

package/out/internal/reactive/limits.d.ts

@@ -0,0 +1 @@
+export {};

package/out/internal/reactive/limits.luau

@@ -0,0 +1,54 @@
+-- Compiled with roblox-ts v3.0.0
+--* @internal Runs one effect may make in one flush before it stops as a feedback loop. 
+local MAX_RUNS_PER_EFFECT = 64
+--* @internal Effect runs in one flush, first runs included, before the rest waits for the next flush. 
+local MAX_EFFECT_RUNS_PER_FLUSH = 65_536
+--* @internal Rounds in one flush before the rest waits for the next flush. 
+local MAX_FLUSH_ROUNDS = 256
+--* @internal Live direct children of one generation lifetime before one warning names the owner. 
+local OWNER_CHILDREN_WARNING = 4_096
+--* @internal Reserved for the UI layer's render commit, `Enum.RenderPriority.Last.Value + 1`. Nothing binds it yet. 
+local RENDER_COMMIT_PRIORITY = 2_001
+--* @internal Replicated declarations one realm admits. 
+local MAX_REPLICATED_DECLARATIONS = 256
+--* @internal Table nesting one replicated value may use, at compile time and at admission. 
+local SYNC_VALUE_DEPTH = 28
+--* @internal Bytes in one string of a replicated value. 
+local SYNC_STRING_BYTES = 49_152
+--* @internal Bytes in one whole sync frame packet. One value can never exceed it. 
+local SYNC_FRAME_BYTES = 196_608
+--* @internal Collection entries in one sync frame. 
+local SYNC_FRAME_COLLECTION_ENTRIES = 12_000
+--* @internal Codec value visits in one sync frame. Also bounds one structural comparison. 
+local SYNC_FRAME_VALUE_VISITS = 48_000
+--* @internal Admission visits for one value: value nodes plus every table key touched. 
+local SYNC_ADMISSION_VISITS = 96_000
+--* @internal Visits one peer examination may spend, the snapshot included. 
+local SYNC_PEER_VISITS = 262_144
+--* @internal Frame bytes one Heartbeat sends to all peers, at least one frame. 
+local SYNC_HEARTBEAT_BYTES = 1_048_576
+--* @internal Peers one Heartbeat examines, at least one. 
+local SYNC_HEARTBEAT_PEERS = 64
+--* @internal A peer starts only while the Heartbeat has spent fewer visits than this. A threshold, not a ceiling. 
+local SYNC_HEARTBEAT_VISITS = 65_536
+--* @internal The last revision a peer's frames may carry. 
+local SYNC_MAX_REVISION = 4_294_967_295
+return {
+	MAX_RUNS_PER_EFFECT = MAX_RUNS_PER_EFFECT,
+	MAX_EFFECT_RUNS_PER_FLUSH = MAX_EFFECT_RUNS_PER_FLUSH,
+	MAX_FLUSH_ROUNDS = MAX_FLUSH_ROUNDS,
+	OWNER_CHILDREN_WARNING = OWNER_CHILDREN_WARNING,
+	RENDER_COMMIT_PRIORITY = RENDER_COMMIT_PRIORITY,
+	MAX_REPLICATED_DECLARATIONS = MAX_REPLICATED_DECLARATIONS,
+	SYNC_VALUE_DEPTH = SYNC_VALUE_DEPTH,
+	SYNC_STRING_BYTES = SYNC_STRING_BYTES,
+	SYNC_FRAME_BYTES = SYNC_FRAME_BYTES,
+	SYNC_FRAME_COLLECTION_ENTRIES = SYNC_FRAME_COLLECTION_ENTRIES,
+	SYNC_FRAME_VALUE_VISITS = SYNC_FRAME_VALUE_VISITS,
+	SYNC_ADMISSION_VISITS = SYNC_ADMISSION_VISITS,
+	SYNC_PEER_VISITS = SYNC_PEER_VISITS,
+	SYNC_HEARTBEAT_BYTES = SYNC_HEARTBEAT_BYTES,
+	SYNC_HEARTBEAT_PEERS = SYNC_HEARTBEAT_PEERS,
+	SYNC_HEARTBEAT_VISITS = SYNC_HEARTBEAT_VISITS,
+	SYNC_MAX_REVISION = SYNC_MAX_REVISION,
+}

package/out/internal/reactive/ownership.d.ts

@@ -0,0 +1 @@
+export {};