cluaupp 0.1.0

package/runtime/Fusion/Memory/doCleanup.luau

@@ -0,0 +1,91 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Cleans up the tasks passed in as the arguments.
+	A task can be any of the following:
+
+	- an Instance - will be destroyed
+	- an RBXScriptConnection - will be disconnected
+	- a function - will be run
+	- a table with a `Destroy` or `destroy` function - will be called
+	- an array - `cleanup` will be called on each item
+]]
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+local ExternalDebug = require(Package.ExternalDebug)
+
+local alreadyDestroying: {[Types.Task]: true} = {}
+
+local function doCleanup(
+	task: Types.Task
+): ()
+	if alreadyDestroying[task] then
+		return External.logError("destroyedTwice")
+	end
+	alreadyDestroying[task] = true
+
+	-- case 1: Instance
+	if typeof(task) == "Instance" then
+		task:Destroy()
+
+	-- case 2: RBXScriptConnection
+	elseif typeof(task) == "RBXScriptConnection" then
+		task:Disconnect()
+
+	-- case 3: callback
+	elseif typeof(task) == "function" then
+		task()
+
+	elseif typeof(task) == "table" then
+		local task = (
+			task :: any
+		) :: {
+			Destroy: (...unknown) -> ...unknown?,
+			destroy: (...unknown) -> ...unknown?,
+			Disconnect: (...unknown) -> ...unknown?,
+			disconnect: (...unknown) -> ...unknown?,
+		}
+
+		-- case 4: destroy() function
+		if typeof(task.destroy) == "function" then
+			local task = (task :: any) :: {destroy: (...unknown) -> (...unknown)}
+			task:destroy()
+
+		-- case 5: Destroy() function
+		elseif typeof(task.Destroy) == "function" then
+			local task = (task :: any) :: {Destroy: (...unknown) -> (...unknown)}
+			task:Destroy()
+
+		-- case 6: table of tasks with an array part
+		elseif task[1] ~= nil then
+			local task = task :: {Types.Task}
+
+			-- It is important to iterate backwards through the table, since
+			-- objects are added in order of construction.
+			for index = #task, 1, -1 do
+				doCleanup(task[index])
+				task[index] = nil
+			end
+
+			ExternalDebug.untrackScope(task)
+
+		-- case 7: Disconnect() function
+		elseif typeof(task.Disconnect) == "function" then
+			local task = (task :: any) :: { Disconnect: (...unknown) -> ...unknown }
+			task:Disconnect()
+
+		-- case 8: disconnect() function
+		elseif typeof(task.disconnect) == "function" then
+			local task = (task :: any) :: { disconnect: (...unknown) -> ...unknown }
+			task:disconnect()
+		end
+	end
+	
+	alreadyDestroying[task] = nil
+end
+
+return doCleanup

package/runtime/Fusion/Memory/innerScope.luau

@@ -0,0 +1,34 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Derives a new scope that's destroyed exactly once, whether by the user or by
+	the scope that it's inside of.
+]]
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local ExternalDebug = require(Package.ExternalDebug)
+local deriveScopeImpl = require(Package.Memory.deriveScopeImpl)
+
+local function innerScope<T>(
+	existing: Types.Scope<T>,
+	...: {[unknown]: unknown}
+): any
+	local new = deriveScopeImpl(existing, ...)
+	table.insert(existing, new)
+	table.insert(
+		new, 
+		function()
+			local index = table.find(existing, new)
+			if index ~= nil then
+				table.remove(existing, index)
+			end
+		end
+	)
+	ExternalDebug.trackScope(new)
+	return new
+end
+
+return (innerScope :: any) :: Types.DeriveScopeConstructor

package/runtime/Fusion/Memory/insert.luau

@@ -0,0 +1,22 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Inserts clean up tasks passed in to the scope.
+]]
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+
+local function insert<Tasks...>(
+	scope: Types.Scope<unknown>,
+	...: Tasks...
+): Tasks...
+	for index = 1, select("#", ...) do
+		table.insert(scope, select(index, ...))
+	end
+	return ...
+end
+
+return insert

package/runtime/Fusion/Memory/needsDestruction.luau

@@ -0,0 +1,17 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Returns true if the given value is not automatically memory managed, and
+	requires manual cleanup.
+]]
+
+local function needsDestruction(
+	x: unknown
+): boolean
+	return typeof(x) == "Instance"
+end
+
+return needsDestruction

package/runtime/Fusion/Memory/scoped.luau

@@ -0,0 +1,24 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Creates cleanup tables with access to constructors as methods.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local ExternalDebug = require(Package.ExternalDebug)
+local merge = require(Package.Utility.merge)
+
+local function scoped(
+	...: {[unknown]: unknown}
+): any
+	local metatable = {__index = merge(false, {}, ...)}
+	local scope = setmetatable({}, metatable) :: any
+	ExternalDebug.trackScope(scope)
+	return scope
+end
+
+return (scoped :: any) :: Types.ScopedConstructor

