@tldraw/utils 4.3.0 → 4.4.0-canary.15cff7ea86f8

package/src/lib/throttle.ts

@@ -4,69 +4,179 @@ const isTest = () =>
 	// @ts-expect-error
 	!globalThis.__FORCE_RAF_IN_TESTS__
 
-const fpsQueue: Array<() => void> = []
-const targetFps = 60
-const targetTimePerFrame = Math.floor(1000 / targetFps) * 0.9 // ~15ms - we allow for some variance as browsers aren't that precise.
-let frameRaf: undefined | number
-let flushRaf: undefined | number
-let lastFlushTime = -targetTimePerFrame
-
-const flush = () => {
-	const queue = fpsQueue.splice(0, fpsQueue.length)
-	for (const fn of queue) {
-		fn()
+// Browsers aren't precise with frame timing - this factor prevents skipping frames unnecessarily
+// by aiming slightly below the theoretical frame duration (e.g., ~7.5ms instead of 8.33ms for 120fps)
+const timingVarianceFactor = 0.9
+const getTargetTimePerFrame = (targetFps: number) =>
+	Math.floor(1000 / targetFps) * timingVarianceFactor
+
+/**
+ * A scheduler class that manages a queue of functions to be executed at a target frame rate.
+ * Each instance maintains its own queue and state, allowing for separate throttling contexts
+ * (e.g., UI operations vs network sync operations).
+ *
+ * @public
+ */
+export class FpsScheduler {
+	private targetFps: number
+	private targetTimePerFrame: number
+	private fpsQueue: Array<() => void> = []
+	private frameRaf: undefined | number
+	private flushRaf: undefined | number
+	private lastFlushTime: number
+
+	constructor(targetFps: number = 120) {
+		this.targetFps = targetFps
+		this.targetTimePerFrame = getTargetTimePerFrame(targetFps)
+		this.lastFlushTime = -this.targetTimePerFrame
 	}
-}
 
-function tick(isOnNextFrame = false) {
-	if (frameRaf) return
+	updateTargetFps(targetFps: number) {
+		if (targetFps === this.targetFps) return
+		this.targetFps = targetFps
+		this.targetTimePerFrame = getTargetTimePerFrame(targetFps)
+		this.lastFlushTime = -this.targetTimePerFrame
+	}
 
-	const now = Date.now()
-	const elapsed = now - lastFlushTime
+	private flush() {
+		const queue = this.fpsQueue.splice(0, this.fpsQueue.length)
+		for (const fn of queue) {
+			fn()
+		}
+	}
+
+	private tick(isOnNextFrame = false) {
+		if (this.frameRaf) return
 
-	if (elapsed < targetTimePerFrame) {
-		// If we're too early to flush, we need to wait until the next frame to try and flush again.
-		// eslint-disable-next-line no-restricted-globals
-		frameRaf = requestAnimationFrame(() => {
-			frameRaf = undefined
-			tick(true)
-		})
-		return
+		const now = Date.now()
+		const elapsed = now - this.lastFlushTime
+
+		if (elapsed < this.targetTimePerFrame) {
+			// If we're too early to flush, we need to wait until the next frame to try and flush again.
+			// eslint-disable-next-line no-restricted-globals
+			this.frameRaf = requestAnimationFrame(() => {
+				this.frameRaf = undefined
+				this.tick(true)
+			})
+			return
+		}
+
+		if (isOnNextFrame) {
+			// If we've already waited for the next frame to run the tick, then we can flush immediately
+			if (this.flushRaf) return // ...though if there's a flush raf, that means we'll be flushing on this frame already, so we can do nothing here.
+			this.lastFlushTime = now
+			this.flush()
+		} else {
+			// If we haven't already waited for the next frame to run the tick, we need to wait until the next frame to flush.
+			if (this.flushRaf) return // ...though if there's a flush raf, that means we'll be flushing on the next frame already, so we can do nothing here.
+			// eslint-disable-next-line no-restricted-globals
+			this.flushRaf = requestAnimationFrame(() => {
+				this.flushRaf = undefined
+				this.lastFlushTime = Date.now()
+				this.flush()
+			})
+		}
 	}
 
-	if (isOnNextFrame) {
-		// If we've already waited for the next frame to run the tick, then we can flush immediately
-		if (flushRaf) return // ...though if there's a flush raf, that means we'll be flushing on this frame already, so we can do nothing here.
-		lastFlushTime = now
-		flush()
-	} else {
-		// If we haven't already waited for the next frame to run the tick, we need to wait until the next frame to flush.
-		if (flushRaf) return // ...though if there's a flush raf, that means we'll be flushing on the next frame already, so we can do nothing here.
-		// eslint-disable-next-line no-restricted-globals
-		flushRaf = requestAnimationFrame(() => {
-			flushRaf = undefined
-			lastFlushTime = now
-			flush()
-		})
+	/**
+	 * Creates a throttled version of a function that executes at most once per frame.
+	 * The default target frame rate is set by the FpsScheduler instance.
+	 * Subsequent calls within the same frame are ignored, ensuring smooth performance
+	 * for high-frequency events like mouse movements or scroll events.
+	 *
+	 * @param fn - The function to throttle, optionally with a cancel method
+	 * @returns A throttled function with an optional cancel method to remove pending calls
+	 *
+	 * @public
+	 */
+	fpsThrottle(fn: { (): void; cancel?(): void }): {
+		(): void
+		cancel?(): void
+	} {
+		if (isTest()) {
+			fn.cancel = () => {
+				if (this.frameRaf) {
+					cancelAnimationFrame(this.frameRaf)
+					this.frameRaf = undefined
+				}
+				if (this.flushRaf) {
+					cancelAnimationFrame(this.flushRaf)
+					this.flushRaf = undefined
+				}
+			}
+			return fn
+		}
+
+		const throttledFn = () => {
+			if (this.fpsQueue.includes(fn)) {
+				return
+			}
+			this.fpsQueue.push(fn)
+			this.tick()
+		}
+		throttledFn.cancel = () => {
+			const index = this.fpsQueue.indexOf(fn)
+			if (index > -1) {
+				this.fpsQueue.splice(index, 1)
+			}
+		}
+		return throttledFn
+	}
+
+	/**
+	 * Schedules a function to execute on the next animation frame.
+	 * If the same function is passed multiple times before the frame executes,
+	 * it will only be called once, effectively batching multiple calls.
+	 *
+	 * @param fn - The function to execute on the next frame
+	 * @returns A cancel function that can prevent execution if called before the next frame
+	 *
+	 * @public
+	 */
+	throttleToNextFrame(fn: () => void): () => void {
+		if (isTest()) {
+			fn()
+			return () => void null // noop
+		}
+
+		if (!this.fpsQueue.includes(fn)) {
+			this.fpsQueue.push(fn)
+			this.tick()
+		}
+
+		return () => {
+			const index = this.fpsQueue.indexOf(fn)
+			if (index > -1) {
+				this.fpsQueue.splice(index, 1)
+			}
+		}
 	}
 }
 
+// Default instance for UI operations
+const defaultScheduler = new FpsScheduler(120)
+
 /**
- * Creates a throttled version of a function that executes at most once per frame (60fps).
+ * Creates a throttled version of a function that executes at most once per frame.
+ * The default target frame rate is 120fps, but can be customized per function.
  * Subsequent calls within the same frame are ignored, ensuring smooth performance
  * for high-frequency events like mouse movements or scroll events.
  *
+ * Uses the default throttle instance for UI operations. If you need a separate
+ * throttling queue (e.g., for network operations), create your own Throttle instance.
+ *
  * @param fn - The function to throttle, optionally with a cancel method
  * @returns A throttled function with an optional cancel method to remove pending calls
  *
  * @example
  * ```ts
+ * // Default 120fps throttling
  * const updateCanvas = fpsThrottle(() => {
- *   // This will run at most once per frame (~16.67ms)
+ *   // This will run at most once per frame (~8.33ms)
  *   redrawCanvas()
  * })
  *
- * // Call as often as you want - automatically throttled to 60fps
+ * // Call as often as you want - automatically throttled to 120fps
  * document.addEventListener('mousemove', updateCanvas)
  *
  * // Cancel pending calls if needed
@@ -79,41 +189,16 @@ export function fpsThrottle(fn: { (): void; cancel?(): void }): {
 	(): void
 	cancel?(): void
 } {
-	if (isTest()) {
-		fn.cancel = () => {
-			if (frameRaf) {
-				cancelAnimationFrame(frameRaf)
-				frameRaf = undefined
-			}
-			if (flushRaf) {
-				cancelAnimationFrame(flushRaf)
-				flushRaf = undefined
-			}
-		}
-		return fn
-	}
-
-	const throttledFn = () => {
-		if (fpsQueue.includes(fn)) {
-			return
-		}
-		fpsQueue.push(fn)
-		tick()
-	}
-	throttledFn.cancel = () => {
-		const index = fpsQueue.indexOf(fn)
-		if (index > -1) {
-			fpsQueue.splice(index, 1)
-		}
-	}
-	return throttledFn
+	return defaultScheduler.fpsThrottle(fn)
 }
 
 /**
- * Schedules a function to execute on the next animation frame, targeting 60fps.
+ * Schedules a function to execute on the next animation frame, targeting 120fps.
  * If the same function is passed multiple times before the frame executes,
  * it will only be called once, effectively batching multiple calls.
  *
+ * Uses the default throttle instance for UI operations.
+ *
  * @param fn - The function to execute on the next frame
  * @returns A cancel function that can prevent execution if called before the next frame
  *
@@ -138,20 +223,5 @@ export function fpsThrottle(fn: { (): void; cancel?(): void }): {
  * @internal
  */
 export function throttleToNextFrame(fn: () => void): () => void {
-	if (isTest()) {
-		fn()
-		return () => void null // noop
-	}
-
-	if (!fpsQueue.includes(fn)) {
-		fpsQueue.push(fn)
-		tick()
-	}
-
-	return () => {
-		const index = fpsQueue.indexOf(fn)
-		if (index > -1) {
-			fpsQueue.splice(index, 1)
-		}
-	}
+	return defaultScheduler.throttleToNextFrame(fn)
 }