Dear reader, how are you today? Everything’s fine? Got half an hour to lose? Good! Then you won’t mind me taking you on one of those wild rides in Browser-Land, would you? See, I was working on this CSS ajax transport for jQuery ajaxHooks and something not so surprising happened: I lost a day of my life trying to make sense of the nonsensical.

the problem

Say we want to load a CSS dynamically and notify a callback if and when the stylesheet has actually been loaded. Since you, my dear reader, are perfectly fluent in dynamic script loading and script tag injection, the following snippet immediately popped into your brilliant mind:

var // create a link element
    link = document.createElement( "link" );
// initialize its properties
link.rel = "stylesheet";
link.type = "text/css";
link.href = "http://my.domain/then/my/path/to/my/stylesheet.css";
// attach its onload handler
link.onload = function() {
    console.log( "OMG! LOADED!" );
};
// load
document.getElementsByTagName( "head" )[ 0 ].appendChild( link );

And sure enough, it works fine… in IE and Opera. See, onload is never triggered for link elements in Webkit and Firefox (not the usual culprits, so let’s call this a rare, but still unpleasant, surprise).

But don’t sweat it, my dear reader! That’s not really the problem, because the solution is known, was experimented with in dominoes, was refined and adapted by others as new versions of guilty browsers emerged and, finally, made its way into the awesome yepnope! And the solution is… drum rolls… polling (together with insane tests that will break when browser devs move a single statement in their code base):

var cssPollingId = 0,
    cssPolled = {};

function cssGlobalPoller() {
    var id, sheet;
    for( id in cssPolled ) {
        sheet = cssPolled[ id ].sheet;
        try {
            if ( sheet && !sheet.cssRules /* <= webkit */ || sheet.cssRules.length != null /* <= firefox */ ) {
                cssPolled[ id ].onload();
            }
        } catch( e ) {
            if ( ( e.code === 1e3 ) || ( e.message === "security" || e.message === "denied" ) ) {
                cssPolled[ id ].onload();
            }
        }
    }
}

The snippet above was extracted (nearly) verbatim from the CSS transport in ajaxHooks. When you know you cannot use onload (please take mental note of the seven words you just read), do something like this:

cssPolled[ cssPollingId++ ] = link;
setInterval( cssGlobalPoller, 10 );

Of course, I left aside the logic needed in order not to create a new interval for every link and the logic to clear this interval, but you get the general idea.

If you don’t understand anything about the code in cssGlobalPoller, don’t worry, it’s the result of some trial an error experiments that will work for same-domain and cross-domain links alike, in Webkit and Firefox. Just accept it’ll end up calling onload on the polled elements after some time. It’s horrible, yes, it’s so implementation-dependant it’ll require continuous and painful maintenance, sure, but it gets the job done.

As a side-note, the most observant of you will wonder why we bother with same-domain links (why not use the XMLHTTPRequest object and then create a style element?): that’s because of relative URLs in stylesheets. Unless you want to embed a css parser client-side to search and replace those damn URLs, you’re better off always using a link element to load a stylesheet dynamically.

Anyway…

why it is problem

Well, it’s all in the seven words I told you to take mental note of earlier: you must only use this polling technique “when you know you cannot use onload”. Using them both, in parallel, is bad, wrong, verbotten, booooo!

Why, you ask, dear reader?

First, it is not ideal to use polling on browsers that do not require it. Performance-wise that is. If a browser supports onload on a link element, then let’s use it and avoid the overhead. Old IEs sure don’t need any more weight on their weak shoulders.

But that’s a moot point, the real reason is pretty simple (and a bit frightening): just imagine the extra logic required to make sure cssGlobalPoller doesn’t trigger false positives in IE and Opera. Believe me, I tried and it wasn’t pretty (remember we have to deal with same-domain and cross-domain requests at the same time and they sure as hell don’t behave the same because of the usual security restrictions: different exceptions being the tip of the iceberg).

Now, really, just try and imagine this for a second.

However, if we use polling in Webkit and Firefox, and only in them, then we only have to maintain cssGlobalPoller when one of these two releases a new version (that is far too often already). Now add IE and Opera to the mix and maintenance becomes a job for Jim Phelps and his IMF team, provided it’s even possible (pun pun) to find a global logic that will work for those four together (quite the leap of faith).

Even if it proved possible, is it even desirable? Would you like to maintain something like this?

OK, so now that we’re all scared to death, how about we try and solve the problem?

“not a solution” 1: browser sniffing

How about we check the User Agent string (or use jQuery.browser) to deal with the problem?

Yeah, right: do you also wanna maintain this part of the code if and when Webkit and/or Firefox finally support onload? I think I’ll pass. Not that I’m religiously against browser sniffing (unless I’m working in jQuery itself) but please don’t tell anyone. When it’s unavoidable, it’s unavoidable but, surely, there must be some proper means to feature-test this thing, right? RIGHT?

“not a solution” 2: feature detection

How about we create a link and look if it has an onload property?

var link = document.createElement( "link" );
console.log( "onload" in link );

Wait, this is true in Webkit. Arf!

OK, nevermind, let’s control the event is supported by relying on the attribute being transformed into a function then:

var link = document.createElement( "link" );
link.setAttribute( "onload", "return false;" );
console.log( jQuery.isFunction( link.onload ) );

No luck, true in both Firefox and Webkit (gotta love false positives). Maybe setting the property, not the attribute, would do the trick?

var link = document.createElement( "link" );
link.onload = "return false;";
console.log( jQuery.isFunction( link.onload ) );

• false in Webkit: checked,
• false in Firefox: checked,
• true in Opera: checked (OMG looking good),
• false in IE9 (sob)

OK, so this is definitely not looking good:

-         "onload" in link      link.onload = "return false;"

IE              true                      false
Opera           true                      true
Firefox         false                     false
Webkit          true                      false

Even if we could find a proper logic to use the results in these two columns (I’ll leave this to you as an exercise — no need to thank me), how solid would the feature detection actually be? How likely is it that a specific version of one of these browsers will have a different behaviour (hint: highly)? What about a nasty mobile browser that wouldn’t have the onload property set on a freshly created link element but would support the event nonetheless?

“not a solution” 3: doing it for real

This is the kind of situation when one seriously questions if making a living in web development is really worth it.

So how could we determine if the onload event is triggered when a stylesheet is loaded? Hang on a second… by actually loading a stylesheet, right?

