Skip to content

docs: note that typed JS error handlers cover conversion failures - #6612

Merged
heruan merged 2 commits into
mainfrom
doc-bot/vaadin-flow/26920-ae14e9a423678339
Nov 19, 2026
Merged

heruan merged 2 commits into
mainfrom
doc-bot/vaadin-flow/26920-ae14e9a423678339

Conversation

@vaadin-bot

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

Copy link
Copy Markdown
Contributor

Documentation for vaadin/flow#26920 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: BEHAVIOR_CHANGE

File Change
articles/flow/component-internals/element-api/calling-javascript.adoc Say that the typed then() error handler and toCompletableFuture() also fire for a return value that can't be converted to the target type, not only for a failed execution, and that the resulting JavaScriptException carries the conversion error as its cause. Also say that without an error handler, such a value is logged as a warning and the result handler isn't run. Each of these statements has a 25.4 since badge.

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

Generated by Documentation Bot for #26920 · agent · 66.7 AIC · ⊞ 11.7K · ◷

  • expires on Dec 10, 2026, 8:48 AM UTC

Update Calling JavaScript from the Server to say that the typed
then() error handler and toCompletableFuture() also report a return
value that can't be converted to the target type, not only a failed
execution, and that the future's JavaScriptException carries the
conversion error as its cause.

Documents vaadin/flow#26920 (`fe26d92ac988d6ee5de879e3c2ac58ccd815cda4`).

@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.

Checked against PendingJavaScriptResult on Flow main: the error handler gets a message also when the value can't be converted, and the future fails with a JavaScriptException whose cause is the conversion error.

The failed build-and-deploy check is a preview deploy error (connection timed out while building the image), not a content problem.

@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 2 comments.

Finding
💬 The page doesn't say what happens to a conversion failure when no error handler is given
📐 Behavior that is new in the upcoming version carries no since badge

====

An error handler can be provided as a second callback. The handler receives the error message from the failed JavaScript execution as a `String`:
An error handler can be provided as a second callback. It receives an error message as a `String`, whether the JavaScript execution failed or the returned value can't be converted to the target type:

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 page doesn't say what happens to a conversion failure when no error handler is given

The change documents the conversion failure only for the three-argument then(). Every then() example on the page (lines 97, 133, 173) passes just a result handler. In that case Flow logs the failure as a warning and runs no handler at all (TypedJavaScriptResultUtil.then(), lines 70-78, and the errorHandler javadoc of PendingJavaScriptResult.then(), lines 108-113: "Without an error handler, a return value that can not be converted is logged as a warning").

A reader whose JavaScript returns a value of an unexpected shape sees nothing happen and has no way to tell from this page why. Consider adding one sentence, for example: "Without an error handler, a value that can't be converted is logged as a warning and the result handler isn't run."

calling-javascript.adoc:182 · clarity

new TypeReference<Map<String, Person>>() {});
----

If the execution fails, or the returned value can't be converted to the target type, the future completes exceptionally with a [classname]`JavaScriptException`. When the value can't be converted, its cause is the conversion error.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

📐 Behavior that is new in the upcoming version carries no since badge

The PR metadata categorizes this as a BEHAVIOR_CHANGE, and the class that implements it, TypedJavaScriptResultUtil, is @since 25.4 — the version this branch documents. CONVENTIONS.md says: "Do not write Vaadin version numbers in text. Mark new features with a since badge instead". Line 15 of this same page already badges a 25.4 behavior change inline: [since:com.vaadin:vaadin@V25.4]#works under such a policy as well#.

Both new statements (lines 182 and 202) would read the same way, for example [since:com.vaadin:vaadin@V25.4]#or the returned value can't be converted to the target type#.

calling-javascript.adoc:202 · conventions

@heruan

heruan commented Nov 19, 2026

Copy link
Copy Markdown
Member

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

Mark the conversion failure behaviour of the typed then() error handler
and toCompletableFuture() with a since badge, and say that without an
error handler a value that can't be converted is logged as a warning
and the result handler isn't run.
@totally-not-ai

Copy link
Copy Markdown
Contributor

@heruan Addressed both review comments:

  • Missing error handler: added a sentence after the error handler example saying that without an error handler, a value that can't be converted is logged as a warning and the result handler isn't run. This matches PendingJavaScriptResult.then() and TypedJavaScriptResultUtil on Flow main.
  • since badges: the conversion-failure parts of the error handler and toCompletableFuture() paragraphs, and the new no-handler sentence, now have inline [since:com.vaadin:vaadin@V25.4] badges. The parts that were already true before (a failed execution) aren't badged.

The earlier failed build-and-deploy was a Fly.io connection timeout while building the preview image, not a content problem. This push starts a new preview run.

@github-actions

Copy link
Copy Markdown
Contributor

Preview Deployment

This PR has been deployed for preview.

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

Changed pages

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

Built from f92377e

@heruan
heruan merged commit f2c7ae4 into main Nov 19, 2026
12 of 13 checks passed
@heruan
heruan deleted the doc-bot/vaadin-flow/26920-ae14e9a423678339 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