@monkin/di

@monkin/di is a lightweight (442 bytes), type-safe dependency injection container for TypeScript. It leverages TypeScript's advanced type system to provide a fluent API for service registration and resolution with full type safety and autocompletion.

Table of Contents

• Features
• Installation
• Usage
  • 1. Defining a Service
  • 2. Basic Injection
  • 3. Services with Dependencies
  • 4. Merging Containers
  • 5. Lazy
  • 6. Duplicate Service Name Protection
  • 7. Reserved Field Names
  • 8. Circular Dependencies
• API Reference
• Development
• License

Features

• Full Type Safety: Get autocompletion and type checks for all your injected services.
• No Decorators: No need for reflect-metadata or experimental decorators. Pure TypeScript.
• Fluent API: Chainable service registration makes it easy to compose your container.
• Container Composition: Merge multiple containers together to share dependencies across different parts of your application.
• Lazy: Services are instantiated only on demand (when first accessed) and reused for subsequent accesses.
• Zero Runtime Dependencies: Extremely lightweight (442 bytes minified / 309 bytes gzipped).

Installation

npm install @monkin/di

Usage

1. Defining a Service

A service is a class that implements the DiService interface. It must implement a getServiceName() method which will be used as the key in the container. Use as const to ensure the name is treated as a literal type.

import { DiService } from '@monkin/di';

export class LoggerService implements DiService<"logger"> {
    getServiceName() {
        return "logger" as const;
    }
    
    log(message: string) {
        console.log(`[LOG]: ${message}`);
    }
}

2. Basic Injection

Use DiContainer to register and resolve your services. You can register a single service or multiple services in one call. When registering multiple services, the order doesn't matter; they can even depend on each other.

import { DiContainer } from '@monkin/di';
import { LoggerService } from './LoggerService';
import { ConfigService } from './ConfigService';

// Single service
const container = new DiContainer()
    .inject(LoggerService);

// Multiple services in one call (order-independent)
const multiContainer = new DiContainer()
    .inject(ConfigService, LoggerService);

// Access the service directly on the container
container.logger.log("Service is ready!");

3. Services with Dependencies

To inject dependencies into a service, define its constructor to accept the container. You can use the Di<...T> type helper to specify which services are required. It supports multiple services passed as separate arguments or as a tuple.

import { Di, DiService } from '@monkin/di';
import { LoggerService } from './LoggerService';
import { ConfigService } from './ConfigService';

export class UserService implements DiService<"user"> {
    getServiceName() {
        return "user" as const;
    }
    
    // Single dependency:
    // constructor(private di: Di<LoggerService>) {}

    // Multiple dependencies:
    constructor(private di: Di<LoggerService, ConfigService>) {}

    getUser(id: string) {
        const prefix = this.di.config.get("userPrefix");
        this.di.logger.log(`Fetching user: ${prefix}${id}`);
        return { id, name: "User " + id };
    }
}

const container = new DiContainer()
    .inject(LoggerService)
    .inject(ConfigService)
    .inject(UserService);

container.user.getUser("42");

When using inject with multiple services, they can depend on each other regardless of the order they are passed to the method.

4. Merging Containers

You can create specialized containers and merge them into a main container using injectContainer.

const authContainer = new DiContainer().inject(AuthService);
const apiContainer = new DiContainer().inject(ApiService);

const appContainer = new DiContainer()
    .injectContainer(authContainer)
    .injectContainer(apiContainer)
    .inject(MainApp);

5. Lazy

Services registered via inject are lazy by default. When you register a service, @monkin/di creates a Proxy for it on the container. The actual service instance is only created when you first interact with it (e.g., call a method, access a property). Once created, the same instance is reused for all subsequent accesses.

const container = new DiContainer()
    .inject(ExpensiveService);

// ExpensiveService is NOT instantiated yet
const service = container.expensive; 
// Still NOT instantiated! `service` is a Proxy.

console.log("Container ready");

// ExpensiveService is instantiated NOW because we access a property/method
service.doSomething();

6. Duplicate Service Name Protection

@monkin/di prevents registering multiple services with the same name. This protection works at both compile-time and runtime:

• Type-level Check: If you try to inject a service with a name that already exists in the container, TypeScript will report an error, and the resulting type will be a string literal describing the error.
• Runtime Check: The inject and injectContainer methods will throw an Error if a duplicate key is detected.

const container = new DiContainer()
    .inject(LoggerService);

// TypeScript Error: Type '"Duplicate service name: logger"' ...
// Runtime Error: Duplicated service name: logger
container.inject(AnotherLoggerService); 

7. Reserved Field Names

Since DiContainer uses a fluent API, certain names are reserved for its internal methods and cannot be used as service names:

• inject
• injectContainer

Similar to duplicate names, attempting to use a reserved name will trigger both a Type-level Check and a Runtime Check.

class InjectService implements DiService<"inject"> {
    getServiceName() { return "inject" as const; }
}

const container = new DiContainer();

// TypeScript Error: Type '"Reserved field name: inject"' ...
// Runtime Error: Reserved service name: inject
container.inject(InjectService);

8. Circular Dependencies

@monkin/di supports circular dependencies between services because it uses Proxies for lazy initialization. A service can depend on another service that depends back on it, provided that they don't try to access each other's methods or properties in their constructors.

class ServiceA implements DiService<"a"> {
    getServiceName() { return "a" as const; }
    constructor(private di: Di<ServiceB>) {}
    
    doA() {
        console.log("A doing something...");
        this.di.b.doB();
    }
}

class ServiceB implements DiService<"b"> {
    getServiceName() { return "b" as const; }
    constructor(private di: Di<ServiceA>) {}
    
    doB() {
        console.log("B doing something...");
    }
}

const container = new DiContainer().inject(ServiceA, ServiceB);
container.a.doA(); // Works fine!

[!IMPORTANT] Do not access circular dependencies in the constructor, as this will trigger a stack overflow during instantiation.

API Reference

DiContainer

The main class for managing services.

• inject(...ServiceClasses: new (di: any) => any): DiContainer Registers one or more service classes. Returns the container instance, typed with the newly added services. Each service can depend on other services provided in the same call or already present in the container.
• injectContainer<DC extends DiContainer>(other: DC): this & DC Copies all services from another container into this one. Returns the container instance, typed with the merged services.

DiService<Name>

An interface that your service classes must implement.

• getServiceName(this: null): Name Must return the unique name of the service as a string literal type.

Di<...S>

A utility type to help define dependencies in your service constructors.

• Di<ServiceClass>: Resolves to an object with the service name as the key and the service instance as the value.
• Di<Service1, Service2, ...>: Resolves to a merged object containing all specified services.

Development

Installation

npm install

Build

npm run build

Test

npm test
npm run test:watch  # Watch mode

Linting & Formatting

npm run lint          # Run Biome check (lint, format, and import sorting)
npm run format        # Format code with Biome
npm run format:check  # Check code formatting with Biome

License

MIT