ts-ioc-container 47.5.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,6 +317,7 @@ 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.
 
 > [!IMPORTANT]
@@ -349,6 +421,7 @@ 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
@@ -458,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
@@ -542,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
@@ -643,6 +718,7 @@ describe('hasRegistration', function () {
 ```
 
 ### Dispose
+
 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
@@ -653,7 +729,7 @@ Sometimes you want to dispose a container or scope. For example, when a request,
 
 ```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
@@ -672,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;
 
@@ -689,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'] });
@@ -714,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 } {
@@ -751,6 +824,7 @@ 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.
@@ -886,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 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
@@ -901,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
@@ -1073,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
@@ -1096,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);
@@ -1116,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);
@@ -1214,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}`);
       }
@@ -1226,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(),
@@ -1263,6 +1323,7 @@ describe('lazy registerPipe', () => {
    * - Report generators
    */
   describe('real-world example - feature flags', () => {
+    @register(singleton())
     class FeatureFlagService {
       constructor() {
         initLog.push('FeatureFlagService initialized');
@@ -1302,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));
 
@@ -1316,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));
 
@@ -1333,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
@@ -1340,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
@@ -1361,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';
 }
@@ -1379,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);
@@ -1393,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
@@ -1424,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`;
@@ -1433,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) {}
 
@@ -1445,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'));
@@ -1467,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'] });
@@ -1481,16 +1544,18 @@ describe('SimpleInjector', function () {
 ```
 
 ### Proxy
+
 This type of injector injects dependencies as dictionary `Record<string, unknown>`.
 
 - **`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`
 
 ```typescript
-import { Container, ProxyInjector, Registration as R } from 'ts-ioc-container';
+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}`;
@@ -1517,9 +1582,9 @@ 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');
 
@@ -1527,6 +1592,7 @@ describe('ProxyInjector', function () {
   });
 
   it('should expose runtime args through the reserved "args" property', function () {
+    @register(bindTo('database'))
     class Database {}
 
     class ReportGenerator {
@@ -1544,8 +1610,8 @@ describe('ProxyInjector', function () {
     }
 
     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));
 
     const generator = container.resolve<ReportGenerator>('ReportGenerator', {
       args: ['PDF'],
@@ -1582,6 +1648,7 @@ describe('ProxyInjector', function () {
 ```
 
 ## Provider
+
 Provider is dependency factory which creates dependency.
 
 - `Provider.fromClass(Logger)`
@@ -1590,10 +1657,12 @@ Provider is dependency factory which creates dependency.
 
 ```typescript
 import {
+  args,
   setArgs,
   setArgsFn,
   bindTo,
   Container,
+  inject,
   lazy,
   Provider,
   register,
@@ -1667,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(
@@ -1681,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(
@@ -1735,6 +1804,7 @@ 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.
@@ -1827,23 +1897,30 @@ 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'))`
-- Use `setArgsFn(resolveByArgs)` to resolve `InjectionToken` args at resolution time (tokens are resolved, primitives pass through)
 
 ### Token as argument
-When passing args via `token.args(...)`, if an argument is an `InjectionToken` and the provider uses `setArgsFn(resolveByArgs)`, the token is resolved to its value rather than wrapped as a constant.
+
+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
@@ -1860,10 +1937,10 @@ import {
   bindTo,
   Container,
   inject,
+  args,
   MultiCache,
   register,
   Registration as R,
-  resolveByArgs,
   singleton,
   SingleToken,
 } from 'ts-ioc-container';
@@ -1886,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
@@ -1899,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
@@ -1920,7 +1997,7 @@ describe('ArgsProvider', function () {
       }
 
       class Service {
-        constructor(public env: string) {}
+        constructor(@inject(args(0)) public env: string) {}
       }
 
       const root = createContainer()
@@ -1960,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 {
@@ -2022,6 +2100,7 @@ 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]
@@ -2122,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'))`
@@ -2267,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,
@@ -2325,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,
     ) {}
 
@@ -2381,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)`
@@ -2389,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
@@ -2481,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'))`
 
