@quenty/promise 3.2.1-canary.8533eea.0 → 3.3.1

package/CHANGELOG.md

@@ -3,12 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [3.2.1-canary.8533eea.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/promise@3.2.0...@quenty/promise@3.2.1-canary.8533eea.0) (2021-12-18)
+## [3.3.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/promise@3.3.0...@quenty/promise@3.3.1) (2021-12-30)
+
+**Note:** Version bump only for package @quenty/promise
+
+
+
+
+
+# [3.3.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/promise@3.2.0...@quenty/promise@3.3.0) (2021-12-18)
 
 
 ### Bug Fixes
 
-* Use Promies.spawn() since task.spawn() is probably cheaper now ([96d0732](https://github.com/Quenty/NevermoreEngine/commit/96d0732df7b89f6e98c89d03810a87a41a17277b))
+* Use Promies.spawn() since task.spawn() is probably cheaper now ([6a069c2](https://github.com/Quenty/NevermoreEngine/commit/6a069c2a1c99ca34f53af747a969d5f5c4044e84))
 
 
 

package/README.md

@@ -1,10 +1,10 @@
 ## Promise
 <div align="center">
-  <a href="http://quenty.github.io/api/">
-    <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
+  <a href="http://quenty.github.io/NevermoreEngine/">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/docs.yml/badge.svg" alt="Documentation status" />
   </a>
   <a href="https://discord.gg/mhtGUS8">
-    <img src="https://img.shields.io/badge/discord-nevermore-blue.svg" alt="Discord" />
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
   </a>
   <a href="https://github.com/Quenty/NevermoreEngine/actions">
     <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />
@@ -12,6 +12,8 @@
 </div>
 Promises, but without error handling as this screws with stack traces, using Roblox signals
 
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/Promise">View docs →</a></div>
+
 ## Installation
 ```
 npm install @quenty/promise --save

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/promise",
-  "version": "3.2.1-canary.8533eea.0",
+  "version": "3.3.1",
   "description": "Promise implementation for Roblox",
   "keywords": [
     "Roblox",
@@ -25,12 +25,12 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/deferred": "2.0.1",
-    "@quenty/loader": "3.1.1",
-    "@quenty/maid": "2.0.1"
+    "@quenty/deferred": "^2.0.2",
+    "@quenty/loader": "^3.1.2",
+    "@quenty/maid": "^2.0.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8533eeade3bf6835c0295785c1c326b9abee3222"
+  "gitHead": "d146c77d0a8e452824de0ab0b4b03ba0370bcc1b"
 }

package/src/Shared/Promise.lua

@@ -1,12 +1,12 @@
---- Promises, but without error handling as this screws with stack traces, using Roblox signals
--- @classmod Promise
--- See: https://promisesaplus.com/
+--[=[
+	Promises, but without error handling as this screws with stack traces, using Roblox signals
 
-local RunService = game:GetService("RunService")
+	See: https://promisesaplus.com/
 
-local function isPromise(value)
-	return type(value) == "table" and value.ClassName == "Promise"
-end
+	@class Promise
+]=]
+
+local RunService = game:GetService("RunService")
 
 -- Turns out debug.traceback() is slow
 local ENABLE_TRACEBACK = false
@@ -17,13 +17,27 @@ local Promise = {}
 Promise.ClassName = "Promise"
 Promise.__index = Promise
 
---- Determines whether a value is a promise or not
--- @function isPromise
-Promise.isPromise = isPromise
+--[=[
+	Determines whether a value is a promise or not.
+
+	@param value any
+	@return boolean
+]=]
+function Promise.isPromise(value)
+	return type(value) == "table" and value.ClassName == "Promise"
+end
 
---- Construct a new promise
--- @constructor Promise.new()
--- @treturn Promise
+--[=[
+	Constructs a new promise.
+
+	::warning
+	Do not yield within this func callback, as it will yield on the
+	main thread. This is a performance optimization.
+	::
+
+	@param func (resolve: (...) -> (), reject: (...) -> ()) -> ()?
+	@return Promise<T>
+]=]
 function Promise.new(func)
 	local self = setmetatable({
 		_pendingExecuteList = {};
@@ -38,7 +52,12 @@ function Promise.new(func)
 	return self
 end
 
---- Initializes a new promise with the given function in a deferred wrapper
+--[=[
+	Initializes a new promise with the given function in a deferred wrapper.
+
+	@param func (resolve: (...) -> (), reject: (...) -> ()) -> ()?
+	@return Promise<T>
+]=]
 function Promise.spawn(func)
 	local self = Promise.new()
 
@@ -47,6 +66,12 @@ function Promise.spawn(func)
 	return self
 end
 
+--[=[
+	Initializes a new promise with the given function in a deferred wrapper.
+
+	@param func (resolve: (...) -> (), reject: (...) -> ()) -> ()?
+	@return Promise<T>
+]=]
 function Promise.defer(func)
 	local self = Promise.new()
 
@@ -56,12 +81,18 @@ function Promise.defer(func)
 	return self
 end
 
+--[=[
+	Returns a resolved promise with the following values
+
+	@param ... Values to resolve to
+	@return Promise<T>
+]=]
 function Promise.resolved(...)
 	local n = select("#", ...)
 	if n == 0 then
 		-- Reuse promise here to save on calls to Promise.resolved()
 		return _emptyFulfilledPromise
-	elseif n == 1 and isPromise(...) then
+	elseif n == 1 and Promise.isPromise(...) then
 		local promise = (...)
 
 		-- Resolving to promise that is already resolved. Just return the promise!
@@ -75,6 +106,12 @@ function Promise.resolved(...)
 	return promise
 end
 
+--[=[
+	Returns a rejected promise with the following values
+
+	@param ... Values to reject to
+	@return Promise<T>
+]=]
 function Promise.rejected(...)
 	local n = select("#", ...)
 	if n == 0 then
@@ -87,21 +124,40 @@ function Promise.rejected(...)
 	return promise
 end
 
---- Returns whether or not the promise is pending
--- @treturn bool True if pending, false otherwise
+--[=[
+	Returns whether or not the promise is pending
+
+	@return bool -- True if pending, false otherwise
+]=]
 function Promise:IsPending()
 	return self._pendingExecuteList ~= nil
 end
 
+--[=[
+	Returns whether or not the promise is fulfilled
+
+	@return bool -- True if fulfilled
+]=]
 function Promise:IsFulfilled()
 	return self._fulfilled ~= nil
 end
 
+--[=[
+	Returns whether or not the promise is rejected
+
+	@return bool -- True if rejected
+]=]
 function Promise:IsRejected()
 	return self._rejected ~= nil
 end
 
---- Yield until the promise is complete
+--[=[
+	Yields until the promise is complete, and errors if an error
+	exists, otherwise returns the fulfilled results.
+
+	@yields
+	@return T
+]=]
 function Promise:Wait()
 	if self._fulfilled then
 		return unpack(self._fulfilled, 1, self._valuesLength)
@@ -127,6 +183,14 @@ function Promise:Wait()
 	end
 end
 
+
+--[=[
+	Yields until the promise is complete, then returns a boolean indicating
+	the result, followed by the values from the promise.
+
+	@yields
+	@return boolean, T
+]=]
 function Promise:Yield()
 	if self._fulfilled then
 		return true, unpack(self._fulfilled, 1, self._valuesLength)
@@ -153,9 +217,11 @@ function Promise:Yield()
 end
 
 
---- Promise resolution procedure
--- Resolves a promise
--- @return self
+--[=[
+	Promise resolution procedure, resolves the given values
+
+	@param ... T
+]=]
 function Promise:Resolve(...)
 	if not self._pendingExecuteList then
 		return
@@ -166,7 +232,7 @@ function Promise:Resolve(...)
 		self:_fulfill({}, 0)
 	elseif self == (...) then
 		self:Reject("TypeError: Resolved to self")
-	elseif isPromise(...) then
+	elseif Promise.isPromise(...) then
 		if len > 1 then
 			local message = ("When resolving a promise, extra arguments are discarded! See:\n\n%s")
 				:format(self._source)
@@ -213,9 +279,12 @@ function Promise:Resolve(...)
 	end
 end
 
---- Fulfills the promise with the value
--- @param ... Params to _fulfill with
--- @return self
+--[=[
+	Fulfills the promise with the value
+	@param values { T } -- Params to fulfil with
+	@param valuesLength number
+	@private
+]=]
 function Promise:_fulfill(values, valuesLength)
 	if not self._pendingExecuteList then
 		return
@@ -231,9 +300,10 @@ function Promise:_fulfill(values, valuesLength)
 	end
 end
 
---- Rejects the promise with the value given
--- @param ... Params to reject with
--- @return self
+--[=[
+	Rejects the promise with the values given
+	@param ... T -- Params to reject with
+]=]
 function Promise:Reject(...)
 	self:_reject({...}, select("#", ...))
 end
@@ -272,18 +342,26 @@ function Promise:_reject(values, valuesLength)
 	end
 end
 
---- Handlers if/when promise is fulfilled/rejected. It takes up to two arguments, callback functions
--- for the success and failure cases of the Promise. May return the same promise if certain behavior
--- is met.
--- NOTE: We do not comply with 2.2.4 (onFulfilled or onRejected must not be called until the execution context stack
--- contains only platform code). This means promises may stack overflow, however, it also makes promises a lot cheaper
--- @tparam[opt=nil] function onFulfilled Called if/when fulfilled with parameters
-	-- If/when promise is fulfilled, all respective onFulfilled callbacks must execute in the order of their
-	-- originating calls to then.
--- @tparam[opt=nil] function onRejected Called if/when rejected with parameters
-	-- If/when promise is rejected, all respective onRejected callbacks must execute in the order of their
-	-- originating calls to then.
--- @treturn Promise
+--[=[
+	Handlers if/when promise is fulfilled/rejected. It takes up to two arguments, callback functions
+	for the success and failure cases of the Promise. May return the same promise if certain behavior
+	is met.
+
+	:::info
+	We do not comply with 2.2.4 (onFulfilled or onRejected must not be called until the execution context stack
+	contains only platform code). This means promises may stack overflow, however, it also makes promises a lot cheaper
+	:::
+
+	If/when promise is rejected, all respective onRejected callbacks must execute in the order of their
+	originating calls to then.
+
+	If/when promise is fulfilled, all respective onFulfilled callbacks must execute in the order of their
+	originating calls to then.
+
+	@param onFulfilled function -- Called if/when fulfilled with parameters
+	@param onRejected function -- Called if/when rejected with parameters
+	@return Promise<T>
+]=]
 function Promise:Then(onFulfilled, onRejected)
 	if type(onRejected) == "function" then
 		self._unconsumedException = false
@@ -298,9 +376,16 @@ function Promise:Then(onFulfilled, onRejected)
 	end
 end
 
--- Like then, but the value passed down the chain is the resolved value of the promise, not
--- the value returned from onFulfilled or onRejected
--- Will still yield for the result if a promise is returned, but will discard the result.
+--[=[
+	Like then, but the value passed down the chain is the resolved value of the promise, not
+	the value returned from onFulfilled or onRejected
+
+	Will still yield for the result if a promise is returned, but will discard the result.
+
+	@param onFulfilled function
+	@param onRejected function
+	@return Promise<T> -- Returns self
+]=]
 function Promise:Tap(onFulfilled, onRejected)
 	-- Run immediately like then, but we return something safer!
 	local result = self:Then(onFulfilled, onRejected)
@@ -327,23 +412,36 @@ function Promise:Tap(onFulfilled, onRejected)
 	end
 end
 
+--[=[
+	Executes upon pending stop
+
+	@param func function
+	@return Promise<T>
+]=]
 function Promise:Finally(func)
 	return self:Then(func, func)
 end
 
---- Catch errors from the promise
--- @treturn Promise
+--[=[
+	Catch errors from the promise
+
+	@param onRejected function
+	@return Promise<T>
+]=]
 function Promise:Catch(onRejected)
 	return self:Then(nil, onRejected)
 end
 
---- Rejects the current promise.
--- Utility left for Maid task
--- @treturn nil
+--[=[
+	Rejects the current promise. Utility left for Maid task
+]=]
 function Promise:Destroy()
 	self:_reject({}, 0)
 end
 
+--[=[
+	Returns the results from the promise
+]=]
 function Promise:GetResults()
 	if self._rejected then
 		return false, unpack(self._rejected, 1, self._valuesLength)
@@ -375,7 +473,7 @@ function Promise:_executeThen(onFulfilled, onRejected, promise2)
 				local results = table.pack(onFulfilled(unpack(self._fulfilled, 1, self._valuesLength)))
 				if results.n == 0 then
 					return _emptyFulfilledPromise
-				elseif results.n == 1 and isPromise(results[1]) then
+				elseif results.n == 1 and Promise.isPromise(results[1]) then
 					return results[1]
 				else
 					local promise = Promise.new()
@@ -406,7 +504,7 @@ function Promise:_executeThen(onFulfilled, onRejected, promise2)
 				local results = table.pack(onRejected(unpack(self._rejected, 1, self._valuesLength)))
 				if results.n == 0 then
 					return _emptyFulfilledPromise
-				elseif results.n == 1 and isPromise(results[1]) then
+				elseif results.n == 1 and Promise.isPromise(results[1]) then
 					return results[1]
 				else
 					local promise = Promise.new()

package/src/Shared/PromiseUtils.lua

@@ -1,5 +1,7 @@
---- Utility methods for promise
--- @module PromiseUtils
+--[=[
+	Utility methods for promise
+	@class PromiseUtils
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -7,10 +9,11 @@ local Promise = require("Promise")
 
 local PromiseUtils = {}
 
---- Returns the value of the first promise resolved
--- @constructor First
--- @tparam Array(Promise) promises
--- @treturn Promise Promise that resolves with first result
+--[=[
+	Returns the value of the first promise resolved
+	@param promises { Promise<T> }
+	@return Promise<T> -- Promise that resolves with first result
+]=]
 function PromiseUtils.any(promises)
 	local returnPromise = Promise.new()
 
@@ -29,10 +32,13 @@ function PromiseUtils.any(promises)
 	return returnPromise
 end
 
---- Executes all promises. If any fails, the result will be rejected. However, it yields until
---  every promise is complete
--- @constructor First
--- @treturn Promise
+--[=[
+	Executes all promises. If any fails, the result will be rejected. However, it yields until
+	every promise is complete.
+
+	@param promises { Promise<T> }
+	@return Promise<T>
+]=]
 function PromiseUtils.all(promises)
 	if #promises == 0 then
 		return Promise.resolved()
@@ -62,6 +68,13 @@ function PromiseUtils.all(promises)
 	return returnPromise
 end
 
+--[=[
+	Inverts the result of a promise, turning a resolved promise
+	into a rejected one, and a rejected one into a resolved one.
+
+	@param promise Promise<T>
+	@return Promise<T>
+]=]
 function PromiseUtils.invert(promise)
 	if promise:IsPending() then
 		return promise:Then(function(...)
@@ -79,6 +92,12 @@ function PromiseUtils.invert(promise)
 	end
 end
 
+--[=[
+	Creates a promise from a signal
+
+	@param signal Signal<T>
+	@return Promise<T>
+]=]
 function PromiseUtils.fromSignal(signal)
 	local promise = Promise.new()
 	local conn
@@ -95,6 +114,14 @@ function PromiseUtils.fromSignal(signal)
 	return promise
 end
 
+--[=[
+	Creates a new promise from the given promise that will
+	reject after the given `timeoutTime`
+
+	@param timeoutTime number
+	@param fromPromise Promise<T>
+	@return Promise<T>
+]=]
 function PromiseUtils.timeout(timeoutTime, fromPromise)
 	assert(type(timeoutTime) == "number", "Bad timeoutTime")
 	assert(fromPromise, "Bad fromPromise")
@@ -107,12 +134,11 @@ function PromiseUtils.timeout(timeoutTime, fromPromise)
 
 	promise:Resolve(fromPromise)
 
-	delay(timeoutTime, function()
+	task.delay(timeoutTime, function()
 		promise:Reject()
 	end)
 
 	return promise
-
 end
 
 return PromiseUtils

package/src/Shared/Utility/PendingPromiseTracker.lua

@@ -1,5 +1,7 @@
---- Tracks pending promises
--- @classmod PendingPromiseTracker
+--[=[
+	Tracks pending promises
+	@class PendingPromiseTracker
+]=]
 
 local PendingPromiseTracker = {}
 PendingPromiseTracker.ClassName = "PendingPromiseTracker"

package/src/Shared/Utility/PromiseInstanceUtils.lua

@@ -1,6 +1,6 @@
----
--- @module PromiseInstanceUtils
--- @author Quenty
+--[=[
+	@class PromiseInstanceUtils
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -9,6 +9,10 @@ local Maid = require("Maid")
 
 local PromiseInstanceUtils = {}
 
+--[=[
+	@param instance Instance
+	@return Promise
+]=]
 function PromiseInstanceUtils.promiseRemoved(instance)
 	assert(instance:IsDescendantOf(game))
 

package/src/Shared/Utility/promiseChild.lua

@@ -1,11 +1,22 @@
---- Warps the WaitForChild API with a promise
--- @module promiseChild
+--[=[
+	Warps the WaitForChild API with a promise
+	@class promiseChild
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
 local Promise = require("Promise")
 
---- Wraps the :WaitForChild API with a promise
+--[=[
+	Wraps the :WaitForChild API with a promise
+
+	@function promiseChild
+	@param parent Instance
+	@param name string
+	@param timeOut number?
+	@return Promise<Instance>
+	@within promiseChild
+]=]
 return function(parent, name, timeOut)
 	local result = parent:FindFirstChild(name)
 	if result then

package/src/Shared/Utility/promisePropertyValue.lua

@@ -1,5 +1,7 @@
---- Promises a property value
--- @module promisePropertyValue
+--[=[
+	Promises a property value
+	@class promisePropertyValue
+]=]
 
 local require = require(script.Parent.loader).load(script)
 

package/src/Shared/Utility/promiseWait.lua

@@ -1,5 +1,8 @@
---- Wraps the wait()/delay() API in a promise
--- @module promiseWait
+--[=[
+	Wraps the wait()/delay() API in a promise
+
+	@class promiseWait
+]=]
 
 local require = require(script.Parent.loader).load(script)