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

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

@@ -0,0 +1,84 @@
+import { vi } from 'vitest'
+import { atom } from '../Atom'
+import { whyAmIRunning } from '../capture'
+import { computed } from '../Computed'
+import { react, reactor } from '../EffectScheduler'
+
+// Tests for SPEC.md §13 (debugging aids).
+// Rule IDs like [D2] in test names refer to that document.
+
+describe('whyAmIRunning (D)', () => {
+	it('[D2] throws when called outside of a reactive context', () => {
+		expect(() => whyAmIRunning()).toThrow('whyAmIRunning() called outside of a reactive context')
+	})
+
+	it('[D3] logs which ancestor atoms caused an effect to run', () => {
+		const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+		const name = atom('name', 'Bob')
+		const stop = react('greeting', () => {
+			whyAmIRunning()
+			name.get()
+		})
+
+		expect(log).not.toHaveBeenCalled()
+
+		name.set('Alice')
+
+		expect(log).toHaveBeenCalledTimes(1)
+		expect(log.mock.calls[0][0]).toContain('Effect(greeting) is executing because:')
+		expect(log.mock.calls[0][0]).toContain('Atom(name) changed')
+
+		stop()
+		log.mockRestore()
+	})
+
+	it('[D3] logs which ancestors caused a computed to recompute, including nested computeds', () => {
+		const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+		const a = atom('a', 1)
+		const double = computed('double', () => a.get() * 2)
+		const quadruple = computed('quadruple', () => {
+			whyAmIRunning()
+			return double.get() * 2
+		})
+
+		const stop = react('r', () => {
+			quadruple.get()
+		})
+
+		expect(log).not.toHaveBeenCalled()
+
+		a.set(2)
+
+		expect(log).toHaveBeenCalledTimes(1)
+		expect(log.mock.calls[0][0]).toContain('Computed(quadruple) is recomputing because:')
+		expect(log.mock.calls[0][0]).toContain('Computed(double) changed')
+		expect(log.mock.calls[0][0]).toContain('Atom(a) changed')
+
+		stop()
+		log.mockRestore()
+	})
+
+	it('[D3] logs that an effect was executed manually when no ancestors changed', () => {
+		const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+
+		const a = atom('a', 1)
+		const r = reactor('manual', () => {
+			whyAmIRunning()
+			a.get()
+		})
+
+		r.start()
+		expect(log).not.toHaveBeenCalled()
+
+		r.stop()
+		r.start({ force: true })
+
+		expect(log).toHaveBeenCalledTimes(1)
+		expect(log.mock.calls[0][0]).toContain('Effect(manual) was executed manually.')
+
+		r.stop()
+		log.mockRestore()
+	})
+})

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

