Module jls.lang.Promise
Represents the eventual result of an asynchronous operation.
see https://promisesaplus.com/
Class Promise
| Promise:new (executor) | Creates a promise. |
| promise:next (onFulfilled, onRejected) | Appends fulfillment and rejection handlers to the promise, and returns a new promise resolving to the return value of the called handler, or to its original settled value if the promise was not handled. |
| promise:catch (onRejected) | Appends a rejection handler callback to the promise, and returns a new promise resolving to the return value of the callback if it is called, or to its original fulfillment value if the promise is instead fulfilled. |
| Promise.createWithCallback () | Returns a new promise and its associated callback. |
| Promise.all (promises) | Returns a promise that either fulfills when all of the promises in the iterable argument have fulfilled or rejects as soon as one of the promises in the iterable argument rejects. |
| Promise.race (promises) | Returns a promise that fulfills or rejects as soon as one of the promises in the iterable fulfills or rejects, with the value or reason from that promise. |
| Promise.reject (reason) | Returns a Promise object that is rejected with the given reason. |
| Promise.resolve (value) | Returns a Promise object that is resolved with the given value. |
| Promise.ensureCallback (callback) | Returns the specified callback if any or a callback and its associated promise. |
| Promise.isPromise (promise) | Return true if the specified value is a promise. |
Class Promise
A promise represents the completion (or failure) of an asynchronous operation, and its resulting value (or error).
- Promise:new (executor)
-
Creates a promise.
Parameters:
- executor A function that is passed with the arguments resolve and reject.
Usage:
Promise:new(function(resolve, reject) -- call resolve(value) or reject(reason) end)
- promise:next (onFulfilled, onRejected)
-
Appends fulfillment and rejection handlers to the promise, and returns
a new promise resolving to the return value of the called handler,
or to its original settled value if the promise was not handled.
If onFulfilled or onRejected throws an error, or returns a Promise which rejects, then returns a rejected Promise. If onFulfilled or onRejected returns a Promise which resolves, or returns any other value, then returns a resolved Promise.
Parameters:
- onFulfilled A Function called when the Promise is fulfilled. This function has one argument, the fulfillment value.
- onRejected A Function called when the Promise is rejected. This function has one argument, the rejection reason.
Returns:
-
A new promise.
- promise:catch (onRejected)
-
Appends a rejection handler callback to the promise, and returns a new
promise resolving to the return value of the callback if it is called,
or to its original fulfillment value if the promise is instead fulfilled.
Parameters:
- onRejected A Function called when the Promise is rejected.
Returns:
-
A new promise.
- Promise.createWithCallback ()
-
Returns a new promise and its associated callback.
Usage:
local promise, cb = Promise.createWithCallback() - Promise.all (promises)
-
Returns a promise that either fulfills when all of the promises in the
iterable argument have fulfilled or rejects as soon as one of the
promises in the iterable argument rejects.
Parameters:
- promises table The promises list.
Returns:
-
A promise.
- Promise.race (promises)
-
Returns a promise that fulfills or rejects as soon as one of the
promises in the iterable fulfills or rejects, with the value or reason
from that promise.
Parameters:
- promises The promises.
Returns:
-
A promise.
- Promise.reject (reason)
-
Returns a Promise object that is rejected with the given reason.
Parameters:
- reason The reason for the rejection.
Returns:
-
A rejected promise.
- Promise.resolve (value)
-
Returns a Promise object that is resolved with the given value.
If the value is a thenable (i.e. has a next method), the returned
promise will "follow" that thenable, adopting its eventual state;
otherwise the returned promise will be fulfilled with the value.
Parameters:
- value The resolving value.
Returns:
-
A resolved promise.
- Promise.ensureCallback (callback)
-
Returns the specified callback if any or a callback and its associated promise.
This function helps to create asynchronous functions with an optional ending callback parameter.
Parameters:
- callback An optional existing callback or false to indicate that no promise is expected.
Returns:
-
a callback and an associated promise if necessary.
Usage:
function readAsync(callback) local cb, promise = Promise.ensureCallback(callback) -- call cb(nil, value) on success or cb(reason) on error return promise end
- Promise.isPromise (promise)
-
Return true if the specified value is a promise.
Parameters:
- promise The value to test.
Returns:
-
boolean
true if the specified value is a promise.