@quenty/datastore 13.40.0 → 13.42.0

package/src/Server/PlayerDataStoreManager.spec.lua

@@ -0,0 +1,202 @@
+--!nonstrict
+--[[
+	Integration coverage for PlayerDataStoreManager against a mocked Roblox datastore. The manager
+	auto-enables session locking and session messaging on every DataStore it creates, so even a load
+	does an UpdateAsync round-trip through the mock. Tests use numeric userIds, never real Players.
+
+	@class PlayerDataStoreManager.spec.lua
+]]
+local require = require(script.Parent.loader).load(script)
+
+local DataStoreTestUtils = require("DataStoreTestUtils")
+local Jest = require("Jest")
+local PromiseTestUtils = require("PromiseTestUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+-- Asserts the promise settled within the timeout and returns whether it is now safe to :Yield(), so
+-- a hung promise fails the test instead of freezing the runner.
+local function expectSettled(promise, timeout: number?): boolean
+	local settled = PromiseTestUtils.awaitSettled(promise, timeout)
+	expect(settled).toEqual(true)
+	return settled
+end
+
+describe("PlayerDataStoreManager.GetDataStore", function()
+	it("should return a datastore for a fresh user", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		local dataStore = controller.manager:GetDataStore(1)
+		expect(dataStore).never.toBeNil()
+
+		controller:destroy()
+	end)
+
+	it("should cache the datastore per user", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		local first = controller.manager:GetDataStore(1)
+		local second = controller.manager:GetDataStore(1)
+		expect(first).toEqual(second)
+
+		local other = controller.manager:GetDataStore(2)
+		expect((first == other)).toEqual(false)
+
+		controller:destroy()
+	end)
+
+	it("should apply the key generator", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		local dataStore = controller.manager:GetDataStore(1)
+		expect((dataStore:GetKey())).toEqual("user_1")
+
+		controller:destroy()
+	end)
+end)
+
+describe("PlayerDataStoreManager.PromiseDataStore", function()
+	it("should resolve the datastore and load successfully against a healthy mock", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		local promise = controller.manager:PromiseDataStore(1)
+		if not expectSettled(promise, 10) then
+			controller:destroy()
+			return
+		end
+
+		local ok, dataStore = promise:Yield()
+		expect(ok).toEqual(true)
+		expect(dataStore).never.toBeNil()
+
+		local loadPromise = dataStore:PromiseLoadSuccessful()
+		if not expectSettled(loadPromise, 10) then
+			controller:destroy()
+			return
+		end
+		expect((loadPromise:Wait())).toEqual(true)
+
+		controller:destroy()
+	end)
+end)
+
+describe("PlayerDataStoreManager persistence", function()
+	it("should round-trip a stored value across a removal/reload", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		local dataStore = controller.manager:GetDataStore(1)
+		dataStore:Store("coins", 5)
+
+		-- Removal saves (SaveAndCloseSession) then closes the session, asynchronously.
+		controller.manager:RemovePlayerDataStore(1)
+
+		-- PromiseDataStore waits for the in-progress removal to finish before handing back a
+		-- fresh datastore for the same user.
+		local promise = controller.manager:PromiseDataStore(1)
+		if not expectSettled(promise, 10) then
+			controller:destroy()
+			return
+		end
+
+		local ok, reloaded = promise:Yield()
+		expect(ok).toEqual(true)
+
+		local loadPromise = reloaded:Load("coins")
+		if not expectSettled(loadPromise, 10) then
+			controller:destroy()
+			return
+		end
+
+		local loadOk, value = loadPromise:Yield()
+		expect(loadOk).toEqual(true)
+		expect(value).toEqual(5)
+
+		controller:destroy()
+	end)
+end)
+
+describe("PlayerDataStoreManager.AddRemovingCallback", function()
+	it("should invoke the removing callback when a user's datastore is removed", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		local ran = false
+		controller.manager:AddRemovingCallback(function()
+			ran = true
+		end)
+
+		controller.manager:GetDataStore(1)
+
+		-- Drain the removal to be sure the callback fired.
+		local promise = controller.manager:PromiseAllSaves()
+		if not expectSettled(promise, 10) then
+			controller:destroy()
+			return
+		end
+		expect((promise:Yield())).toEqual(true)
+
+		expect(ran).toEqual(true)
+
+		controller:destroy()
+	end)
+end)
+
+describe("PlayerDataStoreManager.PromiseAllSaves", function()
+	it("should resolve after removing all datastores and flushing pending saves", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		controller.manager:GetDataStore(1):Store("coins", 1)
+		controller.manager:GetDataStore(2):Store("coins", 2)
+
+		local promise = controller.manager:PromiseAllSaves()
+		if not expectSettled(promise, 10) then
+			controller:destroy()
+			return
+		end
+		expect((promise:Yield())).toEqual(true)
+
+		controller:destroy()
+	end)
+end)
+
+describe("PlayerDataStoreManager teardown", function()
+	it("destroys the datastores it still owns when the manager is destroyed", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		local dataStore = controller.manager:GetDataStore(1)
+		if not expectSettled(dataStore:PromiseLoadSuccessful(), 10) then
+			controller:destroy()
+			return
+		end
+
+		controller.manager:Destroy()
+
+		-- BaseObject.Destroy clears the metatable, so a torn-down store reads a nil metatable.
+		expect(getmetatable(dataStore)).toBeNil()
+
+		controller:destroy()
+	end)
+
+	it("flushes staged data synchronously to the underlying store when destroyed", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+
+		local dataStore = controller.manager:GetDataStore(1)
+		if not expectSettled(dataStore:PromiseLoadSuccessful(), 10) then
+			controller:destroy()
+			return
+		end
+
+		dataStore:Store("coins", 5)
+
+		-- Destroy must fire a synchronous Save before tearing each store down, so the staged value is
+		-- already persisted the instant Destroy() returns -- asserted with no awaiting.
+		controller.manager:Destroy()
+
+		local raw = controller.mock:GetRaw("user_1")
+		expect(raw).never.toBeNil()
+		expect(raw.coins).toEqual(5)
+
+		controller:destroy()
+	end)
+end)

package/src/Server/PlayerDataStoreService.lua

@@ -27,6 +27,7 @@ export type PlayerDataStoreService = typeof(setmetatable(
 		_dataStoreManagerPromise: Promise.Promise<PlayerDataStoreManager.PlayerDataStoreManager>,
 		_bindToCloseService: any,
 		_promiseStarted: Promise.Promise<()>,
+		_robloxDataStoreOverride: any?,
 	},
 	{} :: typeof({ __index = PlayerDataStoreService })
 ))
