unscriptable.com » dojo http://unscriptable.com Just another WordPress site Mon, 26 Mar 2012 01:47:11 +0000 en hourly 1 http://wordpress.org/?v=3.3.2 The first annual dojoconf! http://unscriptable.com/2011/09/22/the-first-annual-dojoconf/ http://unscriptable.com/2011/09/22/the-first-annual-dojoconf/#comments Thu, 22 Sep 2011 11:46:06 +0000 John Hann http://unscriptable.com/?p=751 I just got back from the first ever dojoconf in Washington DC. I asked Dylan and Chris if they were planning to do it annually and I got something equivalent to “F**K YEAH!”

Good. cuz it was awesome. :)

I was honored to present about AMD Module Patterns at dojoconf. My slides are here. A half hour is not nearly enough time to present on even a couple of patterns. It didn’t help that I was high on cold medication, so I think I missed half of the points I wanted to make and missed half my slides at the same time. :(

To rectify the situation, I will write a blog post on each pattern. My goal is to write about one pattern a day until they’re all done. Wish me luck. ;)

– John

P.S. This was my first time representing a corporation at a conference. I have been a full-time employee at lifeIMAGE in Newton, MA since August 2010. lifeIMAGE sponsored the Hacker Lounge at dojoconf and paid for the awesome dojo minis! (Btw, we’re always hiring javascript engineers!)

]]> http://unscriptable.com/2011/09/22/the-first-annual-dojoconf/feed/ 0 Bizarro dojo with a slice of cujo.js [updated] http://unscriptable.com/2010/08/19/bizarro-dojo-with-a-slice-of-cujo-js/ http://unscriptable.com/2010/08/19/bizarro-dojo-with-a-slice-of-cujo-js/#comments Thu, 19 Aug 2010 13:25:17 +0000 John Hann http://unscriptable.com/?p=649 Here is the slideshow from my presentation at the Bocoup Loft on August 15th. For some reason, slideshare barfed on it even after I removed all of the video and audio. Srsly, I tried five different variations.
dojo is bizarro jQuery (bocoup)
This presentation is in the QuickTime Presentation format. You must use the space bar or arrow keys to navigate. (I seem to have to click and hit the arrow keys about a dozen times before the presentation starts.)

[update]
I finally got slideshare to accept the slides! Here’s the sideshow.

]]> http://unscriptable.com/2010/08/19/bizarro-dojo-with-a-slice-of-cujo-js/feed/ 0 Firefox’s proposed Resource Packages spec blows! http://unscriptable.com/2010/08/03/firefoxs-proposed-resource-packages-spec-sucks/ http://unscriptable.com/2010/08/03/firefoxs-proposed-resource-packages-spec-sucks/#comments Wed, 04 Aug 2010 04:47:28 +0000 John Hann http://unscriptable.com/?p=634 It’s no secret that one of the keys to a decent user experience is a responsive (fast) user interface. And the most critical component to a fast web app is minimizing the HTTP requests. So it’s no mystery that people are working on ways to solve this problem.

Firefox, of course, is one of the leaders in this area. Their proposal started out fine. Here’s a sample of what it would look like (if you didn’t read the article):

<link rel="resource-package" 
      type="application/zip" 
      href="/static/site-resources.zip"
      content="javascript/jquery.js;
               css/reset.css;
               css/grid.css;
               css/main.css;
               images/save.png;
               images/info.png" />

You specify that the file, /static/site-resources.zip”, contains the listed resources. JavaScript, CSS, and images. (I imagine SWFs and videos would also be options.)

But for some reason, this concise, nearly-valid implementation was trashed in favor of a terse, unfamiliar, and nearly unusable alternative. Here’s what the spec looks like now:

<html packages='[pkg1.zip img1.png script.js styles/style.css]
                [static/pkg2.zip]'>

In this bastardization, the packages are specified as an attribute on the document element (<html> tag). Package definitions in the packages attribute are delimited by square brackets, and the resources within them are delimited by spaces.

WTF? Not only is this ugly and non-standard, but it also has some serious drawbacks. Here’s why:

Reason #1: Any non-trivial web app has hundreds of resources

The spec says that naming the resources is optional. However, not naming them causes the browser to block all further downloads until the resource package is downloaded and unzipped. So to gain optimal performance (not block), we’ve got to list every single resource? Not only is that going to be one hell of a large <html> tag, but it also needs to be maintained every time a new resource is added to the app.

