Class ConnectionStateManager<TService>

Manages the connection state to a backend service.

Generic implementation that works with any client implementing ServiceClient.

Features:

Tracks connection state (disconnected, connecting, connected, error)
Notifies listeners when state changes
Provides current client instance
Supports health check validation
Uses circular buffer for efficient history management (O(1) operations)

Example

const manager = new ConnectionStateManager<MyServiceClient>();
manager.onStateChange((state, client) => {
  if (state === 'connected') {
    console.log('Connected!');
  }
});
await manager.connect(serviceClient);

// With any ServiceClient implementation
const genericManager = new ConnectionStateManager<MyServiceClient>();

Type Parameters

TService extends ServiceClient = ServiceClient
The service client type (must implement ServiceClient)

Index

Constructors

constructor

Methods

clearListeners connect disableAutoReconnect disconnect enableAutoReconnect getClient getHistory getLastError getState isConnected onStateChange reset setConnecting setError

Constructors

constructor

new ConnectionStateManager<TService extends ServiceClient = ServiceClient>(
options?: ConnectionTelemetry | ConnectionStateOptions,
): ConnectionStateManager<TService>
Create a new ConnectionStateManager.
Type Parameters
- TService extends ServiceClient = ServiceClient
  The service client type (must implement ServiceClient)
Parameters
- Optionaloptions: ConnectionTelemetry | ConnectionStateOptions
  Optional configuration (telemetry, healthCheckTimeoutMs). Also accepts a bare ConnectionTelemetry for backwards compatibility.
Returns ConnectionStateManager<TService>
- Defined in src/connection/connection-state.ts:128

Methods

clearListeners

clearListeners(): void
Clear all listeners. Useful for cleanup during shutdown.

Returns void
- Defined in src/connection/connection-state.ts:462

connect

connect(client: TService, skipHealthCheck?: boolean): Promise<boolean>
Set the client and mark as connected. Validates the connection with a health check before completing. Includes OpenTelemetry tracing for the connection process.
Parameters
- client: TService
  The authenticated service client
- skipHealthCheck: boolean = false
  Skip health check validation (for testing)
Returns Promise<boolean>
true if connection was successful
- Defined in src/connection/connection-state.ts:220

disableAutoReconnect

disableAutoReconnect(): void
Disable automatic reconnection. Aborts any in-flight reconnect attempt and removes the listener.

Returns void
- Defined in src/connection/connection-state.ts:374

disconnect

disconnect(): Promise<void>
Disconnect from the backend service. Calls ServiceClient.disconnect if the client implements it, then clears the client reference and sets state to 'disconnected'.

Returns Promise<void>
- Defined in src/connection/connection-state.ts:308

enableAutoReconnect

enableAutoReconnect(options?: ReconnectOptions): void
Enable automatic reconnection with exponential backoff.

When the connection state transitions to 'error', the manager will automatically attempt to reconnect using the stored client instance. Subsequent attempts use exponential backoff up to maxDelayMs.

This handles reconnection to the API backend, NOT MCP transport reconnection (which is client-side, handled by the SDK's StreamableHTTPReconnectionOptions).
Parameters
- Optionaloptions: ReconnectOptions
  Reconnect configuration (all fields optional with sensible defaults)
Returns void
- Defined in src/connection/connection-state.ts:352

getClient

getClient(): TService | null
Get the current service client instance. Returns null if not connected.

Returns TService | null
- Defined in src/connection/connection-state.ts:150

getHistory

getHistory(): readonly ConnectionStateEvent[]
Get the connection state history. Returns the most recent state changes (up to maxHistorySize). History is returned in chronological order (oldest first).

Returns readonly ConnectionStateEvent[]
- Defined in src/connection/connection-state.ts:173

getLastError

getLastError(): Error | null
Get the last error that occurred (if any).

Returns Error | null
- Defined in src/connection/connection-state.ts:164

getState

getState(): ConnectionState
Get the current connection state.

Returns ConnectionState
- Defined in src/connection/connection-state.ts:142

isConnected

isConnected(): boolean
Check if the client is currently connected.

Returns boolean
- Defined in src/connection/connection-state.ts:157

onStateChange

onStateChange(listener: ConnectionStateListener<TService>): () => void
Register a listener for connection state changes.
Parameters
- listener: ConnectionStateListener<TService>
  Function to call when state changes
Returns () => void
Unsubscribe function
- Defined in src/connection/connection-state.ts:198

reset

reset(): void
Reset the connection manager to initial state. Useful for testing or complete reset scenarios.

Returns void
- Defined in src/connection/connection-state.ts:470

setConnecting

setConnecting(): void
Set the connection state to 'connecting'. Call this before attempting to connect.

Returns void
- Defined in src/connection/connection-state.ts:207

setError

setError(error: Error): void
Set connection error state.
Parameters
- error: Error
  The error that occurred
Returns void
- Defined in src/connection/connection-state.ts:334

Class ConnectionStateManager<TService>

Example

Type Parameters

Index

Constructors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns ConnectionStateManager<TService>

Methods

clearListeners

Returns void

connect

Parameters

Returns Promise<boolean>

disableAutoReconnect

Returns void

disconnect

Returns Promise<void>

enableAutoReconnect

Parameters

Returns void

getClient

Returns TService | null

getHistory

Returns readonly ConnectionStateEvent[]

getLastError

Returns Error | null

getState

Returns ConnectionState

isConnected

Returns boolean

onStateChange

Parameters

Returns () => void

reset

Returns void

setConnecting

Returns void

setError

Parameters

Returns void

Settings

On This Page