@tldraw/state 5.1.0 → 5.2.0-canary.019da1aa690a

package/src/lib/__tests__/atom.test.ts

@@ -1,199 +1,203 @@
 import { atom } from '../Atom'
-import { reactor } from '../EffectScheduler'
-import { getGlobalEpoch, transact, transaction } from '../transactions'
-import { RESET_VALUE } from '../types'
+import { computed } from '../Computed'
+import { react } from '../EffectScheduler'
+import { getGlobalEpoch } from '../transactions'
 
-describe('atoms', () => {
-	it('contain data', () => {
-		const a = atom('', 1)
+// Tests for SPEC.md §2 (the epoch clock), §3 (equality), and §4 (atoms).
+// Rule IDs like [EP3] in test names refer to that document.
 
-		expect(a.get()).toBe(1)
-	})
-	it('can be updated', () => {
-		const a = atom('', 1)
+describe('the epoch clock (EP)', () => {
+	it('[EP1] is shared by all atoms', () => {
+		const startEpoch = getGlobalEpoch()
+		const a = atom('a', 1)
+		const b = atom('b', 1)
 
 		a.set(2)
+		expect(getGlobalEpoch()).toBe(startEpoch + 1)
 
-		expect(a.get()).toBe(2)
+		b.set(2)
+		expect(getGlobalEpoch()).toBe(startEpoch + 2)
 	})
-	it('will not advance the global epoch on creation', () => {
+
+	it('[EP2] does not advance when signals are created', () => {
 		const startEpoch = getGlobalEpoch()
-		atom('', 3)
+		atom('a', 3)
+		computed('c', () => 1)
 		expect(getGlobalEpoch()).toBe(startEpoch)
 	})
-	it('will advance the global epoch on .set', () => {
+
+	it('[EP3] advances by exactly one when an atom is set to a new value', () => {
 		const startEpoch = getGlobalEpoch()
-		const a = atom('', 3)
+		const a = atom('a', 3)
 		a.set(4)
 		expect(getGlobalEpoch()).toBe(startEpoch + 1)
 	})
-	it('can store history', () => {
-		const a = atom('', 1, { historyLength: 3, computeDiff: (a, b) => b - a })
 
+	it('[EP4] does not advance when an atom is set to an equal value', () => {
+		const a = atom('a', 3)
 		const startEpoch = getGlobalEpoch()
+		a.set(3)
+		expect(getGlobalEpoch()).toBe(startEpoch)
+	})
 
-		expect(a.getDiffSince(startEpoch)).toEqual([])
+	it('[EP5] is recorded on the atom as lastChangedEpoch when it changes', () => {
+		const a = atom('a', 1)
 
-		a.set(5)
+		a.set(2)
+		const changedEpoch = getGlobalEpoch()
+		expect(a.lastChangedEpoch).toBe(changedEpoch)
 
-		expect(a.getDiffSince(startEpoch)).toEqual([+4])
+		// other atoms changing does not move this atom's lastChangedEpoch
+		const b = atom('b', 1)
+		b.set(2)
+		expect(a.lastChangedEpoch).toBe(changedEpoch)
+	})
+})
 
-		a.set(10)
+describe('equality (EQ)', () => {
+	it('[EQ1] treats === and Object.is values as equal by default', () => {
+		const value = { hello: true }
+		const a = atom('a', value)
+		const startEpoch = getGlobalEpoch()
 
-		expect(a.getDiffSince(startEpoch)).toEqual([+4, +5])
+		a.set(value)
+		expect(getGlobalEpoch()).toBe(startEpoch)
 
-		a.set(20)
+		const n = atom('n', NaN)
+		n.set(NaN)
+		expect(getGlobalEpoch()).toBe(startEpoch)
+	})
 
-		expect(a.getDiffSince(startEpoch)).toEqual([+4, +5, +10])
+	it('[EQ1] consults the old value’s equals method by default', () => {
+		class Box {
+			constructor(public value: number) {}
+			equals(other: unknown) {
+				return other instanceof Box && other.value === this.value
+			}
+		}
 
-		a.set(30)
+		const original = new Box(1)
+		const a = atom('a', original)
 
-		// will be RESET_VALUE because we don't have enough history
-		expect(a.getDiffSince(startEpoch)).toEqual(RESET_VALUE)
+		a.set(new Box(1))
+		expect(a.get()).toBe(original)
+
+		const different = new Box(2)
+		a.set(different)
+		expect(a.get()).toBe(different)
 	})
-	it('has history independent of other atoms', () => {
-		const a = atom('', 1, { historyLength: 3, computeDiff: (a, b) => b - a })
-		const b = atom('', 1, { historyLength: 3, computeDiff: (a, b) => b - a })
 
-		const startEpoch = getGlobalEpoch()
+	it('[EQ2] does not consult the new value’s equals method', () => {
+		const oldValue = { x: 1 }
+		const newValue = { x: 1, equals: () => true }
 
-		b.set(-5)
-		b.set(-10)
-		b.set(-20)
-		expect(b.getDiffSince(startEpoch)).toEqual([-6, -5, -10])
-		expect(b.getDiffSince(getGlobalEpoch())).toEqual([])
+		const a = atom('a', oldValue)
+		a.set(newValue)
 
-		expect(a.getDiffSince(startEpoch)).toEqual([])
-		a.set(5)
-		expect(a.getDiffSince(startEpoch)).toEqual([+4])
-		expect(b.getDiffSince(startEpoch)).toEqual([-6, -5, -10])
-		expect(b.getDiffSince(getGlobalEpoch())).toEqual([])
+		expect(a.get()).toBe(newValue)
 	})
-	it('still updates history during transactions', () => {
-		const a = atom('', 1, { historyLength: 3, computeDiff: (a, b) => b - a })
 
-		const startEpoch = getGlobalEpoch()
+	it('[EQ3] uses a custom isEqual instead of default equality when provided', () => {
+		const foo = { hello: true }
+		const bar = { hello: true }
 
-		transact(() => {
-			expect(a.getDiffSince(startEpoch)).toEqual([])
+		const a = atom('a', foo)
 
-			a.set(5)
+		a.set(bar)
 
-			expect(a.getDiffSince(startEpoch)).toEqual([+4])
+		expect(a.get()).toBe(bar)
 
-			a.set(10)
+		const b = atom('b', foo, { isEqual: (a, b) => a.hello === b.hello })
 
-			expect(a.getDiffSince(startEpoch)).toEqual([+4, +5])
+		b.set(bar)
 
-			a.set(20)
+		expect(b.get()).toBe(foo)
+	})
 
-			expect(a.getDiffSince(startEpoch)).toEqual([+4, +5, +10])
+	it('[EQ4] makes setting an equal value a complete no-op', () => {
+		const initial = { x: 1 }
+		const a = atom('a', initial, {
+			isEqual: (a, b) => a.x === b.x,
+			historyLength: 5,
+			computeDiff: () => 'diff',
 		})
 
-		expect(a.getDiffSince(startEpoch)).toEqual([+4, +5, +10])
-	})
-	it('will clear the history if the transaction aborts', () => {
-		const a = atom('', 1, { historyLength: 3, computeDiff: (a, b) => b - a })
+		const effect = vi.fn(() => {
+			a.get()
+		})
+		const stop = react('r', effect)
+		expect(effect).toHaveBeenCalledTimes(1)
 
 		const startEpoch = getGlobalEpoch()
+		const lastChanged = a.lastChangedEpoch
 
-		transaction((rollback) => {
-			expect(a.getDiffSince(startEpoch)).toEqual([])
+		a.set({ x: 1 })
 
-			a.set(5)
+		expect(getGlobalEpoch()).toBe(startEpoch)
+		expect(a.lastChangedEpoch).toBe(lastChanged)
+		expect(a.get()).toBe(initial)
+		expect(a.getDiffSince(startEpoch)).toEqual([])
+		expect(effect).toHaveBeenCalledTimes(1)
 
-			expect(a.getDiffSince(startEpoch)).toEqual([+4])
+		stop()
+	})
+})
 
-			rollback()
-		})
+describe('atoms (A)', () => {
+	it('[A1] contain data', () => {
+		const a = atom('', 1)
 
-		expect(a.getDiffSince(startEpoch)).toEqual(RESET_VALUE)
+		expect(a.get()).toBe(1)
 	})
-	it('supports an update operation', () => {
-		const startEpoch = getGlobalEpoch()
+
+	it('[A2] can be updated with set', () => {
 		const a = atom('', 1)
 
-		a.update((value) => value + 1)
+		a.set(2)
 
 		expect(a.get()).toBe(2)
-		expect(getGlobalEpoch()).toBe(startEpoch + 1)
 	})
-	it('supports passing diffs in .set', () => {
-		const a = atom('', 1, { historyLength: 3 })
-
-		const startEpoch = getGlobalEpoch()
 
-		a.set(5, +4)
-		expect(a.getDiffSince(startEpoch)).toEqual([+4])
+	it('[A3] set returns the value of the atom after the call', () => {
+		const a = atom('', 1)
 
-		a.set(6, +1)
-		expect(a.getDiffSince(startEpoch)).toEqual([+4, +1])
+		expect(a.set(2)).toBe(2)
+		// setting an equal value returns the unchanged current value
+		expect(a.set(2)).toBe(2)
 	})
-	it('does not push history if nothing changed', () => {
-		const a = atom('', 1, { historyLength: 3 })
 
+	it('[A4] update(fn) sets the atom to fn(currentValue)', () => {
 		const startEpoch = getGlobalEpoch()
+		const a = atom('', 1)
 
-		a.set(5, +4)
-		expect(a.getDiffSince(startEpoch)).toEqual([+4])
-		a.set(5, +4)
-		expect(a.getDiffSince(startEpoch)).toEqual([+4])
-	})
-	it('clears the history buffer if you fail to provide a diff', () => {
-		const a = atom('', 1, { historyLength: 3 })
-		const startEpoch = getGlobalEpoch()
-
-		a.set(5, +4)
-
-		expect(a.getDiffSince(startEpoch)).toEqual([+4])
-
-		a.set(6)
+		a.update((value) => value + 1)
 
-		expect(a.getDiffSince(startEpoch)).toEqual(RESET_VALUE)
+		expect(a.get()).toBe(2)
+		expect(getGlobalEpoch()).toBe(startEpoch + 1)
 	})
-})
 
-describe('reacting to atoms', () => {
-	it('should work', async () => {
-		const a = atom('', 234)
-
-		let val = 0
-		const r = reactor('', () => {
-			val = a.get()
+	it('[A5] __unsafe__getWithoutCapture returns the value without capturing a dependency', () => {
+		const a = atom('a', 1)
+		const effect = vi.fn(() => {
+			a.__unsafe__getWithoutCapture()
 		})
+		const stop = react('r', effect)
 
-		expect(val).toBe(0)
-
-		r.start()
-
-		expect(val).toBe(234)
-
-		a.set(939)
-
-		expect(val).toBe(939)
-
-		r.stop()
+		expect(effect).toHaveBeenCalledTimes(1)
 
-		a.set(2342)
+		a.set(2)
 
-		expect(val).toBe(939)
-		expect(a.get()).toBe(2342)
+		expect(effect).toHaveBeenCalledTimes(1)
+		stop()
 	})
-})
-
-test('isEqual can provide custom equality checks', () => {
-	const foo = { hello: true }
-	const bar = { hello: true }
-
-	const a = atom('a', foo)
 
-	a.set(bar)
+	it('[A6] are independent of each other', () => {
+		const a = atom('a', 1)
+		const b = atom('b', 10)
 
-	expect(a.get()).toBe(bar)
-
-	const b = atom('b', foo, { isEqual: (a, b) => a.hello === b.hello })
-
-	b.set(bar)
+		a.set(2)
 
-	expect(b.get()).toBe(foo)
+		expect(b.get()).toBe(10)
+		expect(b.lastChangedEpoch).toBeLessThan(a.lastChangedEpoch)
+	})
 })

package/src/lib/__tests__/capture.test.ts

@@ -7,10 +7,207 @@ import {
 	unsafe__withoutCapture,
 } from '../capture'
 import { computed } from '../Computed'
-import { react } from '../EffectScheduler'
+import { react, reactor } from '../EffectScheduler'
 import { advanceGlobalEpoch, getGlobalEpoch } from '../transactions'
 import { Child } from '../types'
 
+// Tests for SPEC.md §5 (dependency capture).
+// Rule IDs like [CAP2] in test names refer to that document.
+
+describe('dependency capture (CAP)', () => {
+	it('[CAP1][CAP3] captures each dereferenced signal once, in first-dereference order', () => {
+		const a = atom('a', 1)
+		const b = atom('b', 2)
+
+		const r = reactor('r', () => {
+			a.get()
+			a.get()
+			b.get()
+			a.get()
+		})
+		r.start()
+
+		expect(r.scheduler.parents).toEqual([a, b])
+		r.stop()
+	})
+
+	it('[CAP2] the parent set is exactly the signals dereferenced in the latest run', () => {
+		const which = atom('which', true)
+		const b = atom('b', 1)
+		const c = atom('c', 2)
+
+		let runs = 0
+		const stop = react('r', () => {
+			runs++
+			if (which.get()) {
+				b.get()
+			} else {
+				c.get()
+			}
+		})
+		expect(runs).toBe(1)
+
+		// c is not currently a parent
+		c.set(3)
+		expect(runs).toBe(1)
+
+		which.set(false)
+		expect(runs).toBe(2)
+
+		// b is no longer a parent after the latest run
+		b.set(10)
+		expect(runs).toBe(2)
+
+		// c now is
+		c.set(4)
+		expect(runs).toBe(3)
+
+		stop()
+	})
+
+	it('[CAP4] capture contexts nest: an effect captures a computed, not its parents', () => {
+		const a = atom('a', 1)
+		const double = computed('double', () => a.get() * 2)
+
+		const r = reactor('r', () => {
+			double.get()
+		})
+		r.start()
+
+		expect(r.scheduler.parents).toEqual([double])
+		expect(double.parents).toEqual([a])
+		r.stop()
+	})
+
+	it('[CAP7] liveness propagates transitively up the graph', () => {
+		const a = atom('a', 1)
+		const c = computed('c', () => a.get())
+
+		// lazily dereferencing a computed does not attach anything
+		c.get()
+		expect(a.children.isEmpty).toBe(true)
+		expect(c.children.isEmpty).toBe(true)
+
+		const r = reactor('r', () => {
+			c.get()
+		})
+		r.start()
+
+		expect(a.children.isEmpty).toBe(false)
+		expect(c.children.isEmpty).toBe(false)
+
+		r.stop()
+
+		expect(a.children.isEmpty).toBe(true)
+		expect(c.children.isEmpty).toBe(true)
+	})
+
+	it('[CAP6] dereferencing signals outside a capture context captures nothing', () => {
+		expect(() => {
+			maybeCaptureParent(atom('', 1))
+		}).not.toThrow()
+	})
+})
+
+describe('unsafe__withoutCapture (CAP5)', () => {
+	it('[CAP5] short-circuits the current capture frame in a computed', () => {
+		const atomA = atom('a', 1)
+		const atomB = atom('b', 1)
+		const atomC = atom('c', 1)
+
+		const child = computed('', () => {
+			return atomA.get() + atomB.get() + unsafe__withoutCapture(() => atomC.get())
+		})
+
+		let lastValue: number | undefined
+		let numReactions = 0
+
+		react('', () => {
+			numReactions++
+			lastValue = child.get()
+		})
+
+		expect(lastValue).toBe(3)
+		expect(numReactions).toBe(1)
+
+		atomA.set(2)
+
+		expect(lastValue).toBe(4)
+		expect(numReactions).toBe(2)
+
+		atomB.set(2)
+
+		expect(lastValue).toBe(5)
+		expect(numReactions).toBe(3)
+
+		atomC.set(2)
+
+		// The reaction should not have run because C was not captured
+		expect(lastValue).toBe(5)
+		expect(numReactions).toBe(3)
+	})
+
+	it('[CAP5] short-circuits the current capture frame in an effect', () => {
+		const atomA = atom('a', 1)
+		const atomB = atom('b', 1)
+		const atomC = atom('c', 1)
+
+		let lastValue: number | undefined
+		let numReactions = 0
+
+		react('', () => {
+			numReactions++
+			lastValue = atomA.get() + atomB.get() + unsafe__withoutCapture(() => atomC.get())
+		})
+
+		expect(lastValue).toBe(3)
+		expect(numReactions).toBe(1)
+
+		atomA.set(2)
+
+		expect(lastValue).toBe(4)
+		expect(numReactions).toBe(2)
+
+		atomB.set(2)
+
+		expect(lastValue).toBe(5)
+		expect(numReactions).toBe(3)
+
+		atomC.set(2)
+
+		// The reaction should not have run because C was not captured
+		expect(lastValue).toBe(5)
+		expect(numReactions).toBe(3)
+	})
+
+	it('[CAP5] restores the capture context even if the wrapped function throws', () => {
+		const a = atom('a', 1)
+		let runs = 0
+
+		const stop = react('r', () => {
+			runs++
+			try {
+				unsafe__withoutCapture(() => {
+					throw new Error('oops')
+				})
+			} catch {
+				// ignore
+			}
+			// captured only if the capture context was restored
+			a.get()
+		})
+
+		expect(runs).toBe(1)
+
+		a.set(2)
+
+		expect(runs).toBe(2)
+		stop()
+	})
+})
+
+// Internal contract of startCapturingParents / maybeCaptureParent / stopCapturingParents [CAP8].
+
 const emptyChild = (props: Partial<Child> = {}) =>
 	({
 		parentEpochs: [],
@@ -21,8 +218,8 @@ const emptyChild = (props: Partial<Child> = {}) =>
 		...props,
 	}) as Child
 
-describe('capturing parents', () => {
-	it('can be started and stopped', () => {
+describe('capturing parents (CAP8, internal)', () => {
+	it('[CAP8] can be started and stopped', () => {
 		const a = atom('', 1)
 		const startEpoch = getGlobalEpoch()
 
@@ -42,7 +239,7 @@ describe('capturing parents', () => {
 		expect(child.parents).toEqual([a])
 	})
 
-	it('can handle several parents', () => {
+	it('[CAP8] can handle several parents', () => {
 		const atomA = atom('', 1)
 		const atomAEpoch = getGlobalEpoch()
 		advanceGlobalEpoch() // let's say time has passed
@@ -75,7 +272,7 @@ describe('capturing parents', () => {
 		expect(child.parents).toEqual([atomA, atomB, atomC])
 	})
 
-	it('will reorder if parents are captured in different orders each time', () => {
+	it('[CAP8] will reorder if parents are captured in different orders each time', () => {
 		const atomA = atom('', 1)
 		advanceGlobalEpoch() // let's say time has passed
 		const atomB = atom('', 1)
@@ -109,7 +306,7 @@ describe('capturing parents', () => {
 		expect(child.parents).toEqual([atomA, atomC, atomB])
 	})
 
-	it('will shrink the parent arrays if the number of captured parents shrinks', () => {
+	it('[CAP8] will shrink the parent arrays if the number of captured parents shrinks', () => {
 		const atomA = atom('', 1)
 		const atomAEpoch = getGlobalEpoch()
 		advanceGlobalEpoch() // let's say time has passed
@@ -159,82 +356,4 @@ describe('capturing parents', () => {
 		expect(child.parents).toBe(originalParents)
 		expect(child.parentEpochs).toBe(originalParentEpochs)
 	})
-
-	it('doesnt do anything if you dont start capturing', () => {
-		expect(() => {
-			maybeCaptureParent(atom('', 1))
-		}).not.toThrow()
-	})
-})
-
-describe(unsafe__withoutCapture, () => {
-	it('allows executing comptuer code in a context that short-circuits the current capture frame', () => {
-		const atomA = atom('a', 1)
-		const atomB = atom('b', 1)
-		const atomC = atom('c', 1)
-
-		const child = computed('', () => {
-			return atomA.get() + atomB.get() + unsafe__withoutCapture(() => atomC.get())
-		})
-
-		let lastValue: number | undefined
-		let numReactions = 0
-
-		react('', () => {
-			numReactions++
-			lastValue = child.get()
-		})
-
-		expect(lastValue).toBe(3)
-		expect(numReactions).toBe(1)
-
-		atomA.set(2)
-
-		expect(lastValue).toBe(4)
-		expect(numReactions).toBe(2)
-
-		atomB.set(2)
-
-		expect(lastValue).toBe(5)
-		expect(numReactions).toBe(3)
-
-		atomC.set(2)
-
-		// The reaction should not have run because C was not captured
-		expect(lastValue).toBe(5)
-		expect(numReactions).toBe(3)
-	})
-
-	it('allows executing reactor code in a context that short-circuits the current capture frame', () => {
-		const atomA = atom('a', 1)
-		const atomB = atom('b', 1)
-		const atomC = atom('c', 1)
-
-		let lastValue: number | undefined
-		let numReactions = 0
-
-		react('', () => {
-			numReactions++
-			lastValue = atomA.get() + atomB.get() + unsafe__withoutCapture(() => atomC.get())
-		})
-
-		expect(lastValue).toBe(3)
-		expect(numReactions).toBe(1)
-
-		atomA.set(2)
-
-		expect(lastValue).toBe(4)
-		expect(numReactions).toBe(2)
-
-		atomB.set(2)
-
-		expect(lastValue).toBe(5)
-		expect(numReactions).toBe(3)
-
-		atomC.set(2)
-
-		// The reaction should not have run because C was not captured
-		expect(lastValue).toBe(5)
-		expect(numReactions).toBe(3)
-	})
 })