cluaupp 1.3.0 → 1.4.0

package/examples/game/libs/Fusion/Types.luau

@@ -1,318 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	Stores common public-facing type information for Fusion APIs.
-]]
-
-export type Error = {
-	type: "Error",
-	raw: string,
-	message: string,
-	trace: string,
-	context: string?
-}
-
--- Types that can be expressed as vectors of numbers, and so can be animated.
-export type Animatable =
-	number |
-	CFrame |
-	Color3 |
-	ColorSequenceKeypoint |
-	DateTime |
-	NumberRange |
-	NumberSequenceKeypoint |
-	PhysicalProperties |
-	Ray |
-	Rect |
-	Region3 |
-	Region3int16 |
-	UDim |
-	UDim2 |
-	Vector2 |
-	Vector2int16 |
-	Vector3 |
-	Vector3int16
-
--- A task which can be accepted for cleanup.
-export type Task =
-	Instance |
-	RBXScriptConnection |
-	() -> () |
-	{destroy: (unknown) -> ()} |
-	{Destroy: (unknown) -> ()} |
-	{disconnect: (unknown) -> ()} |
-	{Disconnect: (unknown) -> ()} |
-	{Task}
-
--- A scope of tasks to clean up.
-export type Scope<Constructors = any> = {Task} & Constructors
-
--- An object which uses a scope to dictate how long it lives.
-export type ScopedObject = {
-	scope: Scope<unknown>?,
-	oldestTask: unknown
-}
-
--- Script-readable version information.
-export type Version = {
-	major: number,
-	minor: number,
-	isRelease: boolean
-}
-
--- An object which stores a value scoped in time.
-export type Contextual<T> = {
-	type: "Contextual",
-	now: (Contextual<T>) -> T,
-	is: (Contextual<T>, T) -> ContextualIsMethods
-}
-
-type ContextualIsMethods = {
-	during: <R, A...>(ContextualIsMethods, (A...) -> R, A...) -> R
-}
-
--- A graph object which can have dependencies and dependencies.
-export type GraphObject = ScopedObject & {
-	createdAt: number,
-	dependencySet: {[GraphObject]: unknown},
-	dependentSet: {[GraphObject]: unknown},
-	lastChange: number?,
-	timeliness: "lazy" | "eager",
-	validity: "valid" | "invalid" | "busy",
-	_evaluate: (GraphObject) -> boolean
-}
-
--- An object which stores a piece of reactive state.
-export type StateObject<T> = GraphObject & {
-	type: "State",
-	kind: string,
-	_EXTREMELY_DANGEROUS_usedAsValue: T
-}
-
--- Passing values of this type to `Use` returns `T`.
-export type UsedAs<T> = StateObject<T> | T
-
--- Function signature for use callbacks.
-export type Use = <T>(target: UsedAs<T>) -> T
-
--- A state object whose value can be set at any time by the user.
-export type Value<T, S = T> = StateObject<T> & {
-	kind: "State",
-	timeliness: "lazy",
- 	set: (Value<T, S>, newValue: S, force: boolean?) -> S,
-	____phantom_setType: (never) -> S -- phantom data so this contains S
-}
-export type ValueConstructor = <T>(
-	scope: Scope<unknown>,
-	initialValue: T
-) -> Value<T, any>
-
--- A state object whose value is derived from other objects using a callback.
-export type Computed<T> = StateObject<T> & {
-	kind: "Computed",
-	timeliness: "lazy"
-}
-export type ComputedConstructor = <T, S>(
-	scope: S & Scope<unknown>,
-	callback: (Use, S) -> T
-) -> Computed<T>
-
--- A state object which maps over keys and/or values in another table.
-export type For<KO, VO> = StateObject<{[KO]: VO}>  & {
-	kind: "For"
-}
-export type ForPairsConstructor =  <KI, KO, VI, VO, S>(
-	scope: S & Scope<unknown>,
-	inputTable: UsedAs<{[KI]: VI}>,
-	processor: (Use, S, key: KI, value: VI) -> (KO, VO)
-) -> For<KO, VO>
-export type ForKeysConstructor =  <KI, KO, V, S>(
-	scope: S & Scope<unknown>,
-	inputTable: UsedAs<{[KI]: V}>,
-	processor: (Use, S, key: KI) -> KO
-) -> For<KO, V>
-export type ForValuesConstructor =  <K, VI, VO, S>(
-	scope: S & Scope<unknown>,
-	inputTable: UsedAs<{[K]: VI}>,
-	processor: (Use, S, value: VI) -> VO
-) -> For<K, VO>
-
--- An object which can listen for updates on another state object.
-export type Observer = GraphObject & {
-	type: "Observer",
-	timeliness: "eager",
-	onChange: (Observer, callback: () -> ()) -> (() -> ()),
-	onBind: (Observer, callback: () -> ()) -> (() -> ())
-}
-export type ObserverConstructor = (
-	scope: Scope<unknown>,
-	watching: unknown
-) -> Observer
-
--- A state object which follows another state object using tweens.
-export type Tween<T> = StateObject<T> & {
-	kind: "Tween"
-}
-export type TweenConstructor = <T>(
-	scope: Scope<unknown>,
-	goalState: UsedAs<T>,
-	tweenInfo: UsedAs<TweenInfo>?
-) -> Tween<T>
-
--- A state object which follows another state object using spring simulation.
-export type Spring<T> = StateObject<T>  & {
-	kind: "Spring",
-	setPosition: (Spring<T>, newPosition: T) -> (),
-	setVelocity: (Spring<T>, newVelocity: T) -> (),
-	addVelocity: (Spring<T>, deltaVelocity: T) -> ()
-}
-export type SpringConstructor = <T>(
-	scope: Scope<unknown>,
-	goalState: UsedAs<T>,
-	speed: UsedAs<number>?,
-	damping: UsedAs<number>?
-) -> Spring<T>
-
--- Denotes children instances in an instance or component's property table.
-export type SpecialKey = {
-	type: "SpecialKey",
-	kind: string,
-	stage: "self" | "descendants" | "ancestor" | "observer",
-	apply: (
-		self: SpecialKey,
-		scope: Scope<unknown>,
-		value: unknown,
-		applyTo: Instance
-	) -> ()
-}
-
--- A collection of instances that may be parented to another instance.
-export type Child = Instance | StateObject<Child> | {[unknown]: Child}
-
--- A table that defines an instance's properties, handlers and children.
-export type PropertyTable = {[string | SpecialKey]: unknown}
-
-export type NewConstructor = (
-	scope: Scope<unknown>,
-	className: string
-) -> (propertyTable: PropertyTable) -> Instance
-
-export type HydrateConstructor = (
-	scope: Scope<unknown>,
-	target: Instance
-) -> (propertyTable: PropertyTable) -> Instance
-
--- Is there a sane way to write out this type?
--- ... I sure hope so.
-
-export type DeriveScopeConstructor = (<S>(Scope<S>) -> Scope<S>)
-	& (<S, A>(Scope<S>, A & {}) -> Scope<S & A>)
-	& (<S, A, B>(Scope<S>, A & {}, B & {}) -> Scope<S & A & B>)
-	& (<S, A, B, C>(Scope<S>, A & {}, B & {}, C & {}) -> Scope<S & A & B & C>)
-	& (<S, A, B, C, D>(Scope<S>, A & {}, B & {}, C & {}, D & {}) -> Scope<S & A & B & C & D>)
-	& (<S, A, B, C, D, E>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}) -> Scope<S & A & B & C & D & E>)
-	& (<S, A, B, C, D, E, F>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}, F & {}) -> Scope<S & A & B & C & D & E & F>)
-	& (<S, A, B, C, D, E, F, G>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}) -> Scope<S & A & B & C & D & E & F & G>)
-	& (<S, A, B, C, D, E, F, G, H>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}) -> Scope<S & A & B & C & D & E & F & G & H>)
-	& (<S, A, B, C, D, E, F, G, H, I>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}) -> Scope<S & A & B & C & D & E & F & G & H & I>)
-	& (<S, A, B, C, D, E, F, G, H, I, J>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}, J & {}) -> Scope<S & A & B & C & D & E & F & G & H & I & J>)
-	& (<S, A, B, C, D, E, F, G, H, I, J, K>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}, J & {}, K & {}) -> Scope<S & A & B & C & D & E & F & G & H & I & J & K>)
-	& (<S, A, B, C, D, E, F, G, H, I, J, K, L>(Scope<S>, A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}, J & {}, K & {}, L & {}) -> Scope<S & A & B & C & D & E & F & G & H & I & J & K & L>)
-
-export type ScopedConstructor = (() -> Scope<{}>)
-	& (<A>(A & {}) -> Scope<A>)
-	& (<A, B>(A & {}, B & {}) -> Scope<A & B>)
-	& (<A, B, C>(A & {}, B & {}, C & {}) -> Scope<A & B & C>)
-	& (<A, B, C, D>(A & {}, B & {}, C & {}, D & {}) -> Scope<A & B & C & D>)
-	& (<A, B, C, D, E>(A & {}, B & {}, C & {}, D & {}, E & {}) -> Scope<A & B & C & D & E>)
-	& (<A, B, C, D, E, F>(A & {}, B & {}, C & {}, D & {}, E & {}, F & {}) -> Scope<A & B & C & D & E & F>)
-	& (<A, B, C, D, E, F, G>(A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}) -> Scope<A & B & C & D & E & F & G>)
-	& (<A, B, C, D, E, F, G, H>(A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}) -> Scope<A & B & C & D & E & F & G & H>)
-	& (<A, B, C, D, E, F, G, H, I>(A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}) -> Scope<A & B & C & D & E & F & G & H & I>)
-	& (<A, B, C, D, E, F, G, H, I, J>(A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}, J & {}) -> Scope<A & B & C & D & E & F & G & H & I & J>)
-	& (<A, B, C, D, E, F, G, H, I, J, K>(A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}, J & {}, K & {}) -> Scope<A & B & C & D & E & F & G & H & I & J & K>)
-	& (<A, B, C, D, E, F, G, H, I, J, K, L>(A & {}, B & {}, C & {}, D & {}, E & {}, F & {}, G & {}, H & {}, I & {}, J & {}, K & {}, L & {}) -> Scope<A & B & C & D & E & F & G & H & I & J & K & L>)
-
-export type ContextualConstructor = <T>(defaultValue: T) -> Contextual<T>
-
-export type Safe = <Success, Fail>(
-	callbacks: {
-		try: () -> Success,
-		fallback: (err: unknown) -> Fail
-	}
-) -> Success | Fail
-
-export type Fusion = {
-	version: Version,
-	Contextual: ContextualConstructor,
-	Safe: Safe,
-
-	doCleanup: (Task) -> (),
-	scoped: ScopedConstructor,
-	deriveScope: DeriveScopeConstructor,
-	innerScope: DeriveScopeConstructor,
-	insert: <Tasks...>(scope: Scope<unknown>, Tasks...) -> Tasks...,
-
-	peek: Use,
-	Value: ValueConstructor,
-	Computed: ComputedConstructor,
-	ForPairs: ForPairsConstructor,
-	ForKeys: ForKeysConstructor,
-	ForValues: ForValuesConstructor,
-	Observer: ObserverConstructor,
-
-	Tween: TweenConstructor,
-	Spring: SpringConstructor,
-
-	New: NewConstructor,
-	Hydrate: HydrateConstructor,
-
-	Child: ({Child}) -> Child,
-	Children: SpecialKey,
-	Out: (propertyName: string) -> SpecialKey,
-	OnEvent: (eventName: string) -> SpecialKey,
-	OnChange: (propertyName: string) -> SpecialKey,
-	Attribute: (attributeName: string) -> SpecialKey,
-	AttributeChange: (attributeName: string) -> SpecialKey,
-	AttributeOut: (attributeName: string) -> SpecialKey,
-	Tag: (tagName: string) -> SpecialKey,
-}
-
-export type ExternalProvider = {
-	policies: {
-		allowWebLinks: boolean
-	},
-
-	logErrorNonFatal: (
-		errorString: string
-	) -> (),
-	logWarn: (
-		errorString: string
-	) -> (),
-
-	doTaskImmediate: (
-		resume: () -> ()
-	) -> (),
-	doTaskDeferred: (
-		resume: () -> ()
-	) -> (),
-	startScheduler: () -> (),
-	stopScheduler: () -> ()
-}
-
-export type ExternalDebugger = {
-	startDebugging: () -> (),
-	stopDebugging: () -> (),
-
-	trackScope: (
-		scope: Scope<unknown>
-	) -> (),
-	untrackScope: (
-		scope: Scope<unknown>
-	) -> ()
-}
-
-return nil

