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

package/src/lib/timers.ts

@@ -1,11 +1,40 @@
 /* eslint-disable no-restricted-properties */
 
-/** @public */
+/**
+ * A utility class for managing timeouts, intervals, and animation frames with context-based organization and automatic cleanup.
+ * Helps prevent memory leaks by organizing timers into named contexts that can be cleared together.
+ * @example
+ * ```ts
+ * const timers = new Timers()
+ *
+ * // Set timers with context organization
+ * timers.setTimeout('ui', () => console.log('Auto save'), 5000)
+ * timers.setInterval('ui', () => console.log('Refresh'), 1000)
+ * timers.requestAnimationFrame('ui', () => console.log('Render'))
+ *
+ * // Clear all timers for a context
+ * timers.dispose('ui')
+ *
+ * // Or get context-bound functions
+ * const uiTimers = timers.forContext('ui')
+ * uiTimers.setTimeout(() => console.log('Contextual timeout'), 1000)
+ * ```
+ * @public
+ */
 export class Timers {
 	private timeouts = new Map<string, number[]>()
 	private intervals = new Map<string, number[]>()
 	private rafs = new Map<string, number[]>()
 
+	/**
+	 * Creates a new Timers instance with bound methods for safe callback usage.
+	 * @example
+	 * ```ts
+	 * const timers = new Timers()
+	 * // Methods are pre-bound, safe to use as callbacks
+	 * element.addEventListener('click', timers.dispose)
+	 * ```
+	 */
 	constructor() {
 		this.setTimeout = this.setTimeout.bind(this)
 		this.setInterval = this.setInterval.bind(this)
@@ -13,7 +42,21 @@ export class Timers {
 		this.dispose = this.dispose.bind(this)
 	}
 
-	/** @public */
+	/**
+	 * Creates a timeout that will be tracked under the specified context.
+	 * @param contextId - The context identifier to group this timer under.
+	 * @param handler - The function to execute when the timeout expires.
+	 * @param timeout - The delay in milliseconds (default: 0).
+	 * @param args - Additional arguments to pass to the handler.
+	 * @returns The timer ID that can be used with clearTimeout.
+	 * @example
+	 * ```ts
+	 * const timers = new Timers()
+	 * const id = timers.setTimeout('autosave', () => save(), 5000)
+	 * // Timer will be automatically cleared when 'autosave' context is disposed
+	 * ```
+	 * @public
+	 */
 	setTimeout(contextId: string, handler: TimerHandler, timeout?: number, ...args: any[]): number {
 		const id = window.setTimeout(handler, timeout, args)
 		const current = this.timeouts.get(contextId) ?? []
@@ -21,7 +64,21 @@ export class Timers {
 		return id
 	}
 
-	/** @public */
+	/**
+	 * Creates an interval that will be tracked under the specified context.
+	 * @param contextId - The context identifier to group this timer under.
+	 * @param handler - The function to execute repeatedly.
+	 * @param timeout - The delay in milliseconds between executions (default: 0).
+	 * @param args - Additional arguments to pass to the handler.
+	 * @returns The interval ID that can be used with clearInterval.
+	 * @example
+	 * ```ts
+	 * const timers = new Timers()
+	 * const id = timers.setInterval('refresh', () => updateData(), 1000)
+	 * // Interval will be automatically cleared when 'refresh' context is disposed
+	 * ```
+	 * @public
+	 */
 	setInterval(contextId: string, handler: TimerHandler, timeout?: number, ...args: any[]): number {
 		const id = window.setInterval(handler, timeout, args)
 		const current = this.intervals.get(contextId) ?? []
@@ -29,7 +86,19 @@ export class Timers {
 		return id
 	}
 
-	/** @public */
+	/**
+	 * Requests an animation frame that will be tracked under the specified context.
+	 * @param contextId - The context identifier to group this animation frame under.
+	 * @param callback - The function to execute on the next animation frame.
+	 * @returns The request ID that can be used with cancelAnimationFrame.
+	 * @example
+	 * ```ts
+	 * const timers = new Timers()
+	 * const id = timers.requestAnimationFrame('render', () => draw())
+	 * // Animation frame will be automatically cancelled when 'render' context is disposed
+	 * ```
+	 * @public
+	 */
 	requestAnimationFrame(contextId: string, callback: FrameRequestCallback): number {
 		const id = window.requestAnimationFrame(callback)
 		const current = this.rafs.get(contextId) ?? []
@@ -37,7 +106,22 @@ export class Timers {
 		return id
 	}
 
-	/** @public */
+	/**
+	 * Disposes of all timers associated with the specified context.
+	 * Clears all timeouts, intervals, and animation frames for the given context ID.
+	 * @param contextId - The context identifier whose timers should be cleared.
+	 * @returns void
+	 * @example
+	 * ```ts
+	 * const timers = new Timers()
+	 * timers.setTimeout('ui', () => console.log('timeout'), 1000)
+	 * timers.setInterval('ui', () => console.log('interval'), 500)
+	 *
+	 * // Clear all 'ui' context timers
+	 * timers.dispose('ui')
+	 * ```
+	 * @public
+	 */
 	dispose(contextId: string) {
 		this.timeouts.get(contextId)?.forEach((id) => clearTimeout(id))
 		this.intervals.get(contextId)?.forEach((id) => clearInterval(id))
@@ -48,12 +132,47 @@ export class Timers {
 		this.rafs.delete(contextId)
 	}
 
+	/**
+	 * Disposes of all timers across all contexts.
+	 * Clears every timeout, interval, and animation frame managed by this instance.
+	 * @returns void
+	 * @example
+	 * ```ts
+	 * const timers = new Timers()
+	 * timers.setTimeout('ui', () => console.log('ui'), 1000)
+	 * timers.setTimeout('background', () => console.log('bg'), 2000)
+	 *
+	 * // Clear everything
+	 * timers.disposeAll()
+	 * ```
+	 * @public
+	 */
 	disposeAll() {
 		for (const contextId of this.timeouts.keys()) {
 			this.dispose(contextId)
 		}
 	}
 
+	/**
+	 * Returns an object with timer methods bound to a specific context.
+	 * Convenient for getting context-specific timer functions without repeatedly passing the contextId.
+	 * @param contextId - The context identifier to bind the returned methods to.
+	 * @returns An object with setTimeout, setInterval, requestAnimationFrame, and dispose methods bound to the context.
+	 * @example
+	 * ```ts
+	 * const timers = new Timers()
+	 * const uiTimers = timers.forContext('ui')
+	 *
+	 * // These are equivalent to calling timers.setTimeout('ui', ...)
+	 * uiTimers.setTimeout(() => console.log('timeout'), 1000)
+	 * uiTimers.setInterval(() => console.log('interval'), 500)
+	 * uiTimers.requestAnimationFrame(() => console.log('frame'))
+	 *
+	 * // Dispose only this context
+	 * uiTimers.dispose()
+	 * ```
+	 * @public
+	 */
 	forContext(contextId: string) {
 		return {
 			setTimeout: (handler: TimerHandler, timeout?: number, ...args: any[]) =>

package/src/lib/types.ts

@@ -1,15 +1,137 @@
-/** @public */
+/**
+ * Makes all properties in a type and all nested properties optional recursively.
+ * This is useful for creating partial update objects where you only want to specify
+ * some deeply nested properties while leaving others unchanged.
+ *
+ * @example
+ * ```ts
+ * interface User {
+ *   name: string
+ *   settings: {
+ *     theme: string
+ *     notifications: {
+ *       email: boolean
+ *       push: boolean
+ *     }
+ *   }
+ * }
+ *
+ * type PartialUser = RecursivePartial<User>
+ * // Result: {
+ * //   name?: string
+ * //   settings?: {
+ * //     theme?: string
+ * //     notifications?: {
+ * //       email?: boolean
+ * //       push?: boolean
+ * //     }
+ * //   }
+ * // }
+ *
+ * const update: PartialUser = {
+ *   settings: {
+ *     notifications: {
+ *       email: false
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export type RecursivePartial<T> = {
 	[P in keyof T]?: RecursivePartial<T[P]>
 }
 
-/** @public */
+/**
+ * Expands a type definition to show its full structure in IDE tooltips and error messages.
+ * This utility type forces TypeScript to resolve and display the complete type structure
+ * instead of showing complex conditional types or intersections as-is.
+ *
+ * @example
+ * ```ts
+ * type User = { name: string }
+ * type WithId = { id: string }
+ * type UserWithId = User & WithId
+ *
+ * // Without Expand, IDE shows: User & WithId
+ * // With Expand, IDE shows: { name: string; id: string }
+ * type ExpandedUserWithId = Expand<UserWithId>
+ *
+ * // Useful for complex intersections
+ * type ComplexType = Expand<BaseType & Mixin1 & Mixin2>
+ * ```
+ *
+ * @public
+ */
 export type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never
 
-/** @internal */
+/**
+ * Makes specified keys in a type required while keeping all other properties as-is.
+ * This is useful when you need to ensure certain optional properties are provided
+ * in specific contexts without affecting the entire type structure.
+ *
+ * @example
+ * ```ts
+ * interface Shape {
+ *   id: string
+ *   x?: number
+ *   y?: number
+ *   visible?: boolean
+ * }
+ *
+ * // Make position properties required
+ * type PositionedShape = Required<Shape, 'x' | 'y'>
+ * // Result: {
+ * //   id: string
+ * //   x: number      // now required
+ * //   y: number      // now required
+ * //   visible?: boolean
+ * // }
+ *
+ * const shape: PositionedShape = {
+ *   id: 'rect1',
+ *   x: 10,    // must provide
+ *   y: 20,    // must provide
+ *   // visible is still optional
+ * }
+ * ```
+ *
+ * @internal
+ */
 export type Required<T, K extends keyof T> = Expand<Omit<T, K> & { [P in K]-?: T[P] }>
 
-/** @public */
+/**
+ * Automatically makes properties optional if their type includes `undefined`.
+ * This transforms properties like `prop: string | undefined` to `prop?: string | undefined`,
+ * making the API more ergonomic by not requiring explicit undefined assignments.
+ *
+ * @example
+ * ```ts
+ * interface RawConfig {
+ *   name: string
+ *   theme: string | undefined
+ *   debug: boolean | undefined
+ *   version: number
+ * }
+ *
+ * type Config = MakeUndefinedOptional<RawConfig>
+ * // Result: {
+ * //   name: string
+ * //   theme?: string | undefined    // now optional
+ * //   debug?: boolean | undefined   // now optional
+ * //   version: number
+ * // }
+ *
+ * const config: Config = {
+ *   name: 'MyApp',
+ *   version: 1
+ *   // theme and debug can be omitted instead of explicitly set to undefined
+ * }
+ * ```
+ *
+ * @public
+ */
 export type MakeUndefinedOptional<T extends object> = Expand<
 	{
 		[P in { [K in keyof T]: undefined extends T[K] ? never : K }[keyof T]]: T[P]

package/src/lib/url.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+import { safeParseUrl } from './url'
+
+describe('safeParseUrl', () => {
+	it('returns URL object for valid absolute URLs', () => {
+		const result = safeParseUrl('https://example.com/path')
+
+		expect(result).toBeInstanceOf(URL)
+		expect(result?.href).toBe('https://example.com/path')
+	})
+
+	it('resolves relative URLs with base URL', () => {
+		const result = safeParseUrl('/path', 'https://example.com')
+
+		expect(result).toBeInstanceOf(URL)
+		expect(result?.href).toBe('https://example.com/path')
+	})
+
+	it('accepts URL object as base URL', () => {
+		const baseUrl = new URL('https://example.com')
+		const result = safeParseUrl('/path', baseUrl)
+
+		expect(result).toBeInstanceOf(URL)
+		expect(result?.href).toBe('https://example.com/path')
+	})
+
+	it('returns undefined for invalid URLs', () => {
+		expect(safeParseUrl('')).toBeUndefined()
+		expect(safeParseUrl('not-a-url')).toBeUndefined()
+		expect(safeParseUrl('https://exam ple.com')).toBeUndefined()
+	})
+
+	it('returns undefined when relative URL has no base', () => {
+		const result = safeParseUrl('/relative/path')
+
+		expect(result).toBeUndefined()
+	})
+
+	it('returns undefined when base URL is invalid', () => {
+		const result = safeParseUrl('/path', 'not-a-base-url')
+
+		expect(result).toBeUndefined()
+	})
+})

package/src/lib/url.ts

@@ -1,4 +1,43 @@
-/** @public */
+/**
+ * Safely parses a URL string without throwing exceptions on invalid input.
+ * Returns a URL object for valid URLs or undefined for invalid ones.
+ *
+ * @param url - The URL string to parse
+ * @param baseUrl - Optional base URL to resolve relative URLs against
+ * @returns A URL object if parsing succeeds, undefined if it fails
+ *
+ * @example
+ * ```ts
+ * // Valid absolute URL
+ * const url1 = safeParseUrl('https://example.com')
+ * if (url1) {
+ *   console.log(`Valid URL: ${url1.href}`) // "Valid URL: https://example.com/"
+ * }
+ *
+ * // Invalid URL
+ * const url2 = safeParseUrl('not-a-url')
+ * console.log(url2) // undefined
+ *
+ * // Relative URL with base
+ * const url3 = safeParseUrl('/path', 'https://example.com')
+ * if (url3) {
+ *   console.log(url3.href) // "https://example.com/path"
+ * }
+ *
+ * // Error handling
+ * function handleUserUrl(input: string) {
+ *   const url = safeParseUrl(input)
+ *   if (url) {
+ *     return url
+ *   } else {
+ *     console.log('Invalid URL provided')
+ *     return null
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export const safeParseUrl = (url: string, baseUrl?: string | URL) => {
 	try {
 		return new URL(url, baseUrl)

package/src/lib/value.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'vitest'
+import {
+	isNativeStructuredClone,
+	STRUCTURED_CLONE_OBJECT_PROTOTYPE,
+	structuredClone,
+} from './value'
+
+describe('value utilities', () => {
+	describe('structuredClone', () => {
+		it('should create deep copies of objects', () => {
+			const original = { a: 1, b: { c: 2 } }
+			const copy = structuredClone(original)
+
+			expect(copy).toEqual(original)
+			expect(copy).not.toBe(original)
+			expect(copy.b).not.toBe(original.b)
+
+			// Modifying copy should not affect original
+			copy.b.c = 3
+			expect(original.b.c).toBe(2)
+			expect(copy.b.c).toBe(3)
+		})
+
+		it('should handle primitive values', () => {
+			expect(structuredClone(42)).toBe(42)
+			expect(structuredClone('hello')).toBe('hello')
+			expect(structuredClone(true)).toBe(true)
+			expect(structuredClone(null)).toBe(null)
+			expect(structuredClone(undefined)).toBe(undefined)
+		})
+
+		it('should handle arrays', () => {
+			const original = [1, [2, 3], { a: 4 }]
+			const copy = structuredClone(original)
+
+			expect(copy).toEqual(original)
+			expect(copy).not.toBe(original)
+			expect(copy[1]).not.toBe(original[1])
+			expect(copy[2]).not.toBe(original[2])
+
+			// Modifying copy should not affect original
+			;(copy[1] as number[]).push(5)
+			;(copy[2] as any).a = 99
+
+			expect(original[1]).toEqual([2, 3])
+			expect((original[2] as any).a).toBe(4)
+		})
+
+		it('should handle nested structures', () => {
+			const original = {
+				level1: {
+					level2: {
+						level3: {
+							value: 'deep',
+						},
+					},
+				},
+			}
+
+			const copy = structuredClone(original)
+
+			expect(copy).toEqual(original)
+			expect(copy.level1).not.toBe(original.level1)
+			expect(copy.level1.level2).not.toBe(original.level1.level2)
+			expect(copy.level1.level2.level3).not.toBe(original.level1.level2.level3)
+
+			copy.level1.level2.level3.value = 'modified'
+			expect(original.level1.level2.level3.value).toBe('deep')
+		})
+
+		it('should handle dates', () => {
+			const date = new Date('2023-01-01')
+			const copy = structuredClone(date)
+
+			expect(copy).toEqual(date)
+			expect(copy).not.toBe(date)
+			expect(copy instanceof Date).toBe(true)
+		})
+
+		it('should handle circular references if native structuredClone is available', () => {
+			if (isNativeStructuredClone) {
+				const obj: any = { a: 1 }
+				obj.self = obj
+
+				const copy = structuredClone(obj)
+
+				expect(copy.a).toBe(1)
+				expect(copy.self).toBe(copy)
+				expect(copy).not.toBe(obj)
+			}
+		})
+	})
+
+	describe('STRUCTURED_CLONE_OBJECT_PROTOTYPE', () => {
+		it('should be the prototype of objects created by structuredClone', () => {
+			const obj = {}
+			const cloned = structuredClone(obj)
+
+			expect(Object.getPrototypeOf(cloned)).toBe(STRUCTURED_CLONE_OBJECT_PROTOTYPE)
+		})
+	})
+})

package/src/lib/value.ts

@@ -2,6 +2,20 @@
  * Get whether a value is not undefined.
  *
  * @param value - The value to check.
+ * @returns True if the value is not undefined, with proper type narrowing.
+ * @example
+ * ```ts
+ * const maybeString: string | undefined = getValue()
+ *
+ * if (isDefined(maybeString)) {
+ *   // TypeScript knows maybeString is string, not undefined
+ *   console.log(maybeString.toUpperCase())
+ * }
+ *
+ * // Filter undefined values from arrays
+ * const values = [1, undefined, 2, undefined, 3]
+ * const definedValues = values.filter(isDefined) // [1, 2, 3]
+ * ```
  * @public
  */
 export function isDefined<T>(value: T): value is typeof value extends undefined ? never : T {
@@ -9,9 +23,23 @@ export function isDefined<T>(value: T): value is typeof value extends undefined
 }
 
 /**
- * Get whether a value is null
+ * Get whether a value is not null.
  *
  * @param value - The value to check.
+ * @returns True if the value is not null, with proper type narrowing.
+ * @example
+ * ```ts
+ * const maybeString: string | null = getValue()
+ *
+ * if (isNonNull(maybeString)) {
+ *   // TypeScript knows maybeString is string, not null
+ *   console.log(maybeString.length)
+ * }
+ *
+ * // Filter null values from arrays
+ * const values = ["a", null, "b", null, "c"]
+ * const nonNullValues = values.filter(isNonNull) // ["a", "b", "c"]
+ * ```
  * @public
  */
 export function isNonNull<T>(value: T): value is typeof value extends null ? never : T {
@@ -19,9 +47,23 @@ export function isNonNull<T>(value: T): value is typeof value extends null ? nev
 }
 
 /**
- * Get whether a value is nullish (null, undefined).
+ * Get whether a value is not nullish (not null and not undefined).
  *
  * @param value - The value to check.
+ * @returns True if the value is neither null nor undefined, with proper type narrowing.
+ * @example
+ * ```ts
+ * const maybeString: string | null | undefined = getValue()
+ *
+ * if (isNonNullish(maybeString)) {
+ *   // TypeScript knows maybeString is string, not null or undefined
+ *   console.log(maybeString.charAt(0))
+ * }
+ *
+ * // Filter nullish values from arrays
+ * const values = ["hello", null, "world", undefined, "!"]
+ * const cleanValues = values.filter(isNonNullish) // ["hello", "world", "!"]
+ * ```
  * @public
  */
 export function isNonNullish<T>(
@@ -52,15 +94,37 @@ const _structuredClone = getStructuredClone()
  * Create a deep copy of a value. Uses the structuredClone API if available, otherwise uses JSON.parse(JSON.stringify()).
  *
  * @param i - The value to clone.
- * @public */
+ * @returns A deep copy of the input value.
+ * @example
+ * ```ts
+ * const original = { a: 1, b: { c: 2 } }
+ * const copy = structuredClone(original)
+ *
+ * copy.b.c = 3
+ * console.log(original.b.c) // 2 (unchanged)
+ * console.log(copy.b.c) // 3
+ *
+ * // Works with complex objects
+ * const complexObject = {
+ *   date: new Date(),
+ *   array: [1, 2, 3],
+ *   nested: { deep: { value: "test" } }
+ * }
+ * const cloned = structuredClone(complexObject)
+ * ```
+ * @public
+ */
 export const structuredClone = _structuredClone[0]
 
 /**
+ * Whether the current environment has native structuredClone support.
+ * @returns True if using native structuredClone, false if using JSON fallback.
  * @internal
  */
 export const isNativeStructuredClone = _structuredClone[1]
 
 /**
+ * The prototype object used by structuredClone for cloned objects.
  * When we patch structuredClone in jsdom for testing (see https://github.com/jsdom/jsdom/issues/3363),
  * the Object that is used as a prototype for the cloned object is not the same as the Object in
  * the code under test (that comes from jsdom's fake global context). This constant is used in