Namespace-Friendly JavaScript APIs

By Bret Taylor, July 26, 2006

JavaScript has no support for packages or modules, so namespace conflicts are rampant. In particular, as JavaScript obfuscators become prevalent, a lot of JavaScript libraries have started to look like this (an actual snippet of the Google Maps API JavaScript):

function Cb(a){a.remove();Gb(ab,a)}

Given these obfuscators choose the shortest names possible to make the size of the JavaScript as small as possible, the likelihood of a name collision when multiple APIs are included in a page is almost 100% -- after all, there are only 26 letters in the alphabet.

When you make a JavaScript library, you can make it play well with others by only exporting those symbols that are a part of your API using this simple recipe. First, concatenate all of your JavaScript source code, and surround it in a single, anonymous function:

(function() {
    var privateVariable = 3;

    function MyPublicClass() {
    }

    function MyPrivateClass() {
    }
})();

This will prevent any of your symbols from being accessible to pages that include the API. Then, explicitly export the symbols that make up your API with this simple export function:

function exportSymbol(name, symbol) {
    window[name] = symbol;
}

In the case of the API above, we would add this line to the end of our anonymous function:

(function() {
    var privateVariable = 3;

    function MyPublicClass() {
    }

    function MyPrivateClass() {
    }

    exportSymbol("MyPublicClass", MyPublicClass);
})();

Now, MyPublicClass will be accessible, but the other two symbols defined are "private" and will not interfere with the other libraries included by your API clients.

See the complete example

Digg  del.icio.us  Reddit

Comments

On December 16, 2006, Laurent wrote
I fully disagree with the method, it's cluttering the code and making it confusing. If you want to create an API, you obviously have an API name, so use it as your namespace.

var myAPI = function()
{
function MyPrivateClass() {}
return {
"myPublicClass":function() {}
};
}();
On December 18, 2006, frumbert wrote
what about declaring an empty function as your 'namespace' and then populating it with your methods and properties:

function myAPI() {}

myAPI.MyPrivateClass = {
intX : 6,
setX : function (x) {
function addX() {
x += 1;
}
addX();
return x + myAPI.MyPrivateClass.intX;
}
}
alert(myAPI.MyPrivateClass.setX(6)); //alert "13"

On December 18, 2006, Bret Taylor wrote
The main reason why an explicit export function is useful is for name-mangling JavaScript compilers/obfuscators, which have become common to reduce the size of JavaScript libraries. You can create an API-friendly alias for a class definition that may have been changed to be named "Cb" (as in the example above) by the JavaScript obfuscators. In the simple example above, the exportSymbol line would more likely read exportSymbol("MyPublicClass", Cb) in practice.

Surrounding the entire thing in an anonymous function is also an easy thing to do in a post-processing stage with compilation/obfuscation, so you do not need to touch your code in practice (also very convenient).
On January 10, 2007, jess wrote
Anyone seen Ajile -> http://ajile.iskitz.com/ ? Does all that namespacing work for ya...
On September 21, 2008, David Smith wrote
As a result of namespace posioning this style of programming has caused I developed a completely Open Source Object Oriented Javascript API called JAK (Javascript API Kernel) found at http://avitar.net/ - Not only does this object oriented architecture resolved namespace posioning and add stablity, but it makes it possible to function like a true API.
On September 21, 2008, Jack Pfoff wrote
I use JAK in our enterprise and I have to say I am impressed. JACK (the compressed version) is less then 1 KB and is completely modular in design. It is the Javascript API I have ever seen.

Write a Comment