@tldraw/store 5.2.0-next.e2b8d10bf10e → 5.2.0

package/src/lib/ImmutableMap.test.ts

@@ -1,101 +1,144 @@
 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)
-		})
+// Tests for SPEC.md §27 (ImmutableMap, internal).
+// Rule IDs like [IM1] in test names refer to that document.
+
+describe('ImmutableMap (IM)', () => {
+	it('[IM1] set returns a new map and leaves the original unchanged', () => {
+		const map = new ImmutableMap([['key', 'value']])
+		const newMap = map.set('key', 'newValue')
+
+		expect(newMap.get('key')).toBe('newValue')
+		expect(map.get('key')).toBe('value')
+
+		const withExtra = map.set('other', 'x')
+		expect(withExtra.size).toBe(2)
+		expect(map.size).toBe(1)
 	})
 
-	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
-		})
+	it('[IM1] delete returns a new map without the key, leaving the original unchanged', () => {
+		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)
+
+		expect(map.size).toBe(2)
+		expect(map.get('a')).toBe(1)
 	})
 
-	describe('set', () => {
-		it('should create new map with updated value', () => {
-			const map = new ImmutableMap([['key', 'value']])
-			const newMap = map.set('key', 'newValue')
+	it('[IM2] get returns the value, undefined for missing keys, or the given notSetValue', () => {
+		const map = new ImmutableMap([['a', 1]])
 
-			expect(newMap.get('key')).toBe('newValue')
-			expect(map.get('key')).toBe('value') // Original unchanged
-		})
+		expect(map.get('a')).toBe(1)
+		expect(map.get('missing')).toBeUndefined()
+		expect(map.get('missing', 42)).toBe(42)
+		expect(map.get('a', 42)).toBe(1)
+	})
 
-		it('should handle different object keys correctly', () => {
-			const obj1 = { id: 1 }
-			const obj2 = { id: 2 }
+	it('[IM3] object keys are hashed by identity', () => {
+		const obj1 = { id: 1 }
+		const obj2 = { id: 2 }
 
-			let map = new ImmutableMap()
-			map = map.set(obj1, 'first')
-			map = map.set(obj2, 'second')
+		let map = new ImmutableMap<{ id: number }, string>()
+		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')
-		})
+		expect(map.size).toBe(2)
+		expect(map.get(obj1)).toBe('first')
+		expect(map.get(obj2)).toBe('second')
+		expect(map.get({ id: 1 })).toBeUndefined() // structurally equal, but a different key
 	})
 
-	describe('delete', () => {
-		it('should remove existing keys', () => {
-			const map = new ImmutableMap([
-				['a', 1],
-				['b', 2],
-			])
-			const newMap = map.delete('a')
+	it('[IM3] a constructor given duplicate keys keeps the last value', () => {
+		const map = new ImmutableMap([
+			['a', 1],
+			['a', 2],
+			['a', 3],
+		])
+		expect(map.size).toBe(1)
+		expect(map.get('a')).toBe(3)
+	})
 
-			expect(newMap.size).toBe(1)
-			expect(newMap.get('a')).toBeUndefined()
-			expect(newMap.get('b')).toBe(2)
+	it('[IM4] withMutations batches changes into one new map', () => {
+		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)
+
+		expect(map.size).toBe(1)
+		expect(map.get('a')).toBe(1)
+	})
+
+	it('[IM4] withMutations that changes nothing returns the same instance', () => {
+		const map = new ImmutableMap([['a', 1]])
+		const same = map.withMutations(() => {})
+		expect(same).toBe(map)
 	})
 
-	describe('deleteAll', () => {
-		it('should remove multiple keys', () => {
-			const map = new ImmutableMap([
+	it('[IM5] deleteAll removes all the given keys', () => {
+		const map = new ImmutableMap([
+			['a', 1],
+			['b', 2],
+			['c', 3],
+		])
+		const newMap = map.deleteAll(['a', 'c', 'missing'])
+
+		expect(newMap.size).toBe(1)
+		expect(newMap.get('a')).toBeUndefined()
+		expect(newMap.get('b')).toBe(2)
+		expect(newMap.get('c')).toBeUndefined()
+	})
+
+	it('[IM6] entries, keys, values, and iteration yield every entry exactly once', () => {
+		const map = new ImmutableMap([
+			['a', 1],
+			['b', 2],
+			['c', 3],
+		])
+
+		const entries = Array.from(map.entries())
+		expect(entries.length).toBe(map.size)
+		expect(new Map(entries)).toEqual(
+			new Map([
 				['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()
-		})
+		expect(new Set(map.keys())).toEqual(new Set(['a', 'b', 'c']))
+		expect([...map.values()].sort()).toEqual([1, 2, 3])
+		expect(Array.from(map)).toEqual(entries)
 	})
 
-	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)
-		})
+	it('[IM6] handles many entries consistently (trie depth)', () => {
+		let map = new ImmutableMap<number, number>()
+		for (let i = 0; i < 200; i++) {
+			map = map.set(i, i * 2)
+		}
+		expect(map.size).toBe(200)
+		for (let i = 0; i < 200; i++) {
+			expect(map.get(i)).toBe(i * 2)
+		}
+		expect(Array.from(map.entries()).length).toBe(200)
 	})
 })
 
-describe('emptyMap', () => {
-	it('should create empty map with zero size', () => {
+describe('emptyMap (IM)', () => {
+	it('[IM2] emptyMap has zero size and returns undefined for any key', () => {
 		const empty = emptyMap()
 		expect(empty.size).toBe(0)
 		expect(empty.get('anything')).toBeUndefined()

package/src/lib/ImmutableMap.ts

@@ -273,6 +273,7 @@ export class ImmutableMap<K, V> {
 	 * console.log(map.get('missing', 'default')) // 'default'
 	 * ```
 	 */
+	get(k: K, notSetValue: V): V
 	get(k: K, notSetValue?: V): V {
 		return this._root ? this._root.get(0, undefined as any, k, notSetValue)! : notSetValue!
 	}

package/src/lib/IncrementalSetConstructor.test.ts

@@ -1,111 +1,106 @@
 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)
+// Tests for SPEC.md §26 (IncrementalSetConstructor, internal).
+// Rule IDs like [ISC1] in test names refer to that document.
 
-			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')
+describe('IncrementalSetConstructor (ISC)', () => {
+	it('[ISC1] get returns undefined when nothing was done', () => {
+		const constructor = new IncrementalSetConstructor(new Set(['a', 'b', 'c']))
+		expect(constructor.get()).toBeUndefined()
+	})
 
-			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('[ISC1] adding already-present items is a no-op', () => {
+		const constructor = new IncrementalSetConstructor(new Set(['a', 'b', 'c']))
+		constructor.add('a')
+		constructor.add('b')
+		expect(constructor.get()).toBeUndefined()
+	})
 
-		it('should return correct result when items are removed', () => {
-			const originalSet = new Set(['a', 'b', 'c', 'd'])
-			const constructor = new IncrementalSetConstructor(originalSet)
+	it('[ISC1] removing absent items is a no-op', () => {
+		const constructor = new IncrementalSetConstructor(new Set(['a', 'b']))
+		constructor.remove('c')
+		constructor.remove('d')
+		expect(constructor.get()).toBeUndefined()
+	})
 
-			constructor.remove('c')
-			constructor.remove('d')
+	it('[ISC1] add/remove round trips cancel out', () => {
+		const constructor = new IncrementalSetConstructor(new Set(['a', 'b', 'c']))
+		constructor.add('d')
+		constructor.remove('d')
+		expect(constructor.get()).toBeUndefined()
 
-			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()
-		})
+		const constructor2 = new IncrementalSetConstructor(new Set(['a', 'b', 'c']))
+		constructor2.remove('a')
+		constructor2.add('a')
+		expect(constructor2.get()).toBeUndefined()
+	})
 
-		it('should handle mixed add and remove operations correctly', () => {
-			const originalSet = new Set(['a', 'b', 'c'])
-			const constructor = new IncrementalSetConstructor(originalSet)
+	it('[ISC2] additions produce the new set and an added diff', () => {
+		const original = new Set(['a', 'b'])
+		const constructor = new IncrementalSetConstructor(original)
 
-			constructor.remove('a')
-			constructor.add('d')
-			constructor.add('e')
+		constructor.add('c')
+		constructor.add('d')
 
-			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']))
+		expect(constructor.get()).toEqual({
+			value: new Set(['a', 'b', 'c', 'd']),
+			diff: { added: new Set(['c', 'd']) },
 		})
+		expect(original).toEqual(new Set(['a', 'b']))
+	})
 
-		it('should handle adding existing items as no-op', () => {
-			const originalSet = new Set(['a', 'b', 'c'])
-			const constructor = new IncrementalSetConstructor(originalSet)
+	it('[ISC2] removals produce the new set and a removed diff', () => {
+		const original = new Set(['a', 'b', 'c', 'd'])
+		const constructor = new IncrementalSetConstructor(original)
 
-			constructor.add('a')
-			constructor.add('b')
+		constructor.remove('c')
+		constructor.remove('d')
 
-			const result = constructor.get()
-			expect(result).toBeUndefined()
+		expect(constructor.get()).toEqual({
+			value: new Set(['a', 'b']),
+			diff: { removed: new Set(['c', 'd']) },
 		})
+		expect(original).toEqual(new Set(['a', 'b', 'c', 'd']))
+	})
 
-		it('should handle complex restore and cancel scenarios', () => {
-			const originalSet = new Set(['a', 'b', 'c'])
-			const constructor = new IncrementalSetConstructor(originalSet)
+	it('[ISC2] mixed adds and removes report both sides of the diff', () => {
+		const constructor = new IncrementalSetConstructor(new Set(['a', 'b', 'c']))
 
-			constructor.remove('a')
-			constructor.remove('b')
-			constructor.add('d')
-			constructor.add('a') // Restore one removed item
+		constructor.remove('a')
+		constructor.add('d')
+		constructor.add('e')
 
-			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']))
+		expect(constructor.get()).toEqual({
+			value: new Set(['b', 'c', 'd', 'e']),
+			diff: { added: new Set(['d', 'e']), removed: new Set(['a']) },
 		})
+	})
 
-		it('should handle removing non-existent items as no-op', () => {
-			const originalSet = new Set(['a', 'b'])
-			const constructor = new IncrementalSetConstructor(originalSet)
+	it('[ISC3] re-adding a removed item restores it', () => {
+		const constructor = new IncrementalSetConstructor(new Set(['a', 'b', 'c']))
 
-			constructor.remove('c')
-			constructor.remove('d')
+		constructor.remove('a')
+		constructor.remove('b')
+		constructor.add('d')
+		constructor.add('a') // restore one removed item
 
-			const result = constructor.get()
-			expect(result).toBeUndefined()
+		expect(constructor.get()).toEqual({
+			value: new Set(['a', 'c', 'd']),
+			diff: { added: new Set(['d']), removed: new Set(['b']) },
 		})
+	})
 
-		it('should remove recently added items correctly', () => {
-			const originalSet = new Set(['a', 'b'])
-			const constructor = new IncrementalSetConstructor(originalSet)
+	it('[ISC3] removing an item added earlier cancels the add', () => {
+		const constructor = new IncrementalSetConstructor(new Set(['a', 'b']))
 
-			constructor.add('c')
-			constructor.add('d')
-			constructor.remove('c') // Remove recently added item
+		constructor.add('c')
+		constructor.add('d')
+		constructor.remove('c')
 
-			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()
+		expect(constructor.get()).toEqual({
+			value: new Set(['a', 'b', 'd']),
+			diff: { added: new Set(['d']) },
 		})
 	})
 })

package/src/lib/RecordType.test.ts

@@ -0,0 +1,216 @@
+import { describe, expect, it } from 'vitest'
+import { BaseRecord, RecordId } from './BaseRecord'
+import { assertIdType, createRecordType, RecordType } from './RecordType'
+
+// Tests for SPEC.md §2 (records) and §3 (RecordType).
+// Rule IDs like [RT2] in test names refer to that document.
+
+interface Author extends BaseRecord<'author', RecordId<Author>> {
+	name: string
+	living: boolean
+	age: number
+}
+
+interface Book extends BaseRecord<'book', RecordId<Book>> {
+	title: string
+}
+
+const Author = createRecordType<Author>('author', { scope: 'document' }).withDefaultProperties(
+	() => ({ living: true, age: 35 })
+)
+
+const Book = createRecordType<Book>('book', { scope: 'document' })
+
+describe('creating record types (RT)', () => {
+	it('[RT1] createRecordType uses the given scope and defaults to pass-through validation', () => {
+		const Session = createRecordType('session', { scope: 'session' })
+		expect(Session.scope).toBe('session')
+
+		const anything = { id: 'session:1', typeName: 'session', whatever: NaN }
+		expect(Session.validator.validate(anything)).toBe(anything)
+	})
+
+	it('[RT1] the RecordType constructor defaults scope to document', () => {
+		const type = new RecordType<Book, never>('book', {
+			createDefaultProperties: () => ({}) as any,
+		})
+		expect(type.scope).toBe('document')
+	})
+
+	it('[RT1] createRecordType uses the given validator', () => {
+		const validator = {
+			validate: (r: unknown) => {
+				if ((r as Book).title === 'invalid') throw new Error('bad')
+				return r as Book
+			},
+		}
+		const Strict = createRecordType<Book>('book', { scope: 'document', validator })
+		expect(() => Strict.validate({ title: 'invalid' })).toThrow('bad')
+		const ok = { id: 'book:1', typeName: 'book', title: 'fine' }
+		expect(Strict.validate(ok)).toBe(ok)
+	})
+
+	it('[RT9] ephemeralKeySet contains exactly the keys mapped to true', () => {
+		const WithEphemeral = createRecordType<Author>('author', {
+			scope: 'document',
+			ephemeralKeys: { name: false, living: true, age: true },
+		})
+		expect(WithEphemeral.ephemeralKeySet).toEqual(new Set(['living', 'age']))
+
+		expect(Author.ephemeralKeySet).toEqual(new Set())
+	})
+})
+
+describe('creating records (RT)', () => {
+	it('[RT2] create merges defaults with the given props', () => {
+		const author = Author.create({ name: 'Le Guin' })
+		expect(author).toEqual({
+			id: author.id,
+			typeName: 'author',
+			name: 'Le Guin',
+			living: true,
+			age: 35,
+		})
+
+		const dead = Author.create({ name: 'Tolstoy', living: false })
+		expect(dead.living).toBe(false)
+	})
+
+	it('[RT2] undefined prop values do not override defaults', () => {
+		const author = Author.create({ name: 'Le Guin', living: undefined })
+		expect(author.living).toBe(true)
+	})
+
+	it('[RT3] create uses the given id, else generates one', () => {
+		const id = Author.createId('ursula')
+		expect(Author.create({ name: 'Le Guin', id }).id).toBe(id)
+
+		const generated = Author.create({ name: 'Le Guin' })
+		expect(generated.id).toMatch(/^author:/)
+	})
+
+	it('[RT3] an explicitly undefined id is treated as absent', () => {
+		const author = Author.create({ name: 'Le Guin', id: undefined })
+		expect(author.id).toMatch(/^author:/)
+	})
+
+	it('[R2] [RT3] createId returns typeName:uniquePart, honoring a custom part', () => {
+		expect(Author.createId('123')).toBe('author:123')
+		expect(Book.createId('xyz')).toBe('book:xyz')
+
+		const a = Author.createId()
+		const b = Author.createId()
+		expect(a).toMatch(/^author:/)
+		expect(a).not.toBe(b)
+	})
+
+	it('[RT4] clone deep-clones the record and assigns a fresh id', () => {
+		const Nested = createRecordType<Book & { props: { tags: string[] } }>('book', {
+			scope: 'document',
+		})
+		const original = Nested.create({ title: '1984', props: { tags: ['dystopia'] } })
+		const copy = Nested.clone(original)
+
+		expect(copy.id).not.toBe(original.id)
+		expect(copy.title).toBe(original.title)
+		expect(copy.props).toEqual(original.props)
+		expect(copy.props).not.toBe(original.props)
+	})
+})
+
+describe('ids and type guards (RT)', () => {
+	it('[RT5] parseId returns the part after the colon and throws for other types', () => {
+		expect(Author.parseId('author:123' as any)).toBe('123')
+		expect(Book.parseId('book:xyz' as any)).toBe('xyz')
+
+		expect(() => Author.parseId('book:123' as any)).toThrow()
+		expect(() => Book.parseId('author:xyz' as any)).toThrow()
+	})
+
+	it('[RT5] isId is true exactly for ids starting with typeName:', () => {
+		expect(Author.isId('author:123')).toBe(true)
+		expect(Author.isId('book:123')).toBe(false)
+		expect(Author.isId('author')).toBe(false)
+		expect(Author.isId('authors:123')).toBe(false)
+		expect(Author.isId('')).toBe(false)
+		expect(Author.isId(undefined)).toBe(false)
+	})
+
+	it('[RT5] isInstance checks the typeName', () => {
+		const author = Author.create({ name: 'Le Guin' })
+		const book = Book.create({ title: '1984' })
+
+		expect(Author.isInstance(author)).toBe(true)
+		expect(Author.isInstance(book)).toBe(false)
+		expect(Author.isInstance(undefined)).toBe(false)
+	})
+
+	it('[RT6] assertIdType throws for invalid ids and passes for valid ones', () => {
+		expect(() => assertIdType(Author.createId('ok'), Author)).not.toThrow()
+
+		expect(() => assertIdType(undefined, Author)).toThrow()
+		expect(() => assertIdType('', Author)).toThrow()
+		expect(() => assertIdType('book:123', Author)).toThrow()
+	})
+})
+
+describe('extending and validating (RT)', () => {
+	it('[RT7] withDefaultProperties keeps the type name, validator, scope, and ephemeral keys', () => {
+		const validator = { validate: (r: unknown) => r as Author }
+		const base = createRecordType<Author>('author', {
+			scope: 'presence',
+			validator,
+			ephemeralKeys: { name: false, living: false, age: true },
+		})
+		const extended = base.withDefaultProperties(() => ({ living: false }))
+
+		expect(extended.typeName).toBe('author')
+		expect(extended.scope).toBe('presence')
+		expect(extended.validator).toBe(validator)
+		expect(extended.ephemeralKeys).toBe(base.ephemeralKeys)
+		expect(extended.ephemeralKeySet).toEqual(new Set(['age']))
+
+		const author = extended.create({ name: 'Woolf', age: 59 })
+		expect(author.living).toBe(false)
+	})
+
+	it('[RT8] validate uses validateUsingKnownGoodVersion when a previous record is given', () => {
+		const calls: string[] = []
+		const Tracked = createRecordType<Book>('book', {
+			scope: 'document',
+			validator: {
+				validate: (r) => {
+					calls.push('validate')
+					return r as Book
+				},
+				validateUsingKnownGoodVersion: (_prev, r) => {
+					calls.push('validateUsingKnownGoodVersion')
+					return r as Book
+				},
+			},
+		})
+		const book = Tracked.create({ title: '1984' })
+
+		Tracked.validate({ ...book, title: 'Animal Farm' })
+		expect(calls).toEqual(['validate'])
+
+		Tracked.validate({ ...book, title: 'Animal Farm' }, book)
+		expect(calls).toEqual(['validate', 'validateUsingKnownGoodVersion'])
+	})
+
+	it('[RT8] validate falls back to validate when validateUsingKnownGoodVersion is absent', () => {
+		const calls: string[] = []
+		const Plain = createRecordType<Book>('book', {
+			scope: 'document',
+			validator: {
+				validate: (r) => {
+					calls.push('validate')
+					return r as Book
+				},
+			},
+		})
+		const book = Plain.create({ title: '1984' })
+		Plain.validate({ ...book }, book)
+		expect(calls).toEqual(['validate'])
+	})
+})

package/src/lib/RecordType.ts

@@ -135,7 +135,7 @@ export class RecordType<
 	): R {
 		const result = {
 			...this.createDefaultProperties(),
-			id: 'id' in properties ? properties.id : this.createId(),
+			id: (properties as Partial<R>).id ?? this.createId(),
 		} as any
 
 		for (const [k, v] of Object.entries(properties)) {