A Javascript Module facility, similar to Perl's Modules/Exporter (and JSAN)

JSM.js

// Copyright @2011, David Atchley (david.m.atchley@gmail.com)

/** 
 * @fileOverview 
 * <p>
 * JSM stands for JavaScript Module, and is based on Perl's module and exporter
 * facilities.  Combines a number of those ideas from Perl and from the existing
 * JSAN facility, though with some slight changes.
 * </p>
 *
 * <p>
 * Provides a Package/Module management facility similar to  Perl's Exporter 
 * style modules for JavaScript. Javascript modules can be created by including 
 * a simple Package = {...} declaration at the top of a javascript source file. 
 * The Package declaration defines information about the module, specifically:
 * </p>
 *
  <code><pre>
 	Package = {
 		NAME: the Module's name 
 		VERSION: the version of the module
 		DEFAULT: the default symbols available via Module name, e.g. Module.<symbol>
 		EXPORT: a set of default symbols to export to caller's namespace 
 			(no Module prefix qualitifications)
 		EXPORT_OK: a list of symbols allowed to exported on request
 		EXPORT_TAGS: names that represent useful sets of symbols to export
 	}
  </pre></code>
 *
 * <p>The module can then be used by importing it using this JSM singleton. There are
 * various ways to import,</p>
 *
  <code><pre>
       JSM.use('Foo');         // import module Foo
       JSM.use('Foo', 1.0)     // import module Foo, if version is >= 1.0

       // Each of the above creates a Foo object (namespace) that has the
       // methods that Foo makes available (via DEFAULT).

       JSM.use('Foo', [ 'bar', 'getters:', /^foo/ ]);

       // This call loads the module Foo, which still makes all the default
       // symbols available in the Foo namespace, but additionally exports
       // the symbol 'bar', all symbols that are part of the 'getters' tag
       // and all symbols matching the RegExp, e.g. those starting with 'foo'

  </code></pre>
 *
 * <p>
 * The Javascript file used a module can contain any style of coding and might be
 * a useful set of functions (function library) or a set of classes (class library);
 * but represents a reusable, modular set of functionality. The only requirement to 
 * be a Javascript Module is that it have the Package declaration at the top.
 * </p>
 *
 * @author david.m.atchley@gmail.com, (Dave Atchley)
 * @version 0.1
 */


/**
 * <p>
 * The JavaScript Module (JSM) class is a singleton allowing the 
 * management, loading and inclusion of JSM modules. JSM is designed
 * in a similar fashion to Perl's Module and Exporter facilities.
 * JSM will import modules, which can be any javascript file that
 * includes a valid <b>Package</b> header. See the file overview
 * for information on the Package declaration.</p>
 *
 * <p>The class can be used as follows:</p>
 *
 * 
 <code><pre>
		// Import the module and it's default symbols
		JSM.use('Math.Complex');	

		// Import the module, but only if it's version is >= 2.0
		JSM.use('Math.Complex', 2.0);

		// Import the module, request specific symbols exported to 
		// calling namespace (defaults still available via Module)
		JSM.use('Math.Complex', [ 'add', 'mult']);

 </pre></code>
 *
 * @class 
 */
