@quenty/datastore 13.39.1 → 13.41.0

package/src/Server/DataStoreLockHelper.spec.lua

@@ -0,0 +1,239 @@
+--!nonstrict
+--[[
+	Characterization coverage for DataStore session locking, exercised through a real DataStore
+	against a mocked Roblox datastore. It pins the observable behaviour of the lock lifecycle: a
+	healthy acquire wraps the stored profile in a lock envelope, SaveAndCloseSession releases it,
+	user data survives a lock/unlock round-trip, and a stale lock left by a dead session is stolen.
+
+	@class DataStoreLockHelper.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
+
+describe("DataStore session locking", function()
+	it("wraps the stored profile in a lock envelope on a healthy acquire", function()
+		local controller = DataStoreTestUtils.setup()
+
+		local dataStore = controller.newDataStore()
+		dataStore:SetSessionLockingEnabled(true)
+		dataStore:SetUserIdList({ 1 })
+
+		local promise = dataStore:PromiseLoadSuccessful()
+		if not PromiseTestUtils.awaitSettled(promise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+
+		local ok, loadedOk = promise:Yield()
+		expect(ok).toEqual(true)
+		expect(loadedOk).toEqual(true)
+
+		local raw = controller.mock:GetRaw("player_1")
+		expect(type(raw)).toEqual("table")
+		expect(type(raw.lock)).toEqual("table")
+		expect(raw.lock.ActiveSession).never.toBeNil()
+		expect(raw.lock.ActiveSession.SessionId).toEqual(dataStore:GetSessionId())
+
+		controller:destroy()
+	end)
+
+	it("releases the lock on SaveAndCloseSession so a new session can load", function()
+		local controller = DataStoreTestUtils.setup()
+
+		local sessionA = controller.newDataStore()
+		sessionA:SetSessionLockingEnabled(true)
+		sessionA:SetUserIdList({ 1 })
+
+		local loadA = sessionA:PromiseLoadSuccessful()
+		if not PromiseTestUtils.awaitSettled(loadA, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		expect((loadA:Yield())).toEqual(true)
+
+		local closePromise = sessionA:SaveAndCloseSession()
+		if not PromiseTestUtils.awaitSettled(closePromise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		expect((closePromise:Yield())).toEqual(true)
+
+		-- Closing strips the lock envelope back off the stored value.
+		local raw = controller.mock:GetRaw("player_1")
+		expect(type(raw)).toEqual("table")
+		expect(raw.lock).toEqual(nil)
+
+		local sessionB = controller.newDataStore()
+		sessionB:SetSessionLockingEnabled(true)
+		sessionB:SetUserIdList({ 1 })
+
+		local loadB = sessionB:PromiseLoadSuccessful()
+		if not PromiseTestUtils.awaitSettled(loadB, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		expect((loadB:Yield())).toEqual(true)
+
+		controller:destroy()
+	end)
+
+	it("preserves user data across a lock/unlock round-trip", function()
+		local controller = DataStoreTestUtils.setup()
+
+		local sessionA = controller.newDataStore()
+		sessionA:SetSessionLockingEnabled(true)
+		sessionA:SetUserIdList({ 1 })
+		sessionA:Store("coins", 5)
+
+		local closePromise = sessionA:SaveAndCloseSession()
+		if not PromiseTestUtils.awaitSettled(closePromise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		expect((closePromise:Yield())).toEqual(true)
+
+		local sessionB = controller.newDataStore()
+		sessionB:SetSessionLockingEnabled(true)
+		sessionB:SetUserIdList({ 1 })
+
+		local loadPromise = sessionB:Load("coins")
+		if not PromiseTestUtils.awaitSettled(loadPromise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+
+		local ok, value = loadPromise:Yield()
+		expect(ok).toEqual(true)
+		expect(value).toEqual(5)
+
+		controller:destroy()
+	end)
+
+	it("steals a stale lock left by a dead session", function()
+		local controller = DataStoreTestUtils.setup()
+
+		-- Seed a lock owned by a long-dead session. LastUpdateTime is far enough in the past that
+		-- os.time() - LastUpdateTime exceeds GetAutoSaveTimeSeconds() * 2.1 (default 300 * 2.1 = 630s),
+		-- so the lock is stolen on the first acquire attempt (no retry backoff). Seed user data too,
+		-- to prove it survives the steal.
+		controller.mock:SetRaw("player_1", {
+			coins = 7,
+			lock = {
+				LastUpdateTime = os.time() - 1000000,
+				ActiveSession = {
+					SessionId = "stale-session-id",
+					PlaceId = 987654321,
+					JobId = "stale-job-id",
+				},
+			},
+		})
+
+		local dataStore = controller.newDataStore()
+		dataStore:SetSessionLockingEnabled(true)
+		dataStore:SetUserIdList({ 1 })
+
+		local promise = dataStore:PromiseLoadSuccessful()
+		if not PromiseTestUtils.awaitSettled(promise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		expect((promise:Yield())).toEqual(true)
+
+		local raw = controller.mock:GetRaw("player_1")
+		expect(raw.lock.ActiveSession.SessionId).toEqual(dataStore:GetSessionId())
+
+		-- The dead session's user data survived the steal.
+		local loadPromise = dataStore:Load("coins")
+		if not PromiseTestUtils.awaitSettled(loadPromise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		expect((loadPromise:Wait())).toEqual(7)
+
+		controller:destroy()
+	end)
+
+	it("fires SessionStolen when saving over a lock held by another session", function()
+		local controller = DataStoreTestUtils.setup()
+
+		local dataStore = controller.newDataStore()
+		dataStore:SetSessionLockingEnabled(true)
+		dataStore:SetUserIdList({ 1 })
+
+		local loadPromise = dataStore:PromiseLoadSuccessful()
+		if not PromiseTestUtils.awaitSettled(loadPromise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		expect((loadPromise:Yield())).toEqual(true)
+
+		-- Another session steals the lock out from under us directly in the datastore.
+		controller.mock:SetRaw("player_1", {
+			coins = 1,
+			lock = {
+				LastUpdateTime = os.time(),
+				ActiveSession = {
+					SessionId = "thief-session-id",
+					PlaceId = 111222333,
+					JobId = "thief-job-id",
+				},
+			},
+		})
+
+		local stolenBy = nil
+		dataStore.SessionStolen:Connect(function(session)
+			stolenBy = session
+		end)
+
+		dataStore:Store("coins", 2)
+		local savePromise = dataStore:Save()
+		if not PromiseTestUtils.awaitSettled(savePromise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+
+		expect(stolenBy).never.toBeNil()
+		expect(stolenBy.SessionId).toEqual("thief-session-id")
+
+		controller:destroy()
+	end)
+
+	it("surfaces a locked-load datastore failure fast instead of hanging", function()
+		local controller = DataStoreTestUtils.setup()
+		controller.mock:FailAllRequests()
+
+		local dataStore = controller.newDataStore()
+		dataStore:SetSessionLockingEnabled(true)
+		dataStore:SetUserIdList({ 1 })
+
+		local promise = dataStore:PromiseLoadSuccessful()
+		if not PromiseTestUtils.awaitSettled(promise, 5) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+
+		local ok, loadedOk = promise:Yield()
+		expect(ok).toEqual(true)
+		expect(loadedOk).toEqual(false)
+
+		controller:destroy()
+	end)
+end)

package/src/Server/DataStoreMessageHelper.spec.lua

@@ -0,0 +1,134 @@
+--!nonstrict
+--[[
+	Coverage for DataStoreMessageHelper, the coordinator that drives graceful cross-server
+	session-close over MessagingService. The full request/complete handshake needs a second server
+	to answer, so cross-server behaviour is characterized rather than asserted; what a single server
+	can verify (construction, the "cannot message self" guard, messaging wiring, and the
+	MessagingServiceUtils.toHumanReadable formatter) is exercised here.
+
+	@class DataStoreMessageHelper.spec.lua
+]]
+local require = require(script.Parent.loader).load(script)
+
+local DataStoreMessageHelper = require("DataStoreMessageHelper")
+local DataStoreTestUtils = require("DataStoreTestUtils")
+local Jest = require("Jest")
+local MessagingServiceUtils = require("MessagingServiceUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("DataStoreMessageHelper.new", function()
+	it("should construct against a real ServiceBag and DataStore", function()
+		local controller = DataStoreTestUtils.setup()
+		local helper = controller.newMessageHelper()
+
+		expect(helper).never.toBeNil()
+
+		controller:destroy()
+	end)
+
+	it("should expose the ServiceBag it was built with", function()
+		local controller = DataStoreTestUtils.setup()
+		local helper = controller.newMessageHelper()
+
+		expect((helper:GetServiceBag() == controller.serviceBag)).toEqual(true)
+
+		controller:destroy()
+	end)
+
+	it("should reject a nil serviceBag", function()
+		local controller = DataStoreTestUtils.setup()
+		local dataStore = controller.newDataStore()
+
+		expect(function()
+			DataStoreMessageHelper.new(nil, dataStore)
+		end).toThrow("No serviceBag")
+
+		controller:destroy()
+	end)
+
+	it("should not error on construct then Destroy", function()
+		local controller = DataStoreTestUtils.setup()
+		local helper = controller.newMessageHelper()
+
+		-- The test destroys the helper itself; the maid then skips it, so there is no double-Destroy.
+		expect(function()
+			helper:Destroy()
+		end).never.toThrow()
+
+		controller:destroy()
+	end)
+end)
+
+describe("DataStoreMessageHelper.PromiseSendSessionMessage", function()
+	it("should refuse to message its own session synchronously", function()
+		local controller = DataStoreTestUtils.setup()
+		local helper, dataStore = controller.newMessageHelper()
+
+		local ownSessionId = dataStore:GetSessionId()
+		expect(function()
+			helper:PromiseSendSessionMessage(1, "job", ownSessionId, {
+				type = "close-session",
+				requesterSessionId = ownSessionId,
+			})
+		end).toThrow("Cannot message self")
+
+		controller:destroy()
+	end)
+end)
+
+describe("DataStoreMessageHelper.PromiseCloseSessionGraceful", function()
+	it("should return a promise (cross-server outcome is not unit-testable single-server)", function()
+		-- The graceful handshake needs a second server to answer, so we only assert it returns a
+		-- promise; its settlement is environment dependent and covered by real multi-server usage.
+		local controller = DataStoreTestUtils.setup()
+		local helper = controller.newMessageHelper()
+
+		local promise = helper:PromiseCloseSessionGraceful(1, "some-other-job", "some-other-session")
+		expect(promise).never.toBeNil()
+
+		controller:destroy()
+	end)
+end)
+
+describe("DataStore.SetSessionMessagingEnabled wiring", function()
+	it("should enable then disable session messaging without erroring", function()
+		local controller = DataStoreTestUtils.setup()
+		local dataStore = controller.newDataStore()
+		-- Messaging is documented to work alongside session locking; enable both like real usage.
+		dataStore:SetSessionLockingEnabled(true)
+		dataStore:SetUserIdList({ 1 })
+
+		expect(function()
+			dataStore:SetSessionMessagingEnabled(true, controller.serviceBag)
+		end).never.toThrow()
+
+		expect(function()
+			dataStore:SetSessionMessagingEnabled(false)
+		end).never.toThrow()
+
+		controller:destroy()
+	end)
+end)
+
+describe("MessagingServiceUtils.toHumanReadable", function()
+	it("should JSON-encode a table message", function()
+		local result = MessagingServiceUtils.toHumanReadable({
+			type = "close-session",
+			requesterSessionId = "abc",
+		})
+
+		expect((type(result))).toEqual("string")
+		-- JSON key order is not guaranteed, so pin the shape, not the exact string.
+		expect((string.sub(result, 1, 1))).toEqual("{")
+	end)
+
+	it("should stringify a non-table message", function()
+		expect((MessagingServiceUtils.toHumanReadable(5))).toEqual("5")
+		expect((MessagingServiceUtils.toHumanReadable("hi"))).toEqual("hi")
+		expect((MessagingServiceUtils.toHumanReadable(true))).toEqual("true")
+		expect((MessagingServiceUtils.toHumanReadable(nil))).toEqual("nil")
+	end)
+end)

package/src/Server/DataStoreNonRetryableLoadError.lua

@@ -0,0 +1,61 @@
+--!strict
+--[=[
+	Wraps a datastore-operation failure during a session-locked load so it is distinguishable from
+	lock contention. Op failures (e.g. 509) will not resolve by retrying -- Roblox already retries
+	internally -- so we fail fast rather than grinding the acquire backoff, while lock contention (a
+	successful op that returns a locked profile) keeps retrying. The original error is preserved.
+
+	@server
+	@class DataStoreNonRetryableLoadError
+]=]
+
+local DataStoreNonRetryableLoadError = {}
+DataStoreNonRetryableLoadError.ClassName = "DataStoreNonRetryableLoadError"
+DataStoreNonRetryableLoadError.__index = DataStoreNonRetryableLoadError
+
+export type DataStoreNonRetryableLoadError = typeof(setmetatable(
+	{} :: {
+		innerError: any,
+	},
+	DataStoreNonRetryableLoadError
+))
+
+function DataStoreNonRetryableLoadError.__tostring(self: DataStoreNonRetryableLoadError): string
+	return tostring(self.innerError)
+end
+
+--[=[
+	Wraps an inner error so it is treated as non-retryable during a session-locked load.
+
+	@param innerError any
+	@return DataStoreNonRetryableLoadError
+]=]
+function DataStoreNonRetryableLoadError.new(innerError: any): DataStoreNonRetryableLoadError
+	return setmetatable({ innerError = innerError }, DataStoreNonRetryableLoadError)
+end
+
+--[=[
+	Returns true if the given error is a [DataStoreNonRetryableLoadError].
+
+	@param err any
+	@return boolean
+]=]
+function DataStoreNonRetryableLoadError.isNonRetryableLoadError(err: any): boolean
+	return type(err) == "table" and getmetatable(err) == DataStoreNonRetryableLoadError
+end
+
+--[=[
+	Returns the original inner error if the given error is a [DataStoreNonRetryableLoadError],
+	otherwise returns the error unchanged.
+
+	@param err any
+	@return any
+]=]
+function DataStoreNonRetryableLoadError.unwrapLoadError(err: any): any
+	if DataStoreNonRetryableLoadError.isNonRetryableLoadError(err) then
+		return err.innerError
+	end
+	return err
+end
+
+return DataStoreNonRetryableLoadError

package/src/Server/DataStoreTestUtils.lua

@@ -0,0 +1,206 @@
+--!nonstrict
+--[=[
+	Shared setup helpers for the DataStore server specs. The two controller builders --
+	[DataStoreTestUtils.setup] (raw DataStores) and [DataStoreTestUtils.setupDataStoreManager]
+	(a [PlayerDataStoreManager]) -- each own a [Maid] and register everything they create on it, so a
+	single `controller:destroy()` tears it all down: the stores, the auto-save loop each starts once
+	loaded, the helpers, the manager, and the service bag.
+
+	@class DataStoreTestUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local DataStore = require("DataStore")
+local DataStoreLockHelper = require("DataStoreLockHelper")
+local DataStoreMessageHelper = require("DataStoreMessageHelper")
+local DataStoreMock = require("DataStoreMock")
+local Maid = require("Maid")
+local MessagingServiceMock = require("MessagingServiceMock")
+local PlayerDataStoreManager = require("PlayerDataStoreManager")
+local PromiseTestUtils = require("PromiseTestUtils")
+local ServiceBag = require("ServiceBag")
+
+local DataStoreTestUtils = {}
+
+--[=[
+	Builds the controller the DataStore specs share: a fresh [DataStoreMock], a [ServiceBag] with an
+	in-process [MessagingServiceMock] injected (so messaging-enabled stores never touch the real
+	MessagingService), and builder methods that own everything they create on one Maid. `destroy()`
+	tears it all down. Every builder defaults its key to `"player_1"`; pass a key to override.
+
+	Fields: `mock`, `serviceBag`.
+	Builders: `newDataStore(key?)`, `newSessionLockedStore(key?, userIdList?)`, `newLockHelper(key?)`
+	(returns `helper, dataStore`), `newMessageHelper(dataStore?)` (returns `helper, dataStore`),
+	`newServer(opts?)` (returns `dataStore, helper?`; `opts` = `{ key?, messaging?, autoCloseOnRequest? }`).
+	Helpers: `awaitOwn(dataStore)` -> boolean (loads and reports whether we own the session).
+
+	@return { ... }
+]=]
+function DataStoreTestUtils.setup()
+	local maid = Maid.new()
+
+	local mock = DataStoreMock.new()
+	local serviceBag = DataStoreTestUtils.newServiceBag(maid, MessagingServiceMock.new())
+
+	local function newDataStore(key)
+		return DataStoreTestUtils.newDataStore(maid, mock, key or "player_1")
+	end
+
+	local function newSessionLockedStore(key, userIdList)
+		return DataStoreTestUtils.newSessionLockedStore(maid, mock, key or "player_1", userIdList)
+	end
+
+	local function newLockHelper(key)
+		local dataStore = newDataStore(key)
+		local helper = maid:Add(DataStoreLockHelper.new(dataStore))
+		return helper, dataStore
+	end
+
+	local function newMessageHelper(dataStore)
+		dataStore = dataStore or newDataStore()
+		return DataStoreTestUtils.newMessageHelper(maid, serviceBag, dataStore), dataStore
+	end
+
+	local function newServer(opts)
+		opts = opts or {}
+		local dataStore = newSessionLockedStore(opts.key)
+		local helper
+		if opts.messaging then
+			dataStore:SetSessionMessagingEnabled(true, serviceBag)
+			helper = newMessageHelper(dataStore)
+		end
+		if opts.autoCloseOnRequest then
+			dataStore.SessionCloseRequested:Connect(function()
+				dataStore:SaveAndCloseSession()
+			end)
+		end
+		return dataStore, helper
+	end
+
+	local function awaitOwn(dataStore)
+		local promise = dataStore:PromiseLoadSuccessful()
+		if not PromiseTestUtils.awaitSettled(promise, 10) then
+			return false
+		end
+		local ok, loadedOk = promise:Yield()
+		return ok and loadedOk
+	end
+
+	return {
+		mock = mock,
+		serviceBag = serviceBag,
+		newDataStore = newDataStore,
+		newSessionLockedStore = newSessionLockedStore,
+		newLockHelper = newLockHelper,
+		newMessageHelper = newMessageHelper,
+		newServer = newServer,
+		awaitOwn = awaitOwn,
+		destroy = function()
+			maid:DoCleaning()
+		end,
+	}
+end
+
+--[=[
+	Builds the controller the [PlayerDataStoreManager] specs share: a session-locked manager wired to
+	a fresh [DataStoreMock] (keyed `user_<userId>`), all owned by a Maid. `destroy()` tears down the
+	manager (and the loaded stores whose auto-save loops it owns) and the service bag.
+
+	Fields: `manager`, `mock`, `serviceBag`.
+	Helpers: `storeAndAwaitLock()` -> boolean -- stores a value on user 1's store and waits for the
+	session-locked load to write the lock envelope.
+
+	@return { manager: PlayerDataStoreManager, mock: DataStoreMock, ... }
+]=]
+function DataStoreTestUtils.setupDataStoreManager()
+	local maid = Maid.new()
+
+	local mock = DataStoreMock.new()
+	local serviceBag = DataStoreTestUtils.newServiceBag(maid)
+
+	local manager = maid:Add(PlayerDataStoreManager.new(serviceBag, mock, function(userId)
+		return "user_" .. tostring(userId)
+	end, true))
+
+	local function storeAndAwaitLock()
+		local dataStore = manager:GetDataStore(1)
+		dataStore:Store("coins", 5)
+		-- The session-locked load acquires the lock (writes the envelope) before we remove.
+		return PromiseTestUtils.awaitValue(function()
+			local raw = mock:GetRaw("user_1")
+			return raw ~= nil and raw.lock ~= nil
+		end, 10)
+	end
+
+	return {
+		manager = manager,
+		mock = mock,
+		serviceBag = serviceBag,
+		storeAndAwaitLock = storeAndAwaitLock,
+		destroy = function()
+			maid:DoCleaning()
+		end,
+	}
+end
+
+--[=[
+	Builds a [ServiceBag] with PlaceMessagingService registered and Init/Start'd, owned by the maid.
+	Pass a Roblox MessagingService mock to inject it into PlaceMessagingService between Init and Start.
+
+	@param maid Maid
+	@param robloxMessagingService MessagingServiceMock? -- injected when provided
+	@return ServiceBag
+]=]
+function DataStoreTestUtils.newServiceBag(maid, robloxMessagingService)
+	local serviceBag = maid:Add(ServiceBag.new())
+	local placeMessagingService = serviceBag:GetService(require("PlaceMessagingService"))
+	serviceBag:Init()
+	if robloxMessagingService then
+		placeMessagingService:SetRobloxMessagingService(robloxMessagingService)
+	end
+	serviceBag:Start()
+	return serviceBag
+end
+
+--[=[
+	Builds a [DataStore] over `mock` and owns it with the maid.
+
+	@param maid Maid
+	@param mock DataStoreMock
+	@param key string
+	@return DataStore
+]=]
+function DataStoreTestUtils.newDataStore(maid, mock, key)
+	return maid:Add(DataStore.new(mock, key))
+end
+
+--[=[
+	Builds a session-locked [DataStore] over `mock` and owns it with the maid.
+
+	@param maid Maid
+	@param mock DataStoreMock
+	@param key string
+	@param userIdList { number }? -- defaults to { 1 }
+	@return DataStore
+]=]
+function DataStoreTestUtils.newSessionLockedStore(maid, mock, key, userIdList)
+	local dataStore = maid:Add(DataStore.new(mock, key))
+	dataStore:SetSessionLockingEnabled(true)
+	dataStore:SetUserIdList(userIdList or { 1 })
+	return dataStore
+end
+
+--[=[
+	Builds a [DataStoreMessageHelper] over `dataStore` and owns it with the maid.
+
+	@param maid Maid
+	@param serviceBag ServiceBag
+	@param dataStore DataStore
+	@return DataStoreMessageHelper
+]=]
+function DataStoreTestUtils.newMessageHelper(maid, serviceBag, dataStore)
+	return maid:Add(DataStoreMessageHelper.new(serviceBag, dataStore))
+end
+
+return DataStoreTestUtils

package/src/Server/GameDataStoreService.lua

@@ -37,6 +37,20 @@ function GameDataStoreService.Init(self: GameDataStoreService, serviceBag: Servi
 	self._bindToCloseService = self._serviceBag:GetService(require("BindToCloseService"))
 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 GameDataStoreService.SetRobloxDataStore(self: GameDataStoreService, robloxDataStore: any): ()
+	assert(DataStorePromises.isDataStore(robloxDataStore), "Bad robloxDataStore")
+	assert(not self._robloxDataStorePromise, "Already resolved robloxDataStore, cannot override")
+
+	self._robloxDataStorePromise = Promise.resolved(robloxDataStore)
+end
+
 --[=[
 	Promises a DataStore for the current game that is synchronized every 5 seconds.
 
@@ -61,6 +75,18 @@ function GameDataStoreService.PromiseDataStore(self: GameDataStoreService): Prom
 			end)
 		end))
 
+		-- On service teardown (hot reload / tests) flush and destroy the store. Save() is a best-effort
+		-- synchronous write before Destroy() cancels it. The guard skips it if the game-close callback
+		-- above already tore the store down.
+		self._maid:GiveTask(function()
+			if not dataStore.Destroy then
+				return
+			end
+			-- 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")