Yewdux State Management

Yewdux is a state management solution designed for the Yew front-end library. It provides an ergonomic approach to global state management, allowing multiple components to access and manipulate shared state without the boilerplate typically required by Yew's built-in context manager.

Key features include:

• Simple: The core requirement is implementing the Store trait.
• Ergonomic: Boilerplate is optional.
• Predictable: Provides complete control over state changes.
• Selective: Supports selectors to ensure components only re-render when specific parts of the state change.
• Context agnostic: Dispatches can be created and executed from anywhere.
• Complete component support: Works with both functional and struct components.

Derived state creates a reactive link between a source store and a dependent store through the following lifecycle:

1. Registration: A listener is registered to watch the source state.
2. Trigger: When the source state changes, the dependency is notified.
3. Update: The on_change implementation is executed:
   • DerivedFrom: Creates a brand new instance of the derived state.
   • DerivedFromMut: Modifies the existing derived state instance in place.
4. Notification: Components using the derived state via hooks like use_store_value are notified and re-render.

You can create a private, locally managed store by instantiating a new yewdux::Context. This context is independent of the global state. To interact with this local store, create a Dispatch instance by passing a reference to the new context. Changes made to this dispatch will only affect this specific context and will not be reflected in the global context or any other local contexts.

use yew::prelude::*;
use yewdux::prelude::*;

#[derive(Clone, PartialEq, Default, Store)]
struct Counter(u32);

let cx = yewdux::Context::new();
let dispatch = Dispatch::<Counter>::new(&cx);

Listeners are component-less subscribers used to describe side-effects that should occur whenever a specific state changes. They live for the entire application lifetime.

To create a listener, implement the Listener trait for a struct. You must specify the type Store to indicate which store the listener is subscribing to, and implement the on_change method to define the side-effect. Note that on_change receives an immutable Rc<Self::Store>, which prevents borrowing issues during recursive triggers.

use std::rc::Rc;
use yewdux::prelude::*;

#[derive(Default, Clone, PartialEq, Debug, Store)]
struct State {
    count: u32,
}

struct StateLogger;

impl Listener for StateLogger {
    type Store = State;

    fn on_change(&self, _cx: &yewdux::Context, state: Rc<Self::Store>) {
        yewdux::log::info!("state changed: {:?}", state);
    }
}

The global context allows you to access and manage state from anywhere in your code on the same thread. This is the standard way to use Yewdux for application-wide state. You can access it using Dispatch::<T>::global().

Note: Global context is only supported for wasm targets. For Server-Side Rendering (SSR) support, refer to the SSR documentation.

use yewdux::prelude::*;

#[derive(Clone, PartialEq, Default, Store)]
struct Counter(u32);

// These are equivalent:
let dispatch_1 = Dispatch::<Counter>::global();
let dispatch_2 = Dispatch::<Counter>::new(&yewdux::Context::global());

dispatch_1.set(Counter(1));

To create a manageable state in Yewdux, define a struct and derive Store, Default, Clone, and PartialEq. The Store derive macro enables the struct to be used with Yewdux hooks like use_store.

#[derive(Default, Clone, PartialEq, Store)]
struct State {
    count: u32,
}

You can persist your Yewdux state in either local or session storage by using the #[store] macro on your state struct. Your struct must implement Serialize and Deserialize from serde to allow the state to be converted to and from a storage format.

use yewdux::prelude::*;
use serde::{Serialize, Deserialize};

#[derive(Default, PartialEq, Serialize, Deserialize, Store)]
#[store(storage = "local")] // can also be "session"
struct State {
    count: u32,
}

A Store represents state shared application-wide. It is initialized on first access and lives for the application lifetime. The easiest way to define a store is by using the #[derive(Store)] macro on your state struct.

Note: When using the macro, your struct must also implement Default and PartialEq.

use yewdux::prelude::*;

#[derive(Default, PartialEq, Store)]
struct State {
    count: u32,
}

To run the complete working examples provided in the repository, you must have trunk installed. Use the trunk serve command pointing to the specific example's index.html file.

trunk serve examples/[example]/index.html --open

To activate a listener, call init_listener with a factory function that returns an instance of your listener and the current yewdux::Context.

A recommended pattern is to call init_listener within the Store::new implementation of the store you wish to monitor.

Note: Successive calls to init_listener for the same type will have no effect.

impl Store for State {
    fn new(cx: &yewdux::Context) -> Self {
        init_listener(|| StateLogger, cx);
        Default::default()
    }

    fn should_notify(&self, other: &Self) -> bool {
        self != other
    }
}