@mgdigital/tsinject

Lightweight and flexible dependency injection container for TypeScript.

Documentation

Install with npm add @mgdigital/tsinject or yarn add @mgdigital/tsinject.

Motivation

Several dependency injection solutions exist for TypeScript. Most use either decorators (Inversify; TSyringe) or static class properties (Angular). This has several drawbacks:

✗ The types of service that can be defined are restricted to class instances.

✗ The code of the class needs modifying to work with the container (e.g. by adding decorators or static properties).

✗ It will only work with the experimentalDecorators compiler option enabled.

tsinject adopts an alternative approach with several objectives:

✓ Flexibility, composability and reusability of components

✓ Sharing global resources while avoiding global side effects

✓ Achieving loose coupling in large applications

tsinject works by defining named factory functions in a container builder, with unique symbols mapping services available in the container to their type. These factory functions can return anything, allowing configuration objects, class instances, functions or any other type of value to be defined as a container service. Any code can be containerized without need for modifications such as annotations or static properties.

Any application that does something useful needs to cause side effects. These might include:

Reading or writing some data in a database
Checking the current date and time
Asking the user for input
Logging a message to the console

These capabilities are implemented by components of the application, with some components depending on others, and with the implementation or configuration of components often depending on values read from the environment. The quickest way to allow components to communicate with each other is often via globally defined singleton instances. This increases complexity, making code more difficult to debug, test and maintain. Instead, by building components that have their dependencies injected, we can create complex but decoupled applications.

Usage

Creating a container module and defining services

Take the example of a logging component, that defines services in a container using the following keys (see ./examples/container/loggingModule/keys.ts):

export const loggerConfig = Symbol('loggerConfig') // Provides config values for other logger services
export const logFormatter = Symbol('logFormatter') // Formats log data to a log line string
export const logWriter = Symbol('logWriter') // Writes log lines, e.g. to the console or to a file
export const logger = Symbol('logger') // The logger service that will be used by consumers of this component

We can make a map of container keys to the type of service they represent (see ./examples/container/loggingModule/services.ts):

import type { ILogger, LogFormatter, LoggerConfig, LogWriter } from '../../logging/types'
import type * as keys from './keys'

type LoggingServices = {
  [keys.loggerConfig]: LoggerConfig
  [keys.logFormatter]: LogFormatter
  [keys.logWriter]: LogWriter
  [keys.logger]: ILogger
}

export default LoggingServices

We can then create a ContainerModule by defining a factory function for each service key (see ./examples/container/loggingModule/module.ts):

import type { ContainerModule } from '@mgdigital/tsinject'
import type LoggingServices from './services'
import * as processEnvModule from '../processEnvModule'
import * as keys from './keys'
import consoleLogWriter from '../../logging/consoleLogWriter'
import Logger from '../../logging/Logger'
import loggerConfigFromEnv from '../../logging/config/loggerConfigFromEnv'
import prettyLogFormatter from '../../logging/prettyLogFormatter'
import simpleLogFormatter from '../../logging/simpleLogFormatter'

const loggingModule: ContainerModule<
  processEnvModule.services &
  LoggingServices
> = builder => builder
  // Use another container module that provides services required by this one
  .use(processEnvModule.default)
  // Define a config object based on environment variables
  .define(
    keys.loggerConfig,
    container => loggerConfigFromEnv(
      container.get(processEnvModule.keys.processEnv)
    )
  )
  // Provide a different implementation depending on environment variable configuration
  .define(
    keys.logFormatter,
    container => container.get(keys.loggerConfig).pretty
      ? prettyLogFormatter
      : simpleLogFormatter
  )
  .define(
    keys.logWriter,
    () => consoleLogWriter
  )
  .define(
    keys.logger,
    container => new Logger(
      container.get(keys.logFormatter),
      container.get(keys.logWriter),
      container.get(keys.loggerConfig).level
    )
  )

export default loggingModule

We can now create a container from this module, get the logger service from the container and log something:

