cluaupp 0.1.0

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

package/runtime/Fusion/State/ForPairs.luau

@@ -0,0 +1,91 @@
+--!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
+	values in pairs.
+
+	https://elttob.uk/Fusion/0.3/api-reference/state/members/forpairs/
+
+	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)
+-- 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)
+-- Memory
+local doCleanup = require(Package.Memory.doCleanup)
+
+local SUB_OBJECT_META = {
+	__index = {
+		roamKeys = false,
+		roamValues = false,
+		invalidateInputKey = function(self): ()
+			self._inputKeyState:set(self.inputKey)
+		end,
+		invalidateInputValue = function(self): ()
+			self._inputValueState:set(self.inputValue)
+		end,
+		useOutputPair = function(self, use)
+			local pair = use(self._outputPairState)
+			return pair.key, pair.value
+		end
+	}
+}
+
+local function SubObject<KI, KO, VI, VO, S>(
+	scope: Types.Scope<S>,
+	initialKey: KI,
+	initialValue: VI,
+	processor: (Types.Use, Types.Scope<S>, KI, VI) -> (KO, VO)
+): ForTypes.SubObject<S, KI, KO, VI, VO>
+	local self = {}
+	self.maybeScope = scope
+	self.inputKey = initialKey
+	self.inputValue = initialValue
+	self._inputKeyState = Value(scope, initialKey)
+	self._inputValueState = Value(scope, initialValue)
+	self._processor = processor
+	self._outputPairState = Computed(scope, function(use, scope): {key: KO?, value: VO?}
+		local inputKey = use(self._inputKeyState)
+		local inputValue = use(self._inputValueState)
+		local ok, outputKey, outputValue = xpcall(self._processor, parseError, use, scope, inputKey, inputValue)
+		if ok then
+			return {key = outputKey, value = outputValue}
+		else
+			local error: Types.Error = outputKey :: any
+			error.context = `while processing key {tostring(inputKey)} and value {tostring(inputValue)}`
+			External.logErrorNonFatal("callbackError", error)
+			doCleanup(scope)
+			table.clear(scope)
+			return {key = nil, value = nil}
+		end
+	end)
+	return setmetatable(self, SUB_OBJECT_META) :: any
+end
+
+local function ForPairs<KI, KO, VI, VO, S>(
+	scope: Types.Scope<S>,
+	inputTable: Types.UsedAs<{[KI]: VI}>,
+	processor: (Types.Use, Types.Scope<S>, KI, VI) -> (KO, VO)
+): Types.For<KO, VO>
+	return For(
+		scope,
+		inputTable,
+		function(scope, initialKey, initialValue)
+			return SubObject(scope, initialKey, initialValue, processor)
+		end
+	)
+end
+
+return ForPairs :: Types.ForPairsConstructor

package/runtime/Fusion/State/ForValues.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 values and
+	preserves keys.
+
+	https://elttob.uk/Fusion/0.3/api-reference/state/members/forvalues/
+
+	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)
+-- 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)
+-- Memory
+local doCleanup = require(Package.Memory.doCleanup)
+
+local SUB_OBJECT_META = {
+	__index = {
+		roamKeys = true,
+		roamValues = false,
+		invalidateInputKey = function(self): ()
+			-- do nothing
+		end,
+		invalidateInputValue = function(self): ()
+			self._inputValueState:set(self.inputValue)
+		end,
+		useOutputPair = function(self, use)
+			return self.inputKey, use(self._outputValueState)
+		end
+	}
+}
+
+local function SubObject<K, VI, VO, S>(
+	scope: Types.Scope<S>,
+	initialKey: K,
+	initialValue: VI,
+	processor: (Types.Use, Types.Scope<S>, VI) -> VO
+): ForTypes.SubObject<S, K, K, VI, VO>
+	local self = {}
+	self.maybeScope = scope
+	self.inputKey = initialKey
+	self.inputValue = initialValue
+	self._inputValueState = Value(scope, initialValue)
+	self._processor = processor
+	self._outputValueState = Computed(scope, function(use, scope): VO?
+		local inputValue = use(self._inputValueState)
+		local ok, outputValue = xpcall(self._processor, parseError, use, scope, inputValue)
+		if ok then
+			return outputValue
+		else
+			local error: Types.Error = outputValue :: any
+			error.context = `while processing value {tostring(inputValue)}`
+			External.logErrorNonFatal("callbackError", error)
+			doCleanup(scope)
+			table.clear(scope)
+			return nil
+		end
+	end)
+	return setmetatable(self, SUB_OBJECT_META) :: any
+end
+
+local function ForValues<K, VI, VO, S>(
+	scope: Types.Scope<S>,
+	inputTable: Types.UsedAs<{[K]: VI}>,
+	processor: (Types.Use, Types.Scope<S>, VI) -> VO
+): Types.For<K, VO>
+	return For(
+		scope,
+		inputTable,
+		function(scope, initialKey, initialValue)
+			return SubObject(scope, initialKey, initialValue, processor)
+		end
+	)
+end
+
+return ForValues :: Types.ForValuesConstructor

