TSyringe

Lightweight dependency injection container for JavaScript/TypeScript

Dependency Injection
microsoft/tsyringetsyringe

README

TSyringe


A lightweight dependency injection container for TypeScript/JavaScript for
constructor injection.

Installation


Install by npm

  1. ```sh
  2. npm install --save tsyringe
  3. ```

or install with yarn (this project is developed using yarn)

  1. ```sh
  2. yarn add tsyringe
  3. ```

Modify your tsconfig.json to include the following settings

  1. ```json
  2. {
  3.   "compilerOptions": {
  4.     "experimentalDecorators": true,
  5.     "emitDecoratorMetadata": true
  6.   }
  7. }
  8. ```

Add a polyfill for the Reflect API (examples below use reflect-metadata). You can use:

- reflect-metadata
- core-js (core-js/es7/reflect)
- reflection

The Reflect polyfill import should only be added once, and before DI is used:

  1. ```typescript
  2. // main.ts
  3. import "reflect-metadata";

  5. // Your code here...
  6. ```

Babel


If you're using Babel (e.g. using React Native), you will need to configure it to emit TypeScript metadata.

First get the Babel plugin

Yarn


  1. ```
  2. yarn add --dev babel-plugin-transform-typescript-metadata
  3. ```

npm


  1. ```
  2. npm install --save-dev babel-plugin-transform-typescript-metadata
  3. ```

Then add it to your Babel config

  1. ```
  2. plugins: [
  3.             'babel-plugin-transform-typescript-metadata',
  4.             /* ...the rest of your config... */
  5.          ]
  6. ```

API


TSyringe performs Constructor Injection
on the constructors of decorated classes.

Decorators


injectable()


Class decorator factory that allows the class' dependencies to be injected at
runtime. TSyringe relies on several decorators in order to collect metadata about classes
to be instantiated.

Usage


  1. ```typescript
  2. import {injectable} from "tsyringe";

  4. @injectable()
  5. class Foo {
  6.   constructor(private database: Database) {}
  7. }

  9. // some other file
  10. import "reflect-metadata";
  11. import {container} from "tsyringe";
  12. import {Foo} from "./foo";

  14. const instance = container.resolve(Foo);
  15. ```

singleton()


Class decorator factory that registers the class as a singleton within the
global container.

Usage


  1. ```typescript
  2. import {singleton} from "tsyringe";

  4. @singleton()
  5. class Foo {
  6.   constructor() {}
  7. }

  9. // some other file
  10. import "reflect-metadata";
  11. import {container} from "tsyringe";
  12. import {Foo} from "./foo";

  14. const instance = container.resolve(Foo);
  15. ```

autoInjectable()


Class decorator factory that replaces the decorated class' constructor with
a parameterless constructor that has dependencies auto-resolved.

Note Resolution is performed using the global container.

Usage


  1. ```typescript
  2. import {autoInjectable} from "tsyringe";

  4. @autoInjectable()
  5. class Foo {
  6.   constructor(private database?: Database) {}
  7. }

  9. // some other file
  10. import {Foo} from "./foo";

  12. const instance = new Foo();
  13. ```

Notice how in order to allow the use of the empty constructor new Foo(), we
need to make the parameters optional, e.g. database?: Database.

inject()


Parameter decorator factory that allows for interface and other non-class
information to be stored in the constructor's metadata.

Usage


  1. ```typescript
  2. import {injectable, inject} from "tsyringe";

  4. interface Database {
  5.   // ...
  6. }

  8. @injectable()
  9. class Foo {
  10.   constructor(@inject("Database") private database?: Database) {}
  11. }
  12. ```

injectAll()


Parameter decorator for array parameters where the array contents will come from the container.
It will inject an array using the specified injection token to resolve the values.

Usage


  1. ```typescript
  2. import {injectable, injectAll} from "tsyringe";

  4. @injectable()
  5. class Foo {}

  7. @injectable()
  8. class Bar {
  9.   constructor(@injectAll(Foo) fooArray: Foo[]) {
  10.     // ...
  11.   }
  12. }
  13. ```

injectWithTransform()


Parameter decorator which allows for a transformer object to take an action on the resolved object
before returning the result.

  1. ```typescript
  2. class FeatureFlags {
  3.   public getFlagValue(flagName: string): boolean {
  4.     // ...
  5. }

  7. class Foo() {}

  9. class FeatureFlagsTransformer implements Transform<FeatureFlags, bool> {
  10.   public transform(flags: FeatureFlags, flag: string) {
  11.     return flags.getFlagValue(flag);
  12.   }
  13. }

  15. @injectable()
  16. class MyComponent(foo: Foo, @injectWithTransform(FeatureFlags, FeatureFlagsTransformer, "IsBlahEnabled") blahEnabled: boolean){
  17.   // ...
  18. }
  19. ```

injectAllWithTransform()


This parameter decorator allows for array contents to be passed through a transformer. The transformer can return any type, so this
can be used to map or fold an array.

  1. ```typescript
  2. @injectable()
  3. class Foo {
  4.   public value;
  5. }

  7. class FooTransform implements Transform<Foo[], string[]>{
  8.   public transform(foos: Foo[]): string[]{
  9.     return foos.map(f => f.value));
  10.   }
  11. }

  13. @injectable()
  14. class Bar {
  15.   constructor(@injectAllWithTransform(Foo, FooTransform) stringArray: string[]) {
  16.     // ...
  17.   }
  18. }
  19. ```

