Why you need an IoC container?

[thetutlage]

The code examples shared in this post are imaginary and simplified to discuss the concept of IoC container at theoretical level.

It's usually a good idea to question the existence of an additional layer we are about to introduce in our code and what purpose it serves.

Also, JavaScript/TypeScript does not come with all the bells and whistles; you need to have similar IoC container benefits as PHP or Java. Therefore the list of reasons to use the container is relatively small but compelling.

Terms in use

• Author of the code: A developer who publishes a package.
• User of the code: A developer who uses the published package in their app.
• Binding: A unique name for a value registered inside the container.

Offloading construction boilerplate to the "author of the code."

One of the biggest (in fact, the primary benefit) of using the IoC container is to hide the boilerplate for constructing objects from the User of the code.

Following is a simplified version of code from one of my packages (@adonisjs/drive).

class LocalDriver {
  constructor (config, router) {}
}

class Router {
  constructor (config, encryptor) {}
}

class Encryptor {
  constructor (config) {}
}

As you can notice, to create an instance of the LocalDriver class, we need its config and the router, then Router needs the encryptor, and the Encryptor needs its config.

These dependencies needed to be in a single place to be passed around and construct the final object we want to use.

This might not be a huge problem for smaller applications. However, the framework the size of AdonisJS has a lot of classes relying on each (via Dependency injection), and constructing all the objects by hand can get very messy.

How does the container solves this?

A container is a glorified object which allows you to store dependencies in one place. Here's what the flow looks like in practice:

• The Encryptor class will register itself inside the container with a unique name (publicly shared).

  container.bind('Encryptor', () => {
    /*
     * We will later figure out how to
     * get this config object
     */
    return new Encryptor(config)
  })

• Anyone who needs the Encryptor can ask the container to give it by using its name. The container behind the scenes will run the callback passed to the bind method and returns its value.

  encryptor = container.resolve('Encryptor')

• Similar to the encryptor, all other classes can register themselves within the container.

  container.bind('Router', () => {
    return new Router(config, container.resolve('Encryptor'))
  })

  container.bind('LocalDriver', () => {
    return new LocalDriver(config, container.resolve('Router'))
  })

When you need the local driver, you can call container.resolve('LocalDriver'), and everything will be constructed on-demand.

Essentially, we have offloaded the responsibility of constructing objects from the user of the code to the author of these individual packages.

How to resolve the config required by container bindings?

In our previous examples of container.bind, you can notice that most classes need config to construct class instances.

So, how do they get access to this config object? By using convention over configuration.

Let's introduce another class called Config, which uses a conventional directory to import all the configuration files and make them available from this class.

class Config {
  constructor (configTree) {
  }
  
  get(key) {
    return this.configTree[key]
  }
}

Next, we can bind it to the container as follows.

container.bind('Config', async () => {
  const configDir = join(
    container.resolve('appRoot'),
    'config'
  )

  const configTree = await importAll(configDir)

  return new Config(configTree)
})

• The Config class relies on a convention that we will store all the configuration files inside the config directory.
• The appRoot variable is something you need to put into the container when bootstrapping the application manually.

As a result, all other classes can now use the Config Binding to look up the configuration.

The Encryptor expects the config to be stored inside the config/encryptor.js file.

container.bind('Encryptor', () => {
  const Config = container.resolve('Config')
  const encryptorConfig = Config.get('encryptor')
  
  return new Encryptor(encryptorConfig)
})

Isn't using string literals for binding names a wrong choice?

It might appear that using a string value for the container bindings will give rise to all sorts of issues.

Strings are not unique, and two authors can bind a value under the same name, there can be typos when resolving bindings, and so on.

These issues do not exist (at least on a larger scale). The Java Spring IoC container, and PHP PSR standard all recommend and use strings for bindings. Even in AdonisJS, we have used string-based binding names, and no one has ever complained about naming conflicts.

Even then, if you are not convinced, you can use symbols in JavaScript to bind and lookup container bindings. This is because the JavaScript engine treats two symbols even with the same value as unique.

Symbol('foo') === Symbol('foo')
// false

Let's say you are the author of the Encryptor package. You can use the symbols as follows.

