Merge pull request #164 from ouadi/enh-manage-imports

fixes #162: Allow import of a context-spec into another.

Author: briancavalier

docs/concepts.md

@@ -130,6 +130,30 @@ The second references the `message` String (the first item in the wire spec):
 
 When you feed a spec to wire.js, it will create a [context](#contexts) containing fully realized versions of the components in the spec.  In the Hello Wire case, the context will contain the message String, an *instance* of the `HelloWired` object from the `app/HelloWire` AMD module, and an Array with one element--the `wire/dom` plugin AMD module.
 
+### Assembling applications
+
+In addition to [Application composition](#application-composition), Wire.js helps you assemble large application from parts using the `$imports` keyword.
+
+You may decide to decompose your large application into domains (transacting, settling, accounting, ...). You may also decide to decompose each domain into layers (presentation, business, infrastructure, ...). Let's call a layer of a domain an *application part*. Each application part would be developed, tested and wired in isolation.
+
+To build an application, you will select the appropriate parts and assemble them together. To do so, all you need is import the spec of each selected part within the spec of the final application.
+
+The spec of the final application would be as follows:
+
+```javascript
+define({
+	$imports: [
+		'utils-spec',
+		'commons-spec',
+		'transaction-spec',
+		'settlement-spec',
+		'accounting-spec',
+	]
+});
+```
+
+Reading the above spec, Wire.js will first inline the content of each imported spec then process the result. 
+
 ## Contexts
 
 As the result of processing a spec, wire.js produces a **Context**.  The context is a Javascript Object that contains the fully realized components that were specified in the wiring spec.  The context also has methods for wiring child contexts, resolving references, and destroying the context and all the objects, etc. that were created when it was wired.

lib/context.js

@@ -10,13 +10,14 @@
 (function(define){ 'use strict';
 define(function(require) {
 
-	var when, mixin, loaderAdapter, relativeLoader, Container;
+	var when, mixin, loaderAdapter, relativeLoader, Container, specUtils;
 
 	when = require('when');
 	mixin = require('./object').mixin;
 	loaderAdapter = require('./loader/adapter');
 	relativeLoader = require('./loader/relative');
 	Container = require('./Container');
+	specUtils = require('./specUtils');
 
 	/**
 	 * Creates a new context from the supplied specs, with the supplied
@@ -47,7 +48,7 @@ define(function(require) {
 			options.moduleLoader =
 				createContextLoader(specLoader, findBaseId(specs));
 
-			return mergeSpecs(specLoader, specs).then(function(spec) {
+			return specUtils.mergeSpecs(specLoader, specs).then(function(spec) {
 
 				var container = new Container(parent, options);
 
@@ -99,22 +100,5 @@ define(function(require) {
 
 		return firstId;
 	}
-
-	function mergeSpecs(moduleLoader, specs) {
-		return when(specs, function(specs) {
-			return when.resolve(Array.isArray(specs)
-				? mergeAll(moduleLoader, specs)
-				: (typeof specs === 'string' ? moduleLoader(specs) : specs));
-		});
-	}
-
-	function mergeAll(moduleLoader, specs) {
-		return when.reduce(specs, function(merged, module) {
-			return typeof module == 'string'
-				? when(moduleLoader(module), function(spec) { return mixin(merged, spec); })
-				: mixin(merged, module);
-		}, {});
-	}
-
 });
 }(typeof define === 'function' ? define : function(factory) { module.exports = factory(require); }));

lib/graph/cyclesTracker.js

@@ -0,0 +1,53 @@
+/** @license MIT License (c) copyright B Cavalier & J Hann */
+
+/**
+ * cyclesTracker
+ * @author: brian@hovercraftstudios.com
+ * @author: younes.ouadi@gmail.com
+ */
+(function(define) {
+define(function(require) {
+
+	var findStronglyConnected, formatCycles;
+
+	findStronglyConnected = require('./tarjan');
+	formatCycles = require('./formatCycles');
+
+	/**
+	 * Make sure that the new name doesn't introduce a cycle.
+	 * 
+	 * @param {string} name the name being used.
+	 * @param {string} onBehalfOf some indication of another name on whose behalf this
+	 *  name is being used.  Used to build graph and detect cycles
+	 * @return {string} the name being used.
+	 */
+	function ensureNoCycles(namesGraph, name, onBehalfOf) {
+		var stronglyConnected, cycles;
+
+		// add the name to the graph
+		onBehalfOf = onBehalfOf||'?';
+		namesGraph.addEdge(onBehalfOf, name);
+
+		// compute cycles
+		stronglyConnected = findStronglyConnected(namesGraph);
+		cycles = stronglyConnected.filter(function(node) {
+			// Only consider cycles that:
+			// * have more than one node
+			// * have one node and that node is not self-referenced
+			return node.length > 1 || (node.length === 1 && Object.keys(node[0].edges).indexOf(node[0].name) !== -1);
+		});
+
+		// is there a cycle?
+		if(cycles.length) {
+			// Cycles detected
+			throw new Error('Possible circular usage:\n' + formatCycles(cycles));
+		}
+
+		return name;
+	}
+
+	return {
+		ensureNoCycles: ensureNoCycles
+	};
+});
+}(typeof define === 'function' && define.amd ? define : function(factory) { module.exports = factory(require); }));

lib/scope.js

@@ -12,7 +12,7 @@ define(function(require) {
 
 	var when, defer, sequence, array, object, loader, Map,
 		ComponentFactory, Lifecycle, Resolver, WireProxy, PluginRegistry,
-		undef;
+		undef, specUtils, DirectedGraph, cyclesTracker;
 
 	when = require('when');
 	sequence = require('when/sequence');
@@ -25,7 +25,10 @@ define(function(require) {
 	Resolver = require('./resolver');
 	WireProxy = require('./WireProxy');
 	PluginRegistry = require('./plugin/registry');
-
+	specUtils = require('./specUtils');
+	DirectedGraph = require('./graph/DirectedGraph');
+	cyclesTracker = require('./graph/cyclesTracker');
+	
 	defer = when.defer;
 
 	function Scope(parent, options) {
@@ -169,9 +172,10 @@ define(function(require) {
 			var self = this;
 
 			return this._executeInitializers().then(function() {
-				var parsed = self._parseSpec(spec);
-				return self._createComponents(parsed).then(function() {
-					return self._awaitInstances(parsed);
+				return self._parseSpec(spec).then(function(parsed){
+					return self._createComponents(parsed).then(function() {
+						return self._awaitInstances(parsed);
+					});
 				});
 			});
 		},
@@ -263,34 +267,15 @@ define(function(require) {
 		},
 
 		_parseSpec: function(spec) {
-			var instances, components, ready, plugins, id, initialized;
-
-			instances = this.instances;
-			components = this.components;
-			ready = {};
-
-			// Setup a promise for each item in this scope
-			for (id in spec) {
-				if(id === '$plugins' || id === 'plugins') {
-					plugins = spec[id];
-				} else if (!object.hasOwn(instances, id)) {
-					// An initializer may have inserted concrete components
-					// into the context.  If so, they override components of the
-					// same name from the input spec
-					initialized = defer();
-					ready = defer();
-					components[id] = this._createComponentDef(id, spec[id], initialized, ready);
-					instances[id] = initialized.promise;
-					ready[id] = ready.promise;
-				}
-			}
+			var self = this;
 
-			return {
-				plugins: plugins,
-				components: components,
-				instances: instances,
-				ready: ready
-			};
+			// instantiate the imports graph
+			var importsGraph = new DirectedGraph();
+
+			return processImports(self, spec, importsGraph).then(function(specImports){
+				// modules of importing spec overrides modules of imported spec.
+				return processSpec(self, object.mixin(specImports, spec));
+			});
 		},
 
 		_createComponentDef: function(id, spec, initialized, ready) {
@@ -498,6 +483,66 @@ define(function(require) {
 
 	function noop() {}
 
+	function processImports(scope, spec, importsGraph, importingModuleId) {
+		if(!spec || !spec.$imports) {
+			return when({});
+		}
+
+		if(typeof spec.$imports === 'string') {
+			spec.$imports = [spec.$imports];
+		}
+
+		importingModuleId = importingModuleId || (typeof spec === 'string' ? spec : undefined);
+
+		return when.reduce(spec.$imports, function(currentSpecImports, importedModuleId){
+			// make sure that there is no cycles
+			cyclesTracker.ensureNoCycles(importsGraph, importedModuleId, importingModuleId);
+
+			// go ahead with the import
+			return when(scope.getModule(importedModuleId), function(importedSpec){
+				return processImports(scope, importedSpec, importsGraph, importedModuleId).then(function(importedSpecImports){
+					// modules of importing spec overrides modules of imported specs.
+					var importedSpecAndItsImports = object.mixin(importedSpecImports, importedSpec);
+
+					// modules in the right overrides modules in the left
+					currentSpecImports = object.mixin(currentSpecImports, importedSpecAndItsImports);
+
+					return currentSpecImports;
+				});
+			});
+		}, {});
+	}
+
+	function processSpec(scope, spec) {
+		var instances, components, ready, plugins, id, initialized;
+
+		instances = scope.instances;
+		components = scope.components;
+		ready = {};
+
+		// Setup a promise for each item in this scope
+		for (id in spec) {
+			if(id === '$plugins' || id === 'plugins') {
+				plugins = spec[id];
+			} else if(!object.hasOwn(instances, id)) {
+				// An initializer may have inserted concrete components
+				// into the context.  If so, they override components of the
+				// same name from the input spec
+				initialized = defer();
+				ready = defer();
+				components[id] = scope._createComponentDef(id, spec[id], initialized, ready);
+				instances[id] = initialized.promise;
+				ready[id] = ready.promise;
+			}
+		}
+
+		return when.resolve({
+			plugins: plugins,
+			components: components,
+			instances: instances,
+			ready: ready
+		});
+	}
 });
 })(typeof define == 'function' && define.amd ? define : function(factory) { module.exports = factory(require); }
 );

lib/specUtils.js

@@ -0,0 +1,41 @@
+/** @license MIT License (c) copyright B Cavalier & J Hann */
+
+/**
+ * Licensed under the MIT License at:
+ * http://www.opensource.org/licenses/mit-license.php
+ *
+ * @author: Brian Cavalier
+ * @author: John Hann
+ */
+
+(function(define) { 'use strict';
+define(function(require) {
+
+	var object, when;
+
+	when = require('when');
+	object = require('./object');
+
+	function mergeSpecs(moduleLoader, specs) {
+		return when(specs, function(specs) {
+			return when.resolve(Array.isArray(specs)
+				? mergeAll(moduleLoader, specs)
+				: (typeof specs === 'string' ? moduleLoader(specs) : specs));
+		});
+	}
+
+	function mergeAll(moduleLoader, specs) {
+		return when.reduce(specs, function(merged, module) {
+			return typeof module == 'string'
+				? when(moduleLoader(module), function(spec) { return object.mixin(merged, spec); })
+				: object.mixin(merged, module);
+		}, {});
+	}
+
+	return {
+		mergeSpecs: mergeSpecs,
+		mergeAll: mergeAll
+	};
+});
+})(typeof define == 'function' && define.amd ? define : function(factory) { module.exports = factory(require); }
+);