@quenty/pagesutils 5.20.0 → 5.22.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.22.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/pagesutils@5.21.0...@quenty/pagesutils@5.22.0) (2026-07-23)
+
+### Features
+
+- Add baseline player-mock and support across Nevermore for mocked players. ([567d121](https://github.com/Quenty/NevermoreEngine/commit/567d121ffc014b42391554088189a1a6296dda83))
+
+# [5.21.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/pagesutils@5.20.0...@quenty/pagesutils@5.21.0) (2026-07-18)
+
+**Note:** Version bump only for package @quenty/pagesutils
+
 # [5.20.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/pagesutils@5.19.1...@quenty/pagesutils@5.20.0) (2026-07-18)
 
 **Note:** Version bump only for package @quenty/pagesutils

package/deploy.nevermore.json

@@ -0,0 +1,10 @@
+{
+  "targets": {
+    "test": {
+      "universeId": 9716264427,
+      "placeId": 117954086576258,
+      "project": "test/default.project.json",
+      "scriptTemplate": "test/scripts/Server/ServerMain.server.lua"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/pagesutils",
-  "version": "5.20.0",
+  "version": "5.22.0",
   "description": "Utilities to advance over the Roblox pages API surface",
   "keywords": [
     "Roblox",
@@ -31,10 +31,12 @@
   "dependencies": {
     "@quenty/ducktype": "5.11.0",
     "@quenty/loader": "10.11.0",
-    "@quenty/promise": "10.19.0"
+    "@quenty/nevermore-test-runner": "1.5.0",
+    "@quenty/promise": "10.21.0",
+    "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "cbbb89635bfdcbf32f26a40422ac736292917cca"
+  "gitHead": "1de37218a2bedb8e3f8614a2e09bba9eddc812da"
 }

package/src/Shared/Proxy/PagesDatabase.lua

@@ -13,7 +13,8 @@ PagesDatabase.__index = PagesDatabase
 
 export type PagesDatabase = typeof(setmetatable(
 	{} :: {
-		_pages: Pages,
+		-- nil for a static database (see [PagesDatabase.fromPageData]), which has every page pre-stored
+		_pages: Pages?,
 		_lastIncrementedIndex: number,
 		_pageData: { [number]: { currentPage: any, isFinished: boolean } },
 	},
@@ -32,14 +33,56 @@ function PagesDatabase.new(pages: Pages): PagesDatabase
 	return self
 end
 
+--[=[
+	Constructs a database from static page data instead of a live [Pages] instance, for consumers
+	that already hold the full result set -- e.g. a test fabricating an engine pages result through
+	[PagesProxy]. Each entry in `pageData` is one page's item array; the last page reads back
+	`IsFinished = true`. Empty `pageData` mirrors an empty engine result: a single empty page that
+	is already finished.
+
+	```lua
+	local pages = PagesProxy.new(PagesDatabase.fromPageData({
+		{ "a", "b" },
+		{ "c" },
+	}))
+	```
+
+	@param pageData { { any } }
+	@return PagesDatabase
+]=]
+function PagesDatabase.fromPageData(pageData: { { any } }): PagesDatabase
+	assert(type(pageData) == "table", "Bad pageData")
+
+	local self: PagesDatabase = setmetatable({} :: any, PagesDatabase)
+
+	local pageCount = math.max(#pageData, 1)
+
+	self._lastIncrementedIndex = pageCount
+	self._pageData = {}
+
+	for pageId = 1, pageCount do
+		local page = pageData[pageId] or {}
+		assert(type(page) == "table", "Bad page")
+
+		self._pageData[pageId] = {
+			currentPage = page,
+			isFinished = pageId == pageCount,
+		}
+	end
+
+	return self
+end
+
 function PagesDatabase.isPagesDatabase(value): boolean
 	return DuckTypeUtils.isImplementation(PagesDatabase, value)
 end
 
 function PagesDatabase.IncrementToPageIdAsync(self: PagesDatabase, pageId: number)
 	while self._lastIncrementedIndex < pageId do
+		local pages = assert(self._pages, "Cannot advance a static PagesDatabase past its stored pages")
+
 		self._lastIncrementedIndex += 1
-		self._pages:AdvanceToNextPageAsync()
+		pages:AdvanceToNextPageAsync()
 		self:_storeState()
 	end
 end
@@ -63,9 +106,11 @@ function PagesDatabase._getPageState(self: PagesDatabase, pageId: number)
 end
 
 function PagesDatabase._storeState(self: PagesDatabase)
+	local pages = assert(self._pages, "No pages")
+
 	self._pageData[self._lastIncrementedIndex] = {
-		currentPage = self._pages:GetCurrentPage(),
-		isFinished = self._pages.IsFinished,
+		currentPage = pages:GetCurrentPage(),
+		isFinished = pages.IsFinished,
 	}
 end
 

package/src/Shared/Proxy/PagesDatabase.spec.lua

@@ -0,0 +1,106 @@
+--!strict
+--[[
+	@class PagesDatabase.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local PagesDatabase = require("PagesDatabase")
+local PagesProxy = require("PagesProxy")
+local PagesUtils = require("PagesUtils")
+local PromiseTestUtils = require("PromiseTestUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("PagesDatabase.fromPageData", function()
+	it("should store each page with the last one finished", function()
+		local database = PagesDatabase.fromPageData({
+			{ "a", "b" },
+			{ "c" },
+		})
+
+		expect(PagesDatabase.isPagesDatabase(database)).toBe(true)
+		expect(database:GetPage(1)).toEqual({ "a", "b" })
+		expect(database:GetIsFinished(1)).toBe(false)
+		expect(database:GetPage(2)).toEqual({ "c" })
+		expect(database:GetIsFinished(2)).toBe(true)
+	end)
+
+	it("should mirror an empty engine result as one finished empty page", function()
+		local database = PagesDatabase.fromPageData({})
+
+		expect(database:GetPage(1)).toEqual({})
+		expect(database:GetIsFinished(1)).toBe(true)
+	end)
+
+	it("should no-op advancement to already-stored pages", function()
+		local database = PagesDatabase.fromPageData({ { "a" }, { "b" } })
+
+		database:IncrementToPageIdAsync(2)
+
+		expect(database:GetPage(2)).toEqual({ "b" })
+	end)
+
+	it("should error on advancement past the stored pages", function()
+		local database = PagesDatabase.fromPageData({ { "a" } })
+
+		expect(function()
+			database:IncrementToPageIdAsync(2)
+		end).toThrow()
+	end)
+end)
+
+describe("PagesProxy over a static database", function()
+	it("should duck-type as a pages instance and iterate every page", function()
+		local proxy = PagesProxy.new(PagesDatabase.fromPageData({
+			{ "a", "b" },
+			{ "c" },
+		}))
+
+		expect(PagesProxy.isPagesProxy(proxy)).toBe(true)
+		expect(proxy:GetCurrentPage()).toEqual({ "a", "b" })
+		expect((proxy :: any).IsFinished).toBe(false)
+
+		proxy:AdvanceToNextPageAsync()
+
+		expect(proxy:GetCurrentPage()).toEqual({ "c" })
+		expect((proxy :: any).IsFinished).toBe(true)
+		expect(function()
+			proxy:AdvanceToNextPageAsync()
+		end).toThrow()
+	end)
+
+	it("should clone without sharing advancement state", function()
+		local proxy = PagesProxy.new(PagesDatabase.fromPageData({ { "a" }, { "b" } }))
+		local clone = proxy:Clone()
+
+		clone:AdvanceToNextPageAsync()
+
+		expect(proxy:GetCurrentPage()).toEqual({ "a" })
+		expect(clone:GetCurrentPage()).toEqual({ "b" })
+	end)
+end)
+
+describe("PagesUtils.promiseAdvanceToNextPage", function()
+	it("should resolve the next page's content for a proxy", function()
+		local proxy = PagesProxy.new(PagesDatabase.fromPageData({ { "a" }, { "b" } }))
+
+		local promise = PagesUtils.promiseAdvanceToNextPage(proxy :: any)
+		local outcome, value = PromiseTestUtils.awaitOutcome(promise)
+
+		expect(outcome).toBe("resolved")
+		expect(value).toEqual({ "b" })
+	end)
+
+	it("should reject when the proxy is already finished", function()
+		local proxy = PagesProxy.new(PagesDatabase.fromPageData({ { "a" } }))
+
+		local promise = PagesUtils.promiseAdvanceToNextPage(proxy :: any)
+		local outcome = PromiseTestUtils.awaitOutcome(promise)
+
+		expect(outcome).toBe("rejected")
+	end)
+end)

package/src/jest.config.lua

@@ -0,0 +1,3 @@
+return {
+	testMatch = { "**/*.spec" },
+}

package/test/default.project.json

@@ -0,0 +1,17 @@
+{
+  "name": "PagesUtilsTest",
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "$properties": {
+        "LoadStringEnabled": true
+      },
+      "pagesutils": {
+        "$path": ".."
+      },
+      "Script": {
+        "$path": "scripts/Server"
+      }
+    }
+  }
+}

package/test/scripts/Server/ServerMain.server.lua

@@ -0,0 +1,12 @@
+--!nonstrict
+local ServerScriptService = game:GetService("ServerScriptService")
+
+local root = ServerScriptService.pagesutils
+local loader = root:FindFirstChild("LoaderUtils", true).Parent
+local require = require(loader).bootstrapGame(root)
+
+local NevermoreTestRunnerUtils = require("NevermoreTestRunnerUtils")
+
+if NevermoreTestRunnerUtils.runTestsIfNeededAsync(root) then
+	return
+end