@quenty/binder 14.45.0 → 14.47.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [14.47.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/binder@14.46.0...@quenty/binder@14.47.0) (2026-09-23)
+
+### Bug Fixes
+
+- Binder cleans up during construct/deconstruct moment ([404160e](https://github.com/Quenty/NevermoreEngine/commit/404160efddacbdf95eba0ede5e15066c5d71ed64))
+
+# [14.46.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/binder@14.45.0...@quenty/binder@14.46.0) (2026-09-02)
+
+### Features
+
+- Add RxBinderUtils.observeBoundAncestor<T>() and make sure everything is using binder:ObserveInstance() for performance ([9236c34](https://github.com/Quenty/NevermoreEngine/commit/9236c343fb438d75d29bcfcbaae71025fd344b0e))
+
 # [14.45.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/binder@14.44.0...@quenty/binder@14.45.0) (2026-08-28)
 
 **Note:** Version bump only for package @quenty/binder

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/binder",
-  "version": "14.45.0",
+  "version": "14.47.0",
   "description": "Utility object to Bind a class to Roblox object, and associated helper methods",
   "keywords": [
     "Roblox",
@@ -42,11 +42,10 @@
     "@quenty/servicebag": "11.21.0",
     "@quenty/signal": "7.13.2",
     "@quenty/table": "3.9.2",
-    "@quenty/valueobject": "13.38.0",
     "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "346201e192e467cb71160f43029863853be855b5"
+  "gitHead": "31423d2314075bdd1f14ebbbc3eb637c5e0cb6ce"
 }

package/src/Shared/Binder.lua

@@ -698,6 +698,12 @@ function Binder._add<T>(self: Binder<T>, inst: Instance)
 				tostring(type(constructor) == "table" and constructor.ClassName or constructor)
 			)
 		)
+		if MaidTaskUtils.isValidTask(class) then
+			task.spawn(function()
+				MaidTaskUtils.doTask(class)
+			end)
+		end
+
 		return
 	end
 

package/src/Shared/Collection/BoundChildCollection.lua

@@ -21,6 +21,7 @@ export type BoundChildCollection<T> =
 			_binder: Binder.Binder<T>,
 			_parent: Instance,
 			_classes: Set.Set<T>,
+			_childToClass: { [Instance]: T },
 			ClassAdded: Signal.Signal<T>,
 			ClassRemoved: Signal.Signal<T>,
 			_size: number,
@@ -56,15 +57,9 @@ function BoundChildCollection.new<T>(binder: Binder.Binder<T>, parent: Instance)
 	self.ClassRemoved = self._maid:Add(Signal.new() :: any) -- :Fire(class)
 
 	self._classes = {} -- [class] = true
+	self._childToClass = {}
 	self._size = 0
 
-	self._maid:GiveTask(self._binder:GetClassAddedSignal():Connect(function(...)
-		self:_handleNewClassBound(...)
-	end))
-	self._maid:GiveTask(self._binder:GetClassRemovingSignal():Connect(function(class)
-		self:_removeClass(class)
-	end))
-
 	self:_startTracking()
 
 	return self
@@ -128,29 +123,39 @@ function BoundChildCollection._startTracking<T>(self: BoundChildCollection<T>)
 end
 
 function BoundChildCollection._addChild<T>(self: BoundChildCollection<T>, inst: Instance, doNotFire: boolean?): ()
-	local class = self._binder:Get(inst)
-	if not class then
-		return
-	end
+	self._maid[inst] = self._binder:ObserveInstance(inst, function(class)
+		self:_setChildClass(inst, class)
+	end)
 
-	self:_addClass(class, doNotFire)
+	self:_setChildClass(inst, self._binder:Get(inst), doNotFire)
 end
 
-function BoundChildCollection._handleNewClassBound<T>(self: BoundChildCollection<T>, class: T, inst: Instance): ()
-	if inst.Parent ~= self._parent then
-		return
-	end
+function BoundChildCollection._removeChild<T>(self: BoundChildCollection<T>, inst: Instance): ()
+	self._maid[inst] = nil
 
-	self:_addClass(class)
+	self:_setChildClass(inst, nil)
 end
 
-function BoundChildCollection._removeChild<T>(self: BoundChildCollection<T>, inst: Instance): ()
-	local class = self._binder:Get(inst)
-	if not class then
+function BoundChildCollection._setChildClass<T>(
+	self: BoundChildCollection<T>,
+	inst: Instance,
+	class: T?,
+	doNotFire: boolean?
+): ()
+	local existing = self._childToClass[inst]
+	if existing == class then
 		return
 	end
 
-	self:_removeClass(class)
+	if existing ~= nil then
+		self._childToClass[inst] = nil
+		self:_removeClass(existing)
+	end
+
+	if class ~= nil then
+		self._childToClass[inst] = class
+		self:_addClass(class, doNotFire)
+	end
 end
 
 function BoundChildCollection._addClass<T>(self: BoundChildCollection<T>, class: T, doNotFire: boolean?): ()

package/src/Shared/Collection/BoundChildCollection.spec.lua

@@ -161,6 +161,96 @@ describe("BoundChildCollection dynamic updates", function()
 		controller:Destroy()
 	end)
 
+	it("fires ClassAdded when an existing child binds after construction", function()
+		local controller = setup()
+
+		local parent = controller.newInstance()
+		local child = controller.newInstance(parent)
+		controller.boot()
+
+		local collection = controller.track(BoundChildCollection.new(controller.binder, parent))
+		expect(collection:GetSize()).toEqual(0)
+
+		local added = {}
+		collection.ClassAdded:Connect(function(class)
+			table.insert(added, class)
+		end)
+
+		controller.binder:Tag(child)
+
+		expect(collection:GetSize()).toEqual(1)
+		expect(#added).toEqual(1)
+		expect(added[1]).toEqual(controller.binder:Get(child))
+
+		controller:Destroy()
+	end)
+
+	it("ignores a bind on an instance that is not a child of the parent", function()
+		local controller = setup()
+
+		local parent = controller.newInstance()
+		local outsider = controller.newInstance()
+		local grandchild = controller.newInstance(controller.newInstance(parent))
+		controller.boot()
+
+		local collection = controller.track(BoundChildCollection.new(controller.binder, parent))
+
+		controller.binder:Tag(outsider)
+		controller.binder:Tag(grandchild)
+
+		expect(collection:GetSize()).toEqual(0)
+
+		controller:Destroy()
+	end)
+
+	it("stops following a child that was reparented out", function()
+		local controller = setup()
+
+		local parent = controller.newInstance()
+		local child = controller.newInstance(parent)
+		controller.binder:Tag(child)
+		controller.boot()
+
+		local collection = controller.track(BoundChildCollection.new(controller.binder, parent))
+		expect(collection:GetSize()).toEqual(1)
+
+		child.Parent = controller.container
+		expect(collection:GetSize()).toEqual(0)
+
+		local removed = 0
+		collection.ClassRemoved:Connect(function()
+			removed += 1
+		end)
+
+		controller.binder:Untag(child)
+
+		expect(collection:GetSize()).toEqual(0)
+		expect(removed).toEqual(0)
+
+		controller:Destroy()
+	end)
+
+	it("re-adds a child that leaves and comes back", function()
+		local controller = setup()
+
+		local parent = controller.newInstance()
+		local child = controller.newInstance(parent)
+		controller.binder:Tag(child)
+		controller.boot()
+
+		local collection = controller.track(BoundChildCollection.new(controller.binder, parent))
+		expect(collection:GetSize()).toEqual(1)
+
+		child.Parent = controller.container
+		expect(collection:GetSize()).toEqual(0)
+
+		child.Parent = parent
+		expect(collection:GetSize()).toEqual(1)
+		expect(collection:HasClass(controller.binder:Get(child))).toEqual(true)
+
+		controller:Destroy()
+	end)
+
 	it("fires ClassRemoved when a tracked child is reparented out", function()
 		local controller = setup()
 

package/src/Shared/Trackers/BoundAncestorTracker.lua

@@ -1,83 +0,0 @@
---!strict
---[=[
-	Tracks a parent bound to a specific binder
-	@class BoundAncestorTracker
-]=]
-
-local require = require(script.Parent.loader).load(script)
-
-local BaseObject = require("BaseObject")
-local Binder = require("Binder")
-local BinderUtils = require("BinderUtils")
-local ValueObject = require("ValueObject")
-
-local BoundAncestorTracker = setmetatable({}, BaseObject)
-BoundAncestorTracker.ClassName = "BoundAncestorTracker"
-BoundAncestorTracker.__index = BoundAncestorTracker
-
-export type BoundAncestorTracker<T> =
-	typeof(setmetatable(
-		{} :: {
-			_child: Instance,
-			_binder: Binder.Binder<T>,
-			Class: ValueObject.ValueObject<T?>,
-		},
-		{} :: typeof({ __index = BoundAncestorTracker })
-	))
-	& BaseObject.BaseObject
-
---[=[
-Constructs a new BoundAncestorTracker
-
-@param binder Binder<T>
-@param child Instance
-@return BoundAncestorTracker
-]=]
-function BoundAncestorTracker.new<T>(binder: Binder.Binder<T>, child: Instance): BoundAncestorTracker<T>
-	local self: BoundAncestorTracker<T> = setmetatable(BaseObject.new() :: any, BoundAncestorTracker)
-
-	self._child = child or error("No child")
-	self._binder = binder or error("No binder")
-
-	--[=[
-	@prop Class ValueObject<T>
-	@readonly
-	@within BoundAncestorTracker
-	Bound value
-]=]
-	self.Class = ValueObject.new() :: ValueObject.ValueObject<T?>
-	self._maid:GiveTask(self.Class)
-
-	-- Handle instance removing
-	self._maid:GiveTask(self._binder:GetClassRemovingSignal():Connect(function(class)
-		if class == self.Class.Value then
-			self.Class.Value = nil
-		end
-	end))
-
-	self._maid:GiveTask(self._binder:GetClassAddedSignal():Connect(function(_, instance)
-		if self._child:IsDescendantOf(instance) then
-			self:_update()
-		end
-	end))
-
-	-- Perform update
-	self._maid:GiveTask(self._child.AncestryChanged:Connect(function()
-		self:_update()
-	end))
-	self:_update()
-
-	return self
-end
-
-function BoundAncestorTracker._update<T>(self: BoundAncestorTracker<T>): ()
-	local parent = self._child.Parent
-	if not parent then
-		self.Class.Value = nil
-		return
-	end
-
-	self.Class.Value = BinderUtils.findFirstAncestor(self._binder, parent)
-end
-
-return BoundAncestorTracker

package/src/Shared/Trackers/BoundAncestorTracker.spec.lua

@@ -1,179 +0,0 @@
---!strict
---[[
-	@class BoundAncestorTracker.spec.lua
-]]
-
-local require = require(script.Parent.loader).load(script)
-
-local Binder = require("Binder")
-local BinderProvider = require("BinderProvider")
-local BoundAncestorTracker = require("BoundAncestorTracker")
-local Jest = require("Jest")
-local JestUtils = require("JestUtils")
-local Maid = require("Maid")
-local ServiceBag = require("ServiceBag")
-
-local describe = Jest.Globals.describe
-local expect = Jest.Globals.expect
-local it = Jest.Globals.it
-
-local specCounter = 0
-
-local function makeClass()
-	local Class = {}
-	Class.__index = Class
-	Class.ClassName = "BoundAncestorTrackerSpecClass"
-	function Class.new(inst)
-		return setmetatable({ instance = inst }, Class)
-	end
-	function Class:Destroy() end
-	return Class
-end
-
-local function setup()
-	local maid = Maid.new()
-
-	specCounter += 1
-	local suffix = specCounter
-
-	local serviceBag = ServiceBag.new()
-	local container = Instance.new("Folder")
-	container.Name = "BoundAncestorTrackerSpecContainer"
-	container.Parent = workspace
-
-	local instances: { Instance } = {}
-	local cleanups: { any } = {}
-	local booted = false
-
-	local binder = Binder.new(string.format("BoundAncestorTrackerSpecTag_%d", suffix), makeClass() :: any)
-
-	local function newInstance(parent: Instance?): Instance
-		local inst = Instance.new("Folder")
-		inst.Parent = parent or container
-		table.insert(instances, inst)
-		return inst
-	end
-
-	local function track(item: any): any
-		table.insert(cleanups, item)
-		return item
-	end
-
-	local function boot()
-		assert(not booted, "Already booted")
-		booted = true
-
-		local provider = BinderProvider.new(string.format("BoundAncestorTrackerSpecProvider_%d", suffix), function(self)
-			self:Add(binder)
-		end)
-		serviceBag:GetService(provider)
-		serviceBag:Init()
-		serviceBag:Start()
-	end
-
-	local function awaitChange(tracker, previous)
-		if tracker.Class.Value == previous then
-			tracker.Class.Changed:Wait()
-		end
-		return tracker.Class.Value
-	end
-
-	maid:GiveTask(function()
-		for _, item in cleanups do
-			pcall(function()
-				item:Destroy()
-			end)
-		end
-		serviceBag:Destroy()
-		for _, inst in instances do
-			pcall(function()
-				inst:Destroy()
-			end)
-		end
-		container:Destroy()
-	end)
-
-	local controller = {
-		container = container,
-		binder = binder,
-		newInstance = newInstance,
-		track = track,
-		boot = boot,
-		awaitChange = awaitChange,
-		Destroy = function(_self)
-			maid:DoCleaning()
-		end,
-	}
-
-	maid:GiveTask(JestUtils.afterThis(controller))
-
-	return controller
-end
-
-describe("BoundAncestorTracker tracking", function()
-	it("exposes the nearest bound ancestor's class", function()
-		local controller = setup()
-
-		local grandparent = controller.newInstance()
-		local parent = controller.newInstance(grandparent)
-		local child = controller.newInstance(parent)
-		controller.binder:Tag(grandparent)
-		controller.boot()
-
-		local tracker = controller.track(BoundAncestorTracker.new(controller.binder, child))
-		expect(tracker.Class.Value).toEqual(controller.binder:Get(grandparent))
-
-		controller:Destroy()
-	end)
-
-	it("has no value when no ancestor is bound", function()
-		local controller = setup()
-
-		local parent = controller.newInstance()
-		local child = controller.newInstance(parent)
-		controller.boot()
-
-		local tracker = controller.track(BoundAncestorTracker.new(controller.binder, child))
-		expect(tracker.Class.Value).toBeNil()
-
-		controller:Destroy()
-	end)
-
-	it("updates when an ancestor becomes bound", function()
-		local controller = setup()
-
-		-- The tracker resolves ancestors above the child's direct parent, so bind the grandparent.
-		local ancestor = controller.newInstance()
-		local parent = controller.newInstance(ancestor)
-		local child = controller.newInstance(parent)
-		controller.boot()
-
-		local tracker = controller.track(BoundAncestorTracker.new(controller.binder, child))
-		expect(tracker.Class.Value).toBeNil()
-
-		controller.binder:Tag(ancestor)
-		local value = controller.awaitChange(tracker, nil)
-		expect(value).toEqual(controller.binder:Get(ancestor))
-
-		controller:Destroy()
-	end)
-
-	it("clears the value when the child leaves the bound ancestry", function()
-		local controller = setup()
-
-		local ancestor = controller.newInstance()
-		local parent = controller.newInstance(ancestor)
-		local child = controller.newInstance(parent)
-		controller.binder:Tag(ancestor)
-		controller.boot()
-
-		local tracker = controller.track(BoundAncestorTracker.new(controller.binder, child))
-		local class = controller.binder:Get(ancestor)
-		expect(tracker.Class.Value).toEqual(class)
-
-		child.Parent = controller.container
-		expect(controller.awaitChange(tracker, class)).toBeNil()
-
-		controller:Destroy()
-	end)
-end)

package/src/Shared/Trackers/BoundParentTracker.lua

@@ -1,64 +0,0 @@
---!strict
---[=[
-	Tracks a parent bound to a specific binder
-	@class BoundParentTracker
-]=]
-
-local require = require(script.Parent.loader).load(script)
-
-local BaseObject = require("BaseObject")
-local Binder = require("Binder")
-local ValueObject = require("ValueObject")
-
-local BoundParentTracker = setmetatable({}, BaseObject)
-BoundParentTracker.ClassName = "BoundParentTracker"
-BoundParentTracker.__index = BoundParentTracker
-
-export type BoundParentTracker<T> =
-	typeof(setmetatable(
-		{} :: {
-			_child: Instance,
-			_binder: Binder.Binder<T>,
-			Class: ValueObject.ValueObject<T?>,
-		},
-		{} :: typeof({ __index = BoundParentTracker })
-	))
-	& BaseObject.BaseObject
-
-function BoundParentTracker.new<T>(binder: Binder.Binder<T>, child: Instance): BoundParentTracker<T>
-	local self: BoundParentTracker<T> = setmetatable(BaseObject.new() :: any, BoundParentTracker)
-
-	self._child = child or error("No child")
-	self._binder = binder or error("No binder")
-
-	-- Bound value
-	self.Class = ValueObject.new(nil :: T?)
-	self._maid:GiveTask(self.Class)
-
-	-- Handle instance removing
-	self._maid:GiveTask(self._binder:GetClassRemovingSignal():Connect(function(class)
-		if class == self.Class.Value then
-			self.Class.Value = nil
-		end
-	end))
-
-	-- Perform update
-	self._maid:GiveTask(self._child:GetPropertyChangedSignal("Parent"):Connect(function()
-		self:_update()
-	end))
-	self:_update()
-
-	return self
-end
-
-function BoundParentTracker._update<T>(self: BoundParentTracker<T>): ()
-	local parent = self._child.Parent
-	if not parent then
-		self.Class.Value = nil
-		return
-	end
-
-	self.Class.Value = self._binder:Get(parent)
-end
-
-return BoundParentTracker

package/src/Shared/Trackers/BoundParentTracker.spec.lua

@@ -1,171 +0,0 @@
---!strict
---[[
-	@class BoundParentTracker.spec.lua
-]]
-
-local require = require(script.Parent.loader).load(script)
-
-local Binder = require("Binder")
-local BinderProvider = require("BinderProvider")
-local BoundParentTracker = require("BoundParentTracker")
-local Jest = require("Jest")
-local JestUtils = require("JestUtils")
-local Maid = require("Maid")
-local ServiceBag = require("ServiceBag")
-
-local describe = Jest.Globals.describe
-local expect = Jest.Globals.expect
-local it = Jest.Globals.it
-
-local specCounter = 0
-
-local function makeClass()
-	local Class = {}
-	Class.__index = Class
-	Class.ClassName = "BoundParentTrackerSpecClass"
-	function Class.new(inst)
-		return setmetatable({ instance = inst }, Class)
-	end
-	function Class:Destroy() end
-	return Class
-end
-
-local function setup()
-	local maid = Maid.new()
-
-	specCounter += 1
-	local suffix = specCounter
-
-	local serviceBag = ServiceBag.new()
-	local container = Instance.new("Folder")
-	container.Name = "BoundParentTrackerSpecContainer"
-	container.Parent = workspace
-
-	local instances: { Instance } = {}
-	local cleanups: { any } = {}
-	local booted = false
-
-	local binder = Binder.new(string.format("BoundParentTrackerSpecTag_%d", suffix), makeClass() :: any)
-
-	local function newInstance(parent: Instance?): Instance
-		local inst = Instance.new("Folder")
-		inst.Parent = parent or container
-		table.insert(instances, inst)
-		return inst
-	end
-
-	local function track(item: any): any
-		table.insert(cleanups, item)
-		return item
-	end
-
-	local function boot()
-		assert(not booted, "Already booted")
-		booted = true
-
-		local provider = BinderProvider.new(string.format("BoundParentTrackerSpecProvider_%d", suffix), function(self)
-			self:Add(binder)
-		end)
-		serviceBag:GetService(provider)
-		serviceBag:Init()
-		serviceBag:Start()
-	end
-
-	local function awaitChange(tracker, previous)
-		if tracker.Class.Value == previous then
-			tracker.Class.Changed:Wait()
-		end
-		return tracker.Class.Value
-	end
-
-	maid:GiveTask(function()
-		for _, item in cleanups do
-			pcall(function()
-				item:Destroy()
-			end)
-		end
-		serviceBag:Destroy()
-		for _, inst in instances do
-			pcall(function()
-				inst:Destroy()
-			end)
-		end
-		container:Destroy()
-	end)
-
-	local controller = {
-		container = container,
-		binder = binder,
-		newInstance = newInstance,
-		track = track,
-		boot = boot,
-		awaitChange = awaitChange,
-		Destroy = function(_self)
-			maid:DoCleaning()
-		end,
-	}
-
-	maid:GiveTask(JestUtils.afterThis(controller))
-
-	return controller
-end
-
-describe("BoundParentTracker.new()", function()
-	it("throws without a binder or child", function()
-		expect(function()
-			BoundParentTracker.new(nil :: any, Instance.new("Folder"))
-		end).toThrow()
-	end)
-end)
-
-describe("BoundParentTracker tracking", function()
-	it("exposes the bound class of the direct parent", function()
-		local controller = setup()
-
-		local parent = controller.newInstance()
-		local child = controller.newInstance(parent)
-		controller.binder:Tag(parent)
-		controller.boot()
-
-		local tracker = controller.track(BoundParentTracker.new(controller.binder, child))
-		expect(tracker.Class.Value).toEqual(controller.binder:Get(parent))
-
-		controller:Destroy()
-	end)
-
-	it("clears the value when the child is reparented off the bound parent", function()
-		local controller = setup()
-
-		local parent = controller.newInstance()
-		local child = controller.newInstance(parent)
-		controller.binder:Tag(parent)
-		controller.boot()
-
-		local tracker = controller.track(BoundParentTracker.new(controller.binder, child))
-		local class = controller.binder:Get(parent)
-		expect(tracker.Class.Value).toEqual(class)
-
-		child.Parent = controller.container
-		expect(controller.awaitChange(tracker, class)).toBeNil()
-
-		controller:Destroy()
-	end)
-
-	it("clears the value when the parent's class is unbound", function()
-		local controller = setup()
-
-		local parent = controller.newInstance()
-		local child = controller.newInstance(parent)
-		controller.binder:Tag(parent)
-		controller.boot()
-
-		local tracker = controller.track(BoundParentTracker.new(controller.binder, child))
-		local class = controller.binder:Get(parent)
-		expect(tracker.Class.Value).toEqual(class)
-
-		controller.binder:Untag(parent)
-		expect(controller.awaitChange(tracker, class)).toBeNil()
-
-		controller:Destroy()
-	end)
-end)