@stimulcross/rate-limiter 0.0.1

package/tests/integration/limiters/leaky-bucket.spec.ts

@@ -0,0 +1,357 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { type Clock } from '../../../src/core/clock.js';
+import { RateLimitErrorCode } from '../../../src/enums/rate-limit-error-code.js';
+import { RateLimiterDestroyedError } from '../../../src/errors/rate-limiter-destroyed.error.js';
+import { LeakyBucketLimiter } from '../../../src/limiters/leaky-bucket/leaky-bucket.limiter.js';
+import { type LeakyBucketState } from '../../../src/limiters/leaky-bucket/leaky-bucket.state.js';
+import { InMemoryStateStore } from '../../../src/runtime/in-memory-state-store.js';
+
+describe('LeakyBucketLimiter (Integration)', () => {
+	let clock: Clock;
+	let store: InMemoryStateStore<LeakyBucketState>;
+
+	beforeEach(() => {
+		vi.useFakeTimers();
+		vi.setSystemTime(10_000);
+
+		clock = { now: () => Date.now() };
+		store = new InMemoryStateStore(clock);
+	});
+
+	afterEach(() => {
+		vi.clearAllTimers();
+		vi.useRealTimers();
+	});
+
+	describe('Reject mode (immediate decisions)', () => {
+		it('should allow requests within the capacity immediately', async () => {
+			const limiter = new LeakyBucketLimiter({
+				limitBehavior: 'reject',
+				capacity: 2,
+				leakRate: 10,
+				clock,
+				store,
+			});
+
+			const res1 = await limiter.run(async () => 'A');
+			const res2 = await limiter.run(async () => 'B');
+
+			expect(res1).toBe('A');
+			expect(res2).toBe('B');
+		});
+
+		it('should reject requests that exceed the capacity if behavior is "reject"', async () => {
+			const limiter = new LeakyBucketLimiter({
+				limitBehavior: 'reject',
+				capacity: 1,
+				leakRate: 10,
+				clock,
+				store,
+			});
+
+			await limiter.run(() => 'A');
+
+			const promise = limiter.run(() => 'B');
+			await expect(promise).rejects.toMatchObject({ code: RateLimitErrorCode.LimitExceeded });
+		});
+
+		it('should consume multiple units of capacity if cost > 1', async () => {
+			const limiter = new LeakyBucketLimiter({
+				limitBehavior: 'reject',
+				capacity: 5,
+				leakRate: 10,
+				clock,
+				store,
+			});
+
+			await expect(limiter.run(() => 'A', { cost: 3 })).resolves.toBe('A');
+			await expect(limiter.run(() => 'B', { cost: 3 })).rejects.toMatchObject({
+				code: RateLimitErrorCode.LimitExceeded,
+			});
+		});
+
+		it('should allow new requests after space is freed (leaked)', async () => {
+			const limiter = new LeakyBucketLimiter({
+				limitBehavior: 'reject',
+				capacity: 1,
+				leakRate: 10,
+				clock,
+				store,
+			});
+
+			await limiter.run(() => 'A');
+			await expect(limiter.run(() => 'B')).rejects.toMatchObject({ code: RateLimitErrorCode.LimitExceeded });
+
+			// wait for 1 unit to leak
+			await vi.advanceTimersByTimeAsync(100);
+
+			await expect(limiter.run(() => 'C')).resolves.toBe('C');
+		});
+	});
+
+	describe('Enqueue mode (queueing & scheduling)', () => {
+		it('should delay request and execute it when enough space is leaked', async () => {
+			const limiter = new LeakyBucketLimiter({
+				limitBehavior: 'enqueue',
+				capacity: 1,
+				leakRate: 10,
+				clock,
+				store,
+			});
+
+			void limiter.run(() => 'A');
+
+			const pBSpy = vi.fn().mockReturnValue('B');
+			// delay 100ms
+			const pB = limiter.run<unknown>(pBSpy);
+
+			expect(pBSpy).not.toHaveBeenCalled();
+
+			await vi.advanceTimersByTimeAsync(100);
+
+			const result = await pB;
+			expect(pBSpy).toHaveBeenCalledOnce();
+			expect(result).toBe('B');
+		});
+
+		it('should maintain order and timings for multiple queued requests', async () => {
+			const limiter = new LeakyBucketLimiter({
+				limitBehavior: 'enqueue',
+				capacity: 1,
+				leakRate: 10,
+				clock,
+				store,
+			});
+
+			void limiter.run(() => {});
+
+			const results: string[] = [];
+			const push = (val: string) => () => results.push(val);
+
+			// delay +100ms for each task
+			const pA = limiter.run(push('A'));
+			const pB = limiter.run(push('B'));
+			const pC = limiter.run(push('C'));
+
+			await vi.advanceTimersByTimeAsync(100);
+			await pA;
+			expect(results).toEqual(['A']);
+
+			await vi.advanceTimersByTimeAsync(100);
+			await pB;
+			expect(results).toEqual(['A', 'B']);
+
+			await vi.advanceTimersByTimeAsync(100);
+			await pC;
+			expect(results).toEqual(['A', 'B', 'C']);
+		});
+
+		it('should reject with QueueOverflow if executor queue exceeds maxSize', async () => {
+			const limiter = new LeakyBucketLimiter({
+				limitBehavior: 'enqueue',
+				capacity: 1,
+				leakRate: 10,
+				queue: { capacity: 1 },
+				clock,
+				store,
+			});
+
+			const pA = limiter.run(() => 'A');
+			const pB = limiter.run(() => 'B');
+			await vi.advanceTimersByTimeAsync(0);
+
+			// overflow
+			const pC = limiter.run(() => 'C');
+
+			await expect(pC).rejects.toMatchObject({ code: RateLimitErrorCode.QueueOverflow });
+
+			await vi.advanceTimersByTimeAsync(0);
+			await expect(pA).resolves.toBe('A');
+
+			await vi.advanceTimersByTimeAsync(100);
+			await expect(pB).resolves.toBe('B');
+		});
+
+		it('should execute queued tasks based on priority order', async () => {
+			const limiter = new LeakyBucketLimiter({
+				limitBehavior: 'enqueue',
+				capacity: 1,
+				leakRate: 10,
+				clock,
+				store,
+			});
+
+			await limiter.run(() => 'A');
+
+			const order: string[] = [];
+
+			void limiter.run(() => order.push('Lowest'), { priority: 1 });
+			void limiter.run(() => order.push('Highest'), { priority: 5 });
+
+			await vi.advanceTimersByTimeAsync(200);
+
+			expect(order).toEqual(['Highest', 'Lowest']);
+		});
+
+		it('should enqueue the task and reject it with Expired when TTL is reached', async () => {
+			const limiter = new LeakyBucketLimiter({
+				limitBehavior: 'enqueue',
+				capacity: 1,
+				leakRate: 10,
+				queue: { maxWaitMs: 150 },
+				clock,
+				store,
+			});
+
+			const pA = limiter.run(() => 'A');
+			// delay 100ms
+			const pB = limiter.run(() => 'B');
+			// delay 200ms, expires after 150ms
+			const pC = limiter.run(() => 'C');
+			pC.catch(() => {});
+
+			await expect(pA).resolves.toBe('A');
+
+			await vi.advanceTimersByTimeAsync(100);
+			await expect(pB).resolves.toBe('B');
+
+			await vi.advanceTimersByTimeAsync(50);
+			await expect(pC).rejects.toMatchObject({ code: RateLimitErrorCode.Expired });
+		});
+
+		it('should free up the canceled ticket for new requests', async () => {
+			const limiter = new LeakyBucketLimiter({
+				limitBehavior: 'enqueue',
+				capacity: 1,
+				leakRate: 10,
+				clock,
+				store,
+			});
+
+			const pA = limiter.run(() => 'A');
+
+			const controllerB = new AbortController();
+			// delay 100ms
+			const pB = limiter.run(() => 'B', { signal: controllerB.signal });
+
+			const spyC = vi.fn().mockReturnValue('C');
+			// delay 200ms
+			const pC = limiter.run(spyC);
+
+			await vi.advanceTimersByTimeAsync(0);
+
+			// canceling B
+			// the 200ms ticket should be freed up, the consumed token should be returned to the bucket
+			controllerB.abort();
+			await expect(pB).rejects.toMatchObject({ code: RateLimitErrorCode.Cancelled });
+
+			const spyD = vi.fn().mockReturnValue('D');
+			// delay 200ms (it was freed up by canceling B)
+			const pD = limiter.run(spyD);
+
+			await expect(pA).resolves.toBe('A');
+			expect(spyC).not.toHaveBeenCalled();
+			expect(spyD).not.toHaveBeenCalled();
+
+			// t = 10_100
+			// C takes the 100ms ticket created by B
+			await vi.advanceTimersByTimeAsync(100);
+
+			await expect(pC).resolves.toBe('C');
+			expect(spyC).toHaveBeenCalledOnce();
+			expect(spyD).not.toHaveBeenCalled();
+
+			// t = 10_200
+			// D takes the 200ms ticket created by itself
+			await vi.advanceTimersByTimeAsync(100);
+
+			await expect(pD).resolves.toBe('D');
+			expect(spyD).toHaveBeenCalledOnce();
+		});
+	});
+
+	describe('Runtime overrides', () => {
+		it('should allow overriding limitBehavior per task', async () => {
+			const limiter = new LeakyBucketLimiter({
+				limitBehavior: 'reject',
+				capacity: 1,
+				leakRate: 10,
+				clock,
+				store,
+			});
+
+			await limiter.run(() => 'A');
+			const pB = limiter.run(() => 'B', { limitBehavior: 'enqueue' });
+
+			await vi.advanceTimersByTimeAsync(100);
+			await expect(pB).resolves.toBe('B');
+		});
+
+		it('should override max wait time for a specific task and expire it independently', async () => {
+			const limiter = new LeakyBucketLimiter({
+				limitBehavior: 'enqueue',
+				capacity: 1,
+				leakRate: 10,
+				queue: { maxWaitMs: 5000 },
+				clock,
+				store,
+			});
+
+			void limiter.run(() => 'A');
+
+			// delay 100ms
+			const pB = limiter.run(() => 'B');
+
+			// delay 200ms
+			// expires after 150ms, so it should be rejected
+			const pC = limiter.run(() => 'C', { maxWaitMs: 150 });
+			pC.catch(() => {});
+
+			// delay 300ms
+			const pD = limiter.run(() => 'D', { maxWaitMs: 400 });
+
+			// t=10_100
+			await vi.advanceTimersByTimeAsync(100);
+			await expect(pB).resolves.toBe('B');
+
+			// t=10_150
+			await vi.advanceTimersByTimeAsync(50);
+			await expect(pC).rejects.toMatchObject({ code: RateLimitErrorCode.Expired });
+
+			// t=10_300
+			await vi.advanceTimersByTimeAsync(150);
+			await expect(pD).resolves.toBe('D');
+		});
+	});
+
+	describe('State lifecycle', () => {
+		it('should reset limits and clear queued tasks on clear()', async () => {
+			const limiter = new LeakyBucketLimiter({
+				limitBehavior: 'reject',
+				capacity: 1,
+				leakRate: 10,
+				clock,
+				store,
+			});
+
+			await limiter.run(() => 'A');
+
+			await limiter.clear();
+
+			await expect(limiter.run(() => 'B')).resolves.toBe('B');
+		});
+
+		it('should throw RateLimiterDestroyedError after destroy() is called', async () => {
+			const limiter = new LeakyBucketLimiter({
+				capacity: 5,
+				leakRate: 10,
+				clock,
+				store,
+			});
+
+			await limiter.destroy();
+
+			await expect(limiter.run(() => 'A')).rejects.toThrow(RateLimiterDestroyedError);
+		});
+	});
+});

