PhoenixReplay.Migration behaviour (PhoenixReplay v0.6.2)

Copy Markdown View Source

Adapts recordings whose assigns changed shape since, such as a :dark_mode boolean that became a :theme, as database migrations adapt rows.

Replay renders today's templates with the assigns recorded then. An assign a recording lacks needs nothing: it renders as nil, and the player notes it. A migration is for an assign that is there but means something else now:

defmodule MyAppWeb.ReplayMigrations.DarkModeToTheme do
  use PhoenixReplay.Migration, version: 20261007120000

  @impl true
  def up(MyAppWeb.TaskLive.Index, %{dark_mode: dark?} = assigns),
    do: Map.put_new(assigns, :theme, if(dark?, do: "dark", else: "light"))

  def up(_view_or_component, assigns), do: assigns
end

up/2 takes the view or LiveComponent module, and the assigns it is about to render with; match the module in the function head. Versions are timestamps, as Ecto's migrations name theirs, so they sort as they were written.

Migrations are found among the modules of the view's application, with nothing to configure. Each recording keeps the newest version it was made with (see PhoenixReplay.Recording.Code), and replay applies the newer ones, in order, to its view's assigns and each LiveComponent's. A recording made before versions were kept gets them all, so write up/2 to leave assigns that already have the new shape as they are, as Map.put_new/3 does.

As with Ecto's migrations, a version says when a migration was written, not when it shipped: one merged after a newer one, with an older timestamp, is skipped for recordings made in between, whose version is already past it. Give a migration that lands late a fresh timestamp.

Summary

Types

A migration module and its version.

Callbacks

The assigns module, a view or LiveComponent, renders with today, from those recorded before this migration.

Functions

Makes the module a migration of version :version, a timestamp such as 20261007120000, which replay finds and orders by.

The migrations of the application module belongs to, oldest first. They are read once per set of the application's modules.

Applies migrations to the assigns of module, in order.

The newest migration version of module's application, or nil without any.

The migrations newer than stamp, the version a recording was made with, or all of them for a recording made before versions were kept.

Types

migration()

@type migration() :: {pos_integer(), module()}

A migration module and its version.

Callbacks

up(module, assigns)

@callback up(module :: module(), assigns :: map()) :: map()

The assigns module, a view or LiveComponent, renders with today, from those recorded before this migration.

Functions

__using__(opts)

(macro)

Makes the module a migration of version :version, a timestamp such as 20261007120000, which replay finds and orders by.

all(module)

@spec all(module()) :: [migration()]

The migrations of the application module belongs to, oldest first. They are read once per set of the application's modules.

apply_to(migrations, module, assigns)

@spec apply_to([migration()], module(), map()) :: map()

Applies migrations to the assigns of module, in order.

latest(module)

@spec latest(module()) :: pos_integer() | nil

The newest migration version of module's application, or nil without any.

pending(migrations, stamp)

@spec pending([migration()], pos_integer() | nil) :: [migration()]

The migrations newer than stamp, the version a recording was made with, or all of them for a recording made before versions were kept.