Introduction

Dependency Injection is atechnique where the construction of dependencies of a class or function isseparated from its behavior, in order to keep the codeloosely coupled.

For example, the Sequence Action authenticate in @loopback/authenticationsupports different authentication strategies (e.g. HTTP Basic Auth, OAuth2,etc.). Instead of hard-coding some sort of a lookup table to find the rightstrategy instance, the authenticate action uses dependency injection to letthe caller specify which strategy to use.

The implementation of the authenticate action is shown below.

export class AuthenticateActionProvider implements Provider<AuthenticateFn> {
  constructor(
    // The provider is instantiated for Sequence constructor,
    // at which time we don't have information about the current
    // route yet. This information is needed to determine
    // what auth strategy should be used.
    // To solve this, we are injecting a getter function that will
    // defer resolution of the strategy until authenticate() action
    // is executed.
    @inject.getter(AuthenticationBindings.STRATEGY)
    readonly getStrategy: Getter<AuthenticationStrategy>,
    @inject.setter(AuthenticationBindings.CURRENT_USER)
    readonly setCurrentUser: Setter<UserProfile>,
  ) {}
  /**
   * @returns AuthenticateFn
   */
  value(): AuthenticateFn {
    return request => this.action(request);
  }
  /**
   * The implementation of authenticate() sequence action.
   * @param request - The incoming request provided by the REST layer
   */
  async action(request: Request): Promise<UserProfile | undefined> {
    const strategy = await this.getStrategy();
    if (!strategy) {
      // The invoked operation does not require authentication.
      return undefined;
    }
    const userProfile = await strategy.authenticate(request);
    if (!userProfile) {
      // important to throw a non-protocol-specific error here
      let error = new Error(
        `User profile not returned from strategy's authenticate function`,
      );
      Object.assign(error, {
        code: USER_PROFILE_NOT_FOUND,
      });
      throw error;
    }
    this.setCurrentUser(userProfile);
    return userProfile;
  }
}

Dependency Injection makes the code easier to extend and customize, because thedependencies can be easily rewired by the application developer. It makes thecode easier to test in isolation (in a pure unit test), because the test caninject a custom version of the dependency (a mock or a stub). This is especiallyimportant when testing code interacting with external services like a databaseor an OAuth2 provider. Instead of making expensive network requests, the testcan provide a lightweight implementation returning pre-defined responses.

Configure what to inject

Now that we write a class that gets the dependencies injected, you are probablywondering where are these values going to be injected from and how to configurewhat should be injected. This part is typically handled by an IoC Container,where IoC meansInversion of Control.

In LoopBack, we use Context to keep track of all injectabledependencies.

There are several different ways for configuring the values to inject, thesimplest options is to call app.bind(key).to(value).

export namespace JWTAuthenticationStrategyBindings {
  export const TOKEN_SECRET = BindingKey.create<string>(
    'authentication.strategy.jwt.secret',
  );
  export const TOKEN_EXPIRES_IN = BindingKey.create<string>(
    'authentication.strategy.jwt.expires.in.seconds',
  );
}
...
server
  .bind(JWTAuthenticationStrategyBindings.TOKEN_SECRET)
  .to('myjwts3cr3t');
server
  .bind(JWTAuthenticationStrategyBindings.TOKEN_EXPIRES_IN)
  .to('600');

However, when you want to create a binding that will instantiate a class andautomatically inject required dependencies, then you need to use .toClass()method:

server.bind(TokenServiceBindings.TOKEN_SERVICE).toClass(TokenService);
const tokenService = await server.get(TokenServiceBindings.TOKEN_SERVICE);
// tokenService is a TokenService instance

When a binding is created via .toClass(), Context will create anew instance of the class when resolving the value of this binding, injectingconstructor arguments and property values as configured via @inject decorator.

Note that the dependencies to be injected could be classes themselves, in whichcase Context will recursively instantiate these classes first,resolving their dependencies as needed.

In this particular example, the class is aProvider. Providers allow you to customize theway how a value is created by the Context, possibly depending on other Contextvalues. A provider is typically bound using .toProvider() API:

app
  .bind(AuthenticationBindings.AUTH_ACTION)
  .toProvider(AuthenticateActionProvider);
const authenticate = await app.get(AuthenticationBindings.AUTH_ACTION);
// authenticate is the function returned by provider's value() method

You can learn more about Providers inCreating Components.

Flavors of Dependency Injection

LoopBack supports three kinds of dependency injection:

• constructor injection: the dependencies are provided as arguments of theclass constructor.
• property injection: the dependencies are stored in instance properties afterthe class was constructed.
• method injection: the dependencies are provided as arguments of a methodinvocation. Please note that constructor injection is a special form ofmethod injection to instantiate a class by calling its constructor.

Constructor injection

This is the most common flavor that should be your default choice.

class ProductController {
  constructor(@inject('repositories.Product') repo) {
    this.repo = repo;
  }
  async list() {
    return this.repo.find({where: {available: true}});
  }
}

Property injection

Property injection is usually used for optional dependencies which are notrequired for the class to function or for dependencies that have a reasonabledefault.

class InfoController {
  @inject('logger', {optional: true})
  private logger = ConsoleLogger();
  status() {
    this.logger.info('Status endpoint accessed.');
    return {pid: process.pid};
  }
}

Method injection

Method injection allows injection of dependencies at method invocation level.The parameters are decorated with @inject or other variants to declaredependencies as method arguments.

class InfoController {
  greet(@inject(AuthenticationBindings.CURRENT_USER) user: UserProfile) {
    return `Hello, ${user.name}`;
  }
}

