Repository navigation
docs: note that typed JS error handlers cover conversion failures - #6612
Conversation
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
left a comment
There was a problem hiding this comment.
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
left a comment
There was a problem hiding this comment.
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: |
There was a problem hiding this comment.
💬 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. |
There was a problem hiding this comment.
📐 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
|
@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.
|
@heruan Addressed both review comments:
The earlier failed |
Preview DeploymentThis PR has been deployed for preview. URL: https://docs-preview-pr-6612.fly.dev Changed pagesAdded content is highlighted in green; removed content is marked in red on each page.
Built from f92377e |
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
articles/flow/component-internals/element-api/calling-javascript.adocthen()error handler andtoCompletableFuture()also fire for a return value that can't be converted to the target type, not only for a failed execution, and that the resultingJavaScriptExceptioncarries 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.4sincebadge.Auto-generated by the Documentation Bot — review before merging.