Handling Errors in Gleam with Result: A Practical Alternative to Exceptions

The problem with thrown exceptions

Most JavaScript‑derived languages rely on throw to signal failure. In an asynchronous pipeline this forces you to sprinkle try/catch blocks everywhere, breaking referential transparency and making composition fragile. When a library you depend on throws, the error surface expands silently, and static analysis can’t help you.

Gleam’s Result type as a pure alternative

Gleam ships a single algebraic data type for fallible operations:

pub type Result(value, error) {
  Ok(value)
  Err(error)
}

Every function that can fail returns a Result. The caller decides what to do with Ok or Err – no hidden control flow, no stack unwinding. Because Result is a regular type, it works with the usual combinators (map, bind, map_error) and with pattern matching.

Linear code with try/catch syntax

Gleam adds a lightweight try expression that pattern‑matches on Result and lets you write sequential code:

pub fn read_config() -> Result(Config, FileError) {
  try {
    let contents = File.read!("config.json")
    let parsed   = Json.decode(contents)
    Ok(parsed)
  } catch err -> Err(err)
}

The try block evaluates each line; if any expression yields Err, the block short‑circuits to the catch clause. The generated JavaScript (or Erlang) contains explicit Result checks, not native try/catch, preserving the pure error model.

Worked example: a file‑reading pipeline

Below is a minimal Gleam project that reads a JSON file, validates it, and returns a typed config record.

1. Create the project (run in a terminal with write access to your workspace):

   gleam new config_reader
   cd config_reader

2. Add the gleam_json dependency in gleam.toml:

   [dependencies]
   gleam_json = "~> 1.0"

3. Implement the pipeline in src/config_reader.gleam:

   import gleam/io
   import gleam/result
   import gleam/json
   import gleam/file
   
   pub type Config {
     Config(port: Int, host: String)
   }
   
   pub fn load_config(path: String) -> Result(Config, String) {
     try {
       let raw   = file.read(path)          // Result(String, FileError)
       let text  = result.map(raw, fn(b) { io.utf8_decode(b) })
       let json  = json.decode(text, json.object([
         field("port", json.int),
         field("host", json.string)
       ]))
       let cfg   = result.map(json, fn(o) { Config(port: o.port, host: o.host) })
       Ok(cfg)
     } catch err -> Err(inspect(err))
   }
   
   pub fn main() {
     case load_config("config.json") {
       Ok(cfg) -> io.println("Loaded: " <> inspect(cfg))
       Err(e)  -> io.println("Failed: " <> e)
     }
   }

4. Build and run (requires a config.json file in the project root):

   gleam build
   # Expected: compiled JavaScript in build/dev/javascript/
   gleam run   # runs the generated JS via Node

   If the file exists and is valid JSON, you’ll see Loaded: Config(port: 8080, host: "localhost"). Missing or malformed files produce Failed: … with a readable description.

Trade‑offs and limitations

• Verbosity: each fallible step must be wrapped or combined with Result.map/bind. In large pipelines the code grows compared to a single try/catch block.
• Bundle size: front‑end targets (JavaScript) carry the Result runtime and combinators, adding a few kilobytes. For tiny widgets this may matter.
• Interop friction: calling a JavaScript library that throws re‑introduces exception‑based flow. Wrap such calls in a small Gleam shim that catches and returns Result.
• Learning curve: compiler error messages reference Result constructors rather than line numbers of a thrown exception, which can feel opaque at first.

How to verify the approach in your own codebase

1. Run gleam repl and evaluate a tiny try block:

   > try { Ok(1) } catch e -> Err(e)
   Ok(1) : Result(Int, Nil)

   Confirm the REPL prints Ok or Err without throwing.
2. Add --warn-unused-result (or the equivalent flag in gleam.toml) to get compiler warnings when a Result is ignored.
3. Inspect the generated JavaScript (build/dev/javascript/config_reader.mjs) – you should see explicit if (result.tag === "Ok") … else … branches, not native try/catch.

Actionable next step

Pick one service boundary (e.g., HTTP request handling, file I/O, or a third‑party SDK) and rewrite its error path to return Result. Enable the unused‑result warning, run the test suite, and measure the reduction in uncaught‑exception logs. The change is reversible – you can always fall back to a thin wrapper that throws – but the default becomes explicit, composable, and statically checked.