rust-elm 0.8.0

Elm Architecture for Rust, evolving toward The Composable Architecture (UDF).

Install

[dependencies]
rust-elm = { path = "../rust-elm" }
rust-elm = "0.8.0"
rust-key-paths = "3.4.0"
key-paths-derive = "3.3.0"
tokio = { version = "1.38", features = ["rt-multi-thread", "macros"] }

Feature flags

Build without Tokio (pure descriptions only):

cargo build -p rust-elm --no-default-features

Quick start

use rust_elm::{Cmd, Program, Runtime, RuntimeConfig, Sub, Environment};

#[derive(Default)]
struct State { count: i32 }

fn init() -> (State, Cmd<i32>) {
    (State::default(), Cmd::none())
}

fn update(state: &mut State, msg: i32) -> Cmd<i32> {
    state.count += msg;
    Cmd::none()
}

fn subscriptions(_: &State) -> Sub<i32> {
    Sub::none()
}

fn main() -> Result<(), rust_elm::RuntimeError> {
    let program = Program::new(init, update, subscriptions);
    let runtime = Runtime::from_program(program, Environment::new(), RuntimeConfig::new(64))?;
    let store = runtime.store();
    store.dispatch(1);
    runtime.shutdown();
    Ok(())
}

Snapshot reads: blocking vs background

There is one live runtime per app (Runtime, RwRuntime, SwapRuntime, or TeaRuntime).
Store / TeaStore / … are cloneable handles into that same runtime — not a separate “store runtime”.
Your main thread (or any worker) holds a handle, calls dispatch, and reads snapshots; the reducer thread runs Program::update / ReducerProgram::reduce.

Which thread does what?

main / UI thread                reducer thread (Program lives here)
      |                                |
      |  dispatch(action)              |
      +------------------------------->|  reduce(&mut state, action)
      |                                |  publish snapshot / notify
      |  state() / load() / next()     |
      |<-------------------------------+  (Tea: push Arc<S> on channel)
      |                                |
Tokio effect thread                    |
      |  effect finishes               |
      +--- dispatch(result action) ---->|

dispatch / send never wait for a snapshot — they only enqueue on the action bus (may block if the bus is full).

How you read state depends on the store backend:

Rule of thumb: the reducer thread is the only thread that runs update and publishes new model values. Your thread (main or a reader) consumes snapshots via lock, atomic load, or channel. Subscriptions are push/async relative to reduce; one-off state() / load() are synchronous on the caller.

See architecture.md, tea_ecommerce.md, swap_ecommerce.md, and store.md.

Release notes

0.8.0

• counter, rw_counter, swap_counter examples — CounterState { a, b, c } with keypath-scoped bucket reads; side-by-side Tea / Rw / Swap clone comparison.
• book/counter.md — documents snapshot clone behavior per store backend.
• Snapshot threading docs — README and architecture notes on which thread clones vs borrows state.

0.7.0

• arc-swap feature — optional SwapRuntime, SwapStore, SnapshotStore, snapshot bindings.
• swap_ecommerce example — lock-free snapshot reads on the shared shop domain.
• TeaRuntime / TeaStore — channel-pushed model (true TEA: no shared mutable state).
• tea_ecommerce example — same shop with channel-delivered snapshots.
• RuntimeError / TeaStoreError — fallible runtime bootstrap and tea snapshot reads (no unwrap / expect in library code).
• No unsafe — BusSender drop counter uses Arc<AtomicU64> instead of raw pointers.

0.6.0

• RwRuntime / RwStore / ReadStore — read-heavy store API on RwLock.
• SwapRuntime / SwapStore (arc-swap feature) — lock-free snapshot reads via ArcSwap.
• StoreHub — shared dispatch hub for mutex, Rw, and swap backends.

0.5.0

• safe_reducer module — safe_reduce_update, safe_reduce_rollback, SafeReduceError (replaces reduce_panic / catch_reduce_panic / ReducePanic).
• StateBinding / subscribe_changes — zero-copy store reads and field-level change signals; see binding.md.
• Example renamed: safe_reducer (was catch_reduce).

0.3.0

• RuntimeConfig — bus_capacity, worker_threads, thread_name for Runtime::from_program.
• RefKpTrait — scope/store/optics use core traits directly; StateLens / StateKeypath removed.
• StoreTask::finish_with_timeout — configurable wait for store work.
• pain example — ISO 20022-style validation with fail-fast Validator.

0.2.0

• WebSocket subscriptions, runtime feature flags, ecommerce example.

Modules

Examples (one per feature area)

Quality tooling

# Clippy (crate only)
cargo clippy -p rust-elm --all-targets --no-deps -- -D warnings

# Miri (identified, shared, scope — no runtime)
./scripts/miri-rust-elm.sh

# Scope / ForEach benchmarks
cargo bench -p rust-elm --bench scope_dispatch

Key paths prelude

use rust_elm::keypath::{Kp, KpTrait, RefKpTrait, Readable, Writable};
use key_paths_derive::Kp;

See ROADMAP.md, book/architecture.md, book/safe_reducer.md, book/ecommerce.md, book/rw_ecommerce.md, book/swap_ecommerce.md, book/tea_ecommerce.md, book/counter.md.