Class: Promise

api/models~ Promise

A promise is an object that represents a pending query that will be resolved at some point in the future. A query may either be done or it may fail. Depending on the outcome, the appropriate callbacks will be called. A number of promises may be joined using Promise#join to make it easy to run a function once several independent queries have all been resolved.

new Promise

Parameters:
Name Type Argument Description
opt_object Object <optional>
An object that will be passed to the always/ done/fail/each callbacks.
Properties:
Name Type Description
object * An object that will be passed to the callbacks when the promise resolves.
Since:
  • 1.0.0

Methods

<static> join

Joins several promises into a single promise that can be waited on. The done and fail callbacks will be called when all of the promises have resolved or any of the promises has failed respectively. The argument to the callback function is an array with the resolved object of all promises. In addition to these composite callbacks, the returned promise object has a method called each, which can be used to get a callback when each of the promises complete. The each callbacks will never be called again once the promise has resolved or failed.
Parameters:
Name Type Description
promises Array.<module:api/models~Promise> | ...module:api/models~Promise Either an array of promises to join or the promises as separate parameters.
Since:
  • 1.0.0
Returns:
A new Promise that will be done/fail when all of the joined promises are done/failed.
Type
module:api/models~Promise
Example
var p1 = album.load('name');
var p2 = track.load('name', 'duration');
var wait = models.Promise.join(p1, p2); // or join([p1, p2]);
wait.done(albumAndTrackDone).fail(eitherFailed).each(eitherDone);

always

When the promise is resolved (success or failure doesn't matter), callbacks registered by this method will be invoked. If the promise has already resolved, the callback function will be called immediately, without waiting for the next runloop iteration. The argument to the callback function is the object used to resolve the promise.
Parameters:
Name Type Argument Description
callbackOrThis Object | function(Object) If this argument is an object, it will be used as the "this" context object when calling the callback. If this argument is the callback function instead, the "this" context object will be the promise when the callback is called.
opt_callback function(Object) <optional>
The callback function to invoke, unless specified as the first argument.
Since:
  • 1.0.0
Returns:
Returns the same instance, so that the callback method calls can be easily called in sequence.
Type
module:api/models~Promise
Example
models.Artist.fromURI('spotify:artist:74terC9ol9zMo8rfzhSOiG').load('name')
    .done(function(artist) { console.log(artist.name); })
    .fail(function(artist, error) { console.log(error.message); })
    .always(function(artist, maybeError) { console.log('Done or failed.'); });

done

When the promise is resolved successfully, callbacks registered by this method will be invoked. If the promise has already resolved, the callback function will be called immediately, without waiting for the next runloop iteration. The argument to the callback function is the object used to resolve the promise.
Parameters:
Name Type Argument Description
callbackOrThis Object | function(Object) If this argument is an object, it will be used as the "this" context object when calling the callback. If this argument is the callback function instead, the "this" context object will be the promise when the callback is called.
opt_callback function(Object) <optional>
The callback function to invoke, unless specified as the first argument.
Since:
  • 1.0.0
Returns:
Returns the same instance, so that the callback method calls can be easily called in sequence.
Type
module:api/models~Promise
Example
models.Artist.fromURI('spotify:artist:74terC9ol9zMo8rfzhSOiG').load('name')
    .done(function(artist) { console.log(artist.name); })
    .fail(function(artist, error) { console.log(error.message); });

each

For joined promises, the callback given to this method will be called once for each of the promises in the join. Promises that fail will not invoke the callback. When adding this callback to the promise, all joined promises that already have completed will invoke the callback, in the order they resolved. The argument to the callback is the same argument as given to the individual promises.
Parameters:
Name Type Argument Description
callbackOrThis Object | function(Object) If this argument is an object, it will be used as the "this" context object when calling the callback. If this argument is the callback function instead, the "this" context object will be the promise when the callback is called.
opt_callback function(Object) <optional>
The callback function to invoke, unless specified as the first argument.
Since:
  • 1.0.0
Returns:
Returns the same instance, so that the callback method calls can be easily called in sequence.
Type
module:api/models~Promise
Example
var tracks = getSomeToplist();
var promises = [];
tracks.forEach(function(track) { promises.push(track.load('name')); });
models.Promise.join(promises)
    .each(function(track) { console.log('Loaded one track: ' + track.name); })
    .done(function(tracks) { console.log('Loaded all tracks.'); })
    .fail(function(tracks) { console.log('Failed to load at least one track.'); });

fail

When the promise fails, callbacks registered by this method will be invoked. If the promise has already failed, the callback function will be called immediately, without waiting for the next runloop iteration. The argument to the callback function is an error object describing the failure.
Parameters:
Name Type Argument Description
callbackOrThis Object | function(Object) If this argument is an object, it will be used as the "this" context object when calling the callback. If this argument is the callback function instead, the "this" context object will be the promise when the callback is called.
opt_callback function(Object) <optional>
The callback function to invoke, unless specified as the first argument.
Since:
  • 1.0.0
Returns:
Returns the same instance, so that the callback method calls can be easily called in sequence.
Type
module:api/models~Promise
Example
models.Track.fromURI('spotify:track:6a41rCqZhb2W6rpMolDR08').load('name')
    .done(function(track) { console.log(track.name); })
    .fail(function(track, error) { console.log(error.message); });

setDone

Resolves the promise, with the object that was specified when creating the instance, set manually afterwards or passed to this method. All callbacks for done will be called in the order they were registered.
Parameters:
Name Type Argument Description
opt_object * <optional>
An optional object that should be passed on to all done handlers.
Since:
  • 1.0.0

setFail

Fails the promise, with the given error reason. All callbacks for fail will be called in the order they were registered.
Parameters:
Name Type Description
error Object An error object describing what went wrong.
Since:
  • 1.0.0