Documentation
¶
Overview ¶
Package fragments is the compiled source for docs/guide/fragments-and-dirty-tracking.md.
templ: version: v0.3.1020
Index ¶
Constants ¶
const ( FragmentReading = "dash.reading" FragmentLog = "dash.log" )
Fragment identifiers. A patch names one of these, so changing one is a client-visible change. They match ^[A-Za-z0-9_:.-]{1,64}$ and are unique within the application; New refuses a duplicate.
Variables ¶
This section is empty.
Functions ¶
func Age ¶
Age is derived at the transition, from the event's own At stamp, and rendered as data.
A render may not read a clock: it must be a pure function of state, or two renders of the same state produce different bytes and the identical-render suppression that compares them breaks.
func Fragments ¶
Fragments declares the two live regions.
Dirty is optional. Nil means "re-render on every transition", which is always correct and is the right first answer; declare one when a fragment is expensive or when an unrelated event stream would otherwise re-render it.
func ReadingRegion ¶
Types ¶
type History ¶
type History struct {
Samples []Sample
}
History is the recent readings, oldest first. It is IMMUTABLE: nothing appends in place, and a transition builds a new History and points at it.
It is behind a pointer in State because the library compares consecutive states with == to decide whether the state version moved, and a type that is not comparable is reported as changed on EVERY transition — so a no-op event bumps the version and every fragment's Dirty is asked about a change that did not happen. A slice field makes State uncomparable; one pointer field does not.
type Sample ¶
Sample is one reading. It is a value, and the History holding it is never mutated after construction.
type State ¶
type State struct {
// Latest is the newest reading. A pointer to an immutable value, so == is
// pointer identity: a new reading is a new pointer, and the same reading
// folded twice is the same pointer.
Latest *History
// ChangedAtUnixMilli is when the reading last moved.
//
// It is an int64 and not a time.Time, and that is the hazard this file
// exists to name. A time.Time read from time.Now carries a monotonic clock
// reading as well as a wall clock, and == compares both — plus the
// *Location pointer. Two time.Time values naming the same instant can
// therefore compare unequal, so a Dirty function written with == over a
// time.Time reports a change that did not happen on every transition, and
// State stops being comparable in the way the paragraph on History
// assumes. time.Time.Equal is the correct comparison and == is not; storing
// the instant as an integer removes the choice.
ChangedAtUnixMilli int64
// Paused belongs to this session and to nothing else.
Paused bool
}
State is one session's view.
Every field is comparable. That is what lets the Dirty functions below use ==, and it is what keeps the library's own state comparison working.
Source Files