I’ve been recently working on optimizing performance of a so-called one-page web app. The application was highly dynamic, interactive, and was heavily stuffed with new CSS3 goodness. I’m not talking just border-radius and gradients. It was a full stack of shadows, gradients, transforms, sprinkled with transitions, smooth half-transparent colors, clever pseudo-element -based CSS tricks, and experimental CSS features.

Aside from looking into bottlenecks on Javascript/DOM side, I decided to step into the CSS land. I wanted to see the kind of impact these nice UI elements have on performance. The old version of the app — the one without all the fluff — was much snappier, even though the JS logic behind it hasn’t changed all that drastically. I could see by scrolling and animations that things are just not as quick as they should be.

Was styling to blame?

Fortunately, just few days before, Opera folks came out with an experimental “style profiler” (followed by WebKit’s ticket+patch shortly after). The profiler was meant to reveal the performance of CSS selector matching, document reflow, repaint, and even document and css parsing times.

Perfect!

I wasn’t thrilled about profiling in one environment, and optimizing according to one engine (especially the engine that’s used only in one browser), but decided to give it a try. After all, the offending styles/rules would probably be similar in all engines/browsers. And this was pretty much the only thing out there.

The only other somewhat similar tool was WebKit’s “timeline” tab in Developer Tools. But timeline wasn’t very friendly to work with. It wouldn’t show total time of reflow/repaint/selector matching, and the only way to extract that information was by exporting data as json and parsing it manually (I’ll get to that later).

Below are some of my observations from profiling using both WebKit and Opera tools. TL;DR version is at the end.

Notes

1. The fastest rule is the one that doesn’t exist. There’s a common strategy to combine stylesheet “modules” into one file for production. This makes for one big collection of rules, where some (lots) of them are likely not used by particular part of the site/application. Getting rid of unused rules is one of the best things your can do to optimize CSS performance, as there’s less matching to be done in the first place. There are certain benefits of having one big file, of course, such as the reduced number of requests. But it should be possible to optimize at least critical parts of the app, by including only relevant styles.

   This isn’t a new discovery by any means. Page Speed has always been warning against this. However, I was really surprised to see just how much this could really affect the rendering time. In my case, I shaved ~200-300ms of selector matching — according to Opera profiler — just by getting rid of unused CSS rules. Layout and paint times went down as well.

2. Reducing reflows — another well-known optimization — plays big role here as well. Expensive styles are not so expensive when fewer reflows/repaints need to be performed by the browser. And even simple styles could slow things down if they’re applied a lot. Reducing reflows AND reducing complexity of CSS go hand in hand.

3. Most expensive selectors tend to be universal ones ("*"), and those with multiple classes (".foo.bar", "foo .bar.baz qux", etc.). We already knew this, but it’s nice to get confirmation from profilers.

4. Watch out for universal selectors ("*") that are used for “no reason”. I found selectors like "button > *", even though throughout the site/app buttons only had <span>’s in them. Replacing "button > *" with "button > span" made for some amazing improvements in selector performance. The browser no longer needs to match every element (due to right-left matching). It only needs to walk over <span>’s — the number of which could be significantly smaller — and check if parent element is <button>. You obviously need to be careful substituting "*" with specific tags, as it’s often hard to find all the places where this selector could be used.

   The big downside of this optimization is that you lose flexibility, as changing markup will now require changing CSS as well. You won’t be able to just replace one button implementation with another one in the future. I felt iffy doing this replacement, as it’s essentially getting rid of useful abstraction for the sake of performance. As always, find the right compromise for your particular case, until engines start to optimize such selectors and we don’t have to worry about them.

5. I used this snippet to quickly find which elements to substitute "*" with.

   
   $$(selector).pluck('tagName').uniq(); // ["SPAN"]

   This relies on Array#pluck and Array#uniq extensions from Prototype.js. For plain version (with reliance on ES5 and selectors API), perhaps something like this would do:

   
   Object.keys([].slice.call(
     document.querySelectorAll('button > *'))
       .reduce(function(memo, el){ memo[el.tagName] = 1; return memo; }, {}));
   

6. In both Opera and WebKit, [type="..."] selectors seem to be more expensive than input[type="..."]. Probably due to browsers limiting attribute check to elements of specified tag (after all, [type="..."] IS a universal selector).

7. In Opera, pseudo "::selection" and ":active" are also among more expensive selectors — according to profiler. I can understand ":active" being expensive, but not sure why "::selection" is. Perhaps a “bug” in Opera’s profiler/matcher. Or just the way engine works.

8. In both Opera and WebKit, "border-radius" is among the most expensive CSS properties to affect rendering time. Even more than shadows and gradients. Note that it doesn’t affect layout time — as one would think — but mainly repaint.

   As you can see from this test page, I created a document with 400 buttons.

   

   I started checking how various styles affect rendering performance (“repaint time” in profiler). The basic version of button only had these styles:

   
   background: #F6F6F6;
   border: 1px solid rgba(0, 0, 0, 0.3);
   font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
   font-size: 14px;
   height: 32px;
   vertical-align: middle;
   padding: 7px 10px;
   float: left;
   margin: 5px;
   

   

   The total repaint time of 400 buttons with these basic styles only took 6ms (in Opera). I then gradually added more styles, and recorded change in repaint time. The final version had these additional styles, and was taking 177ms to repaint — a 30x increase!

   
   text-shadow: rgba(255, 255, 255, 0.796875) 0px 1px 0px;
   box-shadow: rgb(255, 255, 255) 0px 1px 1px 0px inset, rgba(0, 0, 0, 0.0976563) 0px 2px 3px 0px;
   border-radius: 13px;
   background: -o-linear-gradient(bottom, #E0E0E0 50%, #FAFAFA 100%);
   opacity: 0.9;
   color: rgba(0,0,0,0.5);
   

   

   The exact breakdown of each one of those properties was as follows:

   The text-shadow and linear-gradient were among the least expensive ones. Opacity and transparent rgba() color were a little more expensive. Then there was box-shadow, with inset one (0 1px 1px 0) slightly faster than regular one (0 2px 3px 0). Finally, the unexpectedly high border-radius.

   I also tried transform with rotate parameter (just 1deg) and got really high numbers. Scrolling the page — with 400 slightly rotated buttons on it — was also noticeably jerky. I’m sure it’s not easy to arbitrarily transform an element on a page. Or maybe this is the case of lack of optimization? Out of curiosity, I checked different degrees of rotation and got this:

   Note how even rotating element by 0.01 degree is very expensive. And as the angle increases, the performance seems to drop, although not linearly but apparently in a wavy fashion (peaking at 45deg, then falling at 90deg).

   There’s room for so many tests here — I’d be curious to see performance characteristics of various transform options (translate, scale, skew, etc.) in various browsers.

9. In Opera, page zoom level affects layout performance. Decreasing zoom increases rendering time. This is quite understandable, as more stuff has to be rendered per same area. It might seem like an insignificant detail, but in order to keep tests consistent, it’s important to make sure zoom level doesn’t mess up your calculations. I had to redo all my tests after discovering this, just to make sure I’m not comparing oranges to grapefruits.

   Speaking of zoom, it could make sense to test decreased font and see how it affects overall performance of an app — is it still usable?

10. In Opera, resizing browser window doesn’t affect rendering performance. It looks like layout/paint/style calculations are not affected by window size.

11. In Chrome, resizing browser window does affect performance. Perhaps Chrome is smarter than Opera, and only renders visible areas.

12. In Opera, page reloads negatively affect performance. The progression is visibly linear. You can see from the graph how rendering time slowly increases over 40 page reloads (each one of those red rectangles on the bottom correspond to page load followed by few second wait). Paint time becomes almost 3 times slower at the end. It looks almost like page is leaking. To err on a side of caution, I always used the average of first ~5 results to get “fresh” numbers.

    

    Script used for testing (reloading page):

    
    window.onload = function() {
      setTimeout(function() {
        var match = location.href.match(/\?(\d+)$/);
        var index = match ? parseInt(match[1]) : 0;
        var numReloads = 10;
        index++;
        if (index < numReloads) {
          location.href = location.href.replace(/\?\d+$/, '') + '?' + index;
        }
      }, 5000);
    };
    

    I haven’t checked if page reloads affect performance in WebKit/Chrome.

13. An interesting offending pattern I came across was a SASS chunk like this:

    
    a.remove > * {
      /* some styles */
      .ie7 & {
        margin-right: 0.25em;
      }
    }
    

    ..which would generate CSS like this:

    
    a.remove > * { /* some styles */ }
    .ie7 a.remove > * { margin-right: 0.25em }
    

    Notice the additional IE7 selector, and how it has a universal rule. We know that universal rules are slow due to right-left matching, and so all browsers except IE7 (which .ie7 — probably on <body> element — is supposed to target) are taking an unnecessary performance hit. This is obviously the worst case of IE7-targeted selector.

    Other ones were more innocent:

    
    .steps {
      li {
        /* some styles */
        .ie7 & {
          zoom: 1;
        }
      }
    }
    

    ..which produces CSS like:

    
    .steps li { /* some styles */ }
    .ie7 .steps li { zoom: 1 }
    

    But even in this case engine needs to check each <li> element (that’s within element with class “steps”) until it would “realize” that there’s no element with “ie7” class further up the tree.

    In my case, there was close to a hundred of such .ie7 and .ie8 -based selectors in a final stylesheet. Some of them were universal. The fix was simple — move all IE-related styles to a separate stylesheet, included via conditional comments. As a result, there were that many less selectors to parse, match and apply.

    Unfortunately, this kind of optimization comes with a price. I find that putting IE-related styles next to the original ones is actually a more maintainable solution. When changing/adding/removing something in the future, there’s only one place to change and so there’s less chance to forget IE-related fixes. Perhaps in the future tools like SASS could optimize declarations like these out of the main file and into conditionally-included ones.

14. In Chrome (and WebKit), you can use “Timeline” tab in Developer tools to get similar information about repaint/reflow/style recalculation performance. Timeline tab allows you to export data as JSON. First time I’ve seen this done was by Marcel Duran in this year’s Performance Calendar. Marcel used node.js and a script to parse and extract data.

    Unfortunately, his script was including “Recalculate styles” time in the “layout” time — something I wanted to avoid. I also wanted to avoid page reloads (and getting average/median time). So I tweaked it to a much simpler version. It walks over entire data, filtering entries related to Repaint, Layout, and Style Calculation; then sums up total time for each of those entries:

    
    var LOGS = './logs/',
        fs = require('fs'),
        files =  fs.readdirSync(LOGS);
    
    files.forEach(function (file, index) {
      var content = fs.readFileSync(LOGS + file),
          log,
          times = {
            Layout: 0,
            RecalculateStyles: 0,
            Paint: 0
          };
    
      try {
        log = JSON.parse(content);
      }
      catch(err) {
        console.log('Error parsing', file, ' ', err.message);
      }
      if (!log || !log.length) return;
    
      log.forEach(function (item) {
        if (item.type in times) {
          times[item.type] += item.endTime - item.startTime;
        }
      });
    
      console.log('\nStats for', file);
      console.log('\n  Layout\t\t', times.Layout.toFixed(2), 'ms');
      console.log('  Recalculate Styles\t', times.RecalculateStyles.toFixed(2), 'ms');
      console.log('  Paint\t\t\t', times.Paint.toFixed(2), 'ms\n');
      console.log('  Total\t\t\t', (times.Layout + times.RecalculateStyles + times.Paint).toFixed(2), 'ms\n');
    });
    

    After saving timeline data and running a script, you would get information like this:

    
    Layout                      6.64 ms
    Recalculate Styles          0.00 ms
    Paint                       114.69 ms
    
    Total                       121.33 ms
    

    Using Chrome’s “Timeline” and this script, I ran original button test that I tested before in Opera and got this:

    Similarly to Opera, border-radius was among least performant. However, linear-gradient was comparatively more expensive than that in Opera and box-shadow was much higher than text-shadow.

    One thing to note about Timeline is that it only provides “Layout” information, whereas Opera’s profiler has “Reflow” AND “Layout”. I’m not sure if reflow data analogous to Opera’s is included in WebKit’s “Layout” or if it’s discarded. Something to find out in the future, in order to have correct testing results.

15. When I was almost done with my findings, WebKit has added selector profiler similar to Opera’s one.

    

    I wasn’t able to do many tests with it, but noticed one interesting thing. Selector matching in WebKit was marginally faster than that of Opera. The same document — that one-page app I was working on (before optimizations) — took 1,144ms on selector matching in Opera, and only 18ms in WebKit. That’s a ~65x difference. Either something is off in calculations of one of the engines, or WebKit is really much much faster at selector matching. For what it’s worth, Chrome’s timeline was showing ~37ms for total style recalculation (much closer to WebKit), and ~52ms for repaint (compare to Opera’s 225ms “Paint” total; different but much closer). I wasn’t able to save “Timeline” data in WebKit, so couldn’t check reflow and repaint numbers there.

Summary

• Reduce total number of selectors (including IE-related styles: .ie7 .foo .bar)
• Avoid universal selectors (including unqualified attribute selectors: [type="url"])
• Page zoom affects CSS performance in some browsers (e.g. Opera)
• Window size affects CSS performance in some browsers (e.g. Chrome)
• Page reloads can negatively affect CSS performance in some browsers (e.g. Opera)
• “border-radius” and “transform” are among most expensive properties (in at least WebKit & Opera)
• “Timeline” tab in WebKit-based browsers can shed light on total recalc/reflow/repaint times
• Selector matching is much faster in WebKit

Questions

As I end these notes, I have tons of other questions related to CSS performance:

• Quoted attribute values vs. unquoted ones (e.g. [type=search] vs [type="search"]). How does this affect performance of selector matching?
• What are the performance characteristics of multiple box-shadows/text-shadows/backgrounds? 1 text-shadow vs. 3 vs. 5.
• Performance of pseudo selectors (:before, :after).
• How do different border-radius values affect performance? Is higher radius more expensive? Does it grow linearly?
• Does !important declaration influence performance? How?
• Does hardware acceleration influence performance? How?
• Are styles similarly expensive in different combinations? (e.g. text-shadow with linear-gradient vs. text-shadow on one-color background)

Future

As our pages/apps become more interactive, the complexity of CSS increases, and browsers start to support more and more “advanced” CSS features, CSS performance will probably become even more important. The existing tools are only scratching the surface. We need the ones for mobile testing and tools in more browsers (IE, Firefox). I created a ticket for Mozilla, so perhaps we’ll see something come out of it soon. I would love to see CSS performance data exposed via scripting, so that we could utilize it in tools like jsperf.com (cssperf.com?). Meanwhile, there’s plenty of tests to be done with existing profilers. So what are you waiting for? ;)

Remember that fabulous canvas library that makes working with canvas a breeze? The one that can parse SVG files on the fly and fluently draw them on canvas; that can render complex text in real time; that can morph objects with a touch of a mouse; with sophisticated, programmatically-accessible object model; easy to use animation and event infrastructure?

Why yes, of course I’m talking about Fabric.js ;)

Version 0.5 is out and here’s a quick overview of 3 main changes:

Node.js & NPM support

Fabric can now run on a server, under Node.js, thanks to wonderful jsdom and node-canvas libraries. It’s basically a wrapper on top of node-canvas that’s on top of jsdom that’s on top of node.