package/examples/game/libs/Fusion/Utility/Contextual.luau

@@ -1,91 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-    Time-based contextual values, to allow for transparently passing values down
-	the call stack.
-]]
-
-local Package = script.Parent.Parent
-local Types = require(Package.Types)
-local External = require(Package.External)
--- Logging
-local parseError = require(Package.Logging.parseError)
-
-export type Self<T> = Types.Contextual<T> & {
-	_valuesNow: {[thread]: {value: T}},
-	_defaultValue: T
-}
-
-local class = {}
-class.type = "Contextual"
-
-local METATABLE = table.freeze {__index = class}
-local WEAK_KEYS_METATABLE = table.freeze {__mode = "k"}
-
-local function Contextual<T>(
-	defaultValue: T
-): Types.Contextual<T>
-	local self: Self<T> = setmetatable(
-		{
-			-- if we held strong references to threads here, then if a thread was
-			-- killed before this contextual had a chance to finish executing its
-			-- callback, it would be held strongly in this table forever
-			_valuesNow = setmetatable({}, WEAK_KEYS_METATABLE),
-			_defaultValue = defaultValue
-		}, 
-		METATABLE
-	) :: any
-
-	return self
-end
-
---[[
-	Returns the current value of this contextual.
-]]
-function class.now<T>(
-	self: Self<T>
-): T
-	local thread = coroutine.running()
-	local value = self._valuesNow[thread]
-	if typeof(value) ~= "table" then
-		return self._defaultValue
-	else
-		return value.value
-	end
-end
-
---[[
-	Temporarily assigns a value to this contextual.
-]]
-function class.is<T>(
-	self: Self<T>,
-	newValue: T
-)
-	local methods = {}
-	
-	function methods.during<T, A...>(
-		_: any, -- during is called with colon syntax but we don't care
-		callback: (A...) -> T,
-		...: A...
-	): T
-		local thread = coroutine.running()
-		local prevValue = self._valuesNow[thread]
-		-- Storing the value in this format allows us to distinguish storing
-		-- `nil` from not calling `:during()` at all.
-		self._valuesNow[thread] = { value = newValue }
-		local ok, value = xpcall(callback, parseError, ...)
-		self._valuesNow[thread] = prevValue
-		if not ok then
-			External.logError("callbackError", value :: any)
-		end
-		return value
-	end
-
-	return methods
-end
-
-table.freeze(class)
-return Contextual

