@quenty/servicebag 11.19.0 → 11.20.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [11.20.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/servicebag@11.19.0...@quenty/servicebag@11.20.0) (2026-07-23)
+
+### Features
+
+- Add baseline player-mock and support across Nevermore for mocked players. ([567d121](https://github.com/Quenty/NevermoreEngine/commit/567d121ffc014b42391554088189a1a6296dda83))
+
 # [11.19.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/servicebag@11.18.1...@quenty/servicebag@11.19.0) (2026-07-18)
 
 **Note:** Version bump only for package @quenty/servicebag

package/deploy.nevermore.json

@@ -0,0 +1,10 @@
+{
+  "targets": {
+    "test": {
+      "universeId": 9716264427,
+      "placeId": 107599629424361,
+      "project": "test/default.project.json",
+      "scriptTemplate": "test/scripts/Server/ServerMain.server.lua"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/servicebag",
-  "version": "11.19.0",
+  "version": "11.20.0",
   "description": "Service providing mechanisms for Nevermore",
   "keywords": [
     "Roblox",
@@ -29,12 +29,14 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/baseobject": "10.14.0",
+    "@quenty/baseobject": "10.15.0",
     "@quenty/loader": "10.11.0",
-    "@quenty/signal": "7.13.1"
+    "@quenty/nevermore-test-runner": "1.5.0",
+    "@quenty/signal": "7.13.1",
+    "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "647acfad93dca41c38f59cda247d2bfc0fff36d4"
+  "gitHead": "1de37218a2bedb8e3f8614a2e09bba9eddc812da"
 }

package/src/Shared/ServiceBag.lua

@@ -58,6 +58,7 @@ export type ServiceBag =
 			_parentProvider: ServiceBag?,
 			_serviceTypesToInitializeSet: { [any]: true }?,
 			_initializedServiceTypeSet: { [any]: true },
+			_initializedServiceTypeList: { any },
 			_serviceTypesToStartSet: { [any]: true }?,
 
 			_initRunAllowed: boolean,
@@ -85,6 +86,7 @@ function ServiceBag.new(parentProvider: ServiceBag?): ServiceBag
 
 	self._serviceTypesToInitializeSet = {}
 	self._initializedServiceTypeSet = {}
+	self._initializedServiceTypeList = {}
 	self._serviceTypesToStartSet = {}
 
 	self._initRunAllowed = false
@@ -345,6 +347,9 @@ function ServiceBag._initService(self: ServiceBag, serviceType)
 		end
 	end
 
+	-- Init-completion order is a valid dependency order (a service's dependencies finish
+	-- initializing before it does, via the GetService recursion), so record it for teardown.
+	table.insert(self._initializedServiceTypeList, serviceType)
 	table.insert(self._serviceTypesToStartSet, serviceType)
 end
 
@@ -371,30 +376,48 @@ end
 
 function ServiceBag._destructServices(self: ServiceBag)
 	local services = self._services
+
+	-- Destroy in reverse initialization order, so dependents tear down before the dependencies
+	-- they may still be writing to (see _initService: init-completion order is a dependency order).
+	local initializedList = self._initializedServiceTypeList
+	for index = #initializedList, 1, -1 do
+		local serviceType = initializedList[index]
+		local service = services[serviceType]
+		if service ~= nil then
+			services[serviceType] = nil
+			self:_destructService(serviceType, service)
+		end
+	end
+
+	-- Anything left never finished initializing; destroy it in arbitrary order, as before.
 	local serviceType, service = next(services)
 	while service ~= nil do
 		services[serviceType] = nil
 
 		if not (self._serviceTypesToInitializeSet and self._serviceTypesToInitializeSet[serviceType]) then
-			local serviceName = self:_getServiceName(serviceType)
+			self:_destructService(serviceType, service)
+		end
 
-			local current
-			task.spawn(function()
-				debug.setmemorycategory(serviceName)
-				current = coroutine.running()
+		serviceType, service = next(services)
+	end
+end
 
-				if service.Destroy then
-					service:Destroy()
-				end
-			end)
+function ServiceBag._destructService(self: ServiceBag, serviceType, service)
+	local serviceName = self:_getServiceName(serviceType)
 
-			local isDead = coroutine.status(current) == "dead"
-			if not isDead then
-				warn(debug.traceback(current, string.format("Destroying service %q yielded", serviceName)))
-			end
+	local current
+	task.spawn(function()
+		debug.setmemorycategory(serviceName)
+		current = coroutine.running()
+
+		if service.Destroy then
+			service:Destroy()
 		end
+	end)
 
-		serviceType, service = next(services)
+	local isDead = coroutine.status(current) == "dead"
+	if not isDead then
+		warn(debug.traceback(current, string.format("Destroying service %q yielded", serviceName)))
 	end
 end
 

package/src/Shared/ServiceBag.spec.lua

@@ -0,0 +1,296 @@
+--!strict
+--[[
+	Pins ServiceBag lifecycle behavior: registration, recursive dependency initialization, start,
+	the lifecycle guards, per-bag isolation, and teardown.
+
+	The "destruction order" describe is the repro for dependents outliving their dependencies:
+	destruction must run in reverse initialization order, so a service destroyed mid-teardown can
+	still write to the dependencies it resolved in Init (the way PlayerTelemetry queues its leave
+	point into InfluxDBService). Destruction that walks the service map in hash order fails these.
+
+	@class ServiceBag.spec.lua
+]]
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local ServiceBag = require("ServiceBag")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+-- Builds a named service definition that records its lifecycle into the shared `events` list as
+-- "<name>.<init|start|destroy>". `initDependencies` are resolved via GetService during Init,
+-- mirroring how real services acquire their dependencies.
+local function makeService(name: string, events: { string }, initDependencies: { any }?)
+	local serviceDefinition = {}
+	serviceDefinition.ServiceName = name
+	serviceDefinition._serviceBag = nil :: any
+
+	function serviceDefinition:Init(serviceBag)
+		self._serviceBag = serviceBag
+
+		if initDependencies then
+			for _, dependency in initDependencies do
+				serviceBag:GetService(dependency)
+			end
+		end
+
+		table.insert(events, name .. ".init")
+	end
+
+	function serviceDefinition:Start()
+		table.insert(events, name .. ".start")
+	end
+
+	function serviceDefinition:Destroy()
+		table.insert(events, name .. ".destroy")
+	end
+
+	return serviceDefinition
+end
+
+local function filterSuffix(events: { string }, suffix: string): { string }
+	local found = {}
+	for _, event in events do
+		if string.sub(event, -#suffix) == suffix then
+			table.insert(found, (string.gsub(event, "%" .. suffix .. "$", "")))
+		end
+	end
+	return found
+end
+
+describe("ServiceBag lifecycle", function()
+	it("initializes and starts a registered service exactly once", function()
+		local events = {}
+		local serviceBag = ServiceBag.new()
+		local definition = makeService("Solo", events)
+
+		serviceBag:GetService(definition)
+		serviceBag:Init()
+		serviceBag:Start()
+
+		expect(events).toEqual({ "Solo.init", "Solo.start" })
+
+		serviceBag:Destroy()
+	end)
+
+	it("passes the bag itself to Init", function()
+		local events = {}
+		local serviceBag = ServiceBag.new()
+		local definition = makeService("Solo", events)
+
+		local service = serviceBag:GetService(definition)
+		serviceBag:Init()
+		serviceBag:Start()
+
+		expect(service._serviceBag).toBe(serviceBag)
+
+		serviceBag:Destroy()
+	end)
+
+	it("returns the same isolated instance per bag", function()
+		local events = {}
+		local definition = makeService("Shared", events)
+
+		local bagA = ServiceBag.new()
+		local bagB = ServiceBag.new()
+		local serviceA = bagA:GetService(definition)
+		local serviceB = bagB:GetService(definition)
+
+		expect(bagA:GetService(definition)).toBe(serviceA)
+		expect(serviceA).never.toBe(serviceB)
+
+		bagA:Destroy()
+		bagB:Destroy()
+	end)
+
+	it("completes a dependency's Init before the dependent's Init completes", function()
+		local events = {}
+		local sink = makeService("Sink", events)
+		local dependent = makeService("Dependent", events, { sink })
+
+		local serviceBag = ServiceBag.new()
+		serviceBag:GetService(dependent)
+		serviceBag:Init()
+		serviceBag:Start()
+
+		expect(filterSuffix(events, ".init")).toEqual({ "Sink", "Dependent" })
+
+		serviceBag:Destroy()
+	end)
+
+	it("initializes a transitive dependency chain leaf-first", function()
+		local events = {}
+		local leaf = makeService("Leaf", events)
+		local middle = makeService("Middle", events, { leaf })
+		local root = makeService("Root", events, { middle })
+
+		local serviceBag = ServiceBag.new()
+		serviceBag:GetService(root)
+		serviceBag:Init()
+		serviceBag:Start()
+
+		expect(filterSuffix(events, ".init")).toEqual({ "Leaf", "Middle", "Root" })
+
+		serviceBag:Destroy()
+	end)
+end)
+
+describe("ServiceBag guards", function()
+	it("reports HasService without registering", function()
+		local events = {}
+		local definition = makeService("Queried", events)
+		local serviceBag = ServiceBag.new()
+
+		expect(serviceBag:HasService(definition)).toBe(false)
+
+		serviceBag:GetService(definition)
+		expect(serviceBag:HasService(definition)).toBe(true)
+
+		serviceBag:Destroy()
+	end)
+
+	it("errors when adding a new service after start", function()
+		local events = {}
+		local serviceBag = ServiceBag.new()
+		serviceBag:Init()
+		serviceBag:Start()
+
+		expect(function()
+			serviceBag:GetService(makeService("Late", events))
+		end).toThrow("Already started")
+
+		serviceBag:Destroy()
+	end)
+
+	it("errors when querying a service after destroy", function()
+		local events = {}
+		local serviceBag = ServiceBag.new()
+		serviceBag:Init()
+		serviceBag:Start()
+		serviceBag:Destroy()
+
+		expect(function()
+			serviceBag:GetService(makeService("PostMortem", events))
+		end).toThrow()
+	end)
+
+	it("errors when starting before initializing", function()
+		local serviceBag = ServiceBag.new()
+
+		expect(function()
+			serviceBag:Start()
+		end).toThrow()
+
+		serviceBag:Destroy()
+	end)
+end)
+
+describe("ServiceBag destruction order", function()
+	it("destroys every service on bag destroy", function()
+		local events = {}
+		local serviceBag = ServiceBag.new()
+		serviceBag:GetService(makeService("First", events))
+		serviceBag:GetService(makeService("Second", events))
+		serviceBag:Init()
+		serviceBag:Start()
+
+		serviceBag:Destroy()
+
+		local destroyed = filterSuffix(events, ".destroy")
+		table.sort(destroyed)
+		expect(destroyed).toEqual({ "First", "Second" })
+	end)
+
+	it("destroys a dependency chain in reverse initialization order", function()
+		-- Repeat with fresh bags: hash-ordered destruction can pass any single arrangement by luck.
+		for _ = 1, 5 do
+			local events = {}
+			local leaf = makeService("Leaf", events)
+			local middle = makeService("Middle", events, { leaf })
+			local root = makeService("Root", events, { middle })
+
+			local serviceBag = ServiceBag.new()
+			serviceBag:GetService(root)
+			serviceBag:Init()
+			serviceBag:Start()
+
+			serviceBag:Destroy()
+
+			expect(filterSuffix(events, ".destroy")).toEqual({ "Root", "Middle", "Leaf" })
+		end
+	end)
+
+	it("destroys services in reverse of their recorded initialization order", function()
+		for _ = 1, 3 do
+			local events = {}
+			local serviceBag = ServiceBag.new()
+
+			local sink = makeService("Sink", events)
+			for index = 1, 6 do
+				serviceBag:GetService(makeService("Dependent" .. index, events, { sink }))
+			end
+
+			serviceBag:Init()
+			serviceBag:Start()
+			serviceBag:Destroy()
+
+			local initOrder = filterSuffix(events, ".init")
+			local destroyOrder = filterSuffix(events, ".destroy")
+
+			local expectedDestroyOrder = {}
+			for index = #initOrder, 1, -1 do
+				table.insert(expectedDestroyOrder, initOrder[index])
+			end
+
+			expect(destroyOrder).toEqual(expectedDestroyOrder)
+		end
+	end)
+
+	it("lets a dependent write into its dependency during teardown", function()
+		-- The PlayerTelemetry/InfluxDBService shape: on Destroy, a dependent flushes into the sink
+		-- it resolved during Init. The sink must still be alive to accept the write.
+		for _ = 1, 5 do
+			local writesAccepted = 0
+			local writesDropped = 0
+
+			local sink = {}
+			sink.ServiceName = "WriteSink"
+			function sink:Init(_serviceBag)
+				self._destroyed = false
+			end
+			function sink:Write()
+				if self._destroyed then
+					writesDropped += 1
+				else
+					writesAccepted += 1
+				end
+			end
+			function sink:Destroy()
+				self._destroyed = true
+			end
+
+			local serviceBag = ServiceBag.new()
+
+			for index = 1, 6 do
+				local dependent = {}
+				dependent.ServiceName = "Writer" .. index
+				function dependent:Init(bag)
+					self._sink = bag:GetService(sink)
+				end
+				function dependent:Destroy()
+					self._sink:Write()
+				end
+				serviceBag:GetService(dependent)
+			end
+
+			serviceBag:Init()
+			serviceBag:Start()
+			serviceBag:Destroy()
+
+			expect(writesDropped).toBe(0)
+			expect(writesAccepted).toBe(6)
+		end
+	end)
+end)

package/src/jest.config.lua

@@ -0,0 +1,3 @@
+return {
+	testMatch = { "**/*.spec" },
+}

package/test/default.project.json

@@ -0,0 +1,25 @@
+{
+  "name": "ServiceBagTest",
+  "globIgnorePaths": [
+    "**/.package-lock.json",
+    "**/.pnpm",
+    "**/.pnpm-workspace-state-v1.json",
+    "**/.modules.yaml",
+    "**/.ignored",
+    "**/.ignored_*"
+  ],
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "$properties": {
+        "LoadStringEnabled": true
+      },
+      "servicebag": {
+        "$path": ".."
+      },
+      "Script": {
+        "$path": "scripts/Server"
+      }
+    }
+  }
+}

package/test/scripts/Server/ServerMain.server.lua

@@ -0,0 +1,13 @@
+--[[
+	@class ServerMain
+]]
+local ServerScriptService = game:GetService("ServerScriptService")
+
+local root = ServerScriptService.servicebag
+local loader = root:FindFirstChild("LoaderUtils", true).Parent
+local require = require(loader).bootstrapGame(root)
+
+local NevermoreTestRunnerUtils = require("NevermoreTestRunnerUtils")
+if NevermoreTestRunnerUtils.runTestsIfNeededAsync(root) then
+	return
+end