The Description Architecture
The goal of the description architecture is to provide a way to describe reactive operations in a way that is both human readable and easy to use in a debug tool.
Validation Descriptions
A validation description allows debugging tools to determine whether a reactive value is still valid.
Timestamp Validation
- kind
timestamp
- timestamp
- (Timestamp) The timestamp represented by the validator. The timestamp is possibly computed.
- isValid()
- A function that returns
true
if the validator is still valid, or false
otherwise.
Digest Validation
A digest validator represents a rule for converting a value into a (string) digest. Digesting inputs can therefore be used to determine whether an output value has changed without computing it.
Note: Starbeam does not currently expose any APIs that use digest validation, but it is contemplated for the future.
- kind
digest
- digest
- (string) The digest represented by the validator. The digest is possibly computed.
- isValid(current)
- A function that returns
true
if the validator is still valid, or false
otherwise.
All Descriptions
All descriptions have:
- name
- A user-specified name, or (in dev mode) a name inferred from the stack
- stack
- (in dev) A stack frame in the user code that created the reactive value
- validator
- (lazy) a validator description
Reactive Scalars
A reactive scalar represents a single value:
Cells
A cell is the fundamental reactive scalar value.
- value
- The current value of the cell
- updated
- The timestamp at which the value was updated
Markers
A marker represents something that can change but whose value is not tracked by Starbeam. You can think of it as a cell whose value is an "updated-at" timestamp.
- updated
- The timestamp at which the value was updated
Formulas
A Formula's description also includes:
- computed
- If the formula was not computed yet,
UNINITIALIZED
. Otherwise, { value, at }
. The value
is the most recent computed value, and at
is the timestamp at which the computation occurred.
- children
- (lazy) A list of the reactive values that this formula directly depends on
- dependencies
- (lazy) A flattened list of the mutable cells that this formula depends on
- updatedAt
- (computed) The most recent timestamp in which any of the formula's dependencies have changed
Collections
A reactive collection is a logical grouping of multiple reactive values, such as a list, map or set.
Iterable Collections
- entries
- a
Marker
that indicates the last time the iteration over entries changed.
Iterable Key-Value Collections
In addition to the properties in Iterable Collections:
- keys
- a
Marker
that indicates the last time the iteration over keys changed. If a key's value was replaced, this marker is not updated. If a key is added or deleted, this marker is updated.
- values
- a
Marker
that indicates the last time the iteration over values changed. This is basically equivalent to entries
, but if a collection has a way to atomically replace a key/value with another key and the same value, the values
marker may not update.
Value Collections
- has(value)
A marker that updates whenever the response to has(value)
would change. If an entry was missing and then deleted, this marker doesn't update.
Key-Value Collections
- has(key)
A marker that updates whenever the response to has(key)
would change. If an entry was missing and then deleted, this marker doesn't update.
- get(key)
A marker that updates whenever the response to get(key)
would change. If an entry was missing and then added, or added and then deleted, this will update (unless the value, when present was undefined
).
Reactive Values
Cells
A cell's description i
- cell reads are operations that read the current value of a cell.
- cell writes are operations that write a new value to a cell.
There are two kinds of fundamental reactive operations:
- cell reads are operations that read the current value of a reactive cell.
- cell writes are operations that change the value of a reactive cell.
- iterations are operations that iterate a reactive collection.
- splices
And two kinds of composite reactive operations:
- formula reads are operations that read a value from a formula
- mutations are operations that change multiple cells at once
Cells
There are a few kinds of fundamental cells:
Data Structure Operations