cluaupp 0.1.0

package/runtime/Fusion/_impl/External.luau

@@ -0,0 +1,156 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Abstraction layer between Fusion internals and external environments,
+	allowing for flexible integration with schedulers and test mocks.
+]]
+
+local Package = script.Parent
+local formatError = require(Package.Logging.formatError)
+local Types = require(Package.Types)
+
+local ERROR_INFO_URL = "https://elttob.uk/Fusion/0.3/api-reference/general/errors/#"
+
+local External = {}
+
+-- Multiplier for running-time safety checks across the Fusion codebase. Used to
+-- stricten tests on infinite loop detection during unit testing.
+External.safetyTimerMultiplier = 1
+
+local updateStepCallbacks = {}
+local currentProvider: Types.ExternalProvider? = nil
+local lastUpdateStep = 0
+
+--[[
+	Swaps to a new provider for external operations.
+	Returns the old provider, so it can be used again later.
+]]
+function External.setExternalProvider(
+	newProvider: Types.ExternalProvider?
+): Types.ExternalProvider?
+	local oldProvider = currentProvider
+	if oldProvider ~= nil then
+		oldProvider.stopScheduler()
+	end
+	currentProvider = newProvider
+	if newProvider ~= nil then
+		newProvider.startScheduler()
+	end
+	return oldProvider
+end
+
+--[[
+   Sends an immediate task to the external provider. Throws if none is set.
+]]
+function External.doTaskImmediate(
+	resume: () -> ()
+)
+	if currentProvider == nil then
+		External.logError("noTaskScheduler")
+	else
+		currentProvider.doTaskImmediate(resume)
+	end
+end
+
+--[[
+	Sends a deferred task to the external provider. Throws if none is set.
+]]
+function External.doTaskDeferred(
+	resume: () -> ()
+)
+	if currentProvider == nil then
+		External.logError("noTaskScheduler")
+	else
+		currentProvider.doTaskDeferred(resume)
+	end
+end
+
+--[[
+	Errors in the current thread and halts execution.
+]]
+function External.logError(
+	messageID: string,
+	errObj: Types.Error?,
+	...: unknown
+): never
+	error(formatError(currentProvider, messageID, errObj, ...), 0)
+end
+
+--[[
+	Errors in a different thread to preserve the flow of execution.
+]]
+function External.logErrorNonFatal(
+	messageID: string,
+	errObj: Types.Error?,
+	...: unknown
+): ()
+	local errorString = formatError(currentProvider, messageID, errObj, ...)
+	if currentProvider ~= nil then
+		currentProvider.logErrorNonFatal(errorString)
+	else
+		print(errorString)
+	end
+end
+
+--[[
+	Shows a warning message in the output.
+]]
+function External.logWarn(
+	messageID: string,
+	...: unknown
+): ()
+	local errorString = formatError(currentProvider, messageID, debug.traceback(nil, 2), ...)
+	if currentProvider ~= nil then
+		currentProvider.logWarn(errorString)
+	else
+		print(errorString)
+	end
+end
+
+--[[
+	Registers a callback to the update step of the external provider.
+	Returns a function that can be used to disconnect later.
+
+	Callbacks are given the current number of seconds since an arbitrary epoch.
+	
+	TODO: This epoch may change between providers. We could investigate ways
+	of allowing providers to co-operate to keep the epoch the same, so that
+	monotonicity can be better preserved.
+]]
+function External.bindToUpdateStep(
+	callback: (
+		now: number
+	) -> ()
+): () -> ()
+	local uniqueIdentifier = {}
+	updateStepCallbacks[uniqueIdentifier] = callback
+	return function()
+		updateStepCallbacks[uniqueIdentifier] = nil
+	end
+end
+
+--[[
+	Steps time-dependent systems with the current number of seconds since an
+	arbitrary epoch. This should be called as early as possible in the external
+	provider's update cycle.
+]]
+function External.performUpdateStep(
+	now: number
+)
+	lastUpdateStep = now
+	for _, callback in updateStepCallbacks do
+		callback(now)
+	end
+end
+
+--[[
+	Returns the timestamp of the last update step.
+]]
+function External.lastUpdateStep()
+	return lastUpdateStep
+end
+
+return External

package/runtime/Fusion/_impl/ExternalDebug.luau

