ts-ioc-container 47.4.0 → 48.0.0

package/README.md

@@ -1,4 +1,4 @@
-# Typescript IoC (Inversion Of Control) container
+# TypeScript Dependency Injection Container
 
 ![NPM version:latest](https://img.shields.io/npm/v/ts-ioc-container/latest.svg?style=flat-square)
 ![npm downloads](https://img.shields.io/npm/dt/ts-ioc-container.svg?style=flat-square)
@@ -7,51 +7,68 @@
 ![License](https://img.shields.io/npm/l/ts-ioc-container)
 [![semantic-release](https://img.shields.io/badge/%20%20%20FLO%20-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
 
+`ts-ioc-container` is a fast, lightweight TypeScript dependency injection
+container for applications that need more than basic constructor injection:
+scoped lifecycles, decorators, typed tokens, lazy dependencies, lifecycle hooks,
+provider pipelines, aliases, and custom injector strategies.
+
+Use it as a `tsyringe` alternative when you want a clear API with more flexible
+customization for real application architecture. Use it as an Inversify or
+Awilix alternative when you want a thinner, cleaner API with explicit scopes and
+no global container objects.
+
 ## Advantages
-- battle tested :boom:
-- written on `typescript`
-- simple and lightweight :heart:
-- clean API :green_heart:
-- supports `tagged scopes`
-- fully test covered :100:
-- can be used with decorators `@inject`
+
+- fast TypeScript dependency resolution
+- lightweight and dependency-minimal
+- clean API for classes, keys, tokens, aliases, and scopes
+- no global container object; pass containers and scopes explicitly
+- supports tagged application, request, transaction, page, and widget scopes
+- decorator support with `@register`, `@inject`, `@onConstruct`, and `@onDispose`
 - can [inject properties](#inject-property)
 - can inject [lazy dependencies](#lazy)
-- composable and open to extend
+- composable provider and registration pipelines
+- custom injectors, hooks, and provider behavior
+- product behavior covered by executable specs
 
 ## Content
 
 - [Setup](#setup)
 - [Quickstart](#quickstart)
 - [Cheatsheet](#cheatsheet)
+- [Spec-driven workflow](#spec-driven-workflow)
+  - [Product capability map](#product-capability-map)
+  - [Acceptance specs](#acceptance-specs)
+- [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`
-    - [Lazy with registerPipe](#lazy-with-registerpipe) `lazy()`
+  - [Basic usage](#basic-usage)
+  - [Scope](#scope) `tags`
+  - [Dynamic Tag Management](#dynamic-tag-management) `addTags`
+  - [Instances](#instances)
+  - [Dispose](#dispose)
+  - [Lazy](#lazy) `lazy`
+  - [Lazy with registerPipe](#lazy-with-registerpipe) `lazy()`
 - [Injector](#injector)
-    - [Metadata](#metadata) `@inject`
-    - [Simple](#simple)
-    - [Proxy](#proxy)
+  - [Metadata](#metadata) `@inject`
+  - [Simple](#simple)
+  - [Proxy](#proxy)
 - [Provider](#provider) `provider`
-    - [Singleton](#singleton) `singleton`
-    - [Arguments](#arguments) `setArgs` `setArgsFn`
-    - [Visibility](#visibility) `visible`
-    - [Alias](#alias) `asAlias`
-    - [Decorator](#decorator) `decorate`
+  - [Singleton](#singleton) `singleton`
+  - [Arguments](#arguments) `setArgs` `setArgsFn`
+  - [Visibility](#visibility) `visible`
+  - [Alias](#alias) `asAlias`
+  - [Decorator](#decorator) `decorate`
 - [Registration](#registration) `@register`
-    - [Key](#key) `asKey`
-    - [Scope](#scope) `scope`
+  - [Key](#key) `asKey`
+  - [Scope](#scope) `scope`
 - [Module](#module)
 - [Hook](#hook) `@hook`
-    - [OnConstruct](#onconstruct) `@onConstruct`
-    - [OnDispose](#ondispose) `@onDispose`
-    - [Inject Property](#inject-property)
-    - [Inject Method](#inject-method)
+  - [OnConstruct](#onconstruct) `@onConstruct`
+  - [OnDispose](#ondispose) `@onDispose`
+  - [Inject Property](#inject-property)
+  - [Inject Method](#inject-method)
 - [Mock](#mock)
 - [Error](#error)
 
@@ -60,16 +77,19 @@
 ```shell script
 npm install ts-ioc-container reflect-metadata
 ```
+
 ```shell script
 yarn add ts-ioc-container reflect-metadata
 ```
 
 Just put it in the entrypoint file of your project. It should be the first line of the code.
+
 ```typescript
 import 'reflect-metadata';
 ```
 
 And `tsconfig.json` should have next options:
+
 ```json
 {
   "compilerOptions": {
@@ -105,8 +125,9 @@ container.resolve(App).start();
 
 ## Cheatsheet
 
-- Register class with key: `@register(bindTo('Key')) class Service {}`
+- Register class with key (preferred): `@register(bindTo('Key')) class Service {}` then `container.addRegistration(R.fromClass(Service))`
 - Register value: `R.fromValue(config).bindToKey('Config')`
+- Register factory: `R.fromFn((c) => createX(c)).bindToKey('X')`
 - Singleton: `@register(singleton())`
 - Scoped registration: `@register(scope((s) => s.hasTag('request')))`
 - Resolve by alias: `container.resolveByAlias('Alias')`
@@ -115,12 +136,56 @@ container.resolve(App).start();
 - Inject decorator: `@inject('Key')`
 - Property inject: `injectProp(target, 'propName', select.token('Key'))`
 
+> [!TIP]
+> For classes, prefer the `@register(bindTo('Key'))` decorator over the fluent
+> `R.fromClass(Class).bindToKey('Key')` chain. The decorator co-locates the binding
+> with the class and reads consistently with other registration pipes
+> (`scope`, `singleton`, `setArgsFn`, ...). Use the fluent `bindToKey` chain only
+> for `R.fromValue(...)` and `R.fromFn(...)` (which have no class to decorate)
+> or for third-party classes you don't own.
+
+## Spec-driven workflow
+
+Public behavior is described as product capabilities before it is implemented.
+The repository keeps the same chain visible in specs, tests, docs, and this
+README:
+
+```text
+Business capability -> user story -> acceptance criteria -> executable spec test -> docs and ADRs
+```
+
+- ADRs in `docs/adr/` explain durable architecture and process decisions.
+- Specs in `specs/` describe epics, stories, use cases, and acceptance criteria.
+- Acceptance tests in `__tests__/specs/` execute the public contract.
+- README examples in `__tests__/readme/` stay executable and are rendered from `.readme.hbs.md`.
+
+### Product capability map
+
+| Capability              | User outcome                                                               | Spec                                     | Acceptance test                                   |
+| ----------------------- | -------------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------- |
+| Dependency resolution   | Resolve dependencies by key, class, token, or constructor injection.       | `specs/epics/dependency-resolution.md`   | `__tests__/specs/dependency-resolution.spec.ts`   |
+| Scoped lifecycle        | Isolate application, request, transaction, page, or widget lifecycles.     | `specs/epics/scoped-lifecycle.md`        | `__tests__/specs/scoped-lifecycle.spec.ts`        |
+| Dependency registration | Describe classes, values, factories, keys, aliases, and scoped services.   | `specs/epics/dependency-registration.md` | `__tests__/specs/dependency-registration.spec.ts` |
+| Provider behavior       | Cache, decorate, delay, restrict, or parameterize dependency creation.     | `specs/epics/provider-behavior.md`       | `__tests__/specs/provider-behavior.spec.ts`       |
+| Token-based injection   | Make dependency requests explicit, typed, reusable, and composable.        | `specs/epics/token-based-injection.md`   | `__tests__/specs/token-based-injection.spec.ts`   |
+| Injector strategies     | Support metadata, simple container, proxy, and custom injection styles.    | `specs/epics/injector-strategies.md`     | `__tests__/specs/injector-strategies.spec.ts`     |
+| Lifecycle hooks         | Run initialization, cleanup, property injection, and custom hook behavior. | `specs/epics/lifecycle-hooks.md`         | `__tests__/specs/lifecycle-hooks.spec.ts`         |
+| Container modules       | Package container configuration by feature, environment, or lifecycle.     | `specs/epics/container-modules.md`       | `__tests__/specs/container-modules.spec.ts`       |
+| Metadata utilities      | Attach labels, tags, and reusable method behavior to application code.     | `specs/epics/metadata-utilities.md`      | `__tests__/specs/metadata-utilities.spec.ts`      |
+| Errors and boundaries   | Make misconfiguration and unsupported usage diagnosable.                   | `specs/epics/errors-and-boundaries.md`   | `__tests__/specs/errors-and-boundaries.spec.ts`   |
+
+### Acceptance specs
+
+Use `pnpm run test:spec` to run only the executable acceptance specs. These
+tests are intentionally product-facing; lower-level regression and implementation
+tests stay in the feature folders under `__tests__/`.
+
 ## Recipes
 
 ### Express/Next handler (per-request scope)
+
 ```typescript
-const app = new Container({ tags: ['application'] })
-  .addRegistration(R.fromClass(Logger).pipe(singleton()));
+const app = new Container({ tags: ['application'] }).addRegistration(R.fromClass(Logger).pipe(singleton()));
 
 function handleRequest() {
   const requestScope = app.createScope({ tags: ['request'] });
@@ -130,6 +195,7 @@ function handleRequest() {
 ```
 
 ### Background worker (singleton client, transient jobs)
+
 ```typescript
 @register(singleton())
 class QueueClient {}
@@ -144,10 +210,13 @@ const worker = new Container({ tags: ['worker'] })
 ```
 
 ### Frontend widget/page scope with lazy dependency
+
 ```typescript
 @register(bindTo('FeatureFlags'), singleton())
 class FeatureFlags {
-  load() { /* fetch flags */ }
+  load() {
+    /* fetch flags */
+  }
 }
 
 class Widget {
@@ -160,6 +229,7 @@ const page = new Container({ tags: ['page'] })
 ```
 
 ## Container
+
 `IContainer` consists of:
 
 - Provider is dependency factory which creates dependency
@@ -170,7 +240,7 @@ const page = new Container({ tags: ['page'] })
 
 ```typescript
 import 'reflect-metadata';
-import { Container, type IContainer, inject, Registration as R, select } from 'ts-ioc-container';
+import { bindTo, Container, type IContainer, inject, register, Registration as R, select } from 'ts-ioc-container';
 
 /**
  * User Management Domain - Basic Dependency Injection
@@ -193,6 +263,7 @@ describe('Basic usage', function () {
   }
 
   // Concrete implementation
+  @register(bindTo('IUserRepository'))
   class UserRepository implements IUserRepository {
     private users: User[] = [{ id: '1', email: 'admin@example.com', passwordHash: 'hashed_password' }];
 
@@ -213,7 +284,7 @@ describe('Basic usage', function () {
     }
 
     // Wire up the container
-    const container = new Container().addRegistration(R.fromClass(UserRepository).bindTo('IUserRepository'));
+    const container = new Container().addRegistration(R.fromClass(UserRepository));
 
     // Resolve AuthService - UserRepository is automatically injected
     const authService = container.resolve(AuthService);
@@ -246,11 +317,17 @@ describe('Basic usage', function () {
 ```
 
 ### Scope
+
 Sometimes you need to create a scope of container. For example, when you want to create a scope per request in web application. You can assign tags to scope and provider and resolve dependencies only from certain scope.
 
-- NOTICE: remember that when scope doesn't have dependency then it will be resolved from parent container
-- NOTICE: when you create a scope of container then all providers are cloned to new scope. For that reason every provider has methods `clone` and `isValid` to clone itself and check if it's valid for certain scope accordingly.
-- NOTICE: when you create a scope then we clone ONLY tags-matched providers.
+> [!IMPORTANT]
+> Scope creation is snapshot-like. Existing parent registrations are applied to the child scope when `createScope()` is called, and when a scope doesn't have a dependency it resolves from the parent container.
+
+> [!WARNING]
+> Registrations added to a parent after a child scope has already been created are not automatically applied to that existing child. Create a new scope or add the registration to the child explicitly.
+
+> [!WARNING]
+> Scope matching happens when a registration is applied to a container. Only registrations whose scope rules match that container are registered there.
 
 ```typescript
 import 'reflect-metadata';
@@ -344,13 +421,16 @@ 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
-- Tags must be added **before** registrations are applied - scope matching happens at registration time
 - 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';
 
@@ -451,6 +531,7 @@ describe('addTags', () => {
 ```
 
 ### Instances
+
 Sometimes you want to get all instances from container and its scopes. For example, when you want to dispose all instances of container.
 
 - you can get instances from container and scope which were created by injector
@@ -535,6 +616,7 @@ 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
@@ -636,15 +718,18 @@ describe('hasRegistration', function () {
 ```
 
 ### 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.
+
+Sometimes you want to dispose a container or scope. For example, when a request, page, widget, or other local lifecycle ends.
 
 - container can be disposed
-- when container is disposed then all scopes are disposed too
-- when container is disposed then it unregisters all providers and remove all instances
+- when container is disposed then it runs its `onDispose` hooks, unregisters its providers, removes its local instances, and detaches from its parent
+
+> [!IMPORTANT]
+> Dispose is local to the container being disposed. Child scopes are not disposed automatically; dispose them explicitly when their own lifecycle ends.
 
 ```typescript
 import 'reflect-metadata';
-import { Container, ContainerDisposedError, Registration as R, select } from 'ts-ioc-container';
+import { bindTo, Container, ContainerDisposedError, register, Registration as R, select } from 'ts-ioc-container';
 
 /**
  * User Management Domain - Resource Cleanup
@@ -663,6 +748,7 @@ import { Container, ContainerDisposedError, Registration as R, select } from 'ts
  */
 
 // Simulates a database connection that must be closed
+@register(bindTo('IDatabase'))
 class DatabaseConnection {
   isClosed = false;
 
@@ -680,9 +766,7 @@ class DatabaseConnection {
 
 describe('Disposing', function () {
   it('should dispose container and prevent further usage', function () {
-    const appContainer = new Container({ tags: ['application'] }).addRegistration(
-      R.fromClass(DatabaseConnection).bindTo('IDatabase'),
-    );
+    const appContainer = new Container({ tags: ['application'] }).addRegistration(R.fromClass(DatabaseConnection));
 
     // Create a request scope with a database connection
     const requestScope = appContainer.createScope({ tags: ['request'] });
@@ -705,9 +789,7 @@ describe('Disposing', function () {
   });
 
   it('should clean up request-scoped resources on request end', function () {
-    const appContainer = new Container({ tags: ['application'] }).addRegistration(
-      R.fromClass(DatabaseConnection).bindTo('IDatabase'),
-    );
+    const appContainer = new Container({ tags: ['application'] }).addRegistration(R.fromClass(DatabaseConnection));
 
     // Simulate Express.js request lifecycle
     function handleRequest(): { connection: DatabaseConnection; scope: Container } {
@@ -742,8 +824,17 @@ describe('Disposing', function () {
 ```
 
 ### Lazy
+
 Sometimes you want to create dependency only when somebody want to invoke it's method or property. This is what `lazy` is for.
 
+- Lazy class instances are wrapped in a JavaScript `Proxy`; the real class instance is created on first property or method access.
+
+> [!IMPORTANT]
+> `lazy` is designed only for class instances resolved from class providers.
+
+> [!WARNING]
+> Do not use `lazy` for primitive values, plain values, functions, or non-class provider results.
+
 ```typescript
 import 'reflect-metadata';
 import { Container, inject, register, Registration as R, select as s, singleton } from 'ts-ioc-container';
@@ -869,9 +960,11 @@ 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.
+
+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 class instance initialization until first access.
 
 **Use cases:**
+
 - Defer expensive initialization (database connections, SMTP, external APIs)
 - Conditional features that may not be used
 - Breaking circular dependencies
@@ -884,7 +977,7 @@ The `lazy()` registerPipe can be used in two ways: with the `@register` decorato
 
 ```typescript
 import 'reflect-metadata';
-import { bindTo, Container, inject, lazy, Provider, register, Registration as R, singleton } from 'ts-ioc-container';
+import { args, bindTo, Container, inject, lazy, Provider, register, Registration as R, singleton } from 'ts-ioc-container';
 
 /**
  * Lazy Loading with registerPipe
@@ -1056,13 +1149,9 @@ describe('lazy registerPipe', () => {
     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()),
-        )
+        .addRegistration(R.fromClass(EmailService).pipe(singleton(), (p) => p.lazy()))
         // SmsService is eager - connects to gateway immediately
-        .addRegistration(R.fromClass(SmsService).bindToKey('SmsService').pipe(singleton()))
+        .addRegistration(R.fromClass(SmsService).pipe(singleton()))
         .addRegistration(R.fromClass(NotificationService));
 
       // Resolve NotificationService
@@ -1079,12 +1168,8 @@ describe('lazy registerPipe', () => {
 
     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(EmailService).pipe(singleton(), (p) => p.lazy()))
+        .addRegistration(R.fromClass(SmsService).pipe(singleton()))
         .addRegistration(R.fromClass(NotificationService));
 
       const notifications = container.resolve<NotificationService>(NotificationService);
@@ -1099,16 +1184,8 @@ describe('lazy registerPipe', () => {
     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(EmailService).pipe(singleton(), (p) => p.lazy()))
+        .addRegistration(R.fromClass(SmsService).pipe(singleton(), (p) => p.lazy()))
         .addRegistration(R.fromClass(NotificationService));
 
       const notifications = container.resolve<NotificationService>(NotificationService);
@@ -1197,10 +1274,11 @@ describe('lazy registerPipe', () => {
    * lazy() works seamlessly with other provider transformations.
    */
   describe('combining with other pipes', () => {
+    @register(bindTo('Config'))
     class ConfigService {
       constructor(
-        public apiUrl: string,
-        public timeout: number,
+        @inject(args(0)) public apiUrl: string,
+        @inject(args(1)) public timeout: number,
       ) {
         initLog.push(`ConfigService initialized with ${apiUrl}`);
       }
@@ -1209,7 +1287,6 @@ describe('lazy registerPipe', () => {
     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(),
@@ -1246,6 +1323,7 @@ describe('lazy registerPipe', () => {
    * - Report generators
    */
   describe('real-world example - feature flags', () => {
+    @register(singleton())
     class FeatureFlagService {
       constructor() {
         initLog.push('FeatureFlagService initialized');
@@ -1285,7 +1363,7 @@ describe('lazy registerPipe', () => {
 
     it('should not initialize premium features for standard users', () => {
       const container = new Container()
-        .addRegistration(R.fromClass(FeatureFlagService).bindToKey('FeatureFlagService').pipe(singleton()))
+        .addRegistration(R.fromClass(FeatureFlagService))
         .addRegistration(R.fromClass(PremiumFeature))
         .addRegistration(R.fromClass(Application));
 
@@ -1299,7 +1377,7 @@ describe('lazy registerPipe', () => {
 
     it('should initialize premium features only for premium users', () => {
       const container = new Container()
-        .addRegistration(R.fromClass(FeatureFlagService).bindToKey('FeatureFlagService').pipe(singleton()))
+        .addRegistration(R.fromClass(FeatureFlagService))
         .addRegistration(R.fromClass(PremiumFeature))
         .addRegistration(R.fromClass(Application));
 
@@ -1316,6 +1394,7 @@ describe('lazy registerPipe', () => {
 ```
 
 ## Injector
+
 `IInjector` is used to describe how dependencies should be injected to constructor.
 
 - `MetadataInjector` - injects dependencies using `@inject` decorator
@@ -1323,11 +1402,12 @@ describe('lazy registerPipe', () => {
 - `SimpleInjector` - just passes container to constructor with others arguments
 
 ### Metadata
+
 This type of injector uses `@inject` decorator to mark where dependencies should be injected. It's bases on `reflect-metadata` package. That's why I call it `MetadataInjector`.
 Also you can [inject property.](#inject-property)
 
 ```typescript
-import { Container, inject, Registration as R } from 'ts-ioc-container';
+import { bindTo, Container, inject, register, Registration as R } from 'ts-ioc-container';
 
 /**
  * User Management Domain - Metadata Injection
@@ -1344,6 +1424,7 @@ import { Container, inject, Registration as R } from 'ts-ioc-container';
  * Requires: "experimentalDecorators" and "emitDecoratorMetadata" in tsconfig.
  */
 
+@register(bindTo('ILogger'))
 class Logger {
   name = 'Logger';
 }
@@ -1362,9 +1443,7 @@ class App {
 
 describe('Metadata Injector', function () {
   it('should inject dependencies using @inject decorator', function () {
-    const container = new Container({ tags: ['application'] }).addRegistration(
-      R.fromClass(Logger).bindToKey('ILogger'),
-    );
+    const container = new Container({ tags: ['application'] }).addRegistration(R.fromClass(Logger));
 
     // Container reads @inject metadata and resolves 'ILogger' for the logger parameter
     const app = container.resolve(App);
@@ -1376,10 +1455,11 @@ describe('Metadata Injector', function () {
 ```
 
 ### Simple
+
 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';
+import { bindTo, Container, type IContainer, register, Registration as R, SimpleInjector } from 'ts-ioc-container';
 
 /**
  * Command Pattern - Simple Injector
@@ -1407,6 +1487,7 @@ class CreateUserCommand implements ICommand {
   constructor(readonly username: string) {}
 }
 
+@register(bindTo('HandlerCreateUser'))
 class CreateUserHandler implements ICommandHandler {
   handle(command: CreateUserCommand): string {
     return `User ${command.username} created`;
@@ -1416,6 +1497,7 @@ class CreateUserHandler implements ICommandHandler {
 describe('SimpleInjector', function () {
   it('should inject container to allow dynamic resolution (Service Locator pattern)', function () {
     // Dispatcher needs the container to find handlers dynamically based on command type
+    @register(bindTo('Dispatcher'))
     class CommandDispatcher {
       constructor(private container: IContainer) {}
 
@@ -1428,8 +1510,8 @@ describe('SimpleInjector', function () {
     }
 
     const container = new Container({ injector: new SimpleInjector() })
-      .addRegistration(R.fromClass(CommandDispatcher).bindToKey('Dispatcher'))
-      .addRegistration(R.fromClass(CreateUserHandler).bindToKey('HandlerCreateUser'));
+      .addRegistration(R.fromClass(CommandDispatcher))
+      .addRegistration(R.fromClass(CreateUserHandler));
 
     const dispatcher = container.resolve<CommandDispatcher>('Dispatcher');
     const result = dispatcher.dispatch(new CreateUserCommand('alice'));
@@ -1450,9 +1532,7 @@ describe('SimpleInjector', function () {
       }
     }
 
-    const container = new Container({ injector: new SimpleInjector() }).addRegistration(
-      R.fromClass(WidgetFactory).bindToKey('WidgetFactory'),
-    );
+    const container = new Container({ injector: new SimpleInjector() }).addRegistration(R.fromClass(WidgetFactory));
 
     // Pass "dark" as the theme argument
     const factory = container.resolve<WidgetFactory>('WidgetFactory', { args: ['dark'] });
@@ -1464,39 +1544,29 @@ describe('SimpleInjector', function () {
 ```
 
 ### Proxy
+
 This type of injector injects dependencies as dictionary `Record<string, unknown>`.
 
-```typescript
-import { Container, ProxyInjector, Registration as R } from 'ts-ioc-container';
+- **`args` reserved keyword**: accessing `deps.args` returns the raw `args[]` array passed at resolve time
+- **Alias convention**: any property name containing `"alias"` (case-insensitive) is resolved via `resolveByAlias` instead of `resolve`
 
-/**
- * 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
- */
+```typescript
+import { bindTo, Container, ProxyInjector, register, Registration as R } from 'ts-ioc-container';
 
 describe('ProxyInjector', function () {
   it('should inject dependencies as a props object', function () {
+    @register(bindTo('logger'))
     class Logger {
       log(msg: string) {
         return `Logged: ${msg}`;
       }
     }
 
-    // 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;
@@ -1512,53 +1582,51 @@ describe('ProxyInjector', function () {
     }
 
     const container = new Container({ injector: new ProxyInjector() })
-      .addRegistration(R.fromClass(Logger).bindToKey('logger'))
+      .addRegistration(R.fromClass(Logger))
       .addRegistration(R.fromValue('USER:').bindToKey('prefix'))
-      .addRegistration(R.fromClass(UserController).bindToKey('UserController'));
+      .addRegistration(R.fromClass(UserController));
 
     const controller = container.resolve<UserController>('UserController');
 
     expect(controller.createUser('bob')).toBe('Logged: USER: bob');
   });
 
-  it('should support mixing injected dependencies with runtime arguments', function () {
+  it('should expose runtime args through the reserved "args" property', function () {
+    @register(bindTo('database'))
     class Database {}
 
-    interface ReportGeneratorDeps {
+    class ReportGenerator {
       database: Database;
-      format: string; // Runtime argument
-    }
+      format: string;
 
-    class ReportGenerator {
-      constructor(public deps: ReportGeneratorDeps) {}
+      constructor({ database, args }: { database: Database; args: string[] }) {
+        this.database = database;
+        this.format = args[0];
+      }
 
       generate(): string {
-        return `Report in ${this.deps.format}`;
+        return `Report in ${this.format}`;
       }
     }
 
     const container = new Container({ injector: new ProxyInjector() })
-      .addRegistration(R.fromClass(Database).bindToKey('database'))
-      .addRegistration(R.fromClass(ReportGenerator).bindToKey('ReportGenerator'));
+      .addRegistration(R.fromClass(Database))
+      .addRegistration(R.fromClass(ReportGenerator));
 
-    // "format" is passed at resolution time
     const generator = container.resolve<ReportGenerator>('ReportGenerator', {
-      args: [{ format: 'PDF' }],
+      args: ['PDF'],
     });
 
-    expect(generator.deps.database).toBeInstanceOf(Database);
+    expect(generator.database).toBeInstanceOf(Database);
     expect(generator.generate()).toBe('Report in PDF');
   });
 
-  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.
-
+  it('should resolve dependencies by alias when property name contains "alias"', function () {
     class FileLogger {}
     class ConsoleLogger {}
 
     interface AppDeps {
-      loggersArray: any[]; // Injected as array of all loggers
+      loggersAlias: any[];
     }
 
     class App {
@@ -1567,23 +1635,20 @@ describe('ProxyInjector', function () {
 
     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 = vi.fn().mockReturnValue(mockLoggers);
 
     const app = container.resolve(App);
 
-    expect(app.deps.loggersArray).toBe(mockLoggers);
-    expect(container.resolveByAlias).toHaveBeenCalledWith('loggersArray');
+    expect(app.deps.loggersAlias).toBe(mockLoggers);
+    expect(container.resolveByAlias).toHaveBeenCalledWith('loggersAlias');
   });
 });
 
 ```
 
 ## Provider
+
 Provider is dependency factory which creates dependency.
 
 - `Provider.fromClass(Logger)`
@@ -1592,10 +1657,12 @@ Provider is dependency factory which creates dependency.
 
 ```typescript
 import {
+  args,
   setArgs,
   setArgsFn,
   bindTo,
   Container,
+  inject,
   lazy,
   Provider,
   register,
@@ -1669,7 +1736,7 @@ describe('Provider', () => {
 
   it('supports args decorator for providing extra arguments', () => {
     class FileService {
-      constructor(readonly basePath: string) {}
+      constructor(@inject(args(0)) readonly basePath: string) {}
     }
 
     const container = new Container().register(
@@ -1683,7 +1750,7 @@ describe('Provider', () => {
 
   it('supports argsFn decorator for dynamic arguments', () => {
     class Database {
-      constructor(readonly connectionString: string) {}
+      constructor(@inject(args(0)) readonly connectionString: string) {}
     }
 
     const container = new Container().register('DbPath', Provider.fromValue('localhost:5432')).register(
@@ -1737,10 +1804,13 @@ describe('Provider', () => {
 ```
 
 ### Singleton
+
 Sometimes you need to create only one instance of dependency per scope. For example, you want to create only one logger per scope.
 
 - Singleton provider creates only one instance in every scope where it's resolved.
-- NOTICE: if you create a scope 'A' of container 'root' then Logger of A !== Logger of root.
+
+> [!IMPORTANT]
+> Singleton means one instance per scope. If you create a scope `A` of container `root`, then `Logger` of `A` !== `Logger` of `root`.
 
 ```typescript
 import 'reflect-metadata';
@@ -1827,17 +1897,39 @@ describe('Singleton', function () {
 ```
 
 ### Arguments
+
 Sometimes you want to bind some arguments to provider. This is what `ArgsProvider` is for.
+
 - `provider(setArgs('someArgument'))`
 - `provider(setArgsFn((container) => [container.resolve(Logger), 'someValue']))`
 - `Provider.fromClass(Logger).pipe(setArgs('someArgument'))`
-- NOTICE: args from this provider has higher priority than args from `resolve` method.
+
+### Token as argument
+
+When you pass an `InjectionToken` via `token.args(...)`, the container resolves it before the value reaches the constructor. Bare constructors are **not** auto-resolved — wrap a class in `ClassToken` to opt into resolution.
+
+- `ServiceToken.args(ValueToken)` — `ValueToken` is resolved from the container, its value is passed as arg
+- `ServiceToken.args(new ClassToken(SomeService))` — `SomeService` is constructed by the container
+- `ServiceToken.args('literal')` — literal value passed directly
 
 ### Positional arg injection with `args(index)`
-Use `@inject(args(index))` to explicitly bind a constructor parameter to a positional argument from `ProviderOptions`. This is useful when combining `setArgsFn(resolveByArgs)` with token-based arg passing.
+
+Constructor parameters that should pick up positional args from `ProviderOptions` must be annotated with `@inject(args(index))`. Parameters without `@inject` resolve to `undefined`.
+
 - `@inject(args(0))` — resolves the first element of the `args` array passed at resolution time
 - Works together with `token.args(...)` to pass typed dependencies through the args context
 
+### Immutable token chaining
+
+`token.args(...)`, `token.argsFn(...)`, and `token.lazy()` all return **new token instances** — the parent token is never mutated. This allows the same token to be specialized in multiple independent ways (one-way linked list: parent → many children).
+
+```typescript
+const ApiToken = new SingleToken<IApiClient>('IApiClient');
+// Independent children — ApiToken is unchanged
+const dataToken = ApiToken.args('https://data.api.com', 5000);
+const userToken = ApiToken.args('https://users.api.com', 1000);
+```
+
 ```typescript
 import {
   setArgs,
@@ -1845,10 +1937,10 @@ import {
   bindTo,
   Container,
   inject,
+  args,
   MultiCache,
   register,
   Registration as R,
-  resolveByArgs,
   singleton,
   SingleToken,
 } from 'ts-ioc-container';
@@ -1871,7 +1963,7 @@ describe('ArgsProvider', function () {
   describe('Static Arguments', () => {
     it('can pass static arguments to constructor', function () {
       class FileLogger {
-        constructor(public filename: string) {}
+        constructor(@inject(args(0)) public filename: string) {}
       }
 
       // Pre-configure the logger with a filename
@@ -1884,7 +1976,7 @@ describe('ArgsProvider', function () {
 
     it('prioritizes provided args over resolve args', function () {
       class Logger {
-        constructor(public context: string) {}
+        constructor(@inject(args(0)) public context: string) {}
       }
 
       // 'FixedContext' wins over any runtime args
@@ -1905,7 +1997,7 @@ describe('ArgsProvider', function () {
       }
 
       class Service {
-        constructor(public env: string) {}
+        constructor(@inject(args(0)) public env: string) {}
       }
 
       const root = createContainer()
@@ -1945,17 +2037,18 @@ describe('ArgsProvider', function () {
       name = 'TodoRepository';
     }
 
-    // EntityManager is generic - it works with ANY repository
-    // We use argsFn(resolveByArgs) to tell it to look at the arguments passed to .args()
+    // EntityManager is generic - it works with ANY repository.
+    // The repository is the first arg passed via `EntityManagerToken.args(...)`.
+    // `@inject(args(0))` reads it; the container auto-resolves InjectionToken args
+    // before they reach the constructor.
     const EntityManagerToken = new SingleToken<EntityManager>('EntityManager');
 
     @register(
       bindTo(EntityManagerToken),
-      setArgsFn(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) {}
+      constructor(@inject(args(0)) public repository: IRepository) {}
     }
 
     class App {
@@ -2007,7 +2100,12 @@ describe('ArgsProvider', function () {
 ```
 
 ### Visibility
+
 Sometimes you want to hide dependency if somebody wants to resolve it from certain scope. This uses `ScopeAccessRule` to control access.
+
+> [!IMPORTANT]
+> Use `scope()` to decide where a provider is registered. Use `scopeAccess()` to decide which invocation scopes can see an already registered provider.
+
 - `provider(scopeAccess(({ invocationScope, providerScope }) => invocationScope === providerScope))` - dependency will be accessible only from the scope where it's registered
 - `Provider.fromClass(Logger).pipe(scopeAccess(({ invocationScope, providerScope }) => invocationScope === providerScope))`
 
@@ -2103,7 +2201,9 @@ describe('Visibility', function () {
 ```
 
 ### Alias
+
 Alias is needed to group keys
+
 - `@register(asAlias('logger'))` helper assigns `logger` alias to registration.
 - `by.aliases((it) => it.has('logger') || it.has('a'))` resolves dependencies which have `logger` or `a` aliases
 - `Provider.fromClass(Logger).pipe(alias('logger'))`
@@ -2248,11 +2348,14 @@ describe('alias', () => {
 ```
 
 ### Decorator
+
 Sometimes you want to decorate you class with some logic. This is what `DecoratorProvider` is for.
+
 - `provider(decorate((instance, container) => new LoggerDecorator(instance)))`
 
 ```typescript
 import {
+  args,
   bindTo,
   Container,
   decorate,
@@ -2306,7 +2409,7 @@ describe('Decorator Pattern', () => {
   // Decorator: Wraps any IRepository with logging behavior
   class LoggingRepository implements IRepository {
     constructor(
-      private repository: IRepository,
+      @inject(args(0)) private repository: IRepository,
       @inject(s.token('Logger').lazy()) private logger: Logger,
     ) {}
 
@@ -2362,7 +2465,9 @@ describe('Decorator Pattern', () => {
 ```
 
 ## Registration
+
 Registration is provider factory which registers provider in container.
+
 - `@register(asKey('logger'))`
 - `Registration.fromClass(Logger).to('logger')`
 - `Registration.fromClass(Logger)`
@@ -2370,6 +2475,7 @@ Registration is provider factory which registers provider in container.
 - `Registration.fromFn((container, ...args) => container.resolve(Logger, {args}))`
 
 ### Key
+
 Sometimes you want to register provider with certain key. This is what `key` is for.
 
 - by default, key is class name
@@ -2462,7 +2568,9 @@ describe('Registration module', function () {
 ```
 
 ### Scope
+
 Sometimes you need to register provider only in scope which matches to certain condition and their sub scopes. Especially if you want to register dependency as singleton for some tags, for example `root`. This uses `ScopeMatchRule` to determine which scopes should have the provider.
+
 - `@register(scope((container) => container.hasTag('root'))` - register provider only in root scope
 - `Registration.fromClass(Logger).when((container) => container.hasTag('root'))`
 
@@ -2504,6 +2612,7 @@ describe('ScopeProvider', function () {
 ```
 
 ## Module
+
 Sometimes you want to encapsulate registration logic in separate module. This is what `IContainerModule` is for.
 
 ```typescript
@@ -2627,9 +2736,11 @@ describe('Container Modules', function () {
 ```
 
 ## Hook
+
 Sometimes you need to invoke methods after construct or dispose of class. This is what hooks are for.
 
 ### OnConstruct
+
 ```typescript
 import {
   AddOnConstructHookModule,
@@ -2690,6 +2801,7 @@ describe('onConstruct', function () {
 ```
 
 ### OnDispose
+
 ```typescript
 import {
   AddOnDisposeHookModule,
@@ -2804,8 +2916,11 @@ describe('inject property', () => {
 
 ## Error
 
+The product-facing error contract is described in
+`specs/epics/errors-and-boundaries.md` and executed by
+`__tests__/specs/errors-and-boundaries.spec.ts`.
+
 - [DependencyNotFoundError.ts](..%2F..%2Flib%2Ferrors%2FDependencyNotFoundError.ts)
 - [MethodNotImplementedError.ts](..%2F..%2Flib%2Ferrors%2FMethodNotImplementedError.ts)
 - [DependencyMissingKeyError.ts](..%2F..%2Flib%2Ferrors%2FDependencyMissingKeyError.ts)
 - [ContainerDisposedError.ts](..%2F..%2Flib%2Ferrors%2FContainerDisposedError.ts)
-