English for Gleam Developers

Gleam brings a statically-typed, functional language to the BEAM (the Erlang virtual machine), which means its vocabulary blends Erlang/Elixir concurrency terms with type-system vocabulary from languages like Rust and OCaml. A team needs to be precise about which layer a bug or design question belongs to — the type system, or the runtime’s process model. This guide covers the English used when discussing Gleam code with a team.

Key Vocabulary

Exhaustiveness checking — the compiler’s guarantee that a case expression handles every possible variant of a custom type, catching missing branches at compile time rather than at runtime. “The compiler is refusing to build because this case doesn’t handle the new Cancelled variant — that’s exhaustiveness checking doing exactly its job.”

Custom type — Gleam’s tagged union type (similar to an enum with data), used to model a fixed set of distinct states or variants explicitly, rather than relying on strings or booleans. “Instead of a boolean is_error flag plus a nullable message field, model this as a custom type with Ok and Error variants — it makes invalid states unrepresentable.”

BEAM process — a lightweight, isolated unit of concurrency provided by the Erlang VM, which Gleam code runs on and can spawn cheaply, each with its own memory and message mailbox. “Don’t share mutable state between these two BEAM processes directly — send a message instead, that’s the concurrency model the whole platform is built around.”

Result type — Gleam’s built-in Result(a, b) type representing either success (Ok) or failure (Error), used pervasively instead of exceptions for expected failure cases. “This function returns a Result instead of throwing, so the caller is forced by the type system to explicitly handle the error case — nothing can silently ignore it.”

Let assert — a pattern-matching construct that asserts a value matches a specific shape, crashing at runtime if it doesn’t, used deliberately for cases considered truly unreachable. “Using let assert Ok(value) = result here is fine because we’ve already validated this can’t fail — but flag it in review, since it bypasses the exhaustiveness guarantee.”

Supervision tree — an Erlang/Elixir/Gleam pattern where processes are organized hierarchically, with supervisors automatically restarting failed child processes according to a defined strategy. “If this worker crashes on a bad message, the supervision tree just restarts it cleanly — we don’t need defensive error handling everywhere, the platform handles recovery.”

Common Phrases

• “Does this case expression handle every variant, or is the compiler flagging a missing branch?”
• “Should this be a custom type instead of a raw string or boolean flag?”
• “Is this state shared between processes, or passed via a message?”
• “Is this function returning a Result, or does failure need to be handled another way?”
• “Is this let assert actually safe, or could that input realistically fail?”

Example Sentences

Reviewing a pull request: “This uses a plain string to represent the order status — let’s model it as a custom type with explicit variants so the compiler catches any unhandled case at build time.”

Explaining a design decision: “We split this into two BEAM processes, one for the incoming message queue and one for processing, so a slow processor doesn’t block message intake.”

Describing a bug: “The crash happened because a let assert on a value we assumed was always present actually failed under a rare input — we should have used a proper case with an explicit error path.”

Professional Tips

• Say “exhaustiveness checking” specifically when explaining why the compiler rejects an incomplete case — it’s the feature’s actual name, not just “type checking.”
• When reviewing state representation, ask “could this be a custom type instead?” — this is the standard nudge away from stringly-typed or boolean-flag designs in Gleam code review.
• Use “BEAM process” rather than “thread” — they are a different concurrency primitive with different guarantees, and conflating the terms confuses newcomers from other languages.
• Flag “let assert” explicitly in review as a deliberate escape hatch from exhaustiveness — it should be rare and justified, not a default habit.

Practice Exercise

1. Explain in two sentences why exhaustiveness checking catches bugs that a runtime language wouldn’t.
2. Write a one-sentence code review comment recommending a custom type over a boolean flag.
3. Describe, in your own words, why sharing mutable state between BEAM processes goes against the platform’s design.