var link = document.createElement( "link" );
link.rel = "stylesheet";
link.type = "text/css";
link.href = "http://my.domain/then/my/path/to/my/test/stylesheet.css";
link.onload = function() {
    console.log( "OMG! onload is supported!" );
};
document.getElementsByTagName( "head" )[ 0 ].appendChild( link );

That’s all fine and dandy but it’s not a solution at all:

• What if the internet connection is severed just when you do the request and only when you do it?
• Would you download a js library that would ask you to put an empty stylesheet someplace on your web server just for feature testing? Or should it be only usable from a CDN?
• If not, how would the lib’s code determine the URL of said stylesheet?
• Also, is it reasonable to take up an HTTP connection at start-up? Do you really want Steve Souders to kill a kitten?
• And, see, if onload is not supported, how are we supposed to get notified in the first place?
• Even if we could get passed those issues: how do we handle the situation where people call the lib to load a stylesheet but the feature testing request is not done yet?

Fear not, my dear reader, kittens are safe! There is a way (and I take donations in any currency)!

the solution part 1: the stylesheet

Let’s first tackle the problem of having to make a network request for an external stylesheet. It seems a bit silly, really, given that the stylesheet is, actually, empty. I wish there was a way to have data in the URL itself… hang on a second…

Enter data URI:

var link = document.createElement( "link" );
link.rel = "stylesheet";
link.type = "text/css";
link.href = "data:text/css,";
link.onload = function() {
    console.log( "OMG! onload is supported and I didn't have to request the interweb to know!" );
};
document.getElementsByTagName( "head" )[ 0 ].appendChild( link );

But wait, you tell me! Older IEs do NOT support data URI!

True enough, however, IE being IE, it won’t prevent it from triggering the onload event. It seems IE will ignore the unknown scheme and just consider the link loaded. Normally, I would cringe at the very idea but, in all honesty, I’m quite glad IE is IE in that instance (and I truly hope it doesn’t mean IE will trigger onload for non-existing stylesheets — please don’t spoil my fun right now).

Beside, if you’re feeling adventurous, you can still use “about:blank” (and get a “wrong content type” warning in the console of any decent browser).

the solution part 2: no onload support

With that out of the way, how do we get notified when there is no onload support?

Our stylesheet now being local, it would make sense for the onload event to be triggered immediately. So we don’t really need to be notified if onload is not supported: as long as we didn’t get notified onload was supported, then we know it isn’t (simple, right?):

var onloadIsSupported = false,
    head = document.getElementsByTagName( "head" )[ 0 ],
    link = document.createElement( "link" );
link.rel = "stylesheet";
link.type = "text/css";
link.href = "data:text/css,";
link.onload = function() {
    onloadIsSupported = true;
};
head.appendChild( link );
// let's clean up our mess
head.removeChild( link );
link.onload = null;

We put the element in the dom, onload is immediately invoked if supported, we then remove the element, end of the story. Our feature test is now synchronous and all our problems are solved, right? RIGHT?

Wrong. Fetching from a data URI may very well be immediate (I have no proof but I love to make things up), yet you still need to give a tiny little bit of time for the onload event to get triggered:

var onloadIsSupported = false,
    head = document.getElementsByTagName( "head" )[ 0 ],
    link = document.createElement( "link" );
link.rel = "stylesheet";
link.type = "text/css";
link.href = "data:text/css,";
link.onload = function() {
    onloadIsSupported = true;
};
head.appendChild( link );
// just let it breathe a little
setTimeout( function() {
    head.removeChild( link );
    link.onload = null;
}, 0 /* see: a really tiny little bit of time */ );

Now, it works. But if a third-party tries and uses the library to load a stylesheet in the short time it takes for the onload event to be triggered, onloadIsSupported is falsy and polling will be used even in IE and Opera (meaning KABOOM!).

the solution part 3: gotta love deferreds

Since ajaxHooks is a jQuery plugin, we have a fantastic tool at our disposal when it comes to asychronous management: Deferreds.

When you ask for a stylesheet to be loaded, you do expect the operation to run asynchronously (that’s why you provide a callback, right?). So it makes absolutely no difference to wait for onloadIsSupported to be determined before trying to actually load the stylesheet (it’s just a “tiny little bit” slower). Since we don’t know how many stylesheets may be requested in the mean time, our best bet is to use a Deferred object to be notified when feature detection is done with (and get the outcome):

var // create our feature detection runner (a Deferred)
    onloadIsSupportedTest = jQuery.Deferred(function( defer ) {
        var head = document.getElementsByTagName( "head" )[ 0 ],
            link = document.createElement( "link" );
        link.rel = "stylesheet";
        link.type = "text/css";
        link.href = "data:text/css,";
        link.onload = function() {
            // onload is supported, resolve the deferred with "true"
            defer.resolve( true );
        };
        head.appendChild( link );
        setTimeout( function() {
            head.removeChild( link );
            link.onload = null;
            // onload is NOT supported, resolve the deferred with "false"
            // (ignored if the deferred was already resolved so 100% safe)
            defer.resolve( false );
        }, 0 );
    });

// public function to load a stylesheet
function loadStylesheet( url, callback ) {
    // wait for the feature detection to finish
    onloadIsSupportedTest.done(function( onloadIsSupported ) {
        // given the result of feature detection
        if ( onloadIsSupported ) {
            // use onload
        } else {
            // use polling
        }
    }); 
}

Since a Deferred will stay resolved even a billion years after it was first resolved (provided you have a very good battery) and since it will just store callbacks if it is not resolved yet (to call them later), then this approach will work whether you call loadStylesheet before, during or after feature detection is performed. We could even wait for the first call to loadStylesheet to actually create the Deferred and perform the associated feature detection (effectively making the cost of feature testing at start-up pretty much a non-issue but that’s another story).

the solution: let’s recapitulate

• we use a data URI to feature test if onload is supported on link elements,
• since onload is triggered asynchronously, we embed the feature detection in a Deferred,
• a Deferred we can then query to know whether or not onload is supported on link elements.

No browser-sniffing and no weak feature detection (understand feature inference).

Now, the real weak spot in the whole code is the logic in the polling callback but that’s something I can (or rather have to) live with. Just waiting to see how many mobile browsers will need some lovin' (or rather hatin') in there.

conclusion

