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

package/src/lib/retry.test.ts

@@ -0,0 +1,77 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { retry } from './retry'
+
+describe('retry', () => {
+	beforeEach(() => {
+		vi.useFakeTimers()
+	})
+
+	afterEach(() => {
+		vi.useRealTimers()
+	})
+
+	it('returns result when function succeeds on first attempt', async () => {
+		const successFn = vi.fn().mockResolvedValue('success')
+
+		const result = await retry(successFn)
+
+		expect(result).toBe('success')
+		expect(successFn).toHaveBeenCalledTimes(1)
+	})
+
+	it('returns result when function succeeds after failures', async () => {
+		const successFn = vi
+			.fn()
+			.mockRejectedValueOnce(new Error('fail 1'))
+			.mockRejectedValueOnce(new Error('fail 2'))
+			.mockResolvedValue('success')
+
+		const promise = retry(successFn)
+
+		await vi.advanceTimersByTimeAsync(3000)
+		const result = await promise
+
+		expect(result).toBe('success')
+		expect(successFn).toHaveBeenCalledTimes(3)
+	})
+
+	it('respects custom waitDuration setting', async () => {
+		const failFn = vi.fn().mockRejectedValueOnce(new Error('fail 1')).mockResolvedValue('success')
+
+		const promise = retry(failFn, { waitDuration: 2500 })
+
+		await vi.advanceTimersByTimeAsync(2000)
+		expect(failFn).toHaveBeenCalledTimes(1)
+
+		await vi.advanceTimersByTimeAsync(1000)
+		const result = await promise
+
+		expect(result).toBe('success')
+		expect(failFn).toHaveBeenCalledTimes(2)
+	})
+
+	it('retries only errors that match the filter', async () => {
+		class NetworkError extends Error {
+			constructor(message: string) {
+				super(message)
+				this.name = 'NetworkError'
+			}
+		}
+
+		const failFn = vi
+			.fn()
+			.mockRejectedValueOnce(new NetworkError('network fail'))
+			.mockRejectedValueOnce(new NetworkError('network fail 2'))
+			.mockResolvedValue('success')
+
+		const promise = retry(failFn, {
+			matchError: (error) => error instanceof NetworkError,
+		})
+
+		await vi.advanceTimersByTimeAsync(3000)
+		const result = await promise
+
+		expect(result).toBe('success')
+		expect(failFn).toHaveBeenCalledTimes(3)
+	})
+})

package/src/lib/retry.ts

@@ -1,6 +1,52 @@
 import { sleep } from './control'
 
