Upgrade QuotaExceededError to a DOMException derived interface

[domenic]

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. webmachinelearning/writing-assistance-apis#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" DOMExceptions get upgraded to instead throw QuotaExceededErrors. 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" DOMExceptions to QuotaExceedErrors:

• ex instanceof DOMException
• ex.name === "QuotaExceededError"
• DOMException.QUOTA_EXCEEDED_ERR === 22
• (new DOMException("message", "QuotaExceededError")).name === "QuotaExceededError"
• (new DOMException("message", "QuotaExceededError")).code === DOMException.QUOTA_EXCEEDED_ERR
• ex.code === DOMException.QUOTA_EXCEEDED_ERR
• ex.code === 22

The following coding patterns will start giving different answers:

• ex.constructor === DOMException
• ex.constructor.name === "DOMException"

We believe that these coding patterns are quite rare. See, for example, these GitHub search results, 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.)

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.

---

Proposed commit message:

Upgrade QuotaExceededError to a DOMException derived interface

Closes #1463.

---

Labeling "do not merge yet" as we should also create PRs for these specs, and we probably don't want to merge until we see if this sticks in Chromium:

• https://fs.spec.whatwg.org/: Update QuotaExceededError usage fs#171
• https://html.spec.whatwg.org/: Update QuotaExceededError usage html#11440
• https://wicg.github.io/handwriting-recognition/: Update QuotaExceededError usage WICG/handwriting-recognition#38
• https://webmachinelearning.github.io/writing-assistance-apis/: Update QuotaExceededError references webmachinelearning/writing-assistance-apis#72
• https://w3c.github.io/IndexedDB/: Update QuotaExceededError usage w3c/IndexedDB#463
• https://w3c.github.io/ServiceWorker/: Update QuotaExceededError usage w3c/ServiceWorker#1782
• https://w3c.github.io/webcodecs/: Update QuotaExceededError usage w3c/webcodecs#898

The following cases did not need PRs because they were using inaccurate spec text (just QuotaExceededError, instead of "QuotaExceededError" DOMException), which has now become correct by accident:

• https://w3c.github.io/media-source/
• https://w3c.github.io/webcrypto/
• https://w3c.github.io/webtransport/

---

• At least two implementers are interested (and none opposed):
  • Chromium
  • Gecko is supportive if Chromium finds the compat risk to be reasonable, per 2025-02-06 WHATNOT meeting
• Tests are written and can be reviewed and commented upon at:
  • Update QuotaExceededError expectations web-platform-tests/wpt#53645
• Implementation bugs are filed:
  • Chromium: https://issues.chromium.org/issues/406162261
  • Gecko: https://bugzilla.mozilla.org/show_bug.cgi?id=1976159
  • WebKit: https://bugs.webkit.org/show_bug.cgi?id=295570
  • Deno: Update QuotaExceededError handling denoland/deno#30028
  • Node.js: Update QuotaExceededError handling nodejs/node#58987
  • webidl2.js: N/A
  • widlparser: N/A
• MDN issue is filed: Upgrade QuotaExceededError to a DOMException derived interface #1465
• The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

---

Preview | Diff

[annevk]

I think the specification and tests should reflect not regressing code. If Chromium wants to wait with complying with that until someone else ships this I suppose that's fine.

[annevk]

Thanks!