@quenty/datastore 13.43.0 → 13.44.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [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.44.0",
   "description": "Quenty's Datastore implementation for Roblox",
   "keywords": [
     "Roblox",
@@ -50,5 +50,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "d2d7ae433f3fa756e038522986144b4f5c616756"
+  "gitHead": "b7e59984e586064ea3cec6176e79b3f7451ecdc5"
 }

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/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)