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

package/src/lib/media/webp.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest'
+import { isWebpAnimated } from './webp'
+
+// Helper function to create a buffer with WebP signature
+function createWebpBuffer(size: number, animated = false): ArrayBuffer {
+	const buffer = new ArrayBuffer(Math.max(size, 21))
+	const view = new Uint8Array(buffer)
+
+	// Set RIFF signature (bytes 0-3: 'RIFF')
+	view[0] = 0x52 // R
+	view[1] = 0x49 // I
+	view[2] = 0x46 // F
+	view[3] = 0x46 // F
+
+	// Set file size (bytes 4-7) - little endian
+	const fileSize = size - 8
+	view[4] = fileSize & 0xff
+	view[5] = (fileSize >> 8) & 0xff
+	view[6] = (fileSize >> 16) & 0xff
+	view[7] = (fileSize >> 24) & 0xff
+
+	// Set WebP signature (bytes 8-11: 'WEBP')
+	view[8] = 87 // W
+	view[9] = 69 // E
+	view[10] = 66 // B
+	view[11] = 80 // P
+
+	// Set VP8X chunk header for extended format (bytes 12-19)
+	view[12] = 86 // V
+	view[13] = 80 // P
+	view[14] = 56 // 8
+	view[15] = 88 // X
+
+	// Set VP8X chunk size (bytes 16-19) - 10 bytes
+	view[16] = 10
+	view[17] = 0
+	view[18] = 0
+	view[19] = 0
+
+	// Set VP8X flags (byte 20) - bit 1 is animation flag
+	if (animated) {
+		view[20] = 0b00000010 // Animation flag set
+	} else {
+		view[20] = 0b00000000 // No animation flag
+	}
+
+	return buffer
+}
+
+describe('isWebpAnimated', () => {
+	it('should return false for non-WebP data', () => {
+		const buffer = new ArrayBuffer(25)
+		const view = new Uint8Array(buffer)
+		view[8] = 80 // Not WebP signature
+		view[9] = 78
+		view[10] = 71
+		view[11] = 0
+
+		expect(isWebpAnimated(buffer)).toBe(false)
+	})
+
+	it('should return false for buffer too small for animation check', () => {
+		const buffer = new ArrayBuffer(10)
+		expect(isWebpAnimated(buffer)).toBe(false)
+	})
+
+	it('should return false for static WebP', () => {
+		const buffer = createWebpBuffer(100, false)
+		expect(isWebpAnimated(buffer)).toBe(false)
+	})
+
+	it('should return true for animated WebP', () => {
+		const buffer = createWebpBuffer(100, true)
+		expect(isWebpAnimated(buffer)).toBe(true)
+	})
+
+	it('should return false for empty buffer', () => {
+		const buffer = new ArrayBuffer(0)
+		expect(isWebpAnimated(buffer)).toBe(false)
+	})
+})

package/src/lib/media/webp.ts

@@ -2,7 +2,24 @@
  * MIT License: https://github.com/sindresorhus/is-webp/blob/main/license
  * Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
  */
