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

package/src/lib/localStorageAtom.ts

@@ -0,0 +1,87 @@
+import { deleteFromLocalStorage, getFromLocalStorage, setInLocalStorage } from '@tldraw/utils'
+import { Atom, atom, AtomOptions } from './Atom'
+import { react } from './EffectScheduler'
+
+/**
+ * Creates a new {@link Atom} that persists its value to localStorage.
+ *
+ * The atom is automatically synced with localStorage - changes to the atom are saved to localStorage,
+ * and the initial value is read from localStorage if it exists. Returns both the atom and a cleanup
+ * function that should be called to stop syncing when the atom is no longer needed. If you need to delete
+ * the atom, you should do it manually after all cleanup functions have been called.
+ *
+ * @example
+ * ```ts
+ * const [theme, cleanup] = localStorageAtom('theme', 'light')
+ *
+ * theme.get() // 'light' or value from localStorage if it exists
+ *
+ * theme.set('dark') // updates atom and saves to localStorage
+ *
+ * // When done:
+ * cleanup() // stops syncing to localStorage
+ * ```
+ *
+ * @param name - The localStorage key and atom name. This is used for both localStorage persistence
+ *   and debugging/profiling purposes.
+ * @param initialValue - The initial value of the atom, used if no value exists in localStorage.
+ * @param options - Optional atom configuration. See {@link AtomOptions}.
+ * @returns A tuple containing the atom and a cleanup function to stop localStorage syncing.
+ * @public
+ */
+export function localStorageAtom<Value, Diff = unknown>(
+	name: string,
+	initialValue: Value,
+	options?: AtomOptions<Value, Diff>
+): [Atom<Value, Diff>, () => void] {
+	// Try to restore the initial value from localStorage
+	let _initialValue = initialValue
+
+	try {
+		const value = getFromLocalStorage(name)
+		if (value) {
+			_initialValue = JSON.parse(value) as Value
+		}
+	} catch {
+		// If parsing fails, the stored value is corrupted - delete it and use the provided initial value
+		deleteFromLocalStorage(name)
+	}
+
+	// Create the atom with the restored or initial value
+	const outAtom = atom(name, _initialValue, options)
+
+	// Set up automatic syncing: whenever the atom changes, save it to localStorage
+	const reactCleanup = react(`save ${name} to localStorage`, () => {
+		setInLocalStorage(name, JSON.stringify(outAtom.get()))
+	})
+
+	// Set up cross-tab sync: listen for storage events from other tabs
+	const handleStorageEvent = (event: StorageEvent) => {
+		// Only handle events for this specific key
+		if (event.key !== name) return
+
+		// If the value was deleted in another tab
+		if (event.newValue === null) {
+			outAtom.set(initialValue)
+			return
+		}
+
+		// If the value was changed in another tab, update the atom
+		try {
+			const newValue = JSON.parse(event.newValue) as Value
+			outAtom.set(newValue)
+		} catch {
+			// If parsing fails, the stored value is corrupted; preserve the existing value
+		}
+	}
+
+	window.addEventListener('storage', handleStorageEvent)
+
+	// Combined cleanup function
+	const cleanup = () => {
+		reactCleanup()
+		window.removeEventListener('storage', handleStorageEvent)
+	}
+
+	return [outAtom, cleanup]
+}

package/src/lib/transactions.ts

@@ -78,14 +78,35 @@ const inst = singleton('transactions', () => ({
 	reactionEpoch: GLOBAL_START_EPOCH + 1,
 }))
 
+/**
+ * Gets the current reaction epoch, which is used to track when reactions are running.
+ * The reaction epoch is updated at the start of each reaction cycle.
+ *
+ * @returns The current reaction epoch number
+ * @public
+ */
 export function getReactionEpoch() {
 	return inst.reactionEpoch
 }
 
+/**
+ * Gets the current global epoch, which is incremented every time any atom changes.
+ * This is used to track changes across the entire reactive system.
+ *
+ * @returns The current global epoch number
+ * @public
+ */
 export function getGlobalEpoch() {
 	return inst.globalEpoch
 }
 
+/**
+ * Checks whether any reactions are currently executing.
+ * When true, the system is in the middle of processing effects and side effects.
+ *
+ * @returns True if reactions are currently running, false otherwise
+ * @public
+ */
 export function getIsReacting() {
 	return inst.globalIsReacting
 }
@@ -184,20 +205,27 @@ function traverseAtomForCleanup(atom: _Atom) {
 	atom.children.visit((child) => traverse(rs, child))
 }
 
