elixir-dev

# Elixir Dev

## Running Mix Commands

See [references/mix-commands.md](references/mix-commands.md) for full command reference.

### Test

```bash
# 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

```bash
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

```bash
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

```bash
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

```elixir
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

```elixir
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](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

```elixir
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

```elixir
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

```elixir
# 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

```elixir
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

```elixir
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

```elixir
# 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
```