@webiny/di

A professional-grade dependency injection container for TypeScript applications built with SOLID principles.

This is not a toy container for simple dependency wiring. @webiny/di is engineered for architects and senior developers who build complex, maintainable systems using Clean Architecture, Domain-Driven Design, and rigorous adherence to SOLID principles.

> ⚠️ Prerequisites: This library assumes you understand and practice:
>
> - Dependency Inversion Principle - Programming to abstractions, not implementations
> - Open/Closed Principle - Extending behavior through decoration, not modification
> - Interface Segregation - Focused, cohesive abstractions
>
> If your codebase doesn't use abstractions, or you're simply using a Service Locator pattern, a simpler solution may be more appropriate.

Table of Contents

- Features
- Who Should Use This
- Installation
- Quick Start
- Core Concepts
- Abstractions
- Implementations
- Dependencies
- Lifetime Scopes
- Transient (Default)
- Singleton
- Why @webiny/di?
- Built for SOLID Principles, Not Just Convenience
- True Type Safety
- First-Class Decorator Pattern
- Comparison with Other Containers
- Advanced Features
- Decorator Pattern
- Multiple Decorators
- Composite Pattern
- Dependency Options
- Hierarchical Containers
- Instance Registration
- Factory Registration
- Resolve All
- Manual Resolution with Dependencies
- Type Safety
- Real-World Example
- Best Practices
- Error Handling
- Testing
- Unit Testing with Mocks
- Integration Testing with Container
- Testing with Child Containers
- Philosophy
- There Are No "Plugins"
- DI Containers Are Only Useful with SOLID
- Professional Tools for Professional Developers
- We Choose Compile-Time Safety Over Runtime Flexibility
- Contributing

Features

- ✨ True Type Safety: Unlike other DI containers, type safety is enforced at compile-time. The Abstraction class unifies tokens and types, making it impossible to resolve dependencies with incorrect types. No manual generic passing, no runtime surprises.
- 🎯 First-Class Decorator Pattern: The only DI container with true abstraction decoration. Implement the Open/Closed Principle without compromise - extend behavior through decoration, not modification.
- 🏛️ SOLID by Design: Every feature exists to enable rigorous adherence to SOLID principles. This isn't a general-purpose container - it's a tool for professional architects building maintainable systems.
- 🔗 Composite Pattern: Register multiple implementations as composites for elegant handling of collections
- 🏗️ Hierarchical Containers: Create child containers with inheritance for scoped lifetimes and feature isolation
- ⚡ Lifetime Scopes: Transient and Singleton lifetime management
- 🔍 Metadata-Based: Uses reflect-metadata for clean, decorator-free API
- 🎨 Clean Architecture Ready: Designed from the ground up for Clean Architecture and Domain-Driven Design

Installation

``bash
npm install @webiny/di reflect-metadata
`

> Note: This package requires reflect-metadata to be installed and imported at your application's entry point.

Who Should Use This

@webiny/di is for you if:

- ✅ You build applications using Clean Architecture or Hexagonal Architecture
- ✅ You practice Domain-Driven Design
- ✅ You understand and apply SOLID principles rigorously
- ✅ You need to extend system behavior through composition, not modification
- ✅ You value compile-time safety over runtime flexibility
- ✅ You're building enterprise applications where maintainability is critical

This library is NOT for you if:

- ❌ You're looking for a quick way to wire up dependencies in a simple app
- ❌ Your codebase uses concrete classes everywhere (no abstractions)
- ❌ You prefer runtime configuration over compile-time safety
- ❌ You're building a prototype or MVP where architecture doesn't matter yet

Quick Start

`typescript
import "reflect-metadata";
import { Container, Abstraction, createImplementation } from "@webiny/di";

// 1. Define an abstraction (interface token)
interface IUserRepository {
getById(id: string): Promise;
}

const UserRepository = new Abstraction("UserRepository");

// 2. Create an implementation
class UserRepositoryImpl implements IUserRepository {
async getById(id: string): Promise {
// implementation
}
}

const UserRepositoryImplementation = createImplementation({
abstraction: UserRepository,
implementation: UserRepositoryImpl,
dependencies: []
});

