Expand description
app-world provides a framework agnostic approach to managing frontend application state.
The Data Model
An AppWorld
is a type that you define that holds your application state as well as other
resources that you’ve deemed useful to have around during your application’s runtime.
Here’s an example of what an AppWorld for a basic e-commerce app frontend might look like:
struct MyAppWorld {
state: MyAppState,
resources: MyAppResources
}
struct MyAppState {
user: User,
products: HashMap<Uuid, Product>
}
struct MyAppResources {
file_store: Box<dyn MyFileStoreTrait>,
api_client: ApiClient
}
The MyAppWorld
struct would be defined in your crate, but it wouldn’t be used directly when
you were passing data around to your views.
Instead, you wrap it in an app_world::AppWorldWrapper<W>
type MyAppWorldWrapper = app_world::AppWorldWrapper<MyAppWorld>;
AppWorldWrapper<W: AppWorld>
The AppWorldWrapper
prevents direct mutable access to your application state, so you cannot
mutate fields wherever you please.
Instead, the AppWorld
trait defines a [AppWorld.msg()
] method that can be used to update
your application state.
Whenever you update state using a .msg()
call, the [RenderFn
] that you provide is called
and your application gets re-rendered.
You can pass your AppWorldWrapper<W>
to different threads by calling
[AppWorldWrapper.clone()
]. Under the hood an Arc
is used to share your data across
threads.
Example Usage
TODO
When to Use app-world
app-world shines in applications that do not have extreme real time rendering requirements, such as almost all browser, desktop and mobile applications. In games and real-time simulations, you’re better off using something like an entity component system to manage your application state.
This is because app-world is designed such that your application state can only be written to from one thread at a time. This is totally fine for almost all browser, desktop and mobile applications, but could be an issue for games and simulations.
If you’re writing a game or simulation you’re likely better off reaching for an entity-component-system library. Otherwise, you should be in good hands here. which could be an issue for a high-performing game or simulation.
Structs
Holds application state and resources and will trigger a re-render after .msg() calls. See the crate level documentation for more details.
Allows us to optionally store sent Msg
’s instead of passing them on to state.
Traits
Defines how messages that indicate that something has happened get sent to the World.