SDIJS v2.1 🚀

Modern Dependency Injection for Node.js - A powerful, enterprise-ready DI container with fluent API, decorators, and universal validation while maintaining the elegant {a,b,c} destructuring syntax.

Features

Core DI Features:

• Fluent/Chainable API - Modern, readable service registration
• Destructuring Support - Keep your elegant {service, config} syntax
• Tag-based Discovery - Find services by tags with AND/OR logic
• Scoped Dependencies - Request/session scoped services
• Factory Functions - With full dependency injection
• Circular Dependency Detection - Automatic detection and helpful errors
• Lifecycle Hooks - beforeCreate, afterCreate, etc.

NEW in v2.1 - Advanced Decorator System:

• Service Decorators - Services that decorate other services with DI
• Custom Function Decorators - Flexible function-based decoration
• Universal Method Validation - Works with ANY method names automatically
• Batch Registration - Declarative service configuration
• Interface Preservation - Automatic validation of service interfaces
• Smart Error Detection - Intelligent signature change warnings

Enterprise Features:

• TypeScript Ready - Full type definitions included
• Zero Dependencies - Lightweight and secure
• Security Hardened - Prototype pollution protection & memory limits
• Verbose Logging - Clear [SDIJS:CATEGORY] logging for debugging
• Performance Optimized - Efficient caching and tag discovery

Why Dependency Injection?

The Dependency Injection pattern separates object instantiation from business logic, providing:

• Explicit dependencies - Clear understanding of service relationships
• Code reuse - Services decoupled from specific implementations
• Easy testing - Mock dependencies effortlessly
• Better architecture - Clean, maintainable code structure

📦 Installation

# Install from npm (recommended)
npm install sdijs

# Or clone the repository for development
git clone https://github.com/mau-io/sdijs.git
cd sdijs

# Install dependencies
npm install

# Run tests
npm test

# Run example
node example.js

Requirements: Node.js 16+ (ES Modules support)

🎯 Quick Start

import { createContainer } from 'sdijs';

// Create container with modern API
const container = createContainer({ 
  verbose: true, 
  autoBinding: true,
  strictMode: false
});

// Sample services with {destructuring} - MAINTAINED!
class Database {
  constructor({config, logger}) {  // ← Still works!
    this.config = config;
    this.logger = logger;
  }
  
  async query(sql) {
    this.logger.info(`Executing: ${sql}`);
    return [];
  }
}

class UserService {
  constructor({database, logger}) {  // ← Destructuring preserved!
    this.database = database;
    this.logger = logger;
  }
  
  async findUser(id) {
    return this.database.query(`SELECT * FROM users WHERE id = ${id}`);
  }
}

// Fluent API - Much more powerful!
container
  .value('config', { dbUrl: 'postgresql://...' })
  .factory('logger', ({config}) => ({
    info: (msg) => console.log(`[INFO] ${msg}`),
    error: (msg) => console.error(`[ERROR] ${msg}`)
  }))
  .singleton(Database)
  .singleton(UserService);

// Use your services
const userService = container.resolve('userService');
const user = await userService.findUser(123);

🎨 Decorator System (NEW in v2.1)

The decorator system allows you to add cross-cutting concerns like logging, caching, and metrics to any service without modifying the original code.

Basic Decorator Usage

// Create decorator services
class LoggingDecorator {
  decorate(serviceInstance) {
    return {
      ...serviceInstance, // Preserve all properties
      findUser: async (id) => {
        console.log(`Finding user ${id}`);
        const result = await serviceInstance.findUser(id);
        console.log(`User ${id} found`);
        return result;
      }
    };
  }
}

class TimingDecorator {
  decorate(serviceInstance) {
    return {
      ...serviceInstance,
      findUser: async (id) => {
        const start = Date.now();
        const result = await serviceInstance.findUser(id);
        console.log(`findUser took ${Date.now() - start}ms`);
        return result;
      }
    };
  }
}

// Register decorators and apply them
container
  .register(LoggingDecorator, 'loggingDecorator').asSingleton()
  .register(TimingDecorator, 'timingDecorator').asSingleton()
  .register(UserService, 'userService')
  .decorateWith(['loggingDecorator', 'timingDecorator'])
  .asSingleton();

Batch Registration

Register multiple services with decorators using declarative configuration:

