@stimulcross/rate-limiter 0.0.1

package/tests/unit/policies/fixed-window.policy.spec.ts

@@ -0,0 +1,260 @@
+import { describe, it, expect } from 'vitest';
+import { InvalidCostError } from '../../../src/index.js';
+import { FixedWindowPolicy } from '../../../src/limiters/fixed-window/fixed-window.policy.js';
+
+describe('FixedWindowPolicy', () => {
+	describe('Constructor', () => {
+		it('should initialize with valid parameters', () => {
+			const policy = new FixedWindowPolicy(10, 1000);
+			expect(policy.limit).toBe(10);
+			expect(policy.windowMs).toBe(1000);
+		});
+
+		it('should throw an error for invalid limit', () => {
+			expect(() => new FixedWindowPolicy(0, 1000)).toThrow(/Invalid limit/u);
+			expect(() => new FixedWindowPolicy(-5, 1000)).toThrow(/Invalid limit/u);
+			expect(() => new FixedWindowPolicy(1.5, 1000)).toThrow(/Invalid limit/u);
+		});
+
+		it('should throw an error for invalid windowMs', () => {
+			expect(() => new FixedWindowPolicy(10, 0)).toThrow(/Invalid windowMs/u);
+			expect(() => new FixedWindowPolicy(10, -100)).toThrow(/Invalid windowMs/u);
+			expect(() => new FixedWindowPolicy(10, 100.5)).toThrow(/Invalid windowMs/u);
+		});
+
+		it('should throw an error for invalid maxReserved', () => {
+			expect(() => new FixedWindowPolicy(10, 1000, -5)).toThrow(/Invalid maxReserved/u);
+			expect(() => new FixedWindowPolicy(10, 1000, 2.5)).toThrow(/Invalid maxReserved/u);
+		});
+
+		it('should return correct initial state', () => {
+			const policy = new FixedWindowPolicy(5, 1000);
+			expect(policy.getInitialState()).toEqual({ windowStart: 0, used: 0, reserved: 0 });
+		});
+	});
+
+	describe('Get Status', () => {
+		const policy = new FixedWindowPolicy(10, 1000);
+
+		it('should return correct info for empty state', () => {
+			const state = policy.getInitialState();
+			const status = policy.getStatus(state, 500);
+
+			expect(status.windowStart).toBe(0);
+			expect(status.windowEnd).toBe(1000);
+			expect(status.used).toBe(0);
+			expect(status.reserved).toBe(0);
+			expect(status.remaining).toBe(10);
+			expect(status.nextAvailableAt).toBe(0);
+			expect(status.resetAt).toBe(1000);
+		});
+
+		it('should return correct timing when queue is partially filled', () => {
+			const state = { windowStart: 0, used: 10, reserved: 5 };
+			const info = policy.getStatus(state, 500);
+
+			expect(info.nextAvailableAt).toBe(1000);
+			expect(info.resetAt).toBe(2000);
+		});
+
+		it('should return correct timing when multiple windows are blocked', () => {
+			const state = { windowStart: 0, used: 10, reserved: 25 };
+			const info = policy.getStatus(state, 500);
+
+			expect(info.nextAvailableAt).toBe(3000);
+			expect(info.resetAt).toBe(4000);
+		});
+	});
+
+	describe('Evaluate', () => {
+		describe('Validation and Edge Cases', () => {
+			const policy = new FixedWindowPolicy(10, 1000);
+
+			it('should throw if cost exceeds the policy limit', () => {
+				const state = policy.getInitialState();
+				expect(() => policy.evaluate(state, 500, 15)).toThrow(InvalidCostError);
+			});
+
+			it('should allow zero cost without consuming tokens (status check)', () => {
+				const state = { windowStart: 0, used: 5, reserved: 0 };
+				const result = policy.evaluate(state, 500, 0);
+
+				expect(result.decision.kind).toBe('allow');
+				expect(result.nextState.used).toBe(5);
+			});
+
+			it('should handle time jumping backwards gracefully', () => {
+				const state = { windowStart: 5000, used: 5, reserved: 0 };
+				const result = policy.evaluate(state, 4000, 1);
+
+				expect(result.decision.kind).toBe('allow');
+				expect(result.nextState.windowStart).toBe(5000);
+				expect(result.nextState.used).toBe(6);
+			});
+		});
+
+		describe('Immediate execution', () => {
+			const policy = new FixedWindowPolicy(2, 1000);
+
+			it('should allow request when within limit', () => {
+				const state = policy.getInitialState();
+				const result = policy.evaluate(state, 500, 1);
+
+				expect(result.decision).toEqual({ kind: 'allow' });
+				expect(result.nextState).toEqual({ windowStart: 0, used: 1, reserved: 0 });
+			});
+
+			it('should allow request with multi-token cost if within limit', () => {
+				const state = policy.getInitialState();
+				const result = policy.evaluate(state, 500, 2);
+
+				expect(result.decision).toEqual({ kind: 'allow' });
+				expect(result.nextState).toEqual({ windowStart: 0, used: 2, reserved: 0 });
+			});
+
+			it('should deny request and return correct retryAt when limit is exceeded', () => {
+				const state = { windowStart: 0, used: 2, reserved: 0 };
+				const result = policy.evaluate(state, 500, 1);
+
+				expect(result.decision).toEqual({ kind: 'deny', retryAt: 1000 });
+				expect(result.nextState).toEqual(state);
+			});
+		});
+
+		describe('Reservation and Delay', () => {
+			const policy = new FixedWindowPolicy(2, 1000, 5);
+
+			it('should delay request when limit is exceeded and reservation is requested', () => {
+				const state = { windowStart: 0, used: 2, reserved: 0 };
+				const result = policy.evaluate(state, 500, 1, true);
+
+				expect(result.decision).toEqual({ kind: 'delay', runAt: 1000 });
+				expect(result.nextState).toEqual({ windowStart: 0, used: 2, reserved: 1 });
+			});
+
+			it('should calculate correct runAt for delayed requests across multiple future windows', () => {
+				const state = { windowStart: 0, used: 2, reserved: 1 };
+				const result1 = policy.evaluate(state, 500, 1, true);
+				const result2 = policy.evaluate(result1.nextState, 500, 1, true);
+
+				expect(result1.decision).toEqual({ kind: 'delay', runAt: 1000 });
+				expect(result2.decision).toEqual({ kind: 'delay', runAt: 2000 });
+				expect(result2.nextState.reserved).toBe(3);
+			});
+
+			it('should deny reservation if maxReserved is exceeded', () => {
+				const state = { windowStart: 0, used: 2, reserved: 4 };
+				const result = policy.evaluate(state, 500, 2, true);
+
+				expect(result.decision.kind).toBe('deny');
+				expect(result.nextState).toEqual(state);
+			});
+
+			it('should exactly calculate retryAt when maxReserved is exceeded (deficit logic)', () => {
+				const fixedWindowPolicy = new FixedWindowPolicy(10, 1000, 20);
+				const state = { windowStart: 0, used: 10, reserved: 20 };
+				const result = fixedWindowPolicy.evaluate(state, 500, 5, true);
+
+				expect(result.decision).toEqual({ kind: 'deny', retryAt: 1000 });
+			});
+		});
+
+		describe('Window Transitions and State Sync', () => {
+			const policy = new FixedWindowPolicy(10, 1000);
+
+			it('should completely reset used count when moving to a new window without debt', () => {
+				const state = { windowStart: 0, used: 10, reserved: 0 };
+				const result = policy.evaluate(state, 1500, 1);
+
+				expect(result.decision.kind).toBe('allow');
+				expect(result.nextState).toEqual({ windowStart: 1000, used: 1, reserved: 0 });
+			});
+
+			it('should carry over reserved requests into used count of the next window', () => {
+				const state = { windowStart: 0, used: 10, reserved: 5 };
+				const result = policy.evaluate(state, 1500, 1, true);
+
+				expect(result.decision.kind).toBe('allow');
+				expect(result.nextState).toEqual({ windowStart: 1000, used: 6, reserved: 0 });
+			});
+
+			it('should burn passed windows and correctly allocate remaining debt into current window', () => {
+				const state = { windowStart: 0, used: 10, reserved: 25 };
+				const result = policy.evaluate(state, 2500, 1, true);
+
+				expect(result.nextState).toEqual({ windowStart: 2000, used: 10, reserved: 6 });
+			});
+		});
+	});
+
+	describe('Revert', () => {
+		const policy = new FixedWindowPolicy(10, 1000);
+
+		describe('Within the same window', () => {
+			it('should revert only used when reserved is empty', () => {
+				const state = { windowStart: 1000, used: 5, reserved: 0 };
+				const nextState = policy.revert(state, 2, 1500);
+
+				expect(nextState).toEqual({ windowStart: 1000, used: 3, reserved: 0 });
+			});
+
+			it('should revert from reserved first', () => {
+				const state = { windowStart: 1000, used: 10, reserved: 5 };
+				const nextState = policy.revert(state, 3, 1500);
+
+				expect(nextState).toEqual({ windowStart: 1000, used: 10, reserved: 2 });
+			});
+
+			it('should revert from both reserved and used if cost spans across both', () => {
+				const state = { windowStart: 1000, used: 10, reserved: 2 };
+				const nextState = policy.revert(state, 5, 1500);
+
+				expect(nextState).toEqual({ windowStart: 1000, used: 7, reserved: 0 });
+			});
+
+			it('should not drop used or reserved below zero', () => {
+				const state = { windowStart: 1000, used: 2, reserved: 0 };
+				const nextState = policy.revert(state, 10, 1500);
+
+				expect(nextState).toEqual({ windowStart: 1000, used: 0, reserved: 0 });
+			});
+		});
+
+		describe('With time sync (window transitions)', () => {
+			it('should sync state and clear used capacity when moving to an empty new window before reverting', () => {
+				const state = { windowStart: 0, used: 10, reserved: 0 };
+				const nextState = policy.revert(state, 2, 1500);
+
+				expect(nextState).toEqual({ windowStart: 1000, used: 0, reserved: 0 });
+			});
+
+			it('should sync state, carry over reserved to used, and then apply revert', () => {
+				const state = { windowStart: 0, used: 10, reserved: 5 };
+				const nextState = policy.revert(state, 2, 1500);
+
+				expect(nextState).toEqual({ windowStart: 1000, used: 3, reserved: 0 });
+			});
+
+			it('should burn passed windows, correctly allocate remaining debt, and then apply revert', () => {
+				const state = { windowStart: 0, used: 10, reserved: 25 };
+				const nextState = policy.revert(state, 7, 2500);
+
+				expect(nextState).toEqual({ windowStart: 2000, used: 8, reserved: 0 });
+			});
+
+			it('should handle exact window boundary sync before reverting', () => {
+				const state = { windowStart: 0, used: 10, reserved: 15 };
+				const nextState = policy.revert(state, 5, 1000);
+
+				expect(nextState).toEqual({ windowStart: 1000, used: 10, reserved: 0 });
+			});
+
+			it('should gracefully handle time jumping backwards during revert', () => {
+				const state = { windowStart: 5000, used: 5, reserved: 0 };
+				const nextState = policy.revert(state, 2, 4000);
+
+				expect(nextState).toEqual({ windowStart: 5000, used: 3, reserved: 0 });
+			});
+		});
+	});
+});

