Higher-Kinded-J: Composable Effects and Advanced Optics for Java

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 one approach to building robust applications, where effects and structure compose in the same vocabulary. At the edge of a service, Mapping at the Boundary turns the DTO-to-domain mapper into compile-time codegen that never loses an error, and for services that need several execution modes, Effect Handlers let you define domain operations as data and interpret them differently for production, testing, or audit.

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

What You Get

Two artefacts, before any theory. The first is the shape of the code you write: a railway where success travels one track and failure the other, and every step reads top-to-bottom.

// 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 second is what a client sees when the data is bad. A request with five defects (one inside a nested record, one on the second element of a list), answered by one response, with nobody writing a line of error-handling code to produce it:

{
  "valid": false,
  "errors": [
    { "path": "id",             "message": "not a UUID (expected e.g. 123e4567-e89b-12d3-a456-426614174000)" },
    { "path": "customer.email", "message": "not an email address" },
    { "path": "lines.1.price",  "message": "not a number in plain notation (expected e.g. 123.45)" },
    { "path": "placedAt",       "message": "not an ISO-8601 instant (expected e.g. 2026-07-28T12:34:56Z)" },
    { "path": "status",         "message": "unknown OrderStatus (expected one of NEW, PAID, SHIPPED)" }
  ],
  "errorCount": 5
}

It falls out of one spec interface and one annotation, and the mapping capstone builds it end to end, proven by a test the build runs. The client fixes all five and resubmits once.

Getting Started

One line configures the dependencies, the annotation processors, -parameters, the preview flags and compile-time Path checking:

// build.gradle.kts
plugins {
    id("io.github.higher-kinded-j.hkj") version "LATEST_VERSION"
}

• Quickstart: Gradle and Maven setup, including the Maven plugin and the required Java 25 preview flags, and your first Effect Paths in five minutes
• Where to Start: one question, five answers, and the tool each one points at
• Cheat Sheet: a one-page operator reference

The Bridge: Effects Meet Optics

What makes Higher-Kinded-J unique is that Effect Paths and the Focus DSL speak the same language. Effect Paths are the effects, what the computation does: fetch, fail, wait, accumulate. Focus Paths are the optics, where the data lives: a field, an optional field, every element of a list. Both compose with via, and when you need to cross between them, the bridge connects the two worlds:

flowchart TB
    subgraph effects["Effects: Effect Paths"]
        direction TB
        E1["MaybePath"] ~~~ E2["EitherPath"] ~~~ E3["TryPath"] ~~~ E4["ValidationPath"]
        E5["EitherOrBothPath"] ~~~ E6["IOPath"] ~~~ E7["VTaskPath"] ~~~ E8["VStreamPath"]
    end
    subgraph optics["Optics: Focus Paths"]
        direction TB
        O1["FocusPath"] ~~~ O2["AffinePath"]
        O3["TraversalPath"]
    end
    effects -->|".focus(path)<br/>navigate the data inside the effect"| B["The bridge"]
    optics -->|".toEitherPath()<br/>.toMaybePath()<br/>lift the optic into an effect"| B
    subgraph one["One composition"]
        direction TB
        S1["userService.findById(id)<br/>effect: fetch"] --> S2[".focus(UserFocus.address())<br/>optics: navigate"]
        S2 --> S3[".via(validateAddress)<br/>effect: validate"]
        S3 --> S4[".focus(AddressFocus.city())<br/>optics: extract"]
        S4 --> S5[".map(String::toUpperCase)<br/>effect: transform"]
    end
    B --> S1

    classDef effect fill:#8caaee,stroke:#1e66f5,color:#232634
    classDef optic fill:#a6d189,stroke:#40a02b,color:#232634
    classDef bridge fill:#e5c890,stroke:#df8e1d,color:#232634
    class E1,E2,E3,E4,E5,E6,E7,E8,S1,S3,S5 effect
    class O1,O2,O3,S2,S4 optic
    class B bridge

