@quenty/datastore 13.40.0 → 13.42.0

package/src/Server/Modules/DataStoreWriter.spec.lua

@@ -0,0 +1,399 @@
+--!nonstrict
+--[[
+	Characterization coverage for DataStoreWriter's merge/diff/write API -- what actually gets
+	persisted when new data, delete tokens, and nested sub-writers are layered onto an original.
+	@class DataStoreWriter.spec.lua
+]]
+local require = require(script.Parent.loader).load(script)
+
+local DataStoreDeleteToken = require("DataStoreDeleteToken")
+local DataStoreWriter = require("DataStoreWriter")
+local Jest = require("Jest")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+-- Recursively freeze so snapshots satisfy the "must be frozen" asserts on Set*Snapshot.
+local function deepFreeze<T>(tab: T): T
+	if type(tab) == "table" and not table.isfrozen(tab :: any) then
+		for _, value in tab :: any do
+			deepFreeze(value)
+		end
+		table.freeze(tab :: any)
+	end
+	return tab
+end
+
+describe("DataStoreWriter.new", function()
+	it("should construct with a debugName and expose the ClassName", function()
+		local writer = DataStoreWriter.new("test")
+
+		expect(writer).never.toBeNil()
+		expect(writer.ClassName).toEqual("DataStoreWriter")
+	end)
+
+	it("should error when constructed without a debugName", function()
+		expect(function()
+			DataStoreWriter.new()
+		end).toThrow("No debugName")
+	end)
+
+	it("should start with empty/unset state", function()
+		local writer = DataStoreWriter.new("test")
+
+		expect(writer:GetDataToSave()).toBeNil()
+		expect(writer:GetUserIdList()).toBeNil()
+		expect(writer:GetSubWritersMap()).toEqual({})
+		expect(writer:IsCompleteWipe()).toEqual(false)
+	end)
+end)
+
+describe("DataStoreWriter:SetSaveDataSnapshot / GetDataToSave", function()
+	it("should store and return a scalar save value", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetSaveDataSnapshot(5)
+
+		expect(writer:GetDataToSave()).toEqual(5)
+	end)
+
+	it("should store a boolean save value (false is not treated as unset)", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetSaveDataSnapshot(false)
+
+		expect(writer:GetDataToSave()).toEqual(false)
+	end)
+
+	it("should deep-copy a frozen table snapshot rather than storing the reference", function()
+		local writer = DataStoreWriter.new("test")
+		local source = table.freeze({ coins = 5, gems = 3 })
+		writer:SetSaveDataSnapshot(source)
+
+		expect(writer:GetDataToSave()).toEqual({ coins = 5, gems = 3 })
+		expect((writer:GetDataToSave() == source)).toEqual(false)
+	end)
+
+	it("should deep-copy nested tables inside the snapshot", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetSaveDataSnapshot(deepFreeze({ stats = { hp = 10, mp = 5 } }))
+
+		expect(writer:GetDataToSave()).toEqual({ stats = { hp = 10, mp = 5 } })
+	end)
+
+	it("should reject an unfrozen table snapshot", function()
+		local writer = DataStoreWriter.new("test")
+
+		expect(function()
+			writer:SetSaveDataSnapshot({ coins = 5 })
+		end).toThrow("saveDataSnapshot should be frozen")
+	end)
+
+	it("should store the delete token as a complete wipe", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetSaveDataSnapshot(DataStoreDeleteToken)
+
+		expect((writer:GetDataToSave() == DataStoreDeleteToken)).toEqual(true)
+		expect(writer:IsCompleteWipe()).toEqual(true)
+	end)
+end)
+
+describe("DataStoreWriter:IsCompleteWipe", function()
+	it("should be false when unset", function()
+		local writer = DataStoreWriter.new("test")
+		expect(writer:IsCompleteWipe()).toEqual(false)
+	end)
+
+	it("should be false for a scalar save value", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetSaveDataSnapshot(5)
+		expect(writer:IsCompleteWipe()).toEqual(false)
+	end)
+
+	it("should be true only for the delete token", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetSaveDataSnapshot(DataStoreDeleteToken)
+		expect(writer:IsCompleteWipe()).toEqual(true)
+	end)
+end)
+
+describe("DataStoreWriter:AddSubWriter / GetWriter / GetSubWritersMap", function()
+	it("should register and retrieve a sub-writer by string name", function()
+		local parent = DataStoreWriter.new("parent")
+		local child = DataStoreWriter.new("child")
+		parent:AddSubWriter("inventory", child)
+
+		expect((parent:GetWriter("inventory") == child)).toEqual(true)
+		expect((parent:GetSubWritersMap()["inventory"] == child)).toEqual(true)
+	end)
+
+	it("should return nil for an unknown sub-writer name", function()
+		local parent = DataStoreWriter.new("parent")
+		expect(parent:GetWriter("missing")).toBeNil()
+	end)
+
+	it("should error when adding two writers under the same name", function()
+		local parent = DataStoreWriter.new("parent")
+		parent:AddSubWriter("inventory", DataStoreWriter.new("a"))
+
+		expect(function()
+			parent:AddSubWriter("inventory", DataStoreWriter.new("b"))
+		end).toThrow("Writer already exists for name")
+	end)
+
+	it("should error when adding a nil writer", function()
+		local parent = DataStoreWriter.new("parent")
+		expect(function()
+			parent:AddSubWriter("inventory", nil)
+		end).toThrow("Bad writer")
+	end)
+
+	it("should error when the name is neither string nor number", function()
+		local parent = DataStoreWriter.new("parent")
+		expect(function()
+			parent:AddSubWriter({}, DataStoreWriter.new("child"))
+		end).toThrow("Bad name")
+	end)
+
+	it("should accept a numeric name but leave it unreachable through GetWriter", function()
+		-- Sharp edge: AddSubWriter permits number keys, yet GetWriter asserts a string name.
+		local parent = DataStoreWriter.new("parent")
+		local child = DataStoreWriter.new("child")
+		parent:AddSubWriter(1, child)
+
+		expect((parent:GetSubWritersMap()[1] == child)).toEqual(true)
+		expect(function()
+			parent:GetWriter(1)
+		end).toThrow("Bad name")
+	end)
+end)
+
+describe("DataStoreWriter:SetUserIdList / GetUserIdList", function()
+	it("should round-trip a user id list", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetUserIdList({ 1, 2, 3 })
+
+		expect(writer:GetUserIdList()).toEqual({ 1, 2, 3 })
+	end)
+
+	it("should return nil before a list is set", function()
+		local writer = DataStoreWriter.new("test")
+		expect(writer:GetUserIdList()).toBeNil()
+	end)
+
+	it("should allow clearing the list back to nil", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetUserIdList({ 1 })
+		writer:SetUserIdList(nil)
+
+		expect(writer:GetUserIdList()).toBeNil()
+	end)
+
+	it("should reject a non-table user id list", function()
+		local writer = DataStoreWriter.new("test")
+		expect(function()
+			writer:SetUserIdList(5)
+		end).toThrow("Bad userIdList")
+	end)
+end)
+
+describe("DataStoreWriter:SetFullBaseDataSnapshot", function()
+	it("should accept a frozen table", function()
+		local writer = DataStoreWriter.new("test")
+		expect(function()
+			writer:SetFullBaseDataSnapshot(table.freeze({ coins = 5 }))
+		end).never.toThrow()
+	end)
+
+	it("should reject an unfrozen table", function()
+		local writer = DataStoreWriter.new("test")
+		expect(function()
+			writer:SetFullBaseDataSnapshot({ coins = 5 })
+		end).toThrow("fullBaseDataSnapshot should be frozen")
+	end)
+
+	it("should reject the delete token", function()
+		local writer = DataStoreWriter.new("test")
+		expect(function()
+			writer:SetFullBaseDataSnapshot(DataStoreDeleteToken)
+		end).toThrow("fullBaseDataSnapshot should not be symbol")
+	end)
+end)
+
+describe("DataStoreWriter:WriteMerge", function()
+	it("should return the original unchanged when nothing is staged", function()
+		local writer = DataStoreWriter.new("test")
+
+		expect((writer:WriteMerge(5))).toEqual(5)
+		expect((writer:WriteMerge(nil))).toBeNil()
+		expect((writer:WriteMerge({ coins = 1 }))).toEqual({ coins = 1 })
+	end)
+
+	it("should return the delete token when the save is a complete wipe", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetSaveDataSnapshot(DataStoreDeleteToken)
+
+		expect((writer:WriteMerge({ coins = 1 }) == DataStoreDeleteToken)).toEqual(true)
+	end)
+
+	it("should replace the original entirely with a scalar save value", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetSaveDataSnapshot(10)
+
+		expect((writer:WriteMerge({ coins = 1 }))).toEqual(10)
+		expect((writer:WriteMerge(nil))).toEqual(10)
+	end)
+
+	it("should merge a table save on top of the original, keeping untouched keys", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetSaveDataSnapshot(table.freeze({ coins = 5 }))
+
+		expect((writer:WriteMerge({ coins = 1, gems = 2 }))).toEqual({ coins = 5, gems = 2 })
+	end)
+
+	it("should remove a key when the save carries a delete token for it", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetSaveDataSnapshot(table.freeze({ coins = DataStoreDeleteToken }))
+
+		expect((writer:WriteMerge({ coins = 1, gems = 2 }))).toEqual({ gems = 2 })
+	end)
+
+	it("should swap a scalar original to a table when the save is a table", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetSaveDataSnapshot(table.freeze({ coins = 5 }))
+
+		expect((writer:WriteMerge(5))).toEqual({ coins = 5 })
+	end)
+
+	it("should treat an empty table save as a no-op merge", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetSaveDataSnapshot(table.freeze({}))
+
+		expect((writer:WriteMerge({ coins = 1 }))).toEqual({ coins = 1 })
+	end)
+
+	it("should not mutate the original table passed in", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetSaveDataSnapshot(table.freeze({ coins = 5 }))
+		local original = { coins = 1, gems = 2 }
+		writer:WriteMerge(original)
+
+		expect(original).toEqual({ coins = 1, gems = 2 })
+	end)
+end)
+
+describe("DataStoreWriter:WriteMerge with sub-writers", function()
+	it("should merge a nested sub-writer's save into its key", function()
+		local parent = DataStoreWriter.new("parent")
+		local child = DataStoreWriter.new("child")
+		child:SetSaveDataSnapshot(table.freeze({ sword = true }))
+		parent:AddSubWriter("inventory", child)
+
+		local result = parent:WriteMerge({ coins = 5, inventory = { shield = true } })
+		expect(result).toEqual({ coins = 5, inventory = { shield = true, sword = true } })
+	end)
+
+	it("should remove the key when a sub-writer resolves to a delete token", function()
+		local parent = DataStoreWriter.new("parent")
+		local child = DataStoreWriter.new("child")
+		child:SetSaveDataSnapshot(DataStoreDeleteToken)
+		parent:AddSubWriter("inventory", child)
+
+		local result = parent:WriteMerge({ coins = 5, inventory = { x = 1 } })
+		expect(result).toEqual({ coins = 5 })
+	end)
+
+	it("should build up a table from a scalar original when sub-writers are present", function()
+		local parent = DataStoreWriter.new("parent")
+		local child = DataStoreWriter.new("child")
+		child:SetSaveDataSnapshot(table.freeze({ a = 1 }))
+		parent:AddSubWriter("sub", child)
+
+		expect((parent:WriteMerge(5))).toEqual({ sub = { a = 1 } })
+	end)
+end)
+
+describe("DataStoreWriter:ComputeDiffSnapshot", function()
+	it("should emit only the changed key against the base", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetFullBaseDataSnapshot(table.freeze({ coins = 5, gems = 3 }))
+
+		expect((writer:ComputeDiffSnapshot({ coins = 5, gems = 10 }))).toEqual({ gems = 10 })
+	end)
+
+	it("should emit a delete token for a key removed from the incoming data", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetFullBaseDataSnapshot(table.freeze({ coins = 5 }))
+
+		local diff = writer:ComputeDiffSnapshot({})
+		expect((diff.coins == DataStoreDeleteToken)).toEqual(true)
+	end)
+
+	it("should emit a newly added key", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetFullBaseDataSnapshot(table.freeze({ coins = 5 }))
+
+		expect((writer:ComputeDiffSnapshot({ coins = 5, gems = 1 }))).toEqual({ gems = 1 })
+	end)
+
+	it("should return nil when the incoming table matches the base", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetFullBaseDataSnapshot(table.freeze({ coins = 5 }))
+
+		expect((writer:ComputeDiffSnapshot({ coins = 5 }))).toBeNil()
+	end)
+
+	it("should diff nested tables and emit only the changed leaf", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetFullBaseDataSnapshot(deepFreeze({ stats = { hp = 10, mp = 5 } }))
+
+		expect((writer:ComputeDiffSnapshot({ stats = { hp = 10, mp = 8 } }))).toEqual({ stats = { mp = 8 } })
+	end)
+
+	it("should return a frozen diff snapshot", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetFullBaseDataSnapshot(table.freeze({ coins = 5 }))
+
+		expect((table.isfrozen(writer:ComputeDiffSnapshot({ coins = 10 })))).toEqual(true)
+	end)
+
+	it("should treat an empty incoming with no base or writers as a full delete", function()
+		local writer = DataStoreWriter.new("test")
+
+		expect((writer:ComputeDiffSnapshot({}) == DataStoreDeleteToken)).toEqual(true)
+	end)
+
+	it("should recurse into sub-writers, diffing against their own base", function()
+		local parent = DataStoreWriter.new("parent")
+		parent:SetFullBaseDataSnapshot(table.freeze({ coins = 5 }))
+
+		local child = DataStoreWriter.new("child")
+		child:SetFullBaseDataSnapshot(table.freeze({ sword = true }))
+		parent:AddSubWriter("inv", child)
+
+		local diff = parent:ComputeDiffSnapshot({ coins = 5, inv = { sword = true, shield = true } })
+		expect(diff).toEqual({ inv = { shield = true } })
+	end)
+
+	it("should diff a scalar incoming against a scalar base", function()
+		local writer = DataStoreWriter.new("test")
+		writer:SetFullBaseDataSnapshot(5)
+
+		expect((writer:ComputeDiffSnapshot(5))).toBeNil()
+		expect((writer:ComputeDiffSnapshot(10))).toEqual(10)
+	end)
+
+	it("should reject the delete token as incoming", function()
+		local writer = DataStoreWriter.new("test")
+		expect(function()
+			writer:ComputeDiffSnapshot(DataStoreDeleteToken)
+		end).toThrow("Incoming value should not be DataStoreDeleteToken")
+	end)
+
+	it("should throw on a scalar incoming when the base is unset", function()
+		-- Sharp edge: the unset sentinel is a symbol, and the scalar path asserts non-symbol.
+		local writer = DataStoreWriter.new("test")
+		expect(function()
+			writer:ComputeDiffSnapshot(5)
+		end).toThrow("original should not be symbol")
+	end)
+end)