The real answer, of course, is to use a dependency-management and packaging solution. dojo.require and dojo.build do all of the work of resource packaging already. (require.js is a good start at dependency-management for the non-dojo world, but still lacks packaging. Admittedly, dojo only packages javascript and html templates, not css or images. cujo.js will also package css, but still not images.)

With dependency-management, resources are named where they are used, not in some other file. Having to remember to go back and list every resource in every HTML file is nothing short of a maintenance hassle.

But hmmmm. Maybe this is a not as big an issue as I originally thought. If I am using a dependency-management solution, my resource packages would consist of one javascript file, one css file, and a few dozen images. That’s still a lot of image files to maintain, but not as bad as maintaining hundreds of javascript and css files.

One of the reasons the browser needs to block is to allow for overrides. If package, pkg2.zip, has a resource with the same path/name as a resource in a package declared earlier, pkg1.zip, then the resource in pkg2.zip will override (replace) the resource in pkg1.zip. Therefore, the resources in the packages must be delineated — either explicitly or by inspecting the package — before the packages can be used.

Again, this override functionality is just duplicating dependency-management solutions. Object-oriented javascript allows us to override methods and properties. OOCSS allows us to override CSS rules in a different, but equally effective, manner. (cujo.js also allows for HTML template inheritance / overrides (OOHTML?).)

When done properly (small, concise OOJS, OOHTML, and OOCSS files) and combined with dependency-management, the download size should be exactly the same and amount of extra RAM needed by the browser should be small compared to the resource packaging solution.

dojo.require('pkg1'); // base functionality (large)
dojo.require('pkg2'); // overrides (small)

Reason #2: There’s no way to specify a resource package dynamically

This is a non-starter for me. I write client-heavy web apps. These apps are typically long-running and are served to the browser as a single page. In other words, the browser doesn’t load a new page every time the user takes an action. Google Docs and Google Mail are good examples.

Using dojo.require and dojo.build, I can package my apps into as many packages as I like. (They’re called “layers” in dojo.) This is especially important in a few scenarios:

  1. the app will load a package only when needed
  2. the user can switch “theme” packages dynamically
  3. the user can switch language packages dynamically

If Firefox goes forward with the packages attribute on the <html> tag, then I don’t see how this is possible. For example:

var html = document.documentElement,
    myNewPackage = 'pkg3.zip js/myModule.js images/myPng.png';
html.setAttribute('packages', html.getAttribute('packages') + ' [' + myNewPackage + ']');

Even if that did work (which I doubt it would), it would undoubtably be unbearably inefficient. Re-parsing, re-scanning, and re-analyzing every package.

The original proposal did not have this problem. It’s a lot simpler to just add a new <link> tag:

var head = document.documentElement.firstChild, // assumes no comments before head!
    link = document.createElement('link');
link.setAttribute('rel', 'resource-package');
link.setAttribute('type', 'application/zip');
link.setAttribute('href', 'pkg3.zip');
link.setAttribute('contents', 'js/myModule.js; images/myPng.png');
head.appendChild(link);
 
// in dojo:
var head = dojo.query('head')[0];
dojo.create('link', {rel: 'resource-package', type: 'application/zip', href: 'pkg3.zip', contents: 'js/myModule.js; images/myPng.png', head, 'last');

So. Can it be fixed?

Of course. But, frankly, I don’t really care. For us dojo developers, all it’s going to help out with is images. And since we’re using less and less images and more and more CSS3, images aren’t such a big deal going forward. (border-image, border-radius, and gradient, FTW!)

But I guess, for image-heavy apps, there’s still a need. So here’s how I’d fix it:

First of all, abandon that dumb-ass packages attribute. It’s ugly, non-standard, and unworkable for the large apps that really need packaging. Go back to the <link> tag. That was a much better idea.

Or better yet, use the <script> tag. (gasp) And while you’re at it, fix the defer attribute so I can decide whether the package contains any resources that may need to invoke blocking. (It could be a package of non-essential images, for instance.)

Hmmmm…. on second thought, the <link> may be semantically and syntactically better. Therefore, maybe just add the defer attribute (and functionality) to the link tag?

Should it be fixed?

The more I think about the proposed solutions, the more it seems they’re targeted toward trivial web apps/pages. Unfortunately, it’s typically the larger, more sophisticated apps that need the performance boost.

Therefore, I say, why bother?

Instead, let’s find a way to package images and make dependency management a standard feature in javascript!

What do you say? Am I missing something? Do you have a better solution? Please let me know in the comments!

]]> http://unscriptable.com/2010/08/03/firefoxs-proposed-resource-packages-spec-sucks/feed/ 4 Deduplicate any array in Javascript http://unscriptable.com/2009/12/08/deduplicate-any-array-in-javascript/ http://unscriptable.com/2009/12/08/deduplicate-any-array-in-javascript/#comments Tue, 08 Dec 2009 05:04:30 +0000 John Hann http://unscriptable.com/?p=467 I’ve neglected this blog lately. My only excuse is that I am very, very busy! Not only have I been lucky enough to land a great opportunity working with some very bright jQuery Interactive Developers at Molecular, but I’ve also been working on something really big. (More on that later!)