-function isWebp(view: Uint8Array) {
+
+/**
+ * Determines whether a byte array represents a WebP image by checking the WebP file signature.
+ *
+ * @param view - The Uint8Array containing the potential WebP image data
+ * @returns True if the byte array is a valid WebP image, false otherwise
+ * @example
+ * ```ts
+ * // Check if file data is WebP format
+ * const file = new File([...], 'image.webp', { type: 'image/webp' })
+ * const buffer = await file.arrayBuffer()
+ * const view = new Uint8Array(buffer)
+ * const isWebPImage = isWebp(view)
+ * console.log(isWebPImage ? 'Valid WebP' : 'Not WebP')
+ * ```
+ * @internal
+ */
+export function isWebp(view: Uint8Array) {
 	if (!view || view.length < 12) {
 		return false
 	}
@@ -10,6 +27,21 @@ function isWebp(view: Uint8Array) {
 	return view[8] === 87 && view[9] === 69 && view[10] === 66 && view[11] === 80
 }
 
+/**
+ * Determines whether a WebP image file contains animation data by checking the animation flag in the WebP VP8X chunk.
+ *
+ * @param buffer - The ArrayBuffer containing the WebP image data
+ * @returns True if the WebP image is animated, false otherwise
+ * @example
+ * ```ts
+ * // Check if a WebP file from user input is animated
+ * const file = new File([...], 'image.webp', { type: 'image/webp' })
+ * const buffer = await file.arrayBuffer()
+ * const animated = isWebpAnimated(buffer)
+ * console.log(animated ? 'Animated WebP' : 'Static WebP')
+ * ```
+ * @public
+ */
 export function isWebpAnimated(buffer: ArrayBuffer) {
 	const view = new Uint8Array(buffer)
 

package/src/lib/network.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from 'vitest'
+import { fetch, Image } from './network'
+
+describe('fetch', () => {
+	it('should call window.fetch with referrerPolicy set to strict-origin-when-cross-origin', async () => {
+		const mockFetch = vi.spyOn(window, 'fetch').mockResolvedValue(new Response('test'))
+
+		await fetch('https://example.com')
+
+		expect(mockFetch).toHaveBeenCalledWith('https://example.com', {
+			referrerPolicy: 'strict-origin-when-cross-origin',
+		})
+		mockFetch.mockRestore()
+	})
+
+	it('should override referrerPolicy if provided in init options', async () => {
+		const mockFetch = vi.spyOn(window, 'fetch').mockResolvedValue(new Response('test'))
+
+		const initOptions: RequestInit = {
+			referrerPolicy: 'no-referrer',
+		}
+
+		await fetch('https://example.com', initOptions)
+
+		expect(mockFetch).toHaveBeenCalledWith('https://example.com', {
+			referrerPolicy: 'no-referrer',
+		})
+		mockFetch.mockRestore()
+	})
+})
+
+describe('Image', () => {
+	it('should create an image with referrerPolicy set to strict-origin-when-cross-origin', () => {
+		const img = Image()
+
+		expect(img.referrerPolicy).toBe('strict-origin-when-cross-origin')
+	})
+})

package/src/lib/network.ts

@@ -1,6 +1,9 @@
 /**
  * Just a wrapper around `window.fetch` that sets the `referrerPolicy` to `strict-origin-when-cross-origin`.
  *
+ * @param input - A Request object or string containing the URL to fetch
+ * @param init - Optional request initialization options
+ * @returns Promise that resolves to the Response object
  * @internal
  */
 export async function fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
@@ -16,6 +19,9 @@ export async function fetch(input: RequestInfo | URL, init?: RequestInit): Promi
  * Just a wrapper around `new Image`, and yeah, it's a bit strange that it's in the network.ts file
  * but the main concern here is the referrerPolicy and setting it correctly.
  *
+ * @param width - Optional width for the image element
+ * @param height - Optional height for the image element
+ * @returns HTMLImageElement with referrerPolicy set to 'strict-origin-when-cross-origin'
  * @internal
  */
 export const Image = (width?: number, height?: number) => {

package/src/lib/number.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'vitest'
+import { invLerp, lerp, modulate, rng } from './number'
+
+describe('lerp', () => {
+	test('should interpolate between two values correctly', () => {
+		expect(lerp(0, 100, 0.5)).toBe(50)
+		expect(lerp(10, 20, 0.25)).toBe(12.5)
+		expect(lerp(-10, -5, 0.5)).toBe(-7.5)
+	})
+
+	test('should extrapolate when t is outside 0-1 range', () => {
+		expect(lerp(0, 10, 1.5)).toBe(15)
+		expect(lerp(0, 10, -0.5)).toBe(-5)
+	})
+})
+
+describe('invLerp', () => {
+	test('should find normalized position correctly', () => {
+		expect(invLerp(0, 100, 25)).toBe(0.25)
+		expect(invLerp(10, 20, 15)).toBe(0.5)
+		expect(invLerp(-10, -5, -7.5)).toBe(0.5)
+	})
+
+	test('should handle values outside the range', () => {
+		expect(invLerp(0, 10, 15)).toBe(1.5)
+		expect(invLerp(0, 10, -5)).toBe(-0.5)
+	})
+})
+
+describe('rng', () => {
+	test('should generate deterministic results for same seed', () => {
+		const random1 = rng('same-seed')
+		const random2 = rng('same-seed')
+
+		const values1 = [random1(), random1(), random1()]
+		const values2 = [random2(), random2(), random2()]
+
+		expect(values1).toEqual(values2)
+	})
+
+	test('should generate different results for different seeds', () => {
+		const random1 = rng('seed-1')
+		const random2 = rng('seed-2')
+
+		const values1 = [random1(), random1(), random1()]
+		const values2 = [random2(), random2(), random2()]
+
+		expect(values1).not.toEqual(values2)
+	})
+})
+
+describe('modulate', () => {
+	test('should map value between ranges correctly', () => {
+		expect(modulate(0, [0, 1], [0, 100])).toBe(0)
+		expect(modulate(0.5, [0, 1], [0, 100])).toBe(50)
+		expect(modulate(1, [0, 1], [0, 100])).toBe(100)
+		expect(modulate(30, [10, 50], [100, 200])).toBe(150)
+	})
+
+	test('should extrapolate without clamping by default', () => {
+		expect(modulate(2, [0, 1], [0, 100])).toBe(200)
+		expect(modulate(-1, [0, 1], [0, 100])).toBe(-100)
+	})
+
+	test('should clamp results when clamp is true', () => {
+		expect(modulate(2, [0, 1], [0, 100], true)).toBe(100)
+		expect(modulate(-1, [0, 1], [0, 100], true)).toBe(0)
+	})
+
+	test('should handle clamping with reversed target range', () => {
+		expect(modulate(2, [0, 1], [100, 0], true)).toBe(0)
+		expect(modulate(-1, [0, 1], [100, 0], true)).toBe(100)
+	})
+})

package/src/lib/number.ts

@@ -1,12 +1,15 @@
 /**
  * Linear interpolate between two values.
  *
+ * @param a - The start value
+ * @param b - The end value
+ * @param t - The interpolation factor (0-1)
+ * @returns The interpolated value
  * @example
- *
  * ```ts
- * const A = lerp(0, 1, 0.5)
+ * const halfway = lerp(0, 100, 0.5) // 50
+ * const quarter = lerp(10, 20, 0.25) // 12.5
  * ```
- *
  * @public
  */
 export function lerp(a: number, b: number, t: number) {
@@ -14,9 +17,18 @@ export function lerp(a: number, b: number, t: number) {
 }
 
 /**
- * Inverse lerp between two values. Given a value `n` in the range [a, b], returns a number between
+ * Inverse lerp between two values. Given a value `t` in the range [a, b], returns a number between
  * 0 and 1.
  *
+ * @param a - The start value of the range
+ * @param b - The end value of the range
+ * @param t - The value within the range [a, b]
+ * @returns The normalized position (0-1) of t within the range [a, b]
+ * @example
+ * ```ts
+ * const position = invLerp(0, 100, 25) // 0.25
+ * const normalized = invLerp(10, 20, 15) // 0.5
+ * ```
  * @public
  */
 export function invLerp(a: number, b: number, t: number) {
@@ -25,10 +37,22 @@ export function invLerp(a: number, b: number, t: number) {
 
 /**
  * Seeded random number generator, using [xorshift](https://en.wikipedia.org/wiki/Xorshift). The
- * result will always be betweeen -1 and 1.
+ * result will always be between -1 and 1.
  *
  * Adapted from [seedrandom](https://github.com/davidbau/seedrandom).
  *
+ * @param seed - The seed string for deterministic random generation (defaults to empty string)
+ * @returns A function that will return a random number between -1 and 1 each time it is called
+ * @example
+ * ```ts
+ * const random = rng('my-seed')
+ * const num1 = random() // Always the same for this seed
+ * const num2 = random() // Next number in sequence
+ *
+ * // Different seed produces different sequence
+ * const otherRandom = rng('other-seed')
+ * const different = otherRandom() // Different value
+ * ```
  * @public
  */
 export function rng(seed = '') {

package/src/lib/object.test.ts

@@ -0,0 +1,236 @@
+import { describe, expect, it } from 'vitest'
+import {
+	areObjectsShallowEqual,
+	filterEntries,
+	getChangedKeys,
+	groupBy,
+	hasOwnProperty,
+	isEqualAllowingForFloatingPointErrors,
+	mapObjectMapValues,
+	objectMapEntries,
+	objectMapEntriesIterable,
+	objectMapFromEntries,
+	objectMapKeys,
+	objectMapValues,
+	omit,
+} from './object'
+
+describe('hasOwnProperty', () => {
+	it('should work with objects that override hasOwnProperty', () => {
+		const obj = {
+			name: 'Alice',
+			hasOwnProperty: () => false,
+		}
+		expect(hasOwnProperty(obj, 'name')).toBe(true)
+	})
+})
+
+describe('objectMapKeys', () => {
+	it('should return typed keys preserving order', () => {
+		const obj = { z: 1, a: 2, m: 3 }
+		const keys = objectMapKeys(obj)
+		expect(keys).toEqual(['z', 'a', 'm'])
+	})
+})
+
+describe('objectMapValues', () => {
+	it('should return typed values preserving order', () => {
+		const obj = { first: 'a', second: 'b', third: 'c' }
+		const values = objectMapValues(obj)
+		expect(values).toEqual(['a', 'b', 'c'])
+	})
+})
+
+describe('objectMapEntries', () => {
+	it('should return typed entries preserving order', () => {
+		const obj = { z: 1, a: 2 }
+		const entries = objectMapEntries(obj)
+		expect(entries).toEqual([
+			['z', 1],
+			['a', 2],
+		])
+	})
+})
+
+describe('objectMapEntriesIterable', () => {
+	it('should skip inherited properties and work as iterator', () => {
+		const parent = { inherited: 'value' }
+		const child = Object.create(parent)
+		child.own = 'ownValue'
+
+		const entries = Array.from(objectMapEntriesIterable(child))
+		expect(entries).toEqual([['own', 'ownValue']])
+	})
+
+	it('should work in for...of loops', () => {
+		const obj = { x: 10, y: 20 }
+		const collected: Array<[string, number]> = []
+
+		for (const [key, value] of objectMapEntriesIterable(obj)) {
+			collected.push([key, value])
+		}
+
+		expect(collected).toEqual([
+			['x', 10],
+			['y', 20],
+		])
+	})
+})
+
+describe('objectMapFromEntries', () => {
+	it('should create typed object from entries', () => {
+		const entries: Array<['name' | 'age', string | number]> = [
+			['name', 'Alice'],
+			['age', 30],
+		]
+		const obj = objectMapFromEntries(entries)
+		expect(obj).toEqual({ name: 'Alice', age: 30 })
+	})
+
+	it('should handle duplicate keys (last wins)', () => {
+		const entries: Array<['key', string]> = [
+			['key', 'first'],
+			['key', 'second'],
+		]
+		const obj = objectMapFromEntries(entries)
+		expect(obj).toEqual({ key: 'second' })
+	})
+})
+
+describe('filterEntries', () => {
+	it('should filter entries and optimize unchanged objects', () => {
+		const scores = { alice: 85, bob: 92, charlie: 78 }
+		const passing = filterEntries(scores, (name, score) => score >= 80)
+		expect(passing).toEqual({ alice: 85, bob: 92 })
+
+		// Optimization: return same reference when no changes
+		const unchanged = filterEntries(scores, () => true)
+		expect(unchanged).toBe(scores)
+	})
+
+	it('should pass key and value to predicate', () => {
+		const obj = { prefix_a: 1, other_b: 2, prefix_c: 3 }
+		const result = filterEntries(obj, (key, value) => key.startsWith('prefix_') && value > 1)
+		expect(result).toEqual({ prefix_c: 3 })
+	})
+})
+
+describe('mapObjectMapValues', () => {
+	it('should map values with key and value access', () => {
+		const obj = { a: 1, b: 2, c: 3 }
+		const result = mapObjectMapValues(obj, (key, value) => `${key}:${value}`)
+		expect(result).toEqual({ a: 'a:1', b: 'b:2', c: 'c:3' })
+	})
+
+	it('should skip inherited properties', () => {
+		const parent = { inherited: 'value' }
+		const child = Object.create(parent)
+		child.own = 'ownValue'
+
+		const result = mapObjectMapValues(child, (k, v) => (v as string).toUpperCase())
+		expect(result).toEqual({ own: 'OWNVALUE' })
+	})
+})
+
+describe('areObjectsShallowEqual', () => {
+	it('should compare shallow equality correctly', () => {
+		const a = { x: 1, y: 2 }
+		const b = { x: 1, y: 2 }
+		const c = { x: 1, y: 3 }
+		const d = { x: 1, z: 2 }
+
+		expect(areObjectsShallowEqual(a, a)).toBe(true) // Same reference
+		expect(areObjectsShallowEqual(a, b)).toBe(true) // Same values
+		expect(areObjectsShallowEqual(a, c)).toBe(false) // Different values
+		expect(areObjectsShallowEqual(a, d as any)).toBe(false) // Different keys
+	})
+
+	it('should use Object.is for value comparison', () => {
+		expect(areObjectsShallowEqual({ x: NaN }, { x: NaN })).toBe(true)
+		expect(areObjectsShallowEqual({ x: -0 }, { x: +0 })).toBe(false)
+	})
+})
+
+describe('groupBy', () => {
+	it('should group items by key selector function', () => {
+		const people = [
+			{ name: 'Alice', age: 25 },
+			{ name: 'Bob', age: 30 },
+			{ name: 'Charlie', age: 25 },
+		]
+		const byAge = groupBy(people, (person) => `age-${person.age}`)
+		expect(byAge).toEqual({
+			'age-25': [
+				{ name: 'Alice', age: 25 },
+				{ name: 'Charlie', age: 25 },
+			],
+			'age-30': [{ name: 'Bob', age: 30 }],
+		})
+	})
+
+	it('should accumulate duplicate keys', () => {
+		const items = ['apple', 'apricot', 'banana']
+		const result = groupBy(items, (item) => item.charAt(0))
+		expect(result).toEqual({ a: ['apple', 'apricot'], b: ['banana'] })
+	})
+})
+
+describe('omit', () => {
+	it('should create new object without specified keys', () => {
+		const user = { id: '123', name: 'Alice', password: 'secret', email: 'alice@example.com' }
+		const publicUser = omit(user, ['password'])
+		expect(publicUser).toEqual({ id: '123', name: 'Alice', email: 'alice@example.com' })
+		expect(publicUser).not.toBe(user)
+	})
+
+	it('should handle multiple keys and non-existent keys', () => {
+		const obj = { a: 1, b: 2, c: 3 }
+		const result = omit(obj, ['b', 'nonexistent'])
+		expect(result).toEqual({ a: 1, c: 3 })
+	})
+})
+
+describe('getChangedKeys', () => {
+	it('should identify changed keys using Object.is', () => {
+		const before = { name: 'Alice', age: 25, city: 'NYC' }
+		const after = { name: 'Alice', age: 26, city: 'NYC' }
+		expect(getChangedKeys(before, after)).toEqual(['age'])
+	})
+
+	it('should use Object.is comparison (NaN and zero handling)', () => {
+		const before = { nan: NaN, zero: -0, normal: 1 }
+		const after = { nan: NaN, zero: +0, normal: 2 }
+		expect(getChangedKeys(before, after)).toEqual(['zero', 'normal'])
+	})
+
+	it('should only check keys from first object', () => {
+		const before = { a: 1, b: 2 }
+		const after = { a: 1, b: 2, c: 3 }
+		expect(getChangedKeys(before, after)).toEqual([])
+	})
+})
+
+describe('isEqualAllowingForFloatingPointErrors', () => {
+	it('should handle floating point precision errors', () => {
+		const a = { x: 0.1 + 0.2 } // 0.30000000000000004
+		const b = { x: 0.3 }
+		expect(isEqualAllowingForFloatingPointErrors(a, b)).toBe(true)
+	})
+
+	it('should work with custom threshold and reject large differences', () => {
+		const a = { x: 0.1 }
+		const b = { x: 0.15 }
+		expect(isEqualAllowingForFloatingPointErrors(a, b, 0.1)).toBe(true)
+		expect(isEqualAllowingForFloatingPointErrors(a, b, 0.01)).toBe(false)
+		expect(isEqualAllowingForFloatingPointErrors({ x: 0.1 }, { x: 0.2 })).toBe(false)
+	})
+
+	it('should handle deep objects and arrays with mixed types', () => {
+		const a = { user: 'Alice', score: 0.1 + 0.2, values: [1.0000001, 'test'] }
+		const b = { user: 'Alice', score: 0.3, values: [1.0000002, 'test'] }
+		expect(isEqualAllowingForFloatingPointErrors(a, b)).toBe(true)
+
+		// Different structure should fail
+		expect(isEqualAllowingForFloatingPointErrors({ x: 0.3 }, { y: 0.3 })).toBe(false)
+	})
+})