@stimulcross/rate-limiter 0.0.1

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

@@ -0,0 +1,182 @@
+import { Priority } from '@stimulcross/ds-policy-priority-queue';
+import { describe, expect, it, vi } from 'vitest';
+import { RateLimitError, RateLimitErrorCode } from '../../../src/index.js';
+import { Task } from '../../../src/runtime/task.js';
+
+const defaultOpts = { id: 'task-1', key: 'key-1' };
+
+describe('Task', () => {
+	describe('Initialization', () => {
+		it('should initialize with default values', () => {
+			const task = new Task(() => 'test', defaultOpts);
+
+			expect(task.id).toBe('task-1');
+			expect(task.key).toBe('key-1');
+			expect(task.priority).toBe(Priority.Normal);
+			expect(task.expiresAt).toBeUndefined();
+			expect(task.isActive).toBe(true);
+			expect(task.isAborted).toBe(false);
+			expect(task.isCancellable).toBe(false);
+		});
+
+		it('should initialize with provided options', () => {
+			const task = new Task(() => 'test', {
+				...defaultOpts,
+				priority: Priority.High,
+				expiresAt: 1000,
+			});
+
+			expect(task.priority).toBe(Priority.High);
+			expect(task.expiresAt).toBe(1000);
+		});
+
+		it('should be cancellable when initialized with an abort signal', () => {
+			const controller = new AbortController();
+			const task = new Task(() => 'test', { ...defaultOpts, signal: controller.signal });
+
+			expect(task.isCancellable).toBe(true);
+		});
+	});
+
+	describe('Execution', () => {
+		it('should resolve the promise when the task completes successfully', async () => {
+			const taskFn = vi.fn().mockResolvedValue('success');
+			const task = new Task(taskFn, defaultOpts);
+
+			await task.run();
+
+			await expect(task).resolves.toBe('success');
+			expect(task.isActive).toBe(false);
+		});
+
+		it('should reject the promise when the task throws an error', async () => {
+			const error = new Error('Task failed');
+			const taskFn = vi.fn().mockRejectedValue(error);
+			const task = new Task(taskFn, defaultOpts);
+
+			await task.run();
+
+			await expect(task).rejects.toThrow(error);
+			expect(task.isActive).toBe(false);
+		});
+
+		it('should mark task as inactive immediately when run starts', () => {
+			const task = new Task(async () => 'test', defaultOpts);
+
+			void task.run();
+
+			expect(task.isActive).toBe(false);
+		});
+	});
+
+	describe('Promise API (PromiseLike)', () => {
+		it('should support .then() chaining', async () => {
+			const task = new Task(() => 'chaining', defaultOpts);
+
+			const promise = task.then(val => `${val}-success`);
+
+			await task.run();
+
+			await expect(promise).resolves.toBe('chaining-success');
+		});
+
+		it('should support .catch() chaining', async () => {
+			const error = new Error('Fail');
+			const task = new Task(() => Promise.reject(error), defaultOpts);
+
+			const promise = task.catch(e => e.message);
+
+			await task.run();
+
+			await expect(promise).resolves.toBe('Fail');
+		});
+
+		it('should support .finally() execution', async () => {
+			const finallyFn = vi.fn();
+			const task = new Task(() => 'test', defaultOpts);
+
+			const promise = task.finally(finallyFn);
+
+			await task.run();
+			await promise;
+
+			expect(finallyFn).toHaveBeenCalledOnce();
+		});
+	});
+
+	describe('State Management', () => {
+		it('should allow manual rejection', async () => {
+			const task = new Task(() => 'test', defaultOpts);
+			const reason = new Error('Manual rejection');
+
+			task.reject(reason);
+
+			expect(task.isActive).toBe(false);
+			await expect(task).rejects.toThrow(reason);
+		});
+
+		it('should mark task as inactive when destroyed', () => {
+			const task = new Task(() => 'test', defaultOpts);
+
+			task.destroy();
+
+			expect(task.isActive).toBe(false);
+		});
+	});
+
+	describe('Abort Signal Handling', () => {
+		it('should abort task, call handler, and reject with RateLimitError when signal triggers', async () => {
+			const controller = new AbortController();
+			const task = new Task(() => 'test', { ...defaultOpts, signal: controller.signal });
+			const abortHandler = vi.fn();
+
+			task.onAbort(abortHandler);
+			controller.abort();
+			// second call should not trigger handler
+			controller.abort();
+
+			expect(task.isAborted).toBe(true);
+			expect(task.isActive).toBe(false);
+			expect(abortHandler).toHaveBeenCalledOnce();
+
+			await expect(task).rejects.toThrow(RateLimitError);
+			await expect(task).rejects.toMatchObject({
+				code: RateLimitErrorCode.Cancelled,
+				message: 'Aborted by client',
+			});
+		});
+
+		it('should clean up signal references and event listeners when destroyed', () => {
+			const controller = new AbortController();
+			const removeEventListenerSpy = vi.spyOn(controller.signal, 'removeEventListener');
+			const task = new Task(() => 'test', { ...defaultOpts, signal: controller.signal });
+
+			task.destroy();
+
+			expect(task.isCancellable).toBe(false);
+			expect(removeEventListenerSpy).toHaveBeenCalledWith('abort', expect.any(Function));
+		});
+
+		it('should safely destroy even if no abort handler is registered', () => {
+			const controller = new AbortController();
+			const task = new Task(() => 'test', { ...defaultOpts, signal: controller.signal });
+
+			expect(() => {
+				task.destroy();
+			}).not.toThrow();
+		});
+
+		it('should not call abort handler if destroyed before signal aborts', () => {
+			const controller = new AbortController();
+			const task = new Task(() => 'test', { ...defaultOpts, signal: controller.signal });
+			const abortHandler = vi.fn();
+
+			task.onAbort(abortHandler);
+			task.destroy();
+			controller.abort();
+
+			expect(abortHandler).not.toHaveBeenCalled();
+			expect(task.isAborted).toBe(false);
+		});
+	});
+});

