cluaupp 1.0.0 → 1.4.0

package/runtime/Fusion/_impl/External.luau

@@ -1,156 +0,0 @@
---!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

@@ -1,70 +0,0 @@
---!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

@@ -1,111 +0,0 @@
---!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

@@ -1,29 +0,0 @@
---!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

@@ -1,81 +0,0 @@
---!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

@@ -1,33 +0,0 @@
---!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

@@ -1,56 +0,0 @@
---!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

@@ -1,58 +0,0 @@
---!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

@@ -1,47 +0,0 @@
---!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

@@ -1,63 +0,0 @@
---!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