// 3. Register and resolve
const container = new Container();
container.register(UserRepositoryImplementation);

const userRepo = container.resolve(UserRepository);
`

Core Concepts

$3

Abstractions are type-safe tokens that represent interfaces or abstract contracts.

`typescript
interface ILogger {
log(message: string): void;
}

const Logger = new Abstraction("Logger");
`

$3

Use createImplementation to bind implementations to abstractions with their dependencies.

`typescript
class ConsoleLogger implements ILogger {
log(message: string): void {
console.log(message);
}
}

const ConsoleLoggerImpl = createImplementation({
abstraction: Logger,
implementation: ConsoleLogger,
dependencies: []
});
`

$3

Specify dependencies as an array of abstractions or tuples with options.

`typescript
interface IUserService {
createUser(name: string): Promise;
}

const UserService = new Abstraction("UserService");

class UserServiceImpl implements IUserService {
constructor(
private repository: IUserRepository,
private logger: ILogger
) {}

async createUser(name: string): Promise {
this.logger.log(Creating user: ${name});
// implementation
}
}

const UserServiceImpl = createImplementation({
abstraction: UserService,
implementation: UserServiceImpl,
dependencies: [UserRepository, Logger]
});
`

Lifetime Scopes

$3

A new instance is created every time the dependency is resolved.

`typescript
container.register(UserRepositoryImpl);
// or explicitly:
container.register(UserRepositoryImpl); // default is transient
`

$3

A single instance is created and reused for all resolutions.

`typescript
container.register(UserRepositoryImpl).inSingletonScope();
`

Advanced Features

$3

Decorators wrap existing implementations to add cross-cutting concerns without modifying the original code.

`typescript
interface IPageRepository {
getById(id: string): Promise;
}

const PageRepository = new Abstraction("PageRepository");

// Base implementation
class PageRepositoryImpl implements IPageRepository {
async getById(id: string): Promise {
// fetch from API
}
}

// Caching decorator
class CachedPageRepository implements IPageRepository {
constructor(
private cache: ICache,
private decoratee: IPageRepository // The decorated instance
) {}

async getById(id: string): Promise {
const cached = await this.cache.get(id);
if (cached) return cached;

const page = await this.decoratee.getById(id);
await this.cache.set(id, page);
return page;
}
}

// Register base implementation
const PageRepositoryImplementation = createImplementation({
abstraction: PageRepository,
implementation: PageRepositoryImpl,
dependencies: []
});

container.register(PageRepositoryImplementation);

// Register decorator
const CachedPageRepositoryDecorator = createDecorator({
abstraction: PageRepository,
decorator: CachedPageRepository,
dependencies: [Cache] // Cache is injected, decoratee is passed automatically
});

container.registerDecorator(CachedPageRepositoryDecorator);
`

Key Points:

- Decorators are applied in the order they are registered
- The last constructor parameter of a decorator must be the decorated type
- Dependencies are resolved before the decoratee is passed

$3

Chain multiple decorators to compose functionality:

`typescript
// 1. Base implementation
container.register(CreatePageUseCaseImpl);

// 2. Add validation
container.registerDecorator(ValidationDecorator);

// 3. Add authorization
container.registerDecorator(AuthorizationDecorator);

// 4. Add metrics
container.registerDecorator(MetricsDecorator);

// Resolution order: MetricsDecorator -> AuthorizationDecorator -> ValidationDecorator -> CreatePageUseCaseImpl
`

$3

Composites collect multiple implementations and expose them as a single implementation.

`typescript
interface IPlugin {
execute(): void;
}

const Plugin = new Abstraction("Plugin");

class PluginComposite implements IPlugin {
constructor(private plugins: IPlugin[]) {}

execute(): void {
this.plugins.forEach(plugin => plugin.execute());
}
}

const PluginCompositeImpl = createComposite({
abstraction: Plugin,
implementation: PluginComposite,
dependencies: [[Plugin, { multiple: true }]]
});

container.registerComposite(PluginCompositeImpl);
`

$3

#### Multiple Dependencies

Resolve all implementations of an abstraction as an array:

`typescript
interface IEventHandler {
handle(event: DomainEvent): Promise;
}

const EventHandler = new Abstraction("EventHandler");