package/tests/unit/policies/generic-cell.policy.spec.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from 'vitest';
+import { InvalidCostError } from '../../../src/index.js';
+import { GenericCellPolicy } from '../../../src/limiters/generic-cell/generic-cell.policy.js';
+
+describe('GenericCellPolicy', () => {
+	describe('Constructor', () => {
+		it('should initialize with valid parameters', () => {
+			const policy = new GenericCellPolicy(100, 5, 200);
+			expect(policy.intervalMs).toBe(100);
+			expect(policy.burst).toBe(5);
+		});
+
+		it('should throw an error for invalid intervalMs', () => {
+			expect(() => new GenericCellPolicy(0, 5)).toThrow(/Invalid intervalMs/u);
+			expect(() => new GenericCellPolicy(-10, 5)).toThrow(/Invalid intervalMs/u);
+			expect(() => new GenericCellPolicy(10.5, 5)).toThrow(/Invalid intervalMs/u);
+		});
+
+		it('should throw an error for invalid burst', () => {
+			expect(() => new GenericCellPolicy(100, 0)).toThrow(/Invalid burst/u);
+			expect(() => new GenericCellPolicy(100, -2)).toThrow(/Invalid burst/u);
+			expect(() => new GenericCellPolicy(100, 1.5)).toThrow(/Invalid burst/u);
+		});
+
+		it('should throw an error for invalid maxDelayMs', () => {
+			expect(() => new GenericCellPolicy(100, 5, -50)).toThrow(/Invalid maxDelayMs/u);
+			expect(() => new GenericCellPolicy(100, 5, 5.5)).toThrow(/Invalid maxDelayMs/u);
+		});
+
+		it('should return correct initial state', () => {
+			const policy = new GenericCellPolicy(100, 5);
+			expect(policy.getInitialState()).toEqual({ tat: 0 });
+		});
+	});
+
+	describe('Get Status', () => {
+		const policy = new GenericCellPolicy(100, 5);
+
+		it('should return correct info for completely idle system', () => {
+			const state = policy.getInitialState();
+			const status = policy.getStatus(state, 1000);
+
+			expect(status.intervalMs).toBe(100);
+			expect(status.burst).toBe(5);
+			expect(status.tat).toBe(1000);
+			expect(status.remaining).toBe(5);
+			expect(status.nextAvailableAt).toBe(1000);
+			expect(status.resetAt).toBe(1000);
+		});
+
+		it('should return correct info for partially utilized burst', () => {
+			const state = { tat: 1200 };
+			const status = policy.getStatus(state, 1000);
+
+			expect(status.tat).toBe(1200);
+			expect(status.remaining).toBe(3);
+			expect(status.nextAvailableAt).toBe(1000);
+			expect(status.resetAt).toBe(1200);
+		});
+
+		it('should return correct info for fully utilized and delayed system (queueing)', () => {
+			const state = { tat: 1700 };
+			const status = policy.getStatus(state, 1000);
+
+			expect(status.tat).toBe(1700);
+			expect(status.remaining).toBe(0);
+
+			expect(status.nextAvailableAt).toBe(1300);
+			expect(status.resetAt).toBe(1700);
+		});
+	});
+
+	describe('Evaluate', () => {
+		describe('Validation and Edge Cases', () => {
+			const policy = new GenericCellPolicy(100, 5, 300);
+
+			it('should throw if cost exceeds burst without reservation', () => {
+				const state = policy.getInitialState();
+				expect(() => policy.evaluate(state, 1000, 6, false)).toThrow(InvalidCostError);
+			});
+
+			it('should throw if cost exceeds total capacity (burst + max queue) with reservation', () => {
+				const state = policy.getInitialState();
+				expect(() => policy.evaluate(state, 1000, 9, true)).toThrow(InvalidCostError);
+			});
+
+			it('should allow zero cost without increasing TAT (status check)', () => {
+				const state = { tat: 1200 };
+				const result = policy.evaluate(state, 1000, 0);
+
+				expect(result.decision.kind).toBe('allow');
+				expect(result.nextState.tat).toBe(1200);
+			});
+		});
+
+		describe('Immediate execution (Burst allowance)', () => {
+			const policy = new GenericCellPolicy(100, 5);
+
+			it('should allow request when TAT is in the past (idle system)', () => {
+				const state = { tat: 500 };
+				const result = policy.evaluate(state, 1000, 1);
+
+				expect(result.decision).toEqual({ kind: 'allow' });
+				expect(result.nextState).toEqual({ tat: 1100 });
+			});
+
+			it('should allow request when TAT is in the future but within burst offset', () => {
+				const state = { tat: 1400 };
+				const result = policy.evaluate(state, 1000, 1);
+
+				expect(result.decision).toEqual({ kind: 'allow' });
+				expect(result.nextState).toEqual({ tat: 1500 });
+			});
+
+			it('should deny request without reservation when TAT exceeds burst offset', () => {
+				const state = { tat: 1600 };
+				const result = policy.evaluate(state, 1000, 1);
+
+				expect(result.decision).toEqual({ kind: 'deny', retryAt: 1200 });
+				expect(result.nextState).toEqual({ tat: 1600 });
+			});
+
+			it('should correctly consume time proportional to the request cost', () => {
+				const state = { tat: 1000 };
+				const result = policy.evaluate(state, 1000, 3);
+
+				expect(result.decision.kind).toBe('allow');
+				expect(result.nextState).toEqual({ tat: 1300 });
+			});
+		});
+
+		describe('Reservation and Delay (Queueing)', () => {
+			const policy = new GenericCellPolicy(100, 5, 300);
+
+			it('should delay request when limit exceeded but within max delay', () => {
+				const state = { tat: 1600 };
+				const result = policy.evaluate(state, 1000, 1, true);
+
+				expect(result.decision).toEqual({ kind: 'delay', runAt: 1200 });
+				expect(result.nextState).toEqual({ tat: 1700 });
+			});
+
+			it('should stack multiple delayed requests sequentially', () => {
+				const state = { tat: 1700 };
+				const result = policy.evaluate(state, 1000, 1, true);
+
+				expect(result.decision).toEqual({ kind: 'delay', runAt: 1300 });
+				expect(result.nextState).toEqual({ tat: 1800 });
+			});
+
+			it('should accurately calculate retryAt when reservation exceeds max delay', () => {
+				const state = { tat: 1900 };
+				const result = policy.evaluate(state, 1000, 1, true);
+
+				expect(result.decision).toEqual({ kind: 'deny', retryAt: 1200 });
+				expect(result.nextState).toEqual({ tat: 1900 });
+			});
+		});
+	});
+
+	describe('Revert', () => {
+		const policy = new GenericCellPolicy(100, 5);
+
+		it('should decrease TAT by the cost interval', () => {
+			const state = { tat: 1500 };
+			const nextState = policy.revert(state, 2);
+
+			expect(nextState).toEqual({ tat: 1300 });
+		});
+
+		it('should not drop TAT below zero', () => {
+			const state = { tat: 150 };
+			const nextState = policy.revert(state, 2);
+
+			expect(nextState).toEqual({ tat: 0 });
+		});
+	});
+});

