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:283

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:317

clearCache

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

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

`Private`fetchWithRetry

fetchWithRetry<T>(
    url: URL,
    endpoint: string,
    minimumTimeoutMs?: number,
): Promise<T>
Private
Wraps a fetch call with the configured retry policy.
Type Parameters
- T
Parameters
- url: URL
  Fully resolved request URL
- endpoint: string
  Relative endpoint path (for error messages)
- OptionalminimumTimeoutMs: number
  Optional per-request minimum timeout (ms)
Returns Promise<T>
- Defined in clients/ep/baseClient.ts:570

`Private`fetchWithTimeout

fetchWithTimeout<T>(
    url: URL,
    endpoint: string,
    minimumTimeoutMs?: number,
): Promise<T>
Private
Executes the HTTP fetch with timeout/abort support and response size guard.
Type Parameters
- T
Parameters
- url: URL
  Fully resolved request URL
- endpoint: string
  Relative endpoint path (for error messages)
- OptionalminimumTimeoutMs: number
  Optional per-request minimum timeout (ms). When provided, the effective timeout is Math.max(minimumTimeoutMs, this.timeoutMs), so it acts as a floor that the global timeout can still extend. Use for known slow EP API endpoints (e.g. procedures/feed, events/feed).
Returns Promise<T>
- Defined in clients/ep/baseClient.ts:488

`Protected`get

get<T extends Record<string, unknown>>(
    endpoint: string,
    params?: Record<string, unknown>,
    minimumTimeoutMs?: number,
): 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
- OptionalminimumTimeoutMs: number
  Optional per-request minimum timeout in milliseconds. When provided, the effective timeout is Math.max(minimumTimeoutMs, this.timeoutMs), so the global timeout (set via --timeout or EP_REQUEST_TIMEOUT_MS) can still extend it beyond the per-endpoint minimum. Use for known slow EP API endpoints such as procedures/feed and events/feed.
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:626

`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:674

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:703

`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:388

`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:351

`Private`toAPIError

toAPIError(error: unknown, endpoint: string): APIError
Private
Converts a caught error to a typed APIError. For timeout errors, the actual timeout value is read from the TimeoutError instance (which carries the effective value used by withTimeoutAndAbort), avoiding the need to re-validate or recompute the per-endpoint minimum here.
Parameters
- error: unknown
  The caught error
- endpoint: string
  Relative endpoint path (for error messages)
Returns APIError
- Defined in clients/ep/baseClient.ts:592

`Private` `Static`parseJsonLdBytes

parseJsonLdBytes(bytes: Uint8Array): JSONLDResponse
Private
Parses a byte buffer as JSON-LD. Returns an empty JSON-LD shape for zero-byte bodies (the EP API sends these for out-of-range offsets). Non-empty bodies must contain valid JSON; any SyntaxError is allowed to propagate so callers (including single-entity endpoints) fail fast instead of receiving a misleading empty-list shape.
Parameters
- bytes: Uint8Array
Returns JSONLDResponse
- Defined in clients/ep/baseClient.ts:375

`Private` `Static`parseResponseJson

parseResponseJson<T>(response: Response): Promise<T>
Private
Treats a truly empty body as an empty JSON-LD shape; invalid JSON for non-empty bodies is surfaced as an error.
Type Parameters
- T
Parameters
- response: Response
Returns Promise<T>
- Defined in clients/ep/baseClient.ts:434

`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:240

`Private` `Static`validateContentType

validateContentType(response: Response): void
Private
Validates the Content-Type header of an API response. Throws if the response is not JSON (e.g. HTML error pages from reverse proxies). Cancels the response body before throwing to allow connection reuse.

A missing or empty Content-Type header is treated as acceptable because the EP API occasionally omits it on valid JSON responses, and rejecting those would cause false-negative failures.
Parameters
- response: Response
Returns void
- Defined in clients/ep/baseClient.ts:461

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 StaticparseJsonLdBytes

Parameters

Returns JSONLDResponse

Private StaticparseResponseJson

Type Parameters

Parameters

Returns Promise<T>

Private StaticresolveConfig

Parameters

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

Private StaticvalidateContentType

Parameters

Returns void

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`parseJsonLdBytes

`Private` `Static`parseResponseJson

`Private` `Static`resolveConfig

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

`Private` `Static`validateContentType