@@ -0,0 +1,70 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Abstraction layer between Fusion internals and external debuggers, allowing
+	for deep introspection using function hooks.
+
+	Unlike `External`, attaching a debugger is optional, and all debugger
+	functions are expected to be infallible and non-blocking.
+]]
+
+local Package = script.Parent
+local Types = require(Package.Types)
+
+local currentProvider: Types.ExternalDebugger? = nil
+local lastUpdateStep = 0
+
+local Debugger = {}
+
+--[[
+	Swaps to a new debugger.
+	Returns the old debugger, so it can be used again later.
+]]
+function Debugger.setDebugger(
+	newProvider: Types.ExternalDebugger?
+): Types.ExternalDebugger?
+	local oldProvider = currentProvider
+	if oldProvider ~= nil then
+		oldProvider.stopDebugging()
+	end
+	currentProvider = newProvider
+	if newProvider ~= nil then
+		newProvider.startDebugging()
+	end
+	return oldProvider
+end
+
+--[[
+	Called at the earliest moment after a scope is created or removed from the
+	scope pool, but not before the scope has finished being prepared by the
+	library, so that debuggers can register its existence and track changes
+	to the scope over time.
+]]
+function Debugger.trackScope(
+	scope: Types.Scope<unknown>
+): ()
+	if currentProvider == nil then
+		return
+	end
+	currentProvider.trackScope(scope)
+end
+
+--[[
+	Called at the final moment before a scope is poisoned or added to the scope
+	pool, after all cleanup tasks have completed, so that debuggers can erase 
+	the scope from internal trackers. Note that, due to scope pooling and user
+	code, never assume that this correlates with garbage collection events.
+]]
+function Debugger.untrackScope(
+	scope: Types.Scope<unknown>
+): ()
+	if currentProvider == nil then
+		return
+	end
+	currentProvider.trackScope(scope)
+end
+
+return Debugger

package/runtime/Fusion/_impl/Graph/Observer.luau

@@ -0,0 +1,111 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	A graph object that runs user code when it's updated by the reactive graph.
+
+	http://elttob.uk/Fusion/0.3/api-reference/state/types/observer/
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+-- Memory
+local checkLifetime = require(Package.Memory.checkLifetime)
+-- Graph
+local castToGraph = require(Package.Graph.castToGraph)
+local depend = require(Package.Graph.depend)
+local evaluate = require(Package.Graph.evaluate)
+-- Utility
+local nicknames = require(Package.Utility.nicknames)
+
+type Self = Types.Observer & {
+	_watchingGraph: Types.GraphObject?,
+	_changeListeners: {[unknown]: () -> ()}
+}
+
+local class = {}
+class.type = "Observer"
+class.timeliness = "eager"
+class.dependentSet = table.freeze {}
+
+local METATABLE = table.freeze {__index = class}
+
+local function Observer(
+	scope: Types.Scope<unknown>,
+	watching: unknown
+): Types.Observer
+	local createdAt = os.clock()
+
+	local self: Self = setmetatable(
+		{
+			scope = scope,
+			createdAt = createdAt,
+			dependencySet = {},
+			lastChange = nil,
+			validity = "invalid",
+			_watchingGraph = castToGraph(watching),
+			_changeListeners = {}
+		},
+		METATABLE
+	) :: any
+	local destroy = function()
+		self.scope = nil
+		for dependency in pairs(self.dependencySet) do
+			dependency.dependentSet[self] = nil
+		end
+	end
+	self.oldestTask = destroy
+	nicknames[self.oldestTask] = "Observer"
+	table.insert(scope, destroy)
+
+	if self._watchingGraph ~= nil then
+		checkLifetime.bOutlivesA(
+			scope, self.oldestTask,
+			self._watchingGraph.scope, self._watchingGraph.oldestTask,
+			checkLifetime.formatters.observer
+		)
+	end
+
+	-- Eagerly evaluated objects need to evaluate themselves so that they're
+	-- valid at all times.
+	evaluate(self, true)
+
+	return self
+end
+
+function class.onBind(
+	self: Self,
+	callback: () -> ()
+): () -> ()
+	External.doTaskImmediate(callback)
+	return self:onChange(callback)
+end
+
+function class.onChange(
+	self: Self,
+	callback: () -> ()
+): () -> ()
+	local uniqueIdentifier = table.freeze {}
+	self._changeListeners[uniqueIdentifier] = callback
+	return function()
+		self._changeListeners[uniqueIdentifier] = nil
+	end
+end
+
+function class._evaluate(
+	self: Self
+): ()
+	if self._watchingGraph ~= nil then
+		depend(self, self._watchingGraph)
+	end
+	for _, callback in self._changeListeners do
+		External.doTaskImmediate(callback)
+	end
+	return true
+end
+
+table.freeze(class)
+return Observer :: Types.ObserverConstructor

package/runtime/Fusion/_impl/Graph/castToGraph.luau

@@ -0,0 +1,29 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Returns the input *only* if it is a graph object.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+
+local function castToGraph(
+	target: any
+): Types.GraphObject?
+	if 
+		typeof(target) == "table" and
+		typeof(target.validity) == "string" and
+		typeof(target.timeliness) == "string" and
+		typeof(target.dependencySet) == "table" and
+		typeof(target.dependentSet) == "table"
+	then
+		return target
+	else
+		return nil
+	end
+end
+
+return castToGraph

