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

package/src/lib/hash.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest'
+import { getHashForBuffer, getHashForObject, getHashForString, lns } from './hash'
+
+describe('getHashForString', () => {
+	it('should produce consistent hashes for the same input', () => {
+		const input = 'hello world'
+		const hash1 = getHashForString(input)
+		const hash2 = getHashForString(input)
+
+		expect(hash1).toBe(hash2)
+	})
+
+	it('should produce different hashes for different inputs', () => {
+		const hash1 = getHashForString('hello')
+		const hash2 = getHashForString('world')
+
+		expect(hash1).not.toBe(hash2)
+	})
+
+	it('should handle empty strings', () => {
+		const result = getHashForString('')
+		expect(result).toBe('0')
+	})
+})
+
+describe('getHashForObject', () => {
+	it('should produce consistent hashes for equivalent objects', () => {
+		const obj1 = { name: 'John', age: 30 }
+		const obj2 = { name: 'John', age: 30 }
+
+		const hash1 = getHashForObject(obj1)
+		const hash2 = getHashForObject(obj2)
+
+		expect(hash1).toBe(hash2)
+	})
+
+	it('should be sensitive to property order', () => {
+		const obj1 = { a: 1, b: 2 }
+		const obj2 = { b: 2, a: 1 }
+
+		const hash1 = getHashForObject(obj1)
+		const hash2 = getHashForObject(obj2)
+
+		expect(hash1).not.toBe(hash2)
+	})
+})
+
+describe('getHashForBuffer', () => {
+	it('should produce consistent hashes for equivalent buffers', () => {
+		const buffer1 = new ArrayBuffer(4)
+		const buffer2 = new ArrayBuffer(4)
+		const view1 = new DataView(buffer1)
+		const view2 = new DataView(buffer2)
+
+		view1.setUint32(0, 0x12345678)
+		view2.setUint32(0, 0x12345678)
+
+		const hash1 = getHashForBuffer(buffer1)
+		const hash2 = getHashForBuffer(buffer2)
+
+		expect(hash1).toBe(hash2)
+	})
+
+	it('should produce different hashes for different buffer contents', () => {
+		const buffer1 = new ArrayBuffer(4)
+		const buffer2 = new ArrayBuffer(4)
+		const view1 = new DataView(buffer1)
+		const view2 = new DataView(buffer2)
+
+		view1.setUint32(0, 0x12345678)
+		view2.setUint32(0, 0x87654321)
+
+		const hash1 = getHashForBuffer(buffer1)
+		const hash2 = getHashForBuffer(buffer2)
+
+		expect(hash1).not.toBe(hash2)
+	})
+
+	it('should handle empty buffers', () => {
+		const buffer = new ArrayBuffer(0)
+		const result = getHashForBuffer(buffer)
+		expect(result).toBe('0')
+	})
+})
+
+describe('lns', () => {
+	it('should produce consistent results for the same input', () => {
+		const input = 'test123'
+		const result1 = lns(input)
+		const result2 = lns(input)
+
+		expect(result1).toBe(result2)
+	})
+
+	it('should handle empty strings', () => {
+		const result = lns('')
+		expect(result).toBe('')
+	})
+})

package/src/lib/hash.ts

