@stimulcross/rate-limiter 0.0.1

package/tests/unit/runtime/in-memory-state-store.spec.ts

@@ -0,0 +1,238 @@
+import { describe, expect, it, vi } from 'vitest';
+import { RateLimitError } from '../../../src/errors/rate-limit.error.js';
+import { InMemoryStateStore } from '../../../src/runtime/in-memory-state-store.js';
+
+interface TestClock {
+	now: () => number;
+}
+
+describe('InMemoryStateStore', () => {
+	const createClock = (startMs = 0): { clock: TestClock; advanceBy: (ms: number) => void } => {
+		let nowMs = startMs;
+
+		return {
+			clock: { now: () => nowMs },
+			advanceBy: (ms: number) => {
+				nowMs += ms;
+			},
+		};
+	};
+
+	describe('CRUD operations', () => {
+		it('should return null for missing keys', async () => {
+			const { clock } = createClock(1000);
+			const store = new InMemoryStateStore<string>(clock);
+
+			await expect(store.get('missing')).resolves.toBeNull();
+
+			await store.destroy();
+		});
+
+		it('should store and retrieve the last set value', async () => {
+			const { clock } = createClock(1000);
+			const store = new InMemoryStateStore<string>(clock);
+
+			await store.set('k', 'v1');
+			await store.set('k', 'v2');
+
+			await expect(store.get('k')).resolves.toBe('v2');
+
+			await store.destroy();
+		});
+
+		it('should delete keys properly', async () => {
+			const { clock } = createClock(1000);
+			const store = new InMemoryStateStore<string>(clock);
+
+			await store.set('k', 'v');
+			await store.delete('k');
+
+			await expect(store.get('k')).resolves.toBeNull();
+
+			await store.destroy();
+		});
+	});
+
+	describe('TTL semantics', () => {
+		it('should expire a value strictly after ttlMs has passed', async () => {
+			const { clock, advanceBy } = createClock(1000);
+			const store = new InMemoryStateStore<string>(clock);
+
+			await store.set('k', 'v', 100);
+
+			await expect(store.get('k')).resolves.toBe('v');
+
+			advanceBy(100);
+
+			await expect(store.get('k')).resolves.toBeNull();
+
+			await store.destroy();
+		});
+
+		it('should never expire when ttlMs is not provided', async () => {
+			const { clock, advanceBy } = createClock(1000);
+			const store = new InMemoryStateStore<string>(clock);
+
+			await store.set('k', 'v');
+
+			advanceBy(10_000_000);
+
+			await expect(store.get('k')).resolves.toBe('v');
+
+			await store.destroy();
+		});
+
+		it('should delete key immediately if ttlMs is 0, even if overwriting an existing key', async () => {
+			const { clock } = createClock(1000);
+			const store = new InMemoryStateStore<string>(clock);
+
+			await store.set('k', 'old_value');
+			await store.set('k', 'new_value', 0);
+
+			await expect(store.get('k')).resolves.toBeNull();
+
+			await store.destroy();
+		});
+
+		it('should delete key immediately if ttlMs is negative', async () => {
+			const { clock } = createClock(1000);
+			const store = new InMemoryStateStore<string>(clock);
+
+			await store.set('k', 'v', -50);
+
+			await expect(store.get('k')).resolves.toBeNull();
+
+			await store.destroy();
+		});
+	});
+
+	describe('Periodic Cleanup', () => {
+		it('should physically remove expired entries on cleanup interval tick', async () => {
+			vi.useFakeTimers();
+
+			const { clock, advanceBy } = createClock(1000);
+			const store = new InMemoryStateStore<string>(clock);
+
+			await store.set('k', 'v', 10);
+
+			advanceBy(10);
+
+			await vi.advanceTimersByTimeAsync(60_000);
+
+			// @ts-ignore private field access
+			expect(store._state.has('k')).toBe(false);
+
+			await store.destroy();
+			vi.useRealTimers();
+		});
+	});
+
+	describe('Mutex (Locks)', () => {
+		it('should allow acquireLock immediately when no lock is held', async () => {
+			const { clock } = createClock(1000);
+			const store = new InMemoryStateStore<string>(clock);
+
+			await expect(store.acquireLock('k')).resolves.toBeUndefined();
+
+			await store.releaseLock('k');
+			await store.destroy();
+		});
+
+		it('should not block locks for entirely different keys', async () => {
+			const { clock } = createClock(1000);
+			const store = new InMemoryStateStore<string>(clock);
+
+			await store.acquireLock('k1');
+
+			let acquiredK2 = false;
+			await store.acquireLock('k2').then(() => (acquiredK2 = true));
+
+			expect(acquiredK2).toBe(true);
+
+			await store.releaseLock('k2');
+			await store.releaseLock('k1');
+			await store.destroy();
+		});
+
+		it('should serialize acquireLock calls and unblock them in strict FIFO order', async () => {
+			const { clock } = createClock(1000);
+			const store = new InMemoryStateStore<string>(clock);
+
+			const executionOrder: number[] = [];
+
+			await store.acquireLock('k');
+			executionOrder.push(1);
+
+			const waiter1 = store.acquireLock('k').then(() => executionOrder.push(2));
+			const waiter2 = store.acquireLock('k').then(() => executionOrder.push(3));
+
+			await Promise.resolve();
+			expect(executionOrder).toEqual([1]);
+
+			await store.releaseLock('k');
+			await Promise.resolve();
+			await Promise.resolve();
+			expect(executionOrder).toEqual([1, 2]);
+
+			await store.releaseLock('k');
+			await waiter1;
+			await waiter2;
+			expect(executionOrder).toEqual([1, 2, 3]);
+
+			await store.releaseLock('k');
+			await store.destroy();
+		});
+	});
+
+	describe('Clear and Destroy logic', () => {
+		it('should clear stored values on clear()', async () => {
+			const { clock } = createClock(1000);
+			const store = new InMemoryStateStore<string>(clock);
+
+			await store.set('a', '1');
+			await store.set('b', '2');
+
+			await store.clear();
+
+			await expect(store.get('a')).resolves.toBeNull();
+			await expect(store.get('b')).resolves.toBeNull();
+
+			await store.destroy();
+		});
+
+		it('should stop the cleanup timer on destroy()', async () => {
+			vi.useFakeTimers();
+
+			const { clock } = createClock(1000);
+			const store = new InMemoryStateStore<string>(clock);
+
+			const clearIntervalSpy = vi.spyOn(globalThis, 'clearInterval');
+
+			await store.destroy();
+
+			expect(clearIntervalSpy).toHaveBeenCalledTimes(1);
+
+			clearIntervalSpy.mockRestore();
+			vi.useRealTimers();
+		});
+
+		it('should reject all waiting locks with RateLimitError when cleared', async () => {
+			const { clock } = createClock(1000);
+			const store = new InMemoryStateStore<string>(clock);
+
+			await store.acquireLock('k');
+
+			const waiter1 = store.acquireLock('k');
+			const waiter2 = store.acquireLock('k');
+
+			await Promise.resolve();
+
+			await store.clear();
+
+			await expect(waiter1).rejects.toThrowError(RateLimitError);
+			await expect(waiter2).rejects.toThrowError(RateLimitError);
+
+			await store.destroy();
+		});
+	});
+});

package/tests/unit/runtime/rate-limiter.executor.spec.ts

@@ -0,0 +1,353 @@
+import { Priority } from '@stimulcross/ds-policy-priority-queue';
+import { createLogger } from '@stimulcross/logger';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { type Clock, RateLimitError, RateLimitErrorCode } from '../../../src/index.js';
+import { RateLimiterExecutor } from '../../../src/runtime/rate-limiter.executor.js';
+
+const defaultOpts = { id: 'task-1', key: 'key-1' };
+
+describe('RateLimiterExecutor', () => {
+	const logger = createLogger('test');
+	let clock: Clock;
+	let executor: RateLimiterExecutor;
+
+	beforeEach(() => {
+		vi.useFakeTimers();
+		vi.setSystemTime(1000);
+
+		clock = { now: () => Date.now() };
+		executor = new RateLimiterExecutor(logger, clock);
+	});
+
+	afterEach(() => {
+		executor.clear();
+		vi.useRealTimers();
+	});
+
+	describe('Properties & State', () => {
+		it('should expose correct queue state and capacity', () => {
+			executor = new RateLimiterExecutor(logger, clock, { capacity: 10 });
+
+			expect(executor.queueSize).toBe(0);
+			expect(executor.queueCapacity).toBe(10);
+			expect(executor.isQueueFull).toBe(false);
+		});
+	});
+
+	describe('Execution & Delay', () => {
+		it('should execute a task successfully', async () => {
+			const task = vi.fn().mockResolvedValue('result');
+			const promise = executor.execute(task, clock.now(), defaultOpts);
+
+			await vi.runAllTimersAsync();
+
+			await expect(promise).resolves.toBe('result');
+			expect(task).toHaveBeenCalledOnce();
+		});
+
+		it('should reject if the task throws an error', async () => {
+			const error = new Error('Task failed');
+			const task = vi.fn().mockRejectedValue(error);
+
+			const promise = executor.execute(task, clock.now(), defaultOpts);
+			promise.catch(() => {});
+
+			await vi.runAllTimersAsync();
+
+			await expect(promise).rejects.toThrow(error);
+		});
+
+		it('should delay task execution until the specified runAt timestamp', async () => {
+			const task = vi.fn().mockResolvedValue('result');
+			const runAt = clock.now() + 500;
+
+			const promise = executor.execute(task, runAt, defaultOpts);
+
+			await vi.advanceTimersByTimeAsync(499);
+			expect(task).not.toHaveBeenCalled();
+
+			await vi.advanceTimersByTimeAsync(1);
+			await expect(promise).resolves.toBe('result');
+			expect(task).toHaveBeenCalledOnce();
+		});
+
+		it('should execute tasks in order of their priority', async () => {
+			executor = new RateLimiterExecutor(logger, clock, { concurrency: 1 });
+
+			const executionOrder: number[] = [];
+			let resolveBlocker: () => void;
+			const blocker = vi.fn(
+				() =>
+					new Promise<void>(res => {
+						resolveBlocker = res;
+					}),
+			);
+
+			executor.execute(blocker, clock.now(), { id: 'blocker', key: 'blocker-key' }).catch(() => {});
+
+			executor
+				.execute(
+					async () => {
+						executionOrder.push(1);
+					},
+					clock.now(),
+					{ id: 'task-low', key: 'key-low', priority: Priority.Low },
+				)
+				.catch(() => {});
+			executor
+				.execute(
+					async () => {
+						executionOrder.push(2);
+					},
+					clock.now(),
+					{ id: 'task-high', key: 'key-high', priority: Priority.High },
+				)
+				.catch(() => {});
+			executor
+				.execute(
+					async () => {
+						executionOrder.push(3);
+					},
+					clock.now(),
+					{ id: 'task-normal', key: 'key-normal', priority: Priority.Normal },
+				)
+				.catch(() => {});
+
+			await vi.advanceTimersByTimeAsync(0);
+
+			resolveBlocker!();
+			await vi.runAllTimersAsync();
+
+			expect(executionOrder).toEqual([2, 3, 1]);
+		});
+	});
+
+	describe('Concurrency', () => {
+		it('should limit the number of concurrent executions', async () => {
+			executor = new RateLimiterExecutor(logger, clock, { concurrency: 1 });
+
+			let resolveTask1: () => void;
+			const task1 = vi.fn(
+				() =>
+					new Promise<void>(res => {
+						resolveTask1 = res;
+					}),
+			);
+			const task2 = vi.fn().mockResolvedValue('task2');
+
+			const promise1 = executor.execute(task1, clock.now(), { id: 't1', key: 'k1' });
+			const promise2 = executor.execute(task2, clock.now(), { id: 't2', key: 'k2' });
+
+			await vi.advanceTimersByTimeAsync(0);
+
+			expect(task1).toHaveBeenCalledOnce();
+			expect(task2).not.toHaveBeenCalled();
+
+			resolveTask1!();
+			await vi.advanceTimersByTimeAsync(0);
+
+			await promise1;
+			await expect(promise2).resolves.toBe('task2');
+			expect(task2).toHaveBeenCalledOnce();
+		});
+	});
+
+	describe('Cancellation', () => {
+		it('should abort a queued task and remove it from execution queue', async () => {
+			const task = vi.fn();
+			const controller = new AbortController();
+
+			const promise = executor.execute(task, clock.now() + 1000, {
+				...defaultOpts,
+				signal: controller.signal,
+			});
+
+			controller.abort();
+
+			await expect(promise).rejects.toThrow(RateLimitError);
+			await expect(promise).rejects.toMatchObject({
+				code: RateLimitErrorCode.Cancelled,
+			});
+
+			expect(task).not.toHaveBeenCalled();
+		});
+	});
+
+	describe('Expiration', () => {
+		it('should reject tasks that expire before they can be executed', async () => {
+			const task = vi.fn();
+			const runAt = clock.now() + 1000;
+			const expiresAt = clock.now() + 500;
+
+			const promise = executor.execute(task, runAt, { ...defaultOpts, expiresAt });
+			promise.catch(() => {});
+
+			await vi.advanceTimersByTimeAsync(500);
+
+			await expect(promise).rejects.toMatchObject({
+				code: RateLimitErrorCode.Expired,
+			});
+
+			expect(task).not.toHaveBeenCalled();
+		});
+
+		it('should expire tasks waiting in queue due to concurrency limits', async () => {
+			executor = new RateLimiterExecutor(logger, clock, { concurrency: 1 });
+
+			let resolveTask1: () => void;
+			const task1 = vi.fn(
+				() =>
+					new Promise<void>(res => {
+						resolveTask1 = res;
+					}),
+			);
+			const task2 = vi.fn();
+
+			const promise1 = executor.execute(task1, clock.now(), { id: 't1', key: 'k1' });
+			const promise2 = executor.execute(task2, clock.now(), {
+				id: 't2',
+				key: 'k2',
+				expiresAt: clock.now() + 500,
+			});
+			promise2.catch(() => {});
+
+			await vi.advanceTimersByTimeAsync(500);
+
+			await expect(promise2).rejects.toMatchObject({
+				code: RateLimitErrorCode.Expired,
+			});
+
+			expect(task2).not.toHaveBeenCalled();
+
+			resolveTask1!();
+			await promise1;
+		});
+
+		it('should handle multiple tasks with different expiration times', async () => {
+			const runAt = clock.now() + 5000;
+			const taskLong = vi.fn();
+			const taskShort = vi.fn();
+
+			const promiseLong = executor.execute(taskLong, runAt, {
+				id: 't-long',
+				key: 'k-long',
+				expiresAt: clock.now() + 2000,
+			});
+			promiseLong.catch(() => {});
+
+			const promiseShort = executor.execute(taskShort, runAt, {
+				id: 't-short',
+				key: 'k-short',
+				expiresAt: clock.now() + 1000,
+			});
+			promiseShort.catch(() => {});
+
+			await vi.advanceTimersByTimeAsync(1000);
+			await expect(promiseShort).rejects.toMatchObject({ code: RateLimitErrorCode.Expired });
+			expect(taskLong).not.toHaveBeenCalled();
+
+			await vi.advanceTimersByTimeAsync(1000);
+			await expect(promiseLong).rejects.toMatchObject({ code: RateLimitErrorCode.Expired });
+		});
+	});
+
+	describe('Tickets Shifting', () => {
+		it('should shift the execution ticket when a queued task is cancelled', async () => {
+			executor = new RateLimiterExecutor(logger, clock, { concurrency: 1 });
+			const executionTimes: Record<string, number> = {};
+
+			const task1 = vi.fn().mockImplementation(() => {
+				executionTimes.task1 = clock.now();
+			});
+			const task2 = vi.fn().mockImplementation(() => {
+				executionTimes.task2 = clock.now();
+			});
+			const task3 = vi.fn().mockImplementation(() => {
+				executionTimes.task3 = clock.now();
+			});
+
+			const controller2 = new AbortController();
+
+			executor.execute(task1, clock.now() + 100, { id: 't1', key: 'k1' }).catch(() => {});
+			const promise2 = executor.execute(task2, clock.now() + 200, {
+				id: 't2',
+				key: 'k2',
+				signal: controller2.signal,
+			});
+			promise2.catch(() => {});
+			executor.execute(task3, clock.now() + 300, { id: 't3', key: 'k3' }).catch(() => {});
+
+			controller2.abort();
+
+			await vi.advanceTimersByTimeAsync(100);
+			expect(task1).toHaveBeenCalledOnce();
+			expect(executionTimes.task1).toBe(1100);
+			await expect(promise2).rejects.toMatchObject({ code: RateLimitErrorCode.Cancelled });
+
+			await vi.advanceTimersByTimeAsync(100);
+
+			expect(task2).not.toHaveBeenCalled();
+			expect(task3).toHaveBeenCalledOnce();
+			// task3 took task2 200ms ticket
+			expect(executionTimes.task3).toBe(1200);
+		});
+
+		it('should shift the execution ticket when a queued task expires', async () => {
+			executor = new RateLimiterExecutor(logger, clock, { concurrency: 1 });
+			const executionTimes: Record<string, number> = {};
+
+			const task1 = vi.fn().mockImplementation(() => {
+				executionTimes.task1 = clock.now();
+			});
+			const task2 = vi.fn().mockImplementation(() => {
+				executionTimes.task2 = clock.now();
+			});
+			const task3 = vi.fn().mockImplementation(() => {
+				executionTimes.task3 = clock.now();
+			});
+
+			executor.execute(task1, clock.now() + 100, { id: 't1', key: 'k1' }).catch(() => {});
+			const promise2 = executor.execute(task2, clock.now() + 200, {
+				id: 't2',
+				key: 'k2',
+				expiresAt: clock.now() + 50,
+			});
+			promise2.catch(() => {});
+			executor.execute(task3, clock.now() + 300, { id: 't3', key: 'k3' }).catch(() => {});
+
+			await vi.advanceTimersByTimeAsync(50);
+			expect(task1).not.toHaveBeenCalled();
+			await expect(promise2).rejects.toMatchObject({ code: RateLimitErrorCode.Expired });
+
+			await vi.advanceTimersByTimeAsync(50);
+			expect(task1).toHaveBeenCalledOnce();
+			expect(executionTimes.task1).toBe(1100);
+
+			await vi.advanceTimersByTimeAsync(100);
+
+			expect(task2).not.toHaveBeenCalled();
+			expect(task3).toHaveBeenCalledOnce();
+			// task3 took task2 200ms ticket
+			expect(executionTimes.task3).toBe(1200);
+		});
+	});
+
+	describe('Clear & Teardown', () => {
+		it('should reject all pending tasks with Destroyed error when cleared', async () => {
+			const task = vi.fn();
+			const promise = executor.execute(task, clock.now() + 1000, defaultOpts);
+
+			executor.clear();
+
+			await expect(promise).rejects.toMatchObject({
+				code: RateLimitErrorCode.Destroyed,
+			});
+
+			expect(task).not.toHaveBeenCalled();
+		});
+
+		it('should handle clearing an empty queue gracefully', () => {
+			expect(() => executor.clear()).not.toThrow();
+		});
+	});
+});