@@ -2523,6 +2612,7 @@ describe('ScopeProvider', function () {
 ```
 
 ## Module
+
 Sometimes you want to encapsulate registration logic in separate module. This is what `IContainerModule` is for.
 
 ```typescript
@@ -2646,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,
@@ -2709,6 +2801,7 @@ describe('onConstruct', function () {
 ```
 
 ### OnDispose
+
 ```typescript
 import {
   AddOnDisposeHookModule,
@@ -2823,6 +2916,10 @@ 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)

package/cjm/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SingleAliasToken = exports.toGroupAlias = exports.GroupAliasToken = exports.InjectionToken = exports.HooksRunner = exports.AddOnDisposeHookModule = exports.onDispose = exports.onDisposeHooksRunner = exports.AddOnConstructHookModule = exports.onConstruct = exports.onConstructHooksRunner = exports.injectProp = exports.createHookContext = exports.createHookContextFactory = exports.HookContext = exports.hasHooks = exports.hook = exports.getHooks = exports.UnexpectedHookResultError = exports.ContainerDisposedError = exports.MethodNotImplementedError = exports.DependencyMissingKeyError = exports.DependencyNotFoundError = exports.Registration = exports.bindTo = exports.register = exports.scope = exports.decorate = exports.MultiCache = exports.multiCache = exports.SingletonProvider = exports.singleton = exports.Provider = exports.resolveByArgs = exports.ProviderDecorator = exports.setArgs = exports.setArgsFn = exports.lazy = exports.scopeAccess = exports.ProxyInjector = exports.SimpleInjector = exports.MetadataInjector = exports.Injector = exports.argsFn = exports.args = exports.resolveArgs = exports.inject = exports.EmptyContainer = exports.Container = exports.isDependencyKey = void 0;
-exports.resolveConstructor = exports.Is = exports.pipe = exports.select = exports.once = exports.shallowCache = exports.debounce = exports.throttle = exports.handleAsyncError = exports.handleError = exports.getMethodTags = exports.methodTag = exports.getMethodLabels = exports.methodLabel = exports.getMethodMeta = exports.methodMeta = exports.getParamTags = exports.paramTag = exports.getParamLabels = exports.paramLabel = exports.getParamMeta = exports.paramMeta = exports.getClassTags = exports.classTag = exports.getClassLabels = exports.classLabel = exports.getClassMeta = exports.classMeta = exports.GroupInstanceToken = exports.ConstantToken = exports.FunctionToken = exports.SingleToken = exports.ClassToken = exports.toSingleAlias = void 0;
+exports.toSingleAlias = exports.SingleAliasToken = exports.toGroupAlias = exports.GroupAliasToken = exports.InjectionToken = exports.HooksRunner = exports.AddOnDisposeHookModule = exports.onDispose = exports.onDisposeHooksRunner = exports.AddOnConstructHookModule = exports.onConstruct = exports.onConstructHooksRunner = exports.injectProp = exports.createHookContext = exports.createHookContextFactory = exports.HookContext = exports.hasHooks = exports.hook = exports.getHooks = exports.UnexpectedHookResultError = exports.ContainerDisposedError = exports.MethodNotImplementedError = exports.DependencyMissingKeyError = exports.DependencyNotFoundError = exports.Registration = exports.bindTo = exports.register = exports.scope = exports.decorate = exports.MultiCache = exports.multiCache = exports.SingletonProvider = exports.singleton = exports.Provider = exports.ProviderDecorator = exports.setArgs = exports.setArgsFn = exports.lazy = exports.scopeAccess = exports.ProxyInjector = exports.SimpleInjector = exports.MetadataInjector = exports.Injector = exports.argsFn = exports.args = exports.resolveArgs = exports.inject = exports.EmptyContainer = exports.Container = exports.isDependencyKey = void 0;
+exports.resolveConstructor = exports.Is = exports.pipe = exports.select = exports.once = exports.shallowCache = exports.debounce = exports.throttle = exports.handleAsyncError = exports.handleError = exports.getMethodTags = exports.methodTag = exports.getMethodLabels = exports.methodLabel = exports.getMethodMeta = exports.methodMeta = exports.getParamTags = exports.paramTag = exports.getParamLabels = exports.paramLabel = exports.getParamMeta = exports.paramMeta = exports.getClassTags = exports.classTag = exports.getClassLabels = exports.classLabel = exports.getClassMeta = exports.classMeta = exports.GroupInstanceToken = exports.ConstantToken = exports.FunctionToken = exports.SingleToken = exports.ClassToken = void 0;
 // Containers
 var IContainer_1 = require("./container/IContainer");
 Object.defineProperty(exports, "isDependencyKey", { enumerable: true, get: function () { return IContainer_1.isDependencyKey; } });
@@ -30,7 +30,6 @@ Object.defineProperty(exports, "lazy", { enumerable: true, get: function () { re
 Object.defineProperty(exports, "setArgsFn", { enumerable: true, get: function () { return IProvider_1.setArgsFn; } });
 Object.defineProperty(exports, "setArgs", { enumerable: true, get: function () { return IProvider_1.setArgs; } });
 Object.defineProperty(exports, "ProviderDecorator", { enumerable: true, get: function () { return IProvider_1.ProviderDecorator; } });
-Object.defineProperty(exports, "resolveByArgs", { enumerable: true, get: function () { return IProvider_1.resolveByArgs; } });
 var Provider_1 = require("./provider/Provider");
 Object.defineProperty(exports, "Provider", { enumerable: true, get: function () { return Provider_1.Provider; } });
 var SingletonProvider_1 = require("./provider/SingletonProvider");

package/cjm/injector/inject.js

@@ -4,7 +4,6 @@ exports.resolveArgs = exports.argsFn = exports.args = exports.inject = void 0;
 const InjectionToken_1 = require("../token/InjectionToken");
 const ConstantToken_1 = require("../token/ConstantToken");
 const toToken_1 = require("../token/toToken");
-const array_1 = require("../utils/array");
 const basic_1 = require("../utils/basic");
 const parameter_1 = require("../metadata/parameter");
 const hookMetaKey = (methodName = 'constructor') => `inject:${methodName}`;
@@ -18,14 +17,11 @@ const args = (index) => (c, { args = [] }) => {
 exports.args = args;
 const argsFn = (fn) => (c, options) => fn(options.args ?? []);
 exports.argsFn = argsFn;
+const resolveTokens = (scope, deps) => deps.map((v) => ((0, InjectionToken_1.isInjectionToken)(v) ? v : new ConstantToken_1.ConstantToken(v))).map((t) => t.resolve(scope));
 const resolveArgs = (Target, methodName) => {
-    const argsTokens = (0, parameter_1.getParamMeta)(hookMetaKey(methodName), Target);
+    const argsMetaTokens = (0, parameter_1.getParamMeta)(hookMetaKey(methodName), Target);
     return (scope, { args = [], lazy }) => {
-        const depsTokens = args.map((v) => {
-            return !(0, InjectionToken_1.isInjectionToken)(v) ? new ConstantToken_1.ConstantToken(v) : v;
-        });
-        const allTokens = (0, array_1.fillEmptyIndexes)(argsTokens, depsTokens);
-        return allTokens.map((fn) => fn.resolve(scope, { args, lazy }));
+        return argsMetaTokens.map((fn) => fn.resolve(scope, { args: resolveTokens(scope, args), lazy }));
     };
 };
 exports.resolveArgs = resolveArgs;

package/cjm/provider/IProvider.js

@@ -1,23 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProviderDecorator = exports.lazy = exports.scopeAccess = exports.resolveByArgs = exports.setArgsFn = exports.setArgs = void 0;
+exports.ProviderDecorator = exports.lazy = exports.scopeAccess = exports.setArgsFn = exports.setArgs = void 0;
 const ProviderPipe_1 = require("./ProviderPipe");
-const InjectionToken_1 = require("../token/InjectionToken");
-const basic_1 = require("../utils/basic");
 const setArgs = (...extraArgs) => (0, ProviderPipe_1.registerPipe)((p) => p.setArgs(() => extraArgs));
 exports.setArgs = setArgs;
 const setArgsFn = (fn) => (0, ProviderPipe_1.registerPipe)((p) => p.setArgs(fn));
 exports.setArgsFn = setArgsFn;
-const resolveByArgs = (s, { args = [] } = {}) => args.map((d) => {
-    if (d instanceof InjectionToken_1.InjectionToken) {
-        return d.resolve(s);
-    }
-    if (basic_1.Is.constructor(d)) {
-        return s.resolve(d);
-    }
-    return d;
-});
-exports.resolveByArgs = resolveByArgs;
 const scopeAccess = (rule) => (0, ProviderPipe_1.registerPipe)((p) => p.setAccessRule(rule));
 exports.scopeAccess = scopeAccess;
 const lazy = () => (0, ProviderPipe_1.registerPipe)((p) => p.lazy());

package/cjm/utils/array.js

@@ -1,20 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Filter = void 0;
-exports.fillEmptyIndexes = fillEmptyIndexes;
 exports.Filter = {
     exclude: (arr) => {
         const excludeSet = arr instanceof Array ? new Set(arr) : arr;
         return (v) => !excludeSet.has(v);
     },
 };
-function fillEmptyIndexes(baseArr, insertArr) {
-    const a = [...baseArr];
-    const b = [...insertArr];
-    for (let i = 0; i < a.length; i++) {
-        if (a[i] === undefined) {
-            a[i] = b.shift();
-        }
-    }
-    return a.concat(b);
-}

package/esm/index.js

@@ -9,7 +9,7 @@ export { MetadataInjector } from './injector/MetadataInjector';
 export { SimpleInjector } from './injector/SimpleInjector';
 export { ProxyInjector } from './injector/ProxyInjector';
 // Providers
-export { scopeAccess, lazy, setArgsFn, setArgs, ProviderDecorator, resolveByArgs, } from './provider/IProvider';
+export { scopeAccess, lazy, setArgsFn, setArgs, ProviderDecorator, } from './provider/IProvider';
 export { Provider } from './provider/Provider';
 export { singleton, SingletonProvider } from './provider/SingletonProvider';
 export { multiCache, MultiCache } from './provider/Cache';

package/esm/injector/inject.js

@@ -1,7 +1,6 @@
 import { isInjectionToken } from '../token/InjectionToken';
 import { ConstantToken } from '../token/ConstantToken';
 import { toToken } from '../token/toToken';
-import { fillEmptyIndexes } from '../utils/array';
 import { Is } from '../utils/basic';
 import { getParamMeta, paramMeta } from '../metadata/parameter';
 const hookMetaKey = (methodName = 'constructor') => `inject:${methodName}`;
@@ -12,13 +11,10 @@ export const args = (index) => (c, { args = [] }) => {
     return args[index];
 };
 export const argsFn = (fn) => (c, options) => fn(options.args ?? []);
+const resolveTokens = (scope, deps) => deps.map((v) => (isInjectionToken(v) ? v : new ConstantToken(v))).map((t) => t.resolve(scope));
 export const resolveArgs = (Target, methodName) => {
-    const argsTokens = getParamMeta(hookMetaKey(methodName), Target);
+    const argsMetaTokens = getParamMeta(hookMetaKey(methodName), Target);
     return (scope, { args = [], lazy }) => {
-        const depsTokens = args.map((v) => {
-            return !isInjectionToken(v) ? new ConstantToken(v) : v;
-        });
-        const allTokens = fillEmptyIndexes(argsTokens, depsTokens);
-        return allTokens.map((fn) => fn.resolve(scope, { args, lazy }));
+        return argsMetaTokens.map((fn) => fn.resolve(scope, { args: resolveTokens(scope, args), lazy }));
     };
 };

package/esm/provider/IProvider.js

@@ -1,17 +1,6 @@
 import { isProviderPipe, registerPipe } from './ProviderPipe';
-import { InjectionToken } from '../token/InjectionToken';
-import { Is } from '../utils/basic';
 export const setArgs = (...extraArgs) => registerPipe((p) => p.setArgs(() => extraArgs));
 export const setArgsFn = (fn) => registerPipe((p) => p.setArgs(fn));
-export const resolveByArgs = (s, { args = [] } = {}) => args.map((d) => {
-    if (d instanceof InjectionToken) {
-        return d.resolve(s);
-    }
-    if (Is.constructor(d)) {
-        return s.resolve(d);
-    }
-    return d;
-});
 export const scopeAccess = (rule) => registerPipe((p) => p.setAccessRule(rule));
 export const lazy = () => registerPipe((p) => p.lazy());
 export class ProviderDecorator {

package/esm/utils/array.js

@@ -4,13 +4,3 @@ export const Filter = {
         return (v) => !excludeSet.has(v);
     },
 };
-export function fillEmptyIndexes(baseArr, insertArr) {
-    const a = [...baseArr];
-    const b = [...insertArr];
-    for (let i = 0; i < a.length; i++) {
-        if (a[i] === undefined) {
-            a[i] = b.shift();
-        }
-    }
-    return a.concat(b);
-}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ts-ioc-container",
-  "version": "47.5.0",
-  "description": "Typescript IoC container",
+  "version": "48.0.0",
+  "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"
   ],
@@ -21,10 +21,24 @@
     "inversion-of-control",
     "container",
     "typescript",
+    "typescript-di",
+    "typescript-ioc",
+    "dependency-injection-container",
     "ioc",
     "di",
+    "ioc-container",
+    "tsyringe-alternative",
+    "inversify-alternative",
+    "awilix-alternative",
+    "clean-api",
+    "no-global-container",
     "scope",
+    "scoped-dependencies",
     "hook",
+    "lifecycle-hooks",
+    "decorators",
+    "lazy-injection",
+    "service-container",
     "inject"
   ],
   "directories": {
@@ -47,12 +61,14 @@
     "generate:docs": "scripts/generate-readme/generate-readme.ts && git add README.md",
     "build": "npm run build:cjm && npm run build:esm && npm run build:types",
     "test": "vitest run",
+    "test:spec": "vitest run __tests__/specs",
+    "bench:spec": "vitest bench __benchmarks__/specs/*.bench.ts",
     "test:coverage": "vitest run --coverage --coverage.reporter=lcov",
     "type-check": "tsc --noEmit",
     "type-check:watch": "tsc --noEmit --watch",
     "commit": "cz",
     "format": "prettier --write \"**/*.ts\"",
-    "lint": "eslint lib/**/*.ts  __tests__/**/*.ts scripts/**/*.ts",
+    "lint": "eslint lib/**/*.ts __tests__/**/*.ts __benchmarks__/**/*.ts scripts/**/*.ts",
     "lint:fix": "npm run lint --fix",
     "audit": "npm audit",
     "prepare": "husky",
@@ -90,6 +106,7 @@
     "rimraf": "6.1.3",
     "semantic-release": "^25.0.2",
     "tsx": "^4.21.0",
+    "tsyringe": "^4.10.0",
     "typescript": "5.8.3",
     "unplugin-swc": "^1.5.9",
     "vite": "^6.4.1",

package/typings/index.d.ts

@@ -6,7 +6,7 @@ export { type IInjector, type InjectOptions, type IInjectFnResolver, Injector }
 export { MetadataInjector } from './injector/MetadataInjector';
 export { SimpleInjector } from './injector/SimpleInjector';
 export { ProxyInjector } from './injector/ProxyInjector';
-export { type ResolveDependency, type IProvider, scopeAccess, lazy, setArgsFn, setArgs, type ArgsFn, ProviderDecorator, resolveByArgs, type IMapper, type ProviderOptions, } from './provider/IProvider';
+export { type ResolveDependency, type IProvider, scopeAccess, lazy, setArgsFn, setArgs, type ArgsFn, ProviderDecorator, type IMapper, type ProviderOptions, } from './provider/IProvider';
 export { Provider } from './provider/Provider';
 export { singleton, SingletonProvider } from './provider/SingletonProvider';
 export { type Cache, multiCache, MultiCache } from './provider/Cache';

package/typings/provider/IProvider.d.ts

@@ -26,7 +26,6 @@ export interface IProvider<T = any> {
 }
 export declare const setArgs: <T>(...extraArgs: unknown[]) => ProviderPipe<T>;
 export declare const setArgsFn: <T>(fn: ArgsFn) => ProviderPipe<T>;
-export declare const resolveByArgs: ArgsFn;
 export declare const scopeAccess: <T>(rule: ScopeAccessRule) => ProviderPipe<T>;
 export declare const lazy: <T>() => ProviderPipe<T>;
 export declare abstract class ProviderDecorator<T> implements IProvider<T> {

package/typings/utils/array.d.ts

@@ -1,4 +1,3 @@
 export declare const Filter: {
     exclude: <T>(arr: Set<T> | T[]) => (v: T) => boolean;
 };
-export declare function fillEmptyIndexes<T>(baseArr: (T | undefined)[], insertArr: T[]): T[];