cluaupp 0.1.0

package/runtime/Fusion/_impl/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/_impl/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/_impl/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/_impl/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/_impl/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/_impl/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

package/runtime/Fusion/_impl/State/For/init.luau

@@ -0,0 +1,101 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	The generic implementation for all `For` objects.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+-- 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)
+-- Utility
+local nicknames = require(Package.Utility.nicknames)
+
+local Disassembly = require(Package.State.For.Disassembly)
+
+type Self<S, KI, KO, VI, VO> = Types.For<KO, VO> & {
+	_disassembly: ForTypes.Disassembly<S, KI, KO, VI, VO>
+}
+
+local class = {}
+class.type = "State"
+class.kind = "For"
+class.timeliness = "lazy"
+
+local METATABLE = table.freeze {__index = class}
+
+local function For<S, KI, KO, VI, VO>(
+	scope: Types.Scope<S>,
+	inputTable: Types.UsedAs<{[KI]: VI}>,
+	constructor: (
+		Types.Scope<S>,
+		initialKey: KI,
+		initialValue: VI
+	) -> ForTypes.SubObject<S, KI, KO, VI, VO>
+): Types.For<KO, VO>
+	local createdAt = os.clock()
+	local self: Self<S, KI, KO, VI, VO> = setmetatable(
+		{
+			createdAt = createdAt,
+			dependencySet = {},
+			dependentSet = {},
+			scope = scope,
+			validity = "invalid",
+			_EXTREMELY_DANGEROUS_usedAsValue = {},
+			_disassembly = Disassembly(
+				scope,
+				inputTable,
+				constructor
+			)
+		}, 
+		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] = "For"
+	table.insert(scope, destroy)
+
+	return self
+end
+
+function class._evaluate<S, KI, KO, VI, VO>(
+	self: Self<S, KI, KO, VI, VO>
+): boolean
+	if self.scope == nil then
+		return false
+	end
+	local outerScope = self.scope :: S & Types.Scope<unknown>
+
+	depend(self, self._disassembly)
+	table.clear(self._EXTREMELY_DANGEROUS_usedAsValue)
+	self._disassembly:populate(
+		function<T>(
+			maybeState: Types.UsedAs<T>
+		): T
+			local state = castToState(maybeState)
+			if state ~= nil then
+				depend(self, state)
+			end
+			return peek(maybeState)
+		end,
+		self._EXTREMELY_DANGEROUS_usedAsValue
+	)
+
+	return true
+end
+
+table.freeze(class)
+return For

package/runtime/Fusion/_impl/State/ForKeys.luau

@@ -0,0 +1,88 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Constructs and returns a new For state object which processes keys and
+	preserves values.
+
+	https://elttob.uk/Fusion/0.3/api-reference/state/members/forkeys/
+
+	TODO: the sub objects constructed here can be more efficiently implemented
+	as a dedicated state object.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+-- Memory
+local doCleanup = require(Package.Memory.doCleanup)
+-- State
+local For = require(Package.State.For)
+local Value = require(Package.State.Value)
+local Computed = require(Package.State.Computed)
+local ForTypes = require(Package.State.For.ForTypes)
+-- Logging
+local parseError = require(Package.Logging.parseError)
+
+local SUB_OBJECT_META = {
+	__index = {
+		roamKeys = false,
+		roamValues = true,
+		invalidateInputKey = function(self): ()
+			self._inputKeyState:set(self.inputKey)
+		end,
+		invalidateInputValue = function(self): ()
+			-- do nothing
+		end,
+		useOutputPair = function(self, use)
+			return use(self._outputKeyState), self.inputValue
+		end
+	}
+}
+
+local function SubObject<KI, KO, V, S>(
+	scope: Types.Scope<S>,
+	initialKey: KI,
+	initialValue: V,
+	processor: (Types.Use, Types.Scope<S>, KI) -> KO
+): ForTypes.SubObject<S, KI, KO, V, V>
+	local self = {}
+	self.maybeScope = scope
+	self.inputKey = initialKey
+	self.inputValue = initialValue
+	self._inputKeyState = Value(scope, initialKey)
+	self._processor = processor
+	self._outputKeyState = Computed(scope, function(use, scope): KO?
+		local inputKey = use(self._inputKeyState)
+		local ok, outputKey = xpcall(self._processor, parseError, use, scope, inputKey)
+		if ok then
+			return outputKey
+		else
+			local error: Types.Error = outputKey :: any
+			error.context = `while processing key {tostring(inputKey)}`
+			External.logErrorNonFatal("callbackError", error)
+			doCleanup(scope)
+			table.clear(scope)
+			return nil
+		end
+	end)
+	return setmetatable(self, SUB_OBJECT_META) :: any
+end
+
+local function ForKeys<KI, KO, V, S>(
+	scope: Types.Scope<S>,
+	inputTable: Types.UsedAs<{[KI]: V}>,
+	processor: (Types.Use, Types.Scope<S>, KI) -> KO
+): Types.For<KO, V>
+	return For(
+		scope, 
+		inputTable, 
+		function(scope, initialKey, initialValue)
+			return SubObject(scope, initialKey, initialValue, processor)
+		end
+	)
+end
+
+return ForKeys :: Types.ForKeysConstructor