If you already understand object/function call chaining, just skip down to the good stuff.

The chains that bind you

Just so we’re all on the same page, “chaining” is this wonderful functional property of languages like JavaScript (which treat a function as a first-class citizen). It essentially amounts to making a function call, and the return value from the function is itself either another callable function, or more often, an object that has functions which are directly callable.

jQuery is probably the most prevalent use of this concept. Some example jQuery code:

$("p.neat").addClass("ohmy").show("slow");

In this snippet, $(…) is actually a function call, just like foo(…) or doSomethingReallyEvilButDontTellAnyone(…) (just kidding; only Google would name a function something crazy like that).

The return value from the $(…) call is an object, that has a bunch of properties on it, many of whom are functions. Consider that conceptually an object is returned like this (not actual code):

function $(...) {
   // do something cool
   return {
      addClass:function(...){...},
      show:function(...){...},
      ...
   };
}

So, what happens is that when that object is returned from the function, JavaScript will allow you to immediately de-reference the return value (the object), and using “.” (dot notation), access its properties. So $(…).addClass(…) makes the first chained call (“addClass”) off the return value from $(…). Then, addClass(…) also returns the same (same kind, not identical) object, and so this second return value can identically be de-referenced and a chained function be called. I like to refer to each chained function call as a “chain link”.

This chaining can theoretically go on forever (although for code readability it can be argued that 3 or 4 chain links is probably the most you want to practically do in production code, exceptions aside).

Why chains?

Probably the single biggest argument for developing code API’s that are of this chaining style is to pass context along from one function call to another in an automatic and graceful feeling way. For instance, in jQuery’s case, the reason for chaining is that internally, there’s a collection (a fancy array) of objects, and as each chained function is called, internally it loops over the collection of objects and performs tasks (such as expanding/contracting the collection, modifying objects in the collection, etc).

jQuery could work functionally this way and achieve the same effect:

var collection = $("p.neat");
$.addClass(collection,"ohmy");
$.show(collection,"slow");

See how we had to pass in the “collection” object/array for every function call? It works, but that code is arguably a little less graceful. And certainly it’s a little more repetitive.

So, chaining was a way to accomplish the same task (context passing across function calls) but in a prettier, more graceful fashion. Generally, the idea of adjusting the way a set of code works to make it more expressive or pleasant is called adding “syntactic sugar”.

To be fair, syntactic sugar is not the only reason why chaining in functional languages is useful. In fact, with LABjs, which also has a similar type of chaining API (although internally operates quite differently from jQuery), the reasons were only partially “sugar”; chaining in LABjs’ case actually provides an effective solution to guard against certain types of race conditions.

Because of how JavaScript (single-threaded) works, a chain of function calls is more or less guaranteed to complete fully before any other code comes in and interrupts to execute. This is also probably true of a series of distinct function calls in a single code block, but even more definitely so for a chain of function calls or (as we’ll see in a moment), a loop of function calls.

So why not a chain?

Since chains are powerful and also tend to lead to more expressive code (unless abused) and also generally less code, you may wonder, why wouldn’t we always use chains for everything?

The obvious: some function calls are, by their nature, independent and thus do not need to (or should not!) share a context. Also, under certain circumstances, chaining can be less efficient internally, depending on how the context is stored/shared/used.

Let’s face it: if you really want to write your entire “program” on one line with a bunch of obscure/abusive syntactical tricks, just go write some Perl. I kid, I kid.

But beyond those things, one fundamental fact of chaining is that it’s not “dynamic”. Basically, what I mean by this is that you pretty much hard-code at the time of code writing (aka, “build time”) how a chain is constructed. You can’t decide at run time based on environmental conditions that some parts of the chain are conditionally not executed (like by wrapping them in an if-statement, etc).

The ability to do that kind of run-time logic is restricted syntactically to individual statements/function calls, so a chain will be considered an atomic single indivisible unit for those purposes. You could conditionally decide whether to run one of several different chains depending on conditions, but each chain to be chosen would be pre-defined and for the most part immutable.

So, the truth is, chaining provides a syntactically prettier (more expressive) code approach, but it limits us a little bit in terms of coding flexibility.

I need more concrete

To illustrate, let’s revisit jQuery’s example code from above. Let’s say instead that what you really want to do is only run the addClass(…) call if some condition is true (like for instance, the user has a valid login session, or whatever). So, you want to basically do conceptually something like this:

$("p.neat")
if (userLoggedIn()) {  .addClass("ohmy")  }  // invalid syntax; will not work!
.show("slow");

As I mentioned, you could just have two different chains, one with addClass(…) in the chain, one without it, and choose which chain to execute with your if-statement. This leads to more and repetitive code; a bad thing. DRY (don’t repeat yourself).

