(For background, please check out parts 1, 2, and 3 before reading this post.)

One of the problems about private local variables inside closures is that you can’t see them. Well, duh, you might say, that’s what private means after all. Point taken, but there’s one scenario where it would be really nice to be able to check those enclosed (enclosured?) variables: debugging.

Now, I’m not going to get into the whole argument here about debugging versus testing. I’m of the firm belief that you should be writing unit tests as you go along (and I’m only not doing it here because the code I write for these posts is mainly pedagogical in nature). Once you have properly built a supporting unit test structure around your code, it shouldn’t matter what your local variables contain: the unit tests will test your external interfaces and if they work as expected then you’re gold as far as the behavior of your code is concerned. Anyway…

Back to our stopwatch example – the initial simple version. Now, I will admit that, as written, it’s ruddy hard to unit test this little object. That’s because I’m embedding, essentially, a random process in the middle: the current time. To properly test this I should extract out the code snippet that gets the current time (the weird-looking +new Date() statement) and build it in as an external interface that I can then mock. But let’s say I want to debug this code after I’ve called start() and before I call stop(). As written, there’s no way I can inspect the local variable startTime if I’m in a debugger. The stopwatch object is opaque.

Enter the debugger keyword. This is a reserved word in JavaScript and is designed to trigger a program breakpoint when executed. If there is no JavaScript debugger present, it’s just ignored, but if you are running under Firebug or whatever developer tools your browser provides (I use Firefox myself) the debugger will gain control and hand control over to you.

So what, you may say. Whether you have a manual breakpoint or use this fancy debugger statement, you still have the same problem: you can’t see inside the opaque stopwatch object. True. . . unless you execute the debugger statement inside the context of the closure itself.

Let’s add an inspect() method to the stopwatch object:

var stopwatch = (function () {
  var startTime = -1,

  now = function () {
    return +new Date();
  },

  start = function () {
    startTime = now();
  },

  stop = function () {
    if (startTime === -1) {
      return 0;
    }
    var elapsedTime = now() - startTime;
    startTime = -1;
    return elapsedTime;
  },

  inspect = function () {
    debugger;
  };
  
  return {
    start: start,
    stop: stop,
    inspect: inspect
  };
}());

Notice that this new function is inside the closure. If we call stopwatch.inspect() from the Firebug console, for example, the breakpoint will be triggered, and will be triggered inside the context of the closure. We will be able to see the value of startTime (and modify it if required).

In Firebug, you get something that looks like this:

Now the program execution has stopped inside the closure, you can inspect the value of startTime to your heart’s content.

Now, I’ll be the first to recognize that this technique is a little invasive – after all, you have to write this special function and expose it publicly – but it does nicely solve the “I can’t inspect the values of the locals inside my closure/module” problem.

Now that we’ve seen the simple module pattern as well as ways to augment it, we should take a look at one final piece of the puzzle.

Private fields, as we saw in the last installment, can be a real issue. Sometimes, dammit, we’d just like to refer to that private local variable when we’re augmenting a module object. Just a peek you understand, and we’d make it private again immediately we’re done augmenting, so that the code using the module object doesn’t see this private variable. Unfortunately, given the way we’ve implemented privacy through closures this remains a bit of a problem.

Let’s see what we could do given a blank slate. Let’s create an object called secretData and make its properties the internal data we want to save and to share amongst our augmentation code. Obviously, we’d have to make this a normal property so that other code could use it with the augmentation pattern. Here’s the changed stopwatch:

var stopwatch = (function () {
  var $sd = {},

  start = function () {
    $sd.startTime = $sd.now();
  },

  stop = function () {
    var elapsedTime = $sd.peekElapsedTime();
    $sd.startTime = -1;
    return elapsedTime;
  };

  $sd.startTime = -1;

  $sd.now = function () {
    return +new Date();
  };

  $sd.peekElapsedTime = function () {
    if ($sd.startTime === -1) {
      return 0;
    }
    return $sd.now() - $sd.startTime;
  };

  return {
    start: start,
    stop: stop,
    secretData: $sd
  };
}());

Nothing to it so far: for the first change I declare a local variable called $sd and then add startTime and now() to that object. I also refactored the code a little bit so that there’s a new function that can just calculate the elapsed time. Since we’re going to share this behavior, we might as well isolate the complicated calculation into its own function. The returned object now has a new property called secretData (which is anything but, at the moment) which is a reference to this local variable. The local variable is of course hidden by the closure.

Onto the tight augmentation code:

