Folds: A Practical Guide
Query, search and total nested data through a reusable optic whose type says it never writes.
- Generate folds with
@GenerateFolds, and compose them with other optics into a read-only query path - Query with
getAll,preview,find,exists,allandlength, or get aMaybeback withpreviewMaybe - Aggregate the focused values with
foldMapand a monoid, such as a sum, a maximum or a string join - Combine folds over several paths with
plusandFold.sum, and predict the order of the results - Decide between a fold, a traversal, the Stream API and direct field access
In previous guides, we explored optics that allow both reading and writing: Lens for required fields, Prism for conditional variants, Affine for zero-or-one focus, Iso for lossless conversions, and Traversal for bulk operations on collections.
But what if you need to perform read-only operations? What if you want to query, search, filter, or aggregate data without any possibility of modification? This is where Fold shines.
The Scenario: Analysing E-Commerce Orders
A Fold is a read-only optic designed specifically for querying and data extraction. It plays the part of a Stream over the values it reaches, ending in reduce, anyMatch or count. Unlike a stream, it is a reusable value that composes with other optics, and its type says it never writes. Choosing an optic sets it beside the other optic types.
Consider the chapter's order service, where you need to analyse orders:
The Data Model:
@GenerateLenses
@GenerateFocus
public record LineItem(String sku, Integer quantity, BigDecimal price) {}
@GenerateLenses
@GenerateFocus
@GenerateTraversals
public record Order(
UUID id,
Customer customer,
List<LineItem> lines,
Instant placedAt,
Currency currency,
OrderStatus status) {}
// A customer's past orders, beside the chapter's Order
@GenerateFolds
record OrderHistory(List<Order> orders) {}
Common Query Needs:
- "Find all lines in this order"
- "Get the first line or empty if none"
- "Check if any line is for more than one unit"
- "Count how many lines are in the order"
- "Calculate the order's total"
- "Check if all lines are under £100"
A Fold makes these queries type-safe, composable, and expressive.
Fold vs Traversal: Understanding the Difference
Before we dive deeper, it's crucial to understand how Fold relates to Traversal:
| Aspect | Traversal | Fold |
|---|---|---|
| Purpose | Read and modify collections | Read-only queries |
| Can modify? | Yes (via Traversals.modify) | No |
| Query operations | Yes (via getAll, but not primary purpose) | Yes (designed for this) |
| Intent clarity | "I might modify this" | "I'm only reading this" |
| Conversion | Can be converted to Fold via asFold() | Cannot be converted to Traversal |
| Use cases | Bulk updates, validation with modifications | Queries, searches, aggregations |
Key Insight: Every Traversal can be viewed as a Fold (read-only subset), but not every Fold can be a Traversal. By choosing Fold when you only need reading, you make your code's intent clear and prevent accidental modifications.
A Step-by-Step Walkthrough
Step 1: Generating Folds
Just like with other optics, we use annotations to trigger automatic code generation. Annotating a record with @GenerateFolds creates a companion class (e.g., OrderHistoryFolds) containing a Fold for each field.
import org.higherkindedj.optics.annotations.GenerateFolds;
import java.util.List;
@GenerateFolds
public record OrderHistory(List<Order> orders) {}
This generates:
OrderHistoryFolds.orders()→Fold<OrderHistory, Order>(focuses on every order)
The chapter's Order carries no @GenerateFolds, so the next steps build its fold with Fold.of, from a function that lists the targets: Fold.of(Order::lines) focuses on every line. OrderTraversals.lines().asFold() reaches the same lines through the traversal the cast generates.
As with every generator in this chapter, a targetPackage attribute relocates the generated class; see Customising the Generated Package.
Step 2: The Core Fold Operations
A Fold<S, A> provides these essential query operations:
getAll(source): Extract All Focused Values
Returns a List<A> containing all the values the Fold focuses on.
Order order =
new Order(
UUID.fromString("00000000-0000-0000-0000-000000000123"),
new Customer("Ada", new EmailAddress("ada@example.com")),
List.of(
new LineItem("LAPTOP", 1, new BigDecimal("999.99")),
new LineItem("MOUSE", 2, new BigDecimal("12.50")),
new LineItem("DESK", 1, new BigDecimal("350.00"))),
Instant.parse("2026-10-01T09:00:00Z"),
Currency.getInstance("GBP"),
OrderStatus.NEW);
Fold<Order, LineItem> linesFold = Fold.of(Order::lines);
List<LineItem> allLines = linesFold.getAll(order);
// [LineItem[sku=LAPTOP, ...], LineItem[sku=MOUSE, ...], LineItem[sku=DESK, ...]]
preview(source): Get the First Value
Returns an Optional<A> containing the first focused value, or Optional.empty() if none exist.
Optional<LineItem> firstLine = linesFold.preview(order);
// Optional[LineItem[sku=LAPTOP, quantity=1, price=999.99]]
Order emptyOrder = OrderLenses.withLines(order, List.of());
Optional<LineItem> noLine = linesFold.preview(emptyOrder);
// Optional.empty
find(predicate, source): Find First Matching Value
Returns an Optional<A> containing the first value that matches the predicate.
Optional<LineItem> expensiveLine =
linesFold.find(line -> line.price().compareTo(new BigDecimal("500")) > 0, order);
// Optional[LineItem[sku=LAPTOP, quantity=1, price=999.99]]
exists(predicate, source): Check If Any Match
Returns true if at least one focused value matches the predicate.
boolean hasMultiUnitLine = linesFold.exists(line -> line.quantity() > 1, order);
// true: the mouse line is for two
all(predicate, source): Check If All Match
Returns true if all focused values match the predicate (returns true for empty collections).
boolean allSingleUnits = linesFold.all(line -> line.quantity() == 1, order);
// false: the mouse line is for two
isEmpty(source): Check for Empty
Returns true if there are zero focused values.
boolean hasLines = !linesFold.isEmpty(order);
// true
length(source): Count Values
Returns the number of focused values as an int.
int lineCount = linesFold.length(order);
// 3
Of the operations above, only preview and find speak Optional; the rest hand back a List, a boolean, or an int. If your codebase prefers the library's Maybe type, the Maybe-based extensions later on this page mirror preview, find, and getAll.
Step 3: Composing Folds for Deep Queries
Folds can be composed with other optics to create deep query paths. When composing with Lens, Prism, or other Fold instances, use andThen().
// Get every SKU from every order in a history
Fold<OrderHistory, Order> historyToOrders = OrderHistoryFolds.orders();
Fold<Order, LineItem> orderToLines = Fold.of(Order::lines);
Lens<LineItem, String> lineToSku = LineItemLenses.sku();
Fold<OrderHistory, String> historyToAllSkus =
historyToOrders.andThen(orderToLines).andThen(lineToSku.asFold());
Order secondOrder =
OrderLenses.withId(
OrderLenses.withLines(
order,
List.of(
new LineItem("KEYBOARD", 1, new BigDecimal("75.00")),
new LineItem("MONITOR", 1, new BigDecimal("450.00")))),
UUID.fromString("00000000-0000-0000-0000-000000000124"));
OrderHistory history = new OrderHistory(List.of(order, secondOrder));
List<String> allSkus = historyToAllSkus.getAll(history);
// [LAPTOP, MOUSE, DESK, KEYBOARD, MONITOR]
Step 4: Aggregation with foldMap and Monoids
The most powerful feature of Fold is its ability to aggregate data using monoids. This is where Fold truly shines for combining values in flexible, reusable ways.
foldMap is one method that replaces a family of hand-written loops: sum, count, any-match, all-match, and string joining are all the same fold with a different Monoid. Because monoids compose, so do the queries; and because a Fold cannot write, the compiler guarantees your reporting layer never mutates the domain it reports on.
Understanding Monoids: The Simple Explanation
A monoid is the pair you pass to Stream.reduce(identity, accumulator), held as one value. It has two parts:
- A starting value (called
empty): theidentity, such as 0 when adding numbers, or "" when joining strings - A combining rule (called
combine): theaccumulator, such as "add these two numbers" or "concatenate these two strings"
Simple Examples:
- Adding numbers: Start with 0, combine by adding →
0 + 5 + 10 + 3 = 18 - Joining strings: Start with "", combine by concatenating →
"" + "Hello" + " " + "World" = "Hello World" - Finding maximum: Start with negative infinity, combine by taking larger value
- Checking all conditions: Start with
true, combine with AND (&&) → all must be true
The Power of foldMap
The foldMap method lets you:
- Transform each focused value into a "combinable" type
- Automatically merge all those values using a monoid
Example: Calculate Total Price
Fold<Order, LineItem> lines = Fold.of(Order::lines);
// Define how to combine amounts (addition)
Monoid<BigDecimal> sumMonoid =
new Monoid<>() {
@Override
public BigDecimal empty() {
return BigDecimal.ZERO; // Start with zero
}
@Override
public BigDecimal combine(BigDecimal a, BigDecimal b) {
return a.add(b); // Add them
}
};
// A line's total is its price times its quantity
Function<LineItem, BigDecimal> lineTotal =
line -> line.price().multiply(BigDecimal.valueOf(line.quantity()));
// Work out each line's total and sum them all
BigDecimal orderTotal = lines.foldMap(sumMonoid, lineTotal, order);
// 1374.99, which is 999.99 + 25.00 + 350.00
What's happening here?
- For each
LineItemin the order, work out its total, price times quantity →[999.99, 25.00, 350.00] - Start with
BigDecimal.ZERO(the empty value) - Combine them:
0 + 999.99 + 25.00 + 350.00 = 1374.99
Monoids has ready-made sums for Integer, Long and Double, and none for BigDecimal, so a sum of money is a monoid you write once, as here.
Common Monoid Patterns
Here are the most useful monoid patterns for everyday use. Best Practice: Use the standard implementations from the Monoids utility class whenever possible:
import org.higherkindedj.hkt.Monoids;
// Standard monoids available out of the box:
Monoid<Double> sumDouble = Monoids.doubleAddition();
Monoid<Double> productDouble = Monoids.doubleMultiplication();
Monoid<Integer> sumInt = Monoids.integerAddition();
Monoid<Integer> productInt = Monoids.integerMultiplication();
Monoid<Long> sumLong = Monoids.longAddition();
Monoid<Boolean> andMonoid = Monoids.booleanAnd();
Monoid<Boolean> orMonoid = Monoids.booleanOr();
Monoid<String> stringConcat = Monoids.string();
Monoid<List<String>> listConcat = Monoids.list();
Monoid<Set<String>> setUnion = Monoids.set();
Monoid<Optional<String>> firstWins = Monoids.firstOptional();
Monoid<Optional<String>> lastWins = Monoids.lastOptional();
Monoid<Optional<BigDecimal>> maxValue = Monoids.maximum();
Monoid<Optional<BigDecimal>> minValue = Monoids.minimum();
The collection and Optional monoids work for any element type; String and BigDecimal stand in for yours. maximum() and minimum() need a Comparable element, and take a Comparator otherwise.
Sum (Adding Numbers)
// Monoids has no BigDecimal sum, so money reuses sumMonoid and lineTotal from Calculate Total Price
BigDecimal revenue = linesFold.foldMap(sumMonoid, lineTotal, order);
Product (Multiplying Numbers)
Monoid<Double> productMonoid = Monoids.doubleMultiplication();
// Calculate compound discount (e.g., 0.9 * 0.95 * 0.85)
double finalMultiplier = discountsFold.foldMap(productMonoid, d -> d, discounts);
String Concatenation
Monoid<String> stringMonoid = Monoids.string();
// Join all SKUs
String allSkus = linesFold.foldMap(stringMonoid, LineItem::sku, order);
List Accumulation
Monoid<List<String>> listMonoid = Monoids.list();
// Collect all SKUs (with duplicates)
List<String> skus = linesFold.foldMap(listMonoid,
line -> List.of(line.sku()), order);
Boolean AND (All Must Be True)
Monoid<Boolean> andMonoid = Monoids.booleanAnd();
// Check if every line is for a single unit
boolean allSingleUnits = linesFold.foldMap(andMonoid, line -> line.quantity() == 1, order);
Boolean OR (Any Can Be True)
Monoid<Boolean> orMonoid = Monoids.booleanOr();
// Check if any line is expensive
boolean hasExpensive = linesFold.foldMap(orMonoid,
line -> line.price().compareTo(new BigDecimal("1000")) > 0, order);
Maximum Value
// Use Optional-based maximum from Monoids
Monoid<Optional<BigDecimal>> maxMonoid = Monoids.maximum();
// Find highest price (returns Optional to handle empty collections)
Optional<BigDecimal> maxPrice = linesFold.foldMap(maxMonoid,
line -> Optional.of(line.price()), order);
// Or, since a price is never negative, a custom one that starts from zero:
Monoid<BigDecimal> rawMaxMonoid = new Monoid<>() {
@Override public BigDecimal empty() { return BigDecimal.ZERO; }
@Override public BigDecimal combine(BigDecimal a, BigDecimal b) { return a.max(b); }
};
BigDecimal maxPriceRaw = linesFold.foldMap(rawMaxMonoid, LineItem::price, order);
Why Monoids Matter
Monoids give you:
- Composability: Combine complex aggregations from simple building blocks
- Reusability: Define a monoid once, use it everywhere
- Correctness: The monoid laws guarantee consistent behaviour
- Flexibility: Create custom aggregations for your domain
Pro Tip: You can create custom monoids for any domain-specific aggregation logic, like calculating weighted averages, combining validation results, or merging configuration objects.
Maybe-Based Fold Extensions
Higher-Kinded-J provides extension methods that integrate Fold with Maybe, its functional optional type, offering a more functional approach to handling absent values compared to Java's Optional. These extensions are available via static imports from FoldExtensions.
The Challenge: Working with Nullable Values
Standard Fold operations use Optional<A> for operations that might not find a value (like preview and find). While Optional works well, functional programming often prefers Maybe because it:
- Integrates seamlessly with Higher-Kinded Types (HKT)
- Works consistently with other monadic operations (
flatMap,map,fold) - Provides better composition with validation and error handling types
- Offers a more principled functional API
The Three Extension Methods
All three methods are static imports from org.higherkindedj.optics.extensions.FoldExtensions:
import static org.higherkindedj.optics.extensions.FoldExtensions.*;
1. previewMaybe(fold, source) - Get First Value as Maybe
The previewMaybe method is the Maybe-based equivalent of preview(). It returns the first focused value wrapped in Maybe, or Maybe.nothing() if none exist.
Fold<Order, LineItem> linesFold = Fold.of(Order::lines);
Maybe<LineItem> firstLine = previewMaybe(linesFold, order);
// Just(LineItem[sku=LAPTOP, quantity=1, price=999.99])
Order emptyOrder = OrderLenses.withLines(order, List.of());
Maybe<LineItem> noLine = previewMaybe(linesFold, emptyOrder);
// Nothing
When to use previewMaybe vs preview:
- Use
previewMaybewhen working in a functional pipeline with otherMaybevalues - Use
previewwhen interoperating with standard Java code expectingOptional - Use
previewMaybewhen you need HKT compatibility for generic functional abstractions
2. findMaybe(fold, predicate, source) - Find First Match as Maybe
The findMaybe method is the Maybe-based equivalent of find(). It returns the first focused value matching the predicate, or Maybe.nothing() if no match is found.
Fold<Order, LineItem> linesFold = Fold.of(Order::lines);
Maybe<LineItem> expensiveLine =
findMaybe(linesFold, line -> line.price().compareTo(new BigDecimal("500")) > 0, order);
// Just(LineItem[sku=LAPTOP, quantity=1, price=999.99])
Maybe<LineItem> luxuryLine =
findMaybe(linesFold, line -> line.price().compareTo(new BigDecimal("5000")) > 0, order);
// Nothing
Common Use Cases:
- Product search: Find first available item matching criteria
- Validation: Locate the first invalid field in a form
- Configuration: Find the first matching configuration option
- Inventory: Locate first in-stock item in a category
3. getAllMaybe(fold, source) - Get All Values as Maybe-Wrapped List
The getAllMaybe method returns all focused values as Maybe<List<A>>. If the Fold finds at least one value, you get Just(List<A>). If it finds nothing, you get Nothing.
This is particularly useful when you want to distinguish between "found an empty collection" and "found no results".
Fold<Order, LineItem> linesFold = Fold.of(Order::lines);
Maybe<List<LineItem>> allLines = getAllMaybe(linesFold, order);
// Just([LineItem[sku=LAPTOP, ...], LineItem[sku=MOUSE, ...], LineItem[sku=DESK, ...]])
Order emptyOrder = OrderLenses.withLines(order, List.of());
Maybe<List<LineItem>> noLines = getAllMaybe(linesFold, emptyOrder);
// Nothing
When to use getAllMaybe vs getAll:
| Scenario | Use getAll() | Use getAllMaybe() |
|---|---|---|
| You need the list regardless of emptiness | Returns List<A> (possibly empty) | Overkill |
| You want to treat empty results as a failure case | Must check isEmpty() manually | Returns Nothing for empty results |
| You're chaining functional operations with Maybe | Requires conversion | Directly composable |
| Performance-critical batch processing | Direct list access | Extra Maybe wrapping |
Real-World Scenario: Product Search with Maybe
Here's a practical example showing how Maybe-based extensions simplify null-safe querying:
import org.higherkindedj.optics.Fold;
import org.higherkindedj.optics.annotations.GenerateFolds;
import org.higherkindedj.hkt.maybe.Maybe;
import static org.higherkindedj.optics.extensions.FoldExtensions.*;
// A catalogue entry, keyed by the sku a line item carries
public record Product(String sku, String name, BigDecimal price, int stock) {}
// The catalogue's products; a separate map files each sku under a category
@GenerateFolds
public record ProductCatalogue(List<Product> products) {}
public class ProductSearchService {
private static final Fold<ProductCatalogue, Product> ALL_PRODUCTS =
ProductCatalogueFolds.products();
// Find the cheapest in-stock product in a category
public Maybe<Product> findCheapestInCategory(
ProductCatalogue catalogue,
Map<String, String> categoryBySku,
String category
) {
return getAllMaybe(ALL_PRODUCTS, catalogue)
.map(products -> products.stream()
.filter(p -> category.equals(categoryBySku.get(p.sku())))
.filter(p -> p.stock() > 0)
.min(Comparator.comparing(Product::price))
.orElse(null)
)
.flatMap(Maybe::fromNullable); // Convert null to Nothing
}
// Get first premium product (>£1000)
public Maybe<Product> findPremiumProduct(ProductCatalogue catalogue) {
return findMaybe(
ALL_PRODUCTS,
product -> product.price().compareTo(new BigDecimal("1000")) > 0,
catalogue
);
}
// Check if any products are available
public boolean hasAvailableProducts(ProductCatalogue catalogue) {
return getAllMaybe(ALL_PRODUCTS, catalogue)
.map(products -> products.stream().anyMatch(p -> p.stock() > 0))
.orElse(false);
}
// Extract all product names (or empty message)
public String getProductSummary(ProductCatalogue catalogue) {
return getAllMaybe(ALL_PRODUCTS, catalogue)
.map(products -> products.stream()
.map(Product::name)
.collect(Collectors.joining(", "))
)
.orElse("No products available");
}
}
Optional vs Maybe: A Comparison
Understanding when to use each type helps you make informed decisions:
| Aspect | Optional<A> | Maybe<A> |
|---|---|---|
| Purpose | Standard Java optional values | Functional optional values with HKT support |
| Package | java.util.Optional | org.higherkindedj.hkt.maybe.Maybe |
| HKT Support | No | Yes (integrates with Kind<F, A>) |
| Monadic Operations | map, flatMap, filter | map, flatMap, orElse, orElseGet, toEither, plus the full type class instances |
| Java Interop | Native support | Requires conversion |
| Functional Composition | Basic | Excellent (works with Applicative, Monad, etc.) |
| Pattern Matching | ifPresent(), orElse() | isJust(), isNothing() |
| Use Cases | Standard Java APIs, interop | Functional pipelines, HKT abstractions |
| Conversion | Maybe.fromOptional(opt) | maybe.toOptional() |
Best Practice: Use Optional at API boundaries (public methods, external libraries) and Maybe internally in functional pipelines.
When to Use Each Extension Method
Here's a decision matrix to help you choose the right method:
Use previewMaybe when:
- You need the first value from a Fold
- You're working in a functional pipeline with other
Maybevalues - You want to chain operations (
map,flatMap,fold) on the result - You need HKT compatibility
// Example: Get the first line, if expensive, and calculate a discount
Maybe<BigDecimal> discountedPrice = previewMaybe(linesFold, order)
.flatMap(line -> line.price().compareTo(new BigDecimal("100")) > 0
? Maybe.just(line.price().multiply(new BigDecimal("0.9")).setScale(2, RoundingMode.HALF_EVEN))
: Maybe.nothing());
Use findMaybe when:
- You need to locate a specific value matching a predicate
- You want to avoid the verbosity of
getAll().stream().filter().findFirst() - You're building search functionality
- You want the first match delivered as a
Mayberather than anOptional
// Example: Find the first line for more than one unit
Maybe<LineItem> multiUnit = findMaybe(
linesFold,
line -> line.quantity() > 1,
order
);
Use getAllMaybe when:
- You want to treat empty results as a "nothing" case
- You want to chain functional operations on the entire result set
- You're building batch processing pipelines
- You need to propagate "nothing found" through your computation
// Example: Process all lines or provide default behaviour
String report = getAllMaybe(linesFold, order)
.map(lines -> generateReport(lines))
.orElse("No lines to report");
Integration with Existing Fold Operations
Maybe-based extensions work seamlessly alongside standard Fold operations. You can mix and match based on your needs:
Fold<Order, LineItem> linesFold = Fold.of(Order::lines);
// Standard Fold operations
List<LineItem> allLines = linesFold.getAll(order); // Always returns list
Optional<LineItem> firstOpt = linesFold.preview(order); // Optional-based
int count = linesFold.length(order); // Primitive int
// Maybe-based extensions
Maybe<LineItem> firstMaybe = previewMaybe(linesFold, order); // Maybe-based
Maybe<LineItem> matchMaybe =
findMaybe(linesFold, line -> line.price().compareTo(new BigDecimal("500")) > 0, order); // Maybe-based
Maybe<List<LineItem>> allMaybe = getAllMaybe(linesFold, order); // Maybe-wrapped list
Conversion Between Optional and Maybe:
// Convert Optional to Maybe
Optional<LineItem> firstOptional = linesFold.preview(order);
Maybe<LineItem> liftedToMaybe = Maybe.fromOptional(firstOptional);
// Convert Maybe to Optional
Maybe<LineItem> firstMaybe = previewMaybe(linesFold, order);
Optional<LineItem> loweredToOptional = firstMaybe.toOptional();
Practical Example: Safe Navigation with Maybe
Combining getAllMaybe with composed folds creates powerful null-safe query pipelines:
import org.higherkindedj.optics.Fold;
import org.higherkindedj.hkt.maybe.Maybe;
import static org.higherkindedj.optics.extensions.FoldExtensions.*;
// A customer's past orders, beside the chapter's Order
@GenerateFolds
public record OrderHistory(List<Order> orders) {}
public class OrderAnalytics {
private static final Fold<OrderHistory, Order> ORDERS =
OrderHistoryFolds.orders();
private static final Fold<Order, LineItem> LINES =
Fold.of(Order::lines);
// A line's total: its price times its quantity
private static BigDecimal lineTotal(LineItem line) {
return line.price().multiply(BigDecimal.valueOf(line.quantity()));
}
// Calculate total revenue, handling empty history gracefully
public BigDecimal calculateRevenue(OrderHistory history) {
return getAllMaybe(ORDERS, history)
.flatMap(orders -> {
List<BigDecimal> totals = orders.stream()
.flatMap(order -> getAllMaybe(LINES, order)
.map(lines -> lines.stream().map(OrderAnalytics::lineTotal))
.orElse(Stream.empty()))
.toList();
return totals.isEmpty() ? Maybe.nothing() : Maybe.just(totals);
})
.map(totals -> totals.stream().reduce(BigDecimal.ZERO, BigDecimal::add))
.orElse(BigDecimal.ZERO);
}
// Find the most expensive line across all orders
public Maybe<LineItem> findMostExpensive(OrderHistory history) {
return getAllMaybe(ORDERS, history)
.flatMap(orders -> {
List<LineItem> allLines = orders.stream()
.flatMap(order -> getAllMaybe(LINES, order)
.map(List::stream)
.orElse(Stream.empty()))
.toList();
return allLines.isEmpty()
? Maybe.nothing()
: Maybe.fromNullable(allLines.stream()
.max(Comparator.comparing(LineItem::price))
.orElse(null));
});
}
}
See FoldExtensionsExample.java for a runnable demonstration of all Maybe-based Fold extensions.
Combining Folds
The Problem: Extracting Values from Multiple Paths
Consider a data structure with values scattered across different fields or branches. Without fold combination, you would need to call getAll on each fold separately and concatenate the results manually:
record ProjectTeam(String name, TeamMember lead, List<TeamMember> members) {}
record TeamMember(String name, String email) {}
// Fold.of builds a fold from a function that lists the targets;
// asFold() turns a lens into a single-target fold
Lens<ProjectTeam, TeamMember> teamLeadLens =
Lens.of(ProjectTeam::lead, (t, l) -> new ProjectTeam(t.name(), l, t.members()));
Lens<TeamMember, String> memberEmailLens =
Lens.of(TeamMember::email, (m, email) -> new TeamMember(m.name(), email));
// Separate folds for different paths
Fold<ProjectTeam, String> leadEmail = teamLeadLens.asFold()
.andThen(memberEmailLens.asFold());
Fold<ProjectTeam, String> memberEmails = Fold.<ProjectTeam, TeamMember>of(ProjectTeam::members)
.andThen(memberEmailLens.asFold());
// Manual combination - verbose and error-prone
List<String> allEmails = new ArrayList<>();
allEmails.addAll(leadEmail.getAll(team));
allEmails.addAll(memberEmails.getAll(team));
The Solution: Fold.plus()
Fold.plus() combines two folds into one that returns results from both:
// Clean, composable combination
Fold<ProjectTeam, String> allEmails = leadEmail.plus(memberEmails);
// Use like any other fold
List<String> emails = allEmails.getAll(team);
boolean hasGmail = allEmails.exists(e -> e.endsWith("@gmail.com"), team);
int emailCount = allEmails.length(team);
The Monoid Structure
Folds under plus form a monoid, meaning they satisfy three laws:
| Law | Meaning |
|---|---|
| Left identity | Fold.empty().plus(f) behaves like f |
| Right identity | f.plus(Fold.empty()) behaves like f |
| Associativity | (a.plus(b)).plus(c) behaves like a.plus(b.plus(c)) |
Fold.empty() is the identity element, a fold that focuses on nothing:
Fold<ProjectTeam, String> nothing = Fold.empty();
List<String> none = nothing.getAll(team);
// []
int count = nothing.length(team);
// 0
boolean empty = nothing.isEmpty(team);
// true
For combining three or more folds, use Fold.sum():
Fold<ProjectTeam, String> allText = Fold.sum(
teamNameFold,
leadNameFold,
memberNamesFold
);
// Equivalent to: teamNameFold.plus(leadNameFold).plus(memberNamesFold)
Combining Different Optic Types
Any optic can participate in fold combination via its asFold() method:
// Lens-derived fold (exactly one element)
Fold<ConnectionConfig, String> hostFold = hostLens.asFold();
// Prism-derived fold (zero or one element)
Fold<ConnectionConfig, String> optionalPortFold = portPrism.asFold();
// Affine-derived fold (zero or one element)
Fold<ConnectionConfig, String> optionalDbFold = dbAffine.asFold();
// Combine them all
Fold<ConnectionConfig, String> allConfigStrings = Fold.sum(
hostFold, optionalPortFold, optionalDbFold
);
Ordering Guarantees
Elements from the first fold always appear before elements from the second:
Fold<TeamMember, String> nameFirst = nameLens.asFold().plus(emailLens.asFold());
List<String> nameThenEmail = nameFirst.getAll(member);
// [Alice, alice@example.com]
Fold<TeamMember, String> emailFirst = emailLens.asFold().plus(nameLens.asFold());
List<String> emailThenName = emailFirst.getAll(member);
// [alice@example.com, Alice]
Each fold in a plus combination makes its own pass over the source, which FoldPlusBenchmark in hkj-benchmarks measures. To combine many folds over a very large collection in one pass, write a single foldMap instead.
When to Use Folds vs Other Approaches
Use Fold When
- Read-only queries: You only need to extract or check data
- Intent matters: You want to express "this is a query, not a modification"
- Composable searches: Building reusable query paths
- Aggregations: Using monoids for custom combining logic
- CQRS patterns: Separating queries from commands
// Perfect for read-only analysis
Fold<OrderHistory, LineItem> allLines =
OrderHistoryFolds.orders()
.andThen(Fold.of(Order::lines));
boolean hasLaptop = allLines.exists(
line -> "LAPTOP".equals(line.sku()),
history
);
Use Traversal When
- Modifications needed: You need to update the data
- Effectful updates: Using
modifyFfor validation or async operations - Bulk transformations: Changing multiple values at once
// Use Traversal for modifications
Traversal<Order, LineItem> lineTraversal = OrderTraversals.lines();
Order discountedOrder = Traversals.modify(
lineTraversal.andThen(LineItemLenses.price()),
price -> price.multiply(new BigDecimal("0.9")).setScale(2, RoundingMode.HALF_EVEN),
order
);
Use Stream API When
- Complex filtering: Multiple filter/map/reduce operations
- Parallel processing: Taking advantage of parallel streams
- Standard Java collections: Working with flat collections
- Stateful operations: Operations that require maintaining state
// Better with streams for complex pipelines
List<String> topExpensiveSkus = order.lines().stream()
.filter(line -> line.price().compareTo(new BigDecimal("100")) > 0)
.sorted(Comparator.comparing(LineItem::price).reversed())
.limit(5)
.map(LineItem::sku)
.toList();
Use Direct Field Access When
- Simple cases: Single, straightforward field read
- A hot loop you have measured: Production Readiness says what each call allocates
- One-off operations: Not building reusable logic
// Just use direct access for simple cases
String customerName = order.customer().name();
Common Pitfalls
Don't Do This
// Inefficient: Creating folds repeatedly in loops
for (Order order : orders) {
Fold<Order, LineItem> fold = Fold.of(Order::lines);
List<LineItem> lines = fold.getAll(order);
// ... process lines
}
// Over-engineering: Using Fold for trivial single-field access
Fold<Order, Customer> customerFold = OrderLenses.customer().asFold();
String name = customerFold.getAll(order).get(0).name(); // Just use order.customer().name()!
// Wrong tool: Trying to modify data with a Fold
// Folds are read-only - this won't compile
// Fold<Order, LineItem> lines = Fold.of(Order::lines);
// Order updated = lines.set(newLine, order); // ❌ No 'set' method!
// Verbose: Unnecessary conversion when you only need getAll
Traversal<Order, LineItem> traversal = OrderTraversals.lines();
Fold<Order, LineItem> fold = traversal.asFold();
List<LineItem> lines = fold.getAll(order); // Just use Traversals.getAll() directly!
Do This Instead
// Efficient: Create fold once, reuse many times
Fold<Order, LineItem> linesFold = Fold.of(Order::lines);
for (Order order : orders) {
List<LineItem> lines = linesFold.getAll(order);
// ... process lines
}
// Right tool: Direct access for simple cases
String name = order.customer().name();
// Clear intent: Use Traversal when you need modifications
Traversal<Order, LineItem> linesTraversal = OrderTraversals.lines();
Order updated = Traversals.modify(
linesTraversal,
line -> new LineItem(
line.sku(),
line.quantity(),
line.price().multiply(new BigDecimal("0.9")).setScale(2, RoundingMode.HALF_EVEN)),
order);
// Clear purpose: Use Fold when expressing query intent
Fold<Order, LineItem> queryLines = Fold.of(Order::lines);
boolean hasExpensive =
queryLines.exists(line -> line.price().compareTo(new BigDecimal("1000")) > 0, order);
// Right time for asFold(): when you need foldMap, exists, all, plus, or length
Fold<Order, Integer> quantitiesFold = OrderTraversals.lines()
.andThen(LineItemLenses.quantity())
.asFold();
int units = quantitiesFold.foldMap(Monoids.integerAddition(), quantity -> quantity, order);
Real-World Example: Order Analytics
Here's a practical example showing comprehensive use of Fold for business analytics:
import org.higherkindedj.optics.Fold;
import org.higherkindedj.optics.annotations.GenerateFolds;
import org.higherkindedj.hkt.Monoid;
import java.math.BigDecimal;
import java.math.RoundingMode;
import java.util.*;
// A customer's past orders, beside the chapter's Order
@GenerateFolds
public record OrderHistory(List<Order> orders) {}
public class OrderAnalytics {
private static final Fold<Order, LineItem> ORDER_LINES = Fold.of(Order::lines);
private static final Fold<OrderHistory, Order> HISTORY_ORDERS = OrderHistoryFolds.orders();
private static final Fold<OrderHistory, LineItem> ALL_LINES =
HISTORY_ORDERS.andThen(ORDER_LINES);
private static final Monoid<BigDecimal> SUM_MONOID = new Monoid<>() {
@Override public BigDecimal empty() { return BigDecimal.ZERO; }
@Override public BigDecimal combine(BigDecimal a, BigDecimal b) { return a.add(b); }
};
// A line's total: its price times its quantity
private static BigDecimal lineTotal(LineItem line) {
return line.price().multiply(BigDecimal.valueOf(line.quantity()));
}
// Calculate total revenue across all orders
public static BigDecimal calculateRevenue(OrderHistory history) {
return ALL_LINES.foldMap(SUM_MONOID, OrderAnalytics::lineTotal, history);
}
// Find the most expensive line across all orders
public static Optional<LineItem> findMostExpensiveLine(OrderHistory history) {
return ALL_LINES.getAll(history).stream()
.max(Comparator.comparing(LineItem::price));
}
// Check if any order has a bulk line
public static boolean hasBulkLines(OrderHistory history) {
return ALL_LINES.exists(line -> line.quantity() >= 10, history);
}
// Get all unique SKUs
public static Set<String> getAllSkus(OrderHistory history) {
Fold<OrderHistory, String> skus =
ALL_LINES.andThen(LineItemLenses.sku().asFold());
return new HashSet<>(skus.getAll(history));
}
// Count the units ordered of one SKU
public static int countUnits(OrderHistory history, String sku) {
return ALL_LINES.getAll(history).stream()
.filter(line -> sku.equals(line.sku()))
.mapToInt(LineItem::quantity)
.sum();
}
// Calculate average order value, to the penny
public static BigDecimal calculateAverageOrderValue(OrderHistory history) {
List<Order> allOrders = HISTORY_ORDERS.getAll(history);
if (allOrders.isEmpty()) return BigDecimal.ZERO;
BigDecimal totalRevenue = calculateRevenue(history);
return totalRevenue.divide(BigDecimal.valueOf(allOrders.size()), 2, RoundingMode.HALF_EVEN);
}
// Find orders containing a specific SKU
public static List<Order> findOrdersContaining(OrderHistory history, String sku) {
return HISTORY_ORDERS.getAll(history).stream()
.filter(order -> ORDER_LINES.exists(
line -> sku.equals(line.sku()),
order
))
.toList();
}
}
The Relationship to Foldable
Quick Summary
If you're just getting started, here's what you need to know: A Fold<S, A> is closely related to the Foldable type class from functional programming. While Foldable<F> works with any container type F (like List, Optional, Maybe), a Fold<S, A> lets you treat any structure S as if it were a foldable container of A values: even when S isn't actually a collection.
Key Connection: Both use foldMap to aggregate values using monoids. The Fold optic brings this powerful abstraction to arbitrary data structures, not just collections.
In-Depth Explanation
For those familiar with functional programming or interested in the deeper theory:
The Foldable Type Class
The Foldable<F> type class in Higher-Kinded-J represents any data structure F that can be "folded up" or reduced to a summary value. It's defined with this signature:
public interface Foldable<F extends WitnessArity<TypeArity.Unary>> {
<A, M> M foldMap(
Monoid<M> monoid,
Function<? super A, ? extends M> f,
Kind<F, A> fa
);
}
Common instances include:
List<A>- fold over all elementsOptional<A>- fold over zero or one elementEither<E, A>- fold over the right value if presentMaybe<A>- fold over the value if it is aJust
How Fold Relates to Foldable
A Fold<S, A> can be thought of as a first-class, composable lens into a Foldable structure. More precisely:
- Virtualisation:
Fold<S, A>lets you "view" any structureSas a virtualFoldablecontainer ofAvalues, even ifSis not inherently a collection - Composition: Unlike
Foldable<F>, which is fixed to a specific container typeF,Fold<S, A>can be composed with other optics to create deep query paths - Reification: A
Foldreifies (makes concrete) the act of folding, turning it into a first-class value you can pass around, store, and combine
Example Comparison:
// Using Foldable directly on a List
Foldable<ListKind.Witness> listFoldable = ListTraverse.INSTANCE;
List<Integer> numbers = List.of(1, 2, 3, 4, 5);
int sum = listFoldable.foldMap(
Monoids.integerAddition(), Function.identity(), LIST.widen(numbers));
// Using a Fold optic to query nested structure
Fold<Order, Integer> quantities = Fold.of(Order::lines)
.andThen(LineItemLenses.quantity().asFold());
int units = quantities.foldMap(
Monoids.integerAddition(), Function.identity(), order);
The Fold optic gives you the power of Foldable, but for arbitrary access paths through your domain model, not just direct containers.
Fold Laws and Foldable Laws
Both Fold and Foldable obey the same monoid laws:
- Left identity:
combine(empty, x) = x - Right identity:
combine(x, empty) = x - Associativity:
combine(combine(x, y), z) = combine(x, combine(y, z))
This means foldMap produces consistent, predictable results regardless of how the fold is internally structured.
Practical Implications
Understanding this relationship helps you:
- Transfer knowledge: If you learn
Foldable, you understand the core ofFold - Recognise patterns: Monoid aggregation is universal across both abstractions
- Build intuition: A
Foldis like having a customFoldableinstance for each access path in your domain - Compose freely: You can convert between optics and type classes when needed (e.g.,
Lens.asFold())
The type class itself is covered in depth in Foldable and Traverse.
Complete, Runnable Example
This example demonstrates all major Fold operations in a single, cohesive application:
import java.math.BigDecimal;
import java.math.RoundingMode;
import java.time.Instant;
import java.util.Comparator;
import java.util.Currency;
import java.util.List;
import java.util.Optional;
import java.util.UUID;
import org.higherkindedj.example.book.optics.cast.Customer;
import org.higherkindedj.example.book.optics.cast.EmailAddress;
import org.higherkindedj.example.book.optics.cast.LineItem;
import org.higherkindedj.example.book.optics.cast.LineItemLenses;
import org.higherkindedj.example.book.optics.cast.Order;
import org.higherkindedj.example.book.optics.cast.OrderStatus;
import org.higherkindedj.example.book.optics.cast.OrderTraversals;
import org.higherkindedj.hkt.Monoid;
import org.higherkindedj.hkt.Monoids;
import org.higherkindedj.optics.Fold;
import org.higherkindedj.optics.Traversal;
import org.higherkindedj.optics.annotations.GenerateFolds;
import org.higherkindedj.optics.annotations.GenerateLenses;
import org.higherkindedj.optics.util.Traversals;
/**
* Comprehensive example demonstrating Fold optics for read-only querying and data extraction.
*
* <p>This example showcases:
*
* <ul>
* <li>Basic query operations: getAll, preview, find, exists, all, isEmpty, length
* <li>Composing folds for deep queries across nested structures
* <li>Monoid-based aggregation for calculating sums, checking conditions, etc.
* <li>Real-world analytics on a customer's order history
* </ul>
*
* <p>Fold is a read-only optic designed specifically for querying without modification, making code
* intent clear and preventing accidental mutations.
*/
public class FoldUsageExample {
// A customer's past orders, beside the chapter's Order
@GenerateLenses
@GenerateFolds
public record OrderHistory(List<Order> orders) {}
// An order of the customer's, placed on the same day, in pounds
private static Order order(String id, Customer customer, LineItem... lines) {
return new Order(
UUID.fromString(id),
customer,
List.of(lines),
Instant.parse("2026-10-01T09:00:00Z"),
Currency.getInstance("GBP"),
OrderStatus.NEW);
}
// A line's total: its price times its quantity
private static BigDecimal lineTotal(LineItem line) {
return line.price().multiply(BigDecimal.valueOf(line.quantity()));
}
public static void main(String[] args) {
// Create sample data: two of Ada's orders
Customer ada = new Customer("Ada", new EmailAddress("ada@example.com"));
var order1 =
order(
"00000000-0000-0000-0000-000000000001",
ada,
new LineItem("LAPTOP", 1, new BigDecimal("999.99")),
new LineItem("MOUSE", 2, new BigDecimal("12.50")),
new LineItem("DESK", 1, new BigDecimal("350.00")));
var order2 =
order(
"00000000-0000-0000-0000-000000000002",
ada,
new LineItem("KEYBOARD", 1, new BigDecimal("75.00")),
new LineItem("MONITOR", 1, new BigDecimal("450.00")),
new LineItem("CHAIR", 1, new BigDecimal("200.00")));
var history = new OrderHistory(List.of(order1, order2));
System.out.println("=== FOLD USAGE EXAMPLE ===\n");
// --- SCENARIO 1: Basic Query Operations ---
System.out.println("--- Scenario 1: Basic Query Operations ---");
Fold<Order, LineItem> linesFold = Fold.of(Order::lines);
List<LineItem> allLines = linesFold.getAll(order1);
System.out.println("All lines: " + allLines.size() + " line items");
Optional<LineItem> firstLine = linesFold.preview(order1);
System.out.println("First line: " + firstLine.map(LineItem::sku).orElse("none"));
int count = linesFold.length(order1);
System.out.println("Line count: " + count);
boolean isEmpty = linesFold.isEmpty(order1);
System.out.println("Is empty: " + isEmpty + "\n");
// --- SCENARIO 2: Conditional Queries ---
System.out.println("--- Scenario 2: Conditional Queries ---");
boolean hasMultiUnit = linesFold.exists(line -> line.quantity() > 1, order1);
System.out.println("Has a line for more than one unit: " + hasMultiUnit);
boolean allSingleUnits = linesFold.all(line -> line.quantity() == 1, order1);
System.out.println("All lines for a single unit: " + allSingleUnits);
Optional<LineItem> expensiveLine =
linesFold.find(line -> line.price().compareTo(new BigDecimal("500")) > 0, order1);
System.out.println(
"First line over £500: " + expensiveLine.map(LineItem::sku).orElse("none") + "\n");
// --- SCENARIO 3: Composition ---
System.out.println("--- Scenario 3: Composed Folds ---");
Fold<OrderHistory, LineItem> allHistoryLines = OrderHistoryFolds.orders().andThen(linesFold);
List<LineItem> linesFromHistory = allHistoryLines.getAll(history);
System.out.println("Total lines across all orders: " + linesFromHistory.size());
Fold<OrderHistory, String> allSkus = allHistoryLines.andThen(LineItemLenses.sku().asFold());
System.out.println("Every SKU: " + allSkus.getAll(history) + "\n");
// --- SCENARIO 4: Monoid Aggregation ---
System.out.println("--- Scenario 4: Monoid-Based Aggregation ---");
// Monoids has no BigDecimal sum, so money sums with a monoid of its own
Monoid<BigDecimal> sumMonoid =
new Monoid<>() {
@Override
public BigDecimal empty() {
return BigDecimal.ZERO;
}
@Override
public BigDecimal combine(BigDecimal a, BigDecimal b) {
return a.add(b);
}
};
BigDecimal orderTotal = linesFold.foldMap(sumMonoid, FoldUsageExample::lineTotal, order1);
System.out.println("Order 1 total: £" + orderTotal);
BigDecimal historyTotal =
allHistoryLines.foldMap(sumMonoid, FoldUsageExample::lineTotal, history);
System.out.println("All orders total: £" + historyTotal);
// Standard monoids from the Monoids utility class: Boolean AND for checking conditions
Monoid<Boolean> andMonoid = Monoids.booleanAnd();
boolean allAffordable =
linesFold.foldMap(
andMonoid, line -> line.price().compareTo(new BigDecimal("1000")) < 0, order1);
System.out.println("All lines under £1000: " + allAffordable);
// Boolean OR monoid for checking any condition
Monoid<Boolean> orMonoid = Monoids.booleanOr();
boolean hasOverFourHundred =
allHistoryLines.foldMap(
orMonoid, line -> line.price().compareTo(new BigDecimal("400")) > 0, history);
System.out.println("Has a line over £400: " + hasOverFourHundred + "\n");
// --- SCENARIO 5: Analytics ---
System.out.println("--- Scenario 5: Real-World Analytics ---");
// Most expensive line
Optional<LineItem> mostExpensive =
allHistoryLines.getAll(history).stream().max(Comparator.comparing(LineItem::price));
System.out.println(
"Most expensive line: "
+ mostExpensive.map(line -> line.sku() + " (£" + line.price() + ")").orElse("none"));
// Average line total
List<LineItem> everyLine = allHistoryLines.getAll(history);
BigDecimal averageLine =
everyLine.isEmpty()
? BigDecimal.ZERO
: historyTotal.divide(BigDecimal.valueOf(everyLine.size()), 2, RoundingMode.HALF_EVEN);
System.out.println("Average line total: £" + averageLine);
// Count the lines priced over £100
long overHundredCount =
allHistoryLines.getAll(history).stream()
.filter(line -> line.price().compareTo(new BigDecimal("100")) > 0)
.count();
System.out.println("Lines priced over £100: " + overHundredCount + "\n");
// --- SCENARIO 6: Traversal-Derived Folds ---
System.out.println("--- Scenario 6: Traversal-Derived Folds via asFold() ---");
// Build a Traversal for every line across all orders, then convert to Fold
Traversal<OrderHistory, LineItem> allLinesTraversal =
OrderHistoryLenses.orders()
.andThen(Traversals.<Order>forList())
.andThen(OrderTraversals.lines());
// Convert to Fold: the same query power as the folds above
Fold<OrderHistory, LineItem> traversalDerivedFold = allLinesTraversal.asFold();
// These produce the same results as the folds above
List<LineItem> allLines2 = traversalDerivedFold.getAll(history);
System.out.println("Lines via traversal-derived fold: " + allLines2.size());
BigDecimal total =
traversalDerivedFold.foldMap(sumMonoid, FoldUsageExample::lineTotal, history);
System.out.println("Total via traversal-derived fold: £" + total);
// Filter the traversal, then convert to Fold for targeted queries
Fold<OrderHistory, LineItem> overHundredFold =
allLinesTraversal
.filtered(line -> line.price().compareTo(new BigDecimal("100")) > 0)
.asFold();
int overHundredCount2 = overHundredFold.length(history);
BigDecimal overHundredTotal =
overHundredFold.foldMap(sumMonoid, FoldUsageExample::lineTotal, history);
System.out.println("Lines priced over £100: " + overHundredCount2);
System.out.println("Total of lines priced over £100: £" + overHundredTotal);
System.out.println("\n=== END OF EXAMPLE ===");
}
}
Expected Output:
=== FOLD USAGE EXAMPLE ===
--- Scenario 1: Basic Query Operations ---
All lines: 3 line items
First line: LAPTOP
Line count: 3
Is empty: false
--- Scenario 2: Conditional Queries ---
Has a line for more than one unit: true
All lines for a single unit: false
First line over £500: LAPTOP
--- Scenario 3: Composed Folds ---
Total lines across all orders: 6
Every SKU: [LAPTOP, MOUSE, DESK, KEYBOARD, MONITOR, CHAIR]
--- Scenario 4: Monoid-Based Aggregation ---
Order 1 total: £1374.99
All orders total: £2099.99
All lines under £1000: true
Has a line over £400: true
--- Scenario 5: Real-World Analytics ---
Most expensive line: LAPTOP (£999.99)
Average line total: £350.00
Lines priced over £100: 4
--- Scenario 6: Traversal-Derived Folds via asFold() ---
Lines via traversal-derived fold: 6
Total via traversal-derived fold: £2099.99
Lines priced over £100: 4
Total of lines priced over £100: £1999.99
=== END OF EXAMPLE ===
- A fold is a query the compiler checks: read-only by construction, so reporting code cannot accidentally modify the domain it reports on
- One method per question:
getAll,preview,find,exists,all, andlengthcover the everyday query surface foldMapwith aMonoidreplaces the loop: sums, counts, joins, and custom aggregations all come from the same machineryplus()merges paths: combine folds over different routes into one multi-path query with predictable ordering- Traversal downgrades, Fold never upgrades:
asFold()is free; there is no way back to writing
- Traversals: the read-write counterpart, and
asFold()for downgrading a path you already have - Getters: read-only focus on exactly one value
- Semigroup and Monoid: the combining structures behind
foldMap - Foldable and Traverse: the type class this optic mirrors
- Production Readiness: what each fold read visits, and when to cache a composed optic
- Haskell lens library: Control.Lens.Fold: the original inspiration
- Chris Penner: Optics By Example: comprehensive treatment of folds (Haskell)
Practise fold combination in Tutorial 18: Fold Combination (8 exercises).
Previous: Traversals Next: Getters