@quenty/datastore 13.40.0 → 13.41.0

package/CHANGELOG.md

@@ -3,6 +3,10 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [13.41.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/datastore@13.40.0...@quenty/datastore@13.41.0) (2026-07-18)
+
+**Note:** Version bump only for package @quenty/datastore
+
 # [13.40.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/datastore@13.39.1...@quenty/datastore@13.40.0) (2026-07-14)
 
 **Note:** Version bump only for package @quenty/datastore

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/datastore",
-  "version": "13.40.0",
+  "version": "13.41.0",
   "description": "Quenty's Datastore implementation for Roblox",
   "keywords": [
     "Roblox",
@@ -30,25 +30,25 @@
   ],
   "dependencies": {
     "@quenty/baseobject": "10.13.0",
-    "@quenty/bindtocloseservice": "8.33.0",
+    "@quenty/bindtocloseservice": "8.34.0",
     "@quenty/loader": "10.11.0",
     "@quenty/maid": "3.9.0",
     "@quenty/math": "2.7.5",
-    "@quenty/messagingserviceutils": "7.22.1",
+    "@quenty/messagingserviceutils": "7.23.0",
     "@quenty/nevermore-test-runner": "1.4.0",
-    "@quenty/pagesutils": "5.19.1",
-    "@quenty/promise": "10.18.1",
-    "@quenty/promisemaid": "5.18.1",
-    "@quenty/rx": "13.28.3",
+    "@quenty/pagesutils": "5.20.0",
+    "@quenty/promise": "10.19.0",
+    "@quenty/promisemaid": "5.19.0",
+    "@quenty/rx": "13.29.0",
     "@quenty/servicebag": "11.18.1",
     "@quenty/signal": "7.13.1",
     "@quenty/symbol": "3.5.2",
     "@quenty/table": "3.9.2",
-    "@quenty/valueobject": "13.31.1",
+    "@quenty/valueobject": "13.32.0",
     "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "13f0162f4971a77378e55e9b7236aea94f0dd3a8"
+  "gitHead": "cbbb89635bfdcbf32f26a40422ac736292917cca"
 }

package/src/Server/DataStore.HookErrors.spec.lua

