Profunctor Optics: Advanced Data Transformation
Reuse an optic on a related type, through dimap, composition, an Iso or Lens.of.
- Adapt an optic to a new source or result type with
contramap,mapanddimap - Predict why
contramapalone changes where reads come from but not what an update produces - Run an adapted
OpticthroughmodifyF, since it has nogetorset - Choose composition, an
IsoorLens.ofto get a typedLensback
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:
| Operation | Signature (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:
- The result is an
Optic, not aLensorTraversal. AnOpticsupportsandThenand the effectfulmodifyF, 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. contramapalone is asymmetric.StaffRecordLenses.department().contramap(dtoToEmployee)reads from anEmployeeDto, but a modification still produces aStaffRecord(the original structure typeT). To get a full bridge you must alsomapthe output back, which is exactly whatdimapdoes:
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();
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);
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);
}
- Every optic is an
Optic<S, T, A, B>:contramap,map, anddimaplive there, adapting themodifyFpipeline and returning anOptic contramapalone is read-side only: updates still produce the original structure type; a full bridge needsdimap- Composition is the everyday "contramap": when the new source contains the old,
andThenkeeps the full typed API - A lossless pair is an
Iso: compose it and keepget/set/modify; that isdimapwith the power retained Lens.ofis the honest fallback: hand-build the adapter when the relationship is lopsided or one-off
- Profunctor Optics: Recipes: wrapper-type recipes, V1/V2 migration adapters, and a complete runnable example
- Isomorphisms: the lossless conversions that keep the full optic API
- Composition Rules: what
andThenyields for every optic pairing - Production Readiness: what an adapter adds to the optic it wraps, and when to cache a composed optic
Previous: Isomorphisms Next: Profunctor Optics: Recipes