// 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 Java has been missing: effects and structure, composition and navigation, one vocabulary.

Discover Optics Integration →

Why Higher-Kinded-J?

Modern Java handed you records, sealed interfaces, and pattern matching. What it didn't hand you is a way to make them compose: errors that chain instead of nest, validation that collects every failure instead of stopping at the first, deep immutable updates in one line instead of nested with… calls, and typed errors that survive a network hop. Higher-Kinded-J is the missing layer.

You don't need to learn an esoteric functional library to feel the benefit. Each capability replaces something you already reach for today:

And unlike any of those tools, effects and data navigation speak the same language: the Effect-Optics bridge above is something no other Java library offers.

What's in the Library

Each capability has a chapter that opens with the problem it solves and closes with a capstone. The short version of each, with a quick example folded underneath:

Effect Path API

A railway model for computation: map, via and recover work identically whether you are handling optional values, typed errors, accumulated validations, exceptions or deferred side effects. ForPath comprehensions sequence steps by name, VTaskPath and VStreamPath put structured concurrency on virtual threads behind the same vocabulary, and the lazy carriers chain path-native resilience that treats a business Left as a value, never as a failure to retry.

VResultPath<OrderError, Reservation> guarded =
    reserveInventory(order)
        .withRetry(error -> error instanceof OrderError.SystemError,
            RetryPolicy.exponentialBackoffWithJitter(3, Duration.ofMillis(200)))
        .withTimeout(Duration.ofSeconds(5),
            () -> OrderError.SystemError.timeout("inventory", Duration.ofSeconds(5)));

Explore the Effect Path API →

Optics

The most comprehensive optics implementation available for Java: lenses, prisms, isos, affines, traversals, folds and setters, all composable, generated from annotations on records, sealed interfaces, collections and types you don't own (Jackson, JOOQ, Immutables, Lombok, AutoValue, Protocol Buffers). Filtered and indexed traversals, and 31 container types across the JDK and five third-party collection libraries widening to the right path type automatically.

@GenerateLenses @GenerateFocus
public record Street(String name, int number) {}

@GenerateLenses @GenerateFocus
public record Address(Street street, String city) {}

@GenerateLenses @GenerateFocus
public record User(String name, Address address) {}

User updated = UserFocus.address().street().name().set("New Street", user);

Explore Optics →

Mapping at the Boundary

One spec interface and one annotation replace the hand-written mapper. @GenerateMapping derives both directions at compile time for record, bean-shaped and generic wires of any width: a total build out, an accumulating parse back that locates every bad field, and both PATCH styles as write-backs. A stock codec vocabulary covers the standard conversions, so a typical boundary needs no hand-written leaves, and every tier is law-checked and pinned by golden files.

@GenerateMapping
interface OrderMapping extends MappingSpec<Order, OrderDto> {
  default ValidatedPrism<String, UUID> id()            { return uuid(); }
  default ValidatedPrism<String, LocalDate> placedOn() { return localDate(); }
  default ValidatedPrism<String, OrderStatus> status() { return enumByName(OrderStatus.class); }
  default ValidatedPrism<String, BigDecimal> total()   { return bigDecimal(); }
}

OrderMappingImpl.INSTANCE.parse(new OrderDto("NOPE", "28/07/2026", "SHIPPED", "1E+3"));
// Invalid(NonEmptyList[
//   id: not a UUID (expected e.g. 123e4567-e89b-12d3-a456-426614174000),
//   placedOn: not an ISO-8601 date (expected e.g. 2026-07-28),
//   status: unknown OrderStatus (expected one of NEW, PAID, CANCELLED),
//   total: not a number in plain notation (expected e.g. 123.45)])

Explore Mapping at the Boundary →

Effect Handlers