import { newContainerBuilder } from '@mgdigital/tsinject'
import * as loggingModule from './examples/container/loggingModule'

const container = newContainerBuilder()
  .use(loggingModule.default)
  .createContainer()

const logger = container.get(loggingModule.keys.logger)

logger.info('Logging something!')

Note: We should only call IContainer.get from within a factory function or from the composition root, avoiding the service locator anti-pattern.

Note: When defining a service in the container, if that service key is already defined then the key will not be overwritten. This allows modules to be used multiple times without introducing unpredictable behaviour when using decorators. For example, if modules A and B both depend on module C, they can both use module C, and then be used together module D, where they will share the same dependency instance from module C. If an already defined service needs to be overwritten, this can be done with a decorator.

Decorators

Decorators allow us to modify an already-defined service. Let's create a custom logging module that decorates some of the services in the base module defined above:

import type { ContainerModule } from '@mgdigital/tsinject'
import * as loggingModule from './examples/container/loggingModule'

const myCustomLoggingModule: ContainerModule<
  loggingModule.services
> = builder => builder
  .use(loggingModule.default)
  // Decorate the logger config so that output is always pretty
  .decorate(
    loggingModule.keys.loggerConfig,
    factory => container => ({
      ...factory(container),
      pretty: true
    })
  )
  // Decorate the log formatter to append an exclamation mark to all log entries
  .decorate(
    loggingModule.keys.logFormatter,
    factory => container => {
      const baseFormatter = factory(container)
      return (level, message, data) =>
        baseFormatter(level, message, data) + '!'
    }
  )
  // Overwrite the log writer with some other implementation
  .decorate(
    loggingModule.keys.logWriter,
    () => () => myCustomLogWriter
  )

We can also use decorators to achieve features that aren't explicitly implemented in this library, such as service tagging, which we can do by defining a service as a key-value object (actually, a simple array might do for some cases but using key-values prevents accidental duplicates if modules are reused):

import type { ContainerKey, ContainerModule } from '@mgdigital/tsinject'
import { containerKeyValues } from '@mgdigital/tsinject'

// Assume a type of service that we wish to tag, along with a sevice that depends on the tagged services.

class TaggedService {}

class TaggedServiceConsumer {
  constructor (
    public readonly taggedServices: TaggedService[]
  ) {}
}

const serviceTag = Symbol('serviceTag')
const taggedServiceConsumer = Symbol('taggedServiceConsumer')

type ParentModuleServiceMap = {
  // `TaggedServiceConsumer` depends on an array, but using an object here prevents accidental duplicates.
  [serviceTag]: Record<ContainerKey, TaggedService>
  [taggedServiceConsumer]: TaggedServiceConsumer
}

const parentModule: ContainerModule<
  ParentModuleServiceMap
> = builder => builder
  // Define an empty object of tagged services
  .define(
    serviceTag,
    () => ({})
  )
  .define(
    taggedServiceConsumer,
    container => new TaggedServiceConsumer(
      // This utility method converts the tagged service object to an array
      containerKeyValues(
        container.get(serviceTag)
      )
    )
  )

// Then define child modules that will provide tagged services

const taggedService = Symbol('taggedService')

type ChildModuleServiceMap = {
  [taggedService]: TaggedService
}

const childModule: ContainerModule<
  ParentModuleServiceMap &
  ChildModuleServiceMap
> = builder => builder
  .use(parentModule)
  .define(
    taggedService,
    () => new TaggedService()
  )
  .decorate(
    serviceTag,
    // Add a service to the array of already tagged services
    factory => container => ({
      ...factory(container),
      [taggedService]: container.get(taggedService)
    })
  )

And that's it - unlike some other DI containers that claim to be lightweight, tsinject really is tiny and has a simple API, allowing large and complex but loosely coupled applications to be built from small, simple and easily testable components.

See the examples folder for a more complete application. It includes a simple tasks service with a REST API that can be started by cloning this repository and running yarn install, yarn build then yarn example:start.