@fluojs/di 1.0.0-beta.4 → 1.0.0-beta.6

package/README.ko.md

@@ -76,6 +76,8 @@ const service = await container.resolve(UserService);
 - **request**: `createRequestScope()`마다 새로 생성됩니다.
 - **transient**: resolve할 때마다 새 인스턴스를 만듭니다.
 
+dispose 중에는 루트 컨테이너가 먼저 살아 있는 request scope 자식을 정리한 뒤, 자식 dispose 중 하나 이상이 실패하더라도 루트가 소유한 singleton 정리를 계속 수행합니다. 자식/루트 dispose 실패가 여러 개 발생하면 `dispose()`는 모든 shutdown 실패를 확인할 수 있도록 `AggregateError`로 보고합니다.
+
 ### request scope 분리
 
 ```ts
@@ -91,7 +93,7 @@ provider 객체는 등록 시점에 검증됩니다. 모든 객체 provider는 n
 
 컨테이너는 순환 의존성을 자동으로 감지하고 `CircularDependencyError`를 발생시켜 무한 루프를 방지합니다. 여기에는 직접 참조(A→A), 이중 노드(A→B→A), 깊은 순환(A→B→C→A)이 모두 포함됩니다.
 
-순환 의존성을 해결하려면 `forwardRef()`를 사용하여 의존성 토큰의 해석을 지연시키세요.
+선언 순서 때문에 아직 정의되지 않은 토큰을 참조해야 한다면 `forwardRef()`를 사용하세요. `forwardRef()`는 선언 순서 문제를 위해 토큰 조회를 지연할 뿐이며, 실제 생성자 순환을 해소하지는 않습니다. 그런 순환은 여전히 `CircularDependencyError`로 거부됩니다.
 
 ```typescript
 import { forwardRef } from '@fluojs/di';
@@ -99,12 +101,13 @@ import { Inject } from '@fluojs/core';
 
 @Inject(forwardRef(() => ServiceB))
 class ServiceA {
-  constructor(private serviceB: any) {}
+  constructor(private readonly serviceB: ServiceB) {}
 }
 
-@Inject(forwardRef(() => ServiceA))
 class ServiceB {
-  constructor(private serviceA: any) {}
+  getStatus() {
+    return 'ready';
+  }
 }
 ```
 
@@ -131,7 +134,7 @@ const service = await container.resolve(DataService);
 ## 문제 해결
 
 ### CircularDependencyError
-의존성 그래프에서 순환이 감지될 때 발생합니다. 생성자 주입 항목을 확인하고 필요한 경우 `forwardRef()`를 사용하여 순환을 끊으세요.
+의존성 그래프에서 순환이 감지될 때 발생합니다. 생성자 주입 항목을 확인하고 공유 상태 추출, 중재자 도입, 수명 주기 경계 변경 등으로 순환을 제거하세요. `forwardRef()`는 선언 순서 문제를 위해 토큰 조회만 지연하며, 실제 생성자 순환을 끊지는 않습니다.
 
 ### 토큰을 찾을 수 없음 (Token Not Found)
 필요한 모든 provider가 컨테이너에 등록되어 있는지 확인하세요. `createRequestScope()`를 사용하는 경우 자식 컨테이너는 부모의 토큰을 해석할 수 있지만, 그 반대는 불가능합니다.
@@ -145,6 +148,7 @@ const service = await container.resolve(DataService);
 | `resolve<T>(token)` | 토큰을 인스턴스로 비동기 해석합니다. |
 | `createRequestScope()` | 요청 스코프 의존성을 위한 자식 컨테이너를 생성합니다. |
 | `has(token)` | 컨테이너나 부모에 토큰이 등록되어 있는지 확인합니다. |
+| `hasRequestScopedDependency(token)` | 토큰 해석 시 provider 그래프에 request-scoped 의존성이나 순환이 있어 request-scope 컨테이너가 필요할 수 있는지 확인합니다. |
 
 ## 관련 패키지
 

package/README.md

@@ -75,6 +75,8 @@ fluo DI supports three main provider shapes:
 - **Request**: Instance is created once per `createRequestScope()` call.
 - **Transient**: A new instance is created every time it is resolved.
 
+During disposal, the root container first tears down live request-scope children and then continues with root-owned singleton cleanup even if one or more child disposals fail. When multiple child/root disposals fail, `dispose()` reports an `AggregateError` so callers can inspect every shutdown failure without losing cleanup progress.
+
 ### Request Scoping
 Isolated containers can be created to handle per-request state without polluting the root container.
 
@@ -91,7 +93,7 @@ Provider objects are validated at registration time: every object provider must
 
 The container automatically detects circular dependencies and throws a `CircularDependencyError` to prevent infinite loops. This includes direct (A→A), two-node (A→B→A), and deep (A→B→C→A) cycles.
 
-To resolve a circular dependency, use `forwardRef()` to defer the resolution of the dependent token.
+Use `forwardRef()` when a token is referenced before its declaration. It defers token lookup for declaration-order issues, but it does not make true constructor cycles resolvable; those cycles are still rejected with `CircularDependencyError`.
 
 ```typescript
 import { forwardRef } from '@fluojs/di';