// Augmented stopwatch
var stopwatch = (function (sw) {
  var $sd = sw.secretData;

  $sd.laptimes = [];
  $sd.oldStop = sw.stop;

  sw.stop = function () {
    sw.lap();
    $sd.oldStop();
  };

  sw.lap = function () {
    $sd.laptimes.push($sd.peekElapsedTime());
  };

  sw.reportLaps = function () {
    var laps = $sd.laptimes;
    $sd.laptimes = [];
    return laps;
  };

  return sw;
}(stopwatch));

I first make a copy of the secretData property and then use that copy throughout for any local variables I need in the closure. Other than that, the code for lap() is much simpler (since I’ve made use of the method that returns the elapsed time), as is the overridden stop() method. The returned object still has the very public secretData property of course.

Now the fun bit. After the module object has been finally augmented, we call:

delete stopwatch.secretData;

Whoa. What this does is to delete the secretData property completely. But, notice something else: both closures created by the module pattern have made copies of the secret object already (they both called this copy $sd). The code in the closures still functions just as before since it makes no reference to the secretData property (except when executing the anonymous function to create the closure in the first place). Admittedly with some shenanigans, we’ve created some shared secret data across several closures.

If you don’t like the call to delete there, just create a method in the original unaugmented code (hideSecretData) that “cleans up” the public references to the secret data and call that instead. This makes it a little more more readable:

var stopwatch = (function () {
  var $sd = {},

  start = function () {
    $sd.startTime = $sd.now();
  },

  stop = function () {
    var elapsedTime = $sd.peekElapsedTime();
    $sd.startTime = -1;
    return elapsedTime;
  },
  
  hideSecretData = function () {
    delete this.secretData;
    delete this.hideSecretData;
  };

  $sd.startTime = -1;
  $sd.now = function () {
    return +new Date();
  };
  $sd.peekElapsedTime = function () {
    if ($sd.startTime === -1) {
      return 0;
    }
    return $sd.now() - $sd.startTime;
  };

  return {
    start: start,
    stop: stop,
    secretData: $sd,
    hideSecretData: hideSecretData
  };
}());

and then all you need to call is this to make the intent of the code clearer:

stopwatch.hideSecretData();

After this, not only will the secret data have been hidden, but also the method that hid it will have vanished.

(Part 1, Part 2 of this series.)

Last time I talked about the simple module pattern. This is where you create a function that returns an object with behavior and state and that behavior and state is implemented (and made private) by using a closure. We showed this by using the module pattern to create a stopwatch object.

Let’s now see how we can extend this stopwatch object by adding the facility to have lap times. This gives us the ability to use the same stopwatch to time a sequence of time-consuming actions, rather than creating a new stopwatch every time. The only caveat is that we can’t modify any of the code we’ve already written.

We’ll assume then that we have a new stopwatch object created from the previous code. We need to add a lap() method to record the time since the start or since the last lap. We also need a reportLaps() method that will return an array of lap times. One way to do this would be to create a brand new wrapper object (call it, say, a lapwatch) that uses the already created stopwatch internally as a delegate. In other words, the new lapwatch object would delegate all timings to the internal stopwatch but keep its own lap times. Perfectly doable but it’s hardly extending the original stopwatch object.

What we’ll do is to apply the module pattern again, but this time not to create a new object. Instead we shall augment the existing object. So the first change is to pass in the existing object to our anonymous function.

(function (sw) {

  // some code that operates on sw

}(stopwatch));

We have another auto-executing anonymous function, but this time it takes a single parameter: the stopwatch object. Inside the function, the parameter is known as sw for convenience’ sake. We assume that the as-yet-unwritten code will be modifying sw (and hence the external stopwatch). You could also return sw and re-assign it to stopwatch if you wanted, much like we did previously.

Now we can write the code that provides and reports the lap times.

(function (sw) {
  var laptimes = [];

  sw.lap = function () {
    laptimes.push(sw.stop());
    sw.start();
  };

  sw.reportLaps = function () {
    var laps = laptimes;
    laptimes = [];
    return laps;
  };
}(stopwatch));

As you can see, we have a local array to store the lap times and we add the two new methods to the existing object. The function forms another closure and provides a new private variable. The lap() method is a bit of a hack: since I stipulated that we couldn’t change the original object and since we have no access to the startTime variable, I had to stop the stopwatch to get the elapsed time and then immediately start it again. A better solution perhaps would have been to add a Peek() method to the original code, just so we can see the current elapsed time without stopping the stopwatch.

And here’s some dummy code that exercises this augmented stopwatch:

var i;
stopwatch.start();
for (i = 0; i < 100000; i++);
stopwatch.lap();
for (i = 0; i < 200000; i++);
stopwatch.lap();
for (i = 0; i < 300000; i++);
stopwatch.lap();
console.log(stopwatch.reportLaps());