Wasn’t this as wild a ride as I promised, dear reader? No need to thank me, really, just get one or two Alka-Seltzers and make my shares in the pharmaceutical industry go through the roof! Thank you! If your head doesn’t hurt enough yet though, you can still have a look at the complete CSS transport: there are even more insane tricks to be found in those few lines of code.

Anyway, I wonder if the whole approach (feature testing using a data URI, then wait for it to finish using a Deferred) may (or will) be used elsewhere. Honestly, I hope not because if it continues like this, I’ll have to sue browser developpers and have them pay for all those hours I pass trying to clean up their mess.

And God! Is it a mess, dear reader! So not to worry, there are probably a lot of posts to come, lurking out there, in Browser-Land, eagerly waiting to be written and read!

Sometimes, I’m very pessimistic when it comes to the future of the web. Sure, new technologies arise practically daily now, but it seems to me that standard bodies are so entrenched in the past, they will end up shooting us, web developpers, in the foot. It’s even more saddening when you realize that some of our peers actually contribute to the problem, albeit with the best of intentions.

Nowadays, so-called web “ninjas” are all about knowing the intricaties of such or such part of the standard and circumvent associated limitations. They are revered for it, actually, and for good reasons given how frustrating and mentally demanding this occupation can be. However, it seems to me this very mind-set is actually undermining the general effort to build new and better tools: sometimes we just can’t let go and we keep on trying to drive a nail with a screwdriver.

In effect, I am one of those “ninjas” so, please, don’t take this as some kind of personal vendetta ‘cause it’s not. It’s just the old grunt in me wondering when the hell we, as a community, will embrace change and let go of the past (provided we make it possible to emulate the future using the past — polyfills FTW).

the screwdriver

What is this screwdriver I’m talking about? A script tag. What’s the nail? Loading a script.

Come on, you say, you insert a script tag and you load a script, it makes perfect sense. We always did it that way so why would we change anything?

Problem is a script tag doesn’t just load a script, it loads and then immediately runs the script (I know you have ways to prevent that by removing the script element from the dom at the right moment but bare with me for a minute). So when you want to load several scripts in parallel then control in which order they are executed, you basically have to jump through hoops (see, it wasn’t that big of a minute)… or petition standard bodies to add new attributes or to amend existing behaviour, which is what’s going on at the whatwg wiki right now.

It’s proposal 2 of this very page I’d like to discuss (I won’t get into proposal 1 which is, quite franckly, far worse). So just go and read it.

Back so soon? No, really go and read it. It’s very well written and precise to boot!

The proposed solution is quite smart when you think about it: let’s make script elements behave like img elements. So, as soon as the src property is set, start and fetch the resource… but only display/execute said resouce if and when the element is added to the DOM.

Indeed, Kyle Simpson’s solution is insanely smart but the only problem is that it’s actually pushing for a fancier screwdriver, not a hammer.

See, an image has to be rendered somewhere in the page (that is to say, in the dom). A script does not. Dynamically inserted scripts do not support document.write() so their “position” in the dom is irrelevant when it comes to execution. In fact, the very thought of a “position in the dom” for a dynamically loaded script is kinda weird when you think about it. And, please, don’t get me started on trying and adding support for document.write() in this context: document.write() needs to die and seeing it in so many google libs makes me wanna slap the devs behind across the face (woops, so much for job opportunities I guess).

So let’s get this straight regarding Kyle’s proposal:

• create a script element,
• listen to a specific event,
• set the src property,
• when the event is triggered, script has been (pre)loaded,
• listen to another event (or the same event but triggered with different parameters),
• add the element to the DOM,
• when the event is triggered, script has been executed,
• remove the element from the DOM because you don’t need it anymore and you don’t wanna pollute your dom.
• (error handling is fuzzy because error handling has always been fuzzy when using script tags, so I didn’t get into it here)

If this is not driving a nail with a screwdriver, I don’t know what is but, since we’ve always used script tag injection to load and execute javascript before, since some of us got insanely good at jumping through the many hoops we have there, then we get stuck with it forever. The whole approach is strikingly flawed and short-sighted in my humble opinion.

the nail

Let’s break script execution into the three steps that are actually needed to achieve it:

1. fetch the resource (so far it’s just text),
2. parse the text (we then have an executable script),
3. execute the script (the script is now “live” in the javascript VM).

Step 2 and 3 are separated to remind us of the kind of control we would need in a perfect world from a performance point of view (see, parsing is not “free”, especially for big files). However, for the sake of this discussion, I’ll merge them together as “execute the script”, but keep in mind this step is actually a two-parter, this’ll be of importance when we try and design our hammer.

Anyway, that’s the nail we have to drive.

the hammer

OK, so first we need to ask for the resource, then, once the resource has been fetched, we need to try and execute it. Seems like a perfect use-case for a function that accepts a URL and a callback:

loadScript( url, function( scriptObject ) {
    returnedValue = scriptObject.run();
});

I just looked at the nail and built a tool for it. However it’s still not quite right.

First, the resource may very well not be fetchable: it may not exist anymore (404) or the parameters we gave in the query string may be incorrect (500) or any other reason really. So let’s handle errors (I’ll use the nodejs approach here):

loadScript( url, function( error, scriptObject ) {
    if ( !error ) {
        returnedValue = scriptObject.run();
    }
});

Another problem is that run is not just executing the script, remember? We also have to parse it first. So, while the javascript VM is single-threaded and it seems to make sense to run the script synchronously, we have a small window of opportunity for some non-blocking behaviour: the script can be parsed outside of the main thread, so our run method could benefit from being asynchronous:

loadScript( url, function( error, scriptObject ) {
    if ( !error ) {
        scriptObject.run(function( error, returnedValue ) {
            if ( error ) {
                console.log( "An error occured " + error );
            } else {
                console.log( "Returned value is " + returnedValue );
            }
        });
    }
});

No dom injection, no script element, no non-sense.

enhancing the hammer

One thing I’m toying with these days is script sandboxing (as emphasized by my usejs experiment). How about we enhance the run method with the possibility to provide the global object in the context of which the script is to be executed?

loadScript( url, function( error, scriptObject ) {
    if ( !error ) {
        scriptObject.run(function( error, returnedValue ) {
            if ( error ) {
                console.log( "An error occured " + error );
            } else {
                console.log( "Returned value is " + returnedValue );
            }
        }, myGlobalObject );
    }
});

Now, it’s possible to sandbox jsonp requests pretty easily in case we’re doubtful about the intentions of the site we pull data from:

