@starbeam/debug

This document is outdaated but reflects some early thinking about the description architecture. It's still useful as a way to drive future design work, and should be updated as the design evolves.

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.

• Reactive Scalars
• Formulas
• Collections

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
• Formulas

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