Fabric is also registered as NPM package, so can be installed with the usual one-liner:

> npm install fabric

Here’s how you would use it:

var fabric = require('fabric').fabric,
    canvas = fabric.createCanvasForNode(200, 200);

canvas.add(new fabric.Rect({
  top: 100,
  left: 100,
  width: 100,
  height: 50,
  angle: 30,
  fill: 'rgba(255,0,0,0.5)'
}));

var out = require('fs').createWriteStream(__dirname + '/rectangle.png'),
    stream = canvas.createPNGStream();

stream.on('data', function(chunk) {
  out.write(chunk);
});

.. and here’s what the resulting image would be — 30° rotated half-transparent, red rectangle.

I’m really excited about Node support in fabric. We’ll be using it in production on Printio.ru shortly.

Custom builder

It’s now possible to create custom fabric build, including only those modules that you need. The build process was rewritten to use Node.js instead of Sprockets. Building can only be done via command line for now. Online interface is likely to come in the future:

> node build.js modules=xxx,yyy,zzz

.. where “xxx”, “yyy”, and “zzz” are the names of the modules. Currently available modules are “text”, “serialization”, “parser”, and “node”. By default none of these modules are included. If you wish to include all of the modules, you can use “ALL” keyword:

> node build.js modules=ALL

Smaller footprint

By moving some of the functionality into optional modules (e.g. “parser” and “serialization”), default minimalistic version of fabric is now ~76KB (~22KB gzipped). There’s still more reduction that can be done, so expect even smaller footprint in the near future.

Enjoy.

I often see this confusion about extending things in Javascript.

There’s a big difference between extending native built-in objects and extending host objects. I tried to explain what’s wrong with extending host objects in a blog post, a while back. Now, if you look at the list of problems with extending host objects it’s easy to see that most of them don’t really apply to native, built-in objects.

To avoid any confusion, by native, built-in objects I’m talking about objects and methods introduced in ES5 — Array.prototype extensions (forEach, map, reduce, etc.), Object extensions (Object.create, Object.keys, etc.), Function.prototype.bind, String.prototype.trim, JSON.*, etc. These are the things that are shimmed most often. And the question is — is it OK to extend native, built-in objects with these standardized methods?

Well, let’s quickly go over problems with host objects extension:

Host vs. Native

• “Lack of specification” doesn’t apply here, as long as methods that are being shimmed are part of ES5 (or ES3). ES5 is a standard. There’s a publicly available specification. Implementing ES5 methods according to spec is doable (except certain edge-ish cases).

• “Host objects have no rules” doesn’t apply either. This is native objects we’re dealing with, and semantics of native objects are very well defined in those same ECMA-262 specifications. What this means in practice is that unless we’re dealing with faulty implementations, adding method bind to Function.prototype should allow us to add it. There’s no uncertainty about Function.prototype throwing error on extension, or silently ignoring our command (after all, the spec says: “The initial value of the [[Extensible]] internal property of the Function prototype object is true”). Ditto for other objects.

• “Chance of collisions” is non-existent as well. Since the methods that are being shimmed are part of a standard, and we’re shimming them according to standard, there’s no chance of collisions of any sort. Either implementation has those methods, or it doesn’t. If it doesn’t, methods are shimmed. That’s it.

• “Performance overhead” not only doesn’t exist, but could actually be the opposite of what happens. It’s likely that [].forEach(...) will be faster then _.forEach([], ...), but even if it isn’t, there should certainly be no performance hit with former version. Contrary to DOM objects that might not have [[Prototype]]’s exposed for public extension, there’s no need to manually extend arrays, objects and strings with these methods. Conceptually, there’s no performance overhead there.

• “IE DOM is a mess” doesn’t apply. We’re not dealing with DOM. And native objects are extension-friendly in IE, as far as I know.

So what do we have?

Well, it looks like properly extending native objects — unlike host ones — is actually not all that bad. This is of course considering that we’re talking about standard objects and methods. Extending native built-ins with custom methods immediately makes “collision” problem apparent. It violates “don’t modify objects you don’t own” principle, and makes code not future-proof.

Downsides

Are there any downsides?

Well, for once, there are cases when certain scripts mess up native objects/methods in a non-compliant way. Kind of like what Prototype.js does with some of its methods (e.g. Array.prototype.map or Array.prototype.reverse; standard-compliance is planned for future releases, as far as I know). If the shim adds standard-compliant methods, and application expects those methods to be non-compliant (but script/library-specific), then there could obviously be problems.

Second, as I mentioned above, while we know that native objects are free for extension, there’s always a risk of running into an oddball environment which doesn’t conform to spec. Keeping methods on a standalone (user-defined) object can avoid such scenarios. Whether this could be considered an issue depends on how paranoid you are.

Finally, you have to be careful when shimming methods that are not universally shimmable. Like Object.create, which had a very popular non-compliant shim floating around for a while. The method was defined directly on an Object, but silently failed to do anything useful with second argument — a set of property descriptors. Adding cross-browser support for property descriptors is a rather complicated endeavor, which is why defining such methods on a standalone object could save you some trouble (you could just implement a subset of Object.create functionality and call it a day).

Don’t forget that writing proper, compliant shims is hard. When in doubt, use standalone object. When the method you’re shimming is part of the unfinished spec, use standalone object. Only when you’re certain about method compliance and method is part of the finished, future-proof specification, is it safe to shim native object directly.

Enumerability

Another interesting, but likely insignificant difference is enumerability of shimmed methods. Unless methods are added using ES5 additions that allow to specify property enumerability (Object.defineProperty or Object.defineProperties), methods end up being enumerable:

if (!Array.prototype.map) {
  Array.prototype.map = function() { /* ... */ };
}
Object.keys(Array.prototype); // ["map"]

// can be worked around:

if (!Array.prototype.map) {
  Object.defineProperty(Array.prototype, 'map', {
    value: function() { /* ... */ }
  });
}
Object.keys(Array.prototype); // []

Underscore.js and API consistency

Getting back to underscore.js, I see an important aspect of consistency. Underscore adds not only standard methods like map, reduce and trim, but also its own, custom ones — values, extend, clone, etc. By adding map, reduce, and trim to standalone object, it keeps its API consistent.

I’d like to also mention that I do extend Array.prototype in fabric.js with methods like forEach, map, every. I make sure those methods are spec-compliant, and I take a risk of conflicts with libraries that shim methods in non-compliant way. Methods that are non-standard, on the other hand, are defined under standalone utility object. I’m not worried much about inconsistency, since — unlike in underscore.js — there’s only a handful of shimmed methods.

So there you have it. It should be now clear that extending native built-ins is definitely not as risky as messing with host objects. Do it carefully, follow spec closely, and use your reasonable judgement. For a spec-compliant shims, MDN is a good place to start with (but don’t trust it blindly either, as there were cases of non-compliance there as well).

Understanding the concept of code refactoring is one of the best things you can do to become a better programmer ^[1].

It all started a couple of weeks ago when I — once again — looked at the growing, stinky mess that my code has become. It’s a few thousand LOC app with various interactive widgets and controls all on one page. Even though a lot of functionality was encapsulated in these separately-defined widgets, the main “dashboard” object — a bootstrapper, so to speak — grew like a weed and became quite an abomination.

It was time for refactoring.

Every now and then I would clean things up. And so there I was, once again, trying to figure out where to start. One method was whopping 70 lines long. Another few of them — just below that giant — were doing one specific task and would be better off refactored into a separate module/widget/”class”/object. What are they doing in bootstrapper anyway? I scrolled a little further and witnessed more mess — long methods, spread-out functionality and a 4-argument function sneaking somewhere in between. 4 arguments? That’s just scandalous.

But where to start? Should I just randomly choose a thread to pull? If only I could see the stats for this dashboard object. Some kind of tool to help analyze method length of the entire thing. This way I could start with the messiest part. I could also see overall picture. Heck, I could even use a tool like this on a future project — just to get a feel of how bad things really are.

Well, a thing like that is totally doable, isn’t it?!

And so that how kratko.js was born; a simple tool to help you refactor Javascript.

kratko.js

There are 3 aspects of refactoring I’m usually interested in:

• Which objects/”classes” have too many methods?
• Which methods do too many things?
• Which methods have too many arguments?

Answering these questions and refactoring according to that usually takes care of most of the mess. Objects become more autonomous, by doing only a specific task. Methods become smaller by doing less and having the right level of abstraction. And there’s no more long-argument functions, order of which no one can ever remember.

This is exactly what kratko.js tries to provide.

kratko.js takes an object and collects statistics about its methods and arguments. It can then display that information in a table, allowing to sort by method or argument length. It also provides such numbers as average method/arguments length, and max/min method/arguments length.

It turns out to be pretty useful.

Kratko and TableViewer

To keep things simple and modular, kratko is made of 2 objects: Kratko which has getStatsFor method, and a TableViewer which could take stats object and display it in an interactive HTML table. If you don’t care to view results in a fancy HTML table, you can just use Kratko.getStatsFor passing it an object to inspect and receiving an object with elaborate stats for it. The whole thing is a tiny script — about 170 lines long. You can use it in the browser or on the server. All that’s required is environment that supports function decompilation (in other words, where Function.prototype.toString returns more or less exact representation of a function).

TableViewer, on the other hand, is a layer on top of Kratko and provides an outlook of these stats. What’s really useful, though, is that TableViewer is also interactive. You can sort a table by method or argument length, and view actual method contents.

getStatsFor signature

The signature of Kratko.getStatsFor is pretty straight-forward. Besides having average and min/max numbers, it also stores signatures of each method — just in case you’d like to iterate over it and do something other than getting an average.

{
  methods: {
    name: {
      methodString: ...,
      length: ...,
      argsLength: ...
    }
  },

  totalMethodLength: ...,

  minMethodLength: ...,
  maxMethodLength: ...,

  totalArgsLength: ...,

  minArgsLength: ...,
  maxArgsLength: ...,

  numMethods: ...
}

So, for example, an object with 2 methods — foo and bar:

var obj = {
  foo: function(x, y) {
    return x + y;
  },
  bar: function(a, b, c, d, e, f, g) {
    if (true) {
      // some comment
      alert(123);
    }
  }
};

..would have this kind of representation:

{
  methods: {
    foo: {
      methodString: 'function (x, y) {\n  return x + y;\n}',
      length: 1,
      argsLength: 2
    },
    bar: {
      methodString: 'function (a, b, c, d, e, f, g) {\n  if (true) {\n    //some comment\n    alert(123);\n  }}',
      length: 3,
      argsLength: 7
    }
  },

  totalMethodLength: 4,
  minMethodLength: 1,
  maxMethodLength: 3,

  totalArgsLength: 9,
  minArgsLength: 2,
  maxArgsLength: 7,

  numMethods: 2
}

Bookmarklet

The way I’ve been using kratko.js so far is via simple bookmarklet (up-to-date source). Open this bookmarklet on the page of a project you’re working on; tell it which object to inspect (e.g. SomeWidget.prototype, dashboard, etc.) and a stats table will appear. Now you can sort through the methods, and get a nice outlook on what’s going on.

The bookmarklet and the actual kratko.js script should work on most modern browsers, but I’ve only tested it on Chrome (13) and Firefox (4). I haven’t worked on making it cross-browser, but I also haven’t used anything fancy, so it should be pretty portable.

Distribution graph

After working with kratko.js for a bit, I realized that average method length doesn’t always tell me much. My “class” had 100+ methods. Even though some of them were larger than 50 lines long — and so were unacceptable — the average would still come out to be somewhere along 15-20, due to a large number of short, 1-5 -line methods.

I needed a way to quickly see total method size distribution, and so I added a little graph for that. It groups methods by length, showing which ones prevail and where:

I consider the maximum acceptable length of a method in Javascript to be ~20-25 lines long. Anything more than that is usually messy. It takes longer to figure out what's going on, and it's likely a sign of either not enough abstraction, or a method doing too many things (whereas, ideally, it should be doing just one thing — and as clear as possible).

Having said that, distribution graph is really an excellent indication of how "clean" an object is. You obviously want to stay as much on the left side of it as possible.

Here's an example ^[2] (of a "bad" graph):

As you can see, those lonely 85 and 56 -liners on the right have to go. There's also that little nasty bunch in the 28-43 area. There aren't many of them, thankfully. But they should probably be taken care of as well. Once that's done, the graph would be mainly concentrated in the left 1-20 area. And that would make things much cleaner.

Code style

The elephant in the room at this point is the code style. How can we base our assessment on a line count, when it could vary so much based on code style? Even though kratko.js does strip comments and empty lines ^[3], there's still room for deviations. Some prefer single-line statement, others follow more explicit Allman style:

  if (smth) { smthElse }

  // vs.

  if (smth) {
    smthElse
  }

  // vs.

  if (smth)
  {
    smthElse
  }

That’s exactly why it’s hard to have any absolute assessments. Obviously, it’s important to understand approximate optimal method length rather than follow any exact requirements. Decide for yourself which range you’d like to stay in, based on code style and personal preference (some people like to keep methods even smaller — under 10 lines, for example). Kratko is simply there to show you an overall picture, and guide you through the process of refactoring.

Nested functions

One last interesting point I’d like to go over is that of nested functions. When I started to refactor some of the longer methods, I noticed that many of them are long not due to lack of abstraction but due to presence of other, nested functions. Defining a small function right within another one is a pretty common thing in Javascript. It allows to keep things DRY and to create necessary abstractions.

Here’s a simple example:

function sort(arr1, arr2) {

  function byFirst(a, b) { return a[0] - b[0] }

  // ...

  if (smth) {
    arr1.sort(byFirst);
  }
  else {
    arr2.sort(byFirst);
  }
}

Even more importantly, it allows to scope certain functionality to one place. When an object has logic that requires more than 50 lines, you can either define few methods right on that object, or create one method with few “helper” functions defined right within it.

There’s certainly nothing inherently wrong in doing so. Those are the same nicely-chunked functions, only defined not on an object but within “parent” method. The advantage of such style is more explicit scoping, and the downside is that it could look messy and unclear to someone not familiar with such concepts as hoisting and functions within functions:

// Potential problem #1 is that inner function can look confusing

function foo() {
  function bar() { }
}

// Potential problem #2 is that hoisted function declaration (if any) can look confusing

function foo() {
  bar();

  // ... some other code

  function bar() { }
}

When there’s more than one nested function, and these nested functions aren’t just one-liners, there’s clearly an additional cognitive burden involved in method reading. When reading a method, you now need to distill actual logic from these auxilary function declarations. Grouping all declarations at top (or bottom) of the function can help, but there’s still a slight overhead.

There’s this one function in Prototype.js which I noticed demonstrates this really well. The function is 76 lines long, so please bear with me. I’m inserting it untouched just to show how nested functions — especially scattered ones — could make it harder to read the method and follow its logic. It’s a good thing Prototype.js has always kept its variable/function names as explicit and descriptive as possible — something I’ve always loved about it — or reading this function would be even harder:

function (methods) {
  var F = Prototype.BrowserFeatures, T = Element.Methods.ByTag;

  if (!methods) {
    Object.extend(Form, Form.Methods);
    Object.extend(Form.Element, Form.Element.Methods);
    Object.extend(Element.Methods.ByTag, {
      "FORM":     Object.clone(Form.Methods),
      "INPUT":    Object.clone(Form.Element.Methods),
      "SELECT":   Object.clone(Form.Element.Methods),
      "TEXTAREA": Object.clone(Form.Element.Methods)
    });
  }

  if (arguments.length == 2) {
    var tagName = methods;
    methods = arguments[1];
  }

  if (!tagName) Object.extend(Element.Methods, methods || { });
  else {
    if (Object.isArray(tagName)) tagName.each(extend);
    else extend(tagName);
  }

  function extend(tagName) {
    tagName = tagName.toUpperCase();
    if (!Element.Methods.ByTag[tagName])
      Element.Methods.ByTag[tagName] = { };
    Object.extend(Element.Methods.ByTag[tagName], methods);
  }

  function copy(methods, destination, onlyIfAbsent) {
    onlyIfAbsent = onlyIfAbsent || false;
    for (var property in methods) {
      var value = methods[property];
      if (!Object.isFunction(value)) continue;
      if (!onlyIfAbsent || !(property in destination))
        destination[property] = value.methodize();
    }
  }

  function findDOMClass(tagName) {
    var klass;
    var trans = {
      "OPTGROUP": "OptGroup", "TEXTAREA": "TextArea", "P": "Paragraph",
      "FIELDSET": "FieldSet", "UL": "UList", "OL": "OList", "DL": "DList",
      "DIR": "Directory", "H1": "Heading", "H2": "Heading", "H3": "Heading",
      "H4": "Heading", "H5": "Heading", "H6": "Heading", "Q": "Quote",
      "INS": "Mod", "DEL": "Mod", "A": "Anchor", "IMG": "Image", "CAPTION":
      "TableCaption", "COL": "TableCol", "COLGROUP": "TableCol", "THEAD":
      "TableSection", "TFOOT": "TableSection", "TBODY": "TableSection", "TR":
      "TableRow", "TH": "TableCell", "TD": "TableCell", "FRAMESET":
      "FrameSet", "IFRAME": "IFrame"
    };
    if (trans[tagName]) klass = 'HTML' + trans[tagName] + 'Element';
    if (window[klass]) return window[klass];
    klass = 'HTML' + tagName + 'Element';
    if (window[klass]) return window[klass];
    klass = 'HTML' + tagName.capitalize() + 'Element';
    if (window[klass]) return window[klass];

    var element = document.createElement(tagName),
        proto = element['__proto__'] || element.constructor.prototype;

    element = null;
    return proto;
  }

  var elementPrototype = window.HTMLElement ? HTMLElement.prototype :
   Element.prototype;

  if (F.ElementExtensions) {
    copy(Element.Methods, elementPrototype);
    copy(Element.Methods.Simulated, elementPrototype, true);
  }

  if (F.SpecificElementExtensions) {
    for (var tag in Element.Methods.ByTag) {
      var klass = findDOMClass(tag);
      if (Object.isUndefined(klass)) continue;
      copy(T[tag], klass.prototype);
    }
  }

  Object.extend(Element, Element.Methods);
  delete Element.ByTag;

  if (Element.extend.refresh) Element.extend.refresh();
  Element.cache = { };
}

It’s also worth mentioning that “problem” with nested function can easily be taken care of by moving these auxilary functions into a closure:

var foo = {

  bar: (function(){

    function aux1() { }
    function aux2() { }

    return function() {
      // ...
      aux1();
      aux2();
    };

  })()
}

kratko.js obviously doesn’t know about such “hidden” functions, and so bar now “looks” like this:

function() {
  // ...
  aux1();
  aux2();
}

All of these problems are arguably non-issues, so apply your own judgement and preference when dealing with this kind of things. If you see a method that’s long due to nested functions, and you’re OK with nested functions, move on to something else. The reason I’m bringing this up is to show once again that kratko.js measurements are not absolute and should be taken into consideration rather then followed strictly.

What does future hold?

I was pondering what else could a tool like kratko.js do. Some of the ideas that came to my mind:

• Measure method width (to catch methods that are wider than 100/80/72 characters long, depending on your preference)

• Count statements rather than lines; this could make both of these snippets equal to 1 line long, rather than 10-to-1:

  
  if
  (
  true
  )
  {
  alert
  (
  1
  )
  }
  
  // vs.
  
  if (true) alert(1)
  

• Syntax highlight the code (of the methods)

• Support navigating through objects (e.g. to get to jQuery.fn from jQuery or to fabric.Element.prototype from fabric.Element)

• Integration with other services (e.g. pre-commit hook, pre-production quality check, etc.)

• <insert your idea here>

Source, unit tests

kratko.js is licensed under MIT and is free for any kind of use (just leave attribution, please, and contribute if/what you can). The source is on github. So are unit tests. If you want to change, fix, or suggest something — I welcome any pull requests.

Use it to make your code better. Have fun!

^[1] If you don’t have “Refactoring” or “Clean Code” on a bookshelf, do yourself a favor and go get them now. This will be totally worth it.

^[2] This “bad” graph is actually of my fabric.Element.prototype. Embarassing, I know. Will be fixed soon.

^[3] Note that multiline comments stripping is not very bulletproof and can have false results in certain (rare) cases. it does work well most of the time, though.

if (MyApp == null) {
    var MyApp = {}
}

This was at the beginning of the file, and was obviously a way to define global “namespace” object, if one didn’t exist. The condition in this particular case, however, looked rather unusual — if (MyApp == null). It got me thinking about the ridiculous number of ways in which it is possible to define a global object in Javascript.

I’m sure you’ve seen the variations of this kind:

if (typeof MyApp == 'undefined') {
  var MyApp = { };
}

or:

if (!window.MyApp) {
  window.MyApp = { };
}

or maybe even something as strange as:

if (MyApp === undefined) {
  MyApp = { };
}

But have you ever wondered about the difference between these? Are any of them “better” than the other ones, and why? Is there a particular way you prefer, and for which reason?

If we were to look into some of the possible global object creation patterns, it turns out there’s quite a bit of interesting little details (and traps) here and there. What do you mean they’re not interesting? Of course they are! :)

As a fun exercise, let’s go over some of the more popular variations, explaining the inner workings of each one of them. We’ll take a look at troublesome ones; those that are more compatible than others; and those that differ depending on whether implementation follows ES3 or ES5 rules. Hopefully, you’ll also learn a thing or two about ECMAScript while we’re at it.

How many ways to skin a cat?

So what are the options for creating a global object if one doesn’t exist? Well, let’s see. There are conditions, used as expression in an if statement. And there are actions used as the inner statement in an if statement.

if (condition) {
  action
}

Even if we’re not using if statement, the general pattern of condition + action is still in effect:

condition && action
!condition || action
// etc.

The lists of conditions and actions might look like this (I’ll be using MyApp “name” as an example):

Conditions:

  !MyApp
  !window.MyApp
  !this.MyApp
  !global.MyApp
  typeof MyApp == "undefined"
  typeof MyApp != "object"
  MyApp === undefined
  MyApp == null
  "MyApp" in window
  window.hasOwnProperty("MyApp")

Actions:

  var MyApp = { }
  window.MyApp = { }
  this.MyApp = { }
  global.MyApp = { } // where `global` references global object
  MyApp = { }

There are undoubtedly other similar variations, such as using bracket notation instead of dot notation — if (window['MyApp']) { ... }, or more obscure ones like eval('var MyApp = ...'), but we’ll omit those for the sake of brevity. Arguably, some of the items in this list are rather similar to each other, like window.MyApp, this.MyApp, and global.MyApp — after all, they are all assignments to a property of global object — but I’d like to show the important difference in each one of them, which is why we’ll look at them separately.

I promise not to go over all of the 50+ possible combinations. Only a handful of them.

Patterns overview

1) typeof + variable declaration

if (typeof MyApp == 'undefined') {
  var MyApp = { };
}

This is probably the most popular variation. Good old variable declaration, and a typeof check. When executed as global code, it creates a global variable (if one doesn’t exist) and assigns an object reference to it. What’s important to understand about this snippet is that variable declaration — similar to function declaration — follows the so-called “hoisting” behavior. In other words, MyApp variable is created before any statements in the current scope are executed. This is why the snippet is functionally identical to:

var MyApp;
...
if (typeof MyApp == 'undefined') {
  MyApp = { };
}

When MyApp is already defined and references something, typeof MyApp != 'undefined' check does not succeed and MyApp is not overwritten. The declaration of MyApp does nothing since binding already exists in this scope. However, if MyApp doesn’t yet exist, typeof MyApp evaluates to “undefined”, and MyApp is assigned a reference to a newly created object. The reason typeof MyApp evaluates to “undefined” is because at that point MyApp is already declared and has an undefined value (as all undeclared variables do).

2) boolean conversion + variable declaration

if (!MyApp) {
  var MyApp = { };
}

Another common version is the same as the previous one, only with typeof check replaced by a boolean conversion one. This one is clearly shorter but is it just as reliable? I remember being confused about it a while back. Shouldn’t MyApp throw a ReferenceError if MyApp isn’t declared — I thought. My fears were certainly unfounded. The “hoisting” behavior of variable declarations prevents ReferenceError from occurring here. Similarly to the previous example, let’s see a functionally identical version of a snippet:

var MyApp;
...
if (!MyApp) {
  MyApp = { };
}

var MyApp that’s inside the block, hoists MyApp declaration to the top of the scope. By the time execution gets to the if statement, MyApp is already declared and has an undefined value. if (!MyApp) can never throw a ReferenceError, since the variable is always declared.

3) boolean conversion + undeclared assignment

if (!MyApp) {
  MyApp = { };
}

Sometimes a perfectly good second version is taken to the “next level” with this unpleasant variation. Unlike previous example, there’s no variable declaration here; only an assignment. When MyApp doesn’t exist, !MyApp expression throws ReferenceError for exactly this reason — the variable is never declared, and the access to it should throw! This version is hardly practical, but it’s good to understand why it doesn’t “work”.

Undeclared assignment

Before we move further, take a closer look at MyApp = { } line. Anything looks suspicious there?

This is a so-called undeclared assignment. Instead of declaring a variable via a variable statement (i.e. var MyApp = { }), MyApp is being assigned a value directly. In ECMAScript, when something is being assigned to non-existing variable, the variable with that name is created on a global object and becomes available to any code. Well, to be more precise, it becomes a global property, rather than a variable, but this subtle difference is not important now.

So MyApp = { } creates a global MyApp property, then assigns a newly created object reference to it.

Note how very much MyApp = { } is different from var MyApp = { }. The former one — undeclared assignment — creates a global property, whereas latter one — variable declaration — creates a local variable.

Undeclared assignments are historically considered a bad practice. They lead to confusion and increase the risk of global collisions. There are also certain browser bugs, such as that in IE (MSHTML DOM), where undeclared assignment results in an error if element with same id/name exists in the document. There’s a big chance for beginner to forget var and end up creating an unwanted global property. Or simply consider var’less version to be similar to that with the var. Or not even know about having to use var — after all, plain assignment seems to work just fine.

Since undeclared assignments are such a misleading part of the language, ECMAScript 5 — newest version of ECMAScript — specifies that when they occur in a strict mode, a ReferenceError should be thrown. This makes for more robust code with less chance for unexpected errors. And since strict mode is more or less a future direction of the language, it makes sense to avoid undeclared assignments as if they never existed.

4) typeof + undeclared assignment

if (typeof MyApp == 'undefined') {
  MyApp = { };
}

Another harmful variation, and unfortunately the one that actually “works”. Note how there’s still an undeclared assignment, but the condition is now replaced with a typeof check. typeof check is exactly what makes all of this work, unlike plain variable access in the previous example. In ECMAScript, when typeof is passed an undeclared identifier, it’s specified to return string “undefined”. This kind of leniency exists on purpose — typeof is meant to be used with undeclared identifiers; it doesn’t throw (as regular variable access does) but returns “undefined” instead.

So when MyApp doesn’t exist and if expression succeeds, MyApp = { } is evaluated and creates a global MyApp property. The problem here is that MyApp = { } is still an undeclared assignment and so has all the same problems as undeclared assignment from the previous example.

5) property access on window

if (!window.MyApp) {
  window.MyApp = { };
}

Stepping away from variable declarations and undeclared assignments, which other ways are there to create a global property?

Well, by assigning directly to a global object of course. In browsers global object is often referenced through global window property. So one of the ways to create a property on a global object is by assigning to property of window. This solution is almost perfect, except for two drawbacks.

First, it makes code less portable, as there is a reliance on presence of global window property. If you wanted to run it in a non-browser environment (V8, Rhino, WScript, etc.) window is likely to be non-existent there.

Second problem is a bit more vague. It’s relevant to browser environments only, and it’s about window not referencing global object directly. HTML5 defines window to reference not global object, but so-called WindowProxy object. Even though all operations performed on WindowProxy must also be performed on the Window object, there are few existing quirks — notably in Internet Explorer — where global (variable) object and window are not fully interchangeable (more evidence).

Curiously, current HTML5 draft also says that window typically references a Global Object, which makes it a non-requirement. In practice, however, window almost always references Global Object (or at least an object that acts as if it was a global object).

6) property access on this

If you don’t want to rely on browser-only window, the most straightforward way to assign to a global object is by creating a reference that definitely gives us a Global Object. How to create such reference? Well, since we’re in global code, we can freely use this keyword.

if (!this.MyApp) {
  this.MyApp = { };
}

This works beautifully, and should create a global object in any respectable (i.e. ECMAScript-compliant) implementation. Note, however, that this code can only be run in global scope to ensure that this references global object. Of course you could also run it non-globally as long as this keeps referencing global object:

var myObject = {
  myMethod: function() {
    ...
    if (!this.MyApp) {
      this.MyApp = { };
    }
  }
};

// call method with `this` referencing global object rather than `myObject` 

myObject.myMethod.call(this);

The requirement to be able to create global object from within non-global code might seem contrived. Yet, I’ve seen quite few times how javascript files — representing different “modules” — were concatenated together and wrapped into another, global self-executing function. Or the code would be eval’d after being retrieved from the server via XHR. During evaluation, it would be executed in the scope of a caller, not in the global scope.

This kind of “global object passing” could certainly become cumbersome. If only there was a way to get access to global object from within any scope. Well, there certainly is.

7) property access on global

The easiest way to achieve this is by creating a globally-accessible unique property referencing global object:

// from within global code
var global = this;

.. which brings us to the next variation of global object creation:

if (!global.MyApp) {
  global.MyApp = { };
}

This snippet could now be executed from anywhere — as long as global binding is not shadowed by anything in the executing scope.

(function(global){

  // this obviously won't work since `global` is now a local variable and has a value of `undefined`.

  if (!global.MyApp) {
    globa.MyApp = { };
  }

})();

We solved the problem of not being able to run code from anywhere, but at the expense of having an extra global property. We’ve also introduced a requirement to actually create that global property. If our code is run in unknown environment, where it’s not possible to create this global object shortcut, this kind of solution is out of the question. Additionally, there’s a chance of collisions if another code defines global global property referencing something other than global object.

This is disastrous. What to do?

Global object retrieval

