Elixir Dev

Running Mix Commands

See references/mix-commands.md for full command reference.

Test

# Run all tests
mix test

# Specific file or line
mix test test/my_app/accounts_test.exs:42

# By tag
mix test --only integration

# Failed only (requires --failed flag from prior run)
mix test --failed

# With coverage
mix test --cover

Interpreting failures:

• ** (MatchError) — Pattern match failed; check return value shape.
• ** (Ecto.NoResultsError) — Repo.get! with non-existent ID; use Repo.get or seed data.
• ** (DBConnection.OwnershipError) — Missing async: true or sandbox setup.
• no function clause matching — Wrong arity or unexpected arg type.

Credo

mix credo --strict
mix credo suggest --format json
mix credo explain MyApp.Module  # Explain issues for specific module

Common Credo fixes:

• Credo.Check.Readability.ModuleDoc — Add @moduledoc.
• Credo.Check.Refactor.CyclomaticComplexity — Extract helper functions.
• Credo.Check.Design.TagTODO — Address or remove TODO comments.

Dialyzer

mix dialyzer
mix dialyzer --format short

Common Dialyzer warnings:

• The pattern can never match — Dead code or wrong type in pattern.
• Function has no local return — Crashes on all paths; check internal calls.
• The call will never return — Calling a function that always raises.
• Fix: Add @spec annotations; use @dialyzer {:nowarn_function, func: arity} as last resort.

Format

mix format
mix format --check-formatted  # CI mode — exit 1 if unformatted

Module Generation

Always include @moduledoc, @doc, and @spec on public functions.

Context Module

defmodule MyApp.Notifications do
  @moduledoc """
  Manages notification delivery and preferences.
  """
  import Ecto.Query
  alias MyApp.Repo
  alias MyApp.Notifications.Notification

  @doc "List notifications for a user, most recent first."
  @spec list_notifications(String.t(), keyword()) :: [Notification.t()]
  def list_notifications(user_id, opts \\ []) do
    limit = Keyword.get(opts, :limit, 50)

    Notification
    |> where(user_id: ^user_id)
    |> order_by(desc: :inserted_at)
    |> limit(^limit)
    |> Repo.all()
  end
end

Schema Module

defmodule MyApp.Notifications.Notification do
  @moduledoc """
  Schema for push/email/sms notifications.
  """
  use Ecto.Schema
  import Ecto.Changeset

  @type t :: %__MODULE__{}

  @primary_key {:id, :binary_id, autogenerate: true}
  @foreign_key_type :binary_id
  @timestamps_opts [type: :utc_datetime_usec]

  schema "notifications" do
    field :channel, Ecto.Enum, values: [:push, :email, :sms]
    field :title, :string
    field :body, :string
    field :delivered_at, :utc_datetime_usec
    field :user_id, :binary_id

    timestamps()
  end

  @required ~w(channel title body user_id)a

  @doc false
  def changeset(notification, attrs) do
    notification
    |> cast(attrs, @required ++ [:delivered_at])
    |> validate_required(@required)
    |> validate_length(:title, max: 255)
  end
end

OTP Patterns

See references/otp-patterns.md for GenServer, Supervisor, Agent, Task patterns.

When to Use What

| Pattern | Use When |

|---------|----------|

| GenServer | Stateful process with sync/async calls (cache, rate limiter, connection pool) |

| Agent | Simple state wrapper with no complex logic |

| Task | One-off async work, fire-and-forget or awaited |

| Task.Supervisor | Supervised fire-and-forget tasks |

| Supervisor | Managing child process lifecycles |

| Registry | Process lookup by name/key |

| DynamicSupervisor | Starting children at runtime |

GenServer Template

defmodule MyApp.RateLimiter do
  @moduledoc "Token bucket rate limiter."
  use GenServer

  # Client API
  def start_link(opts) do
    name = Keyword.get(opts, :name, __MODULE__)
    GenServer.start_link(__MODULE__, opts, name: name)
  end

  @spec check_rate(String.t()) :: :ok | {:error, :rate_limited}
  def check_rate(key), do: GenServer.call(__MODULE__, {:check, key})

  # Server callbacks
  @impl true
  def init(opts) do
    {:ok, %{limit: Keyword.get(opts, :limit, 100), window_ms: 60_000, buckets: %{}}}
  end

  @impl true
  def handle_call({:check, key}, _from, state) do
    now = System.monotonic_time(:millisecond)
    {count, state} = increment(state, key, now)
    if count <= state.limit, do: {:reply, :ok, state}, else: {:reply, {:error, :rate_limited}, state}
  end

  defp increment(state, key, now) do
    # Implementation
  end
end

Common Compilation Errors

| Error | Cause | Fix |

|-------|-------|-----|

| module X is not available | Missing dep or typo | Check mix.exs deps, verify module name |

| undefined function X/N | Not imported/aliased | Add import, alias, or full module path |

| (CompileError) redefining module | Duplicate module name | Rename one of them |

| protocol not implemented | Missing protocol impl | Add defimpl for your struct |

| cannot use ^x outside of match | Pin in wrong position | Move to pattern match context |

Ecto Query Patterns

Dynamic Filters

def list(filters) do
  Enum.reduce(filters, base_query(), fn
    {:status, val}, q -> where(q, [r], r.status == ^val)
    {:since, dt}, q -> where(q, [r], r.inserted_at >= ^dt)
    {:search, term}, q -> where(q, [r], ilike(r.name, ^"%#{term}%"))
    _, q -> q
  end)
  |> Repo.all()
end

Preloading

# Query-time preload (single query with join)
from(p in Post, join: a in assoc(p, :author), preload: [author: a])

# Separate query preload
Post |> Repo.all() |> Repo.preload(:author)

# Nested
Repo.preload(posts, [comments: :author])

Aggregates

from(o in Order,
  where: o.tenant_id == ^tenant_id,
  group_by: o.status,
  select: {o.status, count(o.id), sum(o.amount)}
)
|> Repo.all()

Phoenix LiveView Basics

Mount + Handle Events

defmodule MyAppWeb.DashboardLive do
  use MyAppWeb, :live_view

  @impl true
  def mount(_params, _session, socket) do
    {:ok, assign(socket, items: [], loading: true)}
  end

  @impl true
  def handle_event("delete", %{"id" => id}, socket) do
    MyApp.Items.delete_item!(id)
    {:noreply, assign(socket, items: MyApp.Items.list_items())}
  end

  @impl true
  def render(assigns) do
    ~H"""
    <div :for={item <- @items}>
      <span><%= item.name %></span>
      <button phx-click="delete" phx-value-id={item.id}>Delete</button>
    </div>
    """
  end
end

PubSub for Real-time

# Subscribe in mount
def mount(_, _, socket) do
  if connected?(socket), do: Phoenix.PubSub.subscribe(MyApp.PubSub, "items")
  {:ok, assign(socket, items: list_items())}
end

# Broadcast from context
def create_item(attrs) do
  with {:ok, item} <- %Item{} |> Item.changeset(attrs) |> Repo.insert() do
    Phoenix.PubSub.broadcast(MyApp.PubSub, "items", {:item_created, item})
    {:ok, item}
  end
end

# Handle in LiveView
def handle_info({:item_created, item}, socket) do
  {:noreply, update(socket, :items, &[item | &1])}
end