cluaupp 0.1.0

package/runtime/FormatNumber/init.lua

@@ -0,0 +1,20 @@
+local FormatNumber = { }
+
+FormatNumber.Version = require(script.Version)
+
+FormatNumber.Main = require(script.Main)
+FormatNumber.Simple = require(script.Simple)
+
+function FormatNumber.Abbreviate(value: number, digits: number?): string
+	return FormatNumber.Simple.FormatCompact(value)
+end
+
+function FormatNumber.Comma(value: number): string
+	return FormatNumber.Simple.Format(value, "group-on")
+end
+
+function FormatNumber.Compact(value: number): string
+	return FormatNumber.Simple.FormatCompact(value)
+end
+
+return FormatNumber

package/runtime/FormatNumber/init.luau

@@ -0,0 +1,20 @@
+--!strict
+-- Cluaupp FormatNumber — typed border. Compact/Abbreviate are number -> string.
+
+--[=[
+	@class FormatNumber
+	Abbreviate, Comma, and Compact number formatters.
+]=]
+
+local Impl = require(script._impl)
+
+export type FormatNumber = {
+	Abbreviate: (value: number, digits: number?) -> string,
+	Comma: (value: number) -> string,
+	Compact: (value: number) -> string,
+	Main: typeof(Impl.Main),
+	Simple: typeof(Impl.Simple),
+	Version: typeof(Impl.Version),
+}
+
+return Impl :: FormatNumber

package/runtime/Fusion/Animation/ExternalTime.luau

@@ -0,0 +1,84 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	Outputs the current external time as a state object.
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+-- Graph
+local change = require(Package.Graph.change)
+-- Utility
+local nicknames = require(Package.Utility.nicknames)
+
+type ExternalTime = Types.StateObject<number>
+
+type Self = ExternalTime
+
+local class = {}
+class.type = "State"
+class.kind = "ExternalTime"
+class.timeliness = "lazy"
+class.dependencySet = table.freeze {}
+class._EXTREMELY_DANGEROUS_usedAsValue = External.lastUpdateStep()
+
+local METATABLE = table.freeze {__index = class}
+
+local allTimers: {Self} = {}
+
+local function ExternalTime(
+	scope: Types.Scope<unknown>
+): ExternalTime
+	local createdAt = os.clock()
+	local self: Self = setmetatable(
+		{
+			createdAt = createdAt,
+			dependentSet = {},
+			lastChange = nil,
+			scope = scope,
+			validity = "invalid"
+		}, 
+		METATABLE
+	) :: any
+	local destroy = function()
+		self.scope = nil
+		local index = table.find(allTimers, self)
+		if index ~= nil then
+			table.remove(allTimers, index)
+		end
+	end
+	self.oldestTask = destroy
+	nicknames[self.oldestTask] = "ExternalTime"
+	table.insert(scope, destroy)
+	table.insert(allTimers, self)
+	return self
+end
+
+function class._evaluate(
+	self: Self
+): boolean
+	-- While someone else could call `change()` on this object, it wouldn't be
+	-- idiomatic. So, since the only idiomatic time this function runs is when
+	-- the external update step runs, it's safe enough to assume that the result
+	-- has always meaningfully changed. The worst that can happen is unexpected
+	-- refreshing for people doing unorthodox shenanigans, which is an OK trade.
+	return true
+end
+
+External.bindToUpdateStep(function(
+	externalNow: number
+): ()
+	class._EXTREMELY_DANGEROUS_usedAsValue = External.lastUpdateStep()
+	for _, timer in allTimers do
+		change(timer)
+	end
+end)
+
+-- Do *not* freeze the class table, because it stores the shared value of all
+-- external time objects, and is updated every frame because of that.
+-- table.freeze(class)
+return ExternalTime

package/runtime/Fusion/Animation/Spring.luau