var JSM = (function() {
	/** @lends JSM */

	/** @private version of JSM being run */
	var version = 0.1,

	/** @private The include path used by JSM to find modules, can be set with {@link setIncludePath} */
	inc = ['.', 'lib/js'],

	/** @private timeout value (milliseconds) for waiting for modules to load */
	poll_timeout = 200,

	/** @private number of attempts to try loading a given script url */
	tries = 3,
	attempted = 3,			// track attempts here

	/** @private global namespace for exporting, can be set with {@link setGlobalScope} */ 
	globalcontext = self,

	/** @private keep track of loaded files */
	loaded = [];

	/**
	 * <p>Check to see if the XHR object has loaded the given url
	 * and whether we have exceeded our timeout thresh hold {@link poll_timeout}.
	 * If timeout hasn't been exceeded, reset the poll and continue.
	 * Otherwise throw an exception.</p>
	 *
	 * <p>JSM will poll {@link tries} times (in {@link poll_timeout} intervals)
	 * to see if the module is loaded. After that it bails.</p>
	 *
	 * @function
	 * @param {Object} xhrobj the XMLHTTPRequest object being used
	 * @param {String} url the url of the file it's attempting to load
	 */
	var poll = function(url) {
		setTimeout(function() {
			attempted--;
			if (loaded.indexOf(url) != -1) {
				// NOOP: Loaded successfully, module script is in {@link loaded}
			}
			else if (attempted > 0) {
				// Continue: keep trying ...
				poll(url); 
			}
			else {
				// We've timed out looking/loading script, reset attempts and error out
				attempted = tries;
				throw new Error("JSM: (XHR): loading of " + url + " timed out");
			}
		}, poll_timeout);
	}

	/**
	 * Will attempt to load the given url via XHR (synchronously).
	 * If the the requested javascript file is not found, it 
	 * returns null. Otherwise it returns the javascript code as
	 * a string.
	 * <p>This is a synchronous XMLHTTPRequest call that uses polling
	 * to check on the state of things, throwing an exception if the
	 * {@link poll_timeout} value is reached.</p>
	 *
	 * @function
	 * @param {String} url the url of the javascript module to load
	 * @returns {String|null} the javascript contained in the file
	 *		or null if not found.
	 */
	var loadJSFromURL = function(url) { 
		if (typeof XMLHttpRequest != 'undefined') {
			var ajax = new XMLHttpRequest();
		}
		else {
			var ajax = new ActiveXObject("Microsoft.XMLHTTP");
		}
		ajax.open("GET", url, false);
		try {
			ajax.send(null);
			var stat = ajax.status;
			if (stat == 200 || stat == 304 || stat == 0 || stat == null) {
				var responseText = ajax.responseText;
				return responseText;
			}
		}
		catch (e) {
			// throw new Error("File not found: " + url);
			return null;
		}
		// throw new Error("File not found: " + url);
		return null;
	}

	/**
	 * Given a DEFAULT defined in the package header for a
	 * module, returns the list of default symbols to import 
	 * for the module being processed.
	 *
	 * @function
	 * @param {Object} pkghdr package haeader from the module
	 * @returns {Array} list of default symbols to import
	 */
	var getDefaultImportList = function(pkghdr) {
		var DEFAULTS = pkghdr['DEFAULT'] || [];

		var default_list = [];

		// The DEFAULT is the always available interface
		// provided by the module.
		for (var i = 0; i < DEFAULTS.length; i++) {
			default_list.push(DEFAULTS[i]);
		}
		return default_list;
	}

	/**
	 * Given the EXPORT* definitions in a package header, returns
	 * the available symbols for export for the module being processed.
	 * @function
	 * @param {Object} pkghdr package header from the module
	 * @param {Array} symbols an array of requested symbols to import
	 */
	var getExportList = function(pkghdr, symbols) {
		var EXPORTS = pkghdr['EXPORT'] || [];
		var EXPORT_OK = pkghdr['EXPORT_OK'] || [];
		var EXPORT_TAGS = pkghdr['EXPORT_TAGS'] || {};
		var ALL_EXPORTS = EXPORTS.concat(EXPORT_OK);

		var export_list = [];

		if (!symbols || symbols.length == 0) {
			for (var i = 0; i < EXPORTS.length; i++) {
				var symbol = EXPORTS[i];
				export_list.push(symbol);
			}
		}
		else {
			for (var i = 0; i < symbols.length; i++) {
				var symbol = symbols[i];

				// TAG: add all symbols from the matching tag [ex., 'all:']
				if (!(symbol instanceof RegExp) && symbol.match(/.*:$/)) {			
					var symbol = symbol.replace(':','');	
					for (tag in EXPORT_TAGS) {
						if (tag == symbol) {
							EXPORT_TAGS[tag].forEach(function(v,i) {
								export_list.push(v);	
							});
						}
					}
					continue;
				}
				// REGEXP: add any symbols that match [ex., /^get/ ]
				else if (symbol instanceof RegExp) {
					ALL_EXPORTS.forEach(function(v,i) {
						if (v.match(symbol)) {
							export_list.push(v);
						}
					});
					continue;
				}
				// SYMBOL: add all matching symbols [ex., 'getTimer']
				else {
					ALL_EXPORTS.forEach(function(v,i) {
						if (v == symbol) {
							export_list.push(v);
						}		
					});
					continue;
				}
			}
		}
		return export_list;
	}

	/**
	 * <p>Import the package requested. Optionally, a specific
	 * version can be requested and specific symbols (ONLY)
	 * can also be requested for export.</p> 
	 *
	 * <p>Calls {@link loadJSFromURL} to load the requested package.</p>
	 *
	 * @function
	 * @param {String} pkgname package name of the module to import
	 * @param {Number} [version] a specific version number of the module
	 * @param {Array} [symbols] a specific list of symbols to export
	 */
	var import = function(pkgname, version, symbols) {
		var scriptUrl = pkgname.replace('.','/','gi') + '.js';

		if (loaded.indexOf(scriptUrl) != -1) {
			throw new Error("Module " + pkgname + " already loaded, skipping.");
		}

		// Try loading the script via each include path
		for (var i = 0; i < inc.length; i++) {
			var js,
				url = inc[i] + '/' + scriptUrl;

			try {
				poll(scriptUrl);				// Poll for the package being loaded
				js = loadJSFromURL(url);
			}
			catch (e) {
				if (i == (inc.length - 1)) {
					// Only rethrow the error if we've depelted our include path search
					throw e;	
				}
			}

			if (js) {
				var ns = createNamespace(pkgname);
				(function() {
					// Eval the returned javascript making it available in local scope
					eval(js);

					// If we have the right Module and Version, continue building namespace
					if (typeof Package != 'undefined' && Package['NAME'] == pkgname) {

						if (version && Package['VERSION'] && Package['VERSION'] < version)  {
							throw new Error("module " + Package['NAME'] + '(' + Package['VERSION'] + "), requested version " + version + " or higher");
						}

						// Modules should ALWAYS define some kind of interface in DEFAULT
						if (!Package['DEFAULT'] || Package['DEFAULT'].length == 0) {
							throw new Error("module " + Package['NAME'] + " does not have an available interface");
						}

						// Track valid modules so we don't reload later
						loaded.push(scriptUrl);

						// Add Package info to our locally built namespace
						ns['Package'] = Package;

						//
						// Import Default Namespace
						//
						var default_import_list = getDefaultImportList(Package);
						default_import_list.forEach(function(v,i) {
							if (typeof eval(v) != 'undefined') {
								console.log("\t importing: " + v);
								ns[v] = eval(v);							// accessible via Module name qualifier
							}
						});

						//
						// Export to Namespace
						//

						// Handle any symbols requested for 'export'
						var export_symbols_list = getExportList(Package, symbols);

						// Requested symbols are exported to caller's scope
						export_symbols_list.forEach(function(v,i) {
							if (typeof eval(v) != 'undefined') {
								console.log("\t exporting: " + v);
								globalcontext[v] = ns[v] = eval(v);			// export to global scope here
							}
						});
					}
					else {
						throw new Error('Invalid JSM Package format in ' + scriptUrl);
					}
				})();
				return ns;
			}
		}
		// I find your lack of script disturbing....
		throw new Error("Couldn't find script in JSM.inc = [" + inc + "]");
	}

	/**
	 * Create a new namespace based on a package name of a module.
	 * @function
	 * @param {String} pkgname the name of the package containing the module
	 * @returns {Object} the new namespace to contain the module's symbols
	 */
	var createNamespace = function(pkgname) {
		var parts = name.split('.');  
		var container = {};

		for (var i = 0; i < parts.length; i++) {
			if (!container[parts[i]]) {
				container[parts[i]] = {};
			}
			else if (typeof container[parts[i]] != 'object') {
				var n = parts.slice(0,i).join('.');
				throw new Error(n + " module already exists and is not an object");
			}
			container = container[parts[i]];
		}

		// Namespace is created in the global context 
		globalcontext[pkgname] = container;
		return container;
	}

	return {

		/**
		 * Add a new path to the JSM include path list
		 * @function
		 * @param {String|String[]} 
		 */
		addIncludePath: function(/* single path or array */) {
			var paths = [].slice.apply(arguments, 0);	
			inc.concat(paths); 
		},

		/**
		 * Return the JSM include path list used to find modules
		 * @function
		 * @returns {Array} the JSM include path
		 */
		getIncludePath: function() {
			return inc;
		},

		/**
		 * Set the global scope for exporting symbols. Call this
		 * prior to calling {@link JSM.use}
		 * @function
		 * @param {Object} context object to use when exporting symbols globally 
		 */
		setGlobalScope: function(context) {
			if (typeof context !== 'undefined')
				throw new TypeError;
			globalcontext = context;
		},

		/**
		 * Dynamically load and import a module from a javascript package.
		 * @function
		 * @param {String} pkgname the name of the module to import
		 * @param {Number} [version] require a specific version of this module
		 * @param {Array} [symbols] any specific symbols to export from module
		 *
		 * @returns	{Object} reference to the local namespace for module
		 */	
		use: function(/* pkgname, version, [symbol, ...] */) {
			var args = [].slice.call(arguments, 0);

			// Check module name, first parameter: e.g., JSM.use('Mod') 
			if (!args[0] && typeof args[0] !== 'string') 
				throw new TypeError("expect module name as string in first parameter");
		
			// Get the package name and version requested (if any)
			var pkgname = args.shift();
			if (args.length >= 1 && typeof args[0] == 'number') {
				var version = args.shift();
			}
			if (args.length >= 1 && typeof args[0] == 'object') {
				var symbols = args.shift();
			}

			// Import the script (with optional, specific version)
			var ns = import(pkgname, version, symbols);

			// Get symbols to import to caller's namespace (if any): eg.,  JSM.use('Mod', fn, fn2,...)
			return ns;
		}
	}
	/* end return */

})();

