roblox-opencode 1.0.0 → 1.0.2

package/vendor/rbxutil/trove/init.luau

@@ -1,787 +1,787 @@
---!strict
-
-local RunService = game:GetService("RunService")
-
-export type Trove = {
-	Extend: (self: Trove) -> Trove,
-	Clone: <T>(self: Trove, instance: T & Instance) -> T,
-	Construct: <T, A...>(self: Trove, class: Constructable<T, A...>, A...) -> T,
-	Connect: (
-		self: Trove,
-		signal: SignalLike | SignalLikeMetatable | RBXScriptSignal,
-		fn: (...any) -> ...any
-	) -> ConnectionLike | ConnectionLikeMetatable,
-	BindToRenderStep: (self: Trove, name: string, priority: number, fn: (dt: number) -> ()) -> (),
-	AddPromise: <T>(self: Trove, promise: (T & PromiseLike) | (T & PromiseLikeMetatable)) -> T,
-	Add: <T>(self: Trove, object: T & Trackable, cleanupMethod: string?) -> T,
-	Remove: <T>(self: Trove, object: T & Trackable) -> boolean,
-	Pop: <T>(self: Trove, object: T & Trackable) -> boolean,
-	Clean: (self: Trove) -> (),
-	WrapClean: (self: Trove) -> () -> (),
-	AttachToInstance: (self: Trove, instance: Instance) -> RBXScriptConnection,
-	Destroy: (self: Trove) -> (),
-}
-
-type TroveInternal = Trove & {
-	_objects: { any },
-	_cleaning: boolean,
-	_findAndRemoveFromObjects: (self: TroveInternal, object: any, cleanup: boolean) -> boolean,
-	_cleanupObject: (self: TroveInternal, object: any, cleanupMethod: string?) -> (),
-}
-
---[=[
-	@within Trove
-	@type Trackable Instance | RBXScriptConnection | ConnectionLike | ConnectLikeMetatable | PromiseLike | PromiseLikeMetatable | thread | ((...any) -> ...any) | Destroyable | DestroyableMetatable | DestroyableLowercase | DestroyableLowercaseMetatable | Disconnectable | DisconnectableMetatable | DisconnectableLowercase | DisconnectableLowercaseMetatable | SignalLike | SignalLikeMetatable
-	Represents all trackable objects by Trove.
-]=]
-export type Trackable =
-	| Instance
-	| RBXScriptConnection
-	| ConnectionLike
-	| ConnectionLikeMetatable
-	| PromiseLike
-	| PromiseLikeMetatable
-	| thread
-	| ((...any) -> ...any)
-	| Destroyable
-	| DestroyableMetatable
-	| DestroyableLowercase
-	| DestroyableLowercaseMetatable
-	| Disconnectable
-	| DisconectableMetatable
-	| DisconnectableLowercase
-	| DisconnectableLowercaseMetatable
-	| SignalLike
-	| SignalLikeMetatable
-
---[=[
-	@within Trove
-	@interface ConnectionLike
-	.Connected boolean
-	.Disconnect (self) -> ()
-]=]
-type ConnectionLike = {
-	Connected: boolean,
-	Disconnect: (self: ConnectionLike) -> (),
-}
-
---[=[
-	@within Trove
-	@interface ConnectionLikeMetatable
-	.Connected boolean
-	.Disconnect (self) -> ()
-	@tag Metatable
-]=]
-type ConnectionLikeMetatable = typeof(setmetatable(
-	{},
-	{} :: { Connected: boolean, Disconnect: (self: ConnectionLikeMetatable) -> () }
-))
-
---[=[
-	@within Trove
-	@interface SignalLike
-	.Connect (self, callback: (...any) -> ...any) -> ConnectionLike
-	.Once (self, callback: (...any) -> ...any) -> ConnectionLike
-]=]
-type SignalLike = {
-	Connect: (self: SignalLike, callback: (...any) -> ...any) -> ConnectionLike | ConnectionLikeMetatable,
-	Once: (self: SignalLike, callback: (...any) -> ...any) -> ConnectionLike | ConnectionLikeMetatable,
-}
-
---[=[
-	@within Trove
-	@interface SignalLikeMetatable
-	.Connect (self, callback: (...any) -> ...any) -> ConnectionLike
-	.Once (self, callback: (...any) -> ...any) -> ConnectionLike
-	@tag Metatable
-]=]
-type SignalLikeMetatable = typeof(setmetatable(
-	{},
-	{} :: {
-		Connect: (self: SignalLikeMetatable, callback: (...any) -> ...any) -> ConnectionLike | ConnectionLikeMetatable,
-		Once: (self: SignalLikeMetatable, callback: (...any) -> ...any) -> ConnectionLike | ConnectionLikeMetatable,
-	}
-))
-
---[=[
-	@within Trove
-	@interface PromiseLike
-	.getStatus (self) -> string
-	.finally (self, callback: (...any) -> ...any) -> PromiseLike
-	.cancel (self) -> ()
-]=]
-type PromiseLike = {
-	getStatus: (self: PromiseLike) -> string,
-	finally: (self: PromiseLike, callback: (...any) -> ...any) -> PromiseLike | PromiseLikeMetatable,
-	cancel: (self: PromiseLike) -> (),
-}
-
---[=[
-	@within Trove
-	@interface PromiseLikeMetatable
-	.getStatus (self) -> string
-	.finally (self, callback: (...any) -> ...any) -> PromiseLike
-	.cancel (self) -> ()
-	@tag Metatable
-]=]
-type PromiseLikeMetatable = typeof(setmetatable(
-	{},
-	{} :: {
-		getStatus: (self: any) -> string,
-		finally: (self: PromiseLikeMetatable, callback: (...any) -> ...any) -> PromiseLike | PromiseLikeMetatable,
-		cancel: (self: PromiseLikeMetatable) -> (),
-	}
-))
-
---[=[
-	@within Trove
-	@type Constructable { new: (A...) -> T } | (A...) -> T
-]=]
-type Constructable<T, A...> = { new: (A...) -> T } | (A...) -> T
-
---[=[
-	@within Trove
-	@interface Destroyable
-	.Destroy (self) -> ()
-]=]
-type Destroyable = {
-	Destroy: (self: Destroyable) -> (),
-}
-
---[=[
-	@within Trove
-	@interface DestroyableMetatable
-	.Destroy (self) -> ()
-	@tag Metatable
-]=]
-type DestroyableMetatable = typeof(setmetatable({}, {} :: { Destroy: (self: DestroyableMetatable) -> () }))
-
---[=[
-	@within Trove
-	@interface DestroyableLowercase
-	.destroy (self) -> ()
-]=]
-type DestroyableLowercase = {
-	destroy: (self: DestroyableLowercase) -> (),
-}
-
---[=[
-	@within Trove
-	@interface DestroyableLowercaseMetatable
-	.destroy (self) -> ()
-	@tag Metatable
-]=]
-type DestroyableLowercaseMetatable = typeof(setmetatable(
-	{},
-	{} :: { destroy: (self: DestroyableLowercaseMetatable) -> () }
-))
-
---[=[
-	@within Trove
-	@interface Disconnectable
-	.Disconnect (self) -> ()
-]=]
-type Disconnectable = {
-	Disconnect: (self: Disconnectable) -> (),
-}
-
---[=[
-	@within Trove
-	@interface DisconectableMetatable
-	.Disconnect (self) -> ()
-	@tag Metatable
-]=]
-type DisconectableMetatable = typeof(setmetatable({}, {} :: { Disconnect: (self: DisconectableMetatable) -> () }))
-
---[=[
-	@within Trove
-	@interface DisconnectableLowercase
-	.disconnect (self) -> ()
-]=]
-type DisconnectableLowercase = {
-	disconnect: (self: DisconnectableLowercase) -> (),
-}
-
---[=[
-	@within Trove
-	@interface DisconnectableLowercaseMetatable
-	.disconnect (self) -> ()
-	@tag Metatable
-]=]
-type DisconnectableLowercaseMetatable = typeof(setmetatable(
-	{},
-	{} :: { disconnect: (self: DisconnectableLowercaseMetatable) -> () }
-))
-
-local FN_MARKER = newproxy()
-local THREAD_MARKER = newproxy()
-local GENERIC_OBJECT_CLEANUP_METHODS = table.freeze({ "Destroy", "Disconnect", "destroy", "disconnect" })
-
-local function getObjectCleanupFunction(object: any, cleanupMethod: string?)
-	local t = typeof(object)
-
-	if t == "function" then
-		return FN_MARKER
-	elseif t == "thread" then
-		return THREAD_MARKER
-	end
-
-	if cleanupMethod then
-		return cleanupMethod
-	end
-
-	if t == "Instance" then
-		return "Destroy"
-	elseif t == "RBXScriptConnection" then
-		return "Disconnect"
-	elseif t == "table" then
-		for _, genericCleanupMethod in GENERIC_OBJECT_CLEANUP_METHODS do
-			if typeof(object[genericCleanupMethod]) == "function" then
-				return genericCleanupMethod
-			end
-		end
-	end
-
-	error(`failed to get cleanup function for object {t}: {object}`, 3)
-end
-
-local function assertPromiseLike(object: any)
-	if
-		typeof(object) ~= "table"
-		or typeof(object.getStatus) ~= "function"
-		or typeof(object.finally) ~= "function"
-		or typeof(object.cancel) ~= "function"
-	then
-		error("did not receive a promise as an argument", 3)
-	end
-end
-
-local function assertSignalLike(object: any)
-	if
-		typeof(object) ~= "RBXScriptSignal"
-		and (typeof(object) ~= "table" or typeof(object.Connect) ~= "function" or typeof(object.Once) ~= "function")
-	then
-		error("did not receive a signal as an argument", 3)
-	end
-end
-
---[=[
-	@class Trove
-	A Trove is helpful for tracking any sort of object during
-	runtime that needs to get cleaned up at some point.
-]=]
-local Trove = {}
-Trove.__index = Trove
-
---[=[
-	@return Trove
-	Constructs a Trove object.
-
-	```lua
-	local trove = Trove.new()
-	```
-]=]
-function Trove.new(): Trove
-	local self = setmetatable({}, Trove)
-
-	self._objects = {}
-	self._cleaning = false
-
-	return (self :: any) :: Trove
-end
-
---[=[
-	@method Add
-	@within Trove
-	@param object any -- Object to track
-	@param cleanupMethod string? -- Optional cleanup name override
-	@return object: any
-	Adds an object to the trove. Once the trove is cleaned or
-	destroyed, the object will also be cleaned up.
-
-	The following types are accepted (e.g. `typeof(object)`):
-
-	| Type | Cleanup |
-	| ---- | ------- |
-	| `Instance` | `object:Destroy()` |
-	| `RBXScriptConnection` | `object:Disconnect()` |
-	| `function` | `object()` |
-	| `thread` | `task.cancel(object)` |
-	| `table` | `object:Destroy()` _or_ `object:Disconnect()` _or_ `object:destroy()` _or_ `object:disconnect()` |
-	| `table` with `cleanupMethod` | `object:<cleanupMethod>()` |
-
-	Returns the object added.
-
-	```lua
-	-- Add a part to the trove, then destroy the trove,
-	-- which will also destroy the part:
-	local part = Instance.new("Part")
-	trove:Add(part)
-	trove:Destroy()
-
-	-- Add a function to the trove:
-	trove:Add(function()
-		print("Cleanup!")
-	end)
-	trove:Destroy()
-
-	-- Standard cleanup from table:
-	local tbl = {}
-	function tbl:Destroy()
-		print("Cleanup")
-	end
-	trove:Add(tbl)
-
-	-- Custom cleanup from table:
-	local tbl = {}
-	function tbl:DoSomething()
-		print("Do something on cleanup")
-	end
-	trove:Add(tbl, "DoSomething")
-	```
-]=]
-function Trove.Add(self: TroveInternal, object: Trackable, cleanupMethod: string?): any
-	if self._cleaning then
-		error("cannot call trove:Add() while cleaning", 2)
-	end
-
-	local cleanup = getObjectCleanupFunction(object, cleanupMethod)
-	table.insert(self._objects, { object, cleanup })
-
-	return object
-end
-
---[=[
-	@method Clone
-	@within Trove
-	@return Instance
-	Clones the given instance and adds it to the trove. Shorthand for
-	`trove:Add(instance:Clone())`.
-
-	```lua
-	local clonedPart = trove:Clone(somePart)
-	```
-]=]
-function Trove.Clone(self: TroveInternal, instance: Instance): Instance
-	if self._cleaning then
-		error("cannot call trove:Clone() while cleaning", 2)
-	end
-
-	return self:Add(instance:Clone())
-end
-
---[=[
-	@method Construct
-	@within Trove
-	@param class { new(Args...) -> T } | (Args...) -> T
-	@param ... Args...
-	@return T
-	Constructs a new object from either the
-	table or function given.
-
-	If a table is given, the table's `new`
-	function will be called with the given
-	arguments.
-
-	If a function is given, the function will
-	be called with the given arguments.
-
-	The result from either of the two options
-	will be added to the trove.
-
-	This is shorthand for `trove:Add(SomeClass.new(...))`
-	and `trove:Add(SomeFunction(...))`.
-
-	```lua
-	local Signal = require(somewhere.Signal)
-
-	-- All of these are identical:
-	local s = trove:Construct(Signal)
-	local s = trove:Construct(Signal.new)
-	local s = trove:Construct(function() return Signal.new() end)
-	local s = trove:Add(Signal.new())
-
-	-- Even Roblox instances can be created:
-	local part = trove:Construct(Instance, "Part")
-	```
-]=]
-function Trove.Construct<T, A...>(self: TroveInternal, class: Constructable<T, A...>, ...: A...)
-	if self._cleaning then
-		error("Cannot call trove:Construct() while cleaning", 2)
-	end
-
-	local object = nil
-	local t = type(class)
-	if t == "table" then
-		object = (class :: any).new(...)
-	elseif t == "function" then
-		object = (class :: any)(...)
-	end
-
-	return self:Add(object)
-end
-
---[=[
-	@method Connect
-	@within Trove
-	@param signal RBXScriptSignal
-	@param fn (...: any) -> ()
-	@return RBXScriptConnection
-	Connects the function to the signal, adds the connection
-	to the trove, and then returns the connection.
-
-	This is shorthand for `trove:Add(signal:Connect(fn))`.
-
-	```lua
-	trove:Connect(workspace.ChildAdded, function(instance)
-		print(instance.Name .. " added to workspace")
-	end)
-	```
-]=]
-function Trove.Connect(
-	self: TroveInternal,
-	signal: SignalLike | SignalLikeMetatable | RBXScriptSignal,
-	fn: (...any) -> ...any
-)
-	if self._cleaning then
-		error("Cannot call trove:Connect() while cleaning", 2)
-	end
-	assertSignalLike(signal)
-
-	local confirmedSignal = signal :: SignalLike
-
-	return self:Add(confirmedSignal:Connect(fn))
-end
-
---[=[
-	@method Once
-	@within Trove
-	@param signal RBXScriptSignal
-	@param fn (...: any) -> ()
-	@return RBXScriptConnection
-	Connects the function to the signal using the `Once`
-	method, adds the connection to the trove, and then
-	returns the connection.
-
-	This is shorthand for `trove:Add(signal:Once(fn))`.
-
-	```lua
-	trove:Connect(workspace.ChildAdded, function(instance)
-		print(instance.Name .. " added to workspace")
-	end)
-	```
-]=]
-function Trove.Once(
-	self: TroveInternal,
-	signal: SignalLike | SignalLikeMetatable | RBXScriptSignal,
-	fn: (...any) -> ...any
-)
-	if self._cleaning then
-		error("Cannot call trove:Connect() while cleaning", 2)
-	end
-	assertSignalLike(signal)
-
-	local confirmedSignal = signal :: SignalLike
-
-	local conn
-	conn = confirmedSignal:Once(function(...)
-		fn(...)
-		self:Pop(conn)
-	end)
-
-	return self:Add(conn)
-end
-
---[=[
-	@method BindToRenderStep
-	@within Trove
-	@param name string
-	@param priority number
-	@param fn (dt: number) -> ()
-	Calls `RunService:BindToRenderStep` and registers a function in the
-	trove that will call `RunService:UnbindFromRenderStep` on cleanup.
-
-	```lua
-	trove:BindToRenderStep("Test", Enum.RenderPriority.Last.Value, function(dt)
-		-- Do something
-	end)
-	```
-]=]
-function Trove.BindToRenderStep(self: TroveInternal, name: string, priority: number, fn: (dt: number) -> ())
-	if self._cleaning then
-		error("cannot call trove:BindToRenderStep() while cleaning", 2)
-	end
-
-	RunService:BindToRenderStep(name, priority, fn)
-
-	self:Add(function()
-		RunService:UnbindFromRenderStep(name)
-	end)
-end
-
---[=[
-	@method AddPromise
-	@within Trove
-	@param promise Promise
-	@return Promise
-	Gives the promise to the trove, which will cancel the promise if the trove is cleaned up or if the promise
-	is removed. The exact promise is returned, thus allowing chaining.
-
-	```lua
-	trove:AddPromise(doSomethingThatReturnsAPromise())
-		:andThen(function()
-			print("Done")
-		end)
-	-- Will cancel the above promise (assuming it didn't resolve immediately)
-	trove:Clean()
-
-	local p = trove:AddPromise(doSomethingThatReturnsAPromise())
-	-- Will also cancel the promise
-	trove:Remove(p)
-	```
-
-	:::caution Promise v4 Only
-	This is only compatible with the [roblox-lua-promise](https://eryn.io/roblox-lua-promise/) library, version 4.
-	:::
-]=]
-function Trove.AddPromise(self: TroveInternal, promise: PromiseLike | PromiseLikeMetatable)
-	if self._cleaning then
-		error("cannot call trove:AddPromise() while cleaning", 2)
-	end
-	assertPromiseLike(promise)
-	local confirmedPromise = promise :: PromiseLike
-
-	if confirmedPromise:getStatus() == "Started" then
-		confirmedPromise:finally(function()
-			if self._cleaning then
-				return
-			end
-			self:_findAndRemoveFromObjects(confirmedPromise, false)
-		end)
-
-		self:Add(confirmedPromise, "cancel")
-	end
-
-	return confirmedPromise
-end
-
---[=[
-	@method Remove
-	@within Trove
-	@param object any
-	Removes the object from the Trove and cleans it up. To remove without
-	cleaning, use the `Pop` method instead.
-
-	```lua
-	local part = Instance.new("Part")
-	trove:Add(part)
-	trove:Remove(part) -- Part is destroyed
-	```
-]=]
-function Trove.Remove(self: TroveInternal, object: Trackable): boolean
-	if self._cleaning then
-		error("cannot call trove:Remove() while cleaning", 2)
-	end
-
-	return self:_findAndRemoveFromObjects(object, true)
-end
-
---[=[
-	@method Pop
-	@within Trove
-	@param object any
-	Removes the object from the Trove, but does _not_ clean it up. To
-	clean up the object on removal, use the `Remove` method instead.
-
-	```lua
-	local part = Instance.new("Part")
-	trove:Add(part)
-	trove:Pop(part)
-	trove:Clean() -- Part is NOT destroyed
-	```
-]=]
-function Trove.Pop(self: TroveInternal, object: Trackable): boolean
-	if self._cleaning then
-		error("cannot call trove:Pop() while cleaning", 2)
-	end
-
-	return self:_findAndRemoveFromObjects(object, false)
-end
-
---[=[
-	@method Extend
-	@within Trove
-	@return Trove
-	Creates and adds another trove to itself. This is just shorthand
-	for `trove:Construct(Trove)`. This is useful for contexts where
-	the trove object is present, but the class itself isn't.
-
-	:::note
-	This does _not_ clone the trove. In other words, the objects in the
-	trove are not given to the new constructed trove. This is simply to
-	construct a new Trove and add it as an object to track.
-	:::
-
-	```lua
-	local trove = Trove.new()
-	local subTrove = trove:Extend()
-
-	trove:Clean() -- Cleans up the subTrove too
-	```
-]=]
-function Trove.Extend(self: TroveInternal)
-	if self._cleaning then
-		error("cannot call trove:Extend() while cleaning", 2)
-	end
-
-	return self:Construct(Trove)
-end
-
---[=[
-	@method Clean
-	@within Trove
-	Cleans up all objects in the trove. This is
-	similar to calling `Remove` on each object
-	within the trove. The ordering of the objects
-	removed is _not_ guaranteed.
-
-	```lua
-	trove:Clean()
-	```
-]=]
-function Trove.Clean(self: TroveInternal)
-	if self._cleaning then
-		return
-	end
-
-	self._cleaning = true
-
-	for _, obj in self._objects do
-		self:_cleanupObject(obj[1], obj[2])
-	end
-
-	table.clear(self._objects)
-	self._cleaning = false
-end
-
---[=[
-	@method WrapClean
-	@within Trove
-	Returns a function that wraps the trove's `Clean()`
-	method. Calling the returned function will clean up
-	the trove.
-
-	This is often useful in contexts where functions
-	are the primary mode for cleaning up an environment,
-	such as in many "observer" patterns.
-
-	```lua
-	local cleanup = trove:WrapClean()
-
-	-- Sometime later...
-	cleanup()
-	```
-
-	```lua
-	-- Common observer pattern example:
-	someObserver(function()
-		local trove = Trove.new()
-		-- Foo
-		return trove:WrapClean()
-	end)
-	```
-]=]
-function Trove.WrapClean(self: TroveInternal)
-	return function()
-		self:Clean()
-	end
-end
-
-function Trove._findAndRemoveFromObjects(self: TroveInternal, object: any, cleanup: boolean): boolean
-	local objects = self._objects
-
-	for i, obj in objects do
-		if obj[1] == object then
-			local n = #objects
-			objects[i] = objects[n]
-			objects[n] = nil
-
-			if cleanup then
-				self:_cleanupObject(obj[1], obj[2])
-			end
-
-			return true
-		end
-	end
-
-	return false
-end
-
-function Trove._cleanupObject(_self: TroveInternal, object: any, cleanupMethod: string?)
-	if cleanupMethod == FN_MARKER then
-		task.spawn(object)
-	elseif cleanupMethod == THREAD_MARKER then
-		pcall(task.cancel, object)
-	else
-		object[cleanupMethod](object)
-	end
-end
-
---[=[
-	@method AttachToInstance
-	@within Trove
-	@param instance Instance
-	@return RBXScriptConnection
-	Attaches the trove to a Roblox instance. Once this
-	instance is removed from the game (parent or ancestor's
-	parent set to `nil`), the trove will automatically
-	clean up.
-
-	This inverses the ownership of the Trove object, and should
-	only be used when necessary. In other words, the attached
-	instance dictates when the trove is cleaned up, rather than
-	the trove dictating the cleanup of the instance.
-
-	:::caution
-	Will throw an error if `instance` is not a descendant
-	of the game hierarchy.
-	:::
-
-	```lua
-	trove:AttachToInstance(somePart)
-	trove:Add(function()
-		print("Cleaned")
-	end)
-
-	-- Destroying the part will cause the trove to clean up, thus "Cleaned" printed:
-	somePart:Destroy()
-	```
-]=]
-function Trove.AttachToInstance(self: TroveInternal, instance: Instance)
-	if self._cleaning then
-		error("cannot call trove:AttachToInstance() while cleaning", 2)
-	elseif not instance:IsDescendantOf(game) then
-		error("instance is not a descendant of the game hierarchy", 2)
-	end
-
-	return self:Connect(instance.Destroying, function()
-		self:Destroy()
-	end)
-end
-
---[=[
-	@method Destroy
-	@within Trove
-	Alias for `trove:Clean()`.
-
-	```lua
-	trove:Destroy()
-	```
-]=]
-function Trove.Destroy(self: TroveInternal)
-	self:Clean()
-end
-
-return {
-	new = Trove.new,
-}
+--!strict
+
+local RunService = game:GetService("RunService")
+
+export type Trove = {
+	Extend: (self: Trove) -> Trove,
+	Clone: <T>(self: Trove, instance: T & Instance) -> T,
+	Construct: <T, A...>(self: Trove, class: Constructable<T, A...>, A...) -> T,
+	Connect: (
+		self: Trove,
+		signal: SignalLike | SignalLikeMetatable | RBXScriptSignal,
+		fn: (...any) -> ...any
+	) -> ConnectionLike | ConnectionLikeMetatable,
+	BindToRenderStep: (self: Trove, name: string, priority: number, fn: (dt: number) -> ()) -> (),
+	AddPromise: <T>(self: Trove, promise: (T & PromiseLike) | (T & PromiseLikeMetatable)) -> T,
+	Add: <T>(self: Trove, object: T & Trackable, cleanupMethod: string?) -> T,
+	Remove: <T>(self: Trove, object: T & Trackable) -> boolean,
+	Pop: <T>(self: Trove, object: T & Trackable) -> boolean,
+	Clean: (self: Trove) -> (),
+	WrapClean: (self: Trove) -> () -> (),
+	AttachToInstance: (self: Trove, instance: Instance) -> RBXScriptConnection,
+	Destroy: (self: Trove) -> (),
+}
+
+type TroveInternal = Trove & {
+	_objects: { any },
+	_cleaning: boolean,
+	_findAndRemoveFromObjects: (self: TroveInternal, object: any, cleanup: boolean) -> boolean,
+	_cleanupObject: (self: TroveInternal, object: any, cleanupMethod: string?) -> (),
+}
+
+--[=[
+	@within Trove
+	@type Trackable Instance | RBXScriptConnection | ConnectionLike | ConnectLikeMetatable | PromiseLike | PromiseLikeMetatable | thread | ((...any) -> ...any) | Destroyable | DestroyableMetatable | DestroyableLowercase | DestroyableLowercaseMetatable | Disconnectable | DisconnectableMetatable | DisconnectableLowercase | DisconnectableLowercaseMetatable | SignalLike | SignalLikeMetatable
+	Represents all trackable objects by Trove.
+]=]
+export type Trackable =
+	| Instance
+	| RBXScriptConnection
+	| ConnectionLike
+	| ConnectionLikeMetatable
+	| PromiseLike
+	| PromiseLikeMetatable
+	| thread
+	| ((...any) -> ...any)
+	| Destroyable
+	| DestroyableMetatable
+	| DestroyableLowercase
+	| DestroyableLowercaseMetatable
+	| Disconnectable
+	| DisconectableMetatable
+	| DisconnectableLowercase
+	| DisconnectableLowercaseMetatable
+	| SignalLike
+	| SignalLikeMetatable
+
+--[=[
+	@within Trove
+	@interface ConnectionLike
+	.Connected boolean
+	.Disconnect (self) -> ()
+]=]
+type ConnectionLike = {
+	Connected: boolean,
+	Disconnect: (self: ConnectionLike) -> (),
+}
+
+--[=[
+	@within Trove
+	@interface ConnectionLikeMetatable
+	.Connected boolean
+	.Disconnect (self) -> ()
+	@tag Metatable
+]=]
+type ConnectionLikeMetatable = typeof(setmetatable(
+	{},
+	{} :: { Connected: boolean, Disconnect: (self: ConnectionLikeMetatable) -> () }
+))
+
+--[=[
+	@within Trove
+	@interface SignalLike
+	.Connect (self, callback: (...any) -> ...any) -> ConnectionLike
+	.Once (self, callback: (...any) -> ...any) -> ConnectionLike
+]=]
+type SignalLike = {
+	Connect: (self: SignalLike, callback: (...any) -> ...any) -> ConnectionLike | ConnectionLikeMetatable,
+	Once: (self: SignalLike, callback: (...any) -> ...any) -> ConnectionLike | ConnectionLikeMetatable,
+}
+
+--[=[
+	@within Trove
+	@interface SignalLikeMetatable
+	.Connect (self, callback: (...any) -> ...any) -> ConnectionLike
+	.Once (self, callback: (...any) -> ...any) -> ConnectionLike
+	@tag Metatable
+]=]
+type SignalLikeMetatable = typeof(setmetatable(
+	{},
+	{} :: {
+		Connect: (self: SignalLikeMetatable, callback: (...any) -> ...any) -> ConnectionLike | ConnectionLikeMetatable,
+		Once: (self: SignalLikeMetatable, callback: (...any) -> ...any) -> ConnectionLike | ConnectionLikeMetatable,
+	}
+))
+
+--[=[
+	@within Trove
+	@interface PromiseLike
+	.getStatus (self) -> string
+	.finally (self, callback: (...any) -> ...any) -> PromiseLike
+	.cancel (self) -> ()
+]=]
+type PromiseLike = {
+	getStatus: (self: PromiseLike) -> string,
+	finally: (self: PromiseLike, callback: (...any) -> ...any) -> PromiseLike | PromiseLikeMetatable,
+	cancel: (self: PromiseLike) -> (),
+}
+
+--[=[
+	@within Trove
+	@interface PromiseLikeMetatable
+	.getStatus (self) -> string
+	.finally (self, callback: (...any) -> ...any) -> PromiseLike
+	.cancel (self) -> ()
+	@tag Metatable
+]=]
+type PromiseLikeMetatable = typeof(setmetatable(
+	{},
+	{} :: {
+		getStatus: (self: any) -> string,
+		finally: (self: PromiseLikeMetatable, callback: (...any) -> ...any) -> PromiseLike | PromiseLikeMetatable,
+		cancel: (self: PromiseLikeMetatable) -> (),
+	}
+))
+
+--[=[
+	@within Trove
+	@type Constructable { new: (A...) -> T } | (A...) -> T
+]=]
+type Constructable<T, A...> = { new: (A...) -> T } | (A...) -> T
+
+--[=[
+	@within Trove
+	@interface Destroyable
+	.Destroy (self) -> ()
+]=]
+type Destroyable = {
+	Destroy: (self: Destroyable) -> (),
+}
+
+--[=[
+	@within Trove
+	@interface DestroyableMetatable
+	.Destroy (self) -> ()
+	@tag Metatable
+]=]
+type DestroyableMetatable = typeof(setmetatable({}, {} :: { Destroy: (self: DestroyableMetatable) -> () }))
+
+--[=[
+	@within Trove
+	@interface DestroyableLowercase
+	.destroy (self) -> ()
+]=]
+type DestroyableLowercase = {
+	destroy: (self: DestroyableLowercase) -> (),
+}
+
+--[=[
+	@within Trove
+	@interface DestroyableLowercaseMetatable
+	.destroy (self) -> ()
+	@tag Metatable
+]=]
+type DestroyableLowercaseMetatable = typeof(setmetatable(
+	{},
+	{} :: { destroy: (self: DestroyableLowercaseMetatable) -> () }
+))
+
+--[=[
+	@within Trove
+	@interface Disconnectable
+	.Disconnect (self) -> ()
+]=]
+type Disconnectable = {
+	Disconnect: (self: Disconnectable) -> (),
+}
+
+--[=[
+	@within Trove
+	@interface DisconectableMetatable
+	.Disconnect (self) -> ()
+	@tag Metatable
+]=]
+type DisconectableMetatable = typeof(setmetatable({}, {} :: { Disconnect: (self: DisconectableMetatable) -> () }))
+
+--[=[
+	@within Trove
+	@interface DisconnectableLowercase
+	.disconnect (self) -> ()
+]=]
+type DisconnectableLowercase = {
+	disconnect: (self: DisconnectableLowercase) -> (),
+}
+
+--[=[
+	@within Trove
+	@interface DisconnectableLowercaseMetatable
+	.disconnect (self) -> ()
+	@tag Metatable
+]=]
+type DisconnectableLowercaseMetatable = typeof(setmetatable(
+	{},
+	{} :: { disconnect: (self: DisconnectableLowercaseMetatable) -> () }
+))
+
+local FN_MARKER = newproxy()
+local THREAD_MARKER = newproxy()
+local GENERIC_OBJECT_CLEANUP_METHODS = table.freeze({ "Destroy", "Disconnect", "destroy", "disconnect" })
+
+local function getObjectCleanupFunction(object: any, cleanupMethod: string?)
+	local t = typeof(object)
+
+	if t == "function" then
+		return FN_MARKER
+	elseif t == "thread" then
+		return THREAD_MARKER
+	end
+
+	if cleanupMethod then
+		return cleanupMethod
+	end
+
+	if t == "Instance" then
+		return "Destroy"
+	elseif t == "RBXScriptConnection" then
+		return "Disconnect"
+	elseif t == "table" then
+		for _, genericCleanupMethod in GENERIC_OBJECT_CLEANUP_METHODS do
+			if typeof(object[genericCleanupMethod]) == "function" then
+				return genericCleanupMethod
+			end
+		end
+	end
+
+	error(`failed to get cleanup function for object {t}: {object}`, 3)
+end
+
+local function assertPromiseLike(object: any)
+	if
+		typeof(object) ~= "table"
+		or typeof(object.getStatus) ~= "function"
+		or typeof(object.finally) ~= "function"
+		or typeof(object.cancel) ~= "function"
+	then
+		error("did not receive a promise as an argument", 3)
+	end
+end
+
+local function assertSignalLike(object: any)
+	if
+		typeof(object) ~= "RBXScriptSignal"
+		and (typeof(object) ~= "table" or typeof(object.Connect) ~= "function" or typeof(object.Once) ~= "function")
+	then
+		error("did not receive a signal as an argument", 3)
+	end
+end
+
+--[=[
+	@class Trove
+	A Trove is helpful for tracking any sort of object during
+	runtime that needs to get cleaned up at some point.
+]=]
+local Trove = {}
+Trove.__index = Trove
+
+--[=[
+	@return Trove
+	Constructs a Trove object.
+
+	```lua
+	local trove = Trove.new()
+	```
+]=]
+function Trove.new(): Trove
+	local self = setmetatable({}, Trove)
+
+	self._objects = {}
+	self._cleaning = false
+
+	return (self :: any) :: Trove
+end
+
+--[=[
+	@method Add
+	@within Trove
+	@param object any -- Object to track
+	@param cleanupMethod string? -- Optional cleanup name override
+	@return object: any
+	Adds an object to the trove. Once the trove is cleaned or
+	destroyed, the object will also be cleaned up.
+
+	The following types are accepted (e.g. `typeof(object)`):
+
+	| Type | Cleanup |
+	| ---- | ------- |
+	| `Instance` | `object:Destroy()` |
+	| `RBXScriptConnection` | `object:Disconnect()` |
+	| `function` | `object()` |
+	| `thread` | `task.cancel(object)` |
+	| `table` | `object:Destroy()` _or_ `object:Disconnect()` _or_ `object:destroy()` _or_ `object:disconnect()` |
+	| `table` with `cleanupMethod` | `object:<cleanupMethod>()` |
+
+	Returns the object added.
+
+	```lua
+	-- Add a part to the trove, then destroy the trove,
+	-- which will also destroy the part:
+	local part = Instance.new("Part")
+	trove:Add(part)
+	trove:Destroy()
+
+	-- Add a function to the trove:
+	trove:Add(function()
+		print("Cleanup!")
+	end)
+	trove:Destroy()
+
+	-- Standard cleanup from table:
+	local tbl = {}
+	function tbl:Destroy()
+		print("Cleanup")
+	end
+	trove:Add(tbl)
+
+	-- Custom cleanup from table:
+	local tbl = {}
+	function tbl:DoSomething()
+		print("Do something on cleanup")
+	end
+	trove:Add(tbl, "DoSomething")
+	```
+]=]
+function Trove.Add(self: TroveInternal, object: Trackable, cleanupMethod: string?): any
+	if self._cleaning then
+		error("cannot call trove:Add() while cleaning", 2)
+	end
+
+	local cleanup = getObjectCleanupFunction(object, cleanupMethod)
+	table.insert(self._objects, { object, cleanup })
+
+	return object
+end
+
+--[=[
+	@method Clone
+	@within Trove
+	@return Instance
+	Clones the given instance and adds it to the trove. Shorthand for
+	`trove:Add(instance:Clone())`.
+
+	```lua
+	local clonedPart = trove:Clone(somePart)
+	```
+]=]
+function Trove.Clone(self: TroveInternal, instance: Instance): Instance
+	if self._cleaning then
+		error("cannot call trove:Clone() while cleaning", 2)
+	end
+
+	return self:Add(instance:Clone())
+end
+
+--[=[
+	@method Construct
+	@within Trove
+	@param class { new(Args...) -> T } | (Args...) -> T
+	@param ... Args...
+	@return T
+	Constructs a new object from either the
+	table or function given.
+
+	If a table is given, the table's `new`
+	function will be called with the given
+	arguments.
+
+	If a function is given, the function will
+	be called with the given arguments.
+
+	The result from either of the two options
+	will be added to the trove.
+
+	This is shorthand for `trove:Add(SomeClass.new(...))`
+	and `trove:Add(SomeFunction(...))`.
+
+	```lua
+	local Signal = require(somewhere.Signal)
+
+	-- All of these are identical:
+	local s = trove:Construct(Signal)
+	local s = trove:Construct(Signal.new)
+	local s = trove:Construct(function() return Signal.new() end)
+	local s = trove:Add(Signal.new())
+
+	-- Even Roblox instances can be created:
+	local part = trove:Construct(Instance, "Part")
+	```
+]=]
+function Trove.Construct<T, A...>(self: TroveInternal, class: Constructable<T, A...>, ...: A...)
+	if self._cleaning then
+		error("Cannot call trove:Construct() while cleaning", 2)
+	end
+
+	local object = nil
+	local t = type(class)
+	if t == "table" then
+		object = (class :: any).new(...)
+	elseif t == "function" then
+		object = (class :: any)(...)
+	end
+
+	return self:Add(object)
+end
+
+--[=[
+	@method Connect
+	@within Trove
+	@param signal RBXScriptSignal
+	@param fn (...: any) -> ()
+	@return RBXScriptConnection
+	Connects the function to the signal, adds the connection
+	to the trove, and then returns the connection.
+
+	This is shorthand for `trove:Add(signal:Connect(fn))`.
+
+	```lua
+	trove:Connect(workspace.ChildAdded, function(instance)
+		print(instance.Name .. " added to workspace")
+	end)
+	```
+]=]
+function Trove.Connect(
+	self: TroveInternal,
+	signal: SignalLike | SignalLikeMetatable | RBXScriptSignal,
+	fn: (...any) -> ...any
+)
+	if self._cleaning then
+		error("Cannot call trove:Connect() while cleaning", 2)
+	end
+	assertSignalLike(signal)
+
+	local confirmedSignal = signal :: SignalLike
+
+	return self:Add(confirmedSignal:Connect(fn))
+end
+
+--[=[
+	@method Once
+	@within Trove
+	@param signal RBXScriptSignal
+	@param fn (...: any) -> ()
+	@return RBXScriptConnection
+	Connects the function to the signal using the `Once`
+	method, adds the connection to the trove, and then
+	returns the connection.
+
+	This is shorthand for `trove:Add(signal:Once(fn))`.
+
+	```lua
+	trove:Connect(workspace.ChildAdded, function(instance)
+		print(instance.Name .. " added to workspace")
+	end)
+	```
+]=]
+function Trove.Once(
+	self: TroveInternal,
+	signal: SignalLike | SignalLikeMetatable | RBXScriptSignal,
+	fn: (...any) -> ...any
+)
+	if self._cleaning then
+		error("Cannot call trove:Connect() while cleaning", 2)
+	end
+	assertSignalLike(signal)
+
+	local confirmedSignal = signal :: SignalLike
+
+	local conn
+	conn = confirmedSignal:Once(function(...)
+		fn(...)
+		self:Pop(conn)
+	end)
+
+	return self:Add(conn)
+end
+
+--[=[
+	@method BindToRenderStep
+	@within Trove
+	@param name string
+	@param priority number
+	@param fn (dt: number) -> ()
+	Calls `RunService:BindToRenderStep` and registers a function in the
+	trove that will call `RunService:UnbindFromRenderStep` on cleanup.
+
+	```lua
+	trove:BindToRenderStep("Test", Enum.RenderPriority.Last.Value, function(dt)
+		-- Do something
+	end)
+	```
+]=]
+function Trove.BindToRenderStep(self: TroveInternal, name: string, priority: number, fn: (dt: number) -> ())
+	if self._cleaning then
+		error("cannot call trove:BindToRenderStep() while cleaning", 2)
+	end
+
+	RunService:BindToRenderStep(name, priority, fn)
+
+	self:Add(function()
+		RunService:UnbindFromRenderStep(name)
+	end)
+end
+
+--[=[
+	@method AddPromise
+	@within Trove
+	@param promise Promise
+	@return Promise
+	Gives the promise to the trove, which will cancel the promise if the trove is cleaned up or if the promise
+	is removed. The exact promise is returned, thus allowing chaining.
+
+	```lua
+	trove:AddPromise(doSomethingThatReturnsAPromise())
+		:andThen(function()
+			print("Done")
+		end)
+	-- Will cancel the above promise (assuming it didn't resolve immediately)
+	trove:Clean()
+
+	local p = trove:AddPromise(doSomethingThatReturnsAPromise())
+	-- Will also cancel the promise
+	trove:Remove(p)
+	```
+
+	:::caution Promise v4 Only
+	This is only compatible with the [roblox-lua-promise](https://eryn.io/roblox-lua-promise/) library, version 4.
+	:::
+]=]
+function Trove.AddPromise(self: TroveInternal, promise: PromiseLike | PromiseLikeMetatable)
+	if self._cleaning then
+		error("cannot call trove:AddPromise() while cleaning", 2)
+	end
+	assertPromiseLike(promise)
+	local confirmedPromise = promise :: PromiseLike
+
+	if confirmedPromise:getStatus() == "Started" then
+		confirmedPromise:finally(function()
+			if self._cleaning then
+				return
+			end
+			self:_findAndRemoveFromObjects(confirmedPromise, false)
+		end)
+
+		self:Add(confirmedPromise, "cancel")
+	end
+
+	return confirmedPromise
+end
+
+--[=[
+	@method Remove
+	@within Trove
+	@param object any
+	Removes the object from the Trove and cleans it up. To remove without
+	cleaning, use the `Pop` method instead.
+
+	```lua
+	local part = Instance.new("Part")
+	trove:Add(part)
+	trove:Remove(part) -- Part is destroyed
+	```
+]=]
+function Trove.Remove(self: TroveInternal, object: Trackable): boolean
+	if self._cleaning then
+		error("cannot call trove:Remove() while cleaning", 2)
+	end
+
+	return self:_findAndRemoveFromObjects(object, true)
+end
+
+--[=[
+	@method Pop
+	@within Trove
+	@param object any
+	Removes the object from the Trove, but does _not_ clean it up. To
+	clean up the object on removal, use the `Remove` method instead.
+
+	```lua
+	local part = Instance.new("Part")
+	trove:Add(part)
+	trove:Pop(part)
+	trove:Clean() -- Part is NOT destroyed
+	```
+]=]
+function Trove.Pop(self: TroveInternal, object: Trackable): boolean
+	if self._cleaning then
+		error("cannot call trove:Pop() while cleaning", 2)
+	end
+
+	return self:_findAndRemoveFromObjects(object, false)
+end
+
+--[=[
+	@method Extend
+	@within Trove
+	@return Trove
+	Creates and adds another trove to itself. This is just shorthand
+	for `trove:Construct(Trove)`. This is useful for contexts where
+	the trove object is present, but the class itself isn't.
+
+	:::note
+	This does _not_ clone the trove. In other words, the objects in the
+	trove are not given to the new constructed trove. This is simply to
+	construct a new Trove and add it as an object to track.
+	:::
+
+	```lua
+	local trove = Trove.new()
+	local subTrove = trove:Extend()
+
+	trove:Clean() -- Cleans up the subTrove too
+	```
+]=]
+function Trove.Extend(self: TroveInternal)
+	if self._cleaning then
+		error("cannot call trove:Extend() while cleaning", 2)
+	end
+
+	return self:Construct(Trove)
+end
+
+--[=[
+	@method Clean
+	@within Trove
+	Cleans up all objects in the trove. This is
+	similar to calling `Remove` on each object
+	within the trove. The ordering of the objects
+	removed is _not_ guaranteed.
+
+	```lua
+	trove:Clean()
+	```
+]=]
+function Trove.Clean(self: TroveInternal)
+	if self._cleaning then
+		return
+	end
+
+	self._cleaning = true
+
+	for _, obj in self._objects do
+		self:_cleanupObject(obj[1], obj[2])
+	end
+
+	table.clear(self._objects)
+	self._cleaning = false
+end
+
+--[=[
+	@method WrapClean
+	@within Trove
+	Returns a function that wraps the trove's `Clean()`
+	method. Calling the returned function will clean up
+	the trove.
+
+	This is often useful in contexts where functions
+	are the primary mode for cleaning up an environment,
+	such as in many "observer" patterns.
+
+	```lua
+	local cleanup = trove:WrapClean()
+
+	-- Sometime later...
+	cleanup()
+	```
+
+	```lua
+	-- Common observer pattern example:
+	someObserver(function()
+		local trove = Trove.new()
+		-- Foo
+		return trove:WrapClean()
+	end)
+	```
+]=]
+function Trove.WrapClean(self: TroveInternal)
+	return function()
+		self:Clean()
+	end
+end
+
+function Trove._findAndRemoveFromObjects(self: TroveInternal, object: any, cleanup: boolean): boolean
+	local objects = self._objects
+
+	for i, obj in objects do
+		if obj[1] == object then
+			local n = #objects
+			objects[i] = objects[n]
+			objects[n] = nil
+
+			if cleanup then
+				self:_cleanupObject(obj[1], obj[2])
+			end
+
+			return true
+		end
+	end
+
+	return false
+end
+
+function Trove._cleanupObject(_self: TroveInternal, object: any, cleanupMethod: string?)
+	if cleanupMethod == FN_MARKER then
+		task.spawn(object)
+	elseif cleanupMethod == THREAD_MARKER then
+		pcall(task.cancel, object)
+	else
+		object[cleanupMethod](object)
+	end
+end
+
+--[=[
+	@method AttachToInstance
+	@within Trove
+	@param instance Instance
+	@return RBXScriptConnection
+	Attaches the trove to a Roblox instance. Once this
+	instance is removed from the game (parent or ancestor's
+	parent set to `nil`), the trove will automatically
+	clean up.
+
+	This inverses the ownership of the Trove object, and should
+	only be used when necessary. In other words, the attached
+	instance dictates when the trove is cleaned up, rather than
+	the trove dictating the cleanup of the instance.
+
+	:::caution
+	Will throw an error if `instance` is not a descendant
+	of the game hierarchy.
+	:::
+
+	```lua
+	trove:AttachToInstance(somePart)
+	trove:Add(function()
+		print("Cleaned")
+	end)
+
+	-- Destroying the part will cause the trove to clean up, thus "Cleaned" printed:
+	somePart:Destroy()
+	```
+]=]
+function Trove.AttachToInstance(self: TroveInternal, instance: Instance)
+	if self._cleaning then
+		error("cannot call trove:AttachToInstance() while cleaning", 2)
+	elseif not instance:IsDescendantOf(game) then
+		error("instance is not a descendant of the game hierarchy", 2)
+	end
+
+	return self:Connect(instance.Destroying, function()
+		self:Destroy()
+	end)
+end
+
+--[=[
+	@method Destroy
+	@within Trove
+	Alias for `trove:Clean()`.
+
+	```lua
+	trove:Destroy()
+	```
+]=]
+function Trove.Destroy(self: TroveInternal)
+	self:Clean()
+end
+
+return {
+	new = Trove.new,
+}