[whatwg/webidl] Upgrade QuotaExceededError to a DOMException derived interface (PR #1465)

### The proposal

The web platform benefits from having a type of exception that tells you about when you exceed quotas. In some cases, it can be helpful to tell you what the quota was, and by how much you exceeded it. https://github.com/webmachinelearning/writing-assistance-apis/issues/5 gives one specific use case.

The web platform already has an exception type for telling you when you exceed quotas: it is `DOMException`, with the specific `name` property set to `"QuotaExceededError"`. However, this does not allow carrying additional information.

This PR proposes removing `"QuotaExceededError"` from the list of built-in `DOMException` names, and instead creates a class named `QuotaExceededError` that derives from `DOMException` and has the additional optional properties `quota` and `requested`. We propose that all instances of specs that throw `"QuotaExceededError"` `DOMException`s get upgraded to instead throw `QuotaExceededError`s. For now, such specs would leave the `quota` and `requested` properties at their default value of `null`, but they could eventually upgrade to include that data, if it's useful for their use case (and isn't, e.g., a privacy leak).

### Alternative considered

The most promising alternative considered was to add a new class that sits alongside `"QuotaExceededError"` `DOMException`. Maybe it would be called `QuotaExceededErrorWithDetails`, or maybe we could even call it `QuotaExceededError` despite the confusion this might cause. But it would be undesirable for the web platform to have two types of quota-exceeded errors, with different APIs giving different ones. So, because we believe the compat implications are not too bad, we're interested in trying this upgrade route instead.

There are other possibilities, such as using custom bindings to sometimes add properties to base `"QuotaExceededError"` `DOMException` instances, or trying to add some generic additional information capability to the base `DOMException` class. However, these don't fit well with how classes work on the web platform, with getters providing predefined data on a per-class basis. They would be hacky to maintain both in specs and implementations, and a bit surprising for web developers as well due to the mismatch with other web platform classes.

### Compat considerations

The following coding patterns will work unchanged if we upgrade all `"QuotaExceededError"` `DOMException`s to `QuotaExceedError`s:

- `ex instanceof DOMException`
- `ex.name === "QuotaExceededError"`
- `DOMException.QUOTA_EXCEEDED_ERR === 22`
- `(new DOMException("message", "QuotaExceededError")).name === "QuotaExceededError"`

The following coding patterns will start giving different answers:

- `ex.constructor === DOMException`
- `ex.constructor.name === "DOMException"`
- `(new DOMException("message", "QuotaExceededError")).code === DOMException.QUOTA_EXCEEDED_ERR` (now it will be `0`)

We believe that these coding patterns are quite rare. See, for example, [these GitHub search results](https://github.com/search?q=lang%3Ats+OR+lang%3Ajs+%22.constructor+%3D%3D%3D+DOMException%22&type=code), which show only a couple instances of `.constructor` testing (repeated in a few forks).

The tests like `ex instanceof DOMException` and `ex.name === "QuotaExceededError"` are much more common, and commonly seen in documentation. (See, e.g., [these GitHub search results](https://github.com/search?q=lang%3Ats+OR+lang%3Ajs+%22.name+%3D%3D%3D+%5C%22QuotaExceededError%5C%22%22+OR+%22.name+%3D%3D%3D+%27QuotaExceededError%27%22&type=code).)

Furthermore, since quotas being exceeded is a relatively rare thing to happen on the web, we suspect that the combination of these rare coding patterns with this rare type of `DOMException` means the impacted number of page views will be extremely small.

We could add some use counters for these coding patterns, but they would be sloppy. In particular, we could count cases where `.constructor` is accessed, but not cases where it is compared to `DOMException`, so any count would be inflated by generic constructor-accessing code, and not really tell us much about the problematic coding pattern.

Nevertheless, there's definitely some compat risk. So the best rollout plan here would probably be for Chromium to cautiously take the lead and report back if it sticks, before necessarily merging changes to all the relevant specs.

---

Closes #1463.

---

Labeling "do not merge yet" as this is just to see what it would look like and I haven't yet consulted other Chrome team members as to whether we want to go this direction.

If we do go this direction, we'd need to update specs and tests for:

- [ ] https://fs.spec.whatwg.org/
- [ ] https://html.spec.whatwg.org/
- [ ] https://wicg.github.io/handwriting-recognition/
- [ ] https://webmachinelearning.github.io/writing-assistance-apis/
- [ ] https://w3c.github.io/IndexedDB/
- [ ] https://w3c.github.io/media-source/
- [ ] https://w3c.github.io/ServiceWorker/
- [ ] https://w3c.github.io/webcodecs/
- [ ] https://w3c.github.io/webcrypto/
- [ ] https://w3c.github.io/webtransport/

----

<!--
Thank you for contributing to the Web IDL Standard! Please describe the change you are making and complete the checklist below if your change is not editorial.
When editing this comment after the PR is created, check that PR-Preview doesn't overwrite your changes.
If you think your PR is ready to land, please double-check that the build is passing and the checklist is complete before pinging.
-->

- [ ] At least two implementers are interested (and none opposed):
   * …
   * …
- [ ] [Tests](https://github.com/web-platform-tests/wpt) are written and can be reviewed and commented upon at:
   * … <!-- If these tests are tentative, link a PR to make them non-tentative. -->
- [ ] [Implementation bugs](https://github.com/whatwg/meta/blob/main/MAINTAINERS.md#handling-pull-requests) are filed:
   * Chromium: …
   * Gecko: …
   * WebKit: …
   * Deno: …
   * Node.js: …
   * webidl2.js: …
   * widlparser: …
- [ ] [MDN issue](https://github.com/whatwg/meta/blob/main/MAINTAINERS.md#handling-pull-requests) is filed: …
- [ ] The top of this comment includes a [clear commit message](https://github.com/whatwg/meta/blob/main/COMMITTING.md) to use. <!-- If you created this PR from a single commit, Github copied its message. Otherwise, you need to add a commit message yourself. -->

(See [WHATWG Working Mode: Changes](https://whatwg.org/working-mode#changes) for more details.)


<!--
    This comment and the below content is programmatically generated.
    You may add a comma-separated list of anchors you'd like a
    direct link to below (e.g. #idl-serializers, #idl-sequence):

    Don't remove this comment or modify anything below this line.
    If you don't want a preview generated for this pull request,
    just replace the whole of this comment's content by "no preview"
    and remove what's below.
-->
***
<a href="https://whatpr.org/webidl/1465.html" title="Last updated on Jan 27, 2025, 7:45 AM UTC (5e1d7e8)">Preview</a> | <a href="https://whatpr.org/webidl/1465/90b5184...5e1d7e8.html" title="Last updated on Jan 27, 2025, 7:45 AM UTC (5e1d7e8)">Diff</a>
You can view, comment on, or merge this pull request online at:

  https://github.com/whatwg/webidl/pull/1465

-- Commit Summary --

  * Upgrade QuotaExceededError to a DOMException derived interface

-- File Changes --

    M index.bs (144)

-- Patch Links --

https://github.com/whatwg/webidl/pull/1465.patch
https://github.com/whatwg/webidl/pull/1465.diff

-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/webidl/pull/1465
You are receiving this because you are subscribed to this thread.

Message ID: <whatwg/webidl/pull/1465@github.com>