api/dev.s7a.strata.state/DerivedStateSource

DerivedStateSource

interface DerivedStateSource<out T> : StateSource<T> (source)

Runtime capability for a pure, single-input derived observation. The source and transformation are immutable and caller-owned; runtimes evaluate committed inputs on their owner thread. Implementations must also implement ordinary StateSource.subscribe with its complete lifetime contract.

Properties

upstream

abstract val upstream: StateSource<*>

The input whose revision identifies this source's observation; dependency graphs must be acyclic.

Functions

derive

abstract fun derive(value: Any?): T

Transforms one upstream value without reading live state or performing effects. The value has the upstream's declared type, including null when permitted. Failures propagate to the caller; a runtime must release its acquired observations on failure.

map

fun <T, R> StateSource<T>.map(transform: (T) -> R): StateSource<R>

Creates a lazy, caller-owned projection of this source, supporting nullable values and chained projections. Construction does not subscribe or evaluate transform. Keep the returned identity when consumers share a projection. The transformation must be deterministic, side-effect-free, and return normally; ordinary subscriptions may transform on any notifying thread. Ordinary subscriptions preserve every revision, including equal results. Retained UI consumers instead share the upstream subscription, transform a frame-committed input, and suppress dependent UI work when the transformed result is equal by ==. No source history or global cache is retained. Heavy work and I/O belong outside the transformation.

abstract fun subscribe(observer: (StateSnapshot<T>) -> Unit): StateSubscription<T>

Establishes one observation and returns its initial value and close handle.