# r3bl_redux
## Why R3BL?
R3BL
TUI
library
&
suite
of
apps
focused
on
developer
productivity
We are working on building command line apps in Rust which have rich text user interfaces (TUI).
We want to lean into the terminal as a place of productivity, and build all kinds of awesome
apps for it.
1. 🔮 Instead of just building one app, we are building a library to enable any kind of rich TUI
development w/ a twist: taking concepts that work really well for the frontend mobile and web
development world and re-imagining them for TUI & Rust.
- Taking inspiration from things like [React](https://react.dev/),
[SolidJS](https://www.solidjs.com/),
[Elm](https://guide.elm-lang.org/architecture/),
[iced-rs](https://docs.rs/iced/latest/iced/), [Jetpack
Compose](https://developer.android.com/compose),
[JSX](https://ui.dev/imperative-vs-declarative-programming),
[CSS](https://www.w3.org/TR/CSS/#css), but making everything async (so they can
be run in parallel & concurrent via [Tokio](https://crates.io/crates/tokio)).
- Even the thread running the main event loop doesn't block since it is async.
- Using proc macros to create DSLs to implement something inspired by
[CSS](https://www.w3.org/TR/CSS/#css) &
[JSX](https://ui.dev/imperative-vs-declarative-programming).
2. 🌎 We are building apps to enhance developer productivity & workflows.
- The idea here is not to rebuild `tmux` in Rust (separate processes mux'd onto a
single terminal window). Rather it is to build a set of integrated "apps" (or
"tasks") that run in the same process that renders to one terminal window.
- Inside of this terminal window, we can implement things like "app" switching,
routing, tiling layout, stacking layout, etc. so that we can manage a lot of TUI
apps (which are tightly integrated) that are running in the same process, in the
same window. So you can imagine that all these "app"s have shared application
state. Each "app" may also have its own local application state.
- Here are some examples of the types of "app"s we plan to build (for which this
infrastructure acts as the open source engine):
1. Multi user text editors w/ syntax highlighting.
2. Integrations w/ github issues.
3. Integrations w/ calendar, email, contacts APIs.
All the crates in the `r3bl-open-core`
[repo](https://github.com/r3bl-org/r3bl-open-core/) provide lots of useful
functionality to help you build TUI (text user interface) apps, along w/ general
niceties & ergonomics that all Rustaceans 🦀 can enjoy 🎉.
## Table of contents
- [Introduction](#introduction)
- [Changelog](#changelog)
- [Learn how these crates are built, provide feedback](#learn-how-these-crates-are-built-provide-feedback)
- [Middlewares](#middlewares)
- [Subscribers](#subscribers)
- [Reducers](#reducers)
- [Summary](#summary)
- [Small example step by step](#small-example-step-by-step)
- [Complete example in one go](#complete-example-in-one-go)
## Introduction
`Store` is thread safe and asynchronous (using Tokio). You have to implement `async` traits in
order to use it, by defining your own reducer, subscriber, and middleware trait objects. You
also have to supply the Tokio runtime, this library will not create its own runtime. However,
for best results, it is best to use the multithreaded Tokio runtime.
Once you setup your Redux store w/ your reducer, subscriber, and middleware, you can use it by
calling `spawn_dispatch_action!( store, action )`. This kicks off a parallel Tokio task that
will run the middleware functions, reducer functions, and finally the subscriber functions. So
this will not block the thread of whatever code you call this from. The
`spawn_dispatch_action!()` macro itself is not `async`. So you can call it from non `async`
code, however you still have to provide a Tokio executor / runtime, without which you will get a
panic when `spawn_dispatch_action!()` is called.
> Here are some interesting links for you to look into further:
>
> 1. [In depth guide on this Redux
> implementation](https://developerlife.com/2022/03/12/rust-redux/).
> 2. [Code example of an address book using
> Redux](https://github.com/r3bl-org/address-book-with-redux-tui).
> 3. [Code example of TUI apps using
> Redux](https://github.com/r3bl-org/r3bl-open-core/tree/main/tui/examples/demo).
## Changelog
Please check out the
[changelog](https://github.com/r3bl-org/r3bl-open-core/blob/main/CHANGELOG.md#r3bl_redux)
to see how the library has evolved over time.
## Learn how these crates are built, provide feedback
To learn how we built this crate, please take a look at the following resources.
- If you like consuming video content, here's our [YT channel](https://www.youtube.com/@developerlifecom). Please consider [subscribing](https://www.youtube.com/channel/CHANNEL_ID?sub_confirmation=1).
- If you like consuming written content, here's our developer [site](https://developerlife.com/). Please consider subscribing to our [newsletter](https://developerlife.com/subscribe.html).
- If you have questions, please join our [discord server](https://discord.gg/8M2ePAevaM).
## Middlewares
Your middleware (`async` trait implementations) will be run concurrently or in parallel via
Tokio tasks. You get to choose which `async` trait to implement to do one or the other. And
regardless of which kind you implement the `Action` that is optionally returned will be
dispatched to the Redux store at the end of execution of all the middlewares (for that
particular `spawn_dispatch_action!()` call).
1. `AsyncMiddlewareSpawns` - Your middleware has to use `tokio::spawn` to run
`async` blocks in a [separate
thread](https://docs.rs/tokio/latest/tokio/task/index.html#spawning) and return a
`JoinHandle` that contains an `Option`. You can use [tokio::task::spawn] to
spawn parallel blocks of code in your `async` functions. These are added to the
store via a call to `add_middleware_spawns(...)`.
2. `AsyncMiddleware` - They are will all be run together concurrently using
[`futures::join_all()`](https://docs.rs/futures/latest/futures/future/fn.join_all.html).
These are added to the store via a call to `add_middleware(...)`.
## Subscribers
The subscribers will be run asynchronously via Tokio tasks. They are all run together
concurrently but not in parallel, using
[`futures::join_all()`](https://docs.rs/futures/latest/futures/future/fn.join_all.html).
## Reducers
The reducer functions are also are `async` functions that are run in the tokio runtime. They're
also run one after another in the order in which they're added.
âš¡ **Any functions or blocks that you write which uses the Redux library will have to be marked
`async` as well. And you will have to spawn the Tokio runtime by using the `#[tokio::main]`
macro. If you use the default runtime then Tokio will use multiple threads and its task stealing
implementation to give you parallel and concurrent behavior. You can also use the single
threaded runtime; its really up to you.**
1. To create middleware you have to implement the `AsyncMiddleware` trait or
`AsyncMiddlewareSpawns` trait. Please read the [`AsyncMiddleware`
docs](https://docs.rs/r3bl_rs_utils/latest/r3bl_rs_utils/redux/async_middleware/trait.AsyncMiddleware.html)
for examples of both. The `run()` method is passed two arguments: the `State` and the
`Action`.
1. For `AsyncMiddlewareSpawns` in your `run()` implementation you can use
[tokio::task::spawn] surround your code. And this will return a
`JoinHandle>`.
2. For `AsyncMiddleware` in your `run()` implementation you just have to return an
`Option>`.
2. To create reducers you have to implement the `AsyncReducer` trait.
- These should be [pure
functions](https://redux.js.org/understanding/thinking-in-redux/three-principles#changes-are-made-with-pure-functions)
and simply return a new `State` object.
- The `run()` method will be passed two arguments: a ref to `Action` and ref to `State`.
3. To create subscribers you have to implement the `AsyncSubscriber` trait.
- The `run()` method will be passed a `State` object as an argument.
- It returns nothing `()`.
## Summary
Here's the gist of how to make & use one of these:
1. Create a struct. Make it derive `Default`. Or you can add your own properties / fields to
this struct, and construct it yourself, or even provide a constructor function.
- A default constructor function `new()` is provided for you by the trait.
- Just follow how that works for when you need to make your own constructor function for a
struct w/ your own properties.
2. Implement the `AsyncMiddleware`, `AsyncMiddlewareSpawns`, `AsyncReducer`, or
`AsyncSubscriber` trait on your struct.
3. Register this struct w/ the store using one of the `add_middleware()`,
`add_middleware_spawns()`, `add_reducer()`, or `add_subscriber()` methods. You can register
as many of these as you like.
- If you have a struct w/ no properties, you can just use the default `::new()` method to
create an instance and pass that to the `add_???()` methods.
- If you have a struct w/ custom properties, you can either implement your own constructor
function or use the following as an argument to the `add_???()` methods:
`Box::new($YOUR_STRUCT))`.
## Small example step by step
💡 There are lots of examples in the
[tests](https://github.com/r3bl-org/r3bl-rs-utils/blob/main/tests/test_redux.rs) for this
library and in this [CLI application](https://github.com/r3bl-org/address-book-with-redux-tui/)
built using it.
Here's an example of how to use it. Let's start w/ the import statements.
```rust
/// Imports.
use async_trait::async_trait;
use r3bl_rs_utils::redux::{
AsyncMiddlewareSpawns, AsyncMiddleware, AsyncReducer,
AsyncSubscriber, Store, StoreStateMachine,
};
use std::sync::{Arc, Mutex};
use tokio::sync::RwLock;
```
1. Make sure to have the `tokio` and `async-trait` crates installed as well as `r3bl_rs_utils`
in your `Cargo.toml` file.
2. Here's an example
[`Cargo.toml`](https://github.com/nazmulidris/rust_scratch/blob/main/address-book-with-redux/Cargo.toml).
Let's say we have the following action enum, and state struct.
```rust
/// Action enum.
#[derive(Debug, PartialEq, Eq, Clone)]
pub enum Action {
Add(i32, i32),
AddPop(i32),
Clear,
MiddlewareCreateClearAction,
Noop,
}
impl Default for Action {
fn default() -> Self {
Action::Noop
}
}
/// State.
#[derive(Clone, Default, PartialEq, Debug)]
pub struct State {
pub stack: Vec,
}
```
Here's an example of the reducer function.
```rust
/// Reducer function (pure).
#[derive(Default)]
struct MyReducer;
#[async_trait]
impl AsyncReducer for MyReducer {
async fn run(
&self,
action: &Action,
state: &mut State,
) {
match action {
Action::Add(a, b) => {
let sum = a + b;
state.stack = vec![sum];
}
Action::AddPop(a) => {
let sum = a + state.stack[0];
state.stack = vec![sum];
}
Action::Clear => State {
state.stack.clear();
},
_ => {}
}
}
}
```
Here's an example of an async subscriber function (which are run in parallel after an action is
dispatched). The following example uses a lambda that captures a shared object. This is a pretty
common pattern that you might encounter when creating subscribers that share state in your
enclosing block or scope.
```rust
/// This shared object is used to collect results from the subscriber
/// function & test it later.
let shared_object = Arc::new(Mutex::new(Vec::::new()));
#[derive(Default)]
struct MySubscriber {
pub shared_object_ref: Arc>>,
}
#[async_trait]
impl AsyncSubscriber for MySubscriber {
async fn run(
&self,
state: State,
) {
let mut stack = self
.shared_object_ref
.lock()
.unwrap();
if !state.stack.is_empty() {
stack.push(state.stack[0]);
}
}
}
let my_subscriber = MySubscriber {
shared_object_ref: shared_object_ref.clone(),
};
```
Here are two types of async middleware functions. One that returns an action (which will get
dispatched once this middleware returns), and another that doesn't return anything (like a
logger middleware that just dumps the current action to the console). Note that both these
functions share the `shared_object` reference from above.
```rust
/// This shared object is used to collect results from the subscriber
/// function & test it later.
#[derive(Default)]
struct MwExampleNoSpawn {
pub shared_object_ref: Arc>>,
}
#[async_trait]
impl AsyncMiddleware for MwExampleNoSpawn {
async fn run(
&self,
action: Action,
_store_ref: Arc>>,
) {
let mut stack = self
.shared_object_ref
.lock()
.unwrap();
match action {
Action::MwExampleNoSpawn_Add(_, _) => stack.push(-1),
Action::MwExampleNoSpawn_AddPop(_) => stack.push(-2),
Action::MwExampleNoSpawn_Clear => stack.push(-3),
_ => {}
}
None
}
}
let mw_example_no_spawn = MwExampleNoSpawn {
shared_object_ref: shared_object_ref.clone(),
};
/// This shared object is used to collect results from the subscriber
/// function & test it later.
#[derive(Default)]
struct MwExampleSpawns {
pub shared_object_ref: Arc>>,
}
#[async_trait]
impl AsyncMiddlewareSpawns for MwExampleSpawns {
async fn run(
&self,
action: Action,
store_ref: Arc>>,
) -> JoinHandle> {
tokio::task::spawn(async move
{
let mut stack = self
.shared_object_ref
.lock()
.unwrap();
match action {
Action::MwExampleSpawns_ModifySharedObject_ResetState => {
shared_vec.push(-4);
return Some(Action::Reset);
}
_ => {}
}
None
}
);
}
}
let mw_example_spawns = MwExampleSpawns {
shared_object_ref: shared_object_ref.clone(),
};
```
Here's how you can setup a store with the above reducer, middleware, and subscriber functions.
```rust
// Setup store.
let mut store = Store::::default();
store
.add_reducer(MyReducer::new()) // Note the use of `::new()` here.
.await
.add_subscriber(Box::new( // We aren't using `::new()` here
my_subscriber, // because the struct has properties.
))
.await
.add_middleware_spawns(Box::new( // We aren't using `::new()` here
mw_example_spawns, // because the struct has properties.
))
.await
.add_middleware(Box::new( // We aren't using `::new()` here
mw_example_no_spawn, // because the struct has properties.
))
.await;
```
Finally here's an example of how to dispatch an action in a test. You can dispatch actions in
parallel using `spawn_dispatch_action!()` which is "fire and forget" meaning that the caller
won't block or wait for the `spawn_dispatch_action!()` to return.
```rust
// Test reducer and subscriber by dispatching `Add`, `AddPop`, `Clear` actions in parallel.
spawn_dispatch_action!( store, Action::Add(1, 2) );
assert_eq!(shared_object.lock().unwrap().pop(), Some(3));
spawn_dispatch_action!( store, Action::AddPop(1) );
assert_eq!(shared_object.lock().unwrap().pop(), Some(4));
spawn_dispatch_action!( store, Action::Clear );
assert_eq!(store.get_state().stack.len(), 0);
```
## Complete example in one go
If you like to learn by example, below is a full example of using this Redux crate.
```rust
use std::sync::Arc;
use async_trait::async_trait;
use r3bl_rs_utils::{redux::{AsyncReducer, AsyncSubscriber, Store},
SharedStore};
use tokio::sync::RwLock;
#[allow(non_camel_case_types)]
#[derive(Debug, PartialEq, Eq, Clone)]
pub enum Action {
// Reducer actions.
Add(i32, i32),
AddPop(i32),
Reset,
Clear,
// Middleware actions for MwExampleNoSpawn.
MwExampleNoSpawn_Foo(i32, i32),
MwExampleNoSpawn_Bar(i32),
MwExampleNoSpawn_Baz,
// Middleware actions for MwExampleSpawns.
MwExampleSpawns_ModifySharedObject_ResetState,
// For Default impl.
Noop,
}
impl Default for Action {
fn default() -> Self { Action::Noop }
}
#[derive(Clone, Default, PartialEq, Eq, Debug)]
pub struct State {
pub stack: Vec,
}
#[tokio::test]
async fn test_redux_store_works_for_main_use_cases() {
// This shared object is used to collect results from the subscriber &
// middleware & reducer functions & test it later.
let shared_vec = Arc::new(RwLock::new(Vec::::new()));
// Create the store.
let mut _store = Store::::default();
let shared_store: SharedStore = Arc::new(RwLock::new(_store));
run_reducer_and_subscriber(&shared_vec, &shared_store.clone()).await;
}
async fn reset_shared_object(shared_vec: &Arc>>) {
shared_vec.write().await.clear();
}
async fn reset_store(shared_store: &SharedStore) {
shared_store.write().await.clear_reducers().await;
shared_store.write().await.clear_subscribers().await;
shared_store.write().await.clear_middlewares().await;
}
async fn run_reducer_and_subscriber(
shared_vec: &Arc>>, shared_store: &SharedStore,
) {
// Setup store w/ only reducer & subscriber (no middlewares).
let my_subscriber = MySubscriber {
shared_vec: shared_vec.clone(),
};
reset_shared_object(shared_vec).await;
reset_store(shared_store).await;
shared_store
.write()
.await
.add_reducer(MyReducer::new())
.await
.add_subscriber(Box::new(my_subscriber))
.await;
shared_store
.write()
.await
.dispatch_action(Action::Add(1, 2))
.await;
assert_eq!(shared_vec.write().await.pop(), Some(3));
shared_store
.write()
.await
.dispatch_action(Action::AddPop(1))
.await;
assert_eq!(shared_vec.write().await.pop(), Some(4));
// Clean up the store's state.
shared_store
.write()
.await
.dispatch_action(Action::Clear)
.await;
let state = shared_store.read().await.get_state();
assert_eq!(state.stack.len(), 0);
}
struct MySubscriber {
pub shared_vec: Arc>>,
}
#[async_trait]
impl AsyncSubscriber for MySubscriber {
async fn run(&self, state: State) {
let mut stack = self.shared_vec.write().await;
if !state.stack.is_empty() {
stack.push(state.stack[0]);
}
}
}
#[derive(Default)]
struct MyReducer;
#[async_trait]
impl AsyncReducer for MyReducer {
async fn run(&self, action: &Action, state: &State) -> State {
match action {
Action::Add(a, b) => {
let sum = a + b;
State { stack: vec![sum] }
}
Action::AddPop(a) => {
let sum = a + state.stack[0];
State { stack: vec![sum] }
}
Action::Clear => State { stack: vec![] },
Action::Reset => State { stack: vec![-100] },
_ => state.clone(),
}
}
}
```
License: Apache-2.0