@quenty/datastore 13.43.0 → 13.45.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [13.45.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/datastore@13.44.0...@quenty/datastore@13.45.0) (2026-07-21)
+
+### Features
+
+- Add ephemeral save slots ([16bd91b](https://github.com/Quenty/NevermoreEngine/commit/16bd91b87943a65165245cba90d44274585903d6))
+
+# [13.44.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/datastore@13.43.0...@quenty/datastore@13.44.0) (2026-07-21)
+
+### Features
+
+- Add data store overflow handling ([96df5f5](https://github.com/Quenty/NevermoreEngine/commit/96df5f57bff20c41a8293dfaadb951e1831297b3))
+
 # [13.43.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/datastore@13.42.0...@quenty/datastore@13.43.0) (2026-07-20)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/datastore",
-  "version": "13.43.0",
+  "version": "13.45.0",
   "description": "Quenty's Datastore implementation for Roblox",
   "keywords": [
     "Roblox",
@@ -50,5 +50,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "d2d7ae433f3fa756e038522986144b4f5c616756"
+  "gitHead": "f04837e2cf40c9cb66cb672f1f4d3f28ddb0088c"
 }

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

@@ -0,0 +1,109 @@
+--!nonstrict
+--[[
+	Integration coverage for the overflow-save failure: when a key accumulates more data than Roblox
+	can serialize under its per-key size ceiling, the write throws and the save must fail loudly rather
+	than silently drop the data or corrupt what was already stored. Driven through the full DataStore
+	stack against a DataStoreMock configured with a small [DataStoreMock.SetMaxValueLength] so the
+	overflow triggers without a multi-megabyte payload.
+
+	@class DataStore.Overflow.spec.lua
+]]
+local require = require(script.Parent.loader).load(script)
+
+local DataStoreMock = require("DataStoreMock")
+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, so a hung promise fails the test (here) instead of
+-- freezing the runner on the following :Yield().
+local function expectSettled(promise, timeout: number?)
+	expect(PromiseTestUtils.awaitSettled(promise, timeout)).toEqual(true)
+end
+
+describe("DataStore overflow save", function()
+	it("should reject a save whose serialized value exceeds the datastore size limit", function()
+		local controller = DataStoreTestUtils.setup()
+		local dataStore = controller.newDataStore()
+
+		expectSettled(dataStore:Load("data"))
+
+		controller.mock:SetMaxValueLength(1024)
+		dataStore:Store("data", string.rep("A", 8192))
+
+		local savePromise = dataStore:Save()
+		expectSettled(savePromise, 5)
+		expect((savePromise:Yield())).toEqual(false)
+
+		controller:destroy()
+	end)
+
+	it("should leave the previously saved value intact when an oversized save fails", function()
+		local controller = DataStoreTestUtils.setup()
+		local writer = controller.newDataStore()
+
+		writer:Store("data", "known-good")
+		expectSettled(writer:Save())
+
+		-- Now grow the same key past the ceiling and try to save again.
+		controller.mock:SetMaxValueLength(1024)
+		writer:Store("data", string.rep("A", 8192))
+
+		local savePromise = writer:Save()
+		expectSettled(savePromise, 5)
+		expect((savePromise:Yield())).toEqual(false)
+
+		-- The failed write must not have clobbered the stored value.
+		controller.mock:SetMaxValueLength(nil)
+		local reader = controller.newDataStore()
+		local loadPromise = reader:Load("data")
+		expectSettled(loadPromise)
+
+		local ok, value = loadPromise:Yield()
+		expect(ok).toEqual(true)
+		expect(value).toEqual("known-good")
+
+		controller:destroy()
+	end)
+
+	it("should still save values that fit within the real 4 MB ceiling", function()
+		local controller = DataStoreTestUtils.setup()
+		local dataStore = controller.newDataStore()
+
+		controller.mock:SetMaxValueLength(DataStoreMock.MAX_VALUE_LENGTH)
+		dataStore:Store("coins", 5)
+
+		local savePromise = dataStore:Save()
+		expectSettled(savePromise)
+		expect((savePromise:Yield())).toEqual(true)
+
+		local reader = controller.newDataStore()
+		local loadPromise = reader:Load("coins")
+		expectSettled(loadPromise)
+		expect((loadPromise:Yield())).toEqual(true)
+
+		controller:destroy()
+	end)
+
+	it("should fail the save when data accumulated across substores overflows the key", function()
+		local controller = DataStoreTestUtils.setup()
+		local dataStore = controller.newDataStore()
+
+		expectSettled(dataStore:Load("data"))
+
+		-- The whole key value -- every substore merged together -- is what gets serialized, so a single
+		-- oversized substore entry overflows the entire save.
+		controller.mock:SetMaxValueLength(1024)
+		dataStore:GetSubStore("inventory"):Store("blob", string.rep("A", 8192))
+
+		local savePromise = dataStore:Save()
+		expectSettled(savePromise, 5)
+		expect((savePromise:Yield())).toEqual(false)
+
+		controller:destroy()
+	end)
+end)

package/src/Server/InMemoryDataStore.lua

@@ -0,0 +1,73 @@
+--!strict
+--[=[
+	A [DataStoreStage] root that lives entirely in memory: it is never backed by a Roblox datastore, so
+	nothing it holds is ever written or read across sessions. Reads resolve to whatever has been staged in
+	memory (defaults when unset) and writes stay local to this object, vanishing when it is destroyed.
+
+	Every read/write/substore/observe method comes from [DataStoreStage] unchanged -- the base class computes
+	its view purely from in-memory snapshots. The only thing a stage normally needs a parent for is
+	[DataStoreStage.PromiseViewUpToDate] (loading its base layer from the datastore above it); a root has no
+	parent, so this class resolves that immediately against its own view. That single override is the whole
+	difference between this and [DataStore], which loads/saves through Roblox.
+
+	Use it wherever code wants a real store surface for data that must not persist -- e.g. a throwaway session
+	slot -- without paying for [DataStore]'s load, save, autosave, and session-locking machinery.
+
+	```lua
+	local store = InMemoryDataStore.new()
+	store:Store("coins", 5)
+	print(store:Load("coins"):Yield()) -- 5, never touches a datastore
+	```
+
+	@server
+	@class InMemoryDataStore
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local DataStoreStage = require("DataStoreStage")
+local Promise = require("Promise")
+
+local InMemoryDataStore = setmetatable({}, DataStoreStage)
+InMemoryDataStore.ClassName = "InMemoryDataStore"
+InMemoryDataStore.__index = InMemoryDataStore
+
+export type InMemoryDataStore =
+	typeof(setmetatable({} :: {}, {} :: typeof({ __index = InMemoryDataStore })))
+	& DataStoreStage.DataStoreStage
+
+--[=[
+	Constructs a new in-memory data store.
+
+	@param loadName (string | number)? -- diagnostic name only (see [DataStoreStage.GetFullPath]); defaults to "InMemoryDataStore"
+	@return InMemoryDataStore
+]=]
+function InMemoryDataStore.new(loadName: (string | number)?): InMemoryDataStore
+	local self: InMemoryDataStore =
+		setmetatable(DataStoreStage.new(loadName or "InMemoryDataStore") :: any, InMemoryDataStore)
+
+	return self
+end
+
+--[=[
+	The view is always exactly what has been staged in memory, so it is never out of date: there is no
+	parent or datastore to sync from. Overriding this (the base class errors on a parentless stage) is what
+	makes every inherited read work in-memory.
+
+	@return Promise
+]=]
+function InMemoryDataStore.PromiseViewUpToDate(_self: InMemoryDataStore): Promise.Promise<()>
+	return Promise.resolved()
+end
+
+--[=[
+	A no-op that resolves: there is no backing datastore to flush to. Present so this is a drop-in root for
+	code that expects to be able to call `:Save()` on its store.
+
+	@return Promise
+]=]
+function InMemoryDataStore.Save(_self: InMemoryDataStore): Promise.Promise<()>
+	return Promise.resolved()
+end
+
+return InMemoryDataStore

package/src/Server/InMemoryDataStore.spec.lua

@@ -0,0 +1,248 @@
+--!nonstrict
+--[[
+	Coverage for InMemoryDataStore.
+
+	The bulk is a *matrix* suite: one shared battery of DataStoreStage-surface behaviors run against both
+	store roots -- the real DataStore (over a DataStoreMock) and InMemoryDataStore -- so the in-memory store
+	is proven to behave identically to the persisted one on every read/write/substore/observe path they share.
+	The store-specific describe blocks then cover what only the in-memory store guarantees: isolation between
+	instances, a no-op save, and never reaching a datastore at all.
+
+	@class InMemoryDataStore.spec.lua
+]]
+local require = require(script.Parent.loader).load(script)
+
+local DataStoreTestUtils = require("DataStoreTestUtils")
+local InMemoryDataStore = require("InMemoryDataStore")
+local Jest = require("Jest")
+local Maid = require("Maid")
+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 its resolved value, so a hung promise fails
+-- the test here instead of freezing the runner on a later :Yield().
+local function resolve(promise, timeout: number?)
+	expect(PromiseTestUtils.awaitSettled(promise, timeout or 10)).toEqual(true)
+	local ok, value = promise:Yield()
+	expect(ok).toEqual(true)
+	return value
+end
+
+-- A controller exposes makeStore() (a fresh store root) and destroy() (tears down everything it created).
+-- The matrix runs the same suite against one of these per store implementation.
+local function newInMemoryController()
+	local maid = Maid.new()
+	return {
+		makeStore = function()
+			return maid:Add(InMemoryDataStore.new())
+		end,
+		destroy = function()
+			maid:DoCleaning()
+		end,
+	}
+end
+
+local function newDataStoreController()
+	local controller = DataStoreTestUtils.setup()
+	return {
+		makeStore = function()
+			return controller.newDataStore()
+		end,
+		destroy = controller.destroy,
+	}
+end
+
+-- The shared behavior battery. `newController` returns a fresh controller so each test is isolated.
+local function describeSharedBehavior(caseName: string, newController)
+	describe(caseName, function()
+		it("loads the default value when the key is empty", function()
+			local c = newController()
+			expect(resolve(c.makeStore():Load("coins", 99))).toEqual(99)
+			c.destroy()
+		end)
+
+		it("round-trips a stored value", function()
+			local c = newController()
+			local store = c.makeStore()
+			store:Store("coins", 5)
+			expect(resolve(store:Load("coins"))).toEqual(5)
+			c.destroy()
+		end)
+
+		it("round-trips multiple keys and loads defaults for missing ones", function()
+			local c = newController()
+			local store = c.makeStore()
+			store:Store("coins", 5)
+			store:Store("gems", 10)
+
+			local all = resolve(store:LoadAll())
+			expect(all.coins).toEqual(5)
+			expect(all.gems).toEqual(10)
+			expect(resolve(store:Load("missing", "default"))).toEqual("default")
+			c.destroy()
+		end)
+
+		it("deletes a key so it no longer loads", function()
+			local c = newController()
+			local store = c.makeStore()
+			store:Store("a", 1)
+			store:Store("b", 2)
+			store:Delete("a")
+
+			local all = resolve(store:LoadAll())
+			expect(all.a).toEqual(nil)
+			expect(all.b).toEqual(2)
+			c.destroy()
+		end)
+
+		it("overwrites the whole view", function()
+			local c = newController()
+			local store = c.makeStore()
+			store:Store("a", 1)
+			store:Store("b", 2)
+			store:Overwrite({ c = 3 })
+
+			local all = resolve(store:LoadAll())
+			expect(all.a).toEqual(nil)
+			expect(all.b).toEqual(nil)
+			expect(all.c).toEqual(3)
+			c.destroy()
+		end)
+
+		it("wipes to empty", function()
+			local c = newController()
+			local store = c.makeStore()
+			store:Store("a", 1)
+			store:Wipe()
+			expect(resolve(store:LoadAll({}))).toEqual({})
+			c.destroy()
+		end)
+
+		it("round-trips substore values and nests them under the parent", function()
+			local c = newController()
+			local store = c.makeStore()
+			store:GetSubStore("inventory"):Store("sword", true)
+
+			expect(resolve(store:GetSubStore("inventory"):Load("sword"))).toEqual(true)
+
+			local all = resolve(store:LoadAll())
+			expect(all.inventory.sword).toEqual(true)
+			c.destroy()
+		end)
+
+		it("lists the top-level keys", function()
+			local c = newController()
+			local store = c.makeStore()
+			store:Store("a", 1)
+			store:Store("b", 2)
+
+			local keys = resolve(store:PromiseKeyList())
+			table.sort(keys)
+			expect(keys).toEqual({ "a", "b" })
+			c.destroy()
+		end)
+
+		it("stores table values by deep copy, immune to later mutation of the source", function()
+			local c = newController()
+			local store = c.makeStore()
+			local source = { count = 1 }
+			store:Store("data", source)
+			source.count = 999 -- Mutating after the store must not change what was stored.
+
+			expect(resolve(store:Load("data")).count).toEqual(1)
+			c.destroy()
+		end)
+
+		it("observes a key: emits the initial value then updates on store", function()
+			local c = newController()
+			local store = c.makeStore()
+
+			local maid = Maid.new()
+			local seen = {}
+			maid:GiveTask(store:Observe("coins", 0):Subscribe(function(value)
+				table.insert(seen, value)
+			end))
+
+			expect(PromiseTestUtils.awaitValue(function()
+				return #seen >= 1
+			end, 5)).toEqual(true)
+			expect(seen[1]).toEqual(0) -- default before anything is stored
+
+			store:Store("coins", 7)
+			expect(PromiseTestUtils.awaitValue(function()
+				return seen[#seen] == 7
+			end, 5)).toEqual(true)
+
+			maid:DoCleaning()
+			c.destroy()
+		end)
+	end)
+end
+
+describeSharedBehavior("matrix: DataStore over DataStoreMock", newDataStoreController)
+describeSharedBehavior("matrix: InMemoryDataStore", newInMemoryController)
+
+-- A single test that runs an identical op sequence against both roots at once and asserts they land on the
+-- exact same view -- the matrix's consistency guarantee stated directly, not just implied by parallel suites.
+describe("matrix: cross-implementation consistency", function()
+	it("yields the same view for the same op sequence on both roots", function()
+		local dataStoreController = newDataStoreController()
+		local inMemoryController = newInMemoryController()
+
+		local function runOps(store)
+			store:Store("coins", 5)
+			store:Store("gems", 10)
+			store:GetSubStore("inventory"):Store("sword", true)
+			store:Delete("gems")
+			return resolve(store:LoadAll())
+		end
+
+		local persistedView = runOps(dataStoreController.makeStore())
+		local inMemoryView = runOps(inMemoryController.makeStore())
+
+		expect(inMemoryView).toEqual(persistedView)
+
+		dataStoreController.destroy()
+		inMemoryController.destroy()
+	end)
+end)
+
+describe("InMemoryDataStore isolation and non-persistence", function()
+	it("does not share data between separate instances", function()
+		local maid = Maid.new()
+		local first = maid:Add(InMemoryDataStore.new())
+		first:Store("coins", 5)
+
+		local second = maid:Add(InMemoryDataStore.new())
+		expect(resolve(second:Load("coins", 0))).toEqual(0)
+
+		maid:DoCleaning()
+	end)
+
+	it("resolves Save as a no-op", function()
+		local maid = Maid.new()
+		local store = maid:Add(InMemoryDataStore.new())
+		store:Store("coins", 5)
+
+		expect(resolve(store:Save())).toEqual(nil)
+		-- Data is still readable in memory after the (no-op) save.
+		expect(resolve(store:Load("coins"))).toEqual(5)
+
+		maid:DoCleaning()
+	end)
+
+	it("resolves reads immediately with no parent to sync from", function()
+		local maid = Maid.new()
+		local store = maid:Add(InMemoryDataStore.new())
+
+		-- The base class errors on Load for a parentless stage; this proves the override took.
+		expect(resolve(store:LoadAll({}))).toEqual({})
+
+		maid:DoCleaning()
+	end)
+end)
+
+return nil

package/src/Server/Mocks/DataStoreMock.lua

@@ -23,6 +23,8 @@
 
 local require = require(script.Parent.loader).load(script)
 
+local HttpService = game:GetService("HttpService")
+
 local Table = require("Table")
 
 local function deepCopy(value: any): any
@@ -33,6 +35,14 @@ local function deepCopy(value: any): any
 	return Table.deepCopy(value)
 end
 
+-- Mirrors how Roblox reports a value that serializes past the per-key size ceiling.
+local function valueTooLargeMessage(maxValueLength: number): string
+	return string.format(
+		"105: The value provided exceeds the %d byte maximum size limit for a data store value",
+		maxValueLength
+	)
+end
+
 local DataStoreMock = {}
 DataStoreMock.ClassName = "DataStoreMock"
 DataStoreMock.__index = DataStoreMock
@@ -46,6 +56,17 @@ DataStoreMock.__index = DataStoreMock
 DataStoreMock.OPERATION_NOT_ALLOWED_509 =
 	"509: Data Store operations blocked while running on a Personal RCC to prevent possible data corruption"
 
+--[=[
+	The per-key serialized-value ceiling Roblox enforces (4 MB). Real datastores serialize a key's
+	whole value to JSON and reject the write when that blob is larger than this, which is how a save
+	fails once too much data accumulates under one key. Pass this (or a smaller value, to trigger it
+	without a multi-megabyte payload) to [DataStoreMock.SetMaxValueLength].
+
+	@prop MAX_VALUE_LENGTH number
+	@within DataStoreMock
+]=]
+DataStoreMock.MAX_VALUE_LENGTH = 4194304
+
 export type ErrorInjectorContext = {
 	method: string,
 	key: string,
@@ -68,6 +89,7 @@ export type DataStoreMock = typeof(setmetatable(
 		_yieldTime: number,
 		_errorInjector: ErrorInjector?,
 		_blocked: boolean,
+		_maxValueLength: number?,
 	},
 	{} :: typeof({ __index = DataStoreMock })
 ))
@@ -106,6 +128,7 @@ function DataStoreMock.new(name: string?, scope: string?): DataStoreMock
 	self._yieldTime = 0
 	self._errorInjector = nil
 	self._blocked = false
+	self._maxValueLength = nil
 
 	return self
 end
@@ -122,6 +145,24 @@ function DataStoreMock.SetYieldTime(self: DataStoreMock, yieldTime: number): ()
 	self._yieldTime = yieldTime
 end
 
+--[=[
+	Enforces a serialized-value ceiling on `SetAsync`/`UpdateAsync`, mirroring the way real
+	datastores reject a write once a key's whole value serializes past their per-key size limit.
+	A write whose value JSON-encodes to more than `maxValueLength` bytes throws (and stores nothing),
+	so tests can exercise the overflow-save failure path without a multi-megabyte payload. A value the
+	mock cannot serialize at all throws the same way a real datastore rejects non-UTF-8 data.
+
+	Pass [DataStoreMock.MAX_VALUE_LENGTH] for the real 4 MB ceiling, a smaller number to trigger it
+	cheaply, or nil to disable the check (the default, so existing tests are unaffected).
+
+	@param maxValueLength number?
+]=]
+function DataStoreMock.SetMaxValueLength(self: DataStoreMock, maxValueLength: number?): ()
+	assert(maxValueLength == nil or (type(maxValueLength) == "number" and maxValueLength >= 0), "Bad maxValueLength")
+
+	self._maxValueLength = maxValueLength
+end
+
 --[=[
 	Injects a callback consulted before every request. Returning a string from the callback
 	makes that request throw the string as its error; returning nil lets the request proceed.
@@ -261,6 +302,27 @@ function DataStoreMock._beginRequest(self: DataStoreMock, method: string, key: s
 	end
 end
 
+-- Rejects a write whose value serializes past the configured size ceiling, the way real datastores
+-- reject a key value that grew too large to store safely. A no-op unless SetMaxValueLength was set.
+function DataStoreMock._assertWithinSizeLimit(self: DataStoreMock, value: any): ()
+	local maxValueLength = self._maxValueLength
+	if maxValueLength == nil or value == nil then
+		return
+	end
+
+	local ok, encoded = pcall(function()
+		return HttpService:JSONEncode(value)
+	end)
+	if not ok then
+		-- A real datastore likewise refuses a value it cannot serialize.
+		error("104: Cannot store value in data store. Data stores can only accept valid UTF-8 characters", 0)
+	end
+
+	if #encoded > maxValueLength then
+		error(valueTooLargeMessage(maxValueLength), 0)
+	end
+end
+
 function DataStoreMock._makeKeyInfo(self: DataStoreMock, key: string)
 	local userIds = self._userIds[key]
 	local metadata = self._metadata[key]
@@ -312,6 +374,7 @@ function DataStoreMock.SetAsync(
 	assert(type(key) == "string", "Bad key")
 
 	self:_beginRequest("SetAsync", key)
+	self:_assertWithinSizeLimit(value)
 
 	self._store[key] = deepCopy(value)
 	self._userIds[key] = userIds and Table.deepCopy(userIds) or nil
@@ -351,6 +414,8 @@ function DataStoreMock.UpdateAsync(
 		return nil, keyInfo
 	end
 
+	self:_assertWithinSizeLimit(newValue)
+
 	self._store[key] = deepCopy(newValue)
 	self._userIds[key] = userIds and Table.deepCopy(userIds) or nil
 	self._metadata[key] = metadata and Table.deepCopy(metadata) or nil

package/src/Server/Mocks/DataStoreMock.spec.lua

@@ -359,6 +359,83 @@ describe("DataStoreMock call counting", function()
 	end)
 end)
 
+describe("DataStoreMock serialized-size overflow", function()
+	it("should not enforce any size limit by default", function()
+		local store = DataStoreMock.new()
+		-- A value far larger than a small limit persists fine when no limit is configured.
+		expect(function()
+			store:SetAsync("key", string.rep("A", 100000))
+		end).never.toThrow()
+	end)
+
+	it("should reject a SetAsync whose value exceeds the configured limit", function()
+		local store = DataStoreMock.new()
+		store:SetMaxValueLength(1024)
+
+		expect(function()
+			store:SetAsync("key", string.rep("A", 4096))
+		end).toThrow("maximum size limit")
+	end)
+
+	it("should allow a SetAsync whose value fits within the configured limit", function()
+		local store = DataStoreMock.new()
+		store:SetMaxValueLength(1024)
+
+		expect(function()
+			store:SetAsync("key", "small")
+		end).never.toThrow()
+		expect((store:GetAsync("key"))).toEqual("small")
+	end)
+
+	it("should not persist an oversized value that was rejected", function()
+		local store = DataStoreMock.new()
+		store:SetAsync("key", "original")
+		store:SetMaxValueLength(1024)
+
+		pcall(function()
+			store:SetAsync("key", string.rep("A", 4096))
+		end)
+
+		store:SetMaxValueLength(nil)
+		expect((store:GetAsync("key"))).toEqual("original")
+	end)
+
+	it("should reject an UpdateAsync whose returned value exceeds the configured limit", function()
+		local store = DataStoreMock.new()
+		store:SetMaxValueLength(1024)
+
+		expect(function()
+			store:UpdateAsync("key", function()
+				return string.rep("A", 4096)
+			end)
+		end).toThrow("maximum size limit")
+	end)
+
+	it("should measure the serialized size of tables, not their length", function()
+		local store = DataStoreMock.new()
+		store:SetMaxValueLength(64)
+
+		local big = {}
+		for i = 1, 100 do
+			big[i] = i
+		end
+
+		expect(function()
+			store:SetAsync("key", big)
+		end).toThrow("maximum size limit")
+	end)
+
+	it("should stop enforcing once the limit is cleared", function()
+		local store = DataStoreMock.new()
+		store:SetMaxValueLength(1024)
+		store:SetMaxValueLength(nil)
+
+		expect(function()
+			store:SetAsync("key", string.rep("A", 4096))
+		end).never.toThrow()
+	end)
+end)
+
 describe("DataStoreMock:SetRaw / GetRaw", function()
 	it("should seed and read without triggering failures", function()
 		local store = DataStoreMock.new()

package/src/Shared/Utility/DataStoreStringUtils.spec.lua

@@ -29,4 +29,63 @@ describe("DataStoreStringUtils.isValidUTF8(str)", function()
 		local result = DataStoreStringUtils.isValidUTF8("")
 		expect(result).toEqual(true)
 	end)
+
+	it("should return true across the full 7-bit ASCII range", function()
+		local bytes = {}
+		for i = 0, 127 do
+			bytes[i + 1] = string.char(i)
+		end
+		local result = DataStoreStringUtils.isValidUTF8(table.concat(bytes))
+		expect(result).toEqual(true)
+	end)
+
+	it("should return true for control characters and embedded NUL bytes", function()
+		expect(DataStoreStringUtils.isValidUTF8("line\r\n\tvalue")).toEqual(true)
+		expect(DataStoreStringUtils.isValidUTF8("with\0null")).toEqual(true)
+	end)
+
+	it("should return true at the 127 boundary and false at 128", function()
+		expect(DataStoreStringUtils.isValidUTF8(string.char(127))).toEqual(true)
+
+		local result, reason = DataStoreStringUtils.isValidUTF8(string.char(128))
+		expect(result).toEqual(false)
+		expect(reason).toEqual("Invalid string")
+	end)
+
+	it("should reject well-formed UTF-8 that contains non-ASCII code points", function()
+		-- "café" is valid UTF-8 but the accented character is above the ASCII range, which is the
+		-- string-saving-attack surface isValidUTF8 exists to block.
+		local result, reason = DataStoreStringUtils.isValidUTF8("caf\u{00E9}")
+		expect(result).toEqual(false)
+		expect(reason).toEqual("Invalid string")
+	end)
+
+	it("should reject emoji and other multi-byte code points", function()
+		local result, reason = DataStoreStringUtils.isValidUTF8("party \u{1F389}")
+		expect(result).toEqual(false)
+		expect(reason).toEqual("Invalid string")
+	end)
+
+	it("should reject bytes that are not valid UTF-8 at all", function()
+		-- 0xFF is never a legal UTF-8 byte, so utf8.len fails before the ASCII check runs.
+		local result, reason = DataStoreStringUtils.isValidUTF8(string.char(255))
+		expect(result).toEqual(false)
+		expect(reason).toEqual("Invalid string")
+	end)
+
+	it("should reject a lone continuation byte", function()
+		local result, reason = DataStoreStringUtils.isValidUTF8(string.char(0x80))
+		expect(result).toEqual(false)
+		expect(reason).toEqual("Invalid string")
+	end)
+
+	it("should return false with a reason for nil and table values", function()
+		local nilResult, nilReason = DataStoreStringUtils.isValidUTF8(nil :: any)
+		expect(nilResult).toEqual(false)
+		expect(nilReason).toEqual("Not a string")
+
+		local tableResult, tableReason = DataStoreStringUtils.isValidUTF8({} :: any)
+		expect(tableResult).toEqual(false)
+		expect(tableReason).toEqual("Not a string")
+	end)
 end)