inventive title

Promise.js 2.0 – Promise Framework for JavaScript

Ron Buckton — Mon, 15 Aug 2011 13:10:00 GMT

Well over a year ago I posted an article describing how to employ an asynchrony concept known as a Promise. Since then a number of implementations of Promises have shown up in libraries such as jQuery Deferred and CommonJS. I’ve updated the sources and removed the dependency on ASP.NET Ajax, however the current version depends on features of ECMAScript 5, which is supported in IE 9, Chrome, and Firefox. If you need support for Safari, Opera, or IE 8 and under you need to use an ES5 Polyfill. In addition the license has been changed from MSR-LA (Non-Commercial) to MS-PL which allows commercial use.

Introduction

Promise is a programming model that deals with deferred results in concurrent programming. The basic idea around promises are that rather than issuing a blocking call for a resource (IO, Network, etc.) you can immediately return a promise for a future value that will eventually be fulfilled. This allows you to write non-blocking logic that executes asynchronously without having to write a lot of synchronization and plumbing code.

License

Promise.js is licensed under the Microsoft Public License (MS-PL).

Source

promise.zip

Description

Promises are especially useful in JavaScript due to the fact that most of the JavaScript runtimes do not provide a means to block execution to wait on a result from a possibly long-running operation. To facilitate rich interactive experiences in the browser, asynchrony is imperative. All of the current generation (and many earlier generation) browsers support XMLHttpRequest as a means to asynchronously fetch content from the server on demand. Without a Promise model, fetching html from the server might use code like the following:

 1: function fetchSync(url) {

 2:   var xhr = new XMLHttpRequest();

 3:   xhr.open(url, "GET", false, null, null);

 4:   xhr.send(null);

 5:   if (xhr.status == 200) {

 6:     return xhr;

 7:   }

 8:   throw new Error(xhr.statusText);

 9: }

10:

 11: function fetchAsync(url, callback, errorCallback) {

 12:   var xhr = new XMLHttpRequest();

 13:   xhr.onreadystatechange = function() {

 14:     if (xhr.readyState == 4) {

 15:       if (xhr.status == 200) {

 16:         callback(xhr);

 17:       }

 18:       else {

 19:         errorCallback(new Error(xhr.statusText));

 20:       }

 21:     }

 22:   }

 23:   xhr.open(url, "GET", true, null, null);

 24:   xhr.send(null);

 25: }

In the first example, the RSS feed is fetched synchronously (see line 3). In this case the code is straightforward but the request is blocking, which means script execution is suspended until the request is completed or fails. This is not optimal in an AJAX application as it can impact the interactivity of the page.

The second example attempts to alleviate the blocking call by introducing a callback that will be executed when the request completes. This is advantageous as it is non-blocking, however the programming model can become inconsistent if you are working with different asynchronous data sources including loading local resources, performing computationally intensive tasks (such as xml transforms or other data transformation), etc.

To actually use the resulting feed you might have to do some additional work:

 1: fetchAsync(

 2:   "/feeds/changes.rss",

 3:   function (rssXhr) {

 4:     fetchAsync(

 5:       "/resources/rss.xsl",

 6:       function (xslXhr) {

 7:         document.getElementById("host").innerHTML =

 8:           rssXhr.responseXML.transformNode(xslXhr.responseXML);

 9:       },

 10:       function (e) {

 11:         document.getElementById("host").innerHTML =

 12:           "Error: " + e.message;

 13:       });

 14:   }, function (e) {

 15:     document.getElementById("host").innerHTML =

 16:       "Error: " + e.message;

 17:   });

In this example we now have two asynchronous calls for content, however one depends on the other and as a result we can’t take advantage of concurrent requests to speed up the process.

Using promises we could instead do the following:

 1: var changes = Promise.get("/feeds/changes.rss");

 2: var xsl = Promise.get("/resources/rss.xsl");

 3: Promise

 4:   .all(changes, xsl)

 5:   .then(function(ar) {

 6:     document.getElementById("host").innerHTML =

 7:       ar[0].responseXML.transformNode(ar[1].responseXML);

 8:   }, function(e) {

 9:      document.getElementById("host").innerText = e.message;

 10:   })

Another feature of Promises is pipelining, the ability to create a series of operations based on the result of a promise. Then then() function is used to pipeline a promise, creating a new Promise based on the eventual output of the source. For example:

 1: Promise

 2:   .get("somefeed.xml")

 3:   .then({

 4:     resolve: function(xhr) { return xhr.responseXML }),

 5:     progress: function(xhr) { console.log("Loading...") }

 6:   })

 7:   .then({

 8:     resolve: function(xdoc) { console.log(xdoc.xml) },

 9:     reject: function(e) { console.error(e.message) )

 10:   })

On line 2 we fetch an xml document from the server. On line 4 we create a pipeline that will eventually convert the response into an XML document. On line 8 when the document is finally available we can handle the results.

Here's an example using piplined promises and JSONP to get the public timeline from Twitter:

 1: Promise

 2:   .jsonp("https://api.twitter.com/1/statuses/public_timeline.json")

 3:   .then(function (data) {

 4:     data.forEach(function (tweet) {

 5:       var newTweet = createTweet(tweet);

 6:       document.getElementById("tweets").appendChild(newTweet);

 7:     });

 8:   })

 9:   .then({ reject: function (e) { alert(e) } });

