One very nice thing about JavaScript is it’s support for first-class functions and closures. Crockford calls JavaScript “Lisp in C’s Clothing”. I’m no Lisper, but I enjoy I discovering new tricks or applications of functional programming in JavaScript.
I wanted to hook all the browser’s asynchronous JavaScript “entry points” : events, timers, asynchronous XMLHttpRequests, script tags, and “javascript:” URLs. This article deals with the first two, events and timers.
To do this, I figured I could somehow “wrap” all the callback functions passed to setTimeout(), setInterval(), and addEventListener(). By “wrapped” I mean another function that we specify calls the original function, rather than the original function getting called directly. This allows us do whatever we want right before and after calling the original function, including manipulating the arguments and return value, logging to the console, calling other functions, putting it in a try/catch, etc.
Here’s the implementation of “callbackWrap”, the function that does all the work:
function callbackWrap(object, property, argumentIndex, wrapperFactory, extra) {
var original = object[property];
object[property] = function() {
arguments[argumentIndex] = wrapperFactory(arguments[argumentIndex], extra);
return original.apply(this, arguments);
}
return original;
}
To use it, you need function that takes another function as a parameter and returns a wrapped version of that function which does whatever you want it to. In this case it just prints out “whoooaaaaa:” followed by the “extra” parameter:
function logWrapper(func, extra) {
return function() {
console.log("whoooaaaaa: " + extra);
return func.apply(this, arguments);
}
}
Finally, to actually use this, we call callbackWrap with the object that contains the function we want to wrap, the name of the function property, the index of the callback argument to the function (0 for setTimeout/setInterval, 1 for addEventListener), a wrapper “factory” function, and optionally an extra argument that’s made available (via the closure) to the wrapped function. The extra parameter can be used for any data you need to pass to the wrapper function, or it can be ignored.
Here’s how this would be used on setTimeout, setInterval, and addEventListener on window, Element.prototype and Document.prototype (so it applies to all Elements and Documents):
callbackWrap(window, "setTimeout", 0, logWrapper, "wrapped a window.setTimeout!");
callbackWrap(window, "setInterval", 0, logWrapper, "wrapped a window.setInterval!");
callbackWrap(window, "addEventListener", 1, logWrapper, "wrapped a window.addEventListener!");
callbackWrap(Element.prototype, "addEventListener", 1, logWrapper, "wrapped a Element.addEventListener!");
callbackWrap(Document.prototype, "addEventListener", 1, logWrapper, "wrapped a Document.addEventListener!");
Here’s a live example. (edit: the button example seems to be broken in Firefox)
The first thing callbackWrap does is save the original function (window.setTimeout, for this example) in a local variable, “original”, since we’ll need it later. We then replace the original with a new function. When this new function is called (the new window.setTimeout), we first call the “wrapperMaker” function (“logWrapper” in the example), passing it the callback function, which is the argument at the argumentIndex position, and the optional “extra” argument. That function returns a new function which replaces the original callback argument, before we then call the original function (saved in the local variable “original”) with the same arguments (except the callback is now wrapped).
So really this blog post should have been called “a function that wraps other functions such that all callback functions passed to it are wrapped by yet another function”. There’s two levels of wrapping going on: the original function is wrapped, such that it wraps every callback given to it. If you’re confused I don’t blame you.
Why would I want to do this, you ask? There are a couple scenarios I had in mind, and I’m sure you can think of others.
First, I wanted to catch all uncaught exceptions for a debugging tool I’m working on. Sure, you can assign an error handler to the “onerror” property of the window object, but this only gives you the error name, file name, and line number – I wanted the full exception object to be caught by a try/catch.
Here’s a wrapper that catches all uncaught exceptions and alerts them:
function exceptionWrapper(func, extra) {
return function() {
try {
return func.apply(this, arguments);
} catch (e) {
alert(e);
}
}
}
Second, in Cappuccino we mimic Cocoa’s concept of a “run loop”, but due to the way browsers work the implementation is a bit different. A consequence of this was that we couldn’t automatically call “[[CPRunLoop currentRunLoop] performSelectors];” at the end of each run loop, which is required for various pieces of Cappuccino. If you’ve ever come across a situation where you perform some action but the UI doesn’t update until you move the mouse, it’s probably because performSelectors isn’t being called. This isn’t common, since Cappuccino encapsulates events, XMLHttpRequests, and now timers with CPEvent, CPURLConnection, and CPTimer, respectively. These Cappuccino classes handle calling performSelectors for you. However, if you wanted to integrate with a third party library or use setTimeout, XMLHttpRequest, etc directly, currently you would need to call performSelectors manually. With this new trick we can call it automagically.
Here’s the wrapper that does exactly that (note the inline Objective-J call to “[[CPRunLoop currentRunLoop] performSelectors]”):
function performSelectorsWrapper(func, extra) {
return function() {
var result = func.apply(this, arguments);
return [[CPRunLoop currentRunLoop] performSelectors];
}
}
One minor feature I didn’t demonstrate was that callbackWrap returns the original function that it wrapped. If you need the original for any reason you can save it to some other variable.
callbackWrap could use a few improvements. Currently this breaks on cases where you pass a string instead of a function. A simple check for the argument type, and appropriate handling would solve this (either skipping the wrapping, or compiling the the string with a “new Function()” call). But using strings instead of functions is considered poor practice anyway.