loadScript( "http://untrusted.site.com/path/to/data?callback=callback", function( error, scriptObject ) {
    if ( !error ) {
        scriptObject.run(function( error, returnedValue ) {
            if ( error ) {
                console.log( "An error occured " + error );
            } else {
                console.log( "Returned value is " + returnedValue );
            }
        }, {
            callback: function( data ) {
                return data;
            }
        });
    }
});

Now, we can sandbox a script and, also, leverage browser caching for jsonp requests (the callback parameter is always the same). It was easy to do so because we have a hammer and adding better, more advanced, ways to drive the nail is pretty straight-forward when the base tool is fit for the task at hand.

Which brings us to…

why the hammer is better than the screwdriver

Let’s see:

• it’s very easy to write and read: it actually does what you read and you don’t need to have a phd in decyphering standards to make sense of the code (it is a hammer driving a nail, as simple as that),
• we get a return value which is a huge bonus,
• everything it does is already implemented in the browsers internally, except, today, we resort to dom manipulation acrobatics to access these functionalities: the hammer can only be more performant,
• talking about performances, the run method being asynchronous, parsing won’t block the main thread (but I hope that’s already the case with script tag injection),
• it’s easy enough to write a polyfill for this: just look if loadScript is defined and, if not, code it the old clunky way,
• we can now run a script several times without refetching it, effectively decoupling loading and execution,
• no access to the script’s code is required which is in sync with current browser security policies (not being authorized to inspect/modify script source fetched from another domain),
• there is no dom dependency, so it can be used in any javascript environment: it’s a new javascript built-in, as opposed to yet another browser trick,
• if we add the context argument (and why wouldn’t we?) on the run method, then we have the main building block for a nodejs-like require functionality in pure javascript, even server-side (again, no dom dependency).

in conclusion

Let go of the past. Let’s stop being damn stubborn specialists, let’s take a step back and look at what we’re actually trying to achieve. Let’s stop “enhancing” (understand complexify) failing standards: we’re limiting ourselves and making it impossible to go further and think two steps ahead.

For crying out loud, let’s be smart about what we’re doing and then, maybe, we won’t try to amend the wrong standard (dom) and start working for the greater good (ecmascript).

If we only have screwdrivers at our disposal to drive nails then we must build hammers. It’s not a question of opinion, it’s not a question of taste, it’s a question of common sense.

There has been a lot of talk lately about how Deferreds should be implemented in jQuery and the strong belief they should be implemented following Kris Zyp’s Promise/A proposal.

I’m inbetween trains at the moment (Paris –> Brussels –> London –> Brussels) so comparing point to point two very similar APIs (Promise/A and, well, let’s dub current jQuery’s take on it Promise/J) is not something I intended to do right now. But time is of the essence, right?

Since I don’t have that much essence in store, I’ll make some general observation and then present what I think is a reasonably advanced use case. That way, everyone will be able to see where those two APIs differ and what benefits each may have.

It will also serve as some kind of pre-documentation paper that some people in the team may find useful and plugin developpers may be interested in.

from one to the other

One thing I always love to do when comparing APIs that are close enough (provided they are not some monstruous beasts the size of, say, DirectX and OpenGL), is to try and write one into the other. So, how do you pass from a Promise/A to a Promise/J:

function toPromiseJ( promiseA ) {

    function flattened( isSuccess , args ) {
        var i,
            length,
            elem,
            type;

        for ( i = 0 , length = args.length ; i < length ; i++ ) {
            elem = args[ i ];
            type = jQuery.type( elem );
            if ( type === "array" ) {
                flattened( isSuccess , elem );
            } else if ( type === "function" ) {
                promiseA.then( isSuccess ? elem : null , isSuccess ? null : elem );
            }
        }
    }

    return jQuery.extend( {} , promiseA , {
        then: function() {
            flattened( true , arguments );
            return this;
        },
        fail: function() {
            flattened( false , arguments );
            return this;
        }
    } );
}

This adapter makes it clear how Promise/J handles the parameters of then and fail: it flattens the arguments array and filters out anything that is not a function (it can be a good idea to keep that in mind for some points in the use case to come).

Note also that this is not a perfect adapter, namely because Promise/A does not specify if a fullfilled (or failed) promise executes the callbacks right away whereas Promise/J ensures a specific order for consistency. Calls to then and fail are “atomic” in the sense that all the callbacks provided in a single call will be “pushed” before being executed no matter the promise’s state. This has some nice properties, especially when a callback attaches another callback to the promise. For instance, the following code:

var str = "";

promiseJ.then( function() {
    promiseJ.then( function() {
        alert( str );
    } );
    str += "A";
},
function() {
    str += "B";
} );

will alert “AB” whether the promise is already fullfilled or whether it gets fullfilled in the future. Simulating this with Promise/A is nearly impossible unless you rely on some setTimeout( func , 0 ) to execute the callbacks (and I’m not really sure if the actual behaviour of such a hack can be made consistent across browsers).

That being said, let’s see how we can pass from a Promise/J to a Promise/A:

function toPromiseA( promiseJ ) {
    return jQuery.extend( {} , promiseJ , {
        then: function( fullfilledHandler , errorHandler ) {
            promiseJ.then( fullfilledHandler ).fail( errorHandler );
        }
    } );
}

This adapter is clearly more compact but don’t be fooled: it doesn’t say anything about the APIs other than the fact Promise/J seems more expressive than Promise/A, that’s all. Beside, then now accepts arrays which, while being compatible, is not strictly compliant with Promise/A. The progressHandler has been left out intentionally but if it proved useful, it wouldn’t be a real hassle to add a progress method to Promise/J (though how these callbacks are to be called, with what value and how often is something Promise/A keeps in the dark — Should at least the value provided to the callbacks be specified? Maybe a percentage? A float? A status text? Really, it’s a tricky subject where Promise/A doesn’t take side and rightfully so given how implementation sensitive it could get).

add promises to an existing plugin

Now we start our use case. I decided to take the perspective of a plugin developer because, let’s face it, if we’re going to see how easy/uneasy such or such API may be, then we’d better stay away from “Hello World” examples. It’s clear the two pieces of code below are too close to one another to be any indicator:

promiseA.then( successCallback, errorCallback );
// vs
promiseJ.then( successCallback ).fail( errorCallback );