Here's an example of computing a future factorial using Web Workers (supported in Safari, Chrome, Firefox, Opera and IE 10 (as of Platform Preview 2):

 1: // factorial.js

 2: onmessage = function(e) {

 3:   var value = e.data;

 4:   var result = 0;

 5:   do {

 6:     result += value;

 7:   }

 8:   while (--value > 0);

 9:   postMessage(result);

 10: }

 1: // client.js

 2: Promise

 3:   .work("factorial.js", 10)

 4:   .then(function(result) { console.log(result) })

Documentation

// PromiseSource
var source = new PromiseSource()
/// Creates a new PromiseSource

source.isCanceled
/// Gets a value indicating whether the Promise was 
/// canceled

source.promise
/// 
/// Gets the Promise for the current PromiseSource
/// 

source.resolve(value)
/// Resolve the promise using the provided value
/// 
/// The value for the promise
/// 

source.reject(error)
/// Reject the promise using the provided error
/// The error for the promise

source.progress(value)
/// Send a progress notification using the provided value
/// 

var registration = source.cleanup(cleanupCallback)
/// 
/// Register a callback used to cleanup when the related promise is canceled
/// 
/// 
/// The callback function to execute
/// 
/// 
/// A function that can be used to unregister the cleanup callback
/// 

source.cancel(dueTime)
/// 
/// Cancels the promise and executes cleanup callbacks immediately or 
/// optionally after a period of time
/// 
/// 
/// Optional. The time in milliseconds to wait before canceling the promise
/// 


// Promise
var promise = new Promise(initCallback)
/// 
/// Creates a new Promise for the provided completion callback
/// 
/// 
/// A callback used to initialize the promise.
/// 
/// 
/// The object used to resolve the promise
/// 
/// 
/// 

promise.isComplete
/// 
/// Gets a value indicating whether the Promise has completed
/// 

promise.isFaulted
/// 
/// Gets a value indicating whether the Promise is faulted
/// 

promise.isCanceled
/// 
/// Gets a value indicating whether the Promise was canceled
/// 

promise.cancel(dueTime)
/// 
/// Cancels the promise and executes cleanup callbacks immediately or 
/// optionally after a period of time
/// 
/// 
/// Optional. The time in milliseconds to wait before canceling the promise
/// 

var newPromise = promise.then(resolve, reject, progress)
var newPromise = promise.when(resolve, reject, progress)
/// 
/// Creates a new promise that executes an action based on the value of the 
/// antecedent promise.
/// 
/// 
/// The callback that is executed when the promise resolves successfully.
/// Its results are fed into a new Promise.
/// 
/// 
/// The value from the antecedent promise
/// 
/// The result for the new promise
/// 
/// 
/// 
/// The callback that is executed when the promise fails. Its results are 
/// fed into a new Promise.
/// 
/// 
/// The error raised from the antecedent promise
/// 
/// The result for the new promise
/// 
/// 
/// 
/// The callback that is executed when a promise posts progress.
/// 
/// 
/// The progress value from the antecedent promise
/// 
/// 
/// 
/// 
/// The promise created for the provided callbacks
/// 

var newPromise = promise.then(options)
var newPromise = promise.when(options)
/// 
/// Creates a new promise that executes an action based on the value of the 
/// antecedent promise. 
/// 
/// 
/// An object literal for the arguments "resolve", "reject", and "progress"
/// 
/// 
/// The promise created for the provided callbacks
/// 

var newPromise = promise.get(name)
/// 
/// Creates a promise for the value of the data property with the specified 
/// name from the result of this promise
/// 
/// The name of the data property
/// 
/// A new Promise that returns the value of the data property
/// 

var newPromise = promise.put(name, value)
/// 
/// Creates a promise that completes without a value after setting the value 
/// of the data property with the specified name from the result of this 
/// promise
/// 
/// The name of the data property
/// 
/// The value for the data property
/// 
/// 
/// A new Promise with no value that completes after the value of the data 
/// property is set
/// 

var newPromise = promise.post(name, args)
/// 
/// Creates a Promise that returns the result of calling the named function 
/// with the supplied arguments on the result of this promise. Arguments are 
/// passed in a fashion similar to Function.prototype.apply
/// 
/// The name of the function
/// 
/// An array of arguments for the function
/// 
/// 
/// A new Promise that returns the value of the function call
/// 

var newPromise = promise.send(name, ...args)
/// 
/// Creates a Promise that returns the result of calling the named function 
/// with the supplied arguments on the result of this promise. Arguments are 
/// passed in a fashion similar to Function.prototype.call
/// 
/// The name of the function
/// 
/// A parameter array of arguments for the function
/// 
/// 
/// A new Promise that returns the value of the function call
/// 

var newPromise = promise.unwrap()
/// 
/// Creates a Promise for the underlying value of a Promise who's result is 
/// itself a Promise
/// 
/// 
/// A promise for the underlying value of the Promise
/// 

var newPromise = promise.end()
/// 
/// Creates a Promise that throws any unhandled exception to the host object.
/// 
/// 

Promise.canUseWorker
/// 
/// Gets a value indicating whether Web Workers are supported
/// 

Promise.isPromise(value)
/// Determines whether the provided value is a Promise
/// 
/// The object that may be a promise
/// 
/// 
/// True if the value provided is a Promise, otherwise false
/// 

var promise = Promise.resolve(value)
/// Returns the provided value as a Promise
/// 
/// The value to Promise
/// 
/// The Promise for the value
/// 
/// If the provided value is already a Promise it is returned. If it is a 
/// PromiseSource its associated Promise is returned. Otherwise, a new 
/// Promise is created and fully resolved with the provided value
/// 

