tsyringe is a lightweight dependency injection container for TypeScript and JavaScript applications. It helps manage class dependencies and promotes the use of the Inversion of Control (IoC) principle, making it easier to write modular, testable, and maintainable code.
Dependency Injection
This feature allows you to inject dependencies into classes. In the example, `Foo` is injected into `Bar`, and `Bar` can use `Foo`'s methods.
const { container, injectable, inject } = require('tsyringe');
@injectable()
class Foo {
log() {
console.log('Foo');
}
}
@injectable()
class Bar {
constructor(@inject(Foo) foo) {
this.foo = foo;
}
log() {
this.foo.log();
console.log('Bar');
}
}
const bar = container.resolve(Bar);
bar.log();Singleton Registration
This feature allows you to register a class as a singleton, ensuring that only one instance of the class is created and shared across the application.
const { container, singleton } = require('tsyringe');
@singleton()
class SingletonService {
constructor() {
this.id = Math.random();
}
}
const instance1 = container.resolve(SingletonService);
const instance2 = container.resolve(SingletonService);
console.log(instance1.id === instance2.id); // trueScoped Registration
This feature allows you to register a class with a scoped lifecycle, meaning a new instance is created for each container scope.
const { container, scoped, Lifecycle } = require('tsyringe');
@scoped(Lifecycle.ContainerScoped)
class ScopedService {
constructor() {
this.id = Math.random();
}
}
const childContainer = container.createChildContainer();
const instance1 = childContainer.resolve(ScopedService);
const instance2 = childContainer.resolve(ScopedService);
console.log(instance1.id === instance2.id); // true
const instance3 = container.resolve(ScopedService);
console.log(instance1.id === instance3.id); // falseCustom Providers
This feature allows you to register custom providers for dependencies, giving you more control over how dependencies are resolved.
const { container, inject, injectable } = require('tsyringe');
class CustomProvider {
get() {
return 'Custom Value';
}
}
container.register('CustomProvider', { useClass: CustomProvider });
@injectable()
class Consumer {
constructor(@inject('CustomProvider') provider) {
this.provider = provider;
}
log() {
console.log(this.provider.get());
}
}
const consumer = container.resolve(Consumer);
consumer.log(); // Custom ValueInversify is a powerful and flexible IoC container for TypeScript and JavaScript. It offers more advanced features like middleware, multi-injection, and context-based bindings. However, it has a steeper learning curve compared to tsyringe.
TypeDI is another dependency injection tool for TypeScript. It is similar to tsyringe in terms of ease of use and simplicity but offers additional features like service decorators and parameter decorators. It is slightly more feature-rich but also a bit more complex.
Awilix is a dependency injection container for JavaScript and TypeScript with a focus on developer experience. It offers features like lifecycle management and resolution modes. It is more flexible and configurable but can be more verbose compared to tsyringe.
A lightweight dependency injection container for TypeScript/JavaScript for constructor injection.
Install by npm
npm install --save tsyringe
or install with yarn (this project is developed using yarn)
yarn add tsyringe
Modify your tsconfig.json to include the following settings
{
"compilerOptions": {
"experimentalDecorators": true,
"emitDecoratorMetadata": true
}
}
Add a polyfill for the Reflect API (examples below use reflect-metadata). You can use:
The Reflect polyfill import should only be added once, and before DI is used:
// main.ts
import "reflect-metadata";
// Your code here...
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 add --dev babel-plugin-transform-typescript-metadata
npm install --save-dev babel-plugin-transform-typescript-metadata
Then add it to your Babel config
plugins: [
'babel-plugin-transform-typescript-metadata',
/* ...the rest of your config... */
]
TSyringe performs Constructor Injection on the constructors of decorated classes.
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.
import {injectable} from "tsyringe";
@injectable()
class Foo {
constructor(private database: Database) {}
}
// some other file
import "reflect-metadata";
import {container} from "tsyringe";
import {Foo} from "./foo";
const instance = container.resolve(Foo);
Class decorator factory that registers the class as a singleton within the global container.
import {singleton} from "tsyringe";
@singleton()
class Foo {
constructor() {}
}
// some other file
import "reflect-metadata";
import {container} from "tsyringe";
import {Foo} from "./foo";
const instance = container.resolve(Foo);
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.
import {autoInjectable} from "tsyringe";
@autoInjectable()
class Foo {
constructor(private database?: Database) {}
}
// some other file
import {Foo} from "./foo";
const instance = new Foo();
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.
Parameter decorator factory that allows for interface and other non-class information to be stored in the constructor's metadata.
import {injectable, inject} from "tsyringe";
interface Database {
// ...
}
@injectable()
class Foo {
constructor(@inject("Database") private database?: Database) {}
}
By default, @inject() throws an exception if no registration is found. If you want to have undefined injected when the registration isn't found, you can pass this options { isOptional: true } as the second parameter:
import {injectable, injectAll} from "tsyringe";
@injectable()
class Foo {
constructor(@inject("Database", { isOptional: true }) private database?: Database) {}
}
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.
import {injectable, injectAll} from "tsyringe";
@injectable()
class Foo {}
@injectable()
class Bar {
constructor(@injectAll(Foo) fooArray: Foo[]) {
// ...
}
}
By default, @injectAll() throws an exception if no registrations were found. If you want to return an empty array, you can pass this options { isOptional: true } as the second parameter:
import {injectable, injectAll} from "tsyringe";
@injectable()
class Bar {
constructor(@injectAll(Foo, { isOptional: true }) fooArray: Foo[]) {
// ...
}
}
Parameter decorator which allows for a transformer object to take an action on the resolved object before returning the result.
class FeatureFlags {
public getFlagValue(flagName: string): boolean {
// ...
}
}
class Foo() {}
class FeatureFlagsTransformer implements Transform<FeatureFlags, boolean> {
public transform(flags: FeatureFlags, flag: string) {
return flags.getFlagValue(flag);
}
}
@injectable()
class MyComponent(foo: Foo, @injectWithTransform(FeatureFlags, FeatureFlagsTransformer, "IsBlahEnabled") blahEnabled: boolean){
// ...
}
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.
@injectable()
class Foo {
public value;
}
class FooTransform implements Transform<Foo[], string[]>{
public transform(foos: Foo[]): string[]{
return foos.map(f => f.value));
}
}
@injectable()
class Bar {
constructor(@injectAllWithTransform(Foo, FooTransform) stringArray: string[]) {
// ...
}
}
Class decorator factory that registers the class as a scoped dependency within the global container.
@scoped(Lifecycle.ContainerScoped)
class Foo {}
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.
A token may be either a string, a symbol, a class constructor, or a instance of DelayedConstructor.
type InjectionToken<T = any> =
| constructor<T>
| DelayedConstructor<T>
| string
| symbol;
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:
{
token: InjectionToken<T>;
useClass: constructor<T>;
}
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).
{
token: InjectionToken<T>;
useValue: T
}
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.
{
token: InjectionToken<T>;
useFactory: FactoryFunction<T>;
}
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<T> signature
can be used as a factory:
type FactoryFunction<T> = (dependencyContainer: DependencyContainer) => T;
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()
import {instanceCachingFactory} from "tsyringe";
{
token: "SingletonFoo";
useFactory: instanceCachingFactory<Foo>(c => c.resolve(Foo));
}
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)
import {instancePerContainerCachingFactory} from "tsyringe";
{
token: "ContainerScopedFoo";
useFactory: instancePerContainerCachingFactory<Foo>(c => c.resolve(Foo));
}
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.
import {predicateAwareClassFactory} from "tsyringe";
{
token: "FooHttp",
useFactory: predicateAwareClassFactory<Foo>(
c => c.resolve(Bar).useHttps, // Predicate for evaluation
FooHttps, // A FooHttps will be resolved from the container if predicate is true
FooHttp // A FooHttp will be resolved if predicate is false
);
}
{
token: InjectionToken<T>;
useToken: InjectionToken<T>;
}
This provider can be thought of as a redirect or an alias, it simply states that given token x, resolve using token y.
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.
container.register<Foo>(Foo, {useClass: Foo});
container.register<Bar>(Bar, {useValue: new Bar()});
container.register<Baz>("MyBaz", {useValue: new Baz()});
As an optional parameter to .register() you may provide RegistrationOptions
which customize how the registration behaves. See the linked source code for up to date documentation
on available options.
You can also mark up any class with the @registry() decorator to have the given providers registered
upon importing the marked up class. @registry() takes an array of providers like so:
@registry([
{ token: Foobar, useClass: Foobar },
{ token: "theirClass", useFactory: (c) => {
return new TheirClass( "arg" )
},
}
])
class MyClass {}
This is useful when you want to register multiple classes for the same token.
You can also use it to register and declare objects that wouldn't be imported by anything else,
such as more classes annotated with @registry or that are otherwise responsible for registering objects.
Lastly you might choose to use this to register 3rd party instances instead of the container.register(...) method.
note: if you want this class to be @injectable you must put the decorator before @registry, this annotation is not
required though.
Resolution is the process of exchanging a token for an instance. Our container will recursively fulfill the dependencies of the token being resolved in order to return a fully constructed object.
The typical way that an object is resolved is from the container using resolve().
const myFoo = container.resolve(Foo);
const myBar = container.resolve<Bar>("Bar");
You can also resolve all instances registered against a given token with resolveAll().
interface Bar {}
@injectable()
class Foo implements Bar {}
@injectable()
class Baz implements Bar {}
@registry([
// registry is optional, all you need is to use the same token when registering
{token: "Bar", useToken: Foo}, // can be any provider
{token: "Bar", useToken: Baz}
])
class MyRegistry {}
const myBars = container.resolveAll<Bar>("Bar"); // myBars type is Bar[]
You can also add one or more InjectionToken to the registration of your class directly in the @injectable() decorator:
interface Bar {}
@injectable({token: "Bar"})
class Foo implements Bar {}
@injectable({token: ["Bar", "Bar2"]})
class Baz implements Bar {}
class MyRegistry {}
const myBars = container.resolveAll<Bar>("Bar"); // myBars type is Bar[], contains 2 instances
const myBars2 = container.resolveAll<Bar>("Bar2"); // myBars2 type is Bar[], contains 1 instance
You can check if a token is registered in the container using isRegistered().
const isRegistered = container.isRegistered("Bar"); // true
If you have a childContainer and want to recursively check if a token is registered in the parent container, you can pass true as a second parameter of isRegistered().
class Bar {}
container.register(Bar, {useClass: Bar});
const childContainer = container.createChildContainer();
childContainer.isRegistered(Bar); // false
childContainer.isRegistered(Bar, true); // true
Interception allows you to register a callback that will be called before or after the resolution of a specific token. This callback can be registered to execute only once (to perform initialization, for example), on each resolution to do logging, for example.
beforeResolution is used to take an action before an object is resolved.
class Bar {}
container.beforeResolution(
Bar,
// Callback signature is (token: InjectionToken<T>, resolutionType: ResolutionType) => void
() => {
console.log("Bar is about to be resolved!");
},
{frequency: "Always"}
);
afterResolution is used to take an action after the object has been resolved.
class Bar {
public init(): void {
// ...
}
}
container.afterResolution(
Bar,
// Callback signature is (token: InjectionToken<T>, result: T | T[], resolutionType: ResolutionType)
(_t, result) => {
result.init();
},
{frequency: "Once"}
);
If you need to have multiple containers that have disparate sets of registrations, you can create child containers:
const childContainer1 = container.createChildContainer();
const childContainer2 = container.createChildContainer();
const grandChildContainer = childContainer1.createChildContainer();
Each of the child containers will have independent registrations, but if a registration is absent in the child container at resolution, the token will be resolved from the parent. This allows for a set of common services to be registered at the root, with specialized services registered on the child. This can be useful, for example, if you wish to create per-request containers that use common stateless services from the root container.
The container.clearInstances() method allows you to clear all previously created and registered instances:
class Foo {}
@singleton()
class Bar {}
const myFoo = new Foo();
container.registerInstance("Test", myFoo);
const myBar = container.resolve(Bar);
container.clearInstances();
container.resolve("Test"); // throws error
const myBar2 = container.resolve(Bar); // myBar !== myBar2
const myBar3 = container.resolve(Bar); // myBar2 === myBar3
Unlike with container.reset(), the registrations themselves are not cleared.
This is especially useful for testing:
@singleton()
class Foo {}
beforeEach(() => {
container.clearInstances();
});
test("something", () => {
container.resolve(Foo); // will be a new singleton instance in every test
});
Sometimes you need to inject services that have cyclic dependencies between them. As an example:
@injectable()
export class Foo {
constructor(public bar: Bar) {}
}
@injectable()
export class Bar {
constructor(public foo: Foo) {}
}
Trying to resolve one of the services will end in an error because always one of the constructor will not be fully defined to construct the other one.
container.resolve(Foo);
Error: Cannot inject the dependency at position #0 of "Foo" constructor. Reason:
Attempted to construct an undefined constructor. Could mean a circular dependency problem. Try using `delay` function.
delay helper functionThe best way to deal with this situation is to do some kind of refactor to avoid the cyclic dependencies. Usually this implies introducing additional services to cut the cycles.
But when refactor is not an option you can use the delay function helper. The delay function wraps the constructor in an instance of DelayedConstructor.
The delayed constructor is a kind of special InjectionToken that will eventually be evaluated to construct an intermediate proxy object wrapping a factory for the real object.
When the proxy object is used for the first time it will construct a real object using this factory and any usage will be forwarded to the real object.
@injectable()
export class Foo {
constructor(@inject(delay(() => Bar)) public bar: Bar) {}
}
@injectable()
export class Bar {
constructor(@inject(delay(() => Foo)) public foo: Foo) {}
}
// construction of foo is possible
const foo = container.resolve(Foo);
// property bar will hold a proxy that looks and acts as a real Bar instance.
foo.bar instanceof Bar; // true
We can rest in the fact that a DelayedConstructor could be used in the same contexts that a constructor and will be handled transparently by tsyringe. Such idea is used in the next example involving interfaces:
export interface IFoo {}
@injectable()
@registry([
{
token: "IBar",
// `DelayedConstructor` of Bar will be the token
useToken: delay(() => Bar)
}
])
export class Foo implements IFoo {
constructor(@inject("IBar") public bar: IBar) {}
}
export interface IBar {}
@injectable()
@registry([
{
token: "IFoo",
useToken: delay(() => Foo)
}
])
export class Bar implements IBar {
constructor(@inject("IFoo") public foo: IFoo) {}
}
All instances created by the container that implement the Disposable
interface will automatically be disposed of when the container is disposed.
container.dispose();
or to await all asynchronous disposals:
await container.dispose();
Since classes have type information at runtime, we can resolve them without any extra information.
// Foo.ts
export class Foo {}
// Bar.ts
import {Foo} from "./Foo";
import {injectable} from "tsyringe";
@injectable()
export class Bar {
constructor(public myFoo: Foo) {}
}
// main.ts
import "reflect-metadata";
import {container} from "tsyringe";
import {Bar} from "./Bar";
const myBar = container.resolve(Bar);
// myBar.myFoo => An instance of Foo
Interfaces don't have type information at runtime, so we need to decorate them
with @inject(...) so the container knows how to resolve them.
// SuperService.ts
export interface SuperService {
// ...
}
// TestService.ts
import {SuperService} from "./SuperService";
export class TestService implements SuperService {
//...
}
// Client.ts
import {injectable, inject} from "tsyringe";
@injectable()
export class Client {
constructor(@inject("SuperService") private service: SuperService) {}
}
// main.ts
import "reflect-metadata";
import {Client} from "./Client";
import {TestService} from "./TestService";
import {container} from "tsyringe";
container.register("SuperService", {
useClass: TestService
});
const client = container.resolve(Client);
// client's dependencies will have been resolved
Primitive values can also be injected by utilizing named injection
import {singleton, inject} from "tsyringe";
@singleton()
class Foo {
private str: string;
constructor(@inject("SpecialString") value: string) {
this.str = value;
}
}
// some other file
import "reflect-metadata";
import {container} from "tsyringe";
import {Foo} from "./foo";
const str = "test";
container.register("SpecialString", {useValue: str});
const instance = container.resolve(Foo);
The following is a list of features we explicitly plan on not adding:
The library uses the step action EndBug/version-check which requires these two conditions to be met to execute:
Release X.Y.Zpackage.json file.This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
FAQs
Lightweight dependency injection container for JavaScript/TypeScript
The npm package tsyringe receives a total of 503,750 weekly downloads. As such, tsyringe popularity was classified as popular.
We found that tsyringe demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A flawed sandbox in @nestjs/devtools-integration lets attackers run code on your machine via CSRF, leading to full Remote Code Execution (RCE).
Product
Customize license detection with Socket’s new license overlays: gain control, reduce noise, and handle edge cases with precision.
Product
Socket now supports Rust and Cargo, offering package search for all users and experimental SBOM generation for enterprise projects.