Skip to content

Commit 48eba6d

Browse files
domenicdomenic
authored
Upgrade QuotaExceededError to a DOMException derived interface
Closes #1463.
1 parent da6f3b3 commit 48eba6d

File tree

1 file changed

+100
-50
lines changed

1 file changed

+100
-50
lines changed

‎index.bs‎

Lines changed: 100 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -5191,9 +5191,9 @@ over just using {{SyntaxError!!exception}} to refer to the {{DOMException}}. [[D
51915191
<td><strong>Deprecated.</strong></td>
51925192
<td><dfn id="dom-domexception-url_mismatch_err" for="DOMException" const export><code>URL_MISMATCH_ERR</code></dfn>&nbsp;(21)</td>
51935193
</tr>
5194-
<tr>
5195-
<td>"<dfn id="quotaexceedederror" exception export><code>QuotaExceededError</code></dfn>"</td>
5196-
<td>The quota has been exceeded.</td>
5194+
<tr class="deprecated">
5195+
<td>"<code>QuotaExceededError</code>"</td>
5196+
<td><strong>Deprecated.</strong> Use the {{QuotaExceededError}} {{DOMException}}-derived interface instead.</td>
51975197
<td><dfn id="dom-domexception-quota_exceeded_err" for="DOMException" const export><code>QUOTA_EXCEEDED_ERR</code></dfn>&nbsp;(22)</td>
51985198
</tr>
51995199
<tr>
@@ -5293,70 +5293,119 @@ certain rules, in order to have a predictable shape for developers. Specifically
52935293
<p class=note>These requirements mean that the inherited {{DOMException/code}} property of these
52945294
interfaces will always return 0.
52955295

5296-
<div class=example id=example-domexception-derived-interface>
5297-
The definition for a {{DOMException}} derived interface which carries along an additional
5298-
"protocol error code", which is derived from what the server sent over some some hypothetical
5299-
network protocol "protocol X", could look something like this:
5296+
To [=exception/create=] or [=exception/throw=] a {{DOMException}} derived interface, supply its
5297+
[=interface=] [=identifier=] as well as the additional information needed to construct it.
53005298

5301-
<pre highlight=webidl>
5302-
[Exposed=Window, Serializable]
5303-
interface ProtocolXError : DOMException {
5304-
constructor(optional DOMString message = "", ProtocolXErrorOptions options);
5299+
<div class=example id=example-domexception-derived-throwing>
5300+
<p>To throw an instance of {{QuotaExceededError}}:
53055301

5306-
readonly attribute unsigned long long errorCode;
5307-
};
5302+
<blockquote>
5303+
<p>[=exception/Throw=] a {{QuotaExceededError}} whose [=QuotaExceededError/quota=] is 42 and
5304+
[=QuotaExceededError/requested=] is 50.
5305+
</blockquote>
5306+
</div>
53085307

5309-
dictionary ProtocolXErrorOptions {
5310-
required [EnforceRange] unsigned long long errorCode;
5311-
};
5312-
</pre>
5308+
<h4 id="idl-DOMException-derived-predefineds" oldids="example-domexception-derived-interface">Predefined {{DOMException}} derived interfaces</h4>
53135309

5314-
Every <code>ProtocolXError</code> instance has an <dfn for="ProtocolXError">error code</dfn>,
5315-
a number.
5310+
This standard so far defines one predefined {{DOMException}} derived interface:
53165311

5317-
<div algorithm="ProtocolXError constructor">
5318-
The <b><code>new ProtocolXError(|message|, |options|)</code></b> constructor steps are:
5312+
<pre class=idl>
5313+
[Exposed=*, Serializable]
5314+
interface QuotaExceededError : DOMException {
5315+
constructor(optional DOMString message = "", optional QuotaExceededErrorOptions options = {});
53195316

5320-
1. Set [=this=]'s [=DOMException/name=] to "<code>ProtocolXError</code>".
5321-
1. Set [=this=]'s [=DOMException/message=] to |message|.
5322-
1. Set [=this=]'s [=ProtocolXError/error code=] to |options|["<code>errorCode</code>"].
5323-
</div>
5317+
readonly attribute double? quota;
5318+
readonly attribute double? requested;
5319+
};
53245320

5325-
<div algorithm="ProtocolXError errorCode">
5326-
The <b><code>errorCode</code></b> getter steps are to return [=this=]'s
5327-
[=ProtocolXError/error code=].
5328-
</div>
5321+
dictionary QuotaExceededErrorOptions {
5322+
double quota;
5323+
double requested;
5324+
};
5325+
</pre>
53295326

5330-
<code>ProtocolXError</code> objects are [=serializable objects=].
5327+
The {{QuotaExceededError}} exception can be thrown when a quota is exceeded. It has two properties
5328+
that are optionally present, to give more information to the web developer about their request
5329+
compared to the quota value.
53315330

5332-
<div algorithm="ProtocolXError serialization steps">
5333-
Their [=serialization steps=], given |value| and |serialized|, are:
5331+
<p class="note">Previous versions of this standard defined "<code>QuotaExceededError</code>" as one
5332+
of the <a href="#idl-DOMException-error-names">base <code>DOMException</code> error names</a>. It
5333+
has been upgraded to a full interface to support including such information.</p>
53345334

5335-
1. Run the {{DOMException}} [=serialization steps=] given |value| and |serialized|.
5336-
1. Set |serialized|.\[[ErrorCode]] to |value|'s [=ProtocolXError/error code=].
5337-
</div>
5335+
Every {{QuotaExceededError}} instance has a <dfn export for="QuotaExceededError">requested</dfn> and
5336+
a <dfn export for="QuotaExceededError">quota</dfn>, both numbers or null. They are both initially
5337+
null.
5338+
5339+
<div algorithm>
5340+
The <dfn constructor for="QuotaExceededError" lt="QuotaExceededError(message, options)">new QuotaExceededError(|message|, |options|)</dfn>
5341+
constructor steps are:
53385342

5339-
<div algorithm="ProtocolXError deserialization steps">
5340-
Their [=deserialization steps=], given |serialized| and |value|, are:
5343+
1. Set [=this=]'s [=DOMException/name=] to "<code>QuotaExceededError</code>".
53415344

5342-
1. Run the {{DOMException}} [=deserialization steps=] given |serialized| and |value|.
5343-
1. Set |value|'s [=ProtocolXError/error code=] to |serialized|.\[[ErrorCode]].
5344-
</div>
5345+
1. Set [=this=]'s [=DOMException/message=] to |message|.
5346+
5347+
1. If |options|["{{QuotaExceededErrorOptions/quota}}"] is present:
5348+
5349+
1. If |options|["{{QuotaExceededErrorOptions/quota}}"] is less than 0, then throw a
5350+
{{RangeError}}.
5351+
5352+
1. Set [=this=]'s [=QuotaExceededError/quota=] to
5353+
|options|["{{QuotaExceededErrorOptions/quota}}"].
5354+
5355+
1. If |options|["{{QuotaExceededErrorOptions/requested}}"] is present:
5356+
5357+
1. If |options|["{{QuotaExceededErrorOptions/requested}}"] is less than 0, then throw a
5358+
{{RangeError}}.
5359+
5360+
1. Set [=this=]'s [=QuotaExceededError/requested=] to
5361+
|options|["{{QuotaExceededErrorOptions/requested}}"].
5362+
5363+
1. If [=this=]'s [=QuotaExceededError/quota=] is not null, [=this=]'s [=QuotaExceededError/requested=] is not null,
5364+
and [=this=]'s [=QuotaExceededError/requested=] is less than [=this=]'s [=QuotaExceededError/quota=], then
5365+
throw a {{RangeError}}.
53455366
</div>
53465367

5347-
To [=exception/create=] or [=exception/throw=] a {{DOMException}} derived interface, supply its
5348-
[=interface=] [=identifier=] as well as the additional information needed to construct it.
5368+
The <dfn attribute for="QuotaExceededError">quota</dfn> getter steps are to return [=this=]'s
5369+
[=QuotaExceededError/quota=].
53495370

5350-
<div class=example id=example-domexception-derived-throwing>
5351-
<p>To throw an instance of the <code>ProtocolXError</code> exemplified
5352-
<a href=#example-domexception-derived-interface>above</a>:
5371+
The <dfn attribute for="QuotaExceededError">requested</dfn> getter steps are to return [=this=]'s
5372+
[=QuotaExceededError/requested=].
53535373

5354-
<blockquote>
5355-
<p>[=exception/Throw=] a <code>ProtocolXError</code> whose [=ProtocolXError/error code=]
5356-
is 42.
5357-
</blockquote>
5374+
<p class="note">The {{QuotaExceededError}} interface inherits the {{DOMException}} interface's {{DOMException/code}}
5375+
getter, which will always return 22. However, relying on this value is discouraged (for both {{QuotaExceededError}} and
5376+
{{DOMException}}); it is better to use the {{DOMException/name}} getter.
5377+
5378+
<hr>
5379+
5380+
{{QuotaExceededError}} objects are [=serializable objects=].
5381+
5382+
<div algorithm="QuotaExceededError serialization steps">
5383+
Their [=serialization steps=], given |value| and |serialized|, are:
5384+
5385+
1. Run the {{DOMException}} [=serialization steps=] given |value| and |serialized|.
5386+
5387+
1. Set |serialized|.\[[Quota]] to |value|'s [=QuotaExceededError/quota=].
5388+
5389+
1. Set |serialized|.\[[Requested]] to |value|'s [=QuotaExceededError/requested=].
5390+
</div>
5391+
5392+
<div algorithm="QuotaExceededError deserialization steps">
5393+
Their [=deserialization steps=], given |serialized| and |value|, are:
5394+
5395+
1. Run the {{DOMException}} [=deserialization steps=] given |serialized| and |value|.
5396+
5397+
1. Set |value|'s [=QuotaExceededError/quota=] to |serialized|.\[[Quota]].
5398+
5399+
1. Set |value|'s [=QuotaExceededError/requested=] to |serialized|.\[[Requested]].
53585400
</div>
53595401

5402+
<hr>
5403+
5404+
Specifications that [=exception/create=] or [=exception/throw=] a {{QuotaExceededError}} must not
5405+
provide a [=QuotaExceededError/requested=] and [=QuotaExceededError/quota=] that are both non-null
5406+
and where [=QuotaExceededError/requested=] is less than [=QuotaExceededError/quota=].
5407+
5408+
53605409
<h3 id="idl-enums">Enumerations</h3>
53615410

53625411
An <dfn id="dfn-enumeration" export>enumeration</dfn> is a definition (matching
@@ -6713,7 +6762,8 @@ There is no way to represent a constant observable array value in IDL.
67136762

67146763
1. If |employee| is not allowed to enter the building today, then throw a
67156764
"{{NotAllowedError}}" {{DOMException}}.
6716-
1. If |index| is greater than 200, then throw a "{{QuotaExceededError}}" {{DOMException}}.
6765+
1. If |index| is greater than or equal to 200, then throw a {{QuotaExceededError}} whose
6766+
[=QuotaExceededError/quota=] is 200 and [=QuotaExceededError/requested=] is |index|.
67176767
1. Put |employee| to work!
67186768

67196769
The [=observable array attribute/delete an indexed value=] algorithm for

0 commit comments

Comments
 (0)