Atom • tldraw Docs

Table of contents

lastChangedEpoch
name
Properties
Methods

Extends Signal<Value, Diff>.

An Atom is a signal that can be updated directly by calling Atom.set or Atom.update.

Atoms are created using the atom function.

interface Atom<Value, Diff = unknown> extends Signal<Value, Diff> {}

Example

const name = atom('name', 'John')

print(name.get()) // 'John'

Properties

lastChangedEpoch

from Signal

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

name

from Signal

A human-readable identifier for this signal, used primarily for debugging and performance profiling.

The name is displayed in debug output from whyAmIRunning and other diagnostic tools. It does not need to be globally unique within your application.

name: string

Methods

get

from Signal

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.

getDiffSince

from Signal

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.

Parameters

Name	Description
`epoch`	`number` The epoch timestamp to get diffs since

Returns

Diff[] | RESET_VALUE

An array of diff objects representing changes since the epoch, or the unique symbol RESET_VALUE if insufficient history is available

set

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.

Parameters

Name	Description
`value`	`Value` The new value to set.
`diff`	`Diff` The diff to use for the update. If not provided, the diff will be computed using AtomOptions.computeDiff.

Returns

Value

update

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.

Parameters

Name	Description
`updater`	`(value: Value) => Value` A function that takes the current value and returns the new value.

Returns

Value