Optic Composition Rules

The optic type andThen returns for every pair of optics, and why.

You: A lens always finds its field. So a lens followed by a prism always finds something?

andThen: Only when the prism matches. ConsignmentLenses.state() finds the state, and ConsignmentStatePrisms.returned() finds nothing when that state is Pending.

You: So the pair reaches zero or one value. Why is it not a prism?

andThen: A prism can also build the whole from its part. Hand me a Returned: can you build the consignment it belongs to?

You: No. The lens needs a consignment to put the state into.

andThen: Then the pair cannot build, and something that reaches zero or one without building is an Affine.

You: And two prisms in a row?

andThen: Each can build, so the pair can too: a Prism.

You: So I ask two things of each step: how many values it reaches, and whether it can build.

andThen: The pair reaches the wider of the two, and builds only if both build.

The Composition Rules Table works that rule out for every pair, and states it plainly beside the table.


Ranking by Capability

Optics order themselves by capability, from most specific (most operations available) to most general (fewest). An arrow points from an optic to one that can do less, and each is drawn in the chapter's optic shapes:

flowchart TD
    accTitle: Optics ranked by capability
    accDescr: Iso points to Lens and Prism. Lens points to Getter, Fold and Affine, Getter to Fold, and Prism to Affine and Traversal. Affine points to Fold and Traversal, and Traversal to Fold and Setter. Each arrow runs from an optic to one that can do less, so Iso can do the most and Fold and Setter the least.
    I@{ shape: bow-rect, label: "Iso" } --> L(["Lens"])
    I --> P@{ shape: hex, label: "Prism" }
    L --> G@{ shape: doc, label: "Getter" }
    G --> F
    L --> F@{ shape: docs, label: "Fold" }
    L --> A(["Affine"])
    P --> A
    A --> F
    A --> T@{ shape: st-rect, label: "Traversal" }
    P --> T
    T --> F
    T --> St@{ shape: lean-r, label: "Setter" }

    classDef rw fill:#a6d189,stroke:#40a02b,color:#232634
    classDef maybe fill:#a6d189,stroke:#40a02b,color:#232634,stroke-dasharray:6 4
    classDef ro fill:#8caaee,stroke:#1e66f5,color:#232634
    class I,L,P,T,St rw
    class A maybe
    class G,F ro

In words: an Iso can do the most, and Fold and Setter the least: one can only read, the other only write.

Capability, not Java subtyping

These arrows rank what each optic can do; they are not extends edges. Getter extends Fold is the only inheritance between two optic types. Some steps are explicit conversions such as asFold() or asTraversal(); others, such as Lens to Affine, are reached only by composing. Conversions lists the ones that exist, and Optic Capabilities has the per-method table.

What is Affine? An Affine optic focuses on zero or one element within a structure. It combines the partial access of a Prism with the update capability of a Lens. Common use cases include:

  • Accessing Optional<T> fields in records
  • Working with nullable properties
  • Navigating through optional intermediate structures

Key insight: composing two optics gives the most capable optic that both steps can support; the composition rules table states the rule exactly.


Composition Rules Table

Read each cell as what first.andThen(second) returns, with the row as first. The rest of this page writes that as Lens.andThen(Prism) = Affine, a lens's andThen given a prism returns an Affine, and Any stands for any of the five. A test in the examples module reads this table from the andThen overloads themselves, so it cannot promise a composition the library does not have:

first.andThen(second)IsoLensPrismAffineTraversal
IsoIsoLensPrismAffineTraversal
LensLensLensAffineAffineTraversal
PrismPrismAffinePrismAffineTraversal
AffineAffineAffineAffineAffineTraversal
TraversalTraversalTraversalTraversalTraversalTraversal

Each optic is fixed by two answers: how many values it reaches, and whether it can build the whole from its part.

ReachesCan build the wholeCannot
exactly oneIsoLens
zero or onePrismAffine
zero or moreTraversal

A composition reaches the wider of its two steps' reaches, and can build only if both steps can. So a Lens and a Prism reach zero or one value, and the lens cannot build: an Affine. Two prisms reach zero or one and both build: a Prism.

Fold, Getter and Setter compose with their own kind (fold.andThen(otherFold)), and with the others after a conversion such as asFold(); Conversions lists them.


Why Lens.andThen(Prism) = Affine

This is perhaps the most important composition rule to understand.

The Intuition

A Lens guarantees exactly one focus. A Prism provides zero-or-one focuses (it may not match).

When you compose them:

  • The Lens always gets you to A
  • The Prism may or may not get you from A to B

Result: zero-or-one focuses, which is an Affine optic.