package/tests/unit/utils/generate-random-string.spec.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { generateRandomString } from '../../../src/utils/generate-random-string.js';
+
+describe('generateRandomString', () => {
+	const ALPHANUMERIC_REGEX = /^[A-Za-z\d]*$/u;
+
+	describe('length and boundary conditions', () => {
+		it('should return a string of length 7 by default', () => {
+			expect(generateRandomString()).toHaveLength(7);
+		});
+
+		it('should return a string of the exact specified length', () => {
+			expect(generateRandomString(5)).toHaveLength(5);
+			expect(generateRandomString(100)).toHaveLength(100);
+		});
+
+		it('should return an empty string when length is 0', () => {
+			expect(generateRandomString(0)).toBe('');
+		});
+	});
+
+	describe('validation', () => {
+		it('should throw a RangeError for negative lengths', () => {
+			expect(() => generateRandomString(-1)).toThrow(RangeError);
+			expect(() => generateRandomString(-5)).toThrow(/Invalid length/u);
+		});
+
+		it('should throw a RangeError for non-integer lengths', () => {
+			expect(() => generateRandomString(5.5)).toThrow(RangeError);
+		});
+
+		it('should throw a RangeError for unsafe integers and non-numbers', () => {
+			expect(() => generateRandomString(Number.NaN)).toThrow(RangeError);
+			expect(() => generateRandomString(Infinity)).toThrow(RangeError);
+			expect(() => generateRandomString(Number.MAX_SAFE_INTEGER + 1)).toThrow(RangeError);
+		});
+	});
+
+	describe('content and semantics', () => {
+		it('should contain only allowed alphanumeric characters', () => {
+			const result = generateRandomString(50);
+			expect(ALPHANUMERIC_REGEX.test(result)).toBe(true);
+		});
+
+		it('should generate different strings on subsequent calls', () => {
+			const string1 = generateRandomString(20);
+			const string2 = generateRandomString(20);
+			expect(string1).not.toBe(string2);
+		});
+	});
+});