1. Have a file that exports this symbol.

export const ENCRYPTOR_BINDING = Symbol('Encryptor')

2. Use the symbol to register the Binding

import { ENCRYPTOR_BINDING } from './index.js'

container.bind(ENCRYPTOR_BINDING, () => {
  return new Encryptor(config)
})

3. Mention in the README to use the symbol to perform the lookup.

import { ENCRYPTOR_BINDING } from 'encryptor-package'

container.resolve(ENCRYPTOR_BINDING)

I do not use symbols as they make the code visually cluttered (the take is subjective). Since using the container itself is a first step in creating a loosely coupled system, pairing that with string-based binding names should be acceptable.

It's easier to fake and mock implementations

Jest is a popular JavaScript testing framework. It comes with out of the box support for mocking classes (mainly modules). Following is a code snippet from their docs.

1. Given there is a ./sound-player.js file with the following contents.

export default class SoundPlayer {
  constructor() {
    this.foo = 'bar';
  }

  playSoundFile(fileName) {
    console.log('Playing sound file ' + fileName);
  }
}

2. You can mock it by its path.

jest.mock('./sound-player', () => {
  return jest.fn().mockImplementation(() => {
    return {
      playSoundFile: jest.fn()
    }
  })
})

The above code works by mutating the modules cache you can access using the require.cache property in the CommonJS module system.

However, the same cannot work in ESM because one cannot access the tree of imports globally anywhere in the Node runtime. Maybe there is a way to make it all work with loader hooks, so let's wait and see how Jest solves this.

Instead of dabbling between different strategies of mocking for CJS and ESM. We can solve it with a layer of indirection inside the code, and the IoC container perfectly serves that purpose.

In the following example, our UserService class uses Encryptor as a constructor dependency.

class UserService {
  constructor (encryptor) {}
}

You can construct it in some other part of the code as follows.

new UserService(container.resolve('Encryptor'))

You can bind a fake/mocked implementation to the container during testing. We use the swap method in place of bind to later restore the original Binding.

container.swap('Encryptor', () => {
  return {
    encrypt: () => console.log('I have been called') 
  }
})

// write the test

container.restore('Encryptor')

And voila! It all works without relying on the underlying module system.

Why are IoC containers not in the mainstream in the JavaScript ecosystem?

As a community, we have not been able to decide whether to use semi-colons or not to use them. Therefore, it is expected not to have a consensus on using an IoC container.

As I mentioned earlier, the benefits of an IoC container are limited in a language like JavaScript, and Typescript doesn't improve much upon it.

In languages (to my limited knowledge) like PHP, you can extensively use interfaces for features like reflection and validating that an implementation adheres to an interface at runtime.

So maybe, the limited capabilities of a container are not compelling enough for every sub-community to use it. However, for AdonisJS, it has proved to be working great and helps us write cleaner code without having boilerplate all over the place.

[RodolfoSilva]

Very nice 👍🏽

[davidharting]

Great write up! I learned a lot.

[davidharting]

Regarding strings versus symbols for container bindings:

I think TypeScript makes strings way more robust and way less "magical." Because strings are treated as unique type literals. I use string identifiers without any worry. So I think this is a great choice.

I do wonder though if / how you achieve type safety with the container items. E.g., when you bind Encryptor, does container.resolve("encryptor") know the kind of object it will return?

[arthur-er]

Yes, it does

[thetutlage]

Yup, quite easy to do that with a generic. Here's a working example of the same.

Also, by using declaration merging you can extend the ContainerBindings interface from other packages as well. Think of it as, if the Encryptor is a separate package and Router is a separate package, then both the authors can bind these object to the container at runtime and also put them inside the interface as well

[LeadcodeDev]

Hello @thetutlage, I almost systematically design my applications with an IOC since I use Adonis.
One point you didn't address makes me wonder: how do you import a service from the ioc container with a native js/ts import (import xx from '@ioc:Adonis/xxxxx) and have it resolve the service from the container and not a local file ?

In any case, very good "article" if I may say so, that many people should look at with attention !

[Julien-R44]

Hey 👋
Take a look here : #1

[LeadcodeDev]

Oh ! I hadn't seen this article! Thanks a lot !