Profunctor Optics: Advanced Data Transformation

Reuse an optic on a related type, through dimap, composition, an Iso or Lens.of.

What You'll Learn

  • Adapt an optic to a new source or result type with contramap, map and dimap
  • Predict why contramap alone changes where reads come from but not what an update produces
  • Run an adapted Optic through modifyF, since it has no get or set
  • Choose composition, an Iso or Lens.of to get a typed Lens back

See Example Code

In the previous optics guides, we explored how to work with data structures directly using Lens, Prism, Iso, and Traversal. But what happens when you need to use an optic designed for one data type with a completely different data structure? What if you want to adapt an existing optic to work with new input or output formats?

This is where the profunctor nature of optics becomes invaluable. Every optic in Higher-Kinded-J is fundamentally an Optic<S, T, A, B>, and that shared interface carries the profunctor operations. Just as importantly, the everyday answers to "adapt this optic" are often the composition tools you already know; this page shows you which tool fits which job.


The Challenge: Type Mismatch in Real Systems

In real-world applications, you frequently encounter situations where:

  • Legacy Integration: You have optics designed for old data structures but need to work with new ones
  • API Adaptation: External APIs use different field names or data formats than your internal models
  • Type Safety: You want to work with strongly-typed wrapper classes but reuse optics designed for raw values
  • Data Migration: You're transitioning between data formats and need optics that work with both

Consider this scenario: you have a well-tested Lens that operates on a PersonalDetails record, but you need to use it with a StaffRecord that contains PersonalDetails as a nested field. Rather than rewriting the lens, you can adapt it.

Adapting an optic with contramap, map or dimap plays the part of Function.compose and Function.andThen around a function: a conversion runs before the optic reads, or after it writes. Unlike composed functions, the result is a plain Optic, which is why the typed routes later on this page are often the better choice.


The Three Profunctor Operations

Every optic extends Optic<S, T, A, B>, which provides three adaptation methods:

OperationSignature (simplified)Adapts
contramap(f)(C -> S) -> Optic<C, T, A, B>Where reads come from
map(g)(T -> U) -> Optic<S, U, A, B>What updates produce
dimap(f, g)(C -> S, T -> U) -> Optic<C, U, A, B>Both at once

Two things about this API matter in practice:

  1. The result is an Optic, not a Lens or Traversal. An Optic supports andThen and the effectful modifyF, but not the convenience surface (get, set, modify). The profunctor operations shine in effectful pipelines; for everyday field access you usually want one of the typed routes below.
  2. contramap alone is asymmetric. StaffRecordLenses.department().contramap(dtoToEmployee) reads from an EmployeeDto, but a modification still produces a StaffRecord (the original structure type T). To get a full bridge you must also map the output back, which is exactly what dimap does:
Optic<EmployeeDto, EmployeeDto, String, String> departmentBridge =
    StaffRecordLenses.department().dimap(Adapters::dtoToEmployee, Adapters::employeeToDto);

// An Optic is driven through modifyF. Id is the no-op effect: it runs the
// update purely, with no failure, async, or accumulation behaviour attached.
EmployeeDto promoted =
    ID.narrow(departmentBridge.modifyF(
            dept -> Id.of("Senior " + dept), dto, IdMonad.instance()))
        .value();

Why this matters

The profunctor operations are what make modifyF pipelines adaptable without rebuilding them: a validating update written against your domain model can be pointed at a wire DTO by supplying the two conversion functions, and nothing else changes. When you find yourself also wanting get and set on the adapted optic, that is the signal you have an isomorphism, and the next section gives you the full API back.


Getting a Typed Optic Back

The raw operations return Optic. In most day-to-day code you want a real Lens or Traversal back, and there are three idiomatic routes.

Route 1: Composition, when the new source contains the old

The most common "contramap" wish is really a nested-field access, and andThen already does it, keeping every convenience method:

// A StaffRecord holds PersonalDetails; compose instead of adapting
Lens<StaffRecord, String> employeeFirstName =
    StaffRecordLenses.personalInfo().andThen(PersonalDetailsLenses.firstName());

String name = employeeFirstName.get(employee);
StaffRecord shouted = employeeFirstName.modify(String::toUpperCase, employee);

Route 2: An Iso, when the two shapes hold the same information

If your conversion functions form a lossless pair, they are an Iso, and composing with one keeps the whole API in either direction (Lens.andThen(Iso) = Lens, and Iso.andThen(Lens) = Lens). This is dimap with the power retained:

// UserId is a wrapper around String: a textbook Iso
Iso<UserId, String> userIdValue = Iso.of(UserId::value, UserId::new);

// Reuse any String-side optic against the wrapper
Lens<UserAccount, UserId> accountUser = UserAccountLenses.id();
Lens<UserAccount, String> accountUserRaw = accountUser.andThen(userIdValue);

UserAccount renamed = accountUserRaw.modify(String::toUpperCase, account);

Route 3: Lens.of, when the adaptation is genuinely one-off

When neither composition nor an Iso fits (the conversion is lopsided, or you only need one field bridged), build the adapted lens directly. This is the "profunctor-style" adaptation the runnable example demonstrates:

