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

package/src/lib/control.ts

@@ -1,36 +1,160 @@
 import { omitFromStackTrace } from './function'
 
-/** @public */
+/**
+ * Represents a successful result containing a value.
+ *
+ * Interface for the success case of a Result type, containing the computed value.
+ * Used in conjunction with ErrorResult to create a discriminated union for error handling.
+ *
+ * @example
+ * ```ts
+ * const success: OkResult<string> = { ok: true, value: 'Hello World' }
+ * if (success.ok) {
+ *   console.log(success.value) // 'Hello World'
+ * }
+ * ```
+ * @public
+ */
 export interface OkResult<T> {
 	readonly ok: true
 	readonly value: T
 }
-/** @public */
+/**
+ * Represents a failed result containing an error.
+ *
+ * Interface for the error case of a Result type, containing the error information.
+ * Used in conjunction with OkResult to create a discriminated union for error handling.
+ *
+ * @example
+ * ```ts
+ * const failure: ErrorResult<string> = { ok: false, error: 'Something went wrong' }
+ * if (!failure.ok) {
+ *   console.error(failure.error) // 'Something went wrong'
+ * }
+ * ```
+ * @public
+ */
 export interface ErrorResult<E> {
 	readonly ok: false
 	readonly error: E
 }
-/** @public */
+/**
+ * A discriminated union type for handling success and error cases.
+ *
+ * Represents either a successful result with a value or a failed result with an error.
+ * This pattern provides type-safe error handling without throwing exceptions. The 'ok' property
+ * serves as the discriminant for type narrowing.
+ *
+ * @example
+ * ```ts
+ * function divide(a: number, b: number): Result<number, string> {
+ *   if (b === 0) {
+ *     return Result.err('Division by zero')
+ *   }
+ *   return Result.ok(a / b)
+ * }
+ *
+ * const result = divide(10, 2)
+ * if (result.ok) {
+ *   console.log(`Result: ${result.value}`) // Result: 5
+ * } else {
+ *   console.error(`Error: ${result.error}`)
+ * }
+ * ```
+ * @public
+ */
 export type Result<T, E> = OkResult<T> | ErrorResult<E>
 
-/** @public */
+/**
+ * Utility object for creating Result instances.
+ *
+ * Provides factory methods for creating OkResult and ErrorResult instances.
+ * This is the preferred way to construct Result values for consistent structure.
+ *
+ * @example
+ * ```ts
+ * // Create success result
+ * const success = Result.ok(42)
+ * // success: OkResult<number> = { ok: true, value: 42 }
+ *
+ * // Create error result
+ * const failure = Result.err('Invalid input')
+ * // failure: ErrorResult<string> = { ok: false, error: 'Invalid input' }
+ * ```
+ * @public
+ */
 export const Result = {
+	/**
+	 * Create a successful result containing a value.
+	 *
+	 * @param value - The success value to wrap
+	 * @returns An OkResult containing the value
+	 */
 	ok<T>(value: T): OkResult<T> {
 		return { ok: true, value }
 	},
+	/**
+	 * Create a failed result containing an error.
+	 *
+	 * @param error - The error value to wrap
+	 * @returns An ErrorResult containing the error
+	 */
 	err<E>(error: E): ErrorResult<E> {
 		return { ok: false, error }
 	},
 }
 
-/** @internal */
+/**
+ * Throws an error for unhandled switch cases in exhaustive switch statements.
+ *
+ * Utility function to ensure exhaustive handling of discriminated unions in switch
+ * statements. When called, it indicates a programming error where a case was not handled.
+ * The TypeScript 'never' type ensures this function is only reachable if all cases aren't covered.
+ *
+ * @param value - The unhandled value (typed as 'never' for exhaustiveness checking)
+ * @param property - Optional property name to extract from the value for better error messages
+ * @returns Never returns (always throws)
+ *
+ * @example
+ * ```ts
+ * type Shape = 'circle' | 'square' | 'triangle'
+ *
+ * function getArea(shape: Shape): number {
+ *   switch (shape) {
+ *     case 'circle': return Math.PI * 5 * 5
+ *     case 'square': return 10 * 10
+ *     case 'triangle': return 0.5 * 10 * 8
+ *     default: return exhaustiveSwitchError(shape)
+ *   }
+ * }
+ * ```
+ * @internal
+ */
 export function exhaustiveSwitchError(value: never, property?: string): never {
 	const debugValue =
 		property && value && typeof value === 'object' && property in value ? value[property] : value
 	throw new Error(`Unknown switch case ${debugValue}`)
 }
 