-/** @internal */
+/**
+ * Retries an async operation with configurable attempt count, wait duration, and error filtering.
+ * Executes the provided async function repeatedly until it succeeds or the maximum number of attempts is reached.
+ * Includes support for abort signals and custom error matching to determine which errors should trigger retries.
+ *
+ * @param fn - The async function to retry on failure
+ * @param options - Configuration options for retry behavior:
+ *   - `attempts`: Maximum number of retry attempts (default: 3)
+ *   - `waitDuration`: Milliseconds to wait between retry attempts (default: 1000)
+ *   - `abortSignal`: Optional AbortSignal to cancel the retry operation
+ *   - `matchError`: Optional function to determine if an error should trigger a retry
+ * @returns Promise that resolves with the function's return value on success
+ *
+ * @example
+ * ```ts
+ * // Basic retry with default settings (3 attempts, 1 second wait)
+ * const data = await retry(async () => {
+ *   const response = await fetch('/api/data')
+ *   if (!response.ok) throw new Error('Network error')
+ *   return response.json()
+ * })
+ *
+ * // Custom retry configuration
+ * const result = await retry(
+ *   async () => unreliableApiCall(),
+ *   {
+ *     attempts: 5,
+ *     waitDuration: 2000,
+ *     matchError: (error) => error instanceof NetworkError
+ *   }
+ * )
+ *
+ * // With abort signal for cancellation
+ * const controller = new AbortController()
+ * setTimeout(() => controller.abort(), 10000) // Cancel after 10 seconds
+ *
+ * const data = await retry(
+ *   async () => fetchData(),
+ *   {
+ *     attempts: 10,
+ *     abortSignal: controller.signal
+ *   }
+ * )
+ * ```
+ *
+ * @internal
+ */
 export async function retry<T>(
 	fn: () => Promise<T>,
 	{

package/src/lib/sort.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest'
+import { sortById } from './sort'
+
+describe('sortById', () => {
+	it('sorts objects with string ids in ascending order', () => {
+		const items = [
+			{ id: 'c', name: 'Charlie' },
+			{ id: 'a', name: 'Alice' },
+			{ id: 'b', name: 'Bob' },
+		]
+
+		const sorted = items.sort(sortById)
+
+		expect(sorted).toEqual([
+			{ id: 'a', name: 'Alice' },
+			{ id: 'b', name: 'Bob' },
+			{ id: 'c', name: 'Charlie' },
+		])
+	})
+
+	it('sorts objects with numeric ids in ascending order', () => {
+		const items = [
+			{ id: 3, label: 'three' },
+			{ id: 1, label: 'one' },
+			{ id: 2, label: 'two' },
+		]
+
+		const sorted = items.sort(sortById)
+
+		expect(sorted).toEqual([
+			{ id: 1, label: 'one' },
+			{ id: 2, label: 'two' },
+			{ id: 3, label: 'three' },
+		])
+	})
+})

package/src/lib/sort.ts

@@ -1,4 +1,25 @@
-/** @public */
+/**
+ * Compares two objects by their id property for use with Array.sort().
+ * Sorts objects in ascending order based on their id values.
+ *
+ * @param a - First object to compare
+ * @param b - Second object to compare
+ * @returns 1 if a.id \> b.id, -1 if a.id \<= b.id
+ *
+ * @example
+ * ```ts
+ * const items = [
+ *   { id: 'c', name: 'Charlie' },
+ *   { id: 'a', name: 'Alice' },
+ *   { id: 'b', name: 'Bob' },
+ * ]
+ *
+ * const sorted = items.sort(sortById)
+ * // [{ id: 'a', name: 'Alice' }, { id: 'b', name: 'Bob' }, { id: 'c', name: 'Charlie' }]
+ * ```
+ *
+ * @public
+ */
 export function sortById<T extends { id: any }>(a: T, b: T) {
 	return a.id > b.id ? 1 : -1
 }

package/src/lib/storage.test.ts

@@ -0,0 +1,130 @@
+/* eslint-disable no-restricted-syntax */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+	clearLocalStorage,
+	clearSessionStorage,
+	deleteFromLocalStorage,
+	deleteFromSessionStorage,
+	getFromLocalStorage,
+	getFromSessionStorage,
+	setInLocalStorage,
+	setInSessionStorage,
+} from './storage'
+
+describe('storage', () => {
+	// Store original implementations
+	const originalLocalStorage = global.localStorage
+	const originalSessionStorage = global.sessionStorage
+
+	beforeEach(() => {
+		// Mock localStorage
+		const localStorageMock = {
+			getItem: vi.fn(),
+			setItem: vi.fn(),
+			removeItem: vi.fn(),
+			clear: vi.fn(),
+		}
+		global.localStorage = localStorageMock as any
+
+		// Mock sessionStorage
+		const sessionStorageMock = {
+			getItem: vi.fn(),
+			setItem: vi.fn(),
+			removeItem: vi.fn(),
+			clear: vi.fn(),
+		}
+		global.sessionStorage = sessionStorageMock as any
+	})
+
+	afterEach(() => {
+		// Restore original implementations
+		global.localStorage = originalLocalStorage
+		global.sessionStorage = originalSessionStorage
+		vi.clearAllMocks()
+	})
+
+	describe('getFromLocalStorage', () => {
+		it('should return null when localStorage.getItem throws an error', () => {
+			;(localStorage.getItem as any).mockImplementation(() => {
+				throw new Error('Storage not available')
+			})
+
+			const result = getFromLocalStorage('test-key')
+
+			expect(result).toBe(null)
+		})
+	})
+
+	describe('setInLocalStorage', () => {
+		it('should not throw when localStorage.setItem throws an error', () => {
+			;(localStorage.setItem as any).mockImplementation(() => {
+				throw new Error('Quota exceeded')
+			})
+
+			expect(() => setInLocalStorage('test-key', 'test-value')).not.toThrow()
+		})
+	})
+
+	describe('deleteFromLocalStorage', () => {
+		it('should not throw when localStorage.removeItem throws an error', () => {
+			;(localStorage.removeItem as any).mockImplementation(() => {
+				throw new Error('Storage not available')
+			})
+
+			expect(() => deleteFromLocalStorage('test-key')).not.toThrow()
+		})
+	})
+
+	describe('clearLocalStorage', () => {
+		it('should not throw when localStorage.clear throws an error', () => {
+			;(localStorage.clear as any).mockImplementation(() => {
+				throw new Error('Storage not available')
+			})
+
+			expect(() => clearLocalStorage()).not.toThrow()
+		})
+	})
+
+	describe('getFromSessionStorage', () => {
+		it('should return null when sessionStorage.getItem throws an error', () => {
+			;(sessionStorage.getItem as any).mockImplementation(() => {
+				throw new Error('Storage not available')
+			})
+
+			const result = getFromSessionStorage('session-key')
+
+			expect(result).toBe(null)
+		})
+	})
+
+	describe('setInSessionStorage', () => {
+		it('should not throw when sessionStorage.setItem throws an error', () => {
+			;(sessionStorage.setItem as any).mockImplementation(() => {
+				throw new Error('Quota exceeded')
+			})
+
+			expect(() => setInSessionStorage('session-key', 'session-value')).not.toThrow()
+		})
+	})
+
+	describe('deleteFromSessionStorage', () => {
+		it('should not throw when sessionStorage.removeItem throws an error', () => {
+			;(sessionStorage.removeItem as any).mockImplementation(() => {
+				throw new Error('Storage not available')
+			})
+
+			expect(() => deleteFromSessionStorage('session-key')).not.toThrow()
+		})
+	})
+
+	describe('clearSessionStorage', () => {
+		it('should not throw when sessionStorage.clear throws an error', () => {
+			;(sessionStorage.clear as any).mockImplementation(() => {
+				throw new Error('Storage not available')
+			})
+
+			expect(() => clearSessionStorage()).not.toThrow()
+		})
+	})
+})

package/src/lib/storage.tsx

@@ -4,7 +4,14 @@
  * Get a value from local storage.
  *
  * @param key - The key to get.
- *
+ * @returns The stored value as a string, or null if not found or storage is unavailable.
+ * @example
+ * ```ts
+ * const userTheme = getFromLocalStorage('user-theme')
+ * if (userTheme) {
+ *   console.log('Stored theme:', userTheme)
+ * }
+ * ```
  * @internal
  */
 export function getFromLocalStorage(key: string) {
@@ -20,7 +27,12 @@ export function getFromLocalStorage(key: string) {
  *
  * @param key - The key to set.
  * @param value - The value to set.
- *
+ * @returns void
+ * @example
+ * ```ts
+ * const preferences = { theme: 'dark', language: 'en' }
+ * setInLocalStorage('user-preferences', JSON.stringify(preferences))
+ * ```
  * @internal
  */
 export function setInLocalStorage(key: string, value: string) {
@@ -34,8 +46,13 @@ export function setInLocalStorage(key: string, value: string) {
 /**
  * Remove a value from local storage. Will not throw an error if localStorage is not available.
  *
- * @param key - The key to set.
- *
+ * @param key - The key to remove.
+ * @returns void
+ * @example
+ * ```ts
+ * deleteFromLocalStorage('user-preferences')
+ * // Value is now removed from localStorage
+ * ```
  * @internal
  */
 export function deleteFromLocalStorage(key: string) {
@@ -49,6 +66,12 @@ export function deleteFromLocalStorage(key: string) {
 /**
  * Clear all values from local storage. Will not throw an error if localStorage is not available.
  *
+ * @returns void
+ * @example
+ * ```ts
+ * clearLocalStorage()
+ * // All localStorage data is now cleared
+ * ```
  * @internal
  */
 export function clearLocalStorage() {
@@ -63,7 +86,14 @@ export function clearLocalStorage() {
  * Get a value from session storage.
  *
  * @param key - The key to get.
- *
+ * @returns The stored value as a string, or null if not found or storage is unavailable.
+ * @example
+ * ```ts
+ * const currentTool = getFromSessionStorage('current-tool')
+ * if (currentTool) {
+ *   console.log('Active tool:', currentTool)
+ * }
+ * ```
  * @internal
  */
 export function getFromSessionStorage(key: string) {
@@ -79,7 +109,12 @@ export function getFromSessionStorage(key: string) {
  *
  * @param key - The key to set.
  * @param value - The value to set.
- *
+ * @returns void
+ * @example
+ * ```ts
+ * setInSessionStorage('current-tool', 'select')
+ * setInSessionStorage('temp-data', JSON.stringify({ x: 100, y: 200 }))
+ * ```
  * @internal
  */
 export function setInSessionStorage(key: string, value: string) {
@@ -93,8 +128,13 @@ export function setInSessionStorage(key: string, value: string) {
 /**
  * Remove a value from session storage. Will not throw an error if sessionStorage is not available.
  *
- * @param key - The key to set.
- *
+ * @param key - The key to remove.
+ * @returns void
+ * @example
+ * ```ts
+ * deleteFromSessionStorage('temp-data')
+ * // Value is now removed from sessionStorage
+ * ```
  * @internal
  */
 export function deleteFromSessionStorage(key: string) {
@@ -108,6 +148,12 @@ export function deleteFromSessionStorage(key: string) {
 /**
  * Clear all values from session storage. Will not throw an error if sessionStorage is not available.
  *
+ * @returns void
+ * @example
+ * ```ts
+ * clearSessionStorage()
+ * // All sessionStorage data is now cleared
+ * ```
  * @internal
  */
 export function clearSessionStorage() {

package/src/lib/stringEnum.ts

@@ -1,4 +1,23 @@
-/** @internal */
+/**
+ * Creates an enum-like object from string values where each key maps to itself.
+ * Useful for creating string constant objects with type safety and autocompletion.
+ * @param values - The string values to create the enum from.
+ * @returns An object where each provided string is both the key and value.
+ * @example
+ * ```ts
+ * const Colors = stringEnum('red', 'green', 'blue')
+ * // Results in: { red: 'red', green: 'green', blue: 'blue' }
+ *
+ * // Type-safe usage
+ * function setColor(color: keyof typeof Colors) {
+ *   console.log(`Setting color to ${Colors[color]}`)
+ * }
+ *
+ * setColor('red') // ✓ Valid
+ * setColor('yellow') // ✗ TypeScript error
+ * ```
+ * @internal
+ */
 export function stringEnum<T extends string>(...values: T[]): { [K in T]: K } {
 	const obj = {} as { [K in T]: K }
 	for (const value of values) {

package/src/lib/throttle.ts

@@ -52,10 +52,27 @@ function tick(isOnNextFrame = false) {
 }
 
 /**
- * Returns a throttled version of the function that will only be called max once per frame.
- * The target frame rate is 60fps.
- * @param fn - the fun to return a throttled version of
- * @returns
+ * Creates a throttled version of a function that executes at most once per frame (60fps).
+ * 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
+ *
+ * @example
+ * ```ts
+ * const updateCanvas = fpsThrottle(() => {
+ *   // This will run at most once per frame (~16.67ms)
+ *   redrawCanvas()
+ * })
+ *
+ * // Call as often as you want - automatically throttled to 60fps
+ * document.addEventListener('mousemove', updateCanvas)
+ *
+ * // Cancel pending calls if needed
+ * updateCanvas.cancel?.()
+ * ```
+ *
  * @internal
  */
 export function fpsThrottle(fn: { (): void; cancel?(): void }): {
@@ -93,10 +110,31 @@ export function fpsThrottle(fn: { (): void; cancel?(): void }): {
 }
 
 /**
- * Calls the function on the next frame. The target frame rate is 60fps.
- * If the same fn is passed again before the next frame, it will still be called only once.
- * @param fn - the fun to call on the next frame
- * @returns a function that will cancel the call if called before the next frame
+ * Schedules a function to execute on the next animation frame, targeting 60fps.
+ * 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
+ *
+ * @example
+ * ```ts
+ * const updateUI = throttleToNextFrame(() => {
+ *   // Batches multiple calls into the next animation frame
+ *   updateStatusBar()
+ *   refreshToolbar()
+ * })
+ *
+ * // Multiple calls within the same frame are batched
+ * updateUI() // Will execute
+ * updateUI() // Ignored (same function already queued)
+ * updateUI() // Ignored (same function already queued)
+ *
+ * // Get cancel function to prevent execution
+ * const cancel = updateUI()
+ * cancel() // Prevents execution if called before next frame
+ * ```
+ *
  * @internal
  */
 export function throttleToNextFrame(fn: () => void): () => void {

package/src/lib/timers.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Timers } from './timers'
+
+describe('Timers', () => {
+	it('tracks timers by context and disposes them correctly', () => {
+		const timers = new Timers()
+		const mockClearTimeout = vi.fn()
+		const mockClearInterval = vi.fn()
+		const mockCancelAnimationFrame = vi.fn()
+
+		// Mock only the clear functions since those are what we need to verify
+		vi.stubGlobal('setTimeout', vi.fn().mockReturnValueOnce(1).mockReturnValueOnce(2))
+		vi.stubGlobal('setInterval', vi.fn().mockReturnValue(3))
+		vi.stubGlobal('requestAnimationFrame', vi.fn().mockReturnValue(4))
+		vi.stubGlobal('clearTimeout', mockClearTimeout)
+		vi.stubGlobal('clearInterval', mockClearInterval)
+		vi.stubGlobal('cancelAnimationFrame', mockCancelAnimationFrame)
+
+		// Create timers in different contexts
+		timers.setTimeout('context1', () => {}, 1000)
+		timers.setTimeout('context1', () => {}, 2000)
+		timers.setInterval('context1', () => {}, 500)
+		timers.requestAnimationFrame('context2', () => {})
+
+		// Dispose one context
+		timers.dispose('context1')
+
+		// Should clear timers for context1 but not context2
+		expect(mockClearTimeout).toHaveBeenCalledWith(1)
+		expect(mockClearTimeout).toHaveBeenCalledWith(2)
+		expect(mockClearInterval).toHaveBeenCalledWith(3)
+		expect(mockCancelAnimationFrame).not.toHaveBeenCalled()
+
+		vi.unstubAllGlobals()
+	})
+
+	it('disposes all contexts with disposeAll', () => {
+		const timers = new Timers()
+		const mockClearTimeout = vi.fn()
+		const mockClearInterval = vi.fn()
+
+		vi.stubGlobal('setTimeout', vi.fn().mockReturnValueOnce(1).mockReturnValueOnce(2))
+		vi.stubGlobal('setInterval', vi.fn().mockReturnValue(3))
+		vi.stubGlobal('clearTimeout', mockClearTimeout)
+		vi.stubGlobal('clearInterval', mockClearInterval)
+
+		timers.setTimeout('context1', () => {}, 1000)
+		timers.setTimeout('context2', () => {}, 2000)
+		timers.setInterval('context1', () => {}, 500)
+
+		timers.disposeAll()
+
+		expect(mockClearTimeout).toHaveBeenCalledWith(1)
+		expect(mockClearTimeout).toHaveBeenCalledWith(2)
+		expect(mockClearInterval).toHaveBeenCalledWith(3)
+
+		vi.unstubAllGlobals()
+	})
+
+	it('provides context-bound methods via forContext', () => {
+		const timers = new Timers()
+		const mockClearTimeout = vi.fn()
+
+		vi.stubGlobal('setTimeout', vi.fn().mockReturnValue(1))
+		vi.stubGlobal('clearTimeout', mockClearTimeout)
+
+		const contextTimers = timers.forContext('test-context')
+		contextTimers.setTimeout(() => {}, 1000)
+		contextTimers.dispose()
+
+		expect(mockClearTimeout).toHaveBeenCalledWith(1)
+
+		vi.unstubAllGlobals()
+	})
+})