Optional dependencies

Sometimes the dependencies are optional. For example, the logging level for aLogger provider can have a default value if it is not set (bound to thecontext).

To resolve an optional dependency, set optional flag to true:

const ctx = new Context();
await ctx.get('optional-key', {optional: true});
// returns `undefined` instead of throwing an error

Here is another example showing optional dependency injection using propertieswith default values:

// Optional property injection
export class LoggerProvider implements Provider<Logger> {
  // Log writer is an optional dependency and it falls back to `logToConsole`
  @inject('log.writer', {optional: true})
  private logWriter: LogWriterFn = logToConsole;
  // Log level is an optional dependency with a default value `WARN`
  @inject('log.level', {optional: true})
  private logLevel: string = 'WARN';
}

Optional dependencies can also be used with constructor and method injections.

An example showing optional constructor injection in action:

export class LoggerProvider implements Provider<Logger> {
  constructor(
    // Log writer is an optional dependency and it falls back to `logToConsole`
    @inject('log.writer', {optional: true})
    private logWriter: LogWriterFn = logToConsole,
    // Log level is an optional dependency with a default value `WARN`
    @inject('log.level', {optional: true}) private logLevel: string = 'WARN',
  ) {}
}

An example of optional method injection, where the prefix argument isoptional:

export class MyController {
  greet(@inject('hello.prefix', {optional: true}) prefix: string = 'Hello') {
    return `${prefix}, world!`;
  }
}

Additional inject.* decorators

There are a few special decorators from the inject namespace.

• @inject.getter
• @inject.setter
• @inject.binding
• @inject.context
• @inject.tag
• @inject.viewSee Inject decorators for more details.

Circular dependencies

LoopBack can detect circular dependencies and report the path which leads to theproblem.

Consider the following example:

import {Context, inject} from '@loopback/context';
interface Developer {
  // Each developer belongs to a team
  team: Team;
}
interface Team {
  // Each team works on a project
  project: Project;
}
interface Project {
  // Each project has a lead developer
  lead: Developer;
}
class DeveloperImpl implements Developer {
  constructor(@inject('team') public team: Team) {}
}
class TeamImpl implements Team {
  constructor(@inject('project') public project: Project) {}
}
class ProjectImpl implements Project {
  constructor(@inject('lead') public lead: Developer) {}
}
const context = new Context();
context.bind('lead').toClass(DeveloperImpl);
context.bind('team').toClass(TeamImpl);
context.bind('project').toClass(ProjectImpl);
try {
  // The following call will fail
  context.getSync('lead');
} catch (e) {
  console.error(e.toString());
}

When the user attempts to resolve “lead” binding, LoopBack detects a circulardependency and prints the following error:

Error: Circular dependency detected:
  lead --> @DeveloperImpl.constructor[0] -->
  team --> @TeamImpl.constructor[0] -->
  project --> @ProjectImpl.constructor[0] -->
  lead

Dependency injection for bindings with different scopes

Contexts can form a chain and bindings can be registered at different levels.The binding scope controls not only how bound values are cached, but also howits dependencies are resolved.

Let’s take a look at the following example:

The corresponding code is:

import {inject, Context, BindingScope} from '@loopback/context';
import {RestBindings} from '@loopback/rest';
interface Logger() {
  log(message: string);
}
class PingController {
  constructor(@inject('logger') private logger: Logger) {}
}
class MyService {
  constructor(@inject('logger') private logger: Logger) {}
}
class ServerLogger implements Logger {
  log(message: string) {
    console.log('server: %s', message);
  }
}
class RequestLogger implements Logger {
  // Inject the http request
  constructor(@inject(RestBindings.Http.REQUEST) private req: Request) {}
  log(message: string) {
    console.log('%s: %s', this.req.url, message);
  }
}
const appCtx = new Context('application');
appCtx
  .bind('controllers.PingController')
  .toClass(PingController)
  .inScope(BindingScope.TRANSIENT);
const serverCtx = new Context(appCtx, 'server');
serverCtx
  .bind('my-service')
  .toClass(MyService)
  .inScope(BindingScope.SINGLETON);
serverCtx.bind('logger').toClass(ServerLogger);

Please note that my-service is a SINGLETON for the server context subtreeand it expects a logger to be injected.

Now we create a new context per request:

const requestCtx = new Context(serverCtx, 'request');
requestCtx.bind('logger').toClass(RequestLogger);
const myService = await requestCtx.get<MyService>('my-service');
// myService.logger should be an instance of `ServerLogger` instead of `RequestLogger`
requestCtx.close();
// myService survives as it's a singleton

Dependency injection for bindings in SINGLETON scope is resolved using theowner context instead of the current one. This is needed to ensure that resolvedsingleton bindings won’t have dependencies from descendant contexts, which canbe closed before the owner context. The singleton cannot have danglingreferences to values from the child context.

The story is different for PingController as its binding scope is TRANSIENT.

const requestCtx = new Context(serverCtx, 'request');
requestCtx.bind('logger').toClass(RequestLogger);
const pingController = await requestCtx.get<PingController>(
  'controllers.PingController',
);
// pingController.logger should be an instance of `RequestLogger` instead of `ServerLogger`

A new instance of PingController is created for each invocation ofawait requestCtx.get<PingController>('controllers.PingController') and itslogger is injected to an instance of RequestLogger so that it can loginformation (such as url or request-id) for the request.

The following table illustrates how bindings and their dependencies areresolved.

Additional resources

• Dependency Injection onWikipedia
• Dependency Inversion Principleon Wikipedia