Let's start our analysis by looking at the structure represented by the following figure:

The preceding figure shows a typical example of layered architecture; it describes the structure of a simple authentication system. AuthController accepts the input from the client, extracts the login information from the request, and performs some preliminary validation. It then relies on AuthService to check whether the provided credentials match with the information stored in the database; this is done by executing some specific queries using the db module handle, as a means to communicate with the database. The way these three components are connected together will determine their level of reusability, testability, and maintainability.

The most natural way to wire these components together is by requiring the db module from AuthService and then requiring AuthService from AuthController. This is the hardcoded dependency that we are talking about.

Let's demonstrate this in practice by actually implementing the system that we just described. Let's then design a simple authentication server, which exposes the following two HTTP APIs:

For this example, we are going to use several technologies; some of them are not new to us. In particular, we are going to use express (https://npmjs.org/package/express) to implement the Web API and levelup (https://npmjs.org/package/levelup) to store the user's data.

const level = require('level'); 
const sublevel = require('level-sublevel'); 
 
module.exports = sublevel( 
  level('example-db', {valueEncoding: 'json'}) 
); 

// ... 
const db = require('./db'); 
const users = db.sublevel('users'); 
 
const tokenSecret = 'SHHH!'; 
 
exports.login = (username, password, callback) => { 
  users.get(username, function(err, user) { 
    // ... 
  }); 
}; 
 
exports.checkToken = (token, callback) => { 
  // ... 
  users.get(userData.username, function(err, user) { 
    // ... 
  }); 
}; 

const authService = require('./authService'); 
 
exports.login = (req, res, next) => { 
  authService.login(req.body.username, req.body.password, 
    (err, result) => { 
      // ... 
    } 
  ); 
}; 
 
exports.checkToken = (req, res, next) => { 
  authService.checkToken(req.query.token, 
    (err, result) => { 
      // ... 
    } 
  ); 
}; 

const express = require('express'); 
const bodyParser = require('body-parser'); 
const errorHandler = require('errorhandler'); 
const http = require('http'); 
 
const authController = require('./lib/authController'); 
 
const app = module.exports = express(); 
app.use(bodyParser.json()); 
 
app.post('/login', authController.login); 
app.get('/checkToken', authController.checkToken); 

app.use(errorHandler()); 
http.createServer(app).listen(3000, () => { 
  console.log('Express server started'); 
}); 

node app

curl -X POST -d '{"username": "alice", "password":"secret"}' http://localhost:3000/login -H "Content-Type: application/json"

curl -X GET -H "Accept: application/json" http://localhost:3000/checkToken?token=<TOKEN HERE>

{"ok":"true","user":{"username":"alice"}}

The sample we just implemented demonstrates the conventional way of wiring modules in Node.js, leveraging the full power of its module system to manage the dependencies between the various components of the application. We exported stateful instances from our modules, letting Node.js manage their life cycle, and then we required them directly from other parts of the application. The result is an immediately intuitive organization, easy to understand and debug, where each module initializes and wires itself without any external intervention.

On the other hand, however, hardcoding the dependency on a stateful instance limits the possibility of wiring the module against other instances, which makes it less reusable and harder to unit test. For example, reusing authService in combination with another database instance would be close to impossible, as its dependency is hardcoded with one particular instance. Similarly, testing authService in isolation can be a difficult task because we cannot easily mock the database used by the module.

As a last consideration, it's important to see that most of the disadvantages of using hardcoded dependencies are associated with stateful instances. This means that if we use require() to load a stateless module, for example, a factory, constructor, or a set of stateless functions, we don't incur the same kind of problems. We will still have a tight coupling with a specific implementation, but in Node.js, this usually does not impact the reusability of a component, as it does not introduce a coupling with a particular state.

Refactoring our modules to use DI involves the use of a very simple recipe: instead of hardcoding the dependency to a stateful instance, we will instead create a factory, which takes a set of dependencies as arguments.

Let's start immediately with this refactoring; let's work on the lib/db.js module, given as follows:

const level = require('level'); 
const sublevel = require('level-sublevel'); 
 
module.exports = dbName => { 
  return sublevel( 
    level(dbName, {valueEncoding: 'json'}) 
  ); 
}; 

The first step in our refactoring process is to transform the db module into a factory. The result is that we can now use it to create as many database instances as we want; this means that the entire module is now reusable and stateless.

Let's move on and implement the new version of the lib/authService.js module:

const jwt = require('jwt-simple'); 
const bcrypt = require('bcrypt'); 
 
module.exports = (db, tokenSecret) => { 
  const users = db.sublevel('users'); 
  const authService = {}; 
 
  authService.login = (username, password, callback) => { 
    //...same as in the previous version 
  }; 
 
  authService.checkToken = (token, callback) => { 
    //...same as in the previous version 
  }; 
 
  return authService; 
}; 

Also, the authService module is now stateless; it doesn't export any particular instance anymore, just a simple factory. The most important detail, though, is that we made the db dependency injectable as an argument of the factory function, removing what was previously a hardcoded dependency. This simple change enables us to create a new authService module by wiring it to any database instance.

We can refactor the lib/authController.js module in a similar way as follows:

module.exports = (authService) => { 
  const authController = {}; 
 
  authController.login = (req, res, next) => { 
    //...same as in the previous version 
  }; 
 
  authController.checkToken = (req, res, next) => { 
    //...same as in the previous version 
  }; 
 
  return authController; 
}; 

The authController module does not have any hardcoded dependency at all, not even stateless! The only dependency, the authService module, is provided as input to the factory at the moment of its invocation.

Okay, now it's time to see where all these modules are actually created and wired together; the answer lies in the app.js module, which represents the topmost layer in our application. Its code is the following:

// ... 
const dbFactory = require('./lib/db');                        //[1] 
const authServiceFactory = require('./lib/authService'); 
const authControllerFactory = require('./lib/authController'); 
 
const db = dbFactory('example-db');                           //[2] 
const authService = authServiceFactory(db, 'SHHH!'); 
const authController = authControllerFactory(authService); 
 
app.post('/login', authController.login);                     //[3] 
app.get('/checkToken', authController.checkToken); 
// ... 

The previous code can be summed up as follows:

Our authentication server is now wired using DI and ready to be used again.

The example we just presented demonstrated only one type of DI (factory injection), but there are a couple more worth mentioning:

       const service = new Service(dependencyA, dependencyB); 

       const service = new Service();  //works also with a factory 
       service.dependencyA = anInstanceOfDependencyA; 

Property injection implies that an object is created in an inconsistent state because it's not wired to its dependencies, so it's the least robust, but it may sometimes be useful when there are cycles between the dependencies. For example, if we have two components, A and B, both using factory or constructor injection and both depending on each other, we cannot instantiate either of them because both would require the other to exist in order to be created. Let's consider a simple example, as follows:

function Afactory(b) { 
  return { 
    foo: function() { 
      b.say(); 
    }, 
    what: function() { 
      return 'Hello!'; 
    } 
  } 
} 
 
function Bfactory(a) { 
  return { 
    a: a, 
    say: function() { 
      console.log('I say: ' + a.what); 
    } 
  } 
} 

The dependency deadlock between the two preceding factories can be resolved only using property injection, for example, by first creating an incomplete instance of B, which then can be used to create A. Finally, we will inject A into B by setting the relative property as follows:

const b = Bfactory(null); 
const a = Afactory(b); 
a.b = b; 

In the authentication server example using DI, we were able to decouple our modules from a particular dependency instance. The result is that we can now reuse each module with minimal effort and without any change in their code. Testing a module that uses the DI pattern is also greatly simplified; we can easily provide mocked dependencies and test our modules in isolation from the state of the rest of the system.

Another important aspect to be highlighted from the example we presented earlier is that we shifted the dependency wiring responsibility from the bottom to the top of our architecture. The idea is that high-level components are by nature less reusable than low-level components, and that's because the more we go up in the layers of an application, the more a component becomes specific.

Starting from this assumption, we can then understand that the conventional way to see an application architecture where high-level components own their lower-level dependencies can be inverted, so that the lower-level components depend only on an interface (in JavaScript, it's just the interface that we expect from a dependency), while the ownership of defining the implementation of a dependency is given to the higher-level components. In our authentication server, in fact, all the dependencies are instantiated and wired in the topmost component, the app module, which is also the less reusable and so is the most expendable in terms of coupling.

All these advantages in terms of decoupling and reusability, though, come with a price to pay. In general, the inability to resolve a dependency at coding time makes it more difficult to understand the relationship between the various components of a system. Also, if we look at the way we instantiated all the dependencies in the app module, we can see that we had to follow a specific order; we practically had to manually build the dependency graph of the entire application. This can become unmanageable when the number of modules to wire becomes high.

A viable solution to this problem is to split the dependency ownership between multiple components, instead of having it centralized all in one place. This can reduce the complexity involved in managing the dependencies exponentially, as each component would be responsible only for its particular dependency subgraph. Of course, we can also choose to use DI only locally, just when necessary, instead of building the entire application on top of it.

We will see later in the chapter that another possible solution to simplify the wiring of modules in complex architectures is to use a DI container, a component exclusively responsible for instantiating and wiring all the dependencies of an application.

Using DI surely increases the complexity and verbosity of our modules, but as we saw earlier, there are many good reasons for doing this. It is up to us to choose the right approach, depending on the balance between simplicity and reusability that we want to obtain.

We are now going to convert the authentication server to use an injected service locator. To do this, the first step is to implement the service locator itself; we will use a new module, lib/serviceLocator.js:

module.exports = function() { 
  const dependencies = {}; 
  const factories = {}; 
  const serviceLocator = {}; 
 
  serviceLocator.factory = (name, factory) => {     //[1] 
    factories[name] = factory; 
  }; 
 
  serviceLocator.register = (name, instance) => {   //[2] 
    dependencies[name] = instance; 
  }; 
 
  serviceLocator.get = (name) => {                  //[3] 
    if(!dependencies[name]) { 
      const factory = factories[name]; 
      dependencies[name] = factory && factory(serviceLocator); 
      if(!dependencies[name]) { 
        throw new Error('Cannot find module: ' + name); 
      } 
    } 
    return dependencies[name]; 
  }; 
 
  return serviceLocator; 
}; 

Our serviceLocator module is a factory returning an object with three methods:

const dependencies = {};
 const db = require('./lib/db'); 
const authService = require('./lib/authService'); 
 dependencies.db = db(); 
dependencies.authService = authService(dependencies); 

Let's now convert the lib/db.js module straight away to demonstrate how our serviceLocator works:

const level = require('level'); 
const sublevel = require('level-sublevel'); 
 
module.exports = (serviceLocator) => { 
  const dbName = serviceLocator.get('dbName'); 
 
  return sublevel( 
    level(dbName, {valueEncoding: 'json'}) 
  ); 
} 

The db module uses the service locator received in input to retrieve the name of the database to instantiate. This is an interesting point to highlight; a service locator can be used not only to return component instances but also to provide configuration parameters that define the behavior of the entire dependency graph that we want to create.

The next step is to convert the lib/authService.js module:

// ... 
module.exports = (serviceLocator) => { 
  const db = serviceLocator.get('db'); 
  const tokenSecret = serviceLocator.get('tokenSecret'); 
 
  const users = db.sublevel('users'); 
  const authService = {}; 
 
  authService.login = (username, password, callback) => { 
    //...same as in the previous version 
  } 
 
  authService.checkToken = (token, callback) => { 
    //...same as in the previous version 
  } 
 
  return authService; 
}; 

Also, the authService module is a factory that takes the service locator as the input. The two dependencies of the module, the db handle and tokenSecret (which is another configuration parameter), are retrieved using the get() method of the service locator.

In a similar way, we can convert the lib/authController.js module:

module.exports = (serviceLocator) => { 
  const authService = serviceLocator.get('authService'); 
  const authController = {}; 
 
  authController.login = (req, res, next) => { 
    //...same as in the previous version 
  }; 
 
  authController.checkToken = (req, res, next) => { 
    //...same as in the previous version 
  }; 
 
  return authController; 
} 

Now we are ready to see how the service locator is instantiated and configured. This happens, of course, in the app.js module:

//... 
const svcLoc = require('./lib/serviceLocator')();      //[1] 
 
svcLoc.register('dbName', 'example-db');               //[2] 
svcLoc.register('tokenSecret', 'SHHH!'); 
svcLoc.factory('db', require('./lib/db')); 
svcLoc.factory('authService', require('./lib/authService')); 
svcLoc.factory('authController', require('./lib/authController')); 
 
const authController = svcLoc.get('authController');   //[3] 
 
app.post('/login', authController.login); 
app.all('/checkToken', authController.checkToken); 
// ... 

This is how the wiring works using our new service locator:

It's interesting to see the lazy nature of the service locator; each instance is created only when needed. But there is another important implication: we can see, in fact, that every dependency is automatically wired without the need to manually do it in advance. The advantage is that we don't have to know in advance what the right order for instantiating and wiring the modules is—it all happens automatically and on-demand. This is much more convenient compared to the simple DI pattern.

Service locator and Dependency Injection have a lot in common: both shift the dependency ownership to an entity external to the component. But the way we wire the service locator determines the flexibility of our entire architecture. It is not by chance that we chose an injected service locator to implement our example, as opposed to a hardcoded or global service locator. These last two variations almost nullify the advantages of this pattern. In fact, the result would be that, instead of coupling a component directly to its dependencies using require(), we would be coupling it to one particular instance of the service locator. It's also true that a hardcoded service locator will still give more flexibility in configuring what component to associate with a particular name, but this still does not give any big advantage in terms of reusability.

Also, like DI, using a service locator makes it harder to identify the relationship between the components as they are resolved at runtime. In addition, it also makes it more difficult to know exactly what dependency a particular component is going to require. With DI, this is expressed in a much clearer way: by declaring the dependencies in the factory or constructor arguments. With a service locator, this is much less clear and would require a code inspection or an explicit statement in the documentation explaining what dependencies a particular component will try to load.

As a final note, it is important to know that often a service locator is incorrectly mistaken for a DI container because it shares the same role of service registry with it; however, there is a big difference between the two. With a service locator, each component loads its dependencies explicitly from the service locator itself. When using a DI container instead, the component has no knowledge of the container.

The difference between these two approaches is noticeable for two reasons:

In terms of reusability, we can say that the service locator pattern sits inbetween hardcoded dependencies and DI. In terms of convenience and simplicity, it is definitely better than manual DI, as we don't have to manually take care of building the entire dependency graph.

Under these assumptions, a DI container definitely offers the best compromise in terms of reusability of the components and convenience. We are going to better analyze this pattern in the next section.

A DI container is essentially a service locator with the addition of one feature: it identifies the dependency requirements of a module before instantiating it. For this to be possible, a module has to declare its dependencies in some way, and as we will see, we have multiple options for doing this.

The first, and probably the most popular, technique consists of injecting a set of dependencies based on the arguments' names used in a factory or constructor. Let's take, for example, the authService module:

module.exports = (db, tokenSecret) => { 
  //... 
} 

As we defined it, the preceding module will be instantiated by our DI container using the dependencies with names db and tokenSecret—a very simple and intuitive mechanism. However, to be able to read the names of the arguments of a function, it's necessary to use a little trick. In JavaScript, we have the possibility to serialize a function, obtaining at runtime its source code; this is as easy as invoking toString() on the function reference. With regular expressions, obtaining the arguments list is certainly not black magic.

The biggest problem of this approach is that it doesn't play well with minification, a practice used extensively in client-side JavaScript which consists of applying particular code transformations to reduce to the minimum the size of the source code. Many minificators apply a technique known as name mangling, which essentially renames any local variable to reduce its length, usually to a single character. The bad news is that function arguments are local variables and are usually affected by this process, causing the mechanism that we described for declaring dependencies to fall apart. Even though minification is not really necessary in server-side code, it's important to consider that often Node.js modules are shared with the browser, and this is an important factor to consider in our analysis.

Luckily, a DI container might use other techniques to know which dependencies to inject. These techniques are given as follows:

       module.exports = (a, b) => {}; 
       module.exports._inject = ['db', 'another/dependency']; 

       module.exports = ['db', 'another/depencency',(a, b) => {}]; 

       module.exports = function(a /*db*/, b /*another/depencency*/) {}; 

All these techniques are quite opinionated, so for our example, we are going to use the most simple and popular, which is to obtain the dependency names using the arguments of a function.

To demonstrate how a DI container is much less invasive than a service locator, we are now going to again refactor our authentication server, and to do so we are going to use as a starting point the version in which we were using the plain DI pattern. In fact, what we are going to do is just leave untouched all the components of the application except for the app.js module, which is going to be the module responsible for initializing the container.

But first, we need to implement our DI container. Let's do that by creating a new module called diContainer.js under the lib/ directory. This is its initial part:

const fnArgs= require('parse-fn-args'); 
 
module.exports = function() { 
  const dependencies = {}; 
  const factories = {}; 
  const diContainer = {}; 
 
  diContainer.factory = (name, factory) => { 
    factories[name] = factory; 
  }; 
 
  diContainer.register = (name, dep) => { 
    dependencies[name] = dep; 
  }; 
 
  diContainer.get = (name) => { 
    if(!dependencies[name]) { 
      const factory = factories[name]; 
      dependencies[name] = factory && 
          diContainer.inject(factory); 
      if(!dependencies[name]) { 
        throw new Error('Cannot find module: ' + name); 
      } 
    } 
    return dependencies[name]; 
  }; 
  //...to be continued 

The first part of the diContainer module is functionally identical to the service locator we have seen previously. The only notable differences are:

Let's see how the diContainer.inject() method looks:

diContainer.inject = (factory) => { 
  const args = fnArgs(factory) 
  .map(dependency => diContainer.get(dependency)); 
    return factory.apply(null, args); 
  }; 
 
}; //end of module.exports = function() { 

The preceding method is what makes the DI container different from a service locator. Its logic is very straightforward:

That's really it for our diContainer. As we saw, it's not that much different from a service locator, but the simple step of instantiating a module by injecting its dependencies makes a dramatic difference (as compared to injecting the entire service locator).

To complete the refactoring of the authentication server, we also need to tweak the app.js module:

// ... 
const diContainer = require('./lib/diContainer')(); 
 
diContainer.register('dbName', 'example-db'); 
diContainer.register('tokenSecret', 'SHHH!'); 
diContainer.factory('db', require('./lib/db')); 
diContainer.factory('authService', require('./lib/authService')); 
diContainer.factory('authController', require('./lib/authController')); 
 
const authController = diContainer.get('authController'); 
 
app.post('/login', authController.login); 
app.get('/checkToken', authController.checkToken); 
// ... 

As we can see, the code of the app module is identical to the one that we used to initialize the service locator in the previous section. We can also notice that to bootstrap the DI container, and therefore trigger the loading of the entire dependency graph, we still have to use it as a service locator by invoking diContainer.get('authController'). From that point on, every module registered with the DI container will be instantiated and wired automatically.

A DI container assumes that our modules use the DI pattern and therefore inherit most of its pros and cons. In particular, we have an improved decoupling and testability, but on the other hand more complexity, because our dependencies are resolved at runtime. A DI container also shares many properties with the service locator pattern, but it has on its side the fact that it doesn't force the modules to depend on any extra service except its actual dependencies. This is a huge advantage because it allows each module to be used even without the DI container, using a simple manual injection.

That's essentially what we demonstrated in this section: we took the version of the authentication server where we used the plain DI pattern, and then without modifying any of its components (except for the app module), we were able to automatize the injection of every dependency.