@@ -0,0 +1,313 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	A specialised state object for following a goal state smoothly over time,
+	using physics to shape the motion.
+
+	https://elttob.uk/Fusion/0.3/api-reference/animation/types/spring/
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+local External = require(Package.External)
+-- Memory
+local checkLifetime = require(Package.Memory.checkLifetime)
+-- Graph
+local depend = require(Package.Graph.depend)
+local change = require(Package.Graph.change)
+local evaluate = require(Package.Graph.evaluate)
+-- State
+local castToState = require(Package.State.castToState)
+local peek = require(Package.State.peek)
+-- Animation
+local ExternalTime = require(Package.Animation.ExternalTime)
+local Stopwatch = require(Package.Animation.Stopwatch)
+local packType = require(Package.Animation.packType)
+local unpackType = require(Package.Animation.unpackType)
+local springCoefficients = require(Package.Animation.springCoefficients)
+-- Utility
+local nicknames = require(Package.Utility.nicknames)
+
+local EPSILON = 0.00001
+
+type Self<T> = Types.Spring<T> & {
+	_activeDamping: number,
+	_activeGoal: T,
+	_activeLatestP: {number},
+	_activeLatestV: {number},
+	_activeNumSprings: number,
+	_activeSpeed: number,
+	_activeStartP: {number},
+	_activeStartV: {number},
+	_activeTargetP: {number},
+	_activeType: string,
+	_speed: Types.UsedAs<number>,
+	_damping: Types.UsedAs<number>,
+	_goal: Types.UsedAs<T>,
+	_stopwatch: Stopwatch.Stopwatch
+}
+
+local class = {}
+class.type = "State"
+class.kind = "Spring"
+class.timeliness = "eager"
+
+local METATABLE = table.freeze {__index = class}
+
+local function Spring<T>(
+	scope: Types.Scope<unknown>,
+	goal: Types.UsedAs<T>,
+	speed: Types.UsedAs<number>?,
+	damping: Types.UsedAs<number>?
+): Types.Spring<T>
+	local createdAt = os.clock()
+
+	local goalState = castToState(goal)
+	local stopwatch = nil
+	if goalState ~= nil then
+		stopwatch = Stopwatch(scope, ExternalTime(scope))
+		stopwatch:unpause()
+	end
+
+	local speed = speed or 10
+	local damping = damping or 1
+
+	local self: Self<T> = setmetatable(
+		{
+			createdAt = createdAt,
+			dependencySet = {},
+			dependentSet = {},
+			lastChange = nil,
+			scope = scope,
+			validity = "invalid",
+			_activeDamping = -1,
+			_activeGoal = nil,
+			_activeLatestP = {},
+			_activeLatestV = {},
+			_activeNumSprings = 0,
+			_activeSpeed = -1,
+			_activeStartP = {},
+			_activeStartV = {},
+			_activeTargetP = {},
+			_activeType = "",
+			_damping = damping,
+			_EXTREMELY_DANGEROUS_usedAsValue = peek(goal),
+			_goal = goal,
+			_speed = speed,
+			_stopwatch = stopwatch
+		},
+		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] = "Spring"
+	table.insert(scope, destroy)
+	
+	if goalState ~= nil then
+		checkLifetime.bOutlivesA(
+			scope, self.oldestTask,
+			goalState.scope, goalState.oldestTask,
+			checkLifetime.formatters.animationGoal
+		)
+	end
+	local speedState = castToState(speed)
+	if speedState ~= nil then
+		checkLifetime.bOutlivesA(
+			scope, self.oldestTask,
+			speedState.scope, speedState.oldestTask,
+			checkLifetime.formatters.parameter, "speed"
+		)
+	end
+	local dampingState = castToState(damping)
+	if dampingState ~= nil then
+		checkLifetime.bOutlivesA(
+			scope, self.oldestTask,
+			dampingState.scope, dampingState.oldestTask,
+			checkLifetime.formatters.parameter, "damping"
+		)
+	end
+
+	-- Eagerly evaluated objects need to evaluate themselves so that they're
+	-- valid at all times.
+	evaluate(self, true)
+
+	return self
+end
+
+function class.addVelocity<T>(
+	self: Self<T>,
+	deltaValue: T
+): ()
+	evaluate(self, false) -- ensure the _active params are up to date
+	local deltaType = typeof(deltaValue)
+	if deltaType ~= self._activeType then
+		External.logError("springTypeMismatch", nil, deltaType, self._activeType)
+	end
+	local newStartV = unpackType(deltaValue, deltaType)
+	for index, velocity in self._activeLatestV do
+		newStartV[index] += velocity
+	end
+	self._activeStartP = table.clone(self._activeLatestP)
+	self._activeStartV = newStartV
+	self._stopwatch:zero()
+	self._stopwatch:unpause()
+	change(self)
+end
+
+function class.setPosition<T>(
+	self: Self<T>,
+	newValue: T
+): ()
+	evaluate(self, false) -- ensure the _active params are up to date
+	local newType = typeof(newValue)
+	if newType ~= self._activeType then
+		External.logError("springTypeMismatch", nil, newType, self._activeType)
+	end
+	self._activeStartP = unpackType(newValue, newType)
+	self._activeStartV = table.clone(self._activeLatestV)
+	self._stopwatch:zero()
+	self._stopwatch:unpause()
+	change(self)
+end
+
+function class.setVelocity<T>(
+	self: Self<T>,
+	newValue: T
+): ()
+	evaluate(self, false) -- ensure the _active params are up to date
+	local newType = typeof(newValue)
+	if newType ~= self._activeType then
+		External.logError("springTypeMismatch", nil, newType, self._activeType)
+	end
+	self._activeStartP = table.clone(self._activeLatestP)
+	self._activeStartV = unpackType(newValue, newType)
+	self._stopwatch:zero()
+	self._stopwatch:unpause()
+	change(self)
+end
+
+function class._evaluate<T>(
+	self: Self<T>
+): boolean
+	local goal = castToState(self._goal)
+	-- Allow non-state goals to pass through transparently.
+	if goal == nil then
+		self._EXTREMELY_DANGEROUS_usedAsValue = self._goal :: T
+		return false
+	end
+	-- depend(self, goal)
+	local nextFrameGoal = peek(goal)
+	-- Protect against NaN goals.
+	if nextFrameGoal ~= nextFrameGoal then
+		External.logWarn("springNanGoal")
+		return false
+	end
+	local nextFrameGoalType = typeof(nextFrameGoal)
+	local discontinuous = nextFrameGoalType ~= self._activeType
+
+	local stopwatch = self._stopwatch :: Stopwatch.Stopwatch
+	local elapsed = peek(stopwatch)
+	depend(self, stopwatch)
+
+	local oldValue = self._EXTREMELY_DANGEROUS_usedAsValue
+	local newValue: T
+
+	if discontinuous then
+		-- Propagate changes in type instantly throughout the whole reactive
+		-- graph, even if simulation is logically one frame behind, because it
+		-- makes the whole graph behave more consistently.
+		newValue = nextFrameGoal
+	elseif elapsed <= 0 then
+		newValue = oldValue
+	else
+		-- Calculate spring motion.
+		-- IMPORTANT: use the parameters from last frame, not this frame. We're
+		-- integrating the motion that happened over the last frame, after all.
+		-- The stopwatch will have captured the length of time needed correctly.
+		local posPos, posVel, velPos, velVel = springCoefficients(
+			elapsed, 
+			self._activeDamping, 
+			self._activeSpeed
+		)
+		local isMoving = false
+		for index = 1, self._activeNumSprings do
+			local startP = self._activeStartP[index]
+			local targetP = self._activeTargetP[index]
+			local startV = self._activeStartV[index]
+			local startD = startP - targetP
+			local latestD = startD * posPos + startV * posVel
+			local latestV = startD * velPos + startV * velVel
+			if latestD ~= latestD or latestV ~= latestV then
+				External.logWarn("springNanMotion")
+				latestD, latestV = 0, 0
+			end
+			if math.abs(latestD) > EPSILON or math.abs(latestV) > EPSILON then
+				isMoving = true
+			end
+			local latestP = latestD + targetP
+			self._activeLatestP[index] = latestP
+			self._activeLatestV[index] = latestV
+		end
+		-- Sleep and snap to goal if the motion has decayed to a negligible amount.
+		if not isMoving then
+			for index = 1, self._activeNumSprings do
+				self._activeLatestP[index] = self._activeTargetP[index]
+			end
+			-- TODO: figure out how to do sleeping correctly for single frame
+			-- changes
+			-- stopwatch:pause()
+			-- stopwatch:zero()
+		end
+		-- Pack springs into final value.
+		newValue = packType(self._activeLatestP, self._activeType) :: any
+	end
+
+	-- Reconfigure spring when any of its parameters are changed.
+	-- This should happen after integrating the last frame's motion.
+	-- NOTE: don't need to add a dependency on these objects! they do not cause
+	-- a spring to wake from sleep, so the stopwatch dependency is sufficient.
+	local nextFrameSpeed = peek(self._speed) :: number
+	local nextFrameDamping = peek(self._damping) :: number
+	if
+		discontinuous or
+		nextFrameGoal ~= self._activeGoal or
+		nextFrameSpeed ~= self._activeSpeed or
+		nextFrameDamping ~= self._activeDamping
+	then
+		self._activeTargetP = unpackType(nextFrameGoal, nextFrameGoalType)
+		self._activeNumSprings = #self._activeTargetP
+		if discontinuous then
+			self._activeStartP = table.clone(self._activeTargetP)
+			self._activeLatestP = table.clone(self._activeTargetP)
+			self._activeStartV = table.create(self._activeNumSprings, 0)
+			self._activeLatestV = table.create(self._activeNumSprings, 0)
+		else
+			self._activeStartP = table.clone(self._activeLatestP)
+			self._activeStartV = table.clone(self._activeLatestV)
+		end
+		self._activeType = nextFrameGoalType
+		self._activeGoal = nextFrameGoal
+		self._activeDamping = nextFrameDamping
+		self._activeSpeed = nextFrameSpeed
+		stopwatch:zero()
+		stopwatch:unpause()
+	end
+
+	-- Push update and check for similarity.
+	-- Don't need to use the similarity test here because this code doesn't
+	-- deal with tables, and NaN is already guarded against, so the similarity
+	-- test doesn't actually add any new safety here.
+	self._EXTREMELY_DANGEROUS_usedAsValue = newValue
+	return oldValue ~= newValue
+end
+
+table.freeze(class)
+return Spring :: Types.SpringConstructor

