Promise

Parse. Promise

A Promise is returned by async methods as a hook to provide callbacks to be called when the async task is fulfilled.

Typical usage would be like:

   query.find().then(function(results) {
     results[0].set("foo", "bar");
     return results[0].saveAsync();
   }).then(function(result) {
     console.log("Updated " + result.id);
   });

Constructor

new Promise()

Methods

(static) _continueWhile(predicate, asyncFunction)

Runs the given asyncFunction repeatedly, as long as the predicate function returns a truthy value. Stops repeating if asyncFunction returns a rejected promise.

Parameters:
Name Type Description
predicate function

should return false when ready to stop.
asyncFunction function

should return a Promise.

(static) all(promises) → {Parse.Promise}

Returns a new promise that is fulfilled when all of the promises in the iterable argument are resolved. If any promise in the list fails, then the returned promise will be immediately rejected with the reason that single promise rejected. If they all succeed, then the returned promise will succeed, with the results being the results of all the input promises. If the iterable provided is empty, the returned promise will be immediately resolved.

For example: 

  var p1 = Parse.Promise.as(1);
  var p2 = Parse.Promise.as(2);
  var p3 = Parse.Promise.as(3);


  Parse.Promise.all([p1, p2, p3]).then(function([r1, r2, r3]) {
    console.log(r1);  // prints 1
    console.log(r2);  // prints 2
    console.log(r3);  // prints 3
  });

Parameters:
Name Type Description
promises Iterable

an iterable of promises to wait for.
Returns:
Type:
Parse.Promise

the new promise.

(static) as(value) → {Parse.Promise}

Returns a new promise that is resolved with a given value.

Parameters:
Name Type Description
value

The value to resolve the promise with
Returns:
Type:
Parse.Promise

the new promise.

(static) error(error) → {Parse.Promise}

Returns a new promise that is rejected with a given error.

Parameters:
Name Type Description
error

The error to reject the promise with
Returns:
Type:
Parse.Promise

the new promise.

(static) is(promise) → {Boolean}

Returns true iff the given object fulfils the Promise interface.

Parameters:
Name Type Description
promise Object

The object to test
Returns:
Type:
Boolean

(static) race(promises) → {Parse.Promise}

Returns a new promise that is immediately fulfilled when any of the promises in the iterable argument are resolved or rejected. If the first promise to complete is resolved, the returned promise will be resolved with the same value. Likewise, if the first promise to complete is rejected, the returned promise will be rejected with the same reason.

Parameters:
Name Type Description
promises Iterable

an iterable of promises to wait for.
Returns:
Type:
Parse.Promise

the new promise.

(static) reject(error) → {Parse.Promise}

Returns a new promise that is rejected with a given error. This is an alias for Parse.Promise.error, for compliance with the ES6 implementation.

Parameters:
Name Type Description
error

The error to reject the promise with
Returns:
Type:
Parse.Promise

the new promise.

(static) resolve(value) → {Parse.Promise}

Returns a new promise that is resolved with a given value. If that value is a thenable Promise (has a .then() prototype method), the new promise will be chained to the end of the value.

Parameters:
Name Type Description
value

The value to resolve the promise with
Returns:
Type:
Parse.Promise

the new promise.

(static) when(promises) → {Parse.Promise}

Returns a new promise that is fulfilled when all of the input promises are resolved. If any promise in the list fails, then the returned promise will be rejected with an array containing the error from each promise. If they all succeed, then the returned promise will succeed, with the results being the results of all the input promises. For example: 

  var p1 = Parse.Promise.as(1);
  var p2 = Parse.Promise.as(2);
  var p3 = Parse.Promise.as(3);


  Parse.Promise.when(p1, p2, p3).then(function(r1, r2, r3) {
    console.log(r1);  // prints 1
    console.log(r2);  // prints 2
    console.log(r3);  // prints 3
  });

The input promises can also be specified as an array: 

  var promises = [p1, p2, p3];
  Parse.Promise.when(promises).then(function(results) {
    console.log(results);  // prints [1,2,3]
  });

Parameters:
Name Type Description
promises Array

a list of promises to wait for.
Returns:
Type:
Parse.Promise

the new promise.

_continueWith(continuation)

Adds a callback function that should be called regardless of whether this promise failed or succeeded. The callback will be given either the array of results for its first argument, or the error as its second, depending on whether this Promise was rejected or resolved. Returns a new Promise, like "then" would.

Parameters:
Name Type Description
continuation function

the callback.

_thenRunCallbacks(optionsOrCallback, model) → {Parse.Promise}

Run the given callbacks after this promise is fulfilled.

Parameters:
Name Type Description
optionsOrCallback

A Backbone-style options callback, or a callback function. If this is an options object and contains a "model" attributes, that will be passed to error callbacks as the first argument.
model

If truthy, this will be passed as the first result of error callbacks. This is for Backbone-compatability.
Returns:
Type:
Parse.Promise

A promise that will be resolved after the callbacks are run, with the same result as this.

always()

Add handlers to be called when the promise is either resolved or rejected

catch()

Add handlers to be called when the Promise object is rejected

done()

Add handlers to be called when the Promise object is resolved

fail()

Add handlers to be called when the Promise object is rejected Alias for catch().

reject(error)

Marks this promise as fulfilled, firing any callbacks waiting on it.

Parameters:
Name Type Description
error Object

the error to pass to the callbacks.

resolve(result)

Marks this promise as fulfilled, firing any callbacks waiting on it.

Parameters:
Name Type Description
result Object

the result to pass to the callbacks.

then(resolvedCallback, rejectedCallback) → {Parse.Promise}

Adds callbacks to be called when this promise is fulfilled. Returns a new Promise that will be fulfilled when the callback is complete. It allows chaining. If the callback itself returns a Promise, then the one returned by "then" will not be fulfilled until that one returned by the callback is fulfilled.

Parameters:
Name Type Description
resolvedCallback function

Function that is called when this Promise is resolved. Once the callback is complete, then the Promise returned by "then" will also be fulfilled.
rejectedCallback function

Function that is called when this Promise is rejected with an error. Once the callback is complete, then the promise returned by "then" with be resolved successfully. If rejectedCallback is null, or it returns a rejected Promise, then the Promise returned by "then" will be rejected with that error.
Returns:
Type:
Parse.Promise

A new Promise that will be fulfilled after this Promise is fulfilled and either callback has completed. If the callback returned a Promise, then this Promise will not be fulfilled until that one is.