From 5e1d7e892dc503b4c3ec4002fb14d3eb5621587f Mon Sep 17 00:00:00 2001 From: Domenic Denicola Date: Mon, 27 Jan 2025 16:23:46 +0900 Subject: [PATCH] Upgrade QuotaExceededError to a DOMException derived interface Closes #1463. --- index.bs | 144 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 92 insertions(+), 52 deletions(-) diff --git a/index.bs b/index.bs index ab81c07c..1a848e5a 100644 --- a/index.bs +++ b/index.bs @@ -5158,11 +5158,6 @@ over just using {{SyntaxError!!exception}} to refer to the {{DOMException}}. [[D Deprecated. URL_MISMATCH_ERR (21) - - "QuotaExceededError" - The quota has been exceeded. - QUOTA_EXCEEDED_ERR (22) - "TimeoutError" The operation timed out. @@ -5260,70 +5255,114 @@ certain rules, in order to have a predictable shape for developers. Specifically

These requirements mean that the inherited {{DOMException/code}} property of these interfaces will always return 0. -

- The definition for a {{DOMException}} derived interface which carries along an additional - "protocol error code", which is derived from what the server sent over some some hypothetical - network protocol "protocol X", could look something like this: +To [=exception/create=] or [=exception/throw=] a {{DOMException}} derived interface, supply its +[=interface=] [=identifier=] as well as the additional information needed to construct it. - 
-        [Exposed=Window, Serializable]
-        interface ProtocolXError : DOMException {
-          constructor(optional DOMString message = "", ProtocolXErrorOptions options);
+

+    
To throw an instance of {{QuotaExceededError}}:
 
-          readonly attribute unsigned long long errorCode;
-        };
+    

+        
[=exception/Throw=] a {{QuotaExceededError}} whose [=QuotaExceededError/quota=] is 42 and
+        [=QuotaExceededError/requested=] is 50.
+    

+

 
-        dictionary ProtocolXErrorOptions {
-            required [EnforceRange] unsigned long long errorCode;
-        };
-
+

Predefined {{DOMException}} derived interfaces

- Every ProtocolXError instance has an error code, - a number. +This standard so far defines one predefined {{DOMException}} derived interface: -
- The new ProtocolXError(|message|, |options|) constructor steps are: +
+[Exposed=*, Serializable]
+interface QuotaExceededError : DOMException {
+  constructor(optional DOMString message = "", optional QuotaExceededErrorOptions options = {});
 
-        1.  Set [=this=]'s [=DOMException/name=] to "ProtocolXError".
-        1.  Set [=this=]'s [=DOMException/message=] to |message|.
-        1.  Set [=this=]'s [=ProtocolXError/error code=] to |options|["errorCode"].
-
+ readonly attribute double? quota; + readonly attribute double? requested; +}; -
- The errorCode getter steps are to return [=this=]'s - [=ProtocolXError/error code=]. -
+dictionary QuotaExceededErrorOptions { + double quota; + double requested; +}; + - ProtocolXError objects are [=serializable objects=]. +The {{QuotaExceededError}} exception can be thrown when a quota is exceeded. It has two properties +that are optionally present, to give more information to the web developer about their request +compared to the quota value. -
- Their [=serialization steps=], given |value| and |serialized|, are: +

Previous versions of this standard defined "QuotaExceededError" as one +of the base DOMException error names. It +has been upgraded to a full interface to support including such information.

- 1. Run the {{DOMException}} [=serialization steps=] given |value| and |serialized|. - 1. Set |serialized|.\[[ErrorCode]] to |value|'s [=ProtocolXError/error code=]. -
+Every {{QuotaExceededError}} instance has a requested and a +quota, both numbers or null. They are both initially null. + +
+ The new QuotaExceededError(|message|, |options|) + constructor steps are: -
- Their [=deserialization steps=], given |serialized| and |value|, are: + 1. Set [=this=]'s [=DOMException/name=] to "QuotaExceededError". - 1. Run the {{DOMException}} [=deserialization steps=] given |serialized| and |value|. - 1. Set |value|'s [=ProtocolXError/error code=] to |serialized|.\[[ErrorCode]]. -
+ 1. Set [=this=]'s [=DOMException/message=] to |message|. + + 1. If |options|["{{QuotaExceededErrorOptions/quota}}"] is present, then: + + 1. If |options|["{{QuotaExceededErrorOptions/quota}}"] is less than 0, then throw a + {{RangeError}}. + + 1. Set [=this=]'s [=QuotaExceededError/quota=] to + |options|["{{QuotaExceededErrorOptions/quota}}"]. + + 1. If |options|["{{QuotaExceededErrorOptions/requested}}"] is present, then: + + 1. If |options|["{{QuotaExceededErrorOptions/requested}}"] is less than 0, then throw a + {{RangeError}}. + + 1. Set [=this=]'s [=QuotaExceededError/requested=] to + |options|["{{QuotaExceededErrorOptions/requested}}"]. + + 1. If [=this=]'s [=QuotaExceededError/quota=] is not null, [=this=]'s [=QuotaExceededError/requested=] is not null, + and [=this=]'s [=QuotaExceededError/requested=] is less than [=this=]'s [=QuotaExceededError/quota=], then + throw a {{RangeError}}.
-To [=exception/create=] or [=exception/throw=] a {{DOMException}} derived interface, supply its -[=interface=] [=identifier=] as well as the additional information needed to construct it. +The quota getter steps are to return [=this=]'s +[=QuotaExceededError/quota=]. -
-

To throw an instance of the ProtocolXError exemplified - above: +The requested getter steps are to return [=this=]'s +[=QuotaExceededError/requested=]. -

-

[=exception/Throw=] a ProtocolXError whose [=ProtocolXError/error code=] - is 42. -

+
+ +{{QuotaExceededError}} objects are [=serializable objects=]. + +
+ Their [=serialization steps=], given |value| and |serialized|, are: + + 1. Run the {{DOMException}} [=serialization steps=] given |value| and |serialized|. + + 1. Set |serialized|.\[[Quota]] to |value|'s [=QuotaExceededError/quota=]. + + 1. Set |serialized|.\[[Requested]] to |value|'s [=QuotaExceededError/requested=].
+
+ Their [=deserialization steps=], given |serialized| and |value|, are: + + 1. Run the {{DOMException}} [=deserialization steps=] given |serialized| and |value|. + + 1. Set |value|'s [=QuotaExceededError/quota=] to |serialized|.\[[Quota]]. + + 1. Set |value|'s [=QuotaExceededError/requested=] to |serialized|.\[[Requested]]. +
+ +
+ +Specifications that [=exception/create=] or [=exception/throw=] a {{QuotaExceededError}} must not +provide a [=QuotaExceededError/requested=] and [=QuotaExceededError/quota=] that are both non-null +and where [=QuotaExceededError/requested=] is less than [=QuotaExceededError/quota=]. + +

Enumerations

An enumeration is a definition (matching @@ -6651,7 +6690,8 @@ There is no way to represent a constant observable array value in IDL. 1. If |employee| is not allowed to enter the building today, then throw a "{{NotAllowedError}}" {{DOMException}}. - 1. If |index| is greater than 200, then throw a "{{QuotaExceededError}}" {{DOMException}}. + 1. If |index| is greater than or equal to 200, then throw a {{QuotaExceededError}} whose + [=QuotaExceededError/quota=] is 200 and [=QuotaExceededError/requested=] is |index|. 1. Put |employee| to work! The [=observable array attribute/delete an indexed value=] algorithm for