DEV Community: Katarzyna Kozłowska

Sealed Monad: Linear Business Flows as Algebraic Data Types

Katarzyna Kozłowska — Tue, 13 Oct 2026 08:39:37 +0000

Every team that builds a Scala backend long enough makes the same structural mistake: they use nested flatMap and match to express multi-step business logic. The types are right. The code does what it's supposed to do. And then requirements change, someone adds a step, and the next developer has to trace a decision tree through nested match arms to understand what the function actually does. At that point, the maintainability cost is already sunk. You're just paying it in review time and bugs.

This article covers two tools that solve the structural problem together: ADTs for expressing typed business outcomes, and sealed-monad for composing them linearly.

ADTs for business outcomes

A sealed trait is the right type for business outcomes. Not exceptions, not raw booleans, not strings. Here's what a login result looks like:

sealed trait LoginResult
object LoginResult {
  case class LoggedIn(token: String) extends LoginResult
  case object InvalidCredentials     extends LoginResult
  case object Deleted                extends LoginResult
  case object ProviderAuthFailed     extends LoginResult
}

The sealed modifier means the compiler knows the complete list of cases. No subclass can be added outside the file. Add case object AccountLocked extends LoginResult, recompile, and the compiler flags every pattern match on LoginResult that doesn't handle it.

The alternatives don't give you this. Exceptions are invisible to the type system: the signature def login(...): Future[String] tells the caller nothing about what can go wrong. Raw booleans lose the reason: you know the login failed, not why. String errors can't be distinguished by the compiler: Left("invalid credentials") and Left("account deleted") are the same type.

The composition problem

Defining the outcome type is the easy part. The problem is chaining multiple operations, each returning a typed outcome, into a single flow. Consider a login with four steps:

Find the user by email. If none exists: InvalidCredentials.
Check the user isn't archived. If they are: Deleted.
Find the auth method. If none: ProviderAuthFailed.
Verify the credentials. If they fail: InvalidCredentials.

In standard Scala, this is what you write:

def login(email: String): Future[LoginResult] =
  findUser(email).flatMap {
    case None =>
      Future.successful(LoginResult.InvalidCredentials)
    case Some(user) if user.archived =>
      Future.successful(LoginResult.Deleted)
    case Some(user) =>
      findAuthMethod(user.id, Provider.EmailPass).flatMap {
        case None =>
          Future.successful(LoginResult.ProviderAuthFailed)
        case Some(am) if !checkAuthMethod(am) =>
          Future.successful(LoginResult.InvalidCredentials)
        case Some(_) =>
          Future.successful(LoginResult.LoggedIn(issueTokenFor(user)))
      }
  }

The types are correct and the logic is correct. Look at the structure anyway:

The happy path is buried in the innermost match arm.
Error cases are scattered across the nesting rather than declared next to the step they belong to.
Adding a step means adding another nesting level, not another line.
A reviewer has to mentally trace the execution tree to verify the logic matches the requirement.

Four steps already take 6 match arms across 2 nested blocks.

We ran into this at Iterators while building a backend for a client with unusually dense business rules. Login was fine. Order creation was manageable. But the cancellation flow had seven distinct failure modes, each conditional on the previous steps, and the nested version had become something nobody wanted to modify. Adding a step for fraud detection before the payment charge required reading the full function, finding the right nesting level, and not breaking the cases already there. It took longer than it should have, and the resulting review was not clean. The logic was right. The structure was wrong.

sealed-monad

sealed-monad is an open-source Scala library built at Iterators. It wraps the composition pattern in a monadic abstraction that makes for-comprehensions work with ADT-based business flows. The same login logic:

import pl.iterators.sealedmonad.syntax._

def login(email: String): Future[LoginResult] =
  (for {
    user       <- findUser(email)
                    .valueOr(LoginResult.InvalidCredentials)
                    .ensure(!_.archived, LoginResult.Deleted)
    authMethod <- findAuthMethod(user.id, Provider.EmailPass)
                    .valueOr(LoginResult.ProviderAuthFailed)
                    .ensure(checkAuthMethod, LoginResult.InvalidCredentials)
  } yield LoginResult.LoggedIn(issueTokenFor(user))).run

