hidi - Hierarchical Dependency Injection for TypeScript

A lightweight, type-safe dependency injection container for TypeScript applications. Simplify dependency management with support for hierarchical containers, explicit key registration, and a minimal API.

Software Development by Stateless Studio

Features

• 🎯 Type-Safe - Full TypeScript support with generic types for type-safe dependency retrieval
• 🌳 Hierarchical Containers - Support for parent-child container relationships with automatic fallback
• 🔑 Flexible Key Registration - Register dependencies using string keys or class constructors
• ⚙️ Multiple Registration Types - Register classes, instances, or factory functions with different caching behavior
• 🔔 Reactivity (Pub/Sub) - Register stateful values and subscribe to changes with a simple pub/sub API
• 🚀 Fast & Efficient - Optimized for performance with minimal overhead and fast lookups
• 🧩 Minimal API - Focused set of methods for common dependency injection patterns without unnecessary complexity
• 🔒 No External Dependencies - Zero dependencies for maximum compatibility and minimal bundle size
• ⚡ Lightweight - Minimal API surface with zero external dependencies
• 🧪 Well-Tested - 100% code coverage with comprehensive test suite

Installation

npm install hidi

Quick Start

Basic Registration and Retrieval

Register dependencies using string keys:

import { DependencyContainer } from 'hidi';

const container = new DependencyContainer();

// Register a dependency with a string key
container.register('logger', console.log);

// Retrieve the dependency
const logger = container.get('logger');

Using Class Constructors as Keys

Register and retrieve using class constructors:

class DatabaseService {
  connect() {
    console.log('Connected to database');
  }
}

const dbService = new DatabaseService();
container.register(DatabaseService, dbService);

// Retrieve by class constructor
const db = container.get(DatabaseService);
db?.connect(); // "Connected to database"

Documentation

Comprehensive guides are available for each capability:

Registration Methods

Register dependencies using register(), registerInstance(), or registerFactory(). Each method offers different caching and instantiation behavior for different use cases.

// Singleton instance registration
container.registerInstance('apiUrl', 'https://api.example.com');

// Class registration (lazy instantiation, cached)
container.register(UserService);

// Factory registration (new instance per request)
container.registerFactory('timestamp', () => Date.now());

→ Full Registration Guide

Dependency Retrieval

Retrieve your registered dependencies with get(), require(), and has() methods for safe and reliable access.

const config = container.get('apiUrl');
const service = container.require(UserService); // Throws if not found
if (container.has('logger')) {
  const logger = container.get('logger');
}

→ Full Retrieval Guide

Hierarchical Containers

Create parent-child container relationships with extend() and setParent(). Child containers inherit and can override parent dependencies.

const parentContainer = new DependencyContainer();
parentContainer.register('dbUrl', 'postgres://prod');

const childContainer = parentContainer.extend();
childContainer.registerInstance('dbUrl', 'postgres://dev'); // Override

→ Full Hierarchical Containers Guide

Dependency Injection

Implement the HasDependencies interface and use inject() to automatically resolve dependencies for your classes.

class UserService implements HasDependencies {
  private repository: UserRepository;

  inject(container: DependencyContainer): void {
    this.repository = container.require(UserRepository);
  }
}

container.register(UserService, new UserService());
container.inject(); // Resolve all dependencies

→ Full Dependency Injection Guide

State Management & Pub/Sub

Register reactive state values and subscribe to changes. Build reactive systems where services are notified of state updates.

const counter = container.registerState('counter', 0);

const unsubscribe = container.subscribe('counter', (newValue, oldValue) => {
  console.log(`Counter: ${oldValue} → ${newValue}`);
});

counter.value = 1; // Notifies subscribers

→ Full State Management Guide

Usage Examples

Practical, real-world examples including application configuration, service layers, request scoping, reactive state, and more.

// Environment-specific configuration
const dev = rootContainer.extend();
dev.registerInstance('apiUrl', 'http://localhost:3000');

// Request scoping
const requestContainer = globalContainer.extend();
requestContainer.register('requestId', req.id);

// Reactive state management
appState.update((state) => ({
  ...state,
  errors: [...state.errors, 'New error']
}));

→ View All Examples

API Reference Summary

For a quick reference of all available methods:

| Method | Purpose | Documentation | |--------|---------|---| | register() | Register singleton dependencies | Registration Methods | | registerInstance() | Register pre-created instances | Registration Methods | | registerFactory() | Register factory functions | Registration Methods | | get() | Retrieve a dependency | Dependency Retrieval | | require() | Retrieve or throw error | Dependency Retrieval | | has() | Check dependency existence | Dependency Retrieval | | extend() | Create child container | Hierarchical Containers | | setParent() | Set parent container | Hierarchical Containers | | inject() | Resolve dependencies | Dependency Injection | | registerState() | Register reactive state | State Management | | getState() | Retrieve state wrapper | State Management | | subscribe() | Listen to state changes | State Management | | subscribeMany() | Listen to multiple states | State Management |

Contributing & Development

See contributing.md for information on how to develop or contribute to this project!

License

See LICENSE.md