But despite being busy, I felt compelled to post this one. As part of the something really big project, I had to deduplicate a potentially large array of nodes. Dojo doesn’t have a built-in function for deduplication (a.k.a “deduping”). How could it not? Doesn’t everybody have to do this once in a while?

I guess I’ll have to write one. How hard could it be?

It wasn’t because dojo didn’t implement a deduping method that I felt compelled. No, it was the series of events after I wrote my own version. Just after I finished it, one of those smart IDevs at Molecular shared his recent hash map-based implementations that worked only with numbers. Then I noticed that jQuery has a deduping method, unique(). However, it only deduplicates DOM Nodes.

Finally, I ran across this blog post that uses the hash-map method and works only on strings. (Actually, it works on any objects that return unique values from their toString() methods, but that’s not as common as you’d think in Javascript. For example, object literals typically return “[Object object]” from the toString() method.)

It seemed every other implementation used the hash map method and only worked on limited data types. I hate writing the same code twice (unless it’s to improve it), so I decided to write something that works with any data type.

One function to rule them all! (No! Don’t even go there…!)

I probably should have done some research before diving in, but that’s not how I roll. (Where’s the challenge in that?) From previous experience I already knew of at least two ways to do it: a) keeping a hash map of the values (hash map method), or b) pre-sorting the values. The former method (hash map) seemed slower and more memory intensive, so I forged ahead with the second method (pre-sorting).

The pre-sort method works like this:

  1. sort the data items in the array
  2. loop through the sorted data items:
  3. compare each of the data items to the previous one
  4. if the previous is the same as the current, don’t add the current item to the output array

Simple enough!

Here’s the code using dojo to wrap the Javascript 1.6 Array iterators:

    function dedup (/* Array */ array, /* Function */ compareFunc, /* Object? */ context, /* Boolean? */ preemptive) {
        //  summary: removes duplicate items from an array. compareFunc should behave
        //      exactly like the lambda function used in array.sort(), returning:
        //       0 - if the two items to compare are equivalent
        //      -1 - if the first item should be sorted to an earlier position than the second
        //       1 - if the first item should be sorted to a later position than the second
        //      Returns an array with no duplicates.
        //      Note: items found later in the array are favored over earlier items. This means
        //      that if am earlier item is found to be a duplicate of an later item, it is not
        //      included in the returned array.  You might ask, "Who cares which one is favored?"
        //      Glad you asked! It depends upon how you define "duplicate". If you wanted to
        //      remove all nodes with duplicate ids, you could supply a compareFunc that inspected
        //      node ids.  The nodes are not identical in this case, just the ids.
        //      If you wish to favor the earlier items, set preemptive = true;
        //      Note: undefined values are omitted from the output array.
        //  array: Array - the array to be deduped
        //  compareFunc: Function - see above
        //  context: Object - context on which to run compareFunc (i.e. the "this" reference from
        //      within compareFunc). defaults to null/window
        //  preemptive: Boolean - set to true to favor earlier occuring items (see above)
        var comparator = function () { return compareFunc.apply(context, arguments); },
            prev,
            keepers = [];
        // by first sorting the array, we know that dups will be adjacent to each other
        dojo.forEach(array.sort(comparator), function (item, pos) {
            if (typeof item != 'undefined') {
                if (typeof prev == 'undefined') {
                    keepers.push(pos);
                }
                else {
                    // is the previous item different from this one?
                    var eq = comparator(prev, item) == 0;
                    if (preemptive) {
                        if (!eq)
                            keepers.push(pos); // add this one
                    }
                    else {
                        if (eq)
                            keepers.pop(); // remove prev one
                        keepers.push(pos); // always add current one (it may be deleted in the next iteration)
                    }
                }
                prev = item;
            }
        });
        return dojo.map(keepers, function (pos) { return array[pos]; });
    }