Read it top to bottom:

Find the user. If none: InvalidCredentials.
Ensure not archived. If archived: Deleted.
Find auth method. If none: ProviderAuthFailed.
Ensure credentials pass. If not: InvalidCredentials.
If all succeed: LoggedIn.

The happy path is the yield. Each failure case is an inline annotation on the step it belongs to. The structure of the code is the structure of the requirement.

The two operators

valueOr(fallback) converts an Option or Either result. If the step produces None or Left, the chain short-circuits with the fallback:

// Option: short-circuit on None
findUser(email).valueOr(LoginResult.InvalidCredentials)

ensure(predicate, fallback) checks a condition on a successful result. If the predicate fails, the chain short-circuits with the fallback:

// Short-circuit if the user is archived
.ensure(!_.archived, LoginResult.Deleted)

Both work inside a single for-comprehension because the Sealed wrapper is a monad over the effect type F. The .run at the end collapses the chain back into F[LoginResult].

What the compiler checks

Because LoginResult is a sealed trait, the compiler knows every branch. If a call site doesn't handle all cases:

login(email).map {
  case LoginResult.LoggedIn(token) => Ok(token)
  case LoginResult.InvalidCredentials => Unauthorized
  // Warning: match may not be exhaustive.
  // It would fail on: Deleted, ProviderAuthFailed
}

The compiler surfaces the gap before the code reaches production. Add a new failure mode to the business logic, and the compiler flags every call site that doesn't handle it. By default that is a warning, so enable fatal warnings in your build if you want a missing case to fail the compile. With exception-based error handling, adding a new failure case compiles cleanly and the surprise arrives at runtime.

Effect systems

sealed-monad works with any effect type that has a cats.Monad instance:

// Future
def login(email: String): Future[LoginResult] =
  (for { ... } yield LoginResult.LoggedIn(token)).run

// cats-effect IO
def login(email: String): IO[LoginResult] =
  (for { ... } yield LoginResult.LoggedIn(token)).run

// Monix Task
def login(email: String): Task[LoginResult] =
  (for { ... } yield LoginResult.LoggedIn(token)).run

Migrating from Future to IO means changing the effect type of the functions you compose. The business logic in the for-comprehension stays identical.

Where it fits and where it doesn't

sealed-monad is for multi-step business flows where each step can fail with a typed domain error. That's the scope.

It is not a general-purpose error handling library. Infrastructure errors, database failures and network timeouts do not belong in your business ADT. A database timeout is not a LoginResult case. It's an exception, and it should propagate as one. The sealed trait should contain only the outcomes the calling code needs to handle and route.

