com.englishtown.promises.When Maven / Gradle / Ivy
package com.englishtown.promises;
import java.util.List;
import java.util.function.BiFunction;
import java.util.function.Function;
/**
* Promises/A+ and when implementation
*
* This is a port of the when.js version 3.2.3 library written by Brian Cavalier and John Hann
* when is part of the cujoJS family of libraries (http://cujojs.com/)
*/
public interface When {
/**
* Get a trusted promise for x, or by transforming x with onFulfilled
*
* @param x value to be wrapped in a fulfilled trusted promise
* @param type of promise
* @return a new promise that will fulfill with the return
* value of callback or errback or the completion value of promiseOrValue if
* callback and/or errback is not supplied.
*/
Promise when(T x);
/**
* Get a trusted promise for x, or by transforming x with onFulfilled
*
* @param x thenable to be wrapped in a trusted promise
* @param type of promise
* @return a new promise that will fulfill with the return
* value of callback or errback or the completion value of promiseOrValue if
* callback and/or errback is not supplied.
*/
Promise when(Thenable x);
/**
* Get a trusted promise for x, or by transforming x with onFulfilled
*
* @param x value to be wrapped in a fulfilled trusted promise
* @param onFulfilled callback to be called when x is
* successfully fulfilled. If promiseOrValue is an immediate value, callback
* will be invoked immediately.
* @param type of resolved promise
* @param type of thenable returned by onFulfilled
* @return a new promise that will fulfill with the return
* value of callback or errback or the completion value of promiseOrValue if
* callback and/or errback is not supplied.
*/
Promise when(T x, Function> onFulfilled);
/**
* Get a trusted promise for x, or by transforming x with onFulfilled
*
* @param x thenable to be wrapped in a trusted promise
* @param onFulfilled callback to be called when x is
* successfully fulfilled. If promiseOrValue is an immediate value, callback
* will be invoked immediately.
* @param onRejected callback to be called when x is
* rejected.
* @param type of resolved promise
* @param type of thenable returned by onFulfilled or onRejected
* @return a new promise that will fulfill with the return
* value of callback or errback or the completion value of promiseOrValue if
* callback and/or errback is not supplied.
*/
Promise when(T x, Function> onFulfilled, Function> onRejected);
/**
* Get a trusted promise for x, or by transforming x with onFulfilled
*
* @param x value to be wrapped in a fulfilled trusted promise
* @param onFulfilled callback to be called when x is
* successfully fulfilled. If promiseOrValue is an immediate value, callback
* will be invoked immediately.
* @param type of thenable to wrap in a trusted promise
* @param type of thenable returned by onFulfilled
* @return a new promise that will fulfill with the return
* value of callback or errback or the completion value of promiseOrValue if
* callback and/or errback is not supplied.
*/
Promise when(Thenable x, Function> onFulfilled);
/**
* Get a trusted promise for x, or by transforming x with onFulfilled
*
* @param x thenable to be wrapped in a trusted promise
* @param onFulfilled callback to be called when x is
* successfully fulfilled. If promiseOrValue is an immediate value, callback
* will be invoked immediately.
* @param onRejected callback to be called when x is
* rejected.
* @param type of thenable to wrap in a trusted promise
* @param type of thenable returned by onFulfilled
* @return {Promise} a new promise that will fulfill with the return
* value of callback or errback or the completion value of promiseOrValue if
* callback and/or errback is not supplied.
*/
Promise when(Thenable x, Function> onFulfilled, Function> onRejected);
/**
* Create a resolved promise
*
* @param x value to be wrapped in a fulfilled trusted promise
* @param type of value and promise to be returned
* @return a trusted fulfilled promise
*/
Promise resolve(T x);
/**
* Create a resolved promise
*
* @param x thenable to be wrapped in a trusted promise
* @param type of thenable and promise to be returned
* @return a trusted promise
*/
Promise resolve(Thenable x);
/**
* Create a rejected promise
*
* @param x a throwable that is the cause of a rejected promise
* @param the type of rejected promise
* @return a rejected promise
*/
Promise reject(Throwable x);
/**
* Creates a new promise whose fate is determined by resolver.
*
* @param resolver function(resolve, reject, notify)
* @param type of resolver and returned promise
* @return promise whose fate is determine by resolver
*/
Promise promise(PromiseResolver resolver);
/**
* Creates a {promise, resolver} pair, either or both of which
* may be given out safely to consumers.
*
* @param type of deferred
* @return {{promise: Promise, resolve: function, reject: function, notify: function}}
*/
Deferred defer();
/**
* Return a promise that will resolve only once all the supplied arguments
* have resolved. The resolution value of the returned promise will be an array
* containing the resolution values of each of the arguments.
*
* @param promises array of promises to be joined
* @param type of promises
* @return {Promise}
*/
Promise> join(Promise... promises);
/**
* Return a promise that will fulfill once all input promises have
* fulfilled, or reject when any one input promise rejects.
*
* @param promises list of promises
* @param type of promises
* @return promise for list of results
*/
Promise> all(List> promises);
/**
* Return a promise that will always fulfill with an array containing
* the outcome states of all input promises. The returned promise
* will only reject if `promises` itself is a rejected promise.
*
* @param promises list of promises
* @param type of promises
* @return {Promise}
*/
Promise>> settle(List> promises);
/**
* One-winner race
*
* @param promises list of promises
* @param type of promises and returned promise
* @return a promise for the first winner
*/
Promise any(List> promises);
/**
* Multi-winner race
*
* @param promises list of promises
* @param n the number of promises to resolve
* @param type of promises
* @return a promise of a list of n resolved values
*/
Promise> some(List> promises, int n);
/**
* Promise-aware array map function, similar to `Array.prototype.map()`,
* but input array may contain promises or values.
*
* @param promises array of promises
* @param mapFunc map function which may return a promise or value
* @param type of promises
* @return {Promise} promise that will fulfill with an array of mapped values
* or reject if any input promise rejects.
*/
Promise> map(List> promises, Function> mapFunc);
/**
* Traditional reduce function, similar to `Array.prototype.reduce()`, but
* input may contain promises and/or values, and reduceFunc
* may return either a value or a promise, *and* initialValue may`
* be a promise for the starting value.
*
* @param promises array or promise for an array of anything,
* may contain a mix of promises and values.
* @param f reduce function reduce(currentValue, nextValue, index)
* @param type of promises
* @return {Promise} that will resolve to the final reduced value
*/
Promise reduce(List> promises, BiFunction> f);
/**
* Traditional reduce function, similar to `Array.prototype.reduce()`, but
* input may contain promises and/or values, and reduceFunc
* may return either a value or a promise, *and* initialValue may`
* be a promise for the starting value.
*
* @param promises array or promise for an array of anything,
* may contain a mix of promises and values.
* @param f reduce function reduce(currentValue, nextValue, index)
* @param initialValue promise for an initial value
* @param type of promises
* @param type of promise returned
* @return {Promise} that will resolve to the final reduced value
*/
Promise reduce(List> promises, BiFunction> f, Thenable initialValue);
/**
* Run array of tasks in sequence with no overlap
*
* @param tasks {Array|Promise} array or promiseForArray of task functions
* @param arg arguments to be passed to all tasks
* @param type of parameter passed to tasks
* @param type of promise list returned
* @return {Promise} promise for an array containing
* the result of each task in the array position corresponding
* to position of the task in the tasks array
*/
Promise> sequence(List>> tasks, Thenable arg);
/**
* Fulfill-reject competitive race. Return a promise that will settle
* to the same state as the earliest input promise to settle.
*
* @param promises promises to race
* @param type of promise
* @return winning promise
*/
Promise race(List> promises);
}