In ECMAScript 3 — it turns out — there’s a very easy way to retrieve global object from within any code. The beauty of the following solution is also that it’s not affected by local shadowing. It’s pretty much the perfect way to get access to global object:

var global = (function(){return this})();

The idea is simple. In ES3, when function is called as a function (not as a method; more precisely — as a non-reference or as a reference with null base object) its this is set to reference global object. When (function(){ ... })() is executed, it evaluates to a non-reference, so it’s invoked with this referencing global object.

Alternatively, we could have created a reference with null base object, which would also execute function with this referencing global object:

function f(){return this}
var global = f();

.. but that wouldn’t be as short and concise.

Great! We can now have global object from within anywhere. Is there a catch?

ECMAScript 5 strict mode

Well, yes, kind of. The catch is ECMAScript 5 and its newly-introduced strict mode. In ES5 strict mode, this no longer references global object in the above two cases:

"use strict";
(function(){return this})(); // undefined

function f(){return this}
f(); // undefined

The rationale for this was, supposedly, to increase security by limiting access to global object. There is, however, a workaround and it involves indirect eval call (which I explained in the past):

"use strict";
var global = (1,eval)("this");

Indirect eval evaluates code in global scope, and MUST set this to reference global object. So (1,eval)('this'), which is an indirect eval call, should evaluate to a global object.

The downside of this workaround is potential shadowing of eval by something other than built-in eval. The solution is certainly not as robust as (function(){return this})() one, which can be used in ES3 and ES5-non-strict code.

So to summarize:

var global = (function(){return this})(); // ES3, ES5 non strict
var global = (1,eval)('this'); // ES5 strict

In our current world of just-appearing ES5-compliant implementations, it’s hard to come up with a reliable cross-platform solution. Should we use ES3-ES5-non-strict snippet or ES5-strict one? The latter one sounds like a more future-proof solution, but reliance on indirect eval makes it a moving target: as we’ve seen before, indirect eval behavior varies across browsers.

Perhaps we can assume that browsers with strict mode support also follow ES5-compliant indirect eval behavior? In that case solution is simple:

"use strict";
var global = (function(){ return this || (1,eval)('this') })();

Implementations that don’t support strict mode, should evaluate left-hand side of || expression — this, which would be a global object and as any object be truthy. Implementations that DO support strict mode, should evaluate right-hand side of an expression since this would be undefined. Right-hand side should then evaluate to a global object — if eval still references built-in function of course.

This solution is arguably too verbose so it might not be desirable in all cases.

8) property access + variable declaration

Another common pattern is the one that combines any of the previously discussed solutions. For example, property check as condition and variable declaration as action:

if (!window.MyApp) {
  var MyApp = { };
}

or typeof check as condition and property creation as an action:

if (typeof MyApp == 'undefined') {
  window.MyApp = { };
}

Are there any problems with this variation? Benefits?

Well, first version can obviously only work when run from within global code; we need variable declaration to create global binding. The potential problem with this snippet is that we check existence of property on window but create it on global object. If window doesn’t reference global object, there’s a room for discrepancy. We could use previously discussed this or global instead of window — to refer to a global object:

if (!this.MyApp) {
  var MyApp = { };
}

In this case, the snippet is not much different from the first example:

if (typeof MyApp == 'undefined') {
  var MyApp = { };
}

The only subtle difference here is that this.MyApp check proceeds when this.MyApp evaluates to something falsy (0, ”, NaN, null, undefined, false), whereas typeof MyApp == "undefined" — only when MyApp evaluates to undefined:

var MyApp = '';
...

if (!this.MyApp) {
  // this statement is executed; MyApp is overwritten
  var MyApp = { };
}
if (typeof MyApp == 'undefined') {
  // this statement is not executed; MyApp is not overwritten
  var MyApp = { };
}

Since both this.MyApp = { } and var MyApp = { } will create global MyApp binding, the only difference here is that former one makes it deletable, while latter one doesn’t. Other than that, there is no difference — both operate on a global object when run from within global code. At least in theory. In practice, though, there has been some evidence of IE having different objects as global variable object and window object. For best cross-browser results, I would suggest to avoid mixing them up like this.

9) typeof “object”

Sometimes typeof MyApp == 'undefined' check is replaced with the opposite one — typeof MyApp != 'object'.

  if (typeof MyApp != 'object') {
    ...
  }

There isn’t much difference here, of course, except that typeof != 'object' check will also catch any other non-object and non-undefined values; pretty much all primitives except undefined:

  var MyApp = "trolololololo";

  if (typeof MyApp != 'object') {
    MyApp = { }; // MyApp is overwritten
  }

10) == null and === undefined

Other times, typeof check is replaced with direct comparison with undefined or null values:

if (MyApp === undefined) {
  var MyApp = { };
}

// or

if (MyApp == null) {
  var MyApp = { };
}

The second example is what I mentioned in the beginning and what got me surprised in the first place. As you probably know, comparing to null via equality operator (==) returns true when value is either null or undefined. This is why it allows to catch undeclared variables which have undefined values.

If you think about it, there’s really no reason to use this kind of check though. Even though it’s shorter than typeof, comparing to undefined is more fragile, since undefined is a writable property in ES3 (which is why — without taking precautions — it has been generally recommended against). Comparing to null is safer but is still unnecessary; !MyApp is just enough and is even shorter.

11) in and hasOwnProperty

There are even more exotic beasts such as those using in operator or hasOwnProperty method.

if (!('MyApp' in this)) {
  this.MyApp = { };
}

if (!this.hasOwnProperty('MyApp')) {
  this.MyApp = { };
}

Using in is almost identical to using plain boolean conversion — if (!MyApp) .... The only difference is that in will “catch” global properties with any values, whereas boolean conversion-based one — only those that have truthy values. Similarly to typeof ... == "undefined" check, in will catch both — undeclared variables and variables with undefined values.

hasOwnProperty, on the other hand, is a bit more strict. Even though irrelevant in our case, it’s worth remembering that hasOwnProperty will catch only those properties that exist directly on a global object. That means nothing from global object’s prototype chain, which could include Object.prototype, Window.prototype, etc.

this.hasOwnProperty('localStorage'); // false
'localStorage' in this; // true

this.hasOwnProperty('alert'); // false
'alert' in this; // true

this.hasOwnProperty('toString'); // false
'toString' in this; // true

var x;
this.hasOwnProperty('x'); // true
'x' in this; // true

12) || operator

global.MyApp || (global.MyApp = { });
this.MyApp = this.MyApp || { };
typeof MyApp == 'undefined' && (global.MyApp = { });

A slightly different way to write #5, #6, or #7 is using || operator. The functionality is the same; this is only a matter of preference.

Takeaway points

So there you have it. A quick rundown through some of the most popular options. To summarize:

• Avoid undeclared assignments. They are a “dying” part of the language.
• Assigning to window is not completely cross-platform; using this (or retrieving global object) is more portable.
• Retrieving global object is iffy. You can use (function(){ return this || (1,eval)('this') })() which should work in ES3, ES5 and ES5-strict.
• Some variations (e.g. variable assignment) work only in global scope; others (e.g. assignment to window) — from within any.
• No need to perform typeof "undefined", or === undefined checks; plain ! operator works just as well, as long as variable is created via declaration.
• When in global scope, the easiest & simplest version to create global object is if (!MyApp) var MyApp = ...
• When object needs to be deleted at some point after creation, property assignment is the way to go: if (!this.MyApp) this.MyApp = ... (substituting this with window or global as necessary)
• Avoid mixing this/window/global and global variable object (used to create property during variable declaration); they could be different objects.

I was recently working hacking on something in Firebug console and remembered about expression closures — a language addition, introduced in Mozilla’s JavaScript 1.8. The concise explanation on MDC captures the essence of expression closures:

This addition is nothing more than a shorthand for writing simple functions, giving the language something similar to a typical Lambda notation. […] This syntax allows you to leave off the braces and ‘return’ statement – making them implicit. There is no added benefit to writing code in this manner, other than having it be syntactically shorter.

And that’s exactly what I used it for — to quickly experiment with something, shortening function expressions to save on typing.

MDC also gives a simple example, showcasing a function written using expression closure:

  // Regular syntax
  function() { return x * x }

  // Expression closure
  function(x) x * x

As you can see, expression closure is essentially a more concise way to create a function. Based on MDC, expression closure allows us to drop “return” and braces denoting function body.

The information on MDC, however, was so tiny that I became curious about some of the finer details of how expression closures (EC from now on) work. Can they only be used to create function expressions? How about function declarations? What about named function expressions? Is function() ... always identical to function(){return ...} no matter what’s in the ... (function body)? And what are these “simple functions” MDC is talking about?

There was no answer to any of these questions, so I decided to quickly investigate this funky language addition a bit deeper. These are some of my findings; you’ll see that certain behavior isn’t always obvious.

Letting the code speaks for itself, here’s is a list of questions followed by simple tests, attempting to answer those questions. Feel free to skip to the next section for a shorter overview of these findings.

Tests

1. Can EC be used to create function declarations (not just function expressions)?

   Yes.

   
   function f(x, y) x + y
   typeof f; // "function"
   

2. What about named function expressions?

   Works as expected.

   
   typeof (function f(x, y) x + y); // "function"
   

3. How does EC affect function representation?

   As usual, but does not include curly braces (or “return” keyword)!

   
   String(function (x) x + x ); // "function (x) x + x;"
   

4. What about non-standard `name` property?

   Works as expected.

   
   function foo(x, y) x + y;
   foo.name; // "foo"
   

5. How about immediately invoked function expression?

   Works fine.

   
   (function(x, y) x + y)(1, 2); // 3
   

6. What about immediately invoked function expression without wrapping parens?

   Not so fast!

   
   var f1 = (function(x, y) x + y)(1, 2);
   var f2 = function(x, y) x + y (1, 2);
   
   f1; // 3
   f2; // function(x, y) x + y(1, 2)
   

   As you can see, (1, 2) following x + y actually applies to an inner expression, so instead of calling outer function — and assigning returned value to f2 — f2 is being assigned a function that has x + y(1, 2) as its body. Something to be aware of.

7. How does EC work with ES5 accessor syntax (let’s try getter first)?

   Works!

   
   var obj = ({ get foo() 1 });
   obj.foo; // 1
   

8. How about setter?

   Works!

   
   var _x;
   var obj = ({ set foo(x) _x = x });
   obj.foo = 5;
   
   _x; // 5
   

9. How about both?

   Works as well! Well, why wouldn’t it…

   
     var _x = 'initial value';
     var obj = ({ get foo() _x, set foo(x) _x = x });
     obj.foo; // 'initial value'
   
     obj.foo = 'overwritten value';
     obj.foo; // 'overwritten value'
   

10. Can we confuse parser with a comma?

    Yes we can.

    
      ({ set foo(x) bar = 1, baz = 2 }); // SyntaxError
    

    In this case, we might want bar = 1, baz = 2 as an expression inside a function, but instead, comma is parsed as part of an object intializer. Wrapping expression in parenthesis would solve this problem, of course.

    
      ({ set foo(x) (bar = 1, baz = 2) });
    

11. Are statements allowed in function body of a function created via EC?

    No.

    
      var f = function() if (true) "foo"; // Error
    

    This is pretty understandable, considering that expression after function() in EC is treated as an expression inside return statement. And return statement obviously can’t contain other statements (only expressions). Fortunately, there’s always a ternary operator to take care of cases like this:

    
      var f = function() someCondition ? "foo" : "bar";
    

12. Can body of a function created via EC be omitted?

    Nope.

    
      function f() // Error
    

    You would think that function f() should be identical to function f(){ return }, but no, empty function body is not allowed there. It’s not clear why this was made like this. Parsing complexities, perhaps?

13. What happens when we include more than 1 expression?

    Only first one is consumed.

    
      function f() alert("1st statement"); alert("2nd statement"); // alerts "2nd statement"
    

The above is parsed as function f() alert("1st statement"); followed by alert("2nd statement"). Only first expression becomes an expression in the return statement of a function.

14. What about automatic semicolon insertion rules?

    Same rules seem to apply.

    
      function foo(x) x
      (function() {
        /* ... */
      })()
    
      foo; // function foo(x) x(function(){ /* ... */})()
    

    A classic example of ASI — function declaration followed by newline and another expression makes for an unexpected behavior. Same rules apply here, and foo function — even though expressed via EC — ends up having function body of x(function(){})() (rather than just x).

