Struct StateManager

Source

pub struct StateManager { /* private fields */ }

Expand description

StateManager manages immutable state with patch history.

§Design

State is immutable - all changes go through commits
Full history is maintained for replay
Supports batch commits and preview operations

§API Philosophy

commit/commit_batch: Mutating operations that modify state and record history
preview_patch: Pure operation that computes result without modifying state
replay_to: Pure operation that reconstructs historical state

§Example

use tirea_state::{StateManager, StateContext};
use serde_json::json;

let manager = StateManager::new(json!({}));

// Get snapshot and create state context
let snapshot = manager.snapshot().await;
let ctx = StateContext::new(&snapshot);

// ... modify state through ctx ...

// Commit patch (modifies state and records history)
manager.commit(ctx.take_tracked_patch("tool:example")).await?;

// Replay to a specific point
let old_state = manager.replay_to(5).await?;

Implementations§

Source §

impl StateManager

Source

pub fn new(initial: Value) -> Self

Create a new StateManager with initial state.

Source

pub async fn register_lattice<T>(&self, path: impl Into<Path>)
where T: Lattice + Serialize + DeserializeOwned + Send + Sync + 'static,

Register a lattice type at the given path for automatic merge during apply.

Source

pub async fn snapshot(&self) -> Value

Get a snapshot of the current state.

Source

pub async fn commit( &self, patch: TrackedPatch, ) -> Result<ApplyResult, StateError>

Commit a single patch, modifying state and recording to history.

This is a mutating operation that:

Applies the patch to current state
Updates the internal state
Records the patch in history for replay

Source

pub async fn commit_batch( &self, patches: Vec<TrackedPatch>, ) -> Result<ApplyResult, StateError>

Commit multiple patches in batch.

Patches are applied in order atomically. If any patch fails, no changes are persisted to state or history.

Source

pub async fn preview_patch(&self, patch: &Patch) -> Result<Value, StateError>

Preview applying a patch without modifying state (pure operation).

This computes what the state would look like after applying the patch, but does not modify the actual state or record to history.

Useful for validation, dry-runs, or showing users what changes would occur.

Source

pub async fn apply( &self, patch: TrackedPatch, ) -> Result<ApplyResult, StateError>

👎Deprecated since 0.2.0: Use commit instead

Deprecated: Use commit instead.

Source

pub async fn apply_batch( &self, patches: Vec<TrackedPatch>, ) -> Result<ApplyResult, StateError>

👎Deprecated since 0.2.0: Use commit_batch instead

Deprecated: Use commit_batch instead.

Source

pub async fn replay_to(&self, index: usize) -> Result<Value, StateError>

Replay state from the beginning up to (and including) the specified index.

Returns the state as it was after applying patches [0..=index] to the initial state.

Source

pub async fn history(&self) -> Vec<TrackedPatch>

Get the full patch history.

Source

pub async fn history_len(&self) -> usize

Get the number of patches in history.

Source

pub async fn clear_history(&self)

Clear history (keeps current state).

Use with caution - this removes the ability to replay.

Source

pub async fn prune_history(&self, keep_last: usize) -> Result<usize, StateError>

Prune history, keeping only the last keep_last patches.

This is useful for long-running systems to prevent unbounded memory growth. The initial state is updated to the state before the remaining patches, so replay_to will continue to work correctly with the remaining patches.