This module provides functions for instantiating and manipulating topic state.

The state of a topic is composed of a value, observed by subscribed clients, and also hidden internal state, which can be used to share state between calls. The value must only be manipulated by the helper functions (which track the individual updates). The hidden state can be modified directly.

This module also contains a macro - use-ing it sets up a topic server:

defmodule MyApp.Topics.List do
  use Topical.Topic, route: ["lists", :list_id]

  # Initialise the topic
  def init(params) do
    list_id = Keyword.fetch!(params, :list_id)

    value = %{items: %{}, order: []} # exposed 'value' of the topic
    state = %{list_id: list_id} # hidden server state
    topic = Topic.new(value, state)

    {:ok, topic}
  end

  # Optionally, handle subscribe
  def handle_subscribe(topic, _context) do
    {:ok, topic}
  end

  # Optionally, handle unsubscribe
  def handle_unsubscribe(topic, _context) do
    {:ok, topic}
  end

  # Optionally, handle capture
  def handle_capture(topic, _context) do
    {:ok, topic}
  end

  # Optionally, handle execution of an action
  def handle_execute("add_item", {text}, topic, _context) do
    id = Integer.to_string(:erlang.system_time())

    # Update the topic by putting the item in 'items', and appending the id to 'order'
    topic =
      topic
      |> Topic.set([:items, id], %{text: text, done: false})
      |> Topic.insert([:order], id)

    # Return the result (the 'id'), and the updated topic
    {:ok, id, topic}
  end

  # Optionally, handle a notification (an action without a result)
  def handle_notify("update_text", {id, text}, topic, _context) do
    topic  = Topic.set(topic, [:items, id, :text], text)
    {:ok, topic}
  end

  # Optionally, handle Erlang messages
  def handle_info({:done, id}, topic) do
    topic  = Topic.set(topic, [:items, id, :done], true)
    {:ok, topic}
  end

  # Optionally, handle the topic being terminated (e.g., once clients have disconnected)
  def terminate(_reason, topic) do
    # ...
  end
end