package/runtime/Fusion/RobloxExternal.luau

@@ -0,0 +1,98 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+
+--[[
+	Roblox implementation for Fusion's abstract provider layer.
+]]
+
+local RunService = game:GetService("RunService")
+local HttpService = game:GetService("HttpService")
+
+local Package = script.Parent
+local External = require(Package.External)
+
+local RobloxExternal = {}
+
+RobloxExternal.policies = {
+	allowWebLinks = RunService:IsStudio()
+}
+
+--[[
+   Sends an immediate task to the external provider. Throws if none is set.
+]]
+function RobloxExternal.doTaskImmediate(
+	resume: () -> ()
+)
+   task.spawn(resume)
+end
+
+--[[
+	Sends a deferred task to the external provider. Throws if none is set.
+]]
+function RobloxExternal.doTaskDeferred(
+	resume: () -> ()
+)
+	task.defer(resume)
+end
+
+--[[
+	Errors in a different thread to preserve the flow of execution.
+]]
+function RobloxExternal.logErrorNonFatal(
+	errorString: string
+)
+	task.spawn(error, errorString, 0)
+end
+
+--[[
+	Shows a warning message in the output.
+]]
+RobloxExternal.logWarn = warn
+
+--[[
+	Sends an update step to Fusion using the Roblox clock time.
+]]
+local function performUpdateStep()
+	External.performUpdateStep(os.clock())
+end
+
+--[[
+	Binds Fusion's update step to RunService step events.
+]]
+local stopSchedulerFunc = nil :: (() -> ())?
+function RobloxExternal.startScheduler()
+	if stopSchedulerFunc ~= nil then
+		return
+	end
+	if RunService:IsClient() then
+		-- In cases where multiple Fusion modules are running simultaneously,
+		-- this prevents collisions.
+		local id = "FusionUpdateStep_" .. HttpService:GenerateGUID()
+		RunService:BindToRenderStep(
+			id,
+			Enum.RenderPriority.First.Value,
+			performUpdateStep
+		)
+		stopSchedulerFunc = function()
+			RunService:UnbindFromRenderStep(id)
+		end
+	else
+		local connection = RunService.Heartbeat:Connect(performUpdateStep)
+		stopSchedulerFunc = function()
+			connection:Disconnect()
+		end
+	end
+end
+
+--[[
+	Unbinds Fusion's update step from RunService step events.
+]]
+function RobloxExternal.stopScheduler()
+	if stopSchedulerFunc ~= nil then
+		stopSchedulerFunc()
+		stopSchedulerFunc = nil
+	end
+end
+
+return RobloxExternal

package/runtime/Fusion/State/Computed.luau

@@ -0,0 +1,122 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	A specialised state object for tracking single values computed from a
+	user-defined computation.
+
+	https://elttob.uk/Fusion/0.3/api-reference/state/types/computed/
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+-- Logging
+local parseError = require(Package.Logging.parseError)
+-- Utility
+local isSimilar = require(Package.Utility.isSimilar)
+-- Graph
+local depend = require(Package.Graph.depend)
+-- State
+local castToState = require(Package.State.castToState)
+local peek = require(Package.State.peek)
+-- Memory
+local doCleanup = require(Package.Memory.doCleanup)
+local deriveScope = require(Package.Memory.deriveScope)
+local checkLifetime = require(Package.Memory.checkLifetime)
+-- Utility
+local nicknames = require(Package.Utility.nicknames)
+
+type Self<T, S> = Types.Computed<T> & {
+	_innerScope: Types.Scope<S>?,
+	_processor: (Types.Use, Types.Scope<S>) -> T
+}
+
+local class = {}
+class.type = "State"
+class.kind = "Computed"
+class.timeliness = "lazy"
+
+local METATABLE = table.freeze {__index = class}
+
+local function Computed<T, S>(
+	scope: S & Types.Scope<unknown>,
+	processor: (Types.Use, S) -> T
+): Types.Computed<T>
+	local createdAt = os.clock()
+	local self: Self<T, S> = setmetatable(
+		{
+			createdAt = createdAt,
+			dependencySet = {},
+			dependentSet = {},
+			lastChange = nil,
+			scope = scope,
+			validity = "invalid",
+			_EXTREMELY_DANGEROUS_usedAsValue = nil,
+			_innerScope = nil,
+			_processor = processor
+		}, 
+		METATABLE
+	) :: any
+	local destroy = function()
+		self.scope = nil
+		for dependency in pairs(self.dependencySet) do
+			dependency.dependentSet[self] = nil
+		end
+		if self._innerScope ~= nil then
+			doCleanup(self._innerScope)
+			self._innerScope = nil
+		end
+	end
+	self.oldestTask = destroy
+	nicknames[self.oldestTask] = "Computed"
+	table.insert(scope, destroy)
+	return self
+end
+
+function class._evaluate<T, S>(
+	self: Self<T, S>
+): boolean
+	if self.scope == nil then
+		return false
+	end
+	local outerScope = self.scope :: S & Types.Scope<unknown>
+	local innerScope = deriveScope(outerScope)
+	local function use<T>(target: Types.UsedAs<T>): T
+		local targetState = castToState(target)
+		if targetState ~= nil then
+			checkLifetime.bOutlivesA(
+				outerScope, self.oldestTask, 
+				targetState.scope, targetState.oldestTask, 
+				checkLifetime.formatters.useFunction
+			)
+			depend(self, targetState)
+		end
+		return peek(target)
+	end
+	local ok, newValue = xpcall(self._processor, parseError, use, innerScope)
+	if ok then
+		local similar = isSimilar(self._EXTREMELY_DANGEROUS_usedAsValue, newValue)
+		if self._innerScope ~= nil then
+			doCleanup(self._innerScope)
+			self._innerScope = nil
+		end
+		self._innerScope = innerScope
+
+		self._EXTREMELY_DANGEROUS_usedAsValue = newValue
+		return not similar
+	else
+		local errorObj = (newValue :: any) :: Types.Error
+		doCleanup(innerScope)
+		
+		-- this needs to be non-fatal, because otherwise it'd disrupt the
+		-- update process
+		External.logErrorNonFatal("callbackError", errorObj)
+		return false
+	end
+end
+
+table.freeze(class)
+return Computed :: Types.ComputedConstructor

