Domain-Specific Error Types vs. Global Error Enums for Large-Scale Result Handling

Answer to the Core Questions

1. Does a global error type undermine Gleam’s static analysis?

Yes, to a measurable degree. Gleam’s Result type guarantees exhaustive matching only when the Error variant is a concrete type that the compiler can inspect. A global enum forces callers to pattern‑match on a single discriminant, meaning that a change to the enum (adding a new variant) requires updating every place that does a match. In contrast, domain‑specific error types let the compiler enforce that each module only handles the errors it can actually produce, keeping the match sites small and self‑contained.

2. What’s the most maintainable way to lift domain errors into an application‑wide type?

Adopt a two‑layer strategy:

1. Internal layer: Each module defines a Result with its own Error type (or sealed union). This keeps the error surface minimal and type‑safe within the module.
2. External layer: Expose a small, stable AppError enum that represents the failure states clients (or higher‑level orchestration) care about. Provide a conversion function that maps each domain error to the corresponding AppError variant.

When a module returns a Result, callers that need to surface the error to the next layer simply call the conversion. The conversion can be a tiny match that is easy to maintain because it lives in one place. This pattern preserves static exhaustiveness inside modules while still giving you a unified contract for the rest of the system.

Practical Steps for Your Gleam Project

1. Define domain errors. Use a sealed union for each module’s error space, e.g.:

   pub type UserError
     = NotFound
     | ValidationError(String)
     | DatabaseError(DatabaseErr)
   

2. Wrap domain errors into AppError. Create a single enum:

   pub type AppError
     = User(UserError)
     | Auth(AuthError)
     | System(SystemError)
   

3. Implement conversion functions. Each domain module exposes:

   pub fn to_app_error(err: UserError) -> AppError {
     AppError::User(err)
   }
   

4. Propagate with use or Result.map_err. Example:

   pub fn get_user(id: Int) -> Result(User, AppError) {
     UserRepo.fetch(id).map_err(UserError::DatabaseError).map_err(UserError::to_app_error)
   }
   

5. Centralise serialization. When sending errors over the wire, map AppError to a stable JSON or Protobuf representation. Keep the domain errors opaque.

Verification Checklist (Optional)

• Count enum variants vs. domain error types.
• Run gleam test to ensure all match sites are exhaustive.
• Profile error construction overhead if performance is critical.
• Check that all external clients only depend on AppError.

Would you like to confirm the number of public error variants you plan to expose? That detail can influence how many conversion functions you need to maintain.