The dedup() method requires an array (duh) and a comparison function (compareFunc). The comparison function is exactly the same function you’d pass to sort an array. Note that it’s run twice: once to sort the array and once to test if the previous value is the same as the current value.

The context parameter is useful if you need to pull in other data for compareFunc to do its job in the context of some object. For even more control over which duplicate instances are kept, you can use the preemptive parameter. Set this to true to keep items that occur earlier in the array.

I can see some people scratching their heads. Why does it matter which item we keep if they’re duplicates of each other? Well, nobody said they had to be exact duplicates! For instance, maybe you want to reduce a table’s rows to only the ones that have unique integer values in their first cell.

And here’s how you’d do that (error-checking omitted for brevity):

var myDedupedRows = dedup(myTable.rows, function (rowA, rowB) {
    // it's important to use a comparison that works correctly in Array sort() for best efficiency!
    return parseInt(rowA.cells[0].innerHTML) - parseInt(rowB.cells[0].innerHTML);
});

That’s pretty simple if you are already comfortable with writing lambda functions for the sort method, of course.

Deduping numbers:

var uniques = dedup(arrayOfNumberIDs, function (idA, idB) {
    return idA - idB;
});

Deduping object instances:

var uniques = dedup(myObjects, function (objA, objB) {
    // this works for numbers, strings, dates... but don't mix types!
    return objA.keyProperty - objB.keyProperty;
});

Deduping object instances that have multiple key properties:

var uniques = dedup(myObjects, function (objA, objB) {
    var test = objA.keyProperty - objB.keyProperty;
    if (test == 0) // keyProperty is the same, so dig deeper
        return objA.altKey - objB.altKey;
    else
        return test;
});

Deduping numbers the safe way:

var uniques = dedup(arrayOfNumberIDs, function (idA, idB) {
    // force to numbers in case we have strings by accident
    return parseFloat(idA) - parseFloat(idB);
});

At first glance, the pre-sort method looks more complex than the hash map methods, but it’s really not. Once you take out the code that skips undefined values (like all good array iterators should) and the code to allow the preemptive functionality, it’s only a line or two longer.

How about memory usage? Hm. My assumption that my method would use less memory wasn’t as accurate as I thought. In the hash map methods, a temporary array and a hash-map of the non-redundant values are created. In my pre-sort method, a complete copy of the original array and a copy of the deduped array are created. This could go either way, depending on how large the original array is and on how Javascript engines internally manage hash maps (object literals, actually), but it’s likely that the pre-sort has a larger memory footprint. (It’s likely that the Javascript engines create internal data structures to speed-up property look-ups on object literals. However, it’s certain that the engines pre-allocate several kilobytes of space for array items. I’ll bet they allocate a minimum of 16kB per array created.)

Finally, I’m hesitant to claim any performance prizes, either. I assume that since the compareFunc is run at least twice for each item in the array, it’s a performance bottleneck. The hash map methods don’t do much in Javascript besides the loops. The rest is run inside compiled code under the hood of the Javascript engine.

But maybe that’s the price for creating a function that dedups anything?

I’m too lazy busy to test any of my assumptions, but if you are intrigued or bored, please have at it!

And be sure to post any feedback! Did I miss something? Did I make a stoopid mistake? Can you write a version that falls back to the hash map method when using simple data types (and therefore doesn’t need compareFunc)?