var promise = Promise.reject(error)
/// 
/// Creates a Promise that is faulted using the provided Error
/// 
/// 
/// The faulted Promise

var promise = Promise.delay(dueTime, value)
/// 
/// Creates a Promise that completes after a period of time using the 
/// optionally provided value
/// 
/// 
/// The due time in milliseconds at which the Promise will complete
/// 
/// 
/// An optional value to use as the result of the Promise
/// 
/// 

var promise = Promise.start(func, dueTime)
/// 
/// Creates and schedules a Promise to execute the provided function at a 
/// later time
/// 
/// 
/// The callback to execute whose return value will be the result of the 
/// Promise.
/// 
/// The result for the Promise
/// 
/// 
/// 
/// The due time at which to start the callback. The default is immediately
/// 
/// 

var promise = Promise.when(promise, resolve, reject, progress)
/// 
/// Creates a new promise that executes an action based on the value of the 
/// antecedent promise.
/// 
/// 
/// The promise to monitor for a result. If the argument is not a Promise, 
/// one will be created for it
/// 
/// 
/// The callback that is executed when the promise resolves successfully. 
/// Its results are fed into a new Promise.
/// 
/// 
/// The value from the antecedent promise
/// 
/// The result for the new promise
/// 
/// 
/// 
/// The callback that is executed when the promise fails. Its results are 
/// fed into a new Promise.
/// 
/// 
/// The error raised from the antecedent promise
/// 
/// The result for the new promise
/// 
/// 
/// 
/// The callback that is executed when a promise posts progress.
/// 
/// 
/// The progress value from the antecedent promise
/// 
/// 
/// 
/// 
/// The promise created for the provided callbacks
/// 

var promise = Promise.when(options)
/// 
/// Creates a new promise that executes an action based on the value of the 
/// antecedent promise.
/// 
/// 
/// An object literal for the arguments "promise", "resolve", "reject", and 
/// "progress"
/// 
/// 
/// The promise created for the provided callbacks
/// 

var promise = Promise.any(...promises)
/// 
/// Creates a promise that resolves when at least one promise provided 
/// resolves. Arguments are passed as a parameter array
/// 
/// 
/// A parameter array of objects to wait for
/// 
/// 
/// A Promise whose result is the result of the first promise to resolve or 
/// fail.
/// 

var promise = Promise.all(...promises)
/// 
/// Creates a promise that resolves when all of the provided promises resolve 
/// or fail. Arguments are passed as a parameter array
/// 
/// 
/// A parameter array of objects to wait for
/// 
/// 
/// A Promise whose result is an in-order array of the results of the 
/// promises provided
/// 

var promise = Promise.work(url, message)
/// 
/// Creates a Promise for a result posted by a Web Worker thread
/// 
/// 
/// The url to the script for the web worker
/// 
/// 
/// An optional message to send to start the worker
/// 
/// 
/// A Promise for the first message posted by the Web Worker
/// 
/// 
/// This is a simplified approach to Web Worker-based promises. The first 
/// message posted by the worker becomes the result and the worker is then 
/// immediately terminated.
/// 

var promise = Promise.work(options)
/// 
/// Creates a Promise for a result posted by a Web Worker thread
/// 
/// 
/// An object literal for the arguments "url" and "message"
/// 
/// 
/// A Promise for the first message posted by the Web Worker
/// 
/// 
/// This is a simplified approach to Web Worker-based promises. The first 
/// message posted by the worker becomes the result and the worker is then 
/// immediately terminated
/// 

var promise = Promise.get(url, username, password, headers, query)
/// 
/// Issues an HTTP GET request for the content at the provided url
/// 
/// The url for the content
/// 
/// The username for the request.
/// 
/// 
/// The password for the request.
/// 
/// 
/// A JSON object containing headers for the request.
/// 
/// 
/// A JSON object or String containing the querystring for the 
/// request.
/// 
/// 
/// A Promise whose result is an XMLHttpRequest object
/// 

var promise = Promise.get(options)
/// 
/// Issues an HTTP GET request for the content at the provided url
/// 
/// 
/// An object literal for the arguments "url", "username", "password", 
/// "headers", and "query".
/// 
/// 
/// A Promise whose result is an XMLHttpRequest object
/// 

var promise = Promise.put(url, username, password, headers, query, body)
/// 
/// Issues an HTTP PUT request for the content at the provided url
/// 
/// The url for the content
/// 
/// The username for the request.
/// 
/// 
/// The password for the request.
/// 
/// 
/// A JSON object containing headers for the request.
/// 
/// 
/// A JSON object or String containing the querystring for the request.
/// 
/// 
/// A JSON object or String containing the body for the request.
/// 
/// 
/// A Promise whose result is an XMLHttpRequest object
/// 

var promise = Promise.put(options)
/// 
/// Issues an HTTP PUT request for the content at the provided url
/// 
/// 
/// An object literal for the arguments "url", "username", "password", 
/// "headers", "query", and "body"
/// 
/// 
/// A Promise whose result is an XMLHttpRequest object
/// 

