Async.Promise library

The Async.Promise library provides functions for handling asynchronous operations, such as loading a remote node database. All of these functions are contained in the “Async.Promise” and/or “Promise” Lua tables found in the “async.lua” unit.

Usage example:

-- First, you need to require the “async.lua” unit
require("async.lua");

-- Now you can access the functions of the library.
Async.Promise.LIBRARY_FUNCTION(Argument1, Argument2, ...);
or
Promise.LIBRARY_FUNCTION(Argument1, Argument2, ...);

Async.Promise library functions

function Async.Promise.all(promise1[, promise2[, promise3[, ... promiseN]]])
function Async.Promise.all(promisesArray)
function Promise.all(promise1[, promise2[, promise3[, ...promiseN]]])
function Promise.all(promisesArray)

This function takes a set of Promise objects and creates a single Promise object that will be resolved when all provided promises are resolved. The set of Promise objects can be passed to this function using one of the following styles:

Arguments (variable number of arguments style):

Each argument identifies a single Promise object in the set. Examples of valid usages:

Promise.all(promise)
Promise.all(promise, promise2)
Promise.all(promise, promise2, promise3)
Promise.all(promise, promise2, promise3, promise4)

Arguments (array style):

promisesArray - A single array containing all Promise objects of the set.

Return:

A newly created Promise object that monitors all informed Promise objects.

Remarks:

The returned Promise will be successfully resolved when all informed promises are successfully resolved. The success data of the returned Promise will be an array containing the set success data, in the order of the promises passed, regardless of completion order.
If any of the given Promises is resolved to failure, the promise returned by this function will also be resolved to failure, and its associated failure reason will be the same as the first promise that was resolved to failure.
If the given set of Promises is empty, the function will return an already resolved Promise object.

function Async.Promise.isPromise(value)
function Promise.isPromise(value)

Check is the provided value is a Promise object

Arguments:

value - the value that will be verified.

Return:

A boolean; true means the provided value is a promise object, false otherwise.

function Async.Promise.resolved(data)
function Async.Promise.resolve(data)
function Async.Promise.succeeded(data)
function Promise.resolved(data)
function Promise.resolve(data)
function Promise.succeeded(data)

Creates and returns a Promise object that has already been successfully resolved with the provided “data” argument

Arguments:

data - the value that was successfully resolved. This can be any information you want to pass as a successful return value

Return:

The new Promise object

function Async.Promise.toHandle(promise, successCallback,[, failureCallback])
function Promise.toHandle(promise, successCallback[, failureCallback])

Creates a Promise object that receives the outcome of another existing Promise object and potentially returns converted data.

Arguments:

promise - An existing Promise object that will be monitored
successCallback - A function called when the monitored Promise object resolves to success. The first argument received by this function is the outcome data of the monitored promise. Whatever this function returns will be the success data of the new promise.
(Optional) failureCallback - A function called when the monitored Promise object resolves to failure. The first argument received by this function is the error message of the monitored promise. Whatever this function returns will be the success data of the new promise.

Return:

A new Promise object

Remarks

This type of promise is typically used to convert data from an asynchronous operation and/or to provide an alternate outcome if the monitored asynchronous operation fails.
If the execution of `successCallback` raises an error or exception, the new promise will resolve to failure even if the monitored promise resolved to success.
If the execution of `successCallback` returns a third promise object, the outcome of the promise created by this function will be delegated to this third promise.
If the execution of `failureCallback` does not raise an error or exception, the new promise will resolve to success even if the monitored promise resolved to failure.
If the execution of `failureCallback` returns a third promise object, the outcome of the promise created by this function will be delegated to this third promise.

function Async.Promise.toResolve()
function Async.Promise.pending()
function Promise.toResolve()
function Promise.pending()

Creates a Promise object that is in a pending state and its associated Promise Resolution object.

This function returns 2 values:

The first return is a new Promise object
The second return is the PromiseResolution object that is used to resolve the created Promise.

Remarks

While the Promise object represents an asynchronous process that other pieces of code can track, the PromiseResolution object is used to resolve the promise either to success or failure. Typically, you return or pass along the Promise object as a mechanism to monitor the asynchronous operation while keeping and using the PromiseResolution privately.

function Async.Promise.withError(errorMsg)
function Async.Promise.withException(errorMsg)
function Async.Promise.failed(errorMsg)function Async.Promise.reject(errorMsg)
function Promise.withError(errorMsg)
function Promise.withException(errorMsg)
function Promise.failed(errorMsg)
function Promise.reject(errorMsg)

Creates and returns a Promise object that has already been resolved with a failure state and with the provided error message

Arguments:

errorMsg - The error message that describes why the Promise resolved to a failed state.

Return:

The new Promise object

Created with the Personal Edition of HelpNDoc: Eliminate the Struggles of Documentation with a Help Authoring Tool