15. Is “{” interpreted as a block or an object literal?

    As a block! Overall production essentially matches regular function syntax.

    
      function foo(x) { top: 0, left: 0 } // SyntaxError
    

    You would think that function() { … } is interpreted as function(){ return { … } } but the production rules of “regular” function syntax precede here, and function foo() { top: 0, left: 0 } results in an error. { and } are essentially parsed as a function body (and top: 0, left: 0 as function body contents).

16. What if it’s an expression?

    Same thing. Treated as regular function syntax.

    
      (function(x, y) { left: x, top: y }) // SyntaxError
    

    You need to be careful to wrap returning object with parenthesis, so that curly braces aren’t considered to be part of a function production. In this case — left: x, top: y results in an error. But if returned object only contains one value, or no value at all, the silent behavior can make for an unexpected behavior down the road:

    
      (function() { x: 1 } )(); // returns `undefined`
      (function() ({ x: 1 }) )(); // Expression Closure; returns object with x=1
    
      (function() {} )(); // returns `undefined`
      (function() ({}) )(); // Expression Closure; returns object
    

17. Can we make function explicitly strict?

    No.

    
      function foo(x, y) "use strict"; 1 + 1;
      typeof foo(); // "string" (not "number")
    

    This obviously doesn’t work; “use strict” — which is a strict directive that’s supposed to make function behave as per ES5 strict mode rules — doesn’t behave in any special way. It’s simply treated as a string literal and so resulting function becomes identical to function foo(){ return “use strict”; } (followed by a useless 1 + 1 statement).

(This file was used for testing)

Main features

Well that was fun. To summarize some of the main traits:

1. Function body should always be present
2. Only first expression is consumed by an implicit return statement
3. Can be used in place of both — function declaration and function expression (named or anonymous)
4. function idopt (argsopt) expr is not fully identical to function idopt (argsopt) { return expr } (depends on context)
5. Precedence of call expression can be not obvious. For example: (function()x+y)() vs. function()x+y()

Practical?

To my knowledge, expression closures are currently only supported by Mozilla-based browsers. They also aren’t supported by tools like Google Closure Compiler or YUI Compressor, which certainly makes it challenging to use them in production.

It’s not clear if more implementations will join Mozilla and add support for these shortcuts. Could they be part of an experimental road to Harmony (and its shorter function syntax) — the next version of the ECMAScript language? Do you already use expression closures in your work/experiments, or perhaps planning to? And would you change anything in their behavior?

• How eval works
• Eval’ing in global scope
  • Indirect eval call. Theory.
    • Indirect eval call examples.
  • Indirect eval call. In practice.
  • window.execScript
  • window.eval
    • eval context in webkit
  • new Function
  • setTimeout
  • Script insertion
• The problem with `window.execScript || eval`
• Feature testing -based approach
• Global eval in libraries
• Summary

David Flanagan recently wrote about global eval() in Javascript, proposing a simple one-liner like this:

  var geval = this.execScript || eval;

Even though it looked beautifully simple, it wasn’t the best cross-browser solution I could think of. Moreover, it’s not something I would recommend. Pondering a bit more on this subject, I realized that there are actually quite a few ways to evaluate code in global scope in Javascript. Some of those ways — e.g. indirect eval — are also not understood very well, and their implications are not immediately visible. David pointed out to me — in one of the comments — that “indirect eval” is not a well-known idiom except in close circles of implementors. And he was right. There was in fact tons of confusion on the subject of global eval, all over the web.

In hope of making the situation clearer, I’d like to go over “global eval” options, taking a look at how and why they work. I’ll also explain some of the problems with the above-mentioned one-line solution.

How eval works

Before going further, let’s define “global eval” as a way to evaluate code in global scope. Simple as that.

The reason for all this fuss about evaluating code in global scope is because global, built-in eval function evaluates code in the scope of a caller:

  var x = 'outer';
  (function() {
    var x = 'inner';
    eval('x'); // "inner"
  })();

This behavior is described very clearly in both — ES3 and ES5:

[...]
The scope chain is initialised to contain the same objects, in the same order, as the calling context’s scope chain. This includes objects added to the calling context’s scope chain by with statements and catch clauses.
[...]

— 10.2.2 Eval Code [ES3]

In ES5, things are a bit more complicated interesting. The behavior of eval depends on 2 things — whether it is a direct or indirect call and whether invocation happens in strict mode. Don’t worry if you don’t know what “indirect call” is — we’ll take a look at it very soon. When talking about non-strict, direct eval call (i.e. good old eval(...) invocation) the outcome is exactly the same as in ES3 — code is executed in the scope of a caller.

[...]
b. Set the LexicalEnvironment to the same value as the LexicalEnvironment of the calling execution context.
[...]

— 10.4.2 Entering Eval Code [ES5]

Eval’ing in global scope

So native eval doesn’t allow to execute code globally. What to do? Let’s first take a look at some of the options, then try to distill them into a cross-browser solution.

Indirect eval call. Theory.

I mentioned “indirect eval call” before, when explaining behavior of eval in ES5. The reason indirect eval is of interest is because in ES5 it actually does execute code globally. Bingo! But what does it even mean — “indirect eval call”. Indirect eval call is simply any eval call that’s not a direct eval call. And direct eval call is defined as:

A direct call to the eval function is one that is expressed as a CallExpression that meets the following two conditions:

The Reference that is the result of evaluating the MemberExpression in the CallExpression has an environment record as its base value and its reference name is “eval”.

The result of calling the abstract operation GetValue with that Reference as the argument is the standard builtin function defined in 15.1.2.1.

— 15.1.2.1.1 Direct Call to Eval [ES5]

That might sound a bit cryptic, but it’s actually very simple. What specification is trying to tell is that eval('1+1') is a direct call, but (1,eval)('1+1') is not. If we were to dissect first expression — eval('1+1') — syntactically, we would see that it’s really just a CallExpression, which consists of a MemberExpression (eval) followed by Arguments ('(1+1)'), and in which MemberExpression consists of “eval” Identifier:

    eval             ( '1+1' )
  |______|
  Identifier

  |______|          |________|
  MemberExpression  Arguments

  |__________________________|
  CallExpression

This is, more or less, a signature of a direct call. ES3 has a slightly simpler definition, and the one that’s pretty much identical to the graphic above:

“[…] any way other than a direct call (that is, other than by the explicit use of its name as an Identifier which is the MemberExpression in a CallExpression) […]”

— 15.1.2.1 eval(x) [ES3]

So eval('1+1') is a direct eval call, but (1,eval)(‘1+1’) is not. Since the latter one is not a direct call, it is therefore an indirect eval call. Let’s take a look at it in more detail:

  (     1        ,         eval  )        ( '1+1' )
     |____|   |_____|    |_____|
     Literal  Operator   Identifier

     |_________________________|
     Expression

  |______________________________|
  PrimaryExpression

  |______________________________|        |________|
  MemberExpression                        Arguments

  |________________________________________________|
  CallExpression

In the above example, the part before Arguments (invocation parens) clearly doesn’t consist of just “eval” identifier. There’s a whole other expression, consisting of comma operator, numeric literal, and only then “eval” identifier. 1,eval — based on how comma operator works — still evaluates to a standard, built-in eval function, but overall expression is no longer a direct call. It is therefore an indirect eval call.

Indirect eval call examples

If you’re still not quite able to recognize indirect eval calls, these are some of the examples:

(1, eval)('...')
(eval, eval)('...')
(1 ? eval : 0)('...')
(__ = eval)('...')
var e = eval; e('...')
(function(e) { e('...') })(eval)
(function(e) { return e })(eval)('...')
(function() { arguments[0]('...') })(eval)
this.eval('...')
this['eval']('...')
[eval][0]('...')
eval.call(this, '...')
eval('eval')('...')

According to ES5, all of these are indirect calls and should execute code in global scope. I’d love to go over each one of them in more detail, but that would be too much for this post.

Note the var e = eval; e('...') on 5th line.

You can see that this is essentially what David’s solution does — var geval = window.execScript || eval. When geval is executed, geval identifier resolves to a global, built-in eval function, but overall expression does not have “eval” as an Identifier in CallExpression. Instead, there’s “geval” identifier, making this an indirect call and evaluating code globally.

But we’ll get back to that one-liner later, and now let’s take a look at one last, but not least important point about indirect eval call.

Have you noticed how ES5 definition says that eval from CallExpression should evaluate to standard, built-in function? It means that taken out of context, eval('1+1') is not necessarily a direct call. Only when eval actually references standard, built-in function (wasn’t overwritten or shadowed), a call can be considered direct.

  eval = (function(eval) {
    return function(expr) {
      return eval(expr);
    };
  })(eval);

  eval('1+1'); // It looks like a direct call, but really is an indirect one.
               // It's because `eval` resolves to a custom function, rather than standard, built-in one

Now that we looked at a list of indirect calls, how about few examples of direct ones?

  eval('...')
  (eval)('...')
  (((eval)))('...')
  (function() { return eval('...') })()
  eval('eval("...")')
  (function(eval) { return eval('...'); })(eval)
  with({ eval: eval }) eval('...')
  with(window) eval('...')

Looks pretty straightforward, doesn’t it?

But wait a second. Why is it that (eval)('...') and (((eval)))('...') are considered direct calls? Certainly, they don’t adhere to the signature we established earlier — Identifier “eval” within MemberExpression within CallExpression. What’s going on here? Shouldn’t the parenthesis around eval make it an indirect call?

The answer to this tricky question is in the first paragraph of ES5 direct call definition — the fact that “eval” in CallExpression should be a Reference, not a value. During program execution, eval in eval('1+1') expression is nothing but a Reference, and needs to be evaluated to a value. Once it’s evaluated, the value is (most likely) a standard, built-in function object. What happens in previously dissected (1,eval)('1+1') indirect call, is that (1,eval) expression evaluates to a value, not a Reference. Since it doesn’t evaluate to a Reference, it can not be considered a direct eval call.

But what about (eval)('1+1')?

The reason (eval) is considered a direct eval call is because (eval) expression still evaluates to a Reference, not a value. Ditto for ((eval)), (((eval))), and so on. This happens because Grouping Operator — “(” and “)” — does not evaluate its expression. If a Reference is passed to a Grouping operator — “(” and “)” — it still evaluates to a Reference, not a value.

  eval(); // <-- expression to the left of invocation parens — "eval" — evaluates to a Reference
  (eval)(); // <-- expression to the left of invocation parens — "(eval)" — evaluates to a Reference
  (((eval)))(); // <-- expression to the left of invocation parens — "(((eval)))" — evaluates to a Reference
  (1,eval)(); // <-- expression to the left of invocation parens — "(1, eval)" — evaluates to a value
  (eval = eval)(); // <-- expression to the left of invocation parens — "(eval = eval)" — evaluates to a value

Speaking in terms of ECMAScript, this is because both — comma operator (in (1, eval) example) and = operator (in (eval = eval) example) perform GetValue on its operands. As a result, (1, eval) and (eval = eval) evaluate to a value, whereas eval and (eval) — to a Reference.

Hopefully, it is now clear why (eval)('...') and (function(eval){ return eval('...') })(eval) are direct eval calls, but (1, eval)('...') and this.eval('...') aren’t.

Indirect eval call. In practice.

With all the theory of indirect eval behind us, let’s consider practical implications. We already know that ES5 specifies such calls to evaluate code in global scope. There are only 2 things left to consider — ES3 and reality. The fun part starts with ES3, which allows indirect eval calls to throw an error. Not only does ES3 allow for an error, it says nothing about evaluating code in global scope. And what about reality?

It turns out that quite a lot of environments nowadays more or less follow ES5 behavior, evaluating code in global scope. But unfortunately, not all of them.

IE<=8 executes code in the scope of a caller, as if indirect call was direct one. Some versions of Konqueror (~4.3) and Safari <=3.2 do the same thing as IE, evaluating code in the scope of a caller. Older Opera (~9.27) goes even further and actually does throw error, as permitted by a spec. All of this makes indirect eval call (on its own) not a good candidate for a cross-browser “global eval” solution. Not for another few years (when Opera <=9.27, Safari <=3.2 (which is probably still present in earlier iPhones), and other “misbehaving” browsers “disappear”).

Curiously, as of now, even the newest browsers deviate from ES5. Chrome 9, for example, considers this an indirect call — (function(eval){ return eval('x'); })(eval) — which it really isn’t; eval is a reference, it’s part of a MemberExpression within a CallExpression, and evaluates to a standard, built-in function.

Opera 11 and Firefox 4 — both browsers are still in beta for these versions — consider the following expression to be a direct call, even though it doesn’t satisfy all requirements of such (eval doesn’t resolve to a standard, built-in function in this case):

  eval = (function(eval) {
    return function(s) {
      return eval(s)
    };
  })(eval);

  eval('...');

Full ES5 conformance is clearly yet to come (meanwhile, take a look at my simple test suite).

window.execScript

Fortunately for us, there’s a proprietary window.execScript function present in IE. It’s defined to “execute the specified script in the provided language” and allows to execute Javascript code in global scope. It’s not very surprising that Chrome has this function as well; most likely for compatibility reasons. As of today, window.execScript is still present in Chrome 9.

The way window.execScript differs from indirect eval call is that it doesn’t return a value. Actually, it does return value in Chrome, but that value is always null.

  window.execScript('1+1'); // null in Chrome, undefined in IE
  (1,eval)('1+1'); // 2

window.eval

Another, very popular way to execute code in global scope is using window.eval. What’s interesting about it, is that window.eval('...') is often believed to be somehow special when it comes to executing code globally. It’s as if eval called as a property of window object always executes in global scope. The truth is that window.eval('...') is nothing but a… indirect eval call, and is not much different than (1,eval)(‘…’), this.eval('...'), or (eval = eval)('...') when it comes to evaluation.

Not understanding what’s going on, some people unfortunately come up with rather monstrous solutions like eval.call(window, '...'), window.eval.call(window, '...') and even scarier combinations. All of those are, once again, nothing but indirect eval calls. The reason code is executed in global scope is not because eval is called in context of window, but because it’s invoked as an indirect call. eval might as well be a property of foo object, and would still work identically:

  var foo = {
    eval: eval
  };

  foo.eval('...'); // behaviorally identical to `window.eval('...')`
                   // both are indirect calls and so evaluate code in global scope

More confusion can be seen on StackOverflow, where eval is labeled “magic”, and is claimed to somehow lose its magic when aliased — all the symptoms of direct vs. indirect calls.

eval context in webkit

It’s worth mentioning that in some of the WebKit -based browsers — including latest Safari (5) and Chrome (9) — eval throws error when called from within certain context (a.k.a. “this” object). And by “certain context” I mean anything that’s not a window/global object (or at least it seems that way). The error is EvalError: The “this” object passed to eval must be the global object from which eval originated. This is probably done for security reasons.

  window.eval('1+1'); // works
  eval.call(window, '1+1'); // works
  eval.call(null, '1+1'); // works, since eval is invoked with "this" object referencing global object

  eval.call({ }, '1+1'); // EvalError (wrong "this" object)
  [eval][0]('1+1'); // EvalError (wrong "this" object)
  with({ eval: eval }) eval('1+1'); // EvalError (wrong "this" object)

Since all of those calls are indirect ones, such error is allowed by ES3 (see, for example, EvalError — 15.11.6.1)

new Function

Sometimes I see suggestions to use new Function (or just Function) to evaluate code globally:

  Function('return 1+1')(); // 2

This is somewhat misleading.

The code executed from within function created by Function constructor doesn’t really execute in global scope. However, it doesn’t execute in local scope either, which is what probably leads to confusion. Function constructor creates a function whose scope chain consists of nothing but a global scope (preceded with function’s own Activation Object, of course). Any code contained in a function created via Function constructor evaluates in a scope of that function, not in a global scope. However, it’s almost as if code executes globally, since global object is the very next object in the scope chain.

What are the implications of this difference?

Well, for once, any function/variable declarations are performed using created function’s Activation Object as Variable Object. In other words, they are declared local to created function, rather than in a global scope:

  function globalEval(expression) {
    return Function(expression)();
  }

  var x = 'outer';
  (function() {
    var x = 'inner';
    globalEval('alert(x)'); // alerts "outer"
  })();

  // but!

  globalEval('var foo = 1');
  typeof foo; // "undefined" (`foo` was declared within function created by `Function`, not in the global scope)

Another interesting peculiarity of evaluating code via Function('...')() is identifiers leakage. An example of this is "arguments" identifier which resolves to an arguments object, when evaluating code via Function('...')():

  eval('alert(arguments)'); // ReferenceError
  Function('alert(arguments)')(); // alerts representation of an `arguments` object

Function -executed code is a good solution if you wish to avoid executing code locally, but it won’t execute it globally either.

setTimeout

Non-standard (but finally codified in currently draft HTML5) setTimeout is another way to execute code globally — when given code as a string, rather than as a function. The problem with setTimeout, of course, is that it’s asynchronous and that — similarly to window.execScript — it doesn’t return the result of evaluation.

Unfortunately, looking through HTML5 specs, I couldn’t find any mention of the fact that setTimeout should evaluate code in global scope. Hopefully, I missed it; it should certainly be specified.

Script insertion

Finally, in browser environment, there’s always an option of injecting a script element into a document. Contents of that script element are then parsed and executed as a Program in global scope:

  var el = document.createElement('script');
  el.appendChild(document.createTextNode('1+1'));
  document.body.appendChild(el);

As with window.execScript and setTimeout -based solutions, this one doesn’t allow to get meaningful return value (unless some kind of workaround is applied). Script insertion is used by current jQuery (1.4.4) in jQuery.globalEval. It fails to provide a return value, but works in more cross-browser manner than “indirect eval + window.execScript” combination. For example, it works in Safari <=3.2 and in older Opera, in which indirect eval calls fail.

The problem with window.execScript || eval

Let’s get back to this very appealing one-liner, taking a look at some of its problems. Although it seems great in theory, its 2 main downsides can be summarized as:

• Indirect eval is not sufficiently cross-browser; lack of feature-testing
• Non-standard execScript is preferred to standard eval

As you’ve seen before, indirect eval is still quirky across some of the existing browsers. There are also environments where it hasn’t even been tested in — mobile browsers, non-standard platforms, older, rare or unknown browsers, etc. Relying on the fact that indirect eval executes code globally — just because that’s what happens in some of the newer, popular browsers — is rather careless. A much saner strategy is to actually feature test indirect eval call behavior before attempting to use it.

Another problem of one-liner is that window.execScript is tested for existence first, and only when it doesn’t exist, eval is chosen as a fallback. One of the rules of interoperability is that standard features should be preferred over non-standard ones. For example, since window.execScript exists in Chrome, one-liner will end up “using” non-standard (and less-capable) window.execScript rather than standard eval.

Finally, the assumption that if window.execScript doesn’t exist, then indirect eval must be executing code globally (which is what one-liner does) strikes me as rather unsafe.

There are more similarly non-optimal soutions online, where folks seem to be taking trial-and-error approach, not realizing why things work the way they do. Rakesh Pai is bedazzled by the unexplainable difference between eval and window.eval invocations:

I don’t know what Firefox is doing in case 2, and for some reason Safari Nightlies seem to be following it. Maybe it’s just beyond my understanding, but case 2 is not supposed to be different from case 1. Why does case 2 operate in global scope? If window.eval is different from eval, case 3 shouldn’t all have given errors. Someone please help me understand that $hit.

The fact that browsers do not fully conform to ES5 makes things even worse. For example, with(window) eval('...') is considered an indirect call in Chrome 9, even though as per ES5 it is very much a direct one — the “eval” Identifier is within MemberExpression of CallExpression; it’s a Reference, and it resolves to a standard, built-in eval function.

Feature testing -based approach

Creating a more robust version of global eval is not hard.

The idea is similar — use indirect eval, with a fall back on window.execScript. The important difference, however, is that indirect eval is feature-tested and is only used when it’s safe to do so. One potential problem here is that window.execScript is not tested, but is instead assumed to execute code globally. If you find this assumption unsafe, it should be trivial to add feature-test for window.execScript as well.

var globalEval = (function() {

  var isIndirectEvalGlobal = (function(original, Object) {
    try {
      // Does `Object` resolve to a local variable, or to a global, built-in `Object`,
      // reference to which we passed as a first argument?
      return (1,eval)('Object') === original;
    }
    catch(err) {
      // if indirect eval errors out (as allowed per ES3), then just bail out with `false`
      return false;
    }
  })(Object, 123);

  if (isIndirectEvalGlobal) {

    // if indirect eval executes code globally, use it
    return function(expression) {
      return (1,eval)(expression);
    };
  }
  else if (typeof window.execScript !== 'undefined') {

    // if `window.execScript exists`, use it
    return function(expression) {
      return window.execScript(expression);
    };
  }

  // otherwise, globalEval is `undefined` since nothing is returned
})();

The benefit of this kind of implementation is that it enables graceful degradation. You can easily find out if globalEval is available in a current environment (since globalEval would be undefined when none of the 2 solutions are available):

  if (globalEval) {
    /* code can be executed globally */
  }
  else {
    /* use fallback scenario */
  }

Note that — as with any indirect eval / window.execScript approach — globalEval will differ in its ability to return a value, depending on which method was chosen.

Global eval in libraries

So what do some of the popular Javascript libraries do? Which global eval solution do they chose?

As we’ve seen earlier, jQuery sacrifices return value for a more extensive browser support, using script insertion technique in its jQuery.globalEval method.

Prototype.js doesn’t even try to evaluate scripts globally — it uses a good old, direct eval invocation. Instead, Prototype.js warns about ramification of local execution in the documentation.

Dojo choses the infamous window.eval variation, but does something really messed up — it uses indirect eval if eval exists on a global object (which should be true in all ES3-compliant browsers), and falls back on regular eval invocation. This kind of fall back obviously results in code executed locally, which should also happen silently. Dojo’s eval behavior will vary wildly depending on the environment, and has a possibility of uncaught error. On a related, humorous note, I was just as stunned by comments around dojo.eval as David Mark in this message.

Mootools uses window.execScript when present, falling back on script insertion (similar to jQuery). jQuery’s script insertion, however, is more robust than Mootools, as they actually test if it results in evaluation of code.

Fuse.js choses a very elaborate and careful strategy. It tests if indirect eval works as expected (catching an error if any), uses it if it does; if indirect eval is defunct, Fuse falls back on script injection. Unlike jQuery or Mootools, it actually tries to return a value of a code executed via script injection. It does so by wrapping contents of code with eval. An interesting side effect of executing code globally via eval is that function and variable declarations create deletable bindings (which is most likely an insignificant detail).

Summary

So what can we learn from all this?

Hopefully, you now have a true understanding of why eval sometimes executes code in global scope. That window.eval(...) is not very special and is just another form of indirect eval. That behavior of indirect eval is specified differently in ES3 and ES5. That behavior of indirect eval in actual implementations is still often sporadic — partly due to transitioning from ES3 to ES5, partly because of uncaught bugs. You’ve seen that blindly relying on indirect eval is unsafe. That implementations of “global eval” relying on indirect eval should employ feature testing, as with so many other things in cross-browser scripting. Finally, that alternative techniques exist and are used by libraries, such as script injection.

• Why subclass an array?
• Naive approach
• Problems with naive approach
• Special nature of arrays
• Function objects and [[Construct]]
• The importance of array special behavior
• Existing solutions
• ECMAScript 5 accessors to the rescue
• [[Class]] limitations
• Does [[Class]] matter?
• Wrappers. Direct property injection.
• Wrappers. Prototype chain injection.
• Summary

Subclassing an array in Javascript has never been a trivial task. At least for a certain meaning of “subclassing an array”. Curiously, new edition of the language — ECMAScript 5 — still does not allow to fully subclass an array.

Not everything is lost though, and there are few ways ECMAScript 5 makes this task closer to the ideal. However, there are few fundamental issues which prevent true array subclassing from happening.

Let’s talk about that.

Today we’ll take a look at what it means to subclass an array, what some of the existing implementations/workarounds are, and which drawbacks those implementations have; We’ll see what ECMAScript 5 brings to the table, and what those fundamental issues with subclassing are. We’ll also talk about alternative approaches to subclassing an array, such as using wrappers, and get to know their limitations.

But first, what does it mean to subclass an array? And why do we even need it?

Why subclass an array?

We can define “subclassing an array” as the process of creating an object which inherits from native Array object (has Array.prototype in its prototype chain), and follows behavior similar (or identical) to native array.

The last point about behavior similar to native array is actually very important, as we’ll see later on. Having “subclass” of array could be thought of as being able to create an array object, but an object which would inherit not directly from Array, but from another object, and only then from Array.

In other words, we want behavior similar to this:

var sub = new SubArray(1, 2, 3);
sub; // [1, 2, 3]

sub.length; // 3
sub[1]; // 2

sub.push(4);
sub; // [1, 2, 3, 4]

// etc.

sub intanceof SubArray; // true
sub intanceof Array; // true

Note how SubArray constructor creates a sub object identical in its behavior to array (object has “length” property, numeric “0”, “1”, “2” properties, and inherits Array.prototype.* methods). At the same time, it is SubArray that a sub object directly inherits from, not Array.

So what exactly is the purpose of doing all this? Why subclass an array in such way?

There are usually two reasons:

1. Avoid pollution of global Array

Javascript prototypal nature makes it easy to extend all array objects with custom methods. Instead of assigning to direct properties of array objects, it’s much easier and more efficient to assign to array’s “prototype” object (the one that’s usually accessed via Array.prototype).

Array.prototype.last = function () {
  return this[this.length-1];
};
// ...
[1, 2, 3].last(); // 3

However, extending Array.prototype comes with the price; And that price is chance of collisions. When scripts coexist with other scripts in an application, it’s important for those scripts not to conflict with each other. Extending Array.prototype, while tempting and seemingly useful, unfortunately isn’t very safe in a diverse environment. Different scripts can end up defining same-named methods, but with different behavior. Such scenario often leads to inconsistent behavior and hard-to-track errors.

Collisions can happen not only with user-defined code, but also with proprietary methods implemented by environment itself (e.g. Array.prototype.indexOf from JavaScript 1.6, before it was standardized by ES5) or from future standards (e.g. Array.prototype.map, Array.prototype.reduce, etc. — now all part of ES5).

Using constructor function other than native Array — but with same behavior — would allow to avoid such collisions. Instead of extending Array.prototype, another object would be extended (say, SubArray.prototype) and then used to initialize (sub)array objects. Any third party code which depends on methods from Array.prototype would still be able to safely use them.

2. Create data structures naturally inheriting from array

Another reason to subclass an array is to be able to create data structures, which naturally inherit from array; such as Stack, List, Queue, Set, etc. While there are certainly valid use cases for these structures, in this article I will instead focus on the first aspect — reducing chance of collisions. It is somewhat more relevant in context of cross-browser scripting.

Naive approach

Creating objects that inherit from other objects is more or less straightforward in Javascript. We can use well-known clone method:

function clone(obj) {
  function F() { }
  F.prototype = obj;
  return new F();
}

and then set-up inheritance like this:

function Child() { }
Child.prototype = clone(Parent.prototype);

clone might look confusing, but all it does is create an object with another object as nearest ancestor in its prototype chain. It uses intermediate function to avoid executing “parent” constructor. In this example, new Child creates an object with Child.prototype as first object in the prototype chain, Parent.prototype — second, and so on. To visualize, the prototype chain here looks like this:

new Child()
    |
    | [[Prototype]]
    |
    v
Child.prototype
    |
    | [[Prototype]]
    |
    v
Parent.prototype
    |
    | [[Prototype]]
    |
    v
Object.prototype
    |
    | [[Prototype]]
    |
    v
   null

Using clone method is exactly what person attempts when trying to subclass an array for the first time:

function SubArray() {
  // Take any arguments passed to constructor and add them to an instance
  this.push.apply(this, arguments);
}
SubArray.prototype = clone(Array.prototype);

var sub = new SubArray(1, 2, 3);

The approach seems reasonable. After all, the goal is to create an object that inherits from Array, so there’s no reason tried-and-true clone wouldn’t work. Or is there? As with few other things in Javascript, it’s not as trivial as it seems.

Problems with naive approach

So what exactly is wrong with subclassing array using clone method? Let’s take a look at how previously declared SubArray function behaves. We’ll be using native array object alongside, for comparison.

var arr = new Array(1, 2, 3);
var sub = new SubArray(1, 2, 3);

arr.length; // 3
sub.length; // 0 (in IE<8)

arr.length = 2;
sub.length = 2;

arr; // [1, 2]
sub; // [1, 2, 3]

arr[10] = 'foo';
sub[10] = 'foo';

arr.length; // 11
sub.length; // 2

There’s clearly some kind of inconsistency here. Even not counting a bug in IE<8. But what is this strange relation between length and numeric properties in array? And why doesn’t subclassed array behave identical? To understand this, we need to look into what array objects in Javascript really are.

Special nature of arrays

It turns out that arrays in Javascript are almost like plain Object objects, except for one little difference in behavior. The crux of this difference is summarized concisely in one paragraph of specification (15.4):

Array objects give special treatment to a certain class of property names. A property name P (in the form of a string value) is an array index if and only if ToString(ToUint32(P)) is equal to P and ToUint32(P) is not equal to 2^32 - 1. Every Array object has a length property whose value is always a nonnegative integer less than 2^32. The value of the length property is numerically greater than the name of every property whose name is an array index; whenever a property of an Array object is created or changed, other properties are adjusted as necessary to maintain this invariant. Specifically, whenever a property is added whose name is an array index, the length property is changed, if necessary, to be one more than the numeric value of that array index; and whenever the length property is changed, every property whose name is an array index whose value is not smaller than the new length is automatically deleted. This constraint applies only to properties of the Array object itself and is unaffected by length or array index properties that may be inherited from its prototype.

For those allergic to the condensed language of ECMA-262, here’s a short summary.

Array objects treat “numeric” properties in a special way. Whenever such property changes, value of array’s “length” property is adjusted as well; it’s adjusted in such was as to make sure that it is always one more than the greatest numeric (own) property of an array. Similarly, when “length” property is changed, numeric properties are adjusted accordingly (but only those that are larger than value of “length”).

We have already seen relation between numeric properties and length in the previous example, but let’s take a look at it again, step by step:

1) When array object is created, its “length” property is set to a value one more than the largest index of an array.

  var arr = ['x', 'y', 'z'];
  arr.length; // 3 (1 greater than largest index of an array — 2 in this case)

  arr = ['foo'];
  arr.length; // 1 (1 greater than largest index of an array — 0 in this case)

