Skip to content

docs: document typed JavaScript definition results - #6609

Merged
heruan merged 3 commits into
mainfrom
doc-bot/vaadin-flow/26890-2927455383d87af9
Nov 19, 2026
Merged

heruan merged 3 commits into
mainfrom
doc-bot/vaadin-flow/26890-2927455383d87af9

Conversation

@vaadin-bot

@vaadin-bot vaadin-bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Documentation for vaadin/flow#26890 by @totally-not-ai[bot].

Note

The source pull request is merged, so this documentation describes the final
shape of the change. Please review it and mark it ready for review.

Change categories: NEW_FEATURE, API_CHANGE

File Change
articles/flow/component-internals/element-api/calling-javascript.adoc Document declaring JavaScriptResult<T> as a return type to get a converted value with no type token at the call site, update the surrounding return-type and interface-checking text to cover it, and add a new Typed Results subsection.
articles/flow/advanced/browser-access.adoc Say that page-level @JsDefinition methods can also return a typed JavaScriptResult, and link to Typed Results.

Auto-generated by the Documentation Bot — review before merging.

Generated by Documentation Bot for #26890 · agent · 90.9 AIC · ⊞ 11.7K · ◷

  • expires on Dec 9, 2026, 8:26 PM UTC

Add a Typed Results section to Calling JavaScript, and update the
surrounding text to cover declaring JavaScriptResult<T> as a method
return type alongside PendingJavaScriptResult.

Documents vaadin/flow#26890 (`d0a07b236e5ee3ef6ff112c89bc75cc7ac57b29f`).
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Preview Deployment

This PR has been deployed for preview.

URL: https://docs-preview-pr-6609.fly.dev

Changed pages

Added content is highlighted in green; removed content is marked in red on each page.

Built from 89946d8

@heruan heruan left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The rest matches JavaScriptResult on Flow main: the example, the Jackson conversion, the handling of a value that can't be converted, and the rules for the type argument. One sentence is wrong, see the inline comment.


The type argument has to be known from the interface: either a concrete type, such as `JavaScriptResult<Integer>`, or a type variable of an interface the definition extends and binds to a concrete type -- `T` in `JavaScriptResult<T>` when the definition extends `ValueJs<Integer>`. A raw or wildcard [classname]`JavaScriptResult`, or a type variable the definition doesn't bind to a concrete type, is refused (see <<#declaring-javascript,Declaring JavaScript in Java>>).