Algebraic-effect-style programming via Free monads and interpreters. Define domain operations as a sealed interface with record variants, compose several algebras with @ComposeEffects, then write one interpreter per mode (production, test, dry-run, audit) and run the same program unchanged through each. Testing is mock-free through Id interpreters, and ProgramAnalyser inspects a program before any side effect executes.

@EffectAlgebra
public sealed interface PaymentGatewayOp<A>
    permits PaymentGatewayOp.Authorise, PaymentGatewayOp.Charge, PaymentGatewayOp.Refund {

  record Authorise<A>(Money amount, PaymentMethod method,
      Function<AuthorisationToken, A> k) implements PaymentGatewayOp<A> { /* ... */ }

  record Charge<A>(Money amount, PaymentMethod method,
      Function<ChargeResult, A> k) implements PaymentGatewayOp<A> { /* ... */ }

  record Refund<A>(TransactionId txId, Money amount,
      Function<RefundResult, A> k) implements PaymentGatewayOp<A> { /* ... */ }
}

Explore Effect Handlers →

Spring Boot Integration

The hkj-spring-boot-starter lets controllers return Either, Validated, EitherPath, VTaskPath and the rest directly, and an Invalid of located field errors renders as one 422 listing every bad field by path, with no exception handler and no hand-rolled error DTO. @HkjHttpClient keeps the error channel intact when one service calls another.

@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<NonEmptyList<FieldError>, User> createUser(@RequestBody UserDto dto) {
        return userCodec.parse(dto);
        // Valid(user) → HTTP 200
        // Invalid(errors) → one HTTP 422 listing EVERY bad field by path
    }
}

@HttpExchange("/users")
@HkjHttpClient
public interface UserClientApi {

    @GetExchange("/{id}")
    EitherPath<DomainError, User> getUser(@PathVariable String id);
    // HTTP 200 → Right(user); HTTP 404 → Left(UserNotFoundError), decoded from the response
}

Get Started with Spring Boot Integration →

Testing With hkj-test

Fluent AssertJ assertions for every type in the library, the optic laws (LensLaws, PrismLaws, TraversalLaws, ValidatedPrismLaws) and the MappingLaws every generated mapping is checked against, and a SteppableClock for deterministic time. Tests read in the same vocabulary as the code under test.

import static org.higherkindedj.hkt.assertions.EitherAssert.assertThatEither;
import static org.higherkindedj.hkt.assertions.MaybeAssert.assertThatMaybe;
import static org.higherkindedj.hkt.assertions.TryAssert.assertThatTry;

assertThatEither(result).isRight().hasRight(42);
assertThatMaybe(value).isJust().hasValue("hello");
assertThatTry(computation).isFailure().hasExceptionOfType(IOException.class);

Explore hkj-test →

Foundations

Underneath it all: a simulation of higher-kinded types by defunctionalisation, so Functor, Applicative, Monad, Traverse and friends can be written once and applied across Optional, List, CompletableFuture, VTask and your own types; the core types (Either, Maybe, Try, Validated, IO, Reader, Writer, State, Free); and the monad transformers and MTL capabilities for the cases the Path API does not fit: a different outer monad, or polymorphic library code. Most applications start with Effect Paths and never need to look down here; the triage page says when you do.

Path Types at a Glance

Twenty-one Path types share one vocabulary. Most applications start with EitherPath (typed errors), MaybePath (absence), ValidationPath (every error at once) and IOPath (deferred effects), and reach for the rest as a need appears. The lazy carriers (IOPath, VTaskPath, VResultPath) additionally chain path-native resilience (withRetry / withTimeout / withCircuitBreaker / withBulkhead) that treats a business Left as a value, never as a failure to retry.

Learn by Doing

The fastest way to master Higher-Kinded-J is through our interactive tutorial series: seventeen journeys of hands-on exercises with immediate test feedback. Start with Effect API (~65 min) for the railway, Optics: Lens & Prism (~40 min) for immutable updates, or Optics: Boundary Mapping (~35 min) for the 422 leg.

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

Documentation Guide

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.