package/src/Server/PlayerDataStoreManager.RemovalCallbacks.spec.lua

@@ -0,0 +1,99 @@
+--!nonstrict
+--[[
+	How a misbehaving removing callback affects (a) whether the player's data is saved on leave, and
+	(b) whether the session lock is released. SaveAndCloseSession is what releases the lock, so when
+	it is skipped the departing session's lock lingers until it goes stale. Several of these are
+	genuine data-integrity failure modes, so pinning them documents the contract callers must honor.
+
+	@class PlayerDataStoreManager.RemovalCallbacks.spec.lua
+]]
+local require = require(script.Parent.loader).load(script)
+
+local DataStoreTestUtils = require("DataStoreTestUtils")
+local Jest = require("Jest")
+local Promise = require("Promise")
+local PromiseTestUtils = require("PromiseTestUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("PlayerDataStoreManager removal matrix (misbehaving removing callbacks)", function()
+	it("well-behaved callback: saves the data AND releases the lock", function()
+		local controller = DataStoreTestUtils.setupDataStoreManager()
+		controller.manager:AddRemovingCallback(function()
+			return Promise.resolved()
+		end)
+
+		expect(controller.storeAndAwaitLock()).toEqual(true)
+		controller.manager:RemovePlayerDataStore(1)
+
+		expect(PromiseTestUtils.awaitValue(function()
+			local raw = controller.mock:GetRaw("user_1")
+			return raw ~= nil and raw.coins == 5
+		end, 10)).toEqual(true)
+		-- SaveAndCloseSession stripped the lock as it wrote.
+		expect(controller.mock:GetRaw("user_1").lock).toEqual(nil)
+
+		controller:destroy()
+	end)
+
+	describe("failure modes", function()
+		it("rejecting callback: skips the save (data loss) AND leaves the lock held", function()
+			local controller = DataStoreTestUtils.setupDataStoreManager()
+			controller.manager:AddRemovingCallback(function()
+				return Promise.rejected("removing callback failed")
+			end)
+
+			expect(controller.storeAndAwaitLock()).toEqual(true)
+			controller.manager:RemovePlayerDataStore(1)
+
+			-- The rejected callback short-circuits PromiseUtils.all before SaveAndCloseSession: coins are
+			-- never persisted, and the lock is never released.
+			expect(PromiseTestUtils.awaitValue(function()
+				local raw = controller.mock:GetRaw("user_1")
+				return raw ~= nil and raw.coins == 5
+			end, 3)).toEqual(false)
+			expect(controller.mock:GetRaw("user_1").lock ~= nil).toEqual(true)
+
+			controller:destroy()
+		end)
+
+		it("throwing callback: the synchronous throw escapes removal (lock held, stuck)", function()
+			local controller = DataStoreTestUtils.setupDataStoreManager()
+			controller.manager:AddRemovingCallback(function()
+				error("removing callback boom")
+			end)
+
+			expect(controller.storeAndAwaitLock()).toEqual(true)
+
+			-- There is no pcall around removing callbacks, so a synchronous throw escapes removal entirely.
+			expect(function()
+				controller.manager:RemovePlayerDataStore(1)
+			end).toThrow("removing callback boom")
+			expect(controller.mock:GetRaw("user_1").lock ~= nil).toEqual(true)
+
+			controller:destroy()
+		end)
+
+		it("yielding callback: removal blocks forever (no save, lock held)", function()
+			local controller = DataStoreTestUtils.setupDataStoreManager()
+			controller.manager:AddRemovingCallback(function()
+				return Promise.new()
+			end)
+
+			expect(controller.storeAndAwaitLock()).toEqual(true)
+			controller.manager:RemovePlayerDataStore(1)
+
+			-- SaveAndCloseSession is gated behind the yielding callback, so neither the save nor the lock
+			-- release ever happen.
+			expect(PromiseTestUtils.awaitValue(function()
+				local raw = controller.mock:GetRaw("user_1")
+				return raw ~= nil and raw.coins == 5
+			end, 2)).toEqual(false)
+			expect(controller.mock:GetRaw("user_1").lock ~= nil).toEqual(true)
+
+			controller:destroy()
+		end)
+	end)
+end)