var promise = Promise.post(url, username, password, headers, query, body)
/// 
/// Issues an HTTP POST request for the content at the provided url
/// 
/// The url for the content
/// 
/// The username for the request.
/// 
/// 
/// The password for the request.
/// 
/// 
/// A JSON object containing headers for the request.
/// 
/// 
/// A JSON object or String containing the querystring for the request.
/// 
/// 
/// A JSON object or String containing the body for the request.
/// 
/// 
/// A Promise whose result is an XMLHttpRequest object
/// 

var promise = Promise.post(options)
/// 
/// Issues an HTTP POST request for the content at the provided url
/// 
/// 
/// An object literal for the arguments "url", "username", "password", 
/// "headers", "query", and "body"
/// 
/// 
/// A Promise whose result is an XMLHttpRequest object
/// 

var promise = Promise.del(url, username, password, headers, query)
/// 
/// Issues an HTTP DELETE request for the content at the provided url
/// 
/// The url for the content
/// 
/// The username for the request.
/// 
/// 
/// The password for the request.
/// 
/// 
/// A JSON object containing headers for the request.
/// 
/// 
/// A JSON object or String containing the querystring for the request.
/// 
/// 
/// A Promise whose result is an XMLHttpRequest object
/// 

var promise = Promise.del(options)
/// 
/// Issues an HTTP DELETE request for the content at the provided url
/// 
/// 
/// An object literal for the arguments "url", "username", "password", 
/// "headers", and "query"
/// 
/// 
/// A Promise whose result is an XMLHttpRequest object
/// 

var promise = Promise.json(method, url, username, password, headers, query, 
                           body)
/// 
/// Issues an HTTP request for the content at the provided url, returning it 
/// as a JSON object
/// 
/// 
/// The HTTP method to use for the request. May be GET, PUT, POST, or DELETE
/// 
/// The url for the content
/// 
/// The username for the request.
/// 
/// 
/// The password for the request.
/// 
/// 
/// A JSON object containing headers for the request.
/// 
/// 
/// A JSON object or String containing the querystring for the request.
/// 
/// 
/// A JSON object or String containing the body for the request.
/// 
/// 
/// A Promise whose result is a JavaScript object
/// 

var promise = Promise.json(options)
/// 
/// Issues an HTTP request for the content at the provided url, returning it 
/// as a JSON object
/// 
/// 
/// An object literal for the arguments "method", "url", "username", 
/// "password", "headers", "query", and "body"
/// 
/// 
/// A Promise whose result is a JavaScript object
/// 

var promise = Promise.jsonp(url, query, callbackArg)
/// 
/// Issues an HTTP request using JSONP for the content at the provided url
/// 
/// The url for the content
/// 
/// A JSON object or String containing the querystring for the request.
/// 
/// 
/// The name of the callback argument. The default is "callback"
/// 
/// 
/// A Promise whose result is a JavaScript object
/// 

var promise = Promise.jsonp(options)
/// 
/// Issues an HTTP request using JSONP for the content at the provided url
/// 
/// 
/// An object literal for the arguments "url", "query", and "callbackArg"
/// 
/// 
/// A Promise whose result is a JavaScript object
///

Promises and Futures in JavaScript

Ron Buckton — Fri, 29 Jan 2010 12:22:00 GMT

[Note: A new version of Promise.js is available here. It has a less restrictive license and additional functionality. Please be sure to check it out.]

A Promise is a programming model that deals with deferred results in concurrent programming. The basic idea around promises are that rather than issuing a blocking call for a resource (IO, Network, etc.) you can immediately return a promise for a future value that will eventually be fulfilled. This allows you to write non-blocking logic that executes asynchronously without having to write a lot of synchronization and plumbing code.

For example, lets say we want to load an RSS feed via HTTP. To accomplish this in JavaScript we have to leverage the XMLHttpRequest object. The following example shows how one might load the RSS feed from this blog using conventional means:

 1: function fetchSync(url) {

 2:   var xhr = new XMLHttpRequest();

 3:   xhr.open(url, "GET", false, null, null);

 4:   xhr.send(null);

 5:   if (xhr.status == 200) {

 6:     return xhr;

 7:   }

 8:   throw new Error(xhr.statusText);

 9: }

10:

 11: function fetchAsync(url, callback, errorCallback) {

 12:   var xhr = new XMLHttpRequest();

 13:   xhr.onreadystatechange = function() {

 14:     if (xhr.readyState == 4) {

 15:       if (xhr.status == 200) {

 16:         callback(xhr);

 17:       }

 18:       else {

 19:         errorCallback(new Error(xhr.statusText));

 20:       }

 21:     }

 22:   }

 23:   xhr.open(url, "GET", true, null, null);

 24:   xhr.send(null);

 25: }

To actually use the resulting feed you might have to do some additional work:

 1: fetchAsync(

 2:   "https://blogs.msdn.com/rbuckton/rss.xml",

 3:   function (rss) {

 4:     fetchAsync(

 5:       "/some/stylesheet.xsl",

 6:        function (xsl) {

 7:          document.getElementById("host").innerHTML = rss.responseXML.transformNode(xsl.documentElement);

 8:        },

 9:        function (e) {

 10:          document.getElementById("host").innerHTML = "Error: " + ex.message;

 11:        })

 12:   },

 13:   function (ex) {

 14:     document.getElementById("host").innerHTML = "Error: " + ex.message;

 15:   });

In this example we now have two asynchronous calls for content, however one depends on the other and as a result we can’t take advantage of concurrent requests to speed up the process.

Now lets look at a concurrent example:

 1: var rss = null;

 2: var xsl = null;

