Wrapping it in a promise abstracts away the calls to addEventListener and removeEventListener, and allows us to compose this type of action with other promises. For example, let’s assume we want to insert an <img> element and then wait for it to load. Loading an image can take on the order of seconds depending on the size and location, so waiting for the load needs to be an asynchronous action or it will hang your app.

An HTML <img> will either load successfully and fire the load event, or it might fail to load and fire the error event. We only need to wait for one of these events to fire, so we can use WinJS.Promise.any() and our waitForSingleEventAsync() function above to create a promise that will either be fulfilled with the loaded image element or it will fail with the error “Image load failed”. Additionally, if the image load is already complete, we just return immediately.

Missed Catch

The then() method takes up to 3 parameters – onComplete, onError and onProgress. But what happens if an exception is thrown in the onComplete handler?

Well, as specified in the Common JS Promises/A spec, the return value of then() is a promise in the error state. It does not call the onError handler. To handle an exception thrown by JSON.parse() we need to add an additional then(). The easiest way to do this is to provide a trailing then() that passes null for the onComplete handler.

Not Done Yet

As mentioned before, if an exception is thrown in the onComplete handler of then() the return value is a promise in the error state. But if there is no code to handle this error state then the error will silently go unhandled and your application will just keep running in a potentially invalid state.

The right thing to do is end each promise chain with done() which will re-throw any unhandled errors. If the error is unrecoverable, you can just pass no parameters to the done() method and it will re-throw the exception in the next turn of the event loop, likely forcing your Windows Store app to crash because there is no chance to catch the exception. Otherwise if your application can continue running after encountering the error, its in your best interest to at least log the error in order to make debugging easier. Other good options would be to assert, display an error message to the user and/or try to perform the action again. Like the previous example, the easiest way to do this is to provide a trailing done() that passes null for the onComplete handler.

Indisposed

In asynchronous programming, the state of the world can change right out from underneath you. An easy mistake to make is to tear down and dispose an object but to leave a promise inside it running. For example, let’s assume we want to show a Message each time the user performs an action. Additionally, we want to show just one message at time.

If the user is quick enough, he/she might perform two actions in quick succession:

1. User performs Action A
2. Start showing Message A
3. User performs Action B
4. Dispose Message A (we only want to show one message at a time)
5. Start showing Message B

If step 4 causes Message A to be disposed before the animation has finished, it will cause a null reference exception when attempting to access this._element.dispatchEvent() (line 17) after the animation promise completes in showAsync() and calls fireEvent().

There are two potential ways to avoid this issue. The first is to store any promises in a member variable and then call cancel() on each one in dispose(). However, it turns out that WinJS animations support cancellation but swallow the cancellation and complete the animation promise, which means our then() following the animation still runs and we still get a null reference exception in the example above.

The alternative is to use a disposed flag inside your class and check the flag before proceeding. In this case, I’m returning the promise to the caller, so I cancel the promise if the class has been disposed the same way the cancel() method works – by returning a promise in the error state with the error message “Canceled”.