/*
* Promy: Promises library
* Copyright (C) 2013 Nexedi SA
*
* This library is free software: you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/*jslint indent: 2, maxlen: 80, sloppy: true, nomen: true */
/*global setInterval, setTimeout, clearInterval, clearTimeout */
(function (dependencies, module) {
"use strict";
/*global define, exports, window */
if (typeof define === 'function' && define.amd) {
return define(dependencies, module);
}
if (typeof exports === 'object') {
module(exports);
}
if (typeof window === 'object') {
window.promy = {};
module(window.promy);
}
}(['exports'], function (exports) {
"use strict";
var UNRESOLVED = 0, RESOLVED = 1, REJECTED = 2, CANCELLED = 3;
/**
* thenItem(item, [onSucess], [onError], [onProgress]): any
*
* Execute one of the given callback when the item is fulfilled. If the item
* is not a promise, then onSuccess is called with the item as first
* parameter.
*
* @param {Any} item A promise, deferred or a simple value
* @param {Function} [onSuccess] The callback to call on resolve
* @param {Function} [onError] The callback to call on reject
* @param {Function} [onProgress] The callback to call on notify
*/
function thenItem(item, onSuccess, onError, onProgress) {
if (typeof item === 'object' && item !== null) {
if (typeof item.promise === 'object' && item.promise !== null &&
typeof item.promise.then === 'function') {
// item seams to be a Deferred
return item.promise.then(
onSuccess,
onError,
onProgress
);
}
if (typeof item.then === 'function') {
// item seams to be a Promise
return item.then(
onSuccess,
onError,
onProgress
);
}
}
return onSuccess(item);
}
/**
* promiseResolve(promise, answers): any
*
* Resolve the promise with the given answers.
*
* @param {Promise} promise The promise to resolve
* @param {Array} answers The arguments to give
*/
function promiseResolve(promise, answers) {
var array;
if (promise._state === UNRESOLVED) {
promise._state = RESOLVED;
promise._answers = answers;
array = promise._onResolve.slice();
setTimeout(function () {
var i;
for (i = 0; i < array.length; i += 1) {
try {
array[i].apply(promise, promise._answers);
} catch (ignore) {} // errors will never be retrieved by global
}
});
// free the memory
promise._onResolve = undefined;
promise._onReject = undefined;
promise._onProgress = undefined;
}
}
/**
* promiseReject(promise, answers): any
*
* Reject the promise with the given answers.
*
* @param {Promise} promise The promise to reject
* @param {Array} answers The arguments to give
*/
function promiseReject(promise, answers) {
var array;
if (promise._state === UNRESOLVED) {
promise._state = REJECTED;
promise._answers = answers;
array = promise._onReject.slice();
setTimeout(function () {
var i;
for (i = 0; i < array.length; i += 1) {
try {
array[i].apply(promise, promise._answers);
} catch (ignore) {} // errors will never be retrieved by global
}
});
// free the memory
promise._onResolve = undefined;
promise._onReject = undefined;
promise._onProgress = undefined;
}
}
/**
* promiseNotify(promise, answers): any
*
* Notify the promise with the given answers.
*
* @param {Promise} promise The promise to notify
* @param {Array} answers The arguments to give
*/
function promiseNotify(promise, answers) {
var i;
if (promise._onProgress) {
for (i = 0; i < promise._onProgress.length; i += 1) {
try {
promise._onProgress[i].apply(promise, answers);
} catch (ignore) {} // errors will never be retrieved by global
}
}
}
/**
* Promise(cancel)
*
* @class Promise
* @constructor
*/
function Promise(cancel) {
this._onReject = [];
this._onResolve = [];
this._onProgress = [];
this._state = UNRESOLVED;
if (typeof cancel === 'function') {
this.promise._cancel = cancel;
}
}
////////////////////////////////////////////////////////////
// http://wiki.commonjs.org/wiki/Promises/A
// then(fulfilledHandler, errorHandler, progressHandler)
/**
* then([onSuccess], [onError], [onProgress]): Promise
*
* Returns a new Promise with the return value of the `onSuccess` or `onError`
* callback as first parameter. If the pervious promise is resolved, the
* `onSuccess` callback is called. If rejected, the `onError` callback is
* called. If notified, `onProgress` is called.
*
* Deferred.when(1).
* then(function (one) { return one + 1; }).
* then(console.log); // shows 2
*
* @method then
* @param {Function} [onSuccess] The callback to call on resolve
* @param {Function} [onError] The callback to call on reject
* @param {Function} [onProgress] The callback to call on notify
* @return {Promise} The new promise
*/
Promise.prototype.then = function (onSuccess, onError, onProgress) {
/*global Deferred*/
var defer, next = new this.constructor(this._cancel), that = this;
defer = new Deferred();
defer.promise = next;
switch (this._state) {
case RESOLVED:
if (typeof onSuccess === 'function') {
setTimeout(function () {
try {
thenItem(
onSuccess.apply(that, that._answers),
defer.resolve.bind(defer),
defer.reject.bind(defer)
);
} catch (e) {
defer.reject(e);
}
});
} else {
setTimeout(function () {
defer.resolve.apply(defer, that._answers);
});
}
break;
case REJECTED:
if (typeof onError === 'function') {
setTimeout(function () {
var result;
try {
result = onError.apply(that, that._answers);
if (result === undefined) {
return defer.reject.apply(defer, that._answers);
}
thenItem(
result,
defer.reject.bind(defer),
defer.reject.bind(defer)
);
} catch (e) {
defer.reject(e);
}
});
} else {
setTimeout(function () {
defer.reject.apply(defer, that._answers);
});
}
break;
case UNRESOLVED:
if (typeof onSuccess === 'function') {
this._onResolve.push(function () {
try {
thenItem(
onSuccess.apply(that, arguments),
defer.resolve.bind(defer),
defer.reject.bind(defer),
defer.notify.bind(defer)
);
} catch (e) {
defer.reject(e);
}
});
} else {
this._onResolve.push(function () {
defer.resolve.apply(defer, arguments);
});
}
if (typeof onError === 'function') {
this._onReject.push(function () {
try {
thenItem(
onError.apply(that, that._answers),
defer.reject.bind(defer),
defer.reject.bind(defer)
);
} catch (e) {
defer.reject(e);
}
});
} else {
this._onReject.push(function () {
defer.reject.apply(defer, that._answers);
});
}
if (typeof onProgress === 'function') {
this._onProgress.push(function () {
var result;
try {
result = onProgress.apply(that, arguments);
if (result === undefined) {
defer.notify.apply(defer, arguments);
} else {
defer.notify(result);
}
} catch (e) {
defer.notify.apply(defer, arguments);
}
});
} else {
this._onProgress.push(function () {
defer.notify.apply(defer, arguments);
});
}
break;
default:
break;
}
return next;
};
// p.resolve() ?
// p.reject() ?
// p.notify() ?
/**
* p.cancel(): p
*
* Cancels the operation by calling promise._cancel().
*
* @method cancel
* @return {Promise} this
*/
Promise.prototype.cancel = function () {
if (this._state === UNRESOLVED) {
this._state = CANCELLED;
if (typeof this._cancel === 'function') {
this._cancel();
}
this._onResolve = undefined;
this._onReject = undefined;
this._onProgress = undefined;
}
return this;
};
/**
* p.timeout(delay): p
*
* Reject the promise with an Error("Timeout") and cancel the operation.
*
* @method timeout
* @param {Number} delay The delay before rejection
* @return {Promise} this
*/
Promise.prototype.timeout = function (delay) {
return exports.choose(this, exports.delay(delay).then(function () {
throw new Error("Timeout (" + delay + ")");
}));
};
////////////////////////////////////////////////////////////
// http://wiki.commonjs.org/wiki/Promises/A
// get(propertyName)
/**
* get(property): Promise
*
* Get the property of the promise response as first parameter of the new
* Promise.
*
* Deferred.when({'a': 'b'}).get('a').then(console.log); // shows 'b'
*
* @method get
* @param {String} property The object property name
* @return {Promise} The promise
*/
Promise.prototype.get = function (property) {
return this.then(function (dict) {
return dict[property];
});
};
////////////////////////////////////////////////////////////
// http://wiki.commonjs.org/wiki/Promises/A
// call(functionName, arg1, arg2, ...)
/**
* call(function_name, *args): Promise
*
* Deferred.when({'a': console.log}).call('a', 'b'); // shows 'b'
*
* @method call
* @param {String} function_name The function to call
* @param {Any} *[args] The function arguments
* @return {Promise} A new promise
*/
Promise.prototype.call = function (function_name) {
var args = Array.prototype.slice.call(arguments, 1);
return this.then(function (dict) {
return dict[function_name].apply(dict, args);
});
};
/**
* put(property, value): Promise
*
* Put a property value from a promise response and return the registered
* value as first parameter of the new Promise.
*
* Deferred.when({'a': 'b'}).put('a', 'c').then(console.log); // shows 'c'
*
* @method put
* @param {String} property The object property name
* @param {String} value The value to put
* @return {Promise} A new promise
*/
Promise.prototype.put = function (property, value) {
return this.then(function (dict) {
dict[property] = value;
return dict[property];
});
};
/**
* p.done(callback): p
*
* Call the callback on resolve.
*
* Deferred.when(1).
* done(function (one) { return one + 1; }).
* done(console.log); // shows 1
*
* @method done
* @param {Function} callback The callback to call on resolve
* @return {Promise} This promise
*/
Promise.prototype.done = function (callback) {
var that = this;
if (typeof callback !== 'function') {
return this;
}
switch (this._state) {
case RESOLVED:
setTimeout(function () {
try {
callback.apply(that, that._answers);
} catch (ignore) {} // errors will never be retrieved by global
});
break;
case UNRESOLVED:
this._onResolve.push(callback);
break;
default:
break;
}
return this;
};
/**
* p.fail(callback): p
*
* Call the callback on reject.
*
* promisedTypeError().
* fail(function (e) { name_error(); }).
* fail(console.log); // shows TypeError
*
* @method fail
* @param {Function} callback The callback to call on reject
* @return {Promise} This promise
*/
Promise.prototype.fail = function (callback) {
var that = this;
if (typeof callback !== 'function') {
return this;
}
switch (this._state) {
case REJECTED:
setTimeout(function () {
try {
callback.apply(that, that._answers);
} catch (ignore) {} // errors will never be retrieved by global
});
break;
case UNRESOLVED:
this._onReject.push(callback);
break;
default:
break;
}
return this;
};
/**
* p.progress(callback): p
*
* Call the callback on notify.
*
* Promise.delay(100, 10).
* progress(function () { return null; }).
* progress(console.log); // does not show null
*
* @method progress
* @param {Function} callback The callback to call on notify
* @return {Promise} This promise
*/
Promise.prototype.progress = function (callback) {
if (typeof callback !== 'function') {
return this;
}
switch (this._state) {
case UNRESOLVED:
this._onProgress.push(callback);
break;
default:
break;
}
return this;
};
/**
* p.always(callback): p
*
* Call the callback on resolve or on reject.
*
* sayHello().
* done(iAnswer).
* fail(iHeardNothing).
* always(iKeepWalkingAnyway);
*
* @method always
* @param {Function} callback The callback to call on resolve or on reject
* @return {Promise} This promise
*/
Promise.prototype.always = function (callback) {
var that = this;
if (typeof callback !== 'function') {
return this;
}
switch (this._state) {
case RESOLVED:
case REJECTED:
setTimeout(function () {
try {
callback.apply(that, that._answers);
} catch (ignore) {} // errors will never be retrieved by global
});
break;
case UNRESOLVED:
that._onReject.push(callback);
that._onResolve.push(callback);
break;
default:
break;
}
return this;
};
exports.Promise = Promise;
/**
* Deferred(cancel)
*
* @class Deferred
* @constructor
*/
function Deferred(cancel) {
this.promise = new Promise(cancel);
}
/**
* resolve(*args): any
*
* Resolves the promise with the given arguments.
*
* @method resolve
* @param {Any} *[args] The arguments to give
*/
Deferred.prototype.resolve = function () {
return promiseResolve(this.promise, arguments);
};
/**
* reject(*args): any
*
* Rejects the promise with the given arguments.
*
* @method reject
* @param {Any} *[args] The arguments to give
*/
Deferred.prototype.reject = function () {
return promiseReject(this.promise, arguments);
};
/**
* notify(*args): any
*
* Notifies the promise with the given arguments.
*
* @method notify
* @param {Any} *[args] The arguments to give
*/
Deferred.prototype.notify = function () {
return promiseNotify(this.promise, arguments);
};
exports.Deferred = Deferred;
//////////////////////////////////////////////////////////////////////
// Inspired by Task.js
/**
* now(value): Promise
*
* Converts an ordinary value into a fulfilled promise.
*
* @param {Any} value The value to use
* @return {Promise} The resolved promise
*/
exports.now = function (value) {
var deferred = new Deferred();
deferred.resolve(value);
return deferred.promise;
};
/**
* join(*promises): Promise
*
* Produces a promise that is resolved when all the given promises are
* resolved. The resolved value is an array of each of the resolved values of
* the given promises.
*
* If any of the promises is rejected, the joined promise is rejected with the
* same error, and any remaining unfulfilled promises are cancelled.
*
* @param {Promise} *[promises] The promises to join
* @return {Promise} A new promise
*/
exports.join = function () {
var promises, results = [], i, count = 0, deferred;
promises = Array.prototype.slice.call(arguments);
function cancel() {
var j;
for (j = 0; j < promises.length; j += 1) {
promises[j].cancel();
}
}
deferred = new Deferred(cancel);
function succeed(j) {
return function (answer) {
results[j] = answer;
count += 1;
if (count !== promises.length) {
return;
}
deferred.resolve(results);
};
}
function failed(answer) {
cancel();
deferred.reject(answer);
}
function notify(j) {
return function (answer) {
deferred.notify({
"promise": this,
"index": j,
"answer": answer
});
};
}
for (i = 0; i < promises.length; i += 1) {
promises[i].then(succeed(i), failed, notify(i));
}
return deferred.promise;
};
/**
* choose(*promises): Promise
*
* Produces a promise that is fulfilled when any one of the given promises is
* fulfilled. As soon as one of the promises is fulfilled, whether by being
* resolved or rejected, all the other promises are cancelled.
*
* @param {Promise} *[promises] The promises to use
* @return {Promise} A new promise
*/
exports.choose = function () {
var promises, i, deferred;
promises = Array.prototype.slice.call(arguments);
function cancel() {
var j;
for (j = 0; j < promises.length; j += 1) {
promises[j].cancel();
}
}
deferred = new Deferred(cancel);
function succeed(answer) {
cancel();
deferred.resolve(answer);
}
function failed(answer) {
cancel();
deferred.reject(answer);
}
function notify(j) {
return function (answer) {
deferred.notify({
"promise": this,
"index": j,
"answer": answer
});
};
}
for (i = 0; i < promises.length; i += 1) {
promises[i].then(succeed, failed, notify(i));
}
return deferred.promise;
};
/**
* sleep(delay[, every]): Promise
*
* Resolve the promise after `timeout` milliseconds and notfies us every
* `every` milliseconds.
*
* Deferred.delay(50, 10).then(console.log, console.error, console.log);
* // // shows
* // 10 // from progress
* // 20 // from progress
* // 30 // from progress
* // 40 // from progress
* // 50 // from progress
* // 50 // from success
*
* @param {Number} delay In milliseconds
* @param {Number} [every] In milliseconds
* @return {Promise} A new promise
*/
exports.sleep = function (delay, every) {
var deferred, timeout, interval, now = 0;
function cancel() {
clearTimeout(timeout);
clearInterval(interval);
}
deferred = new Deferred(cancel);
if (typeof every === 'number' && isFinite(every)) {
interval = setInterval(function () {
now += every;
deferred.notify(now);
}, every);
}
timeout = setTimeout(function () {
clearInterval(interval);
deferred.notify(delay);
deferred.resolve(delay);
}, delay);
return deferred.promise;
};
////////////////////////////////////////////////////////////
// http://wiki.commonjs.org/wiki/Promises/B
// when(value, callback, errback_opt)
/**
* when(item, [onSuccess], [onError], [onProgress]): Promise
*
* Return an item as first parameter of the promise answer. If item is of
* type Promise, the method will just return the promise. If item is of type
* Deferred, the method will return the deferred promise.
*
* Deferred.when('a').then(console.log); // shows 'a'
*
* @param {Any} item The item to use
* @param {Function} [onSuccess] The callback called on success
* @param {Function} [onError] the callback called on error
* @param {Function} [onProgress] the callback called on progress
* @return {Promise} The promise
*/
exports.when = function (item, onSuccess, onError, onProgress) {
if (typeof item === 'object' && item !== null) {
if (typeof item.promise === 'object' && item.promise !== null &&
typeof item.promise.then === 'function') {
// item seams to be a Deferred
return item.promise.then(onSuccess, onError, onProgress);
}
if (typeof item.then === 'function') {
// item seams to be a Promise
return item.then(onSuccess, onError, onProgress);
}
}
// item is just a value, convert into fulfilled promise
var deferred = new Deferred(), promise;
if (typeof onSuccess === 'function') {
promise = deferred.promise.then(onSuccess);
} else {
promise = deferred.promise;
}
deferred.resolve(item);
return promise;
};
////////////////////////////////////////////////////////////
// http://wiki.commonjs.org/wiki/Promises/B
// get(object, name)
/**
* get(dict, property): Promise
*
* Return the dict property as first parameter of the promise answer.
*
* Deferred.get({'a': 'b'}, 'a').then(console.log); // shows 'b'
*
* @param {Object} dict The object to use
* @param {String} property The object property name
* @return {Promise} The promise
*/
exports.get = function (dict, property) {
var p = new Deferred();
try {
p.resolve(dict[property]);
} catch (e) {
p.reject(e);
}
return p;
};
////////////////////////////////////////////////////////////
// http://wiki.commonjs.org/wiki/Promises/B
// put(object, name, value)
/**
* put(dict, property, value): Promise
*
* Set and return the dict property as first parameter of the promise answer.
*
* Deferred.put({'a': 'b'}, 'a', 'c').then(console.log); // shows 'c'
*
* @param {Object} dict The object to use
* @param {String} property The object property name
* @param {Any} value The value
* @return {Promise} The promise
*/
exports.put = function (dict, property, value) {
var p = new Deferred();
try {
dict[property] = value;
p.resolve(dict[property]);
} catch (e) {
p.reject(e);
}
return p;
};
}));