Example

    // Domain model
    record DatabaseSettings(String host, int port) {}
    record Config(Optional<DatabaseSettings> database) {}

    // The lens always reaches the Optional<DatabaseSettings> field
    Lens<Config, Optional<DatabaseSettings>> databaseLens =
        Lens.of(Config::database, (c, db) -> new Config(db));

    // The prism may or may not find DatabaseSettings inside the Optional
    Prism<Optional<DatabaseSettings>, DatabaseSettings> somePrism = Prisms.some();

    // Composition: Lens.andThen(Prism) = Affine
    Affine<Config, DatabaseSettings> databaseAffine = databaseLens.andThen(somePrism);

    // Usage
    Config config1 = new Config(Optional.of(new DatabaseSettings("localhost", 5432)));
    Optional<DatabaseSettings> result1 = databaseAffine.getOptional(config1);
    // result1 = Optional[DatabaseSettings[host=localhost, port=5432]]

    Config config2 = new Config(Optional.empty());
    Optional<DatabaseSettings> result2 = databaseAffine.getOptional(config2);
    // result2 = Optional.empty, since the prism found nothing

    // Setting through the affine: some() can build the Optional, so the empty one is filled
    Config updated = databaseAffine.set(new DatabaseSettings("newhost", 3306), config2);
    // updated = Config[database=Optional[DatabaseSettings[host=newhost, port=3306]]]

Why Prism.andThen(Lens) = Affine

Similarly, composing a Prism first and then a Lens also yields an Affine.

The Intuition

A Prism may or may not match. If it matches, the Lens always gets you to the field.

Result: zero-or-one focuses, depending on whether the Prism matched.

Example

// Domain model with a sealed interface
sealed interface Shape permits Circle, Rectangle {}

record Circle(double radius, String colour) implements Shape {}

record Rectangle(double width, double height, String colour) implements Shape {}

A prism onto the circles, a lens onto a circle's radius, and the affine they compose to:

    // The Prism may or may not match Circle
    Prism<Shape, Circle> circlePrism =
        Prism.of(shape -> shape instanceof Circle c ? Optional.of(c) : Optional.empty(), c -> c);

    // The Lens always gets the radius from a Circle
    Lens<Circle, Double> radiusLens = Lens.of(Circle::radius, (c, r) -> new Circle(r, c.colour()));

    // Composition: Prism.andThen(Lens) = Affine
    Affine<Shape, Double> circleRadiusAffine = circlePrism.andThen(radiusLens);

    // Usage
    Shape circle = new Circle(5.0, "red");
    Optional<Double> radius = circleRadiusAffine.getOptional(circle);
    // radius = Optional[5.0]

    Shape rectangle = new Rectangle(10.0, 20.0, "blue");
    Optional<Double> empty = circleRadiusAffine.getOptional(rectangle);
    // empty = Optional.empty, since the prism did not match

    // Modification only affects circles
    Shape modified = circleRadiusAffine.modify(r -> r * 2, circle);
    // modified = Circle[radius=10.0, colour=red]

    Shape unchanged = circleRadiusAffine.modify(r -> r * 2, rectangle);
    // unchanged = Rectangle[width=10.0, height=20.0, colour=blue], as it was

Available Composition Methods

higher-kinded-j provides direct andThen methods that automatically return the correct type:

// Lens.andThen(Lens) = Lens
Lens<A, C> lensLens = lensAB.andThen(lensBC);

// Lens.andThen(Prism) = Affine
Affine<A, C> lensPrism = lensAB.andThen(prismBC);

// Prism.andThen(Prism) = Prism
Prism<A, C> prismPrism = prismAB.andThen(prismBC);

// Prism.andThen(Lens) = Affine
Affine<A, C> prismLens = prismAB.andThen(lensBC);

// Affine.andThen(Affine) = Affine
Affine<A, C> affineAffine = affineAB.andThen(affineBC);

// Affine.andThen(Lens) = Affine
Affine<A, C> affineLens = affineAB.andThen(lensBC);

// Traversal.andThen(Traversal) = Traversal
Traversal<A, C> traversalTraversal = traversalAB.andThen(traversalBC);

Via asTraversal (Universal Fallback)

Every pair of the five optics composes directly, so you rarely need this. Convert to Traversal when you want to hold optics of different kinds as one type, such as in a list of paths:

// Any optic composition via Traversal
Traversal<A, D> result =
    optic1.asTraversal()
        .andThen(optic2.asTraversal())
        .andThen(optic3.asTraversal());

It loses type information: you get a Traversal even where a more specific optic was possible. Fold and Getter do not convert to a Traversal at all.


Practical Guidelines

1. Use Direct Composition When Possible