package/runtime/Fusion/_impl/Graph/change.luau

@@ -0,0 +1,81 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Prompts a graph object to re-evaluate its own value. If it meaningfully
+	changes, then dependents will have to re-evaluate their own values in the
+	future.
+
+	https://fluff.blog/2024/04/16/monotonic-painting.html
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+local evaluate = require(Package.Graph.evaluate)
+
+-- How long should this function run before it's considered to be in an infinite
+-- cycle and error out?
+local TERMINATION_TIME = 1
+
+local function change(
+	target: Types.GraphObject
+): ()
+	if target.validity == "busy" then
+		return External.logError("infiniteLoop")
+	end
+
+	local meaningfullyChanged = evaluate(target, true)
+	if not meaningfullyChanged then
+		return
+	end
+
+	local searchInNow: {Types.GraphObject} = {}
+	local searchInNext: {Types.GraphObject} = {}
+	local invalidateList: {Types.GraphObject} = {}
+
+	searchInNow[1] = target
+	local terminateBy = os.clock() + TERMINATION_TIME * External.safetyTimerMultiplier
+	repeat
+		if os.clock() > terminateBy then
+			return External.logError("infiniteLoop")
+		end
+		local done = true
+		for _, searchTarget in searchInNow do
+			for dependent in searchTarget.dependentSet do
+				if dependent.validity == "valid" then
+					done = false
+					table.insert(invalidateList, dependent)
+					table.insert(searchInNext, dependent)
+				elseif dependent.validity == "busy" then
+					return External.logError("infiniteLoop")
+				end
+			end
+		end
+		searchInNow, searchInNext = searchInNext, searchInNow
+		table.clear(searchInNext)
+	until done
+
+	local eagerList: {Types.GraphObject} = {}
+
+	for _, invalidateTarget in invalidateList do
+		invalidateTarget.validity = "invalid"
+		if invalidateTarget.timeliness == "eager" then
+			table.insert(eagerList, invalidateTarget)
+		end
+	end
+	-- If objects are not executed in order of creations, then dynamic graphs
+	-- may experience 'glitches' where nested graph objects see intermediate
+	-- values before being destroyed.
+	-- https://fluff.blog/2024/07/14/glitches-in-dynamic-reactive-graphs.html
+	table.sort(eagerList, function(a, b)
+		return a.createdAt < b.createdAt
+	end)
+	for _, eagerTarget in eagerList do
+		evaluate(eagerTarget, false)
+	end
+end
+
+return change

package/runtime/Fusion/_impl/Graph/depend.luau

@@ -0,0 +1,33 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Forms a dependency on a graph object.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+local evaluate = require(Package.Graph.evaluate)
+local nameOf = require(Package.Utility.nameOf)
+
+local function depend<T>(
+	dependent: Types.GraphObject,
+	dependency: Types.GraphObject
+): ()
+	-- Ensure dependencies are evaluated and up-to-date
+	-- when they are depended on. Also, newly created objects
+	-- might not have any transitive dependencies captured yet,
+	-- so ensure that they're present.
+	evaluate(dependency, false)
+
+	if table.isfrozen(dependent.dependencySet) or table.isfrozen(dependency.dependentSet) then
+		External.logError("cannotDepend", nil, nameOf(dependent, "Dependent"), nameOf(dependency, "dependency"))
+	end
+	dependency.dependentSet[dependent] = true
+	dependent.dependencySet[dependency] = true
+end
+
+return depend

package/runtime/Fusion/_impl/Graph/evaluate.luau

@@ -0,0 +1,56 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Evaluates the graph object if necessary, so that it is up to date.
+	Returns true if it meaningfully changed.
+
+	https://fluff.blog/2024/04/16/monotonic-painting.html
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+
+local function evaluate(
+	target: Types.GraphObject,
+	forceComputation: boolean
+): boolean
+	if target.validity == "busy" then
+		return External.logError("infiniteLoop")
+	end
+	local firstEvaluation = target.lastChange == nil
+	local isInvalid = target.validity == "invalid"
+	if firstEvaluation or isInvalid or forceComputation then
+		local needsComputation = firstEvaluation or forceComputation
+		if not needsComputation then
+			for dependency in target.dependencySet do
+				evaluate(dependency, false)
+				if dependency.lastChange > target.lastChange then
+					needsComputation = true
+					break
+				end
+			end
+		end
+		local targetMeaningfullyChanged = false
+		if needsComputation then
+			for dependency in target.dependencySet do
+				dependency.dependentSet[target] = nil
+				target.dependencySet[dependency] = nil
+			end
+			target.validity = "busy"
+			targetMeaningfullyChanged = target:_evaluate() or firstEvaluation
+		end
+		if targetMeaningfullyChanged then
+			target.lastChange = os.clock()
+		end
+		target.validity = "valid"
+		return targetMeaningfullyChanged
+	else
+		return false
+	end
+end
+
+return evaluate

