Modivo

A lightweight, type-safe dependency injection library for TypeScript (JavaScript too).

Note that until all features are implemented, the library's API will keep chaning. I recommend pinning (~) to a specific version until a full release is made, at which point the API will follow semver releases.

Installation

npm install modivo
# or
pnpm add modivo
# or
yarn add modivo

Features

| Feature | Status | Description | |---------|--------|-------------| | Common Types of Providers | ✅ Supported | Value, Factory, and Class providers | | Type-Safe Dependencies | ✅ Supported | Compile-time dependency checking and validation | | Inferred Provider Type | ✅ Supported | Infer provider return type when using tickets | | Singleton/Transient Scopes | ✅ Supported | Singleton and Transient lifecycle management | | Parent/Child Container Hierarchy | ✅ Supported | Nested containers with parent-child relationships | | Provider Override | ✅ Supported | Be able to override providers (for tests) | | Async Providers | ✅ Supported | Async factory functions for async initialization | | Dependencies via Interfaces | ✅ Supported | Usage of interface return types | | Lifecycle Methods | 🔄 Implementing | Call and hook into lifecycle events of providers (after resolved / before destroyed / etc.) | | Circular Dependencies | 📋 Planned | Support for circular dependencies | | Module-like Container Hierarchy | 📋 Planned | Modular container organization and management (think nestjs) | | Exposed Dependency Resolution Tree | 📋 Planned | See how providers and dependencies were resolved |

Quick Start

import { ContainerBuilder, ProviderTicketMaster } from 'modivo';

// Create a container builder
const containerBuilder = ContainerBuilder.create();

// Define providers using ProviderTicketMaster (this doesn't register them yet)
const configProvider = ProviderTicketMaster.createTicket({
  identifier: 'config',
  value: { apiUrl: 'https://api.example.com' }
});

// Define a service class with type-safe dependencies
class DatabaseService {
  constructor(private config: { apiUrl: string }) {}
  
  connect() {
    console.log(`Connecting to ${this.config.apiUrl}`);
  }
}

// Dependencies are type-enforced - must match constructor parameters
const dbProvider = ProviderTicketMaster.createTicket({
  identifier: 'database',
  class: DatabaseService,
  dependencies: [configProvider] // TypeScript ensures this matches constructor
});

// Register providers to the container (this makes them available for resolution)
containerBuilder.register(configProvider);
containerBuilder.register(dbProvider);
const container = containerBuilder.build();

// Resolve dependencies using the provider's token
const db: unknown = container.resolveDependency(dbProvider.token);

// Alternatively, use the created ticket for type safety
const db: DatabaseService = container.resolveDependency(dbProvider);

db.connect(); // "Connecting to https://api.example.com"

📚 For complete set of (feature) usage examples, see: src/Examples/

Supported Provider Types

| Provider Type | Description | Example | |---------------|-------------|---------| | Value | Static values, constants, or configuration objects | { identifier: 'apiKey', value: 'abc123' } | | Function | Factory functions that return instances | { identifier: 'logger', factory: () => new Logger() } | | Class | Constructor functions with dependency injection | { identifier: 'service', class: MyService, dependencies: [...] } |

Supported Provider Scopes

| Scope | Description | Example | |-------|-------------|---------| | SINGLETON | Same instance returned every time (default) | { scope: ProviderScope.SINGLETON } | | TRANSIENT | New instance created every time | { scope: ProviderScope.TRANSIENT } |

Note: The provider controls the scope of itself, so if you have a singleton provider that takes in transient dependencies, the transient dependencies become singleton for that specific provider. On the other hand, having a transient provider that takes in singleton dependencies will respect the singleton nature of the dependencies. In other words, Singleton scope trumps the Transient scope.

API Reference

ContainerBuilder

• ContainerBuilder.create() - Create a new container builder
• register(ticket) - Register a provider to the container using a provider ticket
• build() - Build the final container for dependency resolution

Container

• resolveProvider(token) - Resolve a provider by its token

ProviderTicketMaster

• createTicket(options) - Create a provider ticket (does not register to container)