package/runtime/Fusion/State/Value.luau

@@ -0,0 +1,76 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	A state object which allows regular Luau code to control its value.
+
+	https://elttob.uk/Fusion/0.3/api-reference/state/types/value/
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+-- Graph
+local change = require(Package.Graph.change)
+-- Utility
+local isSimilar = require(Package.Utility.isSimilar)
+local nicknames = require(Package.Utility.nicknames)
+
+type Self<T, S> = Types.Value<T, S>
+
+local class = {}
+class.type = "State"
+class.kind = "Value"
+class.timeliness = "lazy"
+class.dependencySet = table.freeze {}
+
+local METATABLE = table.freeze {__index = class}
+
+local function Value<T>(
+	scope: Types.Scope<unknown>,
+	initialValue: T
+): Types.Value<T, any>
+	local createdAt = os.clock()
+	local self: Self<T, any> = setmetatable(
+		{
+			createdAt = createdAt,
+			dependentSet = {},
+			lastChange = os.clock(),
+			scope = scope,
+			validity = "valid",
+			_EXTREMELY_DANGEROUS_usedAsValue = initialValue
+		}, 
+		METATABLE
+	) :: any
+	local destroy = function()
+		self.scope = nil
+	end
+	self.oldestTask = destroy
+	nicknames[self.oldestTask] = "Value"
+	table.insert(scope, destroy)
+	return self
+end
+
+function class.set<T, S>(
+	self: Self<T, S>,
+	newValue: S
+): S
+	local oldValue = self._EXTREMELY_DANGEROUS_usedAsValue
+	if not isSimilar(oldValue, newValue) then
+		self._EXTREMELY_DANGEROUS_usedAsValue = newValue :: any
+		change(self)
+	end
+	return newValue
+end
+
+function class._evaluate<T, S>(
+	_self: Self<T, S>
+): boolean
+	-- The similarity test is done in advance when the value is set, so this
+	-- should be fine.
+	return true
+end
+
+table.freeze(class)
+return Value :: Types.ValueConstructor

package/runtime/Fusion/State/castToState.luau

@@ -0,0 +1,26 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Returns the input *only* if it is a state object.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+
+local function castToState<T>(
+	target: Types.UsedAs<T>
+): Types.StateObject<T>?
+	if
+		typeof(target) == "table" and
+		target.type == "State" 
+	then
+		return target
+	else
+		return nil
+	end
+end
+
+return castToState

package/runtime/Fusion/State/peek.luau

@@ -0,0 +1,31 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Extracts a value of type T from its input.
+
+	https://elttob.uk/Fusion/0.3/api-reference/state/members/peek/
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+-- State
+local castToState = require(Package.State.castToState)
+-- Graph
+local evaluate = require(Package.Graph.evaluate)
+
+local function peek<T>(
+	target: Types.UsedAs<T>
+): T
+	local targetState = castToState(target)
+	if targetState ~= nil then
+		evaluate(targetState, false)
+		return targetState._EXTREMELY_DANGEROUS_usedAsValue :: T
+	else
+		return target :: T
+	end
+end
+
+return peek

package/runtime/Fusion/State/updateAll.luau

@@ -0,0 +1 @@
+return nil -- dummy file so I can write tests