> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# ProviderRegistry

> The ProviderRegistry manages dependency injection providers within a scope. It handles provider instantiation, scoping, and lifecycle management.

## Overview

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { ProviderRegistry } from '@frontmcp/sdk';

// Access via scope
const providers = scope.providers;

// Get a singleton provider
const logger = providers.get(LoggerToken);

// Get a scoped provider
const service = providers.getScoped(ServiceToken, views);
```

## Methods

### get()

Get a DEFAULT-scoped (singleton) provider.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
get<T>(token: Token<T>): T
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const logger = registry.get(LoggerToken);
const config = registry.get(ConfigToken);
```

### getScoped()

Get a provider from given views (for session/request scoped providers).

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
getScoped<T>(token: Token<T>, views: ProviderViews): T
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const views = registry.buildViews(sessionKey, contextProviders);
const session = registry.getScoped(SessionToken, views);
```

### resolve()

Lightweight synchronous resolver for app-scoped DI.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
resolve<T>(cls: Class<T>): T
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const service = registry.resolve(MyService);
```

### resolveBootstrapDep()

Resolve a dependency usable during bootstrap phase.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
resolveBootstrapDep<T>(token: Token<T>): T
```

### getProviders()

Get all provider entries.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
getProviders(): ReadonlyArray<ProviderEntry>
```

### buildViews()

Build provider views for different scopes.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
buildViews(
  sessionKey: string,
  contextProviders?: Map<Token, unknown>
): ProviderViews
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const views = registry.buildViews('session-123', new Map([
  [RequestToken, currentRequest],
]));
```

### addRegistry()

Add a registry by type.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
addRegistry<T>(type: RegistryType, value: T): void
```

### getRegistries()

Get registries by type.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
getRegistries<T>(type: RegistryType): T[]
```

### getHooksRegistry()

Get the hooks registry.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
getHooksRegistry(): HookRegistry
```

### getScopeRegistry()

Get the scope registry.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
getScopeRegistry(): ScopeRegistry
```

### mergeFromRegistry()

Merge providers from another registry.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
mergeFromRegistry(providedBy: Token, exported: ProviderExport[]): void
```

### getProviderInfo()

Get exported provider definitions.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
getProviderInfo(token: Token): ProviderDef | undefined
```

### injectProvider()

Inject a provider value directly.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
injectProvider<T>(injected: InjectedProvider<T>): void
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
registry.injectProvider({
  token: ConfigToken,
  value: { debug: true },
});
```

### addDynamicProviders()

Add providers dynamically at runtime.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
addDynamicProviders(dynamicProviders: DynamicProvider[]): void
```

## Session Management

### cleanupSession()

Clean up a specific session's provider cache.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
cleanupSession(sessionKey: string): void
```

### cleanupExpiredSessions()

Clean up expired sessions from cache.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
cleanupExpiredSessions(): void
```

### startSessionCleanup()

Start background session cleanup timer.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
startSessionCleanup(): void
```

### stopSessionCleanup()

Stop background session cleanup timer.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
stopSessionCleanup(): void
```

### getSessionCacheStats()

Get session cache statistics.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
getSessionCacheStats(): SessionCacheStats
```

### isSessionCacheEnabled()

Check if session caching is enabled.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
isSessionCacheEnabled(): boolean
```

### dispose()

Dispose registry and clean up all resources.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
dispose(): void
```

## Server/Scope Access

### getActiveScope()

Get the active scope.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
getActiveScope(): Scope
```

### getActiveServer()

Get the active server.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
getActiveServer(): Server
```

## Provider Scopes

FrontMCP supports multiple provider scopes:

| Scope       | Description                | Lifecycle        |
| ----------- | -------------------------- | ---------------- |
| `SINGLETON` | Shared across all requests | Server lifetime  |
| `SESSION`   | Per-session instance       | Session lifetime |
| `REQUEST`   | Per-request instance       | Request lifetime |
| `CONTEXT`   | Per-execution context      | Context lifetime |

<Note>
  In distributed/serverless mode, `SESSION` is normalized to `CONTEXT` to avoid stale instances.
</Note>

## Provider Views

Provider views represent the hierarchy of available providers:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface ProviderViews {
  singleton: Map<Token, unknown>;  // Server-wide singletons
  session: Map<Token, unknown>;    // Session-scoped instances
  context: Map<Token, unknown>;    // Context-scoped instances
}
```

## Indexes

| Index        | Key            | Description                         |
| ------------ | -------------- | ----------------------------------- |
| `providedBy` | `Token`        | Which registry provided each token  |
| `order`      | `number`       | Topological order for instantiation |
| `registries` | `RegistryType` | Map of registries by kind           |

## Session Caching

The registry implements LRU eviction and TTL-based session caching:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
// Session cache stats
const stats = registry.getSessionCacheStats();
console.log(`Active sessions: ${stats.activeCount}`);
console.log(`Cache hits: ${stats.hits}`);
console.log(`Cache misses: ${stats.misses}`);
```

## Provider Definition

Providers are defined with:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface ProviderDef<T> {
  token: Token<T>;                    // Injection token
  useClass?: Class<T>;                // Class to instantiate
  useFactory?: () => T | Promise<T>;  // Factory function
  useValue?: T;                       // Direct value
  scope?: ProviderScope;              // Lifecycle scope
  deps?: Token[];                     // Dependencies
}
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@Provider({
  token: CacheToken,
  useFactory: () => new RedisCache(),
  scope: ProviderScope.SINGLETON,
})
class CacheProvider { }
```

## Related

* [Provider Decorator](/frontmcp/sdk-reference/decorators/provider)
* [Extensibility: Providers](/frontmcp/extensibility/providers)
* [Registries Overview](/frontmcp/sdk-reference/registries/overview)