@quenty/promise 10.20.0 → 10.21.0

package/CHANGELOG.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/promise",
-  "version": "10.20.0",
+  "version": "10.21.0",
   "description": "Promise implementation for Roblox",
   "keywords": [
     "Roblox",
@@ -30,14 +30,14 @@
   "dependencies": {
     "@quenty/deferred": "2.3.2",
     "@quenty/loader": "10.11.0",
-    "@quenty/maid": "3.10.0",
+    "@quenty/maid": "3.11.0",
     "@quenty/math": "2.7.5",
-    "@quenty/nevermore-test-runner": "1.4.0",
+    "@quenty/nevermore-test-runner": "1.5.0",
     "@quenty/signal": "7.13.1",
     "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "647acfad93dca41c38f59cda247d2bfc0fff36d4"
+  "gitHead": "1de37218a2bedb8e3f8614a2e09bba9eddc812da"
 }

package/src/Shared/Promise.lua

@@ -188,7 +188,8 @@ end
 
 --[=[
 	Yields until the promise is complete, and errors if an error
-	exists, otherwise returns the fulfilled results.
+	exists, otherwise returns the fulfilled results. Raising the rejection to the caller consumes it —
+	no uncaught-exception warning fires for a rejection surfaced here.
 
 	@yields
 	@return T
@@ -197,6 +198,7 @@ function Promise.Wait<T...>(self: Promise<T...>): T...
 	if self._fulfilled then
 		return table.unpack(self._fulfilled, 1, self._fulfilled.n)
 	elseif self._rejected then
+		self._unconsumedException = false
 		error(tostring(self._rejected[1]), 2)
 	else
 		local waitingCoroutine = coroutine.running()
@@ -227,7 +229,8 @@ end
 
 --[=[
 	Yields until the promise is complete, then returns a boolean indicating
-	the result, followed by the values from the promise.
+	the result, followed by the values from the promise. Reading the outcome consumes a rejection — the
+	caller has inspected it, so no uncaught-exception warning fires for it.
 
 	@yields
 	@return boolean, T
@@ -236,6 +239,7 @@ function Promise.Yield<T...>(self: Promise<T...>): (boolean, T...)
 	if self._fulfilled then
 		return true, table.unpack(self._fulfilled, 1, self._fulfilled.n)
 	elseif self._rejected then
+		self._unconsumedException = false
 		return false, table.unpack(self._rejected, 1, self._rejected.n)
 	else
 		local waitingCoroutine = coroutine.running()
@@ -346,7 +350,7 @@ function Promise.Reject<T...>(self: Promise<T...>, ...: any): ()
 	self:_reject(table.pack(...))
 end
 
-function Promise._reject<T...>(self: Promise<T...>, values: { any }): ()
+function Promise._reject<T...>(self: Promise<T...>, values: { n: number, [number]: any }): ()
 	if not self._pendingExecuteList then
 		return
 	end
@@ -359,8 +363,11 @@ function Promise._reject<T...>(self: Promise<T...>, values: { any }): ()
 		self:_executeThen(unpack(data))
 	end
 
-	-- Check for uncaught exceptions
-	if self._unconsumedException and self._rejected.n > 0 then
+	-- Check for uncaught exceptions. A single empty table carries no more information than an
+	-- empty rejection (aggregators may reject with an empty results table), so it is not
+	-- reported either.
+	local isEmptyTableRejection = values.n == 1 and type(values[1]) == "table" and next(values[1]) == nil
+	if self._unconsumedException and values.n > 0 and not isEmptyTableRejection then
 		task.defer(function()
 			-- Yield to end of frame, giving control back to Roblox.
 			-- This is the equivalent of giving something back to a task manager.
@@ -381,8 +388,10 @@ end
 
 function Promise._toHumanReadable<T...>(_self: Promise<T...>, data: any): string
 	if type(data) == "table" then
+		-- A custom __tostring is the best human-readable form; only address-form tables
+		-- ("table: 0x...") fall through to JSON encoding.
 		local converted = tostring(data)
-		if string.sub(converted, 1, 8) ~= "table: 0x" then
+		if string.sub(converted, 1, 9) ~= "table: 0x" then
 			return converted
 		end
 
@@ -501,7 +510,8 @@ function Promise.Destroy<T...>(self: Promise<T...>): ()
 end
 
 --[=[
-	Returns the results from the promise.
+	Returns the results from the promise. Reading the outcome consumes a rejection — the caller has
+	inspected it, so no uncaught-exception warning fires for it.
 
 	:::warning
 	This API surface will error if the promise is still pending.
@@ -512,6 +522,7 @@ end
 ]=]
 function Promise.GetResults<T...>(self: Promise<T...>): (boolean, T...)
 	if self._rejected then
+		self._unconsumedException = false
 		return false, table.unpack(self._rejected, 1, self._rejected.n)
 	elseif self._fulfilled then
 		return true, table.unpack(self._fulfilled, 1, self._fulfilled.n)

package/src/Shared/Promise.spec.lua

@@ -0,0 +1,447 @@
+--!nonstrict
+--[[
+	@class Promise.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+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("Promise.isPromise", function()
+	it("returns true for a promise", function()
+		expect(Promise.isPromise(Promise.new())).toEqual(true)
+		expect(Promise.isPromise(Promise.resolved(1))).toEqual(true)
+	end)
+
+	it("returns false for non-promise values", function()
+		expect(Promise.isPromise(nil)).toEqual(false)
+		expect(Promise.isPromise(5)).toEqual(false)
+		expect(Promise.isPromise("Promise")).toEqual(false)
+		expect(Promise.isPromise({})).toEqual(false)
+		expect(Promise.isPromise({ ClassName = "NotAPromise" })).toEqual(false)
+	end)
+end)
+
+describe("Promise.new", function()
+	it("starts pending with no executor", function()
+		local promise = Promise.new()
+		expect(promise:IsPending()).toEqual(true)
+		expect(promise:IsFulfilled()).toEqual(false)
+		expect(promise:IsRejected()).toEqual(false)
+	end)
+
+	it("resolves synchronously when the executor calls resolve", function()
+		local promise = Promise.new(function(resolve)
+			resolve("value")
+		end)
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("value")
+	end)
+
+	it("rejects when the executor calls reject", function()
+		local promise = Promise.new(function(_resolve, reject)
+			reject("boom")
+		end)
+
+		local outcome, err = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("rejected")
+		expect(err).toEqual("boom")
+	end)
+end)
+
+describe("Promise.spawn", function()
+	it("resolves from a spawned executor", function()
+		local promise = Promise.spawn(function(resolve)
+			resolve("spawned")
+		end)
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("spawned")
+	end)
+end)
+
+describe("Promise.delay", function()
+	it("resolves after the delay elapses", function()
+		local promise = Promise.delay(0, function(resolve)
+			resolve("delayed")
+		end)
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("delayed")
+	end)
+
+	it("is pending before the delay elapses", function()
+		local promise = Promise.delay(10, function(resolve)
+			resolve("late")
+		end)
+		expect(promise:IsPending()).toEqual(true)
+	end)
+end)
+
+describe("Promise.defer", function()
+	it("resolves from a deferred executor", function()
+		local promise = Promise.defer(function(resolve)
+			resolve("deferred")
+		end)
+
+		expect(promise:IsPending()).toEqual(true)
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("deferred")
+	end)
+end)
+
+describe("Promise.resolved", function()
+	it("creates an already-fulfilled promise", function()
+		local promise = Promise.resolved("done")
+		expect(promise:IsFulfilled()).toEqual(true)
+		expect(promise:IsPending()).toEqual(false)
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("done")
+	end)
+
+	it("reuses a single shared promise when resolving with no values", function()
+		expect(Promise.resolved()).toBe(Promise.resolved())
+	end)
+
+	it("returns the same promise when resolving an already-settled promise", function()
+		local inner = Promise.resolved("inner")
+		expect(Promise.resolved(inner)).toBe(inner)
+	end)
+end)
+
+describe("Promise.rejected", function()
+	it("creates an already-rejected promise", function()
+		local outcome, err = PromiseTestUtils.awaitOutcome(Promise.rejected("nope"))
+		expect(outcome).toEqual("rejected")
+		expect(err).toEqual("nope")
+	end)
+
+	it("reuses a single shared promise when rejecting with no values", function()
+		expect(Promise.rejected()).toBe(Promise.rejected())
+	end)
+end)
+
+describe("Promise:Resolve", function()
+	it("fulfills a pending promise", function()
+		local promise = Promise.new()
+		promise:Resolve(1, 2, 3)
+
+		local ok, a, b, c = promise:GetResults()
+		expect(ok).toEqual(true)
+		expect(a).toEqual(1)
+		expect(b).toEqual(2)
+		expect(c).toEqual(3)
+	end)
+
+	it("rejects with a TypeError when resolving to itself", function()
+		local promise = Promise.new()
+		promise:Resolve(promise)
+
+		local outcome, err = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("rejected")
+		expect(string.find(tostring(err), "Resolved to self", 1, true) ~= nil).toEqual(true)
+	end)
+
+	it("adopts the state of a resolved promise", function()
+		local promise = Promise.new()
+		promise:Resolve(Promise.resolved("adopted"))
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("adopted")
+	end)
+
+	it("adopts the rejection of a rejected promise", function()
+		local promise = Promise.new()
+		promise:Resolve(Promise.rejected("adopted rejection"))
+
+		local outcome, err = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("rejected")
+		expect(err).toEqual("adopted rejection")
+	end)
+
+	it("adopts the state of a pending promise once it settles", function()
+		local inner = Promise.new()
+		local promise = Promise.new()
+		promise:Resolve(inner)
+
+		expect(promise:IsPending()).toEqual(true)
+
+		inner:Resolve("later")
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("later")
+	end)
+
+	it("is a no-op once the promise has settled", function()
+		local promise = Promise.resolved("first")
+		promise:Resolve("second")
+
+		local _ok, value = promise:GetResults()
+		expect(value).toEqual("first")
+	end)
+end)
+
+describe("Promise:Reject", function()
+	it("rejects a pending promise", function()
+		local promise = Promise.new()
+		promise:Catch(function() end)
+		promise:Reject("rejected")
+
+		local ok, err = promise:GetResults()
+		expect(ok).toEqual(false)
+		expect(err).toEqual("rejected")
+	end)
+
+	it("is a no-op once the promise has settled", function()
+		local promise = Promise.resolved("value")
+		promise:Reject("too late")
+		expect(promise:IsFulfilled()).toEqual(true)
+		expect(promise:IsRejected()).toEqual(false)
+	end)
+end)
+
+describe("Promise:Wait", function()
+	it("returns the fulfilled values", function()
+		local a, b = Promise.resolved(1, 2):Wait()
+		expect(a).toEqual(1)
+		expect(b).toEqual(2)
+	end)
+
+	it("errors when the promise is rejected", function()
+		local promise = Promise.rejected("boom")
+		local ok, err = pcall(function()
+			promise:Wait()
+		end)
+		expect(ok).toEqual(false)
+		expect(string.find(tostring(err), "boom", 1, true) ~= nil).toEqual(true)
+	end)
+
+	it("yields until a pending promise resolves", function()
+		local promise = Promise.new()
+		task.defer(function()
+			promise:Resolve("eventually")
+		end)
+		expect(promise:Wait()).toEqual("eventually")
+	end)
+end)
+
+describe("Promise:Yield", function()
+	it("returns true and the values when fulfilled", function()
+		local ok, value = Promise.resolved("ok"):Yield()
+		expect(ok).toEqual(true)
+		expect(value).toEqual("ok")
+	end)
+
+	it("returns false and the error when rejected", function()
+		local promise = Promise.rejected("bad")
+		local ok, err = promise:Yield()
+		expect(ok).toEqual(false)
+		expect(err).toEqual("bad")
+	end)
+
+	it("yields until a pending promise settles", function()
+		local promise = Promise.new()
+		task.defer(function()
+			promise:Resolve("settled")
+		end)
+		local ok, value = promise:Yield()
+		expect(ok).toEqual(true)
+		expect(value).toEqual("settled")
+	end)
+end)
+
+describe("Promise:Then", function()
+	it("calls onFulfilled with the resolved value", function()
+		local outcome, value = PromiseTestUtils.awaitOutcome(Promise.resolved(10):Then(function(n)
+			return n * 2
+		end))
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual(20)
+	end)
+
+	it("calls onRejected with the rejection reason", function()
+		local outcome, value = PromiseTestUtils.awaitOutcome(Promise.rejected("err"):Then(nil, function(err)
+			return "recovered from " .. err
+		end))
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("recovered from err")
+	end)
+
+	it("propagates fulfillment when onFulfilled is omitted", function()
+		local outcome, value = PromiseTestUtils.awaitOutcome(Promise.resolved("passthrough"):Then(nil, function() end))
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("passthrough")
+	end)
+
+	it("propagates rejection when onRejected is omitted", function()
+		local source = Promise.rejected("still bad")
+		-- Then with no onRejected does not consume the source rejection, so handle it separately to
+		-- avoid an uncaught-exception warning.
+		source:Catch(function() end)
+
+		local outcome, err = PromiseTestUtils.awaitOutcome(source:Then(function() end))
+		expect(outcome).toEqual("rejected")
+		expect(err).toEqual("still bad")
+	end)
+
+	it("runs handlers attached while pending", function()
+		local promise = Promise.new()
+		local chained = promise:Then(function(n)
+			return n + 1
+		end)
+
+		task.defer(function()
+			promise:Resolve(41)
+		end)
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(chained)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual(42)
+	end)
+
+	it("chains when the handler returns a promise", function()
+		local outcome, value = PromiseTestUtils.awaitOutcome(Promise.resolved(1):Then(function()
+			return Promise.resolved("from inner promise")
+		end))
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("from inner promise")
+	end)
+end)
+
+describe("Promise:Catch", function()
+	it("handles a rejection", function()
+		local outcome, value = PromiseTestUtils.awaitOutcome(Promise.rejected("caught"):Catch(function(err)
+			return "handled " .. err
+		end))
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("handled caught")
+	end)
+
+	it("does not fire for a fulfilled promise", function()
+		local called = { value = false }
+		local outcome, value = PromiseTestUtils.awaitOutcome(Promise.resolved("fine"):Catch(function()
+			called.value = true
+		end))
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("fine")
+		expect(called.value).toEqual(false)
+	end)
+end)
+
+describe("Promise:Tap", function()
+	it("passes the original value through regardless of the handler return", function()
+		local seen = {}
+		local outcome, value = PromiseTestUtils.awaitOutcome(Promise.resolved("original"):Tap(function(v)
+			seen.value = v
+			return "ignored"
+		end))
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("original")
+		expect(seen.value).toEqual("original")
+	end)
+end)
+
+describe("Promise:Finally", function()
+	it("runs on fulfillment", function()
+		local ran = { value = false }
+		Promise.resolved("x"):Finally(function()
+			ran.value = true
+		end)
+		expect(ran.value).toEqual(true)
+	end)
+
+	it("runs on rejection", function()
+		local ran = { value = false }
+		Promise.rejected("x"):Finally(function()
+			ran.value = true
+		end)
+		expect(ran.value).toEqual(true)
+	end)
+end)
+
+describe("Promise:Destroy", function()
+	it("rejects the promise", function()
+		local promise = Promise.new()
+		promise:Catch(function() end)
+		promise:Destroy()
+		expect(promise:IsRejected()).toEqual(true)
+	end)
+end)
+
+describe("Promise:GetResults", function()
+	it("errors while pending", function()
+		local ok, err = pcall(function()
+			Promise.new():GetResults()
+		end)
+		expect(ok).toEqual(false)
+		expect(string.find(tostring(err), "pending", 1, true) ~= nil).toEqual(true)
+	end)
+
+	it("returns true and the values when fulfilled", function()
+		local ok, a, b = Promise.resolved("a", "b"):GetResults()
+		expect(ok).toEqual(true)
+		expect(a).toEqual("a")
+		expect(b).toEqual("b")
+	end)
+
+	it("returns false and the error when rejected", function()
+		local promise = Promise.rejected("failure")
+		local ok, err = promise:GetResults()
+		expect(ok).toEqual(false)
+		expect(err).toEqual("failure")
+	end)
+
+	it("consumes the rejection", function()
+		local promise = Promise.rejected("failure")
+		promise:GetResults()
+		expect((promise :: any)._unconsumedException).toEqual(false)
+	end)
+end)
+
+describe("Promise._toHumanReadable", function()
+	local promise = Promise.new()
+
+	it("stringifies non-table values", function()
+		expect(promise:_toHumanReadable("failure")).toEqual("failure")
+		expect(promise:_toHumanReadable(5)).toEqual("5")
+		expect(promise:_toHumanReadable(nil)).toEqual("nil")
+		expect(promise:_toHumanReadable(false)).toEqual("false")
+	end)
+
+	it("uses a table's custom __tostring when present", function()
+		local data = setmetatable({}, {
+			__tostring = function()
+				return "CustomError<oops>"
+			end,
+		})
+		expect(promise:_toHumanReadable(data)).toEqual("CustomError<oops>")
+	end)
+
+	it("JSON-encodes a plain table instead of returning its address", function()
+		expect(promise:_toHumanReadable({ code = 500 })).toEqual('{"code":500}')
+		expect(promise:_toHumanReadable({})).toEqual("[]")
+	end)
+
+	it("falls back to tostring when the table cannot be JSON-encoded", function()
+		local data = {}
+		data.cycle = data
+		local result = promise:_toHumanReadable(data)
+		expect(string.sub(result, 1, 9)).toEqual("table: 0x")
+	end)
+end)

package/src/Shared/PromiseRetryUtils.spec.lua

@@ -20,8 +20,6 @@ local FAST_OPTIONS = {
 	printWarning = false,
 }
 
--- Returns a callback that rejects with `errorMessage` for its first `failureCount` attempts, then
--- resolves with `value`, and a counter table exposing how many attempts were made.
 local function newFlakyCallback(failureCount: number, errorMessage: string, value: any)
 	local attempts = { count = 0 }
 	local function callback()
@@ -103,7 +101,6 @@ describe("PromiseRetryUtils.retry", function()
 
 		expect(outcome).toEqual("rejected")
 		expect(attempts.count).toEqual(3)
-		-- Consulted after every failure, including the final attempt.
 		expect(consulted.count).toEqual(3)
 	end)
 end)

package/src/Shared/PromiseUtils.lua

@@ -145,6 +145,11 @@ end
 --[=[
 	Combines the result of promises together
 
+	On failure, rejects with the results table when any input rejected with a value (the
+	error is stored under that input's key). When every failing input rejected with no
+	values (i.e. was cancelled), rejects with no values so the cancellation stays a
+	cancellation instead of becoming a valued rejection of partial results.
+
 	@param stateTable any
 	@return Promise<any>
 ]=]
@@ -168,16 +173,25 @@ function PromiseUtils.combine(stateTable: any): Promise.Promise<any>
 
 	local returnPromise = Promise.new()
 	local allFulfilled = true
+	local sawRejectionValue = false
 
 	local function syncronize(key, isFullfilled)
-		return function(value)
+		return function(value, ...)
 			allFulfilled = allFulfilled and isFullfilled
+			if not isFullfilled and (value ~= nil or select("#", ...) > 0) then
+				sawRejectionValue = true
+			end
 			results[key] = value
 			remainingCount = remainingCount - 1
 
 			if remainingCount == 0 then
-				local method = allFulfilled and "Resolve" or "Reject"
-				returnPromise[method](returnPromise, results)
+				if allFulfilled then
+					returnPromise:Resolve(results)
+				elseif sawRejectionValue then
+					returnPromise:Reject(results)
+				else
+					returnPromise:Reject()
+				end
 			end
 		end
 	end

package/src/Shared/PromiseUtils.spec.lua

@@ -0,0 +1,275 @@
+--!nonstrict
+--[[
+	@class PromiseUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local Promise = require("Promise")
+local PromiseTestUtils = require("PromiseTestUtils")
+local PromiseUtils = require("PromiseUtils")
+local Signal = require("Signal")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("PromiseUtils.any / race", function()
+	it("is aliased as race", function()
+		expect(PromiseUtils.race).toBe(PromiseUtils.any)
+	end)
+
+	it("resolves with the first promise to resolve", function()
+		local a = Promise.new()
+		local b = Promise.resolved("b wins")
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(PromiseUtils.any({ a, b }))
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("b wins")
+
+		a:Resolve("ignored")
+	end)
+
+	it("rejects if the first to settle rejects", function()
+		local outcome, err =
+			PromiseTestUtils.awaitOutcome(PromiseUtils.any({ Promise.new(), Promise.rejected("boom") }))
+		expect(outcome).toEqual("rejected")
+		expect(err).toEqual("boom")
+	end)
+end)
+
+describe("PromiseUtils.delayed", function()
+	it("resolves after the delay", function()
+		local outcome = PromiseTestUtils.awaitOutcome(PromiseUtils.delayed(0))
+		expect(outcome).toEqual("resolved")
+	end)
+
+	it("is pending before the delay elapses", function()
+		local promise = PromiseUtils.delayed(10)
+		expect(promise:IsPending()).toEqual(true)
+	end)
+end)
+
+describe("PromiseUtils.all", function()
+	it("resolves an empty list immediately", function()
+		expect(PromiseUtils.all({}):IsFulfilled()).toEqual(true)
+	end)
+
+	it("returns the same promise for a single-element list", function()
+		local only = Promise.resolved("only")
+		expect(PromiseUtils.all({ only })).toBe(only)
+	end)
+
+	it("resolves with every value once all resolve", function()
+		local combined = PromiseUtils.all({ Promise.resolved("a"), Promise.resolved("b"), Promise.resolved("c") })
+
+		expect(PromiseTestUtils.awaitSettled(combined)).toEqual(true)
+		local ok, a, b, c = combined:GetResults()
+		expect(ok).toEqual(true)
+		expect(a).toEqual("a")
+		expect(b).toEqual("b")
+		expect(c).toEqual("c")
+	end)
+
+	it("rejects if any promise rejects", function()
+		-- all() rejects with the positional results array (resolved values and rejection reasons mixed
+		-- by index), so only the rejected outcome itself is asserted here.
+		local outcome =
+			PromiseTestUtils.awaitOutcome(PromiseUtils.all({ Promise.resolved("a"), Promise.rejected("nope") }))
+		expect(outcome).toEqual("rejected")
+	end)
+
+	it("waits for pending promises before resolving", function()
+		local pending = Promise.new()
+		local combined = PromiseUtils.all({ Promise.resolved("a"), pending })
+		expect(combined:IsPending()).toEqual(true)
+
+		pending:Resolve("b")
+		expect(PromiseTestUtils.awaitSettled(combined)).toEqual(true)
+		local ok, a, b = combined:GetResults()
+		expect(ok).toEqual(true)
+		expect(a).toEqual("a")
+		expect(b).toEqual("b")
+	end)
+end)
+
+describe("PromiseUtils.firstSuccessOrLastFailure", function()
+	it("resolves with the first success", function()
+		local outcome, value = PromiseTestUtils.awaitOutcome(
+			PromiseUtils.firstSuccessOrLastFailure({ Promise.rejected("bad"), Promise.resolved("good") })
+		)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("good")
+	end)
+
+	it("rejects with the last failure when all fail", function()
+		local outcome, err = PromiseTestUtils.awaitOutcome(
+			PromiseUtils.firstSuccessOrLastFailure({ Promise.rejected("first"), Promise.rejected("last") })
+		)
+		expect(outcome).toEqual("rejected")
+		expect(err).toEqual("last")
+	end)
+
+	it("returns the same promise for a single-element list", function()
+		local only = Promise.resolved("only")
+		expect(PromiseUtils.firstSuccessOrLastFailure({ only })).toBe(only)
+	end)
+end)
+
+describe("PromiseUtils.combine", function()
+	it("passes through a table with no promises", function()
+		local outcome, value = PromiseTestUtils.awaitOutcome(PromiseUtils.combine({ a = 1, b = 2 }))
+		expect(outcome).toEqual("resolved")
+		expect(value.a).toEqual(1)
+		expect(value.b).toEqual(2)
+	end)
+
+	it("resolves with a table mixing promises and plain values", function()
+		local combined = PromiseUtils.combine({ a = Promise.resolved("A"), b = "B" })
+
+		expect(PromiseTestUtils.awaitSettled(combined)).toEqual(true)
+		local ok, results = combined:GetResults()
+		expect(ok).toEqual(true)
+		expect(results.a).toEqual("A")
+		expect(results.b).toEqual("B")
+	end)
+
+	it("rejects if any promise rejects", function()
+		local outcome = PromiseTestUtils.awaitOutcome(PromiseUtils.combine({ a = Promise.rejected("bad"), b = "B" }))
+		expect(outcome).toEqual("rejected")
+	end)
+
+	it("rejects with the results table carrying the error under its key", function()
+		local combined = PromiseUtils.combine({
+			a = Promise.rejected("bad"),
+			b = Promise.resolved("B"),
+		})
+		combined:Catch(function() end)
+
+		expect(PromiseTestUtils.awaitSettled(combined)).toEqual(true)
+		local ok, results = combined:GetResults()
+		expect(ok).toEqual(false)
+		expect(results.a).toEqual("bad")
+		expect(results.b).toEqual("B")
+	end)
+
+	it("rejects with no values when the only failure is a cancellation", function()
+		local pending = Promise.new()
+		local combined = PromiseUtils.combine({
+			a = pending,
+			b = Promise.resolved("B"),
+		})
+
+		local rejectionCount = nil
+		combined:Then(nil, function(...)
+			rejectionCount = select("#", ...)
+		end)
+
+		pending:Reject() -- cancellation: rejection with no values
+
+		expect(PromiseTestUtils.awaitSettled(combined)).toEqual(true)
+		expect(combined:IsRejected()).toEqual(true)
+		expect(rejectionCount).toEqual(0)
+	end)
+
+	it("still rejects with the results table when a cancellation and a real error mix", function()
+		local cancelled = Promise.new()
+		local combined = PromiseUtils.combine({
+			a = cancelled,
+			b = Promise.rejected("bad"),
+			c = Promise.resolved("C"),
+		})
+		combined:Catch(function() end)
+
+		cancelled:Reject()
+
+		expect(PromiseTestUtils.awaitSettled(combined)).toEqual(true)
+		local ok, results = combined:GetResults()
+		expect(ok).toEqual(false)
+		expect(results.a).toEqual(nil)
+		expect(results.b).toEqual("bad")
+		expect(results.c).toEqual("C")
+	end)
+end)
+
+describe("PromiseUtils.invert", function()
+	it("turns a resolved promise into a rejection", function()
+		local outcome, err = PromiseTestUtils.awaitOutcome(PromiseUtils.invert(Promise.resolved("was ok")))
+		expect(outcome).toEqual("rejected")
+		expect(err).toEqual("was ok")
+	end)
+
+	it("turns a rejected promise into a resolution", function()
+		local source = Promise.rejected("was bad")
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(PromiseUtils.invert(source))
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("was bad")
+	end)
+
+	it("inverts a pending promise once it settles", function()
+		local source = Promise.new()
+		local inverted = PromiseUtils.invert(source)
+		expect(inverted:IsPending()).toEqual(true)
+
+		source:Resolve("later")
+		local outcome, err = PromiseTestUtils.awaitOutcome(inverted)
+		expect(outcome).toEqual("rejected")
+		expect(err).toEqual("later")
+	end)
+end)
+
+describe("PromiseUtils.fromSignal", function()
+	it("resolves when the signal fires", function()
+		local signal = Signal.new()
+		local promise = PromiseUtils.fromSignal(signal)
+		expect(promise:IsPending()).toEqual(true)
+
+		signal:Fire("fired")
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("fired")
+
+		signal:Destroy()
+	end)
+
+	it("disconnects the signal once settled", function()
+		local signal = Signal.new()
+		local promise = PromiseUtils.fromSignal(signal)
+
+		signal:Fire("first")
+		PromiseTestUtils.awaitSettled(promise)
+
+		-- A second fire must not change the already-resolved value.
+		signal:Fire("second")
+		local _ok, value = promise:GetResults()
+		expect(value).toEqual("first")
+
+		signal:Destroy()
+	end)
+end)
+
+describe("PromiseUtils.timeout", function()
+	it("returns the same promise when it is already settled", function()
+		local settled = Promise.resolved("done")
+		expect(PromiseUtils.timeout(1, settled)).toBe(settled)
+	end)
+
+	it("rejects once the timeout elapses", function()
+		local outcome = PromiseTestUtils.awaitOutcome(PromiseUtils.timeout(0, Promise.new()))
+		expect(outcome).toEqual("rejected")
+	end)
+
+	it("resolves with the underlying value if it settles before the timeout", function()
+		local source = Promise.new()
+		local promise = PromiseUtils.timeout(10, source)
+		expect(promise:IsPending()).toEqual(true)
+
+		source:Resolve("in time")
+		local outcome, value = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("in time")
+	end)
+end)

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

@@ -0,0 +1,69 @@
+--!nonstrict
+--[[
+	@class PendingPromiseTracker.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local PendingPromiseTracker = require("PendingPromiseTracker")
+local Promise = require("Promise")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("PendingPromiseTracker", function()
+	it("starts empty", function()
+		local tracker = PendingPromiseTracker.new()
+		expect(#tracker:GetAll()).toEqual(0)
+	end)
+
+	it("tracks a pending promise", function()
+		local tracker = PendingPromiseTracker.new()
+		tracker:Add(Promise.new())
+		expect(#tracker:GetAll()).toEqual(1)
+	end)
+
+	it("ignores an already-settled promise", function()
+		local tracker = PendingPromiseTracker.new()
+		tracker:Add(Promise.resolved("done"))
+		expect(#tracker:GetAll()).toEqual(0)
+	end)
+
+	it("drops a promise once it resolves", function()
+		local tracker = PendingPromiseTracker.new()
+		local promise = Promise.new()
+		tracker:Add(promise)
+		expect(#tracker:GetAll()).toEqual(1)
+
+		promise:Resolve(true)
+		expect(#tracker:GetAll()).toEqual(0)
+	end)
+
+	it("drops a promise once it rejects", function()
+		local tracker = PendingPromiseTracker.new()
+		local promise = Promise.new()
+		promise:Catch(function() end)
+		tracker:Add(promise)
+		expect(#tracker:GetAll()).toEqual(1)
+
+		promise:Reject("boom")
+		expect(#tracker:GetAll()).toEqual(0)
+	end)
+
+	it("tracks multiple pending promises independently", function()
+		local tracker = PendingPromiseTracker.new()
+		local a = Promise.new()
+		local b = Promise.new()
+		tracker:Add(a)
+		tracker:Add(b)
+		expect(#tracker:GetAll()).toEqual(2)
+
+		a:Resolve(true)
+		expect(#tracker:GetAll()).toEqual(1)
+
+		b:Resolve(true)
+		expect(#tracker:GetAll()).toEqual(0)
+	end)
+end)

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

@@ -0,0 +1,41 @@
+--!nonstrict
+--[[
+	@class PromiseInstanceUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local PromiseInstanceUtils = require("PromiseInstanceUtils")
+local PromiseTestUtils = require("PromiseTestUtils")
+
+local Workspace = game:GetService("Workspace")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("PromiseInstanceUtils.promiseRemoved", function()
+	it("is pending while the instance stays parented", function()
+		local folder = Instance.new("Folder")
+		folder.Parent = Workspace
+
+		local promise = PromiseInstanceUtils.promiseRemoved(folder)
+		expect(promise:IsPending()).toEqual(true)
+
+		folder:Destroy()
+	end)
+
+	it("resolves when the instance is removed from the game", function()
+		local folder = Instance.new("Folder")
+		folder.Parent = Workspace
+
+		local promise = PromiseInstanceUtils.promiseRemoved(folder)
+		folder.Parent = nil
+
+		expect(PromiseTestUtils.awaitSettled(promise)).toEqual(true)
+		expect(promise:IsFulfilled()).toEqual(true)
+
+		folder:Destroy()
+	end)
+end)

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

@@ -0,0 +1,64 @@
+--!nonstrict
+--[[
+	@class promiseChild.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local PromiseTestUtils = require("PromiseTestUtils")
+local promiseChild = require("promiseChild")
+
+local Workspace = game:GetService("Workspace")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("promiseChild", function()
+	it("resolves immediately when the child already exists", function()
+		local parent = Instance.new("Folder")
+		local child = Instance.new("Folder")
+		child.Name = "Target"
+		child.Parent = parent
+		parent.Parent = Workspace
+
+		local promise = promiseChild(parent, "Target")
+		expect(promise:IsFulfilled()).toEqual(true)
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual(child)
+
+		parent:Destroy()
+	end)
+
+	it("resolves once a matching child is added", function()
+		local parent = Instance.new("Folder")
+		parent.Parent = Workspace
+
+		local promise = promiseChild(parent, "Later")
+		expect(promise:IsPending()).toEqual(true)
+
+		local child = Instance.new("Folder")
+		child.Name = "Later"
+		child.Parent = parent
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual(child)
+
+		parent:Destroy()
+	end)
+
+	it("rejects when the child never appears before the timeout", function()
+		local parent = Instance.new("Folder")
+		parent.Parent = Workspace
+
+		local outcome, err = PromiseTestUtils.awaitOutcome(promiseChild(parent, "Missing", 0.05))
+		expect(outcome).toEqual("rejected")
+		expect(string.find(tostring(err), "Timed out", 1, true) ~= nil).toEqual(true)
+
+		parent:Destroy()
+	end)
+end)

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

@@ -0,0 +1,53 @@
+--!nonstrict
+--[[
+	@class promisePropertyValue.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local PromiseTestUtils = require("PromiseTestUtils")
+local promisePropertyValue = require("promisePropertyValue")
+
+local Workspace = game:GetService("Workspace")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("promisePropertyValue", function()
+	it("resolves immediately when the property is already truthy", function()
+		local folder = Instance.new("Folder")
+		folder.Name = "HasAName"
+		folder.Parent = Workspace
+
+		local promise = promisePropertyValue(folder, "Name")
+		expect(promise:IsFulfilled()).toEqual(true)
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("HasAName")
+
+		folder:Destroy()
+	end)
+
+	it("resolves once a falsy property becomes truthy", function()
+		local objectValue = Instance.new("ObjectValue")
+		objectValue.Parent = Workspace
+		expect(objectValue.Value).toEqual(nil)
+
+		local promise = promisePropertyValue(objectValue, "Value")
+		expect(promise:IsPending()).toEqual(true)
+
+		local target = Instance.new("Folder")
+		target.Parent = Workspace
+		objectValue.Value = target
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(promise)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual(target)
+
+		objectValue:Destroy()
+		target:Destroy()
+	end)
+end)

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

@@ -0,0 +1,26 @@
+--!nonstrict
+--[[
+	@class promiseWait.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local PromiseTestUtils = require("PromiseTestUtils")
+local promiseWait = require("promiseWait")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("promiseWait", function()
+	it("resolves after the delay elapses", function()
+		local outcome = PromiseTestUtils.awaitOutcome(promiseWait(0))
+		expect(outcome).toEqual("resolved")
+	end)
+
+	it("is pending before the delay elapses", function()
+		local promise = promiseWait(10)
+		expect(promise:IsPending()).toEqual(true)
+	end)
+end)