@navios/di 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,93 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] - 2025-12-21
+
+### Added
+
+- **Priority System for Multiple Registrations**: Services can now be registered with priority levels. Higher priority wins when multiple registrations exist for the same token
+  - New `priority` option in `@Injectable()` decorator
+  - `Registry.getAll(token)` method to retrieve all registrations sorted by priority
+  - `FactoryRecord` now includes `priority` field
+- **Unified Storage Architecture**: Replaced multiple storage classes with a single `UnifiedStorage` class
+  - Replaces `HolderManager`, `SingletonStorage`, `RequestStorage`, and `RequestContext`
+  - Simpler mental model: one storage class regardless of scope
+  - Reverse dependency index for O(1) dependent lookups (vs O(n) iteration)
+  - Consistent API across all scopes
+- **Enhanced Testing Utilities**: Significantly extended `TestContainer` with new assertion helpers
+  - Fluent binding API extended with `toFactory()` method
+  - Assertion helpers: `expectResolved()`, `expectNotResolved()`, `expectSingleton()`, `expectTransient()`, `expectRequestScoped()`
+  - Lifecycle assertions: `expectInitialized()`, `expectDestroyed()`, `expectNotDestroyed()`
+  - Method call tracking: `recordMethodCall()`, `expectCalled()`, `expectCalledWith()`, `expectCallCount()`, `getMethodCalls()`, `getServiceStats()`
+  - Dependency graph utilities: `getDependencyGraph()`, `getSimplifiedDependencyGraph()`
+- **New UnitTestContainer**: Strict isolated unit testing container with auto-tracking
+  - Automatic method call tracking via Proxy
+  - Strict mode (default): unregistered dependencies throw errors
+  - Auto-mocking mode: unregistered dependencies return mock proxies
+  - Simplified provider-based configuration
+- **Enhanced Error Messages**: Extended `DIErrorCode` enum with 8 new error types
+  - `TokenValidationError`: Zod schema validation failed
+  - `TokenSchemaRequiredError`: Schema args required but not provided
+  - `ClassNotInjectable`: Missing `@Injectable` decorator
+  - `ScopeMismatchError`: Wrong container for scope
+  - `PriorityConflictError`: Multiple same-priority registrations
+  - `StorageError`: Storage operation failed
+  - `InitializationError`: Service init failed
+  - `DependencyResolutionError`: Dependency chain error
+- **New Internal Components**:
+  - `NameResolver`: Generates deterministic instance names
+  - `ScopeTracker`: Tracks and validates scope relationships
+  - `AbstractContainer`: Base class for containers
+- **New Container Methods**: Direct access to internal components
+  - `getStorage()`: Returns `UnifiedStorage`
+  - `getServiceInitializer()`: Returns `ServiceInitializer`
+  - `getServiceInvalidator()`: Returns `ServiceInvalidator`
+  - `getTokenResolver()`: Returns `TokenResolver`
+  - `getNameResolver()`: Returns `NameResolver`
+  - `getScopeTracker()`: Returns `ScopeTracker`
+  - `getEventBus()`: Returns `LifecycleEventBus`
+  - `getInstanceResolver()`: Returns `InstanceResolver`
+
+### Changed
+
+- **BREAKING**: `ServiceLocator` wrapper class removed
+  - Container now uses components directly (no ServiceLocator wrapper)
+  - `container.getServiceLocator()` method removed
+  - Use direct component access methods instead (e.g., `container.getStorage()`)
+- **BREAKING**: Internal component renames
+  - `Instantiator` → `ServiceInitializer`
+  - `Invalidator` → `ServiceInvalidator`
+  - `TokenProcessor` → `TokenResolver`
+  - `HolderManager` → `UnifiedStorage`
+  - `SingletonStorage` → `UnifiedStorage` (same class, different instance)
+  - `RequestStorage` → `UnifiedStorage` (same class, different instance)
+  - `RequestContext` → merged into `UnifiedStorage`
+- **BREAKING**: `Container.removeActiveRequest()` renamed to `Container.removeRequestId()`
+- **Registry Changes**:
+  - `Registry.set()` now accepts optional `priority` parameter (5 params instead of 4)
+  - `Registry` stores `FactoryRecord[]` per token instead of single `FactoryRecord`
+  - `FactoryRecord` interface extended with `priority: number` field
+- **Scope Error Handling**: Request scope violations now throw dedicated `ScopeMismatchError` with structured context instead of generic errors
+- **Build Configuration**: Updated tsdown config with external dependencies
+  - Node build: external `node:async_hooks` and `zod`
+  - Browser build: external `zod`
+
+### Performance
+
+- **Reverse Dependency Index**: O(1) dependent lookup during invalidation (vs O(n) iteration)
+- **Priority Cache**: Registry maintains `highestPriority` Map for fast access to winning registration
+- **Unified Storage**: Single storage class eliminates wrapper overhead
+- **No ServiceLocator Wrapper**: Container directly uses components, reducing indirection
+
+### Migration
+
+- Replace `container.getServiceLocator()` with direct component access methods
+- Replace `container.removeActiveRequest()` with `container.removeRequestId()`
+- Update internal class references if you were using them directly
+- Consider using new testing utilities (`TestContainer` assertions, `UnitTestContainer`)
+- Use `priority` option for service registration if needed
+- Use `registry.getAll(token)` if you need all registrations, not just highest priority
+
 ## [0.8.0] - 2025-12-21
 
 ### Added

