@tldraw/store 4.1.0-canary.e653ec63c99b → 4.1.0-canary.e87046ba1a0c

package/src/lib/AtomMap.ts

@@ -9,6 +9,21 @@ import { emptyMap, ImmutableMap } from './ImmutableMap'
 export class AtomMap<K, V> implements Map<K, V> {
 	private atoms: Atom<ImmutableMap<K, Atom<V | UNINITIALIZED>>>
 
+	/**
+	 * Creates a new AtomMap instance.
+	 *
+	 * name - A unique name for this map, used for atom identification
+	 * entries - Optional initial entries to populate the map with
+	 * @example
+	 * ```ts
+	 * // Create an empty map
+	 * const map = new AtomMap('userMap')
+	 *
+	 * // Create a map with initial data
+	 * const initialData: [string, number][] = [['a', 1], ['b', 2]]
+	 * const mapWithData = new AtomMap('numbersMap', initialData)
+	 * ```
+	 */
 	constructor(
 		private readonly name: string,
 		entries?: Iterable<readonly [K, V]>
@@ -24,7 +39,13 @@ export class AtomMap<K, V> implements Map<K, V> {
 		this.atoms = atom(`${name}:atoms`, atoms)
 	}
 
-	/** @internal */
+	/**
+	 * Retrieves the underlying atom for a given key.
+	 *
+	 * @param key - The key to retrieve the atom for
+	 * @returns The atom containing the value, or undefined if the key doesn't exist
+	 * @internal
+	 */
 	getAtom(key: K): Atom<V | UNINITIALIZED> | undefined {
 		const valueAtom = this.atoms.__unsafe__getWithoutCapture().get(key)
 		if (!valueAtom) {
@@ -35,12 +56,39 @@ export class AtomMap<K, V> implements Map<K, V> {
 		return valueAtom
 	}
 
+	/**
+	 * Gets the value associated with a key. Returns undefined if the key doesn't exist.
+	 * This method is reactive and will cause reactive contexts to update when the value changes.
+	 *
+	 * @param key - The key to retrieve the value for
+	 * @returns The value associated with the key, or undefined if not found
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * map.set('name', 'Alice')
+	 * console.log(map.get('name')) // 'Alice'
+	 * console.log(map.get('missing')) // undefined
+	 * ```
+	 */
 	get(key: K): V | undefined {
 		const value = this.getAtom(key)?.get()
 		assert(value !== UNINITIALIZED)
 		return value
 	}
 
+	/**
+	 * Gets the value associated with a key without creating reactive dependencies.
+	 * This method will not cause reactive contexts to update when the value changes.
+	 *
+	 * @param key - The key to retrieve the value for
+	 * @returns The value associated with the key, or undefined if not found
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * map.set('count', 42)
+	 * const value = map.__unsafe__getWithoutCapture('count') // No reactive subscription
+	 * ```
+	 */
 	__unsafe__getWithoutCapture(key: K): V | undefined {
 		const valueAtom = this.atoms.__unsafe__getWithoutCapture().get(key)
 		if (!valueAtom) return undefined
@@ -49,6 +97,20 @@ export class AtomMap<K, V> implements Map<K, V> {
 		return value
 	}
 
+	/**
+	 * Checks whether a key exists in the map.
+	 * This method is reactive and will cause reactive contexts to update when keys are added or removed.
+	 *
+	 * @param key - The key to check for
+	 * @returns True if the key exists in the map, false otherwise
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * console.log(map.has('name')) // false
+	 * map.set('name', 'Alice')
+	 * console.log(map.has('name')) // true
+	 * ```
+	 */
 	has(key: K): boolean {
 		const valueAtom = this.getAtom(key)
 		if (!valueAtom) {
@@ -57,6 +119,19 @@ export class AtomMap<K, V> implements Map<K, V> {
 		return valueAtom.get() !== UNINITIALIZED
 	}
 
+	/**
+	 * Checks whether a key exists in the map without creating reactive dependencies.
+	 * This method will not cause reactive contexts to update when keys are added or removed.
+	 *
+	 * @param key - The key to check for
+	 * @returns True if the key exists in the map, false otherwise
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * map.set('active', true)
+	 * const exists = map.__unsafe__hasWithoutCapture('active') // No reactive subscription
+	 * ```
+	 */
 	__unsafe__hasWithoutCapture(key: K): boolean {
 		const valueAtom = this.atoms.__unsafe__getWithoutCapture().get(key)
 		if (!valueAtom) return false
@@ -64,6 +139,19 @@ export class AtomMap<K, V> implements Map<K, V> {
 		return true
 	}
 
+	/**
+	 * Sets a value for the given key. If the key already exists, its value is updated.
+	 * If the key doesn't exist, a new entry is created.
+	 *
+	 * @param key - The key to set the value for
+	 * @param value - The value to associate with the key
+	 * @returns This AtomMap instance for method chaining
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * map.set('name', 'Alice').set('age', 30)
+	 * ```
+	 */
 	set(key: K, value: V) {
 		const existingAtom = this.atoms.__unsafe__getWithoutCapture().get(key)
 		if (existingAtom) {
@@ -76,6 +164,19 @@ export class AtomMap<K, V> implements Map<K, V> {
 		return this
 	}
 
+	/**
+	 * Updates an existing value using an updater function.
+	 *
+	 * @param key - The key of the value to update
+	 * @param updater - A function that receives the current value and returns the new value
+	 * @throws Error if the key doesn't exist in the map
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * map.set('count', 5)
+	 * map.update('count', count => count + 1) // count is now 6
+	 * ```
+	 */
 	update(key: K, updater: (value: V) => V) {
 		const valueAtom = this.atoms.__unsafe__getWithoutCapture().get(key)
 		if (!valueAtom) {
@@ -86,6 +187,19 @@ export class AtomMap<K, V> implements Map<K, V> {
 		valueAtom.set(updater(value))
 	}
 
+	/**
+	 * Removes a key-value pair from the map.
+	 *
+	 * @param key - The key to remove
+	 * @returns True if the key existed and was removed, false if it didn't exist
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * map.set('temp', 'value')
+	 * console.log(map.delete('temp')) // true
+	 * console.log(map.delete('missing')) // false
+	 * ```
+	 */
 	delete(key: K) {
 		const valueAtom = this.atoms.__unsafe__getWithoutCapture().get(key)
 		if (!valueAtom) {
@@ -101,6 +215,19 @@ export class AtomMap<K, V> implements Map<K, V> {
 		return true
 	}
 
+	/**
+	 * Removes multiple key-value pairs from the map in a single transaction.
+	 *
+	 * @param keys - An iterable of keys to remove
+	 * @returns An array of [key, value] pairs that were actually deleted
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * map.set('a', 1).set('b', 2).set('c', 3)
+	 * const deleted = map.deleteMany(['a', 'c', 'missing'])
+	 * console.log(deleted) // [['a', 1], ['c', 3]]
+	 * ```
+	 */
 	deleteMany(keys: Iterable<K>): [K, V][] {
 		return transact(() => {
 			const deleted: [K, V][] = []
@@ -126,6 +253,17 @@ export class AtomMap<K, V> implements Map<K, V> {
 		})
 	}
 
+	/**
+	 * Removes all key-value pairs from the map.
+	 *
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * map.set('a', 1).set('b', 2)
+	 * map.clear()
+	 * console.log(map.size) // 0
+	 * ```
+	 */
 	clear() {
 		return transact(() => {
 			for (const valueAtom of this.atoms.__unsafe__getWithoutCapture().values()) {
@@ -135,6 +273,20 @@ export class AtomMap<K, V> implements Map<K, V> {
 		})
 	}
 
+	/**
+	 * Returns an iterator that yields [key, value] pairs for each entry in the map.
+	 * This method is reactive and will cause reactive contexts to update when entries change.
+	 *
+	 * @returns A generator that yields [key, value] tuples
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * map.set('a', 1).set('b', 2)
+	 * for (const [key, value] of map.entries()) {
+	 *   console.log(`${key}: ${value}`)
+	 * }
+	 * ```
+	 */
 	*entries(): Generator<[K, V], undefined, unknown> {
 		for (const [key, valueAtom] of this.atoms.get()) {
 			const value = valueAtom.get()
@@ -143,12 +295,40 @@ export class AtomMap<K, V> implements Map<K, V> {
 		}
 	}
 
+	/**
+	 * Returns an iterator that yields all keys in the map.
+	 * This method is reactive and will cause reactive contexts to update when keys change.
+	 *
+	 * @returns A generator that yields keys
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * map.set('name', 'Alice').set('age', 30)
+	 * for (const key of map.keys()) {
+	 *   console.log(key) // 'name', 'age'
+	 * }
+	 * ```
+	 */
 	*keys(): Generator<K, undefined, unknown> {
 		for (const key of this.atoms.get().keys()) {
 			yield key
 		}
 	}
 
+	/**
+	 * Returns an iterator that yields all values in the map.
+	 * This method is reactive and will cause reactive contexts to update when values change.
+	 *
+	 * @returns A generator that yields values
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * map.set('name', 'Alice').set('age', 30)
+	 * for (const value of map.values()) {
+	 *   console.log(value) // 'Alice', 30
+	 * }
+	 * ```
+	 */
 	*values(): Generator<V, undefined, unknown> {
 		for (const valueAtom of this.atoms.get().values()) {
 			const value = valueAtom.get()
@@ -157,20 +337,80 @@ export class AtomMap<K, V> implements Map<K, V> {
 		}
 	}
 
+	/**
+	 * The number of key-value pairs in the map.
+	 * This property is reactive and will cause reactive contexts to update when the size changes.
+	 *
+	 * @returns The number of entries in the map
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * console.log(map.size) // 0
+	 * map.set('a', 1)
+	 * console.log(map.size) // 1
+	 * ```
+	 */
 	// eslint-disable-next-line no-restricted-syntax
 	get size() {
 		return this.atoms.get().size
 	}
 
+	/**
+	 * Executes a provided function once for each key-value pair in the map.
+	 * This method is reactive and will cause reactive contexts to update when entries change.
+	 *
+	 * @param callbackfn - Function to execute for each entry
+	 *   - value - The value of the current entry
+	 *   - key - The key of the current entry
+	 *   - map - The AtomMap being traversed
+	 * @param thisArg - Value to use as `this` when executing the callback
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * map.set('a', 1).set('b', 2)
+	 * map.forEach((value, key) => {
+	 *   console.log(`${key} = ${value}`)
+	 * })
+	 * ```
+	 */
 	forEach(callbackfn: (value: V, key: K, map: AtomMap<K, V>) => void, thisArg?: any): void {
 		for (const [key, value] of this.entries()) {
 			callbackfn.call(thisArg, value, key, this)
 		}
 	}
 
+	/**
+	 * Returns the default iterator for the map, which is the same as entries().
+	 * This allows the map to be used in for...of loops and other iterable contexts.
+	 *
+	 * @returns The same iterator as entries()
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * map.set('a', 1).set('b', 2)
+	 *
+	 * // These are equivalent:
+	 * for (const [key, value] of map) {
+	 *   console.log(`${key}: ${value}`)
+	 * }
+	 *
+	 * for (const [key, value] of map.entries()) {
+	 *   console.log(`${key}: ${value}`)
+	 * }
+	 * ```
+	 */
 	[Symbol.iterator]() {
 		return this.entries()
 	}
 
+	/**
+	 * The string tag used by Object.prototype.toString for this class.
+	 *
+	 * @example
+	 * ```ts
+	 * const map = new AtomMap('myMap')
+	 * console.log(Object.prototype.toString.call(map)) // '[object AtomMap]'
+	 * ```
+	 */
 	[Symbol.toStringTag] = 'AtomMap'
 }

package/src/lib/BaseRecord.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+import { isRecord } from './BaseRecord'
+
+describe('isRecord function', () => {
+	it('should return true for valid records', () => {
+		const validRecord = {
+			id: 'book:123',
+			typeName: 'book',
+			title: '1984',
+		}
+
+		expect(isRecord(validRecord)).toBe(true)
+	})
+
+	it('should return false for null and undefined', () => {
+		expect(isRecord(null)).toBe(false)
+		expect(isRecord(undefined)).toBe(false)
+	})
+
+	it('should return false for primitive types', () => {
+		expect(isRecord('string')).toBe(false)
+		expect(isRecord(42)).toBe(false)
+		expect(isRecord(true)).toBe(false)
+	})
+
+	it('should return false for objects missing required properties', () => {
+		expect(isRecord({})).toBe(false)
+		expect(isRecord({ id: 'test' })).toBe(false)
+		expect(isRecord({ typeName: 'test' })).toBe(false)
+	})
+
+	it('should work as type guard', () => {
+		const unknownValue: unknown = {
+			id: 'book:123',
+			typeName: 'book',
+			title: '1984',
+		}
+
+		if (isRecord(unknownValue)) {
+			expect(unknownValue.id).toBe('book:123')
+			expect(unknownValue.typeName).toBe('book')
+		}
+	})
+})

package/src/lib/BaseRecord.ts

@@ -1,11 +1,78 @@
-/** @public */
+/**
+ * A branded string type that represents a unique identifier for a record.
+ * The brand ensures type safety by preventing mixing of IDs between different record types.
+ *
+ * @example
+ * ```ts
+ * // Define a Book record
+ * interface Book extends BaseRecord<'book', RecordId<Book>> {
+ *   title: string
+ *   author: string
+ * }
+ *
+ * const bookId: RecordId<Book> = 'book:abc123' as RecordId<Book>
+ * const authorId: RecordId<Author> = 'author:xyz789' as RecordId<Author>
+ *
+ * // TypeScript prevents mixing different record ID types
+ * // bookId = authorId // Type error!
+ * ```
+ *
+ * @public
+ */
 export type RecordId<R extends UnknownRecord> = string & { __type__: R }
 
-/** @public */
+/**
+ * Utility type that extracts the ID type from a record type.
+ * This is useful when you need to work with record IDs without having the full record type.
+ *
+ * @example
+ * ```ts
+ * interface Book extends BaseRecord<'book', RecordId<Book>> {
+ *   title: string
+ *   author: string
+ * }
+ *
+ * // Extract the ID type from the Book record
+ * type BookId = IdOf<Book> // RecordId<Book>
+ *
+ * function findBook(id: IdOf<Book>): Book | undefined {
+ *   return store.get(id)
+ * }
+ * ```
+ *
+ * @public
+ */
 export type IdOf<R extends UnknownRecord> = R['id']
 
 /**
- * The base record that all records must extend.
+ * The base record interface that all records in the store must extend.
+ * This interface provides the fundamental structure required for all records: a unique ID and a type name.
+ * The type parameters ensure type safety and prevent mixing of different record types.
+ *
+ * @example
+ * ```ts
+ * // Define a Book record that extends BaseRecord
+ * interface Book extends BaseRecord<'book', RecordId<Book>> {
+ *   title: string
+ *   author: string
+ *   publishedYear: number
+ * }
+ *
+ * // Define an Author record
+ * interface Author extends BaseRecord<'author', RecordId<Author>> {
+ *   name: string
+ *   birthYear: number
+ * }
+ *
+ * // Usage with RecordType
+ * const Book = createRecordType<Book>('book', { scope: 'document' })
+ * const book = Book.create({
+ *   title: '1984',
+ *   author: 'George Orwell',
+ *   publishedYear: 1949
+ * })
+ * // Results in: { id: 'book:abc123', typeName: 'book', title: '1984', ... }
+ * ```
  *
  * @public
  */
@@ -14,9 +81,56 @@ export interface BaseRecord<TypeName extends string, Id extends RecordId<Unknown
 	readonly typeName: TypeName
 }
 
-/** @public */
+/**
+ * A generic type representing any record that extends BaseRecord.
+ * This is useful for type constraints when you need to work with records of unknown types,
+ * but still want to ensure they follow the BaseRecord structure.
+ *
+ * @example
+ * ```ts
+ * // Function that works with any type of record
+ * function logRecord(record: UnknownRecord): void {
+ *   console.log(`Record ${record.id} of type ${record.typeName}`)
+ * }
+ *
+ * // Can be used with any record type
+ * const book: Book = { id: 'book:123' as RecordId<Book>, typeName: 'book', title: '1984' }
+ * const author: Author = { id: 'author:456' as RecordId<Author>, typeName: 'author', name: 'Orwell' }
+ *
+ * logRecord(book)   // "Record book:123 of type book"
+ * logRecord(author) // "Record author:456 of type author"
+ * ```
+ *
+ * @public
+ */
 export type UnknownRecord = BaseRecord<string, RecordId<UnknownRecord>>
 
+/**
+ * Type guard function that checks if an unknown value is a valid record.
+ * A valid record must be an object with both `id` and `typeName` properties.
+ *
+ * @param record - The unknown value to check
+ * @returns `true` if the value is a valid UnknownRecord, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * const maybeRecord: unknown = { id: 'book:123', typeName: 'book', title: '1984' }
+ * const notARecord: unknown = { title: '1984', author: 'Orwell' }
+ * const nullValue: unknown = null
+ *
+ * if (isRecord(maybeRecord)) {
+ *   // TypeScript now knows maybeRecord is UnknownRecord
+ *   console.log(maybeRecord.id) // 'book:123'
+ *   console.log(maybeRecord.typeName) // 'book'
+ * }
+ *
+ * console.log(isRecord(maybeRecord)) // true
+ * console.log(isRecord(notARecord))  // false (missing id and typeName)
+ * console.log(isRecord(nullValue))   // false
+ * ```
+ *
+ * @public
+ */
 export function isRecord(record: unknown): record is UnknownRecord {
 	return typeof record === 'object' && record !== null && 'id' in record && 'typeName' in record
 }

package/src/lib/ImmutableMap.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest'
+import { ImmutableMap, emptyMap } from './ImmutableMap'
+
+describe('ImmutableMap', () => {
+	describe('constructor', () => {
+		it('should handle duplicate keys by keeping last value', () => {
+			const pairs: Array<[string, number]> = [
+				['a', 1],
+				['a', 2],
+				['a', 3],
+			]
+			const map = new ImmutableMap(pairs)
+			expect(map.size).toBe(1)
+			expect(map.get('a')).toBe(3)
+		})
+	})
+
+	describe('get', () => {
+		it('should handle object keys', () => {
+			const objKey = { id: 1 }
+			const map = new ImmutableMap([[objKey, 'object']])
+			expect(map.get(objKey)).toBe('object')
+			expect(map.get({ id: 1 })).toBeUndefined() // Different object
+		})
+	})
+
+	describe('set', () => {
+		it('should create new map with updated value', () => {
+			const map = new ImmutableMap([['key', 'value']])
+			const newMap = map.set('key', 'newValue')
+
+			expect(newMap.get('key')).toBe('newValue')
+			expect(map.get('key')).toBe('value') // Original unchanged
+		})
+
+		it('should handle different object keys correctly', () => {
+			const obj1 = { id: 1 }
+			const obj2 = { id: 2 }
+
+			let map = new ImmutableMap()
+			map = map.set(obj1, 'first')
+			map = map.set(obj2, 'second')
+
+			expect(map.size).toBe(2)
+			expect(map.get(obj1)).toBe('first')
+			expect(map.get(obj2)).toBe('second')
+		})
+	})
+
+	describe('delete', () => {
+		it('should remove existing keys', () => {
+			const map = new ImmutableMap([
+				['a', 1],
+				['b', 2],
+			])
+			const newMap = map.delete('a')
+
+			expect(newMap.size).toBe(1)
+			expect(newMap.get('a')).toBeUndefined()
+			expect(newMap.get('b')).toBe(2)
+		})
+	})
+
+	describe('deleteAll', () => {
+		it('should remove multiple keys', () => {
+			const map = new ImmutableMap([
+				['a', 1],
+				['b', 2],
+				['c', 3],
+			])
+			const newMap = map.deleteAll(['a', 'c'])
+
+			expect(newMap.size).toBe(1)
+			expect(newMap.get('a')).toBeUndefined()
+			expect(newMap.get('b')).toBe(2)
+			expect(newMap.get('c')).toBeUndefined()
+		})
+	})
+
+	describe('withMutations', () => {
+		it('should allow efficient batch operations', () => {
+			const map = new ImmutableMap([['a', 1]])
+			const newMap = map.withMutations((mutable) => {
+				mutable.set('b', 2)
+				mutable.set('c', 3)
+				mutable.delete('a')
+			})
+
+			expect(newMap.size).toBe(2)
+			expect(newMap.get('a')).toBeUndefined()
+			expect(newMap.get('b')).toBe(2)
+			expect(newMap.get('c')).toBe(3)
+		})
+	})
+})
+
+describe('emptyMap', () => {
+	it('should create empty map with zero size', () => {
+		const empty = emptyMap()
+		expect(empty.size).toBe(0)
+		expect(empty.get('anything')).toBeUndefined()
+	})
+})