package/runtime/Fusion/_impl/Instances/Attribute.luau

@@ -0,0 +1,58 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	A special key for property tables, which allows users to apply custom
+	attributes to instances
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+-- Memory
+local checkLifetime = require(Package.Memory.checkLifetime)
+-- Graph
+local Observer = require(Package.Graph.Observer)
+-- State
+local castToState = require(Package.State.castToState)
+local peek = require(Package.State.peek)
+
+local keyCache: {[string]: Types.SpecialKey} = {}
+
+local function Attribute(
+	attributeName: string
+): Types.SpecialKey
+	local key = keyCache[attributeName]
+	if key == nil then
+		key = {
+			type = "SpecialKey",
+			kind = "Attribute",
+			stage = "self",
+			apply = function(
+				self: Types.SpecialKey,
+				scope: Types.Scope<unknown>,
+				value: unknown,
+				applyTo: Instance
+			)
+				if castToState(value) then
+					local value = value :: Types.StateObject<unknown>
+					checkLifetime.bOutlivesA(
+						scope, applyTo,
+						value.scope, value.oldestTask,
+						checkLifetime.formatters.boundAttribute, attributeName
+					)
+					Observer(scope, value :: any):onBind(function()
+						applyTo:SetAttribute(attributeName, peek(value))
+					end)
+				else
+					applyTo:SetAttribute(attributeName, value)
+				end
+			end
+		}
+		keyCache[attributeName] = key
+	end
+	return key
+end
+
+return Attribute

package/runtime/Fusion/_impl/Instances/AttributeChange.luau

@@ -0,0 +1,47 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	A special key for property tables, which allows users to connect to
+	an attribute change on an instance.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+
+local keyCache: {[string]: Types.SpecialKey} = {}
+
+local function AttributeChange(
+	attributeName: string
+): Types.SpecialKey
+	local key = keyCache[attributeName]
+	if key == nil then
+		key = {
+			type = "SpecialKey",
+			kind = "AttributeChange",
+			stage = "observer",
+			apply = function(
+				self: Types.SpecialKey,
+				scope: Types.Scope<unknown>,
+				value: unknown,
+				applyTo: Instance
+			)
+				if typeof(value) ~= "function" then
+					External.logError("invalidAttributeChangeHandler", nil, attributeName)
+				end
+				local value = value :: (...unknown) -> (...unknown)
+				local event = applyTo:GetAttributeChangedSignal(attributeName)
+				table.insert(scope, event:Connect(function()
+					value((applyTo :: any):GetAttribute(attributeName))
+				end))
+			end
+		}
+		keyCache[attributeName] = key
+	end
+	return key
+end
+
+return AttributeChange

package/runtime/Fusion/_impl/Instances/AttributeOut.luau

@@ -0,0 +1,63 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	A special key for property tables, which allows users to save instance attributes
+	into state objects
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+-- Memory
+local checkLifetime = require(Package.Memory.checkLifetime)
+-- State
+local castToState = require(Package.State.castToState)
+
+local keyCache: {[string]: Types.SpecialKey} = {}
+
+local function AttributeOut(
+	attributeName: string
+): Types.SpecialKey
+	local key = keyCache[attributeName]
+	if key == nil then
+		key = {
+			type = "SpecialKey",
+			kind = "AttributeOut",
+			stage = "observer",
+			apply = function(
+				self: Types.SpecialKey,
+				scope: Types.Scope<unknown>,
+				value: unknown,
+				applyTo: Instance
+			)
+				local event = applyTo:GetAttributeChangedSignal(attributeName)
+	
+				if not castToState(value) then
+					External.logError("invalidAttributeOutType")
+				end
+				local value = value :: Types.StateObject<unknown>
+				if value.kind ~= "Value" then
+					External.logError("invalidAttributeOutType")
+				end
+				local value = value :: Types.Value<unknown>
+				checkLifetime.bOutlivesA(
+					scope, applyTo,
+					value.scope, value.oldestTask,
+					checkLifetime.formatters.attributeOutputsTo, attributeName
+				)
+
+				value:set((applyTo :: any):GetAttribute(attributeName))
+				table.insert(scope, event:Connect(function()	
+					value:set((applyTo :: any):GetAttribute(attributeName))
+				end))
+			end
+		}
+		keyCache[attributeName] = key
+	end
+	return key
+end
+
+return AttributeOut