package/runtime/Fusion/State/For/Disassembly.luau

@@ -0,0 +1,207 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Breaks down an input table into reactive sub-objects for each pair.
+]]
+
+local Package = script.Parent.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+-- Graph
+local depend = require(Package.Graph.depend)
+-- State
+local peek = require(Package.State.peek)
+local castToState = require(Package.State.castToState)
+local ForTypes = require(Package.State.For.ForTypes)
+-- Memory
+local doCleanup = require(Package.Memory.doCleanup)
+local deriveScope = require(Package.Memory.deriveScope)
+-- Utility
+local nameOf = require(Package.Utility.nameOf)
+local nicknames = require(Package.Utility.nicknames)
+
+type Self<S, KI, KO, VI, VO> = ForTypes.Disassembly<S, KI, KO, VI, KO> & {
+	scope: (S & Types.Scope<unknown>)?,
+	_inputTable: Types.UsedAs<{[KI]: VI}>,
+	_constructor: (
+		Types.Scope<S>,
+		initialKey: KI,
+		initialValue: VI
+	) -> ForTypes.SubObject<S, KI, KO, VI, VO>,
+	_subObjects: {[ForTypes.SubObject<S, KI, KO, VI, VO>]: true}
+}
+
+
+local class = {}
+class.type = "Graph"
+class.kind = "For.Disassembly"
+class.timeliness = "lazy"
+
+local METATABLE = table.freeze {__index = class}
+
+local function Disassembly<S, KI, KO, VI, VO>(
+	scope: S & Types.Scope<unknown>,
+	inputTable: Types.UsedAs<{[KI]: VI}>,
+	constructor: (
+		Types.Scope<S>,
+		initialKey: KI,
+		initialValue: VI
+	) -> ForTypes.SubObject<S, KI, KO, VI, VO>
+): ForTypes.Disassembly<S, KI, KO, VI, KO>
+	local createdAt = os.clock()
+	local self = setmetatable(
+		{
+			createdAt = createdAt,
+			dependencySet = {},
+			dependentSet = {},
+			scope = scope,
+			validity = "invalid",
+			_inputTable = inputTable,
+			_constructor = constructor,
+			_subObjects = {}
+		}, 
+		METATABLE
+	) :: any
+
+	local destroy = function()
+		self.scope = nil
+		for dependency in pairs(self.dependencySet) do
+			dependency.dependentSet[self] = nil
+		end
+		for subObject in self._subObjects do
+			if subObject.maybeScope ~= nil then
+				doCleanup(subObject.maybeScope)
+				subObject.maybeScope = nil
+			end
+		end
+	end
+	self.oldestTask = destroy
+	nicknames[self.oldestTask] = "For (internal disassembler)"
+	table.insert(scope, destroy)
+	
+	return self
+end
+
+function class.populate<S, KI, KO, VI, VO>(
+	self: Self<S, KI, KO, VI, VO>,
+	use: Types.Use,
+	output: {[KO]: VO}
+): ()
+	local minArrayIndex = math.huge
+	local maxArrayIndex = -math.huge
+	local hasHoles = false
+	for subObject in self._subObjects do
+		local outputKey, outputValue = subObject:useOutputPair(use)
+		if outputKey == nil or outputValue == nil then
+			hasHoles = true
+			continue
+		elseif output[outputKey] ~= nil then
+			External.logErrorNonFatal("forKeyCollision", nil, tostring(outputKey))
+			continue
+		end
+		output[outputKey] = outputValue
+		if typeof(outputKey) == "number" then
+			minArrayIndex = math.min(minArrayIndex, outputKey)
+			maxArrayIndex = math.max(maxArrayIndex, outputKey)
+		end
+	end
+	-- Be careful of NaN here
+	if hasHoles and maxArrayIndex > minArrayIndex then
+		local output: {[number]: VO} = output :: any
+		local moveToIndex = minArrayIndex
+		for moveFromIndex = minArrayIndex, maxArrayIndex do
+			local outputValue = output[moveFromIndex]
+			if outputValue == nil then
+				continue
+			end
+			-- The ordering is important in case the indices are the same
+			output[moveFromIndex] = nil
+			output[moveToIndex] = outputValue
+			moveToIndex += 1
+		end
+	end
+end
+
+function class._evaluate<S, KI, KO, VI, VO>(
+	self: Self<S, KI, KO, VI, VO>
+): boolean
+	local outerScope = self.scope :: S & Types.Scope<unknown>
+	local inputState = castToState(self._inputTable)
+	if inputState ~= nil then
+		if inputState.scope == nil then
+			External.logError(
+				"useAfterDestroy",
+				nil,
+				`The input {nameOf(inputState, "table")}`,
+				`the For object that is watching it`
+			)
+		end
+		depend(self, inputState)
+	end
+
+	local pendingPairs = {} :: {[KI]: VI}
+	for key, value in peek(self._inputTable) do
+		pendingPairs[key] = value
+	end
+
+	local newSubObjects = {} :: typeof(self._subObjects)
+
+	for subObject in self._subObjects do
+		local reused = false
+		local oldInputKey = subObject.inputKey
+		local oldInputValue = subObject.inputValue
+		local newInputKey: KI
+		-- Reuse when the keys are identical.
+		if not subObject.roamKeys and pendingPairs[oldInputKey] ~= nil then
+			reused = true
+			newInputKey = oldInputKey
+		else -- Try and reuse some other pair instead.
+			for pendingKey, pendingValue in pendingPairs do
+				reused = true
+				newInputKey = pendingKey
+				if subObject.roamValues then
+					break
+				end
+				if pendingValue == oldInputValue then
+					-- If the values are the same, then no need to update those,
+					-- so prefer this choice to any other.
+					break 
+				end
+			end
+		end
+		if reused then
+			local newInputValue = pendingPairs[newInputKey]
+			newSubObjects[subObject] = true
+			if newInputKey ~= oldInputKey then
+				subObject.inputKey = newInputKey
+				subObject:invalidateInputKey()
+			end
+			if newInputValue ~= oldInputValue then
+				subObject.inputValue = newInputValue
+				subObject:invalidateInputValue()
+			end
+			pendingPairs[newInputKey] = nil
+		else -- Too many sub objects for the number of pairs.
+			if subObject.maybeScope ~= nil then
+				doCleanup(subObject.maybeScope)
+				subObject.maybeScope = nil
+			end
+		end
+	end
+
+	-- Generate new objects if needed to cover the remaining pending pairs.
+	for pendingKey, pendingValue in pendingPairs do
+		local subObject = self._constructor(deriveScope(outerScope), pendingKey, pendingValue)
+		newSubObjects[subObject] = true
+	end
+
+	self._subObjects = newSubObjects
+
+	return true
+end
+
+table.freeze(class)
+return Disassembly

package/runtime/Fusion/State/For/ForTypes.luau

@@ -0,0 +1,30 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Stores types that are commonly used between For objects.
+]]
+
+local Package = script.Parent.Parent.Parent
+local Types = require(Package.Types)
+
+export type SubObject<S, KI, KO, VI, VO> = {
+	-- Not all sub objects need to store a scope, for example if the scope
+	-- remains empty, it'll be given back to the scope pool.
+	maybeScope: Types.Scope<S>?,
+	inputKey: KI,
+	inputValue: VI,
+	roamKeys: boolean,
+	roamValues: boolean,
+	invalidateInputKey: (SubObject<S, KI, KO, VI, VO>) -> (),
+	invalidateInputValue: (SubObject<S, KI, KO, VI, VO>) -> (),
+	useOutputPair: (SubObject<S, KI, KO, VI, VO>, Types.Use) -> (KO?, VO?)
+}
+
+export type Disassembly<S, KI, KO, VI, VO> = Types.GraphObject & {
+	populate: (Disassembly<S, KI, KO, VI, VO>, Types.Use, output: {[KO]: VO}) -> ()
+}
+
+return nil