Class BaseEPClient

Base class for European Parliament API sub-clients.

Holds the shared HTTP machinery: LRU cache, token-bucket rate limiter, timeout/abort controller, and retry logic. Sub-clients extend this class and call the protected get() helper for all HTTP requests.

BaseEPClient

Hierarchy (View Summary)

BaseEPClient

Constructors

constructor

new BaseEPClient(
config?: EPClientConfig,
shared?: EPSharedResources,
): BaseEPClient
Creates a BaseEPClient.

When shared is provided the constructor reuses those pre-built resources instead of allocating new ones; this is the mechanism used by the facade to ensure all sub-clients share one cache and one rate-limiter.
Parameters
- config: EPClientConfig = {}
  Client configuration (used when shared is absent)
- Optionalshared: EPSharedResources
  Pre-built shared resources (passed by facade to sub-clients)
Returns BaseEPClient
- Defined in clients/ep/baseClient.ts:279

Properties

`Protected` `Readonly`baseURL

baseURL: string

European Parliament API base URL.

`Protected` `Readonly`cache

cache: LRUCache<string, Record<string, unknown>>

LRU cache for API responses.

`Private` `Readonly`cacheCounters

cacheCounters: { hits: number; misses: number }

Shared cache hit/miss counters (shared via EPSharedResources when used as sub-client).

`Protected` `Readonly`enableRetry

enableRetry: boolean

Enable automatic retry on transient failures.

`Protected` `Readonly`maxResponseBytes

maxResponseBytes: number

Maximum allowed response body size in bytes.

`Protected` `Readonly`maxRetries

maxRetries: number

Maximum number of retry attempts.

`Protected` `Readonly`rateLimiter

rateLimiter: RateLimiter

Token bucket rate limiter.

`Protected` `Readonly`timeoutMs

timeoutMs: number

Request timeout in milliseconds.

Methods

`Private`buildRequestUrl

buildRequestUrl(endpoint: string, params?: Record<string, unknown>): URL
Private
Builds the full request URL from endpoint + optional params.
Parameters
- endpoint: string
- Optionalparams: Record<string, unknown>
Returns URL
- Defined in clients/ep/baseClient.ts:313

clearCache

clearCache(): void
Clears all entries from the LRU cache.

Returns void
- Defined in clients/ep/baseClient.ts:556

`Private`fetchWithRetry

fetchWithRetry<T>(url: URL, endpoint: string): Promise<T>
Private
Wraps a fetch call with the configured retry policy.
Type Parameters
- T
Parameters
- url: URL
- endpoint: string
Returns Promise<T>
- Defined in clients/ep/baseClient.ts:455

`Private`fetchWithTimeout

fetchWithTimeout<T>(url: URL, endpoint: string): Promise<T>
Private
Executes the HTTP fetch with timeout/abort support and response size guard.
Type Parameters
- T
Parameters
- url: URL
- endpoint: string
Returns Promise<T>
- Defined in clients/ep/baseClient.ts:407

`Protected`get

get<T extends Record<string, unknown>>(
endpoint: string,
params?: Record<string, unknown>,
): Promise<T>
Protected
Executes a cached, rate-limited GET request to the EP API.
Type Parameters
- T extends Record<string, unknown>
  Expected response type (extends Record<string, unknown>)
Parameters
- endpoint: string
  API endpoint path (relative to baseURL)
- Optionalparams: Record<string, unknown>
  Optional query parameters
Returns Promise<T>
Promise resolving to the typed API response

Throws
On HTTP errors, network failures, or parse failures
- Defined in clients/ep/baseClient.ts:496

`Private`getCacheKey

getCacheKey(endpoint: string, params?: Record<string, unknown>): string
Private
Generates a deterministic cache key.
Parameters
- endpoint: string
  API endpoint path
- Optionalparams: Record<string, unknown>
  Optional query parameters
Returns string
JSON string used as cache key
- Defined in clients/ep/baseClient.ts:543

getCacheStats

getCacheStats(): {
    hitRate: number;
    hits: number;
    maxSize: number;
    misses: number;
    size: number;
}
Returns cache statistics for monitoring and debugging.

