@fluojs/di 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,155 @@
+# @fluojs/di
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+모든 fluo 애플리케이션을 구동하는 최소 토큰 기반 의존성 주입 컨테이너입니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [주요 기능](#주요-기능)
+- [순환 의존성 처리](#순환-의존성-처리)
+- [테스트 및 모킹](#테스트-및-모킹)
+- [문제 해결](#문제-해결)
+- [공개 API](#공개-api)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/di
+```
+
+## 사용 시점
+
+- 런타임에 클래스와 의존성을 실제 인스턴스로 해석해야 할 때
+- singleton, request, transient 같은 수명 주기를 관리해야 할 때
+- 테스트나 환경별 설정에서 구현체를 명시적으로 교체해야 할 때
+- HTTP 요청이나 백그라운드 작업마다 격리된 request scope가 필요할 때
+
+## 빠른 시작
+
+컨테이너는 등록된 provider를 기준으로 토큰을 인스턴스로 해석합니다.
+
+```ts
+import { Container } from '@fluojs/di';
+import { Inject, Scope } from '@fluojs/core';
+
+class Logger {
+  log(message: string) {
+    console.log(message);
+  }
+}
+
+@Inject(Logger)
+@Scope('singleton')
+class UserService {
+  constructor(private readonly logger: Logger) {}
+
+  async getStatus() {
+    this.logger.log('상태 확인 중...');
+    return { status: 'active' };
+  }
+}
+
+const container = new Container();
+container.register(Logger, UserService);
+
+const service = await container.resolve(UserService);
+```
+
+## 주요 기능
+
+### 다양한 provider 형태 지원
+
+- **클래스 provider**: `container.register(MyService)` 또는 `{ provide, useClass }`
+- **값 provider**: `{ provide: 'API_URL', useValue: 'https://api.example.com' }`
+- **팩토리 provider**: `{ provide, useFactory, inject }`
+- **별칭(Alias) provider**: `{ provide: ILogger, useExisting: PinoLogger }`를 사용하여 하나의 토큰을 기존에 등록된 다른 provider로 매핑할 수 있습니다.
+
+### scope-aware 수명 주기 관리
+
+- **singleton**: 루트 컨테이너에서 한 번 생성되어 공유됩니다.
+- **request**: `createRequestScope()`마다 새로 생성됩니다.
+- **transient**: resolve할 때마다 새 인스턴스를 만듭니다.
+
+### request scope 분리
+
+```ts
+const requestContainer = container.createRequestScope();
+const scopedService = await requestContainer.resolve(RequestScopedService);
+```
+
+## 순환 의존성 처리
+
+컨테이너는 순환 의존성을 자동으로 감지하고 `CircularDependencyError`를 발생시켜 무한 루프를 방지합니다. 여기에는 직접 참조(A→A), 이중 노드(A→B→A), 깊은 순환(A→B→C→A)이 모두 포함됩니다.
+
+순환 의존성을 해결하려면 `forwardRef()`를 사용하여 의존성 토큰의 해석을 지연시키세요.
+
+```typescript
+import { forwardRef } from '@fluojs/di';
+import { Inject } from '@fluojs/core';
+
+@Inject(forwardRef(() => ServiceB))
+class ServiceA {
+  constructor(private serviceB: any) {}
+}
+
+@Inject(forwardRef(() => ServiceA))
+class ServiceB {
+  constructor(private serviceA: any) {}
+}
+```
+
+## 테스트 및 모킹
+
+`useValue`를 사용하면 단위 테스트 중에 컨테이너의 provider를 모의 객체(mock)나 스텁(stub)으로 쉽게 교체할 수 있습니다.
+
+```typescript
+import { Container } from '@fluojs/di';
+
+const container = new Container();
+const mockDb = { query: jest.fn() };
+
+// 실제 Database 클래스를 모의 객체 값으로 교체
+container.register({ 
+  provide: Database, 
+  useValue: mockDb 
+});
+
+const service = await container.resolve(DataService);
+// 이제 service는 실제 Database 인스턴스 대신 mockDb를 사용합니다.
+```
+
+## 문제 해결
+
+### CircularDependencyError
+의존성 그래프에서 순환이 감지될 때 발생합니다. 생성자 주입 항목을 확인하고 필요한 경우 `forwardRef()`를 사용하여 순환을 끊으세요.
+
+### 토큰을 찾을 수 없음 (Token Not Found)
+필요한 모든 provider가 컨테이너에 등록되어 있는지 확인하세요. `createRequestScope()`를 사용하는 경우 자식 컨테이너는 부모의 토큰을 해석할 수 있지만, 그 반대는 불가능합니다.
+
+## 공개 API
+
+| 클래스/메서드 | 설명 |
+|---|---|
+| `Container` | 메인 DI 컨테이너 클래스입니다. |
+| `register(...providers)` | 하나 이상의 프로바이더를 등록합니다. |
+| `resolve<T>(token)` | 토큰을 인스턴스로 비동기 해석합니다. |
+| `createRequestScope()` | 요청 스코프 의존성을 위한 자식 컨테이너를 생성합니다. |
+| `has(token)` | 컨테이너나 부모에 토큰이 등록되어 있는지 확인합니다. |
+
+## 관련 패키지
+
+- `@fluojs/core`: `@Inject()`와 `@Scope()` 데코레이터를 정의합니다.
+- `@fluojs/runtime`: 부트스트랩 중 provider 등록과 모듈 그래프 조립을 담당합니다.
+- `@fluojs/http`: 들어오는 요청마다 request scope를 생성합니다.
+
+## 예제 소스
+
+- `packages/di/src/container.ts`
+- `packages/di/src/container.test.ts`
+- `examples/minimal/src/app.ts`

package/README.md

@@ -0,0 +1,155 @@
+# @fluojs/di
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Minimal token-based dependency injection container powering every fluo application.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Key Capabilities](#key-capabilities)
+- [Circular Dependency Handling](#circular-dependency-handling)
+- [Testing and Mocking](#testing-and-mocking)
+- [Troubleshooting](#troubleshooting)
+- [Public API](#public-api)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/di
+```
+
+## When to Use
+
+Use this package when you need to:
+- Resolve classes and their dependencies at runtime.
+- Manage object lifetimes (Singleton, Request, Transient).
+- Override implementations for testing or environment-specific needs.
+- Create isolated request-scoped containers for HTTP or background tasks.
+
+## Quick Start
+
+The container resolves tokens into instances based on their registered providers.
+
+```typescript
+import { Container } from '@fluojs/di';
+import { Inject, Scope } from '@fluojs/core';
+
+class Logger {
+  log(msg: string) { console.log(msg); }
+}
+
+@Inject(Logger)
+@Scope('singleton')
+class UserService {
+  constructor(private logger: Logger) {}
+  
+  async getStatus() {
+    this.logger.log('Checking status...');
+    return { status: 'active' };
+  }
+}
+
+const container = new Container();
+container.register(Logger, UserService);
+
+const service = await container.resolve(UserService);
+const result = await service.getStatus();
+```
+
+## Key Capabilities
+
+### Provider Types
+fluo DI supports three main provider shapes:
+- **Class Providers**: `container.register(MyService)` or `{ provide: MyToken, useClass: MyService }`.
+- **Value Providers**: `{ provide: 'API_URL', useValue: 'https://api.example.com' }`.
+- **Factory Providers**: `{ provide: 'ASYNC_CONFIG', useFactory: async (db) => await db.load(), inject: [Database] }`.
+- **Alias Providers**: `{ provide: ILogger, useExisting: PinoLogger }` allows mapping one token to another existing provider.
+
+### Scope Management
+- **Singleton** (Default): Instance is created once and shared across the entire container.
+- **Request**: Instance is created once per `createRequestScope()` call.
+- **Transient**: A new instance is created every time it is resolved.
+
+### Request Scoping
+Isolated containers can be created to handle per-request state without polluting the root container.
+
+```typescript
+const requestContainer = container.createRequestScope();
+const scopedService = await requestContainer.resolve(RequestScopedService);
+```
+
+## Circular Dependency Handling
+
+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.
+
+```typescript
+import { forwardRef } from '@fluojs/di';
+import { Inject } from '@fluojs/core';
+
+@Inject(forwardRef(() => ServiceB))
+class ServiceA {
+  constructor(private serviceB: any) {}
+}
+
+@Inject(forwardRef(() => ServiceA))
+class ServiceB {
+  constructor(private serviceA: any) {}
+}
+```
+
+## Testing and Mocking
+
+You can easily override providers in the container to use mocks or stubs during unit testing by using `useValue`.
+
+```typescript
+import { Container } from '@fluojs/di';
+
+const container = new Container();
+const mockDb = { query: jest.fn() };
+
+// Override the real Database class with a mock value
+container.register({ 
+  provide: Database, 
+  useValue: mockDb 
+});
+
+const service = await container.resolve(DataService);
+// service will now use mockDb instead of the real Database instance
+```
+
+## 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.
+
+### 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.
+
+## Public API
+
+| Class/Method | Description |
+|---|---|
+| `Container` | The main DI container class. |
+| `register(...providers)` | Registers one or more providers. |
+| `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. |
+
+## Related Packages
+
+- **`@fluojs/core`**: Defines the `@Inject()` and `@Scope()` decorators used to annotate classes.
+- **`@fluojs/runtime`**: Handles automatic registration of providers during application bootstrap.
+- **`@fluojs/http`**: Creates a request scope for every incoming HTTP request.
+
+## Example Sources
+
+- `packages/di/src/container.ts`
+- `packages/di/src/container.test.ts`
+- `examples/minimal/src/app.ts`

package/dist/container.d.ts

@@ -0,0 +1,133 @@
+import { type Token } from '@fluojs/core';
+import type { Provider } from './types.js';
+/**
+ * Scope-aware dependency injection container for Fluo providers.
+ */
+export declare class Container {
+    private readonly parent?;
+    private readonly requestScopeEnabled;
+    private readonly registrations;
+    private readonly multiRegistrations;
+    private readonly multiOverriddenTokens;
+    private readonly requestCache;
+    private readonly multiRequestCache;
+    private readonly multiSingletonCache;
+    private readonly staleDisposalTasks;
+    private readonly staleDisposalErrors;
+    private readonly singletonCache;
+    private readonly childScopes;
+    private disposePromise;
+    private disposed;
+    constructor(parent?: Container | undefined, requestScopeEnabled?: boolean, singletonCache?: Map<Token, Promise<unknown>>);
+    /**
+     * Registers providers in the current container scope.
+     *
+     * @param providers Provider definitions to register in this container.
+     * @returns The same container instance for fluent registration chains.
+     * @throws {ContainerResolutionError} When called after the container was disposed.
+     * @throws {ScopeMismatchError} When registering singleton providers directly on a request scope.
+     * @throws {DuplicateProviderError} When registration conflicts with existing single/multi mappings.
+     * @throws {InvalidProviderError} When a provider definition is structurally invalid.
+     */
+    register(...providers: Provider[]): this;
+    /**
+     * Override one or more already-registered providers.
+     *
+     * **Multi-provider destructive replacement**: when the incoming provider has `multi: true`,
+     * the entire existing multi-registration array for that token is deleted before the new entry
+     * is added. There is intentionally no way to replace a single entry within a multi-provider
+     * set — the whole set is replaced. If you need to preserve other entries, re-register them
+     * together with the replacement in one `override()` call.
+     *
+     * @param providers Provider definitions that should replace existing registrations for each token.
+     * @returns The same container instance for fluent override chains.
+     * @throws {ContainerResolutionError} When called after the container was disposed.
+     * @throws {InvalidProviderError} When a provider definition is structurally invalid.
+     */
+    override(...providers: Provider[]): this;
+    /**
+     * Returns whether a token is registered in this scope chain.
+     *
+     * @param token Token to check across this container and its ancestors.
+     * @returns `true` when a single or multi provider exists for the token.
+     */
+    has(token: Token): boolean;
+    /**
+     * Creates a child request-scope container that shares root singleton cache.
+     *
+     * @returns A request-scope child container bound to this container hierarchy.
+     * @throws {ContainerResolutionError} When called after the container was disposed.
+     */
+    createRequestScope(): Container;
+    /**
+     * Resolves a token to an instance using scope-aware caching rules.
+     *
+     * @param token Token to resolve.
+     * @returns A promise that resolves to the token instance (or multi-provider instance array).
+     * @throws {ContainerResolutionError} When called after disposal or when no provider is registered.
+     * @throws {RequestScopeResolutionError} When request-scoped providers are resolved from root scope.
+     * @throws {ScopeMismatchError} When singleton providers depend on request-scoped providers.
+     * @throws {CircularDependencyError} When provider dependency resolution detects a cycle.
+     */
+    resolve<T>(token: Token<T>): Promise<T>;
+    /**
+     * Disposes cached instances and nested request scopes.
+     *
+     * @returns A promise that settles after all cached disposable instances are torn down.
+     * @throws {Error} Propagates one or more disposal errors (`AggregateError` when multiple failures occur).
+     */
+    dispose(): Promise<void>;
+    private disposeAll;
+    private hasMulti;
+    private assertNoRegistrationConflict;
+    private hasAncestorSingleRegistration;
+    private hasSingleRegistration;
+    private hasAncestorMultiRegistration;
+    private hasMultiRegistration;
+    private collectMultiProviders;
+    private resolveWithChain;
+    private resolveFromRegisteredProviders;
+    private requireProvider;
+    private resolveAliasTarget;
+    private resolveForwardRefCircularDependency;
+    private resolveMultiProviderInstances;
+    private resolveMultiProviderInstance;
+    private resolveExistingProviderTarget;
+    private resolveScopedOrSingletonInstance;
+    private shouldResolveFromRoot;
+    private shouldResolveMultiProviderFromRoot;
+    private resolveDepToken;
+    private withTokenInChain;
+    private root;
+    private lookupProvider;
+    /**
+     * Resolve the cache map that should hold the instance for `provider`.
+     *
+     * **Singleton-in-request-scope**: if a provider with `scope: 'singleton'` (the default) is
+     * registered directly on a request-scope child container (rather than the root), it is cached
+     * in the child's `requestCache` instead of the root's `singletonCache`. This means it behaves
+     * as request-scoped despite the singleton scope annotation. This is intentional — it allows
+     * test and override scenarios to inject short-lived values without polluting the global cache
+     * — but the divergence from the declared scope is a known footgun for consumers who
+     * inadvertently register singletons on child containers.
+     */
+    private cacheFor;
+    private multiCacheFor;
+    private hasLocalMultiProvider;
+    private disposalCacheEntries;
+    private disposeCache;
+    private collectDisposableInstances;
+    private disposeInstancesInReverseOrder;
+    private clearDisposalCaches;
+    private waitForStaleDisposalTasks;
+    private scheduleStaleDisposal;
+    private throwDisposalErrors;
+    private isDisposable;
+    private instantiate;
+    private assertSingletonDependencyScopes;
+    private resolveEffectiveProvider;
+    private resolveProviderDependencyToken;
+    private resolveProviderDeps;
+    private invalidateCachedEntry;
+}
+//# sourceMappingURL=container.d.ts.map

package/dist/container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,KAAK,KAAK,EAAE,MAAM,cAAc,CAAC;AAW3E,OAAO,KAAK,EASV,QAAQ,EAET,MAAM,YAAY,CAAC;AA8FpB;;GAEG;AACH,qBAAa,SAAS;IAelB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IAftC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwC;IACtE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA0C;IAC7E,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAoB;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAmD;IACrF,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAmD;IACvF,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA4B;IAC/D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAiB;IACrD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA+B;IAC9D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;IACpD,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,QAAQ,CAAS;gBAGN,MAAM,CAAC,EAAE,SAAS,YAAA,EAClB,mBAAmB,UAAQ,EAC5C,cAAc,CAAC,EAAE,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAK/C;;;;;;;;;OASG;IACH,QAAQ,CAAC,GAAG,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI;IAyCxC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,GAAG,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI;IA6BxC;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO;IAI1B;;;;;OAKG;IACH,kBAAkB,IAAI,SAAS;IAa/B;;;;;;;;;OASG;IACG,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAW7C;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAiBhB,UAAU;IAgBxB,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,4BAA4B;IAsBpC,OAAO,CAAC,6BAA6B;IAIrC,OAAO,CAAC,qBAAqB;IAM7B,OAAO,CAAC,4BAA4B;IAIpC,OAAO,CAAC,oBAAoB;IAM5B,OAAO,CAAC,qBAAqB;YAgBf,gBAAgB;YAehB,8BAA8B;IA+B5C,OAAO,CAAC,eAAe;YAgBT,kBAAkB;IAMhC,OAAO,CAAC,mCAAmC;YAoB7B,6BAA6B;YAc7B,4BAA4B;IA4B1C,OAAO,CAAC,6BAA6B;YAQvB,gCAAgC;IAuB9C,OAAO,CAAC,qBAAqB;IAI7B,OAAO,CAAC,kCAAkC;YAI5B,eAAe;YAwBf,gBAAgB;IAiB9B,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,cAAc;IAUtB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,QAAQ;IAuBhB,OAAO,CAAC,aAAa;IAuBrB,OAAO,CAAC,qBAAqB;IAI7B,OAAO,CAAC,oBAAoB;YAkBd,YAAY;YAaZ,0BAA0B;YA0B1B,8BAA8B;IAc5C,OAAO,CAAC,mBAAmB;YAWb,yBAAyB;IAMvC,OAAO,CAAC,qBAAqB;IAoB7B,OAAO,CAAC,mBAAmB;IAU3B,OAAO,CAAC,YAAY;YAIN,WAAW;IA+BzB,OAAO,CAAC,+BAA+B;IAsBvC,OAAO,CAAC,wBAAwB;IA6BhC,OAAO,CAAC,8BAA8B;YAYxB,mBAAmB;IAUjC,OAAO,CAAC,qBAAqB;CA6C9B"}