Lens<StaffRecord, String> employeeFirstNameLens =
    Lens.of(
        employee -> PersonalDetailsLenses.firstName().get(employee.personalInfo()),
        (employee, newName) ->
            new StaffRecord(
                employee.id(),
                PersonalDetailsLenses.firstName().set(newName, employee.personalInfo()),
                employee.department()));

Decision Guide: Which Adaptation Do You Need?

flowchart LR
    accTitle: Which adaptation to use
    accDescr: When the new source contains the old one as a field, compose with andThen; when both types hold the same information in two lossless shapes, use an Iso and compose. A one-way conversion in an effectful modifyF pipeline takes the optic's contramap, map or dimap, and anything lopsided or one-off is hand-built with Lens.of.
    Q{"How do the two<br/>types relate?"}
    Q -->|"new source contains<br/>the old as a field"| C["Compose with andThen"]
    Q -->|"same information,<br/>two lossless shapes"| I@{ shape: bow-rect, label: "Iso, then compose" }
    Q -->|"one-way conversion,<br/>effectful modifyF pipeline"| D["Optic contramap / map / dimap"]
    Q -->|"anything lopsided<br/>or one-off"| L["Hand-build with Lens.of"]

    classDef decision fill:#e5c890,stroke:#df8e1d,color:#232634
    classDef tier fill:#a6d189,stroke:#40a02b,color:#232634
    classDef rw fill:#a6d189,stroke:#40a02b,color:#232634
    class Q decision
    class C,D tier
    class I,L rw

In words: when the new source holds the old one as a field, compose with andThen; when both shapes hold the same information, use an Iso. A one-way conversion in a modifyF pipeline takes contramap, map or dimap, and anything lopsided is hand-built with Lens.of.


Common Pitfalls

Don't Do This

// Rebuilding the same adapter inline repeatedly
var lens1 = StaffRecordLenses.personalInfo().andThen(PersonalDetailsLenses.firstName());
var lens2 = StaffRecordLenses.personalInfo().andThen(PersonalDetailsLenses.firstName());

// Expecting contramap alone to give a full bridge
// (reads take a DTO, but updates still produce a StaffRecord)
var readOnlyBridge = StaffRecordLenses.department().contramap(Adapters::dtoToEmployee);

// Pretending a lossy conversion is an Iso
Iso<PersonDto, PersonalDetails> lossy = Iso.of(
    dto -> new PersonalDetails(dto.fullName().split(" ")[0], "", null, List.of()),
    person -> new PersonDto(person.firstName(), "", List.of()));  // Round trip loses data!

Do This Instead

// Create adapters once, reuse everywhere
public static final Lens<StaffRecord, String> EMPLOYEE_FIRST_NAME =
    StaffRecordLenses.personalInfo().andThen(PersonalDetailsLenses.firstName());

// Use dimap when you need the bridge, and drive it through modifyF
public static final Optic<EmployeeDto, EmployeeDto, String, String> DEPARTMENT_BRIDGE =
    StaffRecordLenses.department().dimap(Adapters::dtoToEmployee, Adapters::employeeToDto);

// Reserve Iso for genuinely lossless pairs (wrappers, equivalent records)
public static final Iso<UserId, String> USER_ID_VALUE = Iso.of(UserId::value, UserId::new);

An Iso must not lose data

Iso.of(get, reverseGet) promises a lossless round trip, and the IsoLaws law harness will hold you to it. A DTO conversion that drops or invents fields is not an Iso; route it through @GenerateMapping or a Validated Prism instead.


Real-World Example: API Integration

The runnable OpticProfunctorExample walks a complete integration: an internal StaffRecord/PersonalDetails model, an external EmployeeDto/PersonDto wire format, and adapters hand-built with Lens.of (Route 3), including a formatted-date bridge that reads through a formatter and writes back through a parser, plus a conversion pair driven through modifyF. It compiles and runs on every build, so it is the reference when you wire your own.

The shape to copy:

public class ApiIntegration {

    // One pair of conversion utilities, written once and tested
    static StaffRecord dtoToEmployee(EmployeeDto dto) { /* ... */ }
    static EmployeeDto employeeToDto(StaffRecord employee) { /* ... */ }

    // Typed optics for everyday access, via composition
    public static final Lens<StaffRecord, String> FIRST_NAME =
        StaffRecordLenses.personalInfo().andThen(PersonalDetailsLenses.firstName());

    // A dimap bridge where the pipeline is effectful anyway
    public static final Optic<EmployeeDto, EmployeeDto, String, String> DEPARTMENT =
        StaffRecordLenses.department().dimap(
            ApiIntegration::dtoToEmployee,
            ApiIntegration::employeeToDto);
}

Key Takeaways

  • Every optic is an Optic<S, T, A, B>: contramap, map, and dimap live there, adapting the modifyF pipeline and returning an Optic
  • contramap alone is read-side only: updates still produce the original structure type; a full bridge needs dimap
  • Composition is the everyday "contramap": when the new source contains the old, andThen keeps the full typed API
  • A lossless pair is an Iso: compose it and keep get/set/modify; that is dimap with the power retained
  • Lens.of is the honest fallback: hand-build the adapter when the relationship is lopsided or one-off

See Also


Previous: Isomorphisms Next: Profunctor Optics: Recipes