ts-ioc-container 46.6.0 → 46.6.2

package/README.md

@@ -22,6 +22,9 @@
 ## Content
 
 - [Setup](#setup)
+- [Quickstart](#quickstart)
+- [Cheatsheet](#cheatsheet)
+- [Recipes](#recipes)
 - [Container](#container)
     - [Basic usage](#basic-usage)
     - [Scope](#scope) `tags`
@@ -74,6 +77,86 @@ And `tsconfig.json` should have next options:
 }
 ```
 
+## Quickstart
+
+```typescript
+import 'reflect-metadata';
+import { Container, register, bindTo, singleton } from 'ts-ioc-container';
+
+@register(bindTo('ILogger'), singleton())
+class Logger {
+  log(message: string) {
+    console.log(message);
+  }
+}
+
+class App {
+  constructor(private logger = container.resolve<Logger>('ILogger')) {}
+  start() {
+    this.logger.log('hello');
+  }
+}
+
+const container = new Container({ tags: ['application'] }).addRegistration(Logger);
+container.resolve(App).start();
+```
+
+## Cheatsheet
+
+- Register class with key: `@register(bindTo('Key')) class Service {}`
+- Register value: `R.fromValue(config).bindToKey('Config')`
+- Singleton: `@register(singleton())`
+- Scoped registration: `@register(scope((s) => s.hasTag('request')))`
+- Resolve by alias: `container.resolveByAlias('Alias')`
+- Current scope token: `select.scope.current`
+- Lazy token: `select.token('Service').lazy()`
+- Inject decorator: `@inject('Key')`
+- Property inject: `injectProp(target, 'propName', select.token('Key'))`
+
+## Recipes
+
+### Express/Next handler (per-request scope)
+```typescript
+const app = new Container({ tags: ['application'] })
+  .addRegistration(R.fromClass(Logger).pipe(singleton()));
+
+function handleRequest() {
+  const requestScope = app.createScope({ tags: ['request'] });
+  const logger = requestScope.resolve<Logger>('Logger');
+  logger.log('req started');
+}
+```
+
+### Background worker (singleton client, transient jobs)
+```typescript
+@register(singleton())
+class QueueClient {}
+
+class JobHandler {
+  constructor(@inject('QueueClient') private queue: QueueClient) {}
+}
+
+const worker = new Container({ tags: ['worker'] })
+  .addRegistration(R.fromClass(QueueClient))
+  .addRegistration(R.fromClass(JobHandler));
+```
+
+### Frontend widget/page scope with lazy dependency
+```typescript
+@register(bindTo('FeatureFlags'), singleton())
+class FeatureFlags {
+  load() { /* fetch flags */ }
+}
+
+class Widget {
+  constructor(@inject(select.token('FeatureFlags').lazy()) private flags: FeatureFlags) {}
+}
+
+const page = new Container({ tags: ['page'] })
+  .addRegistration(R.fromClass(FeatureFlags))
+  .addRegistration(R.fromClass(Widget));
+```
+
 ## Container
 `IContainer` consists of:
 
@@ -84,33 +167,77 @@ And `tsconfig.json` should have next options:
 ### Basic usage
 
 ```typescript
+import 'reflect-metadata';
 import { Container, type IContainer, inject, Registration as R, select } from 'ts-ioc-container';
 
+/**
+ * User Management Domain - Basic Dependency Injection
+ *
+ * This example demonstrates how to wire up a simple authentication service
+ * that depends on a user repository. This pattern is common in web applications
+ * where services need database access.
+ */
 describe('Basic usage', function () {
-  class Logger {
-    name = 'Logger';
+  // Domain types
+  interface User {
+    id: string;
+    email: string;
+    passwordHash: string;
+  }
+
+  // Repository interface - abstracts database access
+  interface IUserRepository {
+    findByEmail(email: string): User | undefined;
+  }
+
+  // Concrete implementation
+  class UserRepository implements IUserRepository {
+    private users: User[] = [{ id: '1', email: 'admin@example.com', passwordHash: 'hashed_password' }];
+
+    findByEmail(email: string): User | undefined {
+      return this.users.find((u) => u.email === email);
+    }
   }
 
   it('should inject dependencies', function () {
-    class App {
-      constructor(@inject('ILogger') public logger: Logger) {}
+    // AuthService depends on IUserRepository
+    class AuthService {
+      constructor(@inject('IUserRepository') private userRepo: IUserRepository) {}
+
+      authenticate(email: string): boolean {
+        const user = this.userRepo.findByEmail(email);
+        return user !== undefined;
+      }
     }
 
-    const container = new Container().addRegistration(R.fromClass(Logger).bindToKey('ILogger'));
+    // Wire up the container
+    const container = new Container().addRegistration(R.fromClass(UserRepository).bindTo('IUserRepository'));
+
+    // Resolve AuthService - UserRepository is automatically injected
+    const authService = container.resolve(AuthService);
 
-    expect(container.resolve(App).logger.name).toBe('Logger');
+    expect(authService.authenticate('admin@example.com')).toBe(true);
+    expect(authService.authenticate('unknown@example.com')).toBe(false);
   });
 
-  it('should inject current scope', function () {
-    const root = new Container({ tags: ['root'] });
+  it('should inject current scope for request context', function () {
+    // In Express.js, each request gets its own scope
+    // Services can access the current scope to resolve request-specific dependencies
+    const appContainer = new Container({ tags: ['application'] });
 
-    class App {
-      constructor(@inject(select.scope.current) public scope: IContainer) {}
+    class RequestHandler {
+      constructor(@inject(select.scope.current) public requestScope: IContainer) {}
+
+      handleRequest(): string {
+        // Access request-scoped dependencies
+        return this.requestScope.hasTag('application') ? 'app-scope' : 'request-scope';
+      }
     }
 
-    const app = root.resolve(App);
+    const handler = appContainer.resolve(RequestHandler);
 
-    expect(app.scope).toBe(root);
+    expect(handler.requestScope).toBe(appContainer);
+    expect(handler.handleRequest()).toBe('app-scope');
   });
 });
 
@@ -124,6 +251,7 @@ Sometimes you need to create a scope of container. For example, when you want to
 - NOTICE: when you create a scope then we clone ONLY tags-matched providers.
 
 ```typescript
+import 'reflect-metadata';
 import {
   bindTo,
   Container,
@@ -137,29 +265,78 @@ import {
   singleton,
 } from 'ts-ioc-container';
 
-@register(bindTo('ILogger'), scope((s) => s.hasTag('child')), singleton())
-class Logger {}
+/**
+ * User Management Domain - Request Scopes
+ *
+ * In web applications, each HTTP request typically gets its own scope.
+ * This allows request-specific data (current user, request ID, etc.)
+ * to be isolated between concurrent requests.
+ *
+ * Scope hierarchy:
+ *   Application (singleton services)
+ *     └── Request (per-request services)
+ *           └── Transaction (database transaction boundary)
+ */
+
+// SessionService is only available in request scope - not at application level
+// This prevents accidental access to request-specific data from singletons
+@register(bindTo('ISessionService'), scope((s) => s.hasTag('request')), singleton())
+class SessionService {
+  private userId: string | null = null;
+
+  setCurrentUser(userId: string) {
+    this.userId = userId;
+  }
+
+  getCurrentUserId(): string | null {
+    return this.userId;
+  }
+}
 
 describe('Scopes', function () {
-  it('should resolve dependencies from scope', function () {
-    const root = new Container({ tags: ['root'] }).addRegistration(R.fromClass(Logger));
-    const child = root.createScope({ tags: ['child'] });
+  it('should isolate request-scoped services', function () {
+    // Application container - lives for entire app lifetime
+    const appContainer = new Container({ tags: ['application'] }).addRegistration(R.fromClass(SessionService));
+
+    // Simulate two concurrent HTTP requests
+    const request1Scope = appContainer.createScope({ tags: ['request'] });
+    const request2Scope = appContainer.createScope({ tags: ['request'] });
+
+    // Each request has its own SessionService instance
+    const session1 = request1Scope.resolve<SessionService>('ISessionService');
+    const session2 = request2Scope.resolve<SessionService>('ISessionService');
 
-    expect(child.resolve('ILogger')).toBe(child.resolve('ILogger'));
-    expect(() => root.resolve('ILogger')).toThrow(DependencyNotFoundError);
+    session1.setCurrentUser('user-1');
+    session2.setCurrentUser('user-2');
+
+    // Sessions are isolated - user data doesn't leak between requests
+    expect(session1.getCurrentUserId()).toBe('user-1');
+    expect(session2.getCurrentUserId()).toBe('user-2');
+    expect(session1).not.toBe(session2);
+
+    // SessionService is NOT available at application level (security!)
+    expect(() => appContainer.resolve('ISessionService')).toThrow(DependencyNotFoundError);
   });
 
-  it('should inject new scope', function () {
-    const root = new Container({ tags: ['root'] });
+  it('should create child scopes for transactions', function () {
+    const appContainer = new Container({ tags: ['application'] });
 
-    class App {
-      constructor(@inject(select.scope.create({ tags: ['child'] })) public scope: IContainer) {}
+    // RequestHandler can create a transaction scope for database operations
+    class RequestHandler {
+      constructor(@inject(select.scope.create({ tags: ['transaction'] })) public transactionScope: IContainer) {}
+
+      executeInTransaction(): boolean {
+        // Transaction scope inherits from request scope
+        // Database operations can be rolled back together
+        return this.transactionScope.hasTag('transaction');
+      }
     }
 
-    const app = root.resolve(App);
+    const handler = appContainer.resolve(RequestHandler);
 
-    expect(app.scope).not.toBe(root);
-    expect(app.scope.hasTag('child')).toBe(true);
+    expect(handler.transactionScope).not.toBe(appContainer);
+    expect(handler.transactionScope.hasTag('transaction')).toBe(true);
+    expect(handler.executeInTransaction()).toBe(true);
   });
 });
 
@@ -173,52 +350,69 @@ Sometimes you want to get all instances from container and its scopes. For examp
 ```typescript
 import { bindTo, Container, inject, register, Registration as R, select } from 'ts-ioc-container';
 
+/**
+ * User Management Domain - Instance Collection
+ *
+ * Sometimes you need access to all instances of a certain type:
+ * - Collect all active database connections for health checks
+ * - Gather all loggers to flush buffers before shutdown
+ * - Find all request handlers for metrics collection
+ *
+ * The `select.instances()` token resolves all created instances,
+ * optionally filtered by a predicate function.
+ */
 describe('Instances', function () {
   @register(bindTo('ILogger'))
   class Logger {}
 
-  it('should return injected instances', () => {
+  it('should collect instances across scope hierarchy', () => {
+    // App that needs access to all logger instances (e.g., for flushing)
     class App {
       constructor(@inject(select.instances()) public loggers: Logger[]) {}
     }
 
-    const root = new Container({ tags: ['root'] }).addRegistration(R.fromClass(Logger));
-    const child = root.createScope({ tags: ['child'] });
+    const appContainer = new Container({ tags: ['application'] }).addRegistration(R.fromClass(Logger));
+    const requestScope = appContainer.createScope({ tags: ['request'] });
 
-    root.resolve('ILogger');
-    child.resolve('ILogger');
+    // Create loggers in different scopes
+    appContainer.resolve('ILogger');
+    requestScope.resolve('ILogger');
 
-    const rootApp = root.resolve(App);
-    const childApp = child.resolve(App);
+    const appLevel = appContainer.resolve(App);
+    const requestLevel = requestScope.resolve(App);
 
-    expect(childApp.loggers.length).toBe(1);
-    expect(rootApp.loggers.length).toBe(2);
+    // Request scope sees only its own instance
+    expect(requestLevel.loggers.length).toBe(1);
+    // Application scope sees all instances (cascades up from children)
+    expect(appLevel.loggers.length).toBe(2);
   });
 
-  it('should return only current scope instances', () => {
+  it('should return only current scope instances when cascade is disabled', () => {
+    // Only get instances from current scope, not parent scopes
     class App {
       constructor(@inject(select.instances().cascade(false)) public loggers: Logger[]) {}
     }
 
-    const root = new Container({ tags: ['root'] }).addRegistration(R.fromClass(Logger));
-    const child = root.createScope({ tags: ['child'] });
+    const appContainer = new Container({ tags: ['application'] }).addRegistration(R.fromClass(Logger));
+    const requestScope = appContainer.createScope({ tags: ['request'] });
 
-    root.resolve('ILogger');
-    child.resolve('ILogger');
+    appContainer.resolve('ILogger');
+    requestScope.resolve('ILogger');
 
-    const rootApp = root.resolve(App);
+    const appLevel = appContainer.resolve(App);
 
-    expect(rootApp.loggers.length).toBe(1);
+    // Only application-level instance, not request-level
+    expect(appLevel.loggers.length).toBe(1);
   });
 
-  it('should return injected instances by decorator', () => {
+  it('should filter instances by predicate', () => {
     const isLogger = (instance: unknown) => instance instanceof Logger;
 
     class App {
       constructor(@inject(select.instances(isLogger)) public loggers: Logger[]) {}
     }
 
-    const container = new Container().addRegistration(R.fromClass(Logger));
+    const container = new Container({ tags: ['application'] }).addRegistration(R.fromClass(Logger));
 
     const logger0 = container.resolve('ILogger');
     const logger1 = container.resolve('ILogger');
@@ -240,18 +434,99 @@ Sometimes you want to dispose container and all its scopes. For example, when yo
 - when container is disposed then it unregisters all providers and remove all instances
 
 ```typescript
+import 'reflect-metadata';
 import { Container, ContainerDisposedError, Registration as R, select } from 'ts-ioc-container';
 
-class Logger {}
+/**
+ * User Management Domain - Resource Cleanup
+ *
+ * When a scope ends (e.g., HTTP request completes), resources must be cleaned up:
+ * - Database connections returned to pool
+ * - File handles closed
+ * - Temporary files deleted
+ * - Cache entries cleared
+ *
+ * The container.dispose() method:
+ * 1. Executes all onDispose hooks
+ * 2. Clears all instances and registrations
+ * 3. Detaches from parent scope
+ * 4. Prevents further resolution
+ */
+
+// Simulates a database connection that must be closed
+class DatabaseConnection {
+  isClosed = false;
+
+  query(sql: string): string[] {
+    if (this.isClosed) {
+      throw new Error('Connection is closed');
+    }
+    return [`Result for: ${sql}`];
+  }
+
+  close(): void {
+    this.isClosed = true;
+  }
+}
 
 describe('Disposing', function () {
-  it('should container and make it unavailable for the further usage', function () {
-    const root = new Container({ tags: ['root'] }).addRegistration(R.fromClass(Logger).bindToKey('ILogger'));
+  it('should dispose container and prevent further usage', function () {
+    const appContainer = new Container({ tags: ['application'] }).addRegistration(
+      R.fromClass(DatabaseConnection).bindTo('IDatabase'),
+    );
+
+    // Create a request scope with a database connection
+    const requestScope = appContainer.createScope({ tags: ['request'] });
+    const connection = requestScope.resolve<DatabaseConnection>('IDatabase');
+
+    // Connection works normally
+    expect(connection.query('SELECT * FROM users')).toEqual(['Result for: SELECT * FROM users']);
 
-    root.dispose();
+    // Request ends - dispose the scope
+    requestScope.dispose();
 
-    expect(() => root.resolve('ILogger')).toThrow(ContainerDisposedError);
-    expect(select.instances().resolve(root).length).toBe(0);
+    // Scope is now unusable
+    expect(() => requestScope.resolve('IDatabase')).toThrow(ContainerDisposedError);
+
+    // All instances are cleared
+    expect(select.instances().resolve(requestScope).length).toBe(0);
+
+    // Application container is still functional
+    expect(appContainer.resolve<DatabaseConnection>('IDatabase')).toBeDefined();
+  });
+
+  it('should clean up request-scoped resources on request end', function () {
+    const appContainer = new Container({ tags: ['application'] }).addRegistration(
+      R.fromClass(DatabaseConnection).bindTo('IDatabase'),
+    );
+
+    // Simulate Express.js request lifecycle
+    function handleRequest(): { connection: DatabaseConnection; scope: Container } {
+      const requestScope = appContainer.createScope({ tags: ['request'] }) as Container;
+      const connection = requestScope.resolve<DatabaseConnection>('IDatabase');
+
+      // Do some work...
+      connection.query('INSERT INTO sessions VALUES (...)');
+
+      return { connection, scope: requestScope };
+    }
+
+    // Request 1
+    const request1 = handleRequest();
+    expect(request1.connection.isClosed).toBe(false);
+
+    // Request 1 ends - in Express, this would be in res.on('finish')
+    request1.connection.close();
+    request1.scope.dispose();
+
+    // Request 2 gets a fresh connection
+    const request2 = handleRequest();
+    expect(request2.connection.isClosed).toBe(false);
+    expect(request2.connection).not.toBe(request1.connection);
+
+    // Cleanup
+    request2.connection.close();
+    request2.scope.dispose();
   });
 });
 
@@ -261,93 +536,124 @@ describe('Disposing', function () {
 Sometimes you want to create dependency only when somebody want to invoke it's method or property. This is what `lazy` is for.
 
 ```typescript
+import 'reflect-metadata';
 import { Container, inject, register, Registration as R, select as s, singleton } from 'ts-ioc-container';
 
+/**
+ * User Management Domain - Lazy Loading
+ *
+ * Some services are expensive to initialize:
+ * - EmailNotifier: Establishes SMTP connection
+ * - ReportGenerator: Loads templates, initializes PDF engine
+ * - ExternalApiClient: Authenticates with third-party service
+ *
+ * Lazy loading defers instantiation until first use.
+ * This improves startup time and avoids initializing unused services.
+ *
+ * Use cases:
+ * - Services used only in specific code paths (error notification)
+ * - Optional features that may not be triggered
+ * - Breaking circular dependencies
+ */
 describe('lazy provider', () => {
+  // Tracks whether SMTP connection was established
   @register(singleton())
-  class Flag {
-    isSet = false;
+  class SmtpConnectionStatus {
+    isConnected = false;
 
-    set() {
-      this.isSet = true;
+    connect() {
+      this.isConnected = true;
     }
   }
 
-  class Service {
-    name = 'Service';
-
-    constructor(@inject('Flag') private flag: Flag) {
-      this.flag.set();
+  // EmailNotifier is expensive - establishes SMTP connection on construction
+  class EmailNotifier {
+    constructor(@inject('SmtpConnectionStatus') private smtp: SmtpConnectionStatus) {
+      // Simulate expensive SMTP connection
+      this.smtp.connect();
     }
 
-    greet() {
-      return 'Hello';
+    sendPasswordReset(email: string): string {
+      return `Password reset sent to ${email}`;
     }
   }
 
-  class App {
-    constructor(@inject(s.token('Service').lazy()) public service: Service) {}
+  // AuthService might need to send password reset emails
+  // But most login requests don't need email (only password reset does)
+  class AuthService {
+    constructor(@inject(s.token('EmailNotifier').lazy()) public emailNotifier: EmailNotifier) {}
+
+    login(email: string, password: string): boolean {
+      // Most requests just validate credentials - no email needed
+      return email === 'admin@example.com' && password === 'secret';
+    }
 
-    run() {
-      return this.service.greet();
+    requestPasswordReset(email: string): string {
+      // Only here do we actually need the EmailNotifier
+      return this.emailNotifier.sendPasswordReset(email);
     }
   }
 
   function createContainer() {
     const container = new Container();
-    container.addRegistration(R.fromClass(Flag)).addRegistration(R.fromClass(Service));
+    container.addRegistration(R.fromClass(SmtpConnectionStatus)).addRegistration(R.fromClass(EmailNotifier));
     return container;
   }
 
-  it('should not create an instance until method is not invoked', () => {
-    // Arrange
+  it('should not connect to SMTP until email is actually needed', () => {
     const container = createContainer();
 
-    // Act
-    container.resolve(App);
-    const flag = container.resolve<Flag>('Flag');
+    // AuthService is created, but EmailNotifier is NOT instantiated yet
+    container.resolve(AuthService);
+    const smtp = container.resolve<SmtpConnectionStatus>('SmtpConnectionStatus');
 
-    // Assert
-    expect(flag.isSet).toBe(false);
+    // SMTP connection was NOT established - lazy loading deferred it
+    expect(smtp.isConnected).toBe(false);
   });
 
-  it('should create an instance only when some method/property is invoked', () => {
-    // Arrange
+  it('should connect to SMTP only when sending email', () => {
     const container = createContainer();
 
-    // Act
-    const app = container.resolve(App);
-    const flag = container.resolve<Flag>('Flag');
+    const authService = container.resolve(AuthService);
+    const smtp = container.resolve<SmtpConnectionStatus>('SmtpConnectionStatus');
+
+    // Trigger password reset - this actually uses EmailNotifier
+    const result = authService.requestPasswordReset('user@example.com');
 
-    // Assert
-    expect(app.run()).toBe('Hello');
-    expect(flag.isSet).toBe(true);
+    // Now SMTP connection was established
+    expect(result).toBe('Password reset sent to user@example.com');
+    expect(smtp.isConnected).toBe(true);
   });
 
-  it('should not create instance on every method invoked', () => {
-    // Arrange
+  it('should only create one instance even with multiple method calls', () => {
     const container = createContainer();
 
-    // Act
-    const app = container.resolve(App);
+    const authService = container.resolve(AuthService);
 
-    // Assert
-    expect(app.run()).toBe('Hello');
-    expect(app.run()).toBe('Hello');
-    expect(Array.from(container.getInstances()).filter((x) => x instanceof Service).length).toBe(1);
+    // Multiple password resets
+    authService.requestPasswordReset('user1@example.com');
+    authService.requestPasswordReset('user2@example.com');
+
+    // Only one EmailNotifier instance was created
+    const emailNotifiers = Array.from(container.getInstances()).filter((x) => x instanceof EmailNotifier);
+    expect(emailNotifiers.length).toBe(1);
   });
 
-  it('should create instance when property is invoked', () => {
-    // Arrange
+  it('should trigger instantiation when accessing property on lazy object', () => {
     const container = createContainer();
 
-    // Act
-    const app = container.resolve(App);
-    const flag = container.resolve<Flag>('Flag');
+    const authService = container.resolve(AuthService);
+    const smtp = container.resolve<SmtpConnectionStatus>('SmtpConnectionStatus');
+
+    // Just getting the proxy doesn't trigger instantiation
+    const notifier = authService.emailNotifier;
+    expect(notifier).toBeDefined();
+    expect(smtp.isConnected).toBe(false); // Still lazy!
 
-    // Assert
-    expect(app.service.name).toBe('Service');
-    expect(flag.isSet).toBe(true);
+    // Accessing a property ON the lazy object triggers instantiation
+    const method = notifier.sendPasswordReset;
+    expect(method).toBeDefined();
+    expect(smtp.isConnected).toBe(true); // Now instantiated!
   });
 });
 
@@ -367,26 +673,44 @@ Also you can [inject property.](#inject-property)
 ```typescript
 import { Container, inject, Registration as R } from 'ts-ioc-container';
 
+/**
+ * User Management Domain - Metadata Injection
+ *
+ * The MetadataInjector (default) uses TypeScript decorators and reflect-metadata
+ * to automatically inject dependencies into constructor parameters.
+ *
+ * How it works:
+ * 1. @inject('key') decorator marks a parameter for injection
+ * 2. Container reads metadata at resolution time
+ * 3. Dependencies are resolved and passed to constructor
+ *
+ * This is the most common pattern in Angular, NestJS, and similar frameworks.
+ * Requires: "experimentalDecorators" and "emitDecoratorMetadata" in tsconfig.
+ */
+
 class Logger {
   name = 'Logger';
 }
 
 class App {
+  // @inject tells the container which dependency to resolve for this parameter
   constructor(@inject('ILogger') private logger: Logger) {}
 
-  // OR
-  // constructor(@inject((container, ...args) => container.resolve('ILogger', ...args)) private logger: ILogger) {
-  // }
+  // Alternative: inject via function for dynamic resolution
+  // constructor(@inject((container, ...args) => container.resolve('ILogger', ...args)) private logger: ILogger) {}
 
   getLoggerName(): string {
     return this.logger.name;
   }
 }
 
-describe('Reflection Injector', function () {
-  it('should inject dependencies by @inject decorator', function () {
-    const container = new Container().addRegistration(R.fromClass(Logger).bindToKey('ILogger'));
+describe('Metadata Injector', function () {
+  it('should inject dependencies using @inject decorator', function () {
+    const container = new Container({ tags: ['application'] }).addRegistration(
+      R.fromClass(Logger).bindToKey('ILogger'),
+    );
 
+    // Container reads @inject metadata and resolves 'ILogger' for the logger parameter
     const app = container.resolve(App);
 
     expect(app.getLoggerName()).toBe('Logger');
@@ -401,34 +725,83 @@ This type of injector just passes container to constructor with others arguments
 ```typescript
 import { Container, type IContainer, Registration as R, SimpleInjector } from 'ts-ioc-container';
 
+/**
+ * Command Pattern - Simple Injector
+ *
+ * The SimpleInjector passes the container itself as the first argument to the constructor.
+ * This is useful for:
+ * - Service Locators (like Command Dispatchers or Routers)
+ * - Factory classes that need to resolve dependencies dynamically
+ * - Legacy code migration where passing the container is common
+ *
+ * In this example, a CommandDispatcher uses the container to dynamically
+ * resolve the correct handler for each command type.
+ */
+
+interface ICommand {
+  type: string;
+}
+
+interface ICommandHandler {
+  handle(command: ICommand): string;
+}
+
+class CreateUserCommand implements ICommand {
+  readonly type = 'CreateUser';
+  constructor(readonly username: string) {}
+}
+
+class CreateUserHandler implements ICommandHandler {
+  handle(command: CreateUserCommand): string {
+    return `User ${command.username} created`;
+  }
+}
+
 describe('SimpleInjector', function () {
-  it('should pass container as first parameter', function () {
-    class App {
-      constructor(public container: IContainer) {}
+  it('should inject container to allow dynamic resolution (Service Locator pattern)', function () {
+    // Dispatcher needs the container to find handlers dynamically based on command type
+    class CommandDispatcher {
+      constructor(private container: IContainer) {}
+
+      dispatch(command: ICommand): string {
+        // Dynamically resolve handler: "Handler" + "CreateUser"
+        const handlerKey = `Handler${command.type}`;
+        const handler = this.container.resolve<ICommandHandler>(handlerKey);
+        return handler.handle(command);
+      }
     }
 
-    const container = new Container({ injector: new SimpleInjector() }).addRegistration(
-      R.fromClass(App).bindToKey('App'),
-    );
-    const app = container.resolve<App>('App');
+    const container = new Container({ injector: new SimpleInjector() })
+      .addRegistration(R.fromClass(CommandDispatcher).bindToKey('Dispatcher'))
+      .addRegistration(R.fromClass(CreateUserHandler).bindToKey('HandlerCreateUser'));
+
+    const dispatcher = container.resolve<CommandDispatcher>('Dispatcher');
+    const result = dispatcher.dispatch(new CreateUserCommand('alice'));
 
-    expect(app.container).toBeInstanceOf(Container);
+    expect(result).toBe('User alice created');
   });
 
-  it('should pass parameters alongside with container', function () {
-    class App {
+  it('should pass additional arguments alongside the container', function () {
+    // Factory that creates widgets with a specific theme
+    class WidgetFactory {
       constructor(
-        container: IContainer,
-        public greeting: string,
+        private container: IContainer,
+        private theme: string, // Passed as argument during resolve
       ) {}
+
+      createWidget(name: string): string {
+        return `Widget ${name} with ${this.theme} theme (Container available: ${!!this.container})`;
+      }
     }
 
     const container = new Container({ injector: new SimpleInjector() }).addRegistration(
-      R.fromClass(App).bindToKey('App'),
+      R.fromClass(WidgetFactory).bindToKey('WidgetFactory'),
     );
-    const app = container.resolve<App>('App', { args: ['Hello world'] });
 
-    expect(app.greeting).toBe('Hello world');
+    // Pass "dark" as the theme argument
+    const factory = container.resolve<WidgetFactory>('WidgetFactory', { args: ['dark'] });
+
+    expect(factory.createWidget('Button')).toBe('Widget Button with dark theme (Container available: true)');
   });
 });
 
@@ -438,89 +811,117 @@ describe('SimpleInjector', function () {
 This type of injector injects dependencies as dictionary `Record<string, unknown>`.
 
 ```typescript
-import { args, Container, ProxyInjector, Registration as R } from 'ts-ioc-container';
+import { Container, ProxyInjector, Registration as R } from 'ts-ioc-container';
+
+/**
+ * Clean Architecture - Proxy Injector
+ *
+ * The ProxyInjector injects dependencies as a single object (props/options pattern).
+ * This is popular in modern JavaScript/TypeScript (like React props or destructuring).
+ *
+ * Advantages:
+ * - Named parameters are more readable than positional arguments
+ * - Order of arguments doesn't matter
+ * - Easy to add/remove dependencies without breaking inheritance chains
+ * - Works well with "Clean Architecture" adapters
+ */
 
 describe('ProxyInjector', function () {
-  it('should pass dependency to constructor as dictionary', function () {
-    class Logger {}
+  it('should inject dependencies as a props object', function () {
+    class Logger {
+      log(msg: string) {
+        return `Logged: ${msg}`;
+      }
+    }
 
-    class App {
+    // Dependencies defined as an interface
+    interface UserControllerDeps {
       logger: Logger;
+      prefix: string;
+    }
+
+    // Controller receives all dependencies in a single object
+    class UserController {
+      private logger: Logger;
+      private prefix: string;
 
-      constructor({ logger }: { logger: Logger }) {
+      constructor({ logger, prefix }: UserControllerDeps) {
         this.logger = logger;
+        this.prefix = prefix;
+      }
+
+      createUser(name: string): string {
+        return this.logger.log(`${this.prefix} ${name}`);
       }
     }
 
-    const container = new Container({ injector: new ProxyInjector() }).addRegistration(
-      R.fromClass(Logger).bindToKey('logger'),
-    );
+    const container = new Container({ injector: new ProxyInjector() })
+      .addRegistration(R.fromClass(Logger).bindToKey('logger'))
+      .addRegistration(R.fromValue('USER:').bindToKey('prefix'))
+      .addRegistration(R.fromClass(UserController).bindToKey('UserController'));
 
-    const app = container.resolve(App);
-    expect(app.logger).toBeInstanceOf(Logger);
+    const controller = container.resolve<UserController>('UserController');
+
+    expect(controller.createUser('bob')).toBe('Logged: USER: bob');
   });
 
-  it('should pass arguments as objects', function () {
-    class Logger {}
+  it('should support mixing injected dependencies with runtime arguments', function () {
+    class Database {}
 
-    class App {
-      logger: Logger;
-      greeting: string;
-
-      constructor({
-        logger,
-        greetingTemplate,
-        name,
-      }: {
-        logger: Logger;
-        greetingTemplate: (name: string) => string;
-        name: string;
-      }) {
-        this.logger = logger;
-        this.greeting = greetingTemplate(name);
-      }
+    interface ReportGeneratorDeps {
+      database: Database;
+      format: string; // Runtime argument
     }
 
-    const greetingTemplate = (name: string) => `Hello ${name}`;
+    class ReportGenerator {
+      constructor(public deps: ReportGeneratorDeps) {}
+
+      generate(): string {
+        return `Report in ${this.deps.format}`;
+      }
+    }
 
     const container = new Container({ injector: new ProxyInjector() })
-      .addRegistration(R.fromClass(App).bindToKey('App').pipe(args({ greetingTemplate })))
-      .addRegistration(R.fromClass(Logger).bindToKey('logger'));
+      .addRegistration(R.fromClass(Database).bindToKey('database'))
+      .addRegistration(R.fromClass(ReportGenerator).bindToKey('ReportGenerator'));
+
+    // "format" is passed at resolution time
+    const generator = container.resolve<ReportGenerator>('ReportGenerator', {
+      args: [{ format: 'PDF' }],
+    });
 
-    const app = container.resolve<App>('App', { args: [{ name: `world` }] });
-    expect(app.greeting).toBe('Hello world');
+    expect(generator.deps.database).toBeInstanceOf(Database);
+    expect(generator.generate()).toBe('Report in PDF');
   });
 
-  it('should resolve array dependencies when property name contains "array"', function () {
-    class Logger {}
-    class Service {}
+  it('should resolve array dependencies by alias (convention over configuration)', function () {
+    // If a property is named "loggersArray", it looks for alias "loggersArray"
+    // and resolves it as an array of all matches.
 
-    class App {
-      loggers: Logger[];
-      service: Service;
+    class FileLogger {}
+    class ConsoleLogger {}
 
-      constructor({ loggersArray, service }: { loggersArray: Logger[]; service: Service }) {
-        this.loggers = loggersArray;
-        this.service = service;
-      }
+    interface AppDeps {
+      loggersArray: any[]; // Injected as array of all loggers
     }
 
-    // Mock container's resolveByAlias to return an array with a Logger instance
-    const mockLogger = new Logger();
-    const mockContainer = new Container({ injector: new ProxyInjector() });
-    mockContainer.resolveByAlias = jest.fn().mockImplementation((key) => {
-      // Always return the mock array for simplicity
-      return [mockLogger];
-    });
-    mockContainer.addRegistration(R.fromClass(Service).bindToKey('service'));
-
-    const app = mockContainer.resolve(App);
-    expect(app.loggers).toBeInstanceOf(Array);
-    expect(app.loggers.length).toBe(1);
-    expect(app.loggers[0]).toBe(mockLogger);
-    expect(app.service).toBeInstanceOf(Service);
-    // Verify that resolveByAlias was called with the correct key
-    expect(mockContainer.resolveByAlias).toHaveBeenCalledWith('loggersArray');
+    class App {
+      constructor(public deps: AppDeps) {}
+    }
+
+    const container = new Container({ injector: new ProxyInjector() });
+
+    // Mocking the behavior for this specific test as ProxyInjector uses resolveByAlias
+    // which delegates to the container.
+    // In a real scenario, you'd register multiple loggers with the same alias.
+    const mockLoggers = [new FileLogger(), new ConsoleLogger()];
+
+    container.resolveByAlias = jest.fn().mockReturnValue(mockLoggers);
+
+    const app = container.resolve(App);
+
+    expect(app.deps.loggersArray).toBe(mockLoggers);
+    expect(container.resolveByAlias).toHaveBeenCalledWith('loggersArray');
   });
 });
 
@@ -539,270 +940,138 @@ import {
   argsFn,
   bindTo,
   Container,
-  inject,
   lazy,
   Provider,
   register,
   Registration as R,
   scopeAccess,
-  select as s,
   singleton,
 } from 'ts-ioc-container';
 
-class Logger {}
-
-class ConfigService {
-  constructor(private readonly configPath: string) {}
-
-  getPath(): string {
-    return this.configPath;
-  }
-}
-
-class UserService {}
+/**
+ * Data Processing Pipeline - Provider Patterns
+ *
+ * Providers are the recipes for creating objects. This suite demonstrates
+ * how to customize object creation for a Data Processing Pipeline.
+ *
+ * Scenarios:
+ * - FileProcessor: Created as a class instance
+ * - Config: Created from a simple value object
+ * - BatchProcessor: Singleton to coordinate across the app
+ * - StreamProcessor: Lazy loaded only when needed
+ */
 
-class TestClass {}
-
-class ClassWithoutTransformers {}
+class Logger {}
 
 describe('Provider', () => {
-  it('can be registered as a function', () => {
+  it('can be registered as a function (Factory Pattern)', () => {
+    // dynamic factory
     const container = new Container().register('ILogger', new Provider(() => new Logger()));
     expect(container.resolve('ILogger')).not.toBe(container.resolve('ILogger'));
   });
 
-  it('can be registered as a value', () => {
-    const container = new Container().register('ILogger', Provider.fromValue(new Logger()));
-    expect(container.resolve('ILogger')).toBe(container.resolve('ILogger'));
+  it('can be registered as a value (Config Pattern)', () => {
+    // constant value
+    const config = { maxRetries: 3 };
+    const container = new Container().register('Config', Provider.fromValue(config));
+    expect(container.resolve('Config')).toBe(config);
   });
 
-  it('can be registered as a class', () => {
+  it('can be registered as a class (Standard Pattern)', () => {
     const container = new Container().register('ILogger', Provider.fromClass(Logger));
-    expect(container.resolve('ILogger')).not.toBe(container.resolve('ILogger'));
+    expect(container.resolve('ILogger')).toBeInstanceOf(Logger);
   });
 
-  it('can be featured by pipe method', () => {
-    const root = new Container({ tags: ['root'] }).register('ILogger', Provider.fromClass(Logger).pipe(singleton()));
-    expect(root.resolve('ILogger')).toBe(root.resolve('ILogger'));
+  it('can be featured by fp method (Singleton Pattern)', () => {
+    // Pipe "singleton()" to cache the instance
+    const appContainer = new Container({ tags: ['application'] }).register(
+      'SharedLogger',
+      Provider.fromClass(Logger).pipe(singleton()),
+    );
+    expect(appContainer.resolve('SharedLogger')).toBe(appContainer.resolve('SharedLogger'));
   });
 
-  it('can be created from a dependency key', () => {
+  it('can be created from a dependency key (Alias/Redirect Pattern)', () => {
+    // "LoggerAlias" redirects to "ILogger"
     const container = new Container()
       .register('ILogger', Provider.fromClass(Logger))
       .register('LoggerAlias', Provider.fromKey('ILogger'));
-    const logger1 = container.resolve('ILogger');
-    const logger2 = container.resolve('LoggerAlias');
-    expect(logger2).toBeInstanceOf(Logger);
-    expect(logger2).not.toBe(logger1);
+
+    const logger = container.resolve('LoggerAlias');
+    expect(logger).toBeInstanceOf(Logger);
   });
 
-  it('supports lazy resolution', () => {
+  it('supports lazy resolution (Performance Optimization)', () => {
+    // Logger is not created until accessed
     const container = new Container().register('ILogger', Provider.fromClass(Logger));
     const lazyLogger = container.resolve('ILogger', { lazy: true });
+
+    // It's a proxy, not the real instance yet
     expect(typeof lazyLogger).toBe('object');
-    const loggerPrototype = Object.getPrototypeOf(lazyLogger);
-    expect(loggerPrototype).toBeDefined();
+    // Accessing it would trigger creation
   });
 
   it('supports args decorator for providing extra arguments', () => {
-    const container = new Container().register(
-      'ConfigService',
-      Provider.fromClass(ConfigService).pipe(args('/etc/config.json')),
-    );
-    const config = container.resolve<ConfigService>('ConfigService');
-    expect(config.getPath()).toBe('/etc/config.json');
-  });
+    class FileService {
+      constructor(readonly basePath: string) {}
+    }
 
-  it('supports argsFn decorator for dynamic arguments', () => {
-    const container = new Container()
-      .register('Logger', Provider.fromClass(Logger))
-      .register(
-        'ConfigService',
-        Provider.fromClass(ConfigService).pipe(argsFn((container) => ['/dynamic/config.json'])),
-      );
-    const config = container.resolve<ConfigService>('ConfigService');
-    expect(config.getPath()).toBe('/dynamic/config.json');
-  });
+    const container = new Container().register('FileService', Provider.fromClass(FileService).pipe(args('/var/data')));
 
-  it('combines args from argsFn with manually provided args', () => {
-    const container = new Container()
-      .register('Logger', Provider.fromClass(Logger))
-      .register(
-        'UserService',
-        Provider.fromClass(UserService).pipe(argsFn((container) => [container.resolve('Logger')])),
-      );
-    const configService = new ConfigService('/test/config.json');
-    const userService = container.resolve<UserService>('UserService', { args: [configService] });
-    expect(userService).toBeInstanceOf(UserService);
+    const service = container.resolve<FileService>('FileService');
+    expect(service.basePath).toBe('/var/data');
   });
 
-  it('supports visibility control between parent and child containers', () => {
-    const rootContainer = new Container({ tags: ['root'] }).register(
-      'ILogger',
-      Provider.fromClass(Logger).pipe(
-        scopeAccess(({ invocationScope, providerScope }) => invocationScope.hasTag('admin')),
-      ),
-    );
-    const adminChild = rootContainer.createScope({ tags: ['admin'] });
-    const userChild = rootContainer.createScope({ tags: ['user'] });
-    expect(() => adminChild.resolve('ILogger')).not.toThrow();
-    expect(() => userChild.resolve('ILogger')).toThrow();
-  });
+  it('supports argsFn decorator for dynamic arguments', () => {
+    class Database {
+      constructor(readonly connectionString: string) {}
+    }
 
-  it('supports chaining multiple pipe transformations', () => {
-    const container = new Container().register(
-      'ConfigService',
-      Provider.fromClass(ConfigService).pipe(args('/default/config.json'), singleton()),
+    const container = new Container().register('DbPath', Provider.fromValue('localhost:5432')).register(
+      'Database',
+      Provider.fromClass(Database).pipe(
+        // Dynamically resolve connection string at creation time
+        argsFn((scope) => [`postgres://${scope.resolve('DbPath')}`]),
+      ),
     );
-    const config1 = container.resolve<ConfigService>('ConfigService');
-    const config2 = container.resolve<ConfigService>('ConfigService');
-    expect(config1).toBe(config2);
-    expect(config1.getPath()).toBe('/default/config.json');
-  });
-
-  it('applies transformers when registering a class constructor as a value', () => {
-    const container = new Container()
-      .register('ClassConstructor', Provider.fromValue(TestClass))
-      .register('ClassInstance', Provider.fromClass(TestClass));
-    const instance1 = container.resolve('ClassConstructor');
-    const instance2 = container.resolve('ClassConstructor');
-    const instance3 = container.resolve('ClassInstance');
-    expect(instance1).toBe(TestClass);
-    expect(instance2).toBe(TestClass);
-    expect(instance3).toBeInstanceOf(TestClass);
-  });
 
-  it('handles primitive values in Provider.fromValue', () => {
-    const container = new Container()
-      .register('StringValue', Provider.fromValue('test-string'))
-      .register('NumberValue', Provider.fromValue(42))
-      .register('BooleanValue', Provider.fromValue(true))
-      .register('ObjectValue', Provider.fromValue({ key: 'value' }));
-    expect(container.resolve('StringValue')).toBe('test-string');
-    expect(container.resolve('NumberValue')).toBe(42);
-    expect(container.resolve('BooleanValue')).toBe(true);
-    expect(container.resolve('ObjectValue')).toEqual({ key: 'value' });
+    const db = container.resolve<Database>('Database');
+    expect(db.connectionString).toBe('postgres://localhost:5432');
   });
 
-  it('resolves dependencies with empty args', () => {
-    const container = new Container().register('Logger', Provider.fromClass(Logger));
-    const logger = container.resolve('Logger', { args: [] });
-    expect(logger).toBeInstanceOf(Logger);
-  });
+  it('supports visibility control (Security Pattern)', () => {
+    // AdminService only visible in admin scope
+    class AdminService {}
 
-  it('allows direct manipulation of visibility predicate', () => {
-    const provider = Provider.fromClass(Logger);
-    provider.setAccessRule(({ invocationScope }) => invocationScope.hasTag('special'));
-    const container = new Container({ tags: ['root'] }).register('Logger', provider);
-    const specialChild = container.createScope({ tags: ['special'] });
-    const regularChild = container.createScope({ tags: ['regular'] });
-    expect(() => specialChild.resolve('Logger')).not.toThrow();
-    expect(() => regularChild.resolve('Logger')).toThrow();
-  });
+    const appContainer = new Container({ tags: ['application'] }).register(
+      'AdminService',
+      Provider.fromClass(AdminService).pipe(scopeAccess(({ invocationScope }) => invocationScope.hasTag('admin'))),
+    );
 
-  it('allows direct manipulation of args function', () => {
-    const provider = Provider.fromClass(ConfigService);
-    provider.setArgs(() => ['/custom/path.json']);
-    const container = new Container().register('ConfigService', provider);
-    const config = container.resolve<ConfigService>('ConfigService');
-    expect(config.getPath()).toBe('/custom/path.json');
-  });
+    const adminScope = appContainer.createScope({ tags: ['admin'] });
+    const publicScope = appContainer.createScope({ tags: ['public'] });
 
-  it('handles class constructors when getTransformers returns null', () => {
-    const container = new Container().register('NoTransformers', Provider.fromValue(ClassWithoutTransformers));
-    const result = container.resolve('NoTransformers');
-    expect(result).toBe(ClassWithoutTransformers);
+    expect(() => adminScope.resolve('AdminService')).not.toThrow();
+    expect(() => publicScope.resolve('AdminService')).toThrow();
   });
 
-  it('allows to register lazy provider', () => {
-    let isLoggerCreated = false;
-
-    @register(bindTo('Logger'), lazy())
-    class Logger {
-      private logs: string[] = [];
+  it('allows to register lazy provider via decorator', () => {
+    let created = false;
 
+    @register(bindTo('HeavyService'), lazy())
+    class HeavyService {
       constructor() {
-        isLoggerCreated = true;
-      }
-
-      info(message: string, context: Record<string, unknown>): void {
-        this.logs.push(JSON.stringify({ ...context, level: 'info', message }));
-      }
-
-      serialize(): string {
-        return this.logs.join('\n');
+        created = true;
       }
+      doWork() {}
     }
 
-    class Main {
-      constructor(@inject('Logger') private logger: Logger) {}
+    const container = new Container().addRegistration(R.fromClass(HeavyService));
+    const service = container.resolve<HeavyService>('HeavyService');
 
-      getLogs(): string {
-        return this.logger.serialize();
-      }
-    }
-
-    const root = new Container({ tags: ['root'] }).addRegistration(R.fromClass(Logger));
-    const main = root.resolve(Main);
-
-    expect(isLoggerCreated).toBe(false);
-
-    main.getLogs();
-
-    expect(isLoggerCreated).toBe(true);
-  });
-
-  it('allows to resolve with args', () => {
-    @register(bindTo('ILogger'))
-    class Logger {
-      readonly channel: string;
-
-      constructor(options: { channel: string }) {
-        this.channel = options.channel;
-      }
-    }
-
-    class Main {
-      constructor(@inject(s.token('ILogger').args({ channel: 'file' })) private logger: Logger) {}
-
-      getChannel(): string {
-        return this.logger.channel;
-      }
-    }
-
-    const root = new Container({ tags: ['root'] }).addRegistration(R.fromClass(Logger));
-    const main = root.resolve(Main);
-
-    expect(main.getChannel()).toBe('file');
-  });
-
-  it('allows to resolve with argsFn', () => {
-    @register(bindTo('ILogger'))
-    class Logger {
-      readonly channel: string;
-
-      constructor(options: { channel: string }) {
-        this.channel = options.channel;
-      }
-    }
-
-    class Main {
-      constructor(
-        @inject(s.token('ILogger').argsFn((s) => [{ channel: s.resolve('channel') }])) private logger: Logger,
-      ) {}
-
-      getChannel(): string {
-        return this.logger.channel;
-      }
-    }
-
-    const root = new Container({ tags: ['root'] })
-      .addRegistration(R.fromValue('file').bindToKey('channel'))
-      .addRegistration(R.fromClass(Logger));
-
-    const main = root.resolve(Main);
-
-    expect(main.getChannel()).toBe('file');
+    expect(created).toBe(false); // Not created yet
+    service.doWork(); // Access triggers creation
+    expect(created).toBe(true);
   });
 });
 
@@ -815,34 +1084,84 @@ Sometimes you need to create only one instance of dependency per scope. For exam
 - NOTICE: if you create a scope 'A' of container 'root' then Logger of A !== Logger of root.
 
 ```typescript
+import 'reflect-metadata';
 import { bindTo, Container, register, Registration as R, singleton } from 'ts-ioc-container';
 
-@register(bindTo('logger'), singleton())
-class Logger {}
+/**
+ * User Management Domain - Singleton Pattern
+ *
+ * Singletons are services that should only have one instance per scope.
+ * Common examples:
+ * - PasswordHasher: Expensive to initialize (loads crypto config)
+ * - DatabasePool: Connection pool shared across requests
+ * - ConfigService: Application configuration loaded once
+ *
+ * Note: "singleton" in ts-ioc-container means "one instance per scope",
+ * not "one instance globally". Each scope gets its own singleton instance.
+ */
+
+// PasswordHasher is expensive to create - should be singleton
+@register(bindTo('IPasswordHasher'), singleton())
+class PasswordHasher {
+  private readonly salt: string;
+
+  constructor() {
+    // Simulate expensive initialization (loading crypto config, etc.)
+    this.salt = 'random_salt_' + Math.random().toString(36);
+  }
+
+  hash(password: string): string {
+    return `hashed_${password}_${this.salt}`;
+  }
+
+  verify(password: string, hash: string): boolean {
+    return this.hash(password) === hash;
+  }
+}
 
 describe('Singleton', function () {
-  function createContainer() {
-    return new Container();
+  function createAppContainer() {
+    return new Container({ tags: ['application'] });
   }
 
-  it('should resolve the same container per every request', function () {
-    const container = createContainer().addRegistration(R.fromClass(Logger));
+  it('should resolve the same PasswordHasher for every request in same scope', function () {
+    const appContainer = createAppContainer().addRegistration(R.fromClass(PasswordHasher));
 
-    expect(container.resolve('logger')).toBe(container.resolve('logger'));
+    // Multiple resolves return the same instance
+    const hasher1 = appContainer.resolve<PasswordHasher>('IPasswordHasher');
+    const hasher2 = appContainer.resolve<PasswordHasher>('IPasswordHasher');
+
+    expect(hasher1).toBe(hasher2);
+    expect(hasher1.hash('password')).toBe(hasher2.hash('password'));
   });
 
-  it('should resolve different dependency per scope', function () {
-    const container = createContainer().addRegistration(R.fromClass(Logger));
-    const child = container.createScope();
+  it('should create different singleton per request scope', function () {
+    // Application-level singleton
+    const appContainer = createAppContainer().addRegistration(R.fromClass(PasswordHasher));
+
+    // Each request scope gets its own singleton instance
+    // This is useful when you want per-request caching
+    const request1 = appContainer.createScope({ tags: ['request'] });
+    const request2 = appContainer.createScope({ tags: ['request'] });
+
+    const appHasher = appContainer.resolve<PasswordHasher>('IPasswordHasher');
+    const request1Hasher = request1.resolve<PasswordHasher>('IPasswordHasher');
+    const request2Hasher = request2.resolve<PasswordHasher>('IPasswordHasher');
 
-    expect(container.resolve('logger')).not.toBe(child.resolve('logger'));
+    // Each scope has its own instance
+    expect(appHasher).not.toBe(request1Hasher);
+    expect(request1Hasher).not.toBe(request2Hasher);
   });
 
-  it('should resolve the same dependency for scope', function () {
-    const container = createContainer().addRegistration(R.fromClass(Logger));
-    const child = container.createScope();
+  it('should maintain singleton within a scope', function () {
+    const appContainer = createAppContainer().addRegistration(R.fromClass(PasswordHasher));
+    const requestScope = appContainer.createScope({ tags: ['request'] });
 
-    expect(child.resolve('logger')).toBe(child.resolve('logger'));
+    // Within the same scope, singleton is maintained
+    const hasher1 = requestScope.resolve<PasswordHasher>('IPasswordHasher');
+    const hasher2 = requestScope.resolve<PasswordHasher>('IPasswordHasher');
+
+    expect(hasher1).toBe(hasher2);
   });
 });
 
@@ -861,146 +1180,163 @@ import {
   argsFn,
   bindTo,
   Container,
-  SingleToken,
   inject,
   MultiCache,
   register,
   Registration as R,
   resolveByArgs,
   singleton,
+  SingleToken,
 } from 'ts-ioc-container';
 
-@register(bindTo('logger'))
-class Logger {
-  constructor(
-    public name: string,
-    public type?: string,
-  ) {}
-}
+/**
+ * Advanced - Arguments Provider
+ *
+ * You can inject arguments into providers at registration time or resolution time.
+ * This is powerful for:
+ * - Configuration injection
+ * - Factory patterns
+ * - Generic classes (like Repositories) that need to know what they are managing
+ */
 
 describe('ArgsProvider', function () {
   function createContainer() {
     return new Container();
   }
 
-  it('can assign argument function to provider', function () {
-    const root = createContainer().addRegistration(R.fromClass(Logger).pipe(argsFn(() => ['name'])));
+  describe('Static Arguments', () => {
+    it('can pass static arguments to constructor', function () {
+      class FileLogger {
+        constructor(public filename: string) {}
+      }
 
-    const logger = root.createScope().resolve<Logger>('logger');
-    expect(logger.name).toBe('name');
-  });
+      // Pre-configure the logger with a filename
+      const root = createContainer().addRegistration(R.fromClass(FileLogger).pipe(args('/var/log/app.log')));
+
+      // Resolve by class name (default key) to use the registered provider
+      const logger = root.resolve<FileLogger>('FileLogger');
+      expect(logger.filename).toBe('/var/log/app.log');
+    });
+
+    it('prioritizes provided args over resolve args', function () {
+      class Logger {
+        constructor(public context: string) {}
+      }
 
-  it('can assign argument to provider', function () {
-    const root = createContainer().addRegistration(R.fromClass(Logger).pipe(args('name')));
+      // 'FixedContext' wins over any runtime args
+      const root = createContainer().addRegistration(R.fromClass(Logger).pipe(args('FixedContext')));
 
-    const logger = root.resolve<Logger>('logger');
-    expect(logger.name).toBe('name');
+      // Even if we ask for 'RuntimeContext', we get 'FixedContext'
+      // Resolve by class name to use the registered provider
+      const logger = root.resolve<Logger>('Logger', { args: ['RuntimeContext'] });
+
+      expect(logger.context).toBe('FixedContext');
+    });
   });
 
-  it('should set provider arguments with highest priority in compare to resolve arguments', function () {
-    const root = createContainer().addRegistration(R.fromClass(Logger).pipe(args('name')));
+  describe('Dynamic Arguments (Factory)', () => {
+    it('can resolve arguments dynamically from container', function () {
+      class Config {
+        env = 'production';
+      }
 
-    const logger = root.resolve<Logger>('logger', { args: ['file'] });
+      class Service {
+        constructor(public env: string) {}
+      }
 
-    expect(logger.name).toBe('name');
-    expect(logger.type).toBe('file');
+      const root = createContainer()
+        .addRegistration(R.fromClass(Config)) // Key: 'Config'
+        .addRegistration(
+          R.fromClass(Service).pipe(
+            // Extract 'env' from Config service dynamically
+            // Note: We resolve 'Config' by string key to get the registered instance (if it were singleton)
+            argsFn((scope) => [scope.resolve<Config>('Config').env]),
+          ),
+        );
+
+      const service = root.resolve<Service>('Service');
+      expect(service.env).toBe('production');
+    });
   });
 
-  it('should resolve dependency by passing arguments resolve from container by another argument', function () {
+  describe('Generic Repositories (Advanced Pattern)', () => {
+    // This example demonstrates how to implement the Generic Repository pattern
+    // where a generic EntityManager needs to know WHICH repository to use.
+
     interface IRepository {
       name: string;
     }
 
-    const IUserRepositoryKey = new SingleToken<IRepository>('IUserRepository');
-    const ITodoRepositoryKey = new SingleToken<IRepository>('ITodoRepository');
+    // Tokens for specific repository types
+    const UserRepositoryToken = new SingleToken<IRepository>('UserRepository');
+    const TodoRepositoryToken = new SingleToken<IRepository>('TodoRepository');
 
-    @register(bindTo(IUserRepositoryKey))
+    @register(bindTo(UserRepositoryToken))
     class UserRepository implements IRepository {
       name = 'UserRepository';
     }
 
-    @register(bindTo(ITodoRepositoryKey))
+    @register(bindTo(TodoRepositoryToken))
     class TodoRepository implements IRepository {
       name = 'TodoRepository';
     }
 
-    interface IEntityManager {
-      repository: IRepository;
-    }
-
-    const IEntityManagerKey = new SingleToken<IEntityManager>('IEntityManager');
+    // EntityManager is generic - it works with ANY repository
+    // We use argsFn(resolveByArgs) to tell it to look at the arguments passed to .args()
+    const EntityManagerToken = new SingleToken<EntityManager>('EntityManager');
 
-    @register(bindTo(IEntityManagerKey), argsFn(resolveByArgs))
+    @register(
+      bindTo(EntityManagerToken),
+      argsFn(resolveByArgs), // <--- Key magic: resolves dependencies based on arguments passed to token
+      singleton(MultiCache.fromFirstArg), // Cache unique instance per repository type
+    )
     class EntityManager {
       constructor(public repository: IRepository) {}
     }
 
-    class Main {
+    class App {
       constructor(
-        @inject(IEntityManagerKey.args(IUserRepositoryKey)) public userEntities: EntityManager,
-        @inject(IEntityManagerKey.args(ITodoRepositoryKey)) public todoEntities: EntityManager,
-      ) {}
-    }
-
-    const root = createContainer()
-      .addRegistration(R.fromClass(EntityManager))
-      .addRegistration(R.fromClass(UserRepository))
-      .addRegistration(R.fromClass(TodoRepository));
-    const main = root.resolve(Main);
-
-    expect(main.userEntities.repository).toBeInstanceOf(UserRepository);
-    expect(main.todoEntities.repository).toBeInstanceOf(TodoRepository);
-  });
-
-  it('should resolve memoized dependency by passing arguments resolve from container by another argument', function () {
-    interface IRepository {
-      name: string;
-    }
-
-    const IUserRepositoryKey = new SingleToken<IRepository>('IUserRepository');
-    const ITodoRepositoryKey = new SingleToken<IRepository>('ITodoRepository');
+        // Inject EntityManager configured for Users
+        @inject(EntityManagerToken.args(UserRepositoryToken))
+        public userManager: EntityManager,
 
-    @register(bindTo(IUserRepositoryKey))
-    class UserRepository implements IRepository {
-      name = 'UserRepository';
+        // Inject EntityManager configured for Todos
+        @inject(EntityManagerToken.args(TodoRepositoryToken))
+        public todoManager: EntityManager,
+      ) {}
     }
 
-    @register(bindTo(ITodoRepositoryKey))
-    class TodoRepository implements IRepository {
-      name = 'TodoRepository';
-    }
+    it('should create specialized instances based on token arguments', function () {
+      const root = createContainer()
+        .addRegistration(R.fromClass(EntityManager))
+        .addRegistration(R.fromClass(UserRepository))
+        .addRegistration(R.fromClass(TodoRepository));
 
-    interface IEntityManager {
-      repository: IRepository;
-    }
+      const app = root.resolve(App);
 
-    const IEntityManagerKey = new SingleToken<IEntityManager>('IEntityManager');
+      expect(app.userManager.repository).toBeInstanceOf(UserRepository);
+      expect(app.todoManager.repository).toBeInstanceOf(TodoRepository);
+    });
 
-    @register(bindTo(IEntityManagerKey), argsFn(resolveByArgs), singleton(MultiCache.fromFirstArg))
-    class EntityManager {
-      constructor(public repository: IRepository) {}
-    }
+    it('should cache specialized instances separately', function () {
+      const root = createContainer()
+        .addRegistration(R.fromClass(EntityManager))
+        .addRegistration(R.fromClass(UserRepository))
+        .addRegistration(R.fromClass(TodoRepository));
 
-    class Main {
-      constructor(
-        @inject(IEntityManagerKey.args(IUserRepositoryKey)) public userEntities: EntityManager,
-        @inject(IEntityManagerKey.args(ITodoRepositoryKey)) public todoEntities: EntityManager,
-      ) {}
-    }
+      // Resolve user manager twice
+      const userManager1 = EntityManagerToken.args(UserRepositoryToken).resolve(root);
+      const userManager2 = EntityManagerToken.args(UserRepositoryToken).resolve(root);
 
-    const root = createContainer()
-      .addRegistration(R.fromClass(EntityManager))
-      .addRegistration(R.fromClass(UserRepository))
-      .addRegistration(R.fromClass(TodoRepository));
-    const main = root.resolve(Main);
+      // Should be same instance (cached)
+      expect(userManager1).toBe(userManager2);
 
-    const userRepository = IEntityManagerKey.args(IUserRepositoryKey).resolve(root).repository;
-    expect(userRepository).toBeInstanceOf(UserRepository);
-    expect(main.userEntities.repository).toBe(userRepository);
+      // Resolve todo manager
+      const todoManager = EntityManagerToken.args(TodoRepositoryToken).resolve(root);
 
-    const todoRepository = IEntityManagerKey.args(ITodoRepositoryKey).resolve(root).repository;
-    expect(todoRepository).toBeInstanceOf(TodoRepository);
-    expect(main.todoEntities.repository).toBe(todoRepository);
+      // Should be different from user manager
+      expect(todoManager).not.toBe(userManager1);
+    });
   });
 });
 
@@ -1012,6 +1348,7 @@ Sometimes you want to hide dependency if somebody wants to resolve it from certa
 - `Provider.fromClass(Logger).pipe(scopeAccess(({ invocationScope, providerScope }) => invocationScope === providerScope))`
 
 ```typescript
+import 'reflect-metadata';
 import {
   bindTo,
   Container,
@@ -1023,22 +1360,79 @@ import {
   singleton,
 } from 'ts-ioc-container';
 
+/**
+ * User Management Domain - Visibility Control
+ *
+ * Some services should only be accessible in specific scopes:
+ * - AdminService: Only accessible in admin routes
+ * - AuditLogger: Only accessible at application level (not per-request)
+ * - DebugService: Only accessible in development environment
+ *
+ * scopeAccess() controls VISIBILITY - whether a registered service
+ * can be resolved from a particular scope.
+ *
+ * This provides security-by-design:
+ * - Prevents accidental access to sensitive services
+ * - Enforces architectural boundaries
+ * - Catches misuse at resolution time (not runtime)
+ */
 describe('Visibility', function () {
-  it('should hide from children', () => {
+  it('should restrict admin services to admin routes only', () => {
+    // UserManagementService can delete users - admin only!
     @register(
-      bindTo('logger'),
-      scope((s) => s.hasTag('root')),
+      bindTo('IUserManagement'),
+      scope((s) => s.hasTag('application')), // Registered at app level
       singleton(),
+      // Only accessible from admin scope, not regular request scope
+      scopeAccess(({ invocationScope }) => invocationScope.hasTag('admin')),
+    )
+    class UserManagementService {
+      deleteUser(userId: string): string {
+        return `Deleted user ${userId}`;
+      }
+    }
+
+    const appContainer = new Container({ tags: ['application'] }).addRegistration(R.fromClass(UserManagementService));
+
+    // Admin route scope
+    const adminScope = appContainer.createScope({ tags: ['request', 'admin'] });
+
+    // Regular user route scope
+    const userScope = appContainer.createScope({ tags: ['request', 'user'] });
+
+    // Admin can access UserManagementService
+    const adminService = adminScope.resolve<UserManagementService>('IUserManagement');
+    expect(adminService.deleteUser('user-123')).toBe('Deleted user user-123');
+
+    // Regular users cannot access it - security enforced at DI level
+    expect(() => userScope.resolve('IUserManagement')).toThrowError(DependencyNotFoundError);
+  });
+
+  it('should restrict application-level services from request scope', () => {
+    // AuditLogger should only be used at application initialization
+    // Not from request handlers (to prevent log corruption from concurrent access)
+    @register(
+      bindTo('IAuditLogger'),
+      scope((s) => s.hasTag('application')),
+      singleton(),
+      // Only accessible from the scope where it was registered
       scopeAccess(({ invocationScope, providerScope }) => invocationScope === providerScope),
     )
-    class FileLogger {}
+    class AuditLogger {
+      log(message: string): string {
+        return `AUDIT: ${message}`;
+      }
+    }
 
-    const parent = new Container({ tags: ['root'] }).addRegistration(R.fromClass(FileLogger));
+    const appContainer = new Container({ tags: ['application'] }).addRegistration(R.fromClass(AuditLogger));
 
-    const child = parent.createScope({ tags: ['child'] });
+    const requestScope = appContainer.createScope({ tags: ['request'] });
 
-    expect(() => child.resolve('logger')).toThrowError(DependencyNotFoundError);
-    expect(parent.resolve('logger')).toBeInstanceOf(FileLogger);
+    // Application can use AuditLogger (for startup logging)
+    expect(appContainer.resolve<AuditLogger>('IAuditLogger').log('App started')).toBe('AUDIT: App started');
+
+    // Request handlers cannot access it directly
+    expect(() => requestScope.resolve('IAuditLogger')).toThrowError(DependencyNotFoundError);
   });
 });
 
@@ -1051,6 +1445,7 @@ Alias is needed to group keys
 - `Provider.fromClass(Logger).pipe(alias('logger'))`
 
 ```typescript
+import 'reflect-metadata';
 import {
   bindTo,
   Container,
@@ -1062,95 +1457,127 @@ import {
   select as s,
 } from 'ts-ioc-container';
 
+/**
+ * User Management Domain - Alias Pattern (Multiple Implementations)
+ *
+ * Aliases allow multiple services to be registered under the same key.
+ * This is useful for:
+ * - Plugin systems (multiple notification channels)
+ * - Strategy pattern (multiple authentication providers)
+ * - Event handlers (multiple listeners for same event)
+ *
+ * Example: NotificationService with Email, SMS, and Push implementations
+ */
 describe('alias', () => {
-  const IMiddlewareKey = 'IMiddleware';
-  const middleware = register(bindTo(s.alias(IMiddlewareKey)));
+  // All notification services share this alias
+  const INotificationChannel = 'INotificationChannel';
+  const notificationChannel = register(bindTo(s.alias(INotificationChannel)));
 
-  interface IMiddleware {
-    applyTo(application: IApplication): void;
+  interface INotificationChannel {
+    send(userId: string, message: string): void;
+    getDeliveredMessages(): string[];
   }
 
-  interface IApplication {
-    use(module: IMiddleware): void;
-    markMiddlewareAsApplied(name: string): void;
-  }
+  // Email notification - always available
+  @notificationChannel
+  class EmailNotifier implements INotificationChannel {
+    private delivered: string[] = [];
 
-  @middleware
-  class LoggerMiddleware implements IMiddleware {
-    applyTo(application: IApplication): void {
-      application.markMiddlewareAsApplied('LoggerMiddleware');
+    send(userId: string, message: string): void {
+      this.delivered.push(`EMAIL to ${userId}: ${message}`);
     }
-  }
 
-  @middleware
-  class ErrorHandlerMiddleware implements IMiddleware {
-    applyTo(application: IApplication): void {
-      application.markMiddlewareAsApplied('ErrorHandlerMiddleware');
+    getDeliveredMessages(): string[] {
+      return this.delivered;
     }
   }
 
-  it('should resolve by some alias', () => {
-    class App implements IApplication {
-      private appliedMiddleware: Set<string> = new Set();
-      constructor(@inject(s.alias(IMiddlewareKey)) public middleware: IMiddleware[]) {}
+  // SMS notification - for urgent messages
+  @notificationChannel
+  class SmsNotifier implements INotificationChannel {
+    private delivered: string[] = [];
 
-      markMiddlewareAsApplied(name: string): void {
-        this.appliedMiddleware.add(name);
-      }
+    send(userId: string, message: string): void {
+      this.delivered.push(`SMS to ${userId}: ${message}`);
+    }
 
-      isMiddlewareApplied(name: string): boolean {
-        return this.appliedMiddleware.has(name);
-      }
+    getDeliveredMessages(): string[] {
+      return this.delivered;
+    }
+  }
 
-      use(module: IMiddleware): void {
-        module.applyTo(this);
-      }
+  it('should notify through all channels', () => {
+    // NotificationManager broadcasts to ALL registered channels
+    class NotificationManager {
+      constructor(@inject(s.alias(INotificationChannel)) private channels: INotificationChannel[]) {}
 
-      run() {
-        for (const module of this.middleware) {
-          module.applyTo(this);
+      notifyUser(userId: string, message: string): void {
+        for (const channel of this.channels) {
+          channel.send(userId, message);
         }
       }
+
+      getChannelCount(): number {
+        return this.channels.length;
+      }
     }
 
     const container = new Container()
-      .addRegistration(R.fromClass(LoggerMiddleware))
-      .addRegistration(R.fromClass(ErrorHandlerMiddleware));
+      .addRegistration(R.fromClass(EmailNotifier))
+      .addRegistration(R.fromClass(SmsNotifier));
 
-    const app = container.resolve(App);
-    app.run();
+    const manager = container.resolve(NotificationManager);
+    manager.notifyUser('user-123', 'Your password was reset');
 
-    expect(app.isMiddlewareApplied('LoggerMiddleware')).toBe(true);
-    expect(app.isMiddlewareApplied('ErrorHandlerMiddleware')).toBe(true);
+    // Both channels received the message
+    expect(manager.getChannelCount()).toBe(2);
   });
 
-  it('should resolve by some alias', () => {
-    @register(bindTo(s.alias('ILogger')))
-    class FileLogger {}
+  it('should resolve single implementation by alias', () => {
+    // Sometimes you only need one implementation (e.g., primary email service)
+    @register(bindTo(s.alias('IPrimaryNotifier')))
+    class PrimaryEmailNotifier {
+      readonly type = 'email';
+    }
 
-    const container = new Container().addRegistration(R.fromClass(FileLogger));
+    const container = new Container().addRegistration(R.fromClass(PrimaryEmailNotifier));
 
-    expect(container.resolveOneByAlias('ILogger')).toBeInstanceOf(FileLogger);
-    expect(() => container.resolve('logger')).toThrowError(DependencyNotFoundError);
+    // resolveOneByAlias returns first matching implementation
+    const notifier = container.resolveOneByAlias<PrimaryEmailNotifier>('IPrimaryNotifier');
+    expect(notifier.type).toBe('email');
+
+    // Direct key resolution fails - only alias is registered
+    expect(() => container.resolve('IPrimaryNotifier')).toThrowError(DependencyNotFoundError);
   });
 
-  it('should resolve by alias', () => {
-    @register(bindTo(s.alias('ILogger')), scope((s) => s.hasTag('root')))
-    class FileLogger {}
+  it('should use different implementations per scope', () => {
+    // Development: Console logger for easy debugging
+    @register(bindTo(s.alias('ILogger')), scope((s) => s.hasTag('development')))
+    class ConsoleLogger {
+      readonly type = 'console';
+    }
 
-    @register(bindTo(s.alias('ILogger')), scope((s) => s.hasTag('child')))
-    class DbLogger {}
+    // Production: Database logger for audit trail
+    @register(bindTo(s.alias('ILogger')), scope((s) => s.hasTag('production')))
+    class DatabaseLogger {
+      readonly type = 'database';
+    }
+
+    // Development environment
+    const devContainer = new Container({ tags: ['development'] })
+      .addRegistration(R.fromClass(ConsoleLogger))
+      .addRegistration(R.fromClass(DatabaseLogger));
 
-    const container = new Container({ tags: ['root'] })
-      .addRegistration(R.fromClass(FileLogger))
-      .addRegistration(R.fromClass(DbLogger));
+    // Production environment
+    const prodContainer = new Container({ tags: ['production'] })
+      .addRegistration(R.fromClass(ConsoleLogger))
+      .addRegistration(R.fromClass(DatabaseLogger));
 
-    const result1 = container.resolveOneByAlias('ILogger');
-    const child = container.createScope({ tags: ['child'] });
-    const result2 = child.resolveOneByAlias('ILogger');
+    const devLogger = devContainer.resolveOneByAlias<ConsoleLogger | DatabaseLogger>('ILogger');
+    const prodLogger = prodContainer.resolveOneByAlias<ConsoleLogger | DatabaseLogger>('ILogger');
 
-    expect(result1).toBeInstanceOf(FileLogger);
-    expect(result2).toBeInstanceOf(DbLogger);
+    expect(devLogger.type).toBe('console');
+    expect(prodLogger.type).toBe('database');
   });
 });
 
@@ -1173,7 +1600,23 @@ import {
   singleton,
 } from 'ts-ioc-container';
 
-describe('lazy provider', () => {
+/**
+ * User Management Domain - Decorator Pattern
+ *
+ * The decorator pattern wraps a service with additional behavior:
+ * - Logging: Log all repository operations for audit
+ * - Caching: Cache results of expensive operations
+ * - Retry: Automatically retry failed operations
+ * - Validation: Validate inputs before processing
+ *
+ * In DI, decorators are applied at registration time, so consumers
+ * get the decorated version without knowing about the decoration.
+ *
+ * This example shows a TodoRepository decorated with logging -
+ * every save operation is automatically logged.
+ */
+describe('Decorator Pattern', () => {
+  // Singleton logger collects all log entries
   @register(singleton())
   class Logger {
     private logs: string[] = [];
@@ -1196,50 +1639,58 @@ describe('lazy provider', () => {
     text: string;
   }
 
-  class LogRepository implements IRepository {
+  // Decorator: Wraps any IRepository with logging behavior
+  class LoggingRepository implements IRepository {
     constructor(
       private repository: IRepository,
       @inject(s.token('Logger').lazy()) private logger: Logger,
     ) {}
 
     async save(item: Todo): Promise<void> {
+      // Log the operation
       this.logger.log(item.id);
+      // Delegate to the wrapped repository
       return this.repository.save(item);
     }
   }
 
-  const logRepo = (dep: IRepository, scope: IContainer) => scope.resolve(LogRepository, { args: [dep] });
+  // Decorator factory - creates LoggingRepository wrapping the original
+  const withLogging = (repository: IRepository, scope: IContainer) =>
+    scope.resolve(LoggingRepository, { args: [repository] });
 
-  @register(bindTo('IRepository'), decorate(logRepo))
+  // TodoRepository is automatically decorated with logging
+  @register(bindTo('IRepository'), decorate(withLogging))
   class TodoRepository implements IRepository {
-    async save(item: Todo): Promise<void> {}
+    async save(item: Todo): Promise<void> {
+      // Actual database save logic would go here
+    }
   }
 
   class App {
     constructor(@inject('IRepository') public repository: IRepository) {}
 
     async run() {
-      await this.repository.save({ id: '1', text: 'Hello' });
-      await this.repository.save({ id: '2', text: 'Hello' });
+      await this.repository.save({ id: '1', text: 'Buy groceries' });
+      await this.repository.save({ id: '2', text: 'Walk the dog' });
     }
   }
 
-  function createContainer() {
-    const container = new Container();
-    container.addRegistration(R.fromClass(TodoRepository)).addRegistration(R.fromClass(Logger));
-    return container;
+  function createAppContainer() {
+    return new Container({ tags: ['application'] })
+      .addRegistration(R.fromClass(TodoRepository))
+      .addRegistration(R.fromClass(Logger));
   }
 
-  it('should decorate repo by logger middleware', async () => {
-    // Arrange
-    const container = createContainer();
+  it('should automatically log all repository operations via decorator', async () => {
+    const container = createAppContainer();
 
-    // Act
     const app = container.resolve(App);
     const logger = container.resolve<Logger>('Logger');
+
+    // App uses repository normally - unaware of logging decorator
     await app.run();
 
-    // Assert
+    // All operations were logged transparently
     expect(logger.printLogs()).toBe('1,2');
   });
 });
@@ -1272,52 +1723,75 @@ import {
   singleton,
 } from 'ts-ioc-container';
 
+/**
+ * User Management Domain - Registration Patterns
+ *
+ * Registrations define how dependencies are bound to the container.
+ * Common patterns:
+ * - Register by class (auto-generates key from class name)
+ * - Register by value (constants, configuration)
+ * - Register by factory function (dynamic creation)
+ * - Register with aliases (multiple keys for same service)
+ *
+ * This is the foundation for dependency injection - telling the container
+ * "when someone asks for X, give them Y".
+ */
 describe('Registration module', function () {
-  const createContainer = () => new Container({ tags: ['root'] });
+  const createAppContainer = () => new Container({ tags: ['application'] });
 
-  it('should register class', function () {
-    @register(bindTo('ILogger'), scope((s) => s.hasTag('root')), singleton())
+  it('should register class with scope and lifecycle', function () {
+    // Logger is registered at application scope as a singleton
+    @register(bindTo('ILogger'), scope((s) => s.hasTag('application')), singleton())
     class Logger {}
 
-    const root = createContainer().addRegistration(R.fromClass(Logger));
+    const appContainer = createAppContainer().addRegistration(R.fromClass(Logger));
 
-    expect(root.resolve('ILogger')).toBeInstanceOf(Logger);
+    expect(appContainer.resolve('ILogger')).toBeInstanceOf(Logger);
   });
 
-  it('should register value', function () {
-    const root = createContainer().addRegistration(R.fromValue('smth').bindToKey('ISmth'));
+  it('should register configuration value', function () {
+    // Register application configuration as a value
+    const appContainer = createAppContainer().addRegistration(R.fromValue('production').bindToKey('Environment'));
 
-    expect(root.resolve('ISmth')).toBe('smth');
+    expect(appContainer.resolve('Environment')).toBe('production');
   });
 
-  it('should register fn', function () {
-    const root = createContainer().addRegistration(R.fromFn(() => 'smth').bindToKey('ISmth'));
+  it('should register factory function', function () {
+    // Factory functions are useful for dynamic creation
+    const appContainer = createAppContainer().addRegistration(
+      R.fromFn(() => `app-${Date.now()}`).bindToKey('RequestId'),
+    );
 
-    expect(root.resolve('ISmth')).toBe('smth');
+    expect(appContainer.resolve('RequestId')).toContain('app-');
   });
 
-  it('should raise an error if key is not provider', () => {
+  it('should raise an error if binding key is not provided', () => {
+    // Values and functions must have explicit keys (classes use class name by default)
     expect(() => {
-      createContainer().addRegistration(R.fromValue('smth'));
+      createAppContainer().addRegistration(R.fromValue('orphan-value'));
     }).toThrowError(DependencyMissingKeyError);
   });
 
-  it('should register dependency by class name if @key is not provided', function () {
+  it('should register dependency by class name when no key decorator is used', function () {
+    // Without @register(bindTo('key')), the class name becomes the key
     class FileLogger {}
 
-    const root = createContainer().addRegistration(R.fromClass(FileLogger));
+    const appContainer = createAppContainer().addRegistration(R.fromClass(FileLogger));
 
-    expect(root.resolve('FileLogger')).toBeInstanceOf(FileLogger);
+    expect(appContainer.resolve('FileLogger')).toBeInstanceOf(FileLogger);
   });
 
-  it('should assign additional key which redirects to original one', function () {
+  it('should register with multiple keys using aliases', function () {
+    // Same service accessible via direct key and alias
     @register(bindTo('ILogger'), bindTo(s.alias('Logger')), singleton())
     class Logger {}
 
-    const root = createContainer().addRegistration(R.fromClass(Logger));
+    const appContainer = createAppContainer().addRegistration(R.fromClass(Logger));
 
-    expect(root.resolveByAlias('Logger')[0]).toBeInstanceOf(Logger);
-    expect(root.resolve('ILogger')).toBeInstanceOf(Logger);
+    // Accessible via alias (for group resolution)
+    expect(appContainer.resolveByAlias('Logger')[0]).toBeInstanceOf(Logger);
+    // Accessible via direct key
+    expect(appContainer.resolve('ILogger')).toBeInstanceOf(Logger);
   });
 });
 
@@ -1331,13 +1805,35 @@ Sometimes you need to register provider only in scope which matches to certain c
 ```typescript
 import { bindTo, Container, register, Registration as R, scope, singleton } from 'ts-ioc-container';
 
-@register(bindTo('ILogger'), scope((s) => s.hasTag('root')), singleton())
-class Logger {}
+/**
+ * Scoping - Scope Match Rule
+ *
+ * You can restrict WHERE a provider is registered.
+ * This is useful for singleton services that should only exist in the root scope,
+ * or per-request services that should only exist in request scopes.
+ */
+
 describe('ScopeProvider', function () {
-  it('should return the same instance', function () {
-    const root = new Container({ tags: ['root'] }).addRegistration(R.fromClass(Logger));
-    const child = root.createScope();
-    expect(root.resolve('ILogger')).toBe(child.resolve('ILogger'));
+  it('should register provider only in matching scope', function () {
+    // SharedState should be a singleton in the root 'application' scope
+    // It will be visible to all child scopes, but physically resides in 'application'
+    @register(
+      bindTo('SharedState'),
+      scope((s) => s.hasTag('application')), // Only register in application scope
+      singleton(), // One instance per application
+    )
+    class SharedState {
+      data = 'shared';
+    }
+
+    const appContainer = new Container({ tags: ['application'] }).addRegistration(R.fromClass(SharedState));
+    const requestScope = appContainer.createScope({ tags: ['request'] });
+
+    // Both resolve to the SAME instance because it's a singleton in the app scope
+    const appState = appContainer.resolve('SharedState');
+    const requestState = requestScope.resolve('SharedState');
+
+    expect(appState).toBe(requestState);
   });
 });
 
@@ -1347,41 +1843,120 @@ describe('ScopeProvider', function () {
 Sometimes you want to encapsulate registration logic in separate module. This is what `IContainerModule` is for.
 
 ```typescript
+import 'reflect-metadata';
 import { bindTo, Container, type IContainer, type IContainerModule, register, Registration as R } from 'ts-ioc-container';
 
-@register(bindTo('ILogger'))
-class Logger {}
+/**
+ * User Management Domain - Container Modules
+ *
+ * Modules organize related registrations and allow swapping implementations
+ * based on environment (development, testing, production).
+ *
+ * Common module patterns:
+ * - ProductionModule: Real database, external APIs, email service
+ * - DevelopmentModule: In-memory database, mock APIs, console logging
+ * - TestingModule: Mocks with assertion capabilities
+ *
+ * This enables:
+ * - Easy environment switching
+ * - Isolated testing without external dependencies
+ * - Feature flags via module composition
+ */
+
+// Auth service interface - same API for all environments
+interface IAuthService {
+  authenticate(email: string, password: string): boolean;
+  getServiceType(): string;
+}
+
+// Production: Real authentication with database lookup
+@register(bindTo('IAuthService'))
+class ProductionAuthService implements IAuthService {
+  authenticate(email: string, password: string): boolean {
+    // In production, this would query the database
+    return email === 'admin@example.com' && password === 'secure_password';
+  }
+
+  getServiceType(): string {
+    return 'production';
+  }
+}
+
+// Development: Accepts any credentials for easy testing
+@register(bindTo('IAuthService'))
+class DevelopmentAuthService implements IAuthService {
+  authenticate(_email: string, _password: string): boolean {
+    // Always succeed in development for easier testing
+    return true;
+  }
 
-@register(bindTo('ILogger'))
-class TestLogger {}
+  getServiceType(): string {
+    return 'development';
+  }
+}
 
-class Production implements IContainerModule {
+// Production module - real services with security
+class ProductionModule implements IContainerModule {
   applyTo(container: IContainer): void {
-    container.addRegistration(R.fromClass(Logger));
+    container.addRegistration(R.fromClass(ProductionAuthService));
+    // In a real app, also register:
+    // - Real database connection
+    // - External email service
+    // - Payment gateway
   }
 }
 
-class Development implements IContainerModule {
+// Development module - mocks and conveniences
+class DevelopmentModule implements IContainerModule {
   applyTo(container: IContainer): void {
-    container.addRegistration(R.fromClass(TestLogger));
+    container.addRegistration(R.fromClass(DevelopmentAuthService));
+    // In a real app, also register:
+    // - In-memory database
+    // - Console email logger
+    // - Mock payment gateway
   }
 }
 
 describe('Container Modules', function () {
   function createContainer(isProduction: boolean) {
-    return new Container().useModule(isProduction ? new Production() : new Development());
+    const module = isProduction ? new ProductionModule() : new DevelopmentModule();
+    return new Container().useModule(module);
   }
 
-  it('should register production dependencies', function () {
+  it('should use production auth with strict validation', function () {
     const container = createContainer(true);
+    const auth = container.resolve<IAuthService>('IAuthService');
 
-    expect(container.resolve('ILogger')).toBeInstanceOf(Logger);
+    expect(auth.getServiceType()).toBe('production');
+    expect(auth.authenticate('admin@example.com', 'secure_password')).toBe(true);
+    expect(auth.authenticate('admin@example.com', 'wrong_password')).toBe(false);
   });
 
-  it('should register development dependencies', function () {
+  it('should use development auth with permissive validation', function () {
     const container = createContainer(false);
+    const auth = container.resolve<IAuthService>('IAuthService');
+
+    expect(auth.getServiceType()).toBe('development');
+    // Development mode accepts any credentials
+    expect(auth.authenticate('any@email.com', 'any_password')).toBe(true);
+  });
+
+  it('should allow composing multiple modules', function () {
+    // Modules can be composed for feature flags or A/B testing
+    class FeatureFlagModule implements IContainerModule {
+      constructor(private enableNewFeature: boolean) {}
 
-    expect(container.resolve('ILogger')).toBeInstanceOf(TestLogger);
+      applyTo(container: IContainer): void {
+        if (this.enableNewFeature) {
+          // Register new feature implementations
+        }
+      }
+    }
+
+    const container = new Container().useModule(new ProductionModule()).useModule(new FeatureFlagModule(true));
+
+    // Base services from ProductionModule
+    expect(container.resolve<IAuthService>('IAuthService').getServiceType()).toBe('production');
   });
 });
 
@@ -1402,32 +1977,49 @@ import {
   Registration as R,
 } from 'ts-ioc-container';
 
+/**
+ * Lifecycle - OnConstruct Hook
+ *
+ * The @onConstruct hook allows you to run logic immediately after an object is created.
+ * This is useful for:
+ * - Initialization logic that depends on injected services
+ * - Setting up event listeners
+ * - Establishing connections (though lazy is often better)
+ * - Computing initial state
+ *
+ * Note: You must register the AddOnConstructHookModule or manually add the hook runner.
+ */
+
 const execute: HookFn = (ctx: HookContext) => {
   ctx.invokeMethod({ args: ctx.resolveArgs() });
 };
 
-class Car {
-  private engine!: string;
-
-  @onConstruct(execute)
-  setEngine(@inject('engine') engine: string) {
-    this.engine = engine;
-  }
-
-  getEngine() {
-    return this.engine;
-  }
-}
-
 describe('onConstruct', function () {
-  it('should run methods and resolve arguments from container', function () {
-    const root = new Container()
+  it('should run initialization method after dependencies are resolved', function () {
+    class DatabaseConnection {
+      isConnected = false;
+      connectionString = '';
+
+      // @onConstruct marks this method to be called after instantiation
+      // Arguments are resolved from the container like constructor params
+      @onConstruct(execute)
+      connect(@inject('ConnectionString') connectionString: string) {
+        this.connectionString = connectionString;
+        this.isConnected = true;
+      }
+    }
+
+    const container = new Container()
+      // Enable @onConstruct support
       .useModule(new AddOnConstructHookModule())
-      .addRegistration(R.fromValue('bmw').bindTo('engine'));
+      // Register config
+      .addRegistration(R.fromValue('postgres://localhost:5432').bindTo('ConnectionString'));
 
-    const car = root.resolve(Car);
+    // Resolve class - constructor is called, then @onConstruct method
+    const db = container.resolve(DatabaseConnection);
 
-    expect(car.getEngine()).toBe('bmw');
+    expect(db.isConnected).toBe(true);
+    expect(db.connectionString).toBe('postgres://localhost:5432');
   });
 });
 
@@ -1502,22 +2094,45 @@ describe('onDispose', function () {
 ### Inject property
 
 ```typescript
+import 'reflect-metadata';
 import { Container, hook, HooksRunner, injectProp, Registration } from 'ts-ioc-container';
 
-const onInitHookRunner = new HooksRunner('onInit');
+/**
+ * UI Components - Property Injection
+ *
+ * Property injection is useful when you don't control the class instantiation
+ * (like in some UI frameworks, Web Components, or legacy systems) or when
+ * you want to avoid massive constructors in base classes.
+ *
+ * This example demonstrates a ViewModel that gets dependencies injected
+ * AFTER construction via an initialization hook.
+ */
+
 describe('inject property', () => {
   it('should inject property', () => {
-    class App {
-      @hook('onInit', injectProp('greeting'))
-      greeting!: string;
+    // Runner for the 'onInit' lifecycle hook
+    const onInitHookRunner = new HooksRunner('onInit');
+
+    class UserViewModel {
+      // Inject 'GreetingService' into 'greeting' property during 'onInit'
+      @hook('onInit', injectProp('GreetingService'))
+      greetingService!: string;
+
+      display(): string {
+        return `${this.greetingService} User`;
+      }
     }
-    const expected = 'Hello world!';
 
-    const scope = new Container().addRegistration(Registration.fromValue(expected).bindToKey('greeting'));
-    const app = scope.resolve(App);
-    onInitHookRunner.execute(app, { scope });
+    const container = new Container().addRegistration(Registration.fromValue('Hello').bindToKey('GreetingService'));
+
+    // 1. Create instance (dependencies not yet injected)
+    const viewModel = container.resolve(UserViewModel);
+
+    // 2. Run lifecycle hooks to inject properties
+    onInitHookRunner.execute(viewModel, { scope: container });
 
-    expect(app.greeting).toBe(expected);
+    expect(viewModel.greetingService).toBe('Hello');
+    expect(viewModel.display()).toBe('Hello User');
   });
 });