@quenty/promise 10.18.1 → 10.19.0

package/CHANGELOG.md

@@ -3,6 +3,10 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [10.19.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/promise@10.18.1...@quenty/promise@10.19.0) (2026-07-18)
+
+**Note:** Version bump only for package @quenty/promise
+
 ## [10.18.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/promise@10.18.0...@quenty/promise@10.18.1) (2026-05-30)
 
 **Note:** Version bump only for package @quenty/promise

package/deploy.nevermore.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/promise",
-  "version": "10.18.1",
+  "version": "10.19.0",
   "description": "Promise implementation for Roblox",
   "keywords": [
     "Roblox",
@@ -32,10 +32,12 @@
     "@quenty/loader": "10.11.0",
     "@quenty/maid": "3.9.0",
     "@quenty/math": "2.7.5",
-    "@quenty/signal": "7.13.1"
+    "@quenty/nevermore-test-runner": "1.4.0",
+    "@quenty/signal": "7.13.1",
+    "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "598b2b62b36bdcbdbbd56f7db10c399831cc6eba"
+  "gitHead": "cbbb89635bfdcbf32f26a40422ac736292917cca"
 }

package/src/Shared/PromiseRetryUtils.lua

@@ -15,6 +15,9 @@ export type RetryOptions = {
 	initialWaitTime: number,
 	maxAttempts: number,
 	printWarning: boolean,
+	-- Optional predicate consulted after each failure. Returning false stops retrying immediately and
+	-- rejects with that error (for failures that will not resolve by retrying).
+	shouldRetry: ((any) -> boolean)?,
 }
 
 --[=[
@@ -54,6 +57,13 @@ function PromiseRetryUtils.retry<T...>(callback: () -> Promise.Promise<T...>, op
 				return
 			end
 
+			-- Bail out early on a failure that will not resolve by retrying.
+			if options.shouldRetry and not options.shouldRetry(lastResults[2]) then
+				isLoopResolved = true
+				promise:Reject(table.unpack(lastResults, 2, lastResults.n))
+				return
+			end
+
 			if attemptNumber ~= options.maxAttempts then
 				local thisWaitTime = Math.jitter(waitTime * ((options.exponential or 2) ^ (attemptNumber - 1)))
 				if options.printWarning then

package/src/Shared/PromiseRetryUtils.spec.lua

@@ -0,0 +1,109 @@
+--!nonstrict
+--[[
+	@class PromiseRetryUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local Promise = require("Promise")
+local PromiseRetryUtils = require("PromiseRetryUtils")
+local PromiseTestUtils = require("PromiseTestUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local FAST_OPTIONS = {
+	initialWaitTime = 0,
+	maxAttempts = 3,
+	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()
+		attempts.count += 1
+		if attempts.count <= failureCount then
+			-- Reject asynchronously so retry attaches a rejection handler (consuming the exception)
+			-- rather than reading an already-rejected promise, which would be flagged as uncaught.
+			return Promise.defer(function(_resolve, reject)
+				reject(errorMessage)
+			end)
+		end
+		return Promise.resolved(value)
+	end
+	return callback, attempts
+end
+
+describe("PromiseRetryUtils.retry", function()
+	it("resolves on the first attempt without retrying", function()
+		local callback, attempts = newFlakyCallback(0, "boom", "done")
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(PromiseRetryUtils.retry(callback, FAST_OPTIONS))
+
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("done")
+		expect(attempts.count).toEqual(1)
+	end)
+
+	it("retries after a failure and resolves once the callback succeeds", function()
+		local callback, attempts = newFlakyCallback(2, "boom", "done")
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(PromiseRetryUtils.retry(callback, FAST_OPTIONS))
+
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("done")
+		expect(attempts.count).toEqual(3)
+	end)
+
+	it("rejects after exhausting maxAttempts", function()
+		local callback, attempts = newFlakyCallback(math.huge, "always fails", nil)
+
+		local outcome, err = PromiseTestUtils.awaitOutcome(PromiseRetryUtils.retry(callback, FAST_OPTIONS))
+
+		expect(outcome).toEqual("rejected")
+		expect(string.find(tostring(err), "always fails", 1, true) ~= nil).toEqual(true)
+		expect(attempts.count).toEqual(3)
+	end)
+
+	it("stops immediately and rejects with the error when shouldRetry returns false", function()
+		local callback, attempts = newFlakyCallback(math.huge, "fatal 509", nil)
+
+		local outcome, err = PromiseTestUtils.awaitOutcome(PromiseRetryUtils.retry(callback, {
+			initialWaitTime = 0,
+			maxAttempts = 5,
+			printWarning = false,
+			shouldRetry = function()
+				return false
+			end,
+		}))
+
+		expect(outcome).toEqual("rejected")
+		expect(err).toEqual("fatal 509")
+		expect(attempts.count).toEqual(1)
+	end)
+
+	it("keeps retrying while shouldRetry returns true", function()
+		local callback, attempts = newFlakyCallback(math.huge, "retryable", nil)
+		local consulted = { count = 0 }
+
+		local outcome = PromiseTestUtils.awaitOutcome(PromiseRetryUtils.retry(callback, {
+			initialWaitTime = 0,
+			maxAttempts = 3,
+			printWarning = false,
+			shouldRetry = function(err)
+				consulted.count += 1
+				expect(err).toEqual("retryable")
+				return true
+			end,
+		}))
+
+		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/PromiseTestUtils.lua

@@ -0,0 +1,86 @@
+--!strict
+--[=[
+	Test helpers for awaiting promises with a bounded timeout, so a hung promise fails the test
+	instead of freezing the runner. Awaiting races the promise against a timeout rather than polling
+	with `task.wait()`.
+
+	@class PromiseTestUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Promise = require("Promise")
+local PromiseUtils = require("PromiseUtils")
+
+local PromiseTestUtils = {}
+
+local DEFAULT_TIMEOUT = 5
+
+--[=[
+	Yields until the promise settles (resolves or rejects) or the timeout elapses. Races the promise
+	against a timeout instead of polling.
+
+	@param promise Promise
+	@param timeout number? -- Defaults to 5 seconds
+	@return boolean -- true if the promise settled, false if it timed out
+]=]
+function PromiseTestUtils.awaitSettled<T...>(promise: Promise.Promise<T...>, timeout: number?): boolean
+	if not promise:IsPending() then
+		-- Attach a handler so an already-rejected promise is not flagged as an uncaught exception.
+		promise:Catch(function() end)
+		return true
+	end
+
+	local settled = Promise.new()
+	local function markSettled()
+		settled:Resolve(true)
+	end
+	promise:Then(markSettled, markSettled)
+
+	local timedOut = PromiseUtils.delayed(timeout or DEFAULT_TIMEOUT):Then(function()
+		return false
+	end)
+
+	return (PromiseUtils.race({ settled, timedOut }):Wait())
+end
+
+--[=[
+	Yields until the predicate returns a truthy value or the timeout elapses. Used when the awaited
+	condition is observable state rather than a promise.
+
+	@param predicate () -> boolean
+	@param timeout number? -- Defaults to 5 seconds
+	@return boolean -- The final predicate result
+]=]
+function PromiseTestUtils.awaitValue(predicate: () -> boolean, timeout: number?): boolean
+	local deadline = os.clock() + (timeout or DEFAULT_TIMEOUT)
+	while not predicate() and os.clock() < deadline do
+		task.wait()
+	end
+	return predicate()
+end
+
+--[=[
+	Attaches resolve/reject handlers synchronously (so the rejection is always handled and never
+	surfaces as an uncaught error) and yields for the outcome.
+
+	@param promise Promise
+	@param timeout number? -- Defaults to 5 seconds
+	@return "resolved" | "rejected" | "pending"
+	@return any -- The resolved value or rejection error
+]=]
+function PromiseTestUtils.awaitOutcome<T...>(promise: Promise.Promise<T...>, timeout: number?): (string, any)
+	local outcome: string?
+	local payload: any
+	promise:Then(function(value)
+		outcome, payload = "resolved", value
+	end, function(err)
+		outcome, payload = "rejected", err
+	end)
+
+	PromiseTestUtils.awaitSettled(promise, timeout)
+
+	return outcome or "pending", payload
+end
+
+return PromiseTestUtils

package/src/Shared/PromiseTestUtils.spec.lua

@@ -0,0 +1,75 @@
+--!nonstrict
+--[[
+	@class PromiseTestUtils.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
+
+local SHORT_TIMEOUT = 0.1
+
+describe("PromiseTestUtils.awaitSettled", function()
+	it("returns true for an already-resolved promise", function()
+		expect(PromiseTestUtils.awaitSettled(Promise.resolved(1))).toEqual(true)
+	end)
+
+	it("returns true for a rejected promise", function()
+		expect(PromiseTestUtils.awaitSettled(Promise.rejected("boom"))).toEqual(true)
+	end)
+
+	it("returns true once a pending promise resolves", function()
+		local promise = Promise.new()
+		task.defer(function()
+			promise:Resolve(true)
+		end)
+		expect(PromiseTestUtils.awaitSettled(promise)).toEqual(true)
+	end)
+
+	it("returns false when the promise never settles within the timeout", function()
+		expect(PromiseTestUtils.awaitSettled(Promise.new(), SHORT_TIMEOUT)).toEqual(false)
+	end)
+end)
+
+describe("PromiseTestUtils.awaitOutcome", function()
+	it("reports a resolved value", function()
+		local outcome, value = PromiseTestUtils.awaitOutcome(Promise.resolved(42))
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual(42)
+	end)
+
+	it("reports a rejection error", function()
+		local outcome, err = PromiseTestUtils.awaitOutcome(Promise.rejected("boom"))
+		expect(outcome).toEqual("rejected")
+		expect(err).toEqual("boom")
+	end)
+
+	it("reports pending when the promise never settles within the timeout", function()
+		local outcome = PromiseTestUtils.awaitOutcome(Promise.new(), SHORT_TIMEOUT)
+		expect(outcome).toEqual("pending")
+	end)
+end)
+
+describe("PromiseTestUtils.awaitValue", function()
+	it("returns true once the predicate becomes true", function()
+		local flag = { value = false }
+		task.defer(function()
+			flag.value = true
+		end)
+		expect(PromiseTestUtils.awaitValue(function()
+			return flag.value
+		end)).toEqual(true)
+	end)
+
+	it("returns false when the predicate never becomes true within the timeout", function()
+		expect(PromiseTestUtils.awaitValue(function()
+			return false
+		end, SHORT_TIMEOUT)).toEqual(false)
+	end)
+end)

package/src/Shared/PromiseUtils.lua

@@ -12,9 +12,11 @@ local Signal = require("Signal")
 local PromiseUtils = {}
 
 --[=[
-	Returns the value of the first promise resolved
-	@param promises { Promise<T> }
-	@return Promise<T> -- Promise that resolves with first result
+	Settles with the first of the given promises to settle, resolving if it resolved or rejecting if
+	it rejected. Also available as [PromiseUtils.race].
+
+	@param promises { Promise<T...> }
+	@return Promise<T...> -- Promise that settles with the first result
 ]=]
 function PromiseUtils.any<T...>(promises: { Promise.Promise<T...> }): Promise.Promise<T...>
 	local returnPromise = Promise.new()
@@ -34,6 +36,17 @@ function PromiseUtils.any<T...>(promises: { Promise.Promise<T...> }): Promise.Pr
 	return returnPromise
 end
 
+--[=[
+	Alias for [PromiseUtils.any]. Settles with the first of the given promises to settle, resolving
+	if it resolved or rejecting if it rejected.
+
+	@function race
+	@within PromiseUtils
+	@param promises { Promise<T...> }
+	@return Promise<T...>
+]=]
+PromiseUtils.race = PromiseUtils.any
+
 --[=[
 	Returns a promise that will resolve after the set amount of seconds
 

package/src/jest.config.lua

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

package/test/default.project.json

@@ -0,0 +1,25 @@
+{
+  "name": "PromiseTest",
+  "globIgnorePaths": [
+    "**/.package-lock.json",
+    "**/.pnpm",
+    "**/.pnpm-workspace-state-v1.json",
+    "**/.modules.yaml",
+    "**/.ignored",
+    "**/.ignored_*"
+  ],
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "$properties": {
+        "LoadStringEnabled": true
+      },
+      "promise": {
+        "$path": ".."
+      },
+      "Script": {
+        "$path": "scripts/Server"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,14 @@
+--!nonstrict
+--[[
+	@class ServerMain
+]]
+
+local ServerScriptService = game:GetService("ServerScriptService")
+
+local root = ServerScriptService.promise
+local loader = root:FindFirstChild("LoaderUtils", true).Parent
+local require = require(loader).bootstrapGame(root)
+
+local NevermoreTestRunnerUtils = require("NevermoreTestRunnerUtils")
+
+NevermoreTestRunnerUtils.runTestsIfNeededAsync(root)