class EventPublisher {
constructor(private handlers: IEventHandler[]) {}

async publish(event: DomainEvent): Promise {
for (const handler of this.handlers) {
await handler.handle(event);
}
}
}

const EventPublisherImpl = createImplementation({
abstraction: EventPublisher,
implementation: EventPublisher,
dependencies: [[EventHandler, { multiple: true }]]
});
`

#### Optional Dependencies

Mark dependencies as optional if they may not be registered:

`typescript
class UserService {
constructor(
private repository: IUserRepository,
private logger?: ILogger // Optional
) {}

async createUser(name: string): Promise {
this.logger?.log(Creating user: ${name});
// implementation
}
}

const UserServiceImpl = createImplementation({
abstraction: UserService,
implementation: UserService,
dependencies: [UserRepository, [Logger, { optional: true }]]
});
`

$3

Create child containers that inherit registrations from their parent:

`typescript
const parentContainer = new Container();
parentContainer.register(LoggerImpl).inSingletonScope();

const childContainer = parentContainer.createChildContainer();

// Child can resolve parent's registrations
const logger = childContainer.resolve(Logger);

// Child registrations don't affect parent
childContainer.register(UserRepositoryImpl);
`

Use cases:

- Scoped lifetimes (e.g., per-request in web applications)
- Feature isolation
- Testing with overridden dependencies

$3

Register pre-created instances directly:

`typescript
const configInstance = new Configuration({ apiKey: "secret" });
container.registerInstance(Configuration, configInstance);
`

$3

Register a factory function for custom instance creation:

`typescript
container.registerFactory(Logger, () => {
return new ConsoleLogger(process.env.LOG_LEVEL);
});
`

$3

Get all registered implementations of an abstraction:

`typescript
// Register multiple implementations
container.register(EmailNotificationHandler);
container.register(SmsNotificationHandler);
container.register(PushNotificationHandler);

// Resolve all
const handlers = container.resolveAll(NotificationHandler);
// Returns: [EmailNotificationHandler, SmsNotificationHandler, PushNotificationHandler]
`

$3

Manually create instances with resolved dependencies:

`typescript
const instance = container.resolveWithDependencies({
implementation: MyClass,
dependencies: [Logger, UserRepository]
});
`

Type Safety

The container provides enforced type safety through the Abstraction class. Unlike other DI containers where tokens and types are separate, here they are unified:

`typescript
// The abstraction IS the token AND carries the type
const Logger = new Abstraction("Logger");

// ✅ Type is automatically inferred from the abstraction
const logger = container.resolve(Logger); // Type: ILogger (no manual generic needed!)

// ✅ Dependencies are type-checked against constructor parameters
const UserServiceImpl = createImplementation({
abstraction: UserService,
implementation: UserServiceImpl,
dependencies: [
UserRepository, // Type-checked: must be IUserRepository
Logger // Type-checked: must be ILogger
]
});

// ❌ TypeScript error: wrong type
const wrong: ISomeOtherType = container.resolve(Logger);
// Error: Type 'ILogger' is not assignable to type 'ISomeOtherType'
`

This approach eliminates entire classes of bugs that exist in other DI containers where you can accidentally resolve the wrong type.

Real-World Example

Here's a complete example of a feature using clean architecture principles:

`typescript
import "reflect-metadata";
import { Container, Abstraction, createImplementation, createDecorator } from "@webiny/di";

// Domain Layer
interface User {
id: string;
name: string;
email: string;
}

// Application Layer - Repository Interface
interface IUserRepository {
getById(id: string): Promise;
save(user: User): Promise;
}

const UserRepository = new Abstraction("UserRepository");

// Application Layer - Use Case
interface IGetUserUseCase {
execute(id: string): Promise;
}

const GetUserUseCase = new Abstraction("GetUserUseCase");

class GetUserUseCaseImpl implements IGetUserUseCase {
constructor(private repository: IUserRepository) {}

async execute(id: string): Promise {
return this.repository.getById(id);
}
}

// Infrastructure Layer - Repository Implementation
interface IUserGateway {
fetchUser(id: string): Promise;
}

const UserGateway = new Abstraction("UserGateway");

