Dependency Injection for Node.js

A simple and intuitive asynchronous Dependency Injection library for Node.js with full TypeScript support and comprehensive test coverage.

Why Dependency Injection?

Dependency Injection vs. Pub-Sub/Event Listeners

Aspect	Dependency Injection	Pub-Sub/Event Listeners
Execution Timing	Executes when dependencies are available	Fires immediately when event is emitted
Dependency Management	Creates dependency graph, resolves in correct order	No dependency tracking, manual coordination required
Error Handling	Centralized validation and error handling	Scattered across multiple listeners
Type Safety	Full TypeScript support with compile-time checking	Limited type safety, runtime errors common
Testing	Easy to mock and test individual components	Complex setup with event mocking
Coupling	Loose coupling through interfaces	Tight coupling to event names and signatures

When to Use This Library

✅ Use Dependency Injection when:

• You need to coordinate multiple services that depend on each other
• You want to ensure services are initialized in the correct order
• You need type-safe dependency resolution
• You want to easily test and mock individual components
• You need to handle complex initialization sequences

❌ Use Pub-Sub/Event Listeners when:

• You need immediate, fire-and-forget notifications
• You want to decouple completely unrelated components
• You need one-to-many communication patterns
• You're building real-time systems with immediate responses

Example: Dependency Injection vs. Event Listeners

Event Listeners (Immediate Execution):

// Event listeners fire immediately, even if dependencies aren't ready
eventBus.on('userCreated', (user) => {
  // This might fail if database isn't connected yet
  database.saveUser(user);
});

eventBus.on('userCreated', (user) => {
  // This might fail if email service isn't configured
  emailService.sendWelcomeEmail(user);
});

// Fires immediately - listeners might fail
eventBus.emit('userCreated', user);

Dependency Injection (Coordinated Execution):

// Dependencies are resolved in correct order
injector.resolve(['database', 'emailService'], (db, email) => {
  // Both services are guaranteed to be ready
  db.saveUser(user);
  email.sendWelcomeEmail(user);
});

// Register dependencies when they're actually ready
injector.register('database', databaseConnection);
injector.register('emailService', emailService);

Features

• ✅ Full TypeScript Support - Complete type definitions and IntelliSense
• ✅ Modern Node.js - Requires Node.js 20+ with latest features
• ✅ Asynchronous Resolution - Lazy dependency resolution
• ✅ High Test Coverage - 97.95% overall coverage, 100% source code coverage
• ✅ Zero Dependencies - Only uses lodash for utility functions
• ✅ Lightweight - Minimal overhead and bundle size

Requirements

• Node.js 20.0.0 or higher
• TypeScript 5.0 or higher (for development)

Installation

npm install --save minjex

Quick Start

JavaScript

const DependencyInjector = require('minjex');

const injector = new DependencyInjector();

// Register dependencies
injector.register('database', { host: 'localhost', port: 5432 });
injector.register('apiKey', 'your-api-key-here');

// Resolve dependencies
injector.resolve(['database', 'apiKey'], (db, key) => {
  console.log('Database:', db);
  console.log('API Key:', key);
  // Your application logic here
});

TypeScript

import DependencyInjector, { DependencyInjectionOptions } from 'minjex';

interface DatabaseConfig {
  host: string;
  port: number;
}

const injector = new DependencyInjector();

// Register dependencies with type safety
injector.register('database', { host: 'localhost', port: 5432 } as DatabaseConfig);
injector.register('apiKey', 'your-api-key-here');

// Resolve dependencies with full type support
injector.resolve(['database', 'apiKey'], (db: DatabaseConfig, key: string) => {
  console.log('Database:', db);
  console.log('API Key:', key);
});

API Reference

Constructor

new DependencyInjector(options?: DependencyInjectionOptions)

Options:

• debug?: boolean - Enable debug logging (default: false)
• dependencies?: Record<string, any> - Pre-register dependencies
• dependants?: Record<string, Resolver[]> - Pre-register dependants

Methods

register(dependencyKey: string, dependencyValue: any): void

Registers a dependency that can be resolved later.

injector.register('service', new MyService());
injector.register('config', { timeout: 5000 });

resolve(dependencies: string[], resolver: ResolverFunction): void

Resolves dependencies and invokes the resolver function when all dependencies are available.

injector.resolve(['service', 'config'], (service, config) => {
  // This function is called when both 'service' and 'config' are available
  service.initialize(config);
});

inject(dependencies: string[]): void

Manually triggers dependency injection for the specified dependencies.

Advanced Usage

Lazy Resolution

Dependencies can be registered after resolvers are defined:

// Define resolver first
injector.resolve(['userService'], (userService) => {
  console.log('User service is ready!');
});

// Register dependency later
setTimeout(() => {
  injector.register('userService', new UserService());
}, 1000);

Context Access

Access dependencies through the this context:

injector.resolve(['db', 'cache'], function() {
  const database = this.db;
  const cache = this.cache;
  
  // Use dependencies
  database.query('SELECT * FROM users');
});

Dependency Change Detection

Resolvers are automatically re-invoked when dependencies change:

injector.resolve(['config'], (config) => {
  console.log('Config updated:', config);
});

injector.register('config', { version: '1.0' }); // Resolver called
injector.register('config', { version: '1.0' }); // Not called (same value)
injector.register('config', { version: '2.0' }); // Resolver called again

Debug Mode

Enable debug logging to track dependency resolution:

const injector = new DependencyInjector({ debug: true });

injector.register('test', 'value');
// Output: [DependencyInjection] register [Arguments] { '0': 'test', '1': 'value' }
// Output: [DependencyInjection] inject [ 'test' ]

Development

Prerequisites

• Node.js 20+
• npm or yarn

Setup

git clone https://github.com/serendipious/node-dependency-injection.git
cd node-dependency-injection
npm install

Building

npm run build

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test -- --reporter=html

Code Quality

The project maintains high code quality standards:

• TypeScript with strict type checking
• Pre-commit hooks that run tests and coverage checks
• 97.95% test coverage with comprehensive test suite
• Automated quality gates prevent commits that don't meet standards

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

BSD License - see LICENSE file for details.

Changelog

v0.5

• Initial release as minjex
• TypeScript migration from CoffeeScript
• Node.js 20+ support
• Comprehensive test suite (97.95% coverage)
• Full type definitions
• Pre-commit hooks for quality assurance
• Modern documentation and contribution guidelines