NodeList interface
+ Issue(whatwg/webidl#698): It is unclear whether the NodeList interface
object would implement a \[[Construct]] internal method. In any case, trying to use it as a
constructor will cause a {{TypeError}} to be thrown.
@@ -3927,7 +3927,7 @@ Prose accompanying an [=interface=] with a [=pair iterator=] must define a [=/li
or (b) with a forEach method that instead invokes its callback like
Set.prototype.forEach (where the key is the same as the value).
If you're creating an API that needs such a forEach method, please
- file an issue.
+ file an issue.
@@ -4117,7 +4117,7 @@ async iterator's return() method is invoked. This most commonly occ
We could add a similar hook for throw(). So far there has been no need,
but if you are creating an API that needs such capabilities, please
-file an issue.
+file an issue.
The prose may also define asynchronous iterator initialization steps. These
receive the instance of the [=interface=] being iterated, the newly-created iterator object, and a
@@ -4898,21 +4898,14 @@ No [=extended attributes=] are applicable to dictionaries.
DOMException names table below.
-For [=simple exceptions=], the [=error name=] is the type of the exception.
-For a {{DOMException}}, the [=error name=] must be one of the names
-listed in the [=error names table=] below.
-The table also indicates the {{DOMException}}'s integer code for that error name,
-if it has one.
+As {{DOMException}} is an [=interface type=], it can be used as a type in IDL. This +allows for example an [=operation=] to be declared to have a {{DOMException}} [=return type=]. This +is generally a bad pattern, however, as exceptions are meant to be thrown and not returned. -Note: As {{DOMException}} is an [=interface type=], it can be used as a type in IDL. -This allows for example an [=operation=] -to be declared to have a {{DOMException}} -[=return type=]. +The final kind of exception is a derived interface of {{DOMException}}. These are more complicated, +and thus described in the dedicated section [[#idl-DOMException-derived-interfaces]]. -[=Simple exceptions=] can be created -by providing their [=error name=]. -A {{DOMException}} can be [=created=] -by providing its [=error name=] followed by {{DOMException}}. -Exceptions can also be thrown, by providing the -same details required to [=created|create=] one. +[=Simple exceptions=] can be +created by providing their +type name. A {{DOMException}} can be [=exception/created=] by providing its [=DOMException/name=] +followed by {{DOMException}}. Exceptions can also be +thrown, by providing the same details +required to [=exception/create=] one. In both cases, the caller may provide additional information +about what the exception indicates, which is useful when constructing the exception's message. -The resulting behavior from creating and throwing an exception is language binding-specific. +
Here is are some examples of wording to use to create and throw exceptions. + To throw a new [=simple exception=] whose type is {{TypeError}}: -Note: See [[#es-creating-throwing-exceptions]] for details on what creating and throwing an exception -entails in the ECMAScript language binding. +
+-[=exception/Throw=] a {{TypeError}}. +
To throw a new {{DOMException}} with [=DOMException/name=] "{{NotAllowedError}}": - Here is are some examples of wording to use to create and throw exceptions. - To throw a new [=simple exception=] named {{TypeError}}: +
++ +[=exception/Throw=] a "{{NotAllowedError}}" {{DOMException}}. +
To create a new {{DOMException}} with [=DOMException/name=] "{{SyntaxError}}":
- [=exception/Throw=] a {{TypeError}}. +- To throw a new {{DOMException}} with [=error name=] "{{NotAllowedError!!exception}}": +Let object be a newly [=exception/created=] "{{SyntaxError}}" + {{DOMException}}.
To [=reject=] a promise with a new {{DOMException}} with [=DOMException/name=] + "{{OperationError}}":
- [=exception/Throw=] a "{{NotAllowedError!!exception}}" {{DOMException}}. + [=Reject=] p with an "{{OperationError}}" {{DOMException}}.+
An example of including additional information used to construct the exception message would + be:
- Let object be a newly [=created=] "{{SyntaxError!!exception}}" {{DOMException}}. + [=exception/Throw=] a "{{SyntaxError}}" {{DOMException}} indicating that the given value + had disallowed trailing spaces.+ +
Such additional context is most helpful to implementers when it is not immediately obvious + why the exception is being thrown, e.g., because there are many different steps in the algorithm + which throw a "{{SyntaxError}}" {{DOMException}}. In contrast, if your specification throws a + "{{NotAllowedError}}" {{DOMException}} immediately after checking if the user has provided + permission to use a given feature, it's fairly obvious what sort of message the implementation + ought to construct, and so specifying it is not necessary.
See [[#es-creating-throwing-exceptions]] for details on what creating and throwing an +exception entails in the ECMAScript language binding. -The error names table below lists all the allowed error names -for {{DOMException}}, a description, and legacy code values. -
- The {{DOMException}} names marked as deprecated are kept for legacy purposes but their usage is discouraged. -
+DOMException names table below lists all the
+allowed [=DOMException/names=] for instances of the base {{DOMException}} interface, along with a
+description of what such names mean, and legacy numeric error code values.
+
+Interfaces [=interface/inheriting=] from {{DOMException}}, in the manner described +in [[#idl-DOMException-derived-interfaces]], will have their own names, not listed in this table. + +When [=exception/creating=] or [=exception/throwing=] a {{DOMException}}, specifications must use +one of these names. If a specification author believes none of these names are a good fit for their +case, they must +file an issue +to discuss adding a new name to the shared namespace, so that the community can coordinate such +efforts. Note that adding new use-case-specific names is only important if you believe web +developers will discriminate multiple error conditions arising from a single API. -Note: If an error name is not listed here, please file a bug as indicated at the top of this specification and it will be addressed shortly. Thanks! +
The {{DOMException}} names marked as deprecated are kept for legacy purposes, but
+their usage is discouraged.
Note: Don't confuse the "{{SyntaxError!!exception}}" {{DOMException}} defined here
with ECMAScript's
Error, and must not be any
+ of the names in the DOMException names table.
+* The [=interface=] must have a [=constructor operation=] which sets the instance's
+ [=DOMException/name=] to the interface's [=identifier=].
+* Their [=constructor operation=] must take as its first parameter an [=optional argument|optional=]
+ {{DOMString}} named |message| defaulting to the empty string, and must set the instance's
+ [=DOMException/message=] to |message|.
+* Their [=constructor operation=] should take as its second parameter a [=dictionary=] containing
+ the additional information that needs to be exposed.
+* They should have [=read only=] [=attributes=], whose names are the same as the members of the
+ constructor dictionary, which return the values accepted by the constructor operation.
+* They should be [=serializable objects=], whose [=serialization steps=] and
+ [=deserialization steps=] preserve the additional information.
+
+These requirements mean that the inherited {{DOMException/code}} property of these +interfaces will always return 0. + +
+ [Exposed=Window, Serializable]
+ interface ProtocolXError : DOMException {
+ constructor(optional DOMString message = "", ProtocolXErrorOptions options);
+
+ readonly attribute unsigned long long errorCode;
+ };
+
+ dictionary ProtocolXErrorOptions {
+ required [EnforceRange] unsigned long long errorCode;
+ };
+
+
+ Every ProtocolXError instance has an error code,
+ a number.
+
+ new ProtocolXError(|message|, |options|) constructor steps are:
+
+ 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"].
+ errorCode getter steps are to return [=this=]'s
+ [=ProtocolXError/error code=].
+ ProtocolXError objects are [=serializable objects=].
+
+ To throw an instance of the ProtocolXError exemplified
+ above:
+
+
++[=exception/Throw=] a
ProtocolXErrorwhose [=ProtocolXError/error code=] + is 42. +
DOMException names table.
+
+ 1. Let |ex| be a [=new=] {{DOMException}} created in the [=current realm=].
+
+ 1. Set |ex|'s [=DOMException/name=] to |name|.
+
+ 1. Set |ex|'s [=DOMException/message=] to an [=implementation-defined=] message appropriate for
+ the exceptional situation. The calling specification may contain information to to help
+ implementations construct this message.
+
+ Implementations need to be cautious not to leak sensitive or secured information when
+ constructing this message, e.g., by including the URL of a cross-origin frame, or
+ information which could identify the user.
+
+ 1. Return |ex|.
+new DOMException(|message|, |name|)
@@ -14429,8 +14569,8 @@ The message getter steps ar
return [=this=]'s [=DOMException/message=].
The code getter steps are to return the legacy
-code indicated in the [=error names table=] for [=this=]'s [=DOMException/name=], or 0 if no such
-entry exists in the table.
+code indicated in the DOMException names table for [=this=]'s
+[=DOMException/name=], or 0 if no such entry exists in the table.
{{DOMException}} objects are [=serializable objects=].
@@ -14502,7 +14642,7 @@ It is strongly discouraged to use legacy Web IDL constructs in specifications
unless required to specify the behavior of legacy Web platform features,
or for consistency with such features.
Editors who wish to use legacy Web IDL constructs are strongly advised to discuss this
-by filing an issue
+by filing an issue
before proceeding.
Marking a construct as legacy does not, in itself,