const serviceConfigs = [
  {
    class: OrderService,
    name: 'orderService',
    decorators: ['logging', 'metrics', 'cache'],
    lifecycle: 'singleton',
    tags: ['business', 'critical']
  },
  {
    class: UserService,
    name: 'userService', 
    decorators: ['logging', 'metrics'],
    lifecycle: 'singleton',
    tags: ['business', 'user']
  },
  {
    class: ReportingService,
    name: 'reportingService',
    decorators: ['logging', 'cache'],
    lifecycle: 'singleton',
    tags: ['analytics', 'heavy']
  }
];

container.batchRegister(serviceConfigs);

Custom Function Decorators

For more flexibility, use custom function decorators:

const cacheDecorator = (serviceInstance) => {
  const cache = new Map();
  
  return {
    ...serviceInstance,
    findUser: async (id) => {
      if (cache.has(id)) {
        return cache.get(id);
      }
      
      const result = await serviceInstance.findUser(id);
      cache.set(id, result);
      return result;
    }
  };
};

container
  .register(UserService, 'userService')
  .decorate(cacheDecorator)
  .decorateWith(['logging'])  // Mix function and service decorators
  .asSingleton();

Smart Decorators with Dependency Injection

Decorators can receive their own dependencies:

class UniversalCacheDecorator {
  constructor({ cache, logger }) {
    this.cache = cache;
    this.logger = logger;
  }

  decorate(serviceInstance) {
    const decoratedMethods = {};
    
    // Get ALL public methods dynamically
    const publicMethods = this._getPublicMethods(serviceInstance);
    
    for (const methodName of publicMethods) {
      const originalMethod = serviceInstance[methodName].bind(serviceInstance);
      decoratedMethods[methodName] = async (...args) => {
        const cacheKey = `${serviceInstance.constructor.name}.${methodName}:${JSON.stringify(args)}`;
        
        const cached = await this.cache.get(cacheKey);
        if (cached) {
          this.logger.info(`Cache hit for ${methodName}`);
          return cached;
        }
        
        const result = await originalMethod(...args);
        await this.cache.set(cacheKey, result);
        return result;
      };
    }

    return { ...serviceInstance, ...decoratedMethods };
  }
  
  _getPublicMethods(serviceInstance) {
    // Implementation to discover all public methods
    // Works with ANY method names automatically
  }
}

📚 API Reference

Container Creation

import { createContainer } from 'sdijs';

// Factory function (RECOMMENDED)
const container = createContainer({
  verbose: false,        // Enable/disable logging
  autoBinding: true,     // Auto-bind class methods
  strictMode: false,     // Strict registration rules
  maxServices: 1000,     // Memory limit for services
  maxInstances: 5000,    // Memory limit for instances
  maxScopes: 100,        // Memory limit for scopes
  maxHooksPerEvent: 50   // Memory limit for hooks
});

Service Registration

Fluent Registration API

// Basic registration with lifecycle
container.singleton(UserService);           // Singleton class
container.transient(NotificationService);   // New instance each time
container.value('config', configObject);    // Direct value

// Advanced registration with builder pattern
container
  .register(AdminService)
  .withTag('admin')
  .withTag('security')
  .when(() => process.env.NODE_ENV === 'production')
  .asSingleton();

// Factory functions with DI
container.factory('emailService', ({config, logger}) => {
  return {
    send: async (to, subject, body) => {
      logger.info(`Sending email to ${to}`);
      return { sent: true, to, subject };
    }
  };
}).asSingleton();

// Decorator registration
container
  .register(UserService, 'userService')
  .decorateWith(['loggingDecorator', 'cachingDecorator'])
  .decorate(customTimingDecorator)
  .withTags('business', 'critical')
  .asSingleton();

// Batch registration
container.batchRegister([
  { class: OrderService, name: 'orderService', decorators: ['logging'] },
  { class: UserService, name: 'userService', decorators: ['logging', 'cache'] }
]);

Service Lifecycles

Lifecycle	Description	Method
Singleton	One instance, cached globally	.singleton()
Transient	New instance every time	.transient()
Scoped	One instance per scope	.register().asScoped()
Value	Direct value, no instantiation	.value()

Service Resolution

// Basic resolution
const userService = container.resolve('userService');