package/tests/unit/utils/promise-with-resolvers.spec.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { promiseWithResolvers } from '../../../src/utils/promise-with-resolvers.js';
+
+describe('promiseWithResolvers', () => {
+	it('should return an object with promise, resolve and reject', () => {
+		const r = promiseWithResolvers<number>();
+
+		expect(r).toBeTruthy();
+		expect(r.promise).toBeInstanceOf(Promise);
+		expect(typeof r.resolve).toBe('function');
+		expect(typeof r.reject).toBe('function');
+	});
+
+	it('should resolve the promise with a value', async () => {
+		const r = promiseWithResolvers<number>();
+
+		r.resolve(42);
+
+		await expect(r.promise).resolves.toBe(42);
+	});
+
+	it('should resolve the promise with a PromiseLike value', async () => {
+		const r = promiseWithResolvers<number>();
+
+		r.resolve(Promise.resolve(7));
+
+		await expect(r.promise).resolves.toBe(7);
+	});
+
+	it('should reject the promise with a reason', async () => {
+		const r = promiseWithResolvers<number>();
+		const err = new Error('boom');
+
+		r.reject(err);
+
+		await expect(r.promise).rejects.toBe(err);
+	});
+
+	it('should settle only once (resolve then reject)', async () => {
+		const r = promiseWithResolvers<number>();
+
+		r.resolve(1);
+		r.reject(new Error('should be ignored'));
+
+		await expect(r.promise).resolves.toBe(1);
+	});
+
+	it('should settle only once (reject then resolve)', async () => {
+		const r = promiseWithResolvers<number>();
+		const err = new Error('first');
+
+		r.reject(err);
+		r.resolve(123);
+
+		await expect(r.promise).rejects.toBe(err);
+	});
+});

package/tests/unit/utils/sanitize-priority.spec.ts

@@ -0,0 +1,46 @@
+import { Priority } from '@stimulcross/ds-policy-priority-queue';
+import { describe, it, expect } from 'vitest';
+import { sanitizePriority } from '../../../src/utils/sanitize-priority.js';
+
+describe('sanitizePriority (updated)', () => {
+	it('should return Priority.Normal for non-finite numbers', () => {
+		expect(sanitizePriority(Number.NaN)).toBe(Priority.Normal);
+		expect(sanitizePriority(Number.POSITIVE_INFINITY)).toBe(Priority.Normal);
+		expect(sanitizePriority(Number.NEGATIVE_INFINITY)).toBe(Priority.Normal);
+	});
+
+	it('should clamp below Priority.Lowest to Priority.Lowest (before rounding)', () => {
+		expect(sanitizePriority(Priority.Lowest - 1)).toBe(Priority.Lowest);
+		expect(sanitizePriority(Priority.Lowest - 0.1)).toBe(Priority.Lowest);
+		expect(sanitizePriority(Priority.Lowest - 1000)).toBe(Priority.Lowest);
+	});
+
+	it('should clamp above Priority.Highest to Priority.Highest (before rounding)', () => {
+		expect(sanitizePriority(Priority.Highest + 1)).toBe(Priority.Highest);
+		expect(sanitizePriority(Priority.Highest + 0.1)).toBe(Priority.Highest);
+		expect(sanitizePriority(Priority.Highest + 1000)).toBe(Priority.Highest);
+	});
+
+	it('should round non-integer priorities that are already within range', () => {
+		expect(sanitizePriority(1.4)).toBe(1);
+		expect(sanitizePriority(1.5)).toBe(2);
+		expect(sanitizePriority(3.7)).toBe(4);
+	});
+
+	it('should return the same value for integers within range', () => {
+		expect(sanitizePriority(Priority.Lowest)).toBe(Priority.Lowest);
+		expect(sanitizePriority(Priority.Normal)).toBe(Priority.Normal);
+		expect(sanitizePriority(Priority.Highest)).toBe(Priority.Highest);
+
+		const mid = Math.trunc((Priority.Lowest + Priority.Highest) / 2);
+		expect(sanitizePriority(mid)).toBe(mid);
+	});
+
+	it('should not clamp after rounding (behavior change guard)', () => {
+		expect(sanitizePriority(Priority.Highest - 0.6)).toBe(Priority.Highest - 1);
+		expect(sanitizePriority(Priority.Highest - 0.4)).toBe(Priority.Highest);
+
+		expect(sanitizePriority(Priority.Lowest + 0.6)).toBe(Priority.Lowest + 1);
+		expect(sanitizePriority(Priority.Lowest + 0.4)).toBe(Priority.Lowest);
+	});
+});

