@tldraw/state 4.0.2 → 4.1.0-canary.0259516ffb8c

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

@@ -0,0 +1,168 @@
+import { describe, expect, it, vi } from 'vitest'
+import { ArraySet } from '../ArraySet'
+import { atom } from '../Atom'
+import { reactor } from '../EffectScheduler'
+import { attach, detach, equals, hasReactors, haveParentsChanged, singleton } from '../helpers'
+import { Child } from '../types'
+
+describe('helpers', () => {
+	describe('haveParentsChanged', () => {
+		it('returns false when no parents exist', () => {
+			const child: Child = {
+				parents: [],
+				parentEpochs: [],
+				parentSet: new ArraySet(),
+				name: 'test-child',
+				lastTraversedEpoch: 0,
+				isActivelyListening: true,
+				__debug_ancestor_epochs__: null,
+			}
+
+			expect(haveParentsChanged(child)).toBe(false)
+		})
+
+		it('returns true when parent epoch has changed', () => {
+			const parentAtom = atom('parent', 1)
+			const oldEpoch = parentAtom.lastChangedEpoch
+
+			const child: Child = {
+				parents: [parentAtom],
+				parentEpochs: [oldEpoch],
+				parentSet: new ArraySet(),
+				name: 'test-child',
+				lastTraversedEpoch: 0,
+				isActivelyListening: true,
+				__debug_ancestor_epochs__: null,
+			}
+
+			// Change the parent, which should update its epoch
+			parentAtom.set(2)
+
+			expect(haveParentsChanged(child)).toBe(true)
+		})
+
+		it('returns true when any parent has changed among multiple parents', () => {
+			const parent1 = atom('parent1', 1)
+			const parent2 = atom('parent2', 2)
+			const oldEpoch1 = parent1.lastChangedEpoch
+			const oldEpoch2 = parent2.lastChangedEpoch
+
+			const child: Child = {
+				parents: [parent1, parent2],
+				parentEpochs: [oldEpoch1, oldEpoch2],
+				parentSet: new ArraySet(),
+				name: 'test-child',
+				lastTraversedEpoch: 0,
+				isActivelyListening: true,
+				__debug_ancestor_epochs__: null,
+			}
+
+			// Change only the second parent
+			parent2.set(3)
+
+			expect(haveParentsChanged(child)).toBe(true)
+		})
+	})
+
+	describe('detach', () => {
+		it('removes child from parent children when attached', () => {
+			const parent = atom('parent', 1)
+			const child: Child = {
+				parents: [],
+				parentEpochs: [],
+				parentSet: new ArraySet(),
+				name: 'test-child',
+				lastTraversedEpoch: 0,
+				isActivelyListening: true,
+				__debug_ancestor_epochs__: null,
+			}
+
+			parent.children.add(child)
+			expect(parent.children.size()).toBe(1)
+
+			detach(parent, child)
+
+			expect(parent.children.size()).toBe(0)
+		})
+	})
+
+	describe('attach', () => {
+		it('adds child to parent children when not already attached', () => {
+			const parent = atom('parent', 1)
+			const child: Child = {
+				parents: [],
+				parentEpochs: [],
+				parentSet: new ArraySet(),
+				name: 'test-child',
+				lastTraversedEpoch: 0,
+				isActivelyListening: true,
+				__debug_ancestor_epochs__: null,
+			}
+
+			expect(parent.children.size()).toBe(0)
+
+			attach(parent, child)
+
+			expect(parent.children.size()).toBe(1)
+			expect(Array.from(parent.children)).toContain(child)
+		})
+	})
+
+	describe('equals', () => {
+		it('returns true for identical references and Object.is cases', () => {
+			const obj = { a: 1 }
+			expect(equals(obj, obj)).toBe(true)
+			expect(equals(1, 1)).toBe(true)
+			expect(equals(NaN, NaN)).toBe(true)
+		})
+
+		it('returns false for different values', () => {
+			expect(equals(1, 2)).toBe(false)
+			expect(equals({ id: 1 }, { id: 1 })).toBe(false)
+		})
+
+		it('uses custom equals method when available', () => {
+			const obj1 = {
+				id: 1,
+				equals: (other: any) => other && other.id === 1,
+			}
+			const obj2 = { id: 1, name: 'test' }
+
+			expect(equals(obj1, obj2)).toBe(true)
+		})
+	})
+
+	describe('singleton', () => {
+		it('returns same instance on subsequent calls with same key', () => {
+			const init = vi.fn(() => ({ value: 42 }))
+
+			const instance1 = singleton('test-singleton', init)
+			const instance2 = singleton('test-singleton', init)
+
+			expect(init).toHaveBeenCalledTimes(1)
+			expect(instance1).toBe(instance2)
+		})
+	})
+
+	describe('hasReactors', () => {
+		it('returns false when signal has no actively listening children', () => {
+			const signal = atom('test', 1)
+			expect(hasReactors(signal)).toBe(false)
+		})
+
+		it('integrates correctly with real reactive signals', () => {
+			const baseAtom = atom('base', 1)
+			expect(hasReactors(baseAtom)).toBe(false)
+
+			const reactorInstance = reactor('test-reactor', () => {
+				baseAtom.get()
+			})
+
+			reactorInstance.start()
+			expect(hasReactors(baseAtom)).toBe(true)
+
+			reactorInstance.stop()
+			expect(hasReactors(baseAtom)).toBe(false)
+		})
+	})
+})

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