Profiler Module (example module)

// Package Definition //
var Package = {
	NAME: 'Profiler',
	VERSION: 0.1,
	DEFAULT: ['addProfiling', 'removeProfiling', 'profileReport'],
	EXPORT: [ ],
	EXPORT_OK: ['_start','_stop','_init'],
	EXPORT_TAGS: { }
};

// Private Variables //
var _fnlist = {};

/**
 * Create a tracking object for a new function
 * to be profiled.
 * @function
 */
function _init(fname, fn, scope) {
	console.log("Adding " + fname + ": ");
	if (typeof _fnlist[fname] == 'undefined') {
		_fnlist[fname] = {
			fn: fn,			// save original function
			scope: scope,	// object owner of function (context)
			ncalls: 0,		// number of calls made
			calls: {}		// individual call profiling
		};
	}
	else
		throw new Error(fname + " is already being profiled");
}

/**
 * Start timing this function, run prior to the
 * actual function's execution.
 * @function
 */
function _start(fname, fn, args) {
	_fnlist[fname].ncalls++;
	var start = new Date().getTime();
	var id = start + "_" + _fnlist[fname].ncalls;
	_fnlist[fname].calls[id] = {
		start: start,
		stop: null, 
		args: args,
		total: 0 
	};
	return id;	// unique id for *this* call
}