And to be honest, you could also model this in a pure jQuery way (only in the chain using various filters), a variety of different ways. For instance, something like this (while ugly) might work:

$("p.neat")
.filter(function(){
   return isLoggedIn();
})
.addClass("ohmy")
.end() // ends the most recent filtering operation
.show("slow");

What I did here was use filter(…) to basically conditionally empty out the internal collection if not logged in (by returning false for all iterations), meaning the addClass(…) call is essentially ignored, and then revert back to my original collection with a .end() call before lastly calling .show(…).

Let me be clear: while you can do it this way, this is by far not the most efficient or code-friendly way to do so. This would be an example of an anti-pattern, where you are abusing jQuery’s syntax to solve a problem in a way that it should not be solved. It goes contrary to the spirit of jQuery (“write less, do more”).

Other examples?

Conditional inclusion of “chain links” is only one scenario where traditional chaining is kind of limiting. What if you want to be able to piece together different parts of a chain from various different snippets of code across mutliple functions? This may sound strange, but with complex Web 2.0 web applications, this kind of thing is not uncommon. And it flys in the face of the simple syntactic sugar that chaining is supposed to give us.

Nor are these problems limited to jQuery. With LABjs for instance, a chain might look like this:

$LAB
.script("framework.js")
.script("loggedin.js")
.wait(function(){
  // do something
});

Notice there I may want to only load “loggedin.js” if the user is, in fact, logged in. Same syntactic problem as above. But LABjs has no conditional “filters” that can modify the chain’s context, so we have less options (which in this case is a good thing!)

Or, what if I have a CMS system (like Wordpress for instance) that, across various functions, files, templates, etc, needs to load up a variety of different files, all based on various different environmental conditions and which templates are active, etc. Could I do individual $LAB chain calls in each location? Yes. But then I lose the ability to sequence the loads (ensure execution order). Also, it’s less memory efficient to do 8 different chains with 1 script in each, as opposed to one chain with 8 scripts in it.

Or, what if I want to use LABjs in a larger solution for creating robust fallback for resource loading from CDN locations? I need to conditionally decide during loading/run-time if I need to add more scripts to the “queue” because one load failed. Not possible with traditional chaining.

Unravel the ball of yarn

All this leads up to say that chaining is great and expressive and powerful, but it’s not complete for all our needs. So, we need to get a little more creative in those cases. And this technique is what I’m going to call “Simulated Chaining”.

Recall that at the top of this post, we talked about how chaining works because the return value from a function is either a function itself (and thus can be called directly), or it can be an object that can be de-refenenced and has properties which are functions to be executed.

So, our solution lies in that sentence (emphasis added). The return value from a function can either be used immediately, or it can be stored and used later. This isn’t anything new; if you’ve ever called any function in any language, you know it can return a value that you can store in a variable. What might have escaped you until now is that this return value that you store can be a contextually sensitive object that would otherwise have been used immediately in a chaining situation. And the cool part is it can be used later (like the next loop iteration) to pick up where the chain left off.

So, instead of pre-defining a chain in our code/build-time, we can instead programatically (at run-time) build up a “list” (an array/queue for instance) of functions to be called, and then “simulate” a chain by looping through the list, calling each function, and storing the return value for use in the next iteration.

For instance, the LABjs script code above can be done like this instead:

