Skip to content

Document the new exception API #1046

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 4, 2025
Merged

Document the new exception API #1046

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
938d9e2
Document the new API around exceptions
tsnobip Jun 4, 2025
2052653
update other pages with the new exception API
tsnobip Jun 4, 2025
b757c51
improve wording
tsnobip Jun 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions pages/docs/manual/v12.0.0/async-await.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,15 +130,15 @@ You may use `try / catch` or `switch` to handle exceptions during async executio
```res
// For simulation purposes
let authenticate = async () => {
raise(Exn.raiseRangeError("Authentication failed."))
JsError.RangeError.throwWithMessage("Authentication failed.")
Copy link
Contributor

Choose a reason for hiding this comment

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

Are JsError and JsExn the same thing?

Copy link
Member Author

Choose a reason for hiding this comment

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

JsError is the module around JS errors while JsExn is the module around things that can be thrown and caught in JS, so pretty much anything actually.

}

let checkAuth = async () => {
try {
await authenticate()
} catch {
| Exn.Error(e) =>
switch Exn.message(e) {
| JsExn(e) =>
Copy link
Contributor

Choose a reason for hiding this comment

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

It is still a little confusing where JsExn is coming from.
Is this the "Exceptions are just a special kind of variant" from the beginning?

Copy link
Member Author

Choose a reason for hiding this comment

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

I just updated this page so it stays in sync with the new API, I think this could be improved in another PR.

switch JsExn.message(e) {
| Some(msg) => Console.log("JS error thrown: " ++ msg)
| None => Console.log("Some other exception has been thrown")
}
Expand All @@ -152,14 +152,14 @@ You may unify error and value handling in a single switch as well:

```res
let authenticate = async () => {
raise(Exn.raiseRangeError("Authentication failed."))
JsError.RangeError.throwWithMessage("Authentication failed.")
}

let checkAuth = async () => {
switch await authenticate() {
| _ => Console.log("ok")
| exception Exn.Error(e) =>
switch Exn.message(e) {
| exception JsExn(e) =>
Copy link
Contributor

Choose a reason for hiding this comment

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

Is this exhaustive? How does this work with the other built-in exceptions?
Do we cover all of them with this?
Do I add exception Invalid_argument above this case when I want to match that?

Copy link
Member Author

Choose a reason for hiding this comment

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

This is already covered in the exceptions page, I fear we would repeat ourselves too much otherwise.

Copy link
Contributor

@nojaf nojaf Jun 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

That is one of looking at it, but there you assume your user has read that exceptions page.
And so you assume the docs are read in a certain order.
This is not my experience with the docs. I often go and look at documentation because I have a specific problem, so I find links between these pages very valuable.

Copy link
Member Author

Choose a reason for hiding this comment

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

@nojaf you're totally right, I'd just change this a subsequent PR, I just replaced the calls to the Exn module.

Copy link
Contributor

Choose a reason for hiding this comment

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

Thanks Paul!

switch JsExn.message(e) {
| Some(msg) => Console.log("JS error thrown: " ++ msg)
| None => Console.log("Some other exception has been thrown")
}
Expand Down
Loading