2) When numeric properties change, so does “length” change — to maintain the relationship of being 1 greater than the largest index.

var arr = ['x', 'y'];
arr.length; // 2, as expected

arr[2] = 'z'; // add another numeric property (2) larger than the largest existing one (1)
arr.length; // 3 — length is changed to be 1 greater than (new) largest index (2)

3) When “length” property changes, numeric properties are adjusted in such way so that greatest index is 1 smaller than value of “length”.

var arr = ['x', 'y', 'z'];
arr.length = 2;

arr; // ['x', 'y'] — note how last element (z) is deleted, because being at 2nd index,
     //              it doesn't satisfy criteria of largest index being 1 less than length

arr.length = 4;

arr; // ['x', 'y'] — "increasing" length doesn't affect numeric properties...

arr.join(); // "x,y,," ...but has consequences visible in other cases, such as when using `Array.prototype.join`

arr.push('z');
arr; // ['x', 'y', undefined, undefined, 'z'] — ...or when using `Array.prototype.push`

Now you know the “special” nature of Array objects in Javascript, which is in the relationship between “length” and numeric properties. One little detail we haven’t looked at is that array’s “length” property MUST always have a value of non-negative integer less than 2^32. Whenever this condition is violated, a RangeError is thrown:

var arr = [];
arr.length = Math.pow(2, 32); // RangeError

arr.length; // 0 (length is still 0, as it initially was)

arr.length = Math.pow(2, 32) - 1; // set length to maximum allowed value

arr.length++; // RangeError (when setting length explicitly)
arr.push(1); // RangeError (or when setting length implicitly)

Function objects and [[Construct]]

It should start to make sense why there are discrepancies in behavior of objects created via SubArray and Array functions. Even though SubArray creates an object that inherits from Array.prototype, that object completely lacks array’s special behavior. The SubArray instance is nothing more than a plain Object object (as if it was created via an object literal — { }).

But why does SubArray create an Object object and not an Array object? The core of this issue is in the way functions work in ECMAScript.

When new operator is applied to an object — as in new SubArray — that object’s internal [[Construct]] method is called. In our case, it is [[Construct]] of SubArray function. SubArray — being a native function — has [[Construct]] that’s specified to create a plain Object object, and invoke corresponding function providing newly created object as this value. Any native function, including SubArray, should create an Object object and return it as a result.

Now it’s worth mentioning that it’s possible to sort of supersede return value of [[Construct]] by explicitly returning non-primitive value from constructor function:

function SubArray() {
  this.push.apply(this, arguments);
  return []; // return array object explicitly
}

— but in that case, returned object does NOT inherit from constructor’s “prototype” (SubArray.prototype in this case); neither is constructor function invoked with that object as this value:

var sub = new SubArray(1, 2, 3);

// Object doesn't have 1, 2, 3, as constructor was never called with `this` value referencing returned object
sub; // []

// SubArray is not in the prototype chain of returned object
sub instanceof SubArray; // false

As you can see, creating an object that inherits from Array.prototype is only part of the story. The biggest issue is to preserve the special relation of length and numeric properties. This is why using regular clone approach is not quite up to the task.

The importance of array special behavior

A reasonable question at this point is — “Why does array special behavior matter”? Why would we want to preserve relationship between length and numeric properties when subclassing an array? It turns out that consequences of proper length are not only visible when working with length directly, but also indirectly, when performing other tasks via Array.prototype.* methods.

Take for example Array.prototype.push — a method to append items to the end of array. To determine from which position to start inserting elements into, push retrieves a value of array’s “length”. If length is not preserved properly, elements are inserted at the wrong location:

var arr = ['x', 'y'];
arr.length = 5;
arr.push('z'); // 'z' is inserted at 5th index, since that is what the value of "length" is
arr; // ['x', 'y', undefined, undefined, undefined, 'z']

Take another method — Array.prototype.join. Used to return a representation of an array by concatenating all elements with a separator, Array.prototype.join also uses length property to determine when to stop concatenating values:

var arr = ['x', 'y'];
arr.join(); // "x,y"
arr.length = 5;
arr.join(); // "x,y,,,"

Same goes for Array.prototype.concat — method used to produce a new array by concatenating values passed to concat:

var arr = ['x'];
arr.length = 3;
arr.concat('y'); // ['x', undefined, undefined, 'y']

Finally, the special behavior is often cleverly exploited in other situations, such as to “clear” an array (i.e. delete all of its numeric properties):

var arr = [1, 2, 3];
arr.length = 0;
arr; // [] — setting length to 0 effectively removes all numeric properties (elements) of an array

Existing solutions

Now that we're familiar with the theory, let's see what the situation is with subclassing arrays in practice. There have been few attempts in the past, with various levels of “success”. Here are a couple of most popular ones:

Andrea Giammarchi solution

One of the recent implementations is Stack, by Andrea Giammarchi, which looks like this:

var Stack = (function(){ // (C) Andrea Giammarchi - Mit Style License

  function Stack(length) {
    if (arguments.length === 1 && typeof length === "number") {
      this.length = -1 < length && length === length << 1 >> 1 ? length : this.push(length);
    }
    else if (arguments.length) {
      this.push.apply(this, arguments);
    }
  };

  function Array() { };
  Array.prototype = [];

  Stack.prototype = new Array;
  Stack.prototype.length = 0;
  Stack.prototype.toString = function () {
    return this.slice(0).toString();
  };  

  Stack.prototype.constructor = Stack;
  return Stack;
})();

It's an interesting solution, which mainly works around IE<8 bug with Array.prototype.push and length property. However, as should be obvious by now, it doesn't really solve the problem of maintaining relation between length and numeric properties:

var stack = new Stack('x', 'y');
stack.length;           // 2

// so far so good

stack.push('z');
stack.length;           // 3

// still good

stack[3] = 'foo';
stack.length;           // 3

// not good anymore (length should have been changed to 4)

stack.length = 2;
stack[2];               // 'z'

// still not good (element at 2nd index should have been deleted)

Dean Edwards solution

Another popular solution is by Dean Edwards. This one takes a completely different approach — instead of creating an object that inherits from Array.prototype, an actual Array constructor is "borrowed" from the context of another iframe.

// create an <iframe>
var iframe = document.createElement("iframe");
iframe.style.display = "none";
document.body.appendChild(iframe);

// write a script into the <iframe> and steal its Array object
frames[frames.length - 1].document.write(
  "<script>parent.Array2 = Array;<\/script>";
);

The reason this “works” is due to browsers creating separate execution environments for each frame in a document. Each such environment has a separate set of both — built-in and host objects. Built-in objects include global Array constructor, among others. Array object of one iframe is different from Array object of another iframe. They also don’t have any kind of hierarchical relation:

// assuming that SubArray was borrowed from another iframe

var sub = new SubArray(1, 2, 3);

sub instanceof SubArray; // true
sub instanceof Array; // false
sub instanceof Object; // false

Notice how sub is reported as NOT an instance of Array, and NOT an instance of Object. This is because neither Array, nor Object are anywhere in the prototype chain of sub object. Instead, prototype chain consists of SubArray.prototype, followed by <Object from another iframe>.prototype:

new SubArray()
    |
    | [[Prototype]]
    |
    v
.Array.prototype
    |
    | [[Prototype]]
    |
    v
.Object.prototype
    |
    | [[Prototype]]
    |
    v
   null

This brings us to one “consideration” with this approach — difficulties determining the nature of an object derived from such iframe. It’s no longer possible to determine that an object is an array using instanceof or constructor checks ^[1]:

  // is this object an array?

  sub instanceof Array; // false
  sub.constructor === Array; // false

It is, however, still possible to use [[Class]] check (we’ll talk about [[Class]] later on):

  Object.prototype.toString.call(sub) === '[object Array]'; // true

Another, more inherent, downside of this approach is that it doesn’t work in non-browser environments (or, more precisely, in any environment without support for iframes). This problem is likely to become even bigger, given that server-side Javascript implementations are rising quite fast.

Finally, it was reported that Array borrowing can cause mixed content warning in IE6, among few other minor issues.

Other than that, iframe-based array “subclassing” is free of downsides of solutions like Stack, since we’re dealing with real array objects, and so proper length/indices relation.

ECMAScript 5 accessors to the rescue

But let’s talk about ECMAScript 5, which as I mentioned in the beginning, brings something that helps with subclassing arrays. This “something” is actually nothing but property accessors. These useful language constructs have been present in some popular implementations (SpiderMonkey, JavaScriptCore, and others) as a non-standard extension for quite a while now. They are now standardized by the new edition of the language.

Using accessors, it’s rather trivial to create an Object object with special length/indices relation — relation that’s identical to that of Array objects! And since we already know how to create an object with Array.prototype in its prototype chain, combining these two aspects would allow for a complete emulation of arrays.

There’s one little detail about implementation. Since ECMAScript (including last, 5th version) doesn’t provide any catch-all (aka __noSuchMethod__) mechanism, it’s not possible to change value of length property of an object when numeric property is modified; in other words, we can’t intercept the moment when ‘0’, ‘1’, ‘2’, ‘15’, etc. properties are being set. However, accessors allow us to intercept any read access of length property and return proper value, depending on which numeric properties object has at that moment. This is all we really need.

Here’s an implementation of it, at about 45 lines of code:

var makeSubArray = (function(){

  var MAX_SIGNED_INT_VALUE = Math.pow(2, 32) - 1,
      hasOwnProperty = Object.prototype.hasOwnProperty;

  function ToUint32(value) {
    return value >>> 0;
  }

  function getMaxIndexProperty(object) {
    var maxIndex = -1, isValidProperty;

    for (var prop in object) {

      isValidProperty = (
        String(ToUint32(prop)) === prop &&
        ToUint32(prop) !== MAX_SIGNED_INT_VALUE &&
        hasOwnProperty.call(object, prop));

      if (isValidProperty && prop > maxIndex) {
        maxIndex = prop;
      }
    }
    return maxIndex;
  }

  return function(methods) {
    var length = 0;
    methods = methods || { };

    methods.length = {
      get: function() {
        var maxIndexProperty = +getMaxIndexProperty(this);
        return Math.max(length, maxIndexProperty + 1);
      },
      set: function(value) {
        var constrainedValue = ToUint32(value);
        if (constrainedValue !== +value) {
          throw new RangeError();
        }
        for (var i = constrainedValue, len = this.length; i < len; i++) {
          delete this[i];
        }
        length = constrainedValue;
      }
    };
    methods.toString = {
      value: Array.prototype.join
    };
    return Object.create(Array.prototype, methods);
  };
})();

We can now create “sub arrays” via makeSubArray function. It accepts one argument — an object with methods to add to [[Prototype]] of returned “sub array”.

var subMethods = {
  last: {
    value: function() {
      return this[this.length - 1];
    }
  }
};
var sub = makeSubArray(subMethods);
var sub2 = makeSubArray(subMethods);
// etc.

We can also hide this factory method behind a constructor, to make it similar to Array’s one:

var SubArray = (function() {
  var methods = {
    last: {
      value: function() {
        return this[this.length - 1];
      }
    }
  };
  return function() {
    var arr = makeSubArray(methods);
    if (arguments.length === 1) {
      arr.length = arguments[0];
    }
    else {
      arr.push.apply(arr, arguments);
    }
    return arr;
  };
})();

And then use it as you would use regular Array constructor:

var sub = new SubArray(1, 2, 3);

sub.length; // 3
sub; // [1, 2, 3]

sub.length = 1;
sub; // [1]

sub[10] = 'x';
sub.push(1);

You can find this version of SubArray together with unit tests in Gtihub repository. For brevity, I made this implementation mainly take care of length/indices relation; certain methods (e.g. concat) do not behave identical to Array and need to be implemented accordingly.

[[Class]] limitations

The implementation we have just seen — the one utilizing property accessors — is great. It doesn’t require any host objects (such as iframes); it preserves relation between length and numeric properties; it even disallows out-of-range values for length or indices. All it requires is support for ES5 (or even just Object.create method).

But the dramatic title of this post is not there just for fun. There’s one little detail we’re missing in this otherwise complete implementation. And that detail is proper [[Class]] value — something that ECMAScript still doesn’t give full control over.

I wrote about [[Class]] before, when explaining how to detect arrays. In a nutshell, [[Class]] is an internal property of objects in ECMAScript. Its value is never exposed directly, but can still be inspected using certain methods (e.g. Object.prototype.toString). The usefulness of [[Class]] is that it allows to detect type of objects without relying on instanceof operator or checking object’s constructor — both of which fall short to detect objects from other contexts (e.g. iframes), as we’ve seen earlier.

Now, since objects created by makeSubArray are nothing but plain Object objects (only with special length getters/setters), their [[Class]] is also that of “Object” not an “Array”! We’ve taken care of length/indices relation, we’ve set up Array.prototype inheritance, but there’s no way to change object’s [[Class]] value. And so this solution can not claim to be complete.

Does [[Class]] matter?

You might be wondering — what are the actual implications of these pseudo-array objects having [[Class]] of “Object” not an “Array”. Do we even care? Well, for once, there’s an issue with object detection. Ironically, the solution I proposed to detect arrays relies on [[Class]], and so would fall short with objects like these.

// assuming that `sub` is a pseudo-array
Object.prototype.toString.call(sub) === '[object Array]'; // false

Another, probably more important, implication is that some of the methods in ECMAScript actually rely on [[Class]] value. For example, a well-known Function.prototype.apply accepts an array as its second argument (as well as an arguments object). Section 15.3.4.3 of ES3 says — “if argArray is neither an array nor an arguments object (see 10.1.8), a TypeError exception is thrown”. What this means is that if we pass pseudo-array object as a second argument to apply it will throw TypeError. apply doesn’t know or care if an object inherits from Array.prototype; neither does it care about object implementing special length/indices behavior. All it cares is that object is of proper type — type that we, unfortunately, can not emulate.

// assuming that `sub` is a pseudo-array
someFunction.apply(this, sub); // TypeError

There’s some vagueness in specification on this matter. For example, in Date.prototype.setTime spec says “If the this value is not a Date object, throw a TypeError exception.”, but in Date.prototype.getTime, it uses [[Class]] rather than just “not a Date object” — “If the this value is not an object whose [[Class]] property is “Date”, throw a TypeError exception”.

It’s probably safe to assume that these 2 phrases — “Date object” and “object with [[Class]] of ‘Date’” — have identical meaning. Ditto for “Array object” and “object with [[Class]] of ‘Array’”, as well as others.

Function.prototype.apply is not the only method sensitive to [[Class]] of an object. Array.prototype.concat, for example, follows different algorithm based on whether an object is an array or not (in other words — whether it has [[Class]] of “Array” or not).

// array ([[Class]] == "Array")
var arr = ['x', 'y'];

// object with numeric properties ([[Class]] == "Object")
var obj = { '0': 'x', '1': 'y' };

[1,2,3].concat(arr); // [1, 2, 3, 'x', 'y']
[1,2,3].concat(obj); // [1, 2, 3, { '0': 'x', '1': 'y' }]

As you can see, array values are “flattened”, whereas non-array ones are left as is. It is certainly possible to give these pseudo-arrays custom implementation of concat (and “fix” any other of Array.prototype.* methods), but the problem with Function.prototype.apply can not be solved.

It’s worth mentioning that another downside of accessor-based pseudo-array approach is performance. I haven’t done any tests, but it’s pretty clear that an implementation which has to enumerate over all numeric properties on every access of length property is not going to perform well. This is why I can't recommend this solution for anything other than educational purposes.

Wrappers. Direct property injection.

Realizing a somewhat futile nature of subclassing arrays in Javascript often makes alternative solutions look very attractive. One of such solutions is using wrappers. Wrapper approach avoids setting up inheritance or emulating length/indices relation. Instead, a factory-like function can create a plain Array object, and then augment it directly with any custom methods. Since returned object is an Array one, it maintains proper length/indices relation, as well as [[Class]] of “Array”. It also inherits from Array.prototype, naturally.

function makeSubArray() {
  var arr = [ ];
  arr.push.apply(arr, arguments);
  arr.last = function() {
    return this[this.length - 1];
  };
  return arr;
}

var sub = makeSubArray(1, 2, 3);
sub instanceof Array; // true

sub.length; // 3
sub.last(); // 3

While direct extension of array object is a beautiful, simplistic solution, it’s not without downsides. The main disadvantage is that on each invocation of constructor, an array needs to be extended with N number of methods. The time it takes to create an array is no longer a constant (if methods were on SubArray.prototype), but is directly proportional to the number of methods that need to be added.

Wrappers. Prototype chain injection.

To overcome the problem of “N methods”, another variation of wrappers can be used — the one in which object’s prototype chain is augmented, rather than object itself. Let’s see how this could be done:

function SubArray() { }
SubArray.prototype = new Array;
SubArray.prototype.last = function() {
  return this[this.length - 1];
};

function makeSubArray() {
  var arr = [ ];
  arr.push.apply(arr, arguments);
  arr.__proto__ = SubArray.prototype;
  return arr;
}

The idea is simple. When makeSubArray function is executed, two things happen: 1) an array object is created and is populated with any passed arguments; 2) object’s prototype chain is augmented in such way so that next object is SubArray.prototype, not original Array.prototype. The augmentation of prototype chain is done via non-standard __proto__ property.

But what happens in makeSubArray function is of course only half of the story. To make sure that object has Array.prototype in its prototype chain, we need to make SubArray.prototype inherit from it. This is exactly what’s being done on a second line of this snippet (SubArray.prototype = new Array). Prototype chain of an object returned from makeSubArray now looks like this:

new SubArray()
    |
    | [[Prototype]]
    |
    v
SubArray.prototype
    |
    | [[Prototype]]
    |
    v