@@ -0,0 +1,183 @@
+import { localStorageAtom } from '../localStorageAtom'
+import { getGlobalEpoch } from '../transactions'
+
+// Mock localStorage
+const mockLocalStorage = (() => {
+	let store: Record<string, string> = {}
+
+	return {
+		getItem: vi.fn((key: string) => store[key] || null),
+		setItem: vi.fn((key: string, value: string) => {
+			store[key] = value
+		}),
+		removeItem: vi.fn((key: string) => {
+			delete store[key]
+		}),
+		clear: vi.fn(() => {
+			store = {}
+		}),
+		get length() {
+			return Object.keys(store).length
+		},
+		key: vi.fn((index: number) => Object.keys(store)[index] || null),
+		// Internal helper to reset store
+		_reset: () => {
+			store = {}
+		},
+	}
+})()
+
+// Mock the @tldraw/utils functions
+vi.mock('@tldraw/utils', () => ({
+	getFromLocalStorage: (key: string) => mockLocalStorage.getItem(key),
+	setInLocalStorage: (key: string, value: string) => mockLocalStorage.setItem(key, value),
+	deleteFromLocalStorage: (key: string) => mockLocalStorage.removeItem(key),
+}))
+
+describe('localStorageAtom', () => {
+	beforeEach(() => {
+		mockLocalStorage._reset()
+		vi.clearAllMocks()
+	})
+
+	describe('initialization', () => {
+		it('should create atom with initial value when localStorage is empty', () => {
+			const [atom, cleanup] = localStorageAtom('test-key', 'initial-value')
+
+			expect(atom.get()).toBe('initial-value')
+			cleanup()
+		})
+
+		it('should restore value from localStorage when it exists', () => {
+			mockLocalStorage.setItem('test-key', JSON.stringify('stored-value'))
+
+			const [atom, cleanup] = localStorageAtom('test-key', 'initial-value')
+
+			expect(atom.get()).toBe('stored-value')
+			cleanup()
+		})
+	})
+
+	describe('corrupted localStorage handling', () => {
+		it('should use initial value and delete corrupted localStorage entry', () => {
+			mockLocalStorage.setItem('test-key', 'invalid-json')
+
+			const [atom, cleanup] = localStorageAtom('test-key', 'initial-value')
+
+			expect(atom.get()).toBe('initial-value')
+			expect(mockLocalStorage.removeItem).toHaveBeenCalledWith('test-key')
+			cleanup()
+		})
+
+		it('should handle empty string in localStorage', () => {
+			mockLocalStorage.setItem('test-key', '')
+
+			const [atom, cleanup] = localStorageAtom('test-key', 'initial-value')
+
+			// Empty string should be falsy, so initial value is used
+			expect(atom.get()).toBe('initial-value')
+			cleanup()
+		})
+	})
+
+	describe('localStorage synchronization', () => {
+		it('should save to localStorage when atom value changes', () => {
+			const [atom, cleanup] = localStorageAtom('test-key', 'initial')
+
+			atom.set('new-value')
+
+			expect(mockLocalStorage.setItem).toHaveBeenCalledWith('test-key', JSON.stringify('new-value'))
+			cleanup()
+		})
+
+		it('should update localStorage on multiple changes', () => {
+			const [atom, cleanup] = localStorageAtom('counter', 0)
+
+			// Clear initial call from atom creation
+			vi.clearAllMocks()
+
+			atom.set(1)
+			atom.set(2)
+			atom.set(3)
+
+			expect(mockLocalStorage.setItem).toHaveBeenCalledTimes(3)
+			expect(mockLocalStorage.setItem).toHaveBeenNthCalledWith(1, 'counter', JSON.stringify(1))
+			expect(mockLocalStorage.setItem).toHaveBeenNthCalledWith(2, 'counter', JSON.stringify(2))
+			expect(mockLocalStorage.setItem).toHaveBeenNthCalledWith(3, 'counter', JSON.stringify(3))
+			cleanup()
+		})
+	})
+
+	describe('cleanup functionality', () => {
+		it('should stop syncing to localStorage after cleanup', () => {
+			const [atom, cleanup] = localStorageAtom('test-key', 'initial')
+
+			// Change value before cleanup - should sync
+			atom.set('before-cleanup')
+			expect(mockLocalStorage.setItem).toHaveBeenCalledWith(
+				'test-key',
+				JSON.stringify('before-cleanup')
+			)
+
+			// Clear mocks and cleanup
+			vi.clearAllMocks()
+			cleanup()
+
+			// Change value after cleanup - should not sync
+			atom.set('after-cleanup')
+			expect(mockLocalStorage.setItem).not.toHaveBeenCalled()
+		})
+
+		it('should allow atom to continue functioning after cleanup', () => {
+			const [atom, cleanup] = localStorageAtom('test-key', 'initial')
+
+			cleanup()
+
+			atom.set('new-value')
+			expect(atom.get()).toBe('new-value')
+		})
+	})
+
+	describe('atom options', () => {
+		it('should pass through atom options', () => {
+			const isEqual = (a: string, b: string) => a.toLowerCase() === b.toLowerCase()
+			const [atom, cleanup] = localStorageAtom('test-key', 'Hello', { isEqual })
+
+			atom.set('HELLO')
+			expect(atom.get()).toBe('Hello') // Should use custom equality
+			cleanup()
+		})
+
+		it('should work with history options', () => {
+			const [atom, cleanup] = localStorageAtom('test-key', 0, {
+				historyLength: 3,
+				computeDiff: (a, b) => b - a,
+			})
+
+			const startEpoch = getGlobalEpoch()
+
+			atom.set(5)
+			atom.set(10)
+
+			const diffs = atom.getDiffSince(startEpoch)
+			expect(diffs).toEqual([5, 5])
+			cleanup()
+		})
+	})
+
+	describe('multiple instances', () => {
+		it('should handle multiple atoms with different keys', () => {
+			const [atom1, cleanup1] = localStorageAtom('key1', 'value1')
+			const [atom2, cleanup2] = localStorageAtom('key2', 'value2')
+
+			atom1.set('updated1')
+			atom2.set('updated2')
+
+			expect(mockLocalStorage.setItem).toHaveBeenCalledWith('key1', JSON.stringify('updated1'))
+			expect(mockLocalStorage.setItem).toHaveBeenCalledWith('key2', JSON.stringify('updated2'))
+
+			cleanup1()
+			cleanup2()
+		})
+	})
+})

