Struct State 

pub struct State { /* private fields */ }

A concurrent, type-safe state container that agents read from and write to.

By default, set() writes directly to the inner store. When delta tracking is enabled via with_delta_tracking(), writes go to a separate delta map that can be committed or rolled back.

Implementations

impl State

pub fn new() -> Self

Create a new empty state container.

pub fn with_delta_tracking(&self) -> State

Create a new State with delta tracking enabled. Writes go to the delta map; reads check delta first, then inner.

pub fn get<T: DeserializeOwned>(&self, key: &str) -> Option<T>

Get a value by key, attempting to deserialize to the requested type. When delta tracking is enabled, checks delta first, then inner.

pub fn with<F, R>(&self, key: &str, f: F) -> Option<R>

where F: FnOnce(&Value) -> R,

Borrow a value by key without cloning, applying f to the reference.

This is the zero-copy alternative to get_raw(). The closure receives a &Value directly from the DashMap ref-guard, avoiding the Value::clone() + serde_json::from_value() overhead of get().

Lookup order: delta (if tracking) → inner → derived fallback.

pub fn get_raw(&self, key: &str) -> Option<Value>

Get a raw JSON value by key. When delta tracking is enabled, checks delta first, then inner. If the key is not found and doesn’t contain a prefix, also checks derived:{key} as a transparent fallback for computed variables.

pub fn get_key<T: DeserializeOwned>(&self, key: &StateKey<T>) -> Option<T>

Get a typed value using a StateKey<T>.

pub fn set_key<T: Serialize>(&self, key: &StateKey<T>, value: T)

Set a typed value using a StateKey<T>.

pub fn with_key<T, F, R>(&self, key: &StateKey<T>, f: F) -> Option<R>

where F: FnOnce(&Value) -> R,

Zero-copy borrow using a StateKey<T>.

pub fn set(&self, key: impl Into<String>, value: impl Serialize)

Set a value by key. When delta tracking is enabled, writes to delta instead of inner.

pub fn set_committed(&self, key: impl Into<String>, value: impl Serialize)

Set a value directly in the committed store, bypassing delta tracking.

pub fn modify<T, F>(&self, key: &str, default: T, f: F) -> T

where T: Serialize + DeserializeOwned, F: FnOnce(T) -> T,

Atomically read-modify-write a value.

If the key doesn’t exist, default is used as the initial value. The function f receives the current value and returns the new value. Returns the new value after modification.

pub fn contains(&self, key: &str) -> bool

Check if a key exists (in delta or inner).

pub fn remove(&self, key: &str) -> Option<Value>

Remove a key.

pub fn keys(&self) -> Vec<String>

Get all keys (from both inner and delta when tracking).

pub fn pick(&self, keys: &[&str]) -> State

Create a new State containing only the specified keys.

pub fn merge(&self, other: &State)

Merge another state into this one (other’s values overwrite on conflict).

pub fn rename(&self, from: &str, to: &str)

Rename a key.

pub fn is_tracking_delta(&self) -> bool

Whether delta tracking is enabled.

pub fn has_delta(&self) -> bool

Whether there are uncommitted delta changes.

pub fn delta(&self) -> HashMap<String, Value>

Get a snapshot of the current delta.

pub fn commit(&self)

Commit delta changes into the inner store, then clear the delta.

pub fn rollback(&self)

Discard all uncommitted delta changes.

pub fn app(&self) -> PrefixedState<'_>

Access state with the app: prefix scope.

pub fn user(&self) -> PrefixedState<'_>

Access state with the user: prefix scope.

pub fn temp(&self) -> PrefixedState<'_>

Access state with the temp: prefix scope.

pub fn session(&self) -> PrefixedState<'_>

Access state with the session: prefix scope (auto-tracked signals).

pub fn turn(&self) -> PrefixedState<'_>

Access state with the turn: prefix scope (reset each turn).

pub fn bg(&self) -> PrefixedState<'_>

Access state with the bg: prefix scope (background tasks).

pub fn derived(&self) -> ReadOnlyPrefixedState<'_>

Access read-only state with the derived: prefix scope (computed vars only).

pub fn snapshot_values(&self, keys: &[&str]) -> HashMap<String, Value>

Snapshot the values of specific keys. Returns HashMap of key -> current value. Used by watchers to capture state before mutations.

pub fn diff_values( &self, prev: &HashMap<String, Value>, keys: &[&str], ) -> Vec<(String, Value, Value)>

Diff current state against a previous snapshot. Returns Vec of (key, old_value, new_value) for keys that changed.

pub fn to_hashmap(&self) -> HashMap<String, Value>

Export all state as a HashMap (for persistence/serialization).

pub fn from_hashmap(&self, map: HashMap<String, Value>)

Restore state from a HashMap (for persistence/deserialization).

pub fn clear_prefix(&self, prefix: &str)

Remove all keys with the given prefix.

Trait Implementations

impl Clone for State

fn clone(&self) -> State

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for State

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for State

fn default() -> Self

Returns the “default value” for a type.