Raxol.Debug.TimeTravel (Raxol v2.3.0)

Time-travel debugger for TEA applications.

Records a snapshot of the application model at every update/2 cycle. Supports stepping forward and backward through state history, inspecting diffs between any two points, and restoring the live application to a historical state.

Usage

Enable via Lifecycle options:

Raxol.start_link(MyApp, time_travel: true)
Raxol.start_link(MyApp, time_travel: [max_snapshots: 2000])

Or start standalone and attach to a running Dispatcher:

{:ok, pid} = TimeTravel.start_link(dispatcher: dispatcher_pid)

Then navigate:

TimeTravel.step_back()     # -> {:ok, %Snapshot{}}
TimeTravel.step_forward()  # -> {:ok, %Snapshot{}}
TimeTravel.current()       # -> {:ok, %Snapshot{}}
TimeTravel.jump_to(42)     # -> {:ok, %Snapshot{}}
TimeTravel.restore()       # re-render the model at the cursor position

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear(pid \\ __MODULE__)

Clears all recorded snapshots.

count(pid \\ __MODULE__)

Returns the total number of recorded snapshots.

current(pid \\ __MODULE__)

Returns the snapshot at the current cursor position.

diff(pid \\ __MODULE__, index_a, index_b)

Diffs two snapshots by index. Returns change list.

export(pid \\ __MODULE__, path)

Exports snapshots to a file (Erlang term format).

import_file(pid \\ __MODULE__, path)

Imports snapshots from a file.

jump_to(pid \\ __MODULE__, index)

Jumps the cursor to a specific snapshot index.

list_entries(pid \\ __MODULE__)

Returns a list of snapshot summaries.

pause(pid \\ __MODULE__)

Pauses snapshot recording.

record(pid \\ __MODULE__, message, model_before, model_after)

Records a snapshot. Called by the Dispatcher after each update/2.

restore(pid \\ __MODULE__)

Restores the live application model to the snapshot at the current cursor.

resume(pid \\ __MODULE__)

Resumes recording after a restore (recording pauses automatically on restore).

start_link(opts \\ [])

Starts the time-travel debugger.

step_back(pid \\ __MODULE__)

Steps the cursor back one snapshot.

step_forward(pid \\ __MODULE__)

Steps the cursor forward one snapshot.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear(pid \\ MODULE)

@spec clear(pid() | atom()) :: :ok

Clears all recorded snapshots.

count(pid \\ MODULE)

@spec count(pid() | atom()) :: non_neg_integer()

Returns the total number of recorded snapshots.

current(pid \\ MODULE)

@spec current(pid() | atom()) :: {:ok, Raxol.Debug.Snapshot.t()} | {:error, :empty}

Returns the snapshot at the current cursor position.

diff(pid \\ MODULE, index_a, index_b)

@spec diff(pid() | atom(), non_neg_integer(), non_neg_integer()) ::
  {:ok, [Raxol.Debug.Snapshot.change()]} | {:error, :not_found}

Diffs two snapshots by index. Returns change list.

export(pid \\ MODULE, path)

@spec export(pid() | atom(), Path.t()) :: :ok | {:error, term()}

Exports snapshots to a file (Erlang term format).

import_file(pid \\ MODULE, path)

@spec import_file(pid() | atom(), Path.t()) ::
  {:ok, non_neg_integer()} | {:error, term()}

Imports snapshots from a file.

jump_to(pid \\ MODULE, index)

@spec jump_to(pid() | atom(), non_neg_integer()) ::
  {:ok, Raxol.Debug.Snapshot.t()} | {:error, :not_found}

Jumps the cursor to a specific snapshot index.

list_entries(pid \\ MODULE)

@spec list_entries(pid() | atom()) :: [map()]

Returns a list of snapshot summaries.

pause(pid \\ MODULE)

@spec pause(pid() | atom()) :: :ok

Pauses snapshot recording.

record(pid \\ MODULE, message, model_before, model_after)

@spec record(pid() | atom(), term(), map(), map()) :: :ok

Records a snapshot. Called by the Dispatcher after each update/2.

restore(pid \\ MODULE)

@spec restore(pid() | atom()) :: :ok | {:error, :empty | :no_dispatcher}

Restores the live application model to the snapshot at the current cursor.

Sends {:restore_model, model} to the Dispatcher, which updates its state and triggers a re-render. Automatically pauses recording so the restore itself doesn't get recorded as a new snapshot.

resume(pid \\ MODULE)

@spec resume(pid() | atom()) :: :ok

Resumes recording after a restore (recording pauses automatically on restore).

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the time-travel debugger.

step_back(pid \\ MODULE)

@spec step_back(pid() | atom()) ::
  {:ok, Raxol.Debug.Snapshot.t()} | {:error, :at_start}

Steps the cursor back one snapshot.

step_forward(pid \\ MODULE)

@spec step_forward(pid() | atom()) ::
  {:ok, Raxol.Debug.Snapshot.t()} | {:error, :at_end}

Steps the cursor forward one snapshot.