This pattern is typically known as the Tightly Augmented Module Pattern. We pass in the current object and the function forms another closure over it to modify it. For this code to work we *must* declare the original code first and then this code. If they are in different source code files (the usual case), we must declare the stopwatch code file first, and then this augmented stopwatch code second. That way, the JavaScript interpreter will execute the code in the proper order; the augmentation code won’t get run on an undefined variable.

A slight modification that we can’t really show with our stopwatch example is the Loosely Augmented Module Pattern. With this pattern we’re usually building some kind of utility object or a namespace that contains a whole bunch of other objects that do some work. These other objects don’t require or interact with each other. For example:

var jmbNamepace = (function ($j) {
  $j.date = { ... };
}(jmbNamespace || {}));

--- 

var jmbNamepace = (function ($j) {
  $j.regex = { ... };
}(jmbNamespace || {}));
 
---

var jmbNamepace = (function ($j) {
  $j.url = { ... };
}(jmbNamespace || {}));

Each of these three code segments could be run before any of the others, and each could be omitted, if needed. If they were all in different source files, those source files could be loaded in any order, and only those needed could be loaded. The magic is in the expression jmbNamespace || {}. What this says is “evaluate the expression to be equal to jmbNamespace if it is defined, otherwise evaluate to an empty object”.

Going back to our stopwatch example, notice that there’s something buggy about it. If I’d called stop() on the augmented stopwatch at the end of the last “lap”, the time for it won’t be recorded in the array of lap times. We should allow for this possibility. The way to do this is through an override: we have to override the behavior of stop() if we are using the stopwatch to time laps. Here’s how to do that (and note I’ve changed the definition of the anonymous function to return the augmented stopwatch object to show that this is an equally valid application of the Tightly Augmented Module Pattern):

var stopwatch = (function (sw) {
  var laptimes = [];
  var oldStop = sw.stop;

  sw.stop = function () {
    laptimes.push(oldStop());
  };

  sw.lap = function () {
    sw.stop();
    sw.start();
  };

  sw.reportLaps = function () {
    var laps = laptimes;
    laptimes = [];
    return laps;
  };

  return sw;
}(stopwatch));

The first new thing that happens is that we copy the function object referenced by the stopwatch’s stop() method and save it in the local variable oldStop. (The joys of first-class functions or “functions are objects”!) We then replace the stop() method with a new one that pushes the final lap time onto the array and we call the old stop function to get that final lap time. The lap() method also has to change: we can now just call the stopwatch object’s stop() method to do our work since it’s now rerouted through our override. All these shenanigans are of course hidden from view inside the closure.

Next time we’ll close off this mini-series on the module pattern with some final features.

(Part 1, Part 3 of this series.)

If you recall, JavaScript closures are an extremely powerful concept in the language. By using JavaScript’s rather peculiar scoping rules, closures are a way of creating private variables and functionality for an object. The module pattern builds upon this feature.

A quick recap on scope in JavaScript may be in order. Scope is the means by which programmers limit the visibility and the lifetime of their variables and parameters. Without scope, all variables would be global and visible everywhere. In C#, scope is introduced by braces: you can declare a new variable inside some code in braces — a block — and that variable would not be visible outside the block, and in fact would be destroyed once execution reaches the closing brace. These braces can be the braces surrounding the code in a method, or they can be the braces delineating a block for an if or a for statement, and so on. The essence of scope in C# is: declare a variable inside a block and it won't be visible outside the braces enclosing the block. (For full details about scope in C# you should read section 3.7 of The C# Programming Language (Fourth Edition) by Hejlsberg et al. There’s roughly eight pages of discussion on scope.)

In JavaScript, there is one basic rule: functions define scope. If you declare a variable in a function, it is visible anywhere inside that function, including inside any nested functions, even before it was declared. It is not visible outside the function. Since nested functions are also variables, they will also be visible anywhere in the enclosing function, even before they are declared. In essence, JavaScript hoists all variables to the top of the enclosing function so that they are declared before they are set with a value. This is like the lexical structure of Pascal with its var blocks, except that this hoisting occurs automatically in JavaScript.

Note that by nested functions, I mean functions nested in a lexical sense not in an execution sense. In other words, if function A calls function B, it doesn’t mean that B can suddenly ‘see’ the variables declared in A. For that to happen, B must be coded within the source code for A. It’s the lexical nesting that provides scope.

Let’s see this in code:

var outerFunc = function (paramOuter) {
  // Visible: paramOuter, varOuter
  //          nestedFunc1, nestedFunc2
  var varOuter = 42;

  var nestedFunc1 = function (paramNested1) {
    // Visible: paramOuter, varOuter
    //          nestedFunc1, nestedFunc2
    //          paramNested1, varNested1,
    //          nestedFunc1inner
    var varNested1 = false;

    var nestedFunc1inner = function () {
      // Visible: paramOuter, varOuter
      //          nestedFunc1, nestedFunc2
      //          paramNested1, varNested1,
      //          nestedFunc1inner, inner1
      var inner1 = "hello";

    };
  };

  var nestedFunc2 = function (paramNested2) {
    // Visible: paramOuter, varOuter
    //          nestedFunc1, nestedFunc2
    //          paramNested2, varNested2
    var varNested2 = false;

  };
};

It’s not exactly an example of some edifying code, but it gets the point across. If you look at the nestedFunc1inner function, you can see that all of the variables from the outer function are in scope as well as all the variables from the immediate parent function as well.

The nifty thing about these scoping rules is how well it plays along with closures. A closure encapsulates a function’s environment so that it can continue to exist as an object even after the function terminates. In C#, you see this most of all with lambda expressions and anonymous delegates, but with JavaScript you see it all over the place. jQuery is, in essence, one gigantic closure.

Let’s suppose we have to write a stopwatch object, which we’re going to use to time sections of our JavaScript code. The object should have a start() method that starts the stopwatch ticking, a stop() method to stop the watch (and which should also return the number of milliseconds elapsed). Without closures we’d probably write something like this:

var stopwatch = {
  startTime: -1,

  now: function () {
    return +new Date();
  },

  start: function () {
    this.startTime = this.now();
  },

  stop: function () {
    if (this.startTime === -1) {
      return 0;
    }
    var elapsedTime = this.now() - this.startTime;
    this.startTime = -1;
    return elapsedTime;
  }
};

Notice that I have a helper method called now() (that construction of +new Date() looks too weird in actual code – what does it do again?) as well as an internal field that records the start time of the stopwatch. Unfortunately although this object nicely encapsulated these two members, they are public, fully visible. We have not hidden them. A user of the stopwatch object could access them, change the variable, replace them, whatever. Also, I hate to say it, but all those required references to this doesn’t half obfuscate the code and make it long-winded.

Enter the module pattern. With the module pattern, we create an anonymous function and execute it automatically. The function will return an object that will be our stopwatch object. Let’s look at this step-by step. First we create the outer anonymous function and auto-execute it. For now we’ll have the function return an empty object.

var stopwatch = (function () {
  // other code to be added here
  return {
    // define some fields
  };
}());

Nothing too drastic so far, I’m sure you’ll agree. Now the fun bit starts. Let’s add back the original stopwatch code, altering it so that it makes sense as local variables and nested functions.

var stopwatch = (function () {
  var startTime = -1,

  now = function () {
    return +new Date();
  },

  start = function () {
    startTime = now();
  },

  stop = function () {
    if (startTime === -1) {
      return 0;
    }
    var elapsedTime = now() - startTime;
    startTime = -1;
    return elapsedTime;
  };

  return {
    // define some fields
  };
}());

As you can see all of those annoying this references have gone since there is no enclosing object any more. Instead we can rely on function scope to resolve references to variables. For example, in the start() function we can reference the outer anonymous function’s startTime local variable. For that matter, the same applies to the stop() function. The final step is to make sure that the returned object has the required two methods, start() and stop().

var stopwatch = (function () {
  var startTime = -1,

  now = function () {
    return +new Date();
  },

  start = function () {
    startTime = now();
  },

  stop = function () {
    if (startTime === -1) {
      return 0;
    }
    var elapsedTime = now() - startTime;
    startTime = -1;
    return elapsedTime;
  };

  return {
    start: start,
    stop: stop
  };
}());

The code that creates the new returned object looks a little weird until you read it as “this new object has a stop property whose value is the internal stop() function object, etc.”

The returned object makes use of the closure formed by the anonymous function. The object’s two properties (methods) will call the nested functions inside the closure and those, in turn, will make use of the outer function’s local variable startTime. We’ve essentially created some private members: a local variable and a now() function. These two members are inaccessible outside of the closure.

It must be admitted that the code as written assumes that our stopwatch object is going to be a singleton; after all, we’re auto-executing an anonymous function and it’s hard to do that twice in a row. If you have need of several stopwatches, then the best thing is to assign that anonymous function to a variable called createStopwatch, and then you can call it ad nauseam to create as many stopwatches as you’d like.

var createStopwatch = function () {
  // same code as before
  return {
    start: start,
    stop: stop
  };
};

var stopwatch1 = createStopwatch();
var stopwatch2 = createStopwatch();

Next time, we’ll take a look at how to augment an object created with the module pattern.

(Part 2, Part 3 of this series.)