package/tests/unit/utils/validate-cost.spec.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { InvalidCostError } from '../../../src/errors/invalid-cost.error.js';
+import { validateCost } from '../../../src/utils/validate-cost.js';
+
+describe('validateCost', () => {
+	it('should not throw for a non-negative safe integer', () => {
+		expect(() => validateCost(0)).not.toThrow();
+		expect(() => validateCost(1)).not.toThrow();
+		expect(() => validateCost(123_456)).not.toThrow();
+	});
+
+	it('should throw InvalidCostError for negative numbers', () => {
+		expect(() => validateCost(-1)).toThrow(InvalidCostError);
+	});
+
+	it('should throw InvalidCostError for non-integers', () => {
+		expect(() => validateCost(1.1)).toThrow(InvalidCostError);
+	});
+
+	it('should throw InvalidCostError for NaN', () => {
+		expect(() => validateCost(Number.NaN)).toThrow(InvalidCostError);
+	});
+
+	it('should throw InvalidCostError for Infinity', () => {
+		expect(() => validateCost(Number.POSITIVE_INFINITY)).toThrow(InvalidCostError);
+		expect(() => validateCost(Number.NEGATIVE_INFINITY)).toThrow(InvalidCostError);
+	});
+
+	it('should throw InvalidCostError for non-safe integers', () => {
+		expect(() => validateCost(Number.MAX_SAFE_INTEGER + 1)).toThrow(InvalidCostError);
+	});
+
+	it('should respect max when provided', () => {
+		expect(() => validateCost(10, 10)).not.toThrow();
+		expect(() => validateCost(11, 10)).toThrow(InvalidCostError);
+	});
+
+	it('should respect min when provided', () => {
+		expect(() => validateCost(10, undefined, 10)).not.toThrow();
+		expect(() => validateCost(9, undefined, 10)).toThrow(InvalidCostError);
+	});
+
+	it('should respect both min and max when provided', () => {
+		expect(() => validateCost(5, 10, 0)).not.toThrow();
+		expect(() => validateCost(11, 10, 0)).toThrow(InvalidCostError);
+		expect(() => validateCost(-1, 10, 0)).toThrow(InvalidCostError);
+	});
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "NodeNext",
+		"moduleResolution": "Node16",
+		"lib": ["ES2022", "ES2024.Promise"],
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"strict": true,
+		"skipLibCheck": true,
+		"outDir": "lib"
+	},
+	"include": ["src"]
+}

package/vitest.config.js

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+	test: {
+		environment: 'node',
+		include: ['tests/**/*.spec.ts'],
+		coverage: {
+			provider: 'v8',
+			reportsDirectory: './coverage',
+			include: ['src/limiters', 'src/runtime', 'src/utils'],
+			exclude: [
+				'src/**/index.ts',
+				'src/**/*.info.ts',
+				'src/**/*.state.ts',
+				'src/**/*.status.ts',
+				'src/**/*.options.ts',
+				'src/runtime/queue/queue*.ts',
+				'src/**/http-limit-info.extractor',
+			],
+		},
+	},
+});