@quenty/binder 14.38.0 → 14.40.0

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

@@ -0,0 +1,212 @@
+--!strict
+--[[
+	Coverage for BoundChildCollection, which tracks the bound children of a parent instance.
+
+	The binder is booted through a ServiceBag (as production code does); the collection itself is a
+	plain BaseObject and is constructed directly. Everything lives under a workspace container so
+	CollectionService and ChildAdded/ChildRemoved signals fire. Children tagged before the service
+	bag starts bind synchronously; changes made after construction are awaited event-driven via the
+	collection's own ClassAdded/ClassRemoved signals rather than a fixed sleep.
+
+	@class BoundChildCollection.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Binder = require("Binder")
+local BinderProvider = require("BinderProvider")
+local BoundChildCollection = require("BoundChildCollection")
+local Jest = require("Jest")
+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 = "BoundChildCollectionSpecClass"
+	function Class.new(inst)
+		return setmetatable({ instance = inst }, Class)
+	end
+	function Class:Destroy() end
+	return Class
+end
+
+local function setup()
+	specCounter += 1
+	local suffix = specCounter
+
+	local serviceBag = ServiceBag.new()
+	local container = Instance.new("Folder")
+	container.Name = "BoundChildCollectionSpecContainer"
+	container.Parent = workspace
+
+	local instances = {}
+	local cleanups = {}
+	local booted = false
+
+	local binder = Binder.new(string.format("BoundChildCollectionSpecTag_%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("BoundChildCollectionSpecProvider_%d", suffix), function(self)
+			self:Add(binder)
+		end)
+		serviceBag:GetService(provider)
+		serviceBag:Init()
+		serviceBag:Start()
+	end
+
+	return {
+		container = container,
+		binder = binder,
+		newInstance = newInstance,
+		track = track,
+		boot = boot,
+		destroy = 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,
+	}
+end
+
+describe("BoundChildCollection construction", function()
+	it("counts children bound before construction without firing ClassAdded", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local childA = env.newInstance(parent)
+		local childB = env.newInstance(parent)
+		env.newInstance(parent) -- unbound child
+
+		env.binder:Tag(childA)
+		env.binder:Tag(childB)
+		env.boot()
+
+		local fired = 0
+		local collection = env.track(BoundChildCollection.new(env.binder, parent))
+		collection.ClassAdded:Connect(function()
+			fired += 1
+		end)
+
+		expect(collection:GetSize()).toEqual(2)
+		expect(fired).toEqual(0)
+		expect(#collection:GetClasses()).toEqual(2)
+		expect(collection:HasClass(env.binder:Get(childA))).toEqual(true)
+
+		env.destroy()
+	end)
+end)
+
+describe("BoundChildCollection dynamic updates", function()
+	it("fires ClassAdded when a bound child is reparented in", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		env.boot()
+
+		local collection = env.track(BoundChildCollection.new(env.binder, parent))
+
+		-- Bind an instance living elsewhere, then move it under the tracked parent.
+		local child = env.newInstance()
+		env.binder:Tag(child)
+		local ok, class = env.binder:Promise(child):Yield()
+		assert(ok, "child never bound")
+
+		local addedClass
+		local conn = collection.ClassAdded:Connect(function(c)
+			addedClass = c
+		end)
+
+		child.Parent = parent
+		if collection:GetSize() == 0 then
+			collection.ClassAdded:Wait()
+		end
+		conn:Disconnect()
+
+		expect(addedClass).toEqual(class)
+		expect(collection:GetSize()).toEqual(1)
+
+		env.destroy()
+	end)
+
+	it("fires ClassRemoved when a tracked child is reparented out", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local child = env.newInstance(parent)
+		env.binder:Tag(child)
+		env.boot()
+
+		local collection = env.track(BoundChildCollection.new(env.binder, parent))
+		expect(collection:GetSize()).toEqual(1)
+
+		local removedClass
+		local conn = collection.ClassRemoved:Connect(function(c)
+			removedClass = c
+		end)
+
+		local class = env.binder:Get(child)
+		child.Parent = env.container
+		if collection:GetSize() == 1 then
+			collection.ClassRemoved:Wait()
+		end
+		conn:Disconnect()
+
+		expect(removedClass).toEqual(class)
+		expect(collection:GetSize()).toEqual(0)
+
+		env.destroy()
+	end)
+
+	it("fires ClassRemoved when a tracked child is unbound", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local child = env.newInstance(parent)
+		env.binder:Tag(child)
+		env.boot()
+
+		local collection = env.track(BoundChildCollection.new(env.binder, parent))
+		expect(collection:GetSize()).toEqual(1)
+
+		local conn = collection.ClassRemoved:Connect(function() end)
+		env.binder:Untag(child)
+		if collection:GetSize() == 1 then
+			collection.ClassRemoved:Wait()
+		end
+		conn:Disconnect()
+
+		expect(collection:GetSize()).toEqual(0)
+
+		env.destroy()
+	end)
+end)

package/src/Shared/Promise/promiseBoundClass.spec.lua

@@ -0,0 +1,135 @@
+--!strict
+--[[
+	Coverage for promiseBoundClass, a thin wrapper that delegates to Binder:Promise after
+	validating its arguments.
+
+	The binder is booted through a ServiceBag; the instance is tagged before start so it binds
+	synchronously and the promise resolves immediately.
+
+	@class promiseBoundClass.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Binder = require("Binder")
+local BinderProvider = require("BinderProvider")
+local Jest = require("Jest")
+local ServiceBag = require("ServiceBag")
+local promiseBoundClass = require("promiseBoundClass")
+
+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 = "PromiseBoundClassSpecClass"
+	function Class.new(inst)
+		return setmetatable({ instance = inst }, Class)
+	end
+	function Class:Destroy() end
+	return Class
+end
+
+local function setup()
+	specCounter += 1
+	local suffix = specCounter
+
+	local serviceBag = ServiceBag.new()
+	local container = Instance.new("Folder")
+	container.Name = "PromiseBoundClassSpecContainer"
+	container.Parent = workspace
+
+	local instances = {}
+	local booted = false
+
+	local binder = Binder.new(string.format("PromiseBoundClassSpecTag_%d", suffix), makeClass() :: any)
+
+	local function newInstance(): Instance
+		local inst = Instance.new("Folder")
+		inst.Parent = container
+		table.insert(instances, inst)
+		return inst
+	end
+
+	local function boot()
+		assert(not booted, "Already booted")
+		booted = true
+
+		local provider = BinderProvider.new(string.format("PromiseBoundClassSpecProvider_%d", suffix), function(self)
+			self:Add(binder)
+		end)
+		serviceBag:GetService(provider)
+		serviceBag:Init()
+		serviceBag:Start()
+	end
+
+	return {
+		binder = binder,
+		newInstance = newInstance,
+		boot = boot,
+		destroy = function()
+			serviceBag:Destroy()
+			for _, inst in instances do
+				pcall(function()
+					inst:Destroy()
+				end)
+			end
+			container:Destroy()
+		end,
+	}
+end
+
+describe("promiseBoundClass()", function()
+	it("resolves with the bound class", function()
+		local env = setup()
+
+		local inst = env.newInstance()
+		env.binder:Tag(inst)
+		env.boot()
+
+		local ok, class = promiseBoundClass(env.binder, inst):Yield()
+		assert(ok, "Never bound")
+		expect(class).toEqual(env.binder:Get(inst))
+
+		env.destroy()
+	end)
+
+	it("resolves once an instance is bound after start", function()
+		local env = setup()
+
+		env.boot()
+		local inst = env.newInstance()
+		env.binder:Tag(inst)
+
+		local ok = promiseBoundClass(env.binder, inst):Yield()
+		expect(ok).toEqual(true)
+
+		env.destroy()
+	end)
+
+	it("throws when the binder is not a binder", function()
+		local env = setup()
+		env.boot()
+
+		expect(function()
+			promiseBoundClass({} :: any, env.newInstance())
+		end).toThrow()
+
+		env.destroy()
+	end)
+
+	it("throws when the instance is not an Instance", function()
+		local env = setup()
+		env.boot()
+
+		expect(function()
+			promiseBoundClass(env.binder, 5 :: any)
+		end).toThrow()
+
+		env.destroy()
+	end)
+end)

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

@@ -0,0 +1,175 @@
+--!strict
+--[[
+	Coverage for BoundAncestorTracker, which exposes the bound class of a child's nearest bound
+	ancestor.
+
+	The binder is booted through a ServiceBag; the tracker is a plain BaseObject constructed
+	directly. Instances live under a workspace container so ancestry and CollectionService signals
+	fire. Ancestry changes and late binds are awaited event-driven via the tracker's Class.Changed
+	signal rather than a fixed sleep.
+
+	@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 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()
+	specCounter += 1
+	local suffix = specCounter
+
+	local serviceBag = ServiceBag.new()
+	local container = Instance.new("Folder")
+	container.Name = "BoundAncestorTrackerSpecContainer"
+	container.Parent = workspace
+
+	local instances = {}
+	local cleanups = {}
+	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
+
+	return {
+		container = container,
+		binder = binder,
+		newInstance = newInstance,
+		track = track,
+		boot = boot,
+		awaitChange = awaitChange,
+		destroy = 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,
+	}
+end
+
+describe("BoundAncestorTracker tracking", function()
+	it("exposes the nearest bound ancestor's class", function()
+		local env = setup()
+
+		local grandparent = env.newInstance()
+		local parent = env.newInstance(grandparent)
+		local child = env.newInstance(parent)
+		env.binder:Tag(grandparent)
+		env.boot()
+
+		local tracker = env.track(BoundAncestorTracker.new(env.binder, child))
+		expect(tracker.Class.Value).toEqual(env.binder:Get(grandparent))
+
+		env.destroy()
+	end)
+
+	it("has no value when no ancestor is bound", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local child = env.newInstance(parent)
+		env.boot()
+
+		local tracker = env.track(BoundAncestorTracker.new(env.binder, child))
+		expect(tracker.Class.Value).toBeNil()
+
+		env.destroy()
+	end)
+
+	it("updates when an ancestor becomes bound", function()
+		local env = setup()
+
+		-- The tracker resolves ancestors above the child's direct parent, so bind the grandparent.
+		local ancestor = env.newInstance()
+		local parent = env.newInstance(ancestor)
+		local child = env.newInstance(parent)
+		env.boot()
+
+		local tracker = env.track(BoundAncestorTracker.new(env.binder, child))
+		expect(tracker.Class.Value).toBeNil()
+
+		env.binder:Tag(ancestor)
+		local value = env.awaitChange(tracker, nil)
+		expect(value).toEqual(env.binder:Get(ancestor))
+
+		env.destroy()
+	end)
+
+	it("clears the value when the child leaves the bound ancestry", function()
+		local env = setup()
+
+		local ancestor = env.newInstance()
+		local parent = env.newInstance(ancestor)
+		local child = env.newInstance(parent)
+		env.binder:Tag(ancestor)
+		env.boot()
+
+		local tracker = env.track(BoundAncestorTracker.new(env.binder, child))
+		local class = env.binder:Get(ancestor)
+		expect(tracker.Class.Value).toEqual(class)
+
+		child.Parent = env.container
+		expect(env.awaitChange(tracker, class)).toBeNil()
+
+		env.destroy()
+	end)
+end)

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

@@ -0,0 +1,167 @@
+--!strict
+--[[
+	Coverage for BoundParentTracker, which exposes the bound class on a child's direct parent.
+
+	The binder is booted through a ServiceBag; the tracker is a plain BaseObject constructed
+	directly. Instances live under a workspace container so parent-change and CollectionService
+	signals fire. Parent changes and unbinds are awaited event-driven via the tracker's
+	Class.Changed signal rather than a fixed sleep.
+
+	@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 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()
+	specCounter += 1
+	local suffix = specCounter
+
+	local serviceBag = ServiceBag.new()
+	local container = Instance.new("Folder")
+	container.Name = "BoundParentTrackerSpecContainer"
+	container.Parent = workspace
+
+	local instances = {}
+	local cleanups = {}
+	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
+
+	-- Blocks until the tracker's value moves off `previous`.
+	local function awaitChange(tracker, previous)
+		if tracker.Class.Value == previous then
+			tracker.Class.Changed:Wait()
+		end
+		return tracker.Class.Value
+	end
+
+	return {
+		container = container,
+		binder = binder,
+		newInstance = newInstance,
+		track = track,
+		boot = boot,
+		awaitChange = awaitChange,
+		destroy = 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,
+	}
+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 env = setup()
+
+		local parent = env.newInstance()
+		local child = env.newInstance(parent)
+		env.binder:Tag(parent)
+		env.boot()
+
+		local tracker = env.track(BoundParentTracker.new(env.binder, child))
+		expect(tracker.Class.Value).toEqual(env.binder:Get(parent))
+
+		env.destroy()
+	end)
+
+	it("clears the value when the child is reparented off the bound parent", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local child = env.newInstance(parent)
+		env.binder:Tag(parent)
+		env.boot()
+
+		local tracker = env.track(BoundParentTracker.new(env.binder, child))
+		local class = env.binder:Get(parent)
+		expect(tracker.Class.Value).toEqual(class)
+
+		child.Parent = env.container
+		expect(env.awaitChange(tracker, class)).toBeNil()
+
+		env.destroy()
+	end)
+
+	it("clears the value when the parent's class is unbound", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local child = env.newInstance(parent)
+		env.binder:Tag(parent)
+		env.boot()
+
+		local tracker = env.track(BoundParentTracker.new(env.binder, child))
+		local class = env.binder:Get(parent)
+		expect(tracker.Class.Value).toEqual(class)
+
+		env.binder:Untag(parent)
+		expect(env.awaitChange(tracker, class)).toBeNil()
+
+		env.destroy()
+	end)
+end)