railroad

A terse Haskell railroad error handling DSL abstracting over error functors by catamorphism via Either.

railroad is a tiny, opinionated library that brings Railway Oriented Programming (ROP) to Haskell. It gives you a clean, linear DSL for collapsing error-carrying values (Maybe, Either, Validation, Bool, and collections thereof) directly into your MonadError (or Effectful.Error) context — no noisy case expressions, no repeated either/maybe boilerplate.

---

Why railroad?

Typical error handling in Haskell quickly turns into a tarpit of accidental controlflow:

do
  user <- case fetchUser uid of
    Nothing -> throwError UserNotFound
    Just u  -> pure u

  cfg <- case loadConfig path of
    Left e  -> throwError (toConfigError e)
    Right c -> pure c

railroad replaces all of that with a single, consistent operator family that reads linearly:

do
  user <- fetchUser uid ? UserNotFound          -- Maybe / Either / Validation / Bool
  cfg  <- loadConfig path ?? toConfigError      -- custom error mapping
  items <- queryItems filters ?+ NoResultsFound -- cardinality guard

Install

Nix

Here is an expression you can add to ghcWithPackages:

railroad = pkgs.haskellPackages.callCabal2nix "railroad" (pkgs.fetchFromGitHub 
  { owner  = "mastratisi"
  ; repo   = "railroad"
  ; rev    = "master"
  ; sha256 = pkgs.lib.fakeSha256; # Nix will tell you the real hash on first build   
  }) {};

Hackage

The package is under the name railroad. Link: https://hackage.haskell.org/package/railroad

Operators

Operator	Purpose	Example
??	Main collapse with custom error mapping	action ?? toMyError
?	Collapse to constant error	action ? MyError
?>	Predicate guard	val ?> isBad toErr
??~	Recover with a mapped default (error → value)	action ??~ toDefaultVal
?~	Recover with a fixed default value	action ?~ defaultVal
?+	Require non-empty collection	items ?+ NoResults
?!	Require exactly one element	items ?! fromCardinalityErr
?∅	Require empty collection (alias ?@)	items ?∅ DuplicateFound

All operators work uniformly on:

• Bool
• Maybe a
• Either e a
• Validation e a
• Traversable containers of the above ([Maybe a], Vector (Either e a), …)

Design Highlights

• Bifurcate typeclass turns any “railroad-shaped” functor into Either (CErr f) (CRes f) via catamorphism
• Native support for Effectful (Error effect) and MTL (MonadError) via Railroad.MonadError
• Short-circuiting for Either, error accumulation for Validation

See railroad.md for a deeper tour, or just read the code at Railroad.hs. It's a short file.

Comparison with hoist-error

Both hoist-error and Railroad are small, focused Haskell libraries that make error handling in MonadError (or Error effects) far more pleasant than raw case expressions, either, or maybe. They let you collapse partiality structures (Maybe, Either, etc.) into a linear monadic flow unpacking values while still controlling how errors are turned into your application’s error type.

They solve the same core pain point—“railroad-style” error handling where the happy path stays on the main track and errors branch off cleanly—but they do it with different levels of abstraction and power.

Quick Feature Comparison

Feature	hoist-error	Railroad
Core mechanism	PluckError class + hoistError	Bifurcate type family + catamorphism to Either
Supported functors	Maybe, Either e, ExceptT e m	Bool, Maybe, Either, Validation, traversables of any of the above
Collection handling	None (manual)	Built-in cardinality: ?+ (non-empty), ?! (exactly one), ?∅ (must be empty)
Error mapping	Function or constant (<%?>, <?>)	Function (??) or constant (?) with typed CErr constructors
Recovery / defaults	No built-in	?~ / ??~ (constant or computed fallback)
Guards	No	?> (predicate → error)
Monadic hoisting	<%!?>, hoistErrorM	Handled naturally by >>= + ??
Primary ecosystem	Any MonadError / ExceptT / mtl	Effectful Error (with full MonadError re-export)
Dependencies	Minimal (base + mtl/transformers)	effectful, validation, mtl
Learning curve	Very low (just a few operators)	Slightly higher (8 operators, but ?? and ? cover ~90%)
Size	~150 LOC	~150 LOC

When to choose which?

Choose hoist-error if you want:

• The absolute smallest API and dependency footprint
• Only need simple Maybe/Either/ExceptT hoisting
• Classic mtl or transformers codebases

Choose Railroad if you want:

• A full DSL that feels built into the language
• Excellent Validation support (error accumulation)
• Frequent collection checks or predicate guards
• Maximum readability in Effectful applications

Contact

Feel free to DM me on https://x.com/mastratisi97 . I find it interesting to know if other people also have found this module useful.