RateLimiter
Coordinates rate limits through shared persistent storage.
The RateLimiter service consumes tokens for string keys using fixed-window counters or token-bucket state. It can protect external APIs, enforce quotas, or throttle workers across fibers and processes that share the same store. This module includes helpers that fail when a limit is exceeded, return the delay needed before continuing, or wrap an effect so it waits automatically. It also defines the store service and in-memory or Redis-backed store layers.
Accessors
makeWithRateLimiter
Signature
declare const makeWithRateLimiter: Effect.Effect< (options: { readonly algorithm?: "fixed-window" | "token-bucket"; readonly key: string; readonly limit: number; readonly onExceeded?: "delay" | "fail"; readonly tokens?: number; readonly window: Duration.Input; }) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | RateLimiterError, R>, never, RateLimiter>;Sleeps when the rate limit is exceeded.
Signature
declare function sleep( self: RateLimiter,): (options: { readonly algorithm?: "fixed-window" | "token-bucket"; readonly key: string; readonly limit: number; readonly tokens?: number; readonly window: Input;}) => Effect<ConsumeResult, RateLimiterError>;declare function sleep( self: RateLimiter, options: { readonly algorithm?: "fixed-window" | "token-bucket"; readonly key: string; readonly limit: number; readonly tokens?: number; readonly window: Input; },): Effect<ConsumeResult, RateLimiterError>;Constructors
Creates a RateLimiter from the current RateLimiterStore.
Details
The limiter supports fixed-window and token-bucket algorithms and either fails or returns a delay when a limit is exceeded.
Signature
declare const make: Effect.Effect<RateLimiter, never, RateLimiterStore>;makeStoreRedis
Creates a Redis-backed RateLimiterStore using Lua scripts and the configured key prefix.
Signature
declare const makeStoreRedis: ( ...args: [ options?: { readonly prefix?: string; }, ]) => Effect< { readonly adaptiveConsume: ( options: AdaptiveConsumeOptions, ) => Effect<AdaptiveConsumeResult, RateLimiterError>; readonly adaptiveFeedback: (options: AdaptiveFeedbackOptions) => Effect<void, RateLimiterError>; readonly fixedWindow: (options: { readonly key: string; readonly limit: number | undefined; readonly refillRate: Duration; readonly tokens: number; }) => Effect<readonly [number, number], RateLimiterError>; readonly tokenBucket: (options: { readonly allowOverflow: boolean; readonly key: string; readonly limit: number; readonly refillRate: Duration; readonly tokens: number; }) => Effect<number, RateLimiterError>; }, never, Redis>;Errors
RateLimiterError
Error raised by rate limiter operations, wrapping a concrete failure reason.
Signature
declare class RateLimiterError extends { readonly _tag: "RateLimiterError"; readonly reason: RateLimitExceeded | RateLimitStoreError;} & YieldableError<this> { constructor(props: { readonly reason: RateLimiterErrorReason; }); readonly "~@effect/experimental/RateLimiter/RateLimiterError": "~@effect/experimental/RateLimiter/RateLimiterError"; message: string;}RateLimiterErrorReason
Schema for all reasons that can be carried by RateLimiterError.
Signature
declare const RateLimiterErrorReason: Union<[typeof RateLimitExceeded, typeof RateLimitStoreError]>;RateLimiterErrorReason type
Union of reasons carried by RateLimiterError.
Signature
type RateLimiterErrorReason = RateLimitExceeded | RateLimitStoreError;RateLimitExceeded
Error reason for a rate-limit check that exceeded the configured limit.
Details
Includes the affected key, limit, remaining token count, and retry delay.
Signature
declare class RateLimitExceeded extends { readonly _tag: "RateLimitExceeded"; readonly key: string; readonly limit: number; readonly remaining: number; readonly retryAfter: Duration;} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "RateLimitExceeded"; readonly key: string; readonly limit: number; readonly remaining: number; readonly retryAfter: Duration; }, options?: MakeOptions]); message: string;}RateLimitStoreError
Error reason for failures in the backing RateLimiterStore.
Signature
declare class RateLimitStoreError extends { readonly _tag: "RateLimitStoreError"; readonly cause?: unknown; readonly message: string;} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "RateLimitStoreError"; readonly cause?: unknown; readonly message: string; }, options?: MakeOptions]);}Layers
Provides RateLimiter using the current RateLimiterStore.
Signature
declare const layer: Layer.Layer<RateLimiter, never, RateLimiterStore>;layerStoreMemory
Provides a process-local in-memory RateLimiterStore.
Signature
declare const layerStoreMemory: Layer.Layer<RateLimiterStore>;layerStoreRedis
Provides a Redis-backed RateLimiterStore using makeStoreRedis.
Signature
declare const layerStoreRedis: (options?: { readonly prefix?: string;}) => Layer.Layer<RateLimiterStore, never, Redis.Redis>;layerStoreRedisConfig
Provides a Redis-backed RateLimiterStore from wrapped configuration options.
Signature
declare function layerStoreRedisConfig( options: | { readonly prefix?: Config<string | undefined>; } | Config<{ readonly prefix?: string; }>,): Layer<RateLimiterStore, ConfigError, Redis>;Models
AdaptiveConsumeResult interface
Metadata returned after consuming tokens from the adaptive rate limiter store.
Signature
interface AdaptiveConsumeResult { readonly delay: Duration; readonly epoch: number; readonly phase: AdaptivePhase;}AdaptivePhase type
Phase of adaptive rate limiting driven by server feedback.
Signature
type AdaptivePhase = "inactive" | "cooldown" | "learning" | "learned";ConsumeResult interface
Metadata returned after consuming tokens from a rate limiter.
Signature
interface ConsumeResult { readonly delay: Duration; readonly limit: number; readonly remaining: number; readonly resetAfter: Duration;}RateLimiter interface
Service for consuming rate-limit tokens for a key using fixed-window or token-bucket algorithms.
Signature
interface RateLimiter { readonly "~effect/persistence/RateLimiter": "~effect/persistence/RateLimiter"; readonly adaptiveConsume: ( options: AdaptiveConsumeOptions, ) => Effect<AdaptiveConsumeResult, RateLimiterError>; readonly adaptiveFeedback: (options: AdaptiveFeedbackOptions) => Effect<void, RateLimiterError>; readonly consume: (options: { readonly algorithm?: "fixed-window" | "token-bucket"; readonly key: string; readonly limit: number; readonly onExceeded?: "delay" | "fail"; readonly tokens?: number; readonly window: Input; }) => Effect<ConsumeResult, RateLimiterError>;}Options
AdaptiveConsumeOptions interface
Options for consuming tokens from the adaptive rate limiter store.
Signature
interface AdaptiveConsumeOptions { readonly fallbackLimit: number; readonly fallbackWindow: Duration; readonly key: string; readonly tokens: number;}AdaptiveFeedbackOptions interface
Options for reporting response feedback to the adaptive rate limiter store.
Signature
interface AdaptiveFeedbackOptions { readonly epoch: number; readonly key: string; readonly retryAfter: Duration | undefined; readonly status: number; readonly tokens: number;}Services
RateLimiter
Service tag for persistent token-consumption services.
When to use
Use to access or provide rate-limit checks backed by fixed-window counters or token-bucket state.
Signature
declare const RateLimiter: Service<RateLimiter, RateLimiter>;RateLimiterStore
Defines the low-level backing store for rate-limit state.
When to use
Use to provide the shared counter storage and adaptive feedback state used by persistent rate-limit checks.
Signature
declare class RateLimiterStore extends Shape< "effect/persistence/RateLimiter/RateLimiterStore", { readonly adaptiveConsume: ( options: AdaptiveConsumeOptions, ) => Effect<AdaptiveConsumeResult, RateLimiterError>; readonly adaptiveFeedback: (options: AdaptiveFeedbackOptions) => Effect<void, RateLimiterError>; readonly fixedWindow: (options: { readonly key: string; readonly limit: number | undefined; readonly refillRate: Duration; readonly tokens: number; }) => Effect<readonly [number, number], RateLimiterError>; readonly tokenBucket: (options: { readonly allowOverflow: boolean; readonly key: string; readonly limit: number; readonly refillRate: Duration; readonly tokens: number; }) => Effect<number, RateLimiterError>; }, this> { constructor(_: never);}Type IDs
ErrorTypeId
Runtime type identifier for RateLimiterError.
Signature
declare const ErrorTypeId: ErrorTypeId;ErrorTypeId type
Type-level identifier used to brand RateLimiterError values.
Signature
type ErrorTypeId = "~@effect/experimental/RateLimiter/RateLimiterError";Runtime type identifier for RateLimiter values.
Signature
declare const TypeId: TypeId;Type-level identifier used to brand RateLimiter values.
Signature
type TypeId = "~effect/persistence/RateLimiter";
Accesses a function that applies rate limiting to an effect.