@quenty/binder 14.39.0 → 14.41.0

package/src/Shared/BinderGroup.spec.lua

@@ -0,0 +1,151 @@
+--!strict
+--[[
+	@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 controller = setup()
+
+		local binderA = controller.newBinder()
+		local binderB = controller.newBinder()
+		local group = BinderGroup.new({ binderA, binderB })
+
+		expect(#group:GetBinders()).toEqual(2)
+
+		controller.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 controller = setup()
+
+		local group = BinderGroup.new({})
+		local binder = controller.newBinder()
+		group:Add(binder)
+
+		expect(group:GetBinders()[1]).toEqual(binder)
+
+		controller.destroy()
+	end)
+
+	it("fires BinderAdded with the added binder", function()
+		local controller = setup()
+
+		local group = BinderGroup.new({})
+		local fired
+		group.BinderAdded:Connect(function(binder)
+			fired = binder
+		end)
+
+		local binder = controller.newBinder()
+		group:Add(binder)
+
+		expect(fired).toEqual(binder)
+
+		controller.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 controller = setup()
+
+		local validated = {}
+		local group = BinderGroup.new({}, function(constructor)
+			table.insert(validated, constructor)
+			return true
+		end)
+
+		local binder = controller.newBinder()
+		group:Add(binder)
+
+		expect(validated[1]).toEqual(binder:GetConstructor())
+
+		controller.destroy()
+	end)
+
+	it("throws when the constructor fails validation", function()
+		local controller = setup()
+
+		local group = BinderGroup.new({}, function()
+			return false
+		end)
+
+		local binder = controller.newBinder()
+		expect(function()
+			group:Add(binder)
+		end).toThrow()
+
+		controller.destroy()
+	end)
+end)
+
+describe("BinderGroup:AddList()", function()
+	it("adds each binder in the list", function()
+		local controller = setup()
+
+		local group = BinderGroup.new({})
+		group:AddList({ controller.newBinder(), controller.newBinder() })
+
+		expect(#group:GetBinders()).toEqual(2)
+
+		controller.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/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