Many Edits at Once
Apply several edits as one update, or check a REST PATCH and report every bad field at once.
- Combine edits at different paths into one reusable update with
Edits.combine - Write a sparse update, where a
nullfield means "leave it alone", with noifper field - Check every field of a REST
PATCHwithEdits.accumulate, and report all the bad ones together - Edit fields a record's constructor checks together, so it sees only the final values
The code on this page is MultiEditBook.java: the page includes it directly, so the build compiles and runs it.
The problem
A path makes one edit at a time. The everyday case is several edits at once, and the classic one is a REST PATCH of an order line that trims the SKU, bumps the quantity and sets a new price. The request body is a LineItemPatch(sku, qtyDelta, price), each component null when the client did not send it. By hand that means threading the value through every step, guarding each optional field with an if, and, if you validate at all, throwing on the first bad field:
LineItem updated = line;
if (patch.sku() != null) {
updated = updated.withSku(patch.sku().strip()); // thread the result...
}
if (patch.qtyDelta() != null) {
updated =
updated.withQuantity(updated.quantity() + patch.qtyDelta()); // ...through every step
}
if (patch.price() != null) {
updated = updated.withPrice(new BigDecimal(patch.price())); // throws on a malformed price
}
// The SKU goes unchecked, and a malformed price throws, so the first bad field hides the rest.
Three pains recur: one if per optional field, the value re-threaded by hand at every step, and validation that stops at the first error instead of collecting them all. If you use MapStruct for this, its answer is @MappingTarget with NullValuePropertyMappingStrategy.IGNORE, and Coming from MapStruct sets the two side by side.
The solution: two entry points
The org.higherkindedj.optics.edit package folds all of that into two operations. Which one you reach for depends only on whether any edit can fail:
| Entry point | Reach for it when | Returns |
|---|---|---|
Edits.combine(...) | every edit is always safe (no validation) | one reusable Update<S> |
Edits.accumulate(...) | some edits validate their input (a REST PATCH) | a patch you apply to get Validated<NonEmptyList<FieldError>, S> |
Those are the whole API, with one more form of accumulate for fields a constructor checks together. The rest of this page is how each one behaves, and how the compiler keeps a validating edit from slipping into combine by accident.
Edits that cannot fail: Edits.combine
Each Edit factory pairs an optic (a FocusPath or a Setter) with a value or function. combine joins them, in order, into one Update<LineItem>: a function from line to line that you can name and reuse. The factories are static imports from org.higherkindedj.optics.edit.Edit:
import static org.higherkindedj.optics.edit.Edit.*;
With them in scope, each modify names one edit, and combine joins the edits into one update:
Update<LineItem> tidy =
Edits.combine(
modify(SKU, sku -> sku.strip().toUpperCase()),
modify(PRICE, price -> price.setScale(2, RoundingMode.HALF_EVEN)));
Update<LineItem> doubled = Edits.combine(modify(QUANTITY, quantity -> quantity * 2));
LineItem lamp = tidy.apply(new LineItem(" lamp ", 1, new BigDecimal("40")));
// LineItem[sku=LAMP, quantity=1, price=40.00]
// an Update composes further: the bulbs are tidied, then their quantity doubled
LineItem bulbs = tidy.andThen(doubled).apply(new LineItem("bulb", 4, new BigDecimal("2.5")));
// LineItem[sku=BULB, quantity=8, price=2.50]
Only pure Edits fit combine's signature; a fallible edit is rejected at compile time, so validation failures can never be silently dropped.
Sparse updates: absent means "leave it alone"
The …IfPresent factories treat null as absent: the edit changes nothing, so a sparse request DTO lands one-to-one with no if ceremony:
Edit<LineItem> sku = setIfPresent(SKU, sparsePatch.sku()); // null -> no-op
Edit<LineItem> quantity =
modifyIfPresent(QUANTITY, sparsePatch.qtyDelta(), (delta, qty) -> qty + delta);
LineItem restocked = Edits.combine(sku, quantity).apply(lampLine);
// LineItem[sku=LAMP, quantity=4, price=40.00]
Each request field maps to exactly one slot; an absent field simply contributes nothing to the fold:
flowchart TD
accTitle: A sparse request, field by field
accDescr: A request with no SKU and a quantity delta of 3. The absent SKU changes nothing and the quantity grows by 3, so the line comes back with its quantity changed and its SKU untouched.
Req["LineItemPatch<br/>sku: null, qtyDelta: 3"]
Req --> S["sku absent<br/>no change"]
Req --> Q["qtyDelta present<br/>quantity += 3"]
S --> Out["line': quantity changed,<br/>SKU untouched"]
Q --> Out
classDef tier fill:#a6d189,stroke:#40a02b,color:#232634
classDef out fill:#a6d189,stroke:#40a02b,color:#232634
class Req,S,Q tier
class Out out
A sparse edit cannot clear a field: setIfPresent(path, null) means "no change requested", not "set to null". This suits non-null domain models; if a field must be clearable, model the cleared state explicitly (e.g. Maybe) and set it. The functions given to modifyIfPresent/parseIfPresent are never invoked with null.
Validated PATCH: Edits.accumulate
parseIfPresent parses the incoming value first, and a generated path locates any failure automatically from its own label. The parser you hand it has exactly the shape of a ValidatedPrism's parse, so a boundary defined once as a prism passes its parse here. This request's SKU and price are both bad:
The two parsers
The two parsers
/** The boundary parsers the page hands to {@code parseIfPresent}. */
final class SkuParser {
static Validated<NonEmptyList<FieldError>, String> parse(String raw) {
String sku = raw.strip();
return sku.matches("[A-Z0-9-]+")
? Validated.validNel(sku)
: Validated.invalidNel(FieldError.of("not a SKU"));
}
private SkuParser() {}
}
final class PriceParser {
static Validated<NonEmptyList<FieldError>, BigDecimal> parse(String raw) {
try {
BigDecimal price = new BigDecimal(raw.strip());
return price.signum() >= 0
? Validated.validNel(price)
: Validated.invalidNel(FieldError.of("not a price"));
} catch (NumberFormatException e) {
return Validated.invalidNel(FieldError.of("not a price"));
}
}
private PriceParser() {}
}
Validated<NonEmptyList<FieldError>, LineItem> patched =
Edits.accumulate(
parseIfPresent(SKU, badPatch.sku(), SkuParser::parse),
modifyIfPresent(QUANTITY, badPatch.qtyDelta(), (delta, qty) -> qty + delta),
parseIfPresent(PRICE, badPatch.price(), PriceParser::parse))
.apply(line);
// Invalid(NonEmptyList[sku: not a SKU, price: not a price])
// <- or Valid(line) with only the present fields changed
accumulate checks every edit independently and reports all the bad fields at once, each named by its path. The errors arrive in edit order on the NonEmptyList, as in the accumulating assembly, and one patch can hold any number of edits.
A path from a @GenerateFocus companion carries its record-component name as a segment: LineItemFocus.sku() is labelled "sku". Composing paths joins the segments, so OrderFocus.customer().email().value() is "customer.email.value", which segments() and pathString() return. parseIfPresent locates failures with them automatically, so a generated path needs no .at(...). An explicit .at(label) still prepends outward, for a hand-written optic or extra context, as FieldError.at does.
To carry on in an Effect Path, applyPath(line) is the ValidationPath twin of apply(line), and toValidated() exposes the folded Update itself for reuse.
When the request DTO's fields line up one-to-one with a domain record, the common REST PATCH case, you need not hand-write the fold at all. @GenerateMapping on an UpdateSpec<Domain, Wire> generates this Edits.accumulate over the present fields, in its construct-once form. It returns updateFrom(wire) : Edits.Accumulated<Domain>, with the same apply, applyPath and toValidated. Reach for the hand-written Edits here when the edits are irregular (a qtyDelta that modifies, coupled fields, a computed target); reach for UpdateSpec when each present field maps to one slot.
How the split stays compile-time safe
combine accepts only pure edits; accumulate accepts both. That is not a rule you have to remember: it is carried by the type of each edit. set, modify, and the …IfPresent forms produce an Edit (cannot fail); parseIfPresent produces a FallibleEdit (may fail). Passing a FallibleEdit to combine does not compile, so a validation failure can never be silently dropped.
flowchart TD
accTitle: How combine and accumulate tell the edits apart
accDescr: parseIfPresent makes a FallibleEdit, which may fail. set, modify and the IfPresent forms make an Edit, which cannot fail, and every Edit is also a FallibleEdit. Edits.combine takes only Edits, so a FallibleEdit there is a compile error; Edits.accumulate takes both.
FE["FallibleEdit<S><br/>may fail: carries Validated<NEL<FieldError>, Update<S>>"]
ED["Edit<S><br/>cannot fail: carries the Update<S> directly"]
P["FallibleEdit.Parsed<br/>from parseIfPresent"] --> FE
I["Edit.Infallible<br/>from set, modify, …IfPresent"] --> ED
ED --> FE
C["Edits.combine(Edit…)<br/>only pure edits fit:<br/>a FallibleEdit is a compile error"]
A["Edits.accumulate(FallibleEdit…)<br/>both fit: a pure edit<br/>is one that always validates"]
ED --> C
FE --> A
classDef tier fill:#a6d189,stroke:#40a02b,color:#232634
classDef out fill:#a6d189,stroke:#40a02b,color:#232634
class FE,ED,P,I tier
class C,A out
Semantics: validate everything, then write once
An accumulated patch works in two phases:
- Validate: each edit's incoming value is checked independently. Validation never sees a source, so every check runs, and one patch applies to many sources.
- Apply: only if every edit validated, the writes run as a single left-to-right fold.
flowchart TD
accTitle: Validate everything, then write once
accDescr: In phase 1 each edit is checked on its own, with no source: an absent SKU is a valid no-op, the price is parsed, and a present quantity delta is a valid write. If every edit is valid, phase 2 runs the writes as one left-to-right fold; otherwise the result is Invalid with every bad field located.
subgraph one["Phase 1: validate each edit independently, no source involved"]
direction LR
S1["setIfPresent(SKU, null)<br/>absent, so no change"] --> V1["Valid, a no-op"]
S2["parseIfPresent(PRICE, raw)<br/>the parser runs"] --> V2["Valid(write)<br/>or Invalid(errors)"]
S3["modifyIfPresent(QTY, 3)<br/>present → write"] --> V3["Valid(write)"]
end
one --> Q{"every edit Valid?"}
Q -->|"yes"| Ok["Phase 2: one left-to-right<br/>fold: Valid(line'), only<br/>the present fields written"]
Q -->|"no"| Bad["Invalid(NEL[price: …])<br/>every bad field, located"]
classDef tier fill:#a6d189,stroke:#40a02b,color:#232634
classDef decision fill:#e5c890,stroke:#df8e1d,color:#232634
classDef bad fill:#e78284,stroke:#d20f39,color:#232634
class S1,S2,S3,V1,V2,V3,Ok tier
class Q decision
class Bad bad
Application order is observable only when paths overlap: disjoint paths commute; an edit at an overlapping path sees the previous edit's result (a modify reads the current value at application time). Genuinely coupled fields belong in one atomic edit (see Coupled Fields and Lens.paired), or, when a record's constructor checks them against each other, onto a focus.
Fields a constructor checks together
Each write through a record's path builds a new record, so the constructor sees every value the fold passes through. Take a PriceBand, a catalogue price band in pence, whose constructor refuses floor > ceiling. It cannot move from PriceBand(100, 300) to PriceBand(500, 1000) one end at a time: writing the floor first builds PriceBand(500, 300), and the constructor throws before the ceiling is written, although the final band is valid.
Edits.accumulate(focus, edits...) takes a Lens to a value carrying the fields the edits set, with no check of its own, here Bounds. The request move asks for a floor of 500 and a ceiling of 1000. The edits write onto that value, and the lens sets it back once, so the constructor sees only the final values:
record PriceBand(int floor, int ceiling) {
PriceBand {
if (floor > ceiling) {
throw new IllegalArgumentException("floor above ceiling");
}
}
}
@GenerateFocus
record Bounds(int floor, int ceiling) {} // the fields the edits set, with no check of their own
Lens<PriceBand, Bounds> bounds =
Lens.of(
band -> new Bounds(band.floor(), band.ceiling()),
(_, b) -> new PriceBand(b.floor(), b.ceiling()));
Validated<NonEmptyList<FieldError>, PriceBand> moved =
Edits.accumulate(
bounds,
setIfPresent(BoundsFocus.floor(), move.floor()),
setIfPresent(BoundsFocus.ceiling(), move.ceiling()))
.apply(new PriceBand(100, 300));
// Valid(PriceBand[floor=500, ceiling=1000])
// <- both ends move together. Moving the floor alone would make PriceBand(500, 300), which
// the record's own constructor refuses, and the refusal would arrive as an error.
flowchart TD
accTitle: One record per edit, or one record in all
accDescr: With plain accumulate, setting the floor to 500 on PriceBand(100, 300) builds PriceBand(500, 300), which the constructor refuses. With accumulate onto the Bounds focus, the floor and ceiling are written onto Bounds(100, 300) in turn, giving Bounds(500, 1000), and the lens sets it back once as PriceBand(500, 1000).
%% declared in reverse: the layout places the last subgraph on the left
subgraph once["accumulate(bounds, edits…): one PriceBand in all"]
direction TB
B1["Bounds(100, 300)"] -->|"floor = 500"| B2["Bounds(500, 300)"] -->|"ceiling = 1000"| B3["Bounds(500, 1000)"] -->|"set once"| B4["PriceBand(500, 1000)"]
end
subgraph each["accumulate(edits…): one record per edit"]
direction TB
A1["PriceBand(100, 300)"] -->|"floor = 500"| A2["PriceBand(500, 300)<br/>the constructor throws"]
end
classDef tier fill:#a6d189,stroke:#40a02b,color:#232634
classDef bad fill:#e78284,stroke:#d20f39,color:#232634
class A1,B1,B2,B3,B4 tier
class A2 bad
@GenerateMapping on an UpdateSpec generates exactly this: its updateFrom writes onto the components a PATCH can set and constructs the domain record once.
You can now update nested records, check what you write, and apply a PATCH that reports every bad field. The Capstone that follows puts these pieces together, and When the constructor refuses is the fine print of this page.
What quantity does Edits.combine(modify(QUANTITY, q -> q + 1), modify(QUANTITY, q -> q * 2)) leave on a line of quantity 3?
Answer and why
Answer and why
8. The writes run left to right, and an edit at an overlapping path sees the previous edit's result: 3 becomes 4, then 8.
Where this lives: Semantics: validate everything, then write once.
A PATCH sends a blank SKU, a qtyDelta of 2 and the price forty. With this page's parsers and Edits.accumulate, is the line's quantity changed?
Answer and why
Answer and why
No. The result is Invalid(NonEmptyList[sku: not a SKU, price: not a price]), and an Invalid carries no line. The writes run only when every edit validated, so the good qtyDelta is not applied either.
Where this lives: Semantics: validate everything, then write once.
The fine print
When the constructor refuses
The edits validate exactly as they do in accumulate, and their errors are reported alone: the record is constructed only once every edit validated. After that, apply treats each kind of exception its own way:
| What happens | What apply returns |
|---|---|
Setting the focus back throws a RuntimeException: the constructor refusing the final values | An unlabelled FieldError carrying the exception's message, or not a valid PriceBand when the message is missing or blank |
| An edit's own function, or reading the focus, throws | Nothing: the exception propagates, since only setting the focus back is guarded |
| Every edit is absent | The source as it is, without setting the focus |
toValidated() hands back an Update that writes onto the focus and sets it back once. An Update has no error channel, so a refusal throws from it.
The edits' errors are located relative to the focus. Where the focus is a nested component rather than the source's own fields, add the component's name to each edit with .at("band"), so their errors and the source agree on where they are.
Edits.combinejoins edits that cannot fail into one reusableUpdate<S>. A fallible edit does not compile there.- An absent value changes nothing. The
…IfPresentforms take a sparse request field by field, with noif. Edits.accumulatechecks every edit and reports every bad field. The errors arrive located and in edit order, and a patch holds any number of edits.- A patch validates first, then writes once. Validation never sees the source, and the writes run left to right only when every edit passed.
- Overlapping paths see earlier writes. Fields that must change together belong in one atomic edit, such as
Lens.paired. Edits.accumulate(focus, …)builds the record once. A constructor that checks fields against each other sees only the final values, and its refusal is anInvalid.
Practise the whole model in Tutorial 24: Multi-Edit and Sparse Updates (5 exercises): pure folds, sparse patches, and the all-errors-at-once validated PATCH.
- Updates That Can Fail: one field or one list at a time, through
OpticOps - Semigroup and Monoid: the
Updatemonoid that powerscombine - Accumulating Assembly: the same all-errors-at-once model for constructing values
- Coupled Fields: atomic updates of interdependent fields
- Sparse PATCH (
UpdateSpec): generate thisEdits.accumulatefold when the DTO maps one-to-one
Previous: Updates That Can Fail Next: Capstone: An Order Desk