What? You don’t use dojo?!?! ;) A jQuery port should be brain-dead simple (s/dojo.forEach/$.each/ and s/dojo.map/$.map/). Here’s a version that replaces the dojo calls with Javascript 1.6 array iterators. (Note: Javascript 1.6 array iterators work in recent browsers only!)

    function dedup (array, compareFunc, context, preemptive) {
        var comparator = function () { return compareFunc.apply(context, arguments); },
            prev,
            keepers = [];
        array.sort(comparator).forEach(function (item, pos) {
            if (typeof item != 'undefined') {
                if (typeof prev == 'undefined') {
                    keepers.push(pos);
                }
                else {
                    var eq = comparator(prev, item) == 0;
                    if (preemptive) {
                        if (!eq)
                            keepers.push(pos);
                    }
                    else {
                        if (eq)
                            keepers.pop();
                        keepers.push(pos);
                    }
                }
                prev = item;
            }
        });
        return keepers.map(function (pos) { return array[pos]; });
    }
]]> http://unscriptable.com/2009/12/08/deduplicate-any-array-in-javascript/feed/ 8 Hi-performance Javascript Tips #3: Less is More [Updated 2009-04-09] http://unscriptable.com/2009/04/09/hi-performance-javascript-tips-3-less-is-more/ http://unscriptable.com/2009/04/09/hi-performance-javascript-tips-3-less-is-more/#comments Thu, 09 Apr 2009 07:02:52 +0000 John Hann http://unscriptable.com/?p=250 This should really be Tip #1 since it’s the most critical of all. Let me just say this as clearly as possible:

Your fastest Javascript projects are the ones that have the least Javascript!

Sure, Javascript engines have matured. Safari’s Nitro, Chrome’s V8, Firefox’s TraceMonkey, and Opera’s Carackan all kick some serious butt. (IE8′s JScript, unfortunately, still sucks wind.) However, routines written in C++ still run orders of magnitude faster in most cases.

Don’t write Javascript to do something your browser already does at compiled-code speeds.

Do you have any idea now many person-years of effort went into the regular expressions engine in your browser? Tap into that resource!

Here are some other resources you may be under-utilizing:

  • Array.prototype.join (example)
  • Array.prototype.slice (example)
  • RegExp (many string-related optimizations!)
  • Array iterators
  • DOM selectors (such as Acme (dojo) and Sizzle)

I’ll dive into each of these in later blog posts, but here’s a teaser. This example shows how to replace a relatively slow while loop with an Array iterator.

Our while loop:

var nodes = dojo.query('*[title]'), // using dojo just as an example
    found, // we're looking for a particular node and will store it here
    len = nodes.length, // performance boost to grab this outside of the loop
    i = 0; // just an iteration counter
 
while (!found && i < len) {
    // found will remain false until we find our node
    found = nodes[i].getAttribute('title').indexOf('Loading') >= 0 && nodes[i];
    i++;
}
if (found) {
    // do something with <<found>> here
}

That’s not a bad while loop. You’ll notice that I am overloading the meaning of the found variable. This is an acceptable practice in high-performance situations as long as the code is well-documented to prevent confusion.

Here’s the same loop utilizing the Array iterator some wrapped by dojo NodeList’s some method:

var found; // we're looking for a particular node and will store it here
dojo.query('*[title]').some(function (node) {
    // found will remain false until we find our node
    found = node.getAttribute('title').indexOf('Loading') >= 0 && node;
    return found;
});
if (found) {
    // do something with <<found>> here
}

Leaner! Faster! Sexier!

OK. Here’s the point where I scratch my head. I just ran both of these against dojocampus.org in FF 3.1 and Safari 4.0. To my surprise, the while loop performed slightly better than the some (1ms difference). I removed the [title] attribute from the query selector to get some better test data. Same story.

There was a big difference in IE7, though.

I guess the latest Javascript engines really do kick butt!!!!

Update 2009-04-09:

My best guess is that the NodeList that dojo.query returns is slowing our example code. A NodeList is not a true array. It is an Array-like object, which simply means it exposes its list of items as properties whose names are Cardinal number and also exposes a length property. So I created a quick and dirty test on a true array:

// using some
var a = [];
for(var i = 0; i < 100000; i++) { a[i] = new Date(2009, 1, i); };
var found, s = new Date();
a.some(function (item, i) {
    found = i == 99999 ? item : false;
    return found;
});
console.log((new Date()) - s, found);
 
// using while
var len = a.length, found = false, s = new Date(), i = 0;
while (!found && i < len) {
   found = i == 99999 ? a[i] : false;
    i++;
}
console.log((new Date()) - s, found);