@@ -99,12 +101,13 @@ import { Inject } from '@fluojs/core';
 
 @Inject(forwardRef(() => ServiceB))
 class ServiceA {
-  constructor(private serviceB: any) {}
+  constructor(private readonly serviceB: ServiceB) {}
 }
 
-@Inject(forwardRef(() => ServiceA))
 class ServiceB {
-  constructor(private serviceA: any) {}
+  getStatus() {
+    return 'ready';
+  }
 }
 ```
 
@@ -131,7 +134,7 @@ const service = await container.resolve(DataService);
 ## Troubleshooting
 
 ### CircularDependencyError
-Thrown when the container detects a cycle in the dependency graph. Check your constructor injections and use `forwardRef()` where necessary to break the cycle.
+Thrown when the container detects a cycle in the dependency graph. Check your constructor injections and remove the cycle by extracting shared state, introducing a mediator, or changing the lifetime boundary. `forwardRef()` only defers token lookup for declaration-order issues; it does not break true constructor cycles.
 
 ### Token Not Found
 Ensure all required providers are registered in the container. If you use `createRequestScope()`, the child container can resolve tokens from the parent, but not vice versa.
@@ -145,6 +148,7 @@ Ensure all required providers are registered in the container. If you use `creat
 | `resolve<T>(token)` | Asynchronously resolves a token to an instance. |
 | `createRequestScope()` | Creates a child container for request-scoped dependencies. |
 | `has(token)` | Checks if a token is registered in the container or its parents. |
+| `hasRequestScopedDependency(token)` | Checks whether resolving a token may require a request-scope container because its provider graph contains request-scoped dependencies or is cyclic. |
 
 ## Related Packages
 

package/dist/container.d.ts

