@quenty/datastore 13.40.0 → 13.41.0

package/src/Server/PrivateServerDataStoreService.spec.lua

@@ -0,0 +1,242 @@
+--!nonstrict
+--[[
+	Integration coverage for PrivateServerDataStoreService wired through a real ServiceBag, with the
+	underlying datastore injected via the SetRobloxDataStore test seam. It is not session-locking, so a
+	failing load rejects promptly rather than hanging. The datastore key defaults to "main" (or the
+	private-server id) unless a custom key is set via SetCustomKey before the datastore is resolved.
+
+	@class PrivateServerDataStoreService.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()
+	mock = mock or DataStoreMock.new()
+
+	local serviceBag = maid:Add(ServiceBag.new())
+	local service = serviceBag:GetService(require("PrivateServerDataStoreService"))
+	serviceBag:Init()
+	service:SetRobloxDataStore(mock)
+	serviceBag:Start()
+
+	return {
+		service = service,
+		mock = mock,
+		destroy = function()
+			maid:DoCleaning()
+		end,
+	}
+end
+
+describe("PrivateServerDataStoreService.PromiseDataStore", function()
+	it("should resolve a datastore that loads successfully against a healthy mock", function()
+		local controller = setup()
+
+		local promise = controller.service:PromiseDataStore()
+		if not PromiseTestUtils.awaitSettled(promise) 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) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		expect((loadPromise:Wait())).toEqual(true)
+
+		controller:destroy()
+	end)
+
+	it("should return the same cached promise on repeated calls", function()
+		local controller = setup()
+
+		local first = controller.service:PromiseDataStore()
+		local second = controller.service:PromiseDataStore()
+		expect((first == second)).toEqual(true)
+
+		controller:destroy()
+	end)
+end)
+
+describe("PrivateServerDataStoreService.SetCustomKey", function()
+	it("should key the datastore by the custom key when set before resolving", function()
+		local controller = setup()
+
+		controller.service:SetCustomKey("mykey")
+
+		local promise = controller.service:PromiseDataStore()
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+
+		local ok, dataStore = promise:Yield()
+		expect(ok).toEqual(true)
+		expect((dataStore:GetKey())).toEqual("mykey")
+
+		controller:destroy()
+	end)
+end)
+
+describe("PrivateServerDataStoreService persistence", function()
+	it("should round-trip a stored value into the mock under the datastore key", function()
+		local controller = setup()
+
+		controller.service:SetCustomKey("mykey")
+
+		local promise = controller.service:PromiseDataStore()
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+
+		local ok, dataStore = promise:Yield()
+		expect(ok).toEqual(true)
+
+		local key = dataStore:GetKey()
+		dataStore:Store("motd", "hello")
+
+		local savePromise = dataStore:Save()
+		if not PromiseTestUtils.awaitSettled(savePromise) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		expect((savePromise:Yield())).toEqual(true)
+
+		-- Non-session-locking, so the raw persisted value is the plain data table.
+		local raw = controller.mock:GetRaw(key)
+		expect(raw).never.toBeNil()
+		expect(raw.motd).toEqual("hello")
+
+		controller:destroy()
+	end)
+end)
+
+describe("PrivateServerDataStoreService.SetRobloxDataStore", function()
+	it("should throw when injected twice (already resolved)", function()
+		local controller = setup()
+
+		expect(function()
+			controller.service:SetRobloxDataStore(DataStoreMock.new())
+		end).toThrow("Already resolved robloxDataStore")
+
+		controller:destroy()
+	end)
+
+	it("should throw on a non-datastore argument", function()
+		local controller = setup()
+
+		-- isDataStore is validated before the already-resolved check, so a bad arg throws regardless.
+		expect(function()
+			controller.service:SetRobloxDataStore({})
+		end).toThrow("Bad robloxDataStore")
+
+		expect(function()
+			controller.service:SetRobloxDataStore(nil)
+		end).toThrow("Bad robloxDataStore")
+
+		controller:destroy()
+	end)
+end)
+
+describe("PrivateServerDataStoreService failure handling", function()
+	it("should resolve load as false (not hang) when the datastore is down", function()
+		local mock = DataStoreMock.new()
+		mock:FailAllRequests()
+
+		local controller = setup(mock)
+
+		local promise = controller.service:PromiseDataStore()
+		if not PromiseTestUtils.awaitSettled(promise, 5) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+
+		local ok, dataStore = promise:Yield()
+		expect(ok).toEqual(true)
+
+		-- Non-session-locking: a failing load rejects promptly, so this settles false rather than hanging.
+		local loadPromise = dataStore:PromiseLoadSuccessful()
+		if not PromiseTestUtils.awaitSettled(loadPromise, 5) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+
+		local loadOk, loadedOk = loadPromise:Yield()
+		expect(loadOk).toEqual(true)
+		expect(loadedOk).toEqual(false)
+
+		controller:destroy()
+	end)
+end)
+
+describe("PrivateServerDataStoreService teardown", function()
+	it("destroys its inner datastore when the service is destroyed", function()
+		local controller = setup()
+
+		local promise = controller.service:PromiseDataStore()
+		if not PromiseTestUtils.awaitSettled(promise, 5) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		local _ok, dataStore = promise:Yield()
+
+		controller:destroy()
+
+		expect(getmetatable(dataStore)).toBeNil()
+	end)
+
+	it("flushes staged data synchronously to the underlying store when destroyed", function()
+		local controller = setup()
+
+		-- The cloud test place has a PrivateServerId, so pin the key rather than assuming "main".
+		controller.service:SetCustomKey("mykey")
+
+		local promise = controller.service:PromiseDataStore()
+		if not PromiseTestUtils.awaitSettled(promise, 5) then
+			expect("hung").toEqual("settled")
+			controller:destroy()
+			return
+		end
+		local _ok, dataStore = promise:Yield()
+
+		if not PromiseTestUtils.awaitSettled(dataStore:PromiseLoadSuccessful(), 5) then
+			expect("load hung").toEqual("load settled")
+			controller:destroy()
+			return
+		end
+
+		local key = dataStore:GetKey()
+		dataStore:Store("region", "us")
+
+		-- Destroy must fire a synchronous Save before tearing the store down.
+		controller:destroy()
+
+		local raw = controller.mock:GetRaw(key)
+		expect(raw).never.toBeNil()
+		expect(raw.region).toEqual("us")
+	end)
+end)

package/src/Server/Utility/DataStorePromises.lua

@@ -9,6 +9,7 @@ local require = require(script.Parent.loader).load(script)
 
 local DataStoreService = game:GetService("DataStoreService")
 
+local DataStoreMock = require("DataStoreMock")
 local PagesUtils = require("PagesUtils")
 local Promise = require("Promise")
 local Table = require("Table")
@@ -17,6 +18,18 @@ local DataStorePromises = {}
 
 export type RobloxDataStore = DataStore
 
+--[=[
+	Returns whether the given value can be used as a datastore by these helpers. A real
+	datastore is an `Instance`, but the first-class [DataStoreMock] is also accepted so tests
+	can stand in for a real datastore.
+
+	@param robloxDataStore any
+	@return boolean
+]=]
+function DataStorePromises.isDataStore(robloxDataStore: any): boolean
+	return typeof(robloxDataStore) == "Instance" or DataStoreMock.isDataStoreMock(robloxDataStore)
+end
+
 --[=[
 	Promises a Roblox datastore object with the name and scope. Generally only fails
 	when you haven't published the place.
@@ -70,7 +83,7 @@ end
 	@return Promise<T>
 ]=]
 function DataStorePromises.getAsync<T>(robloxDataStore: DataStore, key: string): Promise.Promise<T>
-	assert(typeof(robloxDataStore) == "Instance", "Bad robloxDataStore")
+	assert(DataStorePromises.isDataStore(robloxDataStore), "Bad robloxDataStore")
 	assert(type(key) == "string", "Bad key")
 
 	return Promise.spawn(function(resolve, reject)
@@ -99,7 +112,7 @@ function DataStorePromises.updateAsync<T>(
 	key: string,
 	updateFunc: (T, DataStoreKeyInfo) -> T?
 ): Promise.Promise<(T, DataStoreKeyInfo)>
-	assert(typeof(robloxDataStore) == "Instance", "Bad robloxDataStore")
+	assert(DataStorePromises.isDataStore(robloxDataStore), "Bad robloxDataStore")
 	assert(type(key) == "string", "Bad key")
 	assert(type(updateFunc) == "function", "Bad updateFunc")
 
@@ -132,7 +145,7 @@ function DataStorePromises.setAsync(
 	value: string,
 	userIds: { number }?
 ): Promise.Promise<boolean>
-	assert(typeof(robloxDataStore) == "Instance", "Bad robloxDataStore")
+	assert(DataStorePromises.isDataStore(robloxDataStore), "Bad robloxDataStore")
 	assert(type(key) == "string", "Bad key")
 	assert(type(userIds) == "table" or userIds == nil, "Bad userIds")
 
@@ -159,7 +172,7 @@ function DataStorePromises.promiseIncrementAsync(
 	key: string,
 	delta: number
 ): Promise.Promise<boolean>
-	assert(typeof(robloxDataStore) == "Instance", "Bad robloxDataStore")
+	assert(DataStorePromises.isDataStore(robloxDataStore), "Bad robloxDataStore")
 	assert(type(key) == "string", "Bad key")
 	assert(type(delta) == "number" or delta == nil, "Bad delta")
 
@@ -181,7 +194,7 @@ end
 	@return Promise<boolean>
 ]=]
 function DataStorePromises.removeAsync(robloxDataStore: DataStore, key: string): Promise.Promise<boolean>