If it was up to that small difference, then Promise/A it would be if only for immediate and free-of-charge interoparability with the libraries already implementing it.

Anyway, let’s go on with our use case. Anything based around the concept of two possible outcomes making use of an options map will do just fine. So let’s consider our wonderful and minimal $.confirm() plugin. This imaginary plugin was written before 1.5 and makes use of options to specify callbacks. So you would use it like this:

jQuery.confirm( {
    message: "Are you sure?",
    ok: function() { /* ok case */ },
    cancel: function() { /* cancel case */ }
} );

Pre-1.5, a call to $.confirm() didn’t return anything. But since Neal Bamn, the author, really liked the changes in $.ajax() — yeah, I know, dream on! —, he decided it would be cool to use promises and add a bit of flexibility in there:

var myConfirm = jQuery.confirm( {
    message: "Are you sure?",
    ok: function() { /* ok case #1 */ },
    cancel: function() { /* cancel case #1 */ }
} );

// then, later
myConfirm.ok( function() { /* ok case #N */ } );
myConfirm.cancel( function() { /* cancel case #N */ } );

// or even
jQuery.when( jQuery.confirm( "Are you sure?" ) ).then( func );

How would he do it using Promise/A?

jQuery.confirm = function( options ) {
    var deferredA = jQuery.DeferredA(),
        promiseA = deferred.getPromise(); // Inventing here since Promise/A doesn't specify this

    // Do what's needed to show the confirm dialog

    return jQuery.extend( {

        ok: function( callback ) {
            promiseA.then( callback );
            return this;
        },
        cancel: function( callback ) {
            promiseA.then( null , callback );
            return this;
        }

    } , promiseA ).then( options.ok , options.cancel );
};

Promise/A doesn’t specify how the promise is retrieved. Promise/J, on the other hand, does. Any object that can be observed using a promise must provide a “promise()” method that returns, you guessed it, a promise (this includes promises themselves, of course). For instance, jQuery.when uses the promise method as a mean to determine if its argument is observable or if a new Deferred must be created and immediately resolved with said argument. The promise method goes along the following lines:

promise: function( object ) {
    object = object || {};
    // Attach "immutable" methods
    // (then, fail, isResolved and isRejected)
    return object;
}

Promise/J takes an Aspect Oriented approach here in the sense you can attach the promise “behaviour” to any existing object. All the methods that do not return a specified value (here, a boolean) must return the object they are attached to (in short, return this). There is no way the promise method can be implemented using a prototype based approach and this is a very intentional design decision. Also of interest, the jQuery.Deferred object actually is a promise.

Note that, as of today, the promise method of a Promise/J is wrong in the sense that it ignores the argument and always returns itself. Expect this to be fixed shortly.

That being said, how would we implement these plugin enhancements with Promise/J:

jQuery.confirm = function( options ) {
    var deferredJ = jQuery.DeferredJ();

    // Do what's needed to show the confirm dialog

    return deferredJ.promise( {

        ok: deferredJ.then,
        cancel: deferredJ.fail

    } ).ok( options.ok ).cancel( options.cancel );
};

There are several key differences to note between the two implementations:

1. Even if the Promise/A implementation made it possible to detach methods and attach them back to another object we would still need those anonymous functions. It’s due to the fact that, in Promise/A, then accepts an errorHandler as its second argument and it’s very doubtful that a user would expect the second argument of ok to be a cancel callback. If anything, he’d probably expect it to be considered as another ok callback.

2. In the Promise/J implementation, new “aliases” are attached to an object on which the promise aspect is added. Here, ok and cancel are the exact same functions as then and fail respectively (think ===): since the most likely use case is one callback given to any of this methods at a time, then and fail will never recurse internally so what we have here is simpler but, also, faster code. As a nice side-effect, we can use ok and cancel with no overhead which makes the code somehow more readable.

3. The return statement in the Promise/J version is a bit clearer — jQuery.extend() doesn’t tick as much as deferred.promise() —, but nothing prevents us from adding the promise helper method to the Promise/A version, so don’t be fooled (same goes for using the deferred directly instead of the promises).

4. Since Promise/J then and fail methods do flatten their arguments and accept arrays, the ok and cancel options can now be arrays of callbacks, for free.

While we have a very simple case here, we could easily extend the concept to some wizard panel with a series of ok/cancel decisions where several promises are to be chained. It’s a good exercice to see how much each solution would grow in size and complexity.

// Promise/A
jQuery.twoPanelsA = function( options ) {
    var deferredMain = jQuery.Deferred(),
        deferredFirst = jQuery.Deferred(),
        promiseMain = deferredMain.getPromise(),
        promiseFirst = deferredFirst.getPromise();

    // Do what's needed to show the wizard

    return jQuery.extend( {} , promiseMain , {

        okFirst: function( callback ) {
            promiseFirst.then( callback );
            return this;
        },
        cancelFirst: function( callback ) {
            promiseFirst.then( null , callback );
            return this;
        }
        ok: function( callback ) {
            promiseMain.then( callback );
            return this;
        },
        cancel: function( callback ) {
            promiseMain.then( null , callback );
            return this;
        }

    } ).then( options.ok , options.cancel )
       .then( options.okFirst , options.cancelFirst )
       .then( null , deferredMain.failed /* <= name not specified in Promise/A */ );
};

// Promise/J
jQuery.twoPanelsJ = function( options ) {
    var deferredMain = jQuery.Deferred(),
        deferredFirst = jQuery.Deferred();

    // Do what's needed to show the wizard

    return deferredMain.promise( {

        okFirst: deferredFirst.then,
        cancelFirst: deferredFirst.fail,
        ok: deferredMain.then,
        cancel: deferredMain.fail

    } ).ok( options.ok )
       .cancel( options.cancel )
       .okFirst( options.okFirst )
       .cancelFirst( options.cancelFirst , deferredMain.reject );
};

If you generalize this to all the plugins that would be prone to evolve to promise, Promise/A forces developers into an enormous amount of tedious anonymous functions wrappers. The downside of Promise/J is one more function call to attach options callbacks. On the other hand, since calling ok, cancel, okFirst or cancelFirst comes with no performance penalty, it gets tempting to generalize the code (jQuery.each is used here, but it’s obvious a for in loop would be faster and, thus, preferable):

jQuery.each( "ok cancel okFirst cancelFirst".split( " " ) , function( _ , name ) {
    promise[ name ]( options[ name ] );
} );