class UserRepositoryImpl implements IUserRepository {
constructor(private gateway: IUserGateway) {}

async getById(id: string): Promise {
return this.gateway.fetchUser(id);
}

async save(user: User): Promise {
// implementation
}
}

class UserGraphQLGateway implements IUserGateway {
async fetchUser(id: string): Promise {
// GraphQL query
return { id, name: "John", email: "john@example.com" };
}
}

// Cross-cutting Concerns - Logging Decorator
interface ILogger {
log(message: string): void;
}

const Logger = new Abstraction("Logger");

class ConsoleLogger implements ILogger {
log(message: string): void {
console.log([LOG] ${message});
}
}

class LoggingGetUserDecorator implements IGetUserUseCase {
constructor(
private logger: ILogger,
private decoratee: IGetUserUseCase
) {}

async execute(id: string): Promise {
this.logger.log(Fetching user: ${id});
const user = await this.decoratee.execute(id);
this.logger.log(User fetched: ${user?.name || "not found"});
return user;
}
}

// DI Setup
const container = new Container();

// Register infrastructure
container.register(
createImplementation({
abstraction: UserGateway,
implementation: UserGraphQLGateway,
dependencies: []
})
);

container
.register(
createImplementation({
abstraction: UserRepository,
implementation: UserRepositoryImpl,
dependencies: [UserGateway]
})
)
.inSingletonScope();

// Register use case
container.register(
createImplementation({
abstraction: GetUserUseCase,
implementation: GetUserUseCaseImpl,
dependencies: [UserRepository]
})
);

// Register logger
container
.register(
createImplementation({
abstraction: Logger,
implementation: ConsoleLogger,
dependencies: []
})
)
.inSingletonScope();

// Add logging decorator
container.registerDecorator(
createDecorator({
abstraction: GetUserUseCase,
decorator: LoggingGetUserDecorator,
dependencies: [Logger]
})
);

// Usage
const useCase = container.resolve(GetUserUseCase);
const user = await useCase.execute("123");
`

Best Practices

$3

`typescript
// features/users/abstractions.ts
export interface IUserRepository {
/ ... /
}
export const UserRepository = new Abstraction("UserRepository");

export interface IGetUserUseCase {
/ ... /
}
export const GetUserUseCase = new Abstraction("GetUserUseCase");
`

$3

`typescript
export const UserRepository = new Abstraction("UserRepository");

export namespace UserRepository {
export type Interface = IUserRepository;
}

// Usage
function example(repo: UserRepository.Interface) {
// ...
}
`

$3

`typescript
// features/users/feature.ts
export function registerUserFeature(container: Container) {
container.register(UserGatewayImpl);
container.register(UserRepositoryImpl).inSingletonScope();
container.register(GetUserUseCaseImpl);
}
`

$3

`typescript
// Stateful services should be singletons
container.register(CacheImpl).inSingletonScope();
container.register(DatabaseConnectionImpl).inSingletonScope();

// Stateless services can be transient
container.register(GetUserUseCaseImpl); // transient by default
`

$3

`typescript
// ✅ Good: Constructor injection
class UserService {
constructor(private repository: IUserRepository) {}
}

// ❌ Avoid: Property injection or service locator pattern
class UserService {
repository?: IUserRepository;

setRepository(repo: IUserRepository) {
this.repository = repo;
}
}
`

Error Handling

The container provides clear error messages:

`typescript
// Circular dependency detection
try {
container.resolve(ServiceA);
} catch (error) {
// Error: Circular dependency detected for ServiceA
}

// Missing registration
try {
container.resolve(UnregisteredService);
} catch (error) {
// Error: No registration found for UnregisteredService
}

// Missing abstraction metadata
try {
container.register(ImplementationWithoutMetadata);
} catch (error) {
// Error: No abstraction metadata found for ImplementationWithoutMetadata
}
`

Testing

$3

`typescript
import { describe, it, expect, vi } from "vitest";

