@tldraw/utils 4.1.0-next.b6dfe9bccde9 → 4.1.0-next.b73a0d46b63f

package/src/lib/ExecutionQueue.ts

@@ -1,12 +1,75 @@
 import { sleep } from './control'
 
-/** @internal */
+/**
+ * A queue that executes tasks sequentially with optional delay between tasks.
+ *
+ * ExecutionQueue ensures that tasks are executed one at a time in the order they were added,
+ * with an optional timeout delay between each task execution. This is useful for rate limiting,
+ * preventing race conditions, or controlling the flow of asynchronous operations.
+ *
+ * @example
+ * ```ts
+ * // Create a queue with 100ms delay between tasks
+ * const queue = new ExecutionQueue(100)
+ *
+ * // Add tasks to the queue
+ * const result1 = await queue.push(() => fetch('/api/data'))
+ * const result2 = await queue.push(async () => {
+ *   const data = await processData()
+ *   return data
+ * })
+ *
+ * // Check if queue is empty
+ * if (queue.isEmpty()) {
+ *   console.log('All tasks completed')
+ * }
+ *
+ * // Clean up
+ * queue.close()
+ * ```
+ *
+ * @internal
+ */
 export class ExecutionQueue {
 	private queue: (() => Promise<any>)[] = []
 	private running = false
 
+	/**
+	 * Creates a new ExecutionQueue.
+	 *
+	 * Creates a new execution queue that will process tasks sequentially.
+	 * If a timeout is provided, there will be a delay between each task execution,
+	 * which is useful for rate limiting or controlling execution flow.
+	 *
+	 * timeout - Optional delay in milliseconds between task executions
+	 * @example
+	 * ```ts
+	 * // Create queue without delay
+	 * const fastQueue = new ExecutionQueue()
+	 *
+	 * // Create queue with 500ms delay between tasks
+	 * const slowQueue = new ExecutionQueue(500)
+	 * ```
+	 */
 	constructor(private readonly timeout?: number) {}
 
+	/**
+	 * Checks if the queue is empty and not currently running a task.
+	 *
+	 * Determines whether the execution queue has completed all tasks and is idle.
+	 * Returns true only when there are no pending tasks in the queue AND no task is currently being executed.
+	 *
+	 * @returns True if the queue has no pending tasks and is not currently executing
+	 * @example
+	 * ```ts
+	 * const queue = new ExecutionQueue()
+	 *
+	 * console.log(queue.isEmpty()) // true - queue is empty
+	 *
+	 * queue.push(() => console.log('task'))
+	 * console.log(queue.isEmpty()) // false - task is running/pending
+	 * ```
+	 */
 	isEmpty() {
 		return this.queue.length === 0 && !this.running
 	}
@@ -25,10 +88,34 @@ export class ExecutionQueue {
 		} finally {
 			// this try/finally should not be needed because the tasks don't throw
 			// but better safe than sorry
+			// console.log('\n\n\nrunning false\n\n\n')
 			this.running = false
 		}
 	}
 