You get the idea.

Of course, another approach would be to return one promise by panel and be a bit more “organized” but that would imply an intermediate object that provides methods to get access to said promises, actually breaking chainability (at least not without some convoluted code). It seems reasonable plugin developers will prefer to provide methods named after existing options, especially for plugins that already return an object (that was the case for jQuery.ajax for instance).

using the plugin

But let’s go back to Neal’s awesomely awesome 1.5 compliant new version of a plugin that’s just been uploaded (see what happens when I keep you occupied?). Corin Volser, a jQuery addict, grabs it as soon as it’s released. But it will come as no surprise to you that Corin’s boss is a clueless naysayer of massive proportions: it’s 7pm and he wants a journal of each users ok/cancel “clicks” now.

“This pug'in you talk about is no good to me if I don’t have that excel report on my desk by tomorrow morning!” he barks.

Worse of all, the boss demands an alert to pop out and the confirm window not to close if and when a user cancels “too often”. So logging on cancel must take place before any other cancel callback (I’ll spare you the spaghetti code involved backstage to prevent the confirm to close while the plugin does not support it).

How would Corin do this if Neal’s plugin was based on Promise/A?

jQuery.loggedConfirm = function( options ) {
    var originalCancel = options.cancel;

    return jQuery.confirm( jQuery.extend( options , {
        cancel: function() {
            logger.cancel( options );
            if ( jQuery.isFunction( originalCancel ) ) {
                originalCancel.apply( this , arguments );
            }
        }
    } ) ).ok( function() {
        logger.ok( options );
    } );
};

Cumbersome and confusing: an intermediate variable, a jQuery.isFunction test, quite heavy on the plumbery. Let’s see if the Promise/J version is any better:

jQuery.loggedConfirm = function( options ) {

    return jQuery.confirm( jQuery.extend( options , {
        ok: [ function() { logger.logOK( options ); }, options.ok ],
        cancel: [ function() { logger.logCancel( options ); }, options.cancel ]
    } ) );
};

Still ugly, really, but at least the options testing is delegated to then and fail, so we lose the variable and now all log callbacks only contain a single statement which makes it a little more bearable (and more tempting to add the ok logger in the options for code consistency).

Damn these bosses, their Excels and their silly “special cases”.

best of both worlds?

Maybe it’s time for us to make a little pause and summarize what we saw so far:

1. There are a lot of things in Promise/A that are left for implementors to decide. While it makes sense for some parts (like progress handlers which may, indeed, not even have their place in the spec at all), other parts would benefit from some clarifications and constraints (like callbacks execution order and mandatory “helper” methods).

2. The code in the use case seemed generally cleaner using Promise/J than using Promise/A, but a lot is actually due a serious lack of specified helper methods on Promise/A’s end.

3. However, the real issue is the fact Promise/A’s then method mixes success and error callbacks. While it makes sense in the simplest example, it comes at great cost (repetitive anonymous functions wrappers) when extending any legacy code which requires some flexibility in how things are named and published. The key point here is that Promise/A’s then method doesn’t really make much sense when not attached to the promise itself which makes it a poor candidate for Aspect Oriented programming. The Promise/J approach that clearly separates the two handlers types manages to limit the number of function redirections drastically (down to zero actually) while also enabling more elegant ways to deal with callbacks lists.

Now there’s been a lot of discussion about an intermediate solution that would solve some of the issues with Promise/A. This new interface (let’s call it Promise/A+) is actually the exact output of the Promise/J to Promise/A adapter we saw earlier:

then: function( arrayOfSuccessHandlers , arrayOfErrorHandlers ),
fail: function( errorHandler1, errorHandler2, ... )

The problem with Promise/A+ is that it doesn’t remove the mix of success and error handlers that de-facto precludes an Aspect Oriented approach which means the army of anonymous functions will still camp in your source-yard. Even worse, the Promise/A+ API is asymetrical with then and fail no longer having the same signature which is just plain counter-intuitive.

j@ubourg’s opinion

Well, the real issue that has been debated to death is “interoperability”. I really think a lot of people are confused about what it actually means. If interoperability meant “the same interface everywhere” then I think we would all code in a single, universal language. Interoperability has always been about “being able to communicate” which can very well be understood as “finding a bridge” between two systems.

So, in my humble opinion, I see providing an adapter as the best option. The Promise/J to Promise/A adapter is trivial to implement, is incredibly small once minified and could be delivered as an official plugin. I thought about having it inside jQuery core itself, but I believe it would be confusing for users to have 2 different promise interfaces right off the bat and would lead to some incredibly convoluted code mixing both. The kind of code you only see in #jquery.

Another solution would be to make Promise/J’s then compliant with Promise/A and to move the actual Promise/J’s then under another name (success? done?). However I’m really not a fan of this as I see it as potentially even more confusing than a dual-deferred offer. This is the solution that was chosen: the original Promise/J “then” method has been renamed as “done”. In jQuery 1.5, jQuery.Deferred provides a Promise/A-compliant “then” method. I’m more comfortable with the approach than I thought I would be when I wrote this very blog post.

One thing I know for sure is that Promise/J seems to be helpful in reducing user code size and complexity, while Promise/A seems oddly unadapted to a language like Javascript were functions are prime citizens and AOP is such a performance and hassle saver. It’s funny how big a change in users' code such tiny a difference in an interface can make.

afterword

So here we are, 11pm passed, and I have to prepare my bag and wake up early tomorrow morning. So, it’s quite obvious you’ll find typos, gigantic mistakes and things I simply forgot in this post. Still, I hope you’ll get a better understanding of how jQuery’s current deferred implementation works and why it was designed the way it was.

Maybe you know, maybe you don’t, maybe you just don’t care but jQuery-JSONP passed the 2.0 landmark.

What makes v2 so special is that the plugin no longer uses iframes internally while still allowing concurrent requests with the same callback name, a feature that was mandatory to me and caused much delay.

And if you have no clue what I’m talking about, go make some JSONP or, better yet, close this very tab and forget you ever heard about the UHKAJSONWP (Ugly Hack Known As JSON With Padding) a.k.a JSONP: you’re better off without this thing, believe me.

If you’re still here then I guess you broke two or three teeth on some fuglily designed “Data API” or on some script tag injection trickeries… or both. You may be a veteran but the hack I’m about to talk about is not for the faint of heart. It is the ugliest thing that works as intended I ever uncovered. Though you have to be as out of your mind as I am to expect it to behave like it does.

