source: Dev/trunk/src/client/dojo/when.js @ 532

define([
        "./Deferred",
        "./promise/Promise"
], function(Deferred, Promise){
        "use strict";

        // module:
        //              dojo/when

        return function when(valueOrPromise, callback, errback, progback){
                // summary:
                //              Transparently applies callbacks to values and/or promises.
                // description:
                //              Accepts promises but also transparently handles non-promises. If no
                //              callbacks are provided returns a promise, regardless of the initial
                //              value. Foreign promises are converted.
                //
                //              If callbacks are provided and the initial value is not a promise,
                //              the callback is executed immediately with no error handling. Returns
                //              a promise if the initial value is a promise, or the result of the
                //              callback otherwise.
                // valueOrPromise:
                //              Either a regular value or an object with a `then()` method that
                //              follows the Promises/A specification.
                // callback: Function?
                //              Callback to be invoked when the promise is resolved, or a non-promise
                //              is received.
                // errback: Function?
                //              Callback to be invoked when the promise is rejected.
                // progback: Function?
                //              Callback to be invoked when the promise emits a progress update.
                // returns: dojo/promise/Promise
                //              Promise, or if a callback is provided, the result of the callback.

                var receivedPromise = valueOrPromise && typeof valueOrPromise.then === "function";
                var nativePromise = receivedPromise && valueOrPromise instanceof Promise;

                if(!receivedPromise){
                        if(arguments.length > 1){
                                return callback ? callback(valueOrPromise) : valueOrPromise;
                        }else{
                                return new Deferred().resolve(valueOrPromise);
                        }
                }else if(!nativePromise){
                        var deferred = new Deferred(valueOrPromise.cancel);
                        valueOrPromise.then(deferred.resolve, deferred.reject, deferred.progress);
                        valueOrPromise = deferred.promise;
                }

                if(callback || errback || progback){
                        return valueOrPromise.then(callback, errback, progback);
                }
                return valueOrPromise;
        };
});