# @suaveplan/rate-limiter - Enterprise rate limiter: TokenBucket, SlidingWindow, FixedWindow algorithms; tenant multipliers; rule-based routing; pluggable storage; OTel instrumentation

## Summary

Enterprise rate limiter with three algorithms, rule-based routing, tenant multipliers, pluggable storage, and OTel instrumentation.

<!-- begin:auto-docs -->
## Documentation tree

- [fixed-window](./src/core/fixed-window/fixed-window.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [fixed-window](./src/core/fixed-window/fixed-window.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [errors](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [rate-limiter-error](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [rate-limiter.schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
<!-- end:auto-docs -->  - [fixed-window](./src/core/fixed-window/fixed-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter-error](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter.schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [fixed-window](./src/core/fixed-window/fixed-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter-error](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter.schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [fixed-window](./src/core/fixed-window/fixed-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter-error](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter.schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [fixed-window](./src/core/fixed-window/fixed-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_  - [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_  - [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_  - [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_  - [rate-limiter-error](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_  - [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_  - [rate-limiter.schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_  - [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_  - [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_
## Algorithms

| Algorithm | Use case |
|---|---|
| `TokenBucket` | Burst-friendly continuous rate |
| `SlidingWindow` | Smooth per-key limit (default) |
| `FixedWindow` | Coarse counter, lowest memory |

## Quick Start

```ts
import { createRateLimiter } from "@suaveplan/rate-limiter";

const limiter = createRateLimiter({
  defaultConfig: { limit: 100, window: 60_000 },
});

const result = await limiter.check({ key: "user:42" });
if (!result.allowed) {
  console.log(`Retry after ${result.retryAfter}ms`);
}
```

## Rule-based routing

```ts
const limiter = createRateLimiter({
  defaultConfig: { limit: 100, window: 60_000 },
  rules: [
    {
      id: "admin-bypass",
      limit: 0, window: 60_000,
      priority: 100, bypass: true,
      conditions: [{ field: "userId", operator: "in", value: ["admin-1"] }],
    },
    {
      id: "strict-login",
      limit: 5, window: 60_000,
      priority: 50,
      conditions: [{ field: "path", operator: "eq", value: "/login" }],
    },
  ],
  enableTenantLimits: true,
  tenantMultipliers: { enterprise: 10 },
});
```

## Modules

- [`src/errors/rate-limiter-error.md`](src/errors/rate-limiter-error.md) — Error codes and `RateLimiterError`
- [`src/types/rate-limiter.types.md`](src/types/rate-limiter.types.md) — All shared types
- [`src/core/token-bucket/token-bucket.md`](src/core/token-bucket/token-bucket.md) — TokenBucket algorithm
- [`src/core/sliding-window/sliding-window.md`](src/core/sliding-window/sliding-window.md) — SlidingWindow algorithm
- [`src/core/fixed-window/fixed-window.md`](src/core/fixed-window/fixed-window.md) — FixedWindow algorithm
- [`src/core/rate-limiter/rate-limiter.md`](src/core/rate-limiter/rate-limiter.md) — `createRateLimiter` orchestrator
- [`src/storage/storage-adapter/storage-adapter.md`](src/storage/storage-adapter/storage-adapter.md) — `RateLimitStorage` interface
- [`src/storage/memory-storage/memory-storage.md`](src/storage/memory-storage/memory-storage.md) — `MemoryStorage` adapter
- [`src/middleware/rate-limit-middleware/rate-limit-middleware.md`](src/middleware/rate-limit-middleware/rate-limit-middleware.md) — Middleware helpers
- [`src/schemas/rate-limiter.schemas.md`](src/schemas/rate-limiter.schemas.md) — Zod schemas