package/examples/game/libs/Fusion/Utility/Safe.luau

@@ -1,23 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-    A variant of xpcall() designed for inline usage, letting you define fallback
-	values based on caught errors.
-]]
-
-local Package = script.Parent.Parent
-
-local function Safe<Success, Fail>(
-	callbacks: {
-		try: () -> Success,
-		fallback: (err: unknown) -> Fail
-	}
-): Success | Fail
-	local _, value = xpcall(callbacks.try, callbacks.fallback)
-	return value
-end
-
-return Safe

package/examples/game/libs/Fusion/Utility/isSimilar.luau

@@ -1,29 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	Implements the 'similarity test' used to determine whether two values have
-	a meaningful difference.
-
-	https://elttob.uk/Fusion/0.3/tutorials/best-practices/optimisation/#similarity
-]]
-
-local function isSimilar(
-	a: unknown, 
-	b: unknown
-): boolean
-	local typeA = typeof(a)
-	local isTable = typeA == "table"
-	local isUserdata = typeA == "userdata"
-	return
-		if not (isTable or isUserdata) then
-			a == b or a ~= a and b ~= b
-		elseif typeA == typeof(b) and (isUserdata or table.isfrozen(a :: any) or getmetatable(a :: any) ~= nil) then
-			a == b
-		else
-			false
-end
-
-return isSimilar