describe("GetUserUseCase", () => {
it("should fetch user by id", async () => {
const mockRepository: IUserRepository = {
getById: vi.fn().mockResolvedValue({ id: "1", name: "John" }),
save: vi.fn()
};

const useCase = new GetUserUseCaseImpl(mockRepository);
const user = await useCase.execute("1");

expect(user?.name).toBe("John");
expect(mockRepository.getById).toHaveBeenCalledWith("1");
});
});
`

$3

`typescript
import { describe, it, expect, beforeEach } from "vitest";

describe("User Feature Integration", () => {
let container: Container;

beforeEach(() => {
container = new Container();
registerUserFeature(container);
});

it("should wire up all dependencies correctly", () => {
const useCase = container.resolve(GetUserUseCase);
expect(useCase).toBeDefined();
});

it("should execute use case with real dependencies", async () => {
const useCase = container.resolve(GetUserUseCase);
const user = await useCase.execute("123");
expect(user).toBeDefined();
});
});
`

$3

`typescript
describe("User Feature with Overrides", () => {
it("should use mock repository in tests", async () => {
const parentContainer = new Container();
registerUserFeature(parentContainer);

const testContainer = parentContainer.createChildContainer();

// Override repository with mock
const mockRepo = new MockUserRepository();
testContainer.registerInstance(UserRepository, mockRepo);

const useCase = testContainer.resolve(GetUserUseCase);
const user = await useCase.execute("123");

expect(mockRepo.getByIdCalled).toBe(true);
});
});
`

Performance Considerations

- Singleton Scope: Use for expensive-to-create objects (database connections, caches)
- Transient Scope: Use for lightweight, stateless services
- Resolution Caching: Singleton instances are cached automatically
- Decorator Overhead: Minimal, but avoid excessive decorator chains (>10)

Why @webiny/di?

$3

Most DI containers are designed to make dependency wiring convenient. @webiny/di goes further - it's engineered to make SOLID principles not just possible, but natural and frictionless.

The truth about DI containers: They provide architectural value _only_ when used with SOLID principles. Without abstractions (Dependency Inversion Principle) and without the need to extend behavior (Open/Closed Principle), a DI container is just glorified object instantiation.

@webiny/di doesn't pretend otherwise. This library is for professionals building:

- Clean Architecture applications with clear layer boundaries
- Domain-Driven Design systems with rich domain models
- Extensible platforms where behavior is composed, not hardcoded
- Enterprise applications where maintainability matters more than quick hacks

$3

Most DI containers claim to be "type-safe," but they rely on manual generic parameters that can be incorrect. In these libraries, the token (string/symbol) and the type (generic parameter) are separate, allowing for mismatches:

`typescript
// ❌ Other libraries - token and type are separate
const TYPES = { UserRepository: Symbol.for("UserRepository") };
container.bind(TYPES.UserRepository).to(UserRepositoryImpl);

// ❌ You can resolve with the WRONG type - compiles fine, fails at runtime!
const repo = container.get(TYPES.UserRepository);
// TypeScript can't catch this mistake because token and type are disconnected
`

@webiny/di solves this by unifying tokens and types in the Abstraction class:

`typescript
// ✅ Token and type are unified - impossible to mess up
const UserRepository = new Abstraction("UserRepository");

// ✅ Type is automatically enforced
const repo = container.resolve(UserRepository); // Always returns IUserRepository

// ✅ Wrong type assignment caught at compile-time
const wrong: IProductRepository = container.resolve(UserRepository);
// TypeScript error: Type 'IUserRepository' is not assignable to type 'IProductRepository'
`

Key benefits:

- No manual generic passing - types are automatic
- Compile-time verification of all dependencies
- Impossible to resolve with incorrect types
- Refactoring-safe - rename interfaces and all usages update

$3

@webiny/di is the only DI container that implements true decoration of abstractions, making the Open/Closed Principle practical and natural.

> "Software entities should be open for extension, but closed for modification." - Bertrand Meyer

This library makes it the default way of working. Decorators are registered on the abstraction, not on concrete implementations:

`typescript
// ✅ Register base implementation - closed for modification
container.register(PageRepositoryImpl);

// ✅ Extend through decoration - open for extension
container.registerDecorator(CachingDecorator);
container.registerDecorator(LoggingDecorator);
container.registerDecorator(MetricsDecorator);

