cluaupp 0.1.0

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

package/runtime/Fusion/Instances/Child.luau

@@ -0,0 +1,21 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Helper function for type checking purposes. Casts the input to a `Child`
+	type, while constraining the input to be an array of `Child` - this prevents
+	Luau from erroneously inferring a different array type for the input.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+
+local function Child(
+	x: {Types.Child}
+): Types.Child
+	return x
+end
+
+return Child

package/runtime/Fusion/Instances/Children.luau

@@ -0,0 +1,148 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	A special key for property tables, which parents any given descendants into
+	an instance.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+local Observer = require(Package.Graph.Observer)
+local peek = require(Package.State.peek)
+local castToState = require(Package.State.castToState)
+local doCleanup = require(Package.Memory.doCleanup)
+
+type Set<T> = {[T]: unknown}
+
+-- Experimental flag: name children based on the key used in the [Children] table
+local EXPERIMENTAL_AUTO_NAMING = false
+
+return {
+	type = "SpecialKey",
+	kind = "Children",
+	stage = "descendants",
+	apply = function(
+		self: Types.SpecialKey,
+		scope: Types.Scope<unknown>,
+		value: unknown,
+		applyTo: Instance
+	)
+		local newParented: Set<Instance> = {}
+		local oldParented: Set<Instance> = {}
+	
+		-- save scopes for state object observers
+		local newScopes: {[Types.StateObject<unknown>]: Types.Scope<unknown>} = {}
+		local oldScopes: {[Types.StateObject<unknown>]: Types.Scope<unknown>} = {}
+	
+		-- Rescans this key's value to find new instances to parent and state objects
+		-- to observe for changes; then unparents instances no longer found and
+		-- disconnects observers for state objects no longer present.
+		local function updateChildren()
+			oldParented, newParented = newParented, oldParented
+			oldScopes, newScopes = newScopes, oldScopes
+	
+			local function processChild(
+				child: unknown,
+				autoName: string?
+			)
+				local childType = typeof(child)
+	
+				if childType == "Instance" then
+					-- case 1; single instance
+					local child = child :: Instance
+	
+					newParented[child] = true
+					if oldParented[child] == nil then
+						-- wasn't previously present
+	
+						-- TODO: check for ancestry conflicts here
+						child.Parent = applyTo
+					else
+						-- previously here; we want to reuse, so remove from old
+						-- set so we don't encounter it during unparenting
+						oldParented[child] = nil
+					end
+	
+					if EXPERIMENTAL_AUTO_NAMING and autoName ~= nil then
+						child.Name = autoName
+					end
+	
+				elseif castToState(child) then
+					-- case 2; state object
+					local child = child :: Types.StateObject<unknown>
+	
+					local value = peek(child)
+					-- allow nil to represent the absence of a child
+					if value ~= nil then
+						processChild(value, autoName)
+					end
+	
+					local childScope = oldScopes[child]
+					if childScope == nil then
+						-- wasn't previously present
+						childScope = {}
+						Observer(childScope, child):onChange(updateChildren)
+					else
+						-- previously here; we want to reuse, so remove from old
+						-- set so we don't encounter it during unparenting
+						oldScopes[child] = nil
+					end
+	
+					newScopes[child] = childScope
+	
+				elseif childType == "table" then
+					-- case 3; table of objects
+					local child = child :: {[unknown]: unknown}
+	
+					for key, subChild in pairs(child) do
+						local keyType = typeof(key)
+						local subAutoName: string? = nil
+	
+						if keyType == "string" then
+							local key = key :: string
+							subAutoName = key
+						elseif keyType == "number" and autoName ~= nil then
+							local key = key :: number
+							subAutoName = autoName .. "_" .. key
+						end
+	
+						processChild(subChild, subAutoName)
+					end
+	
+				else
+					External.logWarn("unrecognisedChildType", childType)
+				end
+			end
+	
+			if value ~= nil then
+				-- `propValue` is set to nil on cleanup, so we don't process children
+				-- in that case
+				processChild(value)
+			end
+	
+			-- unparent any children that are no longer present
+			for oldInstance in pairs(oldParented) do
+				oldInstance.Parent = nil
+			end
+			table.clear(oldParented)
+	
+			-- disconnect observers which weren't reused
+			for oldState, childScope in pairs(oldScopes) do
+				doCleanup(childScope)
+			end
+			table.clear(oldScopes)
+		end
+	
+		table.insert(scope, function()
+			value = nil
+			updateChildren()
+		end)
+	
+		-- perform initial child parenting
+		updateChildren()
+	end
+} :: Types.SpecialKey

package/runtime/Fusion/Instances/Hydrate.luau

@@ -0,0 +1,29 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Processes and returns an existing instance, with options for setting
+	properties, event handlers and other attributes on the instance.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local applyInstanceProps = require(Package.Instances.applyInstanceProps)
+
+local function Hydrate(
+	scope: Types.Scope<unknown>,
+	target: Instance
+)
+	return function(
+		props: Types.PropertyTable
+	): Instance
+	
+		table.insert(scope, target)
+		applyInstanceProps(scope, props, target)
+		return target
+	end
+end
+
+return Hydrate

package/runtime/Fusion/Instances/New.luau

