_   _ _       _                      _   ___           _          _        ___
| | | (_)     | |                    | | / (_)         | |        | |      |_  |
| |_| |_  __ _| |__   ___ _ __ ______| |/ / _ _ __   __| | ___  __| |______  | |
|  _  | |/ _` | '_ \ / _ \ '__|______|    \| | '_ \ / _` |/ _ \/ _` |______| | |
| | | | | (_| | | | |  __/ |         | |\  \ | | | | (_| |  __/ (_| |    /\__/ /
\_| |_/_|\__, |_| |_|\___|_|         \_| \_/_|_| |_|\__,_|\___|\__,_|    \____/
          __/ |
         |___/

Unifying Composable Effects and Advanced Optics for Java

Higher-Kinded-J brings two capabilities that Java has long needed: composable error handling through the Effect Path API, and type-safe immutable data navigation through the Focus DSL. Each is powerful alone. Together, they form a unified approach to building robust applications, where effects and structure compose seamlessly.

No more pyramids of nested checks. No more scattered validation logic. Just clean, flat pipelines that read like the business logic they represent.

The Effect Path API

At the heart of Higher-Kinded-J lies the Effect Path API: a railway model for computation where success travels one track and failure travels another. Operations like map, via, and recover work identically across all effect types, whether you are handling optional values, typed errors, accumulated validations, or deferred side effects.

// Traditional Java: pyramid of nested checks
if (user != null) {
    if (validator.validate(request).isValid()) {
        try {
            return paymentService.charge(user, amount);
        } catch (PaymentException e) { ... }
    }
}

// Effect Path API: flat, composable railway
return Path.maybe(findUser(userId))
    .toEitherPath(() -> new UserNotFound(userId))
    .via(user -> Path.either(validator.validate(request)))
    .via(valid -> Path.tryOf(() -> paymentService.charge(user, amount)))
    .map(OrderResult::success);

The nesting is gone. Each step follows the same pattern. Failures propagate automatically. The business logic reads top-to-bottom, not outside-in.

Explore the Effect Path API →

The Bridge: Effects Meet Optics

What makes Higher-Kinded-J unique is the seamless integration between Effect Paths and the Focus DSL. Where Effect Paths navigate computational effects, Focus Paths navigate data structures. Both use the same vocabulary. Both compose with via. And when you need to cross between them, the bridge API connects both worlds.

                    THE EFFECT-OPTICS BRIDGE

  EFFECTS DOMAIN                           OPTICS DOMAIN
  ══════════════                           ═════════════

  EitherPath<E, User>  ────┐         ┌──── FocusPath<User, Address>
  TryPath<Config>      ────┤         ├──── AffinePath<User, Email>
  IOPath<Data>         ────┤         ├──── TraversalPath<Team, Player>
  ValidationPath<E, A> ────┘         └────
                            │       │
                            ▼       ▼
                       ┌─────────────────┐
                       │  .focus(path)   │
                       │  .toEitherPath  │
                       │  .toMaybePath   │
                       └─────────────────┘
                              │
                              ▼
                    UNIFIED COMPOSITION
                    ════════════════════

  userService.findById(id)        // Effect: fetch
      .focus(UserFocus.address()) // Optics: navigate
      .via(validateAddress)       // Effect: validate
      .focus(AddressFocus.city()) // Optics: extract
      .map(String::toUpperCase)   // Transform

// Fetch user (effect) → navigate to address (optics) →
// extract postcode (optics) → validate (effect)
EitherPath<Error, String> result =
    userService.findById(userId)           // EitherPath<Error, User>
        .focus(UserFocus.address())        // EitherPath<Error, Address>
        .focus(AddressFocus.postcode())    // EitherPath<Error, String>
        .via(code -> validatePostcode(code));

This is the unification that Java has been missing: effects and structure, composition and navigation, all speaking the same language.

Discover Focus-Effect Integration →

Two Foundations

The Effect Path API is built on two powerful functional programming pillars:

Higher-Kinded Types

Java lacks native support for abstracting over type constructors like Optional<A>, List<A>, or CompletableFuture<A>. Higher-Kinded-J simulates HKTs using defunctionalisation, unlocking:

• Polymorphic functions that work across optionality, asynchrony, and error handling
• Type classes like Functor, Applicative, and Monad with consistent interfaces
• Monad transformers for composing effect stacks (EitherT, StateT, ReaderT)

Advanced Optics

Higher-Kinded-J provides the most comprehensive optics implementation available for Java. Working with immutable records means verbose "copy-and-update" logic; the Optics library treats data access as first-class values:

• Complete optic hierarchy: Lenses, Prisms, Isos, Affines, Traversals, Folds, and Setters
• Automatic generation via annotation processor for Java records and sealed interfaces
• Filtered traversals for predicate-based focusing within collections
• Indexed optics for position-aware transformations
• Profunctor architecture enabling adaptation between different data shapes
• Focus DSL for type-safe, fluent path navigation
• Effect integration bridging optics with the Effect Path API

Why Higher-Kinded-J?

Higher-Kinded-J offers the most advanced optics implementation in the Java ecosystem, combined with a unified effect system that no other library provides.

^1^ Derive4J generates getters/setters but requires Functional Java for actual optic classes

Path Types at a Glance

Each Path wraps its underlying effect and provides map, via, run, recover, and integration with the Focus DSL.

Learn by Doing

The fastest way to master Higher-Kinded-J is through our interactive tutorial series. Eight journeys guide you through hands-on exercises with immediate test feedback.

Perfect for developers who prefer learning by building. Get started →

Spring Boot Integration

Building enterprise applications with Spring Boot? The hkj-spring-boot-starter brings functional programming patterns seamlessly into your REST APIs, eliminating exception-based error handling whilst maintaining Spring's familiar conventions.

With Spring Boot Integration, you can:

• Return Functional Types from Controllers: Use Either<Error, Data>, Validated<Errors, Data>, and CompletableFuturePath as return types with automatic HTTP response conversion.
• Eliminate Exception Handling Boilerplate: No more try-catch blocks or @ExceptionHandler methods; errors are explicit in your return types.
• Compose Operations Naturally: Chain operations with map and via whilst preserving type safety and error information.
• Accumulate Validation Errors: Use Validated to collect all validation errors in a single request, improving user experience.
• Handle Async Operations: Use CompletableFuturePath to compose asynchronous operations seamlessly.
• Monitor in Production: Track EitherPath success rates, ValidationPath error distributions, and CompletableFuturePath async performance with Spring Boot Actuator metrics.
• Secure Functionally: Integrate Spring Security with Either-based authentication and Validated-based authorisation logic.
• Zero Configuration Required: Auto-configuration handles everything; just add the dependency and start coding.

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public Either<DomainError, User> getUser(@PathVariable String id) {
        return userService.findById(id);
        // Right(user) → HTTP 200 with JSON
        // Left(UserNotFoundError) → HTTP 404 with error details
    }

    @PostMapping
    public Validated<List<ValidationError>, User> createUser(@RequestBody UserRequest request) {
        return userService.validateAndCreate(request);
        // Valid(user) → HTTP 200
        // Invalid(errors) → HTTP 400 with ALL validation errors
    }
}

Get Started with Spring Boot Integration →

Getting Started

Add the following dependencies to your build.gradle.kts:

dependencies {
    implementation("io.github.higher-kinded-j:hkj-core:LATEST_VERSION")
    annotationProcessor("io.github.higher-kinded-j:hkj-processor-plugins:LATEST_VERSION")
}

The annotation processor generates Focus paths and Effect paths for your records, enabling seamless integration between effects and data navigation.

For Spring Boot Integration:

dependencies {
    implementation("io.github.higher-kinded-j:hkj-spring-boot-starter:LATEST_VERSION")
}

For SNAPSHOTS:

repositories {
    mavenCentral()
    maven {
        url = uri("https://central.sonatype.com/repository/maven-snapshots/")
    }
}

Documentation Guide

Effect Path API (Start Here)

1. Effect Path Overview: The railway model, creating paths, core operations
2. Capability Interfaces: The powers that paths possess
3. Path Types: When to use each path type
4. Focus-Effect Integration: Bridging optics and effects

Optics Guides

1. Introduction to Optics: What optics are and the problems they solve
2. Practical Guide: Lenses: Nested immutable updates
3. Practical Guide: Prisms: Working with sum types
4. Focus DSL: Type-safe structural navigation
5. Profunctor Optics: Adapting optics to different data shapes

Foundations (Reference)

These sections document the underlying machinery. Most users can start with Effect Paths directly.

1. Higher-Kinded Types: The simulation and why it matters
2. Type Classes: Functor, Monad, and other type classes
3. Core Types: Either, Maybe, Try, and other effect types
4. Order Example Walkthrough: A complete workflow with monad transformers

History

Higher-Kinded-J evolved from a simulation originally created for the blog post Higher Kinded Types with Java and Scala. Since then it has grown into a comprehensive functional programming toolkit, with the Effect Path API providing the unifying layer that connects HKTs, type classes, and optics into a coherent whole.

Effect Path API: Navigating Computational Territory

"A map is not the territory it represents, but, if correct, it has a similar structure to the territory, which accounts for its usefulness."

— Alfred Korzybski, Science and Sanity

Every Java application navigates territory that doesn't appear on any class diagram: the landscape of what might go wrong. A database connection that refuses to connect. A user ID that points to nobody. A file that was there yesterday. A validation rule that nobody told you about.

Traditional Java handles this territory with a patchwork of approaches: nulls here, exceptions there, Optional when someone remembered, raw booleans when they didn't. Each approach speaks a different dialect. None compose cleanly with the others.

The Effect Path API provides a unified map for this territory.

Rather than learning separate idioms for absence (Optional), failure (try-catch), typed errors (Either), and deferred effects (CompletableFuture), you work with Path types: thin, composable wrappers that share a common vocabulary. The same map, via, and recover operations work regardless of what kind of effect you're handling. The underlying complexity remains (it must), but the Path contains it.

If you've used the Focus DSL from the optics chapters, the patterns will feel familiar. Where FocusPath navigates through data structures, EffectPath navigates through computational effects. Both use via for composition. Both provide fluent, chainable operations. The territory differs; the cartography rhymes. And when you need to cross between territories—extracting structured data into effect pipelines, or drilling into effect results with optics—the bridge API connects both worlds seamlessly.

Chapter Contents

1. Effect Path Overview - The problem, the model, the first steps
2. Capability Interfaces - The interface hierarchy powering composition
3. Path Types - Detailed coverage of each Path type
4. Composition Patterns - Chaining, combining, parallel execution, and debugging
5. Type Conversions - Moving between different Path types
6. Focus-Effect Integration - Bridging optics and effects
7. Patterns and Recipes - Real-world patterns, resilience, and hard-won wisdom
8. Advanced Effects - Reader, State, and Writer patterns
9. Advanced Topics - Stack-safety, DSLs, resources, parallelism, resilience

Next: Effect Path Overview

Effect Path Overview

"There is no real direction here, neither lines of power nor cooperation. Decisions are never really made; at best they manage to emerge, from a chaos of peeves, whims, hallucinations and all-round assholery."

— Thomas Pynchon, Gravity's Rainbow

Pynchon was describing wartime bureaucracy, but he might as well have been reading a poorly implemented service layer on a Monday morning.

The Pyramid of Doom

You've seen this shape before. You may have even written it, promising yourself to refactor it later:

public OrderResult processOrder(String userId, OrderRequest request) {
    User user = userRepository.findById(userId);
    if (user == null) {
        return OrderResult.error("User not found");
    }

    try {
        ValidationResult validation = validator.validate(request);
        if (!validation.isValid()) {
            return OrderResult.error(validation.getErrors().get(0));
        }

        InventoryCheck inventory = inventoryService.check(request.getItems());
        if (!inventory.isAvailable()) {
            return OrderResult.error("Items unavailable");
        }

        try {
            PaymentResult payment = paymentService.charge(user, inventory.getTotal());
            if (payment.isFailed()) {
                return OrderResult.error(payment.getFailureReason());
            }

            return OrderResult.success(createOrder(user, request, payment));
        } catch (PaymentException e) {
            return OrderResult.error("Payment failed: " + e.getMessage());
        }
    } catch (ValidationException e) {
        return OrderResult.error("Validation error: " + e.getMessage());
    }
}

Five levels of nesting. Three different error-handling idioms. The actual business logic, create an order, buried at the bottom like a punchline nobody can find. And this is a simple example. I've witnessed far worse in Production.

The problem isn't any single technique. Null checks are sometimes appropriate. Exceptions have their place. The problem is that they don't compose. Each approach speaks its own dialect, demands its own syntax, follows its own rules for propagating failure. String enough of them together, and you get Pynchon's chaos: decisions that don't so much get made as reluctantly emerge.

The Railway Model

Functional programmers solved this problem decades ago with a simple model: the railway.

                         THE EFFECT RAILWAY

    Success ═══●═══●═══●═══●═══●═══════════════════▶  Result
               │   │   │   │   │
              map via map via run
                   │       │
                   ╳       │         error occurs, switch tracks
                   │       │
    Failure  ──────●───────┼───────────────────────▶  Error
                   │       │
                mapError  recover
                           │
                           ╳                         recovery, switch back

Your data travels along the success track. Operations like map and via transform it as it goes. If something fails, the data switches to the failure track and subsequent operations are skipped, no explicit checks required, no nested conditionals. Recovery operations (recover, recoverWith) can switch the data back to the success track if you have a sensible fallback.

This is what Path types implement. The railway is the model; Paths are the rolling stock.

The Same Logic, Flattened

Here's that order processing code rewritten with Effect Paths:

public EitherPath<OrderError, Order> processOrder(String userId, OrderRequest request) {
    return Path.maybe(userRepository.findById(userId))
        .toEitherPath(() -> new OrderError.UserNotFound(userId))
        .via(user -> Path.either(validator.validate(request))
            .mapError(OrderError.ValidationFailed::new))
        .via(validated -> Path.either(inventoryService.check(request.getItems()))
            .mapError(OrderError.InventoryError::new))
        .via(inventory -> Path.tryOf(() -> paymentService.charge(user, inventory.getTotal()))
            .toEitherPath(OrderError.PaymentFailed::new))
        .via(payment -> Path.right(createOrder(user, request, payment)));
}

The nesting has gone. Each step follows the same pattern: transform or chain, handle errors consistently, let failures propagate automatically. The business logic reads top-to-bottom instead of outside-in.

This isn't magic. The underlying complexity hasn't vanished; you still need to handle the same failure cases. But the accidental complexity (the pyramids, the repeated null checks, the catch blocks that just wrap and rethrow) are gone. What remains is the essential shape of your logic.

Path Types at a Glance

Each Path type wraps its underlying effect and provides:

• map(f) - Transform the success value
• via(f) - Chain to another Path (monadic bind)
• run() - Extract the underlying effect
• Type-specific operations for recovery, error transformation, and more

Creating Paths

The Path class provides factory methods for all Path types. A small sampler:

// MaybePath: optional values
MaybePath<String> greeting = Path.just("Hello");
MaybePath<String> empty = Path.nothing();
MaybePath<User> user = Path.maybe(repository.findById(id));

// EitherPath: typed errors
EitherPath<String, Integer> success = Path.right(42);
EitherPath<String, Integer> failure = Path.left("Something went wrong");

// TryPath: exception handling
TryPath<Config> config = Path.tryOf(() -> loadConfig());

// IOPath: deferred side effects
IOPath<String> readFile = Path.io(() -> Files.readString(path));

Transforming with map

All Path types support map for transforming the success value:

MaybePath<String> greeting = Path.just("hello");
MaybePath<String> upper = greeting.map(String::toUpperCase);
// → Just("HELLO")

MaybePath<String> empty = Path.nothing();
MaybePath<String> stillEmpty = empty.map(String::toUpperCase);
// → Nothing (map doesn't run on empty paths)

The function inside map only executes if the Path is on the success track. Failures pass through unchanged. No defensive checks required.

Chaining with via

The via method chains computations where each step depends on the previous result:

EitherPath<Error, Invoice> invoice =
    Path.either(findUser(userId))
        .via(user -> Path.either(getCart(user)))
        .via(cart -> Path.either(calculateTotal(cart)))
        .via(total -> Path.either(createInvoice(total)));

Each via receives the success value and returns a new Path. If any step fails, subsequent steps are skipped; the failure propagates to the end.

The name via mirrors the Focus DSL from the optics chapters. Where FocusPath uses via to navigate through lenses, EffectPath uses via to navigate through effects. Different territory, same verb.

Extracting Results

Eventually you need to leave the railway and extract a result:

// MaybePath
Maybe<String> maybe = path.run();
String value = path.getOrElse("default");
String value = path.getOrThrow(() -> new NoSuchElementException());

// EitherPath
Either<Error, User> either = path.run();
String result = either.fold(
    error -> "Failed: " + error,
    user -> "Found: " + user.name()
);

// IOPath: actually runs the effect
String content = ioPath.unsafeRun();      // may throw
Try<String> safe = ioPath.runSafe();      // captures exceptions

Debugging with peek

When a pipeline misbehaves, peek lets you observe values mid-flow without disrupting the computation:

EitherPath<Error, User> result =
    Path.either(validateInput(input))
        .peek(valid -> log.debug("Input validated: {}", valid))
        .via(valid -> Path.either(createUser(valid)))
        .peek(user -> log.info("User created: {}", user.getId()));

For failure paths, peek only executes on success. Failures pass through silently, which is usually what you want when debugging the happy path.

Structural Navigation with focus

Effect paths integrate with the Focus DSL, enabling structural navigation within effect contexts. Where map transforms values and via chains effects, focus drills into nested structures using optics.

                         FOCUS WITHIN EFFECTS

    EitherPath<Error, User>
            │
            │  focus(namePath)         ← optic navigation
            ▼
    EitherPath<Error, String>
            │
            │  map(String::toUpperCase)  ← value transformation
            ▼
    EitherPath<Error, String>
            │
            │  via(validateName)         ← effect chaining
            ▼
    EitherPath<Error, ValidName>

Basic Usage

// Given a FocusPath from the optics domain
FocusPath<User, String> namePath = UserFocus.name();

// Apply within an effect
EitherPath<Error, User> userResult = fetchUser(userId);
EitherPath<Error, String> nameResult = userResult.focus(namePath);

The focus preserves the effect's semantics: if userResult is Left, nameResult is also Left. Only Right values are navigated.

Handling Optional Focus

When using AffinePath (for optional fields), provide an error for the absent case:

// AffinePath for Optional<String> email
AffinePath<User, String> emailPath = UserFocus.email();

// Must provide error if email is absent
EitherPath<Error, String> emailResult =
    userResult.focus(emailPath, new Error("Email not configured"));

Effect-Specific Behaviour

Each effect type handles absent focuses differently:

Chaining Focus with Effects

Focus composes naturally with other path operations:

// Complex pipeline: fetch → navigate → validate → transform
EitherPath<Error, String> result =
    fetchUser(userId)                              // → EitherPath<Error, User>
        .focus(UserFocus.address())                // → EitherPath<Error, Address>
        .focus(AddressFocus.postcode(), noPostcodeError)  // → EitherPath<Error, String>
        .via(code -> validatePostcode(code))       // → EitherPath<Error, ValidPostcode>
        .map(ValidPostcode::formatted);            // → EitherPath<Error, String>

When to Use focus vs via

// focus: structural navigation (optics)
path.focus(UserFocus.name())

// via: effect sequencing (monadic bind)
path.via(user -> validateUser(user))

// map: value transformation (functor)
path.map(name -> name.toUpperCase())

Summary

Continue to Capability Interfaces to understand the powers that make this possible.

Previous: Introduction Next: Capability Interfaces

Capability Interfaces

"Caress the detail, the divine detail."

— Vladimir Nabokov

Nabokov was speaking of prose, but the principle applies to API design. The Effect Path API doesn't give every Path type every operation. Instead, it builds a hierarchy of capabilities, interfaces that add specific powers to types that genuinely possess them. A MaybePath can recover from absence; an IdPath cannot fail in the first place, so recovery would be meaningless. The type system prevents you from reaching for tools that don't apply.

This isn't bureaucratic fastidiousness. It's how the library stays honest about what each type can do.

The Hierarchy

┌──────────────────────────────────────────────────────────────────────────────┐
│                     CAPABILITY HIERARCHY                                     │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│                          ┌────────────────┐                                  │
│                          │   Composable   │  map(), peek()                   │
│                          │   (Functor)    │  "I can transform what's inside" │
│                          └───────┬────────┘                                  │
│                                  │                                           │
│                          ┌───────┴────────┐                                  │
│                          │   Combinable   │  zipWith(), map2()               │
│                          │ (Applicative)  │  "I can merge independent work"  │
│                          └───────┬────────┘                                  │
│                                  │                                           │
│                          ┌───────┴────────┐                                  │
│                          │   Chainable    │  via(), flatMap(), then()        │
│                          │    (Monad)     │  "I can sequence dependent work" │
│                          └───────┬────────┘                                  │
│                                  │                                           │
│      ┌───────────────────────────┼───────────────────────────┐               │
│      │                           │                           │               │
│ ┌────┴───────┐           ┌───────┴────────┐          ┌───────┴────────┐      │
│ │ Recoverable│           │   Effectful    │          │  Accumulating  │      │
│ │(MonadError)│           │     (IO)       │          │  (Validated)   │      │
│ │            │           │                │          │                │      │
│ │ "I can     │           │ "I defer until │          │ "I collect all │      │
│ │  handle    │           │  you're ready" │          │  the problems" │      │
│ │  failure"  │           │                │          │                │      │
│ └────────────┘           └────────────────┘          └────────────────┘      │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

Each level builds on the previous. A Chainable type can do everything a Combinable can do, plus sequential chaining. The three leaf capabilities, Recoverable, Effectful, and Accumulating, represent specialised powers that only some types possess.

This isn't arbitrary taxonomy. It's how you avoid calling recover() on a type that never fails, or unsafeRun() on a type that doesn't defer execution. The compiler catches category errors before they become runtime surprises.

Composable (Functor)

What it means: You can transform the value inside without changing the surrounding structure.

The analogy: A translator. The message changes; the envelope stays sealed.

public interface Composable<A> {
    <B> Composable<B> map(Function<? super A, ? extends B> f);
    Composable<A> peek(Consumer<? super A> action);
}

Every Path type is Composable. It's the minimum viable capability.

MaybePath<String> name = Path.just("alice");
MaybePath<Integer> length = name.map(String::length);  // Just(5)

MaybePath<String> empty = Path.nothing();
MaybePath<Integer> stillEmpty = empty.map(String::length);  // Nothing

The function passed to map only runs if there's a value to transform. Failures, absences, and pending effects pass through unchanged. This is why you don't need defensive null checks inside map; the structure handles it.

The Functor Laws

All Path types satisfy these laws, which is what makes composition predictable:

1. Identity: path.map(x -> x) equals path
2. Composition: path.map(f).map(g) equals path.map(f.andThen(g))

The first law says mapping with the identity function changes nothing. The second says you can fuse consecutive maps into one. These aren't aspirational guidelines; they're guarantees the implementation must honour.

Combinable (Applicative)

What it means: You can merge the results of independent computations.

The analogy: A meeting coordinator. Everyone works separately, then results are combined at the end. If someone fails to deliver, there's nothing to combine.

public interface Combinable<A> extends Composable<A> {
    <B, C> Combinable<C> zipWith(
        Combinable<B> other,
        BiFunction<? super A, ? super B, ? extends C> f
    );

    <B, C, D> Combinable<D> zipWith3(
        Combinable<B> second,
        Combinable<C> third,
        TriFunction<? super A, ? super B, ? super C, ? extends D> f
    );
}

The key property is independence. Neither computation depends on the other's result:

// These validations don't affect each other
EitherPath<String, String> name = validateName(input.name());
EitherPath<String, String> email = validateEmail(input.email());
EitherPath<String, Integer> age = validateAge(input.age());

// Combine all three
EitherPath<String, User> user = name.zipWith3(email, age, User::new);

If all three succeed, User::new receives the three values. If any fails, the first failure propagates. (For collecting all failures, you need Accumulating; patience.)

zipWith vs via

A common source of confusion, worth addressing directly:

If you're validating a form, the fields are independent: use zipWith. If you're fetching a user then loading their preferences, the second needs the first: use via.

Chainable (Monad)

What it means: You can sequence computations where each step depends on the previous result.

The analogy: A relay race. Each runner receives the baton from the previous and decides what to do next. If someone drops the baton, the race ends there.

public interface Chainable<A> extends Combinable<A> {
    <B> Chainable<B> via(Function<? super A, ? extends Chainable<B>> f);
    <B> Chainable<B> flatMap(Function<? super A, ? extends Chainable<B>> f);
    <B> Chainable<B> then(Supplier<? extends Chainable<B>> next);
}

The via method is the workhorse:

EitherPath<Error, Invoice> invoice =
    Path.either(findUser(userId))
        .via(user -> Path.either(getCart(user)))      // needs user
        .via(cart -> Path.either(calculateTotal(cart))) // needs cart
        .via(total -> Path.either(createInvoice(total))); // needs total

Each step receives the previous result and returns a new Path. The railway metaphor applies: success continues forward, failure short-circuits to the end.

flatMap is an alias for via, the same operation with the traditional name. Use whichever reads better in context.

then is for sequencing when you don't need the previous value:

IOPath<Unit> workflow =
    Path.io(() -> log.info("Starting"))
        .then(() -> Path.io(() -> initialise()))
        .then(() -> Path.io(() -> process()));

The Monad Laws

1. Left Identity: Path.just(a).via(f) equals f.apply(a)
2. Right Identity: path.via(Path::just) equals path
3. Associativity: path.via(f).via(g) equals path.via(x -> f.apply(x).via(g))

These ensure that chaining behaves predictably regardless of how you group operations. Refactoring a chain into helper methods won't change its behaviour.

Recoverable (MonadError)

What it means: You can handle failures and potentially continue on the success track.

The analogy: A safety net. If you fall, something catches you. You might climb back up, or you might stay down, but the fall doesn't have to be fatal.

public interface Recoverable<E, A> extends Chainable<A> {
    Recoverable<E, A> recover(Function<? super E, ? extends A> handler);
    Recoverable<E, A> recoverWith(
        Function<? super E, ? extends Recoverable<E, A>> handler
    );
    Recoverable<E, A> orElse(Supplier<? extends Recoverable<E, A>> alternative);
    <F> Recoverable<F, A> mapError(Function<? super E, ? extends F> f);
}

Different Path types have different notions of "error":

// MaybePath: "error" is absence
MaybePath<User> user = Path.maybe(findUser(id))
    .orElse(() -> Path.just(User.guest()));

// EitherPath: "error" is a typed value
EitherPath<Error, Config> config = Path.either(loadConfig())
    .recover(error -> Config.defaults())
    .mapError(e -> new ConfigError("Load failed", e));

// TryPath: "error" is an exception
TryPath<Integer> parsed = Path.tryOf(() -> Integer.parseInt(input))
    .recover(ex -> 0);

Recoverable is perhaps the most frequently used capability after Chainable, which tells you something about the general state of affairs in software.

Effectful (IO)

What it means: The computation is deferred until you explicitly run it.

The analogy: A written contract. It describes what will happen, but nothing happens until someone signs and executes it.

public interface Effectful<A> extends Chainable<A> {
    A unsafeRun();
    Try<A> runSafe();
    Effectful<A> handleError(Function<? super Throwable, ? extends A> handler);
    Effectful<A> handleErrorWith(
        Function<? super Throwable, ? extends Effectful<A>> handler
    );
    Effectful<A> ensuring(Runnable cleanup);
}

Only IOPath implements Effectful. All other Path types evaluate immediately when you call map or via. With IOPath, nothing happens until you call unsafeRun() or runSafe():

IOPath<String> readFile = Path.io(() -> {
    System.out.println("Reading file...");  // Not printed yet
    return Files.readString(path);
});

// Still nothing happens
IOPath<Integer> lineCount = readFile.map(s -> s.split("\n").length);

// NOW it executes
Integer count = lineCount.unsafeRun();  // "Reading file..." printed

The ensuring method guarantees cleanup runs regardless of success or failure:

IOPath<Data> withCleanup = Path.io(() -> acquireResource())
    .via(resource -> Path.io(() -> useResource(resource)))
    .ensuring(() -> releaseResource());

The name unsafeRun is deliberate. It's a warning: side effects are about to happen, referential transparency ends here. Call it at the edge of your system, not scattered throughout.

Accumulating (Validated)

What it means: You can combine independent computations while collecting all errors, not just the first.

The analogy: A code review. The reviewer notes every problem, then hands back the full list. They don't stop at the first issue and declare the review complete.

public interface Accumulating<E, A> extends Composable<A> {
    <B, C> Accumulating<E, C> zipWithAccum(
        Accumulating<E, B> other,
        BiFunction<? super A, ? super B, ? extends C> combiner
    );

    Accumulating<E, A> andAlso(Accumulating<E, ?> other);
}

Only ValidationPath implements Accumulating. The key difference from Combinable.zipWith:

ValidationPath<List<String>, String> name = validateName(input);
ValidationPath<List<String>, String> email = validateEmail(input);
ValidationPath<List<String>, Integer> age = validateAge(input);

// Accumulate ALL errors
ValidationPath<List<String>, User> user = name.zipWith3Accum(
    email,
    age,
    User::new
);

// If name and email both fail: Invalid(["Name too short", "Invalid email"])
// Not just: Invalid(["Name too short"])

Error accumulation requires a Semigroup to define how errors combine. For List<String>, errors concatenate. For String, they might join with ;. The Semigroup is provided when creating the ValidationPath.

Use Accumulating for user-facing validation where showing all problems at once is kinder than making users fix them one by one.

Which Capabilities Each Path Type Has

* GenericPath recovery depends on the underlying monad.

Note that IdPath lacks Recoverable; it cannot fail, so recovery is meaningless. IOPath lacks Recoverable but has Effectful, which includes its own error handling via handleError. These aren't omissions; they're the type system being honest about what makes sense.

Summary

The hierarchy is designed so you can write code at the appropriate level of abstraction. If map suffices, use map. Reach for via only when you need sequencing. The capabilities tell you what's available; the types ensure you don't ask for more than a Path can deliver.

Continue to Path Types for detailed coverage of each type.

Previous: Effect Path Overview Next: Path Types

Path Types

"It is not down on any map; true places never are."

— Herman Melville, Moby-Dick

Melville was speaking of Queequeg's island home, but the observation applies to software: the territory you're navigating (nullable returns, network failures, validation errors, deferred effects) isn't marked on any class diagram. You need to choose your vessel before setting sail.

This chapter covers each Path type in detail. But before cataloguing the fleet, a more pressing question: which one do you need?

Choosing Your Path

Before diving into specifics, orient yourself by the problem you're solving:

"The value might not exist"

You're dealing with absence: a lookup that returns nothing, an optional configuration, a field that might be null.

Reach for MaybePath if absence is normal and expected, not an error condition. Nobody needs to know why the value is missing.

Reach for OptionalPath if you're bridging to Java's Optional ecosystem and want to stay close to the standard library.

"The operation might fail, and I need to know why"

Something can go wrong, and the error carries information: a validation message, a typed error code, a domain-specific failure.

Reach for EitherPath when you control the error type and want typed, structured errors.

Reach for TryPath when you're wrapping code that throws exceptions and want to stay in exception-land (with Throwable as the error type).

"I need ALL the errors, not just the first"

Multiple independent validations, and stopping at the first failure would be unkind to your users.

Reach for ValidationPath with zipWithAccum to accumulate every error.

"The operation has side effects I want to defer"

You're reading files, calling APIs, writing to databases, effects that shouldn't happen until you're ready.

Reach for IOPath to describe the effect without executing it. Nothing runs until you call unsafeRun().

"I need stack-safe recursion"

Deep recursive algorithms that would blow the stack with direct recursion.

Reach for TrampolinePath for guaranteed stack safety regardless of depth.

"I want to build an interpretable DSL"

Separate description from execution, test with mock interpreters, or support multiple interpretation strategies.

Reach for FreePath for sequential DSLs or FreeApPath for parallel/static-analysis-friendly DSLs.

"The operation always succeeds"

No failure case, no absence; you just want Path operations on a pure value.

Reach for IdPath when you need a trivial Path for generic code or testing.

"None of the above"

You have a custom monad, or you're writing highly generic code.

Reach for GenericPath as the escape hatch; it wraps any Kind<F, A> with a Monad instance.

Quick Reference

Path Types by Category

Value Containers (Immediate Evaluation)

These types wrap values and evaluate operations immediately:

• MaybePath - For values that might be absent
• OptionalPath - Bridge to Java's Optional
• IdPath - Always contains a value (identity)

Error Handling (Immediate Evaluation)

These types handle failures with different strategies:

• EitherPath - Typed errors, short-circuit on first failure
• TryPath - Exception-based errors
• ValidationPath - Accumulate all errors

Deferred Computation

These types describe computations without executing them:

• IOPath - Side effects, runs when you call unsafeRun()
• TrampolinePath - Stack-safe recursion

DSL Building

These types support building domain-specific languages:

• FreePath - Sequential, monadic DSLs
• FreeApPath - Parallel, applicative DSLs

Universal

• GenericPath - Works with any monad

Summary: Choosing Your Vessel

The choice isn't always obvious, and that's fine. You can convert between types as your needs evolve (MaybePath to EitherPath when you need error messages, TryPath to EitherPath when you want typed errors). The Type Conversions chapter covers these conversions in detail.

Previous: Capability Interfaces Next: MaybePath

MaybePath

MaybePath<A> wraps Maybe<A> for computations that might produce nothing. It's the simplest failure mode: either you have a value, or you don't.

Creation

// From a value
MaybePath<String> greeting = Path.just("hello");

// Absence
MaybePath<String> nothing = Path.nothing();

// From existing Maybe
MaybePath<User> user = Path.maybe(repository.findById(id));

// From nullable (null becomes Nothing)
MaybePath<String> fromNullable = Path.fromNullable(possiblyNull);

Core Operations

MaybePath<String> name = Path.just("Alice");

// Transform
MaybePath<Integer> length = name.map(String::length);  // Just(5)

// Chain
MaybePath<String> upper = name.via(s -> Path.just(s.toUpperCase()));

// Combine independent values
MaybePath<Integer> age = Path.just(25);
MaybePath<String> summary = name.zipWith(age, (n, a) -> n + " is " + a);
// Just("Alice is 25")

Recovery

MaybePath<User> user = Path.maybe(findUser(id))
    .orElse(() -> Path.just(User.guest()));

// Filter (returns Nothing if predicate fails)
MaybePath<Integer> positive = Path.just(42).filter(n -> n > 0);  // Just(42)
MaybePath<Integer> rejected = Path.just(-1).filter(n -> n > 0);  // Nothing

Extraction

MaybePath<String> path = Path.just("hello");

Maybe<String> maybe = path.run();
String value = path.getOrElse("default");
String value = path.getOrThrow(() -> new NoSuchElementException());

When to Use

MaybePath is right when:

• Absence is normal, not exceptional
• You don't need to explain why the value is missing
• You're modelling optional data (configuration, nullable fields, lookups)

MaybePath is wrong when:

• Callers need to know the reason for failure → use EitherPath
• You're wrapping code that throws → use TryPath

Previous: Path Types Overview Next: EitherPath

EitherPath

EitherPath<E, A> wraps Either<E, A> for computations with typed errors. The left side carries failure; the right side carries success. (Right is right, as the mnemonic goes.)

Creation

// Success
EitherPath<Error, Integer> success = Path.right(42);

// Failure
EitherPath<Error, Integer> failure = Path.left(new ValidationError("invalid"));

// From existing Either
EitherPath<Error, User> user = Path.either(validateUser(input));

Core Operations

EitherPath<String, Integer> number = Path.right(42);

// Transform success
EitherPath<String, String> formatted = number.map(n -> "Value: " + n);

// Chain
EitherPath<String, Integer> doubled = number.via(n ->
    n > 0 ? Path.right(n * 2) : Path.left("Must be positive"));

// Combine independent values
EitherPath<String, String> name = Path.right("Alice");
EitherPath<String, Integer> age = Path.right(25);
EitherPath<String, Person> person = name.zipWith(age, Person::new);

Error Handling

EitherPath<String, Config> config = Path.either(loadConfig())
    // Provide fallback value
    .recover(error -> Config.defaults())

    // Transform error type
    .mapError(e -> new ConfigError(e))

    // Recover with another computation
    .recoverWith(error -> Path.either(loadBackupConfig()))

    // Provide alternative path
    .orElse(() -> Path.right(Config.defaults()));

Bifunctor Operations

Transform both sides simultaneously:

EitherPath<String, Integer> original = Path.right(42);

EitherPath<Integer, String> transformed = original.bimap(
    String::length,      // Transform error
    n -> "Value: " + n   // Transform success
);

Extraction

EitherPath<String, Integer> path = Path.right(42);
Either<String, Integer> either = path.run();

// Pattern match
String result = either.fold(
    error -> "Error: " + error,
    value -> "Value: " + value
);

// Direct access (throws if wrong side)
if (either.isRight()) {
    Integer value = either.getRight();
}

When to Use

EitherPath is right when:

• Errors carry meaningful, typed information
• Different errors need different handling
• You're building validation pipelines (with short-circuit semantics)
• You want to transform errors as they propagate

EitherPath is wrong when:

• You need to collect all errors → use ValidationPath
• Absence isn't really an error → use MaybePath

Previous: MaybePath Next: TryPath

TryPath

TryPath<A> wraps Try<A> for computations that might throw exceptions. It bridges the gap between Java's exception-based world and functional composition.

Creation

// Successful value
TryPath<Integer> success = Path.success(42);

// Failed value
TryPath<Integer> failure = Path.failure(new RuntimeException("oops"));

// From computation that may throw
TryPath<Integer> parsed = Path.tryOf(() -> Integer.parseInt(input));

// From existing Try
TryPath<Config> config = Path.tryPath(loadConfigTry());

Core Operations

TryPath<String> content = Path.tryOf(() -> Files.readString(path));

// Transform
TryPath<Integer> lineCount = content.map(s -> s.split("\n").length);

// Chain
TryPath<Data> data = content.via(c -> Path.tryOf(() -> parseJson(c)));

// Combine
TryPath<String> file1 = Path.tryOf(() -> readFile("a.txt"));
TryPath<String> file2 = Path.tryOf(() -> readFile("b.txt"));
TryPath<String> combined = file1.zipWith(file2, (a, b) -> a + "\n" + b);

Error Handling

TryPath<Integer> parsed = Path.tryOf(() -> Integer.parseInt(input))
    // Recover with value
    .recover(ex -> 0)

    // Recover based on exception type
    .recoverWith(ex -> {
        if (ex instanceof NumberFormatException) {
            return Path.success(-1);
        }
        return Path.failure(ex);
    })

    // Alternative
    .orElse(() -> Path.success(defaultValue));

Extraction

TryPath<Integer> path = Path.success(42);
Try<Integer> tryValue = path.run();

Integer value = path.getOrElse(-1);

if (tryValue.isSuccess()) {
    System.out.println("Value: " + tryValue.get());
} else {
    System.out.println("Error: " + tryValue.getCause().getMessage());
}

When to Use

TryPath is right when:

• You're wrapping APIs that throw exceptions
• The specific exception type matters for recovery
• You want exception-safe composition without try-catch blocks
• Interoperating with legacy code

TryPath is wrong when:

• You want typed errors (not just Throwable) → use EitherPath
• The code doesn't throw → use MaybePath or EitherPath

Previous: EitherPath Next: IOPath

IOPath

IOPath<A> wraps IO<A> for deferred side-effectful computations. Unlike other Path types, nothing happens until you explicitly run it.

"Buy the ticket, take the ride... and if it occasionally gets a little heavier than what you had in mind, well... maybe chalk it up to forced consciousness expansion."

— Hunter S. Thompson, Fear and Loathing in Las Vegas

Thompson's advice applies here. When you call unsafeRun(), you've bought the ticket. The effects will happen. There's no going back. Until that moment, an IOPath is just a description—a plan you haven't committed to yet.

Creation

// Pure value (no effects)
IOPath<Integer> pure = Path.ioPure(42);

// Deferred effect
IOPath<String> readFile = Path.io(() -> Files.readString(Paths.get("data.txt")));

// From existing IO
IOPath<Connection> conn = Path.ioPath(databaseIO);

Core Operations (All Deferred)

IOPath<String> content = Path.io(() -> fetchFromApi(url));

// Transform (deferred)
IOPath<Data> data = content.map(this::parse);

// Chain (deferred)
IOPath<Result> result = content.via(c -> Path.io(() -> process(c)));

// Combine (deferred)
IOPath<String> header = Path.io(() -> readHeader());
IOPath<String> body = Path.io(() -> readBody());
IOPath<String> combined = header.zipWith(body, (h, b) -> h + "\n" + b);

// Sequence (discarding first result)
IOPath<Unit> setup = Path.ioRunnable(() -> log("Starting..."));
IOPath<Data> withSetup = setup.then(() -> Path.io(() -> loadData()));

Execution: Buying the Ticket

IOPath<String> io = Path.io(() -> fetchData());

// Execute (may throw)
String result = io.unsafeRun();

// Execute safely (captures exceptions)
Try<String> result = io.runSafe();

// Convert to TryPath (executes immediately)
TryPath<String> tryPath = io.toTryPath();

The naming is deliberate. unsafeRun warns you: referential transparency ends here. Side effects are about to happen. Call it at the boundaries of your system (in your main method, your HTTP handler, your message consumer), not scattered throughout your business logic.

Error Handling

IOPath<Config> config = Path.io(() -> loadConfig())
    // Handle any exception
    .handleError(ex -> Config.defaults())

    // Handle with another effect
    .handleErrorWith(ex -> Path.io(() -> loadBackupConfig()))

    // Ensure cleanup runs regardless of outcome
    .guarantee(() -> releaseResources());

Resource Management

bracket

The bracket pattern ensures resources are properly released:

IOPath<String> content = IOPath.bracket(
    () -> Files.newInputStream(path),      // acquire
    in -> new String(in.readAllBytes()),   // use
    in -> in.close()                       // release (always runs)
);

withResource

For AutoCloseable resources:

IOPath<String> content = IOPath.withResource(
    () -> Files.newBufferedReader(path),
    reader -> reader.lines().collect(Collectors.joining("\n"))
);
// reader.close() is called automatically

Parallel Execution

IOPath<String> fetchA = Path.io(() -> callServiceA());
IOPath<String> fetchB = Path.io(() -> callServiceB());

// Run in parallel, combine results
IOPath<String> combined = fetchA.parZipWith(fetchB, (a, b) -> a + b);

// Race: first to complete wins
IOPath<String> fastest = fetchA.race(fetchB);

// Run many in parallel
List<IOPath<String>> ios = List.of(io1, io2, io3);
IOPath<List<String>> all = PathOps.parSequenceIO(ios);

Retry with Resilience

IOPath<String> resilient = Path.io(() -> callFlakyService())
    .retry(5, Duration.ofMillis(100))  // exponential backoff
    .withRetry(RetryPolicy.fixed(3, Duration.ofMillis(50)));

See Patterns and Recipes for more resilience patterns.

Lazy Evaluation in Action

IOPath<String> effect = Path.io(() -> {
    System.out.println("Side effect!");  // Not printed yet
    return "result";
});

// Still nothing
IOPath<Integer> transformed = effect.map(String::length);

// NOW it runs
Integer length = transformed.unsafeRun();  // Prints "Side effect!"

When to Use

IOPath is right when:

• You're performing side effects (file I/O, network, database)
• You want lazy evaluation: describe now, execute later
• You want referential transparency throughout your core logic
• You need to compose complex effect pipelines before committing

IOPath is wrong when:

• You want immediate execution → use TryPath
• There are no side effects → use EitherPath or MaybePath

Previous: TryPath Next: ValidationPath

ValidationPath

ValidationPath<E, A> wraps Validated<E, A> for computations that accumulate errors instead of short-circuiting on the first failure.

Creation

// Valid value
ValidationPath<List<String>, Integer> valid =
    Path.valid(42, Semigroups.list());

// Invalid value with errors
ValidationPath<List<String>, Integer> invalid =
    Path.invalid(List.of("Error 1", "Error 2"), Semigroups.list());

// From existing Validated
ValidationPath<String, User> user =
    Path.validation(validatedUser, Semigroups.first());

The Semigroup<E> parameter defines how errors combine when multiple validations fail. Common choices:

• Semigroups.list() - concatenate error lists
• Semigroups.string("; ") - join strings with separator

Core Operations

ValidationPath<List<String>, String> name =
    Path.valid("Alice", Semigroups.list());

// Transform (same as other paths)
ValidationPath<List<String>, Integer> length = name.map(String::length);

// Chain with via (short-circuits on first error)
ValidationPath<List<String>, String> upper =
    name.via(s -> Path.valid(s.toUpperCase(), Semigroups.list()));

Error Accumulation: The Point of It All

The key operation is zipWithAccum, which collects all errors:

ValidationPath<List<String>, String> nameV = validateName(input.name());
ValidationPath<List<String>, String> emailV = validateEmail(input.email());
ValidationPath<List<String>, Integer> ageV = validateAge(input.age());

// Accumulate ALL errors (does not short-circuit)
ValidationPath<List<String>, User> userV = nameV.zipWith3Accum(
    emailV,
    ageV,
    User::new
);

// If name and email both fail:
// Invalid(["Name too short", "Invalid email format"])
// NOT just Invalid(["Name too short"])

Compare with zipWith, which short-circuits:

// Short-circuits: only first error returned
ValidationPath<List<String>, User> shortCircuit =
    nameV.zipWith(emailV, ageV, User::new);

Combining Validations

// andAlso runs both, accumulating errors, keeping first value if both valid
ValidationPath<List<String>, String> thorough =
    checkNotEmpty(name)
        .andAlso(checkMaxLength(name, 100))
        .andAlso(checkNoSpecialChars(name));
// All three checks run; all errors collected

Extraction

ValidationPath<List<String>, User> path = validateUser(input);
Validated<List<String>, User> validated = path.run();

String result = validated.fold(
    errors -> "Errors: " + String.join(", ", errors),
    user -> "Valid user: " + user.name()
);

When to Use

ValidationPath is right when:

• You want users to see all validation errors at once
• Multiple independent checks must all run
• Form validation, batch processing, comprehensive error reports
• Being kind to users matters (it does)

ValidationPath is wrong when:

• You only need the first error → use EitherPath
• Subsequent validations depend on earlier ones passing → use EitherPath with via

Previous: IOPath Next: IdPath

IdPath

IdPath<A> wraps Id<A>, the identity monad. It always contains a value and never fails. This sounds useless until you need it.

Creation

IdPath<String> id = Path.id("hello");
IdPath<User> fromId = Path.idPath(idUser);

Core Operations

IdPath<String> name = Path.id("Alice");

IdPath<Integer> length = name.map(String::length);  // Id(5)
IdPath<String> upper = name.via(s -> Path.id(s.toUpperCase()));
IdPath<String> combined = name.zipWith(Path.id(25), (n, a) -> n + " is " + a);

Extraction

IdPath<String> path = Path.id("hello");
String value = path.run().value();  // "hello"
String value = path.get();          // "hello"

When to Use

IdPath is right when:

• You're writing generic code that works over any Path type
• Testing monadic code with known, predictable values
• You need a "no-op" Path that always succeeds
• Satisfying a type parameter that demands a Path

IdPath is wrong when:

• Failure is possible → you need one of the other types

// Works with any Path type
<P extends Path<P, A>, A> P process(P path) {
    return path.map(this::transform);
}

// Test with IdPath (no failures to worry about)
IdPath<String> testPath = Path.id("test");
IdPath<String> result = process(testPath);

Previous: ValidationPath Next: OptionalPath

OptionalPath

OptionalPath<A> wraps Java's java.util.Optional<A>, bridging the standard library and the Path API.

Creation

OptionalPath<String> present = Path.present("hello");
OptionalPath<String> absent = Path.absent();
OptionalPath<User> user = Path.optional(repository.findById(id));

Core Operations

OptionalPath<String> name = Path.present("Alice");

OptionalPath<Integer> length = name.map(String::length);
OptionalPath<String> upper = name.via(s -> Path.present(s.toUpperCase()));

Extraction and Conversion

OptionalPath<String> path = Path.present("hello");

Optional<String> optional = path.run();
String value = path.getOrElse("default");
boolean hasValue = path.isPresent();

// Convert to MaybePath for richer operations
MaybePath<String> maybe = path.toMaybePath();

When to Use

OptionalPath is right when:

• You're integrating with Java APIs that return Optional
• You prefer staying close to standard library semantics
• Bridging between Higher-Kinded-J and existing codebases

OptionalPath is wrong when:

• You're not constrained by Optional → MaybePath is slightly richer

Previous: IdPath Next: GenericPath

GenericPath

GenericPath<F, A> is the escape hatch. It wraps any Kind<F, A> with a Monad instance, letting you use Path operations on custom types.

Creation

Monad<ListKind.Witness> listMonad = ListMonad.INSTANCE;
Kind<ListKind.Witness, Integer> listKind =
    ListKindHelper.LIST.widen(List.of(1, 2, 3));

GenericPath<ListKind.Witness, Integer> listPath =
    Path.generic(listKind, listMonad);

Core Operations

GenericPath<ListKind.Witness, Integer> numbers = Path.generic(listKind, listMonad);

GenericPath<ListKind.Witness, String> strings = numbers.map(n -> "n" + n);

GenericPath<ListKind.Witness, Integer> doubled = numbers.via(n ->
    Path.generic(ListKindHelper.LIST.widen(List.of(n, n * 2)), listMonad));

Extraction

Kind<ListKind.Witness, Integer> kind = path.runKind();
List<Integer> list = ListKindHelper.LIST.narrow(kind);

When to Use

GenericPath is right when:

• You have a custom monad not covered by specific Path types
• Writing highly generic code across multiple monad types
• Experimenting with new effect types

Previous: OptionalPath Next: TrampolinePath

TrampolinePath

TrampolinePath<A> wraps Trampoline<A> for stack-safe recursion. Deep recursive algorithms that would blow the stack with direct recursion become safe with trampolining.

Creation

// Immediate value (already computed)
TrampolinePath<Integer> done = Path.trampolineDone(42);

// Suspended computation (thunked)
TrampolinePath<Integer> suspended = Path.trampolineSuspend(() -> 42);

// From existing Trampoline
TrampolinePath<Integer> path = Path.trampoline(trampoline);

Core Operations

TrampolinePath<Integer> start = Path.trampolineDone(10);

TrampolinePath<Integer> doubled = start.map(n -> n * 2);  // 20

TrampolinePath<Integer> chained = start.via(n ->
    Path.trampolineDone(n + 5));  // 15

Stack-Safe Recursion

The real power is in recursive algorithms. Here's factorial without stack overflow:

TrampolinePath<Long> factorial(long n) {
    return factorialHelper(n, 1L);
}

TrampolinePath<Long> factorialHelper(long n, long acc) {
    if (n <= 1) {
        return Path.trampolineDone(acc);
    }
    // Suspend to avoid stack growth
    return Path.trampolineSuspend(() ->
        factorialHelper(n - 1, n * acc).run());
}

// Compute factorial of 10000 - no stack overflow!
Long result = factorial(10000L).run().run();

Compare with naive recursion:

// This WILL overflow the stack for large n
long naiveFactorial(long n) {
    if (n <= 1) return 1;
    return n * naiveFactorial(n - 1);  // Stack frame per call!
}

Mutual Recursion

Trampolining also handles mutual recursion:

TrampolinePath<Boolean> isEven(int n) {
    if (n == 0) return Path.trampolineDone(true);
    return Path.trampolineSuspend(() -> isOdd(n - 1).run());
}

TrampolinePath<Boolean> isOdd(int n) {
    if (n == 0) return Path.trampolineDone(false);
    return Path.trampolineSuspend(() -> isEven(n - 1).run());
}

// Works for any depth
Boolean result = isEven(1_000_000).run().run();  // true

Extraction

TrampolinePath<Integer> path = Path.trampolineDone(42);

// Get the Trampoline
Trampoline<Integer> trampoline = path.run();

// Execute (runs the trampoline to completion)
Integer value = trampoline.run();

// Or chain: path.run().run()

When to Use

TrampolinePath is right when:

• You have deep recursive algorithms that could overflow the stack
• Tree traversal, graph algorithms, or mathematical computations
• Mutual recursion patterns
• You need guaranteed stack safety regardless of input size

TrampolinePath is wrong when:

• Recursion depth is bounded and small (regular recursion is simpler)
• You're not doing recursion at all
• Performance is critical and you can use iteration instead

Previous: GenericPath Next: FreePath

FreePath

FreePath<F, A> wraps Free<F, A> for building domain-specific languages (DSLs). It separates the description of a program from its execution, enabling multiple interpreters for the same program.

The Idea

Free monads let you:

1. Describe operations as data structures
2. Compose descriptions into programs
3. Interpret programs with different strategies

This enables testing with mock interpreters, swapping implementations, and reasoning about programs as data.

Defining a DSL

First, define your operations as a sum type (algebra):

// Console operations
sealed interface ConsoleOp<A> permits Ask, Tell {}

record Ask<A>(String prompt, Function<String, A> next) implements ConsoleOp<A> {}
record Tell<A>(String message, A next) implements ConsoleOp<A> {}

Creating Programs

Lift operations into FreePath:

FreePath<ConsoleOp.Witness, String> ask(String prompt) {
    return Path.freeLiftF(new Ask<>(prompt, Function.identity()));
}

FreePath<ConsoleOp.Witness, Void> tell(String message) {
    return Path.freeLiftF(new Tell<>(message, null));
}

Compose into programs:

FreePath<ConsoleOp.Witness, String> greetUser =
    ask("What is your name?").via(name ->
        tell("Hello, " + name + "!").map(v -> name));

Core Operations

// Pure value (no operations)
FreePath<ConsoleOp.Witness, Integer> pure = Path.freePure(42);

// Transform results
FreePath<ConsoleOp.Witness, String> asString = pure.map(n -> "Value: " + n);

// Chain operations
FreePath<ConsoleOp.Witness, Integer> chained = pure.via(n ->
    ask("Continue?").map(s -> n + s.length()));

Interpreters

An interpreter is a natural transformation from your algebra to a target monad:

// Real console interpreter
NaturalTransformation<ConsoleOp.Witness, IO.Witness> realInterpreter =
    new NaturalTransformation<>() {
        public <A> Kind<IO.Witness, A> apply(Kind<ConsoleOp.Witness, A> fa) {
            ConsoleOp<A> op = ConsoleOpHelper.narrow(fa);
            return switch (op) {
                case Ask<A> a -> IO.of(() -> {
                    System.out.print(a.prompt() + " ");
                    return a.next().apply(scanner.nextLine());
                });
                case Tell<A> t -> IO.of(() -> {
                    System.out.println(t.message());
                    return t.next();
                });
            };
        }
    };

// Test interpreter (uses predefined responses)
NaturalTransformation<ConsoleOp.Witness, State.Witness> testInterpreter = ...;

Running Programs

FreePath<ConsoleOp.Witness, String> program = greetUser;

// Get the Free structure
Free<ConsoleOp.Witness, String> free = program.run();

// Interpret to IO
Kind<IO.Witness, String> io = free.foldMap(realInterpreter, ioMonad);

// Execute
String result = IOKindHelper.narrow(io).unsafeRunSync();

When to Use

FreePath is right when:

• You want to separate description from execution
• Multiple interpreters for the same program (prod/test/mock)
• Building embedded DSLs for domain operations
• You need to inspect or transform programs before running them

FreePath is wrong when:

• Simple direct effects suffice → use IOPath
• You don't need multiple interpreters
• Performance is critical (free monads have overhead)
• Operations can be parallelized → consider FreeApPath

// Production: real database
NaturalTransformation<DbOp.Witness, IO.Witness> prodInterpreter = ...;

// Test: in-memory map
NaturalTransformation<DbOp.Witness, State.Witness> testInterpreter = ...;

// Same program, different interpreters
FreePath<DbOp.Witness, User> program = findUser(userId);
Kind<IO.Witness, User> prod = program.run().foldMap(prodInterpreter, ioMonad);
Kind<State.Witness, User> test = program.run().foldMap(testInterpreter, stateMonad);

Previous: TrampolinePath Next: FreeApPath

FreeApPath

FreeApPath<F, A> wraps FreeAp<F, A> for building applicative DSLs. Unlike FreePath, operations in FreeApPath can be analyzed and potentially executed in parallel because they don't depend on each other's results.

The Key Difference

FreePath (monadic): Each operation can depend on previous results. FreeApPath (applicative): Operations are independent; results combine at the end.

// FreePath: second operation depends on first
FreePath<F, String> monadic = getUser(id).via(user ->
    getOrders(user.id()));  // Sequential: must wait for user

// FreeApPath: operations are independent
FreeApPath<F, Summary> applicative =
    getUser(id).zipWith(getOrders(id), Summary::new);  // Parallel-safe!

Creation

// Pure value
FreeApPath<ConfigOp.Witness, String> pure = Path.freeApPure("default");

// Lift an operation
FreeApPath<ConfigOp.Witness, String> dbUrl =
    Path.freeApLift(new GetConfig("database.url"));

Core Operations

FreeApPath<ConfigOp.Witness, String> host = getConfig("host");
FreeApPath<ConfigOp.Witness, Integer> port = getConfig("port").map(Integer::parseInt);

// Combine independent operations
FreeApPath<ConfigOp.Witness, String> url =
    host.zipWith(port, (h, p) -> "http://" + h + ":" + p);

// Map over results
FreeApPath<ConfigOp.Witness, String> upper = host.map(String::toUpperCase);

Static Analysis

Because operations are independent, you can analyze programs before running them:

// Collect all config keys that will be requested
Set<String> getRequestedKeys(FreeAp<ConfigOp.Witness, ?> program) {
    return program.analyze(op -> {
        GetConfig config = ConfigOpHelper.narrow(op);
        return Set.of(config.key());
    }, Monoids.set());
}

FreeApPath<ConfigOp.Witness, DbConfig> program =
    getConfig("db.host")
        .zipWith(getConfig("db.port"), DbConfig::new);

Set<String> keys = getRequestedKeys(program.run());
// Set.of("db.host", "db.port")

This enables:

• Validation before execution
• Optimization (batching, caching)
• Documentation generation
• Dependency analysis

Parallel Execution

Interpreters can exploit independence for parallelism:

// Sequential interpreter
NaturalTransformation<ConfigOp.Witness, IO.Witness> sequential =
    op -> IO.of(() -> loadConfig(op.key()));

// Parallel interpreter (batch all requests)
Kind<IO.Witness, Config> parallel = program.run().foldMap(
    batchingInterpreter,
    ioApplicative
);

Running Programs

FreeApPath<ConfigOp.Witness, DbConfig> program =
    getConfig("host").zipWith(getConfig("port"), DbConfig::new);

// Get the FreeAp structure
FreeAp<ConfigOp.Witness, DbConfig> freeAp = program.run();

// Interpret
Kind<IO.Witness, DbConfig> io = freeAp.foldMap(interpreter, ioApplicative);

// Execute
DbConfig config = IOKindHelper.narrow(io).unsafeRunSync();

When to Use

FreeApPath is right when:

• Operations are independent (don't depend on each other's results)
• You want to analyze programs before running (static analysis)
• Parallel/batched execution is beneficial
• Building configuration loaders, query builders, validation pipelines

FreeApPath is wrong when:

• Operations depend on previous results → use FreePath
• You don't need static analysis or parallelism
• Simpler direct effects suffice → use IOPath

// Define config operations
FreeApPath<ConfigOp.Witness, String> dbHost = getConfig("db.host");
FreeApPath<ConfigOp.Witness, Integer> dbPort = getConfig("db.port").map(Integer::parseInt);
FreeApPath<ConfigOp.Witness, String> dbName = getConfig("db.name");

// Combine into complete config (all three fetched independently)
FreeApPath<ConfigOp.Witness, DbConfig> dbConfig =
    dbHost.zipWith3(dbPort, dbName, DbConfig::new);

// Analyze: what keys are needed?
Set<String> keys = analyze(dbConfig);  // {db.host, db.port, db.name}

// Execute: fetch all in parallel/batch
DbConfig config = run(dbConfig, parallelInterpreter);

Previous: FreePath Next: Composition Patterns

Composition Patterns

"The world, that understandable and lawful world, was slipping away."

— William Golding, Lord of the Flies

Golding's boys lost their grip on order gradually, one compromised rule at a time. Code works the same way. A null check here, an uncaught exception there, a boolean flag that means three different things depending on context, and suddenly your "understandable and lawful" service layer has become something you approach with trepidation.

Composition is how you hold the line. Each pattern in this chapter is a way of connecting operations so that failures propagate predictably, successes build on each other, and the logic remains visible even as complexity grows.

Sequential Composition: One Thing After Another

The via method chains computations where each step depends on the previous result. It's the workhorse of effect composition.

EitherPath<Error, Invoice> pipeline =
    Path.either(findUser(userId))
        .via(user -> Path.either(getCart(user)))
        .via(cart -> Path.either(calculateTotal(cart)))
        .via(total -> Path.either(createInvoice(total)));

Each via receives the success value and returns a new Path. The railway model applies: travel along the success track until something fails, then skip to the end.

Short-Circuiting

When a step fails, subsequent steps don't execute:

EitherPath<String, String> result =
    Path.right("start")
        .via(s -> Path.left("failed here"))     // Fails
        .via(s -> Path.right(s + " never"))     // Skipped
        .via(s -> Path.right(s + " reached"));  // Skipped

// result.run() → Left("failed here")

This isn't just convenient; it's essential. Without short-circuiting, you'd need defensive checks at every step. The Path handles it structurally.

then: Sequencing Without the Value

Sometimes you need sequencing but don't care about the previous result:

IOPath<Result> workflow =
    Path.io(() -> log.info("Starting"))
        .then(() -> Path.io(() -> initialise()))
        .then(() -> Path.io(() -> process()))
        .then(() -> Path.io(() -> log.info("Done")));

then discards the previous value and runs the next computation. Use it for side effects that must happen in order but don't pass data forward.

Independent Combination: All Together Now

zipWith combines computations that don't depend on each other. Neither needs the other's result to proceed.

EitherPath<String, String> name = validateName(input.name());
EitherPath<String, String> email = validateEmail(input.email());
EitherPath<String, Integer> age = validateAge(input.age());

EitherPath<String, User> user = name.zipWith3(email, age, User::new);

If all three succeed, User::new receives the values. If any fails, the first failure propagates.

The Difference Matters

This distinction trips people up, so let's be explicit:

// WRONG: using via when computations are independent
Path.right(validateName(input))
    .via(name -> Path.right(validateEmail(input)))  // Doesn't use name!
    .via(email -> Path.right(validateAge(input)));  // Doesn't use email!

// RIGHT: using zipWith for independent computations
validateName(input).zipWith3(
    validateEmail(input),
    validateAge(input),
    User::new
);

The first version works but misleads readers into thinking there's a dependency. The second says what it means.

Variants

// Two values
pathA.zipWith(pathB, (a, b) -> combine(a, b))

// Three values
pathA.zipWith3(pathB, pathC, (a, b, c) -> combine(a, b, c))

// Four values
pathA.zipWith4(pathB, pathC, pathD, (a, b, c, d) -> combine(a, b, c, d))

Beyond four, consider whether your design is asking too much of a single expression.

Mixed Composition: The Real World

Production code rarely uses just one pattern. You validate independently, then sequence dependent operations, then combine more independent work. The key is clarity about which pattern you're using where.

EitherPath<Error, Order> createOrder(OrderInput input) {
    // Phase 1: Independent validation
    EitherPath<Error, String> name = validateName(input.name());
    EitherPath<Error, String> email = validateEmail(input.email());
    EitherPath<Error, Address> address = validateAddress(input.address());

    EitherPath<Error, CustomerInfo> customer =
        name.zipWith3(email, address, CustomerInfo::new);

    // Phase 2: Sequential operations that depend on customer
    return customer
        .via(info -> Path.either(checkInventory(input.items())))
        .via(inventory -> Path.either(calculatePricing(inventory)))
        .via(pricing -> Path.either(createOrder(customer, pricing)));
}

The phases are distinct: independent validation first, then a sequential pipeline that threads through the validated data. Readers can see the structure at a glance.

Parallel Composition

"The machine didn't think about one thing at a time. It thought about many things, all at once, in parallel streams that only converged when they had to."

— Neal Stephenson, Cryptonomicon

Sequential composition with via is appropriate when each step depends on the previous. But when computations are genuinely independent, running them in parallel can dramatically reduce total execution time.

Expressing Parallelism with parZipWith

parZipWith is zipWith with explicit parallel execution:

IOPath<User> fetchUser = IOPath.delay(() -> userService.get(id));
IOPath<Preferences> fetchPrefs = IOPath.delay(() -> prefService.get(id));

// Sequential: ~200ms (100ms + 100ms)
IOPath<Profile> sequential = fetchUser.zipWith(fetchPrefs, Profile::new);

// Parallel: ~100ms (max of both)
IOPath<Profile> parallel = fetchUser.parZipWith(fetchPrefs, Profile::new);

The operations are the same; the execution strategy differs. Use parZipWith when you want to make the parallel intent explicit.

N-ary Parallel Composition

For three or four independent paths, use PathOps utilities:

IOPath<Dashboard> dashboard = PathOps.parZip3(
    fetchMetrics(),
    fetchAlerts(),
    fetchUsers(),
    Dashboard::new
);

IOPath<Report> report = PathOps.parZip4(
    fetchSales(),
    fetchInventory(),
    fetchCustomers(),
    fetchTrends(),
    Report::new
);

List Parallelism with parSequenceIO

When you have a dynamic number of independent operations:

List<IOPath<Product>> fetches = productIds.stream()
    .map(id -> IOPath.delay(() -> productService.get(id)))
    .toList();

// All fetches run concurrently
IOPath<List<Product>> products = PathOps.parSequenceIO(fetches);

Racing Computations

Sometimes you want whichever completes first:

IOPath<Config> primary = IOPath.delay(() -> fetchFromPrimary());
IOPath<Config> backup = IOPath.delay(() -> fetchFromBackup());

// Returns whichever config arrives first
IOPath<Config> fastest = primary.race(backup);

Sequential vs Parallel: The Decision

The wrong choice doesn't break correctness—just performance. When in doubt, prefer sequential; parallelise when profiling shows it matters.

Debugging with peek

Effect chains can frustrate debugging. When something fails mid-pipeline, you know that it failed but not where. Traditional print debugging would break the chain. Debugger breakpoints are awkward with lambdas.

peek solves this by letting you observe values without disrupting the flow:

EitherPath<Error, User> result =
    Path.either(validateInput(input))
        .peek(valid -> log.debug("Validated: {}", valid))
        .via(valid -> Path.either(createUser(valid)))
        .peek(user -> log.info("Created user: {}", user.getId()))
        .via(user -> Path.either(sendWelcomeEmail(user)))
        .peek(email -> log.debug("Email sent"));

peek only executes on the success track. Failures pass through silently, which is usually what you want when tracing the happy path.

A Debugging Helper

For detailed tracing, wrap the pattern:

<A> EitherPath<Error, A> traced(EitherPath<Error, A> path, String step) {
    return path.peek(v -> log.debug("[{}] → {}", step, v));
}

EitherPath<Error, Invoice> pipeline =
    traced(Path.either(findUser(id)), "findUser")
        .via(user -> traced(Path.either(getCart(user)), "getCart"))
        .via(cart -> traced(Path.either(checkout(cart)), "checkout"));

When something goes wrong, the logs show exactly how far you got.

Error Handling Strategies

Not every error should halt processing. Sometimes you have a sensible fallback. Sometimes you need to transform the error for the next layer. Sometimes you want to try several approaches before giving up.

Strategy 1: Recover with a Default

The operation might fail, but you have a reasonable fallback:

MaybePath<Config> config = Path.maybe(loadConfig())
    .orElse(() -> Path.just(Config.defaults()));

EitherPath<Error, User> user = Path.either(findUser(id))
    .recover(error -> User.guest());

Use this when the fallback is genuinely acceptable, not when you're papering over problems you should be handling properly.

Strategy 2: Transform the Error

Low-level errors leak implementation details. Transform them at layer boundaries:

EitherPath<ServiceError, Data> result =
    Path.either(externalApi.fetch())
        .mapError(apiError -> new ServiceError("API unavailable", apiError));

The original error is preserved as the cause; callers see a domain-appropriate type.

Strategy 3: Fallback Chain

Multiple sources for the same data, each with trade-offs:

EitherPath<Error, Config> config =
    Path.either(loadFromFile())
        .recoverWith(e1 -> {
            log.warn("File config failed: {}", e1);
            return Path.either(loadFromEnvironment());
        })
        .recoverWith(e2 -> {
            log.warn("Env config failed: {}", e2);
            return Path.right(Config.defaults());
        });

Each recoverWith only triggers if the previous step failed. The first success short-circuits the chain.

Strategy 4: Accumulate All Errors

For validation where users should see everything wrong at once:

ValidationPath<List<String>, User> user =
    validateName(input.name())
        .zipWith3Accum(
            validateEmail(input.email()),
            validateAge(input.age()),
            User::new
        );

// All three validations run; all errors collected

See ValidationPath for the full API.

Strategy 5: Error Enrichment

Add context as errors propagate:

EitherPath<DetailedError, Data> enriched =
    path.mapError(error -> new DetailedError(
        error,
        "During user lookup",
        Map.of("userId", userId, "timestamp", Instant.now())
    ));

When the error surfaces, you know not just what failed but where and with what context.

Conversion Between Paths

As requirements evolve, you may need to switch Path types:

MaybePath → EitherPath

Absence becomes a typed error:

MaybePath<User> maybe = Path.maybe(findUser(id));
EitherPath<String, User> either = maybe.toEitherPath("User not found");

TryPath → EitherPath

Exception becomes a typed error:

TryPath<Config> tried = Path.tryOf(() -> loadConfig());
EitherPath<String, Config> either = tried.toEitherPath(Throwable::getMessage);

IOPath → TryPath

Execute the deferred effect and capture the result:

IOPath<Data> io = Path.io(() -> fetchData());
TryPath<Data> tried = io.toTryPath();  // Executes immediately!

The Full Conversion Map

See Type Conversions for comprehensive coverage of all conversion paths.

A Realistic Example

Bringing the patterns together:

public class OrderService {
    private final UserRepository users;
    private final InventoryService inventory;
    private final PaymentService payments;

    public EitherPath<OrderError, Order> placeOrder(OrderRequest request) {
        // Validate request (fail-fast)
        return validateRequest(request)
            .peek(v -> log.debug("Request validated"))

            // Get user (convert Maybe → Either)
            .via(valid -> Path.maybe(users.findById(valid.userId()))
                .toEitherPath(() -> new OrderError.UserNotFound(valid.userId())))
            .peek(user -> log.debug("Found user: {}", user.getId()))

            // Check inventory
            .via(user -> Path.either(inventory.check(request.items()))
                .mapError(OrderError.InventoryError::new))

            // Process payment
            .via(available -> Path.tryOf(() ->
                    payments.charge(user, available.total()))
                .toEitherPath(OrderError.PaymentFailed::new))
            .peek(payment -> log.info("Payment processed: {}", payment.getId()))

            // Create order
            .via(payment -> Path.right(
                createOrder(user, request.items(), payment)));
    }

    private EitherPath<OrderError, ValidatedRequest> validateRequest(
            OrderRequest request) {
        if (request.items().isEmpty()) {
            return Path.left(new OrderError.EmptyCart());
        }
        return Path.right(new ValidatedRequest(request));
    }
}

The structure is visible: validate, fetch, check, charge, create. Errors propagate with appropriate types. Logging traces the happy path. Each conversion (toEitherPath, mapError) happens at a deliberate boundary.

Common Mistakes

Mistake 1: Using via for Independent Operations

// Misleading: suggests email validation depends on name
validateName(input)
    .via(name -> validateEmail(input))  // Doesn't use name!

// Clearer: shows independence
validateName(input).zipWith(validateEmail(input), (n, e) -> ...)

Mistake 2: Side Effects in map

// Wrong: side effect hidden in map
path.map(user -> {
    database.save(user);  // Side effect!
    return user;
});

// Right: use peek for side effects
path.peek(user -> database.save(user));

// Or be explicit with IOPath
path.via(user -> Path.io(() -> {
    database.save(user);
    return user;
}));

Mistake 3: Forgetting to Run

// Bug: nothing happens
void processUser(String id) {
    Path.maybe(findUser(id))
        .map(this::process);  // Result discarded!
}

// Fixed: extract the result
void processUser(String id) {
    Path.maybe(findUser(id))
        .map(this::process)
        .run();
}

Mistake 4: Converting Back and Forth

// Wasteful: converting repeatedly
Path.maybe(findUser(id))
    .toEitherPath(() -> error)
    .toMaybePath()
    .toEitherPath(() -> error);  // Why?

// Clean: convert once
Path.maybe(findUser(id))
    .toEitherPath(() -> error);

Summary

The world remains understandable and lawful when each operation has a clear purpose and failures propagate predictably. Composition is the discipline that makes this possible.

Continue to ForPath Comprehension for detailed coverage of moving between Path types.

Previous: Path Types Next: ForPath Comprehension

ForPath: For-Comprehensions with Effect Paths

"Though this be madness, yet there is method in't."

— William Shakespeare, Hamlet

And so it is with for-comprehensions: what appears to be arcane syntax hides a deeply methodical approach to composing sequential operations.

The Problem: Bridging Two Worlds

The standard For class provides powerful for-comprehension syntax, but it operates on raw Kind<M, A> values and requires explicit Monad instances. When working with the Effect Path API, this creates friction:

// Using standard For with Path types requires extraction and rewrapping
Kind<MaybeKind.Witness, Integer> kindResult = For.from(maybeMonad, path1.run().kind())
    .from(a -> path2.run().kind())
    .yield((a, b) -> a + b);

MaybePath<Integer> result = Path.maybe(MAYBE.narrow(kindResult));

The intent is clear, but the ceremony obscures it. ForPath eliminates this friction:

// ForPath works directly with Path types
MaybePath<Integer> result = ForPath.from(path1)
    .from(a -> path2)
    .yield((a, b) -> a + b);

The comprehension accepts Path types and returns Path types. No manual extraction, no rewrapping, no boilerplate.

Entry Points

ForPath provides entry points for each supported Path type:

The when() guard operation is only available for Path types backed by MonadZero, which can represent emptiness or failure.

Core Operations

Generators: .from()

The .from() operation extracts a value from the current step and chains to a new Path-producing computation. This is the monadic bind (flatMap) in disguise.

MaybePath<String> result = ForPath.from(Path.just("Alice"))
    .from(name -> Path.just(name.length()))         // a = "Alice", b = 5
    .from(t -> Path.just(t._1() + ":" + t._2()))    // t is Tuple2<String, Integer>
    .yield((name, len, combined) -> combined);      // "Alice:5"

Each .from() adds a new value to the accumulating tuple, making all previous values available to subsequent steps.

Value Bindings: .let()

The .let() operation computes a pure value from accumulated results without introducing a new effect. It's equivalent to map that carries the value forward.

MaybePath<String> result = ForPath.from(Path.just(10))
    .let(a -> a * 2)                    // b = 20 (pure calculation)
    .let(t -> t._1() + t._2())          // c = 30 (can access tuple)
    .yield((a, b, c) -> "Sum: " + c);   // "Sum: 30"

Guards: .when()

For Path types with MonadZero (MaybePath, OptionalPath, NonDetPath), the .when() operation filters results. When the predicate returns false, the computation short-circuits to the monad's zero value (Nothing, empty, etc.).

MaybePath<Integer> evenOnly = ForPath.from(Path.just(4))
    .when(n -> n % 2 == 0)              // passes: 4 is even
    .yield(n -> n * 10);                // Just(40)

MaybePath<Integer> filtered = ForPath.from(Path.just(3))
    .when(n -> n % 2 == 0)              // fails: 3 is odd
    .yield(n -> n * 10);                // Nothing

Projection: .yield()

Every comprehension ends with .yield(), which maps the accumulated values to a final result. You can access values individually or as a tuple:

// Individual parameters
.yield((a, b, c) -> a + b + c)

// Or as a tuple for many values
.yield(t -> t._1() + t._2() + t._3())

Optics Integration

ForPath integrates with the Focus DSL for structural navigation within comprehensions.

Extracting with .focus()

The .focus() operation uses a FocusPath to extract a nested value:

record User(String name, Address address) {}
record Address(String city, String postcode) {}

// Create lenses for each field
Lens<User, Address> addressLens = Lens.of(
    User::address, (u, a) -> new User(u.name(), a));
Lens<Address, String> cityLens = Lens.of(
    Address::city, (a, c) -> new Address(c, a.postcode()));

// Compose paths with via() for nested access
FocusPath<User, Address> addressPath = FocusPath.of(addressLens);
FocusPath<User, String> userCityPath = addressPath.via(FocusPath.of(cityLens));

MaybePath<String> result = ForPath.from(Path.just(user))
    .focus(userCityPath)                        // extract city directly
    .yield((user, city) -> city.toUpperCase());

Alternatively, chain focus operations where the second takes a function:

FocusPath<User, Address> addressPath = FocusPath.of(addressLens);

MaybePath<String> result = ForPath.from(Path.just(user))
    .focus(addressPath)                         // extract address -> Steps2
    .focus(t -> t._2().city())                  // extract city from tuple
    .yield((user, address, city) -> city.toUpperCase());

Pattern Matching with .match()

The .match() operation uses an AffinePath for optional extraction. When the focus is absent, the comprehension short-circuits for MonadZero types:

sealed interface Result permits Success, Failure {}
record Success(String value) implements Result {}
record Failure(String error) implements Result {}

AffinePath<Result, Success> successPath = AffinePath.of(
    Affine.of(
        r -> r instanceof Success s ? Optional.of(s) : Optional.empty(),
        (r, s) -> s
    )
);

MaybePath<String> result = ForPath.from(Path.just((Result) new Success("data")))
    .match(successPath)                         // extract Success
    .yield((r, success) -> success.value().toUpperCase());
// Just("DATA")

MaybePath<String> empty = ForPath.from(Path.just((Result) new Failure("error")))
    .match(successPath)                         // fails to match
    .yield((r, success) -> success.value());
// Nothing

EitherPath Example

For error-handling scenarios, EitherPath comprehensions propagate failures automatically:

record User(String id, String name) {}
record Order(String orderId, User user) {}

Function<String, EitherPath<String, User>> findUser = id ->
    id.equals("user-1")
        ? Path.right(new User("user-1", "Alice"))
        : Path.left("User not found: " + id);

Function<User, EitherPath<String, Order>> createOrder = user ->
    Path.right(new Order("order-123", user));

EitherPath<String, String> result = ForPath.from(findUser.apply("user-1"))
    .from(user -> createOrder.apply(user))
    .yield((user, order) -> "Created " + order.orderId() + " for " + user.name());
// Right("Created order-123 for Alice")

EitherPath<String, String> failed = ForPath.from(findUser.apply("unknown"))
    .from(user -> createOrder.apply(user))
    .yield((user, order) -> "Created " + order.orderId());
// Left("User not found: unknown")

IOPath Example

IOPath comprehensions compose deferred side-effectful computations:

IOPath<String> readConfig = Path.io(() -> "production");
IOPath<Integer> readPort = Path.io(() -> 8080);

IOPath<String> serverInfo = ForPath.from(readConfig)
    .from(env -> readPort)
    .let(t -> t._1().toUpperCase())
    .yield((env, port, upperEnv) -> upperEnv + " server on port " + port);

// Nothing executes until:
String result = serverInfo.unsafeRun();  // "PRODUCTION server on port 8080"

NonDetPath Example

NonDetPath (backed by List) generates all combinations:

NonDetPath<String> combinations = ForPath.from(Path.list("red", "blue"))
    .from(c -> Path.list("S", "M", "L"))
    .when(t -> !t._1().equals("blue") || !t._2().equals("S"))  // filter out blue-S
    .yield((colour, size) -> colour + "-" + size);

List<String> result = combinations.run();
// ["red-S", "red-M", "red-L", "blue-M", "blue-L"]

When to Use ForPath vs For

For monad transformer stacks, the standard For class remains the appropriate choice as it works directly with the transformer's Kind representation.

Previous: Composition Patterns Next: Type Conversions

Type Conversions

"The system was invisible, as they had intended, until you looked."

— Don DeLillo, Underworld

DeLillo's observation captures the nature of type conversions in effect-oriented code. The conversions exist invisibly, implicit in how the types relate to each other. But once you see the system (the natural transformations between Maybe and Either, the bridges from Try to Validation), the invisible becomes navigable.

This chapter makes that system visible.

Conversion Overview

The Path API supports rich conversions between all path types. Some conversions preserve all information; others require additional context (like an error value when converting from MaybePath to EitherPath).

┌──────────────────────────────────────────────────────────────────────────────────┐
│                           PATH TYPE CONVERSIONS                                  │
├──────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│  ERROR-HANDLING PATHS                                                            │
│  ────────────────────                                                            │
│    MaybePath ←──────────────────────────────────────────────→ EitherPath         │
│       │     toEitherPath(error)  /  toMaybePath()                  │             │
│       │                                                            │             │
│    TryPath ←────────────────────────────────────────────────→ EitherPath         │
│       │     toEitherPath(mapper) /  toTryPath()                    │             │
│       │                                                            │             │
│    TryPath ←────── toMaybePath() ────────────────────────────→ MaybePath         │
│       │                                                                          │
│    IOPath ──────── toTryPath() ──────────────────────────────→ TryPath           │
│                                                                                  │
│  VALIDATION PATHS                                                                │
│  ────────────────                                                                │
│    EitherPath ←─────────────────────────────────────────────→ ValidationPath     │
│              toValidationPath() / toEitherPath()                                 │
│                                                                                  │
│    TryPath ─────── toValidationPath(mapper) ────────────────→ ValidationPath     │
│                                                                                  │
│  UTILITY PATHS                                                                   │
│  ─────────────                                                                   │
│    IdPath ←──────── toIdPath() / toMaybePath() ─────────────→ MaybePath          │
│                                                                                  │
│    OptionalPath ←── toOptionalPath() / toMaybePath() ───────→ MaybePath          │
│                                                                                  │
│    GenericPath ←─── Wraps any Kind<F, A> with Monad instance                     │
│                                                                                  │
└──────────────────────────────────────────────────────────────────────────────────┘

MaybePath Conversions

MaybePath → EitherPath

Convert absence to a typed error:

MaybePath<User> maybeUser = Path.maybe(findUser(id));

// Provide error for Nothing case
EitherPath<String, User> withError =
    maybeUser.toEitherPath("User not found");

// With lazy error
EitherPath<UserError, User> withLazyError =
    maybeUser.toEitherPath(() -> new UserError("User " + id + " not found"));

This is useful when:

• An optional value becomes a required value
• You need to propagate error information downstream

// Service that returns Maybe internally but Either externally
public EitherPath<Error, User> getUserOrError(String id) {
    return Path.maybe(userRepository.findById(id))
        .toEitherPath(() -> new Error.UserNotFound(id));
}

EitherPath → MaybePath

Discard error information:

EitherPath<String, User> eitherUser = Path.either(validateUser(input));

// Errors become Nothing
MaybePath<User> maybeUser = eitherUser.toMaybePath();

This is useful when:

• You only care about success/failure, not the error details
• Integrating with APIs that expect Maybe

TryPath Conversions

TryPath → EitherPath

Convert exceptions to typed errors:

TryPath<Config> tryConfig = Path.tryOf(() -> loadConfig());

// Keep the exception as the error type
EitherPath<Throwable, Config> withException =
    tryConfig.toEitherPath(ex -> ex);

// Transform exception to your error type
EitherPath<ConfigError, Config> withTypedError =
    tryConfig.toEitherPath(ex -> new ConfigError("Failed to load: " + ex.getMessage()));

// Extract just the message
EitherPath<String, Config> withMessage =
    tryConfig.toEitherPath(Throwable::getMessage);

TryPath → MaybePath

Failures become Nothing:

TryPath<Integer> parsed = Path.tryOf(() -> Integer.parseInt(input));

// Failure → Nothing, Success → Just
MaybePath<Integer> maybeParsed = parsed.toMaybePath();

// Use case: optional parsing
MaybePath<Integer> port = Path.tryOf(() -> Integer.parseInt(config.get("port")))
    .toMaybePath()
    .orElse(() -> Path.just(8080));  // Default port

EitherPath → TryPath

Wrap error as exception:

EitherPath<String, User> eitherUser = validateUser(input);

// Error becomes RuntimeException
TryPath<User> tryUser = eitherUser.toTryPath();

IOPath Conversions

IOPath → TryPath

Execute the IO and capture the result:

IOPath<Data> ioData = Path.io(() -> fetchFromNetwork());

// Execute and capture in Try
TryPath<Data> tryData = ioData.toTryPath();
// The IO has been executed at this point!

IOPath Safe Execution

For explicit control over execution:

IOPath<Data> io = Path.io(() -> fetchData());

// Execute safely (captures exceptions)
Try<Data> result = io.runSafe();

// Then convert to path if needed
TryPath<Data> tryPath = Path.of(result);

ValidationPath Conversions

EitherPath → ValidationPath

Convert to accumulating validation mode:

EitherPath<String, Integer> eitherValue = Path.right(42);

// Convert to ValidationPath (preserves success/failure)
ValidationPath<String, Integer> validationValue = eitherValue.toValidationPath();

// Now can use accumulating operations
ValidationPath<String, Integer> other = Path.valid(10);
ValidationPath<String, Integer> combined = validationValue.zipWithAccum(
    other,
    Integer::sum,
    (e1, e2) -> e1 + "; " + e2
);

ValidationPath → EitherPath

Convert back to short-circuiting mode:

ValidationPath<List<String>, User> validated = validateUser(input);

// Convert to EitherPath for chaining
EitherPath<List<String>, User> either = validated.toEitherPath();

// Now can use via() for dependent operations
EitherPath<List<String>, Order> order = either
    .via(user -> createOrder(user));

TryPath → ValidationPath

Convert exceptions to validation errors:

TryPath<Config> tryConfig = Path.tryOf(() -> loadConfig());

// Transform exception to error type
ValidationPath<String, Config> validConfig =
    tryConfig.toValidationPath(ex -> "Config error: " + ex.getMessage());

When to Convert

Convert EitherPath to ValidationPath when:

• You need to combine multiple independent validations
• You want to accumulate all errors, not just the first

Convert ValidationPath to EitherPath when:

• You need to chain dependent operations with via
• You want fail-fast behaviour for the next step

IdPath Conversions

IdPath wraps pure values with no failure case. Conversions are straightforward:

IdPath → MaybePath

IdPath<String> idValue = Path.id("hello");

// Always becomes Just (IdPath cannot fail)
MaybePath<String> maybe = idValue.toMaybePath();
// → Just("hello")

MaybePath → IdPath

MaybePath<String> maybe = Path.just("hello");

// Requires a default for Nothing case
IdPath<String> id = maybe.toIdPath("default");
// → Id("hello")

MaybePath<String> nothing = Path.nothing();
IdPath<String> idDefault = nothing.toIdPath("default");
// → Id("default")

IdPath Use Cases

IdPath is useful when:

• Working with generic code that expects a path type
• You have a pure value but need path operations (map, via)
• Testing monadic code with known values

OptionalPath Conversions

OptionalPath bridges Java's java.util.Optional with the Path API.

OptionalPath ↔ MaybePath

// From Optional
Optional<String> javaOpt = Optional.of("hello");
OptionalPath<String> optPath = Path.optional(javaOpt);

// To MaybePath
MaybePath<String> maybe = optPath.toMaybePath();

// From MaybePath
MaybePath<String> maybe2 = Path.just("world");
OptionalPath<String> optPath2 = maybe2.toOptionalPath();

// To Optional
Optional<String> javaOpt2 = optPath2.run();

OptionalPath → EitherPath

OptionalPath<User> optUser = Path.optional(findUser(id));

// Provide error for empty case
EitherPath<String, User> either = optUser.toEitherPath("User not found");

When to Use OptionalPath

Use OptionalPath when:

• Integrating with Java APIs that return Optional
• You want path operations on Optional values
• Bridging between Java stdlib and higher-kinded-j

GenericPath Conversions

GenericPath wraps any Kind<F, A> with a Monad instance, providing an escape hatch for custom types.

Creating GenericPath

// Wrap any Kind with its Monad instance
Kind<MaybeKind.Witness, String> maybeKind = MaybeKind.widen(Maybe.just("hello"));
GenericPath<MaybeKind.Witness, String> generic = Path.generic(
    maybeKind,
    MaybeMonad.INSTANCE
);

Using GenericPath

// All standard path operations work
GenericPath<MaybeKind.Witness, Integer> mapped = generic.map(String::length);

GenericPath<MaybeKind.Witness, String> chained = generic.via(s ->
    Path.generic(MaybeKind.widen(Maybe.just(s.toUpperCase())), MaybeMonad.INSTANCE)
);

// Extract the underlying Kind
Kind<MaybeKind.Witness, String> underlying = generic.runKind();

When to Use GenericPath

Use GenericPath when:

• Working with custom monad types not covered by specific Path types
• Writing generic code that works with any monad
• You need path operations for a third-party Kind type

Lifting Values

Lifting to MaybePath

// From a value
MaybePath<String> just = Path.just("hello");

// From Nothing
MaybePath<String> nothing = Path.nothing();

// From nullable
String nullable = possiblyNullValue();
MaybePath<String> maybe = Path.fromNullable(nullable);

// Conditional lifting
MaybePath<Integer> validated = value > 0
    ? Path.just(value)
    : Path.nothing();

Lifting to EitherPath

// Success
EitherPath<Error, Integer> success = Path.right(42);

// Failure
EitherPath<Error, Integer> failure = Path.left(new Error("failed"));

// Conditional lifting
EitherPath<String, Integer> validated = value > 0
    ? Path.right(value)
    : Path.left("Value must be positive");

Lifting to TryPath

// Success
TryPath<Integer> success = Path.success(42);

// Failure
TryPath<Integer> failure = Path.failure(new RuntimeException("error"));

// From computation
TryPath<Config> config = Path.tryOf(() -> loadConfig());

Lifting to IOPath

// Pure value (no side effects)
IOPath<Integer> pure = Path.ioPure(42);

// Deferred computation
IOPath<String> deferred = Path.io(() -> readFile());

Lifting to ValidationPath

// Valid value
ValidationPath<String, Integer> valid = Path.valid(42);

// Invalid value
ValidationPath<String, Integer> invalid = Path.invalid("Must be positive");

// From existing Validated
Validated<String, User> validated = validateUser(input);
ValidationPath<String, User> path = Path.validation(validated);

Lifting to IdPath

// Wrap a pure value
IdPath<String> id = Path.id("hello");

// From existing Id
Id<Integer> idValue = Id.of(42);
IdPath<Integer> idPath = Path.idOf(idValue);

Lifting to OptionalPath

// From Optional
OptionalPath<String> present = Path.optional(Optional.of("hello"));
OptionalPath<String> empty = Path.optional(Optional.empty());

// From nullable value
OptionalPath<String> fromNullable = Path.optionalOfNullable(possiblyNull);

Lifting to GenericPath

// Wrap any Kind with its Monad
Kind<ListKind.Witness, Integer> listKind = ListKind.widen(List.of(1, 2, 3));
GenericPath<ListKind.Witness, Integer> genericList = Path.generic(listKind, ListMonad.INSTANCE);

Terminal Operations

MaybePath Extraction

MaybePath<String> path = Path.just("hello");

// Get underlying Maybe
Maybe<String> maybe = path.run();

// Get or default
String value = path.getOrElse("default");

// Get or compute default
String value = path.getOrElse(() -> computeDefault());

// Get or throw
String value = path.getOrThrow(() -> new NoSuchElementException());

// Check presence
boolean hasValue = path.run().isJust();

EitherPath Extraction

EitherPath<String, Integer> path = Path.right(42);

// Get underlying Either
Either<String, Integer> either = path.run();

// Pattern match with fold
String result = either.fold(
    error -> "Error: " + error,
    value -> "Value: " + value
);

// Get success (throws if Left)
Integer value = either.getRight();

// Get error (throws if Right)
String error = either.getLeft();

// Check state
boolean isSuccess = either.isRight();

TryPath Extraction

TryPath<Integer> path = Path.success(42);

// Get underlying Try
Try<Integer> tryValue = path.run();

// Get or default
Integer value = path.getOrElse(-1);

// Get or compute
Integer value = path.getOrElse(() -> computeDefault());

// Get (may throw)
Integer value = tryValue.get();

// Check state
boolean succeeded = tryValue.isSuccess();

// Get exception (if failure)
Throwable cause = tryValue.getCause();

IOPath Extraction

IOPath<String> path = Path.io(() -> readFile());

// Execute (may throw)
String result = path.unsafeRun();

// Execute safely
Try<String> result = path.runSafe();

// Convert to Try for further composition
TryPath<String> tryPath = path.toTryPath();

ValidationPath Extraction

ValidationPath<List<String>, User> path = validateUser(input);

// Get underlying Validated
Validated<List<String>, User> validated = path.run();

// Pattern match with fold
String result = validated.fold(
    errors -> "Errors: " + errors,
    user -> "Valid: " + user.name()
);

// Check state
boolean isValid = validated.isValid();
boolean isInvalid = validated.isInvalid();

IdPath Extraction

IdPath<String> path = Path.id("hello");

// Get underlying Id
Id<String> id = path.run();

// Get the value (always succeeds)
String value = id.value();
// or
String value = path.get();

OptionalPath Extraction

OptionalPath<String> path = Path.optional(Optional.of("hello"));

// Get underlying Optional
Optional<String> opt = path.run();

// Get or default
String value = opt.orElse("default");

// Get or throw
String value = opt.orElseThrow(() -> new NoSuchElementException());

GenericPath Extraction

GenericPath<MaybeKind.Witness, String> path = Path.generic(
    MaybeKind.widen(maybe), MaybeMonad.INSTANCE);

// Get underlying Kind
Kind<MaybeKind.Witness, String> kind = path.runKind();

// Narrow to concrete type
Maybe<String> maybe = MaybeKind.narrow(kind);

Conversion Chains

Real code often chains multiple conversions:

// Start with Maybe, end with Either with error handling
EitherPath<ServiceError, Order> processOrder(String userId, OrderInput input) {
    return Path.maybe(userRepository.findById(userId))         // MaybePath<User>
        .toEitherPath(() -> new ServiceError.UserNotFound())   // EitherPath<ServiceError, User>
        .via(user -> Path.tryOf(() -> validateOrder(input))    // Chain TryPath
            .toEitherPath(ServiceError.ValidationFailed::new)) // Convert to EitherPath
        .via(validated -> Path.either(createOrder(user, validated)));
}

Best Practices

Convert at Boundaries

Convert at service boundaries, not throughout:

// Good: Convert once at the boundary
public EitherPath<Error, User> getUser(String id) {
    return Path.maybe(repository.findById(id))  // Internal Maybe
        .toEitherPath(() -> Error.notFound(id)); // Convert at boundary
}

// Avoid: Converting back and forth
public EitherPath<Error, User> getUser(String id) {
    return Path.maybe(repository.findById(id))
        .toEitherPath(() -> Error.notFound(id))
        .toMaybePath()  // Why convert back?
        .toEitherPath(() -> Error.notFound(id)); // And forth again?
}

Match Error Granularity

Choose the right error type for the layer:

// Repository: Maybe (absence is normal)
public Maybe<User> findById(String id) { ... }

// Service: Either with domain errors
public EitherPath<UserError, User> getUserById(String id) {
    return Path.maybe(repository.findById(id))
        .toEitherPath(() -> UserError.NOT_FOUND);
}

// Controller: Either with HTTP-friendly errors
public EitherPath<HttpError, UserDto> getUser(String id) {
    return userService.getUserById(id)
        .mapError(this::toHttpError)
        .map(UserDto::from);
}

Summary

Error-Handling Path Conversions

Validation Path Conversions

Utility Path Conversions

Continue to Patterns and Recipes for real-world usage patterns.

Previous: ForPath Comprehension Next: Focus-Effect Integration

Focus-Effect Integration

Bridging Structural Navigation and Effect Composition

"The knife had two edges: one was tempered for common use, but the other was keener than any blade that had ever existed before. It could cut through anything, even the fabric of the universe itself... With the right touch, you could open a window to another world."

— Philip Pullman, The Subtle Knife

The Focus DSL and Effect Paths inhabit different worlds. One navigates the structure of data—drilling into records, unwrapping optionals, traversing collections. The other navigates the shape of computation—handling absence, failure, side effects, accumulated errors. Both worlds have their own grammar, their own rules, their own power.

But like the subtle knife, the bridge API lets you cut cleanly between them.

When you hold structured data and need the railway semantics of effects, the toXxxPath methods open a window from optics into effects. When you're deep in an effect pipeline and need to navigate the contained structure, focus() opens a window back. The passage is seamless. The types guide you. Each world remains itself, but now they connect.

The Two Domains

    ┌─────────────────────────────────────────────────────────────────┐
    │                       OPTICS DOMAIN                             │
    │                                                                 │
    │   FocusPath<S, A>    ───── exactly one focus (Lens)             │
    │   AffinePath<S, A>   ───── zero or one focus (Affine)           │
    │   TraversalPath<S, A> ──── zero or more focuses (Traversal)     │
    │                                                                 │
    │   Navigation: get, set, modify, via(optic)                      │
    └─────────────────────────────────────────────────────────────────┘
                                    │
                                    │  Bridge API
                                    ▼
    ┌─────────────────────────────────────────────────────────────────┐
    │                       EFFECTS DOMAIN                            │
    │                                                                 │
    │   MaybePath<A>         ───── optional value                     │
    │   EitherPath<E, A>     ───── success or typed error             │
    │   TryPath<A>           ───── success or exception               │
    │   IOPath<A>            ───── deferred side effect               │
    │   ValidationPath<E, A> ───── accumulating errors                │
    │                                                                 │
    │   Navigation: map, via(effect), run, recover                    │
    └─────────────────────────────────────────────────────────────────┘

Direction 1: Optics → Effects

When you have a data structure and want to start an effect pipeline, use the toXxxPath methods on Focus paths.

FocusPath Bridge Methods

FocusPath always has a value, so these methods always produce successful effects:

FocusPath<User, String> namePath = UserFocus.name();
User alice = new User("Alice", Optional.of("alice@example.com"));

// Lift into different effect types
MaybePath<String> maybeName = namePath.toMaybePath(alice);     // → Just("Alice")
EitherPath<E, String> eitherName = namePath.toEitherPath(alice); // → Right("Alice")
TryPath<String> tryName = namePath.toTryPath(alice);           // → Success("Alice")
IdPath<String> idName = namePath.toIdPath(alice);              // → Id("Alice")

AffinePath Bridge Methods

AffinePath may not have a value, so these methods require error handling:

AffinePath<User, String> emailPath = UserFocus.email(); // Optional<String> → String

User withEmail = new User("Alice", Optional.of("alice@example.com"));
User withoutEmail = new User("Bob", Optional.empty());

// MaybePath: absence becomes Nothing
emailPath.toMaybePath(withEmail);    // → Just("alice@example.com")
emailPath.toMaybePath(withoutEmail); // → Nothing

// EitherPath: provide error for absence
emailPath.toEitherPath(withEmail, "No email");    // → Right("alice@example.com")
emailPath.toEitherPath(withoutEmail, "No email"); // → Left("No email")

// TryPath: provide exception supplier for absence
emailPath.toTryPath(withEmail, () -> new MissingEmailException());    // → Success
emailPath.toTryPath(withoutEmail, () -> new MissingEmailException()); // → Failure

TraversalPath Bridge Methods

TraversalPath focuses on multiple values:

TraversalPath<Company, User> employeesPath = CompanyFocus.employees();
Company company = new Company("TechCorp", List.of(alice, bob, charlie));

// ListPath: all values as a list
ListPath<User> allEmployees = employeesPath.toListPath(company);

// StreamPath: lazy stream
StreamPath<User> employeeStream = employeesPath.toStreamPath(company);

// MaybePath: first value (or Nothing)
MaybePath<User> firstEmployee = employeesPath.toMaybePath(company);

Bridge Method Summary

Direction 2: Effects → Optics

When you're already in an effect context and need to navigate into the contained value, use the focus() method.

Basic focus() Usage

// Start with an effect containing structured data
EitherPath<Error, User> userResult = fetchUser(userId);

// Navigate into the structure
FocusPath<User, String> namePath = UserFocus.name();
EitherPath<Error, String> nameResult = userResult.focus(namePath);

// The effect semantics are preserved
// If userResult was Left(error), nameResult is also Left(error)
// If userResult was Right(user), nameResult is Right(user.name())

focus() with AffinePath

When the navigation might fail (AffinePath), you must provide an error for the absent case:

AffinePath<User, String> emailPath = UserFocus.email();

// EitherPath requires an error value
EitherPath<Error, String> emailResult =
    userResult.focus(emailPath, new Error("Email not configured"));

// TryPath requires an exception supplier
TryPath<String> emailTry =
    userTryPath.focus(emailPath, () -> new MissingEmailException());

// MaybePath just becomes Nothing (no error needed)
MaybePath<String> emailMaybe = userMaybePath.focus(emailPath);

Effect-Specific focus() Behaviour

Practical Patterns

Pattern 1: Extract and Validate

The problem: You have nested data and need to extract and validate specific fields.

The solution:

EitherPath<List<String>, User> validateUser(User user) {
    FocusPath<User, String> namePath = UserFocus.name();
    AffinePath<User, String> emailPath = UserFocus.email();

    return Path.<List<String>, User>right(user)
        .via(u -> {
            // Validate name length
            String name = namePath.get(u);
            if (name.length() < 2) {
                return Path.left(List.of("Name too short"));
            }
            return Path.right(u);
        })
        .via(u -> {
            // Validate email if present
            return emailPath.toEitherPath(u, List.of("Email required"))
                .via(email -> email.contains("@")
                    ? Path.right(u)
                    : Path.left(List.of("Invalid email format")));
        });
}

Pattern 2: Nested Service Results

The problem: Service calls return effects, and you need to extract nested data.

The solution:

EitherPath<Error, String> getOrderCustomerCity(OrderId orderId) {
    return orderService.findById(orderId)           // → EitherPath<Error, Order>
        .focus(OrderFocus.customer())               // → EitherPath<Error, Customer>
        .focus(CustomerFocus.address())             // → EitherPath<Error, Address>
        .focus(AddressFocus.city());                // → EitherPath<Error, String>
}

Pattern 3: Safe Deep Access

The problem: Accessing deeply nested optional data without null checks.

The solution:

// Traditional approach (pyramid of doom)
String getManagerEmail(Company company) {
    Department dept = company.getDepartment(0);
    if (dept == null) return "unknown";
    Employee manager = dept.getManager();
    if (manager == null) return "unknown";
    String email = manager.getEmail();
    return email != null ? email : "unknown";
}

// Focus-Effect approach
String getManagerEmail(Company company) {
    return CompanyFocus.department(0)
        .toMaybePath(company)                       // → MaybePath<Department>
        .focus(DepartmentFocus.manager())           // → MaybePath<Employee>
        .focus(EmployeeFocus.email())               // → MaybePath<String>
        .getOrElse("unknown");
}

Pattern 4: Batch Processing with Traversals

The problem: Apply an effectful operation to all items in a collection.

The solution:

// Validate all employee emails
ValidationPath<List<String>, Company> validateAllEmails(Company company) {
    return CompanyFocus.employees()
        .toListPath(company)
        .via(employees -> {
            // Validate each employee's email
            var results = employees.stream()
                .map(e -> EmployeeFocus.email()
                    .toEitherPath(e, List.of("Missing email for " + e.name())))
                .toList();
            // Combine results...
        });
}

When to Use Which

Decision Flow

Start with...
    │
    ├─► Concrete data?
    │       │
    │       └─► Use FocusPath.toXxxPath(data) to enter effect domain
    │
    └─► Effect containing data?
            │
            ├─► Need to navigate structure?
            │       │
            │       └─► Use effectPath.focus(opticPath)
            │
            ├─► Need to chain effects?
            │       │
            │       └─► Use effectPath.via(f)
            │
            └─► Need to transform value?
                    │
                    └─► Use effectPath.map(f)

Composing Both Directions

The most powerful patterns combine both directions fluently:

// Complete workflow: fetch → navigate → validate → transform → save
EitherPath<Error, SaveResult> processUserUpdate(UserId userId, UpdateRequest request) {
    return userService.findById(userId)                    // Effect: fetch user
        .focus(UserFocus.profile())                        // Optics: navigate to profile
        .via(profile -> {                                  // Effect: validate
            return ProfileFocus.email()
                .toEitherPath(profile, Error.missingEmail())
                .via(email -> validateEmail(email));
        })
        .via(validEmail -> {                               // Effect: apply update
            return applyUpdate(request, validEmail);
        })
        .via(updated -> {                                  // Effect: save
            return userService.save(updated);
        });
}

Previous: Type Conversions Next: Patterns and Recipes

Patterns and Recipes

"When the going gets weird, the weird turn professional."

— Hunter S. Thompson, Fear and Loathing on the Campaign Trail '72

Every codebase eventually gets weird. Edge cases multiply. Requirements contradict. Legacy systems refuse to behave. The patterns in this chapter are for those moments: tested approaches from production code where the weird was met professionally.

These aren't academic exercises. They're recipes that survived contact with reality.

Validation Pipelines

User input arrives untrustworthy. Every field might be missing, malformed, or actively hostile. Traditional validation scatters null checks and conditionals throughout your code. Path types let you build validation as composable pipelines where each rule is small, testable, and reusable.

Single Field Validation

Each field gets its own validation function returning a Path:

private EitherPath<String, String> validateEmail(String email) {
    if (email == null || email.isBlank()) {
        return Path.left("Email is required");
    }
    if (!email.contains("@")) {
        return Path.left("Email must contain @");
    }
    if (!email.contains(".")) {
        return Path.left("Email must contain a domain");
    }
    return Path.right(email.toLowerCase().trim());
}

Or with modern pattern matching:

private EitherPath<String, String> validateEmail(String email) {
    return switch (email) {
        case null -> Path.left("Email is required");
        case String e when e.isBlank() -> Path.left("Email is required");
        case String e when !e.contains("@") -> Path.left("Email must contain @");
        case String e when !e.contains(".") -> Path.left("Email must have a domain");
        case String e -> Path.right(e.toLowerCase().trim());
    };
}

The validated value may be transformed (lowercase, trimmed); the Path carries the clean version forward.

Combining Validations (Fail-Fast)

When all fields must be valid to proceed:

record User(String name, String email, int age) {}

EitherPath<String, User> validateUser(UserInput input) {
    return validateName(input.name())
        .zipWith3(
            validateEmail(input.email()),
            validateAge(input.age()),
            User::new
        );
}

First failure stops processing. For user-facing forms, this is often too abrupt; see the next pattern.

Combining Validations (Accumulating)

When users deserve to see all problems at once:

ValidationPath<List<String>, User> validateUser(UserInput input) {
    return validateNameV(input.name())
        .zipWith3Accum(
            validateEmailV(input.email()),
            validateAgeV(input.age()),
            User::new
        );
}

// Usage
validateUser(input).run().fold(
    errors -> showAllErrors(errors),  // ["Name too short", "Invalid email"]
    user -> proceed(user)
);

The difference is respect for the user's time.

Nested Validation

Complex objects with nested structures:

record Registration(User user, Address address, List<Preference> prefs) {}

EitherPath<String, Registration> validateRegistration(RegistrationInput input) {
    EitherPath<String, User> user = validateUser(input.user());

    EitherPath<String, Address> address = validateStreet(input.street())
        .zipWith3(
            validateCity(input.city()),
            validatePostcode(input.postcode()),
            Address::new
        );

    EitherPath<String, List<Preference>> prefs =
        validatePreferences(input.preferences());

    return user.zipWith3(address, prefs, Registration::new);
}

Each sub-validation is independent; they combine at the end.

Service Layer Patterns

Services orchestrate multiple operations: fetching data, applying business rules, calling external systems. Each step might fail differently. Path types make the orchestration explicit.

Repository Pattern

Repositories return Maybe (absence is expected). Services convert to Either (absence becomes an error in context):

public class UserRepository {
    public Maybe<User> findById(String id) {
        return Maybe.fromOptional(
            jdbcTemplate.queryForOptional("SELECT...", id)
        );
    }

    public Maybe<User> findByEmail(String email) {
        return Maybe.fromOptional(
            jdbcTemplate.queryForOptional("SELECT...", email)
        );
    }
}

public class UserService {
    private final UserRepository repository;

    public EitherPath<UserError, User> getById(String id) {
        return Path.maybe(repository.findById(id))
            .toEitherPath(() -> new UserError.NotFound(id));
    }

    public EitherPath<UserError, User> getByEmail(String email) {
        return Path.maybe(repository.findByEmail(email))
            .toEitherPath(() -> new UserError.NotFound(email));
    }
}

The conversion happens at the layer boundary. Repository callers get Maybe; service callers get Either with meaningful errors.

Chained Service Calls

When each step depends on the previous:

public class OrderService {
    private final UserService users;
    private final InventoryService inventory;
    private final PaymentService payments;

    public EitherPath<OrderError, Order> placeOrder(
            String userId, List<Item> items) {
        return users.getById(userId)
            .mapError(OrderError::fromUserError)
            .via(user -> inventory.reserve(items)
                .mapError(OrderError::fromInventoryError))
            .via(reservation -> payments.charge(user, reservation.total())
                .mapError(OrderError::fromPaymentError))
            .via(payment -> Path.right(
                createOrder(user, items, payment)));
    }
}

Each mapError translates the sub-service error into the order domain. The final Order is created only if all steps succeed.

Service with Fallbacks

When multiple sources can satisfy a request:

public class ConfigService {
    public EitherPath<ConfigError, Config> loadConfig() {
        return Path.either(loadFromFile())
            .recoverWith(e -> {
                log.warn("File config unavailable: {}", e.getMessage());
                return Path.either(loadFromEnvironment());
            })
            .recoverWith(e -> {
                log.warn("Env config unavailable: {}", e.getMessage());
                return Path.right(Config.defaults());
            });
    }
}

The logs record what was tried; the caller gets a working config or a clear failure.

IO Effect Patterns

Resource Management

Acquire, use, release, regardless of success or failure:

public class FileProcessor {
    public IOPath<ProcessResult> process(Path path) {
        return Path.io(() -> new BufferedReader(new FileReader(path.toFile())))
            .via(reader -> Path.io(() -> processContent(reader)))
            .ensuring(() -> {
                // Cleanup runs regardless of outcome
                log.debug("Processing complete: {}", path);
            });
    }
}

For true resource safety with acquisition and release:

public IOPath<Result> withConnection(Function<Connection, Result> action) {
    return Path.io(() -> dataSource.getConnection())
        .via(conn -> Path.io(() -> action.apply(conn))
            .ensuring(() -> {
                try { conn.close(); }
                catch (SQLException e) { log.warn("Close failed", e); }
            }));
}

Composing Effect Pipelines

Build complex pipelines that execute later:

public class DataPipeline {
    public IOPath<Report> generateReport(ReportRequest request) {
        return Path.io(() -> log.info("Starting report: {}", request.id()))
            .then(() -> Path.io(() -> fetchData(request)))
            .via(data -> Path.io(() -> transform(data)))
            .via(transformed -> Path.io(() -> aggregate(transformed)))
            .via(aggregated -> Path.io(() -> format(aggregated)))
            .peek(report -> log.info("Report ready: {} rows", report.rowCount()));
    }
}

// Nothing happens until:
Report report = pipeline.generateReport(request).unsafeRun();

Expressing Parallel Intent

While IOPath doesn't parallelise automatically, zipWith expresses independence:

IOPath<CombinedData> fetchAll() {
    IOPath<UserData> users = Path.io(() -> fetchUsers());
    IOPath<ProductData> products = Path.io(() -> fetchProducts());
    IOPath<OrderData> orders = Path.io(() -> fetchOrders());

    return users.zipWith3(products, orders, CombinedData::new);
}

A more sophisticated runtime could parallelise these. For now, they execute in sequence, but the structure is clear.

Error Handling Strategies

Error Enrichment

Add context as errors propagate through layers:

public <A> EitherPath<DetailedError, A> withContext(
        EitherPath<Error, A> path,
        String operation,
        Map<String, Object> context) {
    return path.mapError(error -> new DetailedError(
        error,
        operation,
        context,
        Instant.now()
    ));
}

// Usage
return withContext(
    userService.getUser(id),
    "getUser",
    Map.of("userId", id, "requestId", requestId)
);

When the error surfaces, you know what was happening and with what parameters.

Recovery with Logging

Log the failure, provide a fallback:

public <A> EitherPath<Error, A> withRecoveryLogging(
        EitherPath<Error, A> path,
        A fallback,
        String operation) {
    return path.recover(error -> {
        log.warn("Operation '{}' failed: {}. Using fallback.",
            operation, error);
        return fallback;
    });
}

Circuit Breaker

Stop calling a failing service:

public class CircuitBreaker<E, A> {
    private final AtomicInteger failures = new AtomicInteger(0);
    private final int threshold;
    private final Supplier<EitherPath<E, A>> fallback;

    public EitherPath<E, A> execute(Supplier<EitherPath<E, A>> operation) {
        if (failures.get() >= threshold) {
            log.debug("Circuit open, using fallback");
            return fallback.get();
        }

        return operation.get()
            .peek(success -> failures.set(0))
            .recoverWith(error -> {
                int count = failures.incrementAndGet();
                log.warn("Failure {} of {}", count, threshold);
                return Path.left(error);
            });
    }
}

A proper implementation would include timeouts and half-open states. This shows the pattern.

Resilience: Retry with Backoff

"The protocol specified exponential backoff: wait one second, try again; wait two seconds, try again; wait four seconds..."

— Neal Stephenson, Cryptonomicon

Transient failures—network blips, brief overloads—often succeed on retry. But retrying immediately can worsen the problem. The RetryPolicy API provides configurable backoff strategies.

Creating Retry Policies

// Fixed delay: 100ms between each of 3 attempts
RetryPolicy fixed = RetryPolicy.fixed(3, Duration.ofMillis(100));

// Exponential backoff: 1s, 2s, 4s, 8s...
RetryPolicy exponential = RetryPolicy.exponentialBackoff(5, Duration.ofSeconds(1));

// With jitter to prevent thundering herd
RetryPolicy jittered = RetryPolicy.exponentialBackoffWithJitter(5, Duration.ofSeconds(1));

Applying Retry to Paths

IOPath<Response> resilient = IOPath.delay(() -> httpClient.get(url))
    .withRetry(RetryPolicy.exponentialBackoff(3, Duration.ofSeconds(1)));

// Convenience method for simple cases
IOPath<Response> simple = IOPath.delay(() -> httpClient.get(url))
    .retry(3);  // Uses default exponential backoff

Configuring Retry Behaviour

Policies are immutable but configurable:

RetryPolicy policy = RetryPolicy.exponentialBackoff(5, Duration.ofMillis(100))
    .withMaxDelay(Duration.ofSeconds(30))   // Cap maximum wait
    .retryOn(IOException.class);             // Only retry I/O errors

Selective Retry

Not all errors should trigger retry:

RetryPolicy selective = RetryPolicy.fixed(3, Duration.ofMillis(100))
    .retryIf(ex ->
        ex instanceof IOException ||
        ex instanceof TimeoutException ||
        (ex instanceof HttpException http && http.statusCode() >= 500));

Combining Retry with Fallback

IOPath<Data> robust = fetchFromPrimary()
    .withRetry(RetryPolicy.exponentialBackoff(3, Duration.ofSeconds(1)))
    .handleErrorWith(e -> {
        log.warn("Primary exhausted, trying backup");
        return fetchFromBackup()
            .withRetry(RetryPolicy.fixed(2, Duration.ofMillis(100)));
    })
    .recover(e -> {
        log.error("All sources failed", e);
        return Data.empty();
    });

Handling Exhausted Retries

When all attempts fail, RetryExhaustedException is thrown:

try {
    resilient.unsafeRun();
} catch (RetryExhaustedException e) {
    log.error("All retries failed: {}", e.getMessage());
    Throwable lastFailure = e.getCause();
    return fallbackValue;
}

Retry Pattern Quick Reference

Testing Patterns

Path-returning methods are straightforward to test. The explicit success/failure encoding means you can verify both paths without exception handling gymnastics.

Testing Success and Failure

@Test
void shouldReturnUserWhenFound() {
    when(repository.findById("123")).thenReturn(Maybe.just(testUser));

    EitherPath<UserError, User> result = service.getUser("123");

    assertThat(result.run().isRight()).isTrue();
    assertThat(result.run().getRight()).isEqualTo(testUser);
}

@Test
void shouldReturnErrorWhenNotFound() {
    when(repository.findById("123")).thenReturn(Maybe.nothing());

    EitherPath<UserError, User> result = service.getUser("123");

    assertThat(result.run().isLeft()).isTrue();
    assertThat(result.run().getLeft()).isInstanceOf(UserError.NotFound.class);
}

Testing Error Propagation

Verify that errors from nested operations surface correctly:

@Test
void shouldPropagatePaymentError() {
    when(userService.getUser(any())).thenReturn(Path.right(testUser));
    when(inventory.check(any())).thenReturn(Path.right(availability));
    when(payments.charge(any(), any()))
        .thenReturn(Path.left(new PaymentError("Declined")));

    EitherPath<OrderError, Order> result = orderService.placeOrder(request);

    assertThat(result.run().isLeft()).isTrue();
    assertThat(result.run().getLeft())
        .isInstanceOf(OrderError.PaymentFailed.class);

    // Order creation should never be called
    verify(orderRepository, never()).save(any());
}

Property-Based Testing

Use jqwik or similar to verify laws across many inputs:

@Property
void functorIdentityLaw(@ForAll @StringLength(min = 1, max = 100) String value) {
    MaybePath<String> path = Path.just(value);
    MaybePath<String> mapped = path.map(Function.identity());

    assertThat(mapped.run()).isEqualTo(path.run());
}

@Property
void recoverAlwaysSucceeds(
        @ForAll String errorMessage,
        @ForAll String fallback) {
    EitherPath<String, String> failed = Path.left(errorMessage);
    EitherPath<String, String> recovered = failed.recover(e -> fallback);

    assertThat(recovered.run().isRight()).isTrue();
    assertThat(recovered.run().getRight()).isEqualTo(fallback);
}

Testing Deferred Effects

Verify that IOPath defers execution:

@Test
void shouldDeferExecution() {
    AtomicInteger callCount = new AtomicInteger(0);
    IOPath<Integer> io = Path.io(() -> callCount.incrementAndGet());

    assertThat(callCount.get()).isEqualTo(0);  // Not yet

    int result = io.unsafeRun();

    assertThat(callCount.get()).isEqualTo(1);  // Now
    assertThat(result).isEqualTo(1);
}

@Test
void shouldCaptureExceptionInRunSafe() {
    IOPath<String> failing = Path.io(() -> {
        throw new RuntimeException("test error");
    });

    Try<String> result = failing.runSafe();

    assertThat(result.isFailure()).isTrue();
    assertThat(result.getCause().getMessage()).isEqualTo("test error");
}

Integration with Existing Code

Real projects have legacy code that throws exceptions, returns Optional, or uses patterns that predate functional error handling.

Wrapping Exception-Throwing APIs

public class LegacyWrapper {
    private final LegacyService legacy;

    public TryPath<Data> fetchData(String id) {
        return Path.tryOf(() -> legacy.fetchData(id));
    }

    public EitherPath<ServiceError, Data> fetchDataSafe(String id) {
        return Path.tryOf(() -> legacy.fetchData(id))
            .toEitherPath(ex -> new ServiceError("Fetch failed", ex));
    }
}

Wrapping Optional-Returning APIs

public class ModernWrapper {
    private final ModernService modern;

    public MaybePath<User> findUser(String id) {
        return Path.maybe(Maybe.fromOptional(modern.findUser(id)));
    }
}

Exposing to Non-Path Consumers

When callers expect traditional patterns:

public class ServiceAdapter {
    private final PathBasedService service;

    // For consumers expecting Optional
    public Optional<User> findUser(String id) {
        return service.findUser(id).run().toOptional();
    }

    // For consumers expecting exceptions
    public User getUser(String id) throws UserNotFoundException {
        Either<UserError, User> result = service.getUser(id).run();
        if (result.isLeft()) {
            throw new UserNotFoundException(result.getLeft().message());
        }
        return result.getRight();
    }
}

Common Pitfalls

Pitfall 1: Excessive Conversion

// Wasteful
Path.maybe(findUser(id))
    .toEitherPath(() -> error)
    .toMaybePath()
    .toEitherPath(() -> error);

// Clean
Path.maybe(findUser(id))
    .toEitherPath(() -> error);

Pitfall 2: Side Effects in Pure Operations

// Wrong
path.map(user -> {
    auditLog.record(user);  // Side effect in map!
    return user;
});

// Right
path.peek(user -> auditLog.record(user));

Pitfall 3: Ignoring the Result

// Bug: result discarded, nothing happens
void processOrder(OrderRequest request) {
    validateAndProcess(request);  // Returns EitherPath, ignored
}

// Fixed
void processOrder(OrderRequest request) {
    validateAndProcess(request).run();  // Actually execute
}

Pitfall 4: Treating All Errors the Same

// Loses information
.mapError(e -> "An error occurred")

// Preserves structure
.mapError(e -> new DomainError(e.code(), e.message(), e))

Quick Reference

Summary

The patterns in this chapter share a common theme: making the implicit explicit. Error handling becomes visible in the types. Composition becomes visible in the pipeline. Dependencies become visible in the choice of via vs zipWith.

When the going gets weird (and it will), these patterns are your professional toolkit. They won't make the weirdness go away, but they'll help you handle it with composure.

Continue to Advanced Effects for Reader, State, and Writer patterns.

Previous: Focus-Effect Integration Next: Advanced Effects

Advanced Effects

"We are surrounded by huge institutions we can never penetrate... They've made themselves user-friendly, but they define the tastes to which we conform. They're rather subtle, subservient tyrannies, but no less sinister for that."

— J.G. Ballard

Ballard was describing the modern landscape of invisible systems: banks, networks, bureaucracies that shape our choices while remaining opaque. Software faces the same challenge. Configuration systems, database connections, logging infrastructure. These are the "institutions" your code must navigate. They're everywhere, they're necessary, and handling them explicitly at every call site creates clutter that obscures your actual logic.

This chapter introduces three effect types that model these pervasive concerns: Reader for environment access, State for threaded computation state, and Writer for accumulated output. Each represents a different kind of computational context that you'd otherwise pass explicitly through every function signature.

ReaderPath: The Environment You Inherit

ReaderPath<R, A> wraps Reader<R, A>, representing a computation that needs access to an environment of type R to produce a value of type A.

Think of it as implicit parameter passing. Instead of threading a Config or DatabaseConnection through every method signature, you describe computations that assume the environment exists, then provide it once at the edge of your system.

Why Reader?

Consider a typical service method:

// Without Reader: environment threaded explicitly
public User getUser(String id, DbConnection db, Config config, Logger log) {
    log.debug("Fetching user: " + id);
    int timeout = config.getTimeout();
    return db.query("SELECT * FROM users WHERE id = ?", id);
}

Every function in the call chain needs these parameters. The signatures become cluttered; the actual logic is buried.

With Reader:

// With Reader: environment is implicit
public ReaderPath<AppEnv, User> getUser(String id) {
    return ReaderPath.ask()
        .via(env -> {
            env.logger().debug("Fetching user: " + id);
            return ReaderPath.pure(
                env.db().query("SELECT * FROM users WHERE id = ?", id)
            );
        });
}

The environment is accessed when needed but not passed explicitly. The method signature shows what it computes, not what it requires.

Creation

// Pure value (ignores environment)
ReaderPath<Config, String> pure = ReaderPath.pure("hello");

// Access the environment
ReaderPath<Config, Config> askAll = ReaderPath.ask();

// Project part of the environment
ReaderPath<Config, String> dbUrl = ReaderPath.asks(Config::databaseUrl);

// From a Reader function
ReaderPath<Config, Integer> timeout = ReaderPath.of(config -> config.timeout());

Core Operations

ReaderPath<Config, String> dbUrl = ReaderPath.asks(Config::databaseUrl);

// Transform
ReaderPath<Config, Integer> urlLength = dbUrl.map(String::length);

// Chain dependent computations
ReaderPath<Config, Connection> connection =
    dbUrl.via(url -> ReaderPath.of(config ->
        DriverManager.getConnection(url, config.username(), config.password())
    ));

Running a Reader

Eventually you must provide the environment:

Config config = loadConfig();

ReaderPath<Config, User> userPath = getUser("123");
User user = userPath.run(config);  // Provide environment here

The Reader executes with the given environment. All ask and asks calls within the computation receive this environment.

Local Environment Modification

Sometimes a sub-computation needs a modified environment:

ReaderPath<Config, Result> withTestMode =
    computation.local(config -> config.withTestMode(true));

The inner computation sees the modified environment; the outer computation is unaffected.

When to Use ReaderPath

ReaderPath is right when:

• Multiple functions need the same "context" (config, connection, logger)
• You want dependency injection without frameworks
• Computations should be testable with different environments
• You're building a DSL where environment is implicit

ReaderPath is wrong when:

• The environment changes during computation: use StatePath
• You need to accumulate results: use WriterPath
• The environment is only needed in one place: just pass it directly

StatePath: Computation with Memory

StatePath<S, A> wraps State<S, A>, representing a computation that threads state through a sequence of operations. Each step can read the current state, produce a value, and update the state for subsequent steps.

Unlike mutable state, StatePath keeps everything pure: the "mutation" is actually a transformation that produces new state values.

Why State?

Consider tracking statistics through a pipeline:

// Without State: manual state threading
Stats stats1 = new Stats();
ResultA a = processA(input, stats1);
Stats stats2 = stats1.incrementProcessed();
ResultB b = processB(a, stats2);
Stats stats3 = stats2.incrementProcessed();
// ... and so on

With State:

// With State: automatic threading
StatePath<Stats, ResultC> pipeline =
    StatePath.of(processA(input))
        .via(a -> StatePath.modify(Stats::incrementProcessed)
            .then(() -> StatePath.of(processB(a))))
        .via(b -> StatePath.modify(Stats::incrementProcessed)
            .then(() -> StatePath.of(processC(b))));

Tuple2<Stats, ResultC> result = pipeline.run(Stats.initial());

The state threads through automatically. Each step can read it, modify it, or ignore it.

Creation

// Pure value (state unchanged)
StatePath<Counter, String> pure = StatePath.pure("hello");

// Get current state
StatePath<Counter, Counter> current = StatePath.get();

// Set new state (discards old)
StatePath<Counter, Unit> reset = StatePath.set(Counter.zero());

// Modify state
StatePath<Counter, Unit> increment = StatePath.modify(Counter::increment);

// Get and modify in one step
StatePath<Counter, Integer> getAndIncrement =
    StatePath.getAndModify(counter -> {
        int value = counter.value();
        return Tuple.of(counter.increment(), value);
    });

Core Operations

StatePath<Counter, Integer> current = StatePath.get().map(Counter::value);

// Chain with state threading
StatePath<Counter, String> counted =
    StatePath.modify(Counter::increment)
        .then(() -> StatePath.get())
        .map(c -> "Count: " + c.value());

// Combine independent state operations
StatePath<Counter, Result> combined =
    operationA.zipWith(operationB, Result::new);

Running State

Counter initial = Counter.zero();

StatePath<Counter, String> computation = ...;

// Get both final state and result
Tuple2<Counter, String> both = computation.run(initial);

// Get just the result
String result = computation.eval(initial);

// Get just the final state
Counter finalState = computation.exec(initial);

When to Use StatePath

StatePath is right when:

• You need to accumulate or track information through a computation
• Multiple operations must coordinate through shared state
• You're implementing state machines or interpreters
• You want mutable-like semantics with immutable guarantees

StatePath is wrong when:

• State never changes: use ReaderPath
• You're accumulating a log rather than replacing state: use WriterPath
• The state is external (database, file): use IOPath

WriterPath: Accumulating Output

WriterPath<W, A> wraps Writer<W, A>, representing a computation that produces both a value and accumulated output. The output (type W) is combined using a Monoid, allowing automatic aggregation of logs, metrics, or any combinable data.

Why Writer?

Consider building an audit trail:

// Without Writer: manual log passing
public Tuple2<List<String>, User> createUser(UserInput input, List<String> log) {
    List<String> log2 = append(log, "Validating input");
    Validated validated = validate(input);
    List<String> log3 = append(log2, "Creating user record");
    User user = repository.save(validated);
    List<String> log4 = append(log3, "User created: " + user.id());
    return Tuple.of(log4, user);
}

With Writer:

// With Writer: automatic log accumulation
public WriterPath<List<String>, User> createUser(UserInput input) {
    return WriterPath.tell(List.of("Validating input"))
        .then(() -> WriterPath.pure(validate(input)))
        .via(validated -> WriterPath.tell(List.of("Creating user record"))
            .then(() -> WriterPath.pure(repository.save(validated))))
        .via(user -> WriterPath.tell(List.of("User created: " + user.id()))
            .map(unit -> user));
}

The log accumulates automatically. No explicit threading required.

Creation

// Pure value (empty log)
WriterPath<List<String>, Integer> pure = WriterPath.pure(42, Monoids.list());

// Write to log (no value)
WriterPath<List<String>, Unit> logged =
    WriterPath.tell(List.of("Something happened"), Monoids.list());

// Create with both value and log
WriterPath<List<String>, User> withLog =
    WriterPath.of(user, List.of("Created user"), Monoids.list());

The Monoid<W> parameter defines how log entries combine:

• Monoids.list(): concatenate lists
• Monoids.string(): concatenate strings
• Custom monoids for metrics, events, etc.

Core Operations

WriterPath<List<String>, Integer> computation = ...;

// Transform value (log unchanged)
WriterPath<List<String>, String> formatted = computation.map(n -> "Value: " + n);

// Add to log
WriterPath<List<String>, Integer> withExtra =
    computation.tell(List.of("Extra info"));

// Chain with log accumulation
WriterPath<List<String>, Result> pipeline =
    stepOne()
        .via(a -> stepTwo(a))
        .via(b -> stepThree(b));
// Logs from all three steps combine automatically

Running Writer

WriterPath<List<String>, User> computation = createUser(input);

// Get both log and result
Tuple2<List<String>, User> both = computation.run();

// Get just the result
User user = computation.value();

// Get just the log
List<String> log = computation.written();

When to Use WriterPath

WriterPath is right when:

• You're building audit trails or structured logs
• Accumulating metrics or statistics
• Collecting warnings or diagnostics alongside computation
• Any scenario where output should aggregate, not replace

WriterPath is wrong when:

• Output should replace previous output: use StatePath
• You need to read accumulated output mid-computation: use StatePath
• Output goes to external systems: use IOPath

Combining Advanced Effects

These effect types compose with each other and with the core Path types.

Reader + Either: Environment with Errors

// A computation that needs config and might fail
ReaderPath<Config, EitherPath<Error, User>> getUser(String id) {
    return ReaderPath.asks(Config::database)
        .map(db -> Path.either(db.findUser(id))
            .toEitherPath(() -> new Error.NotFound(id)));
}

State + Writer: State with Logging

// Track state and log what happens
public StatePath<GameState, WriterPath<List<Event>, Move>> makeMove(Position pos) {
    return StatePath.get()
        .via(state -> {
            Move move = calculateMove(state, pos);
            GameState newState = state.apply(move);
            return StatePath.set(newState)
                .map(unit -> WriterPath.of(
                    move,
                    List.of(new Event.MoveMade(pos, move)),
                    Monoids.list()
                ));
        });
}

Patterns: Configuration Service

public class ConfigurableService {
    public ReaderPath<ServiceConfig, EitherPath<Error, Result>> process(Request req) {
        return ReaderPath.ask()
            .via(config -> {
                if (!config.isEnabled()) {
                    return ReaderPath.pure(Path.left(new Error.ServiceDisabled()));
                }
                return ReaderPath.pure(
                    Path.tryOf(() -> doProcess(req, config))
                        .toEitherPath(Error.ProcessingFailed::new)
                );
            });
    }
}

// Usage
ServiceConfig config = loadConfig();
EitherPath<Error, Result> result = service.process(request).run(config);

Patterns: Audit Trail

public class AuditedRepository {
    public WriterPath<List<AuditEvent>, EitherPath<Error, User>> saveUser(User user) {
        return WriterPath.tell(List.of(new AuditEvent.AttemptSave(user.id())))
            .then(() -> {
                Either<Error, User> result = repository.save(user);
                if (result.isRight()) {
                    return WriterPath.of(
                        Path.right(result.getRight()),
                        List.of(new AuditEvent.SaveSucceeded(user.id())),
                        Monoids.list()
                    );
                } else {
                    return WriterPath.of(
                        Path.left(result.getLeft()),
                        List.of(new AuditEvent.SaveFailed(user.id(), result.getLeft())),
                        Monoids.list()
                    );
                }
            });
    }
}

Summary

These effects handle the "invisible institutions" of software: the configuration that's everywhere, the state that threads through, the logs that accumulate. By making them explicit in the type system, you gain the same composability and predictability that the core Path types provide for error handling.

The systems remain subtle and pervasive, but no longer tyrannical.

Previous: Patterns and Recipes Next: Effect Contexts

Effect Contexts: Taming Transformer Power

"Evrything has a shape and so does the nite only you cant see the shape of nite nor you cant think it."

— Russell Hoban, Riddley Walker

Hoban's narrator speaks of invisible shapes—structures that exist whether or not we perceive them. Monad transformers are like this. EitherT<IOKind.Witness, ApiError, User> has a definite shape: it's a computation that defers execution, might fail with a typed error, and produces a user when successful. The shape is there. But the syntax makes it hard to see, hard to think.

Effect Contexts give that shape a face you can recognise.

They're a middle layer between the simple Path types you've already learned and the raw transformers lurking beneath. When EitherPath isn't quite enough—when you need error handling and deferred execution, or optional values and IO effects—Effect Contexts provide a user-friendly API that hides the transformer machinery while preserving its power.

The Problem: Transformer Syntax

Consider a typical API call. It might fail. It uses IO. You want typed errors. The raw transformer approach looks like this:

// Raw transformer: correct but noisy
EitherTMonad<IOKind.Witness, ApiError> monad = new EitherTMonad<>(IOMonad.INSTANCE);

Kind<EitherTKind.Witness<IOKind.Witness, ApiError>, User> userKind =
    EitherT.fromKind(IO_OP.widen(IO.delay(() -> {
        try {
            return Either.right(userService.fetch(userId));
        } catch (Exception e) {
            return Either.left(new ApiError(e.getMessage()));
        }
    })));

Kind<EitherTKind.Witness<IOKind.Witness, ApiError>, Profile> profileKind =
    monad.flatMap(user ->
        EitherT.fromKind(IO_OP.widen(IO.delay(() -> {
            try {
                return Either.right(profileService.fetch(user.profileId()));
            } catch (Exception e) {
                return Either.left(new ApiError(e.getMessage()));
            }
        }))),
        userKind);

The business logic—fetch a user, then fetch their profile—is drowning in ceremony. You're manually constructing witnesses, wrapping IO, handling Kind types, threading monads. The what disappears into the how.

The Solution: Effect Contexts

The same logic with ErrorContext:

// Effect Context: same power, readable syntax
ErrorContext<IOKind.Witness, ApiError, Profile> profile = ErrorContext
    .<ApiError, User>io(
        () -> userService.fetch(userId),
        ApiError::fromException)
    .via(user -> ErrorContext.io(
        () -> profileService.fetch(user.profileId()),
        ApiError::fromException));

Either<ApiError, Profile> result = profile.runIO().unsafeRun();

The transformer is still there—ErrorContext wraps EitherT—but the API speaks in terms you recognise: io() for effectful computation, via() for chaining, runIO() to execute. The shape of the computation emerges from the noise.

The Three-Layer Architecture

Higher-Kinded-J provides three ways to work with combined effects, each serving different needs:

┌─────────────────────────────────────────────────────────────────┐
│  LAYER 1: Effect Path API                                       │
│  ─────────────────────────                                      │
│                                                                 │
│  EitherPath, MaybePath, TryPath, IOPath, ValidationPath...      │
│                                                                 │
│  ✓ Simple, fluent API                                           │
│  ✓ Single effect per path                                       │
│  ✓ Best for: Most application code                              │
│                                                                 │
│  Limitation: Can't combine effects (e.g., IO + typed errors)    │
├─────────────────────────────────────────────────────────────────┤
│  LAYER 2: Effect Contexts                       ← NEW           │
│  ────────────────────────                                       │
│                                                                 │
│  ErrorContext, OptionalContext, JavaOptionalContext,            │
│  ConfigContext, MutableContext                                  │
│                                                                 │
│  ✓ User-friendly transformer wrappers                           │
│  ✓ Hides HKT complexity (no Kind<F, A> in your code)            │
│  ✓ Best for: Combined effects without ceremony                  │
│                                                                 │
│  Limitation: Fixed to common patterns                           │
├─────────────────────────────────────────────────────────────────┤
│  LAYER 3: Raw Transformers                                      │
│  ─────────────────────────                                      │
│                                                                 │
│  EitherT, MaybeT, OptionalT, ReaderT, StateT                    │
│                                                                 │
│  ✓ Full transformer power                                       │
│  ✓ Arbitrary effect stacking                                    │
│  ✓ Best for: Library authors, unusual combinations              │
│                                                                 │
│  Limitation: Requires HKT fluency                               │
└─────────────────────────────────────────────────────────────────┘

Most code lives in Layer 1. When you need combined effects, Layer 2 handles the common cases cleanly. Layer 3 waits for the rare occasions when nothing else suffices.

Available Effect Contexts

Each Effect Context wraps a specific transformer, exposing its capabilities through a streamlined API:

Choosing the Right Context

                    What's your primary concern?
                              │
           ┌──────────────────┼──────────────────┐
           │                  │                  │
    Typed Errors       Optional Values     Environment/State
           │                  │                  │
           ▼                  │          ┌──────┴──────┐
     ErrorContext             │          │             │
                              │     ConfigContext  MutableContext
                    ┌─────────┴─────────┐
                    │                   │
             Using Maybe?         Using Optional?
                    │                   │
                    ▼                   ▼
            OptionalContext    JavaOptionalContext

ErrorContext when you need:

• Typed errors across IO operations
• Exception-catching with custom error types
• Error recovery and transformation

OptionalContext / JavaOptionalContext when you need:

• Optional values from IO operations
• Fallback chains for missing data
• The choice between them is simply which optional type you prefer

ConfigContext when you need:

• Dependency injection without frameworks
• Environment/configuration threading
• Local configuration overrides

MutableContext when you need:

• State threading through IO operations
• Accumulators, counters, or state machines
• Both the final value and final state

Common Patterns

The Error-Handling Pipeline

ErrorContext<IOKind.Witness, ApiError, Order> orderPipeline =
    ErrorContext.<ApiError, User>io(
        () -> userService.fetch(userId),
        ApiError::fromException)
    .via(user -> ErrorContext.io(
        () -> cartService.getCart(user.id()),
        ApiError::fromException))
    .via(cart -> ErrorContext.io(
        () -> orderService.createOrder(cart),
        ApiError::fromException))
    .recover(error -> Order.failed(error.message()));

The Optional Lookup Chain

OptionalContext<IOKind.Witness, Config> config =
    OptionalContext.<Config>io(() -> cache.get("config"))
        .orElse(() -> OptionalContext.io(() -> database.loadConfig()))
        .orElse(() -> OptionalContext.some(Config.defaults()));

Dependency Injection

ConfigContext<IOKind.Witness, ServiceConfig, Report> report =
    ConfigContext.io(config ->
        reportService.generate(config.reportFormat()));

Report result = report.runWithSync(new ServiceConfig("PDF", 30));

Stateful Computation

MutableContext<IOKind.Witness, Counter, String> workflow =
    MutableContext.<Counter>get()
        .map(c -> "Started at: " + c.value())
        .flatMap(msg -> MutableContext.<Counter, Unit>modify(Counter::increment)
            .map(u -> msg));

StateTuple<Counter, String> result = workflow.runWith(new Counter(0)).unsafeRun();
// result.state().value() == 1
// result.value() == "Started at: 0"

Escape Hatches

Every Effect Context provides access to its underlying transformer via an escape hatch method. When you need capabilities beyond what the Context API exposes, you can drop to Layer 3:

ErrorContext<IOKind.Witness, ApiError, User> ctx = ErrorContext.success(user);

// Escape to raw transformer
EitherT<IOKind.Witness, ApiError, User> transformer = ctx.toEitherT();

// Now you have full transformer capabilities
// ... perform advanced operations ...

Use escape hatches sparingly. They're for genuine edge cases, not everyday operations.

Summary

Effect Contexts occupy the middle ground: more power than simple Paths, more clarity than raw transformers. They make the invisible shapes visible, the unthinkable thinkable.

Previous: Advanced Effects Next: ErrorContext

ErrorContext: Typed Errors in Effectful Code

"You wont never get the whole thing its too big in the nite of your head ther aint room."

— Russell Hoban, Riddley Walker

API calls fail. Database queries timeout. Files go missing. The "whole thing" of what can go wrong in effectful code is indeed too big to hold in your head at once. But you can give those failures names—typed errors that the compiler understands and your code can reason about. ErrorContext captures both the deferred nature of IO and the typed-error semantics of Either in a single, composable abstraction.

The Problem

Traditional Java error handling fragments across styles:

// Style 1: Checked exceptions
public User fetchUser(String id) throws UserNotFoundException { ... }

// Style 2: Unchecked exceptions
public Order createOrder(Cart cart) { /* might throw RuntimeException */ }

// Style 3: Optional returns
public Optional<Profile> getProfile(User user) { ... }

// Style 4: Custom result types
public Result<ValidationError, Order> validateOrder(OrderRequest req) { ... }

Composing across these styles requires constant translation. Each boundary demands explicit handling, cluttering your code with conversion logic.

The Solution

ErrorContext unifies error handling for IO-based operations. Exceptions become typed errors. Optionality can be converted to errors. All computations compose through the same operations:

ErrorContext<IOKind.Witness, OrderError, Order> orderPipeline =
    ErrorContext.<OrderError, User>io(
        () -> userService.fetch(userId),           // May throw
        OrderError::fromException)
    .via(user -> ErrorContext.io(
        () -> orderService.validate(user, request),
        OrderError::fromException))
    .via(validated -> ErrorContext.io(
        () -> orderService.create(validated),
        OrderError::fromException))
    .recover(error -> Order.placeholder(error.message()));

One unified API. One error type. The compiler tracks what can fail.

Creating ErrorContexts

From Throwing Computations

The most common factory method catches exceptions and maps them to your error type:

ErrorContext<IOKind.Witness, ApiError, User> user = ErrorContext.io(
    () -> httpClient.get("/users/" + id),   // May throw
    ApiError::fromException                   // Throwable → ApiError
);

The computation is deferred—nothing executes until you call runIO(). Exceptions thrown during execution are caught and converted to the error type.

From Either-Returning Computations

When your code already returns Either:

ErrorContext<IOKind.Witness, ValidationError, Order> validated = ErrorContext.ioEither(
    () -> validator.validate(request)   // Returns Either<ValidationError, Order>
);

Pure Values

For successful or failed values you already have:

// Known success
ErrorContext<IOKind.Witness, String, Integer> success = ErrorContext.success(42);

// Known failure
ErrorContext<IOKind.Witness, String, Integer> failure = ErrorContext.failure("Not found");

// From an existing Either
Either<ApiError, User> either = lookupUser(id);
ErrorContext<IOKind.Witness, ApiError, User> ctx = ErrorContext.fromEither(either);

Transforming Values

map: Transform the Success Value

map transforms the value inside a successful context:

ErrorContext<IOKind.Witness, String, String> greeting = ErrorContext.success("world");

ErrorContext<IOKind.Witness, String, String> result = greeting.map(s -> "Hello, " + s);
// Success("Hello, world")

ErrorContext<IOKind.Witness, String, String> failed = ErrorContext.failure("oops");
ErrorContext<IOKind.Witness, String, String> stillFailed = failed.map(s -> "Hello, " + s);
// Failure("oops") — map doesn't run on failures

The function only executes if the context is successful. Failures pass through unchanged.

Chaining Computations

via: Chain Dependent Operations

via is the workhorse for sequencing operations where each step depends on the previous:

ErrorContext<IOKind.Witness, DbError, Invoice> invoice =
    ErrorContext.<DbError, Customer>io(
        () -> customerRepo.find(customerId),
        DbError::fromException)
    .via(customer -> ErrorContext.io(
        () -> orderRepo.findByCustomer(customer.id()),
        DbError::fromException))
    .via(orders -> ErrorContext.io(
        () -> invoiceService.generate(orders),
        DbError::fromException));

Each step receives the previous result. If any step fails, subsequent steps are skipped—the failure propagates to the end.

flatMap: Type-Preserving Chain

flatMap is equivalent to via but with a more explicit type signature:

// Using flatMap instead of via
ErrorContext<IOKind.Witness, ApiError, Profile> profile =
    fetchUser(userId)
        .flatMap(user -> fetchProfile(user.profileId()))
        .flatMap(prof -> enrichProfile(prof));

Choose based on readability. Both short-circuit on failure.

then: Sequence Without Using the Value

When you need to sequence but don't care about the previous value:

ErrorContext<IOKind.Witness, String, Unit> workflow =
    ErrorContext.<String, Unit>success(Unit.INSTANCE)
        .then(() -> logAction("Starting"))
        .then(() -> performAction())
        .then(() -> logAction("Completed"));

Recovering from Errors

recover: Provide a Fallback Value

recover catches errors and produces a fallback value:

ErrorContext<IOKind.Witness, String, Config> config =
    ErrorContext.<String, Config>io(
        () -> loadConfigFromServer(),
        Throwable::getMessage)
    .recover(error -> {
        log.warn("Using defaults: {}", error);
        return Config.defaults();
    });

If the original computation fails, the recovery function runs. If it succeeds, recovery is never invoked.

recoverWith: Provide a Fallback Computation

When recovery itself might fail:

ErrorContext<IOKind.Witness, ApiError, Data> data =
    ErrorContext.<ApiError, Data>io(
        () -> primaryService.fetch(),
        ApiError::fromException)
    .recoverWith(error -> ErrorContext.io(
        () -> backupService.fetch(),
        ApiError::fromException));

The fallback is another ErrorContext. This enables fallback chains that can themselves fail.

orElse: Alternative Without Inspecting Error

When you don't need the error details:

ErrorContext<IOKind.Witness, String, User> user =
    fetchFromCache(userId)
        .orElse(() -> fetchFromDatabase(userId))
        .orElse(() -> ErrorContext.success(User.anonymous()));

Transforming Errors

mapError: Change the Error Type

mapError transforms the error without affecting success values:

ErrorContext<IOKind.Witness, String, User> lowLevel = ErrorContext.failure("connection refused");

ErrorContext<IOKind.Witness, ApiError, User> highLevel =
    lowLevel.mapError(msg -> new ApiError(500, msg));

This is essential when composing code from different modules that use different error types.

Execution

runIO: Get an IOPath

runIO() extracts an IOPath<Either<E, A>> for deferred execution:

ErrorContext<IOKind.Witness, ApiError, User> ctx = ...;

// Get the IOPath (nothing runs yet)
IOPath<Either<ApiError, User>> ioPath = ctx.runIO();

// Execute when ready
Either<ApiError, User> result = ioPath.unsafeRun();

runIOOrThrow: Success or Exception

For cases where failure should throw:

try {
    User user = userContext.runIOOrThrow();
    // Use the user
} catch (RuntimeException e) {
    // Error was wrapped: e.getMessage() contains error.toString()
}

runIOOrElse: Success or Default

For cases where failure should use a default:

User user = userContext.runIOOrElse(User.guest());

runIOOrElseGet: Success or Computed Default

When the default depends on the error:

User user = userContext.runIOOrElseGet(error -> {
    log.error("Failed with: {}", error);
    return User.guest();
});

Real-World Patterns

API Client with Error Handling

public class UserClient {
    public ErrorContext<IOKind.Witness, ApiError, User> fetchUser(String id) {
        return ErrorContext.<ApiError, User>io(
            () -> {
                HttpResponse response = httpClient.get("/users/" + id);
                if (response.status() == 404) {
                    throw new NotFoundException("User not found: " + id);
                }
                return parseUser(response.body());
            },
            ApiError::fromException);
    }

    public ErrorContext<IOKind.Witness, ApiError, Profile> fetchProfile(User user) {
        return ErrorContext.<ApiError, Profile>io(
            () -> {
                HttpResponse response = httpClient.get("/profiles/" + user.profileId());
                return parseProfile(response.body());
            },
            ApiError::fromException);
    }
}

// Usage
ErrorContext<IOKind.Witness, ApiError, Profile> profile =
    client.fetchUser(userId)
        .via(client::fetchProfile)
        .recover(error -> Profile.empty());

Multi-Step Transaction

public ErrorContext<IOKind.Witness, OrderError, Order> processOrder(OrderRequest request) {
    return validateRequest(request)
        .via(this::checkInventory)
        .via(this::reserveItems)
        .via(this::chargePayment)
        .via(this::createOrder)
        .recoverWith(error -> {
            // Compensating action
            return rollbackReservations()
                .then(() -> ErrorContext.failure(error));
        });
}

Layered Error Types

// Low-level: database errors
ErrorContext<IOKind.Witness, DbError, User> dbUser =
    ErrorContext.io(() -> db.query("SELECT ..."), DbError::fromSql);

// Mid-level: repository errors
ErrorContext<IOKind.Witness, RepoError, User> repoUser =
    dbUser.mapError(RepoError::fromDbError);

// High-level: API errors
ErrorContext<IOKind.Witness, ApiError, User> apiUser =
    repoUser.mapError(ApiError::fromRepoError);

Escape Hatch

When you need the raw transformer:

ErrorContext<IOKind.Witness, String, Integer> ctx = ErrorContext.success(42);

EitherT<IOKind.Witness, String, Integer> transformer = ctx.toEitherT();

// Now you have full EitherT capabilities

Summary

ErrorContext brings order to effectful error handling. Exceptions become data. Failures propagate predictably. Recovery is explicit. The shapes in the night become visible.

Previous: Effect Contexts Next: Optional Contexts

Optional Contexts: Graceful Absence in Effects

"Sum tyms theres mor in the emty than the ful."

— Russell Hoban, Riddley Walker

Hoban's riddler knew that absence can be as meaningful as presence. A database query that returns nothing isn't always an error—sometimes the record genuinely doesn't exist, and that's valuable information. OptionalContext and JavaOptionalContext model this graceful absence within effectful computations, giving you the compositional power of transformers without forcing non-existence into an error mould.

Two Flavours of Optionality

Higher-Kinded-J provides two optional context types:

They're functionally equivalent. Choose based on what your codebase already uses:

• If you're working with code that uses Optional, use JavaOptionalContext
• If you're using Higher-Kinded-J's Maybe throughout, use OptionalContext
• If starting fresh, either works—Maybe is slightly more idiomatic for FP patterns

The Problem

Consider a lookup chain:

// Each might return null or Optional.empty()
User user = cache.get(userId);
if (user == null) {
    user = database.find(userId);
}
if (user == null) {
    user = legacySystem.lookup(userId);
}
if (user == null) {
    throw new UserNotFoundException(userId);
}

Four null checks. Three nested lookups. The actual logic—try cache, then database, then legacy—is obscured by defensive programming.

The Solution

With OptionalContext:

OptionalContext<IOKind.Witness, User> user =
    OptionalContext.<User>io(() -> cache.get(userId))
        .orElse(() -> OptionalContext.io(() -> database.find(userId)))
        .orElse(() -> OptionalContext.io(() -> legacySystem.lookup(userId)));

// Convert to ErrorContext when absence is actually an error
ErrorContext<IOKind.Witness, UserError, User> required =
    user.toErrorContext(new UserError("User not found: " + userId));

The lookup chain reads top-to-bottom. Fallbacks are explicit. The point where absence becomes an error is clear.

Creating OptionalContexts

From Nullable Suppliers

The io() factory handles null gracefully—null becomes empty:

// If findById returns null, the context is empty
OptionalContext<IOKind.Witness, User> user =
    OptionalContext.io(() -> repository.findById(userId));

// Same pattern with JavaOptionalContext
JavaOptionalContext<IOKind.Witness, User> user =
    JavaOptionalContext.io(() -> repository.findById(userId));

From Maybe/Optional-Returning Computations

When your code already returns the optional type:

// Maybe-returning supplier
OptionalContext<IOKind.Witness, Config> config =
    OptionalContext.ioMaybe(() -> configLoader.load("app.properties"));

// Optional-returning supplier
JavaOptionalContext<IOKind.Witness, Config> config =
    JavaOptionalContext.ioOptional(() -> configLoader.load("app.properties"));

Pure Values

For known values:

// Present value
OptionalContext<IOKind.Witness, Integer> some = OptionalContext.some(42);
JavaOptionalContext<IOKind.Witness, Integer> present = JavaOptionalContext.some(42);

// Empty
OptionalContext<IOKind.Witness, Integer> none = OptionalContext.none();
JavaOptionalContext<IOKind.Witness, Integer> absent = JavaOptionalContext.none();

// From existing Maybe/Optional
Maybe<User> maybe = Maybe.just(user);
OptionalContext<IOKind.Witness, User> fromMaybe = OptionalContext.fromMaybe(maybe);

Optional<User> optional = Optional.of(user);
JavaOptionalContext<IOKind.Witness, User> fromOpt = JavaOptionalContext.fromOptional(optional);

Transforming Values

map: Transform Present Values

OptionalContext<IOKind.Witness, String> name = OptionalContext.some("Alice");

OptionalContext<IOKind.Witness, String> upper = name.map(String::toUpperCase);
// → some("ALICE")

OptionalContext<IOKind.Witness, String> empty = OptionalContext.none();
OptionalContext<IOKind.Witness, String> stillEmpty = empty.map(String::toUpperCase);
// → none (map doesn't run on empty)

Chaining Computations

via: Chain Dependent Lookups

OptionalContext<IOKind.Witness, Address> address =
    OptionalContext.<User>io(() -> userRepo.findById(userId))
        .via(user -> OptionalContext.io(() -> addressRepo.findByUserId(user.id())));

If the user isn't found, the address lookup never runs. If the user exists but has no address, the result is empty. Both cases produce the same none() outcome.

flatMap: Type-Preserving Chain

OptionalContext<IOKind.Witness, Profile> profile =
    lookupUser(userId)
        .flatMap(user -> lookupProfile(user.profileId()))
        .flatMap(profile -> enrichProfile(profile));

then: Sequence Ignoring Values

OptionalContext<IOKind.Witness, String> result =
    validateExists()
        .then(() -> fetchData())
        .then(() -> processResult());

Providing Fallbacks

orElse: Fallback to Another Context

The primary pattern for lookup chains:

OptionalContext<IOKind.Witness, Config> config =
    OptionalContext.<Config>io(() -> loadFromEnvironment())
        .orElse(() -> OptionalContext.io(() -> loadFromFile()))
        .orElse(() -> OptionalContext.io(() -> loadFromDefaults()))
        .orElse(() -> OptionalContext.some(Config.hardcodedDefaults()));

Each fallback runs only if all previous attempts returned empty.

orElseValue: Fallback to a Direct Value

When the fallback is known:

OptionalContext<IOKind.Witness, Integer> count =
    OptionalContext.<Integer>io(() -> cache.getCount())
        .orElseValue(0);  // Default to zero if not cached

recover: Transform Absence

When you need to compute the fallback:

OptionalContext<IOKind.Witness, Config> config =
    loadConfig()
        .recover(unit -> {
            log.info("No config found, using defaults");
            return Config.defaults();
        });

The unit parameter is always Unit.INSTANCE—it's the "error" type for optionality, representing the absence of information about why the value is missing.

recoverWith: Fallback to Another Computation

OptionalContext<IOKind.Witness, Data> data =
    fetchFromPrimary()
        .recoverWith(unit -> fetchFromBackup());

Converting to ErrorContext

Often, absence at some point becomes an error. The boundary is explicit:

OptionalContext<IOKind.Witness, User> optionalUser =
    OptionalContext.<User>io(() -> userRepo.findById(userId));

// Absence → Typed Error
ErrorContext<IOKind.Witness, UserNotFound, User> requiredUser =
    optionalUser.toErrorContext(new UserNotFound(userId));

// Now we can use ErrorContext operations
Either<UserNotFound, User> result = requiredUser.runIO().unsafeRun();

This runs the underlying computation and converts the result. For deferred conversion, use the escape hatch to the raw transformer.

Converting Between Optional Types

JavaOptionalContext can convert to OptionalContext:

JavaOptionalContext<IOKind.Witness, User> javaOptional =
    JavaOptionalContext.io(() -> repo.find(id));

OptionalContext<IOKind.Witness, User> maybeContext =
    javaOptional.toOptionalContext();

Execution

runIO: Get an IOPath

// For OptionalContext
OptionalContext<IOKind.Witness, User> optionalCtx = OptionalContext.some(user);
IOPath<Maybe<User>> maybeIO = optionalCtx.runIO();

// For JavaOptionalContext
JavaOptionalContext<IOKind.Witness, User> javaCtx = JavaOptionalContext.some(user);
IOPath<Optional<User>> optionalIO = javaCtx.runIO();

// Execute
Maybe<User> maybeResult = maybeIO.unsafeRun();
Optional<User> optionalResult = optionalIO.unsafeRun();

runIOOrElse: Value or Default

User user = userContext.runIOOrElse(User.guest());

runIOOrThrow: Value or Exception

User user = userContext.runIOOrThrow();  // Throws NoSuchElementException if empty

Real-World Patterns

Cache-Through Pattern

public OptionalContext<IOKind.Witness, Product> getProduct(String id) {
    return OptionalContext.<Product>io(() -> cache.get(id))
        .orElse(() -> {
            Product product = database.find(id);
            if (product != null) {
                cache.put(id, product);  // Populate cache
            }
            return product == null
                ? OptionalContext.none()
                : OptionalContext.some(product);
        });
}

Configuration Layering

public OptionalContext<IOKind.Witness, String> getSetting(String key) {
    return OptionalContext.<String>io(() -> System.getenv(key))          // Environment first
        .orElse(() -> OptionalContext.io(() -> System.getProperty(key))) // System property
        .orElse(() -> OptionalContext.io(() -> configFile.get(key)))     // Config file
        .orElse(() -> OptionalContext.io(() -> defaults.get(key)));      // Defaults last
}

Validation with Optional Fields

record UserInput(String name, String email, String phone) {}

public OptionalContext<IOKind.Witness, String> getContactMethod(UserInput input) {
    return OptionalContext.<String>io(() -> nullIfBlank(input.email()))
        .orElse(() -> OptionalContext.io(() -> nullIfBlank(input.phone())));
    // Returns the first available contact method
}

private String nullIfBlank(String s) {
    return s == null || s.isBlank() ? null : s;
}

Graceful Degradation

public OptionalContext<IOKind.Witness, DashboardData> loadDashboard(String userId) {
    return OptionalContext.<DashboardData>io(() -> fullDashboardService.load(userId))
        .orElse(() -> OptionalContext.io(() -> simplifiedDashboard(userId)))
        .orElse(() -> OptionalContext.some(DashboardData.empty()));
}

Escape Hatch

When you need the raw transformer:

OptionalContext<IOKind.Witness, User> ctx = OptionalContext.some(user);
MaybeT<IOKind.Witness, User> transformer = ctx.toMaybeT();

JavaOptionalContext<IOKind.Witness, User> jCtx = JavaOptionalContext.some(user);
OptionalT<IOKind.Witness, User> transformer = jCtx.toOptionalT();

Summary

Optional contexts embrace the wisdom that emptiness can be meaningful. Not every missing value is a bug. Sometimes there's more in the empty than the full.

Previous: ErrorContext Next: ConfigContext

ConfigContext: Dependency Injection Without the Framework

"The onlyes power is no power."

— Russell Hoban, Riddley Walker

Hoban's aphorism hints at a paradox: sometimes the most powerful abstractions are those that feel like nothing at all. ConfigContext provides dependency injection that doesn't feel like a framework—no annotations, no containers, no reflection. Dependencies flow through your code as naturally as function arguments, but without cluttering every signature.

The Problem

Consider a service that needs configuration:

public class ReportService {
    public Report generate(ReportConfig config, UserId userId) {
        User user = userService.fetch(config.userServiceUrl(), config.timeout(), userId);
        List<Order> orders = orderService.fetch(config.orderServiceUrl(), config.timeout(), user);
        return buildReport(config.format(), user, orders);
    }
}

The config parameter appears everywhere. Every method in the call chain needs it, even if it only uses one field. Signatures become cluttered. Testing requires constructing complete config objects even when you only care about one aspect.

Dependency injection frameworks solve this with containers and annotations—but those come with their own complexity: lifecycle management, circular dependency detection, runtime magic.

The Solution

ConfigContext threads configuration implicitly:

public ConfigContext<IOKind.Witness, ReportConfig, Report> generate(UserId userId) {
    return ConfigContext.<ReportConfig>ask()
        .via(config -> fetchUser(userId))       // Config available inside
        .via(user -> fetchOrders(user))         // Config still available
        .via(orders -> buildReport(orders));    // And here
}

// Execute by providing config once at the edge
Report report = generate(userId).runWithSync(config);

Configuration is declared once. Every computation in the chain can access it. No parameters threaded through signatures.

Creating ConfigContexts

ask: Access the Entire Configuration

ask() yields the configuration itself:

ConfigContext<IOKind.Witness, AppConfig, AppConfig> config = ConfigContext.ask();

// Then project what you need
ConfigContext<IOKind.Witness, AppConfig, String> apiUrl =
    ConfigContext.<AppConfig>ask()
        .map(AppConfig::apiUrl);

io: Compute Using Configuration

When your computation depends on config:

ConfigContext<IOKind.Witness, DbConfig, Connection> connection =
    ConfigContext.io(config -> DriverManager.getConnection(
        config.url(),
        config.username(),
        config.password()
    ));

The function receives the configuration and returns a value. Execution is immediate when the context runs.

ioDeferred: Defer Computation

When you want the IO aspect to be truly deferred:

ConfigContext<IOKind.Witness, ApiConfig, Response> response =
    ConfigContext.ioDeferred(config -> () -> {
        // This supplier is invoked later when runWith() is called
        return httpClient.get(config.endpoint());
    });

pure: Ignore Configuration

For values that don't need the config:

ConfigContext<IOKind.Witness, AnyConfig, Integer> fortyTwo =
    ConfigContext.pure(42);

Transforming Values

map: Transform the Result

ConfigContext<IOKind.Witness, ServiceConfig, String> endpoint =
    ConfigContext.<ServiceConfig>ask()
        .map(ServiceConfig::baseUrl);

ConfigContext<IOKind.Witness, ServiceConfig, URI> uri =
    endpoint.map(URI::create);

Chaining Computations

via: Chain Dependent Operations

record AppConfig(String userServiceUrl, String orderServiceUrl, Duration timeout) {}

ConfigContext<IOKind.Witness, AppConfig, Invoice> invoice =
    ConfigContext.<AppConfig>ask()
        .via(config -> fetchUser(config.userServiceUrl()))
        .via(user -> fetchOrders(user.id()))
        .via(orders -> createInvoice(orders));

private ConfigContext<IOKind.Witness, AppConfig, User> fetchUser(String url) {
    return ConfigContext.io(config -> userClient.fetch(url, config.timeout()));
}

private ConfigContext<IOKind.Witness, AppConfig, List<Order>> fetchOrders(UserId id) {
    return ConfigContext.io(config -> orderClient.fetch(config.orderServiceUrl(), id));
}

Each step has access to the same configuration. The config flows through without explicit passing.

flatMap: Type-Preserving Chain

ConfigContext<IOKind.Witness, AppConfig, Report> report =
    getUser()
        .flatMap(user -> getOrders(user))
        .flatMap(orders -> generateReport(orders));

then: Sequence Ignoring Values

ConfigContext<IOKind.Witness, Config, String> workflow =
    logStart()
        .then(() -> doWork())
        .then(() -> logComplete())
        .then(() -> ConfigContext.pure("done"));

Modifying Configuration Locally

local: Temporary Config Override

Sometimes a sub-computation needs modified settings:

ConfigContext<IOKind.Witness, ApiConfig, Data> withLongerTimeout =
    fetchData()
        .local(config -> config.withTimeout(Duration.ofMinutes(5)));

The modified config applies only to this computation. Other computations in the same chain see the original.

Pattern: Feature Flags

record AppConfig(boolean debugMode, int maxRetries) {}

ConfigContext<IOKind.Witness, AppConfig, Result> withDebugMode =
    processData()
        .local(config -> new AppConfig(true, config.maxRetries()));

Pattern: Environment-Specific Settings

ConfigContext<IOKind.Witness, ServiceConfig, Response> callService =
    ConfigContext.io(config -> httpClient.call(config.endpoint()));

// In tests, use a test environment
ConfigContext<IOKind.Witness, ServiceConfig, Response> testCall =
    callService.local(config -> config.withEndpoint("http://localhost:8080"));

Adapting to Different Config Types

contramap: Transform the Required Config

When composing code with different config types:

record GlobalConfig(DatabaseConfig db, ApiConfig api) {}

// This needs DatabaseConfig
ConfigContext<IOKind.Witness, DatabaseConfig, Connection> dbConnection = ...;

// Adapt to work with GlobalConfig
ConfigContext<IOKind.Witness, GlobalConfig, Connection> adapted =
    dbConnection.contramap(GlobalConfig::db);

contramap transforms the input (the config), allowing you to compose contexts that expect different configuration types.

Pattern: Modular Configuration

// User module expects UserConfig
ConfigContext<IOKind.Witness, UserConfig, User> fetchUser = ...;

// Order module expects OrderConfig
ConfigContext<IOKind.Witness, OrderConfig, Order> fetchOrder = ...;

// Application config combines both
record AppConfig(UserConfig userConfig, OrderConfig orderConfig) {}

// Adapt both to AppConfig
ConfigContext<IOKind.Witness, AppConfig, User> appUser =
    fetchUser.contramap(AppConfig::userConfig);

ConfigContext<IOKind.Witness, AppConfig, Order> appOrder =
    fetchOrder.contramap(AppConfig::orderConfig);

// Now they can be chained
ConfigContext<IOKind.Witness, AppConfig, Invoice> invoice =
    appUser.via(user -> appOrder.map(order -> createInvoice(user, order)));

Execution

runWith: Get an IOPath

ConfigContext<IOKind.Witness, AppConfig, Report> reportCtx = generateReport();

// Provide config, get IOPath
AppConfig config = loadConfig();
IOPath<Report> ioPath = reportCtx.runWith(config);

// Execute when ready
Report report = ioPath.unsafeRun();

runWithSync: Immediate Execution

For synchronous code:

Report report = reportCtx.runWithSync(config);

This is equivalent to runWith(config).unsafeRun().

Real-World Patterns

Service Layer with Configuration

public class OrderService {
    public ConfigContext<IOKind.Witness, ServiceConfig, Order> createOrder(OrderRequest request) {
        return validateRequest(request)
            .via(valid -> checkInventory(valid))
            .via(checked -> processPayment(checked))
            .via(paid -> saveOrder(paid));
    }

    private ConfigContext<IOKind.Witness, ServiceConfig, ValidatedRequest> validateRequest(
            OrderRequest request) {
        return ConfigContext.io(config ->
            validator.validate(request, config.validationRules()));
    }

    private ConfigContext<IOKind.Witness, ServiceConfig, CheckedRequest> checkInventory(
            ValidatedRequest request) {
        return ConfigContext.io(config ->
            inventoryClient.check(config.inventoryServiceUrl(), request.items()));
    }

    // ... similar for other methods
}

// At the application edge
ServiceConfig config = loadConfig();
Order order = orderService.createOrder(request).runWithSync(config);

Database Access

record DbConfig(String url, String user, String password, int poolSize) {}

public class UserRepository {
    public ConfigContext<IOKind.Witness, DbConfig, User> findById(UserId id) {
        return ConfigContext.io(config -> {
            try (Connection conn = getConnection(config)) {
                return queryUser(conn, id);
            }
        });
    }

    private Connection getConnection(DbConfig config) {
        return DriverManager.getConnection(config.url(), config.user(), config.password());
    }
}

Testability

// Production config
DbConfig prodConfig = new DbConfig(
    "jdbc:postgresql://prod-db:5432/app",
    "app_user",
    prodPassword,
    20
);

// Test config
DbConfig testConfig = new DbConfig(
    "jdbc:h2:mem:test",
    "sa",
    "",
    1
);

// Same code, different config
User prodUser = repository.findById(id).runWithSync(prodConfig);
User testUser = repository.findById(id).runWithSync(testConfig);

Combining with ErrorContext

public ConfigContext<IOKind.Witness, ApiConfig, ErrorContext<IOKind.Witness, ApiError, User>>
        fetchUser(UserId id) {
    return ConfigContext.io(config -> {
        return ErrorContext.<ApiError, User>io(
            () -> httpClient.get(config.userEndpoint() + "/" + id),
            ApiError::fromException);
    });
}

Escape Hatch

When you need the raw transformer:

ConfigContext<IOKind.Witness, AppConfig, String> ctx = ConfigContext.ask().map(AppConfig::name);

ReaderT<IOKind.Witness, AppConfig, String> transformer = ctx.toReaderT();

Summary

ConfigContext embodies the paradox of invisible power. Dependencies flow through your code without ceremony, without frameworks, without the infrastructure that usually accompanies "enterprise" patterns. The only power is no power—the power that feels like nothing at all.

Previous: Optional Contexts Next: MutableContext

MutableContext: Stateful Computation Made Pure

"Its the same thing every time. The stoan you find aint the stoan you thot youd be looking for."

— Russell Hoban, Riddley Walker

State transforms as you work with it. The counter you started with isn't the counter you end with. The accumulator grows. The traversal position shifts. MutableContext lets you write code that feels like mutation—get the current value, update it, continue—while remaining purely functional underneath. The state you find at the end isn't the state you started with, but the transformation is explicit and controlled.

The Problem

Consider tracking statistics through a processing pipeline:

// Mutable approach: threading state manually
class Stats {
    int processed = 0;
    int errors = 0;
    long totalBytes = 0;
}

void processFiles(List<Path> files, Stats stats) {
    for (Path file : files) {
        try {
            byte[] content = Files.readAllBytes(file);
            stats.totalBytes += content.length;
            process(content);
            stats.processed++;
        } catch (Exception e) {
            stats.errors++;
        }
    }
}

The mutation is scattered. Testing requires mutable fixtures. Parallelisation becomes dangerous. And the state threading is implicit—you have to trace through the code to understand how stats changes.

The Solution

MutableContext makes state threading explicit and composable:

record Stats(int processed, int errors, long totalBytes) {
    Stats incrementProcessed() { return new Stats(processed + 1, errors, totalBytes); }
    Stats incrementErrors() { return new Stats(processed, errors + 1, totalBytes); }
    Stats addBytes(long bytes) { return new Stats(processed, errors, totalBytes + bytes); }
}

MutableContext<IOKind.Witness, Stats, Unit> processFile(Path file) {
    return MutableContext.io(stats -> {
        try {
            byte[] content = Files.readAllBytes(file);
            return StateTuple.of(
                stats.addBytes(content.length).incrementProcessed(),
                Unit.INSTANCE);
        } catch (Exception e) {
            return StateTuple.of(stats.incrementErrors(), Unit.INSTANCE);
        }
    });
}

// Process all files
MutableContext<IOKind.Witness, Stats, Unit> processAll =
    files.stream()
        .map(this::processFile)
        .reduce(MutableContext.pure(Unit.INSTANCE),
            (a, b) -> a.then(() -> b));

Stats finalStats = processAll.execWith(new Stats(0, 0, 0)).unsafeRun();

State changes are explicit. Each operation declares how it modifies state. The flow is clear.

Creating MutableContexts

io: State Transformation with Value

The core factory creates a context from a function S -> StateTuple<S, A>:

record Counter(int value) {
    Counter increment() { return new Counter(value + 1); }
}

MutableContext<IOKind.Witness, Counter, String> getAndIncrement =
    MutableContext.io(counter -> StateTuple.of(
        counter.increment(),           // New state
        "Was: " + counter.value()      // Produced value
    ));

get: Read Current State

get() yields the current state as the value without modifying it:

MutableContext<IOKind.Witness, Counter, Counter> current = MutableContext.get();

// Often followed by map to extract what you need
MutableContext<IOKind.Witness, Counter, Integer> currentValue =
    MutableContext.<Counter>get()
        .map(Counter::value);

put: Replace State Entirely

put() sets a new state, returning Unit:

MutableContext<IOKind.Witness, Counter, Unit> reset =
    MutableContext.put(new Counter(0));

modify: Update State

modify() applies a transformation to the current state:

MutableContext<IOKind.Witness, Counter, Unit> increment =
    MutableContext.modify(Counter::increment);

MutableContext<IOKind.Witness, Counter, Unit> addFive =
    MutableContext.modify(c -> new Counter(c.value() + 5));

pure: Value Without State Change

For values that don't affect state:

MutableContext<IOKind.Witness, AnyState, String> constant =
    MutableContext.pure("Hello");

Transforming Values

map: Transform the Result

MutableContext<IOKind.Witness, Counter, Integer> count =
    MutableContext.<Counter>get()
        .map(Counter::value);

MutableContext<IOKind.Witness, Counter, String> countStr =
    count.map(n -> "Count: " + n);

map transforms the value; the state flows through unchanged by the transformation itself.

Chaining Stateful Operations

via / flatMap: Sequence State Changes

Each operation sees the state left by previous operations:

MutableContext<IOKind.Witness, Counter, String> workflow =
    MutableContext.<Counter>get()                              // Read initial state
        .map(c -> "Started at " + c.value())
        .flatMap(msg -> MutableContext.<Counter, Unit>modify(Counter::increment)
            .map(u -> msg))                                     // State now incremented
        .flatMap(msg -> MutableContext.<Counter>get()
            .map(c -> msg + ", now at " + c.value()));          // See updated state

then: Sequence Ignoring Values

When you only care about the state effects:

MutableContext<IOKind.Witness, Counter, Unit> incrementThrice =
    MutableContext.<Counter, Unit>modify(Counter::increment)
        .then(() -> MutableContext.modify(Counter::increment))
        .then(() -> MutableContext.modify(Counter::increment));

Pattern: Accumulator

record Accumulator(List<String> items) {
    Accumulator add(String item) {
        var newItems = new ArrayList<>(items);
        newItems.add(item);
        return new Accumulator(List.copyOf(newItems));
    }
}

MutableContext<IOKind.Witness, Accumulator, Unit> collect(String item) {
    return MutableContext.modify(acc -> acc.add(item));
}

MutableContext<IOKind.Witness, Accumulator, List<String>> collectAll =
    collect("first")
        .then(() -> collect("second"))
        .then(() -> collect("third"))
        .then(() -> MutableContext.<Accumulator>get().map(Accumulator::items));

List<String> items = collectAll.evalWith(new Accumulator(List.of())).unsafeRun();
// ["first", "second", "third"]

Execution

MutableContext offers three ways to run, depending on what you need:

runWith: Get Both State and Value

Returns IOPath<StateTuple<S, A>>:

MutableContext<IOKind.Witness, Counter, String> workflow = ...;

IOPath<StateTuple<Counter, String>> ioPath = workflow.runWith(new Counter(0));
StateTuple<Counter, String> result = ioPath.unsafeRun();

Counter finalState = result.state();   // The final state
String value = result.value();          // The produced value

evalWith: Get Only the Value

When you don't need the final state:

IOPath<String> valueIO = workflow.evalWith(new Counter(0));
String value = valueIO.unsafeRun();

execWith: Get Only the Final State

When you only care about the accumulated state:

IOPath<Counter> stateIO = workflow.execWith(new Counter(0));
Counter finalState = stateIO.unsafeRun();

Real-World Patterns

Request ID Generation

record IdState(long nextId) {
    IdState advance() { return new IdState(nextId + 1); }
}

MutableContext<IOKind.Witness, IdState, Long> generateId() {
    return MutableContext.io(state -> StateTuple.of(
        state.advance(),
        state.nextId()
    ));
}

MutableContext<IOKind.Witness, IdState, Request> tagRequest(Request req) {
    return generateId().map(id -> req.withId(id));
}

// Process multiple requests, each getting unique ID
MutableContext<IOKind.Witness, IdState, List<Request>> tagAll(List<Request> requests) {
    return requests.stream()
        .map(this::tagRequest)
        .reduce(
            MutableContext.pure(List.<Request>of()),
            (accCtx, reqCtx) -> accCtx.flatMap(list ->
                reqCtx.map(req -> {
                    var newList = new java.util.ArrayList<>(list);
                    newList.add(req);
                    return List.copyOf(newList);
                }))
        );
}

List<Request> tagged = tagAll(requests).evalWith(new IdState(1000)).unsafeRun();

Processing Statistics

record ProcessingStats(int success, int failure, Duration totalTime) {
    ProcessingStats recordSuccess(Duration d) {
        return new ProcessingStats(success + 1, failure, totalTime.plus(d));
    }
    ProcessingStats recordFailure() {
        return new ProcessingStats(success, failure + 1, totalTime);
    }
}

MutableContext<IOKind.Witness, ProcessingStats, Result> processWithStats(Item item) {
    return MutableContext.io(stats -> {
        Instant start = Instant.now();
        try {
            Result result = processor.process(item);
            Duration elapsed = Duration.between(start, Instant.now());
            return StateTuple.of(stats.recordSuccess(elapsed), result);
        } catch (Exception e) {
            return StateTuple.of(stats.recordFailure(), Result.failed(e));
        }
    });
}

State Machine

sealed interface GameState {
    record WaitingForPlayers(int count) implements GameState {}
    record InProgress(int round) implements GameState {}
    record Finished(String winner) implements GameState {}
}

MutableContext<IOKind.Witness, GameState, Unit> addPlayer() {
    return MutableContext.modify(state -> switch (state) {
        case GameState.WaitingForPlayers(var count) ->
            new GameState.WaitingForPlayers(count + 1);
        case GameState.InProgress _, GameState.Finished _ -> state;  // No-op
    });
}

MutableContext<IOKind.Witness, GameState, Unit> startGame() {
    return MutableContext.modify(state -> switch (state) {
        case GameState.WaitingForPlayers(var count) when count >= 2 ->
            new GameState.InProgress(1);
        case GameState.WaitingForPlayers _, GameState.InProgress _,
             GameState.Finished _ -> state;
    });
}

MutableContext<IOKind.Witness, GameState, Unit> advanceRound() {
    return MutableContext.modify(state -> switch (state) {
        case GameState.InProgress(var round) when round < 10 ->
            new GameState.InProgress(round + 1);
        case GameState.InProgress(var round) ->
            new GameState.Finished("Player 1");  // End after 10 rounds
        case GameState.WaitingForPlayers _, GameState.Finished _ -> state;
    });
}

Combining with Other Contexts

// Stateful computation that might fail
MutableContext<IOKind.Witness, Counter, ErrorContext<IOKind.Witness, String, Data>>
    fetchWithCounter() {
    return MutableContext.<Counter, Unit>modify(Counter::increment)
        .map(u -> ErrorContext.<String, Data>io(
            () -> dataService.fetch(),
            Throwable::getMessage));
}

Escape Hatch

When you need the raw transformer:

MutableContext<IOKind.Witness, Counter, Integer> ctx =
    MutableContext.<Counter>get().map(Counter::value);

StateT<Counter, IOKind.Witness, Integer> transformer = ctx.toStateT();

Summary

MutableContext reconciles the intuition of stateful programming with the safety of pure functions. You write code that reads state, updates state, and produces values—but the state never mutates in place. Each step produces a new state, and the transformation is explicit. The stone you find isn't the stone you started with, but you can trace every change that got you there.

Previous: ConfigContext Next: Advanced Topics

Advanced Effect Topics

"The Cryptonomicon was like an idea that had been exploded into a thousand fragments and scattered across the world... You had to pick up all the pieces and fit them together just right for any of it to make sense."

— Neal Stephenson, Cryptonomicon

Stephenson's observation about scattered fragments applies equally to advanced effect patterns. Stack safety, resource management, parallel execution, resilience—these are the fragments that, assembled correctly, transform fragile code into production-ready systems. Each piece makes sense alone; together they unlock capabilities that would otherwise require external frameworks or unsafe compromises.

This chapter explores advanced capabilities that build on the core Path types: stack-safe recursion, DSL building, resource management, parallelism, and resilience. These aren't academic exercises. They're the patterns that emerge when simple composition meets real-world demands.

Stack-Safe Recursion with TrampolinePath

"Randy had learned that the science of secrecy was really about recursion. Even after you'd encrypted something, you had to worry about whether the encrypted thing was encrypted safely."

— Neal Stephenson, Cryptonomicon

Recursion is elegant—until it overflows your stack. Java's call stack is finite, typically 512KB to 1MB depending on configuration. A recursive algorithm that works beautifully for small inputs becomes a StackOverflowError waiting to happen once the depth exceeds a few thousand calls.

TrampolinePath eliminates this limitation through trampolining: converting recursive calls into a loop that consumes constant stack space regardless of depth. The recursive structure of your algorithm remains; the stack overflow doesn't.

The Problem

Consider calculating factorial recursively:

// This will overflow around n = 10,000
long factorial(long n) {
    if (n <= 1) return 1;
    return n * factorial(n - 1);  // Stack frame per call
}

Each recursive call adds a stack frame. For large n, you exhaust the stack before reaching the base case.

The Solution

TrampolinePath separates describing the recursion from executing it:

TrampolinePath<BigInteger> factorial(BigInteger n, BigInteger acc) {
    if (n.compareTo(BigInteger.ONE) <= 0) {
        return TrampolinePath.done(acc);    // Base case: return immediately
    }
    return TrampolinePath.defer(() ->        // Recursive case: describe next step
        factorial(n.subtract(BigInteger.ONE), n.multiply(acc)));
}

// Safe for any input size
BigInteger result = factorial(BigInteger.valueOf(100000), BigInteger.ONE).run();

TrampolinePath.done(value) signals completion. TrampolinePath.defer(supplier) describes the next step without immediately executing it. When you call run(), the trampoline bounces through the deferred steps in a loop, never growing the call stack.

How It Works

The trampoline maintains a simple loop:

1. Check if the current step is done → return the value
2. If it's defer → evaluate the supplier to get the next step
3. Repeat

This converts stack depth into iteration count. Memory usage stays constant regardless of recursion depth.

Mutual Recursion

Trampolining handles mutual recursion—functions that call each other—with the same elegance:

TrampolinePath<Boolean> isEven(int n) {
    if (n == 0) return TrampolinePath.done(true);
    return TrampolinePath.defer(() -> isOdd(n - 1));
}

TrampolinePath<Boolean> isOdd(int n) {
    if (n == 0) return TrampolinePath.done(false);
    return TrampolinePath.defer(() -> isEven(n - 1));
}

// Works for any depth
boolean result = isEven(1_000_000).run();  // true

Without trampolining, isEven(1_000_000) would overflow after about 10,000 calls. With trampolining, it completes in milliseconds.

Fibonacci with Accumulator

The classic fibonacci benefits from trampolining when using accumulator style:

TrampolinePath<BigInteger> fibonacci(int n) {
    return fibHelper(n, BigInteger.ZERO, BigInteger.ONE);
}

TrampolinePath<BigInteger> fibHelper(int n, BigInteger a, BigInteger b) {
    if (n <= 0) {
        return TrampolinePath.done(a);
    }
    return TrampolinePath.defer(() -> fibHelper(n - 1, b, a.add(b)));
}

// fib(10000) completes without stack overflow
BigInteger result = fibonacci(10000).run();

When to Use TrampolinePath

Conversion and Integration

TrampolinePath integrates with other Path types:

TrampolinePath<Integer> computation = /* ... */;

// Convert to IOPath for deferred execution
IOPath<Integer> io = computation.toIOPath();

// Convert to LazyPath for memoised evaluation
LazyPath<Integer> lazy = computation.toLazyPath();

Building DSLs with Free Structures

"The key to the whole thing was that Turing had taken the seemingly useless ability to write numbers down and combined it with a few simple rules. From this, everything else followed."

— Neal Stephenson, Cryptonomicon

Sometimes you want to describe a computation without immediately executing it. You might want to:

• Test the same program against mock and real interpreters
• Optimise the program before running it
• Log or serialise what the program would do
• Run the same description in different contexts

Free structures—FreePath and FreeApPath—let you build domain-specific languages (DSLs) where the program is data that can be inspected, transformed, and interpreted later.

FreePath: The Free Monad

FreePath<F, A> represents a computation built from a functor F that can be interpreted into any monad. It supports the full Chainable interface: you can use via to sequence operations where later steps depend on earlier results.

Defining a DSL

First, define your DSL operations as a sealed interface:

// A simple Console DSL
sealed interface ConsoleOp<A> {
    record PrintLine<A>(String message, A next) implements ConsoleOp<A> {}
    record ReadLine<A>(Function<String, A> cont) implements ConsoleOp<A> {}
}

Building Programs

Lift operations into FreePath and compose them:

FreePath<ConsoleOp.Witness, Unit> print(String msg) {
    return FreePath.liftF(new PrintLine<>(msg, Unit.INSTANCE), consoleFunctor);
}

FreePath<ConsoleOp.Witness, String> readLine() {
    return FreePath.liftF(new ReadLine<>(s -> s), consoleFunctor);
}

// Build a program
FreePath<ConsoleOp.Witness, String> greet =
    print("What's your name?")
        .then(() -> readLine())
        .via(name -> print("Hello, " + name).map(_ -> name));

The program greet doesn't do anything yet. It's a data structure describing what should happen.

Interpretation

Interpret the program by providing a natural transformation to a target monad:

// Real interpreter: performs actual I/O
NaturalTransformation<ConsoleOp.Witness, IOKind.Witness> realInterpreter =
    new NaturalTransformation<>() {
        @Override
        public <A> Kind<IOKind.Witness, A> apply(Kind<ConsoleOp.Witness, A> fa) {
            ConsoleOp<A> op = ConsoleOp.narrow(fa);
            return switch (op) {
                case PrintLine(var msg, var next) ->
                    IO.delay(() -> { System.out.println(msg); return next; });
                case ReadLine(var cont) ->
                    IO.delay(() -> cont.apply(scanner.nextLine()));
            };
        }
    };

// Execute with real I/O
GenericPath<IOKind.Witness, String> result = greet.foldMap(realInterpreter, ioMonad);
String name = result.run().unsafeRun();

Testing with Mock Interpreters

The same program can be tested without real I/O:

// Test interpreter with canned responses
NaturalTransformation<ConsoleOp.Witness, StateKind.Witness> testInterpreter =
    /* returns canned values, records outputs */;

// Same program, different execution
GenericPath<StateKind.Witness, String> testResult =
    greet.foldMap(testInterpreter, stateMonad);

FreeApPath: The Free Applicative

FreeApPath<F, A> is more restricted: it implements Combinable but not Chainable. You can use zipWith to combine independent computations, but you cannot use via to make one computation depend on another's result.

Why would you want less power? Because the restriction enables static analysis. Since no step depends on previous results, you can inspect the entire structure before running anything.

Validation Example

// Validation operations
sealed interface ValidationOp<A> {
    record ValidateField<A>(String field, Predicate<String> check, A onSuccess)
        implements ValidationOp<A> {}
}

// Build validation program
FreeApPath<ValidationOp.Witness, User> validateUser =
    FreeApPath.liftF(new ValidateField<>("name", s -> !s.isBlank(), "name"), valFunctor)
        .zipWith3(
            FreeApPath.liftF(new ValidateField<>("email", s -> s.contains("@"), "email"), valFunctor),
            FreeApPath.liftF(new ValidateField<>("age", s -> Integer.parseInt(s) > 0, "age"), valFunctor),
            (name, email, age) -> new User(name, email, Integer.parseInt(age))
        );

All three validations are independent—they can run in parallel, and all errors can be collected rather than stopping at the first failure.

FreePath vs FreeApPath

When to Use Free Structures

Resource Management

"He had learned to think of the system as a living thing, with resources that had to be carefully husbanded."

— Lionel Davidson, Kolymsky Heights

Davidson's protagonist survived the Siberian wilderness by meticulous resource management. Software faces analogous challenges: database connections, file handles, network sockets. Acquire them, use them, release them—and make absolutely certain the release happens even when something goes wrong.

The bracket Pattern

bracket is the fundamental resource pattern: acquire, use, release. The release always runs, regardless of whether the use succeeds or fails:

IOPath<String> readFile = IOPath.bracket(
    () -> new FileInputStream("data.txt"),      // acquire
    stream -> new String(stream.readAllBytes()), // use
    stream -> stream.close()                     // release (always runs)
);

If readAllBytes() throws, the stream still closes. The exception propagates after cleanup completes.

bracketIO for Effectful Use

When the use phase itself returns an IOPath:

IOPath<List<String>> processFile = IOPath.bracketIO(
    () -> Files.newBufferedReader(path),
    reader -> IOPath.delay(() -> reader.lines().toList()),
    reader -> { try { reader.close(); } catch (Exception e) { /* log */ } }
);

withResource for AutoCloseable

When your resource implements AutoCloseable, withResource provides a cleaner syntax:

IOPath<List<String>> lines = IOPath.withResource(
    () -> Files.newBufferedReader(path),
    reader -> reader.lines().toList()
);

The reader is automatically closed after use, with proper exception handling.

withResourceIO Variant

IOPath<Config> config = IOPath.withResourceIO(
    () -> new FileInputStream("config.json"),
    stream -> IOPath.delay(() -> parseConfig(stream))
);

guarantee for Cleanup Actions

Sometimes you don't need acquire/release semantics—you just need to ensure something runs after a computation completes:

IOPath<Result> computation = fetchData()
    .guarantee(() -> log.info("Fetch completed"));

The guarantee runs whether fetchData() succeeds or fails.

guaranteeIO for Effectful Cleanup

IOPath<Result> withCleanup = process()
    .guaranteeIO(() -> IOPath.delay(() -> {
        cleanup();
        return Unit.INSTANCE;
    }));

Nested Resources

Resources often nest. bracket composes cleanly:

IOPath<Result> nested = IOPath.bracketIO(
    () -> acquireConnection(),
    connection -> IOPath.bracketIO(
        () -> connection.prepareStatement(sql),
        statement -> IOPath.bracket(
            () -> statement.executeQuery(),
            resultSet -> processResults(resultSet),
            resultSet -> resultSet.close()
        ),
        statement -> statement.close()
    ),
    connection -> connection.close()
);

Resources are released in reverse order: result set, then statement, then connection. If any step fails, all acquired resources are still released.

Resource Pattern Summary

Parallel Execution

"In cryptography, you sometimes have to try many keys simultaneously. The first one that works wins."

— Neal Stephenson, Cryptonomicon

Some computations are independent. Fetching user data and fetching preferences don't depend on each other; why wait for one to finish before starting the other?

parZipWith: Binary Parallelism

parZipWith runs two IOPath computations concurrently and combines their results:

IOPath<String> fetchUser = IOPath.delay(() -> {
    Thread.sleep(100);
    return "User123";
});

IOPath<String> fetchPrefs = IOPath.delay(() -> {
    Thread.sleep(100);
    return "DarkMode";
});

// Sequential: ~200ms (100ms + 100ms)
IOPath<String> sequential = fetchUser.zipWith(fetchPrefs, (u, p) -> u + "/" + p);

// Parallel: ~100ms (max of both)
IOPath<String> parallel = fetchUser.parZipWith(fetchPrefs, (u, p) -> u + "/" + p);

The operations are the same; the execution strategy differs.

parZip3 and parZip4

For three or four independent computations, use PathOps utilities:

IOPath<Dashboard> dashboard = PathOps.parZip3(
    fetchMetrics(),
    fetchAlerts(),
    fetchUsers(),
    Dashboard::new
);

IOPath<Report> report = PathOps.parZip4(
    fetchSales(),
    fetchInventory(),
    fetchCustomers(),
    fetchTrends(),
    Report::new
);

All operations start immediately and run concurrently. The result is available when all complete.

parSequenceIO: List Parallelism

When you have a dynamic number of independent operations:

List<IOPath<User>> fetches = userIds.stream()
    .map(id -> IOPath.delay(() -> userService.fetch(id)))
    .toList();

// Sequential: N * fetchTime
IOPath<List<User>> sequential = PathOps.sequenceIO(fetches);

// Parallel: ~1 * fetchTime (with enough threads)
IOPath<List<User>> parallel = PathOps.parSequenceIO(fetches);

parSequenceFuture for CompletableFuturePath

The same pattern works with CompletableFuturePath:

List<CompletableFuturePath<Data>> futures = /* ... */;
CompletableFuturePath<List<Data>> all = PathOps.parSequenceFuture(futures);

race: First to Finish

Sometimes you want whichever completes first:

IOPath<Config> primary = IOPath.delay(() -> fetchFromPrimary());
IOPath<Config> backup = IOPath.delay(() -> fetchFromBackup());

// Returns whichever config arrives first
IOPath<Config> fastest = primary.race(backup);

raceIO for Multiple Competitors

List<IOPath<Response>> sources = List.of(
    fetchFromRegionA(),
    fetchFromRegionB(),
    fetchFromRegionC()
);

IOPath<Response> fastest = PathOps.raceIO(sources);

Sequential vs Parallel: The Decision

The wrong choice doesn't break correctness—just performance. When in doubt, prefer sequential; parallelise when profiling shows it matters.

Resilience Patterns

"The protocol specified exponential backoff: wait one second, try again; wait two seconds, try again; wait four seconds..."

— Neal Stephenson, Cryptonomicon

Networks fail. Services timeout. Databases hiccup. Resilient code doesn't assume success—it plans for failure and recovers gracefully.

RetryPolicy

RetryPolicy encapsulates retry strategy: how many attempts, how long between them, which failures to retry:

// Fixed delay: 100ms between each of 3 attempts
RetryPolicy fixed = RetryPolicy.fixed(3, Duration.ofMillis(100));

// Exponential backoff: 1s, 2s, 4s, 8s...
RetryPolicy exponential = RetryPolicy.exponentialBackoff(5, Duration.ofSeconds(1));

// With jitter to prevent thundering herd
RetryPolicy jittered = RetryPolicy.exponentialBackoffWithJitter(5, Duration.ofSeconds(1));

Understanding Backoff Strategies

Jitter adds randomisation to prevent the "thundering herd" problem where many clients retry at exactly the same moment, overwhelming a recovering service.

Configuring Retry Behaviour

Policies are immutable but configurable through builder-style methods:

RetryPolicy policy = RetryPolicy.exponentialBackoff(5, Duration.ofMillis(100))
    .withMaxDelay(Duration.ofSeconds(30))   // Cap maximum wait
    .retryOn(IOException.class);             // Only retry I/O errors

Custom Retry Predicates

RetryPolicy selective = RetryPolicy.fixed(3, Duration.ofMillis(100))
    .retryIf(ex ->
        ex instanceof IOException ||
        ex instanceof TimeoutException ||
        (ex instanceof HttpException http && http.statusCode() >= 500));

Using withRetry

IOPath and CompletableFuturePath integrate directly with retry policies:

IOPath<Response> resilient = IOPath.delay(() -> httpClient.get(url))
    .withRetry(RetryPolicy.exponentialBackoff(3, Duration.ofSeconds(1)));

Convenience Method

For simple cases with default exponential backoff:

IOPath<Response> simple = IOPath.delay(() -> httpClient.get(url))
    .retry(3);  // 3 attempts with default backoff

Handling Exhausted Retries

When all attempts fail, RetryExhaustedException is thrown with the last failure as its cause:

try {
    resilient.unsafeRun();
} catch (RetryExhaustedException e) {
    log.error("All {} retries failed", e.getMessage());
    Throwable lastFailure = e.getCause();
    return fallbackValue;
}

Combining Resilience Patterns

Retry composes with other Path operations:

IOPath<Data> robust = IOPath.delay(() -> primarySource.fetch())
    .withRetry(RetryPolicy.exponentialBackoff(3, Duration.ofSeconds(1)))
    .handleErrorWith(e -> {
        log.warn("Primary exhausted, trying backup", e);
        return IOPath.delay(() -> backupSource.fetch())
            .withRetry(RetryPolicy.fixed(2, Duration.ofMillis(100)));
    })
    .recover(e -> {
        log.error("All sources failed", e);
        return Data.empty();
    });

Retry with Resource Management

IOPath<Result> resilientWithResource = IOPath.withResourceIO(
    () -> acquireConnection(),
    conn -> IOPath.delay(() -> conn.execute(query))
        .withRetry(RetryPolicy.fixed(3, Duration.ofMillis(50)))
);

The connection is acquired once; the query is retried within that connection.

Retry Pattern Quick Reference

Summary

These patterns are the fragments Stephenson described: individually useful, collectively transformative. Combined with the core Path types from earlier chapters, they provide a comprehensive toolkit for building robust, composable systems that handle the full spectrum of real-world complexity.

Previous: MutableContext

Monad Transformers: Combining Effects

"Shall I project a world?"

– Thomas Pynchon, The Crying of Lot 49

A transformer projects one monad's world into another's. EitherT takes the world of typed errors and projects it into whatever outer monad you choose: CompletableFuture, IO, List. The result is a new monad that combines both effects: asynchronous computation with error handling, deferred execution with failure semantics.

The problem being solved is fundamental: monads don't compose naturally. You can have a CompletableFuture<A>. You can have an Either<E, A>. But a CompletableFuture<Either<E, A>>, whilst perfectly expressible in Java, becomes awkward to work with. Every operation requires nested thenApply and map calls, peeling back layers manually. The ergonomics deteriorate rapidly.

Transformers restore sanity. EitherT<CompletableFutureKind.Witness, DomainError, Result> presents a unified interface: a single flatMap sequences async operations that might fail; a single map transforms successful results; error handling works at the combined level. The nesting is still there (it must be), but the transformer hides it.

Higher-Kinded-J provides transformers for common combinations: EitherT for typed errors, MaybeT and OptionalT for optional values, ReaderT for dependency injection, and StateT for state threading. Each takes an outer monad and adds its specific capability.

The Stacking Concept

    ┌─────────────────────────────────────────────────────────────┐
    │  WITHOUT TRANSFORMER                                        │
    │                                                             │
    │    CompletableFuture<Either<Error, Result>>                 │
    │                                                             │
    │    future.thenApply(either ->                               │
    │        either.map(result ->                                 │
    │            either2.map(r2 ->                                │
    │                ...)))   // Nesting grows unboundedly        │
    └─────────────────────────────────────────────────────────────┘

    ┌─────────────────────────────────────────────────────────────┐
    │  WITH TRANSFORMER                                           │
    │                                                             │
    │    EitherT<FutureWitness, Error, Result>                    │
    │                                                             │
    │    eitherT                                                  │
    │        .flatMap(result -> operation1(result))               │
    │        .flatMap(r1 -> operation2(r1))                       │
    │        .map(r2 -> finalTransform(r2))  // Flat!             │
    └─────────────────────────────────────────────────────────────┘

Same semantics. Vastly different ergonomics.

Available Transformers

What You'll Learn

Chapter Contents

1. Monad Transformers - Why monads stack poorly and what transformers solve
2. EitherT - Typed errors in any monadic context
3. OptionalT - Java Optional lifting
4. MaybeT - Maybe lifting
5. ReaderT - Environment threading
6. StateT - State management in effectful computation

Next: Monad Transformers

The Transformers:

Combining Monadic Effects

The Problem

When building applications, we often encounter scenarios where we need to combine different computational contexts or effects. For example:

• An operation might be asynchronous (represented by CompletableFuture).
• The same operation might also fail with specific domain errors (represented by Either<DomainError, Result>).
• An operation might need access to a configuration (using Reader) and also be asynchronous.
• A computation might accumulate logs (using Writer) and also potentially fail (using Maybe or Either).

Monads Stack Poorly

Directly nesting these monadic types, like CompletableFuture<Either<DomainError, Result>> or Reader<Config, Optional<Data>>, leads to complex, deeply nested code ("callback hell" or nested flatMap/map calls). It becomes difficult to sequence operations and handle errors or contexts uniformly.

For instance, an operation might need to be both asynchronous and handle potential domain-specific errors. Representing this naively leads to nested types like:

// A future that, when completed, yields either a DomainError or a SuccessValue
Kind<CompletableFutureKind.Witness, Either<DomainError, SuccessValue>> nestedResult;

But now, how do we map or flatMap over this stack without lots of boilerplate?

Monad Transformers: A wrapper to simplify nested Monads

Monad Transformers are a design pattern in functional programming used to combine the effects of two different monads into a single, new monad. They provide a standard way to "stack" monadic contexts, allowing you to work with the combined structure more easily using familiar monadic operations like map and flatMap.

A monad transformer T takes a monad M and produces a new monad T<M> that combines the effects of both T (conceptually) and M.

For example:

• MaybeT m a wraps a monad m and adds Maybe-like failure
• StateT s m a wraps a monad m and adds state-handling capability
• ReaderT r m a adds dependency injection (read-only environment)

They allow you to stack monadic behaviours.

Key characteristics:

1. Stacking: They allow "stacking" monadic effects in a standard way.
2. Unified Interface: The resulting transformed monad (e.g., EitherT<CompletableFutureKind, ...>) itself implements the Monad (and often MonadError, etc.) interface.
3. Abstraction: They hide the complexity of manually managing the nested structure. You can use standard map, flatMap, handleErrorWith operations on the transformed monad, and it automatically handles the logic for both underlying monads correctly.

Transformers in Higher-Kinded-J

Note: All transformers require an outer monad F where F extends WitnessArity<TypeArity.Unary>. This ensures the transformer can work with any properly-typed monad in the framework.

1. EitherT<F, L, R> (Monad Transformer)

• Definition: A monad transformer (EitherT) that combines an outer monad F with an inner Either<L, R>. Implemented as a record wrapping Kind<F, Either<L, R>>.
• Kind Interface: EitherTKind<F, L, R>
• Witness Type G: EitherTKind.Witness<F, L> (where F and L are fixed for a given type class instance)
• Helper: EitherTKindHelper (wrap, unwrap). Instances are primarily created via EitherT static factories (fromKind, right, left, fromEither, liftF).
• Type Class Instances:
  • EitherTMonad<F, L> (MonadError<EitherTKind.Witness<F, L>, L>)
• Notes: Simplifies working with nested structures like F<Either<L, R>>. Requires a Monad<F> instance for the outer monad F passed to its constructor. Implements MonadError for the inner Either's Left type L. See the Order Processing Example Walkthrough for practical usage with CompletableFuture as F.
• Usage: How to use the EitherT Monad Transformer

2. MaybeT<F, A> (Monad Transformer)

• Definition: A monad transformer (MaybeT) that combines an outer monad F with an inner Maybe<A>. Implemented as a record wrapping Kind<F, Maybe<A>>.
• Kind Interface: MaybeTKind<F, A>
• Witness Type G: MaybeTKind.Witness<F> (where F is fixed for a given type class instance)
• Helper: MaybeTKindHelper (wrap, unwrap). Instances are primarily created via MaybeT static factories (fromKind, just, nothing, fromMaybe, liftF).
• Type Class Instances:
  • MaybeTMonad<F> (MonadError<MaybeTKind.Witness<F>, Void>)
• Notes: Simplifies working with nested structures like F<Maybe<A>>. Requires a Monad<F> instance for the outer monad F. Implements MonadError where the error type is Void, corresponding to the Nothing state from the inner Maybe.
• Usage: How to use the MaybeT Monad Transformer

3. OptionalT<F, A> (Monad Transformer)

• Definition: A monad transformer (OptionalT) that combines an outer monad F with an inner java.util.Optional<A>. Implemented as a record wrapping Kind<F, Optional<A>>.
• Kind Interface: OptionalTKind<F, A>
• Witness Type G: OptionalTKind.Witness<F> (where F is fixed for a given type class instance)
• Helper: OptionalTKindHelper (wrap, unwrap). Instances are primarily created via OptionalT static factories (fromKind, some, none, fromOptional, liftF).
• Type Class Instances:
  • OptionalTMonad<F> (MonadError<OptionalTKind.Witness<F>, Void>)
• Notes: Simplifies working with nested structures like F<Optional<A>>. Requires a Monad<F> instance for the outer monad F. Implements MonadError where the error type is Void, corresponding to the Optional.empty() state from the inner Optional.
• Usage: How to use the OptionalT Monad Transformer

4. ReaderT<F, R, A> (Monad Transformer)

• Definition: A monad transformer (ReaderT) that combines an outer monad F with an inner Reader<R, A>-like behaviour (dependency on environment R). Implemented as a record wrapping a function R -> Kind<F, A>.
• Kind Interface: ReaderTKind<F, R, A>
• Witness Type G: ReaderTKind.Witness<F, R> (where F and R are fixed for a given type class instance)
• Helper: ReaderTKindHelper (wrap, unwrap). Instances are primarily created via ReaderT static factories (of, lift, reader, ask).
• Type Class Instances:
  • ReaderTMonad<F, R> (Monad<ReaderTKind<F, R, ?>>)
• Notes: Simplifies managing computations that depend on a read-only environment R while also involving other monadic effects from F. Requires a Monad<F> instance for the outer monad. The run() method of ReaderT takes R and returns Kind<F, A>.
• Usage: How to use the ReaderT Monad Transformer

5. StateT<S, F, A> (Monad Transformer)

• Definition: A monad transformer (StateT) that adds stateful computation (type S) to an underlying monad F. It represents a function S -> Kind<F, StateTuple<S, A>>.
• Kind Interface:StateTKind<S, F, A>
• Witness Type G:StateTKind.Witness<S, F> (where S for state and F for the underlying monad witness are fixed for a given type class instance; A is the value type parameter)
• Helper:StateTKindHelper (narrow, wrap, runStateT, evalStateT, execStateT, lift). Instances are created via StateT.create(), StateTMonad.of(), or StateTKind.lift().
• Type Class Instances:
  • StateTMonad<S, F> (Monad<StateTKind.Witness<S, F>>)
• Notes: Allows combining stateful logic with other monadic effects from F. Requires a Monad<F> instance for the underlying monad. The runStateT(initialState) method executes the computation, returning Kind<F, StateTuple<S, A>>.
• Usage:How to use the StateT Monad Transformer

Java-Focused Resources

Beginner Level: -Monad Transformers in Java: A Practical Guide - John McClean's clear explanation with Cyclops examples (15 min read) -Functional Programming in Java: Beyond Streams - Venkat Subramaniam discusses composition patterns (45 min watch) -Combining CompletableFuture with Optional: The Problem - Baeldung's treatment of nested monads (10 min read)

Intermediate Level: -Stacking Monads in Functional Java - ATT Israel Engineering team's practical examples (20 min read)

Advanced: -Free Monads and Monad Transformers - Rock the JVM's Scala-based but Java-applicable deep dive (30 min read)

General FP Concepts

-Monad Transformers Step by Step - Martin Grabmüller's classic paper, accessible even for Java developers (PDF, 40 min read) -Monad Transformer - HaskellWiki - Formal definitions with clear examples -What is a Monad Transformer? - FP Complete's tutorial with interactive examples

Related Libraries & Comparisons

-Cyclops-React Transformers - AOL's comprehensive Java FP library -Arrow-kt Resource - Kotlin's excellent documentation -Cats MTL - Scala's monad transformer library (advanced)

Community & Discussion

-Why are Monad Transformers useful? - Stack Overflow discussion with practical examples -Monad Transformers in Production - Real-world experiences from Java developers

Previous: Introduction Next: EitherT

The EitherT Transformer:

Combining Monadic Effects

EitherT Monad Transformer.

EitherT<F, L, R>: Combining any Monad F with Either<L, R>

The EitherT monad transformer allows you to combine the error-handling capabilities of Either<L, R> with another outer monad F. It transforms a computation that results in Kind<F, Either<L, R>> into a single monadic structure that can be easily composed. This is particularly useful when dealing with operations that can fail (represented by Left<L>) within an effectful context F (like asynchronous operations using CompletableFutureKind or computations involving state with StateKind).

• F: The witness type of the outer monad (e.g., CompletableFutureKind.Witness, OptionalKind.Witness). This monad handles the primary effect (e.g., asynchronicity, optionality).
• L: The Left type of the inner Either. This typically represents the error type for the computation or alternative result.
• R: The Right type of the inner Either. This typically represents the success value type.

public record EitherT<F, L, R>(@NonNull Kind<F, Either<L, R>> value) { 
  /* ... static factories ... */ }

It holds a value of type Kind<F, Either<L, R>>. The real power comes from its associated type class instance, EitherTMonad.

Essentially, EitherT<F, L, R> wraps a value of type Kind<F, Either<L, R>>. It represents a computation within the context F that will eventually yield an Either<L, R>.

The primary goal of EitherT is to provide a unified Monad interface (specifically MonadError for the L type) for this nested structure, hiding the complexity of manually handling both the outer F context and the inner Either context.

EitherTKind<F, L, R>: The Witness Type

Just like other types in the Higher-Kinded-J, EitherT needs a corresponding Kind interface to act as its witness type in generic functions. This is EitherTKind<F, L, R>.

• It extends Kind<G, R> where G (the witness for the combined monad) is EitherTKind.Witness<F, L>.
• F and L are fixed for a specific EitherT context, while R is the variable type parameter A in Kind<G, A>.

You'll primarily interact with this type when providing type signatures or receiving results from EitherTMonad methods.

EitherTKindHelper

• Provides widen and narrow methods to safely convert between the concrete EitherT<F, L, R> and its Kind representation (Kind<EitherTKind<F, L, ?>, R>).

EitherTMonad<F, L>: Operating on EitherT

• The EitherTMonad class implements MonadError<EitherTKind.Witness<F, L>, L>.

• It requires a Monad<F> instance for the outer monad F (where F extends WitnessArity<TypeArity.Unary>) to be provided during construction. This outer monad instance is used internally to handle the effects of F.
• It uses EITHER_T.widen and EITHER_T.narrow internally to manage the conversion between the Kind and the concrete EitherT.
• The error type E for MonadError is fixed to L, the 'Left' type of the inner Either. Error handling operations like raiseError(L l) will create an EitherT representing F<Left(l)>, and handleErrorWith allows recovering from such Left states.

// Example: F = CompletableFutureKind.Witness, L = DomainError
// 1. Get the MonadError instance for the outer monad F
MonadError<CompletableFutureKind.Witness, Throwable> futureMonad = CompletableFutureMonad.INSTANCE;

// 2. Create the EitherTMonad, providing the outer monad instance
//    This EitherTMonad handles DomainError for the inner Either.
MonadError<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, DomainError> eitherTMonad =
    new EitherTMonad<>(futureMonad);

// Now 'eitherTMonad' can be used to operate on Kind<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, A> values.

// Assume:
Monad<OptionalKind.Witness> optMonad = OptionalMonad.INSTANCE; // Outer Monad F=Optional
String errorL = "FAILED";
String successR = "OK";
Integer otherR = 123;

// 1. Lifting a pure 'Right' value: Optional<Right(R)>
EitherT<OptionalKind.Witness, String, String> etRight = EitherT.right(optMonad, successR);
// Resulting wrapped value: Optional.of(Either.right("OK"))

// 2. Lifting a pure 'Left' value: Optional<Left(L)>
EitherT<OptionalKind.Witness, String, Integer> etLeft = EitherT.left(optMonad, errorL);
// Resulting wrapped value: Optional.of(Either.left("FAILED"))

// 3. Lifting a plain Either: Optional<Either(input)>
Either<String, String> plainEither = Either.left(errorL);
EitherT<OptionalKind.Witness, String, String> etFromEither = EitherT.fromEither(optMonad, plainEither);
// Resulting wrapped value: Optional.of(Either.left("FAILED"))

// 4. Lifting an outer monad value F<R>: Optional<Right(R)>
Kind<OptionalKind.Witness, Integer> outerOptional = OPTIONAL.widen(Optional.of(otherR));
EitherT<OptionalKind.Witness, String, Integer> etLiftF = EitherT.liftF(optMonad, outerOptional);
// Resulting wrapped value: Optional.of(Either.right(123))

// 5. Wrapping an existing nested Kind: F<Either<L, R>>
Kind<OptionalKind.Witness, Either<String, String>> nestedKind =
    OPTIONAL.widen(Optional.of(Either.right(successR)));
EitherT<OptionalKind.Witness, String, String> etFromKind = EitherT.fromKind(nestedKind);
// Resulting wrapped value: Optional.of(Either.right("OK"))

// Accessing the wrapped value:
Kind<OptionalKind.Witness, Either<String, String>> wrappedValue = etRight.value();
Optional<Either<String, String>> unwrappedOptional = OPTIONAL.narrow(wrappedValue);
// unwrappedOptional is Optional.of(Either.right("OK"))

public class EitherTExample {

  // --- Setup ---

  // Assume DomainError is a sealed interface for specific errors
  // Re-defining a local DomainError to avoid dependency on the full DomainError hierarchy for this isolated example.
  // In a real scenario, you would use the shared DomainError.
  record DomainError(String message) {}
  record ValidatedData(String data) {}
  record ProcessedData(String data) {}

  MonadError<CompletableFutureKind.Witness, Throwable> futureMonad = CompletableFutureMonad.INSTANCE;
  MonadError<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, DomainError> eitherTMonad =
          new EitherTMonad<>(futureMonad);

  // --- Workflow Steps (returning Kinds) ---

  // Simulates a sync validation returning Either
  Kind<EitherKind.Witness<DomainError>, ValidatedData> validateSync(String input) {
    System.out.println("Validating synchronously...");
    if (input.isEmpty()) {
      return EITHER.widen(Either.left(new DomainError("Input empty")));
    }
    return EITHER.widen(Either.right(new ValidatedData("Validated:" + input)));
  }

  // Simulates an async processing step returning Future<Either>
  Kind<CompletableFutureKind.Witness, Either<DomainError, ProcessedData>> processAsync(ValidatedData vd) {
    System.out.println("Processing asynchronously for: " + vd.data());
    CompletableFuture<Either<DomainError, ProcessedData>> future =
            CompletableFuture.supplyAsync(() -> {
              try {
                Thread.sleep(50);
              } catch (InterruptedException e) { /* ignore */ }
              if (vd.data().contains("fail")) {
                return Either.left(new DomainError("Processing failed"));
              }
              return Either.right(new ProcessedData("Processed:" + vd.data()));
            });
    return FUTURE.widen(future);
  }

  // Function to run the workflow for given input
  Kind<CompletableFutureKind.Witness, Either<DomainError, ProcessedData>> runWorkflow(String initialInput) {

    // Start with initial data lifted into EitherT
    Kind<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, String> initialET = eitherTMonad.of(initialInput);

    // Step 1: Validate (Sync Either lifted into EitherT)
    Kind<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, ValidatedData> validatedET =
            eitherTMonad.flatMap(
                    input -> {
                      // Call sync step returning Kind<EitherKind.Witness,...>
                      // Correction 1: Use EitherKind.Witness here
                      Kind<EitherKind.Witness<DomainError>, ValidatedData> validationResult = validateSync(input);
                      // Lift the Either result into EitherT using fromEither
                      return EitherT.fromEither(futureMonad, EITHER.narrow(validationResult));
                    },
                    initialET
            );

    // Step 2: Check Inventory (Asynchronous - returns Future<Either<DomainError, Unit>>) 
    Kind<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, WorkflowContext> inventoryET =
        eitherTMonad.flatMap( // Chain from validation result
            ctx -> { // Executed only if validatedET was F<Right(...)>
                // Call async step -> Kind<CompletableFutureKind.Witness, Either<DomainError, Unit>> 
                Kind<CompletableFutureKind.Witness, Either<DomainError, Unit>> inventoryCheckFutureKind =
                    steps.checkInventoryAsync(ctx.validatedOrder().productId(), ctx.validatedOrder().quantity());
    
                // Lift the F<Either> directly into EitherT using fromKind
                Kind<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, Unit> inventoryCheckET = 
                    EitherT.fromKind(inventoryCheckFutureKind);
    
                // If inventory check resolves to Right (now Right(Unit.INSTANCE)), update context.
 
                return eitherTMonad.map(unitInstance -> ctx.withInventoryChecked(), inventoryCheckET);
            },
            validatedET // Input is result of validation step
        );

    // Unwrap the final EitherT to get the underlying Future<Either>
    return ((EitherT<CompletableFutureKind.Witness, DomainError, ProcessedData>) processedET).value();
  }

  public void asyncWorkflowErrorHandlingExample(){
    // --- Workflow Definition using EitherT ---

    // Input data
    String inputData = "Data";
    String badInputData = "";
    String processingFailData = "Data-fail";

    // --- Execution ---
    System.out.println("--- Running Good Workflow ---");

    Kind<CompletableFutureKind.Witness, Either<DomainError, ProcessedData>> resultGoodKind = runWorkflow(inputData);
    System.out.println("Good Result: "+FUTURE.join(resultGoodKind));
    // Expected: Right(ProcessedData[data=Processed:Validated:Data])

    System.out.println("\n--- Running Bad Input Workflow ---");

    Kind<CompletableFutureKind.Witness, Either<DomainError, ProcessedData>> resultBadInputKind = runWorkflow(badInputData);
    System.out.println("Bad Input Result: "+ FUTURE.join(resultBadInputKind));
    // Expected: Left(DomainError[message=Input empty])

    System.out.println("\n--- Running Processing Failure Workflow ---");

    Kind<CompletableFutureKind.Witness, Either<DomainError, ProcessedData>> resultProcFailKind = runWorkflow(processingFailData);
    System.out.println("Processing Fail Result: "+FUTURE.join(resultProcFailKind));
    // Expected: Left(DomainError[message=Processing failed])

  }
  public static void main(String[] args){
    EitherTExample example = new EitherTExample();
    example.asyncWorkflowErrorHandlingExample();

  }

}

// --- From OrderWorkflowRunner.java ---
// Assume setup:
// F = CompletableFutureKind<?>
// L = DomainError
// futureMonad = CompletableFutureMonad.INSTANCE;
// eitherTMonad = new EitherTMonad<>(futureMonad);
// steps = new OrderWorkflowSteps(dependencies); // Contains workflow logic

// Initial Context (lifted)
WorkflowContext initialContext = WorkflowContext.start(orderData);
Kind<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, WorkflowContext> initialET =
    eitherTMonad.of(initialContext); // F<Right(initialContext)>

// Step 1: Validate Order (Synchronous - returns Either)
Kind<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, WorkflowContext> validatedET =
    eitherTMonad.flatMap( // Use flatMap on EitherTMonad
        ctx -> { // Lambda receives WorkflowContext if initialET was Right
            // Call sync step -> Either<DomainError, ValidatedOrder>
            Either<DomainError, ValidatedOrder> syncResultEither =
                EITHER.narrow(steps.validateOrder(ctx.initialData()));

            // Lift sync Either into EitherT: -> F<Either<DomainError, ValidatedOrder>>
            Kind<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, ValidatedOrder>
                validatedOrderET = EitherT.fromEither(futureMonad, syncResultEither);

            // If validation produced Left, map is skipped.
            // If validation produced Right(vo), map updates the context: F<Right(ctx.withValidatedOrder(vo))>
            return eitherTMonad.map(ctx::withValidatedOrder, validatedOrderET);
        },
        initialET // Input to the flatMap
    );

// Step 2: Check Inventory (Asynchronous - returns Future<Either<DomainError, Void>>)
Kind<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, WorkflowContext> inventoryET =
    eitherTMonad.flatMap( // Chain from validation result
        ctx -> { // Executed only if validatedET was F<Right(...)>
            // Call async step -> Kind<CompletableFutureKind.Witness, Either<DomainError, Void>>
            Kind<CompletableFutureKind.Witness, Either<DomainError, Void>> inventoryCheckFutureKind =
                steps.checkInventoryAsync(ctx.validatedOrder().productId(), ctx.validatedOrder().quantity());

            // Lift the F<Either> directly into EitherT using fromKind
            Kind<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, Void> inventoryCheckET =
                EitherT.fromKind(inventoryCheckFutureKind);

            // If inventory check resolves to Right, update context. If Left, map is skipped.
            return eitherTMonad.map(ignored -> ctx.withInventoryChecked(), inventoryCheckET);
        },
        validatedET // Input is result of validation step
    );

// Step 4: Create Shipment (Asynchronous with Recovery)
Kind<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, WorkflowContext> shipmentET =
    eitherTMonad.flatMap( // Chain from previous step
        ctx -> {
            // Call async shipment step -> F<Either<DomainError, ShipmentInfo>>
            Kind<CompletableFutureKind.Witness, Either<DomainError, ShipmentInfo>> shipmentAttemptFutureKind =
                steps.createShipmentAsync(ctx.validatedOrder().orderId(), ctx.validatedOrder().shippingAddress());

            // Lift into EitherT
            Kind<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, ShipmentInfo> shipmentAttemptET =
                 EitherT.fromKind(shipmentAttemptFutureKind);

            // *** Error Handling using MonadError ***
            Kind<EitherTKind.Witness<CompletableFutureKind.Witness, DomainError>, ShipmentInfo> recoveredShipmentET =
                eitherTMonad.handleErrorWith( // Operates on the EitherT value
                    shipmentAttemptET,
                    error -> { // Lambda receives DomainError if shipmentAttemptET resolves to Left(error)
                        if (error instanceof DomainError.ShippingError se && "Temporary Glitch".equals(se.reason())) {
                           // Specific recoverable error: Return a *successful* EitherT
                           return eitherTMonad.of(new ShipmentInfo("DEFAULT_SHIPPING_USED"));
                        } else {
                           // Non-recoverable error: Re-raise it within EitherT
                           return eitherTMonad.raiseError(error); // Returns F<Left(error)>
                        }
                    });

            // Map the potentially recovered result to update context
            return eitherTMonad.map(ctx::withShipmentInfo, recoveredShipmentET);
        },
        paymentET // Assuming paymentET was the previous step
    );

// ... rest of workflow ...

// Final unwrap
// EitherT<CompletableFutureKind.Witness, DomainError, FinalResult> finalET = ...;
// Kind<CompletableFutureKind.Witness, Either<DomainError, FinalResult>> finalResultKind = finalET.value();

Java-Focused Resources

Beginner Level: -Error Handling with Either in Java - Baeldung's introduction to Either (10 min read) -CompletableFuture Error Handling Patterns - Tomasz Nurkiewicz's comparison to traditional async error handling (15 min read) -Railway Oriented Programming in Java - Scott Wlaschin's classic talk adapted to Java contexts (60 min watch)

Intermediate Level: -Combining Async and Error Handling in Java - Real-world async error workflows (20 min read)

Advanced: -Type-Safe Error Handling at Scale - Zalando's production experience (conference talk, 40 min)

General FP Concepts

-Railway Oriented Programming - F# for Fun and Profit's accessible explanation (20 min read) -Handling Errors Without Exceptions - Chapter 4 from "Functional Programming in Scala" (free excerpt) -Either Type - Wikipedia - Formal definition and language comparisons

Related Libraries & Comparisons

-Arrow Either - Kotlin's excellent API design -Result Type in Rust - See how a systems language solves this problem

Community & Discussion

-Either vs Exceptions in Java - Stack Overflow debate with practical insights -Using Either in Production Java Code - Hacker News discussion with war stories

Previous: Monad Transformers Next: OptionalT

The OptionalT Transformer:

Combining Monadic Effects with java.util.Optional

OptionalT Monad Transformer

The OptionalT monad transformer (short for Optional Transformer) is designed to combine the semantics of java.util.Optional<A> (representing a value that might be present or absent) with an arbitrary outer monad F. It effectively allows you to work with computations of type Kind<F, Optional<A>> as a single, unified monadic structure.

This is particularly useful when operations within an effectful context F (such as asynchronicity with CompletableFutureKind, non-determinism with ListKind, or dependency injection with ReaderKind) can also result in an absence of a value (represented by Optional.empty()).

Structure

OptionalT<F, A>: The Core Data Type

OptionalT<F, A> is a record that wraps a computation yielding Kind<F, Optional<A>>.

public record OptionalT<F, A>(@NonNull Kind<F, Optional<A>> value)
    implements OptionalTKind<F, A> {
  // ... static factory methods ...
}

• F: The witness type of the outer monad (e.g., CompletableFutureKind.Witness, ListKind.Witness). This monad encapsulates the primary effect of the computation.
• A: The type of the value that might be present within the **Optional, which itself is within the context of F.
• value: The core wrapped value of type **Kind<F, Optional<A>>. This represents an effectful computation F that, upon completion, yields a java.util.Optional<A>.

OptionalTKind<F, A>: The Witness Type

For integration with Higher-Kinded-J's generic programming model, OptionalTKind<F, A> acts as the higher-kinded type witness.

• It extends Kind<G, A>, where G (the witness for the combined OptionalT monad) is OptionalTKind.Witness<F>.
• The outer monad F is fixed for a particular OptionalT context, while A is the variable type parameter representing the value inside the Optional.

public interface OptionalTKind<F, A> extends Kind<OptionalTKind.Witness<F>, A> {
  // Witness type G = OptionalTKind.Witness<F>
  // Value type A = A (from Optional<A>)
}

OptionalTKindHelper: Utility for Wrapping and Unwrapping

OptionalTKindHelper is a final utility class providing static methods to seamlessly convert between the concrete OptionalT<F, A> type and its Kind representation (Kind<OptionalTKind.Witness<F>, A>).

public enum OptionalTKindHelper {
   
  OPTIONAL_T;
  
    // Unwraps Kind<OptionalTKind.Witness<F>, A> to OptionalT<F, A>
    public  <F, A> @NonNull OptionalT<F, A> narrow(
        @Nullable Kind<OptionalTKind.Witness<F>, A> kind);

    // Wraps OptionalT<F, A> into OptionalTKind<F, A>
    public  <F, A> @NonNull OptionalTKind<F, A> widen(
        @NonNull OptionalT<F, A> optionalT);
}

Internally, it uses a private record OptionalTHolder to implement OptionalTKind, but this is an implementation detail.

OptionalTMonad<F>: Operating on OptionalT

The OptionalTMonad<F> class implements MonadError<OptionalTKind.Witness<F>, Unit>. This provides the standard monadic operations (of, map, flatMap, ap) and error handling capabilities for the OptionalT structure. The error type E for MonadError is fixed to Unit signifying that an "error" in this context is the Optional.empty() state within F<Optional<A>>.

• It requires a Monad<F> instance for the outer monad F (where F extends WitnessArity<TypeArity.Unary>), which must be supplied during construction. This outerMonad is used to manage and sequence the effects of F.

// Example: F = CompletableFutureKind.Witness
// 1. Get the Monad instance for the outer monad F
Monad<CompletableFutureKind.Witness> futureMonad = CompletableFutureMonad.INSTANCE;

// 2. Create the OptionalTMonad
OptionalTMonad<CompletableFutureKind.Witness> optionalTFutureMonad =
    new OptionalTMonad<>(futureMonad);

// Now 'optionalTFutureMonad' can be used to operate on
// Kind<OptionalTKind.Witness<CompletableFutureKind.Witness>, A> values.

public void createExample() {
    // --- Setup ---
    // Outer Monad F = CompletableFutureKind.Witness
    Monad<CompletableFutureKind.Witness> futureMonad = CompletableFutureMonad.INSTANCE;
    String presentValue = "Data";
    Integer numericValue = 123;

    // 1. `OptionalT.fromKind(Kind<F, Optional<A>> value)`
    //    Wraps an existing F<Optional<A>>.
    Kind<CompletableFutureKind.Witness, Optional<String>> fOptional =
        FUTURE.widen(CompletableFuture.completedFuture(Optional.of(presentValue)));
    OptionalT<CompletableFutureKind.Witness, String> ot1 = OptionalT.fromKind(fOptional);
    // Value: CompletableFuture<Optional.of("Data")>

    // 2. `OptionalT.some(Monad<F> monad, A a)`
    //    Creates an OptionalT with a present value, F<Optional.of(a)>.
    OptionalT<CompletableFutureKind.Witness, String> ot2 = OptionalT.some(futureMonad, presentValue);
    // Value: CompletableFuture<Optional.of("Data")>

    // 3. `OptionalT.none(Monad<F> monad)`
    //    Creates an OptionalT representing an absent value, F<Optional.empty()>.
    OptionalT<CompletableFutureKind.Witness, String> ot3 = OptionalT.none(futureMonad);
    // Value: CompletableFuture<Optional.empty()>

    // 4. `OptionalT.fromOptional(Monad<F> monad, Optional<A> optional)`
    //    Lifts a plain java.util.Optional into OptionalT, F<Optional<A>>.
    Optional<Integer> optInt = Optional.of(numericValue);
    OptionalT<CompletableFutureKind.Witness, Integer> ot4 = OptionalT.fromOptional(futureMonad, optInt);
    // Value: CompletableFuture<Optional.of(123)>


    Optional<Integer> optEmpty = Optional.empty();
    OptionalT<CompletableFutureKind.Witness, Integer> ot4Empty = OptionalT.fromOptional(futureMonad, optEmpty);
    // Value: CompletableFuture<Optional.empty()>


    // 5. `OptionalT.liftF(Monad<F> monad, Kind<F, A> fa)`
    //    Lifts an F<A> into OptionalT. If A is null, it becomes F<Optional.empty()>, otherwise F<Optional.of(A)>.
    Kind<CompletableFutureKind.Witness, String> fValue =
        FUTURE.widen(CompletableFuture.completedFuture(presentValue));
    OptionalT<CompletableFutureKind.Witness, String> ot5 = OptionalT.liftF(futureMonad, fValue);
    // Value: CompletableFuture<Optional.of("Data   ")>

    Kind<CompletableFutureKind.Witness, String> fNullValue =
        FUTURE.widen(CompletableFuture.completedFuture(null)); // F<null>
    OptionalT<CompletableFutureKind.Witness, String> ot5Null = OptionalT.liftF(futureMonad, fNullValue);
    // Value: CompletableFuture<Optional.empty()> (because the value inside F was null)


    // Accessing the wrapped value:
    Kind<CompletableFutureKind.Witness, Optional<String>> wrappedFVO = ot1.value();
    CompletableFuture<Optional<String>> futureOptional = FUTURE.narrow(wrappedFVO);
    futureOptional.thenAccept(optStr -> System.out.println("ot1 result: " + optStr));
  }

public static class OptionalTAsyncExample {

    // --- Monad Setup ---
    static final Monad<CompletableFutureKind.Witness> futureMonad = CompletableFutureMonad.INSTANCE;
    static final OptionalTMonad<CompletableFutureKind.Witness> optionalTFutureMonad =
        new OptionalTMonad<>(futureMonad);
    static final ExecutorService executor = Executors.newFixedThreadPool(2);

    public static Kind<CompletableFutureKind.Witness, Optional<User>> fetchUserAsync(String userId) {
      return FUTURE.widen(CompletableFuture.supplyAsync(() -> {
        System.out.println("Fetching userLogin " + userId + " on " + Thread.currentThread().getName());
        try {
          TimeUnit.MILLISECONDS.sleep(50);
        } catch (InterruptedException e) { /* ignore */ }
        return "user1".equals(userId) ? Optional.of(new User(userId, "Alice")) : Optional.empty();
      }, executor));
    }

    public static Kind<CompletableFutureKind.Witness, Optional<UserProfile>> fetchProfileAsync(String userId) {
      return FUTURE.widen(CompletableFuture.supplyAsync(() -> {
        System.out.println("Fetching profile for " + userId + " on " + Thread.currentThread().getName());
        try {
          TimeUnit.MILLISECONDS.sleep(50);
        } catch (InterruptedException e) { /* ignore */ }
        return "user1".equals(userId) ? Optional.of(new UserProfile(userId, "Loves HKJ")) : Optional.empty();
      }, executor));
    }

    public static Kind<CompletableFutureKind.Witness, Optional<UserPreferences>> fetchPrefsAsync(String userId) {
      return FUTURE.widen(CompletableFuture.supplyAsync(() -> {
        System.out.println("Fetching preferences for " + userId + " on " + Thread.currentThread().getName());
        try {
          TimeUnit.MILLISECONDS.sleep(50);
        } catch (InterruptedException e) { /* ignore */ }
        // Simulate preferences sometimes missing even for a valid userLogin
        return "user1".equals(userId) && Math.random() > 0.3 ? Optional.of(new UserPreferences(userId, "dark")) : Optional.empty();
      }, executor));
    }

    // --- Service Stubs (simulating async calls returning Future<Optional<T>>) ---

    // --- Workflow using OptionalT ---
    public static OptionalT<CompletableFutureKind.Witness, UserPreferences> getFullUserPreferences(String userId) {
      // Start by fetching the userLogin, lifting into OptionalT
      OptionalT<CompletableFutureKind.Witness, User> userOT =
          OptionalT.fromKind(fetchUserAsync(userId));

      // If userLogin exists, fetch profile
      OptionalT<CompletableFutureKind.Witness, UserProfile> profileOT =
          OPTIONAL_T.narrow(
              optionalTFutureMonad.flatMap(
                  userLogin -> OPTIONAL_T.widen(OptionalT.fromKind(fetchProfileAsync(userLogin.id()))),
                  OPTIONAL_T.widen(userOT)
              )
          );

      // If profile exists, fetch preferences
      OptionalT<CompletableFutureKind.Witness, UserPreferences> preferencesOT =
          OPTIONAL_T.narrow(
              optionalTFutureMonad.flatMap(
                  profile -> OPTIONAL_T.widen(OptionalT.fromKind(fetchPrefsAsync(profile.userId()))),
                  OPTIONAL_T.widen(profileOT)
              )
          );
      return preferencesOT;
    }

    // Workflow with recovery / default
    public static OptionalT<CompletableFutureKind.Witness, UserPreferences> getPrefsWithDefault(String userId) {
      OptionalT<CompletableFutureKind.Witness, UserPreferences> prefsAttemptOT = getFullUserPreferences(userId);

      Kind<OptionalTKind.Witness<CompletableFutureKind.Witness>, UserPreferences> recoveredPrefsOTKind =
          optionalTFutureMonad.handleErrorWith(
              OPTIONAL_T.widen(prefsAttemptOT),
              (Unit v) -> { // This lambda is called if prefsAttemptOT results in F<Optional.empty()>
                System.out.println("Preferences not found for " + userId + ", providing default.");
                // Lift a default preference into OptionalT
                UserPreferences defaultPrefs = new UserPreferences(userId, "default-light");
                return OPTIONAL_T.widen(OptionalT.some(futureMonad, defaultPrefs));
              }
          );
      return OPTIONAL_T.narrow(recoveredPrefsOTKind);
    }

    public static void main(String[] args) {
      System.out.println("--- Attempting to get preferences for existing userLogin (user1) ---");
      OptionalT<CompletableFutureKind.Witness, UserPreferences> resultUser1OT = getFullUserPreferences("user1");
      CompletableFuture<Optional<UserPreferences>> future1 =
          FUTURE.narrow(resultUser1OT.value());

      future1.whenComplete((optPrefs, ex) -> {
        if (ex != null) {
          System.err.println("Error for user1: " + ex.getMessage());
        } else {
          System.out.println("User1 Preferences: " + optPrefs.map(UserPreferences::toString).orElse("NOT FOUND"));
        }
      });


      System.out.println("\n--- Attempting to get preferences for non-existing userLogin (user2) ---");
      OptionalT<CompletableFutureKind.Witness, UserPreferences> resultUser2OT = getFullUserPreferences("user2");
      CompletableFuture<Optional<UserPreferences>> future2 =
          FUTURE.narrow(resultUser2OT.value());

      future2.whenComplete((optPrefs, ex) -> {
        if (ex != null) {
          System.err.println("Error for user2: " + ex.getMessage());
        } else {
          System.out.println("User2 Preferences: " + optPrefs.map(UserPreferences::toString).orElse("NOT FOUND (as expected)"));
        }
      });

      System.out.println("\n--- Attempting to get preferences for user1 WITH DEFAULT ---");
      OptionalT<CompletableFutureKind.Witness, UserPreferences> resultUser1WithDefaultOT = getPrefsWithDefault("user1");
      CompletableFuture<Optional<UserPreferences>> future3 =
          FUTURE.narrow(resultUser1WithDefaultOT.value());

      future3.whenComplete((optPrefs, ex) -> {
        if (ex != null) {
          System.err.println("Error for user1 (with default): " + ex.getMessage());
        } else {
          // This will either be the fetched prefs or the default.
          System.out.println("User1 Preferences (with default): " + optPrefs.map(UserPreferences::toString).orElse("THIS SHOULD NOT HAPPEN if default works"));
        }
        // Wait for async operations to complete for demonstration
        try {
          TimeUnit.SECONDS.sleep(1);
        } catch (InterruptedException e) {
          Thread.currentThread().interrupt();
        }
        executor.shutdown();
      });
    }

    // --- Domain Model ---
    record User(String id, String name) {
    }

    record UserProfile(String userId, String bio) {
    }

    record UserPreferences(String userId, String theme) {
    }
  }