Kind Field Support in Focus DSL

Automatic Traversal for Higher-Kinded Type Fields

Domain records in a Higher-Kinded-J codebase often hold their contents in a Kind<F, A>: a team's members as Kind<ListKind.Witness, Member>, an optional lead as Kind<MaybeKind.Witness, Member>. The processor recognises those witnesses and generates the traversal for you, so the field reads exactly like a plain List field would:

// Kind<ListKind.Witness, Member> members, and yet:
List<Member> everyone = TeamFocus.members().getAll(team);

Team levelled =
    TeamFocus.members()
        .via(MemberFocus.skills())
        .modifyAll(Fixture::improve, team);

The Problem It Removes

Without automatic detection, every Kind field would need its Traverse instance threaded in by hand at each use site:

// What you would otherwise write, once per field, per call site
TraversalPath<Team, Member> memberPath =
    FocusPath.of(TeamLenses.members()).<ListKind.Witness, Member>traverseOver(ListTraverse.INSTANCE);

The processor knows which Traverse belongs to ListKind.Witness, so the generated method has already applied it.

Convention-Based Detection

A witness is the marker type that stands in for the higher-kinded F (see Higher-Kinded Types). The library's witnesses are recognised by name:

Parameterised witnesses are handled too: an EitherKind.Witness<String> field generates a call to EitherTraverse.<String>instance() with the type argument carried through.

// One record, three witnesses, three path types
AffinePath<ApiResponse, Member> lead = ApiResponseFocus.lead();          // MaybeKind
TraversalPath<ApiResponse, String> warnings = ApiResponseFocus.warnings(); // ListKind
AffinePath<ApiResponse, String> result = ApiResponseFocus.result();      // EitherKind<String>

Optional<Member> theLead = lead.getOptional(response);
List<String> allWarnings = warnings.getAll(response);

What the Semantics Decide

KindSemantics is cardinality for witnesses: it classifies a witness by how many values its type can hold, exactly as a container's Cardinality does for a plain field, and that classification picks the path type:

• ZERO_OR_MORE (ListKind, StreamKind): a TraversalPath, straight from traverseOver.
• ZERO_OR_ONE (MaybeKind, OptionalKind, TryKind, EitherKind, ValidatedKind): a TraversalPath narrowed with headOption() to an AffinePath.
• EXACTLY_ONE (IdKind): also narrowed to an AffinePath.

Custom Kind Types with @TraverseField

For a witness outside the library, name the Traverse instance and the cardinality:

@GenerateFocus
record Forest(
    String name,
    @TraverseField(
        traverse = "com.example.TreeTraverse.INSTANCE",
        semantics = KindSemantics.ZERO_OR_MORE)
    Kind<TreeKind.Witness, Tree> trees) {}

// Generates: TraversalPath<Forest, Tree> trees()

The expression is emitted verbatim, so any of these forms works:

@TraverseField(traverse = "com.example.TreeTraverse.INSTANCE")     // enum singleton
@TraverseField(traverse = "com.example.TreeTraverse.instance()")   // factory method
@TraverseField(traverse = "com.example.TreeTraverse.TRAVERSE")     // static field

A Kind<F, A> field with an unrecognised witness and no @TraverseField is not an error: the processor falls back to a plain FocusPath focusing the raw Kind, and you apply traverseOver yourself.

headOption(): Narrowing a Traversal

headOption() turns a TraversalPath into an AffinePath. Its read is the first focused element; its write goes to every focused element, because that is what the underlying traversal does:

TraversalPath<Member, Skill> skills = MemberFocus.skills();

AffinePath<Member, Skill> firstSkill = skills.headOption();
Optional<Skill> first = firstSkill.getOptional(alice);   // Optional[Skill[name=Java, proficiency=95]]

Member flattened = firstSkill.set(new Skill("Go", 50), alice);
// BOTH skills are now Skill[name=Go, proficiency=50]: the set is setAll underneath

Composing with the Rest of the DSL

Kind field paths are ordinary paths, so filtering, conditional modification and chaining all apply:

// Members who have a weak skill
TraversalPath<Team, Member> needsTraining =
    TeamFocus.members().filter(m -> MemberFocus.skills().exists(s -> s.proficiency() < 50, m));

List<Member> juniors = needsTraining.getAll(team);

// Improve only their skills
Team afterTraining =
    TeamFocus.members()
        .modifyWhen(
            m -> MemberFocus.skills().exists(s -> s.proficiency() < 50, m),
            m -> MemberFocus.skills().modifyAll(Fixture::improve, m),
            team);

Previous: Focus DSL with External Libraries Next: Fluent API