// Multiple resolution
const {database, logger, config} = container.resolveAll([
  'database', 'logger', 'config'
]);

// Lazy resolution
const getUserService = container.getResolver('userService');
const service = getUserService(); // Resolved when called

// Scoped resolution
const requestService = requestScope.resolve('requestService');

Scoped Dependencies

Perfect for web applications with request/session-specific data:

// Create scopes
const requestScope = container.createScope('request');
const sessionScope = container.createScope('session');

// Register scoped services
class RequestContext {
  constructor({}) {
    this.requestId = Math.random().toString(36).substr(2, 9);
    this.startTime = Date.now();
  }
  
  getElapsed() {
    return Date.now() - this.startTime;
  }
}

container.register(RequestContext).asScoped();

// Use in different scopes
const ctx1 = requestScope.resolve('requestContext');
const ctx2 = requestScope.resolve('requestContext');
console.log(ctx1 === ctx2); // true - same instance within scope

// Clean up when done
requestScope.dispose();

Lifecycle Hooks

container
  .hook('beforeCreate', ({service}) => {
    console.log(`Creating ${service.name}`);
  })
  .hook('afterCreate', ({service, instance}) => {
    console.log(`Created ${service.name}`);
  });

// Clean up hooks when needed
container.clearHooks('beforeCreate');

Tag-based Service Discovery

Tag-based service discovery enables powerful architectural patterns like plugin systems, environment-specific services, and layered architectures:

// Register services with multiple tags
container
  .register(DatabaseRepository)
  .withTag('repository')
  .withTag('persistence')
  .withTag('production')
  .withTag('database')
  .asSingleton();

container
  .register(ApiRepository)
  .withTag('repository')
  .withTag('http')
  .withTag('external')
  .withTag('api')
  .asSingleton();

container
  .register(CacheService)
  .withTag('cache')
  .withTag('performance')
  .withTag('memory')
  .asSingleton();

// POWERFUL TAG-BASED SERVICE DISCOVERY

// 1. Find services with ALL specified tags (AND mode - default)
const prodRepositories = container.getServicesByTags(['repository', 'production']);
// Returns: [{ name: 'databaseRepository', service: {...}, tags: [...], lifecycle: 'singleton' }]

// 2. Find services with ANY specified tags (OR mode)  
const dataServices = container.getServicesByTags(['repository', 'cache'], 'OR');
// Returns: All repositories AND cache services

// 3. Get just the service names (simplified)
const repoNames = container.getServiceNamesByTags(['repository']);
// Returns: ['databaseRepository', 'apiRepository']

// 4. Resolve services directly by tags
const resolvedRepos = container.resolveServicesByTags(['repository']);
// Returns: [{ name: 'databaseRepository', instance: <resolved>, tags: [...] }]

// 5. Get all available tags (sorted)
const allTags = container.getAllTags();
console.log(allTags); 
// ['api', 'cache', 'database', 'external', 'http', 'memory', 'persistence', 'production', 'repository']

// 6. Get services grouped by tag
const grouped = container.getServicesByTag();
console.log(grouped.repository); // ['databaseRepository', 'apiRepository']
console.log(grouped.cache);      // ['cacheService']

Tag Discovery Methods:

Method	Purpose	Returns
getServicesByTags(tags, mode)	Full service metadata	Array<{name, service, tags, lifecycle}>
getServiceNamesByTags(tags, mode)	Just service names	string[]
resolveServicesByTags(tags, mode, scope)	Resolved instances	Array<{name, instance, tags}>
getAllTags()	All unique tags	string[] (sorted)
getServicesByTag()	Services grouped by tag	Record<string, string[]>

Real-World Tag Use Cases

Tags enable enterprise-grade architectural patterns:

// 1. ENVIRONMENT-SPECIFIC SERVICES
// Register different implementations for different environments
container.register(MockPaymentService).withTags('payment', 'development').asSingleton();
container.register(StripePaymentService).withTags('payment', 'production').asSingleton();
container.register(TestEmailService).withTags('email', 'test').asSingleton();
container.register(SendGridEmailService).withTags('email', 'production').asSingleton();

// Load environment-specific services
const env = process.env.NODE_ENV || 'development';
const paymentService = container.getServicesByTags(['payment', env])[0];
const emailServices = container.resolveServicesByTags(['email', env]);