// ✅ All decorators automatically applied in order
const repo = container.resolve(PageRepository);
// Returns: MetricsDecorator -> LoggingDecorator -> CachingDecorator -> PageRepositoryImpl
`

This is the Open/Closed Principle in practice:

- Base implementation is closed for modification - it never changes
- Behavior is open for extension - add decorators without touching core code
- Decorators are registered separately from implementations
- Third-party code can extend behavior by simply registering decorators

#### Real-World Example: Extensible Systems

`typescript
// Core application - defines abstractions and base implementations
container.register(CreatePageUseCaseImpl);

// ✅ Team member adds validation - extends via decoration
container.registerDecorator(ValidationDecorator);

// ✅ Team member adds authorization - extends via decoration
container.registerDecorator(AuthorizationDecorator);

// ✅ DevOps adds metrics - extends via decoration
container.registerDecorator(MetricsDecorator);

// ✅ Customer adds custom business rules - extends via decoration
container.registerDecorator(CustomBusinessRulesDecorator);

// All decorators automatically compose!
const useCase = container.resolve(CreatePageUseCase);
// Execution flow:
// CustomBusinessRulesDecorator
// -> MetricsDecorator
// -> AuthorizationDecorator
// -> ValidationDecorator
// -> CreatePageUseCaseImpl

// Original CreatePageUseCaseImpl was NEVER modified - Open/Closed Principle achieved.
``

This pattern is fundamental to:

- Clean Architecture - Use cases decorated with cross-cutting concerns
- Domain-Driven Design - Domain services enhanced with infrastructure concerns
- Hexagonal Architecture - Ports decorated with adapters
- CQRS - Command handlers decorated with validation, authorization, auditing

Only @webiny/di makes this pattern first-class. In other containers, you're fighting the framework. Here, you're working with it.

Comparison with Other Containers

@webiny/di isn't trying to be a general-purpose DI container. It's optimized for one thing: making SOLID principles practical in TypeScript applications.

Here's how it compares to other popular containers:

| Feature | @webiny/di | InversifyJS | TSyringe |
| --------------------- | ------------------------------------------- | ------------------------ | ------------------------ |
| Type Safety | ✅ Enforced (Token = Type) | ⚠️ Manual (Token ≠ Type) | ⚠️ Manual (Token ≠ Type) |
| Wrong Type Resolution | ✅ Compile error | ❌ Runtime error | ❌ Runtime error |
| Decorator Pattern | ✅ First-class (abstraction decoration) | ❌ Manual chaining only | ❌ Manual chaining only |
| Open/Closed Principle | ✅ Native support | ⚠️ Manual implementation | ⚠️ Manual implementation |
| Composites | ✅ Built-in | ❌ No | ❌ No |
| Child Containers | ✅ Yes | ✅ Yes | ✅ Yes |
| Metadata | ✅ reflect-metadata | ✅ reflect-metadata | ✅ reflect-metadata |
| Target Audience | Professional architects | General purpose | General purpose |
| Learning Curve | Low (if you know SOLID) | Medium | Low |

Bottom line: If you're building with SOLID principles, @webiny/di removes friction. If you're not, other containers might be more flexible for your use case.

Philosophy

@webiny/di is opinionated by design. It embodies a specific philosophy about software architecture:

$3

What people call "plugins" are simply:

- Implementations of abstractions defined by the core system
- Decorations of abstractions to extend behavior
- Composites that collect multiple implementations

$3

A DI container without SOLID principles is like:

- A type system without types
- A database without queries
- A compiler without syntax checking

You can use it, but you're missing the entire point.

$3

This library doesn't try to be everything to everyone. It's a professional tool for developers who:

- Understand that architecture matters!
- Know that maintainability is more valuable than initial simplicity
- Accept that good design requires discipline and expertise

If you're building a throwaway prototype, use something simpler. If you're building a system that will live for years and be maintained by multiple teams, @webiny/di will pay dividends.

$3

Some DI containers let you do anything at runtime. This library intentionally restricts you to compile-time verified operations.

Why? Because runtime errors in production are expensive. Compile-time errors are free.

We'd rather you hit a TypeScript error during development than a runtime error at 3 AM.

Contributing

- 💬 Slack: Join our community
- 🐛 Issues: GitHub Issues