@quenty/promise 10.21.0 → 10.23.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.
 
+# [10.23.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/promise@10.22.0...@quenty/promise@10.23.0) (2026-07-25)
+
+### Features
+
+- Promises don't reject on Promise.rejected(nil) ([be63400](https://github.com/Quenty/NevermoreEngine/commit/be63400f89c863624b75b1903f7e8357ddca7bf9))
+
+# [10.22.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/promise@10.21.0...@quenty/promise@10.22.0) (2026-07-23)
+
+### Features
+
+- Even more stuff ([fea7e95](https://github.com/Quenty/NevermoreEngine/commit/fea7e9587e7195bbfa7f4753c130a3d597f9a34b))
+
 # [10.21.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/promise@10.20.0...@quenty/promise@10.21.0) (2026-07-23)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/promise",
-  "version": "10.21.0",
+  "version": "10.23.0",
   "description": "Promise implementation for Roblox",
   "keywords": [
     "Roblox",
@@ -39,5 +39,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "1de37218a2bedb8e3f8614a2e09bba9eddc812da"
+  "gitHead": "8677b70e89a1ef1585f8492b0638ec4a29aba8a3"
 }

package/src/Shared/Promise.lua

@@ -363,11 +363,8 @@ function Promise._reject<T...>(self: Promise<T...>, values: { n: number, [number
 		self:_executeThen(unpack(data))
 	end
 
-	-- 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
+	-- Check for uncaught exceptions
+	if self._unconsumedException and self:_isReportableRejection(values) 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.
@@ -386,6 +383,23 @@ function Promise._reject<T...>(self: Promise<T...>, values: { n: number, [number
 	end
 end
 
+-- A rejection is only worth reporting if it carries information. Rejecting with no values at all
+-- (what Destroy() and cancellation produce), with values that are all nil, or with a single empty
+-- table (aggregators may reject with an empty results table) says nothing a warning could relay.
+function Promise._isReportableRejection<T...>(_self: Promise<T...>, values: { n: number, [number]: any }): boolean
+	if values.n == 1 and type(values[1]) == "table" and next(values[1]) == nil then
+		return false
+	end
+
+	for index = 1, values.n do
+		if values[index] ~= nil then
+			return true
+		end
+	end
+
+	return false
+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
@@ -433,15 +447,24 @@ function Promise.Then<T...>(
 	onFulfilled: ((T...) -> ...any)?,
 	onRejected: ((...any) -> ...any)?
 ): Promise<...any>
-	if type(onRejected) == "function" then
+	if self._pendingExecuteList then
+		-- Attaching any continuation delegates this promise's rejection to the returned
+		-- child promise, which becomes the new carrier of the unconsumed exception. So the
+		-- parent is consumed even without an onRejected here: a rejection flowing through a
+		-- handler-less Then is forwarded, not dropped, and the warning surfaces only at the
+		-- tail of the chain if nobody ever handles it.
 		self._unconsumedException = false
-	end
 
-	if self._pendingExecuteList then
 		local promise: Promise<T...> = Promise.new()
 		self._pendingExecuteList[#self._pendingExecuteList + 1] = { onFulfilled, onRejected, promise } :: { any }
 		return promise
 	else
+		-- Already settled: _executeThen returns self when there is no matching handler, so
+		-- self stays the carrier. Only an actual onRejected consumes the rejection here.
+		if type(onRejected) == "function" then
+			self._unconsumedException = false
+		end
+
 		return self:_executeThen(onFulfilled, onRejected, nil)
 	end
 end

package/src/Shared/Promise.spec.lua

@@ -133,6 +133,25 @@ describe("Promise.rejected", function()
 	it("reuses a single shared promise when rejecting with no values", function()
 		expect(Promise.rejected()).toBe(Promise.rejected())
 	end)
+
+	it("rejects with nil without reporting an uncaught exception", function()
+		local promise = Promise.rejected(nil)
+
+		expect(promise:IsRejected()).toEqual(true)
+		expect(promise:_isReportableRejection(promise._rejected)).toEqual(false)
+
+		local ok, err = promise:GetResults()
+		expect(ok).toEqual(false)
+		expect(err).toEqual(nil)
+	end)
+
+	it("rejects with several nils without reporting an uncaught exception", function()
+		local promise = Promise.rejected(nil, nil, nil)
+
+		expect(promise:IsRejected()).toEqual(true)
+		expect(promise._rejected.n).toEqual(3)
+		expect(promise:_isReportableRejection(promise._rejected)).toEqual(false)
+	end)
 end)
 
 describe("Promise:Resolve", function()
@@ -324,6 +343,123 @@ describe("Promise:Then", function()
 	end)
 end)
 
+describe("Promise:Then unconsumed-exception propagation", function()
+	it("consumes a pending promise once any continuation is attached", function()
+		local root = Promise.new()
+		expect((root :: any)._unconsumedException).toEqual(true)
+
+		root:Then(function() end)
+
+		expect((root :: any)._unconsumedException).toEqual(false)
+	end)
+
+	it("transfers the unconsumed exception to the returned child", function()
+		local root = Promise.new()
+		local child = root:Then(function() end)
+
+		expect((root :: any)._unconsumedException).toEqual(false)
+		expect((child :: any)._unconsumedException).toEqual(true)
+
+		root:Reject("boom")
+
+		-- Consume the child before the deferred uncaught-exception warning fires.
+		child:Catch(function() end)
+	end)
+
+	it("propagates a rejection through handler-less Thens to a downstream handler", function()
+		local root = Promise.new()
+		local tail = root:Then(function() end):Then(function() end):Then(nil, function(err)
+			return "recovered from " .. err
+		end)
+
+		root:Reject("boom")
+
+		local outcome, value = PromiseTestUtils.awaitOutcome(tail)
+		expect(outcome).toEqual("resolved")
+		expect(value).toEqual("recovered from boom")
+	end)
+
+	it("consumes every intermediate hop so none of them warn", function()
+		local root = Promise.new()
+		local hop1 = root:Then(function() end)
+		local hop2 = hop1:Then(function() end)
+		hop2:Then(nil, function(err)
+			return err
+		end)
+
+		root:Reject("boom")
+
+		expect((root :: any)._unconsumedException).toEqual(false)
+		expect((hop1 :: any)._unconsumedException).toEqual(false)
+		expect((hop2 :: any)._unconsumedException).toEqual(false)
+	end)
+
+	it("leaves an unhandled tail flagged so the error is not silently dropped", function()
+		local root = Promise.new()
+		local tail = root:Then(function() end):Then(function() end)
+
+		root:Reject("boom")
+
+		expect(tail:IsRejected()).toEqual(true)
+		expect((tail :: any)._unconsumedException).toEqual(true)
+
+		-- Consume it before the deferred uncaught-exception warning fires.
+		tail:Catch(function() end)
+		expect((tail :: any)._unconsumedException).toEqual(false)
+	end)
+
+	it("gives each fan-out branch its own unconsumed carrier", function()
+		local root = Promise.new()
+		local branchA = root:Then(function() end)
+		local branchB = root:Then(function() end)
+
+		root:Reject("boom")
+
+		expect((branchA :: any)._unconsumedException).toEqual(true)
+		expect((branchB :: any)._unconsumedException).toEqual(true)
+
+		branchA:Catch(function() end)
+		branchB:Catch(function() end)
+	end)
+
+	it("does not consume an already-rejected source when onRejected is omitted", function()
+		local source = Promise.rejected("nope")
+		-- Settled + no onRejected returns self, so self stays the carrier and must remain flagged.
+		local same = source:Then(function() end)
+
+		expect(same == source).toEqual(true)
+		expect((source :: any)._unconsumedException).toEqual(true)
+
+		source:Catch(function() end)
+		expect((source :: any)._unconsumedException).toEqual(false)
+	end)
+
+	it("runs the tail error handler for the datastore graceful-close shape", function()
+		local outer = Promise.new()
+		local root = Promise.new()
+
+		root:Then(function()
+			return "unused"
+		end)
+			:Then(function()
+				return "unused"
+			end)
+			:Then(function(value)
+				outer:Resolve(value)
+			end, function(err)
+				outer:Reject(string.format("locked: %s", err))
+			end)
+
+		root:Reject("still locked")
+
+		local outcome, err = PromiseTestUtils.awaitOutcome(outer)
+		expect(outcome).toEqual("rejected")
+		expect(err).toEqual("locked: still locked")
+
+		expect((root :: any)._unconsumedException).toEqual(false)
+	end)
+end)
+
 describe("Promise:Catch", function()
 	it("handles a rejection", function()
 		local outcome, value = PromiseTestUtils.awaitOutcome(Promise.rejected("caught"):Catch(function(err)
@@ -414,6 +550,34 @@ describe("Promise:GetResults", function()
 	end)
 end)
 
+describe("Promise._isReportableRejection", function()
+	local promise = Promise.new()
+
+	it("reports a rejection that carries a value", function()
+		expect(promise:_isReportableRejection(table.pack("boom"))).toEqual(true)
+		expect(promise:_isReportableRejection(table.pack(false))).toEqual(true)
+		expect(promise:_isReportableRejection(table.pack(0))).toEqual(true)
+		expect(promise:_isReportableRejection(table.pack({ code = 500 }))).toEqual(true)
+	end)
+
+	it("reports a rejection whose value is not the first one", function()
+		expect(promise:_isReportableRejection(table.pack(nil, "boom"))).toEqual(true)
+	end)
+
+	it("does not report a rejection with no values", function()
+		expect(promise:_isReportableRejection({ n = 0 })).toEqual(false)
+	end)
+
+	it("does not report a rejection whose values are all nil", function()
+		expect(promise:_isReportableRejection(table.pack(nil))).toEqual(false)
+		expect(promise:_isReportableRejection(table.pack(nil, nil, nil))).toEqual(false)
+	end)
+
+	it("does not report a rejection carrying a single empty table", function()
+		expect(promise:_isReportableRejection(table.pack({}))).toEqual(false)
+	end)
+end)
+
 describe("Promise._toHumanReadable", function()
 	local promise = Promise.new()