@@ -91,6 +92,20 @@ function PlayerDataStoreService.SetDataStoreScope(self: PlayerDataStoreService,
 	self._dataStoreScope = dataStoreScope
 end
 
+--[=[
+	Injects the underlying datastore the manager wraps, instead of resolving a real one. Accepts
+	a real datastore or a [DataStoreMock]. Intended for testing; must be called before the manager
+	is first built.
+
+	@param robloxDataStore DataStore | DataStoreMock
+]=]
+function PlayerDataStoreService.SetRobloxDataStore(self: PlayerDataStoreService, robloxDataStore: any): ()
+	assert(DataStorePromises.isDataStore(robloxDataStore), "Bad robloxDataStore")
+	assert(not self._dataStoreManagerPromise, "Already built manager, cannot override")
+
+	self._robloxDataStoreOverride = robloxDataStore
+end
+
 --[=[
 	Gets the datastore for the player.
 
@@ -138,6 +153,9 @@ function PlayerDataStoreService.PromiseManager(
 
 	self._dataStoreManagerPromise = self._promiseStarted
 		:Then(function()
+			if self._robloxDataStoreOverride then
+				return self._robloxDataStoreOverride
+			end
 			return DataStorePromises.promiseDataStore(self._dataStoreName, self._dataStoreScope)
 		end)
 		:Then(function(dataStore)

package/src/Server/PlayerDataStoreService.spec.lua

@@ -0,0 +1,218 @@
+--!nonstrict
+--[[
+	Integration coverage for PlayerDataStoreService, the ServiceBag-driven wrapper around one
+	PlayerDataStoreManager, with the underlying datastore injected via the SetRobloxDataStore test
+	seam. The manager auto-enables session locking, so even a load does an UpdateAsync round-trip
+	through the mock. Tests use numeric userIds, never real Players.
+
+	@class PlayerDataStoreService.spec.lua
+]]
+local require = require(script.Parent.loader).load(script)
+
+local DataStoreMock = require("DataStoreMock")
+local Jest = require("Jest")
+local Maid = require("Maid")
+local PromiseTestUtils = require("PromiseTestUtils")
+local ServiceBag = require("ServiceBag")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function setup(mock)
+	local maid = Maid.new()
+
+	local serviceBag = maid:Add(ServiceBag.new())
+	local service = serviceBag:GetService(require("PlayerDataStoreService"))
+	serviceBag:Init()
+
+	if mock then
+		service:SetRobloxDataStore(mock)
+		serviceBag:Start()
+	end
+
+	return {
+		service = service,
+		mock = mock,
+		destroy = function()
+			maid:DoCleaning()
+		end,
+	}
+end
+
+describe("PlayerDataStoreService.PromiseDataStore", function()
+	it("should resolve a datastore and load successfully against a healthy mock", function()
+		local controller = setup(DataStoreMock.new())
+
+		local promise = controller.service:PromiseDataStore(1)
+		if not PromiseTestUtils.awaitSettled(promise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+
+		local ok, dataStore = promise:Yield()
+		expect(ok).toEqual(true)
+		expect(dataStore).never.toBeNil()
+
+		local loadPromise = dataStore:PromiseLoadSuccessful()
+		if not PromiseTestUtils.awaitSettled(loadPromise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		expect((loadPromise:Wait())).toEqual(true)
+
+		controller:destroy()
+	end)
+end)
+
+describe("PlayerDataStoreService configuration guards", function()
+	it("should throw when SetDataStoreName is called after start", function()
+		local controller = setup(DataStoreMock.new())
+
+		expect(function()
+			controller.service:SetDataStoreName("X")
+		end).toThrow("Already started, cannot configure")
+
+		controller:destroy()
+	end)
+
+	it("should throw when SetDataStoreScope is called after start", function()
+		local controller = setup(DataStoreMock.new())
+
+		expect(function()
+			controller.service:SetDataStoreScope("X")
+		end).toThrow("Already started, cannot configure")
+
+		controller:destroy()
+	end)
+
+	it("should throw when SetRobloxDataStore is called after the manager is built", function()
+		local controller = setup(DataStoreMock.new())
+
+		-- Building the manager (via PromiseDataStore) locks out further overrides.
+		local promise = controller.service:PromiseDataStore(1)
+		if not PromiseTestUtils.awaitSettled(promise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+
+		expect(function()
+			controller.service:SetRobloxDataStore(controller.mock)
+		end).toThrow("Already built manager")
+
+		controller:destroy()
+	end)
+
+	it("should throw when SetRobloxDataStore is given a bad datastore", function()
+		local controller = setup()
+
+		expect(function()
+			controller.service:SetRobloxDataStore(nil)
+		end).toThrow("Bad robloxDataStore")
+
+		expect(function()
+			controller.service:SetRobloxDataStore({})
+		end).toThrow("Bad robloxDataStore")
+
+		controller:destroy()
+	end)
+end)
+
+describe("PlayerDataStoreService.PromiseAddRemovingCallback", function()
+	it("should resolve after registering the removing callback", function()
+		local controller = setup(DataStoreMock.new())
+
+		local promise = controller.service:PromiseAddRemovingCallback(function() end)
+		if not PromiseTestUtils.awaitSettled(promise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		expect((promise:Yield())).toEqual(true)
+
+		controller:destroy()
+	end)
+end)
+
+describe("PlayerDataStoreService failure handling", function()
+	it("surfaces a datastore failure to the player fast instead of hanging", function()
+		local mock = DataStoreMock.new()
+		mock:FailAllRequests()
+
+		local controller = setup(mock)
+
+		-- PromiseDataStore resolves synchronously; the session-locked load underneath is what must
+		-- settle rather than hang against a failing datastore.
+		local promise = controller.service:PromiseDataStore(1)
+		if not PromiseTestUtils.awaitSettled(promise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+
+		local ok, dataStore = promise:Yield()
+		expect(ok).toEqual(true)
+		expect(dataStore).never.toBeNil()
+
+		local loadPromise = dataStore:PromiseLoadSuccessful()
+		expect(PromiseTestUtils.awaitSettled(loadPromise, 5)).toEqual(true)
+		expect((loadPromise:Wait())).toEqual(false)
+
+		controller:destroy()
+	end)
+end)
+
+describe("PlayerDataStoreService teardown", function()
+	it("destroys the datastore its manager owns when the service is destroyed", function()
+		local controller = setup(DataStoreMock.new())
+
+		local promise = controller.service:PromiseDataStore(1)
+		if not PromiseTestUtils.awaitSettled(promise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		local _ok, dataStore = promise:Yield()
+
+		if not PromiseTestUtils.awaitSettled(dataStore:PromiseLoadSuccessful(), 10) then
+			expect("load hung").toEqual("load settled")
+			controller:destroy()
+			return
+		end
+
+		controller:destroy()
+
+		expect(getmetatable(dataStore)).toBeNil()
+	end)
+
+	it("flushes staged data synchronously to the underlying store when destroyed", function()
+		local controller = setup(DataStoreMock.new())
+
+		local promise = controller.service:PromiseDataStore(1)
+		if not PromiseTestUtils.awaitSettled(promise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		local _ok, dataStore = promise:Yield()
+
+		if not PromiseTestUtils.awaitSettled(dataStore:PromiseLoadSuccessful(), 10) then
+			expect("load hung").toEqual("load settled")
+			controller:destroy()
+			return
+		end
+
+		dataStore:Store("coins", 7)
+
+		-- Destroy must fire a synchronous Save before tearing the store down.
+		controller:destroy()
+
+		-- keyGenerator maps userId 1 -> "1"
+		local raw = controller.mock:GetRaw("1")
+		expect(raw).never.toBeNil()
+		expect(raw.coins).toEqual(7)
+	end)
+end)

package/src/Server/PrivateServerDataStoreService.lua

@@ -51,7 +51,7 @@ function PrivateServerDataStoreService.PromiseDataStore(
 	end
 
 	self._dataStorePromise = self:_promiseRobloxDataStore():Then(function(robloxDataStore)
-		local dataStore = self._maid:Add(DataStore.new(robloxDataStore, self:_getKey()))
+		local dataStore = DataStore.new(robloxDataStore, self:_getKey())
 
 		if game.PrivateServerOwnerId ~= 0 then
 			dataStore:Store("LastPrivateServerOwnerId", game.PrivateServerOwnerId)
@@ -61,6 +61,14 @@ function PrivateServerDataStoreService.PromiseDataStore(
 			return dataStore:Save()
 		end))
 
+		-- On service teardown (hot reload / tests) flush and destroy the store. Save() is a best-effort
+		-- synchronous write before Destroy() cancels it.
+		self._maid:GiveTask(function()
+			-- Best-effort: swallow a rejection (e.g. the load failed) so it is not uncaught.
+			dataStore:Save():Catch(function() end)
+			dataStore:Destroy()
+		end)
+
 		return dataStore
 	end)
 	assert(self._dataStorePromise, "Typechecking assertion")
@@ -77,6 +85,20 @@ function PrivateServerDataStoreService.SetCustomKey(self: PrivateServerDataStore
 	self._customKey = customKey
 end
 
+--[=[
+	Injects the underlying datastore to use instead of resolving a real one. Accepts a real
+	datastore or a [DataStoreMock]. Intended for testing; must be called before the datastore
+	is first resolved.
+
+	@param robloxDataStore DataStore | DataStoreMock
+]=]
+function PrivateServerDataStoreService.SetRobloxDataStore(self: PrivateServerDataStoreService, robloxDataStore: any): ()
+	assert(DataStorePromises.isDataStore(robloxDataStore), "Bad robloxDataStore")
+	assert(not self._robloxDataStorePromise, "Already resolved robloxDataStore, cannot override")
+
+	self._robloxDataStorePromise = Promise.resolved(robloxDataStore)
+end
+
 function PrivateServerDataStoreService._promiseRobloxDataStore(
 	self: PrivateServerDataStoreService
 ): Promise.Promise<any>