The results showed that some ran about 17% faster in Firefox 3.0, 32% faster in Firefox 3.1beta, and 43% faster in Safari 4.0beta. Of course, the code inside our loop is very simple. More complex code will consume a larger slice of the total time and will therefore make the effect of the loop mechanism less important.

Moral of the story: to get the best performance when looping through real arrays (rather than Nodelists or Array-like objects), use the Array iterators or their browser-safe counterparts in the major libraries. When using NodeLists, either method works great as long as you’ve tuned your loop correctly. (Sounds like another blog post…)

I’d like to hear from you! What library do you use and how does it handle Array iterators?

]]> http://unscriptable.com/2009/04/09/hi-performance-javascript-tips-3-less-is-more/feed/ 0 Debouncing Javascript Methods http://unscriptable.com/2009/03/20/debouncing-javascript-methods/ http://unscriptable.com/2009/03/20/debouncing-javascript-methods/#comments Fri, 20 Mar 2009 07:21:21 +0000 John Hann http://unscriptable.com/?p=7 Back in 2006, I was the lead front-end architect for a mission-critical Web 2.0 application. Yah-yah, aren’t they all mission-critical? Yes, but this one really was critical since it was one of those make-or-break moments for the product. What made this project really interesting were the unrealistic expectations the product managers had of web apps.

Sometimes, pressure like this can lead to creativity and innovation. On this occasion, it helped me reach back in to my electrical engineering coursework to apply a hardware concept to software programming.

Just imagine this:

  1. You are tasked to write the entire Javascript-based framework from scratch, including the core functions (inheritance, declarations, event connections), DOM manipulation and querying, a widget framework, MVC, drag-and-drop, and dozens of custom widgets to boot.
  2. You are given unintuitive and un-web-like requirements to ensure that the app allowed customers to adhere to strict FDA regulations.
  3. The product managers had no experience with web app development so they designed the requirements for a Windows application. You know: modal dialogs, instant retrieval of large amounts of data (as if it were coming straight from the disk), workflows that depended on sequenced calls to/from the back-end systems, etc.

Oh, and did I mention there was a deadline and only two of us were hired to code the entire UI side of the project?

Well, I am always up for a challenge, especially if somebody says, “It can’t be done”. So needless to say, I had to really use my brain on this project.

One of the more interesting requirements was to show the user a summary side-bar of information pertaining to the current field (i.e. the input element that had focus). This side-bar information could be from several kilobytes to more than 100 kB. The data had to be fetched via XHR from the back-end and displayed each time the user entered a new field.

This presented a major problem if the user was keyboard-oriented and preferred to use the Tab key to move from field to field. There could be hundreds of fields on the screen, and a user could simply lean on the Tab key to navigate from one end of the form to the other. If the user were lucky enough to be on a fast network connection and had a fast enough browser, this would go fairly smoothly. However, the server would get absolutely hammered by all of the XHR requests necessary to populate the side-bar!

Luckily, I had handled this situation several times before. A simple setTimeout and a few state variables fixes this problem fairly easily. But there were several of these situations in this project, and I wanted to build something reusable.

The more I thought about it, the more it felt like contact debouncing. Debouncing means to coalesce several temporally close signals into one signal. For example, your computer keyboard does this. Every time you hit a key, the contacts actually bounce a few times, causing several signals to be sent to the circuitry. The circuitry determines that the bouncing has ended when no bounces are detected within a certain period (the “detection period”). Since people can’t really type faster than roughly 10 keys per second, any signals happening within 100 msec of each other, for example, are likely part of the same key press. (In practice, you should at least halve this, so about 50 msec for our keyboard example. I have no idea what keyboards really use, by the way. This is just an illustration.)

Debouncing != Throttling

Whenever I bring up the concept of debouncing, developers try to cast it as just a means of throttling. But that’s not true at all. Throttling is the reduction in rate of a repeating event. Throttling is good for reducing mousemove events to a lesser, manageable rate, for instance.

Debouncing is quite more precise. Debouncing ensures that exactly one signal is sent for an event that may be happening several times — or even several hundreds of times over an extended period. As long as the events are occurring fast enough to happen at least once in every detection period, the signal will not be sent!