// 2. LAYERED ARCHITECTURE
// Organize services by architectural layers
container.register(UserRepository).withTags('repository', 'data-layer').asSingleton();
container.register(ProductRepository).withTags('repository', 'data-layer').asSingleton();
container.register(UserService).withTags('service', 'business-layer').asSingleton();
container.register(OrderService).withTags('service', 'business-layer').asSingleton();
container.register(UserController).withTags('controller', 'presentation-layer').asSingleton();

// Load entire layers
const dataLayer = container.resolveServicesByTags(['data-layer']);
const businessLayer = container.resolveServicesByTags(['business-layer']);

// 3. PLUGIN SYSTEM
// Dynamic plugin discovery and initialization
container.register(AuthPlugin).withTags('plugin', 'security').asSingleton();
container.register(LoggingPlugin).withTags('plugin', 'monitoring').asSingleton();
container.register(CachePlugin).withTags('plugin', 'performance').asSingleton();

// Initialize all plugins
const plugins = container.resolveServicesByTags(['plugin']);
plugins.forEach(plugin => {
  console.log(`Initializing plugin: ${plugin.name}`);
  plugin.instance.initialize();
});

// 4. STRATEGY PATTERN IMPLEMENTATION
// Multiple payment strategies
container.register(CreditCardPayment).withTags('payment', 'strategy', 'card').asSingleton();
container.register(PayPalPayment).withTags('payment', 'strategy', 'paypal').asSingleton();
container.register(CryptoPayment).withTags('payment', 'strategy', 'crypto').asSingleton();

// Get all payment strategies
const allPaymentStrategies = container.getServicesByTags(['payment', 'strategy']);
console.log(`Available payment methods: ${allPaymentStrategies.map(s => s.name).join(', ')}`);

// Get specific payment type
const cardPayments = container.resolveServicesByTags(['payment', 'card']);

Pro Tips for Tag Usage:

• Use hierarchical tags: ['service', 'user-service'] for better organization
• Combine environment + feature: ['cache', 'redis', 'production']
• Use descriptive names: ['repository', 'read-only'] vs ['repo', 'ro']
• Group by capability: ['serializer', 'json'], ['serializer', 'xml']
• Version your APIs: ['api', 'v1'], ['api', 'v2']

Conditional Registration

container
  .register(MockEmailService)
  .when(() => process.env.NODE_ENV === 'test')
  .asSingleton();

container
  .register(SendGridEmailService)
  .when(() => process.env.NODE_ENV === 'production')
  .asSingleton();

🔒 Security Features

SDIJS includes enterprise-grade security features:

// Prototype pollution protection
class VulnerableService {
  constructor(deps) {
    deps.__proto__; // Throws: Dangerous property access blocked
    deps.constructor; // Throws: Dangerous property access blocked
  }
}

// Memory limits prevent DoS attacks
const limitedContainer = createContainer({
  maxServices: 100,      // Max registered services
  maxInstances: 500,     // Max cached instances
  maxScopes: 10,         // Max concurrent scopes
  maxHooksPerEvent: 20   // Max hooks per event
});

// Input validation on all methods
container.value('', 'test'); // Throws: Service name must be non-empty
container.factory('test', 'not-a-function'); // Throws: Factory must be a function

💎 Destructuring Support

The key feature that makes SDIJS special - your destructuring syntax remains unchanged:

// All of these still work exactly the same!

class UserService {
  constructor({database, logger, config, emailService}) {
    this.database = database;
    this.logger = logger;
    this.config = config;
    this.emailService = emailService;
  }
}

class PaymentService {
  constructor({userService, database, logger}) {
    // Your existing code doesn't change!
  }
}

// Factory functions too
const utils = ({config, logger}) => {
  return {
    formatUser: (user) => `${user.name} <${user.email}>`,
    logAction: (action) => logger.info(action)
  };
};

🛠️ Utility Methods

// Service management
container.has('serviceName');           // Check if registered
container.unregister('serviceName');    // Remove service
container.clear();                      // Clear all services
container.getServiceNames();            // List all service names

// Scope management
const scope = container.createScope('myScope');
scope.dispose();                        // Clean up scope
scope.getInstances();                   // Get all instances in scope

// Hook management
container.clearHooks('beforeCreate');   // Remove all hooks for event

🔍 Error Handling & Debugging

