Shared signals cannot express parameterized value types (no TypeReference)

[totally-not-ai]

Part of #138. Found while writing the Collaboration Kit to Signals migration guide (vaadin/docs#5888).

Real use case

A user administration form with a CheckboxGroup<String> of roles, or the MultiSelectComboBox from #137. The bound property is a Set<String>, and today it is bound with:

binder.forField(rolesField, Set.class, String.class).bind("roles");

The two class arguments exist precisely because the element type cannot be inferred. On migration to a shared signal there is nowhere to put the second one:

// No way to say "a set of strings"
new SharedValueSignal<>(Set.class);

The value round-trips through JSON as a bare array and comes back without its element type. Multi-select fields are common enough in business forms that most non-trivial CollaborationBinder forms hit this, and the failure is a runtime type problem rather than a compile error, so it surfaces during testing at best.

What Collaboration Kit does

Two ways to name a parameterized type:

• The topic API takes a Jackson TypeReference wherever it takes a Class, so CollaborationMap.get(key, TypeReference) and CollaborationList.getItems(TypeReference) read a Set<String>.
• CollaborationBinder.forField(field, Set.class, String.class) takes the collection type and the element type separately.

What signals have

Only Class. Every shared signal constructor takes Class<T>, and reading converts through treeToValue(node, Class). There is no TypeReference overload anywhere in the API.

Suggested direction

Either:

• TypeReference overloads on the shared signal constructors, matching what the topic API already accepts.
• Or a two-class form mirroring forField(field, collectionType, elementType).

The guide's workaround is to wrap the collection in a record, which is typed all the way down and serializes as an object. That works, but it forces a data model change on migration for what is a limitation of the type token rather than of the data.

[Artur-]

Confirmed against the Flow source (25.1 / com.vaadin.flow.signals): every shared signal type token is a Class, there is no TypeReference or JavaType anywhere in the signals API, and reads go through ObjectMapper.treeToValue(node, Class) in AbstractSharedSignal.fromJson (line ~594). A few details make the gap both sharper and subtler than the description, and they matter for how the guide should present it.

The compile error is real, but one constructor hides it

new SharedValueSignal<Set<String>>(Set.class) does not compile at all — Set.class has type Class<Set>, which is not assignable to Class<Set<String>>. The options are a raw SharedValueSignal<Set> (rawtypes plus unchecked warnings at every read) or an unchecked double cast (Class<Set<String>>) (Class<?>) Set.class.

But the other constructor, SharedValueSignal(T initialValue) (SharedValueSignal line ~61), derives the token from initialValue.getClass():

// compiles cleanly, T infers to Set<String>, token is ImmutableCollections$Set12
var rolesSignal = new SharedValueSignal<>(Set.of("admin"));

So the API looks like it accepts a parameterized type, while the token it stores is the erased runtime class. That is the shape most people will actually write, and it produces no warning at all.

What actually breaks, measured

Jackson 3.1.5, reading a JSON array back through an erased collection token:

Declared type	Element class after read	Result
Set<String>	String	works by accident
Set<Long>	Long	works by accident
Set<Role> (enum)	String	ClassCastException at the use site
Set<SomeBean>	LinkedHashMap	ClassCastException at the use site

Worth knowing for the guide: the CheckboxGroup<String> / Set<String> example in this issue round-trips fine at runtime once you get it past the compiler, because Jackson naturally produces String elements. Someone triaging this may well try that exact snippet and conclude it works. A Set<Role> where Role is an enum, or a MultiSelectComboBox bound to a set of beans, fails properly — and fails at the use site rather than at the read, which is the "surfaces during testing at best" part.

Writing is unaffected: toJson uses valueToTree on the runtime object, so serialization keeps the full element type. This is read-side only.

The Class-only surface, if someone picks this up

• SharedValueSignal(Class<T>) (line ~74) and the protected constructor (line ~95)
• SharedListSignal(Class<T> elementType) (line ~168)
• SharedMapSignal(Class<T> elementType) (line ~62)
• SharedNodeSignal.asValue/asList/asMap(Class) (lines ~201, ~232, ~250)
• SharedNodeSignalState.value(Class) (line ~107)
• the protected helpers AbstractSharedSignal.fromJson and nodeValue (lines ~594, ~614)

Implementation note: store a Jackson JavaType, not the TypeReference itself. Signals are Serializable (Signal extends Serializable, and session serialization is explicitly a concern in SignalTree), and JavaType implements Serializable while TypeReference does not. Class and TypeReference both funnel into TypeFactory.constructType, so one internal field covers both entry points. Two small follow-ons: the assert valueType.isInstance(value) in SharedValueSignal.set becomes javaType.getRawClass().isInstance(value), and equals/hashCode already include the token, so they keep working unchanged.

Argument for the TypeReference option over the two-class form

Flow already pairs Class with TypeReference everywhere else it deserializes JSON into user types:

• Element.getPropertyBean(String, TypeReference)
• PendingJavaScriptResult.then(TypeReference, ...) for executeJs return values
• DomEvent.getEventDetail(TypeReference) and DomListenerRegistration
• JacksonCodec and JacksonUtils

Shared signals are the outlier in Flow's own API surface, not only against Collaboration Kit's topic API. The two-class forField(field, Set.class, String.class) form only covers one level of nesting anyway, so it would not express Map<String, List<Role>>.

Workaround that does not change the data model

The guide's record wrapper works, but it changes the stored JSON from an array to an object, which breaks reading data written by the Collaboration Kit version of the same application, or by anything else sharing the topic. Using JsonNode as the signal value type avoids that — the stored JSON stays a bare array, and the conversion happens in application code where a TypeReference is available:

private static final ObjectMapper mapper = new ObjectMapper();
private static final TypeReference<Set<Role>> ROLES = new TypeReference<>() {};

SharedValueSignal<JsonNode> rolesSignal = new SharedValueSignal<>(JsonNode.class);

// write
rolesSignal.set(mapper.valueToTree(roles));

// read
JsonNode json = rolesSignal.get();
Set<Role> roles = json == null ? Set.of() : mapper.treeToValue(json, ROLES);

Verified that treeToValue(node, JsonNode.class) round-trips the node unchanged, so this works through the existing public API with no casts and no raw types. For a tidier version, AbstractSharedSignal.extractValue(Data) is protected and Node.Data.value() exposes the raw JsonNode, so a subclass can do the same conversion behind a properly typed get().

Related gap found while checking this

AbstractSharedSignal uses a private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper() (line ~104) with no configuration hook, even though the Javadoc on toJson/fromJson says "using the global signal object mapper" and carries @see SignalEnvironment — SignalEnvironment has no mapper at all. Two consequences: registering a module with a custom deserializer is not available as a workaround for this issue, and shared signals do not use Flow's configured mapper from JacksonUtils.getMapper(). Probably worth its own Flow ticket regardless of how the type token question is resolved.

[Legioth]

We should indeed introduce TypeReference APIs in the relevant places.

Since this only affects top-level values, it's usually a reasonable workaround to introduce a helper class such as class RoleSet extends HashSet<Role> for the specific cases where it's needed.