Transform values inside Option, List, and Either with Cats Functor. Build a Page instance, test identity and composition, and understand what map does not guarantee.
Transform values inside Option, List, and Either with Cats Functor. Build a Page instance, test identity and composition, and understand what map does not guarantee.
A value transformation should not need to know whether its input came from an optional lookup, a list of results, or a successful response. It should describe how one value becomes another. The surrounding context can decide whether, and where, that transformation applies.
Consider a backend endpoint that exposes request summaries. The domain model contains counts, accumulated latency, and diagnostics. The response model needs counts and a derived average. The same conversion might serve one optional summary, several summaries, or a lookup that can fail.
This fourth article in the Cats, Cats Effect & fs2 series follows Semigroup and Monoid in Cats: Combining Values Safely. That article focuses on combining values. Here, I will focus on transforming a value while retaining the context around it, using Functor.
The example retains the earlier RequestSummary fields. completed counts finished requests, including failures. failed counts the failed subset. totalLatencyMicros holds the accumulated duration. errors contains selected diagnostic messages.
A SummaryResponse exposes the counts and an optional mean latency. The conversion receives a summary and returns a response value. It performs no lookup, sends no HTTP response, and mutates no shared state:
final case class RequestSummary(
completed: BigInt,
failed: BigInt,
totalLatencyMicros: BigInt,
errors: Vector[String]
):
require(completed >= 0, "completed must be nonnegative")
require(failed >= 0 && failed <= completed, "failed must be between zero and completed")
require(totalLatencyMicros >= 0, "total latency must be nonnegative")
require(completed > 0 || totalLatencyMicros == 0, "an empty summary cannot have latency")
final case class SummaryResponse(
completed: BigInt,
failed: BigInt,
averageLatencyMicros: Option[BigDecimal]
)
def toResponse(summary: RequestSummary): SummaryResponse =
SummaryResponse(
completed = summary.completed,
failed = summary.failed,
averageLatencyMicros = Option.when(summary.completed > 0)(
BigDecimal(summary.totalLatencyMicros) / BigDecimal(summary.completed)
)
)
val summary = RequestSummary(4, 1, 1000, Vector("timeout"))
val emptySummary = RequestSummary(0, 0, 0, Vector.empty)
val secondSummary = RequestSummary(2, 0, 600, Vector.empty)
val response = toResponse(summary)
// SummaryResponse(4, 1, Some(250))For a summary containing four completed requests and 1000 microseconds of total latency, the mean is 250 microseconds. With zero completed requests, the mean is absent. That distinction keeps an unavailable measurement separate from an observed zero-duration request.
The numeric totals remain exact BigInt values. The derived BigDecimal mean uses Scala’s default calculation context and may require an explicit reporting-rounding policy in an application. The response is an in-memory value, not a JSON serialization contract.
I would test this conversion independently of any container. If it reports the wrong field, a lawful mapping operation will faithfully carry that mistake into every result. Separating the function makes the business decision easier to inspect.
The conversion intentionally leaves diagnostic messages out of the response. That is a choice in toResponse, not protection supplied by Functor. Another conversion could copy those messages into a public field. A response review still needs to check which information crosses the application boundary and whether the eventual serializer represents it correctly.
An optional lookup can yield Option[RequestSummary]. A batch can yield List[RequestSummary]. A lookup with explicit failure information can yield Either[LookupError, RequestSummary]. Their successful values need the same conversion:
val optionalResponse = Option(summary).map(toResponse)
val missingResponse = Option.empty[RequestSummary].map(toResponse)
// Some(SummaryResponse(4, 1, Some(250))) and None
val listResponses = List(summary, emptySummary).map(toResponse)
val noResponses = List.empty[RequestSummary].map(toResponse)
// Two responses in input order, and an empty list
enum LookupError:
case NotFound, Unavailable
val foundLookup: Either[LookupError, RequestSummary] = Right(summary)
val failedLookup: Either[LookupError, RequestSummary] = Left(LookupError.NotFound)
val lookupResponse = foundLookup.map(toResponse)
val failedResponse = failedLookup.map(toResponse)
// Right(response) and Left(LookupError.NotFound)For Option, mapping a present summary produces a present response; mapping None leaves the result absent. For List, mapping converts each supplied summary, preserving list order. An empty list remains empty. For the Either used here, mapping converts a Right value and retains a Left error.
These types already have ordinary map methods. Cats is not required just to call Option.map or List.map. Its useful contribution here is a shared capability that generic code can request across these contexts and a domain type defined by the application.
The conversion does not contain branches for absence, collections, or lookup errors. Conversely, the contextual mapping operation does not need to know how the response calculates mean latency. Those responsibilities stay separate.
The lookup’s failure values are explicit domain cases, such as NotFound and Unavailable. Mapping the success value retains whichever failure was already present. It does not decide that an unavailable service is equivalent to a missing summary. Keeping the error side fixed prevents an ordinary response conversion from silently making that application decision.
RequestSummary is a complete value type. Option[RequestSummary] is another complete type. Option by itself is a type constructor: supplying an element type produces a complete type.
In a declaration such as F[_], F stands for a type constructor accepting one type argument. Choosing F = Option makes F[A] mean Option[A]. Choosing F = List makes it mean List[A]. This describes a type relationship; it does not inspect a runtime object to discover a hidden value.
Either needs two type arguments. For this example, the error type stays fixed while the success type changes. A type alias makes that choice explicit:
import cats.Functor
import cats.syntax.all.*
type LookupResult[A] = Either[LookupError, A]
val optionalFunctor: Functor[Option] = Functor[Option]
val lookupFunctor: Functor[LookupResult] = Functor[LookupResult]
val mappedWithContract = optionalFunctor.map(Option(summary))(toResponse)
val fixedErrorResult: LookupResult[SummaryResponse] =
lookupFunctor.map(foundLookup)(toResponse)LookupResult[RequestSummary] means Either[LookupError, RequestSummary], and LookupResult[SummaryResponse] keeps the same error type. Functor[LookupResult] can therefore describe mapping over the remaining success parameter. Scala 3 also supports an anonymous type lambda for this relationship; the named alias keeps the example readable.
The type class and the context value are different things. A Functor[Option] is an instance supplying mapping behavior. An Option[RequestSummary] is a particular value to which that behavior can be applied.
The central operation has the shape map[A, B](fa: F[A])(f: A => B): F[B]. It accepts a contextual value and a value transformation, then produces a result under the same type constructor. The Cats Functor guide introduces this contract.
def mapIn[F[_]: Functor, A, B](fa: F[A])(f: A => B): F[B] =
Functor[F].map(fa)(f)
def toResponses[F[_]: Functor](summaries: F[RequestSummary]): F[SummaryResponse] =
mapIn(summaries)(toResponse)
val genericOptional = toResponses(Option(summary))
val genericList = toResponses(List(summary, emptySummary))
val genericLookup = toResponses[LookupResult](foundLookup)
val genericFailure = toResponses[LookupResult](failedLookup)The context bound F[_]: Functor asks for an available instance. Functor[F] retrieves it, and the instance’s map performs the operation. Imported Cats syntax can express the same request as fa.map(f) when the static type exposes the appropriate capability.
toResponses now works for a present optional summary, a list, or the fixed-error lookup alias. It uses the same toResponse function in every case. It does not decide that a missing result should become a default response or that a lookup failure should be retried.
A concrete function is still appropriate when only one context is needed. The generic form earns its place when several consumers share this transformation pattern. It states a narrower dependency than requesting unrelated capabilities for sequencing, cancellation, or combining independent results.
The shared name is not the whole contract. An arbitrary class can define a method called map without having a Cats instance or satisfying its laws. Generic code using Functor[F] receives a particular implementation of the capability. Its correctness still depends on that instance being a sensible one for the type.
A backend result often carries more than its items. Suppose Page[A] contains an item list, a page number, and the total number of matching items. Converting domain items into response items should retain the pagination information.
final case class Page[A](items: List[A], pageNumber: Int, totalItems: Long):
require(pageNumber >= 1, "page numbers start at one")
require(totalItems >= items.size, "totalItems must include this page's items")
object Page:
given Functor[Page] with
def map[A, B](fa: Page[A])(f: A => B): Page[B] =
Page(
items = fa.items.map(f),
pageNumber = fa.pageNumber,
totalItems = fa.totalItems
)The instance delegates item conversion to List.map and constructs a Page[B] with the original metadata. It neither fetches another page nor recalculates the total. Because Page has no built-in mapping method in this example, Cats syntax uses the companion’s Functor[Page] instance.
The constructor requires page numbers to start at one and the total count to include at least the items on this page. Mapping a valid page with a total function preserves those structural conditions because the item count and pagination fields stay unchanged. These checks are deliberately narrower than a complete pagination protocol.
This is a policy decision worth making explicit. A mapping implementation that silently filters items, reverses them, increments the page number, or resets the total would change the meaning of a representation conversion. The instance should describe the operation the rest of the application expects.
Pagination fields describe a result obtained elsewhere. Preserving them does not establish that they are accurate or that the underlying data remains unchanged between requests. Consistency, authorization, and database snapshot rules belong to the lookup boundary.
The generic consumer needs no new branch for Page. With its instance in scope, it can transform the item values while retaining the same pagination fields:
val sourcePage = Page(List(summary, secondSummary), pageNumber = 2, totalItems = 42)
val responsePage = toResponses(sourcePage)
val syntaxPage = sourcePage.map(toResponse)
// Page(List(response, SummaryResponse(2, 0, Some(300))), 2, 42)
val emptyPage = Page(List.empty[RequestSummary], pageNumber = 1, totalItems = 0)
val emptyResponsePage = toResponses(emptyPage)
// Page(List.empty[SummaryResponse], 1, 0)The first item has a mean of 250 microseconds. The second has two completed requests and 600 microseconds of accumulated latency, giving a mean of 300. The mapped page keeps page number 2 and total item count 42.
An empty item list maps to an empty response item list without needing a fabricated summary. The particular empty-page fixture uses page number 1 and total count 0. Mapping preserves those values too.
An empty page and an absent page are also distinct results. Page(Nil, 1, 0) can report that a lookup succeeded and found no matching items. Option.empty[Page[RequestSummary]] expresses absence around the page itself. Choosing between those representations belongs to the endpoint’s contract, rather than to the item-conversion function.
For this model, converting items preserves their count and order. That statement comes from the chosen Page implementation and its list semantics. It does not mean that every possible F is a collection with a length. A generic consumer should depend on the actual capability, not on assumptions borrowed from one example.
A method with the right signature can still implement surprising behavior. Functor’s laws constrain that behavior. The identity law says that mapping the identity function should produce an equivalent contextual value. The composition law says that mapping with one function and then another should agree with mapping once using their composition.
def responseLabel(value: SummaryResponse): String =
val average = value.averageLatencyMicros.fold("n/a")(_.toString)
s"completed=${value.completed}, failed=${value.failed}, average=$average"
def checkFunctorLaws[F[_]: Functor, A, B, C](samples: List[F[A]])(
f: A => B,
g: B => C
): Unit =
val F = Functor[F]
for fa <- samples do
assert(F.map(fa)(identity[A]) == fa)
assert(F.map(F.map(fa)(f))(g) == F.map(fa)(f.andThen(g)))For Page, checking the whole record matters. A comparison that looks only at items would miss an implementation that corrupts pagination metadata. The assertions use case-class equality for these immutable fixtures, comparing both the item values and their surrounding fields.
The composition check uses ordinary pure functions. Its promise concerns equivalent results, not the allocation of the same object or identical execution traces. A correct implementation can construct a new page when mapping identity, provided the observable result remains equivalent under the chosen equality.
The law also gives a useful review question: if two successive representation transformations can be written as one composed function, should the result change? For this page instance, it should not. That observation does not promise that the compiler fuses traversals or avoids allocations. Any performance claim still needs measurement of the actual implementation and workload.
Finite assertions examine the supplied values and functions. They are not a proof for every possible page and transformation. In an application, generated checks can explore more examples, including empty and multi-item pages. Cats provides law-testing support through cats-laws, Discipline, and ScalaCheck, as described in its law-testing guide.
The supplied function determines the new value type. If that function returns Option[SummaryResponse], mapping it over an optional summary produces Option[Option[SummaryResponse]]. The outer absence and the conversion’s optional result remain separate:
def responseWhenRequests(value: RequestSummary): Option[SummaryResponse] =
Option.when(value.completed > 0)(toResponse(value))
val nested: Option[Option[SummaryResponse]] =
Option(summary).map(responseWhenRequests)
val nestedEmpty: Option[Option[SummaryResponse]] =
Option(emptySummary).map(responseWhenRequests)
// Some(Some(response)) and Some(None), not a flattened Option
def failOnValue(value: RequestSummary): SummaryResponse =
throw new IllegalArgumentException("demonstration only")
val thrownOnSome = scala.util.Try(Option(summary).map(failOnValue))
// Failure(...): Try catches the exception; Option.map did not.
val skippedOnNone = Option.empty[RequestSummary].map(failOnValue)
val skippedOnLeft = failedLookup.map(failOnValue)
val skippedOnNil = List.empty[RequestSummary].map(failOnValue)
// No input value to transform: None, Left(NotFound), and NilFunctor does not flatten the result automatically. Removing a layer changes the required operation. That is a useful point to stop and identify the next capability, rather than hiding a get, a default, or a nested pattern match inside a generic mapper.
Mapping is not exception handling. For the eager contexts demonstrated here, an exception thrown by the conversion propagates from the mapping call. The complete example uses Try around a deliberately throwing call to check that boundary. An Either input does not automatically turn an arbitrary thrown exception into its Left error type.
Mapping is not recovery. A missing optional value stays absent, and a failed lookup retains its error. Choosing a fallback, translating an error, or performing another lookup requires an explicit policy. A successful mapping operation also says nothing about whether its response satisfies a business requirement.
The laws assume suitable transformations. Reading a changing clock, mutating external state, or throwing for selected inputs makes reasoning about pure, total functions inapplicable. Such a function can still fit the Scala method’s parameter type. The compiler does not prove referential transparency or totality merely because the expression compiles.
The capability does not supply an execution model. Nothing in this example schedules threads, runs requests concurrently, or interprets an effect description. The contexts used here perform ordinary eager, sequential transformations. Other contexts can have different execution behavior; a Functor constraint alone is insufficient to infer it.
Expand the source below, save it as Functors.scala, and run scala run Functors.scala with Scala CLI. The file pins Scala 3.3.8 and Cats Core 2.13.0, the versions used for its checks. They are example versions, not a claim about the latest releases.
//> using scala "3.3.8"
//> using dep "org.typelevel::cats-core:2.13.0"
import cats.Functor
import cats.syntax.all.*
object Functors:
final case class RequestSummary(
completed: BigInt,
failed: BigInt,
totalLatencyMicros: BigInt,
errors: Vector[String]
):
require(completed >= 0, "completed must be nonnegative")
require(failed >= 0 && failed <= completed, "failed must be between zero and completed")
require(totalLatencyMicros >= 0, "total latency must be nonnegative")
require(completed > 0 || totalLatencyMicros == 0, "an empty summary cannot have latency")
final case class SummaryResponse(
completed: BigInt,
failed: BigInt,
averageLatencyMicros: Option[BigDecimal]
)
def toResponse(summary: RequestSummary): SummaryResponse =
SummaryResponse(
completed = summary.completed,
failed = summary.failed,
averageLatencyMicros = Option.when(summary.completed > 0)(
BigDecimal(summary.totalLatencyMicros) / BigDecimal(summary.completed)
)
)
val summary = RequestSummary(4, 1, 1000, Vector("timeout"))
val emptySummary = RequestSummary(0, 0, 0, Vector.empty)
val secondSummary = RequestSummary(2, 0, 600, Vector.empty)
val response = toResponse(summary)
// SummaryResponse(4, 1, Some(250))
val optionalResponse = Option(summary).map(toResponse)
val missingResponse = Option.empty[RequestSummary].map(toResponse)
// Some(SummaryResponse(4, 1, Some(250))) and None
val listResponses = List(summary, emptySummary).map(toResponse)
val noResponses = List.empty[RequestSummary].map(toResponse)
// Two responses in input order, and an empty list
enum LookupError:
case NotFound, Unavailable
val foundLookup: Either[LookupError, RequestSummary] = Right(summary)
val failedLookup: Either[LookupError, RequestSummary] = Left(LookupError.NotFound)
val lookupResponse = foundLookup.map(toResponse)
val failedResponse = failedLookup.map(toResponse)
// Right(response) and Left(LookupError.NotFound)
type LookupResult[A] = Either[LookupError, A]
val optionalFunctor: Functor[Option] = Functor[Option]
val lookupFunctor: Functor[LookupResult] = Functor[LookupResult]
val mappedWithContract = optionalFunctor.map(Option(summary))(toResponse)
val fixedErrorResult: LookupResult[SummaryResponse] =
lookupFunctor.map(foundLookup)(toResponse)
def mapIn[F[_]: Functor, A, B](fa: F[A])(f: A => B): F[B] =
Functor[F].map(fa)(f)
def toResponses[F[_]: Functor](summaries: F[RequestSummary]): F[SummaryResponse] =
mapIn(summaries)(toResponse)
val genericOptional = toResponses(Option(summary))
val genericList = toResponses(List(summary, emptySummary))
val genericLookup = toResponses[LookupResult](foundLookup)
val genericFailure = toResponses[LookupResult](failedLookup)
final case class Page[A](items: List[A], pageNumber: Int, totalItems: Long):
require(pageNumber >= 1, "page numbers start at one")
require(totalItems >= items.size, "totalItems must include this page's items")
object Page:
given Functor[Page] with
def map[A, B](fa: Page[A])(f: A => B): Page[B] =
Page(
items = fa.items.map(f),
pageNumber = fa.pageNumber,
totalItems = fa.totalItems
)
val sourcePage = Page(List(summary, secondSummary), pageNumber = 2, totalItems = 42)
val responsePage = toResponses(sourcePage)
val syntaxPage = sourcePage.map(toResponse)
// Page(List(response, SummaryResponse(2, 0, Some(300))), 2, 42)
val emptyPage = Page(List.empty[RequestSummary], pageNumber = 1, totalItems = 0)
val emptyResponsePage = toResponses(emptyPage)
// Page(List.empty[SummaryResponse], 1, 0)
def responseLabel(value: SummaryResponse): String =
val average = value.averageLatencyMicros.fold("n/a")(_.toString)
s"completed=${value.completed}, failed=${value.failed}, average=$average"
def checkFunctorLaws[F[_]: Functor, A, B, C](samples: List[F[A]])(
f: A => B,
g: B => C
): Unit =
val F = Functor[F]
for fa <- samples do
assert(F.map(fa)(identity[A]) == fa)
assert(F.map(F.map(fa)(f))(g) == F.map(fa)(f.andThen(g)))
def responseWhenRequests(value: RequestSummary): Option[SummaryResponse] =
Option.when(value.completed > 0)(toResponse(value))
val nested: Option[Option[SummaryResponse]] =
Option(summary).map(responseWhenRequests)
val nestedEmpty: Option[Option[SummaryResponse]] =
Option(emptySummary).map(responseWhenRequests)
// Some(Some(response)) and Some(None), not a flattened Option
def failOnValue(value: RequestSummary): SummaryResponse =
throw new IllegalArgumentException("demonstration only")
val thrownOnSome = scala.util.Try(Option(summary).map(failOnValue))
// Failure(...): Try catches the exception; Option.map did not.
val skippedOnNone = Option.empty[RequestSummary].map(failOnValue)
val skippedOnLeft = failedLookup.map(failOnValue)
val skippedOnNil = List.empty[RequestSummary].map(failOnValue)
// No input value to transform: None, Left(NotFound), and Nil
def main(args: Array[String]): Unit =
assert(response == SummaryResponse(4, 1, Some(BigDecimal(250))))
assert(toResponse(emptySummary) == SummaryResponse(0, 0, None))
assert(toResponse(secondSummary) == SummaryResponse(2, 0, Some(BigDecimal(300))))
assert(optionalResponse.contains(response))
assert(missingResponse.isEmpty)
assert(listResponses == List(response, SummaryResponse(0, 0, None)))
assert(noResponses == Nil)
assert(lookupResponse == Right(response))
assert(failedResponse == Left(LookupError.NotFound))
assert(mappedWithContract == optionalResponse)
assert(fixedErrorResult == lookupResponse)
assert(genericOptional == optionalResponse)
assert(genericList == listResponses)
assert(genericLookup == lookupResponse)
assert(genericFailure == failedResponse)
assert(mapIn(List(1, 2))(_.toString) == List("1", "2"))
assert(mapIn(Option.empty[Int])(_.toString).isEmpty)
assert(mapIn[LookupResult, Int, String](Left(LookupError.Unavailable))(_.toString) == Left(LookupError.Unavailable))
assert(responsePage == Page(List(response, toResponse(secondSummary)), 2, 42))
assert(syntaxPage == responsePage)
assert(responsePage.items.size == sourcePage.items.size)
assert(responsePage.pageNumber == sourcePage.pageNumber)
assert(responsePage.totalItems == sourcePage.totalItems)
assert(responsePage.items.head.completed == summary.completed)
assert(responsePage.items(1).completed == secondSummary.completed)
assert(sourcePage.items == List(summary, secondSummary))
assert(emptyResponsePage == Page(List.empty[SummaryResponse], 1, 0))
assert(emptyResponsePage.pageNumber == emptyPage.pageNumber)
assert(emptyResponsePage.totalItems == emptyPage.totalItems)
assert(mapIn(Page(List(1, 2), 3, 20))(_.toString) == Page(List("1", "2"), 3, 20))
assert(scala.util.Try(Page(List(1), 0, 1)).isFailure)
assert(scala.util.Try(Page(List(1, 2), 1, 1)).isFailure)
assert(scala.util.Try(Page(List.empty[Int], 1, -1)).isFailure)
assert(nested == Some(Some(response)))
assert(nestedEmpty == Some(None))
assert(Option.empty[RequestSummary].map(responseWhenRequests).isEmpty)
assert(thrownOnSome.isFailure)
assert(thrownOnSome.failed.toOption.exists(_.getMessage == "demonstration only"))
assert(skippedOnNone.isEmpty)
assert(skippedOnLeft == Left(LookupError.NotFound))
assert(skippedOnNil == Nil)
assert(responseLabel(toResponse(emptySummary)) == "completed=0, failed=0, average=n/a")
assert(responseLabel(response) == "completed=4, failed=1, average=250")
assert(scala.util.Try(foundLookup.map(failOnValue)).isFailure)
checkFunctorLaws[Option, RequestSummary, SummaryResponse, String](
List(None, Some(emptySummary), Some(summary), Some(secondSummary))
)(toResponse, responseLabel)
checkFunctorLaws[List, RequestSummary, SummaryResponse, String](
List(Nil, List(emptySummary), List(summary, emptySummary, secondSummary))
)(toResponse, responseLabel)
checkFunctorLaws[LookupResult, RequestSummary, SummaryResponse, String](
List(Left(LookupError.NotFound), Left(LookupError.Unavailable), Right(emptySummary), Right(summary))
)(toResponse, responseLabel)
checkFunctorLaws[Page, RequestSummary, SummaryResponse, String](
List(emptyPage, Page(List(summary), 1, 1), sourcePage)
)(toResponse, responseLabel)
println(s"Optional response: $optionalResponse")
println(s"Failed response: $failedResponse")
println(s"Response page: $responsePage")
println(s"Nested response: $nested")
println("All Functor checks passed.")I start with the plain function: what should one input value become? Then I identify what the surrounding context needs to retain. If the remaining operation is mapping that function while preserving the context’s defined behavior, Functor expresses the dependency directly.
The useful separation is between the conversion and the context handling it. Test the conversion’s business meaning, test a custom instance’s laws, and keep error handling and execution decisions visible. Those checks support different parts of the program.
Continue through the Cats, Cats Effect & fs2 series page, revisit Type classes, Eq, and Show, or browse the other Scala and functional programming articles.
Scala, JVM, AI, and backend systems. I send practical articles when there is something worth reading.
Join the newsletterNecessary cookies keep the site working. With your permission, I use analytics cookies to understand which articles are useful.