package/tests/unit/policies/leaky-bucket.policy.spec.ts

@@ -0,0 +1,215 @@
+import { describe, it, expect } from 'vitest';
+import { InvalidCostError } from '../../../src/index.js';
+import { LeakyBucketPolicy } from '../../../src/limiters/leaky-bucket/leaky-bucket.policy.js';
+
+describe('LeakyBucketPolicy', () => {
+	describe('Constructor', () => {
+		it('should initialize with valid parameters', () => {
+			const policy = new LeakyBucketPolicy(100, 10, 50);
+			expect(policy.capacity).toBe(100);
+			expect(policy.leakRate).toBe(10);
+		});
+
+		it('should throw an error for invalid capacity', () => {
+			expect(() => new LeakyBucketPolicy(0, 10)).toThrow(/Invalid capacity/u);
+			expect(() => new LeakyBucketPolicy(-50, 10)).toThrow(/Invalid capacity/u);
+			expect(() => new LeakyBucketPolicy(10.5, 10)).toThrow(/Invalid capacity/u);
+		});
+
+		it('should throw an error for invalid leakRate', () => {
+			expect(() => new LeakyBucketPolicy(100, 0)).toThrow(/Invalid leakRate/u);
+			expect(() => new LeakyBucketPolicy(100, -5)).toThrow(/Invalid leakRate/u);
+			expect(() => new LeakyBucketPolicy(100, Number.NaN)).toThrow(/Invalid leakRate/u);
+		});
+
+		it('should throw an error for invalid maxOverflow', () => {
+			expect(() => new LeakyBucketPolicy(100, 10, -5)).toThrow(/Invalid maxOverflow/u);
+			expect(() => new LeakyBucketPolicy(100, 10, 5.5)).toThrow(/Invalid maxOverflow/u);
+		});
+
+		it('should return correct initial state', () => {
+			const policy = new LeakyBucketPolicy(100, 10);
+			expect(policy.getInitialState()).toEqual({ level: 0, lastUpdate: 0 });
+		});
+	});
+
+	describe('Get Status', () => {
+		const policy = new LeakyBucketPolicy(100, 10);
+
+		it('should return correct status for empty bucket', () => {
+			const state = policy.getInitialState();
+			const status = policy.getStatus(state, 1000);
+
+			expect(status.capacity).toBe(100);
+			expect(status.leakRate).toBe(10);
+			expect(status.level).toBe(0);
+			expect(status.remaining).toBe(100);
+			expect(status.nextAvailableAt).toBe(1000);
+			expect(status.resetAt).toBe(1000);
+		});
+
+		it('should return correct status for partially filled bucket', () => {
+			const state = { level: 50, lastUpdate: 1000 };
+			const status = policy.getStatus(state, 1000);
+
+			expect(status.level).toBe(50);
+			expect(status.remaining).toBe(50);
+			expect(status.nextAvailableAt).toBe(1000);
+			expect(status.resetAt).toBe(6000);
+		});
+
+		it('should return correct status for overflowed bucket', () => {
+			const state = { level: 150, lastUpdate: 1000 };
+			const status = policy.getStatus(state, 1000);
+
+			expect(status.level).toBe(150);
+			expect(status.remaining).toBe(0);
+
+			expect(status.nextAvailableAt).toBe(6100);
+			expect(status.resetAt).toBe(16_000);
+		});
+	});
+
+	describe('Evaluate', () => {
+		describe('Validation and Edge Cases', () => {
+			const policy = new LeakyBucketPolicy(10, 5);
+
+			it('should throw if cost exceeds the bucket capacity', () => {
+				const state = policy.getInitialState();
+				expect(() => policy.evaluate(state, 1000, 15)).toThrow(InvalidCostError);
+			});
+
+			it('should allow zero cost without increasing level', () => {
+				const state = { level: 5, lastUpdate: 1000 };
+				const result = policy.evaluate(state, 1000, 0);
+
+				expect(result.decision.kind).toBe('allow');
+				expect(result.nextState.level).toBe(5);
+			});
+
+			it('should handle time jumping backwards gracefully', () => {
+				const state = { level: 5, lastUpdate: 2000 };
+				const result = policy.evaluate(state, 1000, 2);
+
+				expect(result.decision.kind).toBe('allow');
+				expect(result.nextState.level).toBe(7);
+				expect(result.nextState.lastUpdate).toBe(2000);
+			});
+		});
+
+		describe('Immediate execution (Burst allowance)', () => {
+			const policy = new LeakyBucketPolicy(10, 5);
+
+			it('should deny request without reservation if capacity is exceeded', () => {
+				const state = { level: 8, lastUpdate: 1000 };
+				const result = policy.evaluate(state, 1000, 4);
+
+				expect(result.decision).toEqual({ kind: 'deny', retryAt: 1400 });
+				expect(result.nextState).toEqual(state);
+			});
+
+			it('should allow request when level exactly reaches capacity', () => {
+				const state = { level: 8, lastUpdate: 1000 };
+				const result = policy.evaluate(state, 1000, 2);
+
+				expect(result.decision).toEqual({ kind: 'allow' });
+				expect(result.nextState.level).toBe(10);
+			});
+
+			it('should deny request without reservation if capacity is exceeded', () => {
+				const state = { level: 8, lastUpdate: 1000 };
+				const result = policy.evaluate(state, 1000, 4);
+
+				expect(result.decision).toEqual({ kind: 'deny', retryAt: 1400 });
+				expect(result.nextState).toEqual(state);
+			});
+		});
+
+		describe('Leak and State Sync', () => {
+			const policy = new LeakyBucketPolicy(20, 10);
+
+			it('should reduce level based on elapsed time before applying cost', () => {
+				const state = { level: 15, lastUpdate: 1000 };
+				const result = policy.evaluate(state, 1500, 5);
+
+				expect(result.decision.kind).toBe('allow');
+				expect(result.nextState).toEqual({ level: 15, lastUpdate: 1500 });
+			});
+
+			it('should not leak below zero', () => {
+				const state = { level: 5, lastUpdate: 1000 };
+				const result = policy.evaluate(state, 3000, 2);
+
+				expect(result.decision.kind).toBe('allow');
+				expect(result.nextState).toEqual({ level: 2, lastUpdate: 3000 });
+			});
+		});
+
+		describe('Reservation and Delay', () => {
+			const policy = new LeakyBucketPolicy(10, 5, 15);
+
+			it('should delay request when capacity exceeded and reservation is enabled', () => {
+				const state = { level: 10, lastUpdate: 1000 };
+				const result = policy.evaluate(state, 1000, 4, true);
+
+				expect(result.decision).toEqual({ kind: 'delay', runAt: 1800 });
+				expect(result.nextState).toEqual({ level: 14, lastUpdate: 1000 });
+			});
+
+			it('should stack multiple reservations sequentially', () => {
+				const state = { level: 14, lastUpdate: 1000 };
+				const result = policy.evaluate(state, 1000, 6, true);
+
+				expect(result.decision).toEqual({ kind: 'delay', runAt: 3000 });
+				expect(result.nextState.level).toBe(20);
+			});
+
+			it('should deny reservation if overflow exceeds maxOverflow', () => {
+				const state = { level: 16, lastUpdate: 1000 };
+				const result = policy.evaluate(state, 1000, 10, true);
+
+				expect(result.decision.kind).toBe('deny');
+				expect(result.nextState).toEqual(state);
+			});
+
+			it('should accurately calculate retryAt when maxOverflow is exceeded', () => {
+				const state = { level: 20, lastUpdate: 1000 };
+				const result = policy.evaluate(state, 1000, 10, true);
+
+				expect(result.decision).toEqual({ kind: 'deny', retryAt: 2000 });
+			});
+		});
+	});
+
+	describe('Revert', () => {
+		const policy = new LeakyBucketPolicy(10, 5);
+
+		it('should reduce the level by the requested cost', () => {
+			const state = { level: 8, lastUpdate: 1000 };
+			const nextState = policy.revert(state, 3, 1000);
+
+			expect(nextState).toEqual({ level: 5, lastUpdate: 1000 });
+		});
+
+		it('should not reduce the level below zero', () => {
+			const state = { level: 2, lastUpdate: 1000 };
+			const nextState = policy.revert(state, 5, 1000);
+
+			expect(nextState).toEqual({ level: 0, lastUpdate: 1000 });
+		});
+
+		it('should correctly reduce the level from an overflowed state', () => {
+			const state = { level: 15, lastUpdate: 1000 };
+			const nextState = policy.revert(state, 10, 1000);
+
+			expect(nextState).toEqual({ level: 5, lastUpdate: 1000 });
+		});
+
+		it('should sync time, leak correctly, and then revert', () => {
+			const state = { level: 10, lastUpdate: 1000 };
+			const nextState = policy.revert(state, 2, 2000);
+
+			expect(nextState).toEqual({ level: 3, lastUpdate: 2000 });
+		});
+	});
+});