SDIJS provides helpful error messages and verbose logging:

// Verbose logging with clear categories
const container = createContainer({ verbose: true });

// Logs show clear categories:
// [SDIJS:REGISTER] Service 'userService' [singleton] with decorators
// [SDIJS:RESOLVE] Resolving dependency: database
// [SDIJS:DECORATOR] Applied decorator 'logging' to service 'userService'
// [SDIJS:VALIDATION] Decorator 'logging' successfully preserved service interface...

// Service not found
container.resolve('nonExistent');
// Error: Service 'nonExistent' not found. Did you forget to register it?

// Circular dependency
container.singleton(ServiceA).singleton(ServiceB);
// Error: Circular dependency detected: serviceA → serviceB → serviceA

// Decorator validation errors
// Error: Decorator 'badDecorator' removed public method(s) from service 'userService': findUser
// Warning: Decorator 'timingDecorator' changed 'findUser' method signature. Original: 1 params, Decorated: 3 params

// Memory limits exceeded
container.value('service1000', {}); 
// Error: Memory limit exceeded for services. Max: 1000

// Security violations
class BadService {
  constructor(deps) {
    deps.__proto__; // Error: Dangerous property access blocked: '__proto__'
  }
}

🚀 Migration from v2.0

New Features in v2.1 (Non-breaking):

• Service decorators with .decorateWith() and .decorate()
• Universal method validation (works with any method names)
• Batch registration with container.batchRegister()
• Enhanced verbose logging with clear categories
• Interface preservation validation
• Smart signature change detection

Your existing v2.0 code works unchanged!

📝 Examples

Main Example

Check out example.js for a comprehensive demonstration of all features.

Comprehensive Examples Directory

Explore the examples/ directory with specialized examples:

# If you cloned the repository
cd examples

# Run individual examples
node 01-basic/simple-di.js              # Basic DI concepts
node 02-advanced/factory-functions.js   # Factory functions
node 02-advanced/scopes-and-hooks.js    # Scoped dependencies & hooks
node 03-patterns/strategy-pattern.js    # Strategy pattern with tags
node 03-patterns/decorator-pattern.js   # Decorator pattern
node 04-enterprise/microservices-communication.js # Enterprise microservices
node 05-web-app/express-integration.js  # Express.js integration
node 06-testing/mocking-and-testing.js  # Testing with mocks
node 07-advanced/tag-discovery.js       # Advanced tag-based discovery
node 09-decorators/basic-decorator-usage.js        # NEW: Basic decorators
node 09-decorators/advanced-decorator-features.js  # NEW: Advanced decorators

NEW Decorator Examples:

• Basic Decorator Usage - Simple logging, timing, and caching decorators
• Advanced Decorator Features - Universal validation, batch registration, enterprise patterns

🔗 TypeScript

Full TypeScript support included with comprehensive type definitions:

import { createContainer, ServiceConfig } from 'sdijs';

interface IUserService {
  findUser(id: number): Promise<User>;
}

interface User {
  id: number;
  name: string;
  email: string;
}

const container = createContainer({ verbose: true });

// Batch registration with types
const configs: ServiceConfig[] = [
  { 
    class: UserService, 
    name: 'userService',
    decorators: ['logging', 'cache'],
    lifecycle: 'singleton',
    tags: ['business']
  }
];

container.batchRegister(configs);
const userService = container.resolve<IUserService>('userService');

📊 Performance

SDIJS v2.1 is designed for enterprise performance:

• Lazy resolution - Services created only when needed
• Efficient caching - Singleton instances cached with WeakMap
• Memory limits - Configurable limits prevent memory leaks
• Auto-binding - Optional method binding with caching
• Minimal overhead - Zero dependencies, pure JavaScript
• Fast tag discovery - Optimized Set operations for tag matching
• Scalable architecture - Performance tested with 55+ services and 100+ tags
• Universal validation - Efficient method discovery with prototype chain walking
• Smart decorator caching - Optimized decorator application and validation

Performance Results:

• Tag discovery: <100ms for 100+ tags
• Service registration: <1000ms for 55+ services
• Universal method validation: <10ms per service
• Decorator application: <5ms per decorator

---

SDIJS v2.1 - Modern DI with advanced decorators that grows with your application while keeping your code clean, secure, and testable. 🚀