dojo/promise/first¶
| authors: | Mark Wubben |
|---|---|
| since: | V1.8 |
Contents
dojo/promise/first is a function that takes multiple promises and returns a new promise that is fulfilled when the first of those promises is fulfilled.
Introduction¶
dojo/promise/first is useful when managing multiple promises that may resolve at different times. This could be
useful in a situation where you are going against responses against several services but only really care about
whichever one is the fastest to return.
Note Cancelling the returned promise from dojo/promise/first will not cancel any of the passed promises.
Usage¶
Usage is straight forward, in that dojo/promise/first is a single argument that is either an Object or an Array. The
returned promise is fulfilled with the results from the first promise that is fulfilled:
require(["dojo/promise/first"], function(first){
first([promise1, promise2]).then(function(result){
// result will be either promise1 or promise2 results, whichever is fulfilled first
});
// -- or --
first({
promise1: promise1,
promise2: promise2
}).then(function(result){
// result will be either promise1 or promise2 results, whichever is fulfilled first
});
});
As mentioned above, dojo/promise/first takes a single argument:
| Argument | Type | Description |
|---|---|---|
| objectOrArray | Object/Array? | The object or array of promises to use |
Examples¶
This example demonstrates simulating 3 service requests and then acting on the first one to return.
require(["dojo/promise/first", "dojo/Deferred", "dojo/dom", "dojo/on", "dojo/json", "dojo/domReady!"],
function(first, Deferred, dom, on, JSON){
function googleRequest(){
var deferred = new Deferred();
setTimeout(function(){
deferred.resolve("foo");
}, 500);
return deferred.promise;
}
function bingRequest(){
var deferred = new Deferred();
setTimeout(function(){
deferred.resolve("bar");
}, 750);
return deferred.promise;
}
function baiduRequest(){
var deferred = new Deferred();
setTimeout(function(){
deferred.resolve("baz");
}, 1000);
return deferred.promise;
}
on(dom.byId("startButton"), "click", function(){
dom.byId("output").innerHTML = "Running...";
first([googleRequest(), bingRequest(), baiduRequest()]).then(function(result){
dom.byId("output").innerHTML = JSON.stringify(result);
});
});
});
<h1>Output:</h1>
<pre id="output"></pre>
<button type="button" id="startButton">Start</button>
This example is essentially the same as above, but passes an Object as a parameter to dojo/promise/first.
require(["dojo/promise/first", "dojo/Deferred", "dojo/dom", "dojo/on", "dojo/json", "dojo/domReady!"],
function(first, Deferred, dom, on, JSON){
function googleRequest(){
var deferred = new Deferred();
setTimeout(function(){
deferred.resolve("foo");
}, 500);
return deferred.promise;
}
function bingRequest(){
var deferred = new Deferred();
setTimeout(function(){
deferred.resolve("bar");
}, 750);
return deferred.promise;
}
function baiduRequest(){
var deferred = new Deferred();
setTimeout(function(){
deferred.resolve("baz");
}, 1000);
return deferred.promise;
}
on(dom.byId("startButton"), "click", function(){
dom.byId("output").innerHTML = "Running...";
first({
google: googleRequest(),
bing: bingRequest(),
baidu: baiduRequest()
}).then(function(results){
dom.byId("output").innerHTML = JSON.stringify(results);
});
});
});
<h1>Output:</h1>
<pre id="output"></pre>
<button type="button" id="startButton">Start</button>
See also¶
- dojo/promise - The rest of the Dojo Promise API
- dojo/promise/all - Like
dojo/promise/firstexcept gets fulfilled when all the promises get fulfilled. - dojo/Deferred - The base class for managing asynchronous thread communication in Dojo.