3:

 4: function tryComplete() {

 5:   if (rss != null && xsl != null) {

 6:     document.getElementById("host").innerHTML = rss.responseXML.transformNode(xsl.documentElement);

 7:   }

 8: }

9:

 10: fetchAsync(

 11:   "https://blogs.msdn.com/rbuckton/rss.xml",

 12:    function(rssXhr) {

 13:      rss = rssXhr;

 14:      tryComplete();

 15:    },

 16:    function (e) {

 17:      document.getElementById("host").innerHTML += "Error: " + e.message + "
";

 18:    });

19:

 20: fetchAsync(

 21:   "/some/stylesheet.xsl",

 22:   function (xslXhr) {

 23:     xsl = xslXhr;

 24:     tryComplete();

 25:   },

 26:    function (e) {

 27:      document.getElementById("host").innerHTML += "Error: " + e.message + "
";

 28:    });

Now the above example can utilize concurrent requests and synchronize the results, but wow that’s a lot code.

Using promises you can instead do the following:

 1: var prss = Promise.fetch("https://blogs.msdn.com/rbuckton/rss.xml");

 2: var pxsl = Promise.fetch("/some/stylesheet.xsl");

 3: Promise.whenOnly(

 4:   Promise.join(prss, pxsl),

 5:   function() {

 6:     var rss = prss.get_value();

 7:     var xsl = pxsl.get_value();

 8:     document.getElementById("host").innerHTML = rss.responseXML.transformNode(xsl.responseXML);

 9:   },

 10:   function(ex) {

 11:     document.getElementById("host").innerHTML = "Error: " + ex.message;

 12:   });

Another feature of Promises is pipelining, the ability to create a series of operations based on the result of promises. The Promise.when() function is used to pipeline a promise, creating a new Promise based on the eventual output of the source. For example:

 1: var pfeed = Promise.fetch("somefeed.xml");

2:

 3: var pfeedXml = Promise.when(pfeed, function(feed) { return feed.responseXML; });

 4: Promise.whenOnly(pfeedXml, function(feedXml) { alert(feedXml.xml); });

5:

 6: var pfeedText = Promise.when(pfeed, function(feed) { return feed.responseText; });

 7: Promise.whenOnly(pfeedText, function(feedText) { console.log(feedText); });

On line 1 we fetch an xml document from the server. On line 3 we create a pipeline that will eventually convert the response into an XML document. On line 4 when the document is finally available we can alert the user. On line 6 we create a pipeline that will eventually get the response value as text. On line 7 we can log it to the console.

Here’s an example of using pipelined Promises to get the public twitter timeline in JSONP:

 1: Promise

 2:   .jsonp("https://twitter.com/statuses/public_timeline.json")

 3:   .whenOnly(function(timeline) {

 4:     alert(timeline.length);

 5:   });

A promise can be created for other deferred actions as well. For example:

 1: var pinput = new Promise(

 2:   function(fulfillPromise, breakPromise) {

 3:     var btn = document.getElementById("button");

 4:     var txt = document.getElementById("txt");

 5:     btn.onclick = function() {

 6:       fulfillPromise(txt.value);

 7:     }

 8:   }

 9: );

10:

 11: pinput.whenOnly(function(value) { alert(value); });

The above sample creates a promise for eventual input that you can act on at any point.

Whether a promise completes after a delay or very quickly (even synchronously), the programming model doesn’t change. The Promise model can even handle present information, so that present and future data can be mixed within the model. This is due to Promise.immediate(), which creates a promise that is fulfilled synchronously. All of the “static” methods on the Promise object will implicitly create a Promise for any non-future data (data that is not already encapsulated in a Promise).

Here’s an example of a future factorial (based on the Wikipedia example):

 1: function factorial(value) {

 2:   return new Promise(

 3:     function(fulfillPromise, breakPromise) {

 4:       setTimeout(

 5:         function() {

 6:           var result = 0;

 7:           do {

 8:             result += value;

 9:           }

 10:           while (--value > 0);

 11:           fulfillPromise(result);

 12:         },

 13:         1);

 14:     }

 15:   );

 16: }

17:

 18: var pfactorial = factorial(100000)

 19:   .when(function(result) { return result + 3; })

 20:   .whenOnly(function(result) { alert(result); });

This example uses setTimeout (at line 4) to ensure the request returns immediately and does not block linear execution of the code.

*NOTE: The attached API does not overcome the Same Origin Policy when used in the browser. This means that you can only make requests back to the same domain as the caller. Same Origin Policy does not apply for Gadgets (Windows 7 and Windows Vista) or for Widgets (Windows Mobile 6.5), which is where I’ve used this library for the most part. I have added some JSONP support in the library however JSONP is very limited.

Here is a quick overview of the current Promise API:

// constructor

var p = new Promise(initCallback) 
// initCallback: callback function that takes two 
// parameters, the fulfillPromise and breakPromise 
// callback functions.

// members

p.get_isComplete() 
// Gets whether the promise is complete
// returns: Boolean value that is True if the promise is 
// complete

p.get_value()
// Gets the value of the promise or 'undefined' if the 
// promise has not completed. If the promise was 
// broken during execution an exception will be thrown
// returns: Object value 

p.call(name, params)
// Calls a named function on the future value of the 
// promise
// name: String value for name of the field on the 
// promise result object that contains a function 
// to call
// params: parameter array of arguments to the 
// function. specified as in-line arguments not as an
// array: p.call("foo", 1, 2, 3)
// returns: a promise for the result of the call

