@quenty/binder 14.38.0 → 14.40.0

package/src/Shared/BinderGroup.spec.lua

@@ -0,0 +1,156 @@
+--!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
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Binder = require("Binder")
+local BinderGroup = require("BinderGroup")
+local Jest = require("Jest")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local tagCounter = 0
+
+local function setup()
+	local binders: { any } = {}
+
+	local function newBinder(): Binder.Binder<any>
+		tagCounter += 1
+		local binder = Binder.new(string.format("BinderGroupSpecTag_%d", tagCounter), function()
+			return {}
+		end)
+		table.insert(binders, binder)
+		return binder
+	end
+
+	return {
+		newBinder = newBinder,
+		destroy = function()
+			for _, binder in binders do
+				pcall(function()
+					binder:Destroy()
+				end)
+			end
+		end,
+	}
+end
+
+describe("BinderGroup.new()", function()
+	it("constructs with an initial list of binders", function()
+		local env = setup()
+
+		local binderA = env.newBinder()
+		local binderB = env.newBinder()
+		local group = BinderGroup.new({ binderA, binderB })
+
+		expect(#group:GetBinders()).toEqual(2)
+
+		env.destroy()
+	end)
+
+	it("constructs empty", function()
+		local group = BinderGroup.new({})
+		expect(#group:GetBinders()).toEqual(0)
+	end)
+end)
+
+describe("BinderGroup:Add()", function()
+	it("adds a binder and exposes it via GetBinders", function()
+		local env = setup()
+
+		local group = BinderGroup.new({})
+		local binder = env.newBinder()
+		group:Add(binder)
+
+		expect(group:GetBinders()[1]).toEqual(binder)
+
+		env.destroy()
+	end)
+
+	it("fires BinderAdded with the added binder", function()
+		local env = setup()
+
+		local group = BinderGroup.new({})
+		local fired
+		group.BinderAdded:Connect(function(binder)
+			fired = binder
+		end)
+
+		local binder = env.newBinder()
+		group:Add(binder)
+
+		expect(fired).toEqual(binder)
+
+		env.destroy()
+	end)
+
+	it("throws when the value is not a binder", function()
+		local group = BinderGroup.new({})
+		expect(function()
+			group:Add({} :: any)
+		end).toThrow()
+	end)
+end)
+
+describe("BinderGroup constructor validation", function()
+	it("accepts binders whose constructor passes validation", function()
+		local env = setup()
+
+		local validated = {}
+		local group = BinderGroup.new({}, function(constructor)
+			table.insert(validated, constructor)
+			return true
+		end)
+
+		local binder = env.newBinder()
+		group:Add(binder)
+
+		expect(validated[1]).toEqual(binder:GetConstructor())
+
+		env.destroy()
+	end)
+
+	it("throws when the constructor fails validation", function()
+		local env = setup()
+
+		local group = BinderGroup.new({}, function()
+			return false
+		end)
+
+		local binder = env.newBinder()
+		expect(function()
+			group:Add(binder)
+		end).toThrow()
+
+		env.destroy()
+	end)
+end)
+
+describe("BinderGroup:AddList()", function()
+	it("adds each binder in the list", function()
+		local env = setup()
+
+		local group = BinderGroup.new({})
+		group:AddList({ env.newBinder(), env.newBinder() })
+
+		expect(#group:GetBinders()).toEqual(2)
+
+		env.destroy()
+	end)
+
+	it("throws on a non-table argument", function()
+		local group = BinderGroup.new({})
+		expect(function()
+			group:AddList(5 :: any)
+		end).toThrow()
+	end)
+end)

package/src/Shared/BinderGroupProvider.spec.lua

@@ -0,0 +1,117 @@
+--!strict
+--[[
+	Coverage for BinderGroupProvider: registration before init, the groups-added promise, and
+	the custom __index guard that rejects unknown lookups.
+
+	@class BinderGroupProvider.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local BinderGroup = require("BinderGroup")
+local BinderGroupProvider = require("BinderGroupProvider")
+local Jest = require("Jest")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("BinderGroupProvider.new()", function()
+	it("constructs a provider", function()
+		local provider = BinderGroupProvider.new(function() end)
+		expect((provider :: any).ClassName).toEqual("BinderGroupProvider")
+	end)
+
+	it("throws without an init method", function()
+		expect(function()
+			BinderGroupProvider.new(nil :: any)
+		end).toThrow()
+	end)
+end)
+
+describe("BinderGroupProvider:Init()", function()
+	it("runs the init method and resolves the groups-added promise", function()
+		local ran = false
+		local provider = BinderGroupProvider.new(function(self)
+			ran = true
+			self:Add("Group", BinderGroup.new({}))
+		end)
+
+		expect(provider:PromiseGroupsAdded():IsPending()).toEqual(true)
+		provider:Init()
+
+		expect(ran).toEqual(true)
+		expect(provider:PromiseGroupsAdded():IsFulfilled()).toEqual(true)
+	end)
+
+	it("passes extra Init args to the init method", function()
+		local received
+		local provider = BinderGroupProvider.new(function(_self, arg)
+			received = arg
+		end)
+		provider:Init(4321)
+		expect(received).toEqual(4321)
+	end)
+
+	it("throws when initialized twice", function()
+		local provider = BinderGroupProvider.new(function() end)
+		provider:Init()
+		expect(function()
+			provider:Init()
+		end).toThrow()
+	end)
+end)
+
+describe("BinderGroupProvider:Add() / Get()", function()
+	it("retrieves an added group by name", function()
+		local group = BinderGroup.new({})
+		local provider = BinderGroupProvider.new(function(self)
+			self:Add("MyGroup", group)
+		end)
+		provider:Init()
+
+		expect(provider:Get("MyGroup")).toEqual(group)
+	end)
+
+	it("returns nil for an unknown group name via Get()", function()
+		local provider = BinderGroupProvider.new(function() end)
+		provider:Init()
+		expect(provider:Get("Missing")).toBeNil()
+	end)
+
+	it("throws when adding a duplicate group name", function()
+		local provider = BinderGroupProvider.new(function(self)
+			self:Add("Dup", BinderGroup.new({}))
+			self:Add("Dup", BinderGroup.new({}))
+		end)
+
+		expect(function()
+			provider:Init()
+		end).toThrow()
+	end)
+
+	it("throws when adding after initialization", function()
+		local provider = BinderGroupProvider.new(function() end)
+		provider:Init()
+		expect(function()
+			provider:Add("Late", BinderGroup.new({}))
+		end).toThrow()
+	end)
+
+	it("throws on a non-string group name", function()
+		local provider = BinderGroupProvider.new(function() end)
+		expect(function()
+			provider:Get(5 :: any)
+		end).toThrow()
+	end)
+end)
+
+describe("BinderGroupProvider __index guard", function()
+	it("throws when indexing an unknown key", function()
+		local provider = BinderGroupProvider.new(function() end)
+		provider:Init()
+		expect(function()
+			return (provider :: any).SomethingInvalid
+		end).toThrow()
+	end)
+end)

package/src/Shared/BinderProvider.spec.lua

@@ -1,11 +1,9 @@
---!nonstrict
+--!strict
 --[[
 	@class BinderProvider.spec.lua
 ]]
 
-local require = (require :: any)(
-		game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent
-	).bootstrapStory(script) :: typeof(require(script.Parent.loader).load(script))
+local require = require(script.Parent.loader).load(script)
 
 local Binder = require("Binder")
 local BinderProvider = require("BinderProvider")
@@ -49,7 +47,7 @@ describe("BinderProvider.new()", function()
 
 		provider:Init()
 
-		expect(provider.Test).toEqual(expect.any("table"))
+		expect((provider :: any).Test).toEqual(expect.any("table"))
 
 		provider:Destroy()
 		if binder then

package/src/Shared/BinderUtils.spec.lua

@@ -0,0 +1,347 @@
+--!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
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Binder = require("Binder")
+local BinderProvider = require("BinderProvider")
+local BinderUtils = require("BinderUtils")
+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 = "BinderUtilsSpecClass"
+	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 = "BinderUtilsSpecContainer"
+	container.Parent = workspace
+
+	local instances = {}
+	local pendingBinders: { any } = {}
+	local tagCounter = 0
+	local booted = false
+
+	local function newBinder(): Binder.Binder<any>
+		assert(not booted, "Cannot add a binder after boot()")
+		tagCounter += 1
+		local binder = Binder.new(string.format("BinderUtilsSpecTag_%d_%d", suffix, tagCounter), makeClass() :: any)
+		table.insert(pendingBinders, binder)
+		return binder
+	end
+
+	local function newInstance(parent: Instance?, className: string?): Instance
+		local inst = Instance.new(className or "Folder")
+		inst.Parent = parent or container
+		table.insert(instances, inst)
+		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
+
+		local binders = pendingBinders
+		local provider = BinderProvider.new(string.format("BinderUtilsSpecProvider_%d", suffix), function(self)
+			for _, binder in binders do
+				self:Add(binder)
+			end
+		end)
+		serviceBag:GetService(provider)
+		serviceBag:Init()
+		serviceBag:Start()
+	end
+
+	return {
+		container = container,
+		newBinder = newBinder,
+		newInstance = newInstance,
+		boot = boot,
+		destroy = function()
+			serviceBag:Destroy()
+			for _, inst in instances do
+				pcall(function()
+					inst:Destroy()
+				end)
+			end
+			container:Destroy()
+		end,
+	}
+end
+
+describe("BinderUtils.findFirstAncestor()", function()
+	it("returns the nearest bound ancestor, skipping the child itself", function()
+		local env = setup()
+
+		local grandparent = env.newInstance()
+		local parent = env.newInstance(grandparent)
+		local child = env.newInstance(parent)
+
+		local binder = env.newBinder()
+		binder:Tag(grandparent)
+		binder:Tag(child) -- child is bound too, but must be skipped
+		env.boot()
+
+		expect(BinderUtils.findFirstAncestor(binder, child)).toEqual(binder:Get(grandparent))
+
+		env.destroy()
+	end)
+
+	it("returns nil when no ancestor is bound", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local child = env.newInstance(parent)
+		local binder = env.newBinder()
+		env.boot()
+
+		expect(BinderUtils.findFirstAncestor(binder, child)).toBeNil()
+
+		env.destroy()
+	end)
+
+	it("throws for a non-instance child", function()
+		local env = setup()
+
+		local binder = env.newBinder()
+		env.boot()
+		expect(function()
+			BinderUtils.findFirstAncestor(binder, 5 :: any)
+		end).toThrow()
+
+		env.destroy()
+	end)
+end)
+
+describe("BinderUtils.findFirstChild()", function()
+	it("returns the first bound child", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local unboundChild = env.newInstance(parent)
+		local boundChild = env.newInstance(parent)
+
+		local binder = env.newBinder()
+		binder:Tag(boundChild)
+		env.boot()
+
+		expect(BinderUtils.findFirstChild(binder, parent)).toEqual(binder:Get(boundChild))
+		expect(binder:Get(unboundChild)).toBeNil()
+
+		env.destroy()
+	end)
+
+	it("returns nil when no child is bound", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		env.newInstance(parent)
+		local binder = env.newBinder()
+		env.boot()
+
+		expect(BinderUtils.findFirstChild(binder, parent)).toBeNil()
+
+		env.destroy()
+	end)
+end)
+
+describe("BinderUtils.getChildren()", function()
+	it("returns every bound child", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local childA = env.newInstance(parent)
+		local childB = env.newInstance(parent)
+		env.newInstance(parent) -- unbound
+
+		local binder = env.newBinder()
+		binder:Tag(childA)
+		binder:Tag(childB)
+		env.boot()
+
+		expect(#BinderUtils.getChildren(binder, parent)).toEqual(2)
+
+		env.destroy()
+	end)
+
+	it("does not include bound descendants deeper than one level", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local child = env.newInstance(parent)
+		local grandchild = env.newInstance(child)
+
+		local binder = env.newBinder()
+		binder:Tag(grandchild)
+		env.boot()
+
+		expect(#BinderUtils.getChildren(binder, parent)).toEqual(0)
+
+		env.destroy()
+	end)
+end)
+
+describe("BinderUtils.getDescendants()", function()
+	it("returns bound instances at any depth", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local child = env.newInstance(parent)
+		local grandchild = env.newInstance(child)
+
+		local binder = env.newBinder()
+		binder:Tag(child)
+		binder:Tag(grandchild)
+		env.boot()
+
+		expect(#BinderUtils.getDescendants(binder, parent)).toEqual(2)
+
+		env.destroy()
+	end)
+end)
+
+describe("BinderUtils.mapBinderListToTable()", function()
+	it("keys binders by their tag", function()
+		local env = setup()
+
+		local binderA = env.newBinder()
+		local binderB = env.newBinder()
+		env.boot()
+
+		local map = BinderUtils.mapBinderListToTable({ binderA, binderB })
+		expect(map[binderA:GetTag()]).toEqual(binderA)
+		expect(map[binderB:GetTag()]).toEqual(binderB)
+
+		env.destroy()
+	end)
+end)
+
+describe("BinderUtils.getMappedFromList()", function()
+	it("resolves bound values across an instance list by tag", function()
+		local env = setup()
+
+		local instA = env.newInstance()
+		local instB = env.newInstance()
+		local binderA = env.newBinder()
+		local binderB = env.newBinder()
+		binderA:Tag(instA)
+		binderB:Tag(instB)
+		env.boot()
+
+		local tagsMap = BinderUtils.mapBinderListToTable({ binderA, binderB })
+		local objects = BinderUtils.getMappedFromList(tagsMap, { instA, instB, env.newInstance() })
+
+		expect(#objects).toEqual(2)
+
+		env.destroy()
+	end)
+end)
+
+describe("BinderUtils.getChildrenOfBinders()", function()
+	it("returns children bound by any binder in the list", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local childA = env.newInstance(parent)
+		local childB = env.newInstance(parent)
+
+		local binderA = env.newBinder()
+		local binderB = env.newBinder()
+		binderA:Tag(childA)
+		binderB:Tag(childB)
+		env.boot()
+
+		expect(#BinderUtils.getChildrenOfBinders({ binderA, binderB }, parent)).toEqual(2)
+
+		env.destroy()
+	end)
+end)
+
+describe("BinderUtils.getLinkedChildren()", function()
+	it("resolves bound targets of matching ObjectValue links", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local target = env.newInstance()
+		local binder = env.newBinder()
+		binder:Tag(target)
+
+		local link = env.newInstance(parent, "ObjectValue") :: ObjectValue
+		link.Name = "Link"
+		link.Value = target
+		env.boot()
+
+		local objects = BinderUtils.getLinkedChildren(binder, "Link", parent)
+		expect(#objects).toEqual(1)
+		expect(objects[1]).toEqual(binder:Get(target))
+
+		env.destroy()
+	end)
+
+	it("ignores links whose name does not match", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local target = env.newInstance()
+		local binder = env.newBinder()
+		binder:Tag(target)
+
+		local link = env.newInstance(parent, "ObjectValue") :: ObjectValue
+		link.Name = "OtherLink"
+		link.Value = target
+		env.boot()
+
+		expect(#BinderUtils.getLinkedChildren(binder, "Link", parent)).toEqual(0)
+
+		env.destroy()
+	end)
+
+	it("deduplicates when two links point to the same bound target", function()
+		local env = setup()
+
+		local parent = env.newInstance()
+		local target = env.newInstance()
+		local binder = env.newBinder()
+		binder:Tag(target)
+
+		for _ = 1, 2 do
+			local link = env.newInstance(parent, "ObjectValue") :: ObjectValue
+			link.Name = "Link"
+			link.Value = target
+		end
+		env.boot()
+
+		expect(#BinderUtils.getLinkedChildren(binder, "Link", parent)).toEqual(1)
+
+		env.destroy()
+	end)
+end)