@@ -0,0 +1,232 @@
+import { promiseWithResolve, sleep } from '@tldraw/utils'
+import { vi } from 'vitest'
+import { atom } from '../Atom'
+import { computed } from '../Computed'
+import { react } from '../EffectScheduler'
+import { deferAsyncEffects, transact, transaction } from '../transactions'
+
+// Tests for SPEC.md §12 (async transactions: deferAsyncEffects).
+// Rule IDs like [AT3] in test names refer to that document.
+
+describe('deferAsyncEffects (AT)', () => {
+	it('[AT1] defers effects until the async transaction commits', async () => {
+		const a = atom('', 0)
+		const b = atom('', 0)
+		const effectCalls = vi.fn()
+
+		react('', () => {
+			a.get()
+			b.get()
+			effectCalls()
+		})
+
+		expect(effectCalls).toHaveBeenCalledTimes(1)
+
+		const txPromise = deferAsyncEffects(async () => {
+			a.set(1)
+			expect(effectCalls).toHaveBeenCalledTimes(1) // no effect yet
+			await sleep(1)
+			b.set(2)
+			expect(effectCalls).toHaveBeenCalledTimes(1) // still no effect
+		})
+
+		await txPromise
+		expect(effectCalls).toHaveBeenCalledTimes(2) // effect runs after commit
+	})
+
+	it('[AT1] keeps computed signals up to date during the async transaction', async () => {
+		const a = atom('', 1)
+		const doubled = computed('', () => a.get() * 2)
+
+		expect(doubled.get()).toBe(2)
+
+		await deferAsyncEffects(async () => {
+			a.set(5)
+			// computed should update during transaction
+			expect(doubled.get()).toBe(10)
+			await sleep(1)
+			a.set(10)
+			expect(doubled.get()).toBe(20)
+		})
+
+		// computed should update after commit
+		expect(doubled.get()).toBe(20)
+		expect(a.get()).toBe(10)
+	})
+
+	it('[AT2] throws if kicked off during a sync transaction', async () => {
+		const a = atom('', 0)
+		let txp: any = null
+		transact(() => {
+			txp = deferAsyncEffects(async () => {
+				expect(a.get()).toBe(1)
+				a.set(2)
+			})
+			a.set(1)
+		})
+
+		await expect(txp).rejects.toMatchInlineSnapshot(
+			`[Error: deferAsyncEffects cannot be called during a sync transaction]`
+		)
+	})
+
+	it('[AT2] allows sync transactions inside the async body', async () => {
+		const a = atom('', 0)
+
+		await deferAsyncEffects(async () => {
+			a.set(1)
+			transaction(() => {
+				a.set(2)
+			})
+			expect(a.get()).toBe(2)
+		})
+		expect(a.get()).toBe(2)
+	})
+
+	it('[AT2] allows transact inside the async body', async () => {
+		const a = atom('', 0)
+
+		await deferAsyncEffects(async () => {
+			a.set(1)
+			transact(() => {
+				a.set(2)
+			})
+			expect(a.get()).toBe(2)
+		})
+		expect(a.get()).toBe(2)
+	})
+
+	it('[AT3] rolls back all changes on exception', async () => {
+		const a = atom('', 0)
+		const b = atom('', 0)
+
+		await expect(
+			deferAsyncEffects(async () => {
+				a.set(1)
+				b.set(2)
+				throw new Error('test error')
+			})
+		).rejects.toThrow('test error')
+
+		expect(a.get()).toBe(0)
+		expect(b.get()).toBe(0)
+	})
+
+	it('[AT3][AT4] rolls back everything when a nested async transaction throws', async () => {
+		const a = atom('', 0)
+		const b = atom('', 0)
+
+		await expect(
+			deferAsyncEffects(async () => {
+				a.set(1)
+
+				await deferAsyncEffects(async () => {
+					b.set(2)
+					throw new Error('inner error')
+				})
+			})
+		).rejects.toThrow('inner error')
+
+		expect(a.get()).toBe(0) // all changes should be rolled back
+		expect(b.get()).toBe(0)
+	})
+
+	it('[AT4] nested async transactions join the outer one', async () => {
+		const a = atom('', 0)
+
+		await deferAsyncEffects(async () => {
+			a.set(1)
+			await deferAsyncEffects(async () => {
+				a.set(2)
+			})
+			expect(a.get()).toBe(2)
+		})
+		expect(a.get()).toBe(2)
+	})
+
+	it('[AT4] concurrent async transactions are merged', async () => {
+		const a = atom('', 0)
+		const b = atom('', 0)
+		const results: number[] = []
+
+		const tx1 = deferAsyncEffects(async () => {
+			a.set(1)
+			await sleep(10)
+			results.push(a.get())
+			return 'tx1'
+		})
+
+		const tx2 = deferAsyncEffects(async () => {
+			b.set(2)
+			await sleep(5)
+			results.push(b.get())
+			return 'tx2'
+		})
+
+		const [result1, result2] = await Promise.all([tx1, tx2])
+
+		expect(result1).toBe('tx1')
+		expect(result2).toBe('tx2')
+		expect(a.get()).toBe(1)
+		expect(b.get()).toBe(2)
+		expect(results).toEqual([2, 1])
+	})
+
+	it('[AT4] overlapping transactions leak state to each other but group their effects', async () => {
+		const a = atom('', 0)
+
+		let txp = null
+
+		const p = deferAsyncEffects(async () => {
+			a.set(1)
+			const x = promiseWithResolve()
+			txp = deferAsyncEffects(async () => {
+				a.set(2)
+				x.resolve(null)
+				await sleep(10)
+				a.set(3)
+				return 'inner'
+			})
+			await x
+			// inner transactions leak, this can't be avoided without AsyncContext
+			// but at least we can group effects.
+			expect(a.get()).toBe(2)
+			return 'outer'
+		})
+
+		await expect(p).resolves.toBe('outer')
+		await expect(txp).resolves.toBe('inner')
+		expect(a.get()).toBe(3)
+	})
+
+	it('[AT5] waits for the reaction phase to finish if kicked off during a reaction', async () => {
+		const a = atom('', 0)
+		const b = atom('', 0)
+
+		let txp: any = null
+
+		react('', () => {
+			a.get()
+			txp = deferAsyncEffects(async () => {
+				await sleep(1)
+				b.set(a.get() + 1)
+			})
+		})
+
+		await txp
+
+		expect(a.get()).toBe(0)
+		expect(b.get()).toBe(1)
+
+		a.set(1)
+
+		await txp
+
+		expect(a.get()).toBe(1)
+		expect(b.get()).toBe(2)
+	})
+
+	it('[AT6] resolves to the return value of the function', async () => {
+		await expect(deferAsyncEffects(async () => 'value')).resolves.toBe('value')
+	})
+})

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

