xonecas.io
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}