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

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

@@ -1,12 +1,13 @@
-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'
+import { getGlobalEpoch, transact, transaction } from '../transactions'
 
-describe('transactions', () => {
-	it('should be abortable', () => {
+// Tests for SPEC.md §11 (transactions), plus rule EP6.
+// Rule IDs like [T4] in test names refer to that document.
+
+describe('transactions (T)', () => {
+	it('[T2][T3][T4][T6] batch changes, defer effects, and can be rolled back', () => {
 		const firstName = atom('', 'John')
 		const lastName = atom('', 'Doe')
 
@@ -32,11 +33,13 @@ describe('transactions', () => {
 			firstName.set('Wilbur')
 			expect(numTimesComputed).toBe(1)
 			expect(numTimesReacted).toBe(1)
+			// [T6] effects never observe intermediate in-transaction values
 			expect(name).toBe('John Doe')
 			lastName.set('Jones')
 			expect(numTimesComputed).toBe(1)
 			expect(numTimesReacted).toBe(1)
 			expect(name).toBe('John Doe')
+			// [T2] reads inside the transaction see the latest values
 			expect(fullName.get()).toBe('Wilbur Jones')
 
 			expect(numTimesComputed).toBe(2)
@@ -46,7 +49,7 @@ describe('transactions', () => {
 			rollback()
 		})
 
-		// computes again
+		// [T6] the aborted transaction still flushes effects, which observe the restored values
 		expect(numTimesComputed).toBe(3)
 		expect(numTimesReacted).toBe(2)
 
@@ -54,7 +57,26 @@ describe('transactions', () => {
 		expect(name).toBe('John Doe')
 	})
 
-	it('nested rollbacks work as expected', () => {
+	it('[T1] returns the value of the function, even when rolled back', () => {
+		expect(transaction(() => 'hello')).toBe('hello')
+		expect(transact(() => 42)).toBe(42)
+		expect(
+			transaction((rollback) => {
+				rollback()
+				return 'rolled back'
+			})
+		).toBe('rolled back')
+	})
+
+	it('[EP6] advances the global epoch when aborted', () => {
+		const startEpoch = getGlobalEpoch()
+		transaction((rollback) => {
+			rollback()
+		})
+		expect(getGlobalEpoch()).toBeGreaterThan(startEpoch)
+	})
+
+	it('[T7] nested transactions roll back independently', () => {
 		const atomA = atom('', 0)
 		const atomB = atom('', 0)
 
@@ -148,7 +170,7 @@ describe('transactions', () => {
 		expect(atomB.get()).toBe(-2)
 	})
 
-	it('should restore the original even if an inner commits', () => {
+	it('[T7] an outer rollback undoes a committed inner transaction', () => {
 		const a = atom('', 'a')
 
 		transaction((rollback) => {
@@ -160,10 +182,26 @@ describe('transactions', () => {
 
 		expect(a.get()).toBe('a')
 	})
+
+	it('[T4] rollback restores computed signals too', () => {
+		const firstName = atom('', 'John')
+		const lastName = atom('', 'Doe')
+
+		const fullName = computed('', () => `${firstName.get()} ${lastName.get()}`)
+
+		transaction((rollback) => {
+			firstName.set('Jane')
+			lastName.set('Jones')
+			expect(fullName.get()).toBe('Jane Jones')
+			rollback()
+		})
+
+		expect(fullName.get()).toBe('John Doe')
+	})
 })
 
-describe('transact', () => {
-	it('executes things in a transaction', () => {
+describe('transact (T)', () => {
+	it('[T5] aborts and rethrows if the function throws', () => {
 		const a = atom('', 'a')
 
 		try {
@@ -180,7 +218,7 @@ describe('transact', () => {
 		expect.assertions(2)
 	})
 
-	it('does not create nested transactions', () => {
+	it('[T1][T8] joins the current transaction instead of nesting, so an inner throw restores nothing', () => {
 		const a = atom('', 'a')
 
 		transact(() => {
@@ -202,427 +240,3 @@ describe('transact', () => {
 		expect.assertions(3)
 	})
 })
-
-describe('setting atoms during a reaction', () => {
-	it('should work', () => {
-		const a = atom('', 0)
-		const b = atom('', 0)
-
-		react('', () => {
-			b.set(a.get() + 1)
-		})
-
-		expect(a.get()).toBe(0)
-		expect(b.get()).toBe(1)
-	})
-
-	it('should throw an error if it gets into a loop', () => {
-		expect(() => {
-			const a = atom('', 0)
-
-			react('', () => {
-				a.set(a.get() + 1)
-			})
-		}).toThrowErrorMatchingInlineSnapshot(`[Error: Reaction update depth limit exceeded]`)
-	})
-
-	it('should work with a transaction running', () => {
-		const a = atom('', 0)
-
-		react('', () => {
-			transact(() => {
-				if (a.get() < 10) {
-					a.set(a.get() + 1)
-				}
-			})
-		})
-
-		expect(a.get()).toBe(10)
-	})
-
-	it('[regression 1] should allow computeds to be updated properly', () => {
-		const a = atom('', 0)
-		const b = atom('', 0)
-		const c = computed('', () => b.get() * 2)
-
-		let cValue = 0
-
-		react('', () => {
-			b.set(a.get() + 1)
-			cValue = c.get()
-		})
-
-		expect(a.get()).toBe(0)
-		expect(b.get()).toBe(1)
-		expect(cValue).toBe(2)
-
-		transact(() => {
-			a.set(1)
-		})
-		expect(cValue).toBe(4)
-	})
-
-	it('[regression 2] should allow computeds to be updated properly', () => {
-		const a = atom('', 0)
-		const b = atom('', 1)
-		const c = atom('', 0)
-		const d = computed('', () => a.get() * 2)
-
-		let dValue = 0
-		react('', () => {
-			// update a, causes a and d to be traversed (but not updated)
-			a.set(b.get())
-			// update c
-			c.set(a.get())
-			// make sure that when we get d, it is updated properly
-			dValue = d.get()
-		})
-
-		expect(a.get()).toBe(1)
-		expect(b.get()).toBe(1)
-		expect(c.get()).toBe(1)
-
-		expect(dValue).toBe(2)
-
-		transact(() => {
-			b.set(2)
-		})
-		expect(dValue).toBe(4)
-	})
-})
-
-test('it should be possible to run a transaction during a reaction', () => {
-	const a = atom('', 0)
-	const b = atom('', 0)
-
-	react('', () => {
-		transaction(() => {
-			b.set(a.get() + 1)
-		})
-	})
-
-	expect(a.get()).toBe(0)
-	expect(b.get()).toBe(1)
-
-	a.set(1)
-
-	expect(b.get()).toBe(2)
-
-	transaction(() => {
-		a.set(2)
-		expect(b.get()).toBe(2)
-	})
-
-	expect(b.get()).toBe(3)
-})
-
-test('it should be possible to abort a transaction during a reaction', () => {
-	const a = atom('', 0)
-	const b = atom('', 0)
-
-	const unsub = react('', () => {
-		transaction((rollback) => {
-			b.set(a.get() + 1)
-			rollback()
-		})
-		expect(b.get()).toBe(0)
-	})
-
-	expect(a.get()).toBe(0)
-	expect(b.get()).toBe(0)
-
-	unsub()
-
-	react('', () => {
-		transaction(() => {
-			b.set(3)
-			try {
-				transaction(() => {
-					b.set(a.get() + 1)
-					throw new Error('oops')
-				})
-			} catch (e: any) {
-				expect(e.message).toBe('oops')
-			} finally {
-				expect(b.get()).toBe(3)
-			}
-		})
-		expect(b.get()).toBe(3)
-	})
-
-	expect(a.get()).toBe(0)
-	expect(b.get()).toBe(3)
-
-	expect.assertions(8)
-})
-
-it('should defer all side effects until the end of the outer transaction', () => {
-	const a = atom('', 0)
-	const b = atom('', 0)
-	const c = atom('', 0)
-
-	const aChanged = vi.fn()
-	const bChanged = vi.fn()
-	const cChanged = vi.fn()
-
-	react('', () => {
-		a.get()
-		aChanged()
-	})
-
-	react('', () => {
-		transaction(() => {
-			a.set(b.get() + 1)
-		})
-		bChanged()
-	})
-
-	react('', () => {
-		transaction(() => {
-			b.set(c.get() + 1)
-		})
-		cChanged()
-	})
-
-	expect(aChanged).toHaveBeenCalledTimes(3)
-	expect(bChanged).toHaveBeenCalledTimes(2)
-	expect(cChanged).toHaveBeenCalledTimes(1)
-
-	expect(a.__unsafe__getWithoutCapture()).toBe(2)
-
-	cChanged.mockImplementationOnce(() => {
-		// b was .set() during c's reaction
-		expect(b.__unsafe__getWithoutCapture()).toBe(2)
-		// a was not yet set because the effect was deferred
-		// util the end of the reaction
-		expect(a.__unsafe__getWithoutCapture()).toBe(2)
-	})
-
-	c.set(1)
-
-	expect(a.__unsafe__getWithoutCapture()).toBe(3)
-	expect(cChanged).toHaveBeenCalledTimes(2)
-})
-
-describe('asyncTransaction', () => {
-	it('works 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('throws an error 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('can have nested sync transactions', 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('can have nested async transactions', 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('allows transact to be called inside asyncTransaction', 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('allows overlapping transactions', 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)
-	})
-})
-
-describe('async tests generated by claude', () => {
-	// Add these tests to your existing asyncTransaction describe block
-
-	it('should rollback 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('should defer effects until 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('should handle computed signals properly in async transactions', 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('should handle multiple concurrent async transactions', 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('should handle exception in nested async transaction', 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)
-	})
-})