package/examples/game/libs/Fusion/Utility/merge.luau

@@ -1,35 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	Attempts to merge a variadic number of tables together.
-]]
-
-local Package = script.Parent.Parent
-local External = require(Package.External)
-
-local function merge(
-	overwrite: boolean,
-	into: {[unknown]: unknown},
-	...: {[unknown]: unknown}
-): {[unknown]: unknown}
-	local fromTables = {...}
-	if #fromTables < 1 then
-		return into
-	else
-		for _, fromTable in fromTables do
-			for key, value in fromTable do
-				if overwrite or into[key] == nil then
-					into[key] = value
-				elseif not overwrite then
-					External.logError("mergeConflict", nil, tostring(key))
-				end
-			end
-		end
-		return into
-	end
-end
-
-return merge

package/examples/game/libs/Fusion/Utility/nameOf.luau

@@ -1,35 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	Returns the most specific custom name for the given object.
-]]
-
-local Package = script.Parent.Parent
--- Utility
-local nicknames = require(Package.Utility.nicknames)
-
-local function nameOf(
-	x: unknown,
-	defaultName: string
-): string
-	local nickname = nicknames[x]
-	if typeof(nickname) == "string" then
-		return nickname
-	end
-	if typeof(x) == "table" then
-		local x = x :: {[any]: any}
-		if typeof(x.name) == "string" then
-			return x.name
-		elseif typeof(x.kind) == "string" then
-			return x.kind
-		elseif typeof(x.type) == "string" then
-			return x.type
-		end
-	end
-	return defaultName
-end
-
-return nameOf

