Provides the ability to define namespaces in JavaScript.

namespace.js

/* ====== namespace.js ====== */

// Provides the ability to define namespaces in JavaScript.

/**
 * Declares a namespace in JavaScript.
 *
 * This function can be called in one of two ways:
 *
 * namespace(ns, obj)
 *  Declares a namespace, by ensuring that a global variable called ns exists,
 *  and appending all the properties of obj to it.
 *
 * namespace(ns, [usings], fn)
 *  Declares a namespace, by ensuring that a global variable called ns exists,
 *  and calls fn passing it the arguments in usings.
 */

function namespace(ns) {
    "use strict";

    var path = ns.split('.');
    var target = window;
    for (var i = 0; i < path.length; i++) {
        var part = path[i];
        if (target.hasOwnProperty(part)) {
            target = target[part];
        }
        else {
            target = target[part] = {};
        }
    }

    var args, obj;

    switch (arguments.length) {
        case 1:
            return target;
        case 2:
            args = [];
            obj = arguments[1];
            break;
        default:
            args = arguments[1];
            obj = arguments[2];
            break;
    }

    if (typeof obj === "function") {
        obj = obj.apply(target, args);
    }

    for (var key in obj) {
        if (obj.hasOwnProperty(key)) {
            target[key] = obj[key];
        }
    }
    return target;
}

x-namespace-example1.coffee

# An example of how to declare a namespace using namespace.js and CoffeeScript

namespace "My.Namespace", [jQuery], ($) ->
    
    # To add a function to a namespace, simply assign it to a property of this
    
    @showMessage = (msg) ->
        $('#message').html(msg).show()

    # Can also do this with classes
    
    @Message = class Message
        constructor: (@msg) ->

        show: ->
            $('#message').html(msg).show()

x-namespace-example1.js

/*
 * An example of how to declare a namespace using namespace.js
 */

namespace("My.Namespace", [jQuery], function($, undefined) {
    "use strict";
    
    /*
     * To add a function to a namespace, simply assign it to a property of this
     */
    
    this.showMessage = function(msg) {
        $('#message').html(msg).show();
    };
});

My.Namespace.showMessage('Hello world');

x-namespace-example2.js

/*
 * How to declare circular references between namespaces.
 * This is not a good idea if you can avoid it, but if you need to,
 * this is how you do it.
 *
 * Calling namespace(namespaceName) without a defining function ensures
 * that the namespace object exists, and returns a reference to it.
 */

namespace ("My.First.Namespace",
    [jQuery, namespace("My.Other.Namespace")],
    function ($, other) {

    /* whatever */
});

namespace ("My.Other.Namespace",
    [jQuery, namespace("My.First.Namespace")],
    function ($, first) {

    /* whatever */
});