@tldraw/state 5.3.2 → 5.4.0-canary.02cd0bd3b597

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

@@ -1,8 +1,9 @@
+import { exhaustiveSwitchError } from '@tldraw/utils'
 import { vi } from 'vitest'
 import { atom } from '../Atom'
 import { Computed, UNINITIALIZED, computed, isUninitialized, withDiff } from '../Computed'
 import { react } from '../EffectScheduler'
-import { EMPTY_ARRAY, assertNever } from '../helpers'
+import { EMPTY_ARRAY } from '../helpers'
 import { getGlobalEpoch, transact, transaction } from '../transactions'
 import { RESET_VALUE, Signal } from '../types'
 
@@ -78,6 +79,35 @@ describe('atom history (H)', () => {
 		expect(calls).toEqual([[1, 5, epochBeforeSet, getGlobalEpoch()]])
 	})
 
+	it('[H2][C2] a computed read inside computeDiff still sees the change afterwards', () => {
+		// computeDiff runs before the epoch ticks, so a dependent computed it reads is not stamped as
+		// checked at the epoch of the write that is still in progress.
+		const a = atom('', 1, {
+			historyLength: 10,
+			computeDiff: (prev, next) => {
+				c.get()
+				return next - prev
+			},
+		})
+		const c: Computed<number> = computed('', () => a.get() * 2)
+		const seen: number[] = []
+		react('', () => seen.push(c.get()))
+
+		a.set(2)
+
+		expect(c.get()).toBe(4)
+		expect(seen).toEqual([2, 4])
+		expect(a.getDiffSince(a.lastChangedEpoch - 1)).toEqual([1])
+	})
+
+	it('[H2] records an explicit null diff rather than treating it as missing', () => {
+		const a = atom<number, null | number>('', 1, { historyLength: 3 })
+		const startEpoch = a.lastChangedEpoch
+		a.set(2, 1)
+		a.set(3, null)
+		expect(a.getDiffSince(startEpoch)).toEqual([1, null])
+	})
+
 	it('[H4] clears the history buffer if no diff can be determined', () => {
 		const a = atom('', 1, { historyLength: 3 })
 		const startEpoch = getGlobalEpoch()
@@ -383,7 +413,7 @@ function getIncrementalRecordMapper<In, Out>(
 					}
 					break
 				default:
-					assertNever(change)
+					exhaustiveSwitchError(change)
 			}
 		}
 

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

@@ -260,4 +260,19 @@ describe('localStorageAtom', () => {
 			cleanup2()
 		})
 	})
+
+	describe('outside the browser', () => {
+		it('[LS6] does not throw without a window and returns a working atom', () => {
+			vi.stubGlobal('window', undefined)
+			try {
+				const [atom, cleanup] = localStorageAtom('test-key', 'initial-value')
+				expect(atom.get()).toBe('initial-value')
+				atom.set('next')
+				expect(atom.get()).toBe('next')
+				expect(() => cleanup()).not.toThrow()
+			} finally {
+				vi.unstubAllGlobals()
+			}
+		})
+	})
 })

package/src/lib/capture.ts

