[**European Parliament MCP Server API v1.3.9**](../../../README.md)

***

[European Parliament MCP Server API](../../../modules.md) / [utils/rateLimiter](../README.md) / RateLimiter

# Class: RateLimiter

Defined in: [utils/rateLimiter.ts:79](https://github.com/Hack23/European-Parliament-MCP-Server/blob/main/src/utils/rateLimiter.ts#L79)

Token bucket rate limiter implementation

## Constructors

### Constructor

> **new RateLimiter**(`options`): `RateLimiter`

Defined in: [utils/rateLimiter.ts:85](https://github.com/Hack23/European-Parliament-MCP-Server/blob/main/src/utils/rateLimiter.ts#L85)

#### Parameters

##### options

`RateLimiterOptions`

#### Returns

`RateLimiter`

## Properties

### intervalMs

> `private` `readonly` **intervalMs**: `number`

Defined in: [utils/rateLimiter.ts:82](https://github.com/Hack23/European-Parliament-MCP-Server/blob/main/src/utils/rateLimiter.ts#L82)

***

### lastRefill

> `private` **lastRefill**: `number`

Defined in: [utils/rateLimiter.ts:83](https://github.com/Hack23/European-Parliament-MCP-Server/blob/main/src/utils/rateLimiter.ts#L83)

***

### tokens

> `private` **tokens**: `number`

Defined in: [utils/rateLimiter.ts:80](https://github.com/Hack23/European-Parliament-MCP-Server/blob/main/src/utils/rateLimiter.ts#L80)

***

### tokensPerInterval

> `private` `readonly` **tokensPerInterval**: `number`

Defined in: [utils/rateLimiter.ts:81](https://github.com/Hack23/European-Parliament-MCP-Server/blob/main/src/utils/rateLimiter.ts#L81)

## Methods

### getAvailableTokens()

> **getAvailableTokens**(): `number`

Defined in: [utils/rateLimiter.ts:291](https://github.com/Hack23/European-Parliament-MCP-Server/blob/main/src/utils/rateLimiter.ts#L291)

Returns the number of tokens currently available in the bucket.

Triggers a refill calculation based on elapsed time before returning
the value, so the result reflects the current real-time availability.

#### Returns

`number`

Current token count (may be fractional; floor before display)

#### Example

```typescript
const tokens = rateLimiter.getAvailableTokens();
console.log(`${tokens} / ${rateLimiter.getMaxTokens()} tokens available`);
```

#### Since

0.8.0

***

### getMaxTokens()

> **getMaxTokens**(): `number`

Defined in: [utils/rateLimiter.ts:311](https://github.com/Hack23/European-Parliament-MCP-Server/blob/main/src/utils/rateLimiter.ts#L311)

Returns the maximum token capacity of this bucket.

Equal to the `tokensPerInterval` value passed at construction time.
Does **not** trigger a refill calculation.

#### Returns

`number`

Maximum number of tokens the bucket can hold

#### Example

```typescript
const max = rateLimiter.getMaxTokens(); // e.g. 100
```

#### Since

0.8.0

***

### getStatus()

> **getStatus**(): [`RateLimiterStatus`](../interfaces/RateLimiterStatus.md)

Defined in: [utils/rateLimiter.ts:333](https://github.com/Hack23/European-Parliament-MCP-Server/blob/main/src/utils/rateLimiter.ts#L333)

Returns a typed status snapshot for health checks and monitoring.

Triggers a refill calculation so the snapshot reflects real-time bucket
state. Useful for `/health` endpoints and Prometheus exporters.

#### Returns

[`RateLimiterStatus`](../interfaces/RateLimiterStatus.md)

Current [RateLimiterStatus](../interfaces/RateLimiterStatus.md) snapshot with `availableTokens`,
  `maxTokens`, and `utilizationPercent` (0–100)

#### Example

```typescript
const status = rateLimiter.getStatus();
console.log(`${status.utilizationPercent}% utilized`);
// e.g. "45% utilized"
```

#### Since

0.8.0

***

### refill()

> `private` **refill**(): `void`

Defined in: [utils/rateLimiter.ts:132](https://github.com/Hack23/European-Parliament-MCP-Server/blob/main/src/utils/rateLimiter.ts#L132)

Refill tokens based on elapsed time

#### Returns

`void`

***

### removeTokens()

> **removeTokens**(`count`, `options?`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`RateLimitResult`](../type-aliases/RateLimitResult.md)\>

Defined in: [utils/rateLimiter.ts:180](https://github.com/Hack23/European-Parliament-MCP-Server/blob/main/src/utils/rateLimiter.ts#L180)

Attempts to consume `count` tokens from the bucket, waiting asynchronously
until tokens are available or the timeout expires.

Refills the bucket based on elapsed time before each check. If sufficient
tokens are available they are consumed immediately. Otherwise the method
sleeps until the bucket has enough tokens and retries. If the required wait
would exceed `options.timeoutMs` (default **5000 ms**) the call returns
immediately with `allowed: false` and a `retryAfterMs` hint. The timeout
is enforced as a hard deadline: even if a sleep fires slightly late due to
event-loop delay, tokens are never consumed after the deadline has elapsed.

#### Parameters

##### count

`number`

Number of tokens to consume (must be a finite integer ≥ 1 and ≤ `tokensPerInterval`); throws for invalid values

##### options?

###### timeoutMs?

`number`

Maximum time to wait in milliseconds (default 5000); non-finite or negative values are coerced to `0`, meaning the call never blocks and returns `allowed: false` immediately if tokens are unavailable

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`RateLimitResult`](../type-aliases/RateLimitResult.md)\>

Promise resolving to a [RateLimitResult](../type-aliases/RateLimitResult.md). `allowed` is `true`
  when tokens were consumed, `false` when the timeout was reached.
  `remainingTokens` is always a non-negative integer (`Math.floor` of the
  internal fractional bucket state); it may differ from
  [RateLimiter.getAvailableTokens](#getavailabletokens) which returns the raw fractional value.

#### Example

```typescript
const result = await rateLimiter.removeTokens(1);
if (!result.allowed) {
  console.warn(`Rate limited – retry after ${result.retryAfterMs}ms`);
} else {
  const data = await fetchFromEPAPI('/meps');
}
```

#### Security

Prevents abusive high-frequency requests to the EP API.
  Per ISMS Policy AC-003, rate limiting is a mandatory access control.

#### Since

0.8.0

***

### reset()

> **reset**(): `void`

Defined in: [utils/rateLimiter.ts:361](https://github.com/Hack23/European-Parliament-MCP-Server/blob/main/src/utils/rateLimiter.ts#L361)

Resets the bucket to full capacity and clears the refill timer.

Useful in tests or after a planned maintenance window where queued
demand should not be penalised by an already-depleted bucket.

#### Returns

`void`

#### Example

```typescript
afterEach(() => {
  rateLimiter.reset();
});
```

#### Since

0.8.0

***

### tryRemoveTokens()

> **tryRemoveTokens**(`count`): `boolean`

Defined in: [utils/rateLimiter.ts:256](https://github.com/Hack23/European-Parliament-MCP-Server/blob/main/src/utils/rateLimiter.ts#L256)

Attempts to consume `count` tokens without throwing on failure.

Synchronous alternative to [removeTokens](#removetokens) that returns `false`
instead of waiting when the bucket lacks tokens. Useful in hot paths
where callers want to branch on availability rather than await a refill.

**Note:** This method still throws for invalid `count` arguments (non-integer,
`< 1`, or exceeding bucket capacity). It only avoids throwing when there are
insufficient tokens in the bucket at the time of the call.

#### Parameters

##### count

`number`

Number of tokens to consume (must be a finite integer ≥ 1 and ≤ `tokensPerInterval`); throws for invalid values

#### Returns

`boolean`

`true` if tokens were successfully consumed, `false` if the
  bucket did not have enough tokens (bucket is left unchanged)

#### Example

```typescript
if (!rateLimiter.tryRemoveTokens(1)) {
  return { error: 'Rate limit exceeded. Please try again later.' };
}
const data = await fetchFromEPAPI('/meps');
```

#### Since

0.8.0

***

### resolveTimeout()

> `private` `static` **resolveTimeout**(`rawTimeoutMs`): `number`

Defined in: [utils/rateLimiter.ts:123](https://github.com/Hack23/European-Parliament-MCP-Server/blob/main/src/utils/rateLimiter.ts#L123)

Coerce an optional timeoutMs value to a safe finite number >= 0.

#### Parameters

##### rawTimeoutMs

`number` \| `undefined`

#### Returns

`number`