+	/**
+	 * Adds a task to the queue and returns a promise that resolves with the task's result.
+	 *
+	 * Enqueues a task for sequential execution. The task will be executed after all
+	 * previously queued tasks have completed. If a timeout was specified in the constructor,
+	 * there will be a delay between this task and the next one.
+	 *
+	 * @param task - The function to execute (can be sync or async)
+	 * @returns Promise that resolves with the task's return value
+	 * @example
+	 * ```ts
+	 * const queue = new ExecutionQueue(100)
+	 *
+	 * // Add async task
+	 * const result = await queue.push(async () => {
+	 *   const response = await fetch('/api/data')
+	 *   return response.json()
+	 * })
+	 *
+	 * // Add sync task
+	 * const number = await queue.push(() => 42)
+	 * ```
+	 */
 	async push<T>(task: () => T): Promise<Awaited<T>> {
 		return new Promise<Awaited<T>>((resolve, reject) => {
 			this.queue.push(() => Promise.resolve(task()).then(resolve).catch(reject))
@@ -36,6 +123,28 @@ export class ExecutionQueue {
 		})
 	}
 
+	/**
+	 * Clears all pending tasks from the queue.
+	 *
+	 * Immediately removes all pending tasks from the queue. Any currently
+	 * running task will complete normally, but no additional tasks will be executed.
+	 * This method does not wait for the current task to finish.
+	 *
+	 * @returns void
+	 * @example
+	 * ```ts
+	 * const queue = new ExecutionQueue()
+	 *
+	 * // Add several tasks
+	 * queue.push(() => console.log('task 1'))
+	 * queue.push(() => console.log('task 2'))
+	 * queue.push(() => console.log('task 3'))
+	 *
+	 * // Clear all pending tasks
+	 * queue.close()
+	 * // Only 'task 1' will execute if it was already running
+	 * ```
+	 */
 	close() {
 		this.queue = []
 	}

package/src/lib/PerformanceTracker.test.ts

@@ -0,0 +1,124 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { PerformanceTracker } from './PerformanceTracker'
+import { PERFORMANCE_COLORS, PERFORMANCE_PREFIX_COLOR } from './perf'
+
+describe('PerformanceTracker', () => {
+	let tracker: PerformanceTracker
+	let mockPerformanceNow: ReturnType<typeof vi.fn>
+	let mockRequestAnimationFrame: ReturnType<typeof vi.fn>
+	let mockCancelAnimationFrame: ReturnType<typeof vi.fn>
+	let mockConsoleDebug: ReturnType<typeof vi.fn>
+	let frameId = 1
+
+	beforeEach(() => {
+		tracker = new PerformanceTracker()
+
+		// Mock performance.now
+		mockPerformanceNow = vi.fn()
+		vi.stubGlobal('performance', { now: mockPerformanceNow })
+
+		// Mock requestAnimationFrame and cancelAnimationFrame
+		mockRequestAnimationFrame = vi.fn().mockImplementation(() => frameId++)
+		mockCancelAnimationFrame = vi.fn()
+		vi.stubGlobal('requestAnimationFrame', mockRequestAnimationFrame)
+		vi.stubGlobal('cancelAnimationFrame', mockCancelAnimationFrame)
+
+		// Mock console.debug
+		mockConsoleDebug = vi.fn()
+		vi.spyOn(console, 'debug').mockImplementation(mockConsoleDebug)
+	})
+
+	afterEach(() => {
+		vi.unstubAllGlobals()
+		vi.restoreAllMocks()
+		frameId = 1
+	})
+
+	it('tracks start/stop state correctly', () => {
+		expect(tracker.isStarted()).toBe(false)
+
+		mockPerformanceNow.mockReturnValue(100)
+		tracker.start('test')
+		expect(tracker.isStarted()).toBe(true)
+
+		mockPerformanceNow.mockReturnValue(200)
+		tracker.stop()
+		expect(tracker.isStarted()).toBe(false)
+	})
+
+	it('calculates and logs FPS correctly', () => {
+		// Setup: 1 second duration with 60 frames
+		mockPerformanceNow.mockReturnValueOnce(0).mockReturnValueOnce(1000)
+
+		tracker.start('render')
+		const recordFrame = mockRequestAnimationFrame.mock.calls[0][0]
+
+		// Simulate 60 frames
+		for (let i = 0; i < 60; i++) {
+			recordFrame()
+		}
+
+		tracker.stop()
+
+		expect(mockConsoleDebug).toHaveBeenCalledWith(
+			'%cPerf%c Render %c60%c fps',
+			`color: white; background: ${PERFORMANCE_PREFIX_COLOR};padding: 2px;border-radius: 3px;`,
+			'font-weight: normal',
+			`font-weight: bold; padding: 2px; background: ${PERFORMANCE_COLORS.Good};color: white;`,
+			'font-weight: normal'
+		)
+	})
+
+	it('resets frame count between tracking sessions', () => {
+		mockPerformanceNow.mockReturnValueOnce(100).mockReturnValueOnce(200)
+
+		// First session with frames
+		tracker.start('test')
+		const recordFrame = mockRequestAnimationFrame.mock.calls[0][0]
+		recordFrame() // simulate frame
+		recordFrame() // simulate frame
+		tracker.stop()
+
+		// Second session should reset frame count
+		mockPerformanceNow.mockReturnValueOnce(300).mockReturnValueOnce(400)
+		tracker.start('test2')
+		tracker.stop()
+
+		// Should show 0 fps for second session (0 frames in 0.1 seconds)
+		expect(mockConsoleDebug).toHaveBeenLastCalledWith(
+			'%cPerf%c Test2 %c0%c fps',
+			expect.any(String),
+			'font-weight: normal',
+			expect.any(String),
+			'font-weight: normal'
+		)
+	})
+
+	it('records frames only while tracking is active', () => {
+		mockPerformanceNow.mockReturnValue(100)
+
+		tracker.start('test')
+		const recordFrame = mockRequestAnimationFrame.mock.calls[0][0]
+
+		tracker.stop()
+		mockRequestAnimationFrame.mockClear()
+
+		// Frame recording should stop after stop() is called
+		recordFrame()
+		expect(mockRequestAnimationFrame).not.toHaveBeenCalled()
+	})
+
+	it('handles zero duration gracefully', () => {
+		// Zero duration should not crash
+		mockPerformanceNow.mockReturnValue(100)
+		tracker.start('instant')
+		tracker.stop()
+		expect(mockConsoleDebug).toHaveBeenCalledWith(
+			'%cPerf%c Instant %c0%c fps',
+			expect.any(String),
+			'font-weight: normal',
+			expect.any(String),
+			'font-weight: normal'
+		)
+	})
+})

package/src/lib/PerformanceTracker.ts

@@ -1,6 +1,25 @@
 import { PERFORMANCE_COLORS, PERFORMANCE_PREFIX_COLOR } from './perf'
 
-/** @public */
+/**
+ * A utility class for measuring and tracking frame rate performance during operations.
+ * Provides visual feedback in the browser console with color-coded FPS indicators.
+ *
+ * @example
+ * ```ts
+ * const tracker = new PerformanceTracker()
+ *
+ * tracker.start('render')
+ * renderShapes()
+ * tracker.stop() // Logs performance info to console
+ *
+ * // Check if tracking is active
+ * if (tracker.isStarted()) {
+ *   console.log('Still tracking performance')
+ * }
+ * ```
+ *
+ * @public
+ */
 export class PerformanceTracker {
 	private startTime = 0
 	private name = ''
@@ -8,6 +27,10 @@ export class PerformanceTracker {
 	private started = false
 	private frame: number | null = null
 
+	/**
+	 * Records animation frames to calculate frame rate.
+	 * Called automatically during performance tracking.
+	 */
 	// eslint-disable-next-line local/prefer-class-methods
 	recordFrame = () => {
 		this.frames++
@@ -16,6 +39,18 @@ export class PerformanceTracker {
 		this.frame = requestAnimationFrame(this.recordFrame)
 	}
 
+	/**
+	 * Starts performance tracking for a named operation.
+	 *
+	 * @param name - A descriptive name for the operation being tracked
+	 *
+	 * @example
+	 * ```ts
+	 * tracker.start('canvas-render')
+	 * // ... perform rendering operations
+	 * tracker.stop()
+	 * ```
+	 */
 	start(name: string) {
 		this.name = name
 		this.frames = 0
@@ -26,6 +61,21 @@ export class PerformanceTracker {
 		this.startTime = performance.now()
 	}
 
+	/**
+	 * Stops performance tracking and logs results to the console.
+	 *
+	 * Displays the operation name, frame rate, and uses color coding:
+	 * - Green background: \> 55 FPS (good performance)
+	 * - Yellow background: 30-55 FPS (moderate performance)
+	 * - Red background: \< 30 FPS (poor performance)
+	 *
+	 * @example
+	 * ```ts
+	 * tracker.start('interaction')
+	 * handleUserInteraction()
+	 * tracker.stop() // Logs: "Perf Interaction 60 fps"
+	 * ```
+	 */
 	stop() {
 		this.started = false
 		if (this.frame !== null) cancelAnimationFrame(this.frame)
@@ -49,6 +99,18 @@ export class PerformanceTracker {
 		)
 	}
 
+	/**
+	 * Checks whether performance tracking is currently active.
+	 *
+	 * @returns True if tracking is in progress, false otherwise
+	 *
+	 * @example
+	 * ```ts
+	 * if (!tracker.isStarted()) {
+	 *   tracker.start('new-operation')
+	 * }
+	 * ```
+	 */
 	isStarted() {
 		return this.started
 	}

package/src/lib/array.test.ts

@@ -1,4 +1,266 @@
-import { mergeArraysAndReplaceDefaults } from './array'
+import {
+	areArraysShallowEqual,
+	compact,
+	dedupe,
+	last,
+	maxBy,
+	mergeArraysAndReplaceDefaults,
+	minBy,
+	partition,
+	rotateArray,
+} from './array'
+
+describe('rotateArray', () => {
+	test('should rotate array to the left with positive offset', () => {
+		// Based on JSDoc examples, this is the expected behavior
+		expect(rotateArray([1, 2, 3, 4], 1)).toEqual([2, 3, 4, 1])
+		expect(rotateArray([1, 2, 3, 4], 2)).toEqual([3, 4, 1, 2])
+	})
+
+	test('should rotate array to the left with negative offset', () => {
+		// Based on JSDoc examples, this is the expected behavior
+		expect(rotateArray([1, 2, 3, 4], -1)).toEqual([2, 3, 4, 1])
+		expect(rotateArray([1, 2, 3, 4], -2)).toEqual([3, 4, 1, 2])
+	})
+
+	it('should handle zero offset', () => {
+		expect(rotateArray([1, 2, 3, 4], 0)).toEqual([1, 2, 3, 4])
+	})
+
+	test('should handle offset larger than array length', () => {
+		// Based on understanding of rotation: offset 5 on length 3 should be same as offset 2
+		expect(rotateArray([1, 2, 3], 5)).toEqual([3, 1, 2])
+		// offset -5 on length 3 should be same as offset -2 which should be same as offset 2
+		expect(rotateArray([1, 2, 3], -5)).toEqual([3, 1, 2])
+	})
+
+	it('should handle empty array', () => {
+		expect(rotateArray([], 1)).toEqual([])
+	})
+
+	test('should work with different types', () => {
+		// Based on JSDoc examples, this is the expected behavior
+		expect(rotateArray(['a', 'b', 'c'], 2)).toEqual(['c', 'a', 'b'])
+	})
+})
+
+describe('dedupe', () => {
+	it('should remove duplicate primitives', () => {
+		expect(dedupe([1, 2, 2, 3, 1])).toEqual([1, 2, 3])
+		expect(dedupe(['a', 'b', 'a', 'c'])).toEqual(['a', 'b', 'c'])
+	})
+
+	it('should preserve order of first occurrence', () => {
+		expect(dedupe([3, 1, 2, 1, 3])).toEqual([3, 1, 2])
+	})
+
+	it('should handle empty array', () => {
+		expect(dedupe([])).toEqual([])
+	})
+
+	it('should handle array with no duplicates', () => {
+		expect(dedupe([1, 2, 3])).toEqual([1, 2, 3])
+	})
+
+	it('should use custom equality function', () => {
+		const objects = [
+			{ id: 1, name: 'a' },
+			{ id: 2, name: 'b' },
+			{ id: 1, name: 'c' },
+		]
+		expect(dedupe(objects, (a, b) => a.id === b.id)).toEqual([
+			{ id: 1, name: 'a' },
+			{ id: 2, name: 'b' },
+		])
+	})
+
+	it('should handle objects without custom equality', () => {
+		const obj1 = { id: 1 }
+		const obj2 = { id: 2 }
+		expect(dedupe([obj1, obj2, obj1])).toEqual([obj1, obj2])
+	})
+})
+
+describe('compact', () => {
+	it('should remove null and undefined values', () => {
+		expect(compact([1, null, 2, undefined, 3])).toEqual([1, 2, 3])
+	})
+
+	it('should preserve falsy values that are not null/undefined', () => {
+		expect(compact([0, false, '', null, undefined, 'hello'])).toEqual([0, false, '', 'hello'])
+	})
+
+	it('should handle empty array', () => {
+		expect(compact([])).toEqual([])
+	})
+
+	it('should handle array with only null/undefined', () => {
+		expect(compact([null, undefined, null])).toEqual([])
+	})
+
+	it('should handle array with no null/undefined', () => {
+		expect(compact([1, 2, 3])).toEqual([1, 2, 3])
+	})
+})
+
+describe('last', () => {
+	it('should return last element of array', () => {
+		expect(last([1, 2, 3])).toBe(3)
+		expect(last(['a', 'b', 'c'])).toBe('c')
+	})
+
+	it('should return undefined for empty array', () => {
+		expect(last([])).toBeUndefined()
+	})
+
+	it('should work with single element array', () => {
+		expect(last([42])).toBe(42)
+	})
+
+	it('should work with readonly arrays', () => {
+		const readonlyArr: readonly number[] = [1, 2, 3]
+		expect(last(readonlyArr)).toBe(3)
+	})
+})
+
+describe('minBy', () => {
+	it('should find item with minimum value', () => {
+		const people = [
+			{ name: 'Alice', age: 30 },
+			{ name: 'Bob', age: 25 },
+			{ name: 'Charlie', age: 35 },
+		]
+		expect(minBy(people, (p) => p.age)).toEqual({ name: 'Bob', age: 25 })
+	})
+
+	it('should work with numbers', () => {
+		expect(minBy([3, 1, 4, 1, 5], (x) => x)).toBe(1)
+	})
+
+	it('should return undefined for empty array', () => {
+		expect(minBy([], (x) => x)).toBeUndefined()
+	})
+
+	it('should handle ties by returning first occurrence', () => {
+		const items = [{ val: 5 }, { val: 3 }, { val: 3 }, { val: 7 }]
+		expect(minBy(items, (x) => x.val)).toEqual({ val: 3 })
+	})
+
+	it('should work with negative values', () => {
+		expect(minBy([-1, -5, -3], (x) => x)).toBe(-5)
+	})
+})
+
+describe('maxBy', () => {
+	it('should find item with maximum value', () => {
+		const people = [
+			{ name: 'Alice', age: 30 },
+			{ name: 'Bob', age: 25 },
+			{ name: 'Charlie', age: 35 },
+		]
+		expect(maxBy(people, (p) => p.age)).toEqual({ name: 'Charlie', age: 35 })
+	})
+
+	it('should work with numbers', () => {
+		expect(maxBy([3, 1, 4, 1, 5], (x) => x)).toBe(5)
+	})
+
+	it('should return undefined for empty array', () => {
+		expect(maxBy([], (x) => x)).toBeUndefined()
+	})
+
+	it('should handle ties by returning first occurrence', () => {
+		const items = [{ val: 5 }, { val: 7 }, { val: 7 }, { val: 3 }]
+		expect(maxBy(items, (x) => x.val)).toEqual({ val: 7 })
+	})
+
+	it('should work with negative values', () => {
+		expect(maxBy([-1, -5, -3], (x) => x)).toBe(-1)
+	})
+})
+
+describe('partition', () => {
+	it('should split array based on predicate', () => {
+		const [evens, odds] = partition([1, 2, 3, 4, 5], (x) => x % 2 === 0)
+		expect(evens).toEqual([2, 4])
+		expect(odds).toEqual([1, 3, 5])
+	})
+
+	it('should preserve order within partitions', () => {
+		const [adults, minors] = partition(
+			[
+				{ name: 'Alice', age: 30 },
+				{ name: 'Bob', age: 17 },
+				{ name: 'Charlie', age: 25 },
+			],
+			(person) => person.age >= 18
+		)
+		expect(adults).toEqual([
+			{ name: 'Alice', age: 30 },
+			{ name: 'Charlie', age: 25 },
+		])
+		expect(minors).toEqual([{ name: 'Bob', age: 17 }])
+	})
+
+	it('should handle empty array', () => {
+		const [satisfies, doesNotSatisfy] = partition([], (x) => x > 0)
+		expect(satisfies).toEqual([])
+		expect(doesNotSatisfy).toEqual([])
+	})
+
+	it('should handle all items satisfying predicate', () => {
+		const [satisfies, doesNotSatisfy] = partition([2, 4, 6], (x) => x % 2 === 0)
+		expect(satisfies).toEqual([2, 4, 6])
+		expect(doesNotSatisfy).toEqual([])
+	})
+
+	it('should handle no items satisfying predicate', () => {
+		const [satisfies, doesNotSatisfy] = partition([1, 3, 5], (x) => x % 2 === 0)
+		expect(satisfies).toEqual([])
+		expect(doesNotSatisfy).toEqual([1, 3, 5])
+	})
+})
+
+describe('areArraysShallowEqual', () => {
+	it('should return true for identical arrays', () => {
+		expect(areArraysShallowEqual([1, 2, 3], [1, 2, 3])).toBe(true)
+		expect(areArraysShallowEqual(['a', 'b'], ['a', 'b'])).toBe(true)
+	})
+
+	it('should return true for same reference', () => {
+		const arr = [1, 2, 3]
+		expect(areArraysShallowEqual(arr, arr)).toBe(true)
+	})
+
+	it('should return false for different lengths', () => {
+		expect(areArraysShallowEqual([1, 2], [1, 2, 3])).toBe(false)
+	})
+
+	it('should return false for different elements', () => {
+		expect(areArraysShallowEqual([1, 2, 3], [1, 2, 4])).toBe(false)
+	})
+
+	it('should return true for empty arrays', () => {
+		expect(areArraysShallowEqual([], [])).toBe(true)
+	})
+
+	it('should use Object.is for comparison', () => {
+		expect(areArraysShallowEqual([NaN], [NaN])).toBe(true)
+		expect(areArraysShallowEqual([0], [-0])).toBe(false)
+	})
+
+	it('should work with object references', () => {
+		const obj = { x: 1 }
+		expect(areArraysShallowEqual([obj], [obj])).toBe(true)
+		expect(areArraysShallowEqual([{ x: 1 }], [{ x: 1 }])).toBe(false)
+	})
+
+	it('should work with readonly arrays', () => {
+		const arr1: readonly number[] = [1, 2, 3]
+		const arr2: readonly number[] = [1, 2, 3]
+		expect(areArraysShallowEqual(arr1, arr2)).toBe(true)
+	})
+})
 
 describe('mergeArraysAndReplaceDefaults', () => {
 	it('should merge custom entries with defaults, allowing custom entries to override defaults', () => {