p.getValue(name)
// Gets the value of a named field on the future
// value of the promise
// name: String value for the name of a field on the
// promise result object
// returns: a promise for the value of the field

p.setValue(name, value)
// Sets the value of a named field on the future
// value of the promise
// name: String value for the name of a field on the
// promise result object
// value: Object value to set on the field for the
// promise result object
// returns: none

p.when(fulfillPromise, breakPromise, context)
// Creates a promise for the value of an action taken
// on the future value of the promise
// fulfillPromise: Function that takes the value of the
// promise when it completes and is used to act
// on the future value. The result is used as the 
// value of the new promise
// breakPromise: Function that takes the exception
// raised by the promise when it fails and is used
// to act on the failure. The result is used as the
// value of the new promise
// context: Optional Object to use as the 'this' value
// for the fulfillPromise or breakPromise callbacks
// returns: a Promise for the result of actions taken
// in fulfillPromise or breakPromise

p.whenOnly(fulfillPromise, breakPromise, context)
// Enqueues an action to be taken on the future 
// value of the promise
// fulfillPromise: Function that takes the value of the
// promise when it completes and is used to act
// on the future value. 
// breakPromise: Function that takes the exception
// raised by the promise when it fails and is used
// to act on the failure. 
// context: Optional object to use as the 'this' value
// for the fulfillPromise or breakPromise callbacks
// returns: none

p.join(promises)
// Creates a new promise that completes when all
// joined promises have completed
// promises: Parameter array of other promises
// returns: a new Promise


// static/type members

Promise.when(promise, fulfillPromise, breakPromise, context)
// Creates a promise for the value of an action taken
// on the future value of the promise
// promise: The promise on which to act
// fulfillPromise: Function that takes the value of the
// promise when it completes and is used to act
// on the future value. The result is used as the 
// value of the new promise
// breakPromise: Function that takes the exception
// raised by the promise when it fails and is used
// to act on the failure. The result is used as the
// value of the new promise
// context: Optional Object to use as the 'this' value
// for the fulfillPromise or breakPromise callbacks
// returns: a Promise for the result of actions taken
// in fulfillPromise or breakPromise

Promise.whenOnly(promise, fulfillPromise, breakPromise, context)
// Enqueues an action to be taken on the future 
// value of the promise
// promise: The promise on which to act
// fulfillPromise: Function that takes the value of the
// promise when it completes and is used to act
// on the future value. 
// breakPromise: Function that takes the exception
// raised by the promise when it fails and is used
// to act on the failure. 
// context: Optional object to use as the 'this' value
// for the fulfillPromise or breakPromise callbacks
// returns: none

Promise.join(promises)
// Creates a new promise that completes when all
// joined promises have completed
// promises: Parameter array of other promises
// returns: a new Promise

Promise.make(value)
// Makes a promise on a value. If the value is a promise it 
// is returned. If the value is not a promise an immediate
// promise is returned
// value: an Object that may or may not be a promise
// returns: a Promise for the value

Promise.broken(exception)
// Makes a promise that is immediately broken
// exception: The error for the promise
// returns: a broken Promise for the exception

Promise.immediate(value)
// Makes a promise that is immediately fulfilled
// value: The value for the promise
// returns: a fulfilled Promise for the value

Promise.fetch(url, method, username, password, headers, query, body)
// Creates a Promise for a completed XMLHttpRequest for the 
// requested resource
// url: String value for the url
// method: Optional string value for the method. default is "GET"
// username: Optional string value for the username for Basic 
// Authentication. default is 'null'
// password: Optional string value for the password for Basic
// Authentication. default is 'null'
// headers: Optional Object containing name/value pairs for 
// HTTP headers. default is 'null'
// query: Optional Object or String containing name/value pairs
// to be added to the url as a querystring. default is 'null'
// body: Optional Object or String containing the request
// body for the request. A String is sent as-is while an Object
// contains name/value pairs that are url form encoded. 
// default is null
// returns: A Promise for the completed XMLHttpRequest

Promise.json(url, method, username, password, headers, query, body)
// Creates a Promise for a JSON object parsed from the result of an 
// XMLHttpRequest for the requested resource.
// This requires the JSON object which is Native in IE8. If you 
// wish to use this method on a browser that does not have the
// native JSON object, please download www.json.org/json2.js
// url: String value for the url
// method: Optional string value for the method. default is "GET"
// username: Optional string value for the username for Basic 
// Authentication. default is 'null'
// password: Optional string value for the password for Basic
// Authentication. default is 'null'
// headers: Optional Object containing name/value pairs for 
// HTTP headers. default is 'null'
// query: Optional Object or String containing name/value pairs
// to be added to the url as a querystring. default is 'null'
// body: Optional Object or String containing the request
// body for the request. A String is sent as-is while an Object
// contains name/value pairs that are url form encoded. 
// default is null
// returns: A Promise for the JSON value of the response

Promise.jsonp(url, query, callbackArg)
// Uses JSONP to request a JSON resource
// url: String value for the url
// query: Optional Object or String containing name/value pairs
// to be added to the url as a querystring. default is 'null'
// callbackArg: Optional string that specifies the name of
// a querystring argument used to hold the name of
// a callback function. default is "callback"

Promise.js is licensed under the MSR-LA for non-commercial use only. The license is included in license.txt in the zip.

promise.zip

TFS Walkthrough Series: Part 3 - Opening the Source Control Explorer