Array.prototype
    |
    | [[Prototype]]
    |
    v
Object.prototype
    |
    | [[Prototype]]
    |
    v
   null

And because returned object is actually an Array, not an Object one, we also get length/indices relation as well as proper [[Class]] value. In fact, we can go even further and move initialization logic into SubArray constructor itself:

function SubArray() {
  var arr = [ ];
  arr.push.apply(arr, arguments);
  arr.__proto__ = SubArray.prototype;
  return arr;
}
SubArray.prototype = new Array;
SubArray.prototype.last = function() {
  return this[this.length - 1];
};

var sub = new SubArray(1, 2, 3);

sub instanceof SubArray; // true
sub instanceof Array; // true

Even though augmenting prototype chain is a more performant solution, there’s a clear downside — it relies on non-standard __proto__ property. ECMAScript, unfortunately, does not allow to set [[Prototype]] of an object — internal property referencing immediate ancestor in its prototype chain. Not even in 5th edition. Even though __proto__ is supported by a rather large number of implementations, it is far from being truly compatible.

Summary

So here it is; all the fun intricacies of subclassing arrays in Javascript.

We’ve seen that contrary to what might seem, actual inheritance is by far not the only aspect of subclassing arrays in Javascript; that arrays are different from regular objects by having special length/indices relation; how this length/indices relation is important and has nothing to do with prototype chain of an object; how arrays have special [[Class]] value of “Array” which is also rather important, and isn’t inherited either; how it’s not possible to change [[Class]] value of an object — not even in ECMAScript 5. We looked at different ways to “subclass” an array, starting from borrowing Array constructors from other contexts, and ending with augmentation of prototype chain. We examined benefits and downsides of each one of those solutions.

What we haven’t touched upon is the performance metrics of each of the implementations — perhaps a good topic for another discussion.

On this note, I leave you with a table summarizing pros/cons of the above mentioned techniques.

^[1] Whether this endeavor is something worth pursuing is a topic for another discussion

P.S. Big thanks to John David Dalton for reviewing an article and giving useful suggestions.

ECMAScript 5 and JScript

The big news is that IE9pre3 has (almost) full support for ES5. By “full support”, I mean that it implements majority of new API, such as Object.create, Object.defineProperty, String.prototype.trim, Array.isArray, Date.now, and many other additions. As of now, IE9 implements the largest number of new methods; even more than latest Chrome, Safari and Firefox. Unbelievable, isn’t it? :)

You can see the results in this compatibility table (note that it lists results of mere “existence” testing, not any kind of conformance).

What’s missing is strict mode, which actually isn’t implemented in any of the browsers yet.

Some of the things I noticed:

ES5 Object.getPrototypeOf on host objects seems to lie, always returning null instead of proper value of [[Prototype]]:

  Object.getPrototypeOf(document.body); // null
  Object.getPrototypeOf(document); // null
  Object.getPrototypeOf(alert); // null
  Object.getPrototypeOf(document.childNodes); // null

This doesn’t happen in other browsers that implement Object.create at the moment, such as latest Chrome, WebKit or Firefox. In Chrome, for example:

  Object.getPrototypeOf(document.body) === HTMLBodyElement.prototype;
  Object.getPrototypeOf(document) === HTMLDocument.prototype;
  Object.getPrototypeOf(alert) === Function.prototype;
  Object.getPrototypeOf(document.childNodes) === NodeList.prototype

… and so on.

Interestingly, bound functions in IE9pre3 are represented as “function(){ [native code] }”, similar to host objects:

  var bound = (function f(x, y){ return this; }).bind({ x: 1 });
  bound + ''; // "function(){ [native code] }"

  // compare to

  alert + ''; // "function alert(){ [native code] }"

Note how function representation does not include identifier (f), parameters (x and y), nor representation of function body (return this;). This of course proves once again that relying on function decompilation is NOT a good idea.

Whitespace character class (as in /\s/) still doesn’t match majority of whitespace characters (as defined by specs). These include “U+00A0”, “U+2000” to “U+200A”, “U+3000”, etc. The test is available here. Curiously, ES5 String.prototype.trim seems to “understand” those characters as whitespace very well, producing empty string — as expected — for something like '\u00A0'.trim().

It was nice to see that ES5 Array.isArray is about 20 times faster than custom implementation, such as this one:

  function isArray(o) {
    return Object.prototype.toString.call(o) === "[object Array]";
  }

The difference in speed is similar to other browsers that implement this method.

An infamous, 10+ year-old JScript NFE bug, which I described at length before, is finally fixed:

  var f = function g() { return f === g; };
  typeof g; // "undefined"

  f(); // true

arguments’ [[Class]] is now an “Arguments”, just like ES5 specifies it:

  var args = (function(){ return arguments; })();
  Object.prototype.toString.call(args); // "[object Arguments]"

DOM

Unfortunately, the entire host objects infrastructure still looks very similar to the one from IE8. Host objects don’t inherit from Object.prototype, don’t report proper typeof, and don’t even have basic properties like “length” or “prototype”, which all function objects must have:

  alert instanceof Object; // false
  typeof alert; // "object"
  alert.length; // undefined

Because they don’t inherit from Object.prototype, we don’t have any of Object.prototype methods, naturally:

  alert.toString; // undefined
  alert.constructor; // undefined
  alert.hasOwnProperty; undefined

Object.prototype is not the only object host methods fail to inherit from. In majority of modern browsers, host objects also inherit from Function.prototype and so have Function.prototype methods like call and apply. This doesn’t happen in IE9pre3.

  alert instanceof Function; // false
  document.createElement instanceof Function; // false

  alert.call; // undefined

Curiously, call and apply are present on some host objects, but they are still not inherited from Function.prototype:

  typeof document.createElement.call; // "function"
  document.createElement.call === Function.prototype.call; // false

Host objects’ [[Class]] is far from ideal as well. IE9pre3 actually violates ES5, which says that objects implementing [[Call]] (or in other words — are callable) should have [[Class]] of “Function” — even if they are host objects. In IE9pre3, alert is a callable host object, yet it reports its [[Class]] as “Object” not “Function”. Not good.

  Object.prototype.toString.call(alert); // "[object Object]"
  Object.prototype.toString.call(document.createElement); // "[object Object]"

IE9pre3 still messes up DOM objects’ attributes and properties, although not as badly as earlier versions:

  var el = document.createElement('p');
  el.setAttribute('x', 'y');
  el.x; // 'y'

  el.foobarbaz = 'moo';
  el.hasAttribute('foobarbaz'); // true
  el.getAttribute('foobarbaz'); // 'moo'

Some old, humorous bugs can still be seen in IE9pre3, such as methods returning “string” when applied typeof on:

  typeof Option.create; // "string"
  typeof Image.create; // "string"
  typeof document.childNodes.item; // "string"

Undeclared assignments still throw error when same-id’ed elements are present in DOM, however not with same-name’ed elements (as it was in previous versions):

  
  ...
  

Similarly to IE8, only Element and specific element type interfaces (HTMLDivElement, HTMLScriptElement, HTMLSpanElement, etc.) are exposed as same-named global properties. Node and HTMLElement are still missing, and element’s prototype chain most likely still looks like this:

  document.createElement('div');
    |
    | [[Prototype]]
    v
  HTMLDivElement.prototype
    |
    | [[Prototype]]
    v
  Element.prototype
    |
    | [[Prototype]]
    v
  null

…rather than what can be seen in almost all other modern browsers:

  document.createElement('div');
    |
    | [[Prototype]]
    v
  HTMLDivElement.prototype
    |
    | [[Prototype]]
    v
  HTMLElement.prototype
    |
    | [[Prototype]]
    v
  Element.prototype
    |
    | [[Prototype]]
    v
  Node.prototype
    |
    | [[Prototype]]
    v
  Object.prototype
    |
    | [[Prototype]]
    v
  null

getComputedStyle from DOM Level 2 is still missing, however its value is mysteriously a null, not undefined. The property actually exists on an object, but has a value of null. Hopefully, this is just a placeholder and proper method will be added before final release.

  document.defaultView.getComputedStyle; // null
  'getComputedStyle' in document.defaultView; // true

Array.prototype.slice can now convert certain host objects (e.g. NodeList’s) to arrays — something that majority of modern browsers have been able to do for quite a while:

  Array.prototype.slice.call(document.childNodes) instanceof Array; // true

That’s it for now.

Unfortunately, I don’t have much time to look into these things extensively, at the moment. There might be more updates on twitter.

As always, any corrections, suggestions, and additions are much appreciated.

Or if anyone even cares anymore.

Elements vs. tags

If you look at section 3 of HTML 4.01 — “on SGML and HTML”, there’s an explicit note about elements not being tags. In HTML 4.01,
<p>foo bar</p> is an element, not a tag. An element consists of a start tag, content, and an end tag. In case of <p>foo bar</p>, <p> is a start tag, foo bar is content, and </p> is an end tag.

In other words, elements consist of tags.

Optional tags

The distinction between tags and elements becomes slightly less clear once we start dealing with elements that have optional tags, as defined by HTML 4.01. For example, <p> or <td> elements don’t have to have end tags. They could very well exist without them. When parser finds <p>foo bar in markup, it still creates an element. There’s no end </p> tag, but parser doesn’t really need it; start <p> tag already denotes what kind of element it is.

  <p>foo bar

  <tr>
    <td>baz
    <td>qux
  </tr>

But that’s not all.

Some elements, besides having optional end tags, have empty content model, which means that they can’t have any content at all. And when an element is not allowed to have any content and has an optional tag, it’s called an empty element. Not only are end tags optional in such elements, but they must be completely omitted. These, unfortunately, are not some obscure elements, but are very much useful ones like <br>, <link>, <img>, <input>, <meta> and few others.

What’s interesting is that <br> is still an element, only an element that consists of start tag only. It’s just that its content and end tag must never be present. The fact that <br>, <img> or other empty elements consist of start tags only, makes things rather confusing.

And we’re not even talking about elements with both tags optional — <html>, <head>, <body>. Those could exist without any visible traces at all, and are only created based on the context.

  <html>
    <!--
            There's no HEAD start tag, no HEAD end tag, and no HEAD content here.
            Yet, HEAD element is still created implicilty.
            This happens because content model of HTML element is defined as `head, body`,
            which means that both elements should be present in HTML element in that order.
            As soon as BODY start tag is found, even if HEAD tags are not present,
            HEAD element is created automatically.  -->
    <body>
    ...
    </body>
  </html>

Which confusion?

So which practical implications does this confusion actually have?

For one, saying something like “insert an image after a <p> tag” is ranging from “wrong” to “ambiguous”, since we can’t insert anything but a chunk of text after a <p> tag, and <p> tag can be either a start one (<p>) or an end one (</p>). In this case, a better way would be to say — “insert an <img> tag after a start <p> tag”:

  <p>
    <img ...> <!-- IMG tag is inserted after a start P tag -->
    ...
  </p>

in which case <img> element would become a child of <p> element. Or we could say — “insert an <img> tag after an end <p> tag”:

  <p>
    ...
  </p>
  <img ...> <!-- IMG tag is inserted after an end P tag -->

in which case <img> element would be a sibling following <p> one.

Of course, most of the time, what people really mean by “insert an image after a <P> tag” is a second version. It’s just that “element” is accidentally replaced with a “tag”. An even better way — and the one that avoids mention of tags in the first place — is to say “insert an <IMG> element after a <P> element”. This version leaves no room for incorrect interpretation.

Global confusion

What’s interesting about all this is not so much the finer points of difference between tags and elements, but just how widely this misconception prevails. Google search returns 480,000 results for “div tag”, but only 137,000 for “div element”. For an empty element, such as img, the difference is even scarier — “img tag” returns 959,000 results, while “img element” only 48,200. An element is confused for a tag everywhere, from blogs, articles, and mailing lists to books, references, and frameworks.

• Ruby on Rails uses “tag” in all of its helpers — tag, image_tag, stylesheet_link_tag, etc. — where each of those methods actually insert an element into a document.
• w3schools uses “tag” throughout its entire reference — “<div> tag”, “<abrr> tag”, etc. — to refer to elements.
• hacks.mozilla.org uses tag when talking about HTML5 video element.
• Ajaxian mentions it here and there.
• Books like “High Performance Javascript” explain things in terms of tags, rather than elements.
• and many, many others…

Pedantry or an important distinction?

Once you start thinking about the distinction, edges become somewhat blurry. Are all of the examples above really wrong?

When describing “image_tag”, Ruby on Rails documentation says “Returns an html image tag …”. The returned string — “<img …>” — can actually very well be considered an image (start) tag. Yes, the string represents an element, but since an element is empty, it’s also a string that consists of <img> tag only, and so can probably be called an “image” tag.

At the same time, “javascript_include_tag” already crosses the line of correctness. It still uses “Returns an html script tag”, but already returns a string that can only be considered an element — “<script type=”text/javascript” src=”…”></script>”, since there’s now a start tag, content (empty), and an end tag.

w3schools is just plain wrong ^[1], saying things like “The <div> tag defines a division or a section in an HTML document.” or “The <div> tag is often used to group block-elements to format them with styles.”. Tags do not define division, they represent elements, and it is elements that have certain semantic meaning; in this case — division.

In some of the popular articles, we can find phrases like “… the nearer ancestor of our <footer> tag is the <body> tag …”, in which case it’s pretty clear that “tag” is not the right word at all; Tags can not be ancestors, but elements can.

However, saying that “browser supports <video> tag” is technically not wrong, since browsers supporting <video> element, most definitely can parse and understand <video> tags as well (it is by recognizing video tags that they are able to create video elements in DOM).

Speaking of DOM…

What about DOM?

Before I knew the difference between tags and elements, I would always think in terms of tags when talking about HTML, and in terms of elements when talking about DOM. It just made sense that HTML, being markup language, consists of tags, while HTML DOM — or rather, the document available for scripting — is a tree-like structure consisting of elements, and other kinds of nodes. I knew that browser parses HTML markup (and so tags), and then creates a tree-like structure to represent a document, in which case tags essentially become elements. The fact that elements are not just kinds of nodes, but are also chunks of text in markup seemed very strange when I first found out about it.

It seems that this is exactly how most of the people think about tags vs. elements. Tags exist in HTML (text), and elements – in document (DOM). This would explain why tags prevail in discussions about HTML, or markup in general; and why elements are mostly mentioned in context of scripting, rendering, etc.

Nevertheless, I believe that keeping terminology straight is important. Things should be called as they really are, to avoid the ambiguity that we’ve seen in the previous example. A method named something like forEachTag should not iterate over each element, and vice-versa; technical discussions, articles, and documentation should really strive to use proper terms.

What now?

The attempts at demystification were already made in the past, yet the effect is barely visible. So I wonder — why? Is it too unintuitive to speak in terms of elements in context of HTML, or is this a lack of explanation and exposure of the subject? Does the distinction even matter? Or does it matter in technical discussions only? Does it make sense to distinguish these two entities, or should we just try to infer the exact meaning based on the context, as it seems to be done right now? Are we all simply used to the word “tag”, and don’t care about the difference most of the time?

What do you think?

^[1] …which is not surprising, considering the amount of other misconceptions on that site, such as classifying HTML comments as tags.