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

package/src/lib/Atom.ts

@@ -66,6 +66,8 @@ export interface Atom<Value, Diff = unknown> extends Signal<Value, Diff> {
 }
 
 /**
+ * Internal implementation of the Atom interface. This class should not be used directly - use the {@link atom} function instead.
+ *
  * @internal
  */
 class __Atom__<Value, Diff = unknown> implements Atom<Value, Diff> {
@@ -85,25 +87,76 @@ class __Atom__<Value, Diff = unknown> implements Atom<Value, Diff> {
 		this.computeDiff = options.computeDiff
 	}
 
+	/**
+	 * Custom equality function for comparing values, or null to use default equality.
+	 * @internal
+	 */
 	readonly isEqual: null | ((a: any, b: any) => boolean)
 
+	/**
+	 * Optional function to compute diffs between old and new values.
+	 * @internal
+	 */
 	computeDiff?: ComputeDiff<Value, Diff>
 
+	/**
+	 * The global epoch when this atom was last changed.
+	 * @internal
+	 */
 	lastChangedEpoch = getGlobalEpoch()
 
+	/**
+	 * Set of child signals that depend on this atom.
+	 * @internal
+	 */
 	children = new ArraySet<Child>()
 
+	/**
+	 * Optional history buffer for tracking changes over time.
+	 * @internal
+	 */
 	historyBuffer?: HistoryBuffer<Diff>
 
+	/**
+	 * Gets the current value without capturing it as a dependency in the current reactive context.
+	 * This is unsafe because it breaks the reactivity chain - use with caution.
+	 *
+	 * @param _ignoreErrors - Unused parameter for API compatibility
+	 * @returns The current value
+	 * @internal
+	 */
 	__unsafe__getWithoutCapture(_ignoreErrors?: boolean): Value {
 		return this.current
 	}
 
+	/**
+	 * Gets the current value of this atom. When called within a computed signal or reaction,
+	 * this atom will be automatically captured as a dependency.
+	 *
+	 * @returns The current value
+	 * @example
+	 * ```ts
+	 * const count = atom('count', 5)
+	 * console.log(count.get()) // 5
+	 * ```
+	 */
 	get() {
 		maybeCaptureParent(this)
 		return this.current
 	}
 
+	/**
+	 * Sets the value of this atom to the given value. If the value is the same as the current value, this is a no-op.
+	 *
+	 * @param value - The new value to set
+	 * @param diff - The diff to use for the update. If not provided, the diff will be computed using {@link AtomOptions.computeDiff}
+	 * @returns The new value
+	 * @example
+	 * ```ts
+	 * const count = atom('count', 0)
+	 * count.set(5) // count.get() is now 5
+	 * ```
+	 */
 	set(value: Value, diff?: Diff): Value {
 		// If the value has not changed, do nothing.
 		if (this.isEqual?.(this.current, value) ?? equals(this.current, value)) {
@@ -136,10 +189,29 @@ class __Atom__<Value, Diff = unknown> implements Atom<Value, Diff> {
 		return value
 	}
 
+	/**
+	 * Updates the value of this atom using the given updater function. If the returned value is the same as the current value, this is a no-op.
+	 *
+	 * @param updater - A function that takes the current value and returns the new value
+	 * @returns The new value
+	 * @example
+	 * ```ts
+	 * const count = atom('count', 5)
+	 * count.update(n => n + 1) // count.get() is now 6
+	 * ```
+	 */
 	update(updater: (value: Value) => Value): Value {
 		return this.set(updater(this.current))
 	}
 
+	/**
+	 * Gets all the diffs that have occurred since the given epoch. When called within a computed
+	 * signal or reaction, this atom will be automatically captured as a dependency.
+	 *
+	 * @param epoch - The epoch to get changes since
+	 * @returns An array of diffs, or RESET_VALUE if history is insufficient
+	 * @internal
+	 */
 	getDiffSince(epoch: number): RESET_VALUE | Diff[] {
 		maybeCaptureParent(this)
 
@@ -152,7 +224,16 @@ class __Atom__<Value, Diff = unknown> implements Atom<Value, Diff> {
 	}
 }
 
+/**
+ * Singleton reference to the Atom constructor. Used internally to create atom instances.
+ * @internal
+ */
 export const _Atom = singleton('Atom', () => __Atom__)
+
+/**
+ * Type alias for instances of the internal Atom class.
+ * @internal
+ */
 export type _Atom = InstanceType<typeof _Atom>
 
 /**
@@ -192,6 +273,17 @@ export function atom<Value, Diff = unknown>(
 
 /**
  * Returns true if the given value is an {@link Atom}.
+ *
+ * @param value - The value to check
+ * @returns True if the value is an Atom, false otherwise
+ * @example
+ * ```ts
+ * const myAtom = atom('test', 42)
+ * const notAtom = 'hello'
+ *
+ * console.log(isAtom(myAtom)) // true
+ * console.log(isAtom(notAtom)) // false
+ * ```
  * @public
  */
 export function isAtom(value: unknown): value is Atom<unknown> {

package/src/lib/Computed.ts

@@ -10,13 +10,28 @@ import { Child, ComputeDiff, RESET_VALUE, Signal } from './types'
 import { logComputedGetterWarning } from './warnings'
 
 /**
+ * A special symbol used to indicate that a computed signal has not been initialized yet.
+ * This is passed as the `previousValue` parameter to a computed signal function on its first run.
+ *
+ * @example
+ * ```ts
+ * const count = atom('count', 0)
+ * const double = computed('double', (prevValue) => {
+ *   if (isUninitialized(prevValue)) {
+ *     console.log('First computation!')
+ *   }
+ *   return count.get() * 2
+ * })
+ * ```
+ *
  * @public
  */
 export const UNINITIALIZED = Symbol.for('com.tldraw.state/UNINITIALIZED')
 /**
  * The type of the first value passed to a computed signal function as the 'prevValue' parameter.
+ * This type represents the uninitialized state of a computed signal before its first calculation.
  *
- * @see {@link isUninitialized}.
+ * @see {@link isUninitialized}
  * @public
  */
 export type UNINITIALIZED = typeof UNINITIALIZED
@@ -44,7 +59,25 @@ export function isUninitialized(value: any): value is UNINITIALIZED {
 	return value === UNINITIALIZED
 }
 
-/** @public */
+/**
+ * A singleton class used to wrap computed signal values along with their diffs.
+ * This class is used internally by the {@link withDiff} function to provide both
+ * the computed value and its diff to the signal system.
+ *
+ * @example
+ * ```ts
+ * const count = atom('count', 0)
+ * const double = computed('double', (prevValue) => {
+ *   const nextValue = count.get() * 2
+ *   if (isUninitialized(prevValue)) {
+ *     return nextValue
+ *   }
+ *   return withDiff(nextValue, nextValue - prevValue)
+ * })
+ * ```
+ *
+ * @public
+ */
 export const WithDiff = singleton(
 	'WithDiff',
 	() =>
@@ -56,9 +89,20 @@ export const WithDiff = singleton(
 		}
 )
 
-/** @public */
+/**
+ * Interface representing a value wrapped with its corresponding diff.
+ * Used in incremental computation to provide both the new value and the diff from the previous value.
+ *
+ * @public
+ */
 export interface WithDiff<Value, Diff> {
+	/**
+	 * The computed value.
+	 */
 	value: Value
+	/**
+	 * The diff between the previous and current value.
+	 */
 	diff: Diff
 }
 
@@ -89,7 +133,17 @@ export function withDiff<Value, Diff>(value: Value, diff: Diff): WithDiff<Value,
 }
 
 /**
- * Options for creating computed signals. Used when calling `computed`.
+ * Options for configuring computed signals. Used when calling `computed` or using the `@computed` decorator.
+ *
+ * @example
+ * ```ts
+ * const greeting = computed('greeting', () => `Hello ${name.get()}!`, {
+ *   historyLength: 10,
+ *   isEqual: (a, b) => a === b,
+ *   computeDiff: (oldVal, newVal) => ({ type: 'change', from: oldVal, to: newVal })
+ * })
+ * ```
+ *
  * @public
  */
 export interface ComputedOptions<Value, Diff> {
@@ -119,13 +173,27 @@ export interface ComputedOptions<Value, Diff> {
 }
 
 /**
- * A computed signal created via `computed`.
+ * A computed signal created via the `computed` function or `@computed` decorator.
+ * Computed signals derive their values from other signals and automatically update when their dependencies change.
+ * They use lazy evaluation, only recalculating when accessed and dependencies have changed.
+ *
+ * @example
+ * ```ts
+ * const firstName = atom('firstName', 'John')
+ * const lastName = atom('lastName', 'Doe')
+ * const fullName = computed('fullName', () => `${firstName.get()} ${lastName.get()}`)
+ *
+ * console.log(fullName.get()) // "John Doe"
+ * firstName.set('Jane')
+ * console.log(fullName.get()) // "Jane Doe"
+ * ```
  *
  * @public
  */
 export interface Computed<Value, Diff = unknown> extends Signal<Value, Diff> {
 	/**
-	 * Whether this computed child is involved in an actively-running effect graph.
+	 * Whether this computed signal is involved in an actively-running effect graph.
+	 * Returns true if there are any reactions or other computed signals depending on this one.
 	 * @public
 	 */
 	readonly isActivelyListening: boolean
@@ -286,7 +354,19 @@ class __UNSAFE__Computed<Value, Diff = unknown> implements Computed<Value, Diff>
 	}
 }
 
+/**
+ * Singleton reference to the computed signal implementation class.
+ * Used internally by the library to create computed signal instances.
+ *
+ * @internal
+ */
 export const _Computed = singleton('Computed', () => __UNSAFE__Computed)
+
+/**
+ * Type alias for the computed signal implementation class.
+ *
+ * @internal
+ */
 export type _Computed = InstanceType<typeof __UNSAFE__Computed>
 
 function computedMethodLegacyDecorator(
@@ -437,7 +517,9 @@ export function getComputedInstance<Obj extends object, Prop extends keyof Obj>(
 }
 
 /**
- * Creates a computed signal.
+ * Creates a computed signal that derives its value from other signals.
+ * Computed signals automatically update when their dependencies change and use lazy evaluation
+ * for optimal performance.
  *
  * @example
  * ```ts
@@ -475,10 +557,10 @@ export function getComputedInstance<Obj extends object, Prop extends keyof Obj>(
  * }
  * ```
  *
- * @param name - The name of the signal.
- * @param compute - The function that computes the value of the signal.
- * @param options - Options for the signal.
- *
+ * @param name - The name of the signal for debugging purposes
+ * @param compute - The function that computes the value of the signal. Receives the previous value and last computed epoch
+ * @param options - Optional configuration for the computed signal
+ * @returns A new computed signal
  * @public
  */
 export function computed<Value, Diff = unknown>(
@@ -490,7 +572,23 @@ export function computed<Value, Diff = unknown>(
 	options?: ComputedOptions<Value, Diff>
 ): Computed<Value, Diff>
 /**
- * `@computed` decorator (TC39 decorators).
+ * TC39 decorator for creating computed methods in classes.
+ *
+ * @example
+ * ```ts
+ * class MyClass {
+ *   value = atom('value', 10)
+ *
+ *   @computed
+ *   doubled() {
+ *     return this.value.get() * 2
+ *   }
+ * }
+ * ```
+ *
+ * @param compute - The method to be decorated
+ * @param context - The decorator context provided by TypeScript
+ * @returns The decorated method
  * @public
  */
 export function computed<This extends object, Value>(
@@ -498,16 +596,48 @@ export function computed<This extends object, Value>(
 	context: ClassMethodDecoratorContext<This, () => Value>
 ): () => Value
 /**
- * `@computed` decorator (legacy typescript decorator syntax).
+ * Legacy TypeScript decorator for creating computed methods in classes.
  *
- * @public */
+ * @example
+ * ```ts
+ * class MyClass {
+ *   value = atom('value', 10)
+ *
+ *   @computed
+ *   doubled() {
+ *     return this.value.get() * 2
+ *   }
+ * }
+ * ```
+ *
+ * @param target - The class prototype
+ * @param key - The property key
+ * @param descriptor - The property descriptor
+ * @returns The modified property descriptor
+ * @public
+ */
 export function computed(
 	target: any,
 	key: string,
 	descriptor: PropertyDescriptor
 ): PropertyDescriptor
 /**
- * `@computed` decorator with options.
+ * Decorator factory for creating computed methods with options.
+ *
+ * @example
+ * ```ts
+ * class MyClass {
+ *   items = atom('items', [1, 2, 3])
+ *
+ *   @computed({ historyLength: 10 })
+ *   sum() {
+ *     return this.items.get().reduce((a, b) => a + b, 0)
+ *   }
+ * }
+ * ```
+ *
+ * @param options - Configuration options for the computed signal
+ * @returns A decorator function that can be applied to methods
  * @public
  */
 export function computed<Value, Diff = unknown>(
@@ -518,7 +648,17 @@ export function computed<Value, Diff = unknown>(
 		context: ClassMethodDecoratorContext<This, () => Value>
 	) => () => Value)
 
-/** @public */
+/**
+ * Implementation function that handles all computed signal creation and decoration scenarios.
+ * This function is overloaded to support multiple usage patterns:
+ * - Creating computed signals directly
+ * - Using as a TC39 decorator
+ * - Using as a legacy decorator
+ * - Using as a decorator factory with options
+ *
+ * @returns Either a computed signal instance or a decorator function depending on usage
+ * @public
+ */
 export function computed() {
 	if (arguments.length === 1) {
 		const options = arguments[0]
@@ -532,11 +672,21 @@ export function computed() {
 
 /**
  * Returns true if the given value is a computed signal.
+ * This is a type guard function that can be used to check if a value is a computed signal instance.
+ *
+ * @example
+ * ```ts
+ * const count = atom('count', 0)
+ * const double = computed('double', () => count.get() * 2)
+ *
+ * console.log(isComputed(count))  // false
+ * console.log(isComputed(double)) // true
+ * ```
  *
- * @param value
- * @returns {value is Computed<any>}
+ * @param value - The value to check
+ * @returns True if the value is a computed signal, false otherwise
  * @public
  */
 export function isComputed(value: any): value is Computed<any> {
-	return value && value instanceof _Computed
+	return !!(value && value instanceof _Computed)
 }

package/src/lib/HistoryBuffer.ts

@@ -1,28 +1,71 @@
 import { RESET_VALUE } from './types'
 
+/**
+ * A tuple representing a range of epochs and the associated diff.
+ * Used internally by HistoryBuffer to store change information.
+ *
+ * @internal
+ */
 type RangeTuple<Diff> = [fromEpoch: number, toEpoch: number, diff: Diff]
 
 /**
- * A structure that stores diffs between values of an atom.
+ * A circular buffer that stores diffs between sequential values of an atom or computed signal.
+ * This enables efficient change tracking and history retrieval for features like undo/redo.
+ *
+ * The buffer uses a wrap-around strategy to maintain a fixed-size history of the most recent
+ * changes, automatically overwriting older entries when the capacity is exceeded.
+ *
+ * @example
+ * ```ts
+ * const buffer = new HistoryBuffer<string>(5)
+ * buffer.pushEntry(0, 1, 'first change')
+ * buffer.pushEntry(1, 2, 'second change')
+ * const changes = buffer.getChangesSince(0) // ['first change', 'second change']
+ * ```
  *
  * @internal
  */
 export class HistoryBuffer<Diff> {
+	/**
+	 * Current write position in the circular buffer.
+	 * @internal
+	 */
 	private index = 0
 
-	// use a wrap around buffer to store the last N values
+	/**
+	 * Circular buffer storing range tuples. Uses undefined to represent empty slots.
+	 * @internal
+	 */
 	buffer: Array<RangeTuple<Diff> | undefined>
 
+	/**
+	 * Creates a new HistoryBuffer with the specified capacity.
+	 *
+	 * capacity - Maximum number of diffs to store in the buffer
+	 * @example
+	 * ```ts
+	 * const buffer = new HistoryBuffer<number>(10) // Store up to 10 diffs
+	 * ```
+	 */
 	constructor(private readonly capacity: number) {
 		this.buffer = new Array(capacity)
 	}
 
 	/**
-	 * Add a diff to the history buffer.
+	 * Adds a diff entry to the history buffer, representing a change between two epochs.
+	 *
+	 * If the diff is undefined, the operation is ignored. If the diff is RESET_VALUE,
+	 * the entire buffer is cleared to indicate that historical tracking should restart.
 	 *
-	 * @param lastComputedEpoch - The epoch when the diff was computed.
-	 * @param currentEpoch - The current epoch.
-	 * @param diff - The diff to add, or else a reset value.
+	 * @param lastComputedEpoch - The epoch when the previous value was computed
+	 * @param currentEpoch - The epoch when the current value was computed
+	 * @param diff - The diff representing the change, or RESET_VALUE to clear history
+	 * @example
+	 * ```ts
+	 * const buffer = new HistoryBuffer<string>(5)
+	 * buffer.pushEntry(0, 1, 'added text')
+	 * buffer.pushEntry(1, 2, RESET_VALUE) // Clears the buffer
+	 * ```
 	 */
 	pushEntry(lastComputedEpoch: number, currentEpoch: number, diff: Diff | RESET_VALUE) {
 		if (diff === undefined) {
@@ -42,7 +85,16 @@ export class HistoryBuffer<Diff> {
 	}
 
 	/**
-	 * Clear the history buffer.
+	 * Clears all entries from the history buffer and resets the write position.
+	 * This is called when a RESET_VALUE diff is encountered.
+	 *
+	 * @example
+	 * ```ts
+	 * const buffer = new HistoryBuffer<string>(5)
+	 * buffer.pushEntry(0, 1, 'change')
+	 * buffer.clear()
+	 * console.log(buffer.getChangesSince(0)) // RESET_VALUE
+	 * ```
 	 */
 	clear() {
 		this.index = 0
@@ -50,10 +102,24 @@ export class HistoryBuffer<Diff> {
 	}
 
 	/**
-	 * Get the diffs since the given epoch.
+	 * Retrieves all diffs that occurred since the specified epoch.
+	 *
+	 * The method searches backwards through the circular buffer to find changes
+	 * that occurred after the given epoch. If insufficient history is available
+	 * or the requested epoch is too old, returns RESET_VALUE indicating that
+	 * a complete state rebuild is required.
 	 *
-	 * @param sinceEpoch - The epoch to get diffs since.
-	 * @returns An array of diffs or a flag to reset the history buffer.
+	 * @param sinceEpoch - The epoch from which to retrieve changes
+	 * @returns Array of diffs since the epoch, or RESET_VALUE if history is insufficient
+	 * @example
+	 * ```ts
+	 * const buffer = new HistoryBuffer<string>(5)
+	 * buffer.pushEntry(0, 1, 'first')
+	 * buffer.pushEntry(1, 2, 'second')
+	 * const changes = buffer.getChangesSince(0) // ['first', 'second']
+	 * const recentChanges = buffer.getChangesSince(1) // ['second']
+	 * const tooOld = buffer.getChangesSince(-100) // RESET_VALUE
+	 * ```
 	 */
 	getChangesSince(sinceEpoch: number): RESET_VALUE | Diff[] {
 		const { index, capacity, buffer } = this