Ron Buckton — Mon, 07 Sep 2009 08:43:00 GMT

Open Microsoft Visual Studio 2008
Ensure you have an active connection to Team Foundation Server (see Walkthrough: Connecting to Team Foundation Server)
In the "Team Explorer" task pane, expand the Team Project
Double-click on the Source Control folder.

Figure 8 - Source Control Explorer

TFS Walkthrough Series: Part 2 - Viewing Work Items

Ron Buckton — Sun, 06 Sep 2009 12:42:00 GMT

Open Microsoft Visual Studio 2008
Ensure you have an active connection to Team Foundation Server (see Walkthrough: Connecting to Team Foundation Server)
In the "Team Explorer" task pane, expand the Team Project (in this example: TeamProject) to the following folder: TeamProject \ Work Items \ Team Queries

Figure 6 - Work Item Queries
Double-click on a Team Query. This will open the list of work items that match the query.

Figure 7 - Example Work Item Query
Review or make any necessary changes and click Save (from the File menu or the disk icon, or press Ctrl+S) to update the server.

TFS Walkthrough Series: Part 1 - Connecting to Team Foundation Server

Ron Buckton — Sun, 06 Sep 2009 08:14:00 GMT

Open Microsoft Visual Studio 2008
In Visual Studio 2008, click the menu: Tools / Connect to Team Foundation Server
In the "Connect to Team Foundation Server" dialog, click the button: Servers…

Figure 3 - Connecting to a Team Foundation Server
In the "Add/Remove Team Foundation Server" dialog, click the button: Add…

Figure 4 - Managing the list of Team Foundation Servers
In the "Add Team Foundation Server" dialog, enter the server name and click the button: OK

Figure 5 - Adding a Team Foundation Server
In the "Add/Remove Team Foundation Server" dialog, click the button: Close
In the "Connect to Team Foundation Server" dialog, check each of the projects you wish to view and click: OK
The "Team Explorer" tool pane should open for you to browse the Team Project.

Team Foundation Server Walkthrough Series: Introduction

Ron Buckton — Sat, 05 Sep 2009 08:38:53 GMT

The following is a series of walkthroughs for Microsoft Visual Studio 2008 Team Foundation Server. They range from simply making a TFS connection to setting up build configurations and branching scenarios.

Connecting to Team Foundation Server
Viewing Work Items
Opening the Source Control Explorer
Creating Workspaces
Checking in Pending Changes
Creating a DEVELOPMENT branch
Creating a PRODUCTION branch
Forward Integration from MAIN to DEVELOPMENT
Forward Integration from MAIN to PRODUCTION
Reverse Integration from DEVELOPMENT to MAIN
Creating a Build Definition
Queuing a Build
Managing Build Quality
Fixing issues in a PRODUCTION release
Performing a Baseless Merge
Sample Peer Code Review Process using Shelvesets

TFS Quick Tips: #1 Adding a screenshot to a work item

Ron Buckton — Wed, 23 Jul 2008 14:43:10 GMT

The Team Explorer in Visual Studio provides a quick (and not exactly obvious) method for attaching a screenshot or other content to a Work Item.

Screenshots

To quickly add a screenshot do the following:

1. Press PrtScrn or Alt+PrntScrn (Captures only the currently active window)

2. Open a Work Item (Bug, Task, etc) in team explorer

3. Click “File Attachments”

4. Press Ctrl+V (Paste)

A file called “Screenshot.png” is automatically attached to the work item.

Copied Text

To quickly add any copied text as an attachment to a work item do the following:

1. Select the text to copy (or press Ctrl+A to select all text in the active input area like a page or document)

2. Open a Work Item (Bug, Task, etc) in team explorer

3. Click “File Attachments”

4. Press Ctrl+V (Paste)

A file called “PastedText.txt” is automatically attached to the work item.

Copied Files

You can also quickly add a file from your desktop as an attachment using the same steps as above:

1. Select the files to copy

2. Open a Work Item (Bug, Task, etc) in team explorer

3. Click “File Attachments”

4. Press Ctrl+V (Paste)

Each of the files selected is now attached to the work item.

Bonus Tip – Copy and Paste Text from an Alert

If you get an alert in a page like so:

Simply press Ctrl+C (Copy) to copy the contents of the dialog into the clipboard. To paste the text you can just use Ctrl+V:

---------------------------

Windows Internet Explorer

---------------------------

You can copy this

---------------------------

"Wheel of Time" author James Oliver Rigney, Jr. aka "Robert Jordan" passes away at 58

Ron Buckton — Mon, 17 Sep 2007 13:54:28 GMT

From the official website:

