Generic Specs

Concrete, threaded, and element-mapped: three ways to map a generic record, one rule for how you reach the Impl.

A generic record (Page<T>, Result<E, A>) raises a question a monomorphic pair never does: is the mapping for one instantiation, for all of them, or parameterised by codecs the spec cannot know? All three are supported, and which one you have determines how the generated Impl is accessed. (No generic records at your boundary? Skip ahead to Merge and Error Envelopes and return when a Page<T> appears.)

Concrete instantiations

As a concrete instantiation, name the type arguments in the spec and every component classifies under that substitution, so the whole toolkit (leaves, nesting, containers, the null doctrine, index location) applies unchanged:

record Page<T>(List<T> items, int total) {}

record PageDto<T>(List<T> items, int total) {}

@GenerateMapping
interface CustomerPageMapping extends MappingSpec<Page<Customer>, PageDto<CustomerDto>> {}


    CustomerPageMappingImpl.INSTANCE.parse(
        new PageDto<>(
            List.of(new CustomerDto("Ada", "ada@corp.example"), new CustomerDto("Bob", "nope")),
            2));
    // Invalid(NonEmptyList[items.1.email: not an email address])

An instantiated mapping registers like any other, so Report(Page<Customer> results) nests it automatically. A threaded spec nests too: a use site's type arguments unify against the spec's declared pair, so Report(Page<String> results) resolves PageMapping<T> as PageMappingImpl.<String>instance(), and a generic outer spec may thread its own variable straight through.

Threaded specs

As a threaded spec, declare the spec generic in its own type parameters and one mapping serves every instantiation. Same-variable elements copy by identity under the null-element scan (a null element is items.1: must not be null, never a smuggled null), and the whole surface (build, parse, asIso on a lossless pair) is generic:

@GenerateMapping
interface PageMapping<T> extends MappingSpec<Page<T>, PageDto<T>> {}

// one Impl for every T: PageMappingImpl.<String>instance(), .<Integer>instance(), ...


    // One generic Impl serves every instantiation; identity elements copy through.
    Page<String> tags = new Page<>(List.of("fp", "hkt"), 2);
    PageDto<String> tagsDto = PageMappingImpl.<String>instance().build(tags);
    Validated<NonEmptyList<FieldError>, Page<Integer>> counts =
        PageMappingImpl.<Integer>instance().parse(new PageDto<>(List.of(1, 2, 3), 3));

A generic Impl cannot carry a typed static INSTANCE, so it follows the library's generic-singleton convention (EitherMonad.instance()): one stateless cached instance behind PageMappingImpl.instance(). Multi-parameter and bounded specs thread too (ResultMapping<E, A>, RankedMapping<T extends Number>), and a same-typed default leaf (ValidatedPrism<T, T>) still routes elements.

In assignment context the witness is inferred, so plain instance() reads naturally; the explicit PageMappingImpl.<String>instance() form is only needed where Java cannot infer:

    PageMapping<String> inferredWitness = PageMappingImpl.instance(); // witness inferred

One rule, three access shapes

The three access shapes are one rule, not three conventions: how much state does the Impl carry?

Element-mapped specs

The third form is element-mapped: thread the two sides under different variables (Page<T> ↔ PageDto<TDto>) and declare the element mapping as an abstract leaf. Nothing on the spec can parse a TDto into a T, so the generated Impl defers it: each abstract leaf becomes a constructor-supplied field behind a public of(...) factory, one ValidatedPrism per leaf in declaration order:

// The element mapping is deliberately open: an abstract leaf, supplied at of(...) time.
@GenerateMapping
interface CodecPageMapping<T, TDto> extends MappingSpec<Page<T>, PageDto<TDto>> {
  ValidatedPrism<TDto, T> items();
}


    // One spec, any element codec: each abstract leaf arrives as a prism through of(...).
    Validated<NonEmptyList<FieldError>, Page<EmailAddress>> mail =
        CodecPageMappingImpl.of(EmailCodecs.EMAIL)
            .parse(new PageDto<>(List.of("ada@example.org", "nope"), 2));
    // Invalid(NonEmptyList[items.1: not an email address])

The Impl carries the prisms as state, so there is no singleton in either spelling: every of(...) call is a fresh, immutable instance.

Element-mapped mappings nest as compositions. A use site whose pair unifies against one resolves each element pair in turn:

• through a leaf on the using spec named after the component (single-leaf specs; a spec with several abstract leaves resolves each pair through the registry),
• or recursively through another registered mapping,

and emits CodecPageMappingImpl.of(entries()).asValidatedPrism() in place. Failures locate through the whole composed path (entries.items.1: not an email address); an unresolvable element pair is a compile error naming the pair and both levers.

Previous: Beans and Sparse PATCH Next: Merge and Error Envelopes