-/** @internal */
+/**
+ * Assert that a value is truthy, throwing an error if it's not.
+ *
+ * TypeScript assertion function that throws an error if the provided value is falsy.
+ * After this function executes successfully, TypeScript narrows the type to exclude falsy values.
+ * Stack trace is omitted from the error for cleaner debugging.
+ *
+ * @param value - The value to assert as truthy
+ * @param message - Optional custom error message
+ *
+ * @example
+ * ```ts
+ * const user = getUser() // User | null
+ * assert(user, 'User must be logged in')
+ * // TypeScript now knows user is non-null
+ * console.log(user.name) // Safe to access properties
+ * ```
+ * @internal
+ */
 export const assert: (value: unknown, message?: string) => asserts value = omitFromStackTrace(
 	(value, message) => {
 		if (!value) {
@@ -39,7 +163,25 @@ export const assert: (value: unknown, message?: string) => asserts value = omitF
 	}
 )
 
-/** @internal */
+/**
+ * Assert that a value is not null or undefined.
+ *
+ * Throws an error if the value is null or undefined, otherwise returns the value
+ * with a refined type that excludes null and undefined. Stack trace is omitted for cleaner debugging.
+ *
+ * @param value - The value to check for null/undefined
+ * @param message - Optional custom error message
+ * @returns The value with null and undefined excluded from the type
+ *
+ * @example
+ * ```ts
+ * const element = document.getElementById('my-id') // HTMLElement | null
+ * const safeElement = assertExists(element, 'Element not found')
+ * // TypeScript now knows safeElement is HTMLElement (not null)
+ * safeElement.addEventListener('click', handler) // Safe to call methods
+ * ```
+ * @internal
+ */
 export const assertExists = omitFromStackTrace(<T>(value: T, message?: string): NonNullable<T> => {
 	// note that value == null is equivalent to value === null || value === undefined
 	if (value == null) {
@@ -48,7 +190,30 @@ export const assertExists = omitFromStackTrace(<T>(value: T, message?: string):
 	return value as NonNullable<T>
 })
 
-/** @internal */
+/**
+ * Create a Promise with externally accessible resolve and reject functions.
+ *
+ * Creates a Promise along with its resolve and reject functions exposed as
+ * properties on the returned object. This allows external code to control when the
+ * Promise resolves or rejects, useful for coordination between async operations.
+ *
+ * @returns A Promise object with additional resolve and reject methods
+ *
+ * @example
+ * ```ts
+ * const deferred = promiseWithResolve<string>()
+ *
+ * // Set up the promise consumer
+ * deferred.then(value => console.log(`Resolved: ${value}`))
+ * deferred.catch(error => console.error(`Rejected: ${error}`))
+ *
+ * // Later, resolve from external code
+ * setTimeout(() => {
+ *   deferred.resolve('Hello World')
+ * }, 1000)
+ * ```
+ * @internal
+ */
 export function promiseWithResolve<T>(): Promise<T> & {
 	resolve(value: T): void
 	reject(reason?: any): void
@@ -65,7 +230,31 @@ export function promiseWithResolve<T>(): Promise<T> & {
 	})
 }
 
-/** @internal */
+/**
+ * Create a Promise that resolves after a specified delay.
+ *
+ * Utility function for introducing delays in async code. Returns a Promise
+ * that resolves with undefined after the specified number of milliseconds. Useful for
+ * implementing timeouts, rate limiting, or adding delays in testing scenarios.
+ *
+ * @param ms - The delay in milliseconds
+ * @returns A Promise that resolves after the specified delay
+ *
+ * @example
+ * ```ts
+ * async function delayedOperation() {
+ *   console.log('Starting...')
+ *   await sleep(1000) // Wait 1 second
+ *   console.log('Done!')
+ * }
+ *
+ * // Can also be used with .then()
+ * sleep(500).then(() => {
+ *   console.log('Half second has passed')
+ * })
+ * ```
+ * @internal
+ */
 export function sleep(ms: number): Promise<void> {
 	// eslint-disable-next-line no-restricted-globals
 	return new Promise((resolve) => setTimeout(resolve, ms))

package/src/lib/debounce.ts

@@ -1,10 +1,35 @@
 /**
- * Debounce a function.
+ * Create a debounced version of a function that delays execution until after a specified wait time.
  *
- * @example
+ * Debouncing ensures that a function is only executed once after a specified delay,
+ * even if called multiple times in rapid succession. Each new call resets the timer. The debounced
+ * function returns a Promise that resolves with the result of the original function. Includes a
+ * cancel method to prevent execution if needed.
+ *
+ * @param callback - The function to debounce (can be sync or async)
+ * @param wait - The delay in milliseconds before executing the function
+ * @returns A debounced function that returns a Promise and includes a cancel method
  *
+ * @example
  * ```ts
- * const A = debounce(myFunction, 1000)
+ * // Debounce a search function
+ * const searchAPI = (query: string) => fetch(`/search?q=${query}`)
+ * const debouncedSearch = debounce(searchAPI, 300)
+ *
+ * // Multiple rapid calls will only execute the last one after 300ms
+ * debouncedSearch('react').then(result => console.log(result))
+ * debouncedSearch('react hooks') // This cancels the previous call
+ * debouncedSearch('react typescript') // Only this will execute
+ *
+ * // Cancel pending execution
+ * debouncedSearch.cancel()
+ *
+ * // With async/await
+ * const saveData = debounce(async (data: any) => {
+ *   return await api.save(data)
+ * }, 1000)
+ *
+ * const result = await saveData({name: 'John'})
  * ```
  *
  * @public

package/src/lib/error.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+import { annotateError, getErrorAnnotations } from './error'
+
+describe('annotateError', () => {
+	it('should annotate an Error object with tags and extras', () => {
+		const error = new Error('test error')
+		annotateError(error, {
+			tags: { userId: '123', operation: 'save' },
+			extras: { timestamp: 1234567890, data: { key: 'value' } },
+		})
+
+		const annotations = getErrorAnnotations(error)
+		expect(annotations.tags.userId).toBe('123')
+		expect(annotations.tags.operation).toBe('save')
+		expect(annotations.extras.timestamp).toBe(1234567890)
+		expect(annotations.extras.data).toEqual({ key: 'value' })
+	})
+
+	it('should merge annotations from multiple calls', () => {
+		const error = new Error('test error')
+
+		annotateError(error, {
+			tags: { userId: '123', operation: 'save' },
+			extras: { timestamp: 1234567890 },
+		})
+
+		annotateError(error, {
+			tags: { userId: '456', component: 'auth' }, // userId should be overwritten
+			extras: { requestId: 'req456' },
+		})
+
+		const annotations = getErrorAnnotations(error)
+		expect(annotations.tags).toEqual({
+			userId: '456', // overwritten
+			operation: 'save', // preserved
+			component: 'auth', // new
+		})
+		expect(annotations.extras).toEqual({
+			timestamp: 1234567890, // preserved
+			requestId: 'req456', // new
+		})
+	})
+
+	it('should handle non-object inputs gracefully', () => {
+		expect(() => annotateError(null, { tags: { test: 'value' } })).not.toThrow()
+		expect(() => annotateError('string error', { tags: { test: 'value' } })).not.toThrow()
+	})
+})
+
+describe('getErrorAnnotations', () => {
+	it('should return empty annotations for unannotated errors', () => {
+		const error = new Error('test error')
+		const annotations = getErrorAnnotations(error)
+
+		expect(annotations).toEqual({
+			tags: {},
+			extras: {},
+		})
+	})
+})

package/src/lib/error.ts

@@ -10,6 +10,18 @@ const annotationsByError = new WeakMap<object, ErrorAnnotations>()
  * Annotate an error with tags and additional data. Annotations won't overwrite existing ones.
  * Retrieve them with `getErrorAnnotations`.
  *
+ * @param error - The error object to annotate
+ * @param annotations - Partial annotations to add (tags and/or extras)
+ * @returns void
+ * @example
+ * ```ts
+ * const error = new Error('Something went wrong')
+ * annotateError(error, {
+ *   tags: { userId: '123', operation: 'save' },
+ *   extras: { timestamp: Date.now() }
+ * })
+ * ```
+ *
  * @internal
  */
 export function annotateError(error: unknown, annotations: Partial<ErrorAnnotations>) {
@@ -35,7 +47,21 @@ export function annotateError(error: unknown, annotations: Partial<ErrorAnnotati
 	}
 }
 
-/** @internal */
+/**
+ * Retrieve annotations that have been added to an error object.
+ *
+ * @param error - The error object to get annotations from
+ * @returns The error annotations (tags and extras) or empty objects if none exist
+ * @example
+ * ```ts
+ * const error = new Error('Something went wrong')
+ * annotateError(error, { tags: { userId: '123' } })
+ * const annotations = getErrorAnnotations(error)
+ * console.log(annotations.tags.userId) // '123'
+ * ```
+ *
+ * @internal
+ */
 export function getErrorAnnotations(error: Error): ErrorAnnotations {
 	return annotationsByError.get(error) ?? { tags: {}, extras: {} }
 }

package/src/lib/file.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest'
+import { FileHelpers } from './file'
+
+describe('FileHelpers', () => {
+	describe('urlToDataUrl', () => {
+		it('should return data URL unchanged if already a data URL', async () => {
+			const dataUrl = 'data:text/plain;base64,SGVsbG8gV29ybGQ='
+			const result = await FileHelpers.urlToDataUrl(dataUrl)
+
+			expect(result).toBe(dataUrl)
+		})
+	})
+
+	describe('rewriteMimeType', () => {
+		it('should return the same blob if MIME type matches', () => {
+			const blob = new Blob(['content'], { type: 'text/plain' })
+			const result = FileHelpers.rewriteMimeType(blob, 'text/plain')
+
+			expect(result).toBe(blob)
+		})
+
+		it('should create new blob with different MIME type', () => {
+			const blob = new Blob(['content'], { type: 'text/plain' })
+			const result = FileHelpers.rewriteMimeType(blob, 'application/json')
+
+			expect(result).not.toBe(blob)
+			expect(result.type).toBe('application/json')
+			expect(result.size).toBe(blob.size)
+		})
+
+		it('should return the same file if MIME type matches', () => {
+			const file = new File(['content'], 'test.txt', { type: 'text/plain' })
+			const result = FileHelpers.rewriteMimeType(file, 'text/plain')
+
+			expect(result).toBe(file)
+		})
+
+		it('should create new file with different MIME type and preserve name', () => {
+			const file = new File(['content'], 'test.txt', { type: 'text/plain' })
+			const result = FileHelpers.rewriteMimeType(file, 'application/json') as File
+
+			expect(result).not.toBe(file)
+			expect(result.type).toBe('application/json')
+			expect(result.name).toBe('test.txt')
+			expect(result.size).toBe(file.size)
+			expect(result).toBeInstanceOf(File)
+		})
+	})
+})

package/src/lib/file.ts

@@ -1,24 +1,87 @@
 import { fetch } from './network'
 
 /**
- * Helpers for files
+ * Utility class providing helper methods for file and blob operations.
+ *
+ * FileHelpers contains static methods for common file operations including
+ * URL fetching, format conversion, and MIME type manipulation. All methods work with
+ * web APIs like fetch, FileReader, and Blob/File objects.
+ *
+ * @example
+ * ```ts
+ * // Fetch and convert a remote image to data URL
+ * const dataUrl = await FileHelpers.urlToDataUrl('https://example.com/image.png')
+ *
+ * // Convert user-selected file to text
+ * const text = await FileHelpers.blobToText(userFile)
+ *
+ * // Change file MIME type
+ * const newFile = FileHelpers.rewriteMimeType(originalFile, 'application/json')
+ * ```
  *
  * @public
  */
 export class FileHelpers {
 	/**
-	 * @param url - The url of the file.
+	 * Converts a URL to an ArrayBuffer by fetching the resource.
+	 *
+	 * Fetches the resource at the given URL and returns its content as an ArrayBuffer.
+	 * This is useful for loading binary data like images, videos, or other file types.
+	 *
+	 * @param url - The URL of the file to fetch
+	 * @returns Promise that resolves to the file content as an ArrayBuffer
+	 * @example
+	 * ```ts
+	 * const buffer = await FileHelpers.urlToArrayBuffer('https://example.com/image.png')
+	 * console.log(buffer.byteLength) // Size of the file in bytes
+	 * ```
+	 * @public
 	 */
 	static async urlToArrayBuffer(url: string) {
 		const response = await fetch(url)
 		return await response.arrayBuffer()
 	}
 
+	/**
+	 * Converts a URL to a Blob by fetching the resource.
+	 *
+	 * Fetches the resource at the given URL and returns its content as a Blob object.
+	 * Blobs are useful for handling file data in web applications.
+	 *
+	 * @param url - The URL of the file to fetch
+	 * @returns Promise that resolves to the file content as a Blob
+	 * @example
+	 * ```ts
+	 * const blob = await FileHelpers.urlToBlob('https://example.com/document.pdf')
+	 * console.log(blob.type) // 'application/pdf'
+	 * console.log(blob.size) // Size in bytes
+	 * ```
+	 * @public
+	 */
 	static async urlToBlob(url: string) {
 		const response = await fetch(url)
 		return await response.blob()
 	}
 
+	/**
+	 * Converts a URL to a data URL by fetching the resource.
+	 *
+	 * Fetches the resource at the given URL and converts it to a base64-encoded data URL.
+	 * If the URL is already a data URL, it returns the URL unchanged. This is useful for embedding
+	 * resources directly in HTML or CSS.
+	 *
+	 * @param url - The URL of the file to convert, or an existing data URL
+	 * @returns Promise that resolves to a data URL string
+	 * @example
+	 * ```ts
+	 * const dataUrl = await FileHelpers.urlToDataUrl('https://example.com/image.jpg')
+	 * // Returns: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA...'
+	 *
+	 * const existing = await FileHelpers.urlToDataUrl('data:text/plain;base64,SGVsbG8=')
+	 * // Returns the same data URL unchanged
+	 * ```
+	 * @public
+	 */
 	static async urlToDataUrl(url: string) {
 		if (url.startsWith('data:')) return url
 		const blob = await FileHelpers.urlToBlob(url)
@@ -26,15 +89,24 @@ export class FileHelpers {
 	}
 
 	/**
-	 * Convert a file to a base64 encoded data url.
+	 * Convert a Blob to a base64 encoded data URL.
 	 *
-	 * @example
+	 * Converts a Blob object to a base64-encoded data URL using the FileReader API.
+	 * This is useful for displaying images or embedding file content directly in HTML.
 	 *
+	 * @param file - The Blob object to convert
+	 * @returns Promise that resolves to a base64-encoded data URL string
+	 * @example
 	 * ```ts
-	 * const A = FileHelpers.toDataUrl(myImageFile)
-	 * ```
+	 * const blob = new Blob(['Hello World'], { type: 'text/plain' })
+	 * const dataUrl = await FileHelpers.blobToDataUrl(blob)
+	 * // Returns: 'data:text/plain;base64,SGVsbG8gV29ybGQ='
 	 *
-	 * @param file - The file as a blob.
+	 * // With an image file
+	 * const imageDataUrl = await FileHelpers.blobToDataUrl(myImageFile)
+	 * // Can be used directly in img src attribute
+	 * ```
+	 * @public
 	 */
 	static async blobToDataUrl(file: Blob): Promise<string> {
 		return await new Promise((resolve, reject) => {
@@ -49,15 +121,24 @@ export class FileHelpers {
 	}
 
 	/**
-	 * Convert a file to a unicode text string.
+	 * Convert a Blob to a unicode text string.
 	 *
-	 * @example
+	 * Reads the content of a Blob object as a UTF-8 text string using the FileReader API.
+	 * This is useful for reading text files or extracting text content from blobs.
 	 *
+	 * @param file - The Blob object to convert to text
+	 * @returns Promise that resolves to the text content as a string
+	 * @example
 	 * ```ts
-	 * const A = FileHelpers.fileToDataUrl(myTextFile)
-	 * ```
+	 * const textBlob = new Blob(['Hello World'], { type: 'text/plain' })
+	 * const text = await FileHelpers.blobToText(textBlob)
+	 * console.log(text) // 'Hello World'
 	 *
-	 * @param file - The file as a blob.
+	 * // With a text file from user input
+	 * const content = await FileHelpers.blobToText(myTextFile)
+	 * console.log(content) // File content as string
+	 * ```
+	 * @public
 	 */
 	static async blobToText(file: Blob): Promise<string> {
 		return await new Promise((resolve, reject) => {
@@ -71,6 +152,30 @@ export class FileHelpers {
 		})
 	}
 
+	/**
+	 * Creates a new Blob or File with a different MIME type.
+	 *
+	 * Creates a copy of the given Blob or File with a new MIME type while preserving
+	 * all other properties. If the current MIME type already matches the new one, returns the
+	 * original object unchanged. For File objects, preserves the filename.
+	 *
+	 * @param blob - The Blob or File object to modify
+	 * @param newMimeType - The new MIME type to assign
+	 * @returns A new Blob or File with the updated MIME type
+	 * @example
+	 * ```ts
+	 * // Change a generic blob to a specific image type
+	 * const blob = new Blob([imageData])
+	 * const imageBlob = FileHelpers.rewriteMimeType(blob, 'image/png')
+	 *
+	 * // Change a file's MIME type while preserving filename
+	 * const file = new File([data], 'document.txt', { type: 'text/plain' })
+	 * const jsonFile = FileHelpers.rewriteMimeType(file, 'application/json')
+	 * console.log(jsonFile.name) // 'document.txt' (preserved)
+	 * console.log(jsonFile.type) // 'application/json' (updated)
+	 * ```
+	 * @public
+	 */
 	static rewriteMimeType(blob: Blob, newMimeType: string): Blob
 	static rewriteMimeType(blob: File, newMimeType: string): File
 	static rewriteMimeType(blob: Blob | File, newMimeType: string): Blob | File {

package/src/lib/function.ts

@@ -6,6 +6,17 @@
  *
  * Only works in platforms that support `Error.captureStackTrace` (ie v8).
  *
+ * @param fn - The function to wrap and exclude from stack traces
+ * @returns A wrapped version of the function that omits itself from error stack traces
+ * @example
+ * ```ts
+ * const assertPositive = omitFromStackTrace((value: number) => {
+ *   if (value <= 0) throw new Error('Value must be positive')
+ *   return value
+ * })
+ *
+ * assertPositive(-1) // Error stack trace will point to this line, not inside assertPositive
+ * ```
  * @internal
  */
 export function omitFromStackTrace<Args extends Array<unknown>, Return>(