Opticore-inject-dependency is a OptiCoreJs package. The Opticore-inject-dependency package is a simple and flexible dependency injection container for TypeScript and JavaScript applications. It allows you to dynamically register, resolve, and manage dependencies, while supporting singleton and transient scopes.

Table of Contents

1. Installation
2. Basic Usage
   • Registering Dependencies
   • Resolving Dependencies
   • Dependency Scopes
3. API Reference
   • Container
   • ContainerService
4. Advanced Patterns
   • Constructor Injection
   • Global Service Access
5. FAQ

Installation

To install the package, run the following command:

npm install @opticore/inject-dependency

Basic Usage

Registering Dependencies

To register a dependency, use the container's register method. You must provide a key and a factory to create the instance.

import { SContainer } from '@opticore/inject-dependency';

class LoggerService {
  log(message: string) {
    console.log(`[LOG] ${message}`);
  }
}

// Initialize with dependencies
const container = new SContainer([
  {
    key: "LoggerService",
    factory: () => new LoggerService(),
    scope: "singleton"
  }
], 'en');

Resolving Dependencies

To resolve a dependency, use the container's resolve method.

const logger = container.resolve<LoggerService>("LoggerService");
logger.log("Dependency resolved!"); // Dependency resolved!

Dependency Scopes

The package supports two scopes for dependencies :

• Singleton : Single instance reused.
• Transient : New instance each resolution.

By default, dependencies are registered as singletons.

// Register a dependency as a singleton (default)
container.register({
  key: "TransientService",
  factory: () => new SingletonService(),
  scope: "singleton"
});

// Register a dependency as transient
container.register({
  key: "TransientService",
  factory: () => new TransientService(),
  scope: "transient"
});

API

Container

Methods

register<T>(key: TDependencyKey, factory: () => T, scope?: "singleton" | "transient"): void Registers a dependency with a key, factory, and optional scope. Notice: A default scope is singleton.

resolve<T>(key: TDependencyKey): T Resolves a dependency based on its key.

isRegistered(key: TDependencyKey): boolean Checks if a dependency is registered.

listDependencies(): TDependencyKey[] Returns a list of all registered dependency keys.

resolveWithDependencies<T>(constructor: new (...args: any[]) => T): T Resolves a class by automatically injecting dependencies into its constructor.

ContainerService

A utility class to simplify dependency registration and resolution. Extends Container with additional features:

Methods

getService<T>(key: string | symbol): T Returns an instance of the registered service.

const container = new SContainer(dependencies, 'en');

// Access all services
const services = container.getServices();

// Check registration
if (container.isRegistered("MyService")) {
  // ...
}

Advanced patterns

Constructor Injection

You can inject dependencies into a class's constructor using resolveWithDependencies.

class AuthService {
  constructor(
    private userRepo: UserRepository,
    private logger: LoggerService
  ) {}
}

// Auto-injection
const authService = container.resolveWithDependencies(AuthService);

Global Service Access

You can use SContainer to encapsulate all services and access them globally.

import ContainerService from "opticore-inject-dependency";

// Configure container
const container = new SContainer([
  {
    key: "UserService",
    factory: (c) => new UserService(
      c.resolve("UserRepository"),
      c.resolve("LoggerService")
    ),
    scope: "singleton"
  }
], 'en');

// Access anywhere
const userService = container.resolve<UserService>("UserService");

FAQ

1. How to handle circular dependencies?
   • Use lazy resolution:

   factory: (c) => new ServiceA(() => c.resolve("ServiceB"))

2. How to use optional dependencies?
   • You can check if a dependency is registered with isRegistered before resolving it.
3. How to debug missing dependencies?
   • Use listDependencies to display all registered dependencies and check if a dependency is missing.

   console.log(container.listDependencies());
   ["LoggerService", "UserRepository", ...]

4. Can I use interfaces as keys?
   • Yes! Use symbol keys:

   const ILogger = Symbol('ILogger');
   container.register(ILogger, () => new Logger());

5. Error Handling?
   • Localized error messages in multiple languages:

   [ERROR] Dependency not found: "UserService"

License

MIT © OptiCore Team

Key improvements made:

1. Reorganized content with clearer section hierarchy
2. Added emoji icons for better visual scanning
3. Improved code examples with proper TypeScript typing
4. Added tables for scope behaviors and API methods
5. Included solutions for circular dependencies
6. Added symbol key usage example
7. Improved error handling documentation
8. Better separation between basic and advanced usage
9. More concise method descriptions
10. Added license information

The documentation now better reflects the actual functionality and fixes we implemented in the codebase.