@navios/di 0.8.0 → 0.9.0

package/src/errors/di-error.mts

@@ -1,9 +1,20 @@
+import type { InjectionTokenSchemaType } from '../token/injection-token.mjs'
+import type { FactoryRecord } from '../token/registry.mjs'
+
 export enum DIErrorCode {
   FactoryNotFound = 'FactoryNotFound',
   FactoryTokenNotResolved = 'FactoryTokenNotResolved',
   InstanceNotFound = 'InstanceNotFound',
   InstanceDestroying = 'InstanceDestroying',
   CircularDependency = 'CircularDependency',
+  TokenValidationError = 'TokenValidationError',
+  TokenSchemaRequiredError = 'TokenSchemaRequiredError',
+  ClassNotInjectable = 'ClassNotInjectable',
+  ScopeMismatchError = 'ScopeMismatchError',
+  PriorityConflictError = 'PriorityConflictError',
+  StorageError = 'StorageError',
+  InitializationError = 'InitializationError',
+  DependencyResolutionError = 'DependencyResolutionError',
   UnknownError = 'UnknownError',
 }
 
@@ -17,6 +28,7 @@ export class DIError extends Error {
   ) {
     super(message)
     this.context = context
+    this.name = 'DIError'
   }
 
   // Static factory methods for common error types
@@ -73,4 +85,88 @@ export class DIError extends Error {
       { cycle },
     )
   }
+
+  static tokenValidationError(
+    message: string,
+    schema: InjectionTokenSchemaType | undefined,
+    value: unknown,
+  ): DIError {
+    return new DIError(DIErrorCode.TokenValidationError, message, {
+      schema,
+      value,
+    })
+  }
+
+  static tokenSchemaRequiredError(token: string | symbol | unknown): DIError {
+    return new DIError(
+      DIErrorCode.TokenSchemaRequiredError,
+      `Token ${token?.toString() ?? 'unknown'} requires schema arguments and cannot be used with addInstance. Use BoundInjectionToken or provide arguments when resolving.`,
+      { token },
+    )
+  }
+
+  static classNotInjectable(className: string): DIError {
+    return new DIError(
+      DIErrorCode.ClassNotInjectable,
+      `Class ${className} is not decorated with @Injectable.`,
+      { className },
+    )
+  }
+
+  static scopeMismatchError(
+    token: string | symbol | unknown,
+    expectedScope: string,
+    actualScope: string,
+  ): DIError {
+    return new DIError(
+      DIErrorCode.ScopeMismatchError,
+      `Scope mismatch for ${token?.toString() ?? 'unknown'}: expected ${expectedScope}, got ${actualScope}`,
+      { token, expectedScope, actualScope },
+    )
+  }
+
+  static priorityConflictError(
+    token: string | symbol | unknown,
+    records: FactoryRecord[],
+  ): DIError {
+    return new DIError(
+      DIErrorCode.PriorityConflictError,
+      `Priority conflict for ${token?.toString() ?? 'unknown'}: multiple bindings with same priority`,
+      { token, records },
+    )
+  }
+
+  static storageError(
+    message: string,
+    operation: string,
+    instanceName?: string,
+  ): DIError {
+    return new DIError(DIErrorCode.StorageError, `Storage error: ${message}`, {
+      operation,
+      instanceName,
+    })
+  }
+
+  static initializationError(
+    serviceName: string,
+    error: Error | string,
+  ): DIError {
+    return new DIError(
+      DIErrorCode.InitializationError,
+      `Service ${serviceName} initialization failed: ${error instanceof Error ? error.message : error}`,
+      { serviceName, error },
+    )
+  }
+
+  static dependencyResolutionError(
+    serviceName: string,
+    dependencyName: string,
+    error: Error | string,
+  ): DIError {
+    return new DIError(
+      DIErrorCode.DependencyResolutionError,
+      `Failed to resolve dependency ${dependencyName} for service ${serviceName}: ${error instanceof Error ? error.message : error}`,
+      { serviceName, dependencyName, error },
+    )
+  }
 }

package/src/event-emitter.mts

@@ -2,7 +2,8 @@
 /* eslint-disable @typescript-eslint/no-empty-object-type */
 /* eslint-disable @typescript-eslint/no-unsafe-function-type */
 
