LiveStash

https://hexdocs.pm/live_stash/1.0.0/
Admin
LiveStash is an Elixir library that provides a public API for stashing and recovering Phoenix...
Tokens:2,330
Snippets:29
Trust Score:9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Implement LiveStash in LiveView

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Full implementation example within a LiveView module.

```elixir
defmodule MyAppWeb.CounterLive do
  use MyAppWeb, :live_view
  use LiveStash, adapter: LiveStash.Adapters.BrowserMemory, security_mode: :sign, stored_keys: [:count]
end
```

--------------------------------

### Configure LiveStash adapter

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Example of using the LiveStash macro with a specific adapter.

```elixir
use LiveStash, adapter: LiveStash.Adapters.ETS
```

--------------------------------

### __using__(opts)

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Injects LiveStash support into a Phoenix.LiveView. This macro is the recommended way to initialize stash handling during the LiveView mount lifecycle.

```APIDOC
## __using__(opts)

### Description
Injects LiveStash support into a `Phoenix.LiveView`. This macro expands to `on_mount({LiveStash, opts})` to initialize stash handling.

### Options
- **adapter** (module) - Required - The persistence backend to use (e.g., `LiveStash.Adapters.ETS`).
- **security_mode** (atom) - Optional - Security configuration for the stash.
- **stored_keys** (list) - Optional - List of keys to be persisted.

### Example
```elixir
defmodule MyAppWeb.CounterLive do
  use MyAppWeb, :live_view
  use LiveStash, adapter: LiveStash.Adapters.BrowserMemory, security_mode: :sign, stored_keys: [:count]
end
```
```

--------------------------------

### Initialize stash support

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Type specification for the init_stash function.

```elixir
@spec init_stash(
  socket :: Phoenix.LiveView.Socket.t(),
  session :: Keyword.t(),
  opts :: Keyword.t()
) ::
  Phoenix.LiveView.Socket.t()
```

--------------------------------

### Initialize LiveStash in a LiveView

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Add LiveStash to a LiveView module by specifying the keys to be persisted.

```elixir
defmodule MyAppWeb.CounterLive do
  use MyAppWeb, :live_view
  use LiveStash, stored_keys: [:count]
end
```

--------------------------------

### Inject LiveStash macro expansion

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Shows the expansion of the __using__ macro.

```elixir
on_mount({LiveStash, opts})
```

--------------------------------

### Configure LiveStash adapter

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Override the default adapter per LiveView or enable multiple adapters in the application configuration.

```elixir
use LiveStash, adapter: LiveStash.Adapters.ETS
```

```elixir
config :live_stash,
  adapters: [LiveStash.Adapters.BrowserMemory, LiveStash.Adapters.ETS]
```

--------------------------------

### Recovering state in mount

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Use recover_state in mount/3 to restore previously stashed data. Recovery does not automatically clear the state.

```elixir
@spec recover_state(socket :: Phoenix.LiveView.Socket.t()) ::
  {recovery_status(), Phoenix.LiveView.Socket.t()}
```

```elixir
def mount(_params, _session, socket) {
  socket
  |> LiveStash.recover_state()
  |> case do
    {:recovered, recovered_socket} ->
      recovered_socket

    {_, socket} ->
      start_new_game(socket)
  end
  |> then(&{:ok, &1})
}
```

--------------------------------

### Recover stashed state in mount

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Attempt to recover previously stashed state during the mount/3 lifecycle callback.

```elixir
def mount(_params, _session, socket) do
  socket
  |> LiveStash.recover_state()
  |> case do
    {:recovered, recovered_socket} ->
      # socket with previously stashed assigns is recovered
      recovered_socket

    {_, socket} ->
      # could not recover assigns, proceed with standard setup using returned socket
      # ...
  end
  |> then(&{:ok, &1})
end
```

--------------------------------

### recover_state(socket)

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Recovers previously stashed state from the socket. This is typically invoked during the mount/3 lifecycle callback.

```APIDOC
## recover_state(socket)

### Description
Recovers previously stashed state and returns a tuple containing the recovery status and the updated socket.

### Signature
`recover_state(socket :: Phoenix.LiveView.Socket.t()) :: {recovery_status(), Phoenix.LiveView.Socket.t()}`

### Usage
```elixir
def mount(_params, _session, socket) do
  socket
  |> LiveStash.recover_state()
  |> case do
    {:recovered, recovered_socket} ->
      recovered_socket
    {_, socket} ->
      start_new_game(socket)
  end
  |> then(&{:ok, &1})