package/examples/game/libs/Fusion/Utility/never.luau

@@ -1,14 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	Never returns.
-]]
-
-local function never(): never
-	error("This codepath should not be reachable")
-end
-
-return never

package/examples/game/libs/Fusion/Utility/nicknames.luau

@@ -1,11 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	Stores nicknames for values that don't support metatables, so that `nameOf`
-	can return values for them.
-]]
-
-return setmetatable({}, {__mode = "k"})

package/examples/game/libs/Fusion/Utility/xtypeof.luau

@@ -1,27 +0,0 @@
---!strict
---!nolint LocalUnused
---!nolint LocalShadow
-local task = nil -- Disable usage of Roblox's task scheduler
-
---[[
-	Extended typeof, designed for identifying custom objects.
-	If given a table with a `type` string, returns that.
-	Otherwise, returns `typeof()` the argument.
-]]
-
-local function xtypeof(
-	x: unknown
-): string
-	local typeString = typeof(x)
-
-	if typeString == "table" then
-		local x = x :: {type: unknown?}
-		if typeof(x.type) == "string" then
-			return x.type
-		end
-	end
-
-	return typeString
-end
-
-return xtypeof

package/examples/game/libs/Fusion/_impl/Animation/ExternalTime.luau

@@ -1,84 +0,0 @@
---!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