package/tests/unit/runtime/semaphore.spec.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from 'vitest';
+import { Semaphore } from '../../../src/runtime/semaphore.js';
+
+describe('Semaphore', () => {
+	describe('should support unlimited mode', () => {
+		it('should always acquire successfully when maxPermits is null', () => {
+			const s = new Semaphore(null);
+
+			expect(s.acquire()).toBe(true);
+			expect(s.acquire()).toBe(true);
+			expect(s.acquire()).toBe(true);
+		});
+
+		it('should ignore release when maxPermits is null', () => {
+			const s = new Semaphore(null);
+
+			s.release();
+			s.release();
+
+			expect(s.acquire()).toBe(true);
+		});
+	});
+
+	describe('should validate constructor argument', () => {
+		it('should accept null (unlimited mode)', () => {
+			expect(() => new Semaphore(null)).not.toThrow();
+		});
+
+		it('should throw for 0', () => {
+			expect(() => new Semaphore(0)).toThrow();
+		});
+
+		it('should accept positive safe integers', () => {
+			expect(() => new Semaphore(1)).not.toThrow();
+			expect(() => new Semaphore(10)).not.toThrow();
+			expect(() => new Semaphore(Number.MAX_SAFE_INTEGER)).not.toThrow();
+		});
+
+		it('should throw for negative integers', () => {
+			expect(() => new Semaphore(-1)).toThrow(/non-negative integer or null/iu);
+			expect(() => new Semaphore(-10)).toThrow(/non-negative integer or null/iu);
+		});
+
+		it('should throw for non-integers (floats)', () => {
+			expect(() => new Semaphore(0.1)).toThrow(/non-negative integer or null/iu);
+			expect(() => new Semaphore(1.5)).toThrow(/non-negative integer or null/iu);
+		});
+
+		it('should throw for NaN', () => {
+			expect(() => new Semaphore(Number.NaN)).toThrow(/non-negative integer or null/iu);
+		});
+
+		it('should throw for Infinity and -Infinity', () => {
+			expect(() => new Semaphore(Number.POSITIVE_INFINITY)).toThrow(/non-negative integer or null/iu);
+			expect(() => new Semaphore(Number.NEGATIVE_INFINITY)).toThrow(/non-negative integer or null/iu);
+		});
+
+		it('should throw for unsafe integers', () => {
+			expect(() => new Semaphore(Number.MAX_SAFE_INTEGER + 1)).toThrow(/non-negative integer or null/iu);
+		});
+	});
+
+	describe('should enforce finite capacity', () => {
+		it('should start full when maxPermits is provided', () => {
+			const s = new Semaphore(2);
+
+			expect(s.acquire()).toBe(true);
+			expect(s.acquire()).toBe(true);
+			expect(s.acquire()).toBe(false);
+		});
+
+		it('should allow acquiring again after release, up to the maximum', () => {
+			const s = new Semaphore(1);
+
+			expect(s.acquire()).toBe(true);
+			expect(s.acquire()).toBe(false);
+
+			s.release();
+
+			expect(s.acquire()).toBe(true);
+			expect(s.acquire()).toBe(false);
+		});
+
+		it('should cap permits at maxPermits after extra releases', () => {
+			const s = new Semaphore(1);
+
+			expect(s.acquire()).toBe(true);
+			expect(s.acquire()).toBe(false);
+
+			s.release();
+			s.release();
+			s.release();
+
+			expect(s.acquire()).toBe(true);
+			expect(s.acquire()).toBe(false);
+		});
+	});
+});