package/src/Server/PlayerDataStoreManager.lua

@@ -55,6 +55,7 @@ local Players = game:GetService("Players")
 local RunService = game:GetService("RunService")
 
 local BaseObject = require("BaseObject")
+local BindToCloseService = require("BindToCloseService")
 local DataStore = require("DataStore")
 local Maid = require("Maid")
 local PendingPromiseTracker = require("PendingPromiseTracker")
@@ -90,6 +91,9 @@ export type PlayerDataStoreManager =
 --[=[
 	Constructs a new PlayerDataStoreManager.
 
+	Unless `skipBindingToClose` is true, this resolves [BindToCloseService] from the serviceBag to
+	save on game close, so that service must be registered before the serviceBag starts.
+
 	@param robloxDataStore DataStore
 	@param keyGenerator (player) -> string -- Function that takes in a player, and outputs a key
 	@param skipBindingToClose boolean?
@@ -125,19 +129,47 @@ function PlayerDataStoreManager.new(
 		self:_removePlayerDataStore(player.UserId)
 	end))
 
+	-- On teardown (e.g. a hot-reloaded ServiceBag, or unit tests) flush and destroy any datastores we
+	-- still own. See _flushAndDestroyAll.
+	self._maid:GiveTask(function()
+		self:_flushAndDestroyAll()
+	end)
+
 	if skipBindingToClose ~= true then
-		game:BindToClose(function()
+		-- Route through BindToCloseService so the callback is unregistered on :Destroy()
+		-- (unlike a raw game:BindToClose, which can never be unbound and would leak on hot reload).
+		local bindToCloseService = self._serviceBag:GetService(BindToCloseService) :: any
+		self._maid:GiveTask(bindToCloseService:RegisterPromiseOnCloseCallback(function()
 			if self._disableSavingInStudio then
-				return
+				return Promise.resolved()
 			end
 
-			self:PromiseAllSaves():Wait()
-		end)
+			return self:PromiseAllSaves()
+		end))
 	end
 
 	return self
 end
 
+--[=[
+	Flushes and tears down every datastore we still own. Runs on manager teardown (a hot-reloaded
+	ServiceBag, or a unit test). Save() is a best-effort synchronous write: the underlying UpdateAsync
+	request is dispatched before Destroy() cancels the promise, so a live server usually honors it, but
+	it is not guaranteed. A store whose load failed rejects, so the rejection is swallowed. Stores handed
+	off gracefully via _removePlayerDataStore have already been pulled out of _datastores, so this only
+	covers the ones nothing else cleaned up.
+]=]
+function PlayerDataStoreManager._flushAndDestroyAll(self: PlayerDataStoreManager): ()
+	for userId, datastore in self._datastores do
+		-- Cast past the DataStore intersection type: the solver otherwise blows up ("code too complex")
+		-- resolving :Save()/:Destroy() through it.
+		local store = datastore :: any
+		store:Save():Catch(function() end)
+		store:Destroy()
+		self._datastores[userId] = nil
+	end
+end
+
 --[=[
 	For if you want to disable saving in studio for faster close time!
 ]=]