@@ -1,41 +1,15 @@
 import { atom } from '../Atom'
-import { computed } from '../Computed'
+import { computed, isUninitialized } from '../Computed'
 import { EffectScheduler, react } from '../EffectScheduler'
 import { haveParentsChanged } from '../helpers'
 import { getGlobalEpoch, transact } from '../transactions'
 import { RESET_VALUE } from '../types'
 
-describe('reactors that error', () => {
-	it('will not roll back the atom value', () => {
-		const a = atom('', 1)
-		react('', () => {
-			if (a.get() === 2) throw new Error('test')
-		})
-		expect(() => a.set(2)).toThrowErrorMatchingInlineSnapshot(`[Error: test]`)
-		expect(a.get()).toBe(2)
-	})
-	it('will not roll back the changes in a transaction', () => {
-		const a = atom('', 1)
-		const b = atom('', 2)
+// Tests for SPEC.md §7 (errors in computed signals) and rule CE6 (effects that throw).
+// Rule IDs like [CE1] in test names refer to that document.
 
-		react('', () => {
-			if (a.get() + b.get() === 4) throw new Error('test')
-		})
-
-		expect(() =>
-			transact(() => {
-				a.set(3)
-				b.set(1)
-			})
-		).toThrowErrorMatchingInlineSnapshot(`[Error: test]`)
-
-		expect(a.get()).toBe(3)
-		expect(b.get()).toBe(1)
-	})
-})
-
-describe('derivations that error', () => {
-	it('will cache thrown values', () => {
+describe('computed signals that throw (CE)', () => {
+	it('[CE1] cache thrown values until a parent changes', () => {
 		let numComputations = 0
 		const a = atom('', 1)
 		const b = computed('', () => {
@@ -62,7 +36,7 @@ describe('derivations that error', () => {
 		expect(b.get()).toBe(3)
 	})
 
-	it('will not trigger effects if they continue to error', () => {
+	it('[CE2] entering the error state notifies effects, but consecutive errors do not', () => {
 		const a = atom('', 1)
 		let numComputations = 0
 		const b = computed('', () => {
@@ -85,21 +59,45 @@ describe('derivations that error', () => {
 
 		a.set(2)
 
+		// entering the error state is a change
 		expect(numReactions).toBe(2)
 		expect(numComputations).toBe(2)
 
 		a.set(4)
 
+		// erroring again while already in the error state is not a change
 		expect(numComputations).toBe(3)
 		expect(numReactions).toBe(2)
 
 		a.set(3)
 
+		// recovering is a change
 		expect(numComputations).toBe(4)
 		expect(numReactions).toBe(3)
 	})
 
-	it('clears the history buffer when an error is thrown', () => {
+	it('[CE3] discard the previous value: recovery receives UNINITIALIZED as previousValue', () => {
+		const a = atom('', 1)
+		const previousValues: unknown[] = []
+		const b = computed('', (prev) => {
+			previousValues.push(prev)
+			if (a.get() === 2) throw new Error('test')
+			return a.get()
+		})
+
+		expect(b.get()).toBe(1)
+
+		a.set(2)
+		expect(() => b.get()).toThrowErrorMatchingInlineSnapshot(`[Error: test]`)
+
+		a.set(3)
+		expect(b.get()).toBe(3)
+
+		expect(previousValues.map(isUninitialized)).toEqual([true, false, true])
+		expect(previousValues[1]).toBe(1)
+	})
+
+	it('[CE4] clear the history buffer when an error is thrown', () => {
 		const a = atom('', 1)
 		const b = computed(
 			'',
@@ -142,24 +140,54 @@ describe('derivations that error', () => {
 		expect(b.getDiffSince(errorEpoch)).toEqual(RESET_VALUE)
 		expect(b.getDiffSince(errorEpoch + 1)).toEqual([1])
 	})
+
+	it('[CE5] haveParentsChanged will not throw if one of the parents is throwing', () => {
+		const a = atom('', 1)
+		const scheduler = new EffectScheduler('', () => {
+			a.get()
+			throw new Error('test')
+		})
+		expect(() => {
+			scheduler.attach()
+			scheduler.execute()
+		}).toThrowErrorMatchingInlineSnapshot(`[Error: test]`)
+
+		expect(haveParentsChanged(scheduler)).toBe(false)
+
+		expect(() => a.set(2)).toThrowErrorMatchingInlineSnapshot(`[Error: test]`)
+
+		// haveParentsChanged should still be false because it already
+		// executed the effect and it errored
+		expect(haveParentsChanged(scheduler)).toBe(false)
+	})
 })
 
-test('haveParentsChanged will not throw if one of the parents is throwing', () => {
-	const a = atom('', 1)
-	const scheduler = new EffectScheduler('', () => {
-		a.get()
-		throw new Error('test')
+describe('effects that throw (CE6)', () => {
+	it('[CE6] will not roll back the atom value', () => {
+		const a = atom('', 1)
+		react('', () => {
+			if (a.get() === 2) throw new Error('test')
+		})
+		expect(() => a.set(2)).toThrowErrorMatchingInlineSnapshot(`[Error: test]`)
+		expect(a.get()).toBe(2)
 	})
-	expect(() => {
-		scheduler.attach()
-		scheduler.execute()
-	}).toThrowErrorMatchingInlineSnapshot(`[Error: test]`)
 
-	expect(haveParentsChanged(scheduler)).toBe(false)
+	it('[CE6] will not roll back the changes in a transaction', () => {
+		const a = atom('', 1)
+		const b = atom('', 2)
 
-	expect(() => a.set(2)).toThrowErrorMatchingInlineSnapshot(`[Error: test]`)
+		react('', () => {
+			if (a.get() + b.get() === 4) throw new Error('test')
+		})
 
-	// haveParentsChanged should still be false because it already
-	// executed the effect and it errored
-	expect(haveParentsChanged(scheduler)).toBe(false)
+		expect(() =>
+			transact(() => {
+				a.set(3)
+				b.set(1)
+			})
+		).toThrowErrorMatchingInlineSnapshot(`[Error: test]`)
+
+		expect(a.get()).toBe(3)
+		expect(b.get()).toBe(1)
+	})
 })

package/src/lib/__tests__/fuzz.tlstate.test.ts

@@ -1,4 +1,4 @@
-import { times } from 'lodash'
+import times from 'lodash/times'
 import { Atom, atom, isAtom } from '../Atom'
 import { Computed, computed, isComputed } from '../Computed'
 import { Reactor, reactor } from '../EffectScheduler'

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

@@ -0,0 +1,49 @@
+import { atom, isAtom } from '../Atom'
+import { computed, getComputedInstance, isComputed } from '../Computed'
+import { isSignal } from '../isSignal'
+
+// Tests for SPEC.md §14 (type guards and module duplication).
+// Rule G2 (singleton sharing across module copies) is covered at the unit level in helpers.test.ts.
+
+describe('type guards (G1)', () => {
+	const a = atom('a', 1)
+	const c = computed('c', () => a.get() * 2)
+
+	class Foo {
+		x = atom('x', 1)
+		@computed
+		getY() {
+			return this.x.get()
+		}
+	}
+	const decorated = getComputedInstance(new Foo(), 'getY')
+
+	const nonSignals = [null, undefined, 0, 1, NaN, 'hello', {}, [], () => {}, Symbol('s')]
+
+	it('[G1] isAtom is true exactly for atoms', () => {
+		expect(isAtom(a)).toBe(true)
+		expect(isAtom(c)).toBe(false)
+		expect(isAtom(decorated)).toBe(false)
+		for (const value of nonSignals) {
+			expect(isAtom(value)).toBe(false)
+		}
+	})
+
+	it('[G1] isComputed is true exactly for computed signals', () => {
+		expect(isComputed(c)).toBe(true)
+		expect(isComputed(decorated)).toBe(true)
+		expect(isComputed(a)).toBe(false)
+		for (const value of nonSignals) {
+			expect(isComputed(value)).toBe(false)
+		}
+	})
+
+	it('[G1] isSignal is true exactly for atoms and computed signals', () => {
+		expect(isSignal(a)).toBe(true)
+		expect(isSignal(c)).toBe(true)
+		expect(isSignal(decorated)).toBe(true)
+		for (const value of nonSignals) {
+			expect(isSignal(value)).toBe(false)
+		}
+	})
+})