package/src/lib/capture.ts

@@ -48,6 +48,25 @@ export function unsafe__withoutCapture<T>(fn: () => T): T {
 	}
 }
 
+/**
+ * Begins capturing parent signal dependencies for the given child signal.
+ *
+ * This function initiates a capture session where any signal accessed via `.get()`
+ * will be automatically registered as a dependency of the child signal. It sets up
+ * the capture stack frame and clears the existing parent set to prepare for fresh
+ * dependency tracking.
+ *
+ * @param child - The child signal (computed or effect) that will capture dependencies
+ *
+ * @example
+ * ```ts
+ * const effect = createEffect('myEffect', () => { /* ... *\/ })
+ * startCapturingParents(effect)
+ * // Now any signal.get() calls will be captured as dependencies
+ * ```
+ *
+ * @internal
+ */
 export function startCapturingParents(child: Child) {
 	inst.stack = new CaptureStackFrame(inst.stack, child)
 	if (child.__debug_ancestor_epochs__) {
@@ -61,6 +80,23 @@ export function startCapturingParents(child: Child) {
 	child.parentSet.clear()
 }
 
+/**
+ * Completes the parent dependency capture session and finalizes the dependency graph.
+ *
+ * This function cleans up the capture session by removing dependencies that are no
+ * longer needed, detaching signals that should no longer be parents, and updating
+ * the dependency arrays to reflect the current set of captured parents. It must be
+ * called after `startCapturingParents` to complete the capture cycle.
+ *
+ * @example
+ * ```ts
+ * startCapturingParents(effect)
+ * // ... signal.get() calls happen here ...
+ * stopCapturingParents() // Finalizes the dependency graph
+ * ```
+ *
+ * @internal
+ */
 export function stopCapturingParents() {
 	const frame = inst.stack!
 	inst.stack = frame.below
@@ -91,7 +127,26 @@ export function stopCapturingParents() {
 	}
 }
 
-// this must be called after the parent is up to date
+/**
+ * Conditionally captures a signal as a parent dependency during an active capture session.
+ *
+ * This function is called whenever a signal's `.get()` method is invoked during a
+ * capture session. It checks if the signal should be added as a dependency and manages
+ * the parent-child relationship in the reactive graph. The function handles deduplication,
+ * attachment/detachment, and tracks changes in dependency order.
+ *
+ * Note: This must be called after the parent signal is up to date.
+ *
+ * @param p - The signal that might be captured as a parent dependency
+ *
+ * @example
+ * ```ts
+ * // This is called internally when you do:
+ * const value = someAtom.get() // maybeCaptureParent(someAtom) is called
+ * ```
+ *
+ * @internal
+ */
 export function maybeCaptureParent(p: Signal<any, any>) {
 	if (inst.stack) {
 		const wasCapturedAlready = inst.stack.child.parentSet.has(p)

package/src/lib/constants.ts

@@ -1,2 +1,26 @@
-// Derivations start on GLOBAL_START_EPOCH so they are dirty before having been computed
+/**
+ * The initial epoch value used to mark derivations (computed signals and effects) as dirty before their first computation.
+ *
+ * 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
+ */
 export const GLOBAL_START_EPOCH = -1

package/src/lib/helpers.ts

@@ -5,16 +5,30 @@ import { Child, Signal } from './types'
  *
  * @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
 }
 
 /**
- * Get whether a child's parents have changed.
+ * 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.
  *
- * @param child The child to check.
- * @returns True if the child's parents have changed, false otherwise.
+ * 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.
+ *
+ * @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++) {
@@ -31,10 +45,24 @@ export function haveParentsChanged(child: Child): boolean {
 }
 
 /**
- * Detach a child from a parent.
+ * 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.
  *
- * @param parent The parent to detach from.
- * @param child The child to detach.
+ * @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.
@@ -51,10 +79,24 @@ export function detach(parent: Signal<any>, child: Child) {
 }
 
 /**
- * Attach a child to a parent.
+ * 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.
+ *
+ * This function is used internally when dependencies are captured during computed signal
+ * evaluation or effect execution.
  *
- * @param parent The parent to attach to.
- * @param child The child to attach.
+ * @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.
@@ -71,10 +113,26 @@ export function attach(parent: Signal<any>, child: Child) {
 }
 
 /**
- * Get whether two values are equal (insofar as @tldraw/state is concerned).
+ * 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.
  *
- * @param a The first value.
- * @param b The second value.
+ * @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 {
 	const shallowEquals =
@@ -82,8 +140,54 @@ 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
+ * the same key, even across different module boundaries.
+ *
+ * The singleton is stored on `globalThis` using a symbol created with
+ * `Symbol.for()`, which ensures global uniqueness across realms.
+ *
+ * @param key - A unique string identifier for the singleton
+ * @param init - A function that creates the initial value if it doesn't exist
+ * @returns The singleton instance
+ * @example
+ * ```ts
+ * // Create a singleton logger
+ * const logger = singleton('logger', () => new Logger())
+ *
+ * // Elsewhere in the codebase, get the same logger instance
+ * const sameLogger = singleton('logger', () => new Logger())
+ * // logger === sameLogger
+ * ```
+ * @internal
+ */
 export function singleton<T>(key: string, init: () => T): T {
 	const symbol = Symbol.for(`com.tldraw.state/${key}`)
 	const global = globalThis as any
@@ -97,7 +201,27 @@ export function singleton<T>(key: string, init: () => T): T {
 export const EMPTY_ARRAY: [] = singleton('empty_array', () => Object.freeze([]) as any)
 
 /**
- * Does this signal have any active reactors attached to it? When it changes, will it cause anything to run?
+ * 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>) {

package/src/lib/isSignal.ts

@@ -3,6 +3,30 @@ import { _Computed } from './Computed'
 import { Signal } from './types'
 
 /**
+ * Type guard function that determines whether a value is a signal (either an Atom or Computed).
+ *
+ * This utility function is helpful when working with mixed data types and you need to
+ * differentiate between regular values and reactive signal containers. It returns `true`
+ * if the provided value is either an atomic signal created with `atom()` or a computed
+ * signal created with `computed()`.
+ *
+ * @param value - The value to check, can be of any type
+ * @returns `true` if the value is a Signal (Atom or Computed), `false` otherwise
+ *
+ * @example
+ * ```ts
+ * import { atom, computed, isSignal } from '@tldraw/state'
+ *
+ * const count = atom('count', 5)
+ * const doubled = computed('doubled', () => count.get() * 2)
+ * const regularValue = 'hello'
+ *
+ * console.log(isSignal(count))        // true
+ * console.log(isSignal(doubled))      // true
+ * console.log(isSignal(regularValue)) // false
+ * console.log(isSignal(null))         // false
+ * ```
+ *
  * @public
  */
 export function isSignal(value: any): value is Signal<any> {