+/**
+ * Advances the global epoch counter by one.
+ * This is used internally to track when changes occur across the reactive system.
+ *
+ * @internal
+ */
 export function advanceGlobalEpoch() {
 	inst.globalEpoch++
 }
 
 /**
  * Batches state updates, deferring side effects until after the transaction completes.
+ * Unlike {@link transact}, this function always creates a new transaction, allowing for nested transactions.
  *
  * @example
  * ```ts
- * const firstName = atom('John')
- * const lastName = atom('Doe')
+ * const firstName = atom('firstName', 'John')
+ * const lastName = atom('lastName', 'Doe')
  *
  * react('greet', () => {
- *   print(`Hello, ${firstName.get()} ${lastName.get()}!`)
+ *   console.log(`Hello, ${firstName.get()} ${lastName.get()}!`)
  * })
  *
  * // Logs "Hello, John Doe!"
@@ -214,11 +242,11 @@ export function advanceGlobalEpoch() {
  *
  * @example
  * ```ts
- * const firstName = atom('John')
- * const lastName = atom('Doe')
+ * const firstName = atom('firstName', 'John')
+ * const lastName = atom('lastName', 'Doe')
  *
  * react('greet', () => {
- *   print(`Hello, ${firstName.get()} ${lastName.get()}!`)
+ *   console.log(`Hello, ${firstName.get()} ${lastName.get()}!`)
  * })
  *
  * // Logs "Hello, John Doe!"
@@ -237,11 +265,11 @@ export function advanceGlobalEpoch() {
  *
  * @example
  * ```ts
- * const firstName = atom('John')
- * const lastName = atom('Doe')
+ * const firstName = atom('firstName', 'John')
+ * const lastName = atom('lastName', 'Doe')
  *
  * react('greet', () => {
- *   print(`Hello, ${firstName.get()} ${lastName.get()}!`)
+ *   console.log(`Hello, ${firstName.get()} ${lastName.get()}!`)
  * })
  *
  * // Logs "Hello, John Doe!"
@@ -258,6 +286,7 @@ export function advanceGlobalEpoch() {
  * ```
  *
  * @param fn - The function to run in a transaction, called with a function to roll back the change.
+ * @returns The return value of the function
  * @public
  */
 export function transaction<T>(fn: (rollback: () => void) => T) {
@@ -299,8 +328,27 @@ export function transaction<T>(fn: (rollback: () => void) => T) {
 
 /**
  * Like {@link transaction}, but does not create a new transaction if there is already one in progress.
+ * This is the preferred way to batch state updates when you don't need the rollback functionality.
  *
- * @param fn - The function to run in a transaction.
+ * @example
+ * ```ts
+ * const count = atom('count', 0)
+ * const doubled = atom('doubled', 0)
+ *
+ * react('update doubled', () => {
+ *   console.log(`Count: ${count.get()}, Doubled: ${doubled.get()}`)
+ * })
+ *
+ * // This batches both updates into a single reaction
+ * transact(() => {
+ *   count.set(5)
+ *   doubled.set(count.get() * 2)
+ * })
+ * // Logs: "Count: 5, Doubled: 10"
+ * ```
+ *
+ * @param fn - The function to run in a transaction
+ * @returns The return value of the function
  * @public
  */
 export function transact<T>(fn: () => T): T {
@@ -311,6 +359,27 @@ export function transact<T>(fn: () => T): T {
 }
 
 /**
+ * Defers the execution of asynchronous effects until they can be properly handled.
+ * This function creates an asynchronous transaction context that batches state updates
+ * across async operations while preventing conflicts with synchronous transactions.
+ *
+ * @example
+ * ```ts
+ * const data = atom('data', null)
+ * const loading = atom('loading', false)
+ *
+ * await deferAsyncEffects(async () => {
+ *   loading.set(true)
+ *   const result = await fetch('/api/data')
+ *   const json = await result.json()
+ *   data.set(json)
+ *   loading.set(false)
+ * })
+ * ```
+ *
+ * @param fn - The async function to execute within the deferred context
+ * @returns A promise that resolves to the return value of the function
+ * @throws Will throw if called during a synchronous transaction
  * @internal
  */
 export async function deferAsyncEffects<T>(fn: () => Promise<T>) {

package/src/lib/types.ts

@@ -1,68 +1,222 @@
 import { ArraySet } from './ArraySet'
 
-/** @public */
+/**
+ * A unique symbol used to indicate that a signal's value should be reset or that
+ * there is insufficient history to compute diffs between epochs.
+ *
+ * This value is returned by {@link Signal.getDiffSince} when the requested epoch
+ * is too far in the past and the diff sequence cannot be reconstructed.
+ *
+ * @example
+ * ```ts
+ * import { atom, getGlobalEpoch, RESET_VALUE } from '@tldraw/state'
+ *
+ * const count = atom('count', 0, { historyLength: 3 })
+ * const oldEpoch = getGlobalEpoch()
+ *
+ * // Make many changes that exceed history length
+ * count.set(1)
+ * count.set(2)
+ * count.set(3)
+ * count.set(4)
+ *
+ * const diffs = count.getDiffSince(oldEpoch)
+ * if (diffs === RESET_VALUE) {
+ *   console.log('Too many changes, need to reset state')
+ * }
+ * ```
+ *
+ * @public
+ */
 export const RESET_VALUE: unique symbol = Symbol.for('com.tldraw.state/RESET_VALUE')
 
-/** @public */
+/**
+ * Type representing the the unique symbol RESET_VALUE symbol, used in type annotations
+ * to indicate when a signal value should be reset or when diff computation
+ * cannot proceed due to insufficient history.
+ *
+ * @public
+ */
 export type RESET_VALUE = typeof RESET_VALUE
 
 /**
- * A Signal is a reactive value container. The value may change over time, and it may keep track of the diffs between sequential values.
+ * A reactive value container that can change over time and track diffs between sequential values.
+ *
+ * Signals are the foundation of the \@tldraw/state reactive system. They automatically manage
+ * dependencies and trigger updates when their values change. Any computed signal or effect
+ * that reads from this signal will be automatically recomputed when the signal's value changes.
  *
  * There are two types of signal:
+ * - **Atomic signals** - Created using `atom()`. These are mutable containers that can be
+ *   directly updated using `set()` or `update()` methods.
+ * - **Computed signals** - Created using `computed()`. These derive their values from other
+ *   signals and are automatically recomputed when dependencies change.
+ *
+ * @example
+ * ```ts
+ * import { atom, computed } from '@tldraw/state'
  *
- * - Atomic signals, created using {@link atom}. These are mutable references to values that can be changed using {@link Atom.set}.
- * - Computed signals, created using `computed`. These are values that are computed from other signals. They are recomputed lazily if their dependencies change.
+ * // Create an atomic signal
+ * const count = atom('count', 0)
+ *
+ * // Create a computed signal that derives from the atom
+ * const doubled = computed('doubled', () => count.get() * 2)
+ *
+ * console.log(doubled.get()) // 0
+ * count.set(5)
+ * console.log(doubled.get()) // 10
+ * ```
  *
  * @public
  */
 export interface Signal<Value, Diff = unknown> {
 	/**
-	 * The name of the signal. This is used at runtime for debugging and perf profiling only. It does not need to be globally unique.
+	 * A human-readable identifier for this signal, used primarily for debugging and performance profiling.
+	 *
+	 * The name is displayed in debug output from {@link whyAmIRunning} and other diagnostic tools.
+	 * It does not need to be globally unique within your application.
 	 */
 	name: string
 	/**
-	 * The current value of the signal. This is a reactive value, and will update when the signal changes.
-	 * Any computed signal that depends on this signal will be lazily recomputed if this signal changes.
-	 * Any effect that depends on this signal will be rescheduled if this signal changes.
+	 * Gets the current value of the signal and establishes a dependency relationship.
+	 *
+	 * When called from within a computed signal or effect, this signal will be automatically
+	 * tracked as a dependency. If this signal's value changes, any dependent computations
+	 * or effects will be marked for re-execution.
+	 *
+	 * @returns The current value stored in the signal
 	 */
 	get(): Value
 
 	/**
-	 * The epoch when this signal's value last changed. Note that this is not the same as when the value was last computed.
-	 * A signal may recompute it's value without changing it.
+	 * The global epoch number when this signal's value last changed.
+	 *
+	 * Note that this represents when the value actually changed, not when it was last computed.
+	 * A computed signal may recalculate and produce the same value without changing its epoch.
+	 * This is used internally for dependency tracking and history management.
 	 */
 	lastChangedEpoch: number
 	/**
-	 * Returns the sequence of diffs between the the value at the given epoch and the current value.
-	 * Returns the `RESET_VALUE` constant if there is not enough information to compute the diff sequence.
-	 * @param epoch - The epoch to get diffs since.
+	 * Gets the sequence of diffs that occurred between a specific epoch and the current state.
+	 *
+	 * This method enables incremental synchronization by providing a list of changes that
+	 * have occurred since a specific point in time. If the requested epoch is too far in
+	 * the past or the signal doesn't have enough history, it returns the unique symbol RESET_VALUE
+	 * to indicate that a full state reset is required.
+	 *
+	 * @param epoch - The epoch timestamp to get diffs since
+	 * @returns An array of diff objects representing changes since the epoch, or the unique symbol RESET_VALUE if insufficient history is available
 	 */
 	getDiffSince(epoch: number): RESET_VALUE | Diff[]
 	/**
-	 * Returns the current value of the signal without capturing it as a dependency.
-	 * Use this if you need to retrieve the signal's value in a hot loop where the performance overhead of dependency tracking is too high.
+	 * Gets the current value of the signal without establishing a dependency relationship.
+	 *
+	 * This method bypasses the automatic dependency tracking system, making it useful for
+	 * performance-critical code paths where the overhead of dependency capture would be
+	 * problematic. Use with caution as it breaks the reactive guarantees of the system.
+	 *
+	 * **Warning**: This method should only be used when you're certain that you don't need
+	 * the calling context to react to changes in this signal.
+	 *
+	 * @param ignoreErrors - Whether to suppress errors during value retrieval (optional)
+	 * @returns The current value without establishing dependencies
 	 */
 	__unsafe__getWithoutCapture(ignoreErrors?: boolean): Value
 	/** @internal */
 	children: ArraySet<Child>
 }
 
-/** @internal */
+/**
+ * Internal interface representing a child node in the signal dependency graph.
+ *
+ * This interface is used internally by the reactive system to manage dependencies
+ * between signals, computed values, and effects. Each child tracks its parent
+ * signals and maintains state needed for efficient dependency graph traversal
+ * and change propagation.
+ *
+ * @internal
+ */
 export interface Child {
+	/**
+	 * The epoch when this child was last traversed during dependency graph updates.
+	 * Used to prevent redundant traversals during change propagation.
+	 */
 	lastTraversedEpoch: number
+
+	/**
+	 * Set of parent signals that this child depends on.
+	 * Used for efficient lookup and cleanup operations.
+	 */
 	readonly parentSet: ArraySet<Signal<any, any>>
+
+	/**
+	 * Array of parent signals that this child depends on.
+	 * Maintained in parallel with parentSet for ordered access.
+	 */
 	readonly parents: Signal<any, any>[]
+
+	/**
+	 * Array of epochs corresponding to each parent signal.
+	 * Used to detect which parents have changed since last computation.
+	 */
 	readonly parentEpochs: number[]
+
+	/**
+	 * Human-readable name for this child, used in debugging output.
+	 */
 	readonly name: string
+
+	/**
+	 * Whether this child is currently subscribed to change notifications.
+	 * Used to optimize resource usage by unsubscribing inactive dependencies.
+	 */
 	isActivelyListening: boolean
+
+	/**
+	 * Debug information tracking ancestor epochs in the dependency graph.
+	 * Only populated in debug builds for diagnostic purposes.
+	 */
 	__debug_ancestor_epochs__: Map<Signal<any, any>, number> | null
 }
 
 /**
- * Computes the diff between the previous and current value.
+ * 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.
+ *
+ * The function should analyze the previous and current values and return a
+ * diff object that represents the change. If the diff cannot be computed
+ * (e.g., the values are too different or incompatible), it should return
+ * the unique symbol RESET_VALUE to indicate that a full state reset is required.
+ *
+ * @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 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
+ *
+ * @example
+ * ```ts
+ * import { atom, RESET_VALUE } from '@tldraw/state'
+ *
+ * // Simple numeric diff
+ * const numberDiff: ComputeDiff<number, number> = (prev, curr) => curr - prev
+ *
+ * // Array diff with reset fallback
+ * const arrayDiff: ComputeDiff<string[], { added: string[], removed: string[] }> = (prev, curr) => {
+ *   if (prev.length > 1000 || curr.length > 1000) {
+ *     return RESET_VALUE // Too complex, force reset
+ *   }
+ *   return {
+ *     added: curr.filter(item => !prev.includes(item)),
+ *     removed: prev.filter(item => !curr.includes(item))
+ *   }
+ * }
  *
- * If the diff cannot be computed for whatever reason, it should return {@link state#RESET_VALUE}.
+ * const count = atom('count', 0, { computeDiff: numberDiff })
+ * ```
  *
  * @public
  */

package/src/lib/warnings.ts

@@ -1,5 +1,41 @@
+/**
+ * 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
 
+/**
+ * Logs a deprecation warning for the deprecated `@computed` getter decorator syntax.
+ * This function is called internally when the library detects usage of `@computed`
+ * on a getter method instead of the recommended method syntax.
+ *
+ * The warning is only shown once per application session to avoid spam in the console.
+ * It provides clear guidance on how to migrate from the deprecated getter syntax
+ * to the current method-based approach.
+ *
+ * @example
+ * ```ts
+ * // Deprecated pattern that triggers this warning:
+ * class MyClass {
+ *   @computed
+ *   get value() {
+ *     return this.someAtom.get()
+ *   }
+ * }
+ *
+ * // Recommended pattern:
+ * class MyClass {
+ *   @computed
+ *   getValue() {
+ *     return this.someAtom.get()
+ *   }
+ * }
+ * ```
+ *
+ * @internal
+ */
 export function logComputedGetterWarning() {
 	if (didWarnComputedGetter) return
 	didWarnComputedGetter = true