|
| 1 | +/** |
| 2 | + * @module timeout-wheel |
| 3 | + * @description |
| 4 | + * Ultra-minimal timing wheel implementation optimized for max performance & many requests. |
| 5 | + * For most of the cases it's 4-100x faster than setTimeout and setInterval alone. |
| 6 | + * Provides efficient scheduling and cancellation of timeouts using a circular array. |
| 7 | + * |
| 8 | + * Position 0 → 1 → 2 → ... → 599 → 0 → 1 → 2 ... |
| 9 | + * Time: 0s 1s 2s 599s 600s 601s 602s |
| 10 | + * |
| 11 | + * The timing wheel consists of 600 slots (one per second for 10 min). |
| 12 | + * Each slot contains a list of timeout items, each associated with a unique key and callback. |
| 13 | + * Timeouts are scheduled by placing them in the appropriate slot based on the delay in seconds. |
| 14 | + * The wheel advances every second, executing and removing callbacks as their timeouts expire. |
| 15 | + * Defaults to setTimeout if the delay exceeds 10 minutes or is not divisible by 1000. |
| 16 | + * |
| 17 | + * @remarks |
| 18 | + * - Designed for minimal footprint and simplicity. |
| 19 | + * - Only supports second-level granularity (minimum timeout: 1 second). |
| 20 | + * - Automatically stops the internal timer when no timeouts remain. |
| 21 | + */ |
| 22 | + |
| 23 | +type TimeoutCallback = () => unknown | Promise<unknown>; |
| 24 | +type TimeoutItem = [string, TimeoutCallback]; // [key, callback] |
| 25 | + |
| 26 | +const WHEEL_SIZE = 600; // 600 slots for 10 min (1 slot per second) |
| 27 | +const SECOND = 1000; // 1 second in milliseconds |
| 28 | +const MAX_WHEEL_MS = WHEEL_SIZE * SECOND; |
| 29 | +const wheel: TimeoutItem[][] = Array(WHEEL_SIZE) |
| 30 | + .fill(0) |
| 31 | + .map(() => []); |
| 32 | + |
| 33 | +const keyMap = new Map<string, number | [NodeJS.Timeout | number]>(); |
| 34 | +let position = 0; |
| 35 | +let timer: NodeJS.Timeout | null = null; |
| 36 | + |
| 37 | +const handleCallback = ([key, callback]: TimeoutItem): void => { |
| 38 | + keyMap.delete(key); |
| 39 | + |
| 40 | + try { |
| 41 | + const result = callback(); |
| 42 | + if (result && result instanceof Promise) { |
| 43 | + // Silently ignore async errors to prevent wheel from stopping |
| 44 | + result.catch(() => {}); |
| 45 | + } |
| 46 | + } catch { |
| 47 | + // Ignore callback errors to prevent wheel from stopping |
| 48 | + } |
| 49 | +}; |
| 50 | + |
| 51 | +export const addTimeout = ( |
| 52 | + key: string, |
| 53 | + cb: TimeoutCallback, |
| 54 | + ms: number, |
| 55 | +): void => { |
| 56 | + removeTimeout(key); |
| 57 | + |
| 58 | + // Fallback to setTimeout if wheel size is exceeded or ms is not divisible by SECOND |
| 59 | + if (ms > MAX_WHEEL_MS || ms % SECOND !== 0) { |
| 60 | + keyMap.set(key, [setTimeout(handleCallback.bind(null, [key, cb]), ms)]); // Store timeout ID instead of slot |
| 61 | + |
| 62 | + return; |
| 63 | + } |
| 64 | + |
| 65 | + // No need for Math.ceil here since ms is guaranteed by modulo above |
| 66 | + const seconds = ms / SECOND; |
| 67 | + const slot = (position + seconds) % WHEEL_SIZE; |
| 68 | + |
| 69 | + wheel[slot].push([key, cb]); |
| 70 | + keyMap.set(key, slot); |
| 71 | + |
| 72 | + if (!timer) { |
| 73 | + timer = setInterval(() => { |
| 74 | + position = (position + 1) % WHEEL_SIZE; |
| 75 | + wheel[position].forEach(handleCallback); |
| 76 | + wheel[position] = []; |
| 77 | + |
| 78 | + if (!keyMap.size && timer) { |
| 79 | + clearInterval(timer); |
| 80 | + timer = null; |
| 81 | + } |
| 82 | + }, SECOND); |
| 83 | + } |
| 84 | +}; |
| 85 | + |
| 86 | +export const removeTimeout = (key: string): void => { |
| 87 | + const slotOrTimeout = keyMap.get(key); |
| 88 | + |
| 89 | + if (slotOrTimeout !== undefined) { |
| 90 | + // It's a Timeout object from setTimeout |
| 91 | + if (Array.isArray(slotOrTimeout)) { |
| 92 | + clearTimeout(slotOrTimeout[0]); |
| 93 | + } else { |
| 94 | + wheel[slotOrTimeout].splice( |
| 95 | + wheel[slotOrTimeout].findIndex(([k]) => k === key), |
| 96 | + 1, |
| 97 | + ); |
| 98 | + } |
| 99 | + |
| 100 | + keyMap.delete(key); |
| 101 | + |
| 102 | + if (!keyMap.size && timer) { |
| 103 | + clearInterval(timer); |
| 104 | + timer = null; |
| 105 | + } |
| 106 | + } |
| 107 | +}; |
| 108 | + |
| 109 | +export const clearAllTimeouts = () => { |
| 110 | + // Clear native setTimeout timeouts first! |
| 111 | + keyMap.forEach((value) => { |
| 112 | + if (Array.isArray(value)) { |
| 113 | + clearTimeout(value[0]); |
| 114 | + } |
| 115 | + }); |
| 116 | + |
| 117 | + if (timer) { |
| 118 | + clearInterval(timer); |
| 119 | + timer = null; |
| 120 | + } |
| 121 | + |
| 122 | + keyMap.clear(); |
| 123 | + wheel.forEach((slot) => (slot.length = 0)); |
| 124 | + position = 0; |
| 125 | +}; |
0 commit comments