the problem

You make a bunch of JSONP requests with the same callback name using script tag injections. Successful requests will all call the same function at one point or another but you have no clue in which order.

So you’ll end up with a bunch of script tag nodes in your document at one point:

<script src="omg.php?callback=myFunc&param=1"></script>
<script src="omg.php?callback=myFunc&param=2"></script>
<script src="omg.php?callback=myFunc&param=3"></script>

With omg.php being something like this:

usleep( mt_rand( 0 , 3000000 ) );
echo( "$_GET[callback]( $_GET[param] );" );

You have no idea how long it will take the omg.php script to answer each request (a wild guess is something roughly between 0 and 3 seconds but that’s because OMG PHP IS SO SLOW!!!111).

Anyway, thing is you also have no idea in what order the calls to myFunc will come.

why it is a problem

Well, you could get around it using iframes like jQuery-JSONP v1 did.

Though it means you accept the following limitations:

• ugly, lenghty code,
• no document.domain in IE (unless you provide a specific document like Ben Alman does for his hashchange plugin, something I’m not comfortable with — the document, not the plugin which is awesome like anything benalmanian ought to be),
• a beautiful, and as intrusive as browserly possible, loading spinner everytime you make a request (especially annoying for background pollers), very poor performance (mainly because of the spinner above). Note that some browsers decided recently that it was ok to throw the spinner at us for simple script tag injection too so meh.

I wanted to get rid of those limitations for v2 hence the use of a simple script tag injection. You could also argue that making concurrent JSONP requests with the same callback name is just plain stupid: why not use a counter and concatenate it to a generic name like jQuery does internally?

How predictable of you, by the way.

Well, here are two reasons for the naysayer in you:

• what if the Data API you use has a fixed callback name (you would be surprised how many of them expect the authentification process, in particular, to be so unique it needs its very own, fixed, callback name — too bad if you want to make an aggregator which needs to log in with several accounts),
• you cannot take advantage of the browser’s cache if you change the callback name at each request (some big services, like youtube, issue 304 HTTP responses for recently issued requests… but only if the callback name is the same, of course).

the solution

Whatever the browser, you cannot intervene before a script is executed. You can only act when the script has been loaded and executed or an error occured.

Since you cannot intervene before the execution and you don’t know in which order the scripts will be loaded and executed, the callback has to be generic. The trick here is to set a (scoped) global variable in this generic callback and test for it (and reset it) in each of your requests callback:

// some generic code
// common to all requests

var lastValue;

function genericCallback( value ) {
  lastValue = [ value ];
}

// then the request specific closure

function request( options ) {

  window[ options.callback ] = genericCallback;

  function requestCallback() {

    var tmp = lastValue;
    lastValue = undefined;

    if ( ! tmp ) {
      options.error();
    } else {
      options.success( tmp[ 0 ] );
    }
  }

  // create the script tag

  // "attach" requestCallback to the script tag

  // put the script tag in the DOM

}

Attaching the request callback to the script tag is a no-brainer and also a one-liner in Firefox and Webkit browsers:

scriptTag.onload = scriptTag.onerror = requestCallback;

Of course, Mr Pedantic… I mean Opera, doesn’t provide the non-standard error callback hook. Please note that the engineers behind this oh so standard browser took the time to develop a completely proprietary and bloated Scope protocol for debugging… or, at least, that’s what I gathered from the highly esoteric introductions I took the time to read. I dunno, maybe they hired some transfuges from Redmond lately.

Anyway, the trick here is to use Opera’s “in-order” execution of injected script tags and add a secondary script tag with some inline code calling the first script tag onload handler (yeah, thank you Opera). To make things clear, you end up with something like this in your DOM:

<script id="autoId666" src="omg.php?callback=myFunc&param=1"></script>
<script type="text/javascript">
    jQuery( "#autoId666" )[ 0 ].onload();
</script>

The script are executed in order. So if you reach the second script tag, something went wrong (it’s your onerror callback). Of course you need to add the appropriate cleanup code and so on but you get the idea.

the problem under internet explorer

Your first instinct when it comes to Internet Explorer would be to do something like this:

scriptTag.onreadystatechange = function() {
  if ( /loaded|complete/.test( scriptTag.readyState ) ) {
    requestCallback();
  }
};

And guess what? It works! Well, until you CTRL-F5 the hell out of quite a simple PHP script.

Then the truth hits you: onreadystatechange is not called right after the script has been executed or has failed. It is just called “after”… an “after” that may very well be after another script tag has finished loading and executing.

the solution for internet explorer

Now fasten your seat belts because it’s were everything goes haywire the Roland Emmerich way.

At this point, we’re pretty much doomed unless we dig deep down the msdn. Let’s have a look at the code below:

<div id="divId" />

<script
  id="scriptId"
  for="divId"
  event="onclick"
  src="script.js">
</script>

What it does is pretty straight-forward actually: it attempts to load script.js. If it succeeds, it creates an onclick property on the div and, whether it succeeds or not, it fires onreadystatechange with a “loaded” readyState (“complete” if already in the cache). The big plus is that the script has not been executed yet!

But let’s take it a little further: do we really need the div? Could we target the script tag itself? The answer is yes:

<script
  id="scriptId"
  for="scriptId"
  event="onclick"
  src="script.js">
</script>

So here we are, with our magic script tag loading a script as its own onclick handler. Now the solution for Internet Explorer is as follows:

scriptTag.event = "onclick";
scriptTag.id = scriptTag.htmlFor = generateNewId();

scriptTag.onreadystatechange = function() {
  if ( /loaded|complete/.test( scriptTag.readyState ) ) {
    try {
      scriptTag.onclick();
    } catch( e ) {}
    requestCallback();
  }
};

the downside

Will this ugly ugly hack work in IE9? Somehow I hope not, as this is probably the weirdest thing I ever witnessed in a browser. Somehow I hope it will because I’m so damn tired of finding hacks for your “products”, Microsoft devs.

thank you and good night

Sleep well. It’s been far too long a post for far too ugly a hack.

So, it seems like everybody has to do his “hello world” of a blog post one day. I will try & spare you the ceremonial, lengthy and, let’s admit it, boring presentations. What’s the point anyway? If you end up coming back around here from time to time, I do hope it’ll be because you dig what you read.

