Module jls.lang.Promise

Represents the eventual result of an asynchronous operation.

Notes: * The then method is replaced by next, because then is a reserved word in Lua. * The promises are not guaranteed to be asynchronous.

see Promises/A+

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:finally (onFinally) Appends a handler callback to the promise for both fulfillment and rejection, and returns an equivalent of the original promise.
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.async (fn[, ...]) Calls the specified function as a coroutine.
Promise.isPromise (promise) Return true if the specified value is a promise.
Promise.withCallback () Returns a new promise and its associated callback.
Promise.withResolvers () Returns a new promise and two functions to resolve or reject it.
Promise.ensureCallback (callback) Returns the specified callback if any or a callback and its associated 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 function 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 function A Function called when the Promise is fulfilled. This function has one argument, the fulfillment value.
  • onRejected function A Function called when the Promise is rejected. This function has one argument, the rejection reason. (optional)

Returns:

    Promise 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 function A Function called when the Promise is rejected

Returns:

    Promise A new promise
promise:finally (onFinally)
Appends a handler callback to the promise for both fulfillment and rejection, and returns an equivalent of the original promise. In case of error or returning a rejected promise in the finally callback, the returned promise will be rejected.

Parameters:

  • onFinally function A Function called when the Promise is either fulfilled or rejected

Returns:

    Promise A new promise
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:

    Promise 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 table The promises list

Returns:

    Promise A promise
Promise.reject (reason)
Returns a Promise object that is rejected with the given reason.

Parameters:

  • reason The reason for the rejection

Returns:

    Promise 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:

    Promise A resolved promise
Promise.async (fn[, ...])
Calls the specified function as a coroutine. The async and await functions allows asynchronous/non-blocking functions to be written in a traditional synchronous/blocking style.

The function will be called with a corresponding await function as first argument.

The await function waits for the Promise on which its is called then returns its fulfillment value or raises an error with the rejection reason if the promise is rejected. You could use the traditional pcall to handle an eventual await error.

The await function can only be called on the async function body not in a callback.

Prior Lua 5.2 and LuaJIT you cannot yield when having a C function between yield and resume.

Parameters:

  • fn function The async function to call
  • ... The optional parameters to pass to the function after the await function (optional)

Returns:

    Promise A promise that resolves once the coroutine ends

Usage:

    local Promise = require('jls.lang.Promise')
local HttpClient = require('jls.net.http.HttpClient')

Promise.async(function(await)
  local client = HttpClient:new('http://www.lua.org')
  local response = await(client:fetch('/'))
  client:close()
  print(response:getStatusCode())
end)

require('jls.lang.event'):loop()
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
Promise.withCallback ()
Returns a new promise and its associated callback.

Returns:

  1. Promise A new promise
  2. function The associated callback

Usage:

    local promise, cb = Promise.withCallback()
Promise.withResolvers ()
Returns a new promise and two functions to resolve or reject it.

Returns:

  1. Promise A new promise
  2. function The function that resolves the promise
  3. function The function that rejects the promise

Usage:

    local promise, resolve, reject = Promise.withResolvers()
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:

  1. function The callback
  2. Promise 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
generated by LDoc 1.4.6