package/runtime/Fusion/Animation/Stopwatch.luau

@@ -0,0 +1,128 @@
+--!strict
+--!nolint LocalUnused
+--!nolint LocalShadow
+local task = nil -- Disable usage of Roblox's task scheduler
+
+--[[
+	State object for measuring time since an event using a reference timer.
+
+	TODO: this should not be exposed to users until it has a proper reactive API
+	surface
+]]
+
+local Package = script.Parent.Parent
+local Types = require(Package.Types)
+-- Memory
+local checkLifetime = require(Package.Memory.checkLifetime)
+-- Graph
+local depend = require(Package.Graph.depend)
+local change = require(Package.Graph.change)
+-- State
+local peek = require(Package.State.peek)
+-- Utility
+local nicknames = require(Package.Utility.nicknames)
+
+export type Stopwatch = Types.StateObject<number> & {
+	zero: (Stopwatch) -> (),
+	pause: (Stopwatch) -> (),
+	unpause: (Stopwatch) -> ()
+}
+
+type Self = Stopwatch & {
+	_measureTimeSince: number,
+	_playing: boolean,
+	_timer: Types.StateObject<number>
+}
+
+local class = {}
+class.type = "State"
+class.kind = "Stopwatch"
+class.timeliness = "lazy"
+
+local METATABLE = table.freeze {__index = class}
+
+local function Stopwatch(
+	scope: Types.Scope<unknown>,
+	timer: Types.StateObject<number>
+): Stopwatch
+	local createdAt = os.clock()
+	local self: Self = setmetatable(
+		{
+			awake = true,
+			createdAt = createdAt,
+			dependencySet = {},
+			dependentSet = {},
+			lastChange = nil,
+			scope = scope,
+			validity = "invalid",
+			_EXTREMELY_DANGEROUS_usedAsValue = 0,
+			_measureTimeSince = 0, -- this should be set on unpause
+			_playing = false,
+			_timer = timer
+		}, 
+		METATABLE
+	) :: any
+	local destroy = function()
+		self.scope = nil
+	end
+	self.oldestTask = destroy
+	nicknames[self.oldestTask] = "Stopwatch"
+	table.insert(scope, destroy)
+
+	checkLifetime.bOutlivesA(
+		scope, self.oldestTask,
+		timer.scope, timer.oldestTask,
+		checkLifetime.formatters.parameter, "timer"
+	)
+	depend(self, timer)
+	return self
+end
+
+function class.zero(
+	self: Self
+): ()
+	local newTimepoint = peek(self._timer)
+	if newTimepoint ~= self._measureTimeSince then
+		self._measureTimeSince = newTimepoint
+		self._EXTREMELY_DANGEROUS_usedAsValue = 0
+		change(self)
+	end
+end
+
+function class.pause(
+	self: Self
+): ()
+	if self._playing == true then
+		self._playing = false
+		change(self)
+	end
+end
+
+function class.unpause(
+	self: Self
+): ()
+	if self._playing == false then
+		self._playing = true
+		self._measureTimeSince = peek(self._timer) - self._EXTREMELY_DANGEROUS_usedAsValue
+		change(self)
+	end
+end
+
+function class._evaluate(
+	self: Self
+): boolean
+	if self._playing then
+		depend(self, self._timer)
+		local currentTime = peek(self._timer)
+		local oldValue = self._EXTREMELY_DANGEROUS_usedAsValue
+		local newValue = currentTime - self._measureTimeSince
+		self._EXTREMELY_DANGEROUS_usedAsValue = newValue
+		return oldValue ~= newValue
+	else
+		return false
+	end
+	
+end
+
+table.freeze(class)
+return Stopwatch