@@ -1,6 +1,20 @@
 /**
  * Hash a string using the FNV-1a algorithm.
  *
+ * Generates a deterministic hash value for a given string using a variant of the FNV-1a
+ * (Fowler-Noll-Vo) algorithm. The hash is returned as a string representation of a 32-bit integer.
+ *
+ * @param string - The input string to hash
+ * @returns A string representation of the 32-bit hash value
+ * @example
+ * ```ts
+ * const hash = getHashForString('hello world')
+ * console.log(hash) // '-862545276'
+ *
+ * // Same input always produces same hash
+ * const hash2 = getHashForString('hello world')
+ * console.log(hash === hash2) // true
+ * ```
  * @public
  */
 export function getHashForString(string: string) {
@@ -13,8 +27,24 @@ export function getHashForString(string: string) {
 }
 
 /**
- * Hash a string using the FNV-1a algorithm.
+ * Hash an object by converting it to JSON and then hashing the resulting string.
+ *
+ * Converts the object to a JSON string using JSON.stringify and then applies the same
+ * hashing algorithm as getHashForString. Useful for creating consistent hash values
+ * for objects, though the hash depends on JSON serialization order.
  *
+ * @param obj - The object to hash (any JSON-serializable value)
+ * @returns A string representation of the 32-bit hash value
+ * @example
+ * ```ts
+ * const hash1 = getHashForObject({ name: 'John', age: 30 })
+ * const hash2 = getHashForObject({ name: 'John', age: 30 })
+ * console.log(hash1 === hash2) // true
+ *
+ * // Arrays work too
+ * const arrayHash = getHashForObject([1, 2, 3, 'hello'])
+ * console.log(arrayHash) // '-123456789'
+ * ```
  * @public
  */
 export function getHashForObject(obj: any) {
@@ -24,6 +54,24 @@ export function getHashForObject(obj: any) {
 /**
  * Hash an ArrayBuffer using the FNV-1a algorithm.
  *
+ * Generates a deterministic hash value for binary data stored in an ArrayBuffer.
+ * Processes the buffer byte by byte using the same hashing algorithm as getHashForString.
+ * Useful for creating consistent identifiers for binary data like images or files.
+ *
+ * @param buffer - The ArrayBuffer containing binary data to hash
+ * @returns A string representation of the 32-bit hash value
+ * @example
+ * ```ts
+ * // Hash some binary data
+ * const data = new Uint8Array([1, 2, 3, 4, 5])
+ * const hash = getHashForBuffer(data.buffer)
+ * console.log(hash) // '123456789'
+ *
+ * // Hash image file data
+ * const fileBuffer = await file.arrayBuffer()
+ * const fileHash = getHashForBuffer(fileBuffer)
+ * console.log(fileHash) // Unique hash for the file
+ * ```
  * @public
  */
 export function getHashForBuffer(buffer: ArrayBuffer) {
@@ -36,7 +84,26 @@ export function getHashForBuffer(buffer: ArrayBuffer) {
 	return hash + ''
 }
 
-/** @public */
+/**
+ * Applies a string transformation algorithm that rearranges and modifies characters.
+ *
+ * Performs a series of character manipulations on the input string including
+ * character repositioning through splicing operations and numeric character transformations.
+ * This appears to be a custom encoding/obfuscation function.
+ *
+ * @param str - The input string to transform
+ * @returns The transformed string after applying all manipulations
+ * @example
+ * ```ts
+ * const result = lns('hello123')
+ * console.log(result) // Transformed string (exact output depends on algorithm)
+ *
+ * // Can be used for simple string obfuscation
+ * const obfuscated = lns('sensitive-data')
+ * console.log(obfuscated) // Obfuscated version
+ * ```
+ * @public
+ */
 export function lns(str: string) {
 	const result = str.split('')
 	result.push(...result.splice(0, Math.round(result.length / 5)))

package/src/lib/id.test.ts

@@ -0,0 +1,32 @@
+import { afterEach, describe, expect, test } from 'vitest'
+import { mockUniqueId, restoreUniqueId, uniqueId } from './id'
+
+describe('mockUniqueId', () => {
+	afterEach(() => {
+		restoreUniqueId()
+	})
+
+	test('replaces uniqueId with custom implementation', () => {
+		mockUniqueId(() => 'test-id')
+
+		expect(uniqueId()).toBe('test-id')
+		expect(uniqueId(10)).toBe('test-id')
+	})
+})
+
+describe('restoreUniqueId', () => {
+	test('restores original uniqueId behavior after mocking', () => {
+		mockUniqueId(() => 'mocked-id')
+		expect(uniqueId()).toBe('mocked-id')
+
+		restoreUniqueId()
+
+		const id1 = uniqueId()
+		const id2 = uniqueId()
+
+		expect(id1).not.toBe('mocked-id')
+		expect(id2).not.toBe('mocked-id')
+		expect(id1).not.toBe(id2)
+		expect(id1).toHaveLength(21)
+	})
+})

package/src/lib/id.ts

@@ -55,25 +55,73 @@ function nanoid(size = 21) {
 }
 
 let impl = nanoid
-/** @internal */
+/**
+ * Mock the unique ID generator with a custom implementation for testing.
+ *
+ * Replaces the internal ID generation function with a custom one. This is useful
+ * for testing scenarios where you need predictable or deterministic IDs.
+ *
+ * @param fn - The mock function that should return a string ID. Takes optional size parameter.
+ * @example
+ * ```ts
+ * // Mock with predictable IDs for testing
+ * mockUniqueId((size = 21) => 'test-id-' + size)
+ * console.log(uniqueId()) // 'test-id-21'
+ * console.log(uniqueId(10)) // 'test-id-10'
+ *
+ * // Restore original implementation when done
+ * restoreUniqueId()
+ * ```
+ * @internal
+ */
 export function mockUniqueId(fn: (size?: number) => string) {
 	impl = fn
 }
 
-/** @internal */
+/**
+ * Restore the original unique ID generator after mocking.
+ *
+ * Resets the ID generation function back to the original nanoid implementation.
+ * This should be called after testing to restore normal ID generation behavior.
+ *
+ * @example
+ * ```ts
+ * // After mocking for tests
+ * mockUniqueId(() => 'mock-id')
+ *
+ * // Restore original behavior
+ * restoreUniqueId()
+ * console.log(uniqueId()) // Now generates real random IDs again
+ * ```
+ * @internal
+ */
 export function restoreUniqueId() {
 	impl = nanoid
 }
 
 /**
- * Generate a unique id.
+ * Generate a unique ID using a modified nanoid algorithm.
  *
- * @example
+ * Generates a cryptographically secure random string ID using URL-safe characters.
+ * The default size is 21 characters, which provides a good balance of uniqueness
+ * and brevity. Uses the global crypto API for secure random number generation.
  *
+ * @param size - Optional length of the generated ID (defaults to 21 characters)
+ * @returns A unique string identifier
+ * @example
  * ```ts
+ * // Generate default 21-character ID
  * const id = uniqueId()
- * ```
+ * console.log(id) // 'V1StGXR8_Z5jdHi6B-myT'
  *
+ * // Generate shorter ID
+ * const shortId = uniqueId(10)
+ * console.log(shortId) // 'V1StGXR8_Z'
+ *
+ * // Generate longer ID
+ * const longId = uniqueId(32)
+ * console.log(longId) // 'V1StGXR8_Z5jdHi6B-myTVKahvjdx...'
+ * ```
  * @public
  */
 export function uniqueId(size?: number): string {

package/src/lib/iterable.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { getFirstFromIterable } from './iterable'
+
+describe('getFirstFromIterable', () => {
+	it('should get first item from Set', () => {
+		const set = new Set([1, 2, 3])
+		expect(getFirstFromIterable(set)).toBe(1)
+	})
+
+	it('should get first value from Map', () => {
+		const map = new Map([
+			['a', 1],
+			['b', 2],
+		])
+		expect(getFirstFromIterable(map)).toBe(1)
+	})
+
+	it('should preserve insertion order', () => {
+		const set = new Set()
+		set.add('third')
+		set.add('first')
+		set.add('second')
+		expect(getFirstFromIterable(set)).toBe('third')
+	})
+})

package/src/lib/iterable.ts

@@ -1,19 +1,18 @@
 /**
  * Get the first item from an iterable Set or Map.
  *
+ * @param value - The iterable Set or Map to get the first item from
+ * @returns The first value from the Set or Map
  * @example
- *
  * ```ts
- * const A = getFirstItem(new Set([1, 2, 3])) // 1
- * const B = getFirstItem(
+ * const A = getFirstFromIterable(new Set([1, 2, 3])) // 1
+ * const B = getFirstFromIterable(
  * 	new Map([
  * 		['a', 1],
  * 		['b', 2],
  * 	])
  * ) // 1
  * ```
- *
- * @param value - The iterable Set or Map.
  * @public
  */
 export function getFirstFromIterable<T = unknown>(set: Set<T> | Map<any, T>): T {

package/src/lib/json-value.ts

@@ -1,10 +1,77 @@
-/** @public */
+/**
+ * A type that represents any valid JSON value. This includes primitives (boolean, null, string, number),
+ * arrays of JSON values, and objects with string keys and JSON values.
+ *
+ * @example
+ * ```ts
+ * const jsonData: JsonValue = {
+ *   name: "Alice",
+ *   age: 30,
+ *   active: true,
+ *   tags: ["user", "premium"],
+ *   metadata: null
+ * }
+ * ```
+ *
+ * @public
+ */
 export type JsonValue = JsonPrimitive | JsonArray | JsonObject
-/** @public */
+
+/**
+ * A type representing JSON primitive values: boolean, null, string, or number.
+ * These are the atomic values that can appear in JSON data.
+ *
+ * @example
+ * ```ts
+ * const primitives: JsonPrimitive[] = [
+ *   true,
+ *   null,
+ *   "hello",
+ *   42
+ * ]
+ * ```
+ *
+ * @public
+ */
 export type JsonPrimitive = boolean | null | string | number
-/** @public */
+
+/**
+ * A type representing a JSON array containing any valid JSON values.
+ * Arrays can contain mixed types of JSON values including nested arrays and objects.
+ *
+ * @example
+ * ```ts
+ * const jsonArray: JsonArray = [
+ *   "text",
+ *   123,
+ *   true,
+ *   { nested: "object" },
+ *   [1, 2, 3]
+ * ]
+ * ```
+ *
+ * @public
+ */
 export type JsonArray = JsonValue[]
-/** @public */
+
+/**
+ * A type representing a JSON object with string keys and JSON values.
+ * Object values can be undefined to handle optional properties safely.
+ *
+ * @example
+ * ```ts
+ * const jsonObject: JsonObject = {
+ *   required: "value",
+ *   optional: undefined,
+ *   nested: {
+ *     deep: "property"
+ *   },
+ *   array: [1, 2, 3]
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface JsonObject {
 	[key: string]: JsonValue | undefined
 }

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

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest'
+import { isApngAnimated } from './apng'
+
+describe('isApngAnimated', () => {
+	it('returns false for empty ArrayBuffer', () => {
+		const buffer = new ArrayBuffer(0)
+		expect(isApngAnimated(buffer)).toBe(false)
+	})
+
+	it('returns false for buffer too small to be PNG', () => {
+		const buffer = new ArrayBuffer(8)
+		expect(isApngAnimated(buffer)).toBe(false)
+	})
+
+	it('returns false for non-PNG data', () => {
+		const buffer = new ArrayBuffer(20)
+		const view = new Uint8Array(buffer)
+		// JPEG signature instead
+		view.set([0xff, 0xd8, 0xff, 0xe0])
+		expect(isApngAnimated(buffer)).toBe(false)
+	})
+
+	it('returns false for regular PNG with IDAT but no acTL', () => {
+		const buffer = new ArrayBuffer(100)
+		const view = new Uint8Array(buffer)
+
+		// PNG signature
+		view.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], 0)
+
+		// Add IDAT chunk at position 20
+		view.set(new TextEncoder().encode('IDAT'), 20)
+
+		expect(isApngAnimated(buffer)).toBe(false)
+	})
+
+	it('returns false when acTL comes after IDAT', () => {
+		const buffer = new ArrayBuffer(100)
+		const view = new Uint8Array(buffer)
+
+		// PNG signature
+		view.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], 0)
+
+		// IDAT chunk at position 20
+		view.set(new TextEncoder().encode('IDAT'), 20)
+
+		// acTL chunk after IDAT - should not count as animated
+		view.set(new TextEncoder().encode('acTL'), 30)
+
+		expect(isApngAnimated(buffer)).toBe(false)
+	})
+
+	it('returns true for APNG with acTL before IDAT', () => {
+		const buffer = new ArrayBuffer(100)
+		const view = new Uint8Array(buffer)
+
+		// PNG signature
+		view.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], 0)
+
+		// acTL chunk before IDAT
+		view.set(new TextEncoder().encode('acTL'), 15)
+
+		// IDAT chunk
+		view.set(new TextEncoder().encode('IDAT'), 30)
+
+		expect(isApngAnimated(buffer)).toBe(true)
+	})
+})

package/src/lib/media/apng.ts

@@ -3,6 +3,35 @@
  * Copyright (c) Philip van Heemstra
  */
 
+/**
+ * Determines whether an ArrayBuffer contains an animated PNG (APNG) image.
+ *
+ * This function checks if the provided buffer contains a valid PNG file with animation
+ * control chunks (acTL) that precede the image data chunks (IDAT), which indicates
+ * it's an animated PNG rather than a static PNG.
+ *
+ * @param buffer - The ArrayBuffer containing the image data to analyze
+ * @returns True if the buffer contains an animated PNG, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Check if an uploaded file contains an animated PNG
+ * if (file.type === 'image/apng') {
+ *   const isAnimated = isApngAnimated(await file.arrayBuffer())
+ *   console.log(isAnimated ? 'Animated PNG' : 'Static PNG')
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use with fetch to check remote images
+ * const response = await fetch('image.png')
+ * const buffer = await response.arrayBuffer()
+ * const hasAnimation = isApngAnimated(buffer)
+ * ```
+ *
+ * @public
+ */
 export function isApngAnimated(buffer: ArrayBuffer): boolean {
 	const view = new Uint8Array(buffer)
 
@@ -29,29 +58,17 @@ export function isApngAnimated(buffer: ArrayBuffer): boolean {
 	}
 
 	/**
-	 * Returns the index of the first occurrence of a sequence in an typed array, or -1 if it is not present.
-	 *
-	 * Works similar to `Array.prototype.indexOf()`, but it searches for a sequence of array values (bytes).
-	 * The bytes in the `haystack` array are decoded (UTF-8) and then used to search for `needle`.
-	 *
-	 * @param haystack `Uint8Array`
-	 * Array to search in.
-	 *
-	 * @param needle `string | RegExp`
-	 * The value to locate in the array.
-	 *
-	 * @param fromIndex `number`
-	 * The array index at which to begin the search.
-	 *
-	 * @param upToIndex `number`
-	 * The array index up to which to search.
-	 * If omitted, search until the end.
+	 * Returns the index of the first occurrence of a string pattern in a Uint8Array, or -1 if not found.
 	 *
-	 * @param chunksize `number`
-	 * Size of the chunks used when searching (default 1024).
+	 * Searches for a string pattern by decoding chunks of the byte array to UTF-8 text and using
+	 * regular expression matching. Handles cases where the pattern might be split across chunk boundaries.
 	 *
-	 * @returns boolean
-	 * Whether the array holds Animated PNG data.
+	 * @param haystack - The Uint8Array to search in
+	 * @param needle - The string or RegExp pattern to locate
+	 * @param fromIndex - The array index at which to begin the search
+	 * @param upToIndex - The array index up to which to search (optional, defaults to array end)
+	 * @param chunksize - Size of the chunks used when searching (default 1024 bytes)
+	 * @returns The index position of the first match, or -1 if not found
 	 */
 	function indexOfSubstring(
 		haystack: Uint8Array,

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

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest'
+import { isAvifAnimated } from './avif'
+
+describe('isAvifAnimated', () => {
+	it('returns true when 4th byte equals 44', () => {
+		const buffer = new ArrayBuffer(10)
+		const view = new Uint8Array(buffer)
+		view[3] = 44
+
+		expect(isAvifAnimated(buffer)).toBe(true)
+	})
+
+	it('returns false when 4th byte is not 44', () => {
+		const buffer = new ArrayBuffer(10)
+		const view = new Uint8Array(buffer)
+		view[3] = 43
+
+		expect(isAvifAnimated(buffer)).toBe(false)
+	})
+
+	it('returns false for buffer smaller than 4 bytes', () => {
+		const buffer = new ArrayBuffer(3)
+		// Accessing index 3 should return undefined, which !== 44
+		expect(isAvifAnimated(buffer)).toBe(false)
+	})
+})

package/src/lib/media/avif.ts

@@ -1,3 +1,37 @@
+/**
+ * Determines whether an ArrayBuffer contains an animated AVIF image.
+ *
+ * This function performs a simple check by examining the 4th byte of the buffer.
+ * AVIF animation is indicated when the byte at index 3 equals 44.
+ *
+ * @param buffer - The ArrayBuffer containing the AVIF image data to analyze
+ * @returns True if the buffer contains an animated AVIF, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Check if an AVIF file is animated
+ * const response = await fetch('image.avif')
+ * const buffer = await response.arrayBuffer()
+ * const isAnimated = isAvifAnimated(buffer)
+ * if (isAnimated) {
+ *   console.log('This AVIF contains animation!')
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use with file input
+ * const fileInput = document.querySelector('input[type="file"]')
+ * fileInput.addEventListener('change', async (event) => {
+ *   const file = event.target.files[0]
+ *   const buffer = await file.arrayBuffer()
+ *   const hasAnimation = isAvifAnimated(buffer)
+ *   console.log(hasAnimation ? 'Animated AVIF' : 'Static AVIF')
+ * })
+ * ```
+ *
+ * @public
+ */
 export const isAvifAnimated = (buffer: ArrayBuffer) => {
 	const view = new Uint8Array(buffer)
 	return view[3] === 44