Document the new exception API #1046
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
Deploying rescript-lang-org with
|
| Latest commit: |
b757c51
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://fd92a308.rescript-lang.pages.dev |
| Branch Preview URL: | https://update-exceptions.rescript-lang.pages.dev |
| @@ -434,6 +420,36 @@ try { | |||
| } | |||
| ``` | |||
|
|
|||
| ### Throw a value that is not an error | |||
|
|
|||
| For some reason, if you need to throw something that is not a JS error, use `JsExn.throw`: | |||
There was a problem hiding this comment.
If you want to throw any value that is not a valid JS Error, use JsExn.throw:
There was a problem hiding this comment.
Thank you very much for tackling this.
I can't deny that it is still a very confusing area of the language.
Could you also link to the Promise API docs in async-await.mdx?
The example of what to do with Promise.catch on https://rescript-langorg-git-update-exceptions-rescript-association.vercel.app/docs/manual/v12.0.0/api/core/promise#value-catch is out of sync I think.
| } | ||
|
|
||
| let checkAuth = async () => { | ||
| try { | ||
| await authenticate() | ||
| } catch { | ||
| | Exn.Error(e) => | ||
| switch Exn.message(e) { | ||
| | JsExn(e) => |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
I just updated this page so it stays in sync with the new API, I think this could be improved in another PR.
| } | ||
|
|
||
| let checkAuth = async () => { | ||
| switch await authenticate() { | ||
| | _ => Console.log("ok") | ||
| | exception Exn.Error(e) => | ||
| switch Exn.message(e) { | ||
| | exception JsExn(e) => |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
This is already covered in the exceptions page, I fear we would repeat ourselves too much otherwise.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@nojaf you're totally right, I'd just change this a subsequent PR, I just replaced the calls to the Exn module.
| @@ -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.") | |||
There was a problem hiding this comment.
Are JsError and JsExn the same thing?
There was a problem hiding this comment.
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.
Well, I really tried my best but I think the previous situation was even worse, but of course we're open to any idea that could further improve the situation!
I didn't specifically update the
The Stdlib/Core API hasn't been synced for ages, as soon as this (#981) is done, it will be corrected since the docstring is fixed already. |
Fixes #1032.