Roblox Lua Promise

A Promise is an abstraction over Lua coroutines that represents a value that will exist in the future. Instead of yielding the current thread (which can cause unintentional delays and race conditions), an asynchronous function returns a Promise object synchronously.

Key behaviors:

• Resolving: When the asynchronous operation succeeds, the Promise is 'resolved' with a value. You can attach a callback using .andThen() to handle this value.
• Rejecting: If the operation fails, the Promise is 'rejected' with an error. You can attach a callback using .catch() to handle the error.
• Non-blocking: Because the function returns the Promise object immediately, the calling thread does not stop execution while waiting for the background task to complete.

local function httpGet(url)
	return Promise.new(function(resolve, reject)
		local ok, result = pcall(HttpService.GetAsync, HttpService, url)

		if ok then
			resolve(result)
		else
			reject(result)
		end
	end)
end

-- Usage:
httpGet("https://google.com")
	:andThen(function(body)
		print("Success:", body)
	end)
	:catch(function(err)
		warn("Failed:", err)
	end)

Promises support cancellation. While cancelling a Promise prevents it from resolving or rejecting, it does not automatically stop the underlying code from running unless you implement a cancellation hook.

Implementing onCancel

To properly abort ongoing operations (like disconnecting events or stopping loops), use the third argument onCancel provided in the Promise.new executor.

Cancellation Behavior

• Immediate Cancellation: If you cancel a Promise immediately after creation, it will only prevent resolution if the executor yields. If the executor resolves without yielding, it is already settled and cannot be cancelled.
• Chained Cancellation: If a Promise is cancelled, any .andThen() or .catch() handlers attached to it will also be cancelled.
• Automatic Cancellation: Chaining can cause automatic cancellation if no consumers are left to care about the value.

local function myFunction()
	return Promise.new(function(resolve, reject, onCancel)
		local connection
		connection = someEvent:Connect(function(...)
			connection:Disconnect()
			resolve(...)
		end)

		-- This hook runs if the promise is cancelled
		onCancel(function()
			connection:Disconnect()
		end)
	end)
end

Promises are chainable. Calling .andThen(), .catch(), or .finally() returns a new Promise that resolves with the value returned from the handler.

• Value Transformation: Return a value from .andThen() to pass it to the next link in the chain.
• Promise Chaining: If you return a new Promise from a handler, the chain will wait for that Promise to settle before moving to the next step.
• Branching: You can call .andThen() multiple times on a single Promise to create multiple execution branches from one source.
• Resolving with a Promise: If you call resolve(anotherPromise), the chain will wait for anotherPromise to settle and resolve with its value.

-- Chaining values
somePromise:andThen(function(number)
  return number + 1
end):andThen(print)

-- Chaining another Promise
Promise.new(function(resolve)
	somethingThatYields()
	resolve(1)
end):andThen(function(x)
	return Promise.new(function(resolve)
		somethingThatYields()
		resolve(x + 1)
	end)
end):andThen(print) --> 2

When a value is no longer needed (e.g., a player closes a menu or an ability is interrupted), you can cancel a Promise. Cancelling a Promise prevents andThen and catch handlers from running.

To stop ongoing work (like a Tween or a network request) when a Promise is cancelled, use the third parameter of the Promise executor, onCancel. This allows you to register a callback that runs specifically when the Promise is cancelled.

If you do not register an onCancel callback, the Promise will stop its chain, but the underlying asynchronous task (like a Tween) will continue to run in the background.

local function tween(obj, tweenInfo, props)
	return Promise.new(function(resolve, reject, onCancel)
		local tween = TweenService:Create(obj, tweenInfo, props)
			
		-- Register a callback to be called if the Promise is cancelled.
		onCancel(function()
			tween:Cancel()
		end) 
		
		tween.Completed:Connect(resolve)
		tween:Play()
	end)
end

-- Usage
local promise = tween(workspace.Part, TweenInfo.new(2), { Transparency = 0.5 }):andThen(function()
	print("This is never printed.")
end):catch(function()
	print("This is never printed.")
end):finally(function()
	print("But this *is* printed!")
end)

wait(1)
promise:cancel() -- Cancel the Promise, which cancels the tween.