Returns { hitRate: number; hits: number; maxSize: number; misses: number; size: number }
{ size, maxSize, hitRate, hits, misses }
- Defined in clients/ep/baseClient.ts:565

`Private`readStreamedBody

readStreamedBody<T>(response: Response): Promise<T>
Private
Reads the response body as a stream, enforcing the response size cap. Used as a fallback when the content-length header is absent (e.g. chunked transfer encoding). Accumulates all chunks and parses the result as JSON.
Type Parameters
- T
Parameters
- response: Response
Returns Promise<T>
- Defined in clients/ep/baseClient.ts:362

`Private`shouldRetryRequest

shouldRetryRequest(error: unknown): boolean
Private
Returns true when an error should trigger a retry.

Retries on:
- 429 Too Many Requests (rate-limited by EP API; exponential backoff applied)
- 5xx Server Errors (transient server failures)
- Network / unknown errors
Does NOT retry on 4xx client errors (except 429).
Parameters
- error: unknown
Returns boolean
- Defined in clients/ep/baseClient.ts:347

`Private`toAPIError

toAPIError(error: unknown, endpoint: string): APIError
Private
Converts a caught error to a typed APIError.
Parameters
- error: unknown
- endpoint: string
Returns APIError
- Defined in clients/ep/baseClient.ts:471

`Private` `Static`resolveConfig

resolveConfig(
    config: EPClientConfig,
): {
    baseURL: string;
    cacheTTL: number;
    enableRetry: boolean;
    maxCacheSize: number;
    maxResponseBytes: number;
    maxRetries: number;
    rateLimiter: RateLimiter;
    timeoutMs: number;
}
Private
Resolves all EPClientConfig options to their final values with defaults applied. Extracted to keep constructor complexity within limits.
Parameters
- config: EPClientConfig
Returns {
    baseURL: string;
    cacheTTL: number;
    enableRetry: boolean;
    maxCacheSize: number;
    maxResponseBytes: number;
    maxRetries: number;
    rateLimiter: RateLimiter;
    timeoutMs: number;
}
- Defined in clients/ep/baseClient.ts:236

Class BaseEPClient

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns BaseEPClient

Properties

Protected ReadonlybaseURL

Protected Readonlycache

Private ReadonlycacheCounters

Protected ReadonlyenableRetry

Protected ReadonlymaxResponseBytes

Protected ReadonlymaxRetries

Protected ReadonlyrateLimiter

Protected ReadonlytimeoutMs

Methods

PrivatebuildRequestUrl

Parameters

Returns URL

clearCache

Returns void

PrivatefetchWithRetry

Type Parameters

Parameters

Returns Promise<T>

PrivatefetchWithTimeout

Type Parameters

Parameters

Returns Promise<T>

Protectedget

Type Parameters

Parameters

Returns Promise<T>

Throws

PrivategetCacheKey

Parameters

Returns string

getCacheStats

Returns { hitRate: number; hits: number; maxSize: number; misses: number; size: number }

PrivatereadStreamedBody

Type Parameters

Parameters

Returns Promise<T>

PrivateshouldRetryRequest

Parameters

Returns boolean

PrivatetoAPIError

Parameters

Returns APIError

Private StaticresolveConfig

Parameters

Returns { baseURL: string; cacheTTL: number; enableRetry: boolean; maxCacheSize: number; maxResponseBytes: number; maxRetries: number; rateLimiter: RateLimiter; timeoutMs: number;}

Settings

On This Page

`Protected` `Readonly`baseURL

`Protected` `Readonly`cache

`Private` `Readonly`cacheCounters

`Protected` `Readonly`enableRetry

`Protected` `Readonly`maxResponseBytes

`Protected` `Readonly`maxRetries

`Protected` `Readonly`rateLimiter

`Protected` `Readonly`timeoutMs

`Private`buildRequestUrl

`Private`fetchWithRetry

`Private`fetchWithTimeout

`Protected`get

`Private`getCacheKey

`Private`readStreamedBody

`Private`shouldRetryRequest

`Private`toAPIError

`Private` `Static`resolveConfig

Returns {
baseURL: string;
cacheTTL: number;
enableRetry: boolean;
maxCacheSize: number;
maxResponseBytes: number;
maxRetries: number;
rateLimiter: RateLimiter;
timeoutMs: number;
}