/**
 * Stop timing a function and calculate total
 * elapsed time (milliseconds)
 * @function
 */
function _stop(fname, id) {
	var ref = _fnlist[fname].calls[id];
	ref.stop = new Date().getTime();
	ref.total = ref.stop - ref.start;
}

/**
 * Add profiling for a given function, identified
 * by the given label. Returns the newly modified
 * function to be assigned to the old function.
 * @example addProfiling('func');
 * @example addProfiling('func', window);
 * @function
 */
function addProfiling(fname, scope) {
	var scope = scope || window;
	_init(fname, scope[fname], scope);
	var tmpfn = scope[fname];
	scope[fname] = function() {
		var id = _start(fname, tmpfn, arguments);
		var rv = tmpfn.apply(tmpfn, arguments);
		_stop(fname, id);
		return rv;	// return result of original function
	}
}

/**
 * Remove a function identified by the lable
 * from being profiled. Returns original function
 * to be reassigned.
 * @example removeProfiling('func');
 * @function
 */
function removeProfiling(fname) {
	_fnlist[fname]['scope'][fname] = _fnlist[fname].fn;
	delete _fnlist[fname];
}

/**
 * Report our profiling information via the console.
 * @function
 */
function profileReport() {
	for (fn in _fnlist) {
		var obj = _fnlist[fn];
		console.log("Function: " + fn + ":");
		console.dir(obj);	
		console.log("\tTotal Calls: " + obj['ncalls']);
		var totaltime = 0;
		for (call in obj['calls']) {
			totaltime += obj['calls'][call].total;
		}
		console.log("\tTotal Time (sec): " + (totaltime/1000).toFixed(5));
	}
}

This is a module facility very similar to what Perl's modules and Exporter make available; and it's similar in a way to the JSAN archives functionality for creating modules as well. We needed something at work that gave us the ability to dynamically load reusable javascript files after the page had loaded. Many of the current libraries offer this, like JQuery's getScript(); but we also needed a good way to organize our shared code across our developers and systems to make them more usable. JSAN offers a nice set of features, and we all do a lot of Perl development and understand those module facilities, so a combination of the two seemed useful.

We wanted each javascript module to be usable outside of this dynamic loading facility as well, so the only addition to the code is the Package declaration at the top of the Module file (much like Perl). Our Package declaration plays the part of defining the Module, what it imports by default, what it makes available for export and gives it a name and a version number as well. I've tested with a number of modules myself and at our office; but again, wider testing would likely find some better ways of doing things.

Feel free to use and give me some feedback on how to improve the code or make it a little more cross browser compatible. I've tested so far on IE 8, FF 3.x and Chrome with no issues.

Removed some dead code in the latest revision. I've also modified the XHR loading of the script to implement polling using setTimeout. JSM now has a poll_timeout value in milliseconds and a number of attempts. So, for each path in the include paths tried for a given modules script, JSM will essentially wait (poll_timeout * tries) milliseconds until giving up. Given that we need to use synchronous XHR instead of async, this needed to be added to handle server latency, missing files, etc. If there's a better way to handle this, let me know.

I've added an example module for those that might want to download and play around with JSM. Plus, it gives a nice sample of the Package header definition for those interested in how it works.