@@ -24,10 +24,10 @@ const inst = singleton('capture', () => ({ stack: null as null | CaptureStackFra
  * @example
  * ```ts
  * const name = atom('name', 'Sam')
- * const time = atom('time', () => new Date().getTime())
+ * const time = atom('time', Date.now())
  *
  * setInterval(() => {
- *   time.set(new Date().getTime())
+ *   time.set(Date.now())
  * })
  *
  * react('log name changes', () => {
@@ -149,21 +149,20 @@ export function stopCapturingParents() {
  */
 export function maybeCaptureParent(p: Signal<any, any>) {
 	if (inst.stack) {
-		const wasCapturedAlready = inst.stack.child.parentSet.has(p)
-		// if the child didn't deref this parent last time it executed, then idx will be -1
-		// if the child did deref this parent last time but in a different order relative to other parents, then idx will be greater than stack.offset
-		// if the child did deref this parent last time in the same order, then idx will be the same as stack.offset
-		// if the child did deref this parent already during this capture session then 0 <= idx < stack.offset
-
-		if (wasCapturedAlready) {
+		// `add` returns false when the parent was already captured this run. In array mode both
+		// `has` and `add` scan with indexOf, so going straight to `add` halves the scans per
+		// captured parent.
+		if (!inst.stack.child.parentSet.add(p)) {
 			return
 		}
 
-		inst.stack.child.parentSet.add(p)
 		if (inst.stack.child.isActivelyListening) {
 			attach(p, inst.stack.child)
 		}
 
+		// Parents are recorded in deref order. If the slot at this offset held a different parent
+		// last run, that parent may have moved later in the order or been dropped; only
+		// stopCapturingParents can tell, so remember it for then.
 		if (inst.stack.offset < inst.stack.child.parents.length) {
 			const maybeRemovedParent = inst.stack.child.parents[inst.stack.offset]
 			if (maybeRemovedParent !== p) {
@@ -183,7 +182,8 @@ export function maybeCaptureParent(p: Signal<any, any>) {
 
 /**
  * A debugging tool that tells you why a computed signal or effect is running.
- * Call in the body of a computed signal or effect function.
+ * Call in the body of a computed signal or effect function. Nothing is logged for the run that
+ * calls it; from the next run on, each run logs the ancestors that changed.
  *
  * @example
  * ```ts
@@ -195,8 +195,8 @@ export function maybeCaptureParent(p: Signal<any, any>) {
  *
  * name.set('Alice')
  *
- * // 'greeting' is running because:
- * //     'name' changed => 'Alice'
+ * // Effect(greeting) is executing because:
+ * //  ↳ Atom(name) changed
  * ```
  *
  * @public

package/src/lib/constants.ts

@@ -1,26 +1,7 @@
 /**
- * The initial epoch value used to mark derivations (computed signals and effects) as dirty before their first computation.
+ * Sentinel below any real epoch. Derived signals and effects start with their epochs set to this
+ * so they are dirty until their first run; real epochs start at `GLOBAL_START_EPOCH + 1`.
  *
- * This constant ensures that all computed signals and effects start in a "dirty" state, guaranteeing they will
- * be computed/executed at least once when first accessed or started. The value -1 is used because:
- * - Global epoch starts at 0 (GLOBAL_START_EPOCH + 1)
- * - Any derived signal initialized with GLOBAL_START_EPOCH (-1) will be considered dirty when compared to any positive epoch
- * - This forces initial computation/execution without requiring special initialization logic
- *
- * Used by:
- * - Computed signals to track when they were last changed
- * - Effect schedulers to track when they were last executed
- * - Transaction system for initial global and reaction epoch values
- *
- * @example
- * ```ts
- * // In Computed class constructor
- * lastChangedEpoch = GLOBAL_START_EPOCH // -1, marking as dirty
- *
- * // When global epoch is 5, this computed will be dirty since -1 < 5
- * const needsComputation = this.lastChangedEpoch < globalEpoch
- * ```
- *
- * @public
+ * @internal
  */
 export const GLOBAL_START_EPOCH = -1

package/src/lib/helpers.ts

@@ -1,42 +1,23 @@
 import { Child, Signal } from './types'
 
-/**
- * Get whether the given value is a child.
- *
- * @param x The value to check.
- * @returns True if the value is a child, false otherwise.
- * @internal
- */
 function isChild(x: any): x is Child {
 	return x && typeof x === 'object' && 'parents' in x
 }
 
 /**
- * Checks if any of a child's parent signals have changed by comparing their current epochs
- * with the child's cached view of those epochs.
- *
- * This function is used internally to determine if a computed signal or effect needs to
- * be re-evaluated because one of its dependencies has changed.
+ * Whether any of the child's parents changed since the child last recorded their epochs. O(parents);
+ * returns at the first changed parent, so parents after it are not brought up to date.
  *
- * @param child - The child (computed signal or effect) to check for parent changes
- * @returns `true` if any parent signal has changed since the child last observed it, `false` otherwise
- * @example
- * ```ts
- * const childSignal = computed('child', () => parentAtom.get())
- * // Check if the child needs to recompute
- * if (haveParentsChanged(childSignal)) {
- *   // Recompute the child's value
- * }
- * ```
  * @internal
  */
 export function haveParentsChanged(child: Child): boolean {
 	for (let i = 0, n = child.parents.length; i < n; i++) {
-		// Get the parent's value without capturing it.
-		child.parents[i].__unsafe__getWithoutCapture(true)
+		const parent = child.parents[i]
+		// Bring the parent up to date first: a computed parent's `lastChangedEpoch` only moves when
+		// it is re-derived.
+		parent.__unsafe__getWithoutCapture(true)
 
-		// If the parent's epoch does not match the child's view of the parent's epoch, then the parent has changed.
-		if (child.parents[i].lastChangedEpoch !== child.parentEpochs[i]) {
+		if (parent.lastChangedEpoch !== child.parentEpochs[i]) {
 			return true
 		}
 	}
@@ -45,32 +26,17 @@ export function haveParentsChanged(child: Child): boolean {
 }
 
 /**
- * Detaches a child signal from its parent signal, removing the parent-child relationship
- * in the reactive dependency graph. If the parent has no remaining children and is itself
- * a child, it will recursively detach from its own parents.
- *
- * This function is used internally to clean up the dependency graph when signals are no
- * longer needed or when dependencies change.
+ * Removes `child` from `parent.children`. A computed parent that loses its last child stops
+ * listening itself, recursively, so a signal's `children` set is empty whenever nothing downstream
+ * is actively listening.
  *
- * @param parent - The parent signal to detach from
- * @param child - The child signal to detach
- * @example
- * ```ts
- * // When a computed signal's dependencies change
- * const oldParent = atom('old', 1)
- * const child = computed('child', () => oldParent.get())
- * // Later, detach the child from the old parent
- * detach(oldParent, child)
- * ```
  * @internal
  */
 export function detach(parent: Signal<any>, child: Child) {
-	// If the child is not attached to the parent, do nothing.
 	if (!parent.children.remove(child)) {
 		return
 	}
 
-	// If the parent has no more children, then detach the parent from its parents.
 	if (parent.children.isEmpty && isChild(parent)) {
 		for (let i = 0, n = parent.parents.length; i < n; i++) {
 			detach(parent.parents[i], parent)
@@ -79,32 +45,16 @@ export function detach(parent: Signal<any>, child: Child) {
 }
 
 /**
- * Attaches a child signal to its parent signal, establishing a parent-child relationship
- * in the reactive dependency graph. If the parent is itself a child, it will recursively
- * attach to its own parents to maintain the dependency chain.
+ * Adds `child` to `parent.children`. A computed parent that gains its first child starts
+ * listening itself, recursively, so that changes to any ancestor are traversed down to the child.
  *
- * This function is used internally when dependencies are captured during computed signal
- * evaluation or effect execution.
- *
- * @param parent - The parent signal to attach to
- * @param child - The child signal to attach
- * @example
- * ```ts
- * // When a computed signal captures a new dependency
- * const parentAtom = atom('parent', 1)
- * const child = computed('child', () => parentAtom.get())
- * // Internally, attach is called to establish the dependency
- * attach(parentAtom, child)
- * ```
  * @internal
  */
 export function attach(parent: Signal<any>, child: Child) {
-	// If the child is already attached to the parent, do nothing.
 	if (!parent.children.add(child)) {
 		return
 	}
 
-	// If the parent itself is a child, add the parent to the parent's parents.
 	if (isChild(parent)) {
 		for (let i = 0, n = parent.parents.length; i < n; i++) {
 			attach(parent.parents[i], parent)
@@ -113,25 +63,10 @@ export function attach(parent: Signal<any>, child: Child) {
 }
 
 /**
- * Checks if two values are equal using the equality semantics of @tldraw/state.
- *
- * This function performs equality checks in the following order:
- * 1. Reference equality (`===`)
- * 2. `Object.is()` equality (handles NaN and -0/+0 cases)
- * 3. Custom `.equals()` method when the left-hand value provides one
- *
- * This is used internally to determine if a signal's value has actually changed
- * when setting new values, preventing unnecessary updates and re-computations.
+ * The default equality used for change detection: `===`, then `Object.is` (so `NaN` equals
+ * `NaN`; `0` and `-0` are already equal by `===`), then the old value's own `.equals(b)` method
+ * if it has one. Only the old value's `equals` is consulted.
  *
- * @param a - The first value to compare
- * @param b - The second value to compare
- * @returns `true` if the values are considered equal, `false` otherwise
- * @example
- * ```ts
- * equals(1, 1) // true
- * equals(NaN, NaN) // true (unlike === which returns false)
- * equals({ equals: (other: any) => other.id === 1 }, { id: 1 }) // Uses custom equals method
- * ```
  * @internal
  */
 export function equals(a: any, b: any): boolean {
@@ -140,32 +75,6 @@ export function equals(a: any, b: any): boolean {
 	return shallowEquals
 }
 
-/**
- * A TypeScript utility function for exhaustiveness checking in switch statements and
- * conditional branches. This function should never be called at runtime—it exists
- * purely for compile-time type checking and is `undefined` in emitted JavaScript.
- *
- * @param x - A value that should be of type `never`
- * @throws Always at runtime because the identifier is undefined
- * @example
- * ```ts
- * type Color = 'red' | 'blue'
- *
- * function handleColor(color: Color) {
- *   switch (color) {
- *     case 'red':
- *       return 'Stop'
- *     case 'blue':
- *       return 'Go'
- *     default:
- *       return assertNever(color) // TypeScript error if not all cases handled
- *   }
- * }
- * ```
- * @public
- */
-export declare function assertNever(x: never): never
-
 /**
  * Creates or retrieves a singleton instance using a global symbol registry.
  * This ensures that the same instance is shared across all code that uses
@@ -199,37 +108,3 @@ export function singleton<T>(key: string, init: () => T): T {
  * @public
  */
 export const EMPTY_ARRAY: [] = singleton('empty_array', () => Object.freeze([]) as any)
-
-/**
- * Checks if a signal has any active reactors (effects or computed signals) that are
- * currently listening to it. This determines whether changes to the signal will
- * cause any side effects or recomputations to occur.
- *
- * A signal is considered to have active reactors if any of its child dependencies
- * are actively listening for changes.
- *
- * @param signal - The signal to check for active reactors
- * @returns `true` if the signal has active reactors, `false` otherwise
- * @example
- * ```ts
- * const count = atom('count', 0)
- *
- * console.log(hasReactors(count)) // false - no effects listening
- *
- * const stop = react('logger', () => console.log(count.get()))
- * console.log(hasReactors(count)) // true - effect is listening
- *
- * stop()
- * console.log(hasReactors(count)) // false - effect stopped
- * ```
- * @public
- */
-export function hasReactors(signal: Signal<any>) {
-	for (const child of signal.children) {
-		if (child.isActivelyListening) {
-			return true
-		}
-	}
-
-	return false
-}

package/src/lib/localStorageAtom.ts

@@ -75,12 +75,19 @@ export function localStorageAtom<Value, Diff = unknown>(
 		}
 	}
 
-	window.addEventListener('storage', handleStorageEvent)
+	// The storage helpers above tolerate environments without localStorage (Node, SSR); do the
+	// same here rather than throwing on `window`.
+	const canListen = typeof window !== 'undefined'
+	if (canListen) {
+		window.addEventListener('storage', handleStorageEvent)
+	}
 
 	// Combined cleanup function
 	const cleanup = () => {
 		reactCleanup()
-		window.removeEventListener('storage', handleStorageEvent)
+		if (canListen) {
+			window.removeEventListener('storage', handleStorageEvent)
+		}
 	}
 
 	return [outAtom, cleanup]

package/src/lib/transactions.ts

@@ -17,21 +17,11 @@ class Transaction {
 
 	initialAtomValues = new Map<_Atom, any>()
 
-	/**
-	 * Get whether this transaction is a root (no parents).
-	 *
-	 * @public
-	 */
 	// eslint-disable-next-line tldraw/no-setter-getter
 	get isRoot() {
 		return this.parent === null
 	}
 
-	/**
-	 * Commit the transaction's changes.
-	 *
-	 * @public
-	 */
 	commit() {
 		if (inst.globalIsReacting) {
 			// if we're committing during a reaction we actually need to
@@ -44,9 +34,17 @@ class Transaction {
 			flushChanges(this.initialAtomValues.keys())
 		} else {
 			// For transactions with parents, add the transaction's initial values to the parent's.
+			// A parent that has recorded nothing yet adopts the map outright: this transaction is
+			// finished with it, and the common nested case is a single inner transaction doing all
+			// the writes.
+			const parentValues = this.parent!.initialAtomValues
+			if (parentValues.size === 0) {
+				this.parent!.initialAtomValues = this.initialAtomValues
+				return
+			}
 			this.initialAtomValues.forEach((value, atom) => {
-				if (!this.parent!.initialAtomValues.has(atom)) {
-					this.parent!.initialAtomValues.set(atom, value)
+				if (!parentValues.has(atom)) {
+					parentValues.set(atom, value)
 				}
 			})
 		}
@@ -60,13 +58,11 @@ class Transaction {
 	abort() {
 		inst.globalEpoch++
 
-		// Reset each of the transaction's atoms to its initial value.
 		this.initialAtomValues.forEach((value, atom) => {
 			atom.set(value)
 			atom.historyBuffer?.clear()
 		})
 
-		// Commit the changes.
 		this.commit()
 	}
 }
@@ -115,7 +111,9 @@ export function getIsReacting() {
 	return inst.globalIsReacting
 }
 
-// Reusable state for traverse to avoid closure allocation
+// The set `traverseChild` collects reactors into. Module-level rather than a closure so that a
+// flush over thousands of atoms doesn't allocate a visitor per atom; traversal never runs user
+// code, so nothing can re-enter and swap it mid-walk.
 let traverseReactors: Set<Reactor>
 
 function traverseChild(child: Child) {
@@ -132,11 +130,6 @@ function traverseChild(child: Child) {
 	}
 }
 
-function traverse(reactors: Set<Reactor>, child: Child) {
-	traverseReactors = reactors
-	traverseChild(child)
-}
-
 /**
  * Collect all of the reactors that need to run for an atom and run them.
  *
@@ -154,11 +147,10 @@ function flushChanges(atoms: Iterable<_Atom>) {
 		inst.globalIsReacting = true
 		inst.reactionEpoch = inst.globalEpoch
 
-		// Collect all of the visited reactors.
 		const reactors = new Set<Reactor>()
-
+		traverseReactors = reactors
 		for (const atom of atoms) {
-			atom.children.visit((child) => traverse(reactors, child))
+			atom.children.visit(traverseChild)
 		}
 
 		// Run each reactor.
@@ -185,14 +177,7 @@ function flushChanges(atoms: Iterable<_Atom>) {
 	}
 }
 
-/**
- * Handle a change to an atom.
- *
- * @param atom The atom that changed.
- * @param previousValue The atom's previous value.
- *
- * @internal
- */
+/** @internal */
 export function atomDidChange(atom: _Atom, previousValue: any) {
 	if (inst.currentTransaction) {
 		// If we are in a transaction, then all we have to do is preserve
@@ -214,16 +199,11 @@ export function atomDidChange(atom: _Atom, previousValue: any) {
 }
 
 function traverseAtomForCleanup(atom: _Atom) {
-	const rs = (inst.cleanupReactors ??= new Set())
-	atom.children.visit((child) => traverse(rs, child))
+	traverseReactors = inst.cleanupReactors ??= new Set()
+	atom.children.visit(traverseChild)
 }
 
-/**
- * Advances the global epoch counter by one.
- * This is used internally to track when changes occur across the reactive system.
- *
- * @internal
- */
+/** @internal */
 export function advanceGlobalEpoch() {
 	inst.globalEpoch++
 }
@@ -251,7 +231,7 @@ export function advanceGlobalEpoch() {
  * // Logs "Hello, Jane Smith!"
  * ```
  *
- * If the function throws, the transaction is aborted and any signals that were updated during the transaction revert to their state before the transaction began.
+ * If the function throws, the transaction is aborted and any signals that were updated during the transaction revert to their state before the transaction began. An aborted transaction still flushes effects: effects whose parents went through a change-and-restore round trip are checked again and, if a parent's value differs from what they last saw (an atom they read directly always will), run once more with the restored values.
  *
  * @example
  * ```ts
@@ -269,8 +249,9 @@ export function advanceGlobalEpoch() {
  *  throw new Error('oops')
  * })
  *
- * // Does not log
  * // firstName.get() === 'John'
+ * // Logs "Hello, John Doe!" again: effects whose parents were changed and restored still run,
+ * // and observe the restored values.
  * ```
  *
  * A `rollback` callback is passed into the function.
@@ -293,9 +274,9 @@ export function advanceGlobalEpoch() {
  *  rollback()
  * })
  *
- * // Does not log
  * // firstName.get() === 'John'
  * // lastName.get() === 'Doe'
+ * // Logs "Hello, John Doe!" again, as above.
  * ```
  *
  * @param fn - The function to run in a transaction, called with a function to roll back the change.
@@ -305,7 +286,6 @@ export function advanceGlobalEpoch() {
 export function transaction<T>(fn: (rollback: () => void) => T) {
 	const txn = new Transaction(inst.currentTransaction, true)
 
-	// Set the current transaction to the transaction
 	inst.currentTransaction = txn
 
 	try {
@@ -313,10 +293,8 @@ export function transaction<T>(fn: (rollback: () => void) => T) {
 		let rollback = false
 
 		try {
-			// Run the function.
 			result = fn(() => (rollback = true))
 		} catch (e) {
-			// Abort the transaction if the function throws.
 			txn.abort()
 			throw e
 		}
@@ -326,7 +304,6 @@ export function transaction<T>(fn: (rollback: () => void) => T) {
 		}
 
 		if (rollback) {
-			// If the rollback was triggered, abort the transaction.
 			txn.abort()
 		} else {
 			txn.commit()
@@ -334,7 +311,6 @@ export function transaction<T>(fn: (rollback: () => void) => T) {
 
 		return result
 	} finally {
-		// Set the current transaction to the transaction's parent.
 		inst.currentTransaction = txn.parent
 	}
 }

package/src/lib/types.ts

@@ -9,12 +9,12 @@ import { ArraySet } from './ArraySet'
  *
  * @example
  * ```ts
- * import { atom, getGlobalEpoch, RESET_VALUE } from '@tldraw/state'
+ * import { atom, RESET_VALUE } from '@tldraw/state'
  *
- * const count = atom('count', 0, { historyLength: 3 })
- * const oldEpoch = getGlobalEpoch()
+ * const count = atom('count', 0, { historyLength: 3, computeDiff: (prev, next) => next - prev })
+ * const oldEpoch = count.lastChangedEpoch
  *
- * // Make many changes that exceed history length
+ * // Make more changes than the history length can hold
  * count.set(1)
  * count.set(2)
  * count.set(3)
@@ -183,8 +183,8 @@ export interface Child {
  * A function type that computes the difference between two values of a signal.
  *
  * This function is used to generate incremental diffs that can be applied to
- * reconstruct state changes over time. It's particularly useful for features
- * like undo/redo, synchronization, and change tracking.
+ * reconstruct state changes over time, so that downstream computeds and effects can
+ * update incrementally instead of recomputing from scratch.
  *
  * The function should analyze the previous and current values and return a
  * diff object that represents the change. If the diff cannot be computed
@@ -193,7 +193,7 @@ export interface Child {
  *
  * @param previousValue - The previous value of the signal
  * @param currentValue - The current value of the signal
- * @param lastComputedEpoch - The epoch when the previous value was set
+ * @param lastComputedEpoch - For an atom, the epoch when the previous value was set. For a computed, the epoch at which it was last checked (the same value its compute function receives), so that `other.getDiffSince(lastComputedEpoch)` yields exactly the changes not yet accounted for.
  * @param currentEpoch - The epoch when the current value was set
  * @returns A diff object representing the change, or the unique symbol RESET_VALUE if no diff can be computed
  *

package/src/lib/warnings.ts

@@ -1,10 +1,4 @@
-/**
- * Flag to track whether the computed getter deprecation warning has already been shown.
- * Prevents the same warning from being logged multiple times during application runtime.
- *
- * @internal
- */
-let didWarnComputedGetter = false
+import { warnOnce } from '@tldraw/utils'
 
 /**
  * Logs a deprecation warning for the deprecated `@computed` getter decorator syntax.
@@ -37,9 +31,7 @@ let didWarnComputedGetter = false
  * @internal
  */
 export function logComputedGetterWarning() {
-	if (didWarnComputedGetter) return
-	didWarnComputedGetter = true
-	console.warn(
+	warnOnce(
 		`Using \`@computed\` as a decorator for getters is deprecated and will be removed in the near future. Please refactor to use \`@computed\` as a decorator for methods.
 
 // Before