@tldraw/store 4.1.0-canary.8e597b345c40 → 4.1.0-canary.95d46c96eb30

package/src/lib/ImmutableMap.ts

@@ -190,6 +190,33 @@ const is = Object.is
 
 class OwnerID {}
 
+/**
+ * A persistent immutable map implementation based on a Hash Array Mapped Trie (HAMT) data structure.
+ * Provides efficient operations for creating, reading, updating, and deleting key-value pairs while
+ * maintaining structural sharing to minimize memory usage and maximize performance.
+ *
+ * This implementation is extracted and adapted from Immutable.js, optimized for tldraw's store needs.
+ * All operations return new instances rather than modifying existing ones, ensuring immutability.
+ *
+ * @public
+ * @example
+ * ```ts
+ * // Create a new map
+ * const map = new ImmutableMap([
+ *   ['key1', 'value1'],
+ *   ['key2', 'value2']
+ * ])
+ *
+ * // Add or update values
+ * const updated = map.set('key3', 'value3')
+ *
+ * // Get values
+ * const value = map.get('key1') // 'value1'
+ *
+ * // Delete values
+ * const smaller = map.delete('key1')
+ * ```
+ */
 export class ImmutableMap<K, V> {
 	// @pragma Construction
 	// @ts-ignore
@@ -203,6 +230,22 @@ export class ImmutableMap<K, V> {
 	// @ts-ignore
 	__altered: boolean
 
+	/**
+	 * Creates a new ImmutableMap instance.
+	 *
+	 * @param value - An iterable of key-value pairs to populate the map, or null/undefined for an empty map
+	 * @example
+	 * ```ts
+	 * // Create from array of pairs
+	 * const map1 = new ImmutableMap([['a', 1], ['b', 2]])
+	 *
+	 * // Create empty map
+	 * const map2 = new ImmutableMap()
+	 *
+	 * // Create from another map
+	 * const map3 = new ImmutableMap(map1)
+	 * ```
+	 */
 	constructor(value?: Iterable<[K, V]> | null | undefined) {
 		// @ts-ignore
 		return value === undefined || value === null
@@ -216,19 +259,83 @@ export class ImmutableMap<K, V> {
 					})
 	}
 
+	/**
+	 * Gets the value associated with the specified key.
+	 *
+	 * @param k - The key to look up
+	 * @returns The value associated with the key, or undefined if not found
+	 * @example
+	 * ```ts
+	 * const map = new ImmutableMap([['key1', 'value1']])
+	 * console.log(map.get('key1')) // 'value1'
+	 * console.log(map.get('missing')) // undefined
+	 * ```
+	 */
 	get(k: K): V | undefined
+	/**
+	 * Gets the value associated with the specified key, with a fallback value.
+	 *
+	 * @param k - The key to look up
+	 * @param notSetValue - The value to return if the key is not found
+	 * @returns The value associated with the key, or the fallback value if not found
+	 * @example
+	 * ```ts
+	 * const map = new ImmutableMap([['key1', 'value1']])
+	 * console.log(map.get('key1', 'default')) // 'value1'
+	 * console.log(map.get('missing', 'default')) // 'default'
+	 * ```
+	 */
 	get(k: K, notSetValue?: V): V {
 		return this._root ? this._root.get(0, undefined as any, k, notSetValue)! : notSetValue!
 	}
 
+	/**
+	 * Returns a new ImmutableMap with the specified key-value pair added or updated.
+	 * If the key already exists, its value is replaced. Otherwise, a new entry is created.
+	 *
+	 * @param k - The key to set
+	 * @param v - The value to associate with the key
+	 * @returns A new ImmutableMap with the key-value pair set
+	 * @example
+	 * ```ts
+	 * const map = new ImmutableMap([['a', 1]])
+	 * const updated = map.set('b', 2) // New map with both 'a' and 'b'
+	 * const replaced = map.set('a', 10) // New map with 'a' updated to 10
+	 * ```
+	 */
 	set(k: K, v: V) {
 		return updateMap(this, k, v)
 	}
 
+	/**
+	 * Returns a new ImmutableMap with the specified key removed.
+	 * If the key doesn't exist, returns the same map instance.
+	 *
+	 * @param k - The key to remove
+	 * @returns A new ImmutableMap with the key removed, or the same instance if key not found
+	 * @example
+	 * ```ts
+	 * const map = new ImmutableMap([['a', 1], ['b', 2]])
+	 * const smaller = map.delete('a') // New map with only 'b'
+	 * const same = map.delete('missing') // Returns original map
+	 * ```
+	 */
 	delete(k: K) {
 		return updateMap(this, k, NOT_SET as any)
 	}
 
+	/**
+	 * Returns a new ImmutableMap with all specified keys removed.
+	 * This is more efficient than calling delete() multiple times.
+	 *
+	 * @param keys - An iterable of keys to remove
+	 * @returns A new ImmutableMap with all specified keys removed
+	 * @example
+	 * ```ts
+	 * const map = new ImmutableMap([['a', 1], ['b', 2], ['c', 3]])
+	 * const smaller = map.deleteAll(['a', 'c']) // New map with only 'b'
+	 * ```
+	 */
 	deleteAll(keys: Iterable<K>) {
 		return this.withMutations((map) => {
 			for (const key of keys) {
@@ -252,32 +359,105 @@ export class ImmutableMap<K, V> {
 		return makeMap(this.size, this._root, ownerID, this.__hash)
 	}
 
+	/**
+	 * Applies multiple mutations efficiently by creating a mutable copy,
+	 * applying all changes, then returning an immutable result.
+	 * This is more efficient than chaining multiple set/delete operations.
+	 *
+	 * @param fn - Function that receives a mutable copy and applies changes
+	 * @returns A new ImmutableMap with all mutations applied, or the same instance if no changes
+	 * @example
+	 * ```ts
+	 * const map = new ImmutableMap([['a', 1]])
+	 * const updated = map.withMutations(mutable => {
+	 *   mutable.set('b', 2)
+	 *   mutable.set('c', 3)
+	 *   mutable.delete('a')
+	 * }) // Efficiently applies all changes at once
+	 * ```
+	 */
 	withMutations(fn: (mutable: this) => void): this {
 		const mutable = this.asMutable()
 		fn(mutable)
 		return mutable.wasAltered() ? mutable.__ensureOwner(this.__ownerID) : this
 	}
 
+	/**
+	 * Checks if this map instance has been altered during a mutation operation.
+	 * This is used internally to optimize mutations.
+	 *
+	 * @returns True if the map was altered, false otherwise
+	 * @internal
+	 */
 	wasAltered() {
 		return this.__altered
 	}
 
+	/**
+	 * Returns a mutable copy of this map that can be efficiently modified.
+	 * Multiple changes to the mutable copy are batched together.
+	 *
+	 * @returns A mutable copy of this map
+	 * @internal
+	 */
 	asMutable() {
 		return this.__ownerID ? this : this.__ensureOwner(new OwnerID())
 	}
 
+	/**
+	 * Makes the map iterable, yielding key-value pairs.
+	 *
+	 * @returns An iterator over [key, value] pairs
+	 * @example
+	 * ```ts
+	 * const map = new ImmutableMap([['a', 1], ['b', 2]])
+	 * for (const [key, value] of map) {
+	 *   console.log(key, value) // 'a' 1, then 'b' 2
+	 * }
+	 * ```
+	 */
 	[Symbol.iterator](): Iterator<[K, V]> {
 		return this.entries()[Symbol.iterator]()
 	}
 
+	/**
+	 * Returns an iterable of key-value pairs.
+	 *
+	 * @returns An iterable over [key, value] pairs
+	 * @example
+	 * ```ts
+	 * const map = new ImmutableMap([['a', 1], ['b', 2]])
+	 * const entries = Array.from(map.entries()) // [['a', 1], ['b', 2]]
+	 * ```
+	 */
 	entries(): Iterable<[K, V]> {
 		return new MapIterator(this, ITERATE_ENTRIES, false)
 	}
 
+	/**
+	 * Returns an iterable of keys.
+	 *
+	 * @returns An iterable over keys
+	 * @example
+	 * ```ts
+	 * const map = new ImmutableMap([['a', 1], ['b', 2]])
+	 * const keys = Array.from(map.keys()) // ['a', 'b']
+	 * ```
+	 */
 	keys(): Iterable<K> {
 		return new MapIterator(this, ITERATE_KEYS, false)
 	}
 
+	/**
+	 * Returns an iterable of values.
+	 *
+	 * @returns An iterable over values
+	 * @example
+	 * ```ts
+	 * const map = new ImmutableMap([['a', 1], ['b', 2]])
+	 * const values = Array.from(map.values()) // [1, 2]
+	 * ```
+	 */
 	values(): Iterable<V> {
 		return new MapIterator(this, ITERATE_VALUES, false)
 	}
@@ -757,6 +937,19 @@ function iteratorValue<K, V>(
 	return iteratorResult
 }
 
+/**
+ * Creates a completed iterator result object indicating iteration is finished.
+ * Used internally by map iterators to signal the end of iteration.
+ *
+ * @returns An IteratorResult object with done set to true and value as undefined
+ * @public
+ * @example
+ * ```ts
+ * // Used internally by iterators
+ * const result = iteratorDone()
+ * console.log(result) // { value: undefined, done: true }
+ * ```
+ */
 export function iteratorDone() {
 	return { value: undefined, done: true }
 }
@@ -772,6 +965,25 @@ function makeMap<K, V>(size: number, root?: MapNode<K, V>, ownerID?: OwnerID, ha
 }
 
 let EMPTY_MAP: ImmutableMap<unknown, unknown>
+/**
+ * Returns a singleton empty ImmutableMap instance.
+ * This function is optimized to return the same empty map instance for all calls,
+ * saving memory when working with many empty maps.
+ *
+ * @returns An empty ImmutableMap instance
+ * @public
+ * @example
+ * ```ts
+ * // Get an empty map
+ * const empty = emptyMap<string, number>()
+ * console.log(empty.size) // 0
+ *
+ * // All empty maps are the same instance
+ * const empty1 = emptyMap()
+ * const empty2 = emptyMap()
+ * console.log(empty1 === empty2) // true
+ * ```
+ */
 export function emptyMap<K, V>(): ImmutableMap<K, V> {
 	return (EMPTY_MAP as any) || (EMPTY_MAP = makeMap(0))
 }

package/src/lib/IncrementalSetConstructor.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest'
+import { IncrementalSetConstructor } from './IncrementalSetConstructor'
+
+describe('IncrementalSetConstructor', () => {
+	describe('core functionality', () => {
+		it('should return undefined when no net changes occur', () => {
+			const originalSet = new Set(['a', 'b', 'c'])
+			const constructor = new IncrementalSetConstructor(originalSet)
+
+			constructor.add('d')
+			constructor.remove('d')
+
+			const result = constructor.get()
+			expect(result).toBeUndefined()
+		})
+
+		it('should return correct result when items are added', () => {
+			const originalSet = new Set(['a', 'b'])
+			const constructor = new IncrementalSetConstructor(originalSet)
+
+			constructor.add('c')
+			constructor.add('d')
+
+			const result = constructor.get()
+			expect(result).toBeDefined()
+			expect(result!.value).toEqual(new Set(['a', 'b', 'c', 'd']))
+			expect(result!.diff.added).toEqual(new Set(['c', 'd']))
+			expect(result!.diff.removed).toBeUndefined()
+		})
+
+		it('should return correct result when items are removed', () => {
+			const originalSet = new Set(['a', 'b', 'c', 'd'])
+			const constructor = new IncrementalSetConstructor(originalSet)
+
+			constructor.remove('c')
+			constructor.remove('d')
+
+			const result = constructor.get()
+			expect(result).toBeDefined()
+			expect(result!.value).toEqual(new Set(['a', 'b']))
+			expect(result!.diff.removed).toEqual(new Set(['c', 'd']))
+			expect(result!.diff.added).toBeUndefined()
+		})
+
+		it('should handle mixed add and remove operations correctly', () => {
+			const originalSet = new Set(['a', 'b', 'c'])
+			const constructor = new IncrementalSetConstructor(originalSet)
+
+			constructor.remove('a')
+			constructor.add('d')
+			constructor.add('e')
+
+			const result = constructor.get()
+			expect(result).toBeDefined()
+			expect(result!.value).toEqual(new Set(['b', 'c', 'd', 'e']))
+			expect(result!.diff.added).toEqual(new Set(['d', 'e']))
+			expect(result!.diff.removed).toEqual(new Set(['a']))
+		})
+
+		it('should handle adding existing items as no-op', () => {
+			const originalSet = new Set(['a', 'b', 'c'])
+			const constructor = new IncrementalSetConstructor(originalSet)
+
+			constructor.add('a')
+			constructor.add('b')
+
+			const result = constructor.get()
+			expect(result).toBeUndefined()
+		})
+
+		it('should handle complex restore and cancel scenarios', () => {
+			const originalSet = new Set(['a', 'b', 'c'])
+			const constructor = new IncrementalSetConstructor(originalSet)
+
+			constructor.remove('a')
+			constructor.remove('b')
+			constructor.add('d')
+			constructor.add('a') // Restore one removed item
+
+			const result = constructor.get()
+			expect(result!.value).toEqual(new Set(['a', 'c', 'd']))
+			expect(result!.diff.added).toEqual(new Set(['d']))
+			expect(result!.diff.removed).toEqual(new Set(['b']))
+		})
+
+		it('should handle removing non-existent items as no-op', () => {
+			const originalSet = new Set(['a', 'b'])
+			const constructor = new IncrementalSetConstructor(originalSet)
+
+			constructor.remove('c')
+			constructor.remove('d')
+
+			const result = constructor.get()
+			expect(result).toBeUndefined()
+		})
+
+		it('should remove recently added items correctly', () => {
+			const originalSet = new Set(['a', 'b'])
+			const constructor = new IncrementalSetConstructor(originalSet)
+
+			constructor.add('c')
+			constructor.add('d')
+			constructor.remove('c') // Remove recently added item
+
+			const result = constructor.get()
+			expect(result!.value).toEqual(new Set(['a', 'b', 'd']))
+			expect(result!.diff.added).toEqual(new Set(['d']))
+			expect(result!.diff.removed).toBeUndefined()
+		})
+	})
+})

package/src/lib/IncrementalSetConstructor.ts

@@ -1,7 +1,24 @@
 import { CollectionDiff } from './Store'
 
 /**
- * A class that can be used to incrementally construct a set of records.
+ * A utility class for incrementally building a set while tracking changes. This class allows
+ * you to add and remove items from a set while maintaining a diff of what was added and
+ * removed from the original set. It's optimized for cases where you need to track changes
+ * to a set over time and get both the final result and the change delta.
+ *
+ * @example
+ * ```ts
+ * const originalSet = new Set(['a', 'b', 'c'])
+ * const constructor = new IncrementalSetConstructor(originalSet)
+ *
+ * constructor.add('d') // Add new item
+ * constructor.remove('b') // Remove existing item
+ * constructor.add('a') // Re-add removed item (no-op since already present)
+ *
+ * const result = constructor.get()
+ * // result.value contains Set(['a', 'c', 'd'])
+ * // result.diff contains { added: Set(['d']), removed: Set(['b']) }
+ * ```
  *
  * @internal
  */
@@ -31,7 +48,23 @@ export class IncrementalSetConstructor<T> {
 	) {}
 
 	/**
-	 * Get the next value of the set.
+	 * Gets the result of the incremental set construction if any changes were made.
+	 * Returns undefined if no additions or removals occurred.
+	 *
+	 * @returns An object containing the final set value and the diff of changes,
+	 * or undefined if no changes were made
+	 *
+	 * @example
+	 * ```ts
+	 * const constructor = new IncrementalSetConstructor(new Set(['a', 'b']))
+	 * constructor.add('c')
+	 *
+	 * const result = constructor.get()
+	 * // result = {
+	 * //   value: Set(['a', 'b', 'c']),
+	 * //   diff: { added: Set(['c']) }
+	 * // }
+	 * ```
 	 *
 	 * @public
 	 */
@@ -65,9 +98,21 @@ export class IncrementalSetConstructor<T> {
 	}
 
 	/**
-	 * Add an item to the set.
+	 * Adds an item to the set. If the item was already present in the original set
+	 * and was previously removed during this construction, it will be restored.
+	 * If the item is already present and wasn't removed, this is a no-op.
+	 *
+	 * @param item - The item to add to the set
+	 *
+	 * @example
+	 * ```ts
+	 * const constructor = new IncrementalSetConstructor(new Set(['a', 'b']))
+	 * constructor.add('c') // Adds new item
+	 * constructor.add('a') // No-op, already present
+	 * constructor.remove('b')
+	 * constructor.add('b') // Restores previously removed item
+	 * ```
 	 *
-	 * @param item - The item to add.
 	 * @public
 	 */
 	add(item: T) {
@@ -108,9 +153,21 @@ export class IncrementalSetConstructor<T> {
 	}
 
 	/**
-	 * Remove an item from the set.
+	 * Removes an item from the set. If the item wasn't present in the original set
+	 * and was added during this construction, it will be removed from the added diff.
+	 * If the item is not present at all, this is a no-op.
+	 *
+	 * @param item - The item to remove from the set
+	 *
+	 * @example
+	 * ```ts
+	 * const constructor = new IncrementalSetConstructor(new Set(['a', 'b']))
+	 * constructor.remove('a') // Removes existing item
+	 * constructor.remove('c') // No-op, not present
+	 * constructor.add('d')
+	 * constructor.remove('d') // Removes recently added item
+	 * ```
 	 *
-	 * @param item - The item to remove.
 	 * @public
 	 */
 	remove(item: T) {