@@ -16,10 +16,15 @@ export declare class Container {
     private readonly staleDisposalErrors;
     private readonly singletonCache;
     private readonly forwardRefTokenCache;
+    private readonly providerLookupPlanCache;
+    private readonly multiProviderPlanCache;
+    private readonly requestScopeVerdictPlanCache;
+    private readonly effectiveProviderPlanCache;
     private childScopes;
     private disposePromise;
     private disposed;
     private trackedByRoot;
+    private graphRevision;
     constructor(parent?: Container | undefined, requestScopeEnabled?: boolean, singletonCache?: Map<Token, Promise<unknown>>);
     /**
      * Registers providers in the current container scope.
@@ -54,6 +59,13 @@ export declare class Container {
      * @returns `true` when a single or multi provider exists for the token.
      */
     has(token: Token): boolean;
+    /**
+     * Returns whether resolving a token may require a request-scope container.
+     *
+     * @param token Provider token to inspect through aliases, multi providers, and dependencies.
+     * @returns `true` when the provider graph contains request-scoped dependencies or is cyclic.
+     */
+    hasRequestScopedDependency(token: Token): boolean;
     /**
      * Creates a child request-scope container that shares root singleton cache.
      *
@@ -88,6 +100,10 @@ export declare class Container {
     private hasAncestorMultiRegistration;
     private hasMultiRegistration;
     private collectMultiProviders;
+    private providerGraphRequiresRequestScope;
+    private unregisteredClassRequiresRequestScope;
+    private normalizedProviderRequiresRequestScope;
+    private dependencyEntryRequiresRequestScope;
     private resolveWithChain;
     private resolveFromRegisteredProviders;
     private requireProvider;
@@ -126,12 +142,20 @@ export declare class Container {
     private collectDisposableInstances;
     private disposeInstancesInReverseOrder;
     private clearDisposalCaches;
+    private currentLineageRevision;
+    private readCachedPlan;
+    private writePlanCache;
+    private advanceGraphRevision;
+    private clearResolutionPlanCaches;
     private waitForStaleDisposalTasks;
     private scheduleStaleDisposal;
     private throwDisposalErrors;
+    private collectDisposalError;
     private isDisposable;
     private instantiate;
     private assertSingletonDependencyScopes;
+    private findRequestScopedDependency;
+    private findRequestScopedDependencyToken;
     private resolveEffectiveProvider;
     private resolveProviderDependencyToken;
     private resolveForwardRefToken;

package/dist/container.d.ts.map

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

package/dist/container.js

@@ -126,10 +126,15 @@ export class Container {
   staleDisposalErrors = [];
   singletonCache;
   forwardRefTokenCache = new WeakMap();
+  providerLookupPlanCache = new Map();
+  multiProviderPlanCache = new Map();
+  requestScopeVerdictPlanCache = new Map();
+  effectiveProviderPlanCache = new Map();
   childScopes;
   disposePromise;
   disposed = false;
   trackedByRoot = false;
+  graphRevision = 0;
   constructor(parent, requestScopeEnabled = false, singletonCache) {
     this.parent = parent;
     this.requestScopeEnabled = requestScopeEnabled;
@@ -166,12 +171,14 @@ export class Container {
         const existing = this.multiRegistrations.get(normalized.provide);
         if (existing) {
           existing.push(normalized);
+          this.advanceGraphRevision();
           continue;
         }
         this.multiRegistrations.set(normalized.provide, [normalized]);
       } else {
         this.registrations.set(normalized.provide, normalized);
       }
+      this.advanceGraphRevision();
     }
     return this;
   }
@@ -205,10 +212,12 @@ export class Container {
       if (normalized.multi) {
         this.multiRegistrations.set(normalized.provide, [normalized]);
         this.multiOverriddenTokens.add(normalized.provide);
+        this.advanceGraphRevision();
         continue;
       }
       this.multiOverriddenTokens.add(normalized.provide);
       this.registrations.set(normalized.provide, normalized);
+      this.advanceGraphRevision();
     }
     return this;
   }
@@ -223,6 +232,20 @@ export class Container {
     return this.lookupProvider(token) !== undefined || this.hasMulti(token);
   }
 
+  /**
+   * Returns whether resolving a token may require a request-scope container.
+   *
+   * @param token Provider token to inspect through aliases, multi providers, and dependencies.
+   * @returns `true` when the provider graph contains request-scoped dependencies or is cyclic.
+   */
+  hasRequestScopedDependency(token) {
+    const cached = this.readCachedPlan(this.requestScopeVerdictPlanCache, token);
+    if (cached) {
+      return cached.value;
+    }
+    return this.writePlanCache(this.requestScopeVerdictPlanCache, token, this.providerGraphRequiresRequestScope(token, new Set()));
+  }
+
   /**
    * Creates a child request-scope container that shares root singleton cache.
    *
@@ -270,6 +293,7 @@ export class Container {
       return;
     }
     this.disposed = true;
+    this.advanceGraphRevision();
     this.disposePromise = this.disposeAll();
     try {
       await this.disposePromise;
@@ -279,13 +303,24 @@ export class Container {
     }
   }
   async disposeAll() {
+    const errors = [];
     try {
       // Dispose all live request-scope children first (root only)
       if (!this.parent && this.childScopes && this.childScopes.size > 0) {
-        await Promise.all(Array.from(this.childScopes).map(child => child.dispose()));
+        const childResults = await Promise.allSettled(Array.from(this.childScopes).map(child => child.dispose()));
+        for (const result of childResults) {
+          if (result.status === 'rejected') {
+            this.collectDisposalError(result.reason, errors);
+          }
+        }
         this.childScopes.clear();
       }
-      await this.disposeCache(this.disposalCacheEntries());
+      try {
+        await this.disposeCache(this.disposalCacheEntries());
+      } catch (error) {
+        this.collectDisposalError(error, errors);
+      }
+      this.throwDisposalErrors(errors);
     } finally {
       if (this.parent && this.trackedByRoot) {
         this.root().childScopes?.delete(this);
@@ -335,15 +370,65 @@ export class Container {
     return this.parent?.hasMultiRegistration(token) ?? false;
   }
   collectMultiProviders(token) {
+    const cached = this.readCachedPlan(this.multiProviderPlanCache, token);
+    if (cached) {
+      return [...cached.value];
+    }
     const local = this.multiRegistrations.get(token);
+    let providers;
     if (this.multiOverriddenTokens.has(token)) {
-      return local ?? [];
+      providers = Object.freeze([...(local ?? [])]);
+    } else {
+      const fromParent = this.parent ? this.parent.collectMultiProviders(token) : [];
+      providers = Object.freeze(local ? [...fromParent, ...local] : [...fromParent]);
+    }
+    this.writePlanCache(this.multiProviderPlanCache, token, providers);
+    return [...providers];
+  }
+  providerGraphRequiresRequestScope(token, visited) {
+    if (visited.has(token)) {
+      return true;
+    }
+    visited.add(token);
+    try {
+      const provider = this.lookupProvider(token);
+      const multiProviders = this.collectMultiProviders(token);
+      if (!provider && multiProviders.length === 0) {
+        return this.unregisteredClassRequiresRequestScope(token, visited);
+      }
+      if (provider && this.normalizedProviderRequiresRequestScope(provider, visited)) {
+        return true;
+      }
+      return multiProviders.some(multiProvider => this.normalizedProviderRequiresRequestScope(multiProvider, visited));
+    } finally {
+      visited.delete(token);
     }
-    const fromParent = this.parent ? this.parent.collectMultiProviders(token) : [];
-    if (local) {
-      return [...fromParent, ...local];
+  }
+  unregisteredClassRequiresRequestScope(token, visited) {
+    if (typeof token !== 'function') {
+      return false;
+    }
+    const metadata = getClassDiMetadata(token);
+    if (metadata?.scope === Scope.REQUEST) {
+      return true;
     }
-    return fromParent;
+    return (metadata?.inject ?? []).some(depEntry => this.dependencyEntryRequiresRequestScope(depEntry, visited));
+  }
+  normalizedProviderRequiresRequestScope(provider, visited) {
+    if (provider.scope === Scope.REQUEST) {
+      return true;
+    }
+    if (provider.type === 'existing' && provider.useExisting !== undefined) {
+      return this.providerGraphRequiresRequestScope(provider.useExisting, visited);
+    }
+    return provider.inject.some(depEntry => this.dependencyEntryRequiresRequestScope(depEntry, visited));
+  }
+  dependencyEntryRequiresRequestScope(depEntry, visited) {
+    const depToken = this.resolveProviderDependencyToken(depEntry);
+    if (isOptionalToken(depEntry) && !this.has(depToken)) {
+      return false;
+    }
+    return this.providerGraphRequiresRequestScope(depToken, visited);
   }
   async resolveWithChain(token, chain, activeTokens, allowForwardRef = false) {
     const cachedForwardRef = this.resolveForwardRefCircularDependency(token, chain, activeTokens, allowForwardRef);
@@ -504,11 +589,13 @@ export class Container {
     return this.multiRequestCache;
   }
   lookupProvider(token) {
-    const local = this.registrations.get(token);
-    if (local) {
-      return local;
+    const cached = this.readCachedPlan(this.providerLookupPlanCache, token);
+    if (cached) {
+      return cached.value;
     }
-    return this.parent?.lookupProvider(token);
+    const local = this.registrations.get(token);
+    const provider = local ?? this.parent?.lookupProvider(token);
+    return this.writePlanCache(this.providerLookupPlanCache, token, provider);
   }
 
   /**
@@ -618,10 +705,40 @@ export class Container {
     if (this.parent) {
       this.requestCache?.clear();
       this.multiRequestCache?.clear();
+      this.clearResolutionPlanCaches();
       return;
     }
     this.singletonCache.clear();
     this.multiSingletonCache.clear();
+    this.clearResolutionPlanCaches();
+  }
+  currentLineageRevision() {
+    const parentRevision = this.parent?.currentLineageRevision();
+    return parentRevision ? `${parentRevision}/${this.graphRevision}` : String(this.graphRevision);
+  }
+  readCachedPlan(cache, token) {
+    const cached = cache.get(token);
+    if (!cached || cached.lineageRevision !== this.currentLineageRevision()) {
+      return undefined;
+    }
+    return cached;
+  }
+  writePlanCache(cache, token, value) {
+    cache.set(token, {
+      lineageRevision: this.currentLineageRevision(),
+      value
+    });
+    return value;
+  }
+  advanceGraphRevision() {
+    this.graphRevision += 1;
+    this.clearResolutionPlanCaches();
+  }
+  clearResolutionPlanCaches() {
+    this.providerLookupPlanCache.clear();
+    this.multiProviderPlanCache.clear();
+    this.requestScopeVerdictPlanCache.clear();
+    this.effectiveProviderPlanCache.clear();
   }
   async waitForStaleDisposalTasks() {
     while (this.staleDisposalTasks.size > 0) {
@@ -652,6 +769,13 @@ export class Container {
       throw new AggregateError(errors, 'Container disposal failed for one or more providers.');
     }
   }
+  collectDisposalError(error, errors) {
+    if (error instanceof AggregateError) {
+      errors.push(...error.errors);
+      return;
+    }
+    errors.push(error);
+  }
   isDisposable(value) {
     return typeof value === 'object' && value !== null && 'onDestroy' in value && typeof value.onDestroy === 'function';
   }
@@ -686,19 +810,61 @@ export class Container {
     if (provider.scope !== Scope.DEFAULT) {
       return;
     }
-    for (const depEntry of provider.inject) {
+    const requestScopedDependency = this.findRequestScopedDependency(provider.inject, new Set([provider.provide]));
+    if (requestScopedDependency) {
+      throw new ScopeMismatchError(`Singleton provider ${formatTokenName(provider.provide)} depends on request-scoped provider ${formatTokenName(requestScopedDependency)}.`, {
+        token: provider.provide,
+        scope: 'singleton',
+        hint: `Singleton providers cannot depend on request-scoped providers. Either change ${formatTokenName(requestScopedDependency)} to singleton/transient scope, or change ${formatTokenName(provider.provide)} to request scope.`
+      });
+    }
+  }
+  findRequestScopedDependency(depEntries, visited) {
+    for (const depEntry of depEntries) {
       const depToken = this.resolveProviderDependencyToken(depEntry);
-      const effectiveProvider = this.resolveEffectiveProvider(depToken);
-      if (effectiveProvider?.scope === 'request') {
-        throw new ScopeMismatchError(`Singleton provider ${formatTokenName(provider.provide)} depends on request-scoped provider ${formatTokenName(depToken)}.`, {
-          token: provider.provide,
-          scope: 'singleton',
-          hint: `Singleton providers cannot depend on request-scoped providers. Either change ${formatTokenName(depToken)} to singleton/transient scope, or change ${formatTokenName(provider.provide)} to request scope.`
-        });
+      if (isOptionalToken(depEntry) && !this.has(depToken)) {
+        continue;
+      }
+      const requestScopedToken = this.findRequestScopedDependencyToken(depToken, visited);
+      if (requestScopedToken) {
+        return requestScopedToken;
       }
     }
+    return undefined;
+  }
+  findRequestScopedDependencyToken(token, visited) {
+    if (visited.has(token)) {
+      return undefined;
+    }
+    visited.add(token);
+    try {
+      const provider = this.resolveEffectiveProvider(token);
+      if (provider) {
+        if (provider.scope === Scope.REQUEST) {
+          return provider.provide;
+        }
+        return this.findRequestScopedDependency(provider.inject, visited);
+      }
+      if (typeof token !== 'function') {
+        return undefined;
+      }
+      const metadata = getClassDiMetadata(token);
+      if (metadata?.scope === Scope.REQUEST) {
+        return token;
+      }
+      return this.findRequestScopedDependency(metadata?.inject ?? [], visited);
+    } finally {
+      visited.delete(token);
+    }
   }
   resolveEffectiveProvider(token, visited = new Set(), chain = []) {
+    const cacheable = visited.size === 0 && chain.length === 0;
+    if (cacheable) {
+      const cached = this.readCachedPlan(this.effectiveProviderPlanCache, token);
+      if (cached) {
+        return cached.value;
+      }
+    }
     let currentToken = token;
     while (true) {
       if (visited.has(currentToken)) {
@@ -707,9 +873,15 @@ export class Container {
       visited.add(currentToken);
       const provider = this.lookupProvider(currentToken);
       if (!provider) {
+        if (cacheable) {
+          return this.writePlanCache(this.effectiveProviderPlanCache, token, undefined);
+        }
         return undefined;
       }
       if (provider.type !== 'existing' || provider.useExisting === undefined) {
+        if (cacheable) {
+          return this.writePlanCache(this.effectiveProviderPlanCache, token, provider);
+        }
         return provider;
       }
       chain.push(currentToken);

package/package.json

@@ -9,7 +9,7 @@
     "container",
     "provider"
   ],
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.6",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,7 +36,7 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.2"
+    "@fluojs/core": "^1.0.0-beta.3"
   },
   "devDependencies": {
     "vitest": "^3.2.4"