var queue = []; // empty array for now
...
queue[queue.length] = "framework.js";
...
if (isLoggedIn()) { queue[queue.length] = "loggedin.js";
...
var $L = $LAB;
for (var i=0, len=queue.length; i<len; i++) {
   $L = $L.script(queue[i]);
}
$L.wait(function(){
   // do something
});

I simulated a chain of function calls with an iterative for-loop. (NOTE: this is conceptually very similar to how you might take what would otherwise be a recursive set of function calls and turn it into a non-recrusive, iterative loop instead, like for performance reasons). The key is: store the return value from a function call, and then use that stored value as the object that makes the next call. Plain and simple. And now more powerful as you can build up your chains at run-time in as complex a way as is necessary.

Theoretically, a very similar approach could be taken for the jQuery examples above. However, I’ll leave that as an exercise for the reader.

Let’s look at one last slightly more advanced example of how to use simulated chaining with LABjs (which is nearly identical to how I do it on several of my sites):

var queue = [];
...
if (conditionOne()) {
   queue.push("framework.js",false); // false will create an empty .wait()
}
...
if (conditionTwo()) {
   queue.push("plugin1.js","plugin2.js",function(){
      // initialize plugins
   });
}
...
queue.push("mypage.js");
...
var $L = $LAB;
for (var i=0, len=queue.length; i<len; i++) {
   if (typeof queue[i] === "function") $L = $L.wait(queue[i]);
   else if (queue[i] === false) $L = $L.wait();
   else $L = $L.script(queue[i]);
}

I specify a queue array that can have one of three types of entries: a [string] is interpreted as a script to load, a [false] is interpreted as an empty .wait() call, and a [function] is passed to a .wait(…) call. I can use any manner of complex logic to build up the queue, and then in one for-loop at the bottom of the page, simulate the chain by looping over the queue.

Hopefully this helps clear up some of the mysticism that is chaining and give you some other ways to approach the challenging use cases you may face in your code. Go forth and chain (or loop)!

This “event” is separate from (and ostensibly noticeably earlier than) the more familiar “onload” event, whose defined behavior means that all of the page’s initial resources have fully loaded — before “onload”, there is an earlier state at which things (such as images and styles) are still loading, but the basic plan or skeleton of the page is now known and understood and the browser knows what to expect.

This “event” is, in some browsers, an actual event, in other browsers it’s a state which can be passively observed, and in some browsers, it has to be divined by examining the alignment of the stars and taking into account the wind speed and gravitational pull of various heavenly bodies, divided by the…

You get the point, there’s an “event” that the browsers try (and some do better than others at this attempt) to expose for when the DOM is ready, which I will now conveniently and uncreatively call “DOM-ready”.

So what if the DOM is ready or not?

Let me make sure that you understand the importance of DOM-ready. In some cases, if you have JavaScript logic that tries to modify the DOM of your page before this DOM-ready event has occured/passed, you can wreak havoc with that browser, and in some cases, cause a fatal error and browser crash.

Think of it this way: if i’m standing on one foot, precariously balanced, and trying to pull on a sock over my bare foot, and my wife comes along and tugs on the rug I’m standing on, am I likely to get that sock put on successfully? Am I even likely to stay standing? Probably not.

So, it’s wise to make sure that you don’t take any actions which could adversely affect the browser’s ability to get his sock on, at least if you don’t want him to fall over. And that’s why we have the concept of DOM-ready — to make sure that you don’t manipulate the DOM too early.

Moreover, the major JS frameworks (for that matter, most of even the minor JS tools out there) all provide ways for you queue up code to be executed at some later time, that time being when the framework is able to detect that the event has occured and that it’s now safe for your code to go about the business of changing things.

The frameworks all take care of that mess for me, right?

Ahh, don’t we wish that were completely true. If it were, this post would be somewhat pointless, and you’d instead be enjoying eating a pizza or watching re-runs of Grey’s Anatomy.

Alas, the world is not that simple. There’s a little known, but I believe important, problem with the way DOM-ready detection is accomplished by the frameworks in a cross-browser way. I’m not going to bore you with all the details of just how this detection occurs, but let’s just say it gets a little hackish in some cases.

For the lion-share of use cases, the DOM-ready detection that the current framework versions employ is acceptable, at least for all the browsers that most of us really care about working correctly. If you’re still worried about Netscape 3.0 though, you’re on your own… good luck!

But, a subtle problem creeps in when you step outside the normal set of uses cases — those being where you simply include a <script> tag at the top (or bottom, if you’re really clever) of your HTML document that loads your framework of choice (let’s say “jquery.js” for the purposes of this post).

Let’s say you have a mashup where you are pulling together multiple websites, and maybe jQuery is not guaranteed to already be present on the page. “No problem!” you say, because you know how to load a script file on-demand, so you’ll just fire off a request to do so, and wait for jQuery to be present before you proceed to make calls against it (and, of course, then use it to change the page!)

Or, let’s say you have a bookmarklet that people can use to popup some nifty little widget in their page of choice, and again, you want to make sure that jQuery is present for your code to utilize. Again, we’ll just load jQuery on-the-fly, and we should be good to go, right?

Or even better, let’s just say you’ve got a really complex application, which loads different scripts into the page at different times depending on the state of what the user does. Yet again, you may need to fetch jQuery at some point well after the initial page loading occured.

There’s yet another use-case, which is actually the one that I ran into that caused me to discover this issue several months ago. If your page uses a script loader, such as LABjs, the one I wrote in cooperation with Steve Souders (of Yahoo! and Google fame), you have to be aware of how certain scripts, notably the frameworks, do their DOM-ready detection and how this applies when the script is loaded dynamically.

Because script-loaders remove the “blocking” nature of script loading that normal <script> tags provide, it is actually quite possible to get into a situation where you load a script, like “jquery.js”, but the rest of the page is so well optimized that the DOM-ready event passes before jQuery arrives. You may very well not intend this to occur, but it can, and worse yet, it can happen as a race-condition, where it happens sometimes, and not others.

(… more …)