scoped()


Class decorator factory that registers the class as a scoped dependency within the global container.

Available scopes


- Transient
  - The default registration scope, a new instance will be created with each resolve
- Singleton
  - Each resolve will return the same instance (including resolves from child containers)
- ResolutionScoped
  - The same instance will be resolved for each resolution of this dependency during a single
    resolution chain
- ContainerScoped
  - The dependency container will return the same instance each time a resolution for this dependency
    is requested. This is similar to being a singleton, however if a child container is made, that child
    container will resolve an instance unique to it.

Usage


  1. ```typescript
  2. @scoped(Lifecycle.ContainerScoped)
  3. class Foo {}
  4. ```

Container


The general principle behind Inversion of Control (IoC) containers
is you give the container a _token_, and in exchange you get an instance/value. Our container automatically figures out the tokens most of the time, with 2 major exceptions, interfaces and non-class types, which require the @inject() decorator to be used on the constructor parameter to be injected (see above).

In order for your decorated classes to be used, they need to be registered with the container. Registrations take the
form of a Token/Provider pair, so we need to take a brief diversion to discuss tokens and providers.

Injection Token


A token may be either a string, a symbol, a class constructor, or a instance of [DelayedConstructor](#circular-dependencies).

  1. ```typescript
  2. type InjectionToken<T = any> =
  3.   | constructor<T>
  4.   | DelayedConstructor<T>
  5.   | string
  6.   | symbol;
  7. ```

Providers


Our container has the notion of a _provider_. A provider is registered with the DI
container and provides the container the information
needed to resolve an instance for a given token. In our implementation, we have the following 4
provider types:

Class Provider


  1. ```TypeScript
  2. {
  3.   token: InjectionToken<T>;
  4.   useClass: constructor<T>;
  5. }
  6. ```

This provider is used to resolve classes by their constructor. When registering a class provider
you can simply use the constructor itself, unless of course you're making an alias (a
class provider where the token isn't the class itself).

Value Provider


  1. ```TypeScript
  2. {
  3.   token: InjectionToken<T>;
  4.   useValue: T
  5. }
  6. ```

This provider is used to resolve a token to a given value. This is useful for registering
constants, or things that have a already been instantiated in a particular way.

Factory provider


  1. ```TypeScript
  2. {
  3.   token: InjectionToken<T>;
  4.   useFactory: FactoryFunction<T>;
  5. }
  6. ```

This provider is used to resolve a token using a given factory. The factory has full access
to the dependency container.

We have provided 2 factories for you to use, though any function that matches the `FactoryFunction` signature
can be used as a factory:

  1. ```typescript
  2. type FactoryFunction<T> = (dependencyContainer: DependencyContainer) => T;
  3. ```

instanceCachingFactory

This factory is used to lazy construct an object and cache result, returning the single instance for each subsequent
resolution. This is very similar to @singleton()

  1. ```typescript
  2. import {instanceCachingFactory} from "tsyringe";

  4. {
  5.   token: "SingletonFoo";
  6.   useFactory: instanceCachingFactory<Foo>(c => c.resolve(Foo));
  7. }
  8. ```

instancePerContainerCachingFactory

This factory is used to lazy construct an object and cache result per DependencyContainer, returning the single instance for each subsequent
resolution from a single container. This is very similar to @scoped(Lifecycle.ContainerScoped)

  1. ```typescript
  2. import {instancePerContainerCachingFactory} from "tsyringe";

  4. {
  5.   token: "ContainerScopedFoo";
  6.   useFactory: instancePerContainerCachingFactory<Foo>(c => c.resolve(Foo));
  7. }
  8. ```

predicateAwareClassFactory

This factory is used to provide conditional behavior upon resolution. It caches the result by default, but
has an optional parameter to resolve fresh each time.

  1. ```typescript
  2. import {predicateAwareClassFactory} from "tsyringe";

  4. {
  5.   token: "FooHttp",
  6.   useFactory: predicateAwareClassFactory<Foo>(
  7.     c => c.resolve(Bar).useHttps, // Predicate for evaluation
  8.     FooHttps, // A FooHttps will be resolved from the container if predicate is true
  9.     FooHttp // A FooHttp will be resolved if predicate is false
  10.   );
  11. }
  12. ```

Token Provider


  1. ```TypeScript
  2. {
  3.   token: InjectionToken<T>;
  4.   useToken: InjectionToken<T>;
  5. }
  6. ```

This provider can be thought of as a redirect or an alias, it simply states that given token _x_,
resolve using token _y_.

Register


The normal way to achieve this is to add DependencyContainer.register() statements somewhere
in your program some time before your first decorated class is instantiated.

  1. ```typescript
  2. container.register<Foo>(Foo, {useClass: Foo});
  3. container.register<Bar>(Bar, {useValue: new Bar()});
  4. container.register<Baz>("MyBaz", {useValue: new Baz()});
  5. ```

Registration options


As an optional parameter to .register() you may provide [RegistrationOptions](./src/types/registration-options.ts)
which customize how the registration behaves. See the linked source code for up to date documentation
on available options.