The practical question before reaching for it: does the function implement a business requirement that has multiple named failure modes, each meaningful to the calling code? If yes, sealed-monad is worth using. If the function is infrastructure plumbing with one failure mode (it worked or it didn't), standard error handling is correct.

One more thing about the compile-time check: it only holds if you treat it seriously. If you add a catch-all case to your pattern matches to make the compiler stop warning, you've opted out of the guarantee.

Getting started

// build.sbt
libraryDependencies += "pl.iterators" %% "sealed-monad" % "2.0.1"

import pl.iterators.sealedmonad.syntax._

Scala 2.13 and Scala 3, cats-core as the only dependency. Apache 2.0 license.

GitHub: https://github.com/theiterators/sealed-monad
Docs: https://theiterators.github.io/sealed-monad/
The longer version of this article, with an order-processing flow and a testing section, is on the Iterators blog.

sealed-monad is maintained by Iterators.

Baklava: Generate API Documentation and Type-Safe Clients from Scala Routing Tests

Katarzyna Kozłowska — Tue, 25 Aug 2026 09:49:56 +0000

API documentation has a reliability problem. The code gets updated; the OpenAPI spec gets forgotten. The spec gets updated; the TypeScript client doesn't regenerate. By the time an enterprise client asks for your API contract, the document you hand them describes a system that no longer exists. Baklava, an open-source library by Iterators, solves this structurally: documentation is generated from the tests that verify your actual API behaviour, so it cannot drift.

The problem

Documentation drift is the default state of any API that lives long enough. The causes are well-understood: docs and code are maintained separately, documentation updates require extra discipline at every PR, and no automated check catches a route signature change that wasn't reflected in the OpenAPI file.

The consequence is real. Clients building against a stale spec hit integration errors in production. Internal teams onboarding to a service spend hours reconciling the documented contract with actual behaviour. TypeScript front-ends break when an API response field changes without a corresponding client update. The problem compounds as the API grows.

The solution

Baklava integrates into your existing test suite. When routing tests run, baklava observes each request and response, infers the API surface, and generates documentation as a test output, not as a separate build step, not as a manually-maintained file.

In baklava, the test is the documentation spec. Instead of a standard assertion block, each route is defined with path(), supports(), and onRequest() scenarios that both verify the API behaviour and describe it for documentation output:

`// The test IS the documentation spec
class UserApiSpec extends AnyFunSpec
with BaklavaPekkoHttp[Unit, Unit, ScalatestAsExecution]
with BaklavaScalatest[Route, ToEntityMarshaller, FromEntityUnmarshaller] {

path("/users/{userId}")(
supports(
GET,
pathParameters = pLong,
summary = "Get user by ID"
)(
onRequest(pathParameters = 1L)
.respondsWithUser
.assert { ctx =>
ctx.performRequest(routes).body.id shouldBe 1L
},
onRequest(pathParameters = 999L)
.respondsWithErrorResponse
.assert { ctx => ctx.performRequest(routes) }
)
)
}
// Running sbt test generates OpenAPI, HTML, and TypeScript, automatically.
// If the test breaks, the docs don't publish.`

If the test passes, the documentation is accurate, because the test verified the behaviour the documentation describes. If the route changes and the test breaks, the documentation won't publish until the test is fixed. Documentation drift becomes structurally impossible.

Coverage

Baklava supports the two dominant Scala HTTP frameworks, Pekko HTTP and http4s, and integrates with ScalaTest, Specs2, and MUnit. Seven output formats, each an independent SBT dependency, auto-discovered via reflection:

Simple HTML: self-contained, browsable human-readable documentation
OpenAPI: OpenAPI 3.0.1 spec with SwaggerUI integration for Pekko HTTP, the standard contract format for enterprise API integrations
TS-REST: TypeScript npm package using ts-rest and Zod for type-safe API contracts
oRPC Contract Format: TypeScript package with oRPC contracts, Zod validators, and a ready-made client factory
TypeScript Fetch Client: plain-TypeScript client using the browser/Node fetch API, no external runtime dependencies
Postman: Postman Collection v2.1, importable into Postman and Insomnia
sttp client: Scala sttp-client4 request builders for every endpoint

Scala 2.13 and Scala 3, JDK 11+. Baklava also integrates with kebs: if your project already uses kebs for domain type derivation, baklava picks up the schema definitions automatically.

Adoption and maintenance

Baklava v1.4.0 was released in May 2026 and is actively maintained by Iterators. Apache 2.0 license.

The approach, deriving documentation from tests rather than maintaining it separately, is not new in principle, but prior implementations in the Scala ecosystem typically required significant test instrumentation or source-level annotation. Baklava keeps the overhead minimal: mix in a trait, run your existing tests, get documentation as output.

Context

OpenAPI generation tools for Scala generally fall into two camps: annotate source code (tapir, endpoints4s) or maintain separate spec files. Source annotation couples documentation concerns into routing logic and requires adopting the library's routing model. Separate spec files require discipline. Baklava is positioned differently: it uses the test suite as the source of truth, which works with any routing code that produces testable HTTP responses, so no migration of existing routes is required.

As Łukasz Sowa, Managing Partner at Iterators, puts it: "Integration tests are one of the most overlooked types of tests. 'Units pass, I'm ok!' until they aren't and it isn't. The amount of work to get them right used to be the usual excuse; now AI can do the heavy lifting, which removes it. But integration tests are more than a good night's sleep pill. They're the ultimate spec for how the outside world interacts with your system. With baklava, we turn integration tests into integration artifacts, for many kinds of consumers."

Baklava is open source under the Apache 2.0 license. GitHub: https://github.com/theiterators/baklava