erussell/as3-async

Utilities for working with asyncronous code in ActionScript 3.

AS3 Async

The goal of this library is to make writing asynchronous code simple, error free and compact as possible. One of the ways we are setting out to achieve this is to provide a clean and compact implementation of the Promise pattern tailored to take advantage of ActionScript 3.

Deferreds and Promises

The most common way to tackle asynchronous execution in Flash is to use Events; however this results in a lot of boiler plate code (which in turn can make things hard to read) and it's easy to make mistakes (ie: forget to remove Event Listeners).

function execute() : void {
    var service : TwitterService = new TwitterService();
    service.addEventListener(TwitterServiceEvent.COMPLETE, onTimelineFetched);
    service.addEventListener(ErrorEvent.ERROR, onServiceFailed);
    service.fetchTimelineFor("jonnyreeves");
}

private function onTimelineFetched(event : TwitterServiceEvent) : void {
    var service : TwitterService = event.target as TwitterService;
    service.removeEventListener(TwitterServiceEvent.COMPLETE, onTimelineFetched);
    service.removeEventListener(ErrorEvent.ERROR, onServiceFailed);    

    // Notify the rest of the app. that we have some tweets!
    dispatchEvent(new TweetsFetchedEvent(event.userTimeline));
}

private function onServiceFailed(event : ErrorEvent) : void {
    var service : TwitterService = event.target as TwitterService;
    service.removeEventListener(TwitterServiceEvent.COMPLETE, onTimelineFetched);
    service.removeEventListener(ErrorEvent.ERROR, onServiceFailed);    
    trace("Error fetching tweets: " + event.text);
}

Now imagine what the code would look like if we wanted to fetch Tweets for 3 different Twitter Users before we dispatched the TweetsFetchedEvent - things would get pretty messy. This is where Deferreds and Promises come into their element

Here's the same TwitterService, but instead of dispatching Events, it returns a Promise when the user invokes fetchTimelineFor.

function execute() : void {
    var service : DeferredTwitterService = new DeferredTwitterService();
    var promise : Promise = service.fetchTimelineFor("jonnyreeves");

    // Wire the complete and error handlers to the Promise.
    promise
        .completes(onTimelineFetched);
        .fails(onServiceFailed);
}

function onTimelineFetched(userTimeline : TwitterUserTimeline) : void {
    dispatchEvent(new TweetsFetchedEvent(userTimeline));
}

function onServiceFailed(error : ErrorEvent) : void {
    trace("Error fetching tweets: " + error.message);
}

Deferred Services (which return Promises when invoked) have a clean and consistent API; handlers added via completes can accept zero or one argument (the outcome of the Service) and handlers added via fails should expect an Error object. You can chain as many handler functions to completes, or fails as you like - they will be called in the order they are added.

Promises let you forget about race conditions when you code. It doesn't matter if you add your completes and fails handlers after the service has resolved - your handler will still get supplied with the correct outcome.

Chaining Deferred Promises with when

when is a global helper method which can be used to combine one or more Promises into a single Promise - sounds complicated, it's easy (and epic!)

function execute() : void {
    when(fetchTweetsFor("jonnyreeves"), fetchTweetsFor("catburton"), fetchTweetsFor("seanparsons"))
        .completes(onAllTweetsFetched);
}

function fetchTweetsFor(username : String) : Promise {
    return new TwitterService().fetchTimelineFor(username);
}

function onAllTweetsFetched(outcomes : Array) : void {
    trace("Got tweets for " + outcomes.length + " users.");
    for each (var userTimeline : TwitterUserTimeline in outcomes) {
        trace(userTimeline.username + ", tweets: " + userTimeline.tweets[0].message);
    }
}

The Promise returned by when will provide handlers added via complete with an Array of outcomes provided by the supplied Deferreds in the order they were added. Should any of the Promises supplied to when fail, then the Promise returned by when will also fail.