This library was initially meant as a Proof of Concept and until today, I haven't used it in a production system (simply because I haven't had a use-case for it).
I'm currently only updating its dependencies, but would like to develop it further. However, I don't have the information about what you, the user, needs or misses from the library. That's why I ask you kindly to open an issue for feature requests or other development ideas. I'm open to develop this library further, but am dependent on your input on how to do so.
Thank you in advance!
LiveEx is a State Management library for Phoenix LiveView.
LiveEx is based on the Flux pattern and its implementation is inspired by the Vuex library.
The Flux pattern tries to solve the problem of middle to large single-page applications (SPAs) that the oversight of which state changes are applied when and from where can be lost easily. Additionally, the information flow within a reasonably sized SPA becomes exponentially more complex the more the SPA grows in terms of components.
The Flux pattern proposes the solution a Store for the state of the SPA that can only be changed through a Dispatcher,
which can be seen as a funnel through which every state change has to pass before it is applied. This sequentializing of
state changes helps to keep an overview of when and how the state was changed. The information flows become much clearer
since they are represented by the sequence and order of state changes.
The diagram below shows the flow of the Flux pattern. A state change is initiated by dispatching an Action, which has a type and an optional payload.
The Action then commits a Mutation, which actually mutates/changes the state. The new state is then saved in the Store again. The Store notifies
the views that a state updates is available.
I completed a medium-sized project using LiveView recently in which I used 2 nested LiveViews. I ran into the typical problem that I lost the oversight of how and when the state shared by the 2 LiveViews changed and whether the views transitioned from one state to another without state corruption (e.g. some variable wasn't updated properly). Therefore, I created this project to help you (and me) to use LiveView for larger than example projects.
Add live_ex to your list of dependencies in mix.exs:
def deps do
[
{:live_ex, "~> 0.2.0"}
]
endHave a look at the Example Implementation for a fully documented implementation of a LiveEx Store.
In order to use the LiveEx Store, create a dedicated module for it, which adheres to the following structure:
defmodule MyAppWeb.Store do
use LiveEx
@initial_store %{
a: 1,
b: "test",
c: true,
d: [nil, nil, nil]
}
def init(socket) do
init(@initial_store, socket)
end
# Actions
def handle_info(%{type: "my_action", payload: payload} = action, socket) do
# This is the Action handler.
# In here you would e.g. access your state here, dispatch other actions, transform the payload,
# or do anything you like as long as it doesn't change the state, which is done in Mutations.
# E.g. make sure that the payload is an integer
payload =
cond do
is_integer(payload) -> payload
is_binary(payload) -> String.to_integer(payload)
true -> raise ArgumentError, message: "payload of my_action must be integer or string-encoded integer"
end
commit("my_action", payload, socket)
end
# Mutations
def my_action(payload, socket) do
# This is the Mutation handler.
# This is the only place where you should change your state.
new_state = socket.assigns.a + payload
assign(socket, :a, new_state)
end
endInitialize the Store in the mount/2 function of your outermost (i.e. root) LiveView, which encapsulates the nested (i.e. child) LiveViews. Since the LiveEx store currently runs in the same process as your root LiveView, we need delegate any Action callbacks (i.e. handle_info) to the Store module. Add the defdelegate line below any handle_info calls you want to make in your LiveView.
alias MyAppWeb.Store
...
def mount(_session, socket) do
{:ok, Store.init(socket)}
end
...
defdelegate handle_info(msg, socket), to: StorePass all Store variables to nested LiveViews and initialize the Store within their mount/2 function as well.
root.html.leex
<%= Phoenix.LiveView.live_render(@socket, MyAppWeb.ChildLive, session: %{"store_pid" => @store_pid}) %>child_live.ex
def mount(_params, %{"store_pid" => store_pid} = _session, socket) do
socket =
socket
|> assign(:store_pid, store_pid)
|> Store.init()
{:ok, socket}
endIf you want to dispatch an action from any LiveView, simply call the dispatch/3 function with an action type and optional payload. For example:
child_live.ex
def handle_event("increment" = event, _value, %{assigns: %{store_pid: store_pid}} = socket) do
Store.dispatch(store_pid, event, socket)
{:noreply, socket}
end
****
def handle_event("add" = event, value, %{assigns: %{store_pid: store_pid}} = socket) do
Store.dispatch(store_pid, event, value, socket)
{:noreply, socket}
endThe current version adds the Store functionality to the root LiveView process. An alternative would be to start the Store in an independent GenServer process to separate the Store functionality from the root LiveView functionality. I added an initial (unfinished) implementation in the feature/integrate-genserver branch. Unfortunately, moving the Store to its own process means adding a lot of boilerplate code that handles the communication between the root LiveView, from where one has to replace the "old" socket with the "updated" socket.
If you ever run into performance issues caused by having both Store and root functionality run in the same process, consider this approach.
Currently, the dispatch/3 function sends a message to its own process to avoid that a Store update blocks the LiveView at times when many state changes occur. One could argue that it would be better to remove the send/2 call and handle everything synchronously. If you have an opinion on this, please don't hesitate to open an issue.
- Checkout the project and run tests with
mix test. - Update the test implementation in
lib/test/test_impl.exwhenever you make changes tolib/live_ex.ex