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