@@ -0,0 +1,48 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Constructs and returns a new instance, with options for setting properties,
+	event handlers and other attributes on the instance right away.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+local defaultProps = require(Package.Instances.defaultProps)
+local applyInstanceProps = require(Package.Instances.applyInstanceProps)
+
+type Component = (Types.PropertyTable) -> Instance
+
+local function New(
+	scope: Types.Scope<unknown>,
+	className: string
+)
+	-- This might look appealing to try and cache. But please don't. The scope
+	-- upvalue is shared between the two curried function calls, so this will
+	-- open incredible cross-codebase wormholes like you've never seen before.
+	return function(
+		props: Types.PropertyTable
+	): Instance
+		local ok, instance = pcall(Instance.new, className)
+		if not ok then
+			External.logError("cannotCreateClass", nil, className)
+		end
+
+		local classDefaults = defaultProps[className]
+		if classDefaults ~= nil then
+			for defaultProp, defaultValue in pairs(classDefaults) do
+				(instance :: any)[defaultProp] = defaultValue
+			end
+		end
+
+		table.insert(scope, instance)
+		applyInstanceProps(scope, props, instance)
+
+		return instance
+	end
+end
+
+return New

package/runtime/Fusion/Instances/OnChange.luau

@@ -0,0 +1,50 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Constructs special keys for property tables which connect property change
+	listeners to an instance.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+
+local keyCache: {[string]: Types.SpecialKey} = {}
+
+local function OnChange(
+	propertyName: string
+): Types.SpecialKey
+	local key = keyCache[propertyName]
+	if key == nil then
+		key = {
+			type = "SpecialKey",
+			kind = "OnChange",
+			stage = "observer",
+			apply = function(
+				self: Types.SpecialKey,
+				scope: Types.Scope<unknown>,
+				callback: unknown,
+				applyTo: Instance
+			)
+				local ok, event = pcall(applyTo.GetPropertyChangedSignal, applyTo, propertyName)
+				if not ok then
+					External.logError("cannotConnectChange", nil, applyTo.ClassName, propertyName)
+				elseif typeof(callback) ~= "function" then
+					External.logError("invalidChangeHandler", nil, propertyName)
+				else
+					local callback = callback :: (...unknown) -> (...unknown)
+					table.insert(scope, event:Connect(function()
+						callback((applyTo :: any)[propertyName])
+					end))
+				end
+			end
+		}
+		keyCache[propertyName] = key
+	end
+	return key
+end
+
+return OnChange

package/runtime/Fusion/Instances/OnEvent.luau

@@ -0,0 +1,54 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Constructs special keys for property tables which connect event listeners to
+	an instance.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+
+local keyCache: {[string]: Types.SpecialKey} = {}
+
+local function getProperty_unsafe(
+	instance: Instance,
+	property: string
+)
+	return (instance :: any)[property]
+end
+
+local function OnEvent(
+	eventName: string
+): Types.SpecialKey
+	local key = keyCache[eventName]
+	if key == nil then
+		key = {
+			type = "SpecialKey",
+			kind = "OnEvent",
+			stage = "observer",
+			apply = function(
+				self: Types.SpecialKey,
+				scope: Types.Scope<unknown>,
+				callback: unknown,
+				applyTo: Instance
+			)
+				local ok, event = pcall(getProperty_unsafe, applyTo, eventName)
+				if not ok or typeof(event) ~= "RBXScriptSignal" then
+					External.logError("cannotConnectEvent", nil, applyTo.ClassName, eventName)
+				elseif typeof(callback) ~= "function" then
+					External.logError("invalidEventHandler", nil, eventName)
+				else
+					table.insert(scope, event:Connect(callback :: any))
+				end
+			end
+		}
+		keyCache[eventName] = key
+	end
+	return key
+end
+
+return OnEvent

package/runtime/Fusion/Instances/Out.luau

@@ -0,0 +1,69 @@
+--!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 extract values from
+	an instance into an automatically-updated Value object.
+]]
+
+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 Out(
+	propertyName: string
+): Types.SpecialKey
+	local key = keyCache[propertyName]
+	if key == nil then
+		key = {
+			type = "SpecialKey",
+			kind = "Out",
+			stage = "observer",
+			apply = function(
+				self: Types.SpecialKey,
+				scope: Types.Scope<unknown>,
+				value: unknown,
+				applyTo: Instance
+			)
+				local ok, event = pcall(applyTo.GetPropertyChangedSignal, applyTo, propertyName)
+				if not ok then
+					External.logError("invalidOutProperty", nil, applyTo.ClassName, propertyName)
+				end
+	
+				if not castToState(value) then
+					External.logError("invalidOutType")
+				end
+				local value = value :: Types.StateObject<unknown>
+				if value.kind ~= "Value" then
+					External.logError("invalidOutType")
+				end
+				local value = value :: Types.Value<unknown>
+				checkLifetime.bOutlivesA(
+					scope, applyTo, 
+					value.scope, value.oldestTask,
+					checkLifetime.formatters.propertyOutputsTo, propertyName
+				)
+
+				value:set((applyTo :: any)[propertyName])
+				table.insert(
+					scope,
+					event:Connect(function()
+						value:set((applyTo :: any)[propertyName])
+					end)
+				)
+			end
+		}
+		keyCache[propertyName] = key
+	end
+	return key
+end
+
+return Out

package/runtime/Fusion/Instances/Tag.luau

@@ -0,0 +1,61 @@
+--!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
+	CollectionService tags 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 } = {}
+
+-- TODO: should this accept tagName: UsedAs<string>?
+local function Tag(tagName: string): Types.SpecialKey
+	local key = keyCache[tagName]
+	if key == nil then
+		key = {
+			type = "SpecialKey",
+			kind = "Tag",
+			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.boundTag,
+						tagName
+					)
+					Observer(scope, value :: any):onBind(function()
+						if peek(value) == true then
+							applyTo:AddTag(tagName)
+						elseif applyTo:HasTag(tagName) then
+							applyTo:RemoveTag(tagName)
+						end
+					end)
+				else
+					if value == true then
+						applyTo:AddTag(tagName)
+					end
+				end
+			end,
+		}
+		keyCache[tagName] = key
+	end
+	return key
+end
+
+return Tag