Merge pull request #20 from Spy-Seth/hooks

Implement post instanciation method call on service

Author: armandabric

.travis.yml

@@ -5,6 +5,7 @@ sudo: false
 node_js:
     - "iojs-v2.4.0"
     - "iojs-v3.1.0"
+    - "iojs-v3.2.0"
     - "0.12"
 
 script:

README.md

@@ -10,17 +10,18 @@ Skippy is designed to be an easy to use, robust, and well tested dependencies co
 - Instantiate service as described in the dependencies configuration.
 - Configure what should be used as service constructor parameters: you can pass another services as reference, parameters, or any values you have configured.
 - Manage singleton instance of service (not defined by design pattern, but by configuration).
-- Check the dependencies graph to avoid cyclic dependencies (only on development environment: `NODE_ENV="development"`).
+- Call custom method on service instance to finish it configuration.
+- Check the dependencies graph to avoid cyclic dependencies.
 - Allowing injection of service mock (only in test environment: `NODE_ENV="test"`).
 
 #### What Skippy don't do (and never will)
 - Introspect JSDoc or parameters name to determine witch service should be inject in a constructor function. You have to define service dependencies in a configuration file.
 - Coffee
 
 #### What Skippy don't at the moment (maybe one day)
-- Use factory service to generate another service
-- Generate a lazy loading proxy function
 - Manage service scope (allowing private service, who can only be used to instantiate other service, not exposed to the world)
+- Use factory service to generate another service (delayed, the post service creation hooks do a part of the job for now)
+- Generate a lazy loading proxy function (delayed, until ES6 proxy is well supported)
 
 
 ## Installation
@@ -100,6 +101,15 @@ module.exports = [
             "@foo.serviceA",
             "@foo.serviceB"
         ]