end
```
```

--------------------------------

### stash(socket)

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Stashes the assigns defined at the module level into the socket state.

```APIDOC
## stash(socket)

### Description
Stashes assigns from `socket.assigns` that were declared at the module level using the LiveStash configuration.

### Signature
`stash(socket :: Phoenix.LiveView.Socket.t()) :: Phoenix.LiveView.Socket.t()`

### Usage
```elixir
def handle_event("increment", _, socket) do
  socket
  |> assign(:count, socket.assigns.count + 1)
  |> LiveStash.stash()
  |> then(&{:noreply, &1})
end
```
```

--------------------------------

### Stashing socket assigns

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Persists specific assigns defined at the module level. Requires the use of the LiveStash macro with stored_keys.

```elixir
@spec stash(socket :: Phoenix.LiveView.Socket.t()) :: Phoenix.LiveView.Socket.t()
```

```elixir
use LiveStash, stored_keys: [:count, :username] # assigns are declared at the module level

def handle_event("increment", _, socket) {
  socket
  |> assign(:count, socket.assigns.count + 1)
  |> LiveStash.stash()
  |> then(&{:noreply, &1})
}
```

--------------------------------

### LiveStash.stash/1

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Stashes assigns from the provided socket based on the keys declared at the module level.

```APIDOC
## LiveStash.stash(socket)

### Description
Stashes assigns from `socket.assigns` declared at the module level.

### Parameters
- **socket** (Phoenix.LiveView.Socket) - Required - The current LiveView socket.
```

--------------------------------

### Stash assigns after events

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Use LiveStash.stash/1 within a handle_event callback to persist the current state.

```elixir
def handle_event("increment", _, socket) do
  socket
  |> assign(:count, socket.assigns.count + 1)
  |> LiveStash.stash()
  |> then(&{:noreply, &1})
end
```

--------------------------------

### Define recovery_status type

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Defines the possible states for recovery operations.

```elixir
@type recovery_status() :: :recovered | :not_found | :new | :error
```

--------------------------------

### reset_stash(socket)

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Clears the stashed state associated with the current LiveView socket.

```APIDOC
## reset_stash(socket)

### Description
Clears stashed state for the current LiveView socket. This is useful when explicitly removing stored state, such as during a game restart.

### Signature
`reset_stash(socket :: Phoenix.LiveView.Socket.t()) :: Phoenix.LiveView.Socket.t()`

### Usage
```elixir
def handle_event("restart_game", _params, socket) do
  socket
  |> LiveStash.reset_stash()
  |> start_new_game()
  |> then(&{:noreply, &1})
end
```
```

--------------------------------

### LiveStash.recover_state/1

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Recovers previously stashed state and returns a tuple containing the recovery status and the updated socket.

```APIDOC
## LiveStash.recover_state(socket)

### Description
Recovers previously stashed state and returns `{status, socket}`.

### Parameters
- **socket** (Phoenix.LiveView.Socket) - Required - The current LiveView socket.

### Response
- **status** (recovery_status) - The result of the recovery operation: :new, :recovered, :not_found, or :error.
- **socket** (Phoenix.LiveView.Socket) - The updated socket.
```

--------------------------------

### LiveStash.reset_stash/1

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Clears the stashed state associated with the current LiveView socket.

```APIDOC
## LiveStash.reset_stash(socket)

### Description
Clears stashed state for the current LiveView socket.

### Parameters
- **socket** (Phoenix.LiveView.Socket) - Required - The current LiveView socket.
```

--------------------------------

### Resetting stashed state

Source: https://hexdocs.pm/live_stash/1.0.0/LiveStash.html

Clears the stashed state for the current socket. Useful when resetting or restarting a process.

```elixir
@spec reset_stash(socket :: Phoenix.LiveView.Socket.t()) ::
  Phoenix.LiveView.Socket.t()
```

```elixir
def handle_event("restart_game", _params, socket) {
  socket
  |> LiveStash.reset_stash()
  |> start_new_game()
  |> then(&{:noreply, &1})
}
```
Tokens:
Raw