New York Times #1 best-selling author Robert Jordan passed away on Sunday September 16th at 2:45 PM EST. His passing was announced by his cousin Wilson on his official blog, hosted here.
[https://www.dragonmount.com/]

I've been reading Robert Jordan's novels for a long time and have all of the available "Wheel of Time" books featured prominently on my bookshelves at home. His fantasy writings were complex and emotional, weaving together the lives of many characters through dark and trying times. He died before completing the 12th and final volume of the "Wheel of Time" series although currently it is believed that enough of the final volume has been penned to be able to complete the series, although the exact time frame for the final volume is still unknown.

The story is on CNN and additional information is available at the following fan sites:

wotmania.com

TarValon.net

Theoryland.com

Visual Studio "Browse with..." multiple browsers

Ron Buckton — Wed, 12 Sep 2007 11:41:14 GMT

Here's a tip if you're doing a lot of cross browser ASP.NET or AJAX development in Visual Studio:

Right click an .aspx file and choose "Browse with..."
If you're like me you've probably added some additional browsers to your "Browse with" list like FireFox, Opera and Safari. If you want to view the page in multiple browsers, CTRL+click each item:
Hit "Browse" and all of the browsers will open for the specified page.
If you want to open multiple browsers every time, click "Set as Default":
Now all of the browsers will open whenever you choose "Browse" from the context menu.

DOM Event inconsistencies between browsers

Ron Buckton — Tue, 11 Sep 2007 16:48:33 GMT

I've been working on some bugs in the Calendar extender from the ASP.NET AJAX Control Toolkit and have been resolving some of the focus/blur events. I've been trying to make the calendar work consistently across all of the browsers and found some frustrating differences in event firing order between the browsers.

Here are a list of some of the DOM events supported by the various browsers I tested:

Table 1 - DOM Events by Browser

Event	DOM Level	IE	FF	OP	SF
DOMActivate	Level 2				*
activate	²	*
DOMFocusIn	Level 2			¹	¹
focusin	²	*
focus	Level 0	*	¹	¹	¹
DOMDeactivate	Level 2
deactivate	²	*
DOMFocusOut	Level 2			¹	¹
focusout	²	*
blur	Level 0	*	¹	¹	¹
mousedown	Level 0	*	*	*	*
mouseup	Level 0	*	*	*	*
click	Level 0	*	*	*	*

IE: Internet Explorer 7.0
FF: Firefox 2.0.0.6
OP: Opera 9.23
SF: Safari 3.03 Beta (Windows)
*: Implemented on any element
1: Implemented only on specific elements
2: IE-only implementation

Internet Explorer uses activate/focusin/focusout instead of DOMActivate/DOMFocusIn/DOMFocusOut for events. Interestingly only IE and Safari support DOMActivate/activate on any element. Another thing I saw was that IE is the only browser which fires focus/blur events for any element. Other browsers can support the focus/blur events on any element that has a tab index however.

The next version of Calendar needs to support the following activation scenarios depending on whether it is also associated with a button:

No Button

Show Popup when textbox receives focus
Show Popup when textbox is clicked
Hide Popup when textbox loses focus
Hide Popup when textbox receives ESC keypress
Hide Popup when a date is selected

Button

Show Popup when the button is clicked
Hide Popup when the button loses focus
Hide Popup when the button receives ESC keypress
Hide Popup when a date is selected

The issue is that when the textbox or button loses focus the popup should hide unless the focus is being directed at the popup itself. The problem is that only IE recognizes a focus event on the popup's DIV tag when the popup is not part of the tab order (and we don't want the popup in the tab order). I was curious the order of DOM events fired in each browser so I wrote a small test page and stepped through for each. The results are as follows:

Table 2 - DOM Event Order by browser

IE	FF	OP	SF
// click on INPUT INPUT: mousedown INPUT: activate INPUT: focusin INPUT: focus INPUT: mouseup INPUT: click // click on DIV DIV: mousedown INPUT: deactivate INPUT: focusout DIV: activate DIV: focusin INPUT: blur DIV: focus DIV: mouseup DIV: click // click away DIV: deactivate DIV: focusout DIV: blur	// click on INPUT INPUT: mousedown INPUT: focus INPUT: mouseup INPUT: click // click on DIV DIV: mousedown INPUT: blur DIV: mouseup DIV: click // click away	// click on INPUT INPUT: focus INPUT: DOMFocusIn INPUT: mousedown INPUT: mouseup INPUT: click // click on DIV INPUT: blur INPUT: DOMFocusOut DIV: mousedown DIV: mouseup DIV: click // click away	// click on INPUT INPUT: mousedown INPUT: focus INPUT: DOMFocusIn INPUT: mouseup INPUT: click INPUT: DOMActivate // click on DIV DIV: mousedown INPUT: blur INPUT: DOMFocusOut DIV: mouseup DIV: click DIV: DOMActivate // click away

Immediately a few things become obvious. First, I obviously cannot rely on focus/blur on the other browsers. IE would allow me to capture focusin on the DIV before the blur fires on the INPUT but that's just IE. Second, on all browsers except Opera the mousedown event of the DIV fires before the blur event of the INPUT. There's no clean sequential way to handle the focus transition in all browsers.

In the current version of Calendar we're making use of a "threading" class I created for the toolkit called DeferredOperation. DeferredOperation wraps a delegate and executes it asynchronously using setTimout. It has some built-in synchronization semantics and was used to handle the focus changes while the popup DIV was part of the tab order (which again, we don't really want). This introduces a subtle delay between activation requests and is problematic on Safari (we had to wait a full second before processing the deferred operation to let safari to catch up).

What I've opted for now is to do the best I can in three out of four of the browsers. I track mousedown/mouseup using a flag and in Internet Explorer, Firefox, and Safari and monitor the flag in the blur event of the textbox. To handle the Opera inconsistency I again use a DeferredOperation to asynchronously handle the blur event which fixes the issue in that browser.

The final issue I discovered was that in all browsers, clicking on the popup causes the textbox (or button) to lose focus which again causes problems with the tab order. On the new Calendar I reset the focus to the textbox (or button) on mouseup on the popup.

Hopefully these changes should make the next toolkit release so keep an eye out for the next update.