package/README.md

@@ -10,10 +10,12 @@ A powerful, type-safe dependency injection library for TypeScript applications.
 - **Factory Pattern**: Create instances using factory classes
 - **Injection Tokens**: Flexible token-based dependency resolution
 - **Scoped Instances**: Singleton, transient, and request scopes
+- **Priority System**: Register multiple services per token with priority levels
 - **Async/Sync Injection**: Both synchronous and asynchronous dependency resolution
 - **Container API**: Simple container-based API for dependency management
 - **Request Context**: Manage request-scoped services with automatic cleanup via ScopedContainer
 - **Circular Dependency Detection**: Automatic detection and helpful error messages for circular dependencies
+- **Enhanced Testing**: Comprehensive test utilities with assertion helpers and auto-tracking
 
 ## Installation
 
@@ -132,6 +134,13 @@ class RequestService {}
 @Injectable({ token: MyToken })
 class TokenizedService {}
 
+// With priority (higher priority wins when multiple registrations exist)
+@Injectable({ priority: 100 })
+class DefaultService {}
+
+@Injectable({ priority: 200 }) // This wins
+class OverrideService {}
+
 // With schema for constructor arguments
 const configSchema = z.object({
   host: z.string(),
@@ -426,6 +435,9 @@ import { Container, Registry } from '@navios/di'
 
 const customRegistry = new Registry()
 const container = new Container(customRegistry)
+
+// Get all registrations for a token (sorted by priority, highest first)
+const allRegistrations = customRegistry.getAll(MyToken)
 ```
 
 ### Error Handling
@@ -444,6 +456,13 @@ try {
       case DIErrorCode.InstanceDestroying:
         console.error('Service is being destroyed')
         break
+      case DIErrorCode.ScopeMismatchError:
+        console.error('Wrong container for scope')
+        break
+      case DIErrorCode.TokenValidationError:
+        console.error('Token validation failed')
+        break
+      // ... and more error codes
     }
   }
 }
@@ -469,11 +488,21 @@ const newService = await container.get(MyService)
 - `dispose(): Promise<void>` - Clean up all resources
 - `clear(): Promise<void>` - Clear all instances and bindings
 - `isRegistered(token: any): boolean` - Check if service is registered
-- `getServiceLocator(): ServiceLocator` - Get underlying service locator
+- `calculateInstanceName(token, args?): string | null` - Calculate the instance name for a token (returns null for unresolved factory tokens or validation errors)
 - `getRegistry(): Registry` - Get the registry
 - `beginRequest(requestId: string, metadata?, priority?): ScopedContainer` - Begin request context
 - `getActiveRequestIds(): ReadonlySet<string>` - Get active request IDs
 - `hasActiveRequest(requestId: string): boolean` - Check if request is active
+- `removeRequestId(requestId: string): void` - Remove a request ID from tracking
+- **Component Access Methods** (for advanced usage):
+  - `getStorage(): UnifiedStorage` - Get storage instance
+  - `getServiceInitializer(): ServiceInitializer` - Get service initializer
+  - `getServiceInvalidator(): ServiceInvalidator` - Get service invalidator
+  - `getTokenResolver(): TokenResolver` - Get token resolver
+  - `getNameResolver(): NameResolver` - Get name resolver
+  - `getScopeTracker(): ScopeTracker` - Get scope tracker
+  - `getEventBus(): LifecycleEventBus` - Get event bus
+  - `getInstanceResolver(): InstanceResolver` - Get instance resolver
 
 ### ScopedContainer
 
@@ -483,12 +512,12 @@ const newService = await container.get(MyService)
 - `dispose(): Promise<void>` - Alias for endRequest()
 - `ready(): Promise<void>` - Wait for pending operations
 - `isRegistered(token: any): boolean` - Check if service is registered
+- `calculateInstanceName(token, args?): string | null` - Calculate the instance name for a token (returns null for unresolved factory tokens or validation errors)
 - `getMetadata(key: string): any` - Get request metadata
 - `setMetadata(key: string, value: any): void` - Set request metadata
-- `addInstance(token: InjectionToken, instance: any): void` - Add pre-prepared instance
 - `getRequestId(): string` - Get the request ID
 - `getParent(): Container` - Get the parent container
-- `getRequestContextHolder(): RequestContext` - Get the underlying request context
+- `getStorage(): UnifiedStorage` - Get the underlying storage instance
 
 ### Injectable Decorator
 
@@ -498,6 +527,7 @@ const newService = await container.get(MyService)
   - `token?: InjectionToken` - Custom injection token
   - `schema?: ZodSchema` - Zod schema for constructor arguments
   - `registry?: Registry` - Custom registry
+  - `priority?: number` - Priority level (higher wins when multiple registrations exist, default: 0)
 - Note: Cannot use both `token` and `schema` options together
 
 ### Factory Decorator
@@ -528,24 +558,21 @@ const newService = await container.get(MyService)
 - `OnServiceInit` - Implement `onServiceInit(): Promise<void> | void`
 - `OnServiceDestroy` - Implement `onServiceDestroy(): Promise<void> | void`
 
-### RequestContext
+### Registry
 
-- `requestId: string` - Unique request identifier
-- `priority: number` - Priority for resolution
-- `metadata: Map<string, any>` - Request metadata
-- `createdAt: number` - Creation timestamp
-- `addInstance(token, instance): void` - Add pre-prepared instance
-- `get(instanceName): InstanceHolder | undefined` - Get instance holder
-- `set(instanceName, holder): void` - Set instance holder
-- `has(instanceName): boolean` - Check if instance exists
-- `clear(): void` - Clear all instances
-- `getMetadata(key): any` - Get metadata value
-- `setMetadata(key, value): void` - Set metadata value
+- `set(token, scope, target, type, priority?): void` - Register a service factory
+- `get(token): FactoryRecord` - Get the highest priority factory record for a token
+- `getAll(token): FactoryRecord[]` - Get all factory records for a token (sorted by priority, highest first)
+- `has(token): boolean` - Check if a token is registered
+- `delete(token): void` - Remove all registrations for a token
+- `updateScope(token, scope): boolean` - Update the scope of an already registered factory
 
 ## Testing
 
 ### TestContainer
 
+`TestContainer` extends `Container` with enhanced testing utilities, including fluent binding API, assertion helpers, method call tracking, and dependency graph inspection.
+
 ```typescript
 import { TestContainer } from '@navios/di/testing'
 
@@ -557,19 +584,89 @@ describe('UserService', () => {
   })
 
   afterEach(async () => {
-    await container.dispose()
+    await container.clear()
   })
 
   it('should create user', async () => {
-    // Bind mock
+    // Fluent binding API
     container.bind(DatabaseService).toValue({
       save: vi.fn().mockResolvedValue({ id: '1' }),
     })
+    
+    // Or bind to class
+    container.bind(UserService).toClass(MockUserService)
+    
+    // Or bind to factory
+    container.bind(ConfigToken).toFactory(() => ({ apiKey: 'test' }))
 
     const userService = await container.get(UserService)
     const user = await userService.create({ name: 'John' })
 
     expect(user.id).toBe('1')
+    
+    // Assertion helpers
+    container.expectResolved(UserService)
+    container.expectSingleton(UserService)
+    container.expectInitialized(UserService)
+    
+    // Method call tracking
+    container.recordMethodCall(UserService, 'create', [{ name: 'John' }], user)
+    container.expectCalled(UserService, 'create')
+    container.expectCalledWith(UserService, 'create', [{ name: 'John' }])
+    container.expectCallCount(UserService, 'create', 1)
+    
+    // Dependency graph inspection
+    const graph = container.getDependencyGraph()
+    console.log(graph)
+  })
+})
+```
+
+### UnitTestContainer
+
+`UnitTestContainer` provides strict isolated unit testing with automatic method call tracking via Proxy. Only services explicitly provided can be resolved.
+
+```typescript
+import { UnitTestContainer } from '@navios/di/testing'
+
+describe('UserService Unit Tests', () => {
+  let container: UnitTestContainer
+
+  beforeEach(() => {
+    container = new UnitTestContainer({
+      providers: [
+        { token: UserService, useClass: MockUserService },
+        { token: ConfigToken, useValue: { apiUrl: 'test' } },
+        { token: ApiClient, useFactory: () => new MockApiClient() },
+      ],
+    })
+  })
+
+  afterEach(async () => {
+    await container.dispose()
+  })
+
+  it('should track method calls automatically', async () => {
+    const service = await container.get(UserService)
+    await service.findUser('123')
+
+    // Auto-tracked assertions (no manual recording needed)
+    container.expectCalled(UserService, 'findUser')
+    container.expectCalledWith(UserService, 'findUser', ['123'])
+    container.expectNotCalled(UserService, 'deleteUser')
+  })
+
+  it('should throw on unregistered dependencies (strict mode)', async () => {
+    // Strict mode (default): unregistered dependencies throw
+    await expect(container.get(UnregisteredService)).rejects.toThrow(DIError)
+  })
+
+  it('should auto-mock unregistered dependencies', async () => {
+    // Enable auto-mocking mode
+    container.enableAutoMocking()
+    const mock = await container.get(UnregisteredService)
+    container.expectAutoMocked(UnregisteredService)
+    container.disableAutoMocking()
   })
 })
 ```
@@ -584,6 +681,9 @@ describe('UserService', () => {
 6. **Prefer singletons** - Unless you specifically need new instances each time
 7. **Use factories** - For complex object creation logic
 8. **Leverage ScopedContainer** - For request-scoped data and cleanup
+9. **Use priority system** - When you need multiple implementations of the same token, use priority to control which one wins
+10. **Use TestContainer for integration tests** - Provides comprehensive assertion helpers and dependency graph inspection
+11. **Use UnitTestContainer for unit tests** - Provides strict isolation and automatic method call tracking
 
 ## License
 

package/lib/browser/container/abstract-container.d.mts

@@ -0,0 +1,112 @@
+import { BoundInjectionToken, ClassType, ClassTypeWithArgument, FactoryInjectionToken, InjectionToken, InjectionTokenSchemaType } from "../token/injection-token.mjs";
+import { Join, UnionToArray } from "../utils/types.mjs";
+import { IContainer } from "../interfaces/container.interface.mjs";
+import { InjectableScope } from "../enums/injectable-scope.enum.mjs";
+import { Factorable } from "../interfaces/factory.interface.mjs";
+import { Registry } from "../token/registry.mjs";
+import { NameResolver } from "../internal/core/name-resolver.mjs";
+import { ServiceInvalidator } from "../internal/core/service-invalidator.mjs";
+import { TokenResolver } from "../internal/core/token-resolver.mjs";
+import { UnifiedStorage } from "../internal/holder/unified-storage.mjs";
+import { ZodType, z } from "zod/v4";
+
+//#region src/container/abstract-container.d.mts
+
+/**
+ * Abstract base class for dependency injection containers.
+ *
+ * Provides shared implementation for common container operations.
+ * Both Container and ScopedContainer extend this class.
+ */
+declare abstract class AbstractContainer implements IContainer {
+  /**
+   * The default scope used when adding instances without explicit registration.
+   */
+  protected abstract readonly defaultScope: InjectableScope;
+  /**
+   * The request ID for scoped containers, undefined for root container.
+   */
+  protected abstract readonly requestId: string | undefined;
+  /**
+   * Gets the storage for this container.
+   */
+  abstract getStorage(): UnifiedStorage;
+  /**
+   * Gets the registry for this container.
+   */
+  protected abstract getRegistry(): Registry;
+  /**
+   * Gets the token resolver.
+   */
+  protected abstract getTokenResolver(): TokenResolver;
+  /**
+   * Gets the name resolver.
+   */
+  protected abstract getNameResolver(): NameResolver;
+  /**
+   * Gets the service invalidator.
+   */
+  protected abstract getServiceInvalidator(): ServiceInvalidator;
+  /**
+   * Gets an instance from the container.
+   */
+  abstract get<T extends ClassType>(token: T): InstanceType<T> extends Factorable<infer R> ? Promise<R> : Promise<InstanceType<T>>;
+  abstract get<T extends ClassTypeWithArgument<R>, R>(token: T, args: R): Promise<InstanceType<T>>;
+  abstract get<T, S extends InjectionTokenSchemaType>(token: InjectionToken<T, S>, args: z.input<S>): Promise<T>;
+  abstract get<T, S extends InjectionTokenSchemaType, R extends boolean>(token: InjectionToken<T, S, R>): R extends false ? Promise<T> : S extends ZodType<infer Type> ? `Error: Your token requires args: ${Join<UnionToArray<keyof Type>, ', '>}` : 'Error: Your token requires args';
+  abstract get<T>(token: InjectionToken<T, undefined>): Promise<T>;
+  abstract get<T>(token: BoundInjectionToken<T, any>): Promise<T>;
+  abstract get<T>(token: FactoryInjectionToken<T, any>): Promise<T>;
+  /**
+   * Invalidates a service and its dependencies.
+   */
+  abstract invalidate(service: unknown): Promise<void>;
+  /**
+   * Disposes the container and cleans up all resources.
+   */
+  abstract dispose(): Promise<void>;
+  /**
+   * Calculates the instance name for a given token and optional arguments.
+   *
+   * @internal
+   * @param token The class type, InjectionToken, BoundInjectionToken, or FactoryInjectionToken
+   * @param args Optional arguments (ignored for BoundInjectionToken which uses its bound value)
+   * @returns The calculated instance name string, or null if the token is a FactoryInjectionToken that is not yet resolved
+   */
+  calculateInstanceName(token: ClassType | InjectionToken<any, any> | BoundInjectionToken<any, any> | FactoryInjectionToken<any, any>, args?: unknown): string | null;
+  /**
+   * Checks if a service is registered in the container.
+   */
+  isRegistered(token: any): boolean;
+  /**
+   * Waits for all pending operations to complete.
+   */
+  ready(): Promise<void>;
+  /**
+   * @internal
+   * Attempts to get an instance synchronously if it already exists.
+   */
+  tryGetSync<T>(token: any, args?: any): T | null;
+  /**
+   * @internal
+   * Internal method for getting instances synchronously with configurable storage.
+   */
+  protected tryGetSyncFromStorage<T>(token: any, args: any, storage: UnifiedStorage, requestId?: string): T | null;
+  /**
+   * Adds an instance to the container.
+   * Accepts class types, InjectionTokens, and BoundInjectionTokens.
+   * Rejects InjectionTokens with required schemas (use BoundInjectionToken instead).
+   *
+   * @param token The class type, InjectionToken, or BoundInjectionToken to register the instance for
+   * @param instance The instance to store
+   */
+  addInstance<T>(token: ClassType | InjectionToken<T, any> | BoundInjectionToken<T, any>, instance: T): void;
+  /**
+   * @internal
+   * Internal method for adding instances with configurable scope and storage.
+   */
+  protected addInstanceToStorage<T>(token: ClassType | InjectionToken<T, any> | BoundInjectionToken<T, any>, instance: T, storage: UnifiedStorage, scope: InjectableScope, requestId?: string): void;
+}
+//#endregion
+export { AbstractContainer };
+//# sourceMappingURL=abstract-container.d.mts.map

package/lib/browser/container/abstract-container.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-container.d.mts","names":[],"sources":["../../../src/container/abstract-container.mts"],"sourcesContent":[],"mappings":"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"}

package/lib/browser/container/abstract-container.mjs

@@ -0,0 +1,100 @@
+import { InjectableScope } from "../enums/injectable-scope.enum.mjs";
+import { InjectableType } from "../enums/injectable-type.enum.mjs";
+import { BoundInjectionToken, InjectionToken } from "../token/injection-token.mjs";
+import { DIError, DIErrorCode } from "../errors/di-error.mjs";
+import { InstanceStatus } from "../internal/holder/instance-holder.mjs";
+import { StubFactoryClass } from "../internal/stub-factory-class.mjs";
+
+//#region src/container/abstract-container.mts
+/**
+* Abstract base class for dependency injection containers.
+*
+* Provides shared implementation for common container operations.
+* Both Container and ScopedContainer extend this class.
+*/ var AbstractContainer = class {
+	/**
+	* Calculates the instance name for a given token and optional arguments.
+	*
+	* @internal
+	* @param token The class type, InjectionToken, BoundInjectionToken, or FactoryInjectionToken
+	* @param args Optional arguments (ignored for BoundInjectionToken which uses its bound value)
+	* @returns The calculated instance name string, or null if the token is a FactoryInjectionToken that is not yet resolved
+	*/ calculateInstanceName(token, args) {
+		const [err, { actualToken, validatedArgs }] = this.getTokenResolver().validateAndResolveTokenArgs(token, args);
+		if (err) {
+			if (err instanceof DIError && err.code === DIErrorCode.FactoryTokenNotResolved) return null;
+			if (err instanceof DIError && err.code === DIErrorCode.TokenValidationError) return null;
+		}
+		const realToken = this.getTokenResolver().getRealToken(actualToken);
+		const registry = this.getRegistry();
+		const scope = registry.has(realToken) ? registry.get(realToken).scope : this.defaultScope;
+		return this.getNameResolver().generateInstanceName(actualToken, validatedArgs, scope === InjectableScope.Request ? this.requestId : void 0, scope);
+	}
+	/**
+	* Checks if a service is registered in the container.
+	*/ isRegistered(token) {
+		const realToken = this.getTokenResolver().getRegistryToken(token);
+		return this.getRegistry().has(realToken);
+	}
+	/**
+	* Waits for all pending operations to complete.
+	*/ async ready() {
+		await this.getServiceInvalidator().readyWithStorage(this.getStorage());
+	}
+	/**
+	* @internal
+	* Attempts to get an instance synchronously if it already exists.
+	*/ tryGetSync(token, args) {
+		return this.tryGetSyncFromStorage(token, args, this.getStorage(), this.requestId);
+	}
+	/**
+	* @internal
+	* Internal method for getting instances synchronously with configurable storage.
+	*/ tryGetSyncFromStorage(token, args, storage, requestId) {
+		const tokenResolver = this.getTokenResolver();
+		const realToken = tokenResolver.getRegistryToken(token);
+		const registry = this.getRegistry();
+		const scope = registry.has(realToken) ? registry.get(realToken).scope : InjectableScope.Singleton;
+		try {
+			const instanceName = this.getNameResolver().generateInstanceName(tokenResolver.normalizeToken(token), args, requestId, scope);
+			const result = storage.get(instanceName);
+			if (result && result[0] === void 0 && result[1]) {
+				const holder = result[1];
+				if (holder.status === InstanceStatus.Created) return holder.instance;
+			}
+		} catch {}
+		return null;
+	}
+	/**
+	* Adds an instance to the container.
+	* Accepts class types, InjectionTokens, and BoundInjectionTokens.
+	* Rejects InjectionTokens with required schemas (use BoundInjectionToken instead).
+	*
+	* @param token The class type, InjectionToken, or BoundInjectionToken to register the instance for
+	* @param instance The instance to store
+	*/ addInstance(token, instance) {
+		this.addInstanceToStorage(token, instance, this.getStorage(), this.defaultScope, this.requestId);
+	}
+	/**
+	* @internal
+	* Internal method for adding instances with configurable scope and storage.
+	*/ addInstanceToStorage(token, instance, storage, scope, requestId) {
+		if (token instanceof InjectionToken) {
+			if (token.schema) {
+				if (token.schema?.def?.type !== "optional") throw DIError.tokenSchemaRequiredError(token.name);
+			}
+		}
+		const tokenResolver = this.getTokenResolver();
+		const registry = this.getRegistry();
+		const normalizedToken = tokenResolver.normalizeToken(token);
+		const realToken = tokenResolver.getRegistryToken(token);
+		if (typeof token === "function" && !registry.has(realToken)) registry.set(realToken, scope, token, InjectableType.Class);
+		else if (!registry.has(realToken)) registry.set(realToken, scope, StubFactoryClass, InjectableType.Class, -1);
+		const instanceName = this.getNameResolver().generateInstanceName(normalizedToken, normalizedToken instanceof BoundInjectionToken ? normalizedToken.value : void 0, requestId, scope);
+		storage.storeInstance(instanceName, instance);
+	}
+};
+
+//#endregion
+export { AbstractContainer };
+//# sourceMappingURL=abstract-container.mjs.map

package/lib/browser/container/abstract-container.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-container.mjs","names":["InjectableScope","InjectableType","DIError","DIErrorCode","InstanceStatus","StubFactoryClass","BoundInjectionToken","InjectionToken","AbstractContainer","calculateInstanceName","token","args","tokenResolver","getTokenResolver","err","actualToken","validatedArgs","validateAndResolveTokenArgs","code","FactoryTokenNotResolved","TokenValidationError","realToken","getRealToken","registry","getRegistry","scope","has","get","defaultScope","getNameResolver","generateInstanceName","Request","requestId","undefined","isRegistered","getRegistryToken","ready","getServiceInvalidator","readyWithStorage","getStorage","tryGetSync","tryGetSyncFromStorage","storage","Singleton","instanceName","normalizeToken","result","holder","status","Created","instance","addInstance","addInstanceToStorage","schema","schemaType","def","type","tokenSchemaRequiredError","name","normalizedToken","set","Class","value","storeInstance"],"sources":["../../../src/container/abstract-container.mts"],"sourcesContent":["import type { z, ZodType } from 'zod/v4'\n\nimport type { IContainer } from '../interfaces/container.interface.mjs'\nimport type { Factorable } from '../interfaces/factory.interface.mjs'\nimport type { NameResolver } from '../internal/core/name-resolver.mjs'\nimport type { ServiceInvalidator } from '../internal/core/service-invalidator.mjs'\nimport type { TokenResolver } from '../internal/core/token-resolver.mjs'\nimport type {\n  ClassType,\n  ClassTypeWithArgument,\n  InjectionTokenSchemaType,\n} from '../token/injection-token.mjs'\nimport type { Registry } from '../token/registry.mjs'\nimport type { Join, UnionToArray } from '../utils/types.mjs'\n\nimport { InjectableScope, InjectableType } from '../enums/index.mjs'\nimport { DIError, DIErrorCode } from '../errors/index.mjs'\nimport { InstanceStatus } from '../internal/holder/instance-holder.mjs'\nimport { UnifiedStorage } from '../internal/holder/unified-storage.mjs'\nimport { StubFactoryClass } from '../internal/index.mjs'\nimport {\n  BoundInjectionToken,\n  FactoryInjectionToken,\n  InjectionToken,\n} from '../token/injection-token.mjs'\n\n/**\n * Abstract base class for dependency injection containers.\n *\n * Provides shared implementation for common container operations.\n * Both Container and ScopedContainer extend this class.\n */\nexport abstract class AbstractContainer implements IContainer {\n  /**\n   * The default scope used when adding instances without explicit registration.\n   */\n  protected abstract readonly defaultScope: InjectableScope\n\n  /**\n   * The request ID for scoped containers, undefined for root container.\n   */\n  protected abstract readonly requestId: string | undefined\n\n  // ============================================================================\n  // ABSTRACT METHODS - Must be implemented by subclasses\n  // ============================================================================\n\n  /**\n   * Gets the storage for this container.\n   */\n  abstract getStorage(): UnifiedStorage\n\n  /**\n   * Gets the registry for this container.\n   */\n  protected abstract getRegistry(): Registry\n\n  /**\n   * Gets the token resolver.\n   */\n  protected abstract getTokenResolver(): TokenResolver\n\n  /**\n   * Gets the name resolver.\n   */\n  protected abstract getNameResolver(): NameResolver\n\n  /**\n   * Gets the service invalidator.\n   */\n  protected abstract getServiceInvalidator(): ServiceInvalidator\n\n  /**\n   * Gets an instance from the container.\n   */\n  // #1 Simple class\n  abstract get<T extends ClassType>(\n    token: T,\n  ): InstanceType<T> extends Factorable<infer R>\n    ? Promise<R>\n    : Promise<InstanceType<T>>\n  // #1.1 Simple class with args\n  abstract get<T extends ClassTypeWithArgument<R>, R>(\n    token: T,\n    args: R,\n  ): Promise<InstanceType<T>>\n  // #2 Token with required Schema\n  abstract get<T, S extends InjectionTokenSchemaType>(\n    token: InjectionToken<T, S>,\n    args: z.input<S>,\n  ): Promise<T>\n  // #3 Token with optional Schema\n  abstract get<T, S extends InjectionTokenSchemaType, R extends boolean>(\n    token: InjectionToken<T, S, R>,\n  ): R extends false\n    ? Promise<T>\n    : S extends ZodType<infer Type>\n      ? `Error: Your token requires args: ${Join<\n          UnionToArray<keyof Type>,\n          ', '\n        >}`\n      : 'Error: Your token requires args'\n  // #4 Token with no Schema\n  abstract get<T>(token: InjectionToken<T, undefined>): Promise<T>\n  abstract get<T>(token: BoundInjectionToken<T, any>): Promise<T>\n  abstract get<T>(token: FactoryInjectionToken<T, any>): Promise<T>\n\n  /**\n   * Invalidates a service and its dependencies.\n   */\n  abstract invalidate(service: unknown): Promise<void>\n\n  /**\n   * Disposes the container and cleans up all resources.\n   */\n  abstract dispose(): Promise<void>\n\n  // ============================================================================\n  // SHARED IMPLEMENTATIONS\n  // ============================================================================\n\n  /**\n   * Calculates the instance name for a given token and optional arguments.\n   *\n   * @internal\n   * @param token The class type, InjectionToken, BoundInjectionToken, or FactoryInjectionToken\n   * @param args Optional arguments (ignored for BoundInjectionToken which uses its bound value)\n   * @returns The calculated instance name string, or null if the token is a FactoryInjectionToken that is not yet resolved\n   */\n  calculateInstanceName(\n    token:\n      | ClassType\n      | InjectionToken<any, any>\n      | BoundInjectionToken<any, any>\n      | FactoryInjectionToken<any, any>,\n    args?: unknown,\n  ): string | null {\n    const tokenResolver = this.getTokenResolver()\n\n    // Use validateAndResolveTokenArgs to handle token normalization and arg resolution\n    const [err, { actualToken, validatedArgs }] =\n      tokenResolver.validateAndResolveTokenArgs(token, args)\n\n    if (err) {\n      // Return null if factory token is not resolved\n      if (\n        err instanceof DIError &&\n        err.code === DIErrorCode.FactoryTokenNotResolved\n      ) {\n        return null\n      }\n\n      // Return null if validation fails (can't calculate name with invalid args)\n      if (\n        err instanceof DIError &&\n        err.code === DIErrorCode.TokenValidationError\n      ) {\n        return null\n      }\n    }\n\n    // Get the real token for registry lookup to determine scope\n    const realToken = this.getTokenResolver().getRealToken(actualToken)\n\n    const registry = this.getRegistry()\n\n    // Get scope from registry, or use default scope if not registered\n    const scope = registry.has(realToken)\n      ? registry.get(realToken).scope\n      : this.defaultScope\n\n    // Generate instance name using the name resolver with actual token and validated args\n    return this.getNameResolver().generateInstanceName(\n      actualToken,\n      validatedArgs,\n      scope === InjectableScope.Request ? this.requestId : undefined,\n      scope,\n    )\n  }\n\n  /**\n   * Checks if a service is registered in the container.\n   */\n  isRegistered(token: any): boolean {\n    const realToken = this.getTokenResolver().getRegistryToken(token)\n    return this.getRegistry().has(realToken)\n  }\n\n  /**\n   * Waits for all pending operations to complete.\n   */\n  async ready(): Promise<void> {\n    await this.getServiceInvalidator().readyWithStorage(this.getStorage())\n  }\n\n  /**\n   * @internal\n   * Attempts to get an instance synchronously if it already exists.\n   */\n  tryGetSync<T>(token: any, args?: any): T | null {\n    return this.tryGetSyncFromStorage(\n      token,\n      args,\n      this.getStorage(),\n      this.requestId,\n    )\n  }\n\n  /**\n   * @internal\n   * Internal method for getting instances synchronously with configurable storage.\n   */\n  protected tryGetSyncFromStorage<T>(\n    token: any,\n    args: any,\n    storage: UnifiedStorage,\n    requestId?: string,\n  ): T | null {\n    const tokenResolver = this.getTokenResolver()\n    const realToken = tokenResolver.getRegistryToken(token)\n    const registry = this.getRegistry()\n    const scope = registry.has(realToken)\n      ? registry.get(realToken).scope\n      : InjectableScope.Singleton\n\n    try {\n      const instanceName = this.getNameResolver().generateInstanceName(\n        tokenResolver.normalizeToken(token),\n        args,\n        requestId,\n        scope,\n      )\n\n      const result = storage.get(instanceName)\n      if (result && result[0] === undefined && result[1]) {\n        const holder = result[1]\n        if (holder.status === InstanceStatus.Created) {\n          return holder.instance as T\n        }\n      }\n    } catch {\n      // Ignore error\n    }\n\n    return null\n  }\n\n  /**\n   * Adds an instance to the container.\n   * Accepts class types, InjectionTokens, and BoundInjectionTokens.\n   * Rejects InjectionTokens with required schemas (use BoundInjectionToken instead).\n   *\n   * @param token The class type, InjectionToken, or BoundInjectionToken to register the instance for\n   * @param instance The instance to store\n   */\n  addInstance<T>(\n    token: ClassType | InjectionToken<T, any> | BoundInjectionToken<T, any>,\n    instance: T,\n  ): void {\n    this.addInstanceToStorage(\n      token,\n      instance,\n      this.getStorage(),\n      this.defaultScope,\n      this.requestId,\n    )\n  }\n\n  /**\n   * @internal\n   * Internal method for adding instances with configurable scope and storage.\n   */\n  protected addInstanceToStorage<T>(\n    token: ClassType | InjectionToken<T, any> | BoundInjectionToken<T, any>,\n    instance: T,\n    storage: UnifiedStorage,\n    scope: InjectableScope,\n    requestId?: string,\n  ): void {\n    // Check if token is an InjectionToken with required schema\n    // BoundInjectionToken is allowed (it already has a value bound)\n    if (token instanceof InjectionToken) {\n      // Check if schema exists and is required (not optional)\n      if (token.schema) {\n        const schemaType = (token.schema as ZodType)?.def?.type\n        if (schemaType !== 'optional') {\n          throw DIError.tokenSchemaRequiredError(token.name)\n        }\n      }\n    }\n\n    const tokenResolver = this.getTokenResolver()\n    const registry = this.getRegistry()\n\n    // Normalize the token\n    const normalizedToken = tokenResolver.normalizeToken(token)\n    const realToken = tokenResolver.getRegistryToken(token)\n\n    // If it's a class type and not registered, register it with the given scope\n    if (typeof token === 'function' && !registry.has(realToken)) {\n      registry.set(realToken, scope, token, InjectableType.Class)\n    } else if (!registry.has(realToken)) {\n      // Set a stub factory class to avoid errors when getting instances of unregistered factory tokens\n      registry.set(\n        realToken,\n        scope,\n        StubFactoryClass,\n        InjectableType.Class,\n        // Lowest priority to avoid conflicts with other registered tokens\n        -1,\n      )\n    }\n\n    // Generate instance name with the given scope\n    const instanceName = this.getNameResolver().generateInstanceName(\n      normalizedToken,\n      normalizedToken instanceof BoundInjectionToken\n        ? normalizedToken.value\n        : undefined,\n      requestId,\n      scope,\n    )\n\n    // Store the instance\n    storage.storeInstance(instanceName, instance)\n  }\n}\n"],"mappings":"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"}