ts-ioc-container 50.2.1 → 50.2.3

package/README.md

@@ -36,11 +36,9 @@ no global container objects.
 - [Cheatsheet](#cheatsheet)
 - [tsyringe alternative](https://igorbabkin.github.io/ts-ioc-container/tsyringe-alternative)
 - [Inversify and Awilix alternative](https://igorbabkin.github.io/ts-ioc-container/inversify-awilix-alternative)
-- [Recipes](#recipes)
 - [Container](#container)
   - [Basic usage](#basic-usage)
   - [Scope](#scope) `tags`
-  - [Dynamic Tag Management](#dynamic-tag-management) `addTags`
   - [Instances](#instances)
   - [Dispose](#dispose)
   - [Lazy](#lazy) `lazy`
@@ -153,208 +151,6 @@ describe('Quickstart', function () {
 > for `R.fromValue(...)` and `R.fromFn(...)` (which have no class to decorate)
 > or for third-party classes you don't own.
 
-## Recipes
-
-### Express/Next handler (per-request scope)
-
-import 'reflect-metadata';
-import { bindTo, Container, inject, register, Registration as R, singleton } from 'ts-ioc-container';
-
-/**
- * Web Framework Integration - Per-Request Scope
- *
- * In Express/Next.js applications, each HTTP request typically gets its own
- * scope. This ensures request-specific state (logger context, current user,
- * correlation IDs) is isolated between concurrent requests.
- *
- * Scope hierarchy:
- *   Application (singleton services — live for entire app lifetime)
- *     └── Request (per-request services — created and disposed per request)
- */
-
-@register(bindTo('ILogger'), singleton())
-class Logger {
-  readonly messages: string[] = [];
-
-  log(message: string) {
-    this.messages.push(message);
-  }
-}
-
-describe('Express/Next per-request scope', () => {
-  it('should give each request its own Logger instance', () => {
-    const app = new Container({ tags: ['application'] }).addRegistration(R.fromClass(Logger));
-
-    // Simulate two concurrent HTTP requests
-    const request1Scope = app.createScope({ tags: ['request'] });
-    const request2Scope = app.createScope({ tags: ['request'] });
-
-    const logger1 = request1Scope.resolve<Logger>('ILogger');
-    const logger2 = request2Scope.resolve<Logger>('ILogger');
-
-    logger1.log('req 1 started');
-    logger2.log('req 2 started');
-
-    // Each request has its own Logger — logs don't leak between requests
-    expect(logger1.messages).toEqual(['req 1 started']);
-    expect(logger2.messages).toEqual(['req 2 started']);
-    expect(logger1).not.toBe(logger2);
-  });
-
-  it('should resolve the same Logger within a single request', () => {
-    const app = new Container({ tags: ['application'] }).addRegistration(R.fromClass(Logger));
-
-    const requestScope = app.createScope({ tags: ['request'] });
-
-    const logger1 = requestScope.resolve<Logger>('ILogger');
-    const logger2 = requestScope.resolve<Logger>('ILogger');
-
-    // Within one request, singleton is maintained
-    expect(logger1).toBe(logger2);
-  });
-});
-
-
-### Background worker (singleton client, transient jobs)
-
-import 'reflect-metadata';
-import { Container, inject, register, Registration as R, singleton } from 'ts-ioc-container';
-
-/**
- * Background Worker - Singleton Client, Transient Jobs
- *
- * A queue worker typically needs:
- * - A single shared QueueClient (expensive to create, holds connections)
- * - A new JobHandler per job (stateful — holds job-specific data)
- *
- * singleton() on QueueClient ensures one shared connection pool.
- * No singleton on JobHandler gives a fresh instance per resolve.
- */
-
-@register(singleton())
-class QueueClient {
-  readonly connected = true;
-
-  dequeue(): string {
-    return 'job-payload';
-  }
-}
-
-class JobHandler {
-  readonly result: string;
-
-  constructor(@inject('QueueClient') private queue: QueueClient) {
-    this.result = this.queue.dequeue();
-  }
-}
-
-describe('Background worker', () => {
-  function createWorker() {
-    return new Container({ tags: ['worker'] })
-      .addRegistration(R.fromClass(QueueClient))
-      .addRegistration(R.fromClass(JobHandler));
-  }
-
-  it('should share a single QueueClient across all job handlers', () => {
-    const worker = createWorker();
-
-    const handler1 = worker.resolve(JobHandler);
-    const handler2 = worker.resolve(JobHandler);
-
-    const client1 = worker.resolve<QueueClient>('QueueClient');
-    const client2 = worker.resolve<QueueClient>('QueueClient');
-
-    // QueueClient is a singleton — same connection shared everywhere
-    expect(client1).toBe(client2);
-    expect(client1.connected).toBe(true);
-
-    // JobHandler is transient — fresh instance per job
-    expect(handler1).not.toBe(handler2);
-  });
-
-  it('should inject the shared QueueClient into each JobHandler', () => {
-    const worker = createWorker();
-
-    const handler = worker.resolve(JobHandler);
-
-    expect(handler.result).toBe('job-payload');
-  });
-});
-
-
-### Frontend widget/page scope with lazy dependency
-
-import 'reflect-metadata';
-import { bindTo, Container, inject, register, Registration as R, select, singleton } from 'ts-ioc-container';
-
-/**
- * Frontend Widget - Page Scope with Lazy Dependency
- *
- * In frontend applications, feature flags are fetched once per page load
- * (singleton per page scope) but a widget may not need them on every render.
- * Lazy injection defers instantiation until the widget actually reads the flags,
- * avoiding unnecessary work for widgets that never display flag-gated content.
- *
- * Scope hierarchy:
- *   Application
- *     └── Page (singleton flags fetched once)
- *           └── Widget (lazy flag access)
- */
-
-@register(bindTo('FeatureFlags'), singleton())
-class FeatureFlags {
-  load(): Record<string, boolean> {
-    return { newDashboard: true };
-  }
-}
-
-class Widget {
-  constructor(@inject(select.token('FeatureFlags').lazy()) public flags: FeatureFlags) {}
-}
-
-describe('Frontend widget/page scope with lazy dependency', () => {
-  function createPage() {
-    return new Container({ tags: ['page'] })
-      .addRegistration(R.fromClass(FeatureFlags))
-      .addRegistration(R.fromClass(Widget));
-  }
-
-  it('should not instantiate FeatureFlags until the widget actually accesses it', () => {
-    const page = createPage();
-
-    const widget = page.resolve(Widget);
-
-    // Widget is resolved, but FeatureFlags has not been instantiated yet
-    let instances = Array.from(page.getInstances()).filter((x) => x instanceof FeatureFlags);
-    expect(instances).toHaveLength(0);
-
-    // Accessing any property on the lazy proxy triggers instantiation
-    const _load = widget.flags.load;
-    expect(_load).toBeDefined();
-
-    instances = Array.from(page.getInstances()).filter((x) => x instanceof FeatureFlags);
-    expect(instances).toHaveLength(1);
-  });
-
-  it('should share the same FeatureFlags singleton across widgets on the same page', () => {
-    const page = createPage();
-
-    const widget1 = page.resolve(Widget);
-    const widget2 = page.resolve(Widget);
-
-    // Trigger instantiation through both widgets
-    const _load1 = widget1.flags.load;
-    const _load2 = widget2.flags.load;
-    expect(_load1).toBeDefined();
-    expect(_load2).toBeDefined();
-
-    // Only one FeatureFlags instance was created across the whole page scope
-    const instances = Array.from(page.getInstances()).filter((x) => x instanceof FeatureFlags);
-    expect(instances).toHaveLength(1);
-  });
-});
-
-
 ## Container
 
 `IContainer` consists of:
@@ -547,116 +343,6 @@ describe('Scopes', function () {
 
 ```
 
-### Dynamic Tag Management
-
-You can dynamically add tags to a container after it's been created using the `addTags()` method. This is useful for environment-based configuration, feature flags, and progressive container setup.
-
-- Tags can be added one at a time or multiple at once
-- Useful for conditional configuration based on `NODE_ENV` or runtime flags
-- Container can be configured incrementally as the application initializes
-
-> [!WARNING]
-> Tags must be added **before** registrations are applied. Scope matching happens at registration time, so adding tags later does not retroactively make providers available.
-
-```typescript
-import { bindTo, Container, register, Registration as R, scope } from 'ts-ioc-container';
-
-describe('addTags', () => {
-  it('should dynamically add tags to enable environment-based registration', () => {
-    @register(bindTo('logger'), scope((s) => s.hasTag('development')))
-    class ConsoleLogger {
-      log(message: string) {
-        console.log(`[DEV] ${message}`);
-      }
-    }
-
-    @register(bindTo('logger'), scope((s) => s.hasTag('production')))
-    class FileLogger {
-      log(message: string) {
-        console.log(`[PROD] ${message}`);
-      }
-    }
-
-    // Create container and configure for environment
-    const container = new Container();
-    const environment = 'development';
-    container.addTags(environment); // Add tag dynamically based on environment
-
-    // Register services after tag is set
-    container.addRegistration(R.fromClass(ConsoleLogger)).addRegistration(R.fromClass(FileLogger));
-
-    // Resolve logger - gets ConsoleLogger because 'development' tag was added
-    const logger = container.resolve<ConsoleLogger>('logger');
-    expect(logger).toBeInstanceOf(ConsoleLogger);
-  });
-
-  it('should add multiple tags for feature-based configuration', () => {
-    @register(bindTo('premiumFeature'), scope((s) => s.hasTag('premium')))
-    class PremiumFeature {}
-
-    @register(bindTo('betaFeature'), scope((s) => s.hasTag('beta')))
-    class BetaFeature {}
-
-    const container = new Container();
-
-    // Add multiple tags at once
-    container.addTags('premium', 'beta', 'experimental');
-
-    // Verify all tags are present
-    expect(container.hasTag('premium')).toBe(true);
-    expect(container.hasTag('beta')).toBe(true);
-    expect(container.hasTag('experimental')).toBe(true);
-
-    // Register features after tags are added
-    container.addRegistration(R.fromClass(PremiumFeature)).addRegistration(R.fromClass(BetaFeature));
-
-    // Both features are available because container has both tags
-    expect(container.resolve('premiumFeature')).toBeInstanceOf(PremiumFeature);
-    expect(container.resolve('betaFeature')).toBeInstanceOf(BetaFeature);
-  });
-
-  it('should affect child scope creation', () => {
-    @register(bindTo('service'), scope((s) => s.hasTag('api')))
-    class ApiService {
-      handleRequest() {
-        return 'API response';
-      }
-    }
-
-    const appContainer = new Container();
-
-    // Add tag to parent
-    appContainer.addTags('api');
-    appContainer.addRegistration(R.fromClass(ApiService));
-
-    // Create child scopes - they inherit parent's registrations
-    const requestScope1 = appContainer.createScope({ tags: ['request'] });
-    const requestScope2 = appContainer.createScope({ tags: ['request'] });
-
-    // Both scopes can access the ApiService from parent
-    expect(requestScope1.resolve<ApiService>('service').handleRequest()).toBe('API response');
-    expect(requestScope2.resolve<ApiService>('service').handleRequest()).toBe('API response');
-  });
-
-  it('should enable incremental tag addition', () => {
-    const container = new Container();
-
-    // Start with basic tags
-    container.addTags('application');
-    expect(container.hasTag('application')).toBe(true);
-
-    // Add more tags as needed
-    container.addTags('monitoring', 'logging');
-    expect(container.hasTag('monitoring')).toBe(true);
-    expect(container.hasTag('logging')).toBe(true);
-
-    // All tags are retained
-    expect(container.hasTag('application')).toBe(true);
-  });
-});
-
-```
-
 ### Instances
 
 Sometimes you want to get all instances from container and its scopes. For example, when you want to dispose all instances of container.
@@ -742,108 +428,6 @@ 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 a container or scope. For example, when a request, page, widget, or other local lifecycle ends.
@@ -2576,6 +2160,9 @@ Sometimes you want to register provider with certain key. This is what `key` is
 - by default, key is class name
 - you can assign the same key to different registrations
 
+> [!TIP]
+> Prefer `SingleToken<T>` over plain string literals as registration keys. Tokens are type-safe, rename-friendly, and prevent typos that only surface at runtime.
+
 ```typescript
 import {
   bindTo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-ioc-container",
-  "version": "50.2.1",
+  "version": "50.2.3",
   "description": "Fast, lightweight TypeScript dependency injection container with a clean API, scoped lifecycles, decorators, tokens, hooks, lazy injection, customizable providers, and no global container objects.",
   "workspaces": [
     "docs"