Modules and Namespaces in JavaScript

JavaScript does not come with support for modules. This blog post examines patterns and APIs that provide such support. It is split into the following parts:

1. Patterns for structuring modules.
2. APIs for loading modules asynchronously.
3. Related reading, background and sources.

1. Patterns for structuring modules

• Namespacing: A top-level module is put into a global variable. That variable is the namespace of the module content.
• Holding content: Each property of the module holds a value.
• Nesting modules: One achieves nesting by putting a module inside another one.

Filling a module with content

    var namespace = {
        func: function() { ... },
        value: 123
    };

    var namespace = {};
    namespace.func = function() { ... };
    namespace.value = 123;

    namespace.func();
    console.log(namespace.value + 44);

1. Object literal.
   • Pro: Elegant syntax.
   • Con: As a single, sometimes very long syntactic construct, it imposes constraints on its contents. One must maintain the opening brace before the content and the closing brace after the content. And one must remember to not add a comma after the last property value. This makes it harder to move content around.
2. Assigning to properties.
   • Con: Redundant repetitions of the namespace identifier.

The Module pattern: private data and initialization

    var namespace = function() {
        // set up private data
        var arr = []; // not visible outside
        for(var i=0; i<4; i++) {
            arr.push(i);
        }
        return {
            // read-only access via getter
            get values() {
                return arr;
            }
        };
    }();
    console.log(namespace.values); // [0,1,2,3]

• Con: Harder to read and harder to figure out what is going on.
• Con: Harder to patch. Every now and then, you can reuse existing code by patching it just a little. Yes, this breaks encapsulation, but it can also be very useful for temporary solutions. The module pattern makes such patching impossible (which may be a feature, depending on your taste).
• Alternative for private data: use a naming convention for private properties, e.g. all properties whose names start with an underscore are private.

    var namespace = {};
    (function(ns) {
        // (set up private data here)
        ns.func = function() { ... };
        ns.value = 123;
    }(namespace));

    var namespace = {};
    (function() {
        // (set up private data here)
        this.func = function() { ... };
        this.value = 123;
    }).call(namespace); // hand in implicit parameter "this"

Referring to sibling properties

    var namespace = {
        _value: 123; // private via naming convention
        getValue: function() {
            return this._value;
        }
        anObject: {
            aMethod: function() {
                // "this" does not point to the module here
            }
        }
    }

    var namespace = {
        _value: 123; // private via naming convention
        getValue: function() {
            return namespace._value;
        }
    }

• Module pattern with object literal: assign the object to a local variable before returning it.
• Module pattern with parameter: the parameter is the custom identifier.

Private data and initialization for properties

    var ns = {
        getValue: function() {
            var arr = []; // not visible outside
            for(var i=0; i<4; i++) {
                arr.push(i);
            }
            return function() { // actual property value
                return arr;
            };
        }()
    };

Types in object literals

• Use an inheritance API where constructor and prototype can be defined simultaneously [4].
• Wrap the two parts of the type in an IIFE:

      var ns = {
          Type: function() {
              var constructor = function() {
                  // ...
              };
              constructor.prototype = {
                  // ...
              };
              return constructor; // value of Type
          }()
      };
  

Managing namespaces

    var namespace = namespace || {};

    var topns = topns || {};
    topns.module1 = {
        // content
    }
    topns.module2 = {
        // content
    }

    YAHOO.namespace("foo.bar");
    YAHOO.foo.bar.doSomething = function() { ... };

2. APIs for loading modules asynchronously

1. The file is downloaded.
2. The file is interpreted.

2.1. RequireJS

CommonJS defines a module format. Unfortunately, it was defined without giving browsers equal footing to other JavaScript environments. Because of that, there are CommonJS spec proposals for Transport formats and an asynchronous require.

RequireJS tries to keep with the spirit of CommonJS, with using string names to refer to dependencies, and to avoid modules defining global objects, but still allow coding a module format that works well natively in the browser. RequireJS implements the Asynchronous Module Definition (formerly Transport/C) proposal.

If you have modules that are in the traditional CommonJS module format, then you can easily convert them to work with RequireJS.

    project-directory/
        project.html
        legacy.js
        scripts/
            main.js
            require.js
            helper/
                util.js

    <!DOCTYPE html>
    <html>
        <head>
            <title>My Sample Project</title>

            <!-- data-main attribute tells require.js to load
                 scripts/main.js after require.js loads. -->
            <script data-main="scripts/main" src="scripts/require.js"></script>
        </head>
        <body>
            <h1>My Sample Project</h1>

        </body>
    </html>

    require(["helper/util", "legacy.js"], function(util) {
        //This function is called when scripts/helper/util.js is loaded.

        require.ready(function() {
            //This function is called when the page is loaded
            //(the DOMContentLoaded event) and when all required
            //scripts are loaded.
        });
    });

• Specify and use internationalization data.
• Load text files (e.g. to be used for HTML templating)
• Use JSONP service results for initial application setup.

2.2. YUI3

    YUI().use('dd', 'anim', function(Y) {
        // Y.DD is available
        // Y.Anim is available
    });

• Provide IDs �dd� and �anim� of the modules you want to load.
• Provide a callback to be invoked once all modules have been loaded.
• The parameter Y of the callback is the YUI namespace. This namespace contains the sub-namespaces DD and Anim for the modules. As you can see, the ID of a module and its namespace are usually different.

    YUI.add('mymodules-mod1',
        function(Y) {
            Y.namespace('mynamespace');
            Y.mynamespace.Mod1 = function() {
                // expose an API
            };
        },
        '0.1.1' // module version
    );

    YUI({
        modules:  {
            yui2_yde_datasource: { // not used below
                fullpath: 'http://yui.yahooapis.com/datasource-min.js'
            },
            yui_flot: {
                fullpath: 'http://bluesmoon.github.com/yui-flot/yui.flot.js'
            }
        }
    }).use('dd', 'yui_flot', function(Y) {
        // do stuff
    });

2.3. Script loaders

• LABjs: a relatively simple script loader. Use it instead of RequireJS if you need to load scripts in a precise order and you don't need to manage module dependencies. Background: �LABjs & RequireJS: Loading JavaScript Resources the Fun Way� describes the differences between LABjs and RequireJS.
• yepnope: A fast script loader that allows you to make the loading of some scripts contingent on the capabilities of the web browser.