package/tests/integration/limiters/sliding-window-counter.limiter.spec.ts

@@ -0,0 +1,175 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { type Clock, RateLimiterDestroyedError, RateLimitErrorCode } from '../../../src/index.js';
+import {
+	SlidingWindowCounterLimiter,
+	type SlidingWindowCounterState,
+} from '../../../src/limiters/sliding-window-counter/index.js';
+import { InMemoryStateStore } from '../../../src/runtime/in-memory-state-store.js';
+
+describe('SlidingWindowCounterLimiter (Integration)', () => {
+	let clock: Clock;
+	let store: InMemoryStateStore<SlidingWindowCounterState>;
+
+	beforeEach(() => {
+		vi.useFakeTimers();
+		vi.setSystemTime(10_000);
+
+		clock = { now: () => Date.now() };
+		store = new InMemoryStateStore(clock);
+	});
+
+	afterEach(() => {
+		vi.clearAllTimers();
+		vi.useRealTimers();
+	});
+
+	describe('Immediate decisions', () => {
+		it('should allow requests within the limit immediately', async () => {
+			const limiter = new SlidingWindowCounterLimiter({
+				limit: 2,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			const res1 = await limiter.run(async () => 'A');
+			const res2 = await limiter.run(async () => 'B');
+
+			expect(res1).toBe('A');
+			expect(res2).toBe('B');
+		});
+
+		it('should reject requests that exceed the limit', async () => {
+			const limiter = new SlidingWindowCounterLimiter({
+				limit: 1,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			await limiter.run(() => 'A');
+
+			const promise = limiter.run(() => 'B');
+			await expect(promise).rejects.toMatchObject({ code: RateLimitErrorCode.LimitExceeded });
+		});
+
+		it('should consume multiple units of capacity if cost > 1', async () => {
+			const limiter = new SlidingWindowCounterLimiter({
+				limit: 5,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			await expect(limiter.run(() => 'A', { cost: 3 })).resolves.toBe('A');
+			await expect(limiter.run(() => 'B', { cost: 3 })).rejects.toMatchObject({
+				code: RateLimitErrorCode.LimitExceeded,
+			});
+		});
+	});
+
+	describe('Window approximation & slides', () => {
+		it('should completely reset the limit after two full windows have passed', async () => {
+			const limiter = new SlidingWindowCounterLimiter({
+				limit: 1,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			await limiter.run(() => 'A');
+			await expect(limiter.run(() => 'B')).rejects.toMatchObject({ code: RateLimitErrorCode.LimitExceeded });
+
+			await vi.advanceTimersByTimeAsync(2000);
+
+			await expect(limiter.run(() => 'C')).resolves.toBe('C');
+		});
+
+		it('should approximate available capacity based on the weighted previous window', async () => {
+			const limiter = new SlidingWindowCounterLimiter({
+				limit: 10,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			await limiter.run(() => 'A', { cost: 10 });
+			await vi.advanceTimersByTimeAsync(1250);
+
+			await expect(limiter.run(() => 'B', { cost: 4 })).rejects.toMatchObject({
+				code: RateLimitErrorCode.LimitExceeded,
+			});
+
+			await expect(limiter.run(() => 'C', { cost: 3 })).resolves.toBe('C');
+		});
+
+		it('should smoothly decrease weight of previous window as time passes', async () => {
+			const limiter = new SlidingWindowCounterLimiter({
+				limit: 10,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			void limiter.run(() => 'A', { cost: 10 });
+
+			await vi.advanceTimersByTimeAsync(1500);
+
+			await expect(limiter.run(() => 'B', { cost: 5 })).resolves.toBe('B');
+
+			await vi.advanceTimersByTimeAsync(400);
+			await expect(limiter.run(() => 'C', { cost: 5 })).rejects.toMatchObject({
+				code: RateLimitErrorCode.LimitExceeded,
+			});
+			await expect(limiter.run(() => 'D', { cost: 4 })).resolves.toBe('D');
+		});
+	});
+
+	describe('Cancellation', () => {
+		it('should reject immediately if the abort signal is already triggered', async () => {
+			const limiter = new SlidingWindowCounterLimiter({
+				limit: 1,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			const controller = new AbortController();
+			controller.abort();
+
+			await expect(limiter.run(() => 'A', { signal: controller.signal })).rejects.toMatchObject({
+				code: RateLimitErrorCode.Cancelled,
+			});
+		});
+	});
+
+	describe('State lifecycle', () => {
+		it('should reset limits on clear()', async () => {
+			const limiter = new SlidingWindowCounterLimiter({
+				limit: 1,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			await limiter.run(() => 'A');
+
+			await limiter.clear();
+
+			await expect(limiter.run(() => 'B')).resolves.toBe('B');
+		});
+
+		it('should throw RateLimitError(Destroyed) after destroy() is called', async () => {
+			const limiter = new SlidingWindowCounterLimiter({
+				limit: 5,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			await limiter.destroy();
+
+			await expect(limiter.run(() => 'A')).rejects.toThrow(RateLimiterDestroyedError);
+		});
+	});
+});

package/tests/integration/limiters/sliding-window-log.spec.ts

@@ -0,0 +1,185 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { type Clock, RateLimiterDestroyedError, RateLimitErrorCode } from '../../../src/index.js';
+import { SlidingWindowLogLimiter, type SlidingWindowLogState } from '../../../src/limiters/sliding-window-log/index.js';
+import { InMemoryStateStore } from '../../../src/runtime/in-memory-state-store.js';
+
+describe('SlidingWindowLogLimiter (Integration)', () => {
+	let clock: Clock;
+	let store: InMemoryStateStore<SlidingWindowLogState>;
+
+	beforeEach(() => {
+		vi.useFakeTimers();
+		vi.setSystemTime(10_000);
+
+		clock = { now: () => Date.now() };
+		store = new InMemoryStateStore(clock);
+	});
+
+	afterEach(() => {
+		vi.clearAllTimers();
+		vi.useRealTimers();
+	});
+
+	describe('Immediate decisions', () => {
+		it('should allow requests within the limit immediately', async () => {
+			const limiter = new SlidingWindowLogLimiter({
+				limit: 2,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			const res1 = await limiter.run(async () => 'A');
+			const res2 = await limiter.run(async () => 'B');
+
+			expect(res1).toBe('A');
+			expect(res2).toBe('B');
+		});
+
+		it('should reject requests that exceed the limit', async () => {
+			const limiter = new SlidingWindowLogLimiter({
+				limit: 1,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			await limiter.run(() => 'A');
+
+			const promise = limiter.run(() => 'B');
+			await expect(promise).rejects.toMatchObject({ code: RateLimitErrorCode.LimitExceeded });
+		});
+
+		it('should consume multiple units of capacity if cost > 1', async () => {
+			const limiter = new SlidingWindowLogLimiter({
+				limit: 5,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			await expect(limiter.run(() => 'A', { cost: 3 })).resolves.toBe('A');
+			await expect(limiter.run(() => 'B', { cost: 3 })).rejects.toMatchObject({
+				code: RateLimitErrorCode.LimitExceeded,
+			});
+		});
+	});
+
+	describe('Precise log cleanup & sliding window', () => {
+		it('should completely reset the limit after the full window has passed without activity', async () => {
+			const limiter = new SlidingWindowLogLimiter({
+				limit: 1,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			await limiter.run(() => 'A');
+			await expect(limiter.run(() => 'B')).rejects.toMatchObject({ code: RateLimitErrorCode.LimitExceeded });
+
+			await vi.advanceTimersByTimeAsync(1000);
+
+			await expect(limiter.run(() => 'C')).resolves.toBe('C');
+		});
+
+		it('should restore capacity precisely as old requests fall out of the window', async () => {
+			const limiter = new SlidingWindowLogLimiter({
+				limit: 2,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			// t = 10_000
+			await limiter.run(() => 'A');
+
+			// t = 10_400
+			await vi.advanceTimersByTimeAsync(400);
+			await limiter.run(() => 'B');
+
+			// capacity 2/2
+			await expect(limiter.run(() => 'C')).rejects.toMatchObject({ code: RateLimitErrorCode.LimitExceeded });
+
+			// t = 11_000 (A expires)
+			await vi.advanceTimersByTimeAsync(600);
+
+			// capacity 1/2
+			await expect(limiter.run(() => 'D')).resolves.toBe('D');
+			await expect(limiter.run(() => 'E')).rejects.toMatchObject({ code: RateLimitErrorCode.LimitExceeded });
+
+			// t = 11_400 (B expires)
+			await vi.advanceTimersByTimeAsync(400);
+
+			// capacity 1/2 (D is still in window)
+			await expect(limiter.run(() => 'F')).resolves.toBe('F');
+		});
+
+		it('should aggregate simultaneous requests into a single log entry but count their total cost', async () => {
+			const limiter = new SlidingWindowLogLimiter({
+				limit: 5,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			// t = 10_000
+			void limiter.run(() => 'A', { cost: 2 });
+			void limiter.run(() => 'B', { cost: 3 });
+
+			await expect(limiter.run(() => 'C')).rejects.toMatchObject({ code: RateLimitErrorCode.LimitExceeded });
+
+			// t = 11_000 (Both A and B expire simultaneously)
+			await vi.advanceTimersByTimeAsync(1000);
+
+			await expect(limiter.run(() => 'D', { cost: 5 })).resolves.toBe('D');
+		});
+	});
+
+	describe('Cancellation', () => {
+		it('should reject immediately if the abort signal is already triggered', async () => {
+			const limiter = new SlidingWindowLogLimiter({
+				limit: 1,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			const controller = new AbortController();
+			controller.abort();
+
+			await expect(limiter.run(() => 'A', { signal: controller.signal })).rejects.toMatchObject({
+				code: RateLimitErrorCode.Cancelled,
+			});
+		});
+	});
+
+	describe('State lifecycle', () => {
+		it('should reset limits on clear()', async () => {
+			const limiter = new SlidingWindowLogLimiter({
+				limit: 1,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			await limiter.run(() => 'A');
+
+			await limiter.clear();
+
+			await expect(limiter.run(() => 'B')).resolves.toBe('B');
+		});
+
+		it('should throw RateLimitError(Destroyed) after destroy() is called', async () => {
+			const limiter = new SlidingWindowLogLimiter({
+				limit: 5,
+				windowMs: 1000,
+				clock,
+				store,
+			});
+
+			await limiter.destroy();
+
+			await expect(limiter.run(() => 'A')).rejects.toThrow(RateLimiterDestroyedError);
+		});
+	});
+});