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: See [[#es-creating-throwing-exceptions]] for details on what creating and throwing an exception -entails in the ECMAScript language binding. +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]]. -
Here is are some examples of wording to use to create and throw exceptions. + To throw a new [=simple exception=] whose type is {{TypeError}}:
- [=exception/Throw=] a {{TypeError}}. +- To throw a new {{DOMException}} with [=error name=] "{{NotAllowedError!!exception}}": +[=exception/Throw=] a {{TypeError}}.
To throw a new {{DOMException}} with [=error name=] "{{NotAllowedError}}":
- [=exception/Throw=] a "{{NotAllowedError!!exception}}" {{DOMException}}. +- To create a new {{DOMException}} with [=error name=] "{{SyntaxError!!exception}}": +[=exception/Throw=] an "{{NotAllowedError}}" {{DOMException}}.
To create a new {{DOMException}} with [=error name=] "{{SyntaxError}}":
- Let object be a newly [=created=] "{{SyntaxError!!exception}}" {{DOMException}}. ++ +Let object be a newly [=exception/created=] "{{SyntaxError}}" + {{DOMException}}. +
To [=reject=] a promise with a new {{DOMException}} with [=error name=] "{{OperationError}}": + +
+ [=Reject=] p with an "{{OperationError}}" {{DOMException}}.
An example of including additional information used to construct the [=exception/message=] + would be: -
+ [=exception/Throw=] a "{{SyntaxError}}" {{DOMException}} indicating that the given value + had disallowed trailing spaces. +-The error names table below lists all the allowed error names -for {{DOMException}}, a description, and legacy code values. +
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 [=exception/message=] the + implementation should construct, and so specifying it is not necessary. +
- The {{DOMException}} names marked as deprecated are kept for legacy purposes but their usage is discouraged. -
+The resulting behavior from creating and throwing an exception is language binding-specific. + +See [[#es-creating-throwing-exceptions]] for details on what creating and throwing an +exception entails in the ECMAScript language binding. + + +
Interfaces [=interface/inheriting=] from {{DOMException}}, in the manner described +in [[#idl-DOMException-derived-interfaces]], will have their own names, not listed in this table. -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! +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. + +
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 {{ECMAScript/SyntaxError}}. @@ -5342,6 +5371,94 @@ over just using {{SyntaxError!!exception}} to refer to the {{DOMException}}. [[D +
Error, and must not be any
+ of the names in the [=error 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=] {{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]
+ interface WidgetError : DOMException {
+ constructor(optional DOMString message = "", WidgetErrorOptions options);
+
+ readonly attribute unsigned long long hardwareErrorCode;
+ };
+
+ dictionary WidgetErrorOptions {
+ required [EnforceRange] unsigned long long hardwareErrorCode;
+ };
+
+
+ Every WidgetError instance has a hardware error code,
+ a number.
+
+ new WidgetError(|message|, |options|) constructor steps are:
+
+ 1. Set [=this=]'s [=DOMException/name=] to "WidgetError".
+ 1. Set [=this=]'s [=DOMException/message=] to |message|.
+ 1. Set [=this=]'s [=WidgetError/hardware error code=] to
+ |options|["hardwareErrorCode"].
+ hardwareErrorCode getter steps are to return [=this=]'s
+ [=WidgetError/hardware error code=].
+ WidgetError objects are [=serializable objects=].
+
+ To throw an instance of the WidgetError exemplified
+ above:
+
+
++[=exception/Throw=] a
WidgetErrorwhose [=WidgetError/hardware error code=] + is 42. +