ts-ioc-container 46.7.0 → 46.8.0

package/README.md

@@ -32,6 +32,7 @@
     - [Instances](#instances)
     - [Dispose](#dispose)
     - [Lazy](#lazy) `lazy`
+    - [Lazy with registerPipe](#lazy-with-registerpipe) `lazy()`
 - [Injector](#injector)
     - [Metadata](#metadata) `@inject`
     - [Simple](#simple)
@@ -533,6 +534,107 @@ describe('Instances', function () {
 
 ```
 
+### Check Registration
+Sometimes you want to check if a registration with a specific key exists in the container. This is useful for conditional registration logic, validation, and debugging.
+
+- `hasRegistration(key)` checks if a registration exists in the current container or parent containers
+- Checks both the current container's registrations and parent container registrations
+- Works with string keys, symbol keys, and token keys
+- Returns false after container disposal
+
+```typescript
+import { Container, Registration as R, bindTo, register, SingleToken } from 'ts-ioc-container';
+
+/**
+ * Container Registration Checking - hasRegistration
+ *
+ * The `hasRegistration` method allows you to check if a registration with a specific key
+ * exists in the current container. This is useful for conditional registration logic,
+ * validation, and debugging.
+ *
+ * Key points:
+ * - Checks only the current container's registrations (not parent containers)
+ * - Works with string keys, symbol keys, and token keys
+ * - Returns false after container disposal
+ * - Useful for conditional registration patterns
+ */
+describe('hasRegistration', function () {
+  const createAppContainer = () => new Container({ tags: ['application'] });
+
+  it('should return true when registration exists with string key', function () {
+    const container = createAppContainer();
+    container.addRegistration(R.fromValue('production').bindToKey('Environment'));
+
+    expect(container.hasRegistration('Environment')).toBe(true);
+  });
+
+  it('should return false when registration does not exist', function () {
+    const container = createAppContainer();
+
+    expect(container.hasRegistration('NonExistentService')).toBe(false);
+  });
+
+  it('should work with symbol keys', function () {
+    const container = createAppContainer();
+    const serviceKey = Symbol('IService');
+    container.addRegistration(R.fromValue({ name: 'Service' }).bindToKey(serviceKey));
+
+    expect(container.hasRegistration(serviceKey)).toBe(true);
+  });
+
+  it('should work with token keys', function () {
+    const container = createAppContainer();
+    const loggerToken = new SingleToken<{ log: (msg: string) => void }>('ILogger');
+    container.addRegistration(R.fromValue({ log: () => {} }).bindTo(loggerToken));
+
+    expect(container.hasRegistration(loggerToken.token)).toBe(true);
+  });
+
+  it('should check current container and parent registrations', function () {
+    // Parent container has a registration
+    const parent = createAppContainer();
+    parent.addRegistration(R.fromValue('parent-config').bindToKey('Config'));
+
+    // Child scope does not have the registration
+    const child = parent.createScope();
+    child.addRegistration(R.fromValue('child-service').bindToKey('Service'));
+
+    // Child should see parent's registration (checks parent as well)
+    expect(child.hasRegistration('Config')).toBe(true);
+    // Child should see its own registration
+    expect(child.hasRegistration('Service')).toBe(true);
+    // Parent should see its own registration
+    expect(parent.hasRegistration('Config')).toBe(true);
+  });
+
+  it('should work with class-based registrations', function () {
+    @register(bindTo('ILogger'))
+    class Logger {}
+
+    const container = createAppContainer();
+    container.addRegistration(R.fromClass(Logger));
+
+    expect(container.hasRegistration('ILogger')).toBe(true);
+  });
+
+  it('should be useful for conditional registration patterns', function () {
+    const container = createAppContainer();
+
+    // Register a base service
+    container.addRegistration(R.fromValue('base-service').bindToKey('BaseService'));
+
+    // Conditionally register an extension only if base exists
+    if (container.hasRegistration('BaseService')) {
+      container.addRegistration(R.fromValue('extension-service').bindToKey('ExtensionService'));
+    }
+
+    expect(container.hasRegistration('BaseService')).toBe(true);
+    expect(container.hasRegistration('ExtensionService')).toBe(true);
+  });
+});
+
+```
+
 ### Dispose
 Sometimes you want to dispose container and all its scopes. For example, when you want to prevent memory leaks. Or you want to ensure that nobody can use container after it was disposed.
 
@@ -766,6 +868,453 @@ describe('lazy provider', () => {
 
 ```
 
+### Lazy with registerPipe
+The `lazy()` registerPipe can be used in two ways: with the `@register` decorator or directly on the `Provider` pipe. This allows you to defer expensive service initialization until first access.
+
+**Use cases:**
+- Defer expensive initialization (database connections, SMTP, external APIs)
+- Conditional features that may not be used
+- Breaking circular dependencies
+- Memory optimization for optional services
+
+**Two approaches:**
+
+1. **With @register decorator**: Use `lazy()` as a registerPipe in the decorator
+2. **With Provider pipe**: Use `Provider.fromClass().pipe(lazy())` directly
+
+```typescript
+import 'reflect-metadata';
+import { bindTo, Container, inject, lazy, Provider, register, Registration as R, singleton } from 'ts-ioc-container';
+
+/**
+ * Lazy Loading with registerPipe
+ *
+ * The lazy() registerPipe can be used in two ways:
+ * 1. With @register decorator - lazy()
+ * 2. Directly on provider - provider.lazy()
+ *
+ * Both approaches defer instantiation until first access,
+ * improving startup time and memory usage.
+ */
+describe('lazy registerPipe', () => {
+  // Track initialization for testing
+  const initLog: string[] = [];
+
+  beforeEach(() => {
+    initLog.length = 0;
+  });
+
+  /**
+   * Example 1: Using lazy() with @register decorator
+   *
+   * The lazy() registerPipe defers service instantiation until first use.
+   * Perfect for expensive services that may not always be needed.
+   */
+  describe('with @register decorator', () => {
+    // Database connection pool - expensive to initialize
+    @register(bindTo('DatabasePool'), singleton())
+    class DatabasePool {
+      constructor() {
+        initLog.push('DatabasePool initialized');
+      }
+
+      query(sql: string): string[] {
+        return [`Results for: ${sql}`];
+      }
+    }
+
+    // Analytics service - expensive, but only used occasionally
+    @register(bindTo('AnalyticsService'), lazy(), singleton())
+    class AnalyticsService {
+      constructor(@inject('DatabasePool') private db: DatabasePool) {
+        initLog.push('AnalyticsService initialized');
+      }
+
+      trackEvent(event: string): void {
+        this.db.query(`INSERT INTO events VALUES ('${event}')`);
+      }
+
+      generateReport(): string {
+        return 'Analytics Report';
+      }
+    }
+
+    // Application service - always used
+    class AppService {
+      constructor(@inject('AnalyticsService') public analytics: AnalyticsService) {
+        initLog.push('AppService initialized');
+      }
+
+      handleRequest(path: string): void {
+        // Most requests don't need analytics
+        if (path.includes('/admin')) {
+          // Only admin requests use analytics
+          this.analytics.trackEvent(`Admin access: ${path}`);
+        }
+      }
+    }
+
+    it('should defer AnalyticsService initialization until first access', () => {
+      const container = new Container()
+        .addRegistration(R.fromClass(DatabasePool))
+        .addRegistration(R.fromClass(AnalyticsService))
+        .addRegistration(R.fromClass(AppService));
+
+      // Resolve AppService
+      const app = container.resolve<AppService>(AppService);
+
+      // AppService is initialized, but AnalyticsService is NOT (it's lazy)
+      // DatabasePool is also not initialized because AnalyticsService hasn't been accessed
+      expect(initLog).toEqual(['AppService initialized']);
+
+      // Handle non-admin request - analytics not used
+      app.handleRequest('/api/users');
+      expect(initLog).toEqual(['AppService initialized']);
+    });
+
+    it('should initialize lazy service when first accessed', () => {
+      const container = new Container()
+        .addRegistration(R.fromClass(DatabasePool))
+        .addRegistration(R.fromClass(AnalyticsService))
+        .addRegistration(R.fromClass(AppService));
+
+      const app = container.resolve<AppService>(AppService);
+
+      // Handle admin request - now analytics IS used
+      app.handleRequest('/admin/dashboard');
+
+      // AnalyticsService was initialized on first access (DatabasePool too, as a dependency)
+      expect(initLog).toEqual(['AppService initialized', 'DatabasePool initialized', 'AnalyticsService initialized']);
+    });
+
+    it('should create only one instance even with multiple accesses', () => {
+      const container = new Container()
+        .addRegistration(R.fromClass(DatabasePool))
+        .addRegistration(R.fromClass(AnalyticsService))
+        .addRegistration(R.fromClass(AppService));
+
+      const app = container.resolve<AppService>(AppService);
+
+      // Access analytics multiple times
+      app.handleRequest('/admin/dashboard');
+      app.analytics.generateReport();
+      app.analytics.trackEvent('test');
+
+      // AnalyticsService initialized only once (singleton + lazy)
+      const analyticsCount = initLog.filter((msg) => msg === 'AnalyticsService initialized').length;
+      expect(analyticsCount).toBe(1);
+    });
+  });
+
+  /**
+   * Example 2: Using lazy() directly on provider
+   *
+   * For manual registration, call .lazy() on the provider pipe.
+   * This gives fine-grained control over lazy loading per dependency.
+   */
+  describe('with pure provider', () => {
+    // Email service - expensive SMTP connection
+    class EmailService {
+      constructor() {
+        initLog.push('EmailService initialized - SMTP connected');
+      }
+
+      send(to: string, subject: string): string {
+        return `Email sent to ${to}: ${subject}`;
+      }
+    }
+
+    // SMS service - expensive gateway connection
+    class SmsService {
+      constructor() {
+        initLog.push('SmsService initialized - Gateway connected');
+      }
+
+      send(to: string, message: string): string {
+        return `SMS sent to ${to}: ${message}`;
+      }
+    }
+
+    // Notification service - uses email and SMS, but maybe not both
+    class NotificationService {
+      constructor(
+        @inject('EmailService') public email: EmailService,
+        @inject('SmsService') public sms: SmsService,
+      ) {
+        initLog.push('NotificationService initialized');
+      }
+
+      notifyByEmail(user: string, message: string): string {
+        return this.email.send(user, message);
+      }
+
+      notifyBySms(phone: string, message: string): string {
+        return this.sms.send(phone, message);
+      }
+    }
+
+    it('should allow selective lazy loading - email lazy, SMS eager', () => {
+      const container = new Container()
+        // EmailService is lazy - won't connect to SMTP until used
+        .addRegistration(
+          R.fromClass(EmailService)
+            .bindToKey('EmailService')
+            .pipe(singleton(), (p) => p.lazy()),
+        )
+        // SmsService is eager - connects to gateway immediately
+        .addRegistration(R.fromClass(SmsService).bindToKey('SmsService').pipe(singleton()))
+        .addRegistration(R.fromClass(NotificationService));
+
+      // Resolve NotificationService
+      const notifications = container.resolve<NotificationService>(NotificationService);
+
+      // SmsService initialized immediately (eager)
+      // EmailService NOT initialized yet (lazy)
+      expect(initLog).toEqual(['SmsService initialized - Gateway connected', 'NotificationService initialized']);
+
+      // Send SMS - already initialized
+      notifications.notifyBySms('555-1234', 'Test');
+      expect(initLog).toEqual(['SmsService initialized - Gateway connected', 'NotificationService initialized']);
+    });
+
+    it('should initialize lazy email service when first accessed', () => {
+      const container = new Container()
+        .addRegistration(
+          R.fromClass(EmailService)
+            .bindToKey('EmailService')
+            .pipe(singleton(), (p) => p.lazy()),
+        )
+        .addRegistration(R.fromClass(SmsService).bindToKey('SmsService').pipe(singleton()))
+        .addRegistration(R.fromClass(NotificationService));
+
+      const notifications = container.resolve<NotificationService>(NotificationService);
+
+      // Send email - NOW EmailService is initialized
+      const result = notifications.notifyByEmail('user@example.com', 'Welcome!');
+
+      expect(result).toBe('Email sent to user@example.com: Welcome!');
+      expect(initLog).toContain('EmailService initialized - SMTP connected');
+    });
+
+    it('should work with multiple lazy providers', () => {
+      const container = new Container()
+        // Both services are lazy
+        .addRegistration(
+          R.fromClass(EmailService)
+            .bindToKey('EmailService')
+            .pipe(singleton(), (p) => p.lazy()),
+        )
+        .addRegistration(
+          R.fromClass(SmsService)
+            .bindToKey('SmsService')
+            .pipe(singleton(), (p) => p.lazy()),
+        )
+        .addRegistration(R.fromClass(NotificationService));
+
+      const notifications = container.resolve<NotificationService>(NotificationService);
+
+      // Neither service initialized yet
+      expect(initLog).toEqual(['NotificationService initialized']);
+
+      // Use SMS - only SMS initialized
+      notifications.notifyBySms('555-1234', 'Test');
+      expect(initLog).toEqual(['NotificationService initialized', 'SmsService initialized - Gateway connected']);
+
+      // Use Email - now Email initialized
+      notifications.notifyByEmail('user@example.com', 'Test');
+      expect(initLog).toEqual([
+        'NotificationService initialized',
+        'SmsService initialized - Gateway connected',
+        'EmailService initialized - SMTP connected',
+      ]);
+    });
+  });
+
+  /**
+   * Example 3: Pure Provider usage (without Registration)
+   *
+   * Use Provider.fromClass() directly with lazy() for maximum flexibility.
+   */
+  describe('with pure Provider', () => {
+    class CacheService {
+      constructor() {
+        initLog.push('CacheService initialized - Redis connected');
+      }
+
+      get(key: string): string | null {
+        return `cached:${key}`;
+      }
+    }
+
+    class ApiService {
+      constructor(@inject('CacheService') private cache: CacheService) {
+        initLog.push('ApiService initialized');
+      }
+
+      fetchData(id: string): string {
+        const cached = this.cache.get(id);
+        return cached || `fresh:${id}`;
+      }
+    }
+
+    it('should use Provider.fromClass with lazy() helper', () => {
+      // Create pure provider with lazy loading
+      const cacheProvider = Provider.fromClass(CacheService).pipe(lazy(), singleton());
+
+      const container = new Container();
+      container.register('CacheService', cacheProvider);
+      container.addRegistration(R.fromClass(ApiService));
+
+      const api = container.resolve<ApiService>(ApiService);
+
+      // CacheService not initialized yet (lazy)
+      expect(initLog).toEqual(['ApiService initialized']);
+
+      // Access cache - NOW it's initialized
+      api.fetchData('user:1');
+      expect(initLog).toContain('CacheService initialized - Redis connected');
+    });
+
+    it('should allow importing lazy as named export', () => {
+      // Demonstrate that lazy() is imported from the library
+      const cacheProvider = Provider.fromClass(CacheService).pipe(lazy());
+
+      const container = new Container();
+      container.register('CacheService', cacheProvider);
+
+      const cache = container.resolve<CacheService>('CacheService');
+
+      // Not initialized until accessed
+      expect(initLog).toEqual([]);
+      cache.get('test');
+      expect(initLog).toEqual(['CacheService initialized - Redis connected']);
+    });
+  });
+
+  /**
+   * Example 4: Combining lazy with other pipes
+   *
+   * lazy() works seamlessly with other provider transformations.
+   */
+  describe('combining with other pipes', () => {
+    class ConfigService {
+      constructor(
+        public apiUrl: string,
+        public timeout: number,
+      ) {
+        initLog.push(`ConfigService initialized with ${apiUrl}`);
+      }
+    }
+
+    it('should combine lazy with args and singleton', () => {
+      const container = new Container().addRegistration(
+        R.fromClass(ConfigService)
+          .bindToKey('Config')
+          .pipe(
+            (p) => p.setArgs(() => ['https://api.example.com', 5000]),
+            (p) => p.lazy(),
+          )
+          .pipe(singleton()),
+      );
+
+      // Config not initialized yet
+      expect(initLog).toEqual([]);
+
+      // Resolve - still not initialized (lazy)
+      const config1 = container.resolve<ConfigService>('Config');
+      expect(initLog).toEqual([]);
+
+      // Access property - NOW initialized
+      const url = config1.apiUrl;
+      expect(url).toBe('https://api.example.com');
+      expect(initLog).toEqual(['ConfigService initialized with https://api.example.com']);
+
+      // Resolve again - same instance (singleton)
+      const config2 = container.resolve<ConfigService>('Config');
+      expect(config2).toBe(config1);
+      expect(initLog.length).toBe(1); // Still only one initialization
+    });
+  });
+
+  /**
+   * Example 5: Real-world use case - Resource Management
+   *
+   * Lazy loading is ideal for:
+   * - Database connections
+   * - File handles
+   * - External API clients
+   * - Report generators
+   */
+  describe('real-world example - feature flags', () => {
+    class FeatureFlagService {
+      constructor() {
+        initLog.push('FeatureFlagService initialized');
+      }
+
+      isEnabled(feature: string): boolean {
+        return feature === 'premium';
+      }
+    }
+
+    @register(bindTo('PremiumFeature'), lazy(), singleton())
+    class PremiumFeature {
+      constructor() {
+        initLog.push('PremiumFeature initialized - expensive operation');
+      }
+
+      execute(): string {
+        return 'Premium feature executed';
+      }
+    }
+
+    class Application {
+      constructor(
+        @inject('FeatureFlagService') private flags: FeatureFlagService,
+        @inject('PremiumFeature') private premium: PremiumFeature,
+      ) {
+        initLog.push('Application initialized');
+      }
+
+      handleRequest(feature: string): string {
+        if (this.flags.isEnabled(feature)) {
+          return this.premium.execute();
+        }
+        return 'Standard feature';
+      }
+    }
+
+    it('should not initialize premium features for standard users', () => {
+      const container = new Container()
+        .addRegistration(R.fromClass(FeatureFlagService).bindToKey('FeatureFlagService').pipe(singleton()))
+        .addRegistration(R.fromClass(PremiumFeature))
+        .addRegistration(R.fromClass(Application));
+
+      const app = container.resolve<Application>(Application);
+
+      // Standard request - premium feature not initialized
+      const result = app.handleRequest('standard');
+      expect(result).toBe('Standard feature');
+      expect(initLog).not.toContain('PremiumFeature initialized - expensive operation');
+    });
+
+    it('should initialize premium features only for premium users', () => {
+      const container = new Container()
+        .addRegistration(R.fromClass(FeatureFlagService).bindToKey('FeatureFlagService').pipe(singleton()))
+        .addRegistration(R.fromClass(PremiumFeature))
+        .addRegistration(R.fromClass(Application));
+
+      const app = container.resolve<Application>(Application);
+
+      // Premium request - NOW premium feature is initialized
+      const result = app.handleRequest('premium');
+      expect(result).toBe('Premium feature executed');
+      expect(initLog).toContain('PremiumFeature initialized - expensive operation');
+    });
+  });
+});
+
+```
+
 ## Injector
 `IInjector` is used to describe how dependencies should be injected to constructor.
 

package/cjm/container/Container.js

@@ -107,6 +107,9 @@ class Container {
     getRegistrations() {
         return [...this.parent.getRegistrations(), ...this.registrations];
     }
+    hasRegistration(key) {
+        return this.registrations.some((r) => r.getKeyOrFail() === key) || this.parent.hasRegistration(key);
+    }
     addOnConstructHook(...hooks) {
         this.onConstructHookList.push(...hooks);
         return this;

package/cjm/container/EmptyContainer.js

@@ -35,6 +35,9 @@ class EmptyContainer {
     getRegistrations() {
         return [];
     }
+    hasRegistration(key) {
+        return false;
+    }
     removeScope() { }
     useModule(module) {
         throw new MethodNotImplementedError_1.MethodNotImplementedError();

package/cjm/registration/Registration.js

@@ -79,5 +79,11 @@ class Registration {
         const provider = this.createProvider();
         container.register(this.key, provider.pipe(...this.mappers), { aliases: [...this.aliases] });
     }
+    getKeyOrFail() {
+        if (!this.key) {
+            throw new DependencyMissingKeyError_1.DependencyMissingKeyError('No key provided for registration');
+        }
+        return this.key;
+    }
 }
 exports.Registration = Registration;

package/esm/container/Container.js

@@ -104,6 +104,9 @@ export class Container {
     getRegistrations() {
         return [...this.parent.getRegistrations(), ...this.registrations];
     }
+    hasRegistration(key) {
+        return this.registrations.some((r) => r.getKeyOrFail() === key) || this.parent.hasRegistration(key);
+    }
     addOnConstructHook(...hooks) {
         this.onConstructHookList.push(...hooks);
         return this;

package/esm/container/EmptyContainer.js

@@ -32,6 +32,9 @@ export class EmptyContainer {
     getRegistrations() {
         return [];
     }
+    hasRegistration(key) {
+        return false;
+    }
     removeScope() { }
     useModule(module) {
         throw new MethodNotImplementedError();

package/esm/registration/Registration.js

@@ -76,4 +76,10 @@ export class Registration {
         const provider = this.createProvider();
         container.register(this.key, provider.pipe(...this.mappers), { aliases: [...this.aliases] });
     }
+    getKeyOrFail() {
+        if (!this.key) {
+            throw new DependencyMissingKeyError('No key provided for registration');
+        }
+        return this.key;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-ioc-container",
-  "version": "46.7.0",
+  "version": "46.8.0",
   "description": "Typescript IoC container",
   "workspaces": [
     "docs"
@@ -63,6 +63,8 @@
     "docs:preview": "pnpm --filter ts-ioc-container-docs run preview"
   },
   "devDependencies": {
+    "@commitlint/cli": "^20.2.0",
+    "@commitlint/config-conventional": "^20.2.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.2",

package/typings/container/Container.d.ts

@@ -30,6 +30,7 @@ export declare class Container implements IContainer {
     dispose(): void;
     addRegistration(registration: IRegistration): this;
     getRegistrations(): IRegistration[];
+    hasRegistration(key: DependencyKey): boolean;
     addOnConstructHook(...hooks: OnConstructHook[]): this;
     addOnDisposeHook(...hooks: OnDisposeHook[]): this;
     addInstance(instance: Instance): void;

package/typings/container/EmptyContainer.d.ts

@@ -16,6 +16,7 @@ export declare class EmptyContainer implements IContainer {
     hasTag(tag: Tag): boolean;
     addTags(...tags: Tag[]): void;
     getRegistrations(): never[];
+    hasRegistration(key: DependencyKey): boolean;
     removeScope(): void;
     useModule(module: IContainerModule): this;
     addRegistration(registration: IRegistration): this;

package/typings/container/IContainer.d.ts

@@ -38,6 +38,7 @@ export interface IContainer extends Tagged {
     register(key: DependencyKey, value: IProvider, options?: RegisterOptions): this;
     addRegistration(registration: IRegistration): this;
     getRegistrations(): IRegistration[];
+    hasRegistration(key: DependencyKey): boolean;
     resolve<T>(target: constructor<T> | DependencyKey, options?: ResolveOneOptions): T;
     resolveByAlias<T>(alias: DependencyKey, options?: ResolveManyOptions): T[];
     resolveOneByAlias<T>(alias: DependencyKey, options?: ResolveOneOptions): T;

package/typings/registration/IRegistration.d.ts

@@ -6,6 +6,7 @@ import { MapFn } from '../utils/fp';
 import { type constructor } from '../utils/basic';
 export type ScopeMatchRule = (s: IContainer, prev?: boolean) => boolean;
 export interface IRegistration<T = any> extends IContainerModule {
+    getKeyOrFail(): DependencyKey;
     when(...predicates: ScopeMatchRule[]): this;
     bindToKey(key: DependencyKey): this;
     bindTo(key: DependencyKey | BindToken): this;

package/typings/registration/Registration.d.ts

@@ -7,7 +7,7 @@ import { type MapFn } from '../utils/fp';
 import { type constructor } from '../utils/basic';
 export declare class Registration<T = any> implements IRegistration<T> {
     private createProvider;
-    private key?;
+    key?: DependencyKey | undefined;
     private scopeRules;
     static fromClass<T>(Target: constructor<T>): IRegistration<any>;
     static fromValue<T>(value: T): IRegistration<any> | Registration<T>;
@@ -23,4 +23,5 @@ export declare class Registration<T = any> implements IRegistration<T> {
     bindTo(key: DependencyKey | BindToken): this;
     private matchScope;
     applyTo(container: IContainer): void;
+    getKeyOrFail(): DependencyKey;
 }