+    },
+    {
+        "name": "foo.serviceD",
+        "service": require("./ServiceD"),
+        "calls": {
+            "setLocale": [
+                "@foo.serviceB",
+                "%default.locale%"
+        ]
     }
 ];
 ```
@@ -109,6 +119,7 @@ A service configuration have four possible keys:
 - `service` (`function`, mandatory): the service constructor function reference.
 - `singleton` (`boolean`, optional, default `true`): If `true`, the service will be a singleton. If `false`, a new service will be instantiated each time.
 - `arguments` (`array`, optional, default empty array): An array of the value to inject in the service constructor (see "Arguments" section for more informations).
+- `calls` (`object`, optional, default empty array): A map of the method to call on the service, each method should have it `arguments` array (see "Arguments" section for more informations).
 
 
 ### Arguments

package.json

@@ -27,9 +27,9 @@
   "devDependencies": {
     "chai": "~3.2.0",
     "coveralls": "~2.11.4",
-    "eslint": "~1.2.1",
-    "istanbul": "~0.3.18",
-    "mocha": "~2.2.5",
+    "eslint": "~1.3.1",
+    "istanbul": "~0.3.19",
+    "mocha": "~2.3.0",
     "sinon": "~1.16.1",
     "sinon-chai": "~2.8.0"
   },

src/Call.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * @param {String} methodName
+ * @param {FunctionArgumentCollection} functionArgumentCollection
+ */
+var Call = function Call(methodName, functionArgumentCollection) {
+    this.methodName = methodName;
+    this.functionArgumentCollection = functionArgumentCollection;
+};
+
+/**
+ * @param {Container} container
+ * @param {Object} instance
+ */
+Call.prototype.trigger = function trigger(container, instance) {
+    if (!instance[this.methodName]) {
+        throw new Error('Can\'t call the given method: "' + this.methodName + '" does not exist on the given instance.');
+    }
+
+    if (!(instance[this.methodName] instanceof Function)) {
+        throw new Error('Can\'t call the given method: "' + this.methodName + '" is not a callable function on the given instance.');
+    }
+
+    instance[this.methodName].apply(instance, this.functionArgumentCollection.resolveArguments(container));
+};
+
+/**
+ * @param {ServiceDefinitionCollection} serviceDefinitionCollection
+ * @param {Function} serviceConstructor
+ */
+Call.prototype.validate = function validate(serviceDefinitionCollection, serviceConstructor) {
+    if (!this._isMethodDefined(serviceConstructor, this.methodName)) {
+        throw new Error('The method "' + this.methodName + '" does not exist on the given constructor.');
+    }
+};
+
+/**
+ * @param {Function} serviceConstructor
+ * @param {String} methodName
+ * @return {Boolean}
+ */
+Call.prototype._isMethodDefined = function _isMethodDefined(serviceConstructor, methodName) {
+    if (serviceConstructor[this.methodName]) {
+        return true;
+    }
+
+    if (serviceConstructor.prototype && (serviceConstructor.prototype !== Function.prototype)) {
+        return this._isMethodDefined(serviceConstructor.prototype, methodName);
+    }
+
+    return false;
+};
+
+module.exports = Call;

src/CallCollection.js

@@ -0,0 +1,35 @@
+'use strict';
+
+var each = require('lodash/collection/each');
+var Call = require('./Call');
+
+/**
+ * @param {Array<Call>} calls
+ */
+var CallCollection = function CallCollection(calls) {
+    calls = calls || [];
+
+    each(calls, function (call, index) {
+        if (!(call instanceof Call)) {
+            throw new Error('Wrong paramater type at position #' + index + '. Only accept Call instance.');
+        }
+    });
+
+    this.calls = calls;
+};
+
+/**
+ * @return {Boolean}
+ */
+CallCollection.prototype.isEmpty = function () {
+    return (this.calls.length === 0);
+};
+
+/**
+ * @param {Function} cb
+ */
+CallCollection.prototype.forEach = function (cb) {
+    each(this.calls, cb);
+};
+
+module.exports = CallCollection;

src/Container.js

@@ -7,14 +7,21 @@ var ServiceStorage = require('./ServiceStorage');
  *
  * @param {ServiceDefinitionCollection} serviceDefinitionCollection
  * @param {ParameterCollection} parameterCollection
+ * @param {Boolean} validateContainer
  * @private
  * @constructor
  */
-var Container = function Container(serviceDefinitionCollection, parameterCollection) {
+var Container = function Container(serviceDefinitionCollection, parameterCollection, validateContainer) {
     this.serviceDefinitionCollection = serviceDefinitionCollection;
     this.parameterCollection = parameterCollection;
 
     this.serviceStorage = new ServiceStorage();
+
+    if (validateContainer) {
+        this.serviceDefinitionCollection.checkCyclicDependencies();
+        this.serviceDefinitionCollection.validateCalls();
+        // TODO: Validate the existance of used parameter as service arguments or call arguments.
+    }
 };
 
 /**
@@ -50,10 +57,15 @@ Container.prototype.getService = function (name) {
 
     var serviceDefinition = this.serviceDefinitionCollection.getServiceDefinition(name);
     var serviceInstance = serviceDefinition.createInstance(this);
+
     if (serviceDefinition.isSingleton()) {
         this.serviceStorage.addInstance(name, serviceInstance);
     }
 
+    if (serviceDefinition.hasCalls()) {
+        serviceDefinition.triggerCalls(this, serviceInstance);
+    }
+
     return serviceInstance;
 };
 
@@ -77,4 +89,5 @@ if (process.env.NODE_ENV === 'test') {
         this.serviceStorage.replaceInstance(name, mock);
     };
 }
+
 module.exports = Container;

src/ContainerFactory.js

@@ -1,18 +1,20 @@
 'use strict';
 
 var each = require('lodash/collection/each');
+var Call = require('./Call');
+var CallCollection = require('./CallCollection');
 var Container = require('./Container');
-var ObjectHelper = require('./ObjectHelper');
 var Parameter = require('./Parameter');
 var ParameterCollection = require('./ParameterCollection');
-var ServiceArgument = require('./ServiceArgument');
-var ServiceArgumentCollection = require('./ServiceArgumentCollection');
+var FunctionArgument = require('./FunctionArgument');
+var FunctionArgumentCollection = require('./FunctionArgumentCollection');
 var ServiceDefinition = require('./ServiceDefinition');
 var ServiceDefinitionCollection = require('./ServiceDefinitionCollection');
 
 /**
  * @param {Array} services
  * @return {ServiceDefinitionCollection}
+ * @private
  */
 var buildServiceDefinitionCollection = function buildServiceDefinitionCollection(services) {
     var servicesConfigurationList = services || [];
@@ -21,16 +23,28 @@ var buildServiceDefinitionCollection = function buildServiceDefinitionCollection
     each(servicesConfigurationList, function (value) {
         var argumentConfigurationList = value.arguments || [];
 
-        var serviceArgumentList = [];
+        var functionArgumentList = [];
         each(argumentConfigurationList, function (argumentValue) {
-            serviceArgumentList.push(new ServiceArgument(argumentValue));
+            functionArgumentList.push(new FunctionArgument(argumentValue));
+        });
+
+        var calls = value.calls || {};
+        var callList = [];
+        each(calls, function (callArguments, methodName) {
+            var callArgumentList = [];
+            each(callArguments, function (argumentValue) {
+                callArgumentList.push(new FunctionArgument(argumentValue));
+            });
+
+            callList.push(new Call(methodName, new FunctionArgumentCollection(callArgumentList)));
         });
 
         servicesDefinitionList.push(new ServiceDefinition(
             value.name,
             value.service,
-            new ServiceArgumentCollection(serviceArgumentList),
-            value.singleton || undefined
+            new FunctionArgumentCollection(functionArgumentList),
+            value.singleton || undefined,
+            new CallCollection(callList)
         ));
     });
 
@@ -53,51 +67,22 @@ var buildParameterCollection = function buildParameterCollection(parameters) {
     return new ParameterCollection(parameterList);
 };
 
-var checkCyclicDependencies = function checkCyclicDependencies(serviceDefinition, serviceDefinitionCollection, parentDependentServiceNames) {
-    parentDependentServiceNames = parentDependentServiceNames || [serviceDefinition.getName()];
-
-    var serviceArguments = serviceDefinition.getArgumentCollection().getServiceArguments();
-    each(serviceArguments, function (argument) {
-        var serviceName = argument.getName();
-
-        if (!serviceDefinitionCollection.hasServiceDefinition(serviceName)) {
-            throw new Error('The service "' + serviceDefinition.getName() + '" has dependencies on the unknown service "' + serviceName + '".');
-        }
-
-        if (parentDependentServiceNames.indexOf(serviceName) !== -1) {
-            parentDependentServiceNames.push(serviceName); // To show the complete dependency graph.
-            throw new Error('Cyclic dependencies detected: "' + parentDependentServiceNames.join(' > ') + '".');
-        }
-
-        var childDependentServiceNames = ObjectHelper.clone(parentDependentServiceNames);
-        childDependentServiceNames.push(serviceName);
-
-        checkCyclicDependencies(serviceDefinitionCollection.getServiceDefinition(serviceName), serviceDefinitionCollection, childDependentServiceNames);
-    });
-};
-
 var ContainerFactory = {};
 
 /**
- * @param {Array<{name: String, service: Function, arguments: Array<String|*>}>} services
+ * @param {Array<{name: String, service: Function, arguments: Array<String|*>, calls: {String: Array<String|*>}}>} services
  * @param {{String: *}} parameters
+ * @param {Boolean} validateContainer
  * @return {Container}
- * @public
  */
-ContainerFactory.create = function create(services, parameters) {
+ContainerFactory.create = function create(services, parameters, validateContainer) {
     services = services || [];
     parameters = parameters || {};
 
     var serviceDefinitionCollection = buildServiceDefinitionCollection(services);
     var parameterCollection = buildParameterCollection(parameters);
 
-    if (process.env.NODE_ENV === 'development') {
-        serviceDefinitionCollection.forEach(function (serviceDefinition) {
-            checkCyclicDependencies(serviceDefinition, serviceDefinitionCollection);
-        });
-    }
-
-    return new Container(serviceDefinitionCollection, parameterCollection);
+    return new Container(serviceDefinitionCollection, parameterCollection, validateContainer);
 };
 
 module.exports = ContainerFactory;