@@ -0,0 +1,92 @@
+--!nonstrict
+--[[
+	Characterizes how the datastore layer handles user-supplied saving callbacks that misbehave:
+	throw, return a rejected promise, or yield forever. Several are genuine data-integrity failure
+	modes, so pinning them documents the contract callers must honor. The removing-callback matrix
+	lives with the manager it exercises in PlayerDataStoreManager.RemovalCallbacks.spec.lua.
+
+	@class DataStoreHookErrors.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("DataStore saving callbacks that misbehave", function()
+	it("runs a well-behaved saving callback and completes the save", function()
+		local controller = DataStoreTestUtils.setup()
+		local dataStore = controller.newDataStore("key")
+
+		local ran = false
+		dataStore:AddSavingCallback(function()
+			ran = true
+		end)
+		dataStore:Store("x", 1)
+
+		local promise = dataStore:Save()
+		if not PromiseTestUtils.awaitSettled(promise, 5) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		expect((promise:Yield())).toEqual(true)
+		expect(ran).toEqual(true)
+
+		controller:destroy()
+	end)
+
+	it("isolates a throwing saving callback into a clean save rejection, preserving the stack trace", function()
+		local controller = DataStoreTestUtils.setup()
+		local dataStore = controller.newDataStore("key")
+
+		dataStore:AddSavingCallback(function()
+			error("saving callback boom")
+		end)
+		dataStore:Store("x", 1)
+
+		local outcome, err = PromiseTestUtils.awaitOutcome(dataStore:Save(), 5)
+		expect(outcome).toEqual("rejected")
+
+		-- The rejection preserves the original message and the invoking frame, so the failure stays debuggable.
+		expect(string.find(tostring(err), "saving callback boom", 1, true) ~= nil).toEqual(true)
+		expect(string.find(tostring(err), "PromiseInvokeSavingCallbacks", 1, true) ~= nil).toEqual(true)
+
+		controller:destroy()
+	end)
+
+	it("rejects the save when a saving callback returns a rejected promise (and does not persist)", function()
+		local controller = DataStoreTestUtils.setup()
+		local dataStore = controller.newDataStore("key")
+
+		dataStore:AddSavingCallback(function()
+			return Promise.rejected("nope")
+		end)
+		dataStore:Store("x", 1)
+
+		expect((PromiseTestUtils.awaitOutcome(dataStore:Save(), 5))).toEqual("rejected")
+		expect(controller.mock:GetRaw("key")).toEqual(nil)
+
+		controller:destroy()
+	end)
+
+	it("blocks the save while a saving callback yields (never resolves)", function()
+		local controller = DataStoreTestUtils.setup()
+		local dataStore = controller.newDataStore("key")
+
+		dataStore:AddSavingCallback(function()
+			return Promise.new()
+		end)
+		dataStore:Store("x", 1)
+
+		local promise = dataStore:Save()
+		expect(PromiseTestUtils.awaitSettled(promise, 2)).toEqual(false)
+
+		controller:destroy()
+	end)
+end)

package/src/Server/DataStore.LoadErrors.spec.lua

@@ -0,0 +1,133 @@
+--!nonstrict
+--[[
+	Characterizes the shared load promise and the auto-save loop. The load view is cached
+	(PromiseViewUpToDate returns one shared promise), so every Load/LoadAll/Store/Observe attaches
+	its own continuation to the same promise; these tests pin that a settled load fans out its
+	resolution or rejection to every consumer, including ones attached mid-yield.
+
+	@class DataStoreLoadErrors.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("shared load promise fan-out", function()
+	it("delivers the resolution to every consumer of the shared load", function()
+		local controller = DataStoreTestUtils.setup()
+		controller.mock:SetRaw("key", { a = 1, b = 2 })
+		local dataStore = controller.newDataStore("key")
+
+		local valueA, valueB, all
+		dataStore:Load("a"):Then(function(value)
+			valueA = value
+		end)
+		dataStore:Load("b"):Then(function(value)
+			valueB = value
+		end)
+		dataStore:LoadAll():Then(function(value)
+			all = value
+		end)
+
+		expect(PromiseTestUtils.awaitValue(function()
+			return valueA ~= nil and valueB ~= nil and all ~= nil
+		end, 5)).toEqual(true)
+		expect(valueA).toEqual(1)
+		expect(valueB).toEqual(2)
+		expect(all).toEqual({ a = 1, b = 2 })
+
+		controller:destroy()
+	end)
+
+	it("resolves all consumers of a slow (yielding) load attached during the yield", function()
+		local controller = DataStoreTestUtils.setup()
+		controller.mock:SetRaw("key", { a = 1 })
+		controller.mock:SetYieldTime(0.3)
+		local dataStore = controller.newDataStore("key")
+
+		local results = {}
+		for i = 1, 3 do
+			dataStore:Load("a"):Then(function(value)
+				results[i] = value
+			end)
+		end
+
+		expect(PromiseTestUtils.awaitValue(function()
+			return results[1] ~= nil and results[2] ~= nil and results[3] ~= nil
+		end, 5)).toEqual(true)
+		expect(results[1]).toEqual(1)
+		expect(results[2]).toEqual(1)
+		expect(results[3]).toEqual(1)
+
+		controller:destroy()
+	end)
+
+	it("delivers the rejection to every consumer when the shared load fails", function()
+		local controller = DataStoreTestUtils.setup()
+		controller.mock:FailAllRequests()
+		local dataStore = controller.newDataStore("key")
+
+		local aRejected, bRejected = false, false
+		dataStore:Load("a"):Then(nil, function()
+			aRejected = true
+		end)
+		dataStore:Load("b"):Then(nil, function()
+			bRejected = true
+		end)
+
+		expect(PromiseTestUtils.awaitValue(function()
+			return aRejected and bRejected
+		end, 5)).toEqual(true)
+
+		controller:destroy()
+	end)
+end)
+
+describe("auto-save loop", function()
+	it("persists staged data on the auto-save schedule without an explicit Save", function()
+		local controller = DataStoreTestUtils.setup()
+		local dataStore = controller.newDataStore("key")
+		dataStore:SetAutoSaveTimeSeconds(0.2)
+
+		-- Store triggers the initial load; once loaded, the auto-save loop starts and flushes.
+		dataStore:Store("coins", 5)
+
+		local saved = PromiseTestUtils.awaitValue(function()
+			local raw = controller.mock:GetRaw("key")
+			return raw ~= nil and raw.coins == 5
+		end, 6)
+		expect(saved).toEqual(true)
+
+		controller:destroy()
+	end)
+
+	it("stops auto-saving after the datastore is destroyed", function()
+		local controller = DataStoreTestUtils.setup()
+		local dataStore = controller.newDataStore("key")
+		dataStore:SetAutoSaveTimeSeconds(0.2)
+		dataStore:Store("coins", 5)
+
+		expect(PromiseTestUtils.awaitValue(function()
+			local raw = controller.mock:GetRaw("key")
+			return raw ~= nil and raw.coins == 5
+		end, 6)).toEqual(true)
+
+		dataStore:Destroy()
+
+		-- After destroy the loop is gone: record the call count, wait past several auto-save
+		-- intervals, and confirm no new saves land.
+		local before = controller.mock:GetCallCount("UpdateAsync")
+		local settled = PromiseTestUtils.awaitValue(function()
+			return false
+		end, 1)
+		expect(settled).toEqual(false)
+		expect(controller.mock:GetCallCount("UpdateAsync")).toEqual(before)
+
+		controller:destroy()
+	end)
+end)

package/src/Server/DataStore.Reentrance.spec.lua

@@ -0,0 +1,119 @@
+--!nonstrict
+--[[
+	Re-entrance and cancellation: when a datastore request is in flight (yielding) and its owning
+	maid is torn down (the DataStore is destroyed / the player leaves), the request thread must be
+	cancelled and never resume to write. A session-locked load can legitimately stay pending for a
+	long time while a lock command is outstanding.
+
+	@class DataStoreReentrance.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("in-flight request cancellation (maid teardown)", function()
+	it("cancels a yielding load thread when the DataStore is destroyed (no leaked thread)", function()
+		local controller = DataStoreTestUtils.setup()
+		controller.mock:BlockRequests() -- the lock-acquire request hangs, so the load is stuck in flight
+
+		local dataStore = controller.newSessionLockedStore()
+		local promise = dataStore:PromiseLoadSuccessful()
+
+		expect(PromiseTestUtils.awaitSettled(promise, 1)).toEqual(false)
+
+		-- Destroy while the request thread is yielding -- its maid must cancel it.
+		dataStore:Destroy()
+
+		-- A properly cancelled thread never resumes, so the lock is never written. A leaked thread
+		-- would resume on unblock and write the lock envelope.
+		controller.mock:UnblockRequests()
+		local everWrote = PromiseTestUtils.awaitValue(function()
+			return controller.mock:GetRaw("player_1") ~= nil
+		end, 2)
+		expect(everWrote).toEqual(false)
+
+		controller:destroy()
+	end)
+
+	it("cancels a yielding save thread when the DataStore is destroyed", function()
+		local controller = DataStoreTestUtils.setup()
+
+		-- Load cleanly first (acquires the lock), then block so the SAVE request hangs in flight.
+		local dataStore = controller.newSessionLockedStore()
+		local loadPromise = dataStore:PromiseLoadSuccessful()
+		if not PromiseTestUtils.awaitSettled(loadPromise, 10) then
+			expect("load hung").toEqual("load settled")
+			controller:destroy()
+			return
+		end
+
+		controller.mock:BlockRequests()
+		dataStore:Store("coins", 5)
+		local savePromise = dataStore:Save()
+		expect(PromiseTestUtils.awaitSettled(savePromise, 1)).toEqual(false)
+
+		local versionsBefore = controller.mock:GetCallCount("UpdateAsync")
+		dataStore:Destroy()
+		controller.mock:UnblockRequests()
+
+		-- The cancelled save thread must not resume and perform another UpdateAsync write.
+		local extraWrites = PromiseTestUtils.awaitValue(function()
+			return controller.mock:GetCallCount("UpdateAsync") > versionsBefore + 1
+		end, 2)
+		expect(extraWrites).toEqual(false)
+
+		controller:destroy()
+	end)
+end)
+
+describe("lock command that does not settle", function()
+	it("keeps the load pending while the lock command is outstanding, then completes when it settles", function()
+		local controller = DataStoreTestUtils.setup()
+		controller.mock:BlockRequests() -- simulate a lock command that hasn't propagated yet (up to ~30s)
+
+		local dataStore = controller.newSessionLockedStore()
+		local promise = dataStore:PromiseLoadSuccessful()
+
+		-- Must NOT spuriously resolve or error while the lock command is outstanding.
+		expect(PromiseTestUtils.awaitSettled(promise, 2)).toEqual(false)
+
+		controller.mock:UnblockRequests()
+		if not PromiseTestUtils.awaitSettled(promise, 10) then
+			expect("hung after unblock").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		expect((promise:Wait())).toEqual(true)
+
+		controller:destroy()
+	end)
+
+	it("re-loads cleanly on a fresh session after a cancelled in-flight lock command", function()
+		local controller = DataStoreTestUtils.setup()
+		controller.mock:BlockRequests()
+
+		local first = controller.newSessionLockedStore()
+		local firstPromise = first:PromiseLoadSuccessful()
+		expect(PromiseTestUtils.awaitSettled(firstPromise, 1)).toEqual(false)
+		first:Destroy() -- cancel the in-flight lock command
+		controller.mock:UnblockRequests()
+
+		-- The cancelled attempt left no lock, so a fresh session acquires cleanly.
+		local second = controller.newSessionLockedStore()
+		local secondPromise = second:PromiseLoadSuccessful()
+		if not PromiseTestUtils.awaitSettled(secondPromise, 10) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		expect((secondPromise:Wait())).toEqual(true)
+
+		controller:destroy()
+	end)
+end)