@quenty/binder 14.40.0 → 14.41.0

package/src/Shared/BinderGroup.spec.lua

@@ -1,10 +1,5 @@
 --!strict
 --[[
-	Coverage for BinderGroup: grouping binders, optional constructor validation, and the
-	BinderAdded signal. The binders here are never started, so no CollectionService state is
-	touched; each is still destroyed through the setup() controller to avoid leaking into the
-	shared test place.
-
 	@class BinderGroup.spec.lua
 ]]
 
@@ -46,15 +41,15 @@ end
 
 describe("BinderGroup.new()", function()
 	it("constructs with an initial list of binders", function()
-		local env = setup()
+		local controller = setup()
 
-		local binderA = env.newBinder()
-		local binderB = env.newBinder()
+		local binderA = controller.newBinder()
+		local binderB = controller.newBinder()
 		local group = BinderGroup.new({ binderA, binderB })
 
 		expect(#group:GetBinders()).toEqual(2)
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("constructs empty", function()
@@ -65,19 +60,19 @@ end)
 
 describe("BinderGroup:Add()", function()
 	it("adds a binder and exposes it via GetBinders", function()
-		local env = setup()
+		local controller = setup()
 
 		local group = BinderGroup.new({})
-		local binder = env.newBinder()
+		local binder = controller.newBinder()
 		group:Add(binder)
 
 		expect(group:GetBinders()[1]).toEqual(binder)
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("fires BinderAdded with the added binder", function()
-		local env = setup()
+		local controller = setup()
 
 		local group = BinderGroup.new({})
 		local fired
@@ -85,12 +80,12 @@ describe("BinderGroup:Add()", function()
 			fired = binder
 		end)
 
-		local binder = env.newBinder()
+		local binder = controller.newBinder()
 		group:Add(binder)
 
 		expect(fired).toEqual(binder)
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("throws when the value is not a binder", function()
@@ -103,7 +98,7 @@ end)
 
 describe("BinderGroup constructor validation", function()
 	it("accepts binders whose constructor passes validation", function()
-		local env = setup()
+		local controller = setup()
 
 		local validated = {}
 		local group = BinderGroup.new({}, function(constructor)
@@ -111,40 +106,40 @@ describe("BinderGroup constructor validation", function()
 			return true
 		end)
 
-		local binder = env.newBinder()
+		local binder = controller.newBinder()
 		group:Add(binder)
 
 		expect(validated[1]).toEqual(binder:GetConstructor())
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("throws when the constructor fails validation", function()
-		local env = setup()
+		local controller = setup()
 
 		local group = BinderGroup.new({}, function()
 			return false
 		end)
 
-		local binder = env.newBinder()
+		local binder = controller.newBinder()
 		expect(function()
 			group:Add(binder)
 		end).toThrow()
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("BinderGroup:AddList()", function()
 	it("adds each binder in the list", function()
-		local env = setup()
+		local controller = setup()
 
 		local group = BinderGroup.new({})
-		group:AddList({ env.newBinder(), env.newBinder() })
+		group:AddList({ controller.newBinder(), controller.newBinder() })
 
 		expect(#group:GetBinders()).toEqual(2)
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("throws on a non-table argument", function()

package/src/Shared/BinderTestUtils.lua

@@ -0,0 +1,163 @@
+--!nonstrict
+--[=[
+	Shared harness for the Binder specs. [BinderTestUtils.setup] boots binders the way production code
+	boots them: registered on a [BinderProvider] that is Init/Start'd through a [ServiceBag] and torn
+	down through `serviceBag:Destroy()`. Adornees are parented into a workspace container because
+	CollectionService.GetInstanceAddedSignal only fires for instances that live in the DataModel.
+
+	Tags are global and the test place is shared across a batch run, so every binder gets a distinct
+	tag from a single module-level counter -- shared across every spec file that requires this module,
+	so tags never collide between files -- and each controller cleans up after itself via `destroy()`.
+
+	@class BinderTestUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Binder = require("Binder")
+local BinderProvider = require("BinderProvider")
+local ServiceBag = require("ServiceBag")
+
+local BinderTestUtils = {}
+
+local specCounter = 0
+
+--[=[
+	A minimal bound class that records its instance and whether it was destroyed. It deliberately does
+	NOT retain its constructor varargs: the ServiceBag is injected as a constructor arg, and its object
+	graph contains Quenty Signals whose strict __index makes jest's deep-equality traversal throw.
+	Keeping the class free of them lets toEqual compare instances safely.
+
+	@return TrackingClass
+]=]
+function BinderTestUtils.makeTrackingClass()
+	local Class = {}
+	Class.__index = Class
+	Class.ClassName = "TrackingClass"
+
+	function Class.new(inst)
+		local self = setmetatable({}, Class)
+		self.instance = inst
+		self.destroyed = false
+		return self
+	end
+
+	function Class:Destroy()
+		self.destroyed = true
+	end
+
+	return Class
+end
+
+--[=[
+	Returns once `inst` is no longer bound. CollectionService tag removal is synchronous here, so the
+	class is usually already gone by the time we check; the guarded wait also covers a deferred case.
+
+	@param binder Binder
+	@param inst Instance
+]=]
+function BinderTestUtils.awaitUnbound(binder, inst)
+	if binder:Get(inst) ~= nil then
+		binder:GetClassRemovedSignal():Wait()
+	end
+end
+
+--[=[
+	A no-op constructor that still returns a value, so Binder's generic bound type stays inhabited.
+
+	@return table
+]=]
+function BinderTestUtils.noopConstructor()
+	return {}
+end
+
+--[=[
+	Builds the controller the Binder specs share. Register binders with `addBinder`, boot them all at
+	once through a ServiceBag with `boot`, create adornees with `newInstance`, and tear everything down
+	with `destroy` (or just the service bag with `destroyServiceBag`).
+
+	Fields: `container`.
+	Builders: `addBinder(constructor, ...)` -> Binder, `newInstance(parent?, className?)` -> Instance.
+	Lifecycle: `boot()`, `destroyServiceBag()`, `destroy()`.
+	Helpers: `uniqueTag()` -> string.
+
+	@return { ... }
+]=]
+function BinderTestUtils.setup()
+	specCounter += 1
+	local suffix = specCounter
+
+	local serviceBag = ServiceBag.new()
+	local serviceBagDestroyed = false
+
+	local container = Instance.new("Folder")
+	container.Name = "BinderSpecContainer"
+	container.Parent = workspace
+
+	local instances = {}
+	local pendingBinders = {}
+	local extraTagCounter = 0
+	local booted = false
+
+	local function uniqueTag()
+		extraTagCounter += 1
+		return string.format("BinderSpecTag_%d_%d", suffix, extraTagCounter)
+	end
+
+	local function addBinder(constructor, ...)
+		assert(not booted, "Cannot add a binder after boot()")
+		local binder = Binder.new(uniqueTag(), constructor, ...)
+		table.insert(pendingBinders, binder)
+		return binder
+	end
+
+	local function boot()
+		assert(not booted, "Already booted")
+		booted = true
+
+		local binders = pendingBinders
+		local provider = BinderProvider.new(string.format("BinderSpecProvider_%d", suffix), function(self)
+			for _, binder in binders do
+				self:Add(binder)
+			end
+		end)
+
+		serviceBag:GetService(provider)
+		serviceBag:Init()
+		serviceBag:Start()
+	end
+
+	local function newInstance(parent, className)
+		local inst = Instance.new(className or "Folder")
+		inst.Parent = parent or container
+		table.insert(instances, inst)
+		return inst
+	end
+
+	local function destroyServiceBag()
+		if not serviceBagDestroyed then
+			serviceBagDestroyed = true
+			serviceBag:Destroy()
+		end
+	end
+
+	return {
+		container = container,
+		uniqueTag = uniqueTag,
+		addBinder = addBinder,
+		boot = boot,
+		newInstance = newInstance,
+		destroyServiceBag = destroyServiceBag,
+		destroy = function()
+			destroyServiceBag()
+			for _, inst in instances do
+				pcall(function()
+					inst:Destroy()
+				end)
+			end
+			container:Destroy()
+		end,
+	}
+end
+
+return BinderTestUtils

package/src/Shared/BinderUtils.spec.lua

@@ -1,12 +1,5 @@
 --!strict
 --[[
-	Coverage for BinderUtils lookup helpers.
-
-	Binders are booted through a ServiceBag (as production code does) and instances are tagged
-	BEFORE the service bag starts, so they bind synchronously and :Get() resolves without waiting.
-	Instances live in a workspace container so the binders' added signals fire. Each test tears
-	down its service bag and instances because the test place is shared across a batch run.
-
 	@class BinderUtils.spec.lua
 ]]
 
@@ -64,8 +57,6 @@ local function setup()
 		return inst
 	end
 
-	-- Tags each instance with the binder, then boots everything through the service bag so the
-	-- instances bind synchronously.
 	local function boot()
 		assert(not booted, "Already booted")
 		booted = true
@@ -100,248 +91,248 @@ end
 
 describe("BinderUtils.findFirstAncestor()", function()
 	it("returns the nearest bound ancestor, skipping the child itself", function()
-		local env = setup()
+		local controller = setup()
 
-		local grandparent = env.newInstance()
-		local parent = env.newInstance(grandparent)
-		local child = env.newInstance(parent)
+		local grandparent = controller.newInstance()
+		local parent = controller.newInstance(grandparent)
+		local child = controller.newInstance(parent)
 
-		local binder = env.newBinder()
+		local binder = controller.newBinder()
 		binder:Tag(grandparent)
 		binder:Tag(child) -- child is bound too, but must be skipped
-		env.boot()
+		controller.boot()
 
 		expect(BinderUtils.findFirstAncestor(binder, child)).toEqual(binder:Get(grandparent))
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("returns nil when no ancestor is bound", function()
-		local env = setup()
+		local controller = setup()
 
-		local parent = env.newInstance()
-		local child = env.newInstance(parent)
-		local binder = env.newBinder()
-		env.boot()
+		local parent = controller.newInstance()
+		local child = controller.newInstance(parent)
+		local binder = controller.newBinder()
+		controller.boot()
 
 		expect(BinderUtils.findFirstAncestor(binder, child)).toBeNil()
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("throws for a non-instance child", function()
-		local env = setup()
+		local controller = setup()
 
-		local binder = env.newBinder()
-		env.boot()
+		local binder = controller.newBinder()
+		controller.boot()
 		expect(function()
 			BinderUtils.findFirstAncestor(binder, 5 :: any)
 		end).toThrow()
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("BinderUtils.findFirstChild()", function()
 	it("returns the first bound child", function()
-		local env = setup()
+		local controller = setup()
 
-		local parent = env.newInstance()
-		local unboundChild = env.newInstance(parent)
-		local boundChild = env.newInstance(parent)
+		local parent = controller.newInstance()
+		local unboundChild = controller.newInstance(parent)
+		local boundChild = controller.newInstance(parent)
 
-		local binder = env.newBinder()
+		local binder = controller.newBinder()
 		binder:Tag(boundChild)
-		env.boot()
+		controller.boot()
 
 		expect(BinderUtils.findFirstChild(binder, parent)).toEqual(binder:Get(boundChild))
 		expect(binder:Get(unboundChild)).toBeNil()
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("returns nil when no child is bound", function()
-		local env = setup()
+		local controller = setup()
 
-		local parent = env.newInstance()
-		env.newInstance(parent)
-		local binder = env.newBinder()
-		env.boot()
+		local parent = controller.newInstance()
+		controller.newInstance(parent)
+		local binder = controller.newBinder()
+		controller.boot()
 
 		expect(BinderUtils.findFirstChild(binder, parent)).toBeNil()
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("BinderUtils.getChildren()", function()
 	it("returns every bound child", function()
-		local env = setup()
+		local controller = setup()
 
-		local parent = env.newInstance()
-		local childA = env.newInstance(parent)
-		local childB = env.newInstance(parent)
-		env.newInstance(parent) -- unbound
+		local parent = controller.newInstance()
+		local childA = controller.newInstance(parent)
+		local childB = controller.newInstance(parent)
+		controller.newInstance(parent) -- unbound
 
-		local binder = env.newBinder()
+		local binder = controller.newBinder()
 		binder:Tag(childA)
 		binder:Tag(childB)
-		env.boot()
+		controller.boot()
 
 		expect(#BinderUtils.getChildren(binder, parent)).toEqual(2)
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("does not include bound descendants deeper than one level", function()
-		local env = setup()
+		local controller = setup()
 
-		local parent = env.newInstance()
-		local child = env.newInstance(parent)
-		local grandchild = env.newInstance(child)
+		local parent = controller.newInstance()
+		local child = controller.newInstance(parent)
+		local grandchild = controller.newInstance(child)
 
-		local binder = env.newBinder()
+		local binder = controller.newBinder()
 		binder:Tag(grandchild)
-		env.boot()
+		controller.boot()
 
 		expect(#BinderUtils.getChildren(binder, parent)).toEqual(0)
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("BinderUtils.getDescendants()", function()
 	it("returns bound instances at any depth", function()
-		local env = setup()
+		local controller = setup()
 
-		local parent = env.newInstance()
-		local child = env.newInstance(parent)
-		local grandchild = env.newInstance(child)
+		local parent = controller.newInstance()
+		local child = controller.newInstance(parent)
+		local grandchild = controller.newInstance(child)
 
-		local binder = env.newBinder()
+		local binder = controller.newBinder()
 		binder:Tag(child)
 		binder:Tag(grandchild)
-		env.boot()
+		controller.boot()
 
 		expect(#BinderUtils.getDescendants(binder, parent)).toEqual(2)
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("BinderUtils.mapBinderListToTable()", function()
 	it("keys binders by their tag", function()
-		local env = setup()
+		local controller = setup()
 
-		local binderA = env.newBinder()
-		local binderB = env.newBinder()
-		env.boot()
+		local binderA = controller.newBinder()
+		local binderB = controller.newBinder()
+		controller.boot()
 
 		local map = BinderUtils.mapBinderListToTable({ binderA, binderB })
 		expect(map[binderA:GetTag()]).toEqual(binderA)
 		expect(map[binderB:GetTag()]).toEqual(binderB)
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("BinderUtils.getMappedFromList()", function()
 	it("resolves bound values across an instance list by tag", function()
-		local env = setup()
+		local controller = setup()
 
-		local instA = env.newInstance()
-		local instB = env.newInstance()
-		local binderA = env.newBinder()
-		local binderB = env.newBinder()
+		local instA = controller.newInstance()
+		local instB = controller.newInstance()
+		local binderA = controller.newBinder()
+		local binderB = controller.newBinder()
 		binderA:Tag(instA)
 		binderB:Tag(instB)
-		env.boot()
+		controller.boot()
 
 		local tagsMap = BinderUtils.mapBinderListToTable({ binderA, binderB })
-		local objects = BinderUtils.getMappedFromList(tagsMap, { instA, instB, env.newInstance() })
+		local objects = BinderUtils.getMappedFromList(tagsMap, { instA, instB, controller.newInstance() })
 
 		expect(#objects).toEqual(2)
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("BinderUtils.getChildrenOfBinders()", function()
 	it("returns children bound by any binder in the list", function()
-		local env = setup()
+		local controller = setup()
 
-		local parent = env.newInstance()
-		local childA = env.newInstance(parent)
-		local childB = env.newInstance(parent)
+		local parent = controller.newInstance()
+		local childA = controller.newInstance(parent)
+		local childB = controller.newInstance(parent)
 
-		local binderA = env.newBinder()
-		local binderB = env.newBinder()
+		local binderA = controller.newBinder()
+		local binderB = controller.newBinder()
 		binderA:Tag(childA)
 		binderB:Tag(childB)
-		env.boot()
+		controller.boot()
 
 		expect(#BinderUtils.getChildrenOfBinders({ binderA, binderB }, parent)).toEqual(2)
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)
 
 describe("BinderUtils.getLinkedChildren()", function()
 	it("resolves bound targets of matching ObjectValue links", function()
-		local env = setup()
+		local controller = setup()
 
-		local parent = env.newInstance()
-		local target = env.newInstance()
-		local binder = env.newBinder()
+		local parent = controller.newInstance()
+		local target = controller.newInstance()
+		local binder = controller.newBinder()
 		binder:Tag(target)
 
-		local link = env.newInstance(parent, "ObjectValue") :: ObjectValue
+		local link = controller.newInstance(parent, "ObjectValue") :: ObjectValue
 		link.Name = "Link"
 		link.Value = target
-		env.boot()
+		controller.boot()
 
 		local objects = BinderUtils.getLinkedChildren(binder, "Link", parent)
 		expect(#objects).toEqual(1)
 		expect(objects[1]).toEqual(binder:Get(target))
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("ignores links whose name does not match", function()
-		local env = setup()
+		local controller = setup()
 
-		local parent = env.newInstance()
-		local target = env.newInstance()
-		local binder = env.newBinder()
+		local parent = controller.newInstance()
+		local target = controller.newInstance()
+		local binder = controller.newBinder()
 		binder:Tag(target)
 
-		local link = env.newInstance(parent, "ObjectValue") :: ObjectValue
+		local link = controller.newInstance(parent, "ObjectValue") :: ObjectValue
 		link.Name = "OtherLink"
 		link.Value = target
-		env.boot()
+		controller.boot()
 
 		expect(#BinderUtils.getLinkedChildren(binder, "Link", parent)).toEqual(0)
 
-		env.destroy()
+		controller.destroy()
 	end)
 
 	it("deduplicates when two links point to the same bound target", function()
-		local env = setup()
+		local controller = setup()
 
-		local parent = env.newInstance()
-		local target = env.newInstance()
-		local binder = env.newBinder()
+		local parent = controller.newInstance()
+		local target = controller.newInstance()
+		local binder = controller.newBinder()
 		binder:Tag(target)
 
 		for _ = 1, 2 do
-			local link = env.newInstance(parent, "ObjectValue") :: ObjectValue
+			local link = controller.newInstance(parent, "ObjectValue") :: ObjectValue
 			link.Name = "Link"
 			link.Value = target
 		end
-		env.boot()
+		controller.boot()
 
 		expect(#BinderUtils.getLinkedChildren(binder, "Link", parent)).toEqual(1)
 
-		env.destroy()
+		controller.destroy()
 	end)
 end)