[classname]`JavaScriptResult<JsonNode>` behaves like [classname]`PendingJavaScriptResult`: its handlers get the JSON as the browser sent it, and [methodname]`then()` can still be called with a [classname]`Class` or [classname]`TypeReference` to choose the Java type to convert to (see <<#deserializing-generic-types-with-typereference,Deserializing Generic Types with TypeReference>>).

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The second half is not correct. then(Class, ...) and then(TypeReference, ...) are declared on PendingJavaScriptResult only. A method declared as JavaScriptResult<JsonNode> has just then(handler), then(handler, errorHandler) and toCompletableFuture().

Suggestion: keep the first half (the handlers get the JSON as the browser sent it) and say that a method must return PendingJavaScriptResult to choose the Java type at the call site.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@heruan Fixed. The sentence now keeps only the first half: with JavaScriptResult<JsonNode> the handlers get the JSON as the browser sent it. It then says that to choose the Java type at the call site with then(Class, ...) or then(TypeReference, ...), the method must return PendingJavaScriptResult.

@heruan

heruan commented Nov 19, 2026

Copy link
Copy Markdown
Member

@totally-not-ai Address the review comments of this PR.

@heruan
heruan marked this pull request as ready for review November 19, 2026 08:56

@vaadin-review-bot vaadin-review-bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the changes — left 3 comments and collected 1 finding below that could not be attached to the diff.

Finding
⚠️ The browser page still says a declared method returns only PendingJavaScriptResult.
💬 The type-variable rule illustrates itself with a ValueJs interface the page never shows.
📐 The note now packs the whole type-argument rule into one 48-word sentence and repeats the new section.
📐 The new Typed Results heading has no since badge.

⚠️ The browser page still says a declared method returns only PendingJavaScriptResult.

A method that declares a return value can use the returned [classname]PendingJavaScriptResult the same way [methodname]executeJs(String, Object...) does.

Page.executeJs(Class) goes through the same JsDefinitionProxy.create as Element.executeJs(Class) (flow-server/src/main/java/com/vaadin/flow/component/page/Page.java:550), so a page definition can return JavaScriptResult<T> as well. After this PR the two pages disagree on what a declared method may return.

Suggestion: "A method that declares a return value answers with a [classname]PendingJavaScriptResult, or with a [classname]JavaScriptResult with a type argument, the same way a declaration on an element does."
browser-access.adoc:116 · accuracy


The value is converted with Jackson, so any type Jackson can deserialize works, including beans and generic types such as `List<Person>`. A value that can't be converted to the declared type goes to the error handler passed to [methodname]`then()`, and fails a future obtained from [methodname]`toCompletableFuture()`; without an error handler, it's logged as a warning.

The type argument has to be known from the interface: either a concrete type, such as `JavaScriptResult<Integer>`, or a type variable of an interface the definition extends and binds to a concrete type -- `T` in `JavaScriptResult<T>` when the definition extends `ValueJs<Integer>`. A raw or wildcard [classname]`JavaScriptResult`, or a type variable the definition doesn't bind to a concrete type, is refused (see <<#declaring-javascript,Declaring JavaScript in Java>>).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💬 The type-variable rule illustrates itself with a ValueJs interface the page never shows.

T in JavaScriptResult<T> when the definition extends ValueJs<Integer>

ValueJs appears nowhere else on the page, so the reader has to invent the interface (something like interface ValueJs<T> { @JsExpression("…") JavaScriptResult<T> readValue(); }) before the sentence means anything. The sentence is also ~45 words with the example folded into it.

Either show the two interfaces as a short code block, or drop the named example and say: "a type variable that an interface the definition extends binds to a concrete type."

calling-javascript.adoc:180 · clarity

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dropped the ValueJs example and split the rule into short sentences: the type argument is either a concrete type such as JavaScriptResult<Integer>, or a type variable that an interface the definition extends binds to a concrete type. Raw, wildcard, and unbound type arguments are refused, because nothing says what to convert the value to.


[NOTE]
The interface is checked when [methodname]`executeJs(Class)` hands out the implementation. It must be annotated with [annotationname]`@JsDefinition`, and every method must be annotated with [annotationname]`@JsExpression` and return `void` or [classname]`PendingJavaScriptResult`. A `default` or `static` method is refused, since it's implemented in Java rather than declaring JavaScript to run in the browser.
The interface is checked when [methodname]`executeJs(Class)` hands out the implementation. It must be annotated with [annotationname]`@JsDefinition`, and every method must be annotated with [annotationname]`@JsExpression` and return `void`, [classname]`PendingJavaScriptResult`, or [classname]`JavaScriptResult` with a type argument that's known from the interface -- either a concrete type, or a type variable that an interface the definition extends binds to a concrete type. A raw or wildcard [classname]`JavaScriptResult`, or one whose type argument is a type variable the interface doesn't bind to a concrete type, is refused, since nothing says what to convert the value to. A `default` or `static` method is refused, since it's implemented in Java rather than declaring JavaScript to run in the browser.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 The note now packs the whole type-argument rule into one 48-word sentence and repeats the new section.

The note's first sentence runs to about 48 words, and the two sentences together restate the rule that the new Typed Results section gives in full at line 180 — which then links back here for it.

CONVENTIONS.md: "When a sentence that you add or change is too long, split it. Give an aside or an example its own sentence. When a list of three or more items makes the sentence long, turn it into a bulleted list."

Keeping the note to the return types and pointing forward would fix both: "… and return void, [classname]PendingJavaScriptResult, or [classname]JavaScriptResult with a type argument that's known from the interface (see <<#typed-results,Typed Results>>)."

calling-javascript.adoc:105 · conventions

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The note now just lists the allowed return types (void, PendingJavaScriptResult, or JavaScriptResult with a type argument known from the interface) and links forward to Typed Results. The full type-argument rules now appear only in that section, which no longer links back to the note.



[[typed-results]]
=== Typed Results

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 The new Typed Results heading has no since badge.

JavaScriptResult is @since 25.4 (flow-server/src/main/java/com/vaadin/flow/component/page/JavaScriptResult.java:73), but the new subsection sits under == Return Values, which carries no badge and also covers the older executeJs(String, …) API.

CONVENTIONS.md: "Mark new features with a since badge instead: the [role="since:com.vaadin:vaadin@V25.2"] attribute above a section heading".

Add [role="since:com.vaadin:vaadin@V25.4"] above === Typed Results.

calling-javascript.adoc:151 · conventions

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added [role="since:com.vaadin:vaadin@V25.4"] above === Typed Results.

@totally-not-ai

Copy link
Copy Markdown
Contributor

Also updated browser-access.adoc: a method declared for Page.executeJs(Class) can now return a PendingJavaScriptResult or a typed JavaScriptResult, the same as a declaration on an element. The page links to Typed Results, so the two pages agree.

@heruan heruan left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, the fix is correct: only PendingJavaScriptResult lets the caller choose the type with then().

@heruan
heruan merged commit babfa5b into main Nov 19, 2026
11 checks passed
@heruan
heruan deleted the doc-bot/vaadin-flow/26890-2927455383d87af9 branch November 19, 2026 13:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants