70160
Ce
cel-tui / files
cel-tui / packages / components / src / ticker.ts
4.6 KB
1import { cel } from "@cel-tui/core"; 2 3/** Timing information passed to a managed animation tick. */ 4export interface TickerTick { 5 /** One-based tick number. This continues across stop/start cycles. */ 6 readonly frame: number; 7 /** Milliseconds since the previous tick (or the latest {@link Ticker.start}). */ 8 readonly deltaMs: number; 9 /** Milliseconds since the latest {@link Ticker.start}. */ 10 readonly elapsedMs: number; 11} 12 13/** Configuration for {@link createTicker}. */ 14export interface TickerOptions { 15 /** 16 * Hard upper bound on callback and render frequency. 17 * 18 * Delayed ticks are skipped instead of replayed, so a stalled event loop 19 * cannot trigger a burst of catch-up renders. 20 * 21 * @default 30 22 */ 23 maxFps?: number; 24 /** Update external animation state before the render is requested. */ 25 onTick?: (tick: TickerTick) => void; 26 /** 27 * Render request invoked once after every tick. 28 * 29 * Defaults to {@link cel.render}. Supplying this is useful when adapting the 30 * ticker to another render owner or when testing it with a deterministic 31 * clock. 32 */ 33 requestRender?: () => void; 34} 35 36/** Explicit lifecycle for an opt-in animation ticker. */ 37export interface Ticker { 38 /** Whether the ticker currently has scheduled work. */ 39 readonly running: boolean; 40 /** Whether this ticker has permanently released its callbacks. */ 41 readonly disposed: boolean; 42 /** Start ticking. Repeated calls while running are ignored. */ 43 start(): void; 44 /** Pause and cancel the pending tick. Safe to call repeatedly. */ 45 stop(): void; 46 /** Stop permanently and release captured callbacks. Safe to call repeatedly. */ 47 dispose(): void; 48} 49 50const DEFAULT_MAX_FPS = 30; 51 52/** 53 * Create an opt-in, rate-limited render ticker. 54 * 55 * cel-tui remains fully reactive by default: constructing a ticker schedules 56 * nothing. Call {@link Ticker.start} only while animation is needed, then 57 * {@link Ticker.stop} or {@link Ticker.dispose} it. The scheduler uses one 58 * drift-corrected timeout and skips missed frames rather than replaying them. 59 * 60 * @example 61 * ```ts 62 * let phase = 0; 63 * const ticker = createTicker({ 64 * maxFps: 12, 65 * onTick: () => phase++, 66 * }); 67 * 68 * ticker.start(); 69 * // ...later 70 * ticker.dispose(); 71 * ``` 72 */ 73export function createTicker(options: TickerOptions = {}): Ticker { 74 const maxFps = options.maxFps ?? DEFAULT_MAX_FPS; 75 if (!Number.isFinite(maxFps) || maxFps <= 0) { 76 throw new RangeError( 77 "Ticker maxFps must be a finite number greater than 0", 78 ); 79 } 80 81 const intervalMs = 1_000 / maxFps; 82 let onTick = options.onTick; 83 let requestRender = options.requestRender ?? cel.render; 84 let timer: ReturnType<typeof setTimeout> | null = null; 85 let running = false; 86 let disposed = false; 87 let frame = 0; 88 let startedAt = 0; 89 let previousTickAt = 0; 90 let nextTickAt = 0; 91 92 function clearTimer(): void { 93 if (timer === null) return; 94 clearTimeout(timer); 95 timer = null; 96 } 97 98 function schedule(now: number): void { 99 // Rounding upward preserves maxFps even though host timers use integer 100 // millisecond delays. 101 const delay = Math.max(0, Math.ceil(nextTickAt - now)); 102 timer = setTimeout(runTick, delay); 103 } 104 105 function runTick(): void { 106 timer = null; 107 if (!running || disposed) return; 108 109 const now = Date.now(); 110 frame++; 111 try { 112 onTick?.({ 113 frame, 114 deltaMs: now - previousTickAt, 115 elapsedMs: now - startedAt, 116 }); 117 if (!disposed) requestRender(); 118 } catch (error) { 119 // A failed callback must not leave a ticker that reports `running` while 120 // no timer is actually scheduled. Surface the original error after 121 // bringing the lifecycle to a consistent stopped state. 122 ticker.stop(); 123 throw error; 124 } 125 if (!running || disposed) return; 126 127 previousTickAt = now; 128 // Never catch up missed frames in a burst. Preserve the original cadence 129 // when possible, but move at least one full interval past a late callback. 130 nextTickAt = Math.max(nextTickAt + intervalMs, now + intervalMs); 131 schedule(now); 132 } 133 134 const ticker: Ticker = { 135 get running() { 136 return running; 137 }, 138 get disposed() { 139 return disposed; 140 }, 141 start() { 142 if (disposed) throw new Error("Cannot start a disposed ticker"); 143 if (running) return; 144 145 running = true; 146 const now = Date.now(); 147 startedAt = now; 148 previousTickAt = now; 149 nextTickAt = now + intervalMs; 150 schedule(now); 151 }, 152 stop() { 153 running = false; 154 clearTimer(); 155 }, 156 dispose() { 157 if (disposed) return; 158 ticker.stop(); 159 disposed = true; 160 onTick = undefined; 161 requestRender = () => {}; 162 }, 163 }; 164 165 return ticker; 166}