Let’s relate this back to our keyboard-oriented user and our huge set of form fields. Throttling here would certainly help. We could reduce the number of XHR requests to a lower rate than the computer’s key repeat rate for sure! However, we’d still be fetching from the back-end more times than necessary, and the occasional re-rendering of the fetched data could temporarily freeze up the browser, deteriorating the user experience.

Debouncing on the other hand could better detect when the user stopped leaning on the keyboard and had arrived at their destination. It’s certainly not perfect. The user still may overshoot their destination, hesitate, and back-track, causing enough delay for the debounce detection period to expire. However, our tests showed that debouncing did a much better job of reducing XHR requests than throttling.

Implementation

The original debounce method was rather large and clunky. I consider it a prototype. A proof of concept. I ended up needing debouncing a few times since that project and rewrote it each time, trying to improve it. I’ve finally devised something that feels good enough to share.

The latest rendition takes two parameters: the detection period (“threshold”) and a Boolean indicating whether the signal should happen at the beginning of the detection period (true) or the end (“execAsap”).

Here it is:

Function.prototype.debounce = function (threshold, execAsap) {
    var func = this, // reference to original function
        timeout; // handle to setTimeout async task (detection period)
    // return the new debounced function which executes the original function only once
    // until the detection period expires
    return function debounced () {
        var obj = this, // reference to original context object
            args = arguments; // arguments at execution time
        // this is the detection function. it will be executed if/when the threshold expires
        function delayed () {
            // if we're executing at the end of the detection period
            if (!execAsap)
                func.apply(obj, args); // execute now
            // clear timeout handle
            timeout = null; 
        };
        // stop any current detection period
        if (timeout)
            clearTimeout(timeout);
        // otherwise, if we're not already waiting and we're executing at the beginning of the detection period
        else if (execAsap)
            func.apply(obj, args); // execute now
        // reset the detection period
        timeout = setTimeout(delayed, threshold || 100); 
    };
}

It works by issuing a setTimeout at the specified detection period. Each time the function is called, the setTimeout is canceled and issued again. This serves as our detection mechanism, but using reverse logic. If/when the setTimeout executes, we know that our function was not called within the detection period.

Wow. It looks rather large with all of those comments. Here is a version without the comments:

Function.prototype.debounce = function (threshold, execAsap) {
 
    var func = this, timeout;
 
    return function debounced () {
        var obj = this, args = arguments;
        function delayed () {
            if (!execAsap)
                func.apply(obj, args);
            timeout = null; 
        };
 
        if (timeout)
            clearTimeout(timeout);
        else if (execAsap)
            func.apply(obj, args);
 
        timeout = setTimeout(delayed, threshold || 100); 
    };
 
}

If you prefer not to augment the native objects, here’s a stand-alone version:

var debounce = function (func, threshold, execAsap) {
 
    var timeout;
 
    return function debounced () {
        var obj = this, args = arguments;
        function delayed () {
            if (!execAsap)
                func.apply(obj, args);
            timeout = null; 
        };
 
        if (timeout)
            clearTimeout(timeout);
        else if (execAsap)
            func.apply(obj, args);
 
        timeout = setTimeout(delayed, threshold || 100); 
    };
 
}

Example uses:

// using debounce in a constructor or initialization function to debounce 
// focus events for a widget (onFocus is the original handler):
    this.debouncedOnFocus = this.onFocus.debounce(500, false);
    this.inputNode.addEventListener('focus', this.debouncedOnFocus, false);
 
 
// to coordinate the debounce of a method for all objects of a certain class, do this:
MyClass.prototype.someMethod = function () {
    /* do something here, but only once */
}.debounce(100, true); // execute at start and use a 100 msec detection period
 
 
// the dojo way to coordinate the debounce of a method for all objects of a certain class
// (using the stand-alone version)
dojo.declare('MyClass', null, {
 
    // other members go here
 
    someMethod: debounce(function () {
        /* do something here, but only once */
    }, 100, true); // execute at start and use a 100 msec detection period
 
});
 
 
// wait until the user is done moving the mouse, then execute
// (using the stand-alone version)
document.onmousemove = debounce(function (e) {
    /* do something here, but only once after mouse cursor stops */
}, 250, false);

Let me know if you find this useful in your projects!

P.S. The mission-critical project was a success!

]]> http://unscriptable.com/2009/03/20/debouncing-javascript-methods/feed/ 17