@rbxts/trove

Trove

A Maid-like pattern for tracking and cleaning up objects.

API

Constructor

const trove = new Trove();

Trove.Trackable

The following type describes the objects that Trove can track.

type Trackable =
	| Instance
	| ConnectionLike
	| Promise<unknown>
	| thread
	| ((...args: unknown[]) => unknown)
	| { destroy: () => void }
	| { disconnect: () => void }
	| { Destroy: () => void }
	| { Disconnect: () => void };

Trove.add

add<T extends Trove.Trackable>(
	obj: T,
	cleanupMethod?: string,
): T

Add an item into the trove to be tracked.

Trove.clean / Trove.destroy

clean(): void
destroy(): void // alias to clean

Cleans up the trove. All tracked objects will be cleaned up and removed from the trove.

Trove.remove

remove<T extends Trove.Trackable>(
	obj: T,
): boolean

Removes and cleans up the given object from the trove. Will return true if the object was found and cleaned up.

Trove.connect

connect<T extends Callback = Callback>(
	signal: SignalLike<T>,
	fn: (...args: Parameters<T>) => void,
): ReturnType<typeof signal.Connect>

Connects to a signal. Shorthand for trove.add(signal.Connect(fn)). Returns the connection.

Trove.addPromise

addPromise<T>(promise: Promise<T>): Promise<T>

Adds the given promise to the trove. If the trove is cleaned up, the promise's cancel() method will be called. The returned promise is the same one passed to the function.

Trove.bindToRenderStep

bindToRenderStep(
	name: string,
	priority: number,
	renderFn: (dt: number) => void,
): void

Binds the renderFn to RenderStep. The function is unbound when the trove is cleaned up.

Trove.clone

clone<T extends Instance>(
	instance: T,
): T

Clones an instance and adds it to the clone. Shorthand for trove.add(instance:Clone()).

Trove.extend

extend(): Trove

Constructs a new trove and adds it to the current trove. Shorthand for trove:Add(new Trove()).

Trove.attachToInstance

attachToInstance(
	instance: Instance,
): RBXScriptConnection

Attaches the trove to the given instance. Once the instance is destroyed (using the instance.Destroying event internally), the trove will destroy itself.

Example

class MyClass {
	private trove = new Trove();

	constructor() {

		// Add folder:
		const folder = this.trove.add(new Instance("Folder"));

		// Add function:
		this.trove.add(() => {
			print("Cleanup");
		});

		// Add event:
		this.trove.connect(Workspace.ChildAdded, (child) => {
			print(`${child} added to Workspace`);
		});

		// Add RenderStep binding:
		this.trove.bindToRenderStep("Hello", Enum.RenderPriority.First.Value, (dt) => {
			// Do something
		});

		// Add promise:
		this.trove.addPromise(new Promise(resolve, reject, onCancel) => {
			// Trove will cancel a promise if it is still in-flight when the trove is cleaned up
			onCancel(() => print("Cancelled!"));
			task.wait(5);
			resolve();
		});

		// Add another trove. This creates a new trove and puts the new one into the current one.
		const nestedTrove = this.trove.extend();

		// Add another folder (note: doesn't have to be an instance already in trove):
		const anotherFolder = this.trove.clone(folder);

		// Remove the above folder (which also destroys it):
		this.trove.remove(anotherFolder);

	}

	public destroy() {
		this.trove.destroy();
	}
}