-	assert(typeof(robloxDataStore) == "Instance", "Bad robloxDataStore")
+	assert(DataStorePromises.isDataStore(robloxDataStore), "Bad robloxDataStore")
 	assert(type(key) == "string", "Bad key")
 
 	return Promise.spawn(function(resolve, reject)

package/src/Server/Utility/DataStorePromises.spec.lua

@@ -0,0 +1,363 @@
+--!nonstrict
+--[[
+	Characterization coverage for DataStorePromises, using DataStoreMock as the datastore.
+	@class DataStorePromises.spec.lua
+]]
+local require = require(script.Parent.loader).load(script)
+
+local DataStoreMock = require("DataStoreMock")
+local DataStorePromises = require("DataStorePromises")
+local Jest = require("Jest")
+local PromiseTestUtils = require("PromiseTestUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("DataStorePromises.isDataStore", function()
+	it("should be true for a DataStoreMock", function()
+		expect(DataStorePromises.isDataStore(DataStoreMock.new())).toEqual(true)
+	end)
+
+	it("should be false for a plain table", function()
+		expect(DataStorePromises.isDataStore({})).toEqual(false)
+	end)
+
+	it("should be false for nil", function()
+		expect(DataStorePromises.isDataStore(nil)).toEqual(false)
+	end)
+
+	it("should be false for primitives", function()
+		expect(DataStorePromises.isDataStore(5)).toEqual(false)
+		expect(DataStorePromises.isDataStore("str")).toEqual(false)
+		expect(DataStorePromises.isDataStore(true)).toEqual(false)
+	end)
+
+	it("should be true for an Instance", function()
+		expect(DataStorePromises.isDataStore(Instance.new("Folder"))).toEqual(true)
+	end)
+end)
+
+describe("DataStorePromises.promiseDataStore", function()
+	it("should resolve an Instance in the cloud test place", function()
+		local promise = DataStorePromises.promiseDataStore("SpecStore", "SpecScope")
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("promise hung").toEqual("promise settled")
+			return
+		end
+
+		local ok, dataStore = promise:Yield()
+		expect(ok).toEqual(true)
+		expect(typeof(dataStore)).toEqual("Instance")
+	end)
+
+	it("should throw synchronously for a non-string name", function()
+		expect(function()
+			DataStorePromises.promiseDataStore(5 :: any, "scope")
+		end).toThrow("Bad name")
+	end)
+
+	it("should throw synchronously for a non-string scope", function()
+		expect(function()
+			DataStorePromises.promiseDataStore("name", 5 :: any)
+		end).toThrow("Bad scope")
+	end)
+end)
+
+describe("DataStorePromises.getAsync", function()
+	it("should resolve with the stored value", function()
+		local mock = DataStoreMock.new()
+		mock:SetRaw("key", { coins = 5 })
+
+		local promise = DataStorePromises.getAsync(mock, "key")
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("promise hung").toEqual("promise settled")
+			return
+		end
+
+		local ok, value = promise:Yield()
+		expect(ok).toEqual(true)
+		expect(value.coins).toEqual(5)
+	end)
+
+	it("should resolve with nil for an unset key", function()
+		local mock = DataStoreMock.new()
+
+		local promise = DataStorePromises.getAsync(mock, "missing")
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("promise hung").toEqual("promise settled")
+			return
+		end
+
+		local ok, value = promise:Yield()
+		expect(ok).toEqual(true)
+		expect(value).toEqual(nil)
+	end)
+
+	it("should reject when the store fails all requests", function()
+		local mock = DataStoreMock.new()
+		mock:FailAllRequests()
+
+		local promise = DataStorePromises.getAsync(mock, "key")
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("promise hung").toEqual("promise settled")
+			return
+		end
+
+		local ok = promise:Yield()
+		expect(ok).toEqual(false)
+	end)
+
+	it("should throw synchronously for a bad robloxDataStore", function()
+		expect(function()
+			DataStorePromises.getAsync({} :: any, "key")
+		end).toThrow("Bad robloxDataStore")
+	end)
+
+	it("should throw synchronously for a non-string key", function()
+		local mock = DataStoreMock.new()
+		expect(function()
+			DataStorePromises.getAsync(mock, 5 :: any)
+		end).toThrow("Bad key")
+	end)
+end)
+
+describe("DataStorePromises.updateAsync", function()
+	it("should resolve with the updated value", function()
+		local mock = DataStoreMock.new()
+		mock:SetRaw("key", 1)
+
+		local promise = DataStorePromises.updateAsync(mock, "key", function(current)
+			return (current or 0) + 1
+		end)
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("promise hung").toEqual("promise settled")
+			return
+		end
+
+		local ok, value = promise:Yield()
+		expect(ok).toEqual(true)
+		expect(value).toEqual(2)
+	end)
+
+	it("should pass the current value to the transform and update the store", function()
+		local mock = DataStoreMock.new()
+		mock:SetRaw("key", 10)
+
+		local seen
+		local promise = DataStorePromises.updateAsync(mock, "key", function(current)
+			seen = current
+			return current + 5
+		end)
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("promise hung").toEqual("promise settled")
+			return
+		end
+
+		local ok = promise:Yield()
+		expect(ok).toEqual(true)
+		expect(seen).toEqual(10)
+		expect(mock:GetRaw("key")).toEqual(15)
+	end)
+
+	it("should reject when the store fails all requests", function()
+		local mock = DataStoreMock.new()
+		mock:FailAllRequests()
+
+		local promise = DataStorePromises.updateAsync(mock, "key", function()
+			return 1
+		end)
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("promise hung").toEqual("promise settled")
+			return
+		end
+
+		local ok = promise:Yield()
+		expect(ok).toEqual(false)
+	end)
+
+	it("should throw synchronously for a bad robloxDataStore", function()
+		expect(function()
+			DataStorePromises.updateAsync({} :: any, "key", function()
+				return 1
+			end)
+		end).toThrow("Bad robloxDataStore")
+	end)
+
+	it("should throw synchronously for a non-string key", function()
+		local mock = DataStoreMock.new()
+		expect(function()
+			DataStorePromises.updateAsync(mock, 5 :: any, function()
+				return 1
+			end)
+		end).toThrow("Bad key")
+	end)
+
+	it("should throw synchronously for a non-function updateFunc", function()
+		local mock = DataStoreMock.new()
+		expect(function()
+			DataStorePromises.updateAsync(mock, "key", 5 :: any)
+		end).toThrow("Bad updateFunc")
+	end)
+end)
+
+describe("DataStorePromises.setAsync", function()
+	it("should resolve true and write the value", function()
+		local mock = DataStoreMock.new()
+
+		local promise = DataStorePromises.setAsync(mock, "key", "value")
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("promise hung").toEqual("promise settled")
+			return
+		end
+
+		local ok, value = promise:Yield()
+		expect(ok).toEqual(true)
+		expect(value).toEqual(true)
+		expect(mock:GetRaw("key")).toEqual("value")
+	end)
+
+	it("should accept userIds", function()
+		local mock = DataStoreMock.new()
+
+		local promise = DataStorePromises.setAsync(mock, "key", "value", { 111, 222 })
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("promise hung").toEqual("promise settled")
+			return
+		end
+
+		local ok = promise:Yield()
+		expect(ok).toEqual(true)
+	end)
+
+	it("should reject when the store fails all requests", function()
+		local mock = DataStoreMock.new()
+		mock:FailAllRequests()
+
+		local promise = DataStorePromises.setAsync(mock, "key", "value")
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("promise hung").toEqual("promise settled")
+			return
+		end
+
+		local ok = promise:Yield()
+		expect(ok).toEqual(false)
+	end)
+
+	it("should throw synchronously for a bad robloxDataStore", function()
+		expect(function()
+			DataStorePromises.setAsync({} :: any, "key", "value")
+		end).toThrow("Bad robloxDataStore")
+	end)
+
+	it("should throw synchronously for a non-string key", function()
+		local mock = DataStoreMock.new()
+		expect(function()
+			DataStorePromises.setAsync(mock, 5 :: any, "value")
+		end).toThrow("Bad key")
+	end)
+
+	it("should throw synchronously for bad userIds", function()
+		local mock = DataStoreMock.new()
+		expect(function()
+			DataStorePromises.setAsync(mock, "key", "value", "notatable" :: any)
+		end).toThrow("Bad userIds")
+	end)
+end)
+
+describe("DataStorePromises.promiseIncrementAsync", function()
+	it("should resolve true and increment the value", function()
+		local mock = DataStoreMock.new()
+		mock:SetRaw("key", 5)
+
+		local promise = DataStorePromises.promiseIncrementAsync(mock, "key", 3)
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("promise hung").toEqual("promise settled")
+			return
+		end
+
+		local ok, value = promise:Yield()
+		expect(ok).toEqual(true)
+		expect(value).toEqual(true)
+		expect(mock:GetRaw("key")).toEqual(8)
+	end)
+
+	it("should reject when the store fails all requests", function()
+		local mock = DataStoreMock.new()
+		mock:FailAllRequests()
+
+		local promise = DataStorePromises.promiseIncrementAsync(mock, "key", 1)
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("promise hung").toEqual("promise settled")
+			return
+		end
+
+		local ok = promise:Yield()
+		expect(ok).toEqual(false)
+	end)
+
+	it("should throw synchronously for a bad robloxDataStore", function()
+		expect(function()
+			DataStorePromises.promiseIncrementAsync({} :: any, "key", 1)
+		end).toThrow("Bad robloxDataStore")
+	end)
+
+	it("should throw synchronously for a non-string key", function()
+		local mock = DataStoreMock.new()
+		expect(function()
+			DataStorePromises.promiseIncrementAsync(mock, 5 :: any, 1)
+		end).toThrow("Bad key")
+	end)
+
+	it("should throw synchronously for a non-number delta", function()
+		local mock = DataStoreMock.new()
+		expect(function()
+			DataStorePromises.promiseIncrementAsync(mock, "key", "notanumber" :: any)
+		end).toThrow("Bad delta")
+	end)
+end)
+
+describe("DataStorePromises.removeAsync", function()
+	it("should resolve true and clear the key", function()
+		local mock = DataStoreMock.new()
+		mock:SetRaw("key", "value")
+
+		local promise = DataStorePromises.removeAsync(mock, "key")
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("promise hung").toEqual("promise settled")
+			return
+		end
+
+		local ok, value = promise:Yield()
+		expect(ok).toEqual(true)
+		expect(value).toEqual(true)
+		expect(mock:GetRaw("key")).toEqual(nil)
+	end)
+
+	it("should reject when the store fails all requests", function()
+		local mock = DataStoreMock.new()
+		mock:FailAllRequests()
+
+		local promise = DataStorePromises.removeAsync(mock, "key")
+		if not PromiseTestUtils.awaitSettled(promise) then
+			expect("promise hung").toEqual("promise settled")
+			return
+		end
+
+		local ok = promise:Yield()
+		expect(ok).toEqual(false)
+	end)
+
+	it("should throw synchronously for a bad robloxDataStore", function()
+		expect(function()
+			DataStorePromises.removeAsync({} :: any, "key")
+		end).toThrow("Bad robloxDataStore")
+	end)
+
+	it("should throw synchronously for a non-string key", function()
+		local mock = DataStoreMock.new()
+		expect(function()
+			DataStorePromises.removeAsync(mock, 5 :: any)
+		end).toThrow("Bad key")
+	end)
+end)

package/src/jest.config.lua

@@ -1,3 +1,6 @@
 return {
 	testMatch = { "**/*.spec" },
+	-- A modest bump over the 5s default: enough to absorb MessagingService loopback variance in the
+	-- two-server tests, without masking the hang tests (they fail via a bounded assertion at ~5s).
+	testTimeout = 10000,
 }