Anyway, I’ll start with something simple as it’s nearing 7am and I should be in bed by now. And since I’m getting public, today’s topic will be the use of function closures as a way to create private “class” (or rather object) members.

That’s something I don’t see used that often and it’s a problem that pops up quite frequently for people coming from the Object Oriented world.

the problem

Take the following snippet of code:

function myClass() {
 this.myProperty = "Can you see me?";
}

myClass.prototype.changeMyProperty = function( newValue ) {
 this.myProperty = newValue;
}

var myObject = new myClass();

myObject.myProperty == "Can you see me?"; // true

myObject.changeMyProperty( "Yes, I can!" );

myObject.myProperty == "Yes, I can!"; // true

To any newcomer, this is a nightmare. There is no “private” keyword in the language, no secret voodoo, and no matter the efforts you will put into it, you simply cannot have private class members.

Most of the time, it’s OK though. Dirty, but OK. There’s this implicit contract between Javacript libraries developers and their users: “only touch to what’s documented”. In effect, it’s quite easy to torture the internals of a widely used library like jQuery to death. That’s not John Resig’s fault, nor is it due to some kind of curse brought by one of Paul Irish’s many esoteric dances: it’s, just, simply, Javascript at its weakest.

why it is a problem

Mainly? This all boils down to refactoring and/or alternative implementations. Let’s take the silly example below:

function SomeValueHolder() {
 this.values = [];
}

SomeValueHolder.prototype.get = function( index ) {
 return this.values[ index ];
}

SomeValueHolder.prototype.set = function( index , value ) {
 this.values[ index ] = value;
 return this;
}

Told you it was silly. But let’s get on with it, shall we? So you have this fancy data holder which stores its items in an internal array. But at one point, you realize you would be better off with an object instead of an array so that you can use strings to index your elements. You rewrite the class in version 1.1:

function SomeValueHolder() {
 this.values = {};
}

SomeValueHolder.prototype.get = function( key ) {
 return this.values[ index ];
}

SomeValueHolder.prototype.set = function( key , value ) {
 this.values[ index ] = value;
 return this;
}

You changed two characters, renamed two parameters because you like your code clean (you know you do) and, boom, you have a hashtable now! It’s also backward compatible, since you can still use numerical keys. Great, right?

But wait! A message pops up on your project’s mailing list: haCkz0R666 is pissed off because his code is all broken now. What gives? You seek through the myst of insults and angry remarks and finally get to the piece of code that got this loyal user’s nerves cracking:

var someValueHolder = new SomeValueHolder();

someValueHolder.set(0,"mummy");
someValueHolder.set(1,"daddy");

// I prefer daddy so...
someValueHolder.values.sort();
// GN0! someValueHolder.values.sort is not a function!

Oh yeah! haCkz0R666 had access to the internal array and he actually did use it directly. You never intended the collection to be sortable, so you never implemented a sort method… yet you had your class guts wide open and, sure enough, someone decided to dig into it.

The issue really is that you don’t want to be dependant on internal implementation when dealing with backward compatibility. The interface stays, the implementation changes. The example is silly of course, but you can see where it could go at a larger scale.

the solution

Beware teh prototypes:

• never use them to define core methods,
• only use them to define syntactic sugar and as a mean to extend your class dynamically (and you could even do without them as we’ll see shortly).

Now that you’re reading these very words in despair since, “dude, prototypes are, like, the way to do object oriented programming in Javascript”, let’s see what we can do once we don’t over-use them:

function SomeValueHolder() {

 var values = {};

 this.get = function( key ) {
  return values[ key ];
 };

 this.set = function( key , value ) {
  values[ key ] = value;
  return this;
 };

}

Done! values is only reachable from within the constructor. The only way to manipulate it is through get & set. Wanna change the way data is stored? No one outside of the class will be impacted.

We can still define syntactic sugar in the prototype:

SomeValueHolder.prototype.swap = function( index1 , index2 ) {

 var tmp = this.get( index1 );

 this.set( index1 , this.get( index2 ) );
 this.set( index2 , tmp );

 return this;

};

It makes sense to put it in the prototype since it only depends on publicly available methods. But let’s say we wanna implement an undo, we will need a private structure to store the list of swaps already made. Time to put some order into all this:

// We scope
( function() {

 window.SomeValueHolder = function() {

  installSetGet( this );

  installSwap( this );

 };

 function installSetGet( object ) {

  var values = {};

  this.get = function( key ) {
   return values[ key ];
  };

  this.set = function( key , value ) {
   values[ key ] = value;
   return this;
  };
 }

 function installSwap( object ) {

  var undo = [];

  this.swap = function( index1 , index2 ) {

   var tmp = this.get( index1 );

   this.set( index1 , this.get( index2 ) );
   this.set( index2 , tmp );

   swapsDone.push( [ index2 , index 1 ] );

   return this;
  };

  this.undoSwap = function() {

   if ( undo.length ) {
    this.swap.apply( this , undo.pop() );
   }

   return this;

  };
 }

} )();

Pretty straight-forward, for each “aspect” of your class, you add a function that will provide a host for private members and define the public methods that go with them. That brings us to the next & last point…

Use Javascript as an aspect oriented language:

function myExtension( instance ) {

 var myPrivateMember;

 instance.myPublicMethod = function() {
  // My code here
 };

}

Simple, effective, dynamic: Javascript.

the downside

Nothing’s perfect and prototypes are there for a reason. Without them:

• memory consumption is higher by an order of magnitude: each object carries its own definition of the method; while it’s consistant from an interface point of view, it acts as if we had as many classes defined as there are instances,
• instantiation is slower, since every method has to be constructed each time an object is instantiated; Sure, modern Javascript VM tend to mitigate the performance penalty but in no way do they make it marginal.

when to use closures to define private members

It’s a trade-off between overall performance (from both a speed and memory consumption point of view) and flexibility. If you’re unsure about the way your class is implemented and if you think you will refactor it in the near future, then use function closures and avoid prototypes as much as possible. At one point or another, your code base will stabilize and you’ll be able to switch to a prototype-based class definition anyway.

Beside, the two aren’t incompatible. You can use prototypes for functionalities you’re confident about and closures for those nasty experimental features. And, of course, methods built on top of others, of a lower level, have their place in the prototype.

thank you and good night

Anyway, this first post was far longer than I anticipated. So I’ll go to bed now and leave the inevitable typos where they are! Good night!