LiveState

LiveState is a state-synchronization framework where the server acts as the single source of truth.

The Workflow:

1. Events: Clients dispatch events to the server.
2. Handling: The server handles these events in Elixir and updates the application state.
3. Updates: The server pushes state updates back to the client. Subsequent updates are diffed using the jsondiff library and sent in jsonpatch format to minimize payload size.

Comparison with LiveView: While LiveView manages both server logic and view presentation in Elixir, LiveState separates them. LiveState event handlers are written in Elixir, but the client is responsible for rendering the state and dispatching events. This makes LiveState better suited for applications where the client-side rendering logic needs to be decoupled from the server or used in non-Phoenix environments.

LiveState encodes state using the c:LiveState.Encoder protocol before serializing it to JSON.

• Default Behavior: The default implementation handles standard Elixir terms, converts structs to maps, and strips the __meta__ field from Ecto.Schema structs.
• Customization: You can implement the c:LiveState.Encoder protocol for custom encoding logic.
• Message Building: For full control over the encoding and serialization process (including how diffs are generated), you can provide a custom module via the message_builder option in use LiveState.Channel.

To use LiveState, add it as a dependency in your mix.exs file. Since LiveState is often used for embedded apps that need to be accessed from different origins, you should also add CORSPlug to your Phoenix endpoint to handle Cross-Origin Resource Sharing.

1. Add :live_state and :cors_plug to your deps.
2. Add plug CORSPlug to your Endpoint module.

# mix.exs
def deps do
  [
    {:live_state, "~> 0.7"},
    {:cors_plug, ">= 0.0.0"}
  ]
end

# lib/pipe_spot_web/endpoint.ex
defmodule PipeSpotWeb.Endpoint do
  use Phoenix.Endpoint, otp_app: :pipe_spot

  plug CORSPlug
  # ...
end

To use LiveState, you must integrate it with Phoenix Channels following these three steps:

1. Configure the Endpoint: Register a socket in your Endpoint module.
2. Create the Socket Module: Define a module using Phoenix.Socket to handle connections and topics.
3. Implement the Channel: Use the LiveState.Channel behaviour in your channel module, passing your web module via the web_module option.

# 1. Endpoint setup
defmodule MyAppWeb.Endpoint do
  socket "/socket", MyAppWeb.Channels.LiveStateSocket
end

# 2. Socket module
defmodule MyAppWeb.Socket do
  use Phoenix.Socket

  channel "topic", MyAppWeb.Channel
  @impl true
  def connect(_params, socket), do: {:ok, socket}

  @impl true
  def id(_), do: "random_id"
end

# 3. Channel implementation
defmodule MyAppWeb.Channel do
  use LiveState.Channel, web_module: MyAppWeb
end

Add live_state to your mix.exs dependencies. It is highly recommended to also include cors_plug to manage cross-origin requests, ensuring clients can connect to your channels securely.

def deps do
  [
    {:live_state, "~> 0.8.1"},
    {:cors_plug, "~> 3.0"}
  ]
end

The LiveState.MessageBuilder relies on the LiveState.Encoder protocol to transform Elixir terms into a JSON-compatible format before calculating diffs.

If you find that JSONDiff is producing incorrect patches for your custom data structures (e.g., complex nested maps or specialized structs), implement the LiveState.Encoder protocol for those types. This gives you control over the 'pre-diff' representation that the builder uses to calculate the state:patch messages.

To use a LiveState custom element on any website, include the compiled JavaScript bundle and use the custom element tag with a url attribute pointing to your LiveState WebSocket endpoint.

Example usage:

<html
<head>
  <!-- Path to your custom elements bundle -->
  <script type="module" src="http://localhost:4000/assets/custom_elements.js"></script>
</head>
<body>
  <!-- The url must point to your Phoenix LiveState socket endpoint -->
  <contact-form url="ws://localhost:4000/live_state"></contact-form>
</body>
</html>

To manage state and handle events in a LiveState channel, implement the init/3 and handle_event/4 callbacks from the LiveState.Channel behaviour.

• init(_channel, _params, _socket): Returns {:ok, initial_state_map}.
• handle_event(event_name, payload, state): Processes incoming events and returns {:noreply, new_state}.

@impl true
def init(_channel, _params, _socket) do
  {:ok, %{complete: false}}
end

@impl true
def handle_event("create-contact", contact_attrs, state) do
  case Contacts.create_contact(contact_attrs) do
    {:ok, _contact} -> {:noreply, Map.put(state, :complete, true)}
    {:error, _} -> {:noreply, state}
  end
end

To consume LiveState on the frontend, use one of the following related projects:

• phx-live-state (npm): The core frontend library for sending/receiving events and subscribing to state changes. Supports building Custom Elements.
• live-templates (npm): A lightweight way to connect frontend templates to a LiveState channel without writing custom JavaScript or Custom Elements.
• use-live-state (React): A dedicated React hook for integrating LiveState into React applications.