programming-elixir— agent skill

Mental model

Elixir is a functional language built on the BEAM, a runtime designed for concurrency, isolation, and fault tolerance. The big architectural lever is OTP — supervision trees and lightweight processes — not language features. "Let it crash" is not a slogan; it's the design: code the happy path, let supervisors restart on failure, and avoid defensive programming. Most maintenance pain comes from treating processes like threads, from rescuing too eagerly, and from spreading business logic across GenServers when plain modules would do.

Functional core

• Pure functions in modules form the bulk of a codebase; processes are for state, isolation, and concurrency — not for organization
• Multi-clause functions with pattern matching replace if/else/case chains
• Pipe (|>) when data flows linearly; then/2 when the value isn't the first argument
• with for happy-path chains of {:ok, _} / {:error, _} — the canonical control-flow construct for fallible pipelines
• Tagged tuples for return values: {:ok, value} / {:error, reason} — never raise for expected outcomes
• Structs (defstruct) for typed data; @type and @spec on the public API

OTP architecture

• A supervision tree is the application skeleton — children listed in the Application module's start/2
• Each process has one job; if a process needs to do two things, it's two processes
• GenServer for stateful services with a clear public API (MyServer.call(...) wrapping GenServer.call)
• DynamicSupervisor for children started at runtime; PartitionSupervisor for sharded workloads
• Task and Task.Supervisor for one-shot async work
• Choose restart strategies deliberately: :one_for_one for independent children, :rest_for_one when later children depend on earlier ones
• Let processes crash on unexpected input — the supervisor restarts cleaner state than rescue blocks paper over

Concurrency patterns

• Processes are cheap (millions on a node) — spawn freely when isolation helps
• Send messages, don't share state; the BEAM gives you message-passing for free
• Long-running work in a Task under a supervisor, not in a controller or LiveView callback
• Backpressure via GenStage / Flow / Broadway when producers can outpace consumers
• Time-outs on every GenServer.call; the default 5 seconds is rarely what you want for slow operations

Error handling

• with for chained fallible operations — one path for success, one clause per failure shape
• Tagged tuples for expected failures; raise only for genuinely exceptional conditions
• Provide context in errors: {:error, {:not_found, %{type: :user, id: id}}} beats {:error, :not_found}
• Rescue at system boundaries (HTTP handlers, message consumers) where you must respond to the outside world

Ecto and persistence

• Schemas describe database shape; changesets validate and cast at the boundary
• Keep query composition explicit: small named functions returning queryables, composed at the call site
• Multi-step writes use Ecto.Multi so the whole transaction rolls back on failure
• Avoid putting business logic in changesets — they validate data, they don't make decisions
• Migrations are forward-only in production; design rollback as a new migration

Phoenix and LiveView

• Contexts (Accounts, Billing, Inventory) are the public API for a domain — controllers and LiveViews call contexts, not Ecto directly
• LiveView holds UI state in socket.assigns; long work goes to a Task and streams results back via handle_info
• Streams (stream/3) for large lists — they avoid sending the full collection on every diff
• Channels for low-level WebSocket needs that LiveView doesn't fit
• Function components and slots for composable UI; keep template logic minimal

Testing

• ExUnit with async: true for tests that don't touch shared state — the BEAM's isolation makes most tests parallelizable
• Pattern-match in assert: assert {:ok, %User{name: "Ada"}} = create_user(params)
• describe blocks group tests around a function; setup and setup_all for fixtures
• Mox for behaviour-based mocks; define a behaviour, swap implementations in tests
• Test contexts and pure modules directly; LiveView/controller tests are integration tests

Common pitfalls

• %{map | key: val} only updates existing keys — Map.put/3 for new
• String.to_atom/1 on user input leaks memory (atoms aren't garbage-collected) — use String.to_existing_atom/1
• Enum materializes; Stream is lazy — use Stream for large or infinite sequences
• A GenServer that calls itself synchronously deadlocks — use cast, or restructure