// Preferred: direct andThen keeps the precise type, here zero or one host
Affine<Config, String> host =
    databaseLens.andThen(somePrism).andThen(hostLens);

2. Chain Multiple Compositions

// Multiple compositions
Affine<Consignment, String> returnReason =
    consignmentStateLens                 // Lens<Consignment, ConsignmentState>
        .andThen(returnedPrism)          // Prism<ConsignmentState, Returned>
        .andThen(reasonLens);            // Lens<Returned, String>

3. Store Complex Compositions as Constants

public final class OrderOptics {
    // Reusable compositions
    public static final Lens<Order, String> CUSTOMER_EMAIL =
        OrderLenses.customer()
            .andThen(CustomerLenses.email())
            .andThen(EmailAddressLenses.value());

    public static final Traversal<Order, BigDecimal> LINE_ITEM_PRICES =
        OrderTraversals.lines()
            .andThen(LineItemLenses.price());
}

Parallel Composition with Fold.plus()

The composition rules describe sequential composition (andThen): navigating deeper into a structure. Higher-Kinded-J also supports parallel composition via Fold.plus(), which combines results from multiple paths at the same level.

OperationTypePurpose
andThenSequentialNavigate deeper: A -> B -> C
plusParallelCombine results: A -> B and A -> C into A -> (B + C)
// Sequential: navigate deeper into the structure
Fold<Order, String> skus = linesFold.andThen(skuFold);

// Parallel: combine results from different paths
Fold<Person, String> allNames = firstNameFold.plus(lastNameFold);

// Both together: compose then combine
Fold<ProjectTeam, String> allEmails = Fold.sum(
    leadLens.asFold().andThen(emailLens.asFold()),
    membersFold.andThen(emailLens.asFold())
);

plus produces a Fold regardless of the input optic types, since the combined result is always read-only. Convert other optics via asFold() before combining.


Common Patterns

Pattern 1: Optional Field Access

Navigate to an optional field that may not exist, such as the second email on the cast's CustomerProfile:

@GenerateLenses
@GenerateFocus
public record CustomerProfile(
    String name, Optional<String> nickname, Optional<EmailAddress> altEmail) {}
// Lens to Optional, Prism to extract, Lens to field
Affine<CustomerProfile, String> altEmail =
    CustomerProfileLenses.altEmail()     // Lens<CustomerProfile, Optional<EmailAddress>>
        .andThen(Prisms.some())          // Prism<Optional<EmailAddress>, EmailAddress>
        .andThen(EmailAddressLenses.value()); // Lens<EmailAddress, String>

Pattern 2: Sum Type Field Access

Navigate into a specific case of a sealed interface, such as the card in the cast's Payment:

@GeneratePrisms
public sealed interface Payment permits Card, Bank {}

@GenerateFocus
public record Card(String pan) implements Payment {}

@GenerateFocus
public record Bank(String iban) implements Payment {}
// Prism to case, Lens to field
Affine<Payment, String> cardPan =
    PaymentPrisms.card()                  // Prism<Payment, Card>
        .andThen(CardFocus.pan().toLens()); // Lens<Card, String>

Pattern 3: Conditional Collection Access

Navigate into items that match a condition:

// Traversal over list, filter by predicate
Traversal<List<Order>, Order> newOrders =
    Traversals.<Order>forList()
        .andThen(Traversals.filtered(order -> order.status() == OrderStatus.NEW));

Which composition fits which data

CompositionResultUse Case
Lens.andThen(Lens)LensNested product types (records)
Lens.andThen(Prism)AffineProduct containing sum type
Prism.andThen(Lens)AffineSum type containing product
Prism.andThen(Prism)PrismNested sum types
Affine.andThen(Affine)AffineChained optional access
Affine.andThen(Lens)AffineOptional then field access
Affine.andThen(Prism)AffineOptional then variant match
Any.andThen(Traversal)TraversalCollection access
Iso.andThen(Any)Same as secondType conversion first

Why this matters

The result type of a composition is not a convenience, it is a promise. When Lens.andThen(Prism) hands you an Affine, the type is telling you the focus can be absent, and the compiler will not let you forget it; when a chain stays a Lens, totality survived every step and no absence handling is needed. That is the same discipline the mapping chapter later formalises as truthful tiers: the API only ever offers what the composition can lawfully support, so a whole class of "worked in the demo, failed in production" bugs becomes unrepresentable.

See Also

  • Affines: the zero-or-one optic most compositions land on
  • Cheat Sheet: the whole optics API on one page

Hands-On Learning

Practise lens composition in Tutorial 02: Lens Composition (7 exercises).


Previous: Conversions Next: Coming from Lombok, Streams and Switch