-import { Injectable, InjectableScope } from './index.mjs'
+import { Injectable } from './decorators/index.mjs'
+import { InjectableScope } from './enums/index.mjs'
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 export type EventsConfig = {
@@ -17,33 +18,8 @@ export type EventsArgs<
   Name extends EventsNames<Events>,
 > = Events[Name] extends any[] ? Events[Name] : []
 
-export type ChannelEmitter<
-  Events extends EventsConfig,
-  Ns extends string,
-  E extends EventsNames<Events>,
-> = {
-  emit<Args extends EventsArgs<Events, E>>(
-    ns: Ns,
-    event: E,
-    ...args: Args
-  ): Promise<any>
-}
-
-export interface EventEmitterInterface<Events extends EventsConfig> {
-  on<E extends EventsNames<Events>, Args extends EventsArgs<Events, E>>(
-    event: E,
-    listener: (...args: Args) => void | Promise<void>,
-  ): () => void
-  emit<E extends EventsNames<Events>, Args extends EventsArgs<Events, E>>(
-    event: E,
-    ...args: Args
-  ): void | Promise<void>
-}
-
 @Injectable({ scope: InjectableScope.Transient })
-export class EventEmitter<Events extends EventsConfig = {}>
-  implements EventEmitterInterface<Events>
-{
+export class EventEmitter<Events extends EventsConfig = {}> {
   private listeners: Map<EventsNames<Events>, Set<Function>> = new Map()
 
   on<E extends EventsNames<Events>, Args extends EventsArgs<Events, E>>(

package/src/index.mts

@@ -1,157 +1,10 @@
-/**
- * @navios/di - Dependency Injection Library
- *
- * This library provides a flexible dependency injection system with support for:
- * - Singleton and request-scoped services
- * - Factory-based and class-based service instantiation
- * - Circular dependency detection
- * - Schema validation for service arguments
- * - Lifecycle hooks (onServiceInit, onServiceDestroy)
- */
-
-// ============================================================================
-// PUBLIC API - Container
-// ============================================================================
-
-export { Container } from './container/container.mjs'
-export { ScopedContainer } from './container/scoped-container.mjs'
-
-// ============================================================================
-// PUBLIC API - Tokens
-// ============================================================================
-
-export {
-  InjectionToken,
-  BoundInjectionToken,
-  FactoryInjectionToken,
-  type ClassType,
-  type ClassTypeWithoutArguments,
-  type ClassTypeWithArgument,
-  type ClassTypeWithOptionalArgument,
-  type ClassTypeWithInstance,
-  type ClassTypeWithInstanceAndArgument,
-  type ClassTypeWithInstanceAndOptionalArgument,
-  type AnyInjectableType,
-  type InjectionTokenType,
-  type InjectionTokenSchemaType,
-} from './token/injection-token.mjs'
-
-export {
-  Registry,
-  globalRegistry,
-  type FactoryRecord,
-} from './token/registry.mjs'
-
-// ============================================================================
-// PUBLIC API - Decorators
-// ============================================================================
-
+export * from './container/index.mjs'
 export * from './decorators/index.mjs'
-
-// ============================================================================
-// PUBLIC API - Enums
-// ============================================================================
-
 export * from './enums/index.mjs'
-
-// ============================================================================
-// PUBLIC API - Interfaces
-// ============================================================================
-
-export * from './interfaces/index.mjs'
-
-// ============================================================================
-// PUBLIC API - Errors
-// ============================================================================
-
 export * from './errors/index.mjs'
-
-// ============================================================================
-// PUBLIC API - Utilities
-// ============================================================================
-
-export * from './utils/index.mjs'
-
-// ============================================================================
-// PUBLIC API - Symbols
-// ============================================================================
-
+export * from './interfaces/index.mjs'
+export * from './internal/index.mjs'
 export * from './symbols/index.mjs'
-
-// ============================================================================
-// PUBLIC API - Event Emitter
-// ============================================================================
-
-export { EventEmitter } from './event-emitter.mjs'
-
-// ============================================================================
-// PUBLIC API - Injectors
-// ============================================================================
-
-export {
-  defaultInjectors,
-  asyncInject,
-  inject,
-  optional,
-  wrapSyncInit,
-  provideFactoryContext,
-} from './injectors.mjs'
-
-// ============================================================================
-// INTERNAL API (exported for advanced use cases)
-// ============================================================================
-
-// Context types
-export type { FactoryContext } from './internal/context/factory-context.mjs'
-export {
-  type RequestContext,
-  type RequestContextHolder,
-  DefaultRequestContext,
-  createRequestContext,
-} from './internal/context/request-context.mjs'
-export {
-  type ResolutionContextData,
-  withResolutionContext,
-  getCurrentResolutionContext,
-  withoutResolutionContext,
-} from './internal/context/resolution-context.mjs'
-
-// Holder types
-export {
-  InstanceStatus,
-  type InstanceHolder,
-  type InstanceEffect,
-  type InstanceDestroyListener,
-  type InstanceHolderCreating,
-  type InstanceHolderCreated,
-  type InstanceHolderDestroying,
-  type InstanceHolderError,
-} from './internal/holder/instance-holder.mjs'
-
-export {
-  BaseHolderManager,
-  type HolderReadyResult,
-} from './internal/holder/base-holder-manager.mjs'
-
-export { HolderManager } from './internal/holder/holder-manager.mjs'
-
-export {
-  type HolderGetResult,
-  type IHolderStorage,
-} from './internal/holder/holder-storage.interface.mjs'
-
-export { SingletonStorage } from './internal/holder/singleton-storage.mjs'
-
-export { RequestStorage } from './internal/holder/request-storage.mjs'
-
-// Lifecycle
-export { LifecycleEventBus } from './internal/lifecycle/lifecycle-event-bus.mjs'
-
-export { CircularDetector } from './internal/lifecycle/circular-detector.mjs'
-
-// Core engine
-export { ServiceLocator } from './internal/core/service-locator.mjs'
-export { InstanceResolver } from './internal/core/instance-resolver.mjs'
-export { Instantiator } from './internal/core/instantiator.mjs'
-export { Invalidator } from './internal/core/invalidator.mjs'
-export { TokenProcessor } from './internal/core/token-processor.mjs'
+export * from './token/index.mjs'
+export * from './utils/index.mjs'
+export * from './event-emitter.mjs'

package/src/interfaces/container.interface.mts

@@ -62,6 +62,19 @@ export interface IContainer {
    */
   isRegistered(token: any): boolean
 
+  /**
+   * 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
+
   /**
    * Disposes the container and cleans up all resources.
    */

package/src/interfaces/factory.interface.mts

@@ -1,4 +1,4 @@
-import { z } from 'zod/v4'
+import type { z } from 'zod/v4'
 
 import type { FactoryContext } from '../internal/context/factory-context.mjs'
 import type { InjectionTokenSchemaType } from '../token/injection-token.mjs'

package/src/interfaces/index.mts

@@ -1,4 +1,4 @@
 export * from './container.interface.mjs'
 export * from './factory.interface.mjs'
-export * from './on-service-init.interface.mjs'
 export * from './on-service-destroy.interface.mjs'
+export * from './on-service-init.interface.mjs'

package/src/internal/context/async-local-storage.mts

@@ -1,3 +1,5 @@
+import type { IAsyncLocalStorage } from './async-local-storage.types.mjs'
+
 import { AsyncLocalStorage } from 'node:async_hooks'
 
 /**
@@ -14,8 +16,6 @@ import { AsyncLocalStorage } from 'node:async_hooks'
  * and works with both ESM and CJS builds.
  */
 
-import type { IAsyncLocalStorage } from './async-local-storage.types.mjs'
-
 export type { IAsyncLocalStorage }
 
 const isProduction = process.env.NODE_ENV === 'production'
@@ -66,3 +66,4 @@ export function createAsyncLocalStorage<T>(): IAsyncLocalStorage<T> {
 export function isUsingNativeAsyncLocalStorage(): boolean {
   return getModule().isUsingNativeAsyncLocalStorage()
 }
+

package/src/internal/context/async-local-storage.types.mts

@@ -5,3 +5,4 @@ export interface IAsyncLocalStorage<T> {
   run<R>(store: T, fn: () => R): R
   getStore(): T | undefined
 }
+

package/src/internal/context/factory-context.mts

@@ -16,3 +16,4 @@ export interface FactoryContext {
   container: IContainer
   addDestroyListener: (listener: () => void) => void
 }
+

package/src/internal/context/index.mts

@@ -1,3 +1,5 @@
+export * from './async-local-storage.mjs'
+export * from './async-local-storage.types.mjs'
 export * from './factory-context.mjs'
 export * from './resolution-context.mjs'
-export * from './request-context.mjs'
+export * from './service-initialization-context.mjs'

package/src/internal/context/resolution-context.mts

@@ -79,3 +79,4 @@ export function withoutResolutionContext<T>(fn: () => T): T {
     fn,
   )
 }
+

package/src/internal/context/service-initialization-context.mts

@@ -0,0 +1,43 @@
+import type { InjectableScope } from '../../enums/index.mjs'
+import type { IContainer } from '../../interfaces/container.interface.mjs'
+import type { Injectors } from '../../utils/index.mjs'
+
+/**
+ * Context provided to injectors during service initialization.
+ *
+ * Extends FactoryContext with additional tracking information about
+ * the service being initialized, its dependencies, and scope.
+ * Used for scope upgrade tracking and dependency management.
+ */
+export interface ServiceInitializationContext {
+  inject: Injectors['asyncInject']
+  /**
+   * The container instance for dependency resolution.
+   * This may be either a Container or ScopedContainer.
+   */
+  container: IContainer
+  addDestroyListener: (listener: () => void) => void
+  getDestroyListeners: () => (() => void)[]
+  /**
+   * The name of the service being initialized.
+   */
+  serviceName: string
+  /**
+   * Set of dependency names that this service depends on.
+   * Automatically populated as dependencies are resolved.
+   */
+  dependencies: Set<string>
+  /**
+   * The scope of the service being initialized.
+   */
+  scope: InjectableScope
+  /**
+   * Track a dependency that was resolved.
+   * Used for scope upgrade tracking - if a Singleton service
+   * resolves a Request dependency, the scope can be upgraded.
+   *
+   * @param name The name of the dependency
+   * @param scope The scope of the dependency
+   */
+  trackDependency(name: string, scope: InjectableScope): void
+}

package/src/internal/core/index.mts

@@ -1,5 +1,6 @@
-export * from './service-locator.mjs'
 export * from './instance-resolver.mjs'
-export * from './instantiator.mjs'
-export * from './invalidator.mjs'
-export * from './token-processor.mjs'
+export * from './name-resolver.mjs'
+export * from './scope-tracker.mjs'
+export * from './service-initializer.mjs'
+export * from './service-invalidator.mjs'
+export * from './token-resolver.mjs'