The addBookmark() example violates this guide's own advice

[mislav]

The guide advises “Rejections Should Be Used for Exceptional Situations”.

However, the addBookmark() example suggests using promise rejections to signal that a user decided not to save a bookmark:

If the end-user aborts the request to add the bookmark (e.g., they hit escape, or press a "cancel" button), reject promise with a new DOMException whose name is "AbortError".

A user choosing "cancel" from a "Save/cancel" dialog in their browser is not an exceptional situation. A better implementation of this use-case would be that the promise was resolved in both cases and that the resolved value is a boolean indicating whether the user has accepted saving the bookmark or not.

The downside of this approach is that this example then stops being a demonstration of how to use rejected promises. I think an example for that should better follow this document's own guidelines.

[domenic]

This is a good question. I want to push back a little and see what you think. But in the end you might be right that just overhauling the example to remove ambiguity would be better.

Part of this is in the name. The name is not requestBookmark() or tryBookmark(). It's addBookmark(). A function called "add bookmark" that fails to add a bookmark seems like an exceptional failure condition.

Maybe the guidance here should be more subtle. E.g., you should not name your functions things like "add bookmark," because that doesn't really reflect how the world works (users have to give permission).