index.bs

<pre class="metadata">
Group: WHATWG
H1: Web IDL
Shortname: webidl
Text Macro: TWITTER webidl
Text Macro: LATESTRD 2025-03
Abstract: This standard defines an interface definition language, Web IDL, that can be used to describe interfaces that
Abstract: are intended to be implemented in web browsers.
Translation: ja https://triple-underscore.github.io/WebIDL-ja.html
Translation: zh-Hans https://htmlspecs.com/webidl/
Complain About: accidental-2119 no
</pre>

<pre class="link-defaults">
spec: infra; type: dfn;
    text: code unit
    text: list
spec: ecmascript; type: dfn;
    for: ECMAScript;
        text: constructor
        text: realm
spec: dom; type: dfn; text: element
</pre>

<pre class="anchors">
urlPrefix: https://tc39.es/ecma262/; spec: ecmascript
    type: method; for: ECMAScript
        text: JSON.stringify(); url: sec-json.stringify
        text: %Array.prototype.entries%; url: sec-array.prototype.entries
        text: %Array.prototype.forEach%; url: sec-array.prototype.foreach
        text: %Array.prototype.keys%; url: sec-array.prototype.keys
        text: %Array.prototype.values%; url: sec-array.prototype.values
        text: %Promise.reject%; url: sec-promise.reject
        text: %Promise.prototype.then%; url: sec-promise.prototype.then
    type: argument
        text: NewTarget; url: sec-built-in-function-objects
    type: abstract-op
        text: CreateAsyncFromSyncIterator; url: sec-createasyncfromsynciterator
        text: Completion; url: sec-completion-record-specification-type
        text: IsInteger; url: sec-isinteger
        text: abs; url: eqn-abs
        text: floor; url: eqn-floor
        text: max; url: eqn-max
        text: min; url: eqn-min
    type: dfn;
        text: Abstract Closure; url: sec-abstract-closure
        text: NumericLiteral; url: sec-literals-numeric-literals
        text: modulo; url: eqn-modulo
        url: sec-returnifabrupt-shorthands
            text: !
            text: ?
        text: ECMA-262 Immutable Prototype Exotic Objects; url: sec-immutable-prototype-exotic-objects
        text: abrupt completion; url: sec-completion-record-specification-type
        text: array iterator object; url: sec-array-iterator-objects
        text: built-in function object; url: sec-built-in-function-objects
        text: callable; for: ECMAScript; url: sec-iscallable
        text: Completion Record; url: sec-completion-record-specification-type
        text: conventions; for: ECMAScript; url: sec-algorithm-conventions
        text: current realm; url: current-realm
        text: element; for: ECMAScript String; url: sec-ecmascript-language-types-string-type
        text: enumerable; url: sec-property-attributes
        text: equally close values; url: sec-ecmascript-language-types-number-type
        text: error objects; for: ECMAScript; url: sec-error-objects
        url: sec-object-internal-methods-and-internal-slots
            text: internal method
            text: internal slot
        for: ordinary object; url: sec-ordinary-object-internal-methods-and-internal-slots
            text: internal method
            text: internal slot
        text: own property; url: sec-own-property
        text: PromiseCapability; url: sec-promisecapability-records
        text: Iterator Record; url: sec-iterator-records
        text: element size; url: table-the-typedarray-constructors
        text: string object; url: sec-string-objects
        url: sec-ecmascript-language-types-bigint-type
            text: is a BigInt
            text: is not a BigInt
        url: sec-ecmascript-language-types-boolean-type
            text: is a Boolean
            text: is not a Boolean
        url: sec-ecmascript-language-types-number-type
            text: is a Number
            text: is not a Number
        url: sec-ecmascript-language-types-string-type
            text: is a String
            text: is not a String
        url: sec-ecmascript-language-types-symbol-type
            text: is a Symbol
            text: is not a Symbol
        url: sec-object-type
            text: is an Object
            text: is not an Object
urlPrefix: https://tc39.es/proposal-resizablearraybuffer/; spec: RESIZABLE-BUFFERS-PROPOSAL
    type: abstract-op
        text: IsResizableArrayBuffer; url: sec-isresizablearraybuffer
</pre>

<pre class=biblio>
{
    "PROPOSAL-FLOAT16ARRAY": {
        "publisher": "Ecma",
        "href": "https://tc39.es/proposal-float16array/",
        "title": "Proposal to add float16 TypedArrays to JavaScript"
    }
}
</pre>

<style>
        pre.set {
          font-size: 80%;
        }

        .syntax .n,
        .syntax .nv {
          font-style: italic;
        }

        .mute,
        .deprecated,
        .deprecated a,
        .deprecated code {
          color: #9D937D;
        }

        .deprecated a:visited,
        .deprecated a {
            border-bottom-color: #9D937D;
        }

        emu-const {
            font-family: sans-serif;
        }

        emu-val {
            font-weight: bold;
        }

        emu-nt {
            font-family: sans-serif;
            font-style: italic;
            white-space: nowrap;
        }

        emu-t {
            font-family: Menlo, Consolas, "DejaVu Sans Mono", Monaco, monospace;
            font-weight: bold;
            white-space: nowrap;
        }

        emu-t.regex {
            font-family: sans-serif;
            font-weight: bold;
        }

        emu-t a[href],
        emu-nt a[href] {
            color: inherit;
            border-bottom: 1px solid transparent;
        }

        emu-t a[href]:focus,
        emu-nt a[href]:focus,
        emu-t a[href]:hover,
        emu-nt a[href]:hover {
            background: #f8f8f8;
            background: rgba(75%, 75%, 75%, .25);
            border-bottom: 3px solid #707070;
            margin-bottom: -2px;
        }

        /* start bug fix, see: https://github.com/tobie/webidl/issues/24 */
        pre.grammar {
            padding-bottom: 1px
        }
        /* end bug fix */

        dt p {
            display: inline;
        }

        #distinguishable-table {
          font-size: 80%;
          border-collapse: collapse;
          width: auto;
        }

        #distinguishable-table th {
          text-align: right;
        }

        #distinguishable-table thead th {
          white-space: nowrap;
          text-align: left;
          border: none;
          height: 100px;
          padding: 0;
        }

        #distinguishable-table .belowdiagonal {
          background: #ddd;
        }

        #distinguishable-table td {
          text-align: center;
          padding: 5px 10px;
          width: 30px;
          min-width: 30px;
          padding: 10px 5px;
          height: 19px
        }

        /* Firefox needs the extra DIV for some reason, otherwise the text disappears if you rotate */
        #distinguishable-table tr:first-child th div {
          transform: translate(27px, 64px) rotate(315deg);
          width: 30px;
        }

        #distinguishable-table thead th div span {
          border-bottom: 1px solid #ccc;
          padding: 5px 10px;
          display: block;
          min-width: 120px;
          text-align: left
        }

        #distinguishable-table thead th:last-child div span {
          border-bottom: none;
        }
</style>


<h2 id="introduction">Introduction</h2>

<i>This section is informative.</i>

This standard defines an interface definition language, Web IDL, that can be used to describe
interfaces that are intended to be implemented in web browsers. Web IDL is an IDL variant with a
number of features that allow the behavior of common script objects in the web platform to be
specified more readily. How interfaces described with Web IDL correspond to constructs within
JavaScript execution environments is also detailed here.

Concretely, Web IDL provides a syntax for specifying the surface APIs of web platform objects, as
well as JavaScript bindings that detail how those APIs manifest as JavaScript constructs. This
ensures common tasks, such as installing global properties, processing numeric inputs, or exposing
iteration behavior, remain uniform across web platform specifications: such specifications describe
their interfaces using Web IDL, and then use prose to specify API-specific details.

<p class="note">The term "JavaScript" is used to refer to ECMA-262, rather than the official term ECMAScript, since the term JavaScript is more widely known.</p>


<h2 id="idl">Interface definition language</h2>

This section describes a language, <em>Web IDL</em>, which can be used to define
interfaces for APIs in the Web platform.  A specification that defines Web APIs
can include one or more <dfn id="dfn-idl-fragment" export lt="IDL fragment">IDL fragments</dfn> that
describe the interfaces (the state and behavior that objects can exhibit)
for the APIs defined by that specification.
An [=IDL fragment=] is
a sequence of definitions that matches the <emu-nt><a href="#prod-Definitions">Definitions</a></emu-nt> grammar symbol.
The set of [=IDL fragments=] that
an implementation supports is not ordered.
See [[#idl-grammar]] for the complete grammar and an explanation of the notation used.

The different kinds of <dfn id="dfn-definition">definitions</dfn> that can appear in an
[=IDL fragment=] are:
[=interfaces=],
[=partial interface|partial interface definitions=],
[=interface mixins=],
[=partial interface mixin|partial mixin definitions=],
[=callback functions=],
[=callback interfaces=],
[=namespaces=],
[=partial namespace|partial namespace definitions=],
[=dictionary|dictionaries=],
[=partial dictionary|partial dictionary definitions=],
[=typedefs=] and
[=includes statements=].
These are all defined in the following sections.

Each [=definition=]
(matching <emu-nt><a href="#prod-Definition">Definition</a></emu-nt>)
can be preceded by a list of [=extended attributes=] (matching
<emu-nt><a href="#prod-ExtendedAttributeList">ExtendedAttributeList</a></emu-nt>),
which can control how the definition will be handled in language bindings.
The extended attributes defined by this specification that are language binding
agnostic are discussed in [[#idl-extended-attributes]],
while those specific to the JavaScript language binding are discussed
in [[#js-extended-attributes]].

<pre highlight="webidl" class="syntax">
    [<mark>extended_attributes</mark>]
    interface identifier {
      /* interface_members... */
    };
</pre>

<pre class="grammar" id="prod-Definitions">
    Definitions :
        ExtendedAttributeList Definition Definitions
        ε
</pre>

<pre class="grammar" id="prod-Definition">
    Definition :
        CallbackOrInterfaceOrMixin
        Namespace
        Partial
        Dictionary
        Enum
        Typedef
        IncludesStatement
</pre>

<div class="example" id="example-25f60a7c">

    The following is an example of an [=IDL fragment=].

    <pre highlight="webidl">
        [Exposed=Window]
        interface Paint { };

        [Exposed=Window]
        interface SolidColor : Paint {
          attribute double red;
          attribute double green;
          attribute double blue;
        };

        [Exposed=Window]
        interface Pattern : Paint {
          attribute DOMString imageURL;
        };

        [Exposed=Window]
        interface GraphicalWindow {
          constructor();
          readonly attribute unsigned long width;
          readonly attribute unsigned long height;

          attribute Paint currentPaint;

          undefined drawRectangle(double x, double y, double width, double height);

          undefined drawText(double x, double y, DOMString text);
        };
    </pre>

    Here, four [=interfaces=]
    are being defined.
    The <code class="idl">GraphicalWindow</code> interface has two
    [=read only=] [=attributes=],
    one writable attribute, and two [=operations=]
    defined on it.  Objects that implement the <code class="idl">GraphicalWindow</code> interface
    will expose these attributes and operations in a manner appropriate to the
    particular language being used.

    In JavaScript, the attributes on the IDL interfaces will be exposed as accessor
    properties and the operations as data properties whose value is a [=built-in function object=] on a
    prototype object for all <code class="idl">GraphicalWindow</code>
    objects; each JavaScript object that implements <code class="idl">GraphicalWindow</code>
    will have that prototype object in its prototype chain.

    The [=constructor operation=] that appears on <code class="idl">GraphicalWindow</code>
    causes a [=constructor=] to exist in JavaScript implementations,
    so that calling <code>new GraphicalWindow()</code> would return a new object
    that implemented the interface.

    All [=interfaces=] have the [{{Exposed}}] [=extended attribute=], which ensures the interfaces
    are only available in [=realms=] whose [=realm/global object=] is a {{Window}} object.
</div>


<h3 id="idl-names">Names</h3>

Every [=interface=],
[=partial interface|partial interface definition=],
[=namespace=],
[=partial namespace|partial namespace definition=],
[=dictionary=],
[=partial dictionary|partial dictionary definition=],
[=enumeration=],
[=callback function=],
[=callback interface=] and
[=typedef=] (together called <dfn id="dfn-named-definition" export lt="named definition">named definitions</dfn>)
and every [=constant=],
[=attribute=],
and [=dictionary member=] has an
<dfn id="dfn-identifier" export>identifier</dfn>, as do some
[=operations=].
The identifier is determined by an
<emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token somewhere
in the declaration:

*   For [=named definitions=],
    the <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token that appears
    directly after the <emu-t>interface</emu-t>, <emu-t>namespace</emu-t>,
    <emu-t>dictionary</emu-t>, <emu-t>enum</emu-t>
    or <emu-t>callback</emu-t> keyword
    determines the identifier of that definition.
    <pre highlight="webidl" class="syntax">
        interface <mark>interface_identifier</mark> { /* interface_members... */ };
        partial interface <mark>interface_identifier</mark> { /* interface_members... */ };
        namespace <mark>namespace_identifier</mark> { /* namespace_members... */ };
        partial namespace <mark>namespace_identifier</mark> { /* namespace_members... */ };
        dictionary <mark>dictionary_identifier</mark> { /* dictionary_members... */ };
        partial dictionary <mark>dictionary_identifier</mark> { /* dictionary_members... */ };
        enum <mark>enumeration_identifier</mark> { "enum", "values" /* , ... */ };
        callback <mark>callback_identifier</mark> = return_type (/* arguments... */);
        callback interface <mark>callback_interface_identifier</mark> { /* interface_members... */ };
    </pre>
*   For [=attributes=],
    [=typedefs=]
    and [=dictionary members=],
    the final <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token before the
    semicolon at the end of the declaration determines the identifier.
    <pre highlight="webidl" class="syntax">
        [extended_attributes]
        interface identifier {
          attribute type <mark>attribute_identifier</mark>;
        };

        typedef type <mark>typedef_identifier</mark>;

        dictionary identifier {
          type <mark>dictionary_member_identifier</mark>;
        };
    </pre>
*   For [=constants=],
    the <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token before the
    equals sign determines the identifier.
    <pre highlight="webidl" class="syntax">const type <mark>constant_identifier</mark> = 42;</pre>
*   For [=operations=], the
    <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token that appears
    after the return type but before the opening parenthesis (that is,
    one that is matched as part of the <emu-nt><a href="#prod-OptionalOperationName">OptionalOperationName</a></emu-nt>
    grammar symbol in an <emu-nt><a href="#prod-OperationRest">OperationRest</a></emu-nt>) determines the identifier of the operation.  If
    there is no such <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token,
    then the operation does not have an identifier.
    <pre highlight="webidl" class="syntax">
        interface interface_identifier {
          return_type <mark>operation_identifier</mark>(/* arguments... */);
        };
    </pre>

Note: Operations can have no identifier when they are being used to declare a
[=special operation|special kind of operation=], such as a getter or setter.

For all of these constructs, the [=identifier=]
is the value of the <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token with any leading
U+005F (_) removed.

Note: A leading U+005F (_) is used to escape an identifier from looking
like a reserved word so that, for example, an interface named "<code>interface</code>" can be
defined. The leading U+005F (_) is dropped to unescape the
identifier.

Operation arguments can take a slightly wider set of identifiers.  In an operation
declaration, the identifier of an argument is specified immediately after its
type and is given by either an <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t>
token or by one of the keywords that match the <emu-nt><a href="#prod-ArgumentNameKeyword">ArgumentNameKeyword</a></emu-nt>
symbol.  If one of these keywords is used, it need not be escaped with a leading
underscore.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      return_type operation_identifier(argument_type <mark>argument_identifier</mark> /* , ... */);
    };
</pre>

<pre class="grammar" id="prod-ArgumentNameKeyword">
    ArgumentNameKeyword :
        "async"
        "attribute"
        "callback"
        "const"
        "constructor"
        "deleter"
        "dictionary"
        "enum"
        "getter"
        "includes"
        "inherit"
        "interface"
        "iterable"
        "maplike"
        "mixin"
        "namespace"
        "partial"
        "readonly"
        "required"
        "setlike"
        "setter"
        "static"
        "stringifier"
        "typedef"
        "unrestricted"
</pre>

If an <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token is used, then the
[=identifier=] of the operation argument
is the value of that token with any leading
U+005F (_) removed.
If instead one of the <emu-nt><a href="#prod-ArgumentNameKeyword">ArgumentNameKeyword</a></emu-nt>
keyword token is used, then the [=identifier=] of the operation argument
is simply that token.

The [=identifier=] of any of the abovementioned
IDL constructs (except operation arguments) must not be "<code>constructor</code>",
"<code>toString</code>",
or begin with a U+005F (_).  These
are known as <dfn id="dfn-reserved-identifier" export>reserved identifiers</dfn>.

Although the "<code>toJSON</code>" [=identifier=] is not a [=reserved identifier=],
it must only be used for [=regular operations=]
that convert objects to [=JSON types=],
as described in [[#idl-tojson-operation]].

Note: Further restrictions on identifier names for particular constructs can be made
in later sections.

Within the set of [=IDL fragments=]
that a given implementation supports,
the [=identifier=] of every
[=interface=],
[=namespace=],
[=dictionary=],
[=enumeration=],
[=callback function=],
[=callback interface=] and
[=typedef=]
must not
be the same as the identifier of any other
[=interface=],
[=namespace=],
[=dictionary=],
[=enumeration=],
[=callback function=],
[=callback interface=] or
[=typedef=].

Within an [=IDL fragment=], a reference
to a [=definition=] need not appear after
the declaration of the referenced definition.  References can also be made
across [=IDL fragments=].

<div class="example" id="example-679e8e2c">

    Therefore, the following [=IDL fragment=] is valid:

    <pre highlight="webidl">
        [Exposed=Window]
        interface B : A {
          undefined f(SequenceOfLongs x);
        };

        [Exposed=Window]
        interface A {
        };

        typedef sequence&lt;long&gt; SequenceOfLongs;
    </pre>
</div>

<div class="example" id="example-1192ff1f">

    The following [=IDL fragment=]
    demonstrates how [=identifiers=]
    are given to definitions and [=interface members=].

    <pre highlight="webidl">
        // Typedef identifier: "number"
        typedef double number;

        // Interface identifier: "System"
        [Exposed=Window]
        interface System {

          // Operation identifier:          "createObject"
          // Operation argument identifier: "interface"
          object createObject(DOMString _interface);

          // Operation argument identifier: "interface"
          sequence&lt;object&gt; getObjects(DOMString interface);

          // Operation has no identifier; it declares a getter.
          getter DOMString (DOMString keyName);
        };

        // Interface identifier: "TextField"
        [Exposed=Window]
        interface TextField {

          // Attribute identifier: "const"
          attribute boolean _const;

          // Attribute identifier: "value"
          attribute DOMString? _value;
        };
    </pre>

    Note that while the second [=attribute=]
    on the <code class="idl">TextField</code> [=interface=]
    need not have been escaped with an underscore (because "<code>value</code>" is
    not a keyword in the IDL grammar), it is still unescaped
    to obtain the attribute's [=identifier=].

</div>


<h3 id="idl-interfaces">Interfaces</h3>

[=IDL fragments=] are used to
describe object oriented systems.  In such systems, objects are entities
that have identity and which are encapsulations of state and behavior.
An <dfn id="dfn-interface" export>interface</dfn> is a definition (matching
<emu-t>interface</emu-t> <emu-nt><a href="#prod-InterfaceRest">InterfaceRest</a></emu-nt>) that declares some
state and behavior that an object implementing that interface will expose.

<pre highlight="webidl" class="syntax">
    [extended_attributes]
    interface identifier {
      /* interface_members... */
    };
</pre>

An interface is a specification of a set of
<dfn id="dfn-interface-member" export lt="interface member">interface members</dfn>
(matching <emu-nt><a href="#prod-InterfaceMembers">InterfaceMembers</a></emu-nt>).
These are the [=members=] that appear between the braces in the interface declaration.

Interfaces in Web IDL describe how objects that implement the
interface behave.  In bindings for object oriented languages, it is
expected that an object that implements a particular IDL interface
provides ways to inspect and modify the object's state and to
invoke the behavior described by the interface.

An interface can be defined to <dfn id="dfn-inherit" for="interface" export>inherit</dfn> from another interface.
If the identifier of the interface is followed by a
U+003A (:)
and an [=identifier=],
then that identifier identifies the inherited interface.
An object that implements an interface that inherits from another
also implements that inherited interface.  The object therefore will also
have members that correspond to the interface members from the inherited interface.

<pre highlight="webidl" class="syntax">
    interface identifier : <mark>identifier_of_inherited_interface</mark> {
      /* interface_members... */
    };
</pre>

The order that members appear in has significance for property enumeration in the <a href="#js-interfaces">JavaScript binding</a>.

Interfaces may specify an interface member that has the same name as
one from an inherited interface.  Objects that implement the derived
interface will expose the member on the derived interface.  It is
language binding specific whether the overridden member can be
accessed on the object.

<div class="example" id="example-367b9481">

    Consider the following two interfaces.

    <pre highlight="webidl">
        [Exposed=Window]
        interface A {
          undefined f();
          undefined g();
        };

        [Exposed=Window]
        interface B : A {
          undefined f();
          undefined g(DOMString x);
        };
    </pre>

    In the JavaScript language binding, an instance of <code class="idl">B</code>
    will have a prototype chain that looks like the following:

    <pre>
        [Object.prototype: the Object prototype object]
             ↑
        [A.prototype: interface prototype object for A]
             ↑
        [B.prototype: interface prototype object for B]
             ↑
        [instanceOfB]
    </pre>

    Calling <code>instanceOfB.f()</code> in JavaScript will invoke the f defined
    on <code class="idl">B</code>.  However, the f from <code class="idl">A</code>
    can still be invoked on an object that implements <code class="idl">B</code> by
    calling <code>A.prototype.f.call(instanceOfB)</code>.

</div>

The <dfn id="dfn-inherited-interfaces" export>inherited interfaces</dfn> of
a given interface |A| is the set of all interfaces that |A|
inherits from, directly or indirectly.  If |A| does not [=interface/inherit=]
from another interface, then the set is empty.  Otherwise, the set
includes the interface |B| that |A| [=interface/inherits=]
from and all of |B|'s [=inherited interfaces=].

An interface must not be declared such that
its inheritance hierarchy has a cycle.  That is, an interface
|A| cannot inherit from itself, nor can it inherit from another
interface |B| that inherits from |A|, and so on.

<div algorithm>
  The [=list=] of <dfn for=interface>inclusive inherited interfaces</dfn> of an [=interface=] |I|
  is defined as follows:

    1.  Let |result| be « ».
    1.  Let |interface| be |I|.
    1.  While |interface| is not null:
        1.  [=list/Append=] |interface| to |result|.
        1.  Set |interface| to the [=interface=] that |I| [=interface/inherits=] from, if any, and
            null otherwise.
    1.  Return |result|.
</div>

Note that general multiple inheritance of interfaces is not supported, and
objects also cannot implement arbitrary sets of interfaces.
Objects can be defined to implement a single given interface |A|,
which means that it also implements all of |A|'s [=inherited interfaces=].
In addition, an [=includes statement=] can be used
to define that objects implementing an [=interface=] |A|
will always also include the [=interface mixin member|members=]
of the [=interface mixins=] |A| [=includes=].

Each interface member can be preceded by a list of [=extended attributes=] (matching
<emu-nt><a href="#prod-ExtendedAttributeList">ExtendedAttributeList</a></emu-nt>),
which can control how the interface member will be handled in language bindings.

<pre highlight="webidl" class="syntax">
    [extended_attributes]
    interface identifier {

      [<mark>extended_attributes</mark>]
      const type constant_identifier = 42;

      [<mark>extended_attributes</mark>]
      attribute type identifier;

      [<mark>extended_attributes</mark>]
      return_type identifier(/* arguments... */);
    };
</pre>

The IDL for interfaces can be split into multiple parts by using
<dfn id="dfn-partial-interface" export>partial interface</dfn> definitions
(matching <emu-t>partial</emu-t> <emu-t>interface</emu-t>
<emu-nt><a href="#prod-PartialInterfaceRest">PartialInterfaceRest</a></emu-nt>).
The [=identifier=] of a partial
interface definition must be the same
as the identifier of an interface definition.  All of
the members that appear on each of the partial interfaces are considered to be
members of the interface itself.

<pre highlight="webidl" class="syntax">
    interface <mark>SomeInterface</mark> {
      /* interface_members... */
    };

    partial interface <mark>SomeInterface</mark> {
      /* interface_members... */
    };
</pre>

Note: Partial interface definitions are intended for use as a specification
editorial aide, allowing the definition of an interface to be separated
over more than one section of the document, and sometimes multiple documents.

The order of appearance of an [=interface=]
definition and any of its [=partial interface=]
definitions does not matter.

Note: A partial interface definition cannot specify that the interface
[=interface/inherits=] from another interface.
Inheritance is to be specified on the original [=interface=]
definition.

The relevant language binding determines how interfaces correspond to constructs
in the language.

The following extended attributes are applicable to interfaces:
[{{CrossOriginIsolated}}],
[{{Exposed}}],
[{{Global}}],
[{{LegacyFactoryFunction}}],
[{{LegacyNoInterfaceObject}}],
[{{LegacyOverrideBuiltIns}}],
[{{LegacyWindowAlias}}], and
[{{SecureContext}}].

The following extended attributes are applicable to [=partial interfaces=]:
[{{CrossOriginIsolated}}],
[{{Exposed}}],
[{{LegacyOverrideBuiltIns}}], and
[{{SecureContext}}].

[=Interfaces=] must be annotated with an [{{Exposed}}] [=extended attribute=].

<div algorithm>

The <dfn>qualified name</dfn> of an [=interface=] |interface| is defined as follows:

1.  Let |identifier| be the [=identifier=] of |interface|.
1.  If |interface| has a [{{LegacyNamespace}}] [=extended attribute=], then:
    1.  Let |namespace| be the identifier argument of the [{{LegacyNamespace}}]
        [=extended attribute=].
    1.  Return the [=concatenation=] of « |namespace|, |identifier| » with
        separator U+002E (.).
1. Return |identifier|.

</div>

<pre class="grammar" id="prod-CallbackOrInterfaceOrMixin">
    CallbackOrInterfaceOrMixin :
        "callback" CallbackRestOrInterface
        "interface" InterfaceOrMixin
</pre>

<pre class="grammar" id="prod-InterfaceOrMixin">
    InterfaceOrMixin :
        InterfaceRest
        MixinRest
</pre>

<pre class="grammar" id="prod-InterfaceRest">
    InterfaceRest :
        identifier Inheritance "{" InterfaceMembers "}" ";"
</pre>

<pre class="grammar" id="prod-Partial">
    Partial :
        "partial" PartialDefinition
</pre>

<pre class="grammar" id="prod-PartialDefinition">
    PartialDefinition :
        "interface" PartialInterfaceOrPartialMixin
        PartialDictionary
        Namespace
</pre>

<pre class="grammar" id="prod-PartialInterfaceOrPartialMixin">
    PartialInterfaceOrPartialMixin :
        PartialInterfaceRest
        MixinRest
</pre>

<pre class="grammar" id="prod-PartialInterfaceRest">
    PartialInterfaceRest :
        identifier "{" PartialInterfaceMembers "}" ";"
</pre>

<pre class="grammar" id="prod-InterfaceMembers">
    InterfaceMembers :
        ExtendedAttributeList InterfaceMember InterfaceMembers
        ε
</pre>

<pre class="grammar" id="prod-InterfaceMember">
    InterfaceMember :
        PartialInterfaceMember
        Constructor
</pre>

<pre class="grammar" id="prod-PartialInterfaceMembers">
    PartialInterfaceMembers :
        ExtendedAttributeList PartialInterfaceMember PartialInterfaceMembers
        ε
</pre>

<pre class="grammar" id="prod-PartialInterfaceMember">
    PartialInterfaceMember :
        Const
        Operation
        Stringifier
        StaticMember
        Iterable
        AsyncIterable
        ReadOnlyMember
        ReadWriteAttribute
        ReadWriteMaplike
        ReadWriteSetlike
        InheritAttribute
</pre>

<pre class="grammar" id="prod-Inheritance">
    Inheritance :
        ":" identifier
        ε
</pre>

<div class="example" id="example-0f0ea08a">

    The following [=IDL fragment=]
    demonstrates the definition of two mutually referential [=interfaces=].
    Both <code class="idl">Human</code> and <code class="idl">Dog</code>
    inherit from <code class="idl">Animal</code>.  Objects that implement
    either of those two interfaces will thus have a <code>name</code> attribute.

    <pre highlight="webidl">
        [Exposed=Window]
        interface Animal {
          attribute DOMString name;
        };

        [Exposed=Window]
        interface Human : Animal {
          attribute Dog? pet;
        };

        [Exposed=Window]
        interface Dog : Animal {
          attribute Human? owner;
        };
    </pre>
</div>

<div class="example" id="example-25ab6a82">

    The following [=IDL fragment=] defines
    simplified versions of a DOM [=interfaces=]
    and a [=callback interface=].

    <pre highlight="webidl">
        [Exposed=Window]
        interface Node {
          readonly attribute DOMString nodeName;
          readonly attribute Node? parentNode;
          Node appendChild(Node newChild);
          undefined addEventListener(DOMString type, EventListener listener);
        };

        callback interface EventListener {
          undefined handleEvent(Event event);
        };
    </pre>

    Plain objects can implement a [=callback interface=] like
    <code class="idl">EventListener</code>:

    <pre highlight="js">
        var node = getNode();                                // Obtain an instance of Node.

        var listener = {
          handleEvent: function(event) {
            // ...
          }
        };
        node.addEventListener("click", listener);            // This works.

        node.addEventListener("click", function() { ... });  // As does this.
    </pre>

    It is not possible for such an object to implement an [=interface=] like
    <code class="idl">Node</code>, however:

    <pre highlight="js">
        var node = getNode();  // Obtain an instance of Node.

        var newNode = {
          nodeName: "span",
          parentNode: null,
          appendChild: function(newchild) {
            // ...
          },
          addEventListener: function(type, listener) {
            // ...
          }
        };
        node.appendChild(newNode);  // This will throw a TypeError exception.
    </pre>
</div>


<h3 id="idl-interface-mixins">Interface mixins</h3>

An <dfn export>interface mixin</dfn> is a definition (matching <emu-t>interface</emu-t> <emu-nt><a href="#prod-MixinRest">MixinRest</a></emu-nt>)
that declares state and behavior that can be [=included=] by one or more [=interfaces=],
and that are exposed by objects that implement an [=interface=]
that [=includes=] the [=interface mixin=].

<pre highlight="webidl" class="syntax">
    interface mixin identifier {
      /* mixin_members... */
    };
</pre>

Note: [=Interface mixins=], much like [=partial interfaces=],
are intended for use as a specification editorial aide,
allowing a coherent set of functionalities to be grouped together,
and included in multiple interfaces, possibly across documents.
They are not meant to be exposed through language bindings.
Guidance on when to choose [=partial interfaces=], [=interface mixins=],
or [=partial interface mixins=] can be found in [[#using-mixins-and-partials]].

An [=interface mixin=] is a specification of a set of <dfn export lt="interface mixin member">interface mixin members</dfn>
(matching <emu-nt><a href="#prod-MixinMembers">MixinMembers</a></emu-nt>),
which are the [=constants=], [=regular operations=], [=regular attributes=], and [=stringifiers=]
that appear between the braces in the [=interface mixin=] declaration.

These [=constants=], [=regular operations=], [=regular attributes=], and [=stringifiers=]
describe the behaviors that can be implemented by an object,
as if they were specified on the [=interface=] that [=includes=] them.

[=Static attributes=], [=static operations=], [=special operations=], and
[=iterable declaration|iterable=], [=asynchronously iterable declaration|asynchronously iterable=],
[=maplike declaration|maplike=], and [=setlike declarations=] cannot appear in [=interface mixin=]
declarations.

As with interfaces, the IDL for [=interface mixins=] can be split into multiple parts by using
<dfn export>partial interface mixin</dfn> definitions
(matching <emu-t>partial</emu-t> <emu-t>interface</emu-t> <emu-nt><a href="#prod-MixinRest">MixinRest</a></emu-nt>).
The [=identifier=] of a [=partial interface mixin=] [=definition=] must
be the same as the [=identifier=] of an [=interface mixin=] [=definition=].
All of the [=interface mixin member|members=] that appear on each of the [=partial interface mixin=] [=definitions=]
are considered to be [=members=] of the [=interface mixin=] itself,
and—by extension—of the [=interfaces=] that [=include=] the [=interface mixin=].

<pre highlight="webidl" class="syntax">
    interface mixin <mark>SomeMixin</mark> {
      /* mixin_members... */
    };

    partial interface mixin <mark>SomeMixin</mark> {
      /* mixin_members... */
    };
</pre>

The order that members appear in has significance for property enumeration
in the <a href="#js-interfaces">JavaScript binding</a>.

Note that unlike [=interfaces=] or [=dictionaries=], [=interface mixins=] do not create types.

Of the extended attributes defined in this specification,
only the [{{CrossOriginIsolated}}], [{{Exposed}}], and [{{SecureContext}}] extended attributes
are applicable to [=interface mixins=].

An <dfn>includes statement</dfn> is a definition
(matching <emu-nt><a href="#prod-IncludesStatement">IncludesStatement</a></emu-nt>)
used to declare that all objects implementing an [=interface=] |I|
(identified by the first [=identifier=])
must additionally include the [=interface mixin member|members=] of [=interface mixin=] |M|
(identified by the second identifier).
[=Interface=] |I| is said to <dfn id="include" for="interface" export>include</dfn>
[=interface mixin=] |M|.

<pre highlight="webidl" class="syntax">
    interface_identifier includes mixin_identifier;
</pre>

The first [=identifier=] must reference a [=interface=] |I|.
The second identifier must reference an [=interface mixin=] |M|.

Each [=interface mixin member|member=] of |M| is considered to be
a [=member=] of each [=interface=] |I|, |J|, |K|, … that [=includes=] |M|,
as if a copy of each [=interface mixin member|member=] had been made.
So for a given member <var ignore>m</var> of |M|,
interface |I| is considered to have a [=member=] <var>m<sub>I</sub></var>,
interface |J| is considered to have a [=member=] <var>m<sub>J</sub></var>,
interface |K| is considered to have a [=member=] <var>m<sub>K</sub></var>, and so on.
The <dfn>host interfaces</dfn> of <var>m<sub>I</sub></var>, <var>m<sub>J</sub></var>,
and <var>m<sub>K</sub></var>, are |I|, |J|, and |K| respectively.

Note: In JavaScript, this implies that each [=regular operation=]
declared as a [=interface mixin member|member=] of [=interface mixin=] |M|,
and exposed as a data property with a [=built-in function object=] value,
is a distinct [=built-in function object=]
in each [=interface prototype object=]
whose associated [=interface=] [=includes=] |M|.
Similarly, for [=attributes=], each copy of the accessor property has
distinct [=built-in function objects=] for its getters and setters.

The order of appearance of [=includes statements=] affects the order in which [=interface mixin=]
are [=included=] by their [=host interface=].

Issue: [=interface mixin member|Member=] order isn't clearly specified,
in particular when [=interface mixins=] are defined in separate documents.
It is discussed in <a href="https://github.com/whatwg/webidl/issues/432">issue #432</a>.

No [=extended attributes=] defined in this specification are applicable to [=includes statements=].

<div class="example" id="example-mixin">

    The following [=IDL fragment=] defines an [=interface=], <code class="idl">Entry</code>,
    and an [=interface mixin=], <code class="idl">Observable</code>.
    The [=includes statement=] specifies that
    <code class="idl">Observable</code>'s [=interface mixin member|members=]
    are always included on objects implementing <code class="idl">Entry</code>.

    <pre highlight="webidl">
        interface Entry {
          readonly attribute unsigned short entryType;
          // ...
        };

        interface mixin Observable {
          undefined addEventListener(DOMString type,
                                EventListener listener,
                                boolean useCapture);
          // ...
        };

        Entry includes Observable;
    </pre>

    A JavaScript implementation would thus have an <code class="idl">addEventListener</code>
    property in the prototype chain of every <code class="idl">Entry</code>:

    <pre highlight="js">
        var e = getEntry();          // Obtain an instance of Entry.
        typeof e.addEventListener;   // Evaluates to "function".
    </pre>

</div>

<div grammar-fill-with="CallbackOrInterfaceOrMixin"></div>

<div grammar-fill-with="CallbackRestOrInterfaceOrMixin"></div>

<div grammar-fill-with="InterfaceOrMixin"></div>

<div grammar-fill-with="Partial"></div>

<div grammar-fill-with="PartialDefinition"></div>

<pre class="grammar" id="prod-MixinRest">
    MixinRest :
        "mixin" identifier "{" MixinMembers "}" ";"
</pre>

<pre class="grammar" id="prod-MixinMembers">
    MixinMembers :
        ExtendedAttributeList MixinMember MixinMembers
        ε
</pre>

<pre class="grammar" id="prod-MixinMember">
    MixinMember :
        Const
        RegularOperation
        Stringifier
        OptionalReadOnly AttributeRest
</pre>

<pre class="grammar" id="prod-IncludesStatement">
    IncludesStatement :
        identifier "includes" identifier ";"
</pre>

<h4 id="using-mixins-and-partials">Using mixins and partials</h4>

<i>This section is informative.</i>

[=Interface mixins=] allow the sharing of [=attributes=], [=constants=], and [=operations=]
across <em>multiple</em> [=interfaces=].
If you're only planning to extend a single interface,
you might consider using a [=partial interface=] instead.

For example, instead of:

<pre highlight="webidl">
    interface mixin WindowSessionStorage {
      readonly attribute Storage sessionStorage;
    };
    Window includes WindowSessionStorage;
</pre>

do:

<pre highlight="webidl">
    partial interface Window {
      readonly attribute Storage sessionStorage;
    };
</pre>

Additionally, you can rely on extending [=interface mixins=] exposed by other specifications
to target common use cases, such as [=exposed|exposing=]
a set of [=attributes=], [=constants=], or [=operations=]
across both window and worker contexts.

For example, instead of the common but verbose:

<pre highlight="webidl">
    interface mixin GlobalCrypto {
      readonly attribute Crypto crypto;
    };

    Window includes GlobalCrypto;
    WorkerGlobalScope includes GlobalCrypto;
</pre>

you can extend the {{WindowOrWorkerGlobalScope}} [=interface mixin=] using a [=partial interface mixin=]:

<pre highlight="webidl">
    partial interface mixin WindowOrWorkerGlobalScope {
      readonly attribute Crypto crypto;
    };
</pre>


<h3 id="idl-callback-interfaces">Callback interfaces</h3>

A <dfn id="dfn-callback-interface" export>callback interface</dfn> is a [=definition=] matching
<emu-t>callback</emu-t> <emu-t>interface</emu-t>
<emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> <emu-t>{</emu-t>
<emu-nt><a href="#prod-CallbackInterfaceMembers">CallbackInterfaceMembers</a></emu-nt>
<emu-t>}</emu-t> <emu-t>;</emu-t>.
It can be implemented by any object, as described in [[#idl-objects]].

Note: A [=callback interface=] is not an [=interface=]. The name and syntax are left over from
earlier versions of this standard, where these concepts had more in common.

A [=callback interface=] is a specification of a set of
<dfn export lt="callback interface member">callback interface members</dfn>
(matching <emu-nt><a href="#prod-CallbackInterfaceMembers">CallbackInterfaceMembers</a></emu-nt>).
These are the [=members=] that appear between the braces in the interface declaration.

<pre highlight="webidl" class="syntax">
    callback interface identifier {
      /* interface_members... */
    };
</pre>

Note: See also the similarly named [=callback function=] definition.

[=Callback interfaces=] must define exactly one [=regular operation=].

<div class="warning">

    Specification authors should not define
    [=callback interfaces=]
    unless required to describe the requirements of existing APIs.
    Instead, a [=callback function=] should be used.

    The definition of {{EventListener}} as a
    [=callback interface=]
    is an example of an existing API that needs to allow
    objects with a
    given property (in this case <code class="idl">handleEvent</code>) to be considered to implement the interface.
    For new APIs, and those for which there are no compatibility concerns,
    using a [=callback function=] will allow
    only a [=function object=] (in the JavaScript
    language binding).

</div>

[=Callback interfaces=] which declare [=constants=]
must be annotated with an [{{Exposed}}] [=extended attribute=].


<pre class="grammar" id="prod-CallbackRestOrInterface">
    CallbackRestOrInterface :
        CallbackRest
        "interface" identifier "{" CallbackInterfaceMembers "}" ";"
</pre>

<pre class="grammar" id="prod-CallbackInterfaceMembers">
    CallbackInterfaceMembers :
        ExtendedAttributeList CallbackInterfaceMember CallbackInterfaceMembers
        ε
</pre>

<pre class="grammar" id="prod-CallbackInterfaceMember">
    CallbackInterfaceMember :
        Const
        RegularOperation
</pre>


<h3 id="idl-members">Members</h3>

[=Interfaces=], [=interface mixins=], and [=namespaces=] are specifications of a set of
<dfn id="dfn-member" export lt="members">members</dfn> (respectively matching
<emu-nt><a href="#prod-InterfaceMembers">InterfaceMembers</a></emu-nt>,
<emu-nt><a href="#prod-MixinMembers">MixinMembers</a></emu-nt>, and
<emu-nt><a href="#prod-NamespaceMembers">NamespaceMembers</a></emu-nt>),
which are the [=constants=], [=attributes=], [=operations=], and
other declarations that appear between the braces of their declarations.
[=Attributes=] describe the state that an object
implementing the [=interface=], [=interface mixin=], or [=namespace=] will expose,
and [=operations=] describe the behaviors that can be invoked on the object.
[=Constants=] declare named constant values
that are exposed as a convenience to users of objects in the system.

<div class="note">

    When an [=interface=] [=includes=] an [=interface mixin=], each [=member=]
    of the interface mixin is also considered a member of the interface. In contrast,
    [=interface/inherit|inherited=] interface members are not considered members
    of the interface.

</div>

The [=constructor steps=], [=getter steps=], [=setter steps=], and [=method steps=] for the various
[=members=] defined on an [=interface=] or [=interface mixin=] have access to a
<dfn export>this</dfn> value, which is an IDL value of the [=interface=] type that the member is
declared on or that [=includes=] the [=interface mixin=] the member is declared on.

[=Setter steps=] also have access to <dfn export>the given value</dfn>,
which is an IDL value of the type the [=attribute=] is declared as.

[=Interfaces=], [=interface mixins=], [=callback interfaces=] and [=namespaces=] each support a
different set of [=members=],
which are specified in [[#idl-interfaces]], [[#idl-interface-mixins]],
[[#idl-callback-interfaces]], and [[#idl-namespaces]],
and summarized in the following informative table:

<table class="data complex non-normative">
    <thead>
        <tr>
            <th></th>
            <th>[=Interfaces=]</th>
            <th>[=Callback interfaces=]</th>
            <th>[=Interface mixins=]</th>
            <th>[=Namespaces=]</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <th>[=Constants=]</th>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td></td>
        </tr>
        <tr>
            <th>[=Regular attributes=]</th>
            <td>●</td>
            <td></td>
            <td>●</td>
            <td>Only [=read only=] attributes</td>
        </tr>
        <tr>
            <th>[=Static attributes=]</th>
            <td>●</td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
        <tr>
            <th>[=Regular Operations=]</th>
            <td>●</td>
            <td>●</td>
            <td>●</td>
            <td>●</td>
        </tr>
        <tr>
            <th>[=Stringifiers=]</th>
            <td>●</td>
            <td></td>
            <td>●</td>
            <td></td>
        </tr>
        <tr>
            <th>[=Special Operations=]</th>
            <td>●</td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
        <tr>
            <th>[=Static Operations=]</th>
            <td>●</td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
        <tr>
            <th>[=Iterable declarations=]</th>
            <td>●</td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
        <tr>
            <th>[=Asynchronously iterable declarations=]</th>
            <td>●</td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
        <tr>
            <th>[=Maplike declarations=]</th>
            <td>●</td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
        <tr>
            <th>[=Setlike declarations=]</th>
            <td>●</td>
            <td></td>
            <td></td>
            <td></td>
        </tr>
    </tbody>
</table>

<h4 id="idl-constants">Constants</h4>

A <dfn id="dfn-constant" export>constant</dfn> is a declaration (matching
<emu-nt><a href="#prod-Const">Const</a></emu-nt>) used to bind a constant value to a name.
Constants can appear on [=interfaces=] and [=callback interfaces=].

<p class="warning">
    Constants have in the past primarily been used to define
    named integer codes in the style of an enumeration.  The Web platform
    is moving away from this design pattern in favor of the use of strings.
    Editors who wish to use this feature are strongly advised to discuss this
    by <a href="https://github.com/whatwg/webidl/issues/new?title=Intent%20to%20use%20Constants">filing an issue</a>
    before proceeding.
</p>

<pre highlight="webidl" class="syntax">const type constant_identifier = 42;</pre>

The [=identifier=] of a
[=constant=]
must not be the same as the identifier
of another [=interface member=] or [=callback interface member=]
defined on the same [=interface=] or [=callback interface=].
The identifier also must not
be "<code>length</code>", "<code>name</code>" or "<code>prototype</code>".

Note: These three names are the names of properties that are defined on the
[=interface object=] in the JavaScript language binding.

The type of a constant (matching <emu-nt><a href="#prod-ConstType">ConstType</a></emu-nt>)
must not be any type other than
a [=primitive type=].
If an [=identifier=] is used,
it must reference a [=typedef=]
whose type is a primitive type.

The <emu-nt><a href="#prod-ConstValue">ConstValue</a></emu-nt> part of a
constant declaration gives the value of the constant, which can be
one of the two boolean literal tokens (<emu-t>true</emu-t>
and <emu-t>false</emu-t>), an
<emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token,
a <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token,
or one of the three special floating point constant values
(<emu-t>-Infinity</emu-t>, <emu-t>Infinity</emu-t> and <emu-t>NaN</emu-t>).

Note: These values – in addition to strings and the empty sequence – can also be used to specify the
[=dictionary member/default value|default value of a dictionary member=] or
<a for="optional argument" lt="default value" class=allow-2119>of an optional argument</a>.
Note that strings, the
empty sequence <emu-t>[]</emu-t>, and the default dictionary <emu-t>{}</emu-t> cannot be used as the value of a
[=constant=].

The value of the boolean literal tokens <emu-t>true</emu-t> and
<emu-t>false</emu-t> are the IDL {{boolean}} values
<code class="idl">true</code> and <code class="idl">false</code>.

<div algorithm="value of integer tokens">

    The value of an <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token
    is an integer whose value is determined as follows:

    1.  Let |S| be the sequence of [=scalar values=] matched by the <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token.
    1.  Let |sign| be −1 if |S| begins with U+002D (-), and 1 otherwise.
    1.  Let |base| be the base of the number based on the [=scalar values=] that follow the optional leading U+002D (-):
        <dl class="switch">
             :  U+0030 (0), U+0058 (X)
             :  U+0030 (0), U+0078 (x)
             :: The base is 16.
             :  U+0030 (0)
             :: The base is 8.
             :  Otherwise
             :: The base is 10.
        </dl>
    1.  Let |number| be the result of interpreting all remaining [=scalar values=] following the optional leading U+002D (-)
        character and any [=scalar values=] indicating the base as an integer specified in base |base|.
    1.  Return |sign| × |number|.
</div>

The type of an <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token is the same
as the type of the constant, dictionary member or optional argument it is being used as the value of.
The value of the <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token must not
lie outside the valid range of values for its type, as given in
[[#idl-types]].

<div id="decimal-token-value" algorithm="value of decimal tokens">
    The value of a <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token is
    either an IEEE 754 single-precision floating point number or an IEEE 754
    double-precision floating point number, depending on the type of the
    constant, dictionary member or optional argument it is being used as the value for, determined as follows:

    1.  Let |S| be the sequence of [=scalar values=] matched by the
        <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token.
    1.  Let |result| be the Mathematical Value that would be obtained if
        |S| were parsed as a JavaScript <emu-nt>[=NumericLiteral=]</emu-nt>.
    1.  If the <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token is being
        used as the value for a {{float}} or {{unrestricted float}}, then
        the value of the <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token
        is the IEEE 754 single-precision floating point number closest to |result|.
    1.  Otherwise, the <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token is being
        used as the value for a {{double}} or {{unrestricted double}}, and
        the value of the <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token
        is the IEEE 754 double-precision floating point number closest to |result|. [[!IEEE-754]]
</div>

The value of a constant value specified as
<emu-t>Infinity</emu-t>, <emu-t>-Infinity</emu-t>, or <emu-t>NaN</emu-t> is either
an IEEE 754 single-precision floating point number or an IEEE 754
double-precision floating point number, depending on the type of the
constant, dictionary member, or optional argument it is being used as the
value for:

<dl class="switch">
     :  Type {{unrestricted float}}, constant value <emu-t>Infinity</emu-t>
     :: The value is the IEEE 754 single-precision positive infinity value.
     :  Type {{unrestricted double}}, constant value <emu-t>Infinity</emu-t>
     :: The value is the IEEE 754 double-precision positive infinity value.
     :  Type {{unrestricted float}}, constant value <emu-t>-Infinity</emu-t>
     :: The value is the IEEE 754 single-precision negative infinity value.
     :  Type {{unrestricted double}}, constant value <emu-t>-Infinity</emu-t>
     :: The value is the IEEE 754 double-precision negative infinity value.
     :  Type {{unrestricted float}}, constant value <emu-t>NaN</emu-t>
     :: The value is the IEEE 754 single-precision NaN value with the bit pattern 0x7fc00000.
     :  Type {{unrestricted double}}, constant value <emu-t>NaN</emu-t>
     :: The value is the IEEE 754 double-precision NaN value with the bit pattern 0x7ff8000000000000.
</dl>

The type of a <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token is the same
as the type of the constant, dictionary member or optional argument it is being used as the value of.
The value of the <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token must not
lie outside the valid range of values for its type, as given in [[#idl-types]].
Also, <emu-t>Infinity</emu-t>, <emu-t>-Infinity</emu-t> and <emu-t>NaN</emu-t> must not
be used as the value of a {{float}} or {{double}}.

The value of the <emu-t>null</emu-t> token is the special
<emu-val>null</emu-val> value that is a member of the
[=nullable types=].  The type of
the <emu-t>null</emu-t> token is the same as the
type of the constant, dictionary member or optional argument it is being used as the value of.

If |VT| is the type of the value assigned to a constant, and |DT|
is the type of the constant, dictionary member or optional argument itself, then these types must
be compatible, which is the case if |DT| and |VT| are identical,
or |DT| is a [=nullable type=]
whose [=nullable types/inner type=] is |VT|.

[=Constants=] are not associated with
particular instances of the [=interface=] or [=callback interface=]
on which they appear.  It is language binding specific whether
[=constants=] are exposed on instances.

<div class="note">

    The JavaScript language binding does however
    allow [=constants=] to be accessed
    through objects implementing the IDL [=interfaces=]
    on which the [=constants=] are declared.
    For example, with the following IDL:

    <pre highlight="webidl">
        [Exposed=Window]
        interface A {
          const short rambaldi = 47;
        };
    </pre>

    the constant value can be accessed in JavaScript either as
    <code>A.rambaldi</code> or <code>instanceOfA.rambaldi</code>.

</div>

The following extended attributes are applicable to constants:
[{{CrossOriginIsolated}}],
[{{Exposed}}], and
[{{SecureContext}}].

<pre class="grammar" id="prod-Const">
    Const :
        "const" ConstType identifier "=" ConstValue ";"
</pre>

<pre class="grammar" id="prod-ConstValue">
    ConstValue :
        BooleanLiteral
        FloatLiteral
        integer
</pre>

<pre class="grammar" id="prod-BooleanLiteral">
    BooleanLiteral :
        "true"
        "false"
</pre>

<pre class="grammar" id="prod-FloatLiteral">
    FloatLiteral :
        decimal
        "-Infinity"
        "Infinity"
        "NaN"
</pre>

<pre class="grammar" id="prod-ConstType">
    ConstType :
        PrimitiveType
        identifier
</pre>

<div class="example" id="example-221dba30">

    The following [=IDL fragment=]
    demonstrates how [=constants=]
    of the above types can be defined.

    <pre highlight="webidl">
        [Exposed=Window]
        interface Util {
          const boolean DEBUG = false;
          const octet LF = 10;
          const unsigned long BIT_MASK = 0x0000fc00;
          const double AVOGADRO = 6.022e23;
        };
    </pre>
</div>


<h4 id="idl-attributes">Attributes</h4>

An <dfn id="dfn-attribute" export>attribute</dfn> is an [=interface member=] or [=namespace member=]
(matching
<emu-t>inherit</emu-t> <emu-nt><a href="#prod-AttributeRest">AttributeRest</a></emu-nt>,
<emu-t>static</emu-t> <emu-nt><a href="#prod-OptionalReadOnly">OptionalReadOnly</a></emu-nt> <emu-nt><a href="#prod-AttributeRest">AttributeRest</a></emu-nt>,
<emu-t>stringifier</emu-t> <emu-nt><a href="#prod-OptionalReadOnly">OptionalReadOnly</a></emu-nt> <emu-nt><a href="#prod-AttributeRest">AttributeRest</a></emu-nt>,
<emu-nt><a href="#prod-OptionalReadOnly">OptionalReadOnly</a></emu-nt> <emu-nt><a href="#prod-AttributeRest">AttributeRest</a></emu-nt>,
or <emu-nt><a href="#prod-AttributeRest">AttributeRest</a></emu-nt>)
that is used to declare data fields with a given type and
[=identifier=] whose value can
be retrieved and (in some cases) changed.  There are two kinds of attributes:

1.  [=regular attributes=], which are those
    used to declare that objects implementing the [=interface=]
    will have a data field member with the given [=identifier=]
        <pre highlight="webidl" class="syntax">
        interface interface_identifier {
          attribute type identifier;
        };
    </pre>
1.  [=static attributes=], which are used
    to declare attributes that are not associated with a particular object implementing the interface
        <pre highlight="webidl" class="syntax">
        interface interface_identifier {
          static attribute type identifier;
        };
    </pre>

If an attribute has no <emu-t>static</emu-t> keyword, then it declares a
<dfn id="dfn-regular-attribute" export>regular attribute</dfn>.  Otherwise,
it declares a [=static attribute=]. Note that in addition to being [=interface members=],
[=read only=] [=regular attributes=] can be [=namespace members=] as well.

The <dfn export>getter steps</dfn> of an attribute |attr| should be introduced using text of the form “The
<code>|attr|</code> getter steps are:” followed by a list, or “The <code>|attr|</code> getter steps
are to” followed by an inline description.

The <dfn export>setter steps</dfn> of an attribute |attr| should be introduced using text of the form “The
<code>|attr|</code> setter steps are:” followed by a list, or “The <code>|attr|</code> setter steps
are to” followed by an inline description.

Note: When defining [=getter steps=], you implicitly have access to [=this=].
When defining [=setter steps=], you implicitly have access to [=this=] and
[=the given value=].

The [=identifier=] of an
[=attribute=]
must not be the same as the identifier
of another [=interface member=]
defined on the same [=interface=].
The identifier of a static attribute must not
be "<code>prototype</code>".

The type of the attribute is given by the type (matching <emu-nt><a href="#prod-Type">Type</a></emu-nt>)
that appears after the <emu-t>attribute</emu-t> keyword.
If the <emu-nt><a href="#prod-Type">Type</a></emu-nt> is an
[=identifier=] or an identifier followed by <emu-t>?</emu-t>,
then the identifier must
identify an [=interface=], [=enumeration=],
[=callback function=], [=callback interface=] or [=typedef=].

The type of the attribute, after resolving typedefs, must not be a
[=nullable type|nullable=] or non-nullable version of any of the following types:

*   a [=sequence type=]
*   an [=async iterable type=]
*   a [=dictionary type=]
*   a [=record type=]
*   a [=union type=]
    that has a nullable or non-nullable sequence type, dictionary,
    or record
    as one of its [=flattened member types=]

The attribute is <dfn id="dfn-read-only" export>read only</dfn> if the
<emu-t>readonly</emu-t> keyword is used before the <emu-t>attribute</emu-t> keyword.
An object that implements the interface on which a read only attribute
is defined will not allow assignment to that attribute.  It is language
binding specific whether assignment is simply disallowed by the language,
ignored or an exception is thrown.

    <pre highlight="webidl" class="syntax">
    interface interface_identifier {
      readonly attribute type identifier;
    };
</pre>

Attributes whose type is a [=promise type=] must be [=read only=]. Additionally, they cannot have
any of the [=extended attributes=] [{{LegacyLenientSetter}}], [{{PutForwards}}], [{{Replaceable}}], or
[{{SameObject}}].

A [=regular attribute=]
that is not [=read only=]
can be declared to <dfn id="dfn-inherit-getter" export>inherit its getter</dfn>
from an ancestor interface.  This can be used to make a read only attribute
in an ancestor interface be writable on a derived interface.  An attribute
[=inherit its getter|inherits its getter=] if
its declaration includes <emu-t>inherit</emu-t> in the declaration.
The read only attribute from which the attribute inherits its getter
is the attribute with the same identifier on the closest ancestor interface
of the one on which the inheriting attribute is defined.  The attribute
whose getter is being inherited must be
of the same type as the inheriting attribute.

Note: The grammar ensures that <emu-t>inherit</emu-t> does not appear on a [=read only=] attribute
or a [=static attribute=].

<pre highlight="webidl" class="syntax">
    [Exposed=Window]
    interface Ancestor {
      readonly attribute TheType theIdentifier;
    };

    [Exposed=Window]
    interface Derived : Ancestor {
      inherit attribute TheType theIdentifier;
    };
</pre>

When the <emu-t>stringifier</emu-t> keyword is used
in a [=regular attribute=]
declaration, it indicates that objects implementing the
interface will be stringified to the value of the attribute.  See
[[#idl-stringifiers]] for details.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      stringifier attribute DOMString identifier;
    };
</pre>

The following [=extended attributes=]
are applicable to regular and static attributes:
[{{CrossOriginIsolated}}],
[{{Exposed}}],
[{{SameObject}}], and
[{{SecureContext}}].

The following [=extended attributes=]
are applicable only to regular attributes:
[{{LegacyLenientSetter}}],
[{{LegacyLenientThis}}],
[{{PutForwards}}],
[{{Replaceable}}],
[{{LegacyUnforgeable}}].

<pre class="grammar" id="prod-ReadOnlyMember">
    ReadOnlyMember :
        "readonly" ReadOnlyMemberRest
</pre>

<pre class="grammar" id="prod-ReadOnlyMemberRest">
    ReadOnlyMemberRest :
        AttributeRest
        MaplikeRest
        SetlikeRest
</pre>

<pre class="grammar" id="prod-ReadWriteAttribute">
    ReadWriteAttribute :
        AttributeRest
</pre>

<pre class="grammar" id="prod-InheritAttribute">
    InheritAttribute :
        "inherit" AttributeRest
</pre>

<pre class="grammar" id="prod-AttributeRest">
    AttributeRest :
        "attribute" TypeWithExtendedAttributes AttributeName ";"
</pre>

<pre class="grammar" id="prod-AttributeName">
    AttributeName :
        AttributeNameKeyword
        identifier
</pre>

<pre class="grammar" id="prod-AttributeNameKeyword">
    AttributeNameKeyword :
        "async"
        "required"
</pre>

<pre class="grammar" id="prod-OptionalReadOnly">
    OptionalReadOnly :
        "readonly"
        ε
</pre>

<div class="example" id="example-ca172334">

    The following [=IDL fragment=]
    demonstrates how [=attributes=]
    can be declared on an [=interface=]:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Animal {

          // A simple attribute that can be set to any string value.
          readonly attribute DOMString name;

          // An attribute whose value can be assigned to.
          attribute unsigned short age;
        };

        [Exposed=Window]
        interface Person : Animal {

          // An attribute whose getter behavior is inherited from Animal, and need not be
          // specified in the description of Person.
          inherit attribute DOMString name;
        };
    </pre>
</div>


<h4 id="idl-operations">Operations</h4>

An <dfn id="dfn-operation" export>operation</dfn> is an [=interface member=], [=callback interface
member=] or [=namespace member=]
(matching <emu-t>static</emu-t> <emu-nt><a href="#prod-RegularOperation">RegularOperation</a></emu-nt>,
<emu-t>stringifier</emu-t>,
<emu-nt><a href="#prod-RegularOperation">RegularOperation</a></emu-nt> or
<emu-nt><a href="#prod-SpecialOperation">SpecialOperation</a></emu-nt>)
that defines a behavior that can be invoked on objects implementing the interface.
There are three kinds of operation:

1.  [=regular operations=], which
    are those used to declare that objects implementing the
    [=interface=] will have a method with
    the given [=identifier=]
    <pre highlight="webidl" class="syntax">
        interface interface_identifier {
          return_type identifier(/* arguments... */);
        };
    </pre>
1.  [=special operations=],
    which are used to declare special behavior on objects
    implementing the interface, such as object indexing and stringification
    <pre highlight="webidl" class="syntax">
        interface interface_identifier {
          /* special_keyword */ return_type identifier(/* arguments... */);
          /* special_keyword */ return_type (/* arguments... */);
        };
    </pre>
1.  [=static operations=],
    which are used to declare operations that are not associated with
    a particular object implementing the interface
    <pre highlight="webidl" class="syntax">
        interface interface_identifier {
          static return_type identifier(/* arguments... */);
        };
    </pre>

If an operation has an identifier but no <emu-t>static</emu-t>
keyword, then it declares a <dfn id="dfn-regular-operation" export>regular operation</dfn>.
If the operation has a
[=special keyword=]
used in its declaration (that is, any keyword matching
<emu-nt><a href="#prod-Special">Special</a></emu-nt>, or
the <emu-t>stringifier</emu-t> keyword),
then it declares a special operation.  A single operation can declare
both a regular operation and a special operation;
see [[#idl-special-operations]] for details on special operations.
Note that in addition to being [=interface members=],
regular operations can also be [=callback interface members=] and [=namespace members=].

If an operation has no identifier,
then it must be declared to be a special operation
using one of the special keywords.

The identifier of a [=regular operation=] or [=static operation=]
must not be the same as the identifier
of a [=constant=] or [=attribute=]
defined on the same [=interface=], [=callback interface=] or [=namespace=].
The identifier of a static operation must not be "<code>prototype</code>".

Note: The identifier can be the same
as that of another operation on the interface, however.
This is how operation overloading is specified.

Note: The [=identifier=] of a [=static operation=]
can be the same as the identifier
of a [=regular operation=]
defined on the same [=interface=].

The <dfn id="dfn-return-type" export>return type</dfn> of the operation is given
by the type (matching <emu-nt><a href="#prod-Type">Type</a></emu-nt>)
that appears before the operation's optional [=identifier=].
If the return type is an
[=identifier=] followed by <emu-t>?</emu-t>,
then the identifier must
identify an [=interface=], [=dictionary=], [=enumeration=],
[=callback function=], [=callback interface=] or [=typedef=].

An operation's arguments (matching <emu-nt><a href="#prod-ArgumentList">ArgumentList</a></emu-nt>)
are given between the parentheses in the declaration.  Each individual argument is specified
as a type (matching <emu-nt><a href="#prod-Type">Type</a></emu-nt>) followed by an [=identifier=]
(matching <emu-nt><a href="#prod-ArgumentName">ArgumentName</a></emu-nt>).

Note: For expressiveness, the identifier of an operation argument can also be specified
as one of the keywords matching the <emu-nt><a href="#prod-ArgumentNameKeyword">ArgumentNameKeyword</a></emu-nt>
symbol without needing to escape it.

If the <emu-nt><a href="#prod-Type">Type</a></emu-nt> of an operation argument is an identifier
followed by <emu-t>?</emu-t>,
then the identifier must identify an [=interface=],
[=enumeration=], [=callback function=], [=callback interface=],
or [=typedef=].
If the operation argument type is an [=identifier=]
not followed by <emu-t>?</emu-t>, then the identifier must
identify any one of those definitions or a [=dictionary=].

If the operation argument type, after resolving typedefs,
is a [=nullable type=],
its [=nullable types/inner type=] must not be a [=dictionary type=].

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      return_type identifier(type identifier, type identifier /* , ... */);
    };
</pre>

The identifier of each argument must not be the same
as the identifier of another argument in the same operation declaration.

Each argument can be preceded by a list of
[=extended attributes=] (matching
<emu-nt><a href="#prod-ExtendedAttributeList">ExtendedAttributeList</a></emu-nt>),
which can control how a value passed as the argument will be handled in
language bindings.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      return_type identifier([<mark>extended_attributes</mark>] type identifier, [<mark>extended_attributes</mark>] type identifier /* , ... */);
    };
</pre>

<div class="example" id="example-891877a9">

    The following [=IDL fragment=]
    demonstrates how [=regular operations=]
    can be declared on an [=interface=]:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Dimensions {
          attribute unsigned long width;
          attribute unsigned long height;
        };

        [Exposed=Window]
        interface Button {

          // An operation that takes no arguments and returns a boolean.
          boolean isMouseOver();

          // Overloaded operations.
          undefined setDimensions(Dimensions size);
          undefined setDimensions(unsigned long width, unsigned long height);
        };
    </pre>
</div>

An operation or [=constructor operation=] is considered to be
<dfn id="dfn-variadic" export>variadic</dfn>
if the final argument uses the <emu-t>...</emu-t> token just
after the argument type.  Declaring an operation to be variadic indicates that
the operation can be invoked with any number of arguments after that final argument.
Those extra implied formal arguments are of the same type as the final explicit
argument in the operation declaration.  The final argument can also be omitted
when invoking the operation.  An argument must not
be declared with the <emu-t>...</emu-t> token unless it
is the final argument in the operation's argument list.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      return_type identifier(type<mark>...</mark> identifier);
      return_type identifier(type identifier, type<mark>...</mark> identifier);
    };
</pre>

[=Extended attributes=]
that [=takes an argument list|take an argument list=]
([{{LegacyFactoryFunction}}], of those
defined in this specification) and [=callback functions=]
are also considered to be [=variadic=]
when the <emu-t>...</emu-t> token is used in their argument lists.

<div class="example" id="example-c79ed320">

    The following [=IDL fragment=] defines an interface that has
    two variadic operations:

    <pre highlight="webidl">
        [Exposed=Window]
        interface IntegerSet {
          readonly attribute unsigned long cardinality;

          undefined union(long... ints);
          undefined intersection(long... ints);
        };
    </pre>

    In the JavaScript binding, variadic operations are implemented by
    functions that can accept the subsequent arguments:

    <pre highlight="js">
        var s = getIntegerSet();  // Obtain an instance of IntegerSet.

        s.union();                // Passing no arguments corresponding to 'ints'.
        s.union(1, 4, 7);         // Passing three arguments corresponding to 'ints'.
    </pre>

    A binding for a language that does not support variadic functions
    might specify that an explicit array or list of integers be passed
    to such an operation.

</div>

An argument is considered to be an <dfn id="dfn-optional-argument" export>optional argument</dfn>
if it is declared with the <emu-t>optional</emu-t> keyword.
The final argument of a [=variadic=] operation
is also considered to be an optional argument. Declaring an argument
to be optional indicates that the argument value can be omitted
when the operation is invoked.  The final argument in an
operation must not explicitly be declared to be
optional if the operation is [=variadic=].

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      return_type identifier(type identifier, optional type identifier);
    };
</pre>

Optional arguments can also have a <dfn id="dfn-optional-argument-default-value" for="optional argument" export>default value</dfn>
specified.  If the argument's identifier is followed by a U+003D (=)
and a value (matching <emu-nt><a href="#prod-DefaultValue">DefaultValue</a></emu-nt>),
then that gives the optional argument its [=optional argument/default value=].
The implicitly optional final argument of a [=variadic=]
operation must not have a default value specified.
The default value is the value to be assumed when the operation is called with the
corresponding argument omitted.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      return_type identifier(type identifier, optional type identifier = "value");
    };
</pre>

<p class="warning">
    It is strongly suggested not to use a [=optional argument/default value=]
    of <emu-val>true</emu-val> for {{boolean}}-typed arguments,
    as this can be confusing for authors who might otherwise expect the default
    conversion of <emu-val>undefined</emu-val> to be used (i.e., <emu-val>false</emu-val>).
    [[API-DESIGN-PRINCIPLES]]
</p>

If the type of an argument is a [=dictionary type=] or a [=union type=] that has
a [=dictionary type=] as one
of its [=flattened member types=], and that dictionary type and its ancestors have no
[=dictionary member/required=] [=dictionary member|members=], and the argument is either the final argument or is
followed only by [=optional arguments=], then the argument must be specified as
optional and have a default value provided.

<div class="note">

    This is to encourage API designs that do not require authors to pass an
    empty dictionary value when they wish only to use the dictionary's
    default values.

    Usually the default value provided will be <emu-t>{}</emu-t>, but in the
    case of a [=union type=] that has a dictionary type as one of its
    [=flattened member types=] a default value could be provided that
    initializes some other member of the union.
</div>

When a boolean literal token (<emu-t>true</emu-t> or <emu-t>false</emu-t>),
the <emu-t>null</emu-t> token,
an <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token, a
<emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token or one of
the three special floating point literal values (<emu-t>Infinity</emu-t>,
<emu-t>-Infinity</emu-t> or <emu-t>NaN</emu-t>) is used as the
[=optional argument/default value=],
it is interpreted in the same way as for a [=constant=].

When the <emu-t>undefined</emu-t> token is used as the
[=optional argument/default value=],
the value is the IDL {{undefined}} value.

<div id="string-literal" algorithm="value of string literal tokens">
    Optional argument default values can also be specified using a
    <emu-t class="regex"><a href="#prod-string">string</a></emu-t>
    token, whose <dfn lt="value of string literal tokens">value</dfn> is a
    [=string type=] determined as follows:

    1.  Let |S| be the sequence of [=scalar values=] matched by
        the <emu-t class="regex"><a href="#prod-string">string</a></emu-t> token
        with its leading and trailing U+0022 (") [=scalar values=] removed.
    1.  Depending on the type of the argument:
        <dl class="switch">
             :  {{DOMString}}
             :  {{USVString}}
             :  an [=enumeration=] type
             :: The value of the <emu-t class="regex"><a href="#prod-string">string</a></emu-t> token
                is |S|.
             :  {{ByteString}}
             :: Assert: |S| doesn't contain any [=code points=] higher than U+00FF.

                The value of the <emu-t class="regex"><a href="#prod-string">string</a></emu-t> token
                is the [=isomorphic encoding=] of |S|.
        </dl>
</div>

If the type of the [=optional argument=]
is an [=enumeration=], then its
[=optional argument/default value=] if specified must
be one of the [=enumeration's values=].

Optional argument default values can also be specified using the
two token value <emu-t>[]</emu-t>, which represents an empty sequence
value.  The type of this value is the same as the type of the optional
argument it is being used as the default value of.  That type
must be a [=sequence type=], a [=nullable type=] whose [=nullable types/inner type=] is a
[=sequence type=] or a [=union type=] or [=nullable type|nullable=] union type
that has a [=sequence type=] in its [=flattened member types=].

Optional argument default values can also be specified using the two token value
<emu-t>{}</emu-t>, which represents a default-initialized (as if from ES
<emu-t>null</emu-t> or an object with no properties) dictionary value.  The type
of this value is the same as the type of the optional argument it is being used
as the default value of.  That type must be a [=dictionary type=], or a [=union
type=] that has a [=dictionary type=] in its [=flattened member types=].

<div class="example" id="example-6c1a4d6e">

    The following [=IDL fragment=]
    defines an [=interface=]
    with a single [=operation=]
    that can be invoked with two different argument list lengths:

    <pre highlight="webidl">
        [Exposed=Window]
        interface ColorCreator {
          object createColor(double v1, double v2, double v3, optional double alpha);
        };
    </pre>

    It is equivalent to an [=interface=]
    that has two [=overloaded=]
    [=operations=]:

    <pre highlight="webidl">
        [Exposed=Window]
        interface ColorCreator {
          object createColor(double v1, double v2, double v3);
          object createColor(double v1, double v2, double v3, double alpha);
        };
    </pre>
</div>

<div class="example" id="example-6acab27b">

    The following [=IDL fragment=]
    defines an [=interface=]
    with an operation that takes a dictionary argument:

    <pre highlight="webidl">
        dictionary LookupOptions {
          boolean caseSensitive = false;
        };

        [Exposed=Window]
        interface AddressBook {
          boolean hasAddressForName(USVString name, optional LookupOptions options = {});
        };
    </pre>

    If <code>hasAddressForName</code> is called with only one argument, the
    second argument will be a default-initialized <code>LookupOptions</code>
    dictionary, which will cause <code>caseSensitive</code> to be set to
    <emu-t>false</emu-t>.
</div>

The following extended attributes are applicable to operations:
[{{CrossOriginIsolated}}],
[{{Default}}],
[{{Exposed}}],
[{{LegacyUnforgeable}}],
[{{NewObject}}], and
[{{SecureContext}}].

The <dfn export>method steps</dfn> of an operation |operation| should be introduced using text of the form
“The <code>|operation|(<var ignore>arg1</var>, <var ignore>arg2</var>, ...)</code> method
steps are:” followed by a list, or “The <code>|operation|(<var ignore>arg1</var>,
<var ignore>arg2</var>, ...)</code> method steps are to” followed by an inline description.

Note: When defining [=method steps=], you implicitly have access to [=this=].

<pre class="grammar" id="prod-DefaultValue">
    DefaultValue :
        ConstValue
        string
        "[" "]"
        "{" "}"
        "null"
        "undefined"
</pre>

<pre class="grammar" id="prod-Operation">
    Operation :
        RegularOperation
        SpecialOperation
</pre>

<pre class="grammar" id="prod-RegularOperation">
    RegularOperation :
        Type OperationRest
</pre>

<pre class="grammar" id="prod-SpecialOperation">
    SpecialOperation :
        Special RegularOperation
</pre>

<pre class="grammar" id="prod-Special">
    Special :
        "getter"
        "setter"
        "deleter"
</pre>

<pre class="grammar" id="prod-OperationRest">
    OperationRest :
        OptionalOperationName "(" ArgumentList ")" ";"
</pre>

<pre class="grammar" id="prod-OptionalOperationName">
    OptionalOperationName :
        OperationName
        ε
</pre>

<pre class="grammar" id="prod-OperationName">
    OperationName :
        OperationNameKeyword
        identifier
</pre>

<pre class="grammar" id="prod-OperationNameKeyword">
    OperationNameKeyword :
        "includes"
</pre>

<pre class="grammar" id="prod-ArgumentList">
    ArgumentList :
        Argument Arguments
        ε
</pre>

<pre class="grammar" id="prod-Arguments">
    Arguments :
        "," Argument Arguments
        ε
</pre>

<pre class="grammar" id="prod-Argument">
    Argument :
        ExtendedAttributeList ArgumentRest
</pre>

<pre class="grammar" id="prod-ArgumentRest">
    ArgumentRest :
        "optional" TypeWithExtendedAttributes ArgumentName Default
        Type Ellipsis ArgumentName
</pre>

<pre class="grammar" id="prod-ArgumentName">
    ArgumentName :
        ArgumentNameKeyword
        identifier
</pre>

<pre class="grammar" id="prod-Ellipsis">
    Ellipsis :
        "..."
        ε
</pre>

<div grammar-fill-with="ArgumentNameKeyword"></div>

<h5 id="idl-tojson-operation">toJSON</h5>

By declaring a <code>toJSON</code> [=regular operation=],
an [=interface=] specifies how to convert the objects that implement it to [=JSON types=].

The <code>toJSON</code> [=regular operation=] is reserved for this usage.
It must take zero arguments and return a [=JSON type=].

The <dfn id="dfn-json-types" export lt="JSON type">JSON types</dfn> are:

*   [=numeric types=],
*   {{boolean}},
*   [=string types=],
*   [=nullable types=] whose [=nullable types/inner type=] is a [=JSON type=],
*   [=annotated types=] whose [=annotated types/inner type=] is a [=JSON type=],
*   [=union types=] whose [=member types=] are [=JSON types=],
*   [=typedefs=] whose [=type being given a new name=] is a [=JSON type=],
*   [=sequence types=] whose parameterized type is a [=JSON type=],
*   [=frozen array types=] whose parameterized type is a [=JSON type=],
*   [=dictionary types=] where the types of all [=dictionary members|members=] declared on the dictionary and all its [=inherited dictionaries=] are [=JSON types=],
*   [=records=] where all of their [=map/values=] are [=JSON types=],
*   {{object}},
*   [=interface types=] that have a <code>toJSON</code> operation declared on themselves or
    one of their [=inherited interfaces=].

How the <code>toJSON</code> [=regular operation=]
is made available on an object in a language binding,
and how exactly the [=JSON types=] are converted into a JSON string,
is language binding specific.

Note: In the JavaScript language binding,
this is done by exposing a <code>toJSON</code> method
which returns the [=JSON type=]
converted into a JavaScript value
that can be turned into a JSON string
by the {{JSON.stringify()}} function.
Additionally, in the JavaScript language binding,
the <code>toJSON</code> operation can take a [{{Default}}] [=extended attribute=],
in which case the [=default toJSON steps=] are exposed instead.

<div class="example" id="tojson-example">

    The following [=IDL fragment=] defines an interface <code class="idl">Transaction</code>
    that has a <code>toJSON</code> method defined in prose:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Transaction {
          readonly attribute DOMString from;
          readonly attribute DOMString to;
          readonly attribute double amount;
          readonly attribute DOMString description;
          readonly attribute unsigned long number;
          TransactionJSON toJSON();
        };

        dictionary TransactionJSON {
          Account from;
          Account to;
          double amount;
          DOMString description;
        };
    </pre>

    The <code>toJSON</code> [=regular operation=] of <code class="idl">Transaction</code> [=interface=]
    could be defined as follows:


    <div algorithm="example tojson">

        The <code>toJSON()</code> method steps are:

        1.  Let |json| be a new [=map=].
        1.  [=list/For each=] attribute [=identifier=] |attr| in « "from", "to", "amount", "description" »:
            1.  Let |value| be the result of running the [=getter steps=] of |attr| on [=this=].
            1.  Set |json|[|attr|] to |value|.
        1.  Return |json|.
    </div>

    In the JavaScript language binding, there would exist a <code>toJSON()</code> method on
    <code class="idl">Transaction</code> objects:

    <pre highlight="js">
        // Get an instance of Transaction.
        var txn = getTransaction();

        // Evaluates to an object like this:
        // {
        //   from: "Bob",
        //   to: "Alice",
        //   amount: 50,
        //   description: "books"
        // }
        txn.toJSON();

        // Evaluates to a string like this:
        // '{"from":"Bob","to":"Alice","amount":50,"description":"books"}'
        JSON.stringify(txn);
    </pre>
</div>


<h4 id=idl-constructors oldids="Constructor" dfn>Constructor operations</h4>

If an [=interface=] has a [=constructor operation=] member (matching
<emu-nt><a href="#prod-Constructor">Constructor</a></emu-nt>), it indicates that it is possible to
create objects that [=implement=] the [=interface=] using a [=constructor=].

Multiple [=constructor operations=] may appear on a given [=interface=].
For each [=constructor operation=] on the [=interface=], there will be a way to attempt to
construct an instance by passing the specified arguments.

The <dfn export>constructor steps</dfn> of a [=constructor operation=] that is a member of an interface
named |interface| should be introduced using text of the form “The
<code>new |interface|(<var ignore>arg1</var>, <var ignore>arg2</var>, ...)</code> constructor steps
are:” followed by a list, or “The
<code>new |interface|(<var ignore>arg1</var>, <var ignore>arg2</var>, ...)</code> constructor steps
are to” followed by an inline description.

The <a>constructor steps</a> must do nothing, initialize the value passed as [=this=], or throw an
exception.

<p class=example id=example-constructor-steps>If the constructor does not initialize
[=this=], one can write “The <code>new Example(<var ignore>init</var>)</code> constructor
steps are to do nothing.”

See [[#interface-object]] for details on how a [=constructor operation=] is to be implemented.

<div class="example" id="example-94745458">

    The following IDL defines two interfaces. The second has [=constructor operations=], while the
    first does not.

    <pre highlight="webidl">
        [Exposed=Window]
        interface NodeList {
          Node item(unsigned long index);
          readonly attribute unsigned long length;
        };

        [Exposed=Window]
        interface Circle {
          constructor();
          constructor(double radius);
          attribute double r;
          attribute double cx;
          attribute double cy;
          readonly attribute double circumference;
        };
    </pre>

    A JavaScript implementation supporting these interfaces would implement a \[[Construct]]
    internal method on the <code class="idl">Circle</code> interface object which would return a
    new object that [=implements=] the interface.
    It would take either zero or one argument.

    Issue(whatwg/webidl#698): It is unclear whether the <code class="idl">NodeList</code> 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.

    <pre highlight="js">
        var x = new Circle();      // This uses the zero-argument constructor to create a
                                   // reference to a platform object that implements the
                                   // Circle interface.

        var y = new Circle(1.25);  // This also creates a Circle object, this time using
                                   // the one-argument constructor.

        var z = new NodeList();    // This would throw a TypeError, since no
                                   // constructor is declared.
    </pre>
</div>



<pre class="grammar" id="prod-Constructor">
    Constructor :
        "constructor" "(" ArgumentList ")" ";"
</pre>

<div grammar-fill-with="ArgumentList"></div>
<div grammar-fill-with="Arguments"></div>
<div grammar-fill-with="Argument"></div>
<div grammar-fill-with="ArgumentRest"></div>
<div grammar-fill-with="ArgumentName"></div>
<div grammar-fill-with="Ellipsis"></div>
<div grammar-fill-with="ArgumentNameKeyword"></div>


<h4 id="idl-stringifiers">Stringifiers</h4>

When an [=interface=] has a <dfn id="dfn-stringifier">stringifier</dfn>, it indicates that objects
that implement the interface have a non-default conversion to a string.  Stringifiers can be
specified using a <emu-t>stringifier</emu-t> keyword, which creates a stringifier operation when
used alone.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      stringifier;
    };
</pre>

Prose accompanying the interface must define
the <dfn id="dfn-stringification-behavior" export>stringification behavior</dfn>
of the interface.

The <emu-t>stringifier</emu-t> keyword
can also be placed on an [=attribute=].
In this case, the string to convert the object to is the
value of the attribute.  The <emu-t>stringifier</emu-t> keyword
must not be placed on an attribute unless
it is declared to be of type {{DOMString}} or {{USVString}}.
It also must not be placed on
a [=static attribute=].

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      stringifier attribute DOMString identifier;
    };
</pre>

On a given [=interface=], there must exist at most one stringifier.

<pre class="grammar" id="prod-Stringifier">
    Stringifier :
        "stringifier" StringifierRest
</pre>

<pre class="grammar" id="prod-StringifierRest">
    StringifierRest :
        OptionalReadOnly AttributeRest
        ";"
</pre>

<div class="example" id="example-f23c7f2e">

    The following [=IDL fragment=]
    defines an interface that will stringify to the value of its
    <code class="idl">name</code> attribute:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Student {
          constructor();
          attribute unsigned long id;
          stringifier attribute DOMString name;
        };
    </pre>

    In the JavaScript binding, using a <code class="idl">Student</code>
    object in a context where a string is expected will result in the
    value of the object's <code class="idl">name</code> property being
    used:

    <pre highlight="js">
        var s = new Student();
        s.id = 12345678;
        s.name = '周杰倫';

        var greeting = 'Hello, ' + s + '!';  // Now greeting == 'Hello, 周杰倫!'.
    </pre>

    The following [=IDL fragment=]
    defines an interface that has custom stringification behavior that is
    not specified in the IDL itself.

    <pre highlight="webidl">
        [Exposed=Window]
        interface Student {
          constructor();
          attribute unsigned long id;
          attribute DOMString? familyName;
          attribute DOMString givenName;

          stringifier;
        };
    </pre>

    Thus, there needs to be prose to explain the stringification behavior.
    We assume that the <code class="idl">familyName</code> and
    <code class="idl">givenName</code> attributes are backed by
    family name and given name concepts, respectively.

    <blockquote>

        The [=stringification behavior=] steps are:

        1. If [=this=]'s family name is null, then return [=this=]'s given name.
        2. Return the concatenation of [=this=]'s given name, followed by U+0020 SPACE, followed by [=this=]'s family name.

    </blockquote>

    A JavaScript implementation of the IDL would behave as follows:

    <pre highlight="js">
        var s = new Student();
        s.id = 12345679;
        s.familyName = 'Smithee';
        s.givenName = 'Alan';

        var greeting = 'Hi ' + s;  // Now greeting == 'Hi Alan Smithee'.
    </pre>
</div>


<h4 id="idl-special-operations">Special operations</h4>

A <dfn id="dfn-special-operation" export>special operation</dfn> is a
declaration of a certain kind of special behavior on objects implementing
the interface on which the special operation declarations appear.
Special operations are declared by using a
<dfn id="dfn-special-keyword" export>special keyword</dfn>
in an operation declaration.

There are three kinds of special operations. The table below indicates
for a given kind of special operation what special keyword
is used to declare it and what the purpose of the special operation is:

<table class="vert data">
    <tr>
        <th>Special operation</th>
        <th>Keyword</th>
        <th>Purpose</th>
    </tr>
    <tr>
        <td><dfn id="dfn-getter" export lt="getter">Getters</dfn></td>
        <td><emu-t>getter</emu-t></td>
        <td>Defines behavior for when an object is indexed for property retrieval.</td>
    </tr>
    <tr>
        <td><dfn id="dfn-setter" export lt="setter">Setters</dfn></td>
        <td><emu-t>setter</emu-t></td>
        <td>Defines behavior for when an object is indexed for property
        assignment or creation.</td>
    </tr>
    <tr>
        <td><dfn id="dfn-deleter" export lt="deleter">Deleters</dfn></td>
        <td><emu-t>deleter</emu-t></td>
        <td>Defines behavior for when an object is indexed for property deletion.</td>
    </tr>
</table>

Not all language bindings support all of the four kinds of special
object behavior.  When special operations are declared using
operations with no identifier, then in language bindings that do
not support the particular kind of special operations there simply
will not be such functionality.

<div class="example" id="example-a42afb64">

    The following IDL fragment defines an interface with a getter and a setter:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Dictionary {
          readonly attribute unsigned long propertyCount;

          getter double (DOMString propertyName);
          setter undefined (DOMString propertyName, double propertyValue);
        };
    </pre>

    In language bindings that do not support property getters and setters,
    objects implementing [=Dictionary=] will not
    have that special behavior.

</div>

Defining a special operation  with an [=identifier=]
is equivalent to separating the special operation out into its own
declaration without an identifier.  This approach is allowed to
simplify [=method steps=] of an interface's operations.

<div class="example" id="example-50d7ab88">

    The following two interfaces are equivalent:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Dictionary {
          readonly attribute unsigned long propertyCount;

          getter double getProperty(DOMString propertyName);
          setter undefined setProperty(DOMString propertyName, double propertyValue);
        };
    </pre>
    <pre highlight="webidl">
        [Exposed=Window]
        interface Dictionary {
          readonly attribute unsigned long propertyCount;

          double getProperty(DOMString propertyName);
          undefined setProperty(DOMString propertyName, double propertyValue);

          getter double (DOMString propertyName);
          setter undefined (DOMString propertyName, double propertyValue);
        };
    </pre>
</div>

A given [=special keyword=] must not
appear twice on an operation.

Getters and setters come in two varieties: ones that
take a {{DOMString}} as a property name,
known as
<dfn id="dfn-named-property-getter" export lt="named property getter">named property getters</dfn> and
<dfn id="dfn-named-property-setter" export lt="named property setter">named property setters</dfn>,
and ones that take an {{unsigned long}}
as a property index, known as
<dfn id="dfn-indexed-property-getter" export lt="indexed property getter">indexed property getters</dfn> and
<dfn id="dfn-indexed-property-setter" export lt="indexed property setter">indexed property setters</dfn>.
There is only one variety of deleter:
<dfn id="dfn-named-property-deleter" export lt="named property deleter">named property deleters</dfn>.
See [[#idl-indexed-properties]]
and [[#idl-named-properties]]
for details.

On a given [=interface=],
there must exist at most one
[=named property deleter=],
and at most one of each variety of getter and setter.

If an interface has a setter of a given variety,
then it must also have a getter of that
variety.  If it has a [=named property deleter=],
then it must also have a
[=named property getter=].

Special operations declared using operations must not
be [=variadic=] nor have any
[=optional arguments=].

If an object implements more than one [=interface=]
that defines a given special operation, then it is undefined which (if any)
special operation is invoked for that operation.


<h5 id="idl-indexed-properties" dfn export>Indexed properties</h5>

An [=interface=] that defines an [=indexed property getter=]
is said to <dfn id="dfn-support-indexed-properties" export>support indexed properties</dfn>.
By extension, a [=platform object=]
is said to [=support indexed properties=] if
it implements an [=interface=] that itself does.

If an interface [=support indexed properties|supports indexed properties=],
then the interface definition must be accompanied by
a description of what indices the object can be indexed with at
any given time. These indices are called the <dfn id="dfn-supported-property-indices" export>supported property indices</dfn>.

Interfaces that [=support indexed properties=] must define
an [=integer types|integer-typed=] [=attribute=] named "<code>length</code>".

Indexed property getters must
be declared to take a single {{unsigned long}} argument.
Indexed property setters must
be declared to take two arguments, where the first is an {{unsigned long}}.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      getter type identifier(unsigned long identifier);
      setter type identifier(unsigned long identifier, type identifier);

      getter type (unsigned long identifier);
      setter type (unsigned long identifier, type identifier);
    };
</pre>

The following requirements apply to the definitions of indexed property getters and setters:

*   If an [=indexed property getter=] was specified using an [=operation=]
    with an [=identifier=],
    then the value returned when indexing the object with a given [=supported property indices|supported property index=]
    is the value that would be returned by invoking the operation, passing
    the index as its only argument.  If the operation used to declare the indexed property getter
    did not have an identifier, then the interface definition must be accompanied
    by a description of how to <dfn id="dfn-determine-the-value-of-an-indexed-property" export>determine the value of an indexed property</dfn>
    for a given index.
*   If an [=indexed property setter=] was specified using an operation
    with an identifier,
    then the behavior that occurs when indexing the object for property assignment with a given supported property index and value
    is the same as if the operation is invoked, passing
    the index as the first argument and the value as the second argument.  If the operation used to declare the indexed property setter
    did not have an identifier, then the interface definition must be accompanied
    by a description of how to <dfn id="dfn-set-the-value-of-an-existing-indexed-property" export>set the value of an existing indexed property</dfn>
    and how to <dfn id="dfn-set-the-value-of-a-new-indexed-property" export>set the value of a new indexed property</dfn>
    for a given property index and value.

<div class="note">

    Note that if an [=indexed property getter=] or
    [=indexed property setters|setter=]
    is specified using an [=operation=] with an [=identifier=],
    then indexing an object with an integer that is not a [=supported property indices|supported property index=]
    does not necessarily elicit the same behavior as invoking the operation with that index.  The actual behavior in this
    case is language binding specific.

    In the JavaScript language binding, a regular property lookup is done.  For example, take the following IDL:

    <pre highlight="webidl">
        [Exposed=Window]
        interface A {
          getter DOMString toWord(unsigned long index);
        };
    </pre>

    Assume that an object implementing <code class="idl">A</code> has [=supported property indices=]
    in the range 0 ≤ <var ignore>index</var> &lt; 2.  Also assume that toWord is defined to return
    its argument converted into an English word.  The behavior when invoking the
    [=operation=] with an out of range index
    is different from indexing the object directly:

    <pre highlight="js">
        var a = getA();

        a.toWord(0);  // Evalautes to "zero".
        a[0];         // Also evaluates to "zero".

        a.toWord(5);  // Evaluates to "five".
        a[5];         // Evaluates to undefined, since there is no property "5".
    </pre>
</div>

<div class="example" id="example-5c76d88c">

    The following [=IDL fragment=] defines an interface
    <code class="idl">OrderedMap</code> which allows
    retrieving and setting values by name or by index number:

    <pre highlight="webidl">
        [Exposed=Window]
        interface OrderedMap {
          readonly attribute unsigned long size;

          getter any getByIndex(unsigned long index);
          setter undefined setByIndex(unsigned long index, any value);

          getter any get(DOMString name);
          setter undefined set(DOMString name, any value);
        };
    </pre>

    Since all of the special operations are declared using
    operations with identifiers, the only additional prose
    that is necessary is that which describes what keys those sets
    have.  Assuming that the <code>get()</code> operation is
    defined to return <emu-val>null</emu-val> if an
    attempt is made to look up a non-existing entry in the
    <code class="idl">OrderedMap</code>, then the following
    two sentences would suffice:

    <blockquote>

        An object <var ignore>map</var> implementing <code class="idl">OrderedMap</code>
        supports indexed properties with indices in the range
        0 ≤ <var ignore>index</var> &lt; <code>map.size</code>.

        Such objects also support a named property for every name that,
        if passed to <code>get()</code>, would return a non-null value.

    </blockquote>

    As described in [[#js-legacy-platform-objects]],
    a JavaScript implementation would create
    properties on a [=legacy platform object=] implementing
    <code class="idl">OrderedMap</code> that correspond to
    entries in both the named and indexed property sets.
    These properties can then be used to interact
    with the object in the same way as invoking the object's
    methods, as demonstrated below:

    <pre highlight="js">
        // Assume map is a legacy platform object implementing the OrderedMap interface.
        var map = getOrderedMap();
        var x, y;

        x = map[0];       // If map.length &gt; 0, then this is equivalent to:
                          //
                          //   x = map.getByIndex(0)
                          //
                          // since a property named "0" will have been placed on map.
                          // Otherwise, x will be set to undefined, since there will be
                          // no property named "0" on map.

        map[1] = false;   // This will do the equivalent of:
                          //
                          //   map.setByIndex(1, false)

        y = map.apple;    // If there exists a named property named "apple", then this
                          // will be equivalent to:
                          //
                          //   y = map.get('apple')
                          //
                          // since a property named "apple" will have been placed on
                          // map.  Otherwise, y will be set to undefined, since there
                          // will be no property named "apple" on map.

        map.berry = 123;  // This will do the equivalent of:
                          //
                          //   map.set('berry', 123)

        delete map.cake;  // If a named property named "cake" exists, then the "cake"
                          // property will be deleted, and then the equivalent to the
                          // following will be performed:
                          //
                          //   map.remove("cake")
    </pre>
</div>


<h5 id="idl-named-properties" dfn export>Named properties</h5>

An [=interface=] that defines a [=named property getter=]
is said to <dfn id="dfn-support-named-properties" export>support named properties</dfn>.
By extension, a [=platform object=]
is said to [=support named properties=] if
it implements an [=interface=] that itself does.

If an interface [=support named properties|supports named properties=],
then the interface definition must be accompanied by
a description of the ordered set of names that can be used to index the object
at any given time.  These names are called the
<dfn id="dfn-supported-property-names" export>supported property names</dfn>.

Named property getters and deleters must
be declared to take a single {{DOMString}} argument.
Named property setters must
be declared to take two arguments, where the first is a {{DOMString}}.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      getter type identifier(DOMString identifier);
      setter type identifier(DOMString identifier, type identifier);
      deleter type identifier(DOMString identifier);

      getter type (DOMString identifier);
      setter type (DOMString identifier, type identifier);
      deleter type (DOMString identifier);
    };
</pre>

The following requirements apply to the definitions of named property getters, setters and deleters:

*   If a [=named property getter=] was specified using an [=operation=]
    with an [=identifier=],
    then the value returned when indexing the object with a given [=supported property name=]
    is the value that would be returned by invoking the operation, passing
    the name as its only argument.  If the operation used to declare the named property getter
    did not have an identifier, then the interface definition must be accompanied
    by a description of how to <dfn id="dfn-determine-the-value-of-a-named-property" export>determine the value of a named property</dfn>
    for a given property name.
*   If a [=named property setter=] was specified using an operation
    with an identifier,
    then the behavior that occurs when indexing the object for property assignment with a given supported property name and value
    is the same as if the operation is invoked, passing
    the name as the first argument and the value as the second argument.  If the operation used to declare the named property setter
    did not have an identifier, then the interface definition must be accompanied
    by a description of how to <dfn id="dfn-set-the-value-of-an-existing-named-property" export>set the value of an existing named property</dfn>
    and how to <dfn id="dfn-set-the-value-of-a-new-named-property" export>set the value of a new named property</dfn>
    for a given property name and value.
*   If a [=named property deleter=] was specified using an operation
    with an identifier,
    then the behavior that occurs when indexing the object for property deletion with a given supported property name
    is the same as if the operation is invoked, passing
    the name as the only argument.  If the operation used to declare the named property deleter
    did not have an identifier, then the interface definition must be accompanied
    by a description of how to <dfn id="dfn-delete-an-existing-named-property" export>delete an existing named property</dfn>
    for a given property name.

Note: As with [=indexed properties=],
if an [=named property getter=],
[=named property setters|setter=] or
[=named property deleters|deleter=]
is specified using an [=operation=] with an [=identifier=],
then indexing an object with a name that is not a [=supported property name=]
does not necessarily elicit the same behavior as invoking the operation with that name; the behavior
is language binding specific.


<h4 id="idl-static-attributes-and-operations">Static attributes and operations</h4>

<dfn id="dfn-static-attribute" export>Static attributes</dfn> and
<dfn id="dfn-static-operation" export>static operations</dfn> are ones that
are not associated with a particular instance of the
[=interface=]
on which it is declared, and is instead associated with the interface
itself.  Static attributes and operations are declared by using the
<emu-t>static</emu-t> keyword in their declarations.

It is language binding specific whether it is possible to invoke
a static operation or get or set a static attribute through a reference
to an instance of the interface.

<pre class="grammar" id="prod-StaticMember">
    StaticMember :
        "static" StaticMemberRest
</pre>

<pre class="grammar" id="prod-StaticMemberRest">
    StaticMemberRest :
        OptionalReadOnly AttributeRest
        RegularOperation
</pre>

<div class="example" id="example-639bc49b">

    The following [=IDL fragment=] defines an interface
    <code class="idl">Circle</code> that has a static
    operation declared on it:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Point { /* ... */ };

        [Exposed=Window]
        interface Circle {
          attribute double cx;
          attribute double cy;
          attribute double radius;

          static readonly attribute long triangulationCount;
          static Point triangulate(Circle c1, Circle c2, Circle c3);
        };
    </pre>

    In the JavaScript language binding, the [=function object=] for
    <code>triangulate</code> and the accessor property for <code>triangulationCount</code>
    will exist on the [=interface object=]
    for <code class="idl">Circle</code>:

    <pre highlight="js">
        var circles = getCircles();           // an Array of Circle objects

        typeof Circle.triangulate;            // Evaluates to "function"
        typeof Circle.triangulationCount;     // Evaluates to "number"
        Circle.prototype.triangulate;         // Evaluates to undefined
        Circle.prototype.triangulationCount;  // Also evaluates to undefined
        circles[0].triangulate;               // As does this
        circles[0].triangulationCount;        // And this

        // Call the static operation
        var triangulationPoint = Circle.triangulate(circles[0], circles[1], circles[2]);

        // Find out how many triangulations we have done
        window.alert(Circle.triangulationCount);
    </pre>
</div>


<h4 id="idl-overloading">Overloading</h4>

If a [=regular operation=]
or [=static operation=]
defined on an [=interface=]
has an [=identifier=]
that is the same as the identifier of another operation on that
interface of the same kind (regular or static), then the operation is said to be
<dfn id="dfn-overloaded" export>overloaded</dfn>.  When the identifier
of an overloaded operation is used to invoke one of the
operations on an object that implements the interface, the
number and types of the arguments passed to the operation
determine which of the overloaded operations is actually
invoked.
[=Constructor operations=] can be overloaded too.
There are some restrictions on the arguments
that overloaded operations and constructors can be
specified to take, and in order to describe these restrictions,
the notion of an <em>effective overload set</em> is used.

A set of overloaded [=operations=] must either:

* contain no [=operations=] whose [=return type=] is a [=promise type=];
* only contain [=operations=] whose [=return type=] is a [=promise type=].

[=Operations=] must not be overloaded across
[=interface=],
[=partial interface=],
[=interface mixin=], and
[=partial interface mixin=]
definitions.

<div class="note">

    For example, the overloads for both <var ignore>f</var> and <var ignore>g</var>
    are disallowed:

    <pre highlight="webidl">
        [Exposed=Window]
        interface A {
          undefined f();
        };

        partial interface A {
          undefined f(double x);
          undefined g();
        };

        partial interface A {
          undefined g(DOMString x);
        };
    </pre>

    Note that [=constructor operations=] and
    [{{LegacyFactoryFunction}}]
    [=extended attributes=] are disallowed from appearing
    on [=partial interface=] definitions,
    so there is no need to also disallow overloading for constructors.

</div>

An <dfn id="dfn-effective-overload-set" export>effective overload set</dfn>
represents the allowable invocations for a particular
[=operation=],
constructor (specified with a [=constructor operation=]
or [{{LegacyFactoryFunction}}]), or
[=callback function=].
The algorithm to [=compute the effective overload set=]
operates on one of the following four types of IDL constructs, and listed with them below are
the inputs to the algorithm needed to compute the set.

 :  For regular operations
 :  For static operations
 :: *   the [=interface=] on which the [=operations=] are to be found
    *   the [=identifier=] of the operations
    *   the number of arguments to be passed
 :  For constructors
 :: *   the [=interface=] on which the [=constructor operations=] are to be found
    *   the number of arguments to be passed
 :  For legacy factory functions
 :: *   the [=interface=] on which the [{{LegacyFactoryFunction}}] [=extended attributes=] are to be found
    *   the [=identifier=] of the legacy factory function
    *   the number of arguments to be passed

An [=effective overload set=] is used, among other things, to determine whether there are
ambiguities in the overloaded operations and constructors specified on an interface.

The [=set/items=] of an [=effective overload set=] are [=tuples=] of the form
([=effective overload set tuple/callable=], [=type list=], [=optionality list=])
whose [=tuple/items=] are described below:

*   A <dfn for="effective overload set tuple">callable</dfn> is an [=operation=]
    if the [=effective overload set=] is for [=regular operations=],
    [=static operations=], or [=constructor operations=]; and it is an [=extended attribute=]
    if the [=effective overload set=] is for [=legacy factory functions=].
*   A <dfn>type list</dfn> is a [=list=] of IDL types.
*   An <dfn>optionality list</dfn> is a [=list=] of
    three possible <dfn id="dfn-optionality-value" export>optionality values</dfn>
    – "required", "optional" or "variadic" –
    indicating whether the argument at a given index was
    declared as being [=optional argument|optional=]
    or corresponds to a [=variadic=] argument.

Each [=tuple=] represents an allowable invocation of the operation,
constructor, or callback function with an argument value list of the given types.
Due to the use of [=optional arguments=]
and [=variadic=] operations
and constructors, there may be multiple items in an [=effective overload set=] identifying
the same operation or constructor.

<div algorithm="compute the effective overload set">
    The algorithm below describes how to <dfn>compute the effective overload set</dfn>.
    The following input variables are used, if they are required:

    *   the identifier of the operation or legacy factory function is |A|
    *   the argument count is |N|
    *   the interface is |I|

    Whenever an argument of an extended attribute is mentioned,
    it is referring to an argument of the extended attribute's
    [=takes a named argument list|named argument list=].

    1.  Let |S| be an [=ordered set=].
    1.  Let |F| be an [=ordered set=] with [=set/items=] as follows,
        according to the kind of [=effective overload set=]:
        <dl class="switch">
             :  For regular operations
             :: The elements of |F| are the [=regular operations=] with
                identifier |A| defined on interface |I|.
             :  For static operations
             :: The elements of |F| are the [=static operations=] with
                identifier |A| defined on interface |I|.
             :  For constructors
             :: The elements of |F| are the
                [=constructor operations=] on interface |I|.
             :  For legacy factory functions
             :: The elements of |F| are the
                [{{LegacyFactoryFunction}}]
                [=extended attributes=] on interface |I| whose
                [=takes a named argument list|named argument lists'=]
                identifiers are |A|.
        </dl>

    1.  Let |maxarg| be the maximum number of arguments the operations,
        legacy factory functions, or callback functions in |F| are declared to take.
        For [=variadic=] operations and legacy factory functions,
        the argument on which the ellipsis appears counts as a single argument.

        Note: So <code>undefined f(long x, long... y);</code> is considered to be declared to take two arguments.
    1.  Let |max| be <a abstract-op>max</a>(|maxarg|, |N|).
    1.  [=set/For each=] operation or extended attribute |X| in |F|:
        1.  Let |arguments| be the [=list=] of arguments |X| is declared to take.
        1.  Let |n| be the [=list/size=] of |arguments|.
        1.  Let |types| be a [=type list=].
        1.  Let |optionalityValues| be an [=optionality list=].
        1.  [=list/For each=] |argument| in |arguments|:
            1.  [=list/Append=] the type of |argument| to |types|.
            1.  [=list/Append=] "variadic" to |optionalityValues| if |argument| is a final, variadic argument,
                "optional" if |argument| is [=optional argument|optional=],
                and "required" otherwise.
        1.  [=set/Append=] the [=tuple=] (|X|, |types|, |optionalityValues|) to |S|.
        1.  If |X| is declared to be [=variadic=], then:
            1.  [=list/For each=] |i| in [=the range=] |n| to |max| − 1, inclusive:
                1.  Let |t| be a [=type list=].
                1.  Let |o| be an [=optionality list=].
                1.  [=list/For each=] |j| in [=the range=] 0 to |n| − 1, inclusive:
                    1.  [=list/Append=] |types|[|j|] to |t|.
                    1.  [=list/Append=] |optionalityValues|[|j|] to |o|.
                1.  [=list/For each=] |j| in [=the range=] |n| to |i|, inclusive:
                    1.  [=list/Append=] |types|[|n| − 1] to |t|.
                    1.  [=list/Append=] "variadic" to |o|.
                1.  [=set/Append=] the [=tuple=] (|X|, |t|, |o|) to |S|.
        1.  Let |i| be |n| − 1.
        1.  [=iteration/While=] |i| ≥ 0:
            1.  If |arguments|[|i|] is not [=optional argument|optional=]
                (i.e., it is not marked as "optional" and is not
                a final, variadic argument), then [=iteration/break=].
            1.  Let |t| be a [=type list=].
            1.  Let |o| be an [=optionality list=].
            1.  [=list/For each=] |j| in [=the range=] 0 to |i| − 1, inclusive:
                1.  [=list/Append=] |types|[|j|] to |t|.
                1.  [=list/Append=] |optionalityValues|[|j|] to |o|.
            1.  [=set/Append=] the [=tuple=] (|X|, |t|, |o|) to |S|.

                Note: if |i| is 0, this means to add to |S| the tuple (|X|, « », « »);
                (where "« »" represents an [=list/is empty|empty list=]).
            1.  Set |i| to |i| − 1.
    1.  Return |S|.
</div>

<div class="example" id="example-95a1dcae">

    For the following interface:

    <pre highlight="webidl">
        [Exposed=Window]
        interface A {
          /* f1 */ undefined f(DOMString a);
          /* f2 */ undefined f(Node a, DOMString b, double... c);
          /* f3 */ undefined f();
          /* f4 */ undefined f(Event a, DOMString b, optional DOMString c, double... d);
        };
    </pre>

    assuming <code class="idl">Node</code> and <code class="idl">Event</code>
    are two other interfaces of which no object can implement both,
    the [=effective overload set=]
    for [=regular operations=] with
    identifier <code>f</code> and argument count 4 is:

    <pre class="set">
      «
        (f1, « DOMString »,                           « required »),
        (f2, « Node, DOMString »,                     « required, required »),
        (f2, « Node, DOMString, double »,             « required, required, variadic »),
        (f2, « Node, DOMString, double, double »,     « required, required, variadic, variadic »),
        (f3, « »,                                     « »),
        (f4, « Event, DOMString »,                    « required, required »),
        (f4, « Event, DOMString, DOMString »,         « required, required, optional »),
        (f4, « Event, DOMString, DOMString, double », « required, required, optional, variadic »)
      »
    </pre>
</div>

Two types are <dfn id="dfn-distinguishable" export>distinguishable</dfn> if
the following algorithm returns <i>true</i>.

<ol class="algorithm">
1.  If one type [=includes a nullable type=]
    and the other type either
    [=includes a nullable type=],
    is a [=union type=] with [=flattened member types=]
    including a [=dictionary type=], or
    is a [=dictionary type=],
    return <i>false</i>.
    <div class="example" id="example-distinguishability-nullable">
        None of the following pairs are distinguishable:
        <ul>
            <li>
                <code>{{double}}?</code> and
                <code>Dictionary1</code>
            </li>
            <li>
                <code>(Interface1 or {{long}})?</code> and
                <code>(Interface2 or {{DOMString}})?</code>
            </li>
            <li>
                <code>(Interface1 or {{long}}?)</code> and
                <code>(Interface2 or {{DOMString}})?</code>
            </li>
            <li>
                <code>(Interface1 or {{long}}?)</code> and
                <code>(Interface2 or {{DOMString}}?)</code>
            </li>
            <li>
                <code>(Dictionary1 or {{long}})</code> and
                <code>(Interface2 or {{DOMString}})?</code>
            </li>
            <li>
                <code>(Dictionary1 or {{long}})</code> and
                <code>(Interface2 or {{DOMString}}?)</code>
            </li>
        </ul>
    </div>
1.  If both types are either a [=union type=] or [=nullable type|nullable=] [=union type=],
    return <i>true</i> if each member type of the one
    is distinguishable with each member type of the other,
    or <i>false</i> otherwise.
1.  If one type is a [=union type=] or nullable union type,
    return <i>true</i> if each
    [=member type=] of the union type is distinguishable
    with the non-union type,
    or <i>false</i> otherwise.
1.  Consider the two "innermost" types derived by taking each type's [=annotated types/inner type=]
    if it is an [=annotated type=], and then taking its [=nullable types/inner type=] inner type
    if the result is a [=nullable type=]. If these two innermost types appear or are in categories
    appearing in the following table and there is a “●” mark in the corresponding entry
    or there is a letter in the corresponding entry and the designated additional
    requirement below the table is satisfied, then return <i>true</i>.
    Otherwise return <i>false</i>.

    Categories:
    <dl>
        <dt>interface-like</dt>
        <dd>
            * [=interface types=]
            * [=buffer source types=]
        <dt>dictionary-like</dt>
        <dd>
            * [=dictionary types=]
            * [=record types=]
            * [=callback interface types=]
        <dt>sequence-like</dt>
        <dd>
            * [=sequence types=]
            * [=frozen array types=]
    </dl>

    <table id="distinguishable-table" class="matrix data complex">
        <thead>
            <tr>
                <th class="corner"></th>
                <th><div><span>undefined</span></div>
                <th><div><span>boolean</span></div>
                <th><div><span>numeric types</span></div>
                <th><div><span>bigint</span></div>
                <th><div><span>string types</span></div>
                <th><div><span>object</span></div>
                <th><div><span>symbol</span></div>
                <th><div><span>interface-like</span></div>
                <th><div><span>callback function</span></div>
                <th><div><span>dictionary-like</span></div>
                <th><div><span>async iterable</span></div>
                <th><div><span>sequence-like</span></div>
        </thead>
        <tr>
            <th>undefined
            <td>
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>
            <td>●
            <td>●
        <tr>
            <th>boolean
            <td class="belowdiagonal">
            <td>
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
        <tr>
            <th>numeric types
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td>
            <td>(b)
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
        <tr>
            <th>bigint
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td>
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
        <tr>
            <th>string types
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td>
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
            <td>(d)
            <td>●
        <tr>
            <th>object
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td>
            <td>●
            <td>
            <td>
            <td>
            <td>
            <td>
        <tr>
            <th>symbol
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td>
            <td>●
            <td>●
            <td>●
            <td>●
            <td>●
        <tr>
            <th>interface-like
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td>(a)
            <td>●
            <td>●
            <td>●
            <td>●
        <tr>
            <th>callback function
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td>
            <td>(c)
            <td>●
            <td>●
        <tr>
            <th>dictionary-like
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td>
            <td>●
            <td>●
        <tr>
            <th>async iterable
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td>
            <td>
        <tr>
            <th>sequence-like
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td class="belowdiagonal">
            <td>
    </table>

    <ol type="a">
        1.  The two identified interface-like types are
            not the same, and no single [=platform object=] implements both
            interface-like types.
        1.  The types are distinguishable, but there is
            <a href="#limit-bigint-numeric-overloading">a separate restriction on their use in
            overloading</a> below. Please also note <a href="#limit-bigint-numeric-unions">the
            advice about using unions of these types</a>.
        1.  A [=callback function=] that does not have
            [{{LegacyTreatNonObjectAsNull}}] extended attribute is
            distinguishable from a type in the dictionary-like category.
            <div class="note">
              For example, when converting an ECMAScript value to [=union
              type=] which includes a [=callback function=] and a
              dictionary-like type, if the value is [=ECMAScript/callable=],
              then it is converted to a [=callback function=]. Otherwise, it is
              converted to a dictionary-like type.
            </div>
        1.  The types are distinguishable, but when converting from an ECMAScript value,
            a [=string object=] is never converted to an [=async iterable type=]
            (even if it has a {{%Symbol.iterator%}} method), if a [=string type=]
            is also in the overload set or union.
    </ol>

    <div class="example" id="example-distinguishability-diff-types">
        {{double}} and {{DOMString}} are distinguishable because
        there is a ● at the intersection of [=numeric types=] with [=string types=].
    </div>

    <div class="example" id="example-distinguishability-same-category">
        {{double}} and {{long}} are not distinguishable because they are both [=numeric types=],
        and there is no ● or letter at the intersection of [=numeric types=] with [=numeric types=].
    </div>

    <div class="example" id="example-distinguishability-callback-interfaces">
        Given:

        <pre highlight="idl">
            callback interface CBIface {
                undefined handle();
            };

            [Exposed=Window]
            interface Iface {
                attribute DOMString attr2;
            };

            dictionary Dict {
                DOMString field1;
            };
        </pre>

        <code>CBIface</code> is distinguishable from <code>Iface</code>
        because there's a ● at the intersection of dictionary-like and interface-like,
        but it is not distinguishable from <code>Dict</code>
        because there's no ● at the intersection of dictionary-like and itself.
    </div>

    <div class="example" id="example-distinguishability-promises">
        [=Promise types=] do not appear in the above table, and as a consequence are
        not distinguishable with any other type.
    </div>

</ol>

If there is more than one [=list/item=] in an [=effective overload set=]
that has a given [=type list=] [=list/size=],
then for those items there must be an index |i| such that
for each pair of items the types at index |i| are [=distinguishable=].
The lowest such index is termed the <dfn id="dfn-distinguishing-argument-index" export>distinguishing argument index</dfn>
for the items of the [=effective overload set=] with the given type list size.

<p id="limit-bigint-numeric-overloading">An [=effective overload set=] must not contain more than
one [=list/item=] with the same [=type list=] [=list/size=], where one [=list/item=] has a
{{bigint}} argument at the [=distinguishing argument index=] and another has a [=numeric type=]
argument at the [=distinguishing argument index=].

<div class="example" id="example-cfba37ec">

    Consider the [=effective overload set=] shown in the previous example.
    There are multiple items in the set with type lists 2, 3 and 4.
    For each of these type list size, the [=distinguishing argument index=] is 0, since <code class="idl">Node</code> and
    <code class="idl">Event</code> are [=distinguishable=].

    The following use of overloading however is invalid:

    <pre highlight="webidl">
        [Exposed=Window]
        interface B {
          undefined f(DOMString x);
          undefined f(USVString x);
        };
    </pre>

    since {{DOMString}} and {{USVString}} are not distinguishable.

</div>

In addition, for each index |j|, where |j| is less than the
[=distinguishing argument index=]
for a given type list size, the types at index |j| in
all of the items' type lists must be the same,
and the [=optionality values=] at index |j| in all of the items' optionality lists must
be the same.

<div class="example" id="example-dab6ca0a">

    The following is invalid:

    <pre highlight="webidl">
        [Exposed=Window]
        interface B {
          /* f1 */ undefined f(DOMString w);
          /* f2 */ undefined f(long w, double x, Node y, Node z);
          /* f3 */ undefined f(double w, double x, DOMString y, Node z);
        };
    </pre>

    For argument count 4, the [=effective overload set=] is:

    <pre class="set">
      «
        (f1, « DOMString »,                       « required »),
        (f2, « long, double, Node, Node »,        « required, required, required, required »),
        (f3, « double, double, DOMString, Node », « required, required, required, required »)
      »
    </pre>

    Looking at items with type list size 4, the
    [=distinguishing argument index=]
    is 2, since <code class="idl">Node</code> and
    {{DOMString}} are [=distinguishable=].
    However, since the arguments in these two overloads at index 0 are different,
    the overloading is invalid.

</div>


<h5 id="idl-overloading-vs-union">Overloading vs. union types</h5>

<i>This section is informative.</i>

<div class="non-normative">

For specifications defining IDL [=operations=], it might seem that [=overloaded|overloads=] and a
combination of [=union types=] and [=optional arguments=] have some feature overlap.

It is first important to note that [=overloaded|overloads=] have different behaviors than [=union
types=] or [=optional arguments=], and one <em>cannot</em> be fully defined using the other (unless,
of course, additional prose is provided, which can defeat the purpose of the Web IDL type system).
For example, consider the {{CanvasDrawPath/stroke()}} operations defined on the {{CanvasDrawPath}}
interface [[HTML]]:

<pre highlight="webidl">
    interface CanvasDrawPathExcerpt {
      undefined stroke();
      undefined stroke(Path2D path);
    };
</pre>

Per the JavaScript language binding, calling <code>stroke(undefined)</code> on an object
implementing <code class="idl">CanvasDrawPathExcerpt</code> would attempt to call the second
overload, yielding a {{TypeError}} since <emu-val>undefined</emu-val> cannot be <a
href="#js-to-interface">converted</a> to a {{Path2D}}. However, if the operations were instead
defined with [=optional arguments=] and merged into one,

<pre highlight="webidl">
    interface CanvasDrawPathExcerptOptional {
      undefined stroke(optional Path2D path);
    };
</pre>

the [=overload resolution algorithm=] would treat the <var ignore>path</var> argument as missing
given the same call <code>stroke(undefined)</code>, and not throw any exceptions.

Note: For this particular example, the latter behavior is actually what Web developers would
generally expect. If {{CanvasDrawPath}} were to be designed today, [=optional arguments=] would be
used for <code class="idl">stroke()</code>.

Additionally, there are semantic differences as well. [=Union types=] are usually used in the sense
that "any of the types would work in about the same way". In contrast, [=overloaded=] operations are
designed to map well to language features such as C++ overloading, and are usually a better fit for
operations with more substantial differences in what they do given arguments of different types.
However, in most cases, operations with such substantial differences are best off with different
names to avoid confusion for Web developers, since the JavaScript language does not provide
language-level overloading. As such, overloads are rarely appropriate for new APIs, instead often
appearing in legacy APIs or in specialized circumstances.

That being said, we offer the following recommendations and examples in case of difficulties to
determine what Web IDL language feature to use:

*   In the unusual case where the operation needs to return values of different types for different
    argument types, [=overloaded|overloading=] will result in more expressive IDL fragments. <span
    class="note">This is almost never appropriate API design, and separate operations with distinct
    names usually are a better choice for such cases.</span>

    Suppose there is an operation <code class="idl">calculate()</code> that accepts a {{long}},
    {{DOMString}}, or <code class="idl">CalculatableInterface</code> (an [=interface type=]) as its
    only argument, and returns a value of the same type as its argument. It would be clearer to
    write the IDL fragment using [=overloaded=] operations as

    <pre highlight="webidl">
        interface A {
          long calculate(long input);
          DOMString calculate(DOMString input);
          CalculatableInterface calculate(CalculatableInterface input);
        };
    </pre>

    than using a [=union type=] with a [=typedef=] as

    <pre highlight="webidl">
        typedef (long or DOMString or CalculatableInterface) Calculatable;
        interface A {
          Calculatable calculate(Calculatable input);
        };
    </pre>

    which does not convey the fact that the return value is always of the same type as <var
    ignore>input</var>.

    If the specified <code class="idl">calculate()</code> is a new API and does not have any
    compatibility concerns, it is suggested to use different names for the overloaded operations,
    perhaps as

    <pre highlight="webidl">
        interface A {
          long calculateNumber(long input);
          DOMString calculateString(DOMString input);
          CalculatableInterface calculateCalculatableInterface(CalculatableInterface input);
        };
    </pre>

    which allows Web developers to write explicit and unambiguous code.

*   When the operation has significantly different semantics for different argument types or
    lengths, [=overloaded|overloading=] is preferred. Again, in such scenarios, it is usually better
    to create separate operations with distinct names, but legacy APIs sometimes follow this
    pattern.

    As an example, the {{CSS/supports(property, value)}} and {{CSS/supports(conditionText)}}
    operations of the {{CSS}} interface are defined as the
    following IDL fragment [[CSS3-CONDITIONAL]] [[CSSOM]].

    <pre highlight="webidl">
        partial interface CSS {
          static boolean supports(CSSOMString property, CSSOMString value);
          static boolean supports(CSSOMString conditionText);
        };
    </pre>

    Using [=optional arguments=] one can rewrite the IDL fragment as follows:

    <pre highlight="webidl">
        partial interface CSSExcerptOptional {
          static boolean supports(CSSOMString propertyOrConditionText, optional CSSOMString value);
        };
    </pre>

    Even though the IDL is shorter in the second version, two distinctively different concepts are
    conflated in the first argument. Without [=overloaded|overloads=], the question "is <var
    ignore>property</var> or <var ignore>conditionText</var> paired with <var ignore>value</var>?"
    is much more difficult to answer without reading the [=method steps=] of the operation. This
    makes the second version remarkably less readable than the first.

    Another consideration is that the [=method steps=] for [=overloaded=] operations can be
    specified in separate blocks, which can aid in both reading and writing specifications. This is
    not the case for [=optional arguments=]. This means that in the first case the specification
    author can write the [=method steps=] of the operations as:

    <div algorithm="execute supports() with overloads">

        The <code class="idl">supports(<var ignore>property</var>, <var ignore>value</var>)</code>
        method steps are:

        1.  …

        ----

        The <code class="idl">supports(<var ignore>conditionText</var>)</code> method steps are:

        1.  …

    </div>

    Yet using <var ignore>value</var> as an [=optional argument=], the specification author has to
    use more boilerplate-style text to effectively replicate the [=overload resolution algorithm=].

    <div algorithm="execute supports() with optional argument">

        The <code class="idl">supports(|propertyOrConditionText|, |value|)</code> method steps are:

        1.  If |value| is given, then:
            1.  Let <var ignore>property</var> be |propertyOrConditionText|.
            1.  …
        1.  Otherwise:
            1.  Let <var ignore>conditionText</var> be |propertyOrConditionText|.
            1.  …

    </div>

    If the two overloads have little to no shared parts, it is better to leave overload resolution
    to the IDL mechanism.

*   If the operation accepts multiple types for multiple arguments with no coupling between types of
    different arguments, [=union types=] can sometimes be the only viable solution.

    <pre highlight="webidl">
        typedef (long long or DOMString or CalculatableInterface) SupportedArgument;
        interface A {
          undefined add(SupportedArgument operand1, SupportedArgument operand2);
        };
    </pre>

    For the <code class="idl">add()</code> operation above, to specify it using
    [=overloaded|overloads=] would require

    <pre highlight="webidl">
        interface A {
          undefined add(long long operand1, long long operand2);
          undefined add(long long operand1, DOMString operand2);
          undefined add(long long operand1, CalculatableInterface operand2);
          undefined add(DOMString operand1, long long operand2);
          undefined add(DOMString operand1, DOMString operand2);
          undefined add(DOMString operand1, CalculatableInterface operand2);
          undefined add(CalculatableInterface operand1, long long operand2);
          undefined add(CalculatableInterface operand1, DOMString operand2);
          undefined add(CalculatableInterface operand1, CalculatableInterface operand2);
        };
    </pre>

    and nine times the corresponding prose!

*   Specification authors are encouraged to treat missing argument and <emu-val>undefined</emu-val>
    argument the same way in the JavaScript language binding.

    Given the following IDL fragment:

    <pre highlight="webidl">
        interface A {
          undefined foo();
          undefined foo(Node? arg);
        };
    </pre>

    Using the JavaScript language binding, calling <code>foo(undefined)</code> and
    <code>foo(null)</code> would both run the steps corresponding to the <code
    class="idl">foo(|arg|)</code> operation, with |arg| set to null, while <code>foo()</code> alone
    would go to the first overload. This can be a surprising behavior for many API users. Instead,
    specification authors are encouraged to use an [=optional argument=], which would categorize
    both <code>foo()</code> and <code>foo(undefined)</code> as "|arg| is missing".

    <pre highlight="webidl">
        interface A {
          undefined foo(optional Node? arg);
        };
    </pre>

    In general, optionality is best expressed using the <emu-t>optional</emu-t> keyword, and not
    using overloads.

When the case fits none of the categories above, it is up to the specification author to choose the
style, since it is most likely that either style would sufficiently and conveniently describe the
intended behavior. However, the definition and <a href="#js-to-union">conversion algorithms</a> of
[=union types=] and [=optional arguments=] are simpler to implement and reason about than [=overload
resolution algorithm|those=] of [=overloaded|overloads=], and usually result in more idiomatic APIs
in the JavaScript language binding. Thus, unless any other considerations apply, [=union types=],
[=optional arguments=], or both are the default choice.

Specifications are also free to mix and match union types and overloads, if the author finds it
appropriate and convenient.

</div>


<h4 id="idl-iterable">Iterable declarations</h4>

An [=interface=] can be declared to be
<dfn id="dfn-iterable" export>iterable</dfn> by using an <dfn id="dfn-iterable-declaration" export>iterable declaration</dfn>
(matching <emu-nt><a href="#prod-Iterable">Iterable</a></emu-nt>) in the body of the interface.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      iterable&lt;value_type&gt;;
      iterable&lt;key_type, value_type&gt;;
    };
</pre>

Objects implementing an interface that is declared to be iterable
support being iterated over to obtain a sequence of values.

Note: In the JavaScript language binding, an interface that is iterable
will have <code class="idl">entries</code>, <code class="idl">forEach</code>,
<code class="idl">keys</code>, <code class="idl">values</code>, and {{%Symbol.iterator%}}
properties on its [=interface prototype object=].

If a single type parameter is given, then the interface has a
<dfn id="dfn-value-iterator" export>value iterator</dfn> and provides
values of the specified type.
If two type parameters are given, then the interface has a
<dfn id="dfn-pair-iterator" export>pair iterator</dfn> and provides
[=value pairs=] with the given types.

A <dfn>value pair</dfn>, given a key type and a value type, is a [=/struct=] with two
[=struct/items=]:
1.  an [=struct/item=] whose [=struct/name=] is "key", which is referred to as the [=value pair=]'s
    <dfn for="value pair">key</dfn>, and whose value is an IDL value of the key type;
1.  an [=struct/item=] whose [=struct/name=] is "value", which is referred to as the
    [=value pair=]'s <dfn for="value pair">value</dfn>, and whose value is an IDL value of the
    value type.

A [=value iterator=]
must only be declared on an interface
that [=support indexed properties|supports indexed properties=].
The value-type of the [=value iterator=]
must be the same as the type returned by
the [=indexed property getter=].
A [=value iterator=] is implicitly
defined to iterate over the object's indexed properties.

A [=pair iterator=]
must not be declared on an interface
that [=support indexed properties|supports indexed properties=].

Prose accompanying an [=interface=] with a [=pair iterator=] must define a [=/list=] of
[=value pairs=] for each instance of the [=interface=], which is the list of
<dfn id="dfn-value-pairs-to-iterate-over" export>value pairs to iterate over</dfn>.

<div class="note">

    The JavaScript forEach method that is generated for a
    [=value iterator=]
    invokes its callback like Array.prototype.forEach does, and the forEach
    method for a [=pair iterator=]
    invokes its callback like Map.prototype.forEach does.

    Since [=value iterators=]
    are currently allowed only on interfaces that
    [=support indexed properties=],
    it makes sense to use an Array-like forEach method.
    There could be a need for [=value iterators=]
    (a) on interfaces that do not
    [=support indexed properties=],
    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
    <a href="https://github.com/whatwg/webidl/issues/new?title=Enhancement%20request%20for%20Iterables">file an issue</a>.

</div>

Note: This is how [=array iterator objects=] work.
For interfaces that [=support indexed properties=],
the iterator objects returned by <code class="idl">entries</code>,
<code class="idl">keys</code>, <code class="idl">values</code>, and {{%Symbol.iterator%}} are
actual [=array iterator objects=].

[=Interfaces=] with an [=iterable declaration=] must not have any [=attributes=], [=constants=], or
[=regular operations=] named "<code>entries</code>", "<code>forEach</code>", "<code>keys</code>", or
"<code>values</code>", or have any [=inherited interfaces=] that have [=attributes=], [=constants=],
or [=regular operations=] with these names.

<div class="example" id="example-d2254660">

    Consider the following interface <code class="idl">SessionManager</code>, which allows access to
    a number of <code class="idl">Session</code> objects keyed by username:

    <pre highlight="webidl">
        [Exposed=Window]
        interface SessionManager {
          Session getSessionForUser(DOMString username);

          iterable&lt;DOMString, Session&gt;;
        };

        [Exposed=Window]
        interface Session {
          readonly attribute DOMString username;
          // ...
        };
    </pre>

    The behavior of the iterator could be defined like so:

    <blockquote>

        The [=value pairs to iterate over=] are the list of [=value pairs=] with the
        [=value pair/key=] being the username and the [=value pair/value=] being the open
        <code class="idl">Session</code> object on the <code class="idl">SessionManager</code>
        object corresponding to that username, sorted by username.

    </blockquote>

    In the JavaScript language binding, the [=interface prototype object=]
    for the <code class=idl>SessionManager</code> [=interface=]
    has a <code>values</code> method that is a function, which, when invoked,
    returns an iterator object that itself has a <code>next</code> method that returns the
    next value to be iterated over.  It has <code>keys</code> and <code>entries</code>
    methods that iterate over the usernames of session objects
    and username/<code class=idl>Session</code> object pairs, respectively.  It also has
    a {{%Symbol.iterator%}} method that allows a <code class="idl">SessionManager</code>
    to be used in a <code>for..of</code> loop that has the same value as the
    <code>entries</code> method:

    <pre highlight="js">
        // Get an instance of SessionManager.
        // Assume that it has sessions for two users, "anna" and "brian".
        var sm = getSessionManager();

        typeof SessionManager.prototype.values;            // Evaluates to "function"
        var it = sm.values();                              // values() returns an iterator object
        String(it);                                        // Evaluates to "[object SessionManager Iterator]"
        typeof it.next;                                    // Evaluates to "function"

        // This loop will log "anna" and then "brian".
        for (;;) {
          let result = it.next();
          if (result.done) {
            break;
          }
          let session = result.value;
          console.log(session.username);
        }

        // This loop will also log "anna" and then "brian".
        for (let username of sm.keys()) {
          console.log(username);
        }

        // Yet another way of accomplishing the same.
        for (let [username, session] of sm) {
          console.log(username);
        }
    </pre>
</div>

An interface must not have more than one
[=iterable declaration=].
The [=inherited interfaces=]
of an interface with an
[=iterable declaration=]
must not also have an
[=iterable declaration=].
An interface with an [=iterable declaration=]
and its [=inherited interfaces=]
must not have a
[=maplike declaration=],
[=setlike declaration=], or
[=asynchronously iterable declaration=].

The following extended attributes are applicable to [=iterable declarations=]:
[{{CrossOriginIsolated}}],
[{{Exposed}}], and
[{{SecureContext}}].

<pre class="grammar" id="prod-Iterable">
    Iterable :
        "iterable" "&lt;" TypeWithExtendedAttributes OptionalType "&gt;" ";"
</pre>

<pre class="grammar" id="prod-OptionalType">
    OptionalType :
        "," TypeWithExtendedAttributes
        ε
</pre>


<h4 oldids="idl-async-iterable" id="idl-async-iterable-declaration">Asynchronously iterable declarations</h4>

An [=interface=] can be declared to be asynchronously iterable by using an
<dfn id="dfn-async-iterable-declaration" export>asynchronously iterable declaration</dfn>
(matching <emu-nt><a href="#prod-AsyncIterable">AsyncIterable</a></emu-nt>) in the body of the
[=interface=].

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      async iterable&lt;value_type&gt;;
      async iterable&lt;value_type&gt;(/* arguments... */);
      async iterable&lt;key_type, value_type&gt;;
      async iterable&lt;key_type, value_type&gt;(/* arguments... */);
    };
</pre>

Objects that [=implement=] an [=interface=] that is declared to be asynchronously iterable support
being iterated over asynchronously to obtain a sequence of values.

If a single type parameter is given, then the interface has a
<dfn export>value asynchronously iterable declaration</dfn> and asynchronously provides values of the
specified type. If two type parameters are given, then the interface has a
<dfn export>pair asynchronously iterable declaration</dfn> and asynchronously provides
[=value pairs=] with the given types.

If given, an [=asynchronously iterable declaration=]'s arguments (matching
<emu-nt><a href="#prod-ArgumentList">ArgumentList</a></emu-nt>) must all be [=optional arguments=].

<div class="note">
    In the JavaScript language binding, an interface that is asynchronously iterable will have
    {{%Symbol.asyncIterator%}} and <code class="idl">values</code> properties on its
    [=interface prototype object=]. If the interface has a
    [=pair asynchronously iterable declaration=], it will additionally have
    <code class="idl">entries</code> and <code class="idl">keys</code> properties. All of these
    methods can be passed optional arguments, which correspond to the argument list in the
    [=asynchronously iterable declaration=], and are processed by the
    [=asynchronous iterator initialization steps=], if any exist.

    With this in mind, the requirement that all arguments be optional ensures that, in the
    JavaScript binding, <code>for</code>-<code>await</code>-<code>of</code> can work directly on
    instances of the interface, since <code>for</code>-<code>await</code>-<code>of</code> calls the
    {{%Symbol.asyncIterator%}} method with no arguments.
</div>

Prose accompanying an [=interface=] with an [=asynchronously iterable declaration=] must define a
<dfn id="dfn-get-the-next-iteration-result" export>get the next iteration result</dfn> algorithm.
This algorithm receives the instance of the [=interface=] that is being iterated, as well as the
async iterator itself (which can be useful for storing state).
It must return a {{Promise}} that either rejects, resolves with a special <dfn export>end of
iteration</dfn> value to signal the end of the iteration, or resolves with one of the following:

: for [=value asynchronously iterable declarations=]:
::  a value of the type given in the declaration;
: for [=pair asynchronously iterable declarations=]:
::  a [=tuple=] containing a value of the first type given in the declaration, and a value of the second type given in the declaration.

The prose may also define an <dfn export>asynchronous iterator return</dfn> algorithm. This
algorithm receives the instance of the [=interface=] that is being iterated, the async iterator
itself, and a single argument value of type {{any}}. This algorithm is invoked in the case of
premature termination of the async iterator. It must return a {{Promise}}; if that promise
fulfills, its fulfillment value will be ignored, but if it rejects, that failure will be passed on
to users of the async iterator API.

<p class="note">In the JavaScript binding, this algorithm allows customizing the behavior when the
async iterator's <code>return()</code> method is invoked. This most commonly occurs when a
<code>break</code> or <code>return</code> statement causes an exit from a
<code>for</code>-<code>await</code>-<code>of</code> loop.

<p class="note">We could add a similar hook for <code>throw()</code>. So far there has been no need,
but if you are creating an API that needs such capabilities, please
<a href="https://github.com/whatwg/webidl/issues/new?title=Enhancement%20request%20for%20Async%20Iterables">file an issue</a>.

The prose may also define <dfn export>asynchronous iterator initialization steps</dfn>. These
receive the instance of the [=interface=] being iterated, the newly-created iterator object, and a
[=list=] of IDL values representing the arguments passed, if any.

[=Interfaces=] with an [=asynchronously iterable declaration=] must not have any [=attributes=],
[=constants=], or [=regular operations=] named "<code>entries</code>", "<code>keys</code>", or
"<code>values</code>", or have any [=inherited interfaces=] that have [=attributes=], [=constants=],
or [=regular operations=] with these names.

<div class="example" id="example-69bd6dcd">

    Consider the following interface <code class="idl">SessionManager</code>, which allows access
    to a number of <code class="idl">Session</code> objects keyed by username:

    <pre highlight="webidl">
        [Exposed=Window]
        interface SessionManager {
          Session getSessionForUser(DOMString username);

          async iterable&lt;DOMString, Session&gt;;
        };

        [Exposed=Window]
        interface Session {
          readonly attribute DOMString username;
          // ...
        };
    </pre>

    The behavior of the iterator could be defined like so:

    <blockquote>

        The [=asynchronous iterator initialization steps=] for a <code class="idl">SessionManager</code>
        async iterator |iterator| are:

        1.  Set |iterator|'s <dfn for="SessionManager async iterator">current state</dfn> to "not
            yet started".

        To [=get the next iteration result=] for a <code class="idl">SessionManager</code>
        |manager| and its async iterator |iterator|:

        1.  Let |promise| be a new promise.
        1.  Let |key| be the following value, if it exists, or null otherwise:
            <dl class="switch">
                  :  If |iterator|'s [=SessionManager async iterator/current state=] is "not yet
                     started"
                  :: the smallest username in |manager|'s open sessions, in lexicographical order

                  :  Otherwise
                  :: the smallest username in |manager|'s open sessions that is greater than
                     |iterator|'s current state, in lexicographical order
            </dl>

            Note: |iterator|'s [=SessionManager async iterator/current state=] might no longer be
            present in the open sessions.
        1.  If |key| is null, then:
            1.  Resolve |promise| with [=end of iteration=].
        1.  Otherwise:
            1.  Let |session| be the <code class="idl">Session</code> object corresponding to |key|.
            1.  Resolve |promise| with (|username|, |session|).
            1.  Set |iterator|'s [=SessionManager async iterator/current state=] to |username|.
        1.  Return |promise|.

    </blockquote>

    In the JavaScript language binding, the [=interface prototype object=] for the
    <code class=idl>SessionManager</code> [=interface=] has a <code>values</code> method that is a
    function, which, when invoked, returns an asynchronous iterator object that itself has a
    <code>next</code> method that returns the next value to be iterated over.
    It has <code>keys</code> and <code>entries</code> methods that iterate over the usernames of
    session objects and (username, <code class=idl>Session</code>) object pairs, respectively.
    It also has a {{%Symbol.asyncIterator%}} method that allows a <code class="idl">SessionManager</code>
    to be used in a <code>for await..of</code> loop that has the same value as the
    <code>entries</code> method:

    <pre highlight="js">
        // Get an instance of SessionManager.
        // Assume that it has sessions for two users, "anna" and "brian".
        var sm = getSessionManager();

        typeof SessionManager.prototype.values;            // Evaluates to "function"
        var it = sm.values();                              // values() returns an iterator object
        typeof it.next;                                    // Evaluates to "function"

        // This loop will log "anna" and then "brian".
        for await (let username of sm.keys()) {
          console.log(username);
        }

        // Yet another way of accomplishing the same.
        for await (let [username, session] of sm) {
          console.log(username);
        }
    </pre>
</div>

An [=interface=] must not have more than one [=asynchronously iterable declaration=].
The [=inherited interfaces=] of an [=interface=] with an [=asynchronously iterable declaration=]
must not also have an [=asynchronously iterable declaration=].
An [=interface=] with an [=asynchronously iterable declaration=] and its [=inherited interfaces=]
must not have a [=maplike declaration=], [=setlike declaration=], or [=iterable declaration=].

The following extended attributes are applicable to [=asynchronously iterable declarations=]:
[{{CrossOriginIsolated}}],
[{{Exposed}}], and
[{{SecureContext}}].

Issue: these [=extended attributes=] are not currently taken into account.
When they are, the effect will be as you would expect.

<pre class="grammar" id="prod-AsyncIterable">
    AsyncIterable :
        "async" "iterable" "&lt;" TypeWithExtendedAttributes OptionalType "&gt;" OptionalArgumentList ";"
</pre>

<pre class="grammar" id="prod-OptionalArgumentList">
    OptionalArgumentList :
        "(" ArgumentList ")"
        ε
</pre>


<h4 id="idl-maplike">Maplike declarations</h4>

An [=interface=] can be declared to be
<dfn id="dfn-maplike" export>maplike</dfn> by using a <dfn id="dfn-maplike-declaration" export>maplike declaration</dfn>
(matching <emu-nt><a href="#prod-ReadWriteMaplike">ReadWriteMaplike</a></emu-nt> or
<emu-t>readonly</emu-t> <emu-nt><a href="#prod-MaplikeRest">MaplikeRest</a></emu-nt>) in the body of the interface.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      readonly maplike&lt;key_type, value_type&gt;;
      maplike&lt;key_type, value_type&gt;;
    };
</pre>

Objects implementing an interface that is declared to be maplike
represent an [=ordered map=] of key–value pairs, initially empty,
known as that object's <dfn id="dfn-map-entries" export>map entries</dfn>.
The types used for the keys and values are given in the angle
brackets of the maplike declaration.  Keys are required to be unique.

Specification authors can modify the contents of the [=map entries=],
which will automatically be reflected in the contents of the object
as observed by JavaScript code.

Maplike interfaces support an API for querying the map entries
appropriate for the language binding.  If the <emu-t>readonly</emu-t>
keyword is not used, then it also supports an API for modifying
the map entries.

Note: In the JavaScript language binding, the API for interacting
with the map entries is similar to that available on JavaScript
{{Map}} objects.  If the <emu-t>readonly</emu-t>
keyword is used, this includes <code class="idl">entries</code>,
<code class="idl">forEach</code>, <code class="idl">get</code>,
<code class="idl">has</code>, <code class="idl">keys</code>,
<code class="idl">values</code>, {{%Symbol.iterator%}} methods, and a
<code class="idl">size</code> getter.
For read–write maplikes, it also includes <code class="idl">clear</code>,
<code class="idl">delete</code>, and <code class="idl">set</code> methods.

Maplike interfaces must not have any [=attributes=], [=constants=], or [=regular operations=] named
"<code>entries</code>", "<code>forEach</code>", "<code>get</code>", "<code>has</code>",
"<code>keys</code>", "<code>size</code>", or "<code>values</code>", or have any
[=inherited interfaces=] that have [=attributes=], [=constants=], or [=regular operations=] with
these names.

Read–write maplike interfaces must not
have any [=attributes=]
or [=constants=] named
"<code>clear</code>", "<code>delete</code>",
or "<code>set</code>", or have any [=inherited interfaces=]
that have [=attributes=] or [=constants=] with these names.

Note: Read-write maplike interfaces <em>can</em> have <em>regular operations</em> named
"<code>clear</code>", "<code>delete</code>", or "<code>set</code>", which will override the default
implementation of those methods (defined in [[#js-maplike]]). If such regular operations are
defined, they must match the input and output expectations of each method, defined in their default
implementation sections.

An interface must not have more than one
[=maplike declaration=].
The [=inherited interfaces=]
of a maplike interface must not
also have a [=maplike declaration=].
A maplike interface and its [=inherited interfaces=]
must not have an
[=iterable declaration=],
an [=asynchronously iterable declaration=],
a [=setlike declaration=], or
an [=indexed property getter=].

<div grammar-fill-with="ReadOnlyMember"></div>

<div grammar-fill-with="ReadOnlyMemberRest"></div>

<pre class="grammar" id="prod-ReadWriteMaplike">
    ReadWriteMaplike :
        MaplikeRest
</pre>

<pre class="grammar" id="prod-MaplikeRest">
    MaplikeRest :
        "maplike" "&lt;" TypeWithExtendedAttributes "," TypeWithExtendedAttributes "&gt;" ";"
</pre>

No [=extended attributes=]
defined in this specification are applicable to [=maplike declarations=].

Issue: Add example.


<h4 id="idl-setlike">Setlike declarations</h4>

An [=interface=] can be declared to be
<dfn id="dfn-setlike" export>setlike</dfn> by using a <dfn id="dfn-setlike-declaration" export>setlike declaration</dfn>
(matching <emu-nt><a href="#prod-ReadWriteSetlike">ReadWriteSetlike</a></emu-nt> or
<emu-t>readonly</emu-t> <emu-nt><a href="#prod-SetlikeRest">SetlikeRest</a></emu-nt>) in the body of the interface.

<pre highlight="webidl" class="syntax">
    interface interface_identifier {
      readonly setlike&lt;type&gt;;
      setlike&lt;type&gt;;
    };
</pre>

Objects implementing an interface that is declared to be setlike
represent an [=ordered set=] of values, initially empty,
known as that object's <dfn id="dfn-set-entries" export>set entries</dfn>.
The type of the values is given in the angle
brackets of the setlike declaration.  Values are required to be unique.

Specification authors can modify the contents of the [=set entries=],
which will automatically be reflected in the contents of the object
as observed by JavaScript code.

Setlike interfaces support an API for querying the set entries
appropriate for the language binding.  If the <emu-t>readonly</emu-t>
keyword is not used, then it also supports an API for modifying
the set entries.

Note: In the JavaScript language binding, the API for interacting
with the set entries is similar to that available on JavaScript
{{Set}} objects.  If the <emu-t>readonly</emu-t>
keyword is used, this includes <code class="idl">entries</code>,
<code class="idl">forEach</code>, <code class="idl">has</code>,
<code class="idl">keys</code>, <code class="idl">values</code>,
{{%Symbol.iterator%}} methods, and a <code class="idl">size</code> getter.
For read–write setlikes, it also includes <code class="idl">add</code>,
<code class="idl">clear</code>, and <code class="idl">delete</code> methods.

Setlike interfaces must not have any [=attributes=], [=constants=], or [=regular operations=] named
"<code>entries</code>", "<code>forEach</code>", "<code>has</code>", "<code>keys</code>",
"<code>size</code>", or "<code>values</code>", or have any [=inherited interfaces=] that have
[=attributes=], [=constants=], or [=regular operations=] with these names.

Read–write setlike interfaces must not
have any [=attributes=]
or [=constants=] named
"<code>add</code>", "<code>clear</code>",
or "<code>delete</code>", or have any [=inherited interfaces=]
that have [=attributes=] or [=constants=] with these names.

Note: Read-write setlike interfaces <em>can</em> have <em>regular operations</em> named
"<code>add</code>", "<code>clear</code>", or "<code>delete</code>", which will override the default
implementation of those methods (defined in [[#js-setlike]]). If such regular operations are
defined, they must match the input and output expectations of each method, defined in their default
implementation sections.

An interface must not have more than one
[=setlike declaration=].
The [=inherited interfaces=]
of a setlike interface must not
also have a [=setlike declaration=].
A setlike interface and its [=inherited interfaces=]
must not have an
[=iterable declaration=],
an [=asynchronously iterable declaration=],
a [=maplike declaration=], or
an [=indexed property getter=].

<div grammar-fill-with="ReadOnlyMember"></div>

<div grammar-fill-with="ReadOnlyMemberRest"></div>

<pre class="grammar" id="prod-ReadWriteSetlike">
    ReadWriteSetlike :
        SetlikeRest
</pre>

<pre class="grammar" id="prod-SetlikeRest">
    SetlikeRest :
        "setlike" "&lt;" TypeWithExtendedAttributes "&gt;" ";"
</pre>

No [=extended attributes=]
defined in this specification are applicable to [=setlike declarations=].

Issue: Add example.


<h3 id="idl-namespaces">Namespaces</h3>

A <dfn id="dfn-namespace" export>namespace</dfn> is a definition (matching <emu-nt><a href="#prod-Namespace">Namespace</a></emu-nt>) that declares a global singleton with
associated behaviors.

<pre highlight="webidl" class="syntax">
    namespace identifier {
      /* namespace_members... */
    };
</pre>

A namespace is a specification of a set of
<dfn id="dfn-namespace-member" export lt="namespace member">namespace members</dfn>
(matching <emu-nt><a href="#prod-NamespaceMembers">NamespaceMembers</a></emu-nt>), which are the
[=regular operations=], [=read only=] [=regular attributes=], and [=constants=] that appear between
the braces in the namespace declaration. These operations and attributes describe the behaviors
packaged into the namespace.

As with interfaces, the IDL for namespaces can be split into multiple parts by using
<dfn id="dfn-partial-namespace" export>partial namespace</dfn> definitions
(matching <emu-t>partial</emu-t> <emu-nt><a href="#prod-Namespace">Namespace</a></emu-nt>). The [=identifier=] of a partial namespace definition must be the same as the identifier of a namespace definition.
All of the members that appear on each of the partial namespace definitions are
considered to be members of the namespace itself.

<pre highlight="webidl" class="syntax">
    namespace <mark>SomeNamespace</mark> {
      /* namespace_members... */
    };

    partial namespace <mark>SomeNamespace</mark> {
      /* namespace_members... */
    };
</pre>

Note: As with partial interface definitions, partial namespace definitions are intended for
use as a specification editorial aide, allowing the definition of a namespace to be
separated over more than one section of the document, and sometimes multiple
documents.

The order that members appear in has significance for property enumeration in the <a href="#js-namespaces">JavaScript binding</a>.

Note that unlike interfaces or dictionaries, namespaces do not create types.

Of the extended attributes defined in this specification, only the [{{CrossOriginIsolated}}], [{{Exposed}}], and [{{SecureContext}}] extended attributes are applicable to namespaces.

[=Namespaces=] must be annotated with the [{{Exposed}}] [=extended attribute=].

<div grammar-fill-with="Partial"></div>

<div grammar-fill-with="PartialDefinition"></div>

<pre class="grammar" id="prod-Namespace">
    Namespace :
        "namespace" identifier "{" NamespaceMembers "}" ";"
</pre>

<pre class="grammar" id="prod-NamespaceMembers">
    NamespaceMembers :
        ExtendedAttributeList NamespaceMember NamespaceMembers
        ε
</pre>

<pre class="grammar" id="prod-NamespaceMember">
    NamespaceMember :
        RegularOperation
        "readonly" AttributeRest
        Const
</pre>

<div class="example" id="example-namespace">

    The following [=IDL fragment=] defines a
    [=namespace=].

    <pre highlight="webidl">
        namespace VectorUtils {
          readonly attribute Vector unit;
          double dotProduct(Vector x, Vector y);
          Vector crossProduct(Vector x, Vector y);
        };
    </pre>

    A JavaScript implementation would then expose a global <code class="idl">VectorUtils</code>
    data property which was a simple object (with prototype
    {{%Object.prototype%}}) with enumerable data properties for each declared operation, and
    enumerable get-only accessors for each declared attribute:

    <pre highlight="js">
        Object.getPrototypeOf(VectorUtils);                         // Evaluates to Object.prototype.
        Object.keys(VectorUtils);                                   // Evaluates to ["dotProduct", "crossProduct"].
        Object.getOwnPropertyDescriptor(VectorUtils, "dotProduct"); // Evaluates to { value: &lt;a function&gt;, enumerable: true, configurable: true, writable: true }.
        Object.getOwnPropertyDescriptor(VectorUtils, "unit");       // Evaluates to { get: &lt;a function&gt;, enumerable: true, configurable: true }.
    </pre>
</div>


<h3 id="idl-dictionaries">Dictionaries</h3>

A <dfn id="dfn-dictionary" export>dictionary</dfn> is a definition (matching
<emu-nt><a href="#prod-Dictionary">Dictionary</a></emu-nt>)
used to define an [=ordered map=] data type with a fixed, ordered set of [=map/entries=],
termed <dfn id="dfn-dictionary-member" export>dictionary members</dfn>,
where [=map/keys=] are strings and [=map/values=] are of a particular type specified in the definition.

<pre highlight="webidl" class="syntax">
    dictionary identifier {
      /* dictionary_members... */
    };
</pre>

Dictionary instances do not retain a reference to their language-specific representations (e.g.,
the corresponding JavaScript object). So for example, returning a dictionary from an [=operation=]
will result in a new JavaScript object being created from the current values of the dictionary. And,
an operation that accepts a dictionary as an argument will perform a one-time conversion from the
given JavaScript value into the dictionary, based on the current properties of the JavaScript
object. Modifications to the dictionary will not be reflected in the corresponding JavaScript
object, and vice-versa.

Dictionaries must not be used as the type of an [=attribute=] or [=constant=].

A dictionary can be defined to <dfn id="dfn-inherit-dictionary" for="dictionary" export>inherit</dfn> from another dictionary.
If the identifier of the dictionary is followed by a colon and a [=identifier=],
then that identifier identifies the inherited dictionary.  The identifier
must identify a dictionary.

A dictionary must not be declared such that
its inheritance hierarchy has a cycle.  That is, a dictionary
|A| cannot inherit from itself, nor can it inherit from another
dictionary |B| that inherits from |A|, and so on.

<pre highlight="webidl" class="syntax">
    dictionary <mark>Base</mark> {
      /* dictionary_members... */
    };

    dictionary Derived : <mark>Base</mark> {
      /* dictionary_members... */
    };
</pre>

The <dfn id="dfn-inherited-dictionaries" export>inherited dictionaries</dfn> of
a given dictionary |D| is the set of all dictionaries that |D|
inherits from, directly or indirectly.  If |D| does not [=dictionary/inherit=]
from another dictionary, then the set is empty.  Otherwise, the set
includes the dictionary |E| that |D| [=interface/inherits=]
from and all of |E|'s [=inherited dictionaries=].

[=Dictionary members=] can be specified as
<dfn id="required-dictionary-member" export for="dictionary member">required</dfn>, meaning that
converting a language-specific value to a dictionary requires providing a value for that member. Any
dictionary member that is not [=dictionary member/required=] is
<dfn export for="dictionary member">optional</dfn>.

Note that specifying [=dictionary members=] as [=dictionary member/required=] only has
an observable effect when converting other representations of dictionaries (like a JavaScript value
supplied as an argument to an [=operation=]) to an IDL dictionary. Specification authors should
leave the members [=dictionary member/optional=] in all other cases, including when a dictionary
type is used solely as the [=return type=] of [=operations=].

A given dictionary value of type |D| can have [=map/entries=] for each of the dictionary members
defined on |D| and on any of |D|'s [=inherited dictionaries=]. Dictionary members that are specified
as [=dictionary member/required=], or that are specified as having a
[=dictionary member/default value=], will always have such corresponding [=map/entries=]. Other
members' entries might or might not [=map/exist=] in the dictionary value.

<p class="note">
    In the JavaScript binding, a value of <emu-val>undefined</emu-val> for the property
    corresponding to a [=dictionary member=] is treated the same as omitting that property. Thus, it
    will cause an error if the member is [=dictionary member/required=], or will trigger the
    [=dictionary member/default value=] if one is present, or will result in no [=map/entry=]
    existing in the dictionary value otherwise.
</p>

<p class="warning">
    As with [=optional argument/default value|operation argument default values=], it is strongly
    encouraged not to use <emu-val>true</emu-val> as the [=dictionary member/default value=] for
    {{boolean}}-typed [=dictionary members=], as this can be confusing for authors who might
    otherwise expect the default conversion of <emu-val>undefined</emu-val> to be used (i.e.,
    <emu-val>false</emu-val>). [[API-DESIGN-PRINCIPLES]]
</p>

An [=ordered map=] with string [=map/keys=] can be implicitly treated as a dictionary value of a
specific dictionary |D| if all of its [=map/entries=] correspond to [=dictionary members=], as long
as those entries have the correct types, and there are [=map/entries=] present for any
[=dictionary member/required=] or [=dictionary member/default value|defaulted=] dictionary members.

<div class="example" id="example-ba8998ea">
    <pre highlight="webidl">
    dictionary Descriptor {
      DOMString name;
      sequence&lt;unsigned long> serviceIdentifiers;
    };
    </pre>

    A <code>Descriptor</code> dictionary could be created as in the following steps:

    1.  Let |identifiers| be « 1, 3, 7 ».
    1.  Return «[ "name" → "test", "serviceIdentifiers" → |identifiers| ]».
</div>

Each [=dictionary member=] (matching
<emu-nt><a href="#prod-DictionaryMember">DictionaryMember</a></emu-nt>) is specified
as a type (matching <emu-nt><a href="#prod-Type">Type</a></emu-nt>) followed by an
[=identifier=]
(given by an <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token following
the type).  The identifier is the key name of the key–value pair.
If the <emu-nt><a href="#prod-Type">Type</a></emu-nt>
is an [=identifier=]
followed by <emu-t>?</emu-t>, then the identifier
must identify an
[=interface=], [=enumeration=],
[=callback function=], [=callback interface=] or [=typedef=].
If the dictionary member type is an identifier
not followed by <emu-t>?</emu-t>, then the identifier must
identify any one of those definitions or a [=dictionary=].

If the type of the [=dictionary member=], after resolving typedefs,
is a [=nullable type=],
its [=nullable types/inner type=] must not be a [=dictionary type=].

<pre highlight="webidl" class="syntax">
    dictionary identifier {
      type identifier;
    };
</pre>

If the identifier for an [=dictionary member/optional=] [=dictionary member=] is followed by a
U+003D (=) and a value (matching <emu-nt><a
href="#prod-DefaultValue">DefaultValue</a></emu-nt>), then that gives the dictionary member its <dfn
id="dfn-dictionary-member-default-value" for="dictionary member" export>default value</dfn>, which
is the value used by default when author code or specification text does not provide a value for
that member.

<pre highlight="webidl" class="syntax">
    dictionary identifier {
      type identifier = "value";
    };
</pre>

When a boolean literal token (<emu-t>true</emu-t> or <emu-t>false</emu-t>),
the <emu-t>null</emu-t> token,
an <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> token, a
<emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t> token,
one of the three special floating point literal values (<emu-t>Infinity</emu-t>,
<emu-t>-Infinity</emu-t> or <emu-t>NaN</emu-t>),
a <emu-t class="regex"><a href="#prod-string">string</a></emu-t> token, the two
token sequence <emu-t>[]</emu-t>, or the two token sequence <emu-t>{}</emu-t> is
used as the
[=dictionary member/default value=],
it is interpreted in the same way as for an [=operation=]'s
[=optional argument/default value|optional argument default value=].

If the type of the [=dictionary member=]
is an [=enumeration=], then its
[=dictionary member/default value=] if specified must
be one of the [=enumeration's values=].

If the type of the dictionary member is preceded by the
<emu-t>required</emu-t> keyword, the member is considered a [=dictionary member/required=]
[=dictionary member=].

<pre highlight="webidl" class="syntax">
    dictionary identifier {
      required type identifier;
    };
</pre>

The type of a dictionary member must not include
the dictionary it appears on.  A type includes a dictionary |D|
if at least one of the following is true:

*   the type is |D|
*   the type is a dictionary that [=dictionary/inherits=] from |D|
*   the type is a [=nullable type=]
    whose [=nullable types/inner type=] includes |D|
*   the type is a [=sequence type=] or [=frozen array type|frozen array=]
    whose element type includes |D|
*   the type is a [=union type=],
    one of whose [=member types=]
    includes |D|
*   the type is a dictionary, one of whose members or inherited members has
    a type that includes |D|
*   the type is <code class="idl">[=record=]&lt;|K|, |V|></code> where |V| includes |D|

As with interfaces, the IDL for dictionaries can be split into multiple parts
by using <dfn id="dfn-partial-dictionary" export>partial dictionary</dfn> definitions
(matching <emu-t>partial</emu-t> <emu-nt><a href="#prod-Dictionary">Dictionary</a></emu-nt>).
The [=identifier=] of a partial
dictionary definition must be the same as the
identifier of a dictionary definition.  All of the members that appear on each
of the partial dictionary definitions are considered to be members of
the dictionary itself.

<pre highlight="webidl" class="syntax">
    dictionary <mark>SomeDictionary</mark> {
      /* dictionary_members... */
    };

    partial dictionary <mark>SomeDictionary</mark> {
      /* dictionary_members... */
    };
</pre>

Note: As with partial interface definitions, partial dictionary definitions are intended for use as a specification
editorial aide, allowing the definition of an interface to be separated
over more than one section of the document, and sometimes multiple documents.

The order of the [=dictionary members=]
on a given dictionary is such that inherited dictionary members are ordered
before non-inherited members, and the dictionary members on the one
dictionary definition (including any partial dictionary definitions) are
ordered lexicographically by the Unicode codepoints that comprise their
identifiers.

<div class="note">

    For example, with the following definitions:

    <pre highlight="webidl">
        dictionary B : A {
          long b;
          long a;
        };

        dictionary A {
          long c;
          long g;
        };

        dictionary C : B {
          long e;
          long f;
        };

        partial dictionary A {
          long h;
          long d;
        };
    </pre>

    the order of the [=dictionary members=]
    of a dictionary value of type <code class="idl">C</code> is
    c, d, g, h, a, b, e, f.

    Dictionaries need to have their members ordered because
    in some language bindings the behavior observed when passing
    a dictionary value to a platform object depends on the order
    the dictionary members are fetched.  For example, consider the
    following additional interface:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Something {
          undefined f(A <!--grammar-check-override-->a);
        };
    </pre>

    and this JavaScript code:

    <pre highlight="js">
        var something = getSomething();  // Get an instance of Something.
        var x = 0;

        var dict = { };
        Object.defineProperty(dict, "d", { get: function() { return ++x; } });
        Object.defineProperty(dict, "c", { get: function() { return ++x; } });

        something.f(dict);
    </pre>

    The order that the dictionary members are fetched in determines
    what values they will be taken to have.  Since the order for
    <code class="idl">A</code> is defined to be c then d,
    the value for c will be 1 and the value for d will be 2.

</div>

The identifier of a dictionary member must not be
the same as that of another dictionary member defined on the dictionary or
on that dictionary's [=inherited dictionaries=].

No [=extended attributes=] are applicable to dictionaries.

<div grammar-fill-with="Partial"></div>

<div grammar-fill-with="PartialDefinition"></div>

<pre class="grammar" id="prod-Dictionary">
    Dictionary :
        "dictionary" identifier Inheritance "{" DictionaryMembers "}" ";"
</pre>

<pre class="grammar" id="prod-DictionaryMembers">
    DictionaryMembers :
        DictionaryMember DictionaryMembers
        ε
</pre>

<pre class="grammar" id="prod-DictionaryMember">
    DictionaryMember :
        ExtendedAttributeList DictionaryMemberRest
</pre>

<pre class="grammar" id="prod-DictionaryMemberRest">
    DictionaryMemberRest :
        "required" TypeWithExtendedAttributes identifier ";"
        Type identifier Default ";"
</pre>

<pre class="grammar" id="prod-PartialDictionary">
    PartialDictionary :
        "dictionary" identifier "{" DictionaryMembers "}" ";"
</pre>

<pre class="grammar" id="prod-Default">
    Default :
        "=" DefaultValue
        ε
</pre>

<div grammar-fill-with="DefaultValue"></div>

<div grammar-fill-with="Inheritance"></div>

<div class="example" id="example-f7efabfd">

    One use of dictionary types is to allow a number of <span class=allow-rfc2119>optional</span>
    arguments to
    an [=operation=] without being
    constrained as to the order they are specified at the call site.  For example,
    consider the following [=IDL fragment=]:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Point {
          constructor();
          attribute double x;
          attribute double y;
        };

        dictionary PaintOptions {
          DOMString fillPattern = "black";
          DOMString strokePattern;
          Point position;
        };

        [Exposed=Window]
        interface GraphicsContext {
          undefined drawRectangle(double width, double height, optional PaintOptions options);
        };
    </pre>

    In a JavaScript implementation of the IDL, an Object
    can be passed in for the <span class=allow-rfc2119>optional</span>
    <code class="idl">PaintOptions</code> dictionary:

    <pre highlight="js">
        // Get an instance of GraphicsContext.
        var ctx = getGraphicsContext();

        // Draw a rectangle.
        ctx.drawRectangle(300, 200, { fillPattern: "red", position: new Point(10, 10) });
    </pre>

    The members of <code class="idl">PaintOptions</code> are [=dictionary member/optional=].
    If <code class="idl">fillPattern</code> is omitted, the definition of
    <code class="idl">drawRectangle</code> can assume that it has the given default values
    and not include explicit wording to handle its omission.
    <code class="idl">drawRectangle</code> needs to explicitly handle the case where
    <code class="idl">strokePattern</code> and <code class="idl">position</code> are omitted.

</div>


<h3 id="idl-exceptions">Exceptions</h3>

An <dfn id="dfn-exception" export>exception</dfn> is a type of object that represents an error and
which can be thrown or treated as a first class value by implementations. Web IDL has a number of
pre-defined exceptions that specifications can reference and throw in their definition of
operations, attributes, and so on. Custom exception types can also be defined, as [=interfaces=]
that [=interface/inherit=] from {{DOMException}}.

A <dfn id="dfn-simple-exception" export>simple exception</dfn> is identified by one of the
following types:

*   <dfn exception>EvalError</dfn>
*   <dfn exception>RangeError</dfn>
*   <dfn exception>ReferenceError</dfn>
*   <dfn exception>TypeError</dfn>
*   <dfn exception>URIError</dfn>

These correspond to all of the JavaScript [=ECMAScript/error objects=] (apart from
<l spec=ecmascript>{{SyntaxError}}</l> and <l spec=ecmascript>{{Error}}</l>, which are deliberately
omitted as they are reserved for use by the JavaScript parser and by authors, respectively). The
meaning of each [=simple exception=] matches its corresponding error object in the JavaScript
specification.

The second kind of exception is a {{DOMException}}, which provides further
programmatically-introspectable detail on the error that occurred by giving a [=DOMException/name=].
Such [=DOMException/names=] are drawn from the <a><code>DOMException</code> names table</a> below.

<p class=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=]. This
is generally a bad pattern, however, as exceptions are meant to be thrown and not returned.

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
<dfn id="dfn-create-exception" for="exception" export lt="create">created</dfn> by providing their
type name. A {{DOMException}} can be [=exception/created=] by providing its [=DOMException/name=]
followed by {{DOMException}}. Exceptions can also be
<dfn id="dfn-throw" for="exception" export lt="throw">thrown</dfn>, 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.

<div class="example" id="example-exception-creation-and-throwing">
    <p>Here is are some examples of wording to use to create and throw exceptions.
    To throw a new [=simple exception=] whose type is {{TypeError}}:

    <blockquote>
        <p>[=exception/Throw=] a {{TypeError}}.
    </blockquote>

    <p>To throw a new {{DOMException}} with [=DOMException/name=] "{{NotAllowedError}}":

    <blockquote>
        <p>[=exception/Throw=] a "{{NotAllowedError}}" {{DOMException}}.
    </blockquote>

    <p>To create a new {{DOMException}} with [=DOMException/name=] "{{SyntaxError}}":

    <blockquote>
        <p>Let <var ignore>object</var> be a newly [=exception/created=] "{{SyntaxError}}"
        {{DOMException}}.
    </blockquote>

    <p>To [=reject=] a promise with a new {{DOMException}} with [=DOMException/name=]
    "{{OperationError}}":

    <blockquote>
        [=Reject=] <var ignore>p</var> with an "{{OperationError}}" {{DOMException}}.
    </blockquote>
</div>

<div class=example id=example-exception-throwing-message-hint>
    <p>An example of including additional information used to construct the exception message would
    be:

    <blockquote>
        [=exception/Throw=] a "{{SyntaxError}}" {{DOMException}} indicating that the given value
        had disallowed trailing spaces.
    </blockquote>

    <p>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.
</div>

The resulting behavior from creating and throwing an exception is language binding specific.

<p class=note>See [[#js-creating-throwing-exceptions]] for details on what creating and throwing an
exception entails in the JavaScript language binding.


<h4 id="idl-DOMException-error-names">Base {{DOMException}} error names</h4>

The <dfn export id="dfn-error-names-table"><code>DOMException</code> names table</dfn> 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.

<p class="note">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
<a href="https://github.com/whatwg/webidl/issues/new?title=DOMException%20name%20proposal">file an issue</a>
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.

<p class="warning">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 JavaScript's <l spec=ecmascript>{{SyntaxError}}</l>.
"{{SyntaxError!!exception}}" {{DOMException}} is used to report parsing errors in web APIs,
for example when parsing selectors,
while the JavaScript <l spec=ecmascript>{{SyntaxError}}</l> is reserved for the JavaScript parser.
To help disambiguate this further,
always favor the "{{SyntaxError!!exception}}" {{DOMException}} notation
over just using {{SyntaxError!!exception}} to refer to the {{DOMException}}. [[DOM]]

<table id="error-names" class="vert data">
    <thead>
        <tr><th>Name</th><th>Description</th><th>Legacy code name and value</th></tr>
    </thead>
    <tbody>
        <tr class="deprecated">
            <td>"<dfn id="indexsizeerror" exception export><code>IndexSizeError</code></dfn>"</td>
            <td><strong>Deprecated.</strong> Use {{RangeError}} instead.</td>
            <td><dfn id="dom-domexception-index_size_err" for="DOMException" const export><code>INDEX_SIZE_ERR</code></dfn>&nbsp;(1)</td>
        </tr>
        <tr>
            <td>"<dfn id="hierarchyrequesterror" exception export><code>HierarchyRequestError</code></dfn>"</td>
            <td>The operation would yield an incorrect [=node tree=]. [[DOM]]</td>
            <td><dfn id="dom-domexception-hierarchy_request_err" for="DOMException" const export><code>HIERARCHY_REQUEST_ERR</code></dfn>&nbsp;(3)</td>
        </tr>
        <tr>
            <td>"<dfn id="wrongdocumenterror" exception export><code>WrongDocumentError</code></dfn>"</td>
            <td>The object is in the wrong [=/document=]. [[DOM]]</td>
            <td><dfn id="dom-domexception-wrong_document_err" for="DOMException" const export><code>WRONG_DOCUMENT_ERR</code></dfn>&nbsp;(4)</td>
        </tr>
        <tr>
            <td>"<dfn id="invalidcharactererror" exception export><code>InvalidCharacterError</code></dfn>"</td>
            <td>The string contains invalid characters.</td>
            <td><dfn id="dom-domexception-invalid_character_err" for="DOMException" const export><code>INVALID_CHARACTER_ERR</code></dfn>&nbsp;(5)</td>
        </tr>
        <tr>
            <td>"<dfn id="nomodificationallowederror" exception export><code>NoModificationAllowedError</code></dfn>"</td>
            <td>The object can not be modified.</td>
            <td><dfn id="dom-domexception-no_modification_allowed_err" for="DOMException" const export><code>NO_MODIFICATION_ALLOWED_ERR</code></dfn>&nbsp;(7)</td>
        </tr>
        <tr>
            <td>"<dfn id="notfounderror" exception export><code>NotFoundError</code></dfn>"</td>
            <td>The object can not be found here.</td>
            <td><dfn id="dom-domexception-not_found_err" for="DOMException" const export><code>NOT_FOUND_ERR</code></dfn>&nbsp;(8)</td>
        </tr>
        <tr>
            <td>"<dfn id="notsupportederror" exception export><code>NotSupportedError</code></dfn>"</td>
            <td>The operation is not supported.</td>
            <td><dfn id="dom-domexception-not_supported_err" for="DOMException" const export><code>NOT_SUPPORTED_ERR</code></dfn>&nbsp;(9)</td>
        </tr>
        <tr>
            <td>"<dfn id="inuseattributeerror" exception export><code>InUseAttributeError</code></dfn>"</td>
            <td>The attribute is in use by another [=/element=]. [[DOM]]</td>
            <td><dfn id="dom-domexception-inuse_attribute_err" for="DOMException" const export><code>INUSE_ATTRIBUTE_ERR</code></dfn>&nbsp;(10)</td>
        </tr>
        <tr>
            <td>"<dfn id="invalidstateerror" exception export><code>InvalidStateError</code></dfn>"</td>
            <td>The object is in an invalid state.</td>
            <td><dfn id="dom-domexception-invalid_state_err" for="DOMException" const export><code>INVALID_STATE_ERR</code></dfn>&nbsp;(11)</td>
        </tr>
        <tr>
            <td>"<dfn id="syntaxerror" exception export><code>SyntaxError</code></dfn>"</td>
            <td>The string did not match the expected pattern.</td>
            <td><dfn id="dom-domexception-syntax_err" for="DOMException" const export><code>SYNTAX_ERR</code></dfn>&nbsp;(12)</td>
        </tr>
        <tr>
            <td>"<dfn id="invalidmodificationerror" exception export><code>InvalidModificationError</code></dfn>"</td>
            <td>The object can not be modified in this way.</td>
            <td><dfn id="dom-domexception-invalid_modification_err" for="DOMException" const export><code>INVALID_MODIFICATION_ERR</code></dfn>&nbsp;(13)</td>
        </tr>
        <tr>
            <td>"<dfn id="namespaceerror" exception export><code>NamespaceError</code></dfn>"</td>
            <td>The operation is not allowed by <cite>Namespaces in XML</cite>. [[XML-NAMES]]</td>
            <td><dfn id="dom-domexception-namespace_err" for="DOMException" const export><code>NAMESPACE_ERR</code></dfn>&nbsp;(14)</td>
        </tr>
        <tr class="deprecated">
            <td>"<dfn id="invalidaccesserror" exception export><code>InvalidAccessError</code></dfn>"</td>
            <td>
                <strong>Deprecated.</strong>
                Use {{TypeError}} for invalid arguments,
                "{{NotSupportedError!!exception}}" {{DOMException}} for unsupported operations, and
                "{{NotAllowedError!!exception}}" {{DOMException}} for denied requests instead.
            </td>
            <td><dfn id="dom-domexception-invalid_access_err" for="DOMException" const><code>INVALID_ACCESS_ERR</code></dfn>&nbsp;(15)</td>
        </tr>
        <tr class="deprecated">
            <td>"<dfn id="typemismatcherror" exception export><code>TypeMismatchError</code></dfn>"</td>
            <td><strong>Deprecated.</strong> Use {{TypeError}} instead.</td>
            <td><dfn id="dom-domexception-type_mismatch_err" for="DOMException" const><code>TYPE_MISMATCH_ERR</code></dfn>&nbsp;(17)</td>
        </tr>
        <tr>
            <td>"<dfn id="securityerror" exception export><code>SecurityError</code></dfn>"</td>
            <td>The operation is insecure.</td>
            <td><dfn id="dom-domexception-security_err" for="DOMException" const export><code>SECURITY_ERR</code></dfn>&nbsp;(18)</td>
        </tr>
        <tr>
            <td>"<dfn id="networkerror" exception export><code>NetworkError</code></dfn>"</td>
            <td>A network error occurred.</td>
            <td><dfn id="dom-domexception-network_err" for="DOMException" const export><code>NETWORK_ERR</code></dfn>&nbsp;(19)</td>
        </tr>
        <tr>
            <td>"<dfn id="aborterror" exception export><code>AbortError</code></dfn>"</td>
            <td>The operation was aborted.</td>
            <td><dfn id="dom-domexception-abort_err" for="DOMException" const export><code>ABORT_ERR</code></dfn>&nbsp;(20)</td>
        </tr>
        <tr class="deprecated">
            <td>"<dfn id="urlmismatcherror" exception export><code>URLMismatchError</code></dfn>"</td>
            <td><strong>Deprecated.</strong></td>
            <td><dfn id="dom-domexception-url_mismatch_err" for="DOMException" const export><code>URL_MISMATCH_ERR</code></dfn>&nbsp;(21)</td>
        </tr>
        <tr>
            <td>"<dfn id="quotaexceedederror" exception export><code>QuotaExceededError</code></dfn>"</td>
            <td>The quota has been exceeded.</td>
            <td><dfn id="dom-domexception-quota_exceeded_err" for="DOMException" const export><code>QUOTA_EXCEEDED_ERR</code></dfn>&nbsp;(22)</td>
        </tr>
        <tr>
            <td>"<dfn id="timeouterror" exception export><code>TimeoutError</code></dfn>"</td>
            <td>The operation timed out.</td>
            <td><dfn id="dom-domexception-timeout_err" for="DOMException" const export><code>TIMEOUT_ERR</code></dfn>&nbsp;(23)</td>
        </tr>
        <tr>
            <td>"<dfn id="invalidnodetypeerror" exception export><code>InvalidNodeTypeError</code></dfn>"</td>
            <td>The supplied [=node=] is incorrect or has an incorrect ancestor for this operation. [[DOM]]</td>
            <td><dfn id="dom-domexception-invalid_node_type_err" for="DOMException" const export><code>INVALID_NODE_TYPE_ERR</code></dfn>&nbsp;(24)</td>
        </tr>
        <tr>
            <td>"<dfn id="datacloneerror" exception export><code>DataCloneError</code></dfn>"</td>
            <td>The object can not be cloned.</td>
            <td><dfn id="dom-domexception-data_clone_err" for="DOMException" const export><code>DATA_CLONE_ERR</code></dfn>&nbsp;(25)</td>
        </tr>
        <tr>
            <td>"<dfn id="encodingerror" exception export><code>EncodingError</code></dfn>"</td>
            <td>The encoding operation (either encoded or decoding) failed.</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="notreadableerror" exception export><code>NotReadableError</code></dfn>"</td>
            <td>The I/O read operation failed.</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="unknownerror" exception export><code>UnknownError</code></dfn>"</td>
            <td>The operation failed for an unknown transient reason (e.g. out of memory).</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="constrainterror" exception export><code>ConstraintError</code></dfn>"</td>
            <td>A mutation operation in a transaction failed because a constraint was not satisfied. [[INDEXEDDB]]</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="dataerror" exception export><code>DataError</code></dfn>"</td>
            <td>Provided data is inadequate.</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="transactioninactiveerror" exception export><code>TransactionInactiveError</code></dfn>"</td>
            <td>A request was placed against a transaction which is currently not active, or which is finished. [[INDEXEDDB]]</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="readonlyerror" exception export><code>ReadOnlyError</code></dfn>"</td>
            <td>The mutating operation was attempted in a "readonly" transaction. [[INDEXEDDB]]</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="versionerror" exception export><code>VersionError</code></dfn>"</td>
            <td>An attempt was made to open a database using a lower version than the existing version. [[INDEXEDDB]]</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="operationerror" exception export><code>OperationError</code></dfn>"</td>
            <td>The operation failed for an operation-specific reason.</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="notallowederror" exception export><code>NotAllowedError</code></dfn>"</td>
            <td>The request is not allowed by the user agent or the platform in the current context, possibly because the user denied permission.</td>
            <td>—</td>
        </tr>
        <tr>
            <td>"<dfn id="optouterror" exception export><code>OptOutError</code></dfn>"</td>
            <td>The user opted out of the process.</td>
            <td>—</td>
        </tr>
    </tbody>
</table>

<h4 id="idl-DOMException-derived-interfaces">{{DOMException}} derived interfaces</h4>

When an exception needs to carry additional programmatically-introspectable information, beyond what
can be provided with a {{DOMException}}'s [=DOMException/name=], specification authors can create an
[=interface=] which [=interface/inherits=] from {{DOMException}}. Such interfaces need to follow
certain rules, in order to have a predictable shape for developers. Specifically:

*   The [=identifier=] of the [=interface=] must end with <code>Error</code>, and must not be any
    of the names in the <a><code>DOMException</code> names table</a>.
*   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.

<p class=note>These requirements mean that the inherited {{DOMException/code}} property of these
interfaces will always return 0.

<div class=example id=example-domexception-derived-interface>
    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:

    <pre highlight=webidl>
        [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;
        };
    </pre>

    Every <code>ProtocolXError</code> instance has an <dfn for="ProtocolXError">error code</dfn>,
    a number.

    <div algorithm="ProtocolXError constructor">
        The <b><code>new ProtocolXError(|message|, |options|)</code></b> constructor steps are:

        1.  Set [=this=]'s [=DOMException/name=] to "<code>ProtocolXError</code>".
        1.  Set [=this=]'s [=DOMException/message=] to |message|.
        1.  Set [=this=]'s [=ProtocolXError/error code=] to |options|["<code>errorCode</code>"].
    </div>

    <div algorithm="ProtocolXError errorCode">
        The <b><code>errorCode</code></b> getter steps are to return [=this=]'s
        [=ProtocolXError/error code=].
    </div>

    <code>ProtocolXError</code> objects are [=serializable objects=].

    <div algorithm="ProtocolXError serialization steps">
        Their [=serialization steps=], given |value| and |serialized|, are:

        1. Run the {{DOMException}} [=serialization steps=] given |value| and |serialized|.
        1. Set |serialized|.\[[ErrorCode]] to |value|'s [=ProtocolXError/error code=].
    </div>

    <div algorithm="ProtocolXError deserialization steps">
        Their [=deserialization steps=], given |serialized| and |value|, are:

        1. Run the {{DOMException}} [=deserialization steps=] given |serialized| and |value|.
        1. Set |value|'s [=ProtocolXError/error code=] to |serialized|.\[[ErrorCode]].
    </div>
</div>

To [=exception/create=] or [=exception/throw=] a {{DOMException}} derived interface, supply its
[=interface=] [=identifier=] as well as the additional information needed to construct it.

<div class=example id=example-domexception-derived-throwing>
    <p>To throw an instance of the <code>ProtocolXError</code> exemplified
    <a href=#example-domexception-derived-interface>above</a>:

    <blockquote>
        <p>[=exception/Throw=] a <code>ProtocolXError</code> whose [=ProtocolXError/error code=]
        is 42.
    </blockquote>
</div>

<h3 id="idl-enums">Enumerations</h3>

An <dfn id="dfn-enumeration" export>enumeration</dfn> is a definition (matching
<emu-nt><a href="#prod-Enum">Enum</a></emu-nt>) used to declare a type
whose valid values are a set of predefined strings.  Enumerations
can be used to restrict the possible
{{DOMString}} values that can be assigned to an
[=attribute=] or passed to an
[=operation=].

<pre highlight="webidl" class="syntax">enum identifier { "enum", "values" /* , ... */ };</pre>

The <dfn id="dfn-enumeration-value" export lt="enumeration value|enumeration’s values">enumeration values</dfn> are specified
as a comma-separated list of <emu-t class="regex"><a href="#prod-string">string</a></emu-t> literals.
The list of [=enumeration values=]
must not include duplicates.

<p class="warning">
    It is strongly suggested that enumeration values be all lowercase,
    and that multiple words be separated using dashes or not be
    separated at all, unless there is a specific reason to use another
    value naming scheme.  For example, an enumeration value that
    indicates an object should be created could be named
    "<code>createobject</code>" or "<code>create-object</code>".
    Consider related uses of enumeration values when deciding whether
    to dash-separate or not separate enumeration value words so that
    similar APIs are consistent.
</p>

The behavior when a string value that is not a valid enumeration value
is used when assigning to an [=attribute=],
or passed as an [=operation=] argument,
whose type is the enumeration, is language binding specific.

Note: In the JavaScript binding, assignment of an invalid string value to an
[=attribute=] is ignored, while
passing such a value in other contexts (for example as an [=operation=] argument)
results in an exception being thrown.

No [=extended attributes=]
defined in this specification are applicable to [=enumerations=].

<pre class="grammar" id="prod-Enum">
    Enum :
        "enum" identifier "{" EnumValueList "}" ";"
</pre>

<pre class="grammar" id="prod-EnumValueList">
    EnumValueList :
        string EnumValueListComma
</pre>

<pre class="grammar" id="prod-EnumValueListComma">
    EnumValueListComma :
        "," EnumValueListString
        ε
</pre>

<pre class="grammar" id="prod-EnumValueListString">
    EnumValueListString :
        string EnumValueListComma
        ε
</pre>

<div class="example" id="example-43a649e6">

    The following [=IDL fragment=]
    defines an [=enumeration=]
    that is used as the type of an [=attribute=]
    and an [=operation=] argument:

    <pre highlight="webidl">
        enum MealType { "rice", "noodles", "other" };

        [Exposed=Window]
        interface Meal {
          attribute MealType type;
          attribute double size;     // in grams

          undefined initialize(MealType type, double size);
        };
    </pre>

    A JavaScript implementation would restrict the strings that can be
    assigned to the type property or passed to the initializeMeal function
    to those identified in the [=enumeration=].

    <pre highlight="js">
        var meal = getMeal();                // Get an instance of Meal.

        meal.initialize("rice", 200);        // Operation invoked as normal.

        try {
          meal.initialize("sandwich", 100);  // Throws a TypeError.
        } catch (e) {
        }

        meal.type = "noodles";               // Attribute assigned as normal.
        meal.type = "dumplings";             // Attribute assignment ignored.
        meal.type == "noodles";              // Evaluates to true.
    </pre>
</div>


<h3 id="idl-callback-functions">Callback functions</h3>

<p class="XXX">
    The “Custom DOM Elements” spec wants to use callback function types for
    platform object provided functions.  Should we rename “callback functions” to
    just “functions” to make it clear that they can be used for both purposes?
</p>

A <dfn id="dfn-callback-function" export>callback function</dfn> is a definition (matching
<emu-t>callback</emu-t> <emu-nt><a href="#prod-CallbackRest">CallbackRest</a></emu-nt>) used to declare a function type.

<pre highlight="webidl" class="syntax">callback identifier = return_type (/* arguments... */);</pre>

Note: See also the similarly named [=callback interfaces=].

The [=identifier=] on the
left of the equals sign gives the name of the [=callback function=]
and the return type and argument list (matching <emu-nt><a href="#prod-Type">Type</a></emu-nt>
and <emu-nt><a href="#prod-ArgumentList">ArgumentList</a></emu-nt>) on the right side of the equals
sign gives the signature of the callback function type.

[=Callback functions=] must not
be used as the type of a [=constant=].

The following extended attribute is applicable to callback functions:
[{{LegacyTreatNonObjectAsNull}}].

<div grammar-fill-with="CallbackOrInterfaceOrMixin"></div>

<div grammar-fill-with="CallbackRestOrInterfaceOrMixin"></div>

<pre class="grammar" id="prod-CallbackRest">
    CallbackRest :
        identifier "=" Type "(" ArgumentList ")" ";"
</pre>

<div class="example" id="example-9e6fa35f">

    The following [=IDL fragment=] defines
    a [=callback function=] used for an API that
    invokes a user-defined function when an operation is complete.

    <pre highlight="webidl">
        callback AsyncOperationCallback = undefined (DOMString status);

        [Exposed=Window]
        interface AsyncOperations {
          undefined performOperation(AsyncOperationCallback whenFinished);
        };
    </pre>

    In the JavaScript language binding, a [=function object=] is
    passed as the operation argument.

    <pre highlight="js">
        var ops = getAsyncOperations();  // Get an instance of AsyncOperations.

        ops.performOperation(function(status) {
          window.alert("Operation finished, status is " + status + ".");
        });
    </pre>
</div>


<h3 id="idl-typedefs">Typedefs</h3>

A <dfn id="dfn-typedef" export>typedef</dfn> is a definition (matching
<emu-nt><a href="#prod-Typedef">Typedef</a></emu-nt>)
used to declare a new name for a type.  This new name is not exposed
by language bindings; it is purely used as a shorthand for referencing
the type in the IDL.

<pre highlight="webidl" class="syntax">typedef type identifier;</pre>

The <dfn>type being given a new name</dfn> is specified after the <emu-t>typedef</emu-t>
keyword (matching <emu-nt><a href="#prod-Type">TypeWithExtendedAttributes</a></emu-nt>), and the
<emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> token following the
type gives the name.

The <emu-nt><a href="#prod-Type">Type</a></emu-nt> must not
be the identifier of the same or another [=typedef=].

No [=extended attributes=]
defined in this specification are applicable to [=typedefs=].

<pre class="grammar" id="prod-Typedef">
    Typedef :
        "typedef" TypeWithExtendedAttributes identifier ";"
</pre>

<div class="example" id="example-1aa575d3">

    The following [=IDL fragment=]
    demonstrates the use of [=typedefs=]
    to allow the use of a short
    [=identifier=] instead of a long
    [=sequence type=].

    <pre highlight="webidl">
        [Exposed=Window]
        interface Point {
          attribute double x;
          attribute double y;
        };

        typedef sequence&lt;Point&gt; Points;

        [Exposed=Window]
        interface Widget {
          boolean pointWithinBounds(Point p);
          boolean allPointsWithinBounds(Points ps);
        };
    </pre>
</div>


<h3 id="idl-objects">Objects implementing interfaces</h3>

In a given implementation of a set of [=IDL fragments=],
an object can be described as being a [=platform object=].

<dfn id="dfn-platform-object" lt="platform object" export>Platform objects</dfn> are objects
that implement an [=interface=].

<dfn id="dfn-legacy-platform-object" export>Legacy platform objects</dfn> are
[=platform objects=] that implement an [=interface=] which
does not have a [{{Global}}] [=extended attribute=], and which
[=support indexed properties|supports indexed properties=],
[=support named properties|named properties=], or both.

In a browser, for example,
the browser-implemented DOM objects (implementing interfaces such as <code class="idl">Node</code> and
<code class="idl">Document</code>) that provide access to a web page's contents
to JavaScript running in the page would be [=platform objects=].  These objects might be exotic objects,
implemented in a language like C++, or they might be native JavaScript objects.  Regardless,
an implementation of a given set of IDL fragments needs to be able to recognize all [=platform objects=]
that are created by the implementation.  This might be done by having some internal state that records whether
a given object is indeed a platform object for that implementation, or perhaps by observing
that the object is implemented by a given internal C++ class.  How exactly platform objects
are recognized by a given implementation of a set of IDL fragments is implementation specific.

All other objects in the system would not be treated as platform objects.  For example, assume that
a web page opened in a browser loads a JavaScript library that implements DOM Core.  This library
would be considered to be a different implementation from the browser provided implementation.
The objects created by the JavaScript library that implement the <code class="idl">Node</code> interface
will not be treated as platform objects that implement <code class="idl">Node</code> by the browser implementation.

[=Callback interfaces=], on the other hand, can be implemented by any JavaScript object. This
allows Web APIs to invoke author-defined operations. For example, the DOM Events implementation
allows authors to register callbacks by providing objects that implement the
{{EventListener}} interface.


<h3 id="idl-types">Types</h3>

This section lists the types supported by Web IDL,
the set of values or [[Infra|Infra]] type
corresponding to each type, and how [=constants=]
of that type are represented.

The following types are known as <dfn id="dfn-integer-type" export>integer types</dfn>:
{{byte}},
{{octet}},
{{short}},
{{unsigned short}},
{{long}},
{{unsigned long}},
{{long long}} and
{{unsigned long long}}.

The following types are known as <dfn id="dfn-numeric-type" export>numeric types</dfn>:
the [=integer types=],
{{float}},
{{unrestricted float}},
{{double}} and
{{unrestricted double}}.

The <dfn id="dfn-primitive-type" export>primitive types</dfn> are
{{bigint}}, {{boolean}} and the [=numeric types=].

The <dfn id="dfn-string-type" export>string types</dfn> are
{{DOMString}}, all [=enumeration types=],
{{ByteString}} and {{USVString}}.

The <dfn export>buffer types</dfn> are {{ArrayBuffer}} and {{SharedArrayBuffer}}.

The <dfn id="dfn-typed-array-type" export>typed array types</dfn> are
{{Int8Array}},
{{Int16Array}},
{{Int32Array}},
{{Uint8Array}},
{{Uint16Array}},
{{Uint32Array}},
{{Uint8ClampedArray}},
{{BigInt64Array}},
{{BigUint64Array}},
{{Float16Array}},
{{Float32Array}}, and
{{Float64Array}}.

The <dfn export>buffer view types</dfn> are {{DataView}} and the [=typed array types=].

The <dfn id="dfn-buffer-source-type" export>buffer source types</dfn> are the [=buffer types=] and the [=buffer view types=].

The {{object}} type,
all [=interface types=], and
all [=callback interface types=]
are known as <dfn id="dfn-object-type" export>object types</dfn>.

<p id="type-conversion-exceptions">
    When conversions are made from language binding specific types to
    IDL types in order to invoke an [=operation=]
    or assign a value to an [=attribute=],
    all conversions necessary will be performed before the
    specified functionality of the operation or attribute assignment
    is carried out.  If the conversion cannot
    be performed, then the operation will not run or
    the attribute will not be updated.  In some language bindings,
    type conversions could result in an exception being thrown.
    In such cases, these exceptions will be propagated to the
    code that made the attempt to invoke the operation or
    assign to the attribute.
</p>

<pre class="grammar" id="prod-Type">
    Type :
        SingleType
        UnionType Null
</pre>

<pre class="grammar" id="prod-TypeWithExtendedAttributes">
    TypeWithExtendedAttributes :
        ExtendedAttributeList Type
</pre>

<pre class="grammar" id="prod-SingleType">
    SingleType :
        DistinguishableType
        "any"
        PromiseType
</pre>

<pre class="grammar" id="prod-UnionType">
    UnionType :
        "(" UnionMemberType "or" UnionMemberType UnionMemberTypes ")"
</pre>

<pre class="grammar" id="prod-UnionMemberType">
    UnionMemberType :
        ExtendedAttributeList DistinguishableType
        UnionType Null
</pre>

<pre class="grammar" id="prod-UnionMemberTypes">
    UnionMemberTypes :
        "or" UnionMemberType UnionMemberTypes
        ε
</pre>

<pre class="grammar" id="prod-DistinguishableType">
    DistinguishableType :
        PrimitiveType Null
        StringType Null
        identifier Null
        "sequence" "&lt;" TypeWithExtendedAttributes "&gt;" Null
        "async_iterable" "&lt;" TypeWithExtendedAttributes "&gt;" Null
        "object" Null
        "symbol" Null
        BufferRelatedType Null
        "FrozenArray" "&lt;" TypeWithExtendedAttributes "&gt;" Null
        "ObservableArray" "&lt;" TypeWithExtendedAttributes "&gt;" Null
        RecordType Null
        "undefined" Null
</pre>

<div grammar-fill-with="ConstType"></div>

<pre class="grammar" id="prod-PrimitiveType">
    PrimitiveType :
        UnsignedIntegerType
        UnrestrictedFloatType
        "boolean"
        "byte"
        "octet"
        "bigint"
</pre>

<pre class="grammar" id="prod-UnrestrictedFloatType">
    UnrestrictedFloatType :
        "unrestricted" FloatType
        FloatType
</pre>

<pre class="grammar" id="prod-FloatType">
    FloatType :
        "float"
        "double"
</pre>

<pre class="grammar" id="prod-UnsignedIntegerType">
    UnsignedIntegerType :
        "unsigned" IntegerType
        IntegerType
</pre>

<pre class="grammar" id="prod-IntegerType">
    IntegerType :
        "short"
        "long" OptionalLong
</pre>

<pre class="grammar" id="prod-OptionalLong">
    OptionalLong :
        "long"
        ε
</pre>

<pre class="grammar" id="prod-StringType">
    StringType :
        "ByteString"
        "DOMString"
        "USVString"
</pre>

<pre class="grammar" id="prod-PromiseType">
    PromiseType :
        "Promise" "&lt;" Type "&gt;"
</pre>

<pre class="grammar" id="prod-RecordType">
    RecordType :
        "record" "&lt;" StringType "," TypeWithExtendedAttributes "&gt;"
</pre>

<pre class="grammar" id="prod-Null">
    Null :
        "?"
        ε
</pre>

<h4 oldids="dom-any" id="idl-any" interface>any</h4>

The {{any}} type is the union of all other possible
non-[=union type|union=] types.

The {{any}} type is like
a discriminated union type, in that each of its values has a
specific non-{{any}} type
associated with it.  For example, one value of the
{{any}} type is the
{{unsigned long}}
150, while another is the {{long}} 150.
These are distinct values.

The particular type of an {{any}}
value is known as its <dfn id="dfn-specific-type" export>specific type</dfn>.
(Values of [=union types=] also have
[=specific types=].)

<h4 id="idl-undefined" oldids="idl-void" interface>undefined</h4>

The {{undefined}} type has a unique value.

{{undefined}} constant values in IDL
are represented with the <emu-t>undefined</emu-t> token.

{{undefined}} must not be used as the type of an argument in any circumstance
(in an [=operation=], [=callback function=], [=constructor operation=], etc),
or as the type of a [=dictionary member=],
whether directly or in a union.
Instead, use an [=optional argument=]
or a non-[=dictionary member/required=] [=dictionary member=].

Note: This value was previously spelled <code>void</code>,
and more limited in how it was allowed to be used.

<h4 oldids="dom-boolean" id="idl-boolean" interface>boolean</h4>

The {{boolean}} type corresponds to [=/booleans=].

{{boolean}} constant values in IDL are
represented with the <emu-t>true</emu-t> and
<emu-t>false</emu-t> tokens.

<h4 oldids="dom-byte" id="idl-byte" interface>byte</h4>

The {{byte}} type corresponds to [=/8-bit signed integers=].

{{byte}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

<h4 oldids="dom-octet" id="idl-octet" interface>octet</h4>

The {{octet}} type corresponds to [=/8-bit unsigned integers=].

{{octet}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

<h4 oldids="dom-short" id="idl-short" interface>short</h4>

The {{short}} type corresponds to [=/16-bit signed integers=].

{{short}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

<h4 oldids="dom-unsignedshort" id="idl-unsigned-short" interface>unsigned short</h4>

The {{unsigned short}} type corresponds to [=/16-bit unsigned integers=].

{{unsigned short}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

<h4 oldids="dom-long" id="idl-long" interface>long</h4>

The {{long}} type corresponds to [=/32-bit signed integers=].

{{long}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

<h4 oldids="dom-unsignedlong" id="idl-unsigned-long" interface>unsigned long</h4>

The {{unsigned long}} type corresponds to [=/32-bit unsigned integers=].

{{unsigned long}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

<h4 oldids="dom-longlong" id="idl-long-long" interface>long long</h4>

The {{long long}} type corresponds to [=/64-bit signed integers=].

{{long long}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

<h4 oldids="dom-unsignedlonglong" id="idl-unsigned-long-long" interface>unsigned long long</h4>

The {{unsigned long long}} type corresponds to [=/64-bit unsigned integers=].

{{unsigned long long}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>
tokens.

<h4 oldids="dom-float" id="idl-float" interface>float</h4>

The {{float}} type is a floating point numeric
type that corresponds to the set of finite single-precision 32-bit
IEEE 754 floating point numbers. [[!IEEE-754]]

{{float}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t>
tokens.

<p class="warning">
    Unless there are specific reasons to use a 32-bit floating point type,
    specifications should use
    {{double}} rather than {{float}},
    since the set of values that a {{double}} can
    represent more closely matches a JavaScript Number.
</p>

<h4 oldids="dom-unrestrictedfloat" id="idl-unrestricted-float" interface>unrestricted float</h4>

The {{unrestricted float}} type is a floating point numeric
type that corresponds to the set of all possible single-precision 32-bit
IEEE 754 floating point numbers, finite, non-finite, and special "not a number" values (NaNs). [[!IEEE-754]]

{{unrestricted float}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t>
tokens.

<h4 oldids="dom-double" id="idl-double" interface>double</h4>

The {{double}} type is a floating point numeric
type that corresponds to the set of finite double-precision 64-bit
IEEE 754 floating point numbers. [[!IEEE-754]]

{{double}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t>
tokens.

<h4 oldids="dom-unrestricteddouble" id="idl-unrestricted-double" interface>unrestricted double</h4>

The {{unrestricted double}} type is a floating point numeric
type that corresponds to the set of all possible double-precision 64-bit
IEEE 754 floating point numbers, finite, non-finite, and special "not a number" values (NaNs). [[!IEEE-754]]

{{unrestricted double}} constant values in IDL are
represented with <emu-t class="regex"><a href="#prod-decimal">decimal</a></emu-t>
tokens.

<h4 id="idl-bigint" interface>bigint</h4>

The {{bigint}} type is an arbitrary integer type, unrestricted in range.

{{bigint}} constant values in IDL are represented with
<emu-t class="regex"><a href="#prod-integer">integer</a></emu-t> tokens.

<h4 oldids="dom-DOMString" id="idl-DOMString" interface>DOMString</h4>

The {{DOMString}} type corresponds to [=strings=].

Note: <emu-val>null</emu-val> is not a value of type {{DOMString}}. To allow
<emu-val>null</emu-val>, a [=nullable type|nullable=] {{DOMString}}, written as
<code>DOMString?</code> in IDL, needs to be used.

Note: A {{DOMString}} value might include unmatched [=surrogate=] [=code points=]. Use {{USVString}}
if this is not desirable.

There is no way to represent a constant {{DOMString}}
value in IDL, although {{DOMString}} [=dictionary member=] [=dictionary member/default values=]
and [=optional argument|operation optional argument=] [=optional argument/default values=]
can be set to [=value of string literal tokens|the value=] of a
<emu-t class="regex"><a href="#prod-string">string</a></emu-t> literal.

<h4 oldids="dom-ByteString" id="idl-ByteString" interface>ByteString</h4>

The {{ByteString}} type corresponds to [=byte sequences=].

There is no way to represent a constant {{ByteString}}
value in IDL, although {{ByteString}} [=dictionary member=] [=dictionary member/default values=]
and [=optional argument|operation optional argument=] [=optional argument/default values=]
can be set to [=value of string literal tokens|the value=] of a
<emu-t class="regex"><a href="#prod-string">string</a></emu-t> literal.

<p class="warning">
    Specifications should only use
    {{ByteString}} for interfacing with protocols
    that use bytes and strings interchangeably, such as HTTP.  In general,
    strings should be represented with
    {{DOMString}} values, even if it is expected
    that values of the string will always be in ASCII or some
    8-bit character encoding. [=sequence types|Sequences=] or
    [=frozen array type|frozen arrays=] with {{octet}} or {{byte}}
    elements, {{Uint8Array}}, or {{Int8Array}} should be used for holding
    8-bit data rather than {{ByteString}}.
</p>


<h4 oldids="dom-USVString" id="idl-USVString" interface>USVString</h4>

The {{USVString}} type
corresponds to [=scalar value strings=].
Depending on the context,
these can be treated as sequences of [=/code units=]
or [=/scalar values=].

There is no way to represent a constant {{USVString}}
value in IDL, although {{USVString}} [=dictionary member=] [=dictionary member/default values=]
and [=optional argument|operation optional argument=] [=optional argument/default values=]
can be set to [=value of string literal tokens|the value=] of a
<emu-t class="regex"><a href="#prod-string">string</a></emu-t> literal.

<p class="warning">
    Specifications should only use
    {{USVString}} for APIs that perform
    text processing and need a string of
    [=scalar values=] to operate on.  Most APIs that use strings
    should instead be using {{DOMString}},
    which does not make any interpretations of the [=code units=]
    in the string.  When in doubt, use {{DOMString}}.
</p>


<h4 oldids="dom-object" id="idl-object" interface>object</h4>

The {{object}} type corresponds to the set of
all possible non-null object references.

There is no way to represent a constant {{object}}
value in IDL.

To denote a type that includes all possible object references plus the
<emu-val>null</emu-val> value, use the [=nullable type=]
<code class="idl">object?</code>.

<h4 id="idl-symbol" interface>symbol</h4>

The {{symbol}} type corresponds to the set of all possible symbol values. Symbol values are opaque,
non-{{object}} values which nevertheless have identity (i.e., are only equal to themselves).

There is no way to represent a constant {{symbol}} value in IDL.

<h4 id="idl-interface" dfn>Interface types</h4>

An [=identifier=] that
identifies an [=interface=] is used to refer to
a type that corresponds to the set of all possible non-null references to objects that
implement that interface.

An IDL value of the interface type is represented just
by an object reference.

There is no way to represent a constant object reference value for
a particular interface type in IDL.

To denote a type that includes all possible references to objects implementing
the given interface plus the <emu-val>null</emu-val> value,
use a [=nullable type=].

<h4 id="idl-callback-interface" dfn>Callback interface types</h4>

An [=identifier=] that identifies a [=callback interface=] is used to refer to a type that
corresponds to the set of all possible non-null references to objects.

An IDL value of the interface type is represented by a tuple of an object reference and a
<dfn id="dfn-callback-context" export>callback context</dfn>.
The [=callback context=] is a language binding specific value, and is used to store information
about the execution context at the time the language binding specific object reference is
converted to an IDL value.

Note: For JavaScript objects, the [=callback context=] is used to hold a reference to the
<a spec="HTML">incumbent settings object</a> at the time the Object value is converted to an IDL
callback interface type value. See [[#js-callback-interface]].

There is no way to represent a constant object reference value for a particular
[=callback interface type=] in IDL.

To denote a type that includes all possible references to objects plus the <emu-val>null</emu-val>
value, use a [=nullable type=].

<h4 id="idl-dictionary" dfn>Dictionary types</h4>

An [=identifier=] that
identifies a [=dictionary=] is used to refer to
a type that corresponds to the set of all dictionaries that adhere to
the dictionary definition.

The literal syntax for [=ordered maps=] may also be used to represent dictionaries, when it is
implicitly understood from context that the map is being treated as an instance of a specific
dictionary type. However, there is no way to represent a constant dictionary value inside IDL
fragments.

<h4 id="idl-enumeration" dfn export>Enumeration types</h4>

An [=identifier=] that
identifies an [=enumeration=] is used to
refer to a type whose values are the set of strings (sequences of
[=code units=], as with
{{DOMString}}) that are the
[=enumeration's values=].

Like {{DOMString}}, there is no way to represent a constant [=enumeration=]
value in IDL, although enumeration-typed [=dictionary member=] [=dictionary member/default values=]
and [=optional argument|operation optional argument=] [=optional argument/default values=]
can be set to [=value of string literal tokens|the value=] of a
<emu-t class="regex"><a href="#prod-string">string</a></emu-t> literal.

<h4 id="idl-callback-function" dfn>Callback function types</h4>

An [=identifier=] that identifies
a [=callback function=] is used to refer to
a type whose values are references to objects that are functions with the given signature.

Note: If the [{{LegacyTreatNonObjectAsNull}}] [=extended attribute=] is specified on the [=definition=] of
the [=callback function=], the values can be references to objects that are not functions.

An IDL value of the callback function type is represented by a tuple of an object
reference and a [=callback context=].

Note: As with [=callback interface types=], the [=callback context=] is used to hold a
reference to the <a spec="HTML">incumbent settings object</a> at
the time a JavaScript Object value is converted to an IDL
callback function type value.  See [[#js-callback-function]].

There is no way to represent a constant [=callback function=]
value in IDL.

<h4 id="idl-nullable-type">Nullable types — |T|?</h4>

A <dfn id="dfn-nullable-type" export>nullable type</dfn> is an IDL type constructed
from an existing type (called the <dfn id="dfn-inner-type" export for="nullable types">inner type</dfn>),
which just allows the additional value <emu-val>null</emu-val>
to be a member of its set of values.  [=Nullable types=]
are represented in IDL by placing a U+003F (?)
character after an existing type.
The [=nullable types/inner type=] must not be:

*   {{any}},
*   a [=promise type=],
*   an [=observable array type=],
*   another nullable type, or
*   a [=union type=] that itself [=includes a nullable type=]
    or has a dictionary type as one of its [=flattened member types=].

Note: Although dictionary types can in general be nullable,
they cannot when used as the type of an operation argument or a dictionary member.

Nullable type constant values in IDL are represented in the same way that
constant values of their [=nullable types/inner type=]
would be represented, or with the <emu-t>null</emu-t> token.

<div class="example" id="example-93b2f0cf">

    For example, a type that allows the values <emu-val>true</emu-val>,
    <emu-val>false</emu-val> and <emu-val>null</emu-val>
    is written as <code class="idl">boolean?</code>:

    <pre highlight="webidl">
        [Exposed=Window]
        interface NetworkFetcher {
          undefined get(optional boolean? areWeThereYet = false);
        };
    </pre>

    The following [=interface=] has two
    [=attributes=]: one whose value can
    be a {{DOMString}} or the <emu-val>null</emu-val>
    value, and another whose value can be a reference to a <code class="idl">Node</code>
    object or the <emu-val>null</emu-val> value:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Node {
          readonly attribute DOMString? namespaceURI;
          readonly attribute Node? parentNode;
          // ...
        };
    </pre>
</div>


<h4 oldids="dom-sequence" id="idl-sequence" lt="sequence" dfn export>Sequence types — sequence&lt;|T|&gt;</h4>

The <dfn lt="sequence type" export>sequence&lt;|T|&gt;</dfn>
type is a parameterized type whose values are (possibly zero-length) [=lists=] of
values of type |T|.

Sequences are always passed by value.  In
language bindings where a sequence is represented by an object of
some kind, passing a sequence to a [=platform object=]
will not result in a reference to the sequence being kept by that object.
Similarly, any sequence returned from a platform object
will be a copy and modifications made to it will not be visible to the platform object.

The literal syntax for [=lists=] may also be used to represent sequences, when it is implicitly
understood from context that the list is being treated as a sequences. However, there is no way to
represent a constant sequence value inside IDL fragments.

Sequences must not be used as the
type of an [=attribute=] or
[=constant=].

Note: This restriction exists so that it is clear to specification writers
and API users that [=sequence types|sequences=]
are copied rather than having references
to them passed around.  Instead of a writable [=attribute=] of a sequence
type, it is suggested that a pair of [=operations=] to get and set the
sequence is used.

Any [=list=] can be implicitly treated as a <code>sequence&lt;|T|&gt;</code>, as long as it contains
only [=list/items=] that are of type |T|.

<!-- Note: if we ever add synchronous iterable types, we should add a note here about why sequences and iterables are not the same. -->

<h4 id="idl-async-iterable-type" lt="async iterable" dfn export>Async iterable types — async iterable&lt;|T|&gt;</h4>

An <dfn lt="async iterable type" export>async iterable type</dfn> is a parameterized
type whose values are references to objects that can produce an asynchronously iterable, possibly infinite,
sequence of values of type |T|.

Unlike [=sequences=], which are fixed-length lists where all values are known in advance, the asynchronously
iterable sequences created by async iterables are lazy. Their values may be produced asynchronously
only during iteration, and thus the values or length might not be known at the time the async
iterable is created.

Async iterables are passed by reference in language bindings where they are represented by an object.
This means that passing an async iterable to a [=platform object=] will result in a reference to the
async iterable being kept by that object. Similarly, any async iterable returned from a platform
object will be a reference to the same object and modifications made to it will be visible to the
platform object. This is in contrast to sequences, which are always passed by value.

Note: Async iterables cannot be constructed from IDL. If returned from an operation, or used as the
type of a dictionary member, the async iterable will have originated from the host environment and
have been turned into an IDL type via a language binding. Instead of returning an async iterable
from an IDL operation, the operation might want to return an [=interface=] that has an
[=asynchronously iterable declaration=].

Async iterables must not be used as the type of an [=attribute=] or [=constant=].

There is no way to represent an async iterable value in IDL.

<h4 id="idl-record" lt="record" dfn export>Record types — record&lt;|K|, |V|&gt;</h4>

A <dfn export>record type</dfn> is a parameterized type whose values are [=ordered maps=] with
[=map/keys=] that are instances of |K| and [=map/values=] that are instances of |V|. |K| must be one
of {{DOMString}}, {{USVString}}, or {{ByteString}}.

The literal syntax for [=ordered maps=] may also be used to represent records, when it is implicitly
understood from context that the map is being treated as a record. However, there is no way to
represent a constant record value inside IDL fragments.

Records are always passed by value. In language bindings where a record
is represented by an object of some kind, passing a record
to a [=platform object=] will not result in a reference to the record
being kept by that object. Similarly, any record returned from a
platform object will be a copy and modifications made to it will not be visible
to the platform object.

Records must not be used as the type of an [=attribute=] or
[=constant=].

Any [=ordered map=] can be implicitly treated as a <code>record&lt;|K|, |V|&gt;</code>, as long as
it contains only [=map/entries=] whose [=map/keys=] are all of of type |K| and whose [=map/values=]
are all of type |V|.


<h4 oldids="dom-promise" id="idl-promise" interface lt="Promise|Promise&lt;T&gt;">Promise types — Promise&lt;|T|&gt;</h4>

A <dfn id="dfn-promise-type" export>promise type</dfn> is a parameterized type
whose values are references to objects that “is used as a place holder
for the eventual results of a deferred (and possibly asynchronous) computation
result of an asynchronous operation”.
See <a href="https://tc39.github.io/ecma262/#sec-promise-objects">section 25.4</a>
of the JavaScript specification for details on the semantics of promise objects.

Promise types are non-nullable, but |T| may be nullable.

There is no way to represent a promise value in IDL.

<h4 id="idl-union">Union types</h4>

A <dfn id="dfn-union-type" export>union type</dfn> is a type whose set of values
is the union of those in two or more other types.  Union types (matching
<emu-nt><a href="#prod-UnionType">UnionType</a></emu-nt>)
are written as a series of types separated by the <emu-t>or</emu-t> keyword
with a set of surrounding parentheses.
The types which comprise the union type are known as the
union's <dfn id="dfn-union-member-type" for="union" export>member types</dfn>.

<div class="note">

    For example, you might write <code>(Node or DOMString)</code>
    or <code>(double or sequence&lt;double&gt;)</code>.  When applying a
    <emu-t>?</emu-t> suffix to a
    [=union type=]
    as a whole, it is placed after the closing parenthesis,
    as in <code>(Node or DOMString)?</code>.

    Note that the [=member types=]
    of a union type do not descend into nested union types.  So for
    <code>(double or (sequence&lt;long&gt; or Event) or (Node or DOMString)?)</code> the member types
    are <code>double</code>, <code>(sequence&lt;long&gt; or Event)</code> and
    <code>(Node or DOMString)?</code>.

</div>

Like the {{any}} type, values of
union types have a [=specific type=],
which is the particular [=member type=]
that matches the value.

<div algorithm>

    The <dfn id="dfn-flattened-union-member-types" for="union" export>flattened member types</dfn>
    of a [=union type=], possibly [=annotated type|annotated=], is a set of types determined as
    follows:

    1.  Let |T| be the [=union type=].
    1.  Initialize |S| to ∅.
    1.  For each [=member type=] |U| of |T|:
        1.  If |U| is an [=annotated type=], then
            set |U| to be the [=annotated types/inner type=] of |U|.
        1.  If |U| is a [=nullable type=], then
            set |U| to be the [=nullable types/inner type=] of |U|.
        1.  If |U| is a [=union type=], then
            add to |S| the [=flattened member types=]
            of |U|.
        1.  Otherwise, |U| is not a [=union type=].
            Add |U| to |S|.
    1.  Return |S|.
</div>


Note: For example, the [=flattened member types=]
of the [=union type=]
<code>(Node or (sequence&lt;long&gt; or Event) or (XMLHttpRequest or DOMString)? or sequence&lt;(sequence&lt;double&gt; or NodeList)&gt;)</code>
are the six types <code>Node</code>, <code>sequence&lt;long&gt;</code>, <code>Event</code>,
<code>XMLHttpRequest</code>, <code>DOMString</code> and
<code>sequence&lt;(sequence&lt;double&gt; or NodeList)&gt;</code>.

<div algorithm>

    The <dfn id="dfn-number-of-nullable-member-types" export>number of nullable member types</dfn>
    of a [=union type=] is an integer
    determined as follows:

    1.  Let |T| be the [=union type=].
    1.  Initialize |n| to 0.
    1.  For each [=member type=] |U| of |T|:
        1.  If |U| is a [=nullable type=], then:
            1.  Set |n| to |n| + 1.
            1.  Set |U| to be the [=nullable types/inner type=] of |U|.
        1.  If |U| is a [=union type=], then:
            1.  Let |m| be the [=number of nullable member types=] of |U|.
            1.  Set |n| to |n| + |m|.
    1.  Return |n|.
</div>

The {{any}} type must not
be used as a [=member types|union member type=].

The [=number of nullable member types=]
of a [=union type=] must
be 0 or 1, and if it is 1 then the union type must also not have
a [=dictionary type=] in its [=flattened member types=].

A type <dfn id="dfn-includes-a-nullable-type" export>includes a nullable type</dfn> if:

*   the type is a [=nullable type=], or
*   the type is an [=annotated type=] and its [=annotated types/inner type=] is a nullable type, or
*   the type is a [=union type=] and its
    [=number of nullable member types=] is 1.

Each pair of [=flattened member types=]
in a [=union type=], <var ignore>T</var> and <var ignore>U</var>,
must be [=distinguishable=].

<p class="warning" id="limit-bigint-numeric-unions">
It is possible to create a union of {{bigint}} and a [=numeric type=].
However, this is generally only supposed to be used for interfaces such as
[[ECMA-402#numberformat-objects|NumberFormat]], which formats the values rather than using them in
calculations.
It would not be appropriate to accept such a union, only to then convert values of the
[=numeric type=] to a {{bigint}} for further processing, as this runs the risk of introducing
precision errors.
Please
<a href="https://github.com/whatwg/webidl/issues/new?title=Intent%20to%20use%20bigint/numeric%20union">file an issue</a>
before using this feature.
</p>

A type <dfn id="dfn-includes-undefined" export>includes undefined</dfn> if:

*   the type is {{undefined}}, or
*   the type is a [=nullable type=] and its [=nullable types/inner type=] [=includes undefined=], or
*   the type is an [=annotated type=] and its [=annotated types/inner type=] [=includes undefined=], or
*   the type is a [=union type=] and one of its [=member types=] [=includes undefined=].

[=Union type=] constant values
in IDL are represented in the same way that constant values of their
[=member types=] would be
represented.

<div grammar-fill-with="UnionType"></div>

<div grammar-fill-with="UnionMemberType"></div>

<div grammar-fill-with="UnionMemberTypes"></div>

<div grammar-fill-with="DistinguishableType"></div>


<h4 id="idl-annotated-types">Annotated types</h4>

Additional types can be created from existing ones by specifying certain [=extended attributes=] on
the existing types. Such types are called <dfn export>annotated types</dfn>, and the types they
annotate are called <dfn export for="annotated types" lt="inner type">inner types</dfn>.

<div class="example" id="example-3082499a">
    <code>[Clamp] long</code> defines a new [=annotated type=], whose behavior is based on that of
    the [=annotated types/inner type=] {{long}}, but modified as specified by the [{{Clamp}}]
    extended attribute.
</div>

The following extended attributes are <dfn for="extended attributes">applicable to types</dfn>:
[{{AllowResizable}}],
[{{AllowShared}}],
[{{Clamp}}],
[{{EnforceRange}}], and
[{{LegacyNullToEmptyString}}].

<div algorithm>
    The <dfn for="IDL type" lt="extended attribute associated with|extended attributes associated with">extended attributes associated with</dfn>
    an IDL type |type| are determined as follows:

    1.  Let |extended attributes| be a new empty [=ordered set|set=].
    1.  If |type| appears as part of a
        <emu-nt><a href="#prod-TypeWithExtendedAttributes">TypeWithExtendedAttributes</a></emu-nt>
        production, [=set/append=] each of the [=extended attributes=] present in the production's
        <emu-nt><a href="#prod-ExtendedAttributeList">ExtendedAttributeList</a></emu-nt> to
        |extended attributes|.

        <div class="example" id="example-92fcfefb">
            <pre class="idl">
                [Exposed=Window]
                interface I {
                    attribute [XAttr] long attrib;
                    undefined f1(sequence<[XAttr] long> arg);
                    undefined f2(optional [XAttr] long arg);

                    maplike&lt;[XAttr2] DOMString, [XAttr3] long>;
                };

                dictionary D {
                    required [XAttr] long member;
                };
            </pre>
        </div>
    1.  If |type| is a [=member type=] of a [=union type=] |U|, [=set/append=] each of the
        [=extended attributes associated with=] |U| to |extended attributes|.

        <div class="example" id="example-2017de6a">
            <pre class="idl">
                [Exposed=Window]
                interface I {
                    attribute [XAttr] (long or Node) attrib;
                };
            </pre>
        </div>
    1.  If |type| appears as part of a <emu-nt><a href="#prod-Type">Type</a></emu-nt> production
        directly within an <emu-nt><a href="#prod-Argument">Argument</a></emu-nt> production,
        [=set/append=] to |extended attributes| all of the [=extended attributes=] present in the
        production's
        <emu-nt><a href="#prod-ExtendedAttributeList">ExtendedAttributeList</a></emu-nt> that are
        [=applicable to types=].

        <div class="example" id="example-3f984a52">
            <pre class="idl">
                [Exposed=Window]
                interface I {
                    undefined f([XAttr] long attrib);
                };
            </pre>

            Note that this is an example of this step only if [<code>XAttr</code>] is
            [=applicable to types=]; otherwise [<code>XAttr</code>] applies to the argument, and not
            the argument's type.
        </div>
    1.  If |type| appears as part of a <emu-nt><a href="#prod-Type">Type</a></emu-nt> production
        directly within a <emu-nt><a href="#prod-DictionaryMember">DictionaryMember</a></emu-nt>
        production, [=set/append=] to |extended attributes| all of the [=extended attributes=]
        present in the production's
        <emu-nt><a href="#prod-ExtendedAttributeList">ExtendedAttributeList</a></emu-nt> that are
        [=applicable to types=].

        <div class="example" id="example-916df766">
            <pre class="idl">
                dictionary D {
                    [XAttr] long member;
                };
            </pre>

            Note that this is an example of this step only if [<code>XAttr</code>] is
            [=applicable to types=]; otherwise [<code>XAttr</code>] applies to the dictionary
            member, and not the member's type.
        </div>
    1.  If |type| is a [=typedef=], [=set/append=] the [=extended attributes associated with=] the
        [=type being given a new name=] to |extended attributes|.

        <div class="example" id="example-ee0b958b">
            <pre class="idl">
                typedef [XAttr] long xlong;
            </pre>
        </div>
    1. Return |extended attributes|.
</div>

For any type, the [=extended attributes associated with=] it must only contain
[=extended attributes=] that are [=applicable to types=].

<h4 id="idl-buffer-source-types">Buffer source types</h4>

There are a number of types that correspond to sets of all possible non-null
references to objects that represent a buffer of data or a view on to a buffer of
data. The table below lists these types and the kind of buffer or view they represent.

<table class="vert data">
    <tr>
        <th>Type
        <th>Kind of buffer
    <tr>
        <td><dfn id="idl-ArrayBuffer" interface>ArrayBuffer</dfn>
        <td>An object that holds a pointer (which can be null) to a buffer of a fixed number of bytes
    <tr>
        <td><dfn id="idl-SharedArrayBuffer" interface>SharedArrayBuffer</dfn>
        <td>An object that holds a pointer (which cannot be null) to a shared buffer of a fixed number of bytes
    <tr>
        <td><dfn id="idl-DataView" interface>DataView</dfn>
        <td>A view on to a [=buffer type=] instance that allows typed access to integers and floating point values stored at arbitrary offsets into the buffer
    <tr>
        <td><dfn id="idl-Int8Array" interface>Int8Array</dfn>
        <td rowspan=4>A view on to a [=buffer type=] instance that exposes it as an array of two's complement signed integers of the given size in bits
    <tr>
        <td><dfn id="idl-Int16Array" interface>Int16Array</dfn>
    <tr>
        <td><dfn id="idl-Int32Array" interface>Int32Array</dfn>
    <tr>
        <td><dfn id="idl-BigInt64Array" interface>BigInt64Array</dfn>
    <tr>
        <td><dfn id="idl-Uint8Array" interface>Uint8Array</dfn>
        <td rowspan=4>A view on to a [=buffer type=] instance that exposes it as an array of unsigned integers of the given size in bits
    <tr>
        <td><dfn id="idl-Uint16Array" interface>Uint16Array</dfn>
    <tr>
        <td><dfn id="idl-Uint32Array" interface>Uint32Array</dfn>
    <tr>
        <td><dfn id="idl-BigUint64Array" interface>BigUint64Array</dfn>
    <tr>
        <td><dfn id="idl-Uint8ClampedArray" interface>Uint8ClampedArray</dfn>
        <td>A view on to a [=buffer type=] instance that exposes it as an array of [=/8-bit unsigned integers=] with clamped conversions
    <tr>
        <td><dfn id="idl-Float16Array" interface>Float16Array</dfn>
        <td rowspan=3>A view on to a [=buffer type=] instance that exposes it as an array of IEEE 754 floating point numbers of the given size in bits; Float16Array corresponds to the ECMAScript proposal [[PROPOSAL-FLOAT16ARRAY]].
    <tr>
        <td><dfn id="idl-Float32Array" interface>Float32Array</dfn>
    <tr>
        <td><dfn id="idl-Float64Array" interface>Float64Array</dfn>
</table>

Note: These types all correspond to classes defined in JavaScript.

There is no way to represent a constant value of any of these types in IDL.

At the specification prose level, IDL [=buffer source types=] are simply references to objects. To
inspect or manipulate the bytes inside the buffer, specification prose needs to use the algorithms
in [[#js-buffer-source-types]].

<pre class="grammar" id="prod-BufferRelatedType">
    BufferRelatedType :
        "ArrayBuffer"
        "SharedArrayBuffer"
        "DataView"
        "Int8Array"
        "Int16Array"
        "Int32Array"
        "Uint8Array"
        "Uint16Array"
        "Uint32Array"
        "Uint8ClampedArray"
        "BigInt64Array"
        "BigUint64Array"
        "Float16Array"
        "Float32Array"
        "Float64Array"
</pre>


<h4 oldids="dom-FrozenArray" id="idl-frozen-array" interface lt="FrozenArray|FrozenArray&lt;T&gt;">Frozen array types — FrozenArray&lt;|T|&gt;</h4>

A <dfn id="dfn-frozen-array-type" export>frozen array type</dfn> is a parameterized
type whose values are references to objects that hold a fixed length array
of unmodifiable values.  The values in the array are of type |T|.

Frozen array types must only be used as the type of [=regular attributes=] or [=static attributes=]
defined on an [=interface=].

<div class="example" id="example-frozen-array">
    The following [=IDL fragment=] defines an [=interface=] with two frozen array attributes, one
    [=read only=] and one not.

    <pre highlight="webidl">
        [Exposed=Window]
        interface PersonalPreferences {
            readonly attribute FrozenArray&lt;DOMString> favoriteColors;
            attribute FrozenArray&lt;DOMString> favoriteFoods;

            undefined randomizeFavoriteColors();
        };
    </pre>

    The behavior of these attributes could be defined like so:

    <blockquote>
        Each <code>PersonalPreferences</code> has associated <b>favorite colors</b>, a {{FrozenArray}}&lt;{{DOMString}}>, initially equal to the result of [=creating a frozen array=] from « "<code>purple</code>", "<code>aquamarine</code>" ».

        Each <code>PersonalPreferences</code> has an associated <b>favorite foods</b>, a {{FrozenArray}}&lt;{{DOMString}}>, initially equal to the result of [=creating a frozen array=] from the empty list.

        The <code>favoriteColors</code> [=getter steps=] are to return [=this=]'s favorite colors.

        The <code>favoriteFoods</code> [=getter steps=] are to return [=this=]'s favorite foods.

        The <code>favoriteFoods</code> [=setter steps=] are to set [=this=]'s favorite foods to [=the given value=].

        The <code>randomizeFavoriteColors()</code> [=method steps=] are:

        1. Let |newFavoriteColors| be a list of two strings representing colors, chosen randomly.

        1. Set [=this=]'s favorite colors to the result of [=creating a frozen array=] from |newFavoriteColors|.
    </blockquote>
</div>

Since <a interface lt="FrozenArray">FrozenArray&lt;|T|&gt;</a> values
are references, they are unlike [=sequence types=],
which are lists of values that are passed by value.

There is no way to represent a constant frozen array value in IDL.

<h4 id="idl-observable-array" interface lt="ObservableArray|ObservableArray&lt;T&gt;">Observable array types — ObservableArray&lt;|T|&gt;</h4>

An <dfn id="dfn-observable-array-type" export>observable array type</dfn> is a parameterized type
whose values are references to a combination of a mutable list of objects of type |T|, as well as
behavior to perform when author code modifies the contents of the list.

The parameterized type |T| must not be a [=dictionary type=], [=sequence type=], [=record type=],
or [=observable array type=]. However, |T| may be nullable.

Similar to [=sequence types=] and [=frozen array types=], observable array types wrap around
JavaScript array types, imposing additional semantics on their usage.

Observable array types must only be used as the type of [=regular attributes=] defined on an [=interface=].

For an attribute whose type is an observable array type, specification authors can specify a series
of algorithms:

*   <dfn export for="observable array attribute">set an indexed value</dfn>, which accepts an IDL
    value that is about to be set in the observable array, and the index at which it is being set;
*   <dfn export for="observable array attribute">delete an indexed value</dfn>, which accepts an
    IDL value that is about to be removed from the observable array, and the index from which it is
    being removed.

Both of these algorithms are optional, and if not provided, the default behavior will be to do
nothing. Either algorithm may throw an exception, e.g., to reject invalid values.

Note that when JavaScript code sets an existing index to a new value, this will first call the
[=observable array attribute/delete an indexed value=] algorithm to remove the existing value, and
then the [=observable array attribute/set an indexed value=] algorithm with the new value.

Every [=regular attribute=] whose type is an [=observable array type=] has a
<dfn export for="observable array attribute">backing list</dfn>, which is a [=list=], initially empty.
Specification authors can modify the contents of the backing list, which will automatically be
reflected in the contents of the observable array as observed by JavaScript code. Similarly, any
modifications by JavaScript code to the contents of the observable array will be reflected back into
the backing list, after passing through the [=observable array attribute/set an indexed value=] and
[=observable array attribute/delete an indexed value=] algorithms.

There is no way to represent a constant observable array value in IDL.

<div class="example" id="example-observable-array">
    <span id="example-af5d265e"></span>
    The following [=IDL fragment=] defines an [=interface=] with an observable array attribute:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Building {
          attribute ObservableArray&lt;Employee> employees;
        };
    </pre>

    The behavior of the attribute could be defined like so:

    <blockquote>
        The [=observable array attribute/set an indexed value=] algorithm for
        <code class="idl">Building</code>'s <code class="idl">employees</code> attribute, given
        |employee| and |index|, is:

        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.  Put |employee| to work!

        The [=observable array attribute/delete an indexed value=] algorithm for
        <code class="idl">Building</code>'s <code class="idl">employees</code> attribute, given
        |employee| and <var ignore>index</var>, is:

        1.  Alert security that |employee| has left the building.
    </blockquote>

    Then, JavaScript code could manipulate the <code class="idl">employees</code> property in
    various ways:

    <pre highlight="js">
        // Get an instance of Building.
        const building = getBuilding();

        building.employees.push(new Employee("A"));
        building.employees.push(new Employee("B"));
        building.employees.push(new Employee("C"));

        building.employees.splice(2, 1);
        const employeeB = building.employees.pop();

        building.employees = [new Employee("D"), employeeB, new Employee("C")];

        building.employees.length = 0;

        // Will throw:
        building.employees.push("not an Employee; a string instead");
    </pre>

    All of these manipulations would pass through the above-defined
    [=observable array attribute/set an indexed value=] algorithm, potentially throwing if the
    conditions described there were met. They would also perform the appropriate side effects listed
    there and in the [=observable array attribute/delete an indexed value=] algorithm.

    Another thing to note about the above code example is how all of the JavaScript array methods
    from {{%Array.prototype%}} work on the observable array. Indeed, it fully behaves like an
    <code>Array</code> instance:

    <pre highlight="js">
        const normalArray = [];

        // If building.employees were defined as an indexed property getter interface: normalArray
        // would contains a single item, building.employees.
        //
        // For observable arrays (and frozen arrays): normalArray contains all of the items inside
        // of building.employees.
        normalArray.concat(building.employees);

        // names is a JavaScript Array.
        const names = building.employees.map(employee => employee.name);

        // Passes various brand checks:
        console.assert(building.employees instanceof Array);
        console.assert(Array.isArray(building.employees));
        console.assert(building.employees.constructor === Array);

        // Even is treated as an array by JSON.stringify! (Note the outer []s.)
        console.assert(JSON.stringify(building.employees) === `[{}]`);
    </pre>
</div>

<h3 id="idl-extended-attributes">Extended attributes</h3>

An <dfn id="dfn-extended-attribute" export>extended attribute</dfn> is an annotation
that can appear on
[=definitions=],
types as [=annotated types=],
[=interface members=],
[=interface mixin members=],
[=callback interface members=],
[=namespace members=],
[=dictionary members=],
and [=operation=] arguments, and
is used to control how language bindings will handle those constructs.
Extended attributes are specified with an
<emu-nt><a href="#prod-ExtendedAttributeList">ExtendedAttributeList</a></emu-nt>,
which is a square bracket enclosed, comma separated list of
<emu-nt><a href="#prod-ExtendedAttribute">ExtendedAttribute</a></emu-nt>s.

The <emu-nt><a href="#prod-ExtendedAttribute">ExtendedAttribute</a></emu-nt>
grammar symbol matches nearly any sequence of tokens, however the
[=extended attributes=]
defined in this document only accept a more restricted syntax.
Any extended attribute encountered in an
[=IDL fragment=] is
matched against the following five grammar symbols to determine
which form (or forms) it is in:

<table class="vert data">
    <tr>
        <th>Grammar symbol</th>
        <th>Form</th>
        <th>Example</th>
    </tr>
    <tr>
        <td>
            <emu-nt><a href="#prod-ExtendedAttributeNoArgs">ExtendedAttributeNoArgs</a></emu-nt>
        </td>
        <td>
            <dfn id="dfn-xattr-no-arguments" for="extended attribute" export>takes no arguments</dfn>
        </td>
        <td>
            <code>[Replaceable]</code>
        </td>
    </tr>
    <tr>
        <td>
            <emu-nt><a href="#prod-ExtendedAttributeArgList">ExtendedAttributeArgList</a></emu-nt>
        </td>
        <td>
            <dfn id="dfn-xattr-argument-list" for="extended attribute" export>takes an argument list</dfn>
        </td>
        <td>
            Not currently used; previously used by <code>[Constructor(double x, double y)]</code>
        </td>
    </tr>
    <tr>
        <td>
            <emu-nt><a href="#prod-ExtendedAttributeNamedArgList">ExtendedAttributeNamedArgList</a></emu-nt>
        </td>
        <td>
            <dfn id="dfn-xattr-named-argument-list" for="extended attribute" export>takes a named argument list</dfn>
        </td>
        <td>
            <code>[LegacyFactoryFunction=Image(DOMString src)]</code>
        </td>
    </tr>
    <tr>
        <td>
            <emu-nt><a href="#prod-ExtendedAttributeIdent">ExtendedAttributeIdent</a></emu-nt>
        </td>
        <td>
            <dfn id="dfn-xattr-identifier" for="extended attribute" export>takes an identifier</dfn>
        </td>
        <td>
            <code>[PutForwards=name]</code>
        </td>
    </tr>
    <tr>
        <td>
            <emu-nt><a href="#prod-ExtendedAttributeIdentList">ExtendedAttributeIdentList</a></emu-nt>
        </td>
        <td>
            <dfn id="dfn-xattr-identifier-list" for="extended attribute" export>takes an identifier list</dfn>
        </td>
        <td>
            <code>[Exposed=(Window,Worker)]</code>
        </td>
    </tr>
    <tr>
        <td>
            <emu-nt><a href="#prod-ExtendedAttributeWildcard">ExtendedAttributeWildcard</a></emu-nt>
        </td>
        <td>
            <dfn id="dfn-xattr-wildcard" for="extended attribute" export>takes a wildcard</dfn>
        </td>
        <td>
            <code>[Exposed=*]</code>
        </td>
    </tr>

</table>

This specification defines a number of extended attributes that
are applicable to the JavaScript language binding, which are described in
[[#js-extended-attributes]].
Each extended attribute definition will state which of the above
five forms are allowed.

<pre class="grammar" id="prod-ExtendedAttributeList">
    ExtendedAttributeList :
        "[" ExtendedAttribute ExtendedAttributes "]"
        ε
</pre>

<pre class="grammar" id="prod-ExtendedAttributes">
    ExtendedAttributes :
        "," ExtendedAttribute ExtendedAttributes
        ε
</pre>

<pre class="grammar" id="prod-ExtendedAttribute">
    ExtendedAttribute :
        "(" ExtendedAttributeInner ")" ExtendedAttributeRest
        "[" ExtendedAttributeInner "]" ExtendedAttributeRest
        "{" ExtendedAttributeInner "}" ExtendedAttributeRest
        Other ExtendedAttributeRest
</pre>

<pre class="grammar" id="prod-ExtendedAttributeRest">
    ExtendedAttributeRest :
        ExtendedAttribute
        ε
</pre>

<pre class="grammar" id="prod-ExtendedAttributeInner">
    ExtendedAttributeInner :
        "(" ExtendedAttributeInner ")" ExtendedAttributeInner
        "[" ExtendedAttributeInner "]" ExtendedAttributeInner
        "{" ExtendedAttributeInner "}" ExtendedAttributeInner
        OtherOrComma ExtendedAttributeInner
        ε
</pre>

<pre class="grammar" id="prod-Other">
    Other :
        integer
        decimal
        identifier
        string
        other
        "-"
        "-Infinity"
        "."
        "..."
        ":"
        ";"
        "&lt;"
        "="
        "&gt;"
        "?"
        "*"
        "ByteString"
        "DOMString"
        "FrozenArray"
        "Infinity"
        "NaN"
        "ObservableArray"
        "Promise"
        "USVString"
        "any"
        "bigint"
        "boolean"
        "byte"
        "double"
        "false"
        "float"
        "long"
        "null"
        "object"
        "octet"
        "or"
        "optional"
        "record"
        "sequence"
        "short"
        "symbol"
        "true"
        "unsigned"
        "undefined"
        ArgumentNameKeyword
        BufferRelatedType
</pre>

<pre class="grammar" id="prod-OtherOrComma">
    OtherOrComma :
        Other
        ","
</pre>

<pre class="grammar" id="prod-IdentifierList">
    IdentifierList :
        identifier Identifiers
</pre>

<pre class="grammar" id="prod-Identifiers">
    Identifiers :
        "," identifier Identifiers
        ε
</pre>

<pre class="grammar" id="prod-ExtendedAttributeNoArgs">
    ExtendedAttributeNoArgs :
        identifier
</pre>

<pre class="grammar" id="prod-ExtendedAttributeArgList">
    ExtendedAttributeArgList :
        identifier "(" ArgumentList ")"
</pre>

<pre class="grammar" id="prod-ExtendedAttributeIdent">
    ExtendedAttributeIdent :
        identifier "=" identifier
</pre>

<pre class="grammar" id="prod-ExtendedAttributeWildcard">
    ExtendedAttributeWildcard :
        identifier "=" "*"
</pre>

<pre class="grammar" id="prod-ExtendedAttributeIdentList">
    ExtendedAttributeIdentList :
        identifier "=" "(" IdentifierList ")"
</pre>

<pre class="grammar" id="prod-ExtendedAttributeNamedArgList">
    ExtendedAttributeNamedArgList :
        identifier "=" identifier "(" ArgumentList ")"
</pre>


<h2 id="javascript-binding" oldids="ecmascript-binding">JavaScript binding</h2>

This section describes how definitions written with the IDL defined in
[[#idl]] correspond to particular constructs
in JavaScript, as defined by the <cite>ECMAScript Language Specification</cite>
[[!ECMA-262]].

Unless otherwise specified, objects defined in this section are ordinary objects as described in
[[ecmascript#sec-ordinary-object-internal-methods-and-internal-slots]], and if the
object is a [=function object=], [[ecmascript#sec-built-in-function-objects]].

This section may redefine certain internal methods and internal slots of objects. Other
specifications may also override the definitions of any internal method or internal slots of a
[=platform object=] that is an instance of an [=interface=]. These objects with changed semantics
shall be treated in accordance with the rules for exotic objects.

<p class="warning">
    As overriding internal JavaScript object methods is a low level operation and
    can result in objects that behave differently from ordinary objects,
    this facility should not be used unless necessary
    for security or compatibility. <span class="non-normative">This is currently used to define the
    {{HTMLAllCollection}} and {{Location}} interfaces. [[HTML]]</span>
</p>

Unless otherwise specified, exotic objects defined in this section and other specifications have the
same [=ordinary object/internal slots=] as ordinary objects, and all of the internal methods for
which alternative definitions are not given are the same as [=ordinary object/internal
methods|those=] of ordinary objects.

Unless otherwise specified, the \[[Extensible]] internal slot
of objects defined in this section has the value <emu-val>true</emu-val>.

Unless otherwise specified, the \[[Prototype]] internal slot
of objects defined in this section is {{%Object.prototype%}}.

Some objects described in this section are defined to have a <dfn id="dfn-class-string" export>class string</dfn>,
which is the string to include in the string returned from <code>Object.prototype.toString</code>.

If an object has a [=class string=] |classString|, then the object must,
at the time it is created, have a property whose name is the {{%Symbol.toStringTag%}} symbol
with PropertyDescriptor{\[[Writable]]: <emu-val>false</emu-val>,
\[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val>,
\[[Value]]: |classString|}.

<p id="ecmascript-abstractop">
    Algorithms in this section use the conventions described in [[ecmascript#sec-algorithm-conventions]], such as the use of steps and substeps, the use of mathematical
    operations, and so on.  This section may also reference abstract operations
    and notations defined in other parts of ECMA-262.
</p>

When an algorithm says to
<dfn noexport lt="JavaScript throw|ECMAScript throw" local-lt="throw" for="JavaScript" id="javascript-throw" oldids="ecmascript-throw">throw</dfn> a <code>|Something|Error</code>
then this means to construct a new JavaScript <code>|Something|Error</code> object in
the [=current realm=] and to throw it, just as the algorithms in ECMA-262 do.

Note that algorithm steps can call in to other algorithms and abstract operations and
not explicitly handle exceptions that are thrown from them.  When an exception
is thrown by an algorithm or abstract operation and it is not explicitly
handled by the caller, then it is taken to end the algorithm and propagate out
to its caller, and so on.

<div class="example" id="example-18239b52">

    <div algorithm="example algorithm">

        Consider the following algorithm:

        1.  Let |x| be the JavaScript value passed in to this algorithm.
        1.  Let |y| be the result of calling [=?=] <a abstract-op>ToString</a>(|x|).
        1.  Return |y|.
    </div>

    Since <a abstract-op>ToString</a> can throw an exception (for example if passed the object
    <code>({ toString: function() { throw 1 } })</code>), and the exception is
    not handled in the above algorithm, if one is thrown then it causes this
    algorithm to end and for the exception to propagate out to its caller, if there
    is one.

</div>


<h3 id="js-environment" oldids="es-environment">JavaScript environment</h3>

In a JavaScript implementation of a given set of
[=IDL fragments=],
there will exist a number of JavaScript objects that correspond to
definitions in those [=IDL fragments=].
These objects are termed the <dfn id="dfn-initial-object" export>initial objects</dfn>,
and comprise the following:

*   [=interface objects=]
*   [=legacy callback interface objects=]
*   [=legacy factory functions=]
*   [=interface prototype objects=]
*   [=named properties objects=]
*   [=iterator prototype objects=]
*   [=attribute getters=]
*   [=attribute setters=]
*   <a href="#js-operations">the function objects that correspond to operations</a>
*   <a href="#js-stringifier">the function objects that correspond to stringifiers</a>

Each [=realm=]
must have its own unique set of each of
the [=initial objects=], created
before control enters any JavaScript execution context associated with the
realm, but after the [=realm/global object=] for that realm is created.  The \[[Prototype]]s
of all initial objects in a given [=realm=] must come from
that same [=realm=].

<div class="example" id="example-9af59e92">

    In an HTML user agent, multiple [=realms=] can exist when
    multiple frames or windows are created.  Each frame or window will have
    its own set of [=initial objects=],
    which the following HTML document demonstrates:

    <pre highlight="html">
        &lt;!DOCTYPE html&gt;
        &lt;title&gt;Different Realms&lt;/title&gt;
        &lt;iframe id=a&gt;&lt;/iframe&gt;
        &lt;script&gt;
        var iframe = document.getElementById("a");
        var w = iframe.contentWindow;              // The global object in the frame

        Object == w.Object;                        // Evaluates to false, per ECMA-262
        Node == w.Node;                            // Evaluates to false
        iframe instanceof w.Node;                  // Evaluates to false
        iframe instanceof w.Object;                // Evaluates to false
        iframe.appendChild instanceof Function;    // Evaluates to true
        iframe.appendChild instanceof w.Function;  // Evaluates to false
        &lt;/script&gt;
    </pre>
</div>

Note: All [=interfaces=] define which [=realms=] they are [=exposed=] in.
This allows, for example, [=realms=] for Web Workers to [=expose=]
different sets of supported interfaces from those exposed in realms
for Web pages.

Although at the time of this writing the JavaScript specification does not reflect this,
every JavaScript object must have an <dfn id="dfn-associated-realm" export>associated [=realm=]</dfn>. The mechanisms
for associating objects with realms are, for now, underspecified. However, we note that
in the case of [=platform objects=], the
associated realm is equal to the object's [=relevant realm=], and
for non-exotic [=function objects=] (i.e. not [=ECMAScript/callable=] proxies, and not bound functions)
the associated realm is equal to the value of the [=function object=]'s \[[Realm]] internal
slot.


<h3 id="js-type-mapping" oldids="es-type-mapping">JavaScript type mapping</h3>

This section describes how types in the IDL map to types in JavaScript.

Each sub-section below describes how values of a given IDL type are represented
in JavaScript.  For each IDL type, it is described how JavaScript values are
<dfn id="dfn-convert-ecmascript-to-idl-value" export lt="converted to an IDL value|converted to IDL values">converted to an IDL value</dfn>
when passed to a [=platform object=] expecting that type, and how IDL values
of that type are <dfn id="dfn-convert-idl-to-javascript-value" oldids="dfn-convert-idl-to-ecmascript-value" export lt="converted to a JavaScript value|converted to JavaScript values|converted to an ECMAScript value|converted to ECMAScript values">converted to JavaScript values</dfn>
when returned from a platform object.

Note that the sub-sections and algorithms below also apply to [=annotated types=] created by applying
extended attributes to the types named in their headers.


<h4 id="js-any" oldids="es-any">any</h4>

Since the IDL {{any}} type
is the union of all other IDL types, it can correspond to any
JavaScript value type.

<div id="js-to-any" algorithm="convert a JavaScript value to any">
    <span id="es-to-any"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{any}} value by running the following algorithm:

    1.  If |V| is <emu-val>undefined</emu-val>, then
        return the unique {{undefined}} IDL value.
    1.  If |V| is <emu-val>null</emu-val>, then
        return the <emu-val>null</emu-val> {{object|object?}} reference.
    1.  If |V| [=is a Boolean=], then
        return the {{boolean}} value that represents the same truth value.
    1.  If |V| [=is a Number=], then
        return the result of <a href="#js-to-unrestricted-double">converting</a> |V|
        to an {{unrestricted double}}.
    1.  If |V| [=is a BigInt=], then
        return the result of <a href="#js-to-bigint">converting</a> |V|
        to a {{bigint}}.
    1.  If |V| [=is a String=], then
        return the result of <a href="#js-to-DOMString">converting</a> |V|
        to a {{DOMString}}.
    1.  If |V| [=is a Symbol=], then
        return the result of <a href="#js-symbol">converting</a> |V|
        to a {{symbol}}.
    1.  If |V| [=is an Object=], then
        return an IDL {{object}} value that references |V|.
</div>

<p id="any-to-js">
    <span id="any-to-es"></span>
    An IDL {{any}} value is [=converted to a JavaScript value=]
    according to the rules for converting
    the [=specific type=] of the IDL {{any}} value
    as described in the remainder of this section.
</p>


<h4 id="js-undefined" oldids="es-undefined,es-void,es-to-void,void-to-es">undefined</h4>

<p id="js-to-undefined">
    <span id="es-to-undefined"></span>
    A JavaScript value |V| is [=converted to an IDL value|converted=] to an IDL {{undefined}} value by
    returning the unique {{undefined}} value, ignoring |V|.
</p>

<p id="undefined-to-js">
    <span id="undefined-to-es"></span>
    The unique IDL {{undefined}} value is [=converted to a JavaScript value|converted=] to the
    JavaScript <emu-val>undefined</emu-val> value.
</p>


<h4 id="js-boolean" oldids="es-boolean">boolean</h4>

<div id="js-to-boolean" algorithm="convert a JavaScript value to boolean">
    <span id="es-to-boolean"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{boolean}} value by running the following algorithm:

    1.  Let |x| be the result of computing <a abstract-op>ToBoolean</a>(|V|).
    1.  Return the IDL {{boolean}} value that is the one that
        represents the same truth value as the
        JavaScript Boolean value |x|.
</div>

<p id="boolean-to-js">
    <span id="boolean-to-es"></span>
    The IDL {{boolean}} value <code class="idl">true</code>
    is [=convert to a JavaScript value|converted=] to
    the JavaScript <emu-val>true</emu-val> value and the IDL {{boolean}}
    value <code class="idl">false</code> is converted to the JavaScript
    <emu-val>false</emu-val> value.
</p>

<h4 id="js-integer-types" oldids="es-integer-types">Integer types</h4>

Mathematical operations used in this section,
including those defined in [[ecmascript#sec-algorithm-conventions]],
are to be understood as computing exact mathematical results
on mathematical real numbers.

In effect, where <var ignore>x</var> is a Number value,
“operating on <var ignore>x</var>” is shorthand for
“operating on the mathematical real number that represents the same numeric value as <var ignore>x</var>”.

<h5 id="js-byte" oldids="es-byte">byte</h5>

<div id="js-to-byte" algorithm="convert a JavaScript value to byte">
    <span id="es-to-byte"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{byte}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 8, "<code>signed</code>").
    1.  Return the IDL {{byte}} value that represents the same numeric value as |x|.
</div>

<p id="byte-to-js">
    <span id="byte-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL {{byte}} value to a JavaScript
    value is a Number that represents
    the same numeric value as the IDL {{byte}} value.
    The Number value will be an integer in the range [−128, 127].
</p>


<h5 id="js-octet" oldids="es-octet">octet</h5>

<div id="js-to-octet" algorithm="convert a JavaScript value to octet">
    <span id="es-to-octet"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{octet}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 8, "<code>unsigned</code>").
    1.  Return the IDL {{octet}} value that represents the same numeric value as |x|.
</div>

<p id="octet-to-js">
    <span id="octet-to-es"></span>
    The result of [=convert to a JavaScript value|converting=]
    an IDL {{octet}} value to a JavaScript
    value is a Number that represents
    the same numeric value as the IDL
    {{octet}} value.
    The Number value will be an integer in the range [0, 255].
</p>


<h5 id="js-short" oldids="es-short">short</h5>

<div id="js-to-short" algorithm="convert a JavaScript value to short">
    <span id="es-to-short"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{short}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 16, "<code>signed</code>").
    1.  Return the IDL {{short}} value that represents the same numeric value as |x|.

</div>

<p id="short-to-js">
    <span id="short-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL {{short}} value to a JavaScript
    value is a Number that represents the
    same numeric value as the IDL
    {{short}} value.
    The Number value will be an integer in the range [−32768, 32767].
</p>


<h5 id="js-unsigned-short" oldids="es-unsigned-short">unsigned short</h5>

<div id="js-to-unsigned-short" algorithm="convert a JavaScript value to unsigned short">
    <span id="es-to-unsigned-short"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{unsigned short}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 16, "<code>unsigned</code>").
    1.  Return the IDL {{unsigned short}} value that represents the same numeric value as |x|.
</div>

<p id="unsigned-short-to-js">
    <span id="unsigned-short-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL {{unsigned short}} value to a JavaScript
    value is a Number that
    represents the same numeric value as the IDL
    {{unsigned short}} value.
    The Number value will be an integer in the range [0, 65535].
</p>


<h5 id="js-long" oldids="es-long">long</h5>

<div id="js-to-long" algorithm="convert a JavaScript value to long">
    <span id="es-to-long"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{long}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 32, "<code>signed</code>").
    1.  Return the IDL {{long}} value that represents the same numeric value as |x|.
</div>

<p id="long-to-js">
    <span id="long-to-es"></span>
    The result of [=convert to a JavaScript value|converting=]
    an IDL {{long}} value to a JavaScript
    value is a Number that
    represents the same numeric value as the IDL
    {{long}} value.
    The Number value will be an integer in the range [−2147483648, 2147483647].
</p>


<h5 id="js-unsigned-long" oldids="es-unsigned-long">unsigned long</h5>

<div id="js-to-unsigned-long" algorithm="convert a JavaScript value to unsigned long">
    <span id="es-to-unsigned-long"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{unsigned long}} value  by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 32, "<code>unsigned</code>").
    1.  Return the IDL {{unsigned long}} value that represents the same numeric value as |x|.
</div>

<p id="unsigned-long-to-js">
    <span id="unsigned-long-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL {{unsigned long}} value to a JavaScript
    value is a Number that
    represents the same numeric value as the IDL
    {{unsigned long}} value.
    The Number value will be an integer in the range [0, 4294967295].
</p>


<h5 id="js-long-long" oldids="es-long-long">long long</h5>

<div id="js-to-long-long" algorithm="convert a JavaScript value to long long">
    <span id="es-to-long-long"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{long long}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 64, "<code>signed</code>").
    1.  Return the IDL {{long long}} value that represents the same numeric value as |x|.
</div>

<p id="long-long-to-js">
    <span id="long-long-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL {{long long}} value to a JavaScript
    value is a Number value that
    represents the closest numeric value to the {{long long}},
    choosing the numeric value with an <em>even significand</em> if there are
    two [=equally close values=].
    If the {{long long}} is in the range
    [−2<sup>53</sup> + 1, 2<sup>53</sup> − 1], then the Number
    will be able to represent exactly the same value as the
    {{long long}}.
</p>


<h5 id="js-unsigned-long-long" oldids="es-unsigned-long-long">unsigned long long</h5>

<div id="js-to-unsigned-long-long" algorithm="convert a JavaScript value to unsigned long long">
    <span id="es-to-unsigned-long-long"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{unsigned long long}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ConvertToInt</a>(|V|, 64, "<code>unsigned</code>").
    1.  Return the IDL {{unsigned long long}} value that represents the same numeric value as |x|.
</div>

<p id="unsigned-long-long-to-js">
    <span id="unsigned-long-long-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL {{unsigned long long}} value to a JavaScript
    value is a Number value that
    represents the closest numeric value to the {{unsigned long long}},
    choosing the numeric value with an <em>even significand</em> if there are
    two [=equally close values=].
    If the {{unsigned long long}} is less than or equal to 2<sup>53</sup> − 1,
    then the Number will be able to
    represent exactly the same value as the
    {{unsigned long long}}.
</p>

<h5 id="js-integer-types-abstract-ops" oldids="es-integer-types-abstract-ops">Abstract operations</h5>

<div algorithm>

    <dfn lt="IntegerPart" abstract-op>IntegerPart(|n|)</dfn>:

    1.  Let |r| be <a abstract-op>floor</a>(<a abstract-op>abs</a>(|n|)).
    1.  If |n| &lt; 0, then return -1 × |r|.
    1.  Otherwise, return |r|.
</div>

<div algorithm>

    <dfn lt="ConvertToInt" abstract-op>ConvertToInt(|V|, |bitLength|, |signedness|)</dfn>:

    1.  If |bitLength| is 64, then:
        1.  Let |upperBound| be 2<sup>53</sup> − 1.
        1.  If |signedness| is "<code>unsigned</code>", then let |lowerBound| be 0.
        1.  Otherwise let |lowerBound| be −2<sup>53</sup> + 1.

            Note: this ensures {{long long}} types
            [=extended attribute associated with|associated with=] [{{EnforceRange}}] or
            [{{Clamp}}] [=extended attributes=] are representable in JavaScript's [=Number type=]
            as unambiguous integers.

    1.  Otherwise, if |signedness| is "<code>unsigned</code>", then:
        1.  Let |lowerBound| be 0.
        1.  Let |upperBound| be 2<sup>|bitLength|</sup> − 1.
    1.  Otherwise:
        1.  Let |lowerBound| be -2<sup>|bitLength| − 1</sup>.
        1.  Let |upperBound| be 2<sup>|bitLength| − 1</sup> − 1.
    1.  Let |x| be [=?=] <a abstract-op>ToNumber</a>(|V|).
    1.  If |x| is −0, then set |x| to +0.
    1.  If the conversion is to an IDL type [=extended attribute associated with|associated with=]
        the [{{EnforceRange}}] [=extended attribute=], then:
        1.  If |x| is <emu-val>NaN</emu-val>, +∞, or −∞,
            then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
        1.  Set |x| to <a abstract-op>IntegerPart</a>(|x|).
        1.  If |x| &lt; |lowerBound| or |x| &gt; |upperBound|,
            then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
        1.  Return |x|.
    1.  If |x| is not <emu-val>NaN</emu-val> and the conversion is to an IDL type
        [=extended attribute associated with|associated with=] the [{{Clamp}}] extended attribute,
        then:
        1.  Set |x| to <a abstract-op>min</a>(<a abstract-op>max</a>(|x|, |lowerBound|), |upperBound|).
        1.  Round |x| to the nearest integer, choosing the even integer if it lies halfway between two,
            and choosing +0 rather than −0.
        1.  Return |x|.
    1.  If |x| is <emu-val>NaN</emu-val>, +0, +∞, or −∞,
        then return +0.
    1.  Set |x| to <a abstract-op>IntegerPart</a>(|x|).
    1.  Set |x| to |x| [=modulo=] 2<sup>|bitLength|</sup>.
    1.  If |signedness| is "<code>signed</code>" and |x| ≥ 2<sup>|bitLength| − 1</sup>,
        then return |x| − 2<sup>|bitLength|</sup>.
    1.  Otherwise, return |x|.
</div>


<h4 id="js-float" oldids="es-float">float</h4>

<div id="js-to-float" algorithm="convert a JavaScript value to float">
    <span id="es-to-float"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{float}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ToNumber</a>(|V|).
    1.  If |x| is <emu-val>NaN</emu-val>, +∞, or −∞,
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Let |S| be the set of finite IEEE 754 single-precision floating
        point values except −0, but with two special values added: 2<sup>128</sup> and
        −2<sup>128</sup>.
    1.  Let |y| be the number in |S| that is closest
        to |x|, selecting the number with an
        <em>even significand</em> if there are two [=equally close values=].
        (The two special values 2<sup>128</sup> and −2<sup>128</sup>
        are considered to have even significands for this purpose.)
    1.  If |y| is 2<sup>128</sup> or −2<sup>128</sup>, then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  If |y| is +0 and |x| is negative, return −0.
    1.  Return |y|.
</div>

<p id="float-to-js">
    <span id="float-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL {{float}} value to a JavaScript
    value is the Number value that represents the same numeric value as the IDL
    {{float}} value.
</p>


<h4 id="js-unrestricted-float" oldids="es-unrestricted-float">unrestricted float</h4>

<div id="js-to-unrestricted-float" algorithm="convert a JavaScript value to unrestricted float">
    <span id="es-to-unrestricted-float"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{unrestricted float}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ToNumber</a>(|V|).
    1.  If |x| is <emu-val>NaN</emu-val>, then return the IDL {{unrestricted float}} value that represents the IEEE 754 NaN value with the bit pattern 0x7fc00000 [[!IEEE-754]].
    1.  Let |S| be the set of finite IEEE 754 single-precision floating
        point values except −0, but with two special values added: 2<sup>128</sup> and
        −2<sup>128</sup>.
    1.  Let |y| be the number in |S| that is closest
        to |x|, selecting the number with an
        <em>even significand</em> if there are two [=equally close values=].
        (The two special values 2<sup>128</sup> and −2<sup>128</sup>
        are considered to have even significands for this purpose.)
    1.  If |y| is 2<sup>128</sup>, return +∞.
    1.  If |y| is −2<sup>128</sup>, return −∞.
    1.  If |y| is +0 and |x| is negative, return −0.
    1.  Return |y|.
</div>

Note: Since there is only a single JavaScript <emu-val>NaN</emu-val> value,
it must be canonicalized to a particular single precision IEEE 754 NaN value.  The NaN value
mentioned above is chosen simply because it is the quiet NaN with the lowest
value when its bit pattern is interpreted as an [=/32-bit unsigned integer=].

<div id="unrestricted-float-to-js" algorithm="convert an unrestricted float to a JavaScript value">
    <span id="unrestricted-float-to-es"></span>

    The result of [=convert to a JavaScript value|converting=]
    an IDL {{unrestricted float}} value to a JavaScript
    value is a Number:

    1.  If the IDL {{unrestricted float}} value is a NaN,
        then the Number value is <emu-val>NaN</emu-val>.
    1.  Otherwise, the Number value is
        the one that represents the same numeric value as the IDL
        {{unrestricted float}} value.
</div>


<h4 id="js-double" oldids="es-double">double</h4>

<div id="js-to-double" algorithm="convert a JavaScript value to double">
    <span id="es-to-double"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{double}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ToNumber</a>(|V|).
    1.  If |x| is <emu-val>NaN</emu-val>, +∞, or −∞,
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Return the IDL {{double}} value
        that represents the same numeric value as |x|.
</div>

<p id="double-to-js">
    <span id="double-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL {{double}} value to a JavaScript
    value is the Number value that represents the
    same numeric value as the IDL {{double}} value.
</p>


<h4 id="js-unrestricted-double" oldids="es-unrestricted-double">unrestricted double</h4>

<div id="js-to-unrestricted-double" algorithm="convert a JavaScript value to unrestricted double">
    <span id="es-to-unrestricted-double"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{unrestricted double}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ToNumber</a>(|V|).
    1.  If |x| is <emu-val>NaN</emu-val>, then
        return the IDL {{unrestricted double}} value that represents
        the IEEE 754 NaN value with the bit pattern 0x7ff8000000000000 [[!IEEE-754]].
    1.  Return the IDL {{unrestricted double}} value
        that represents the same numeric value as |x|.
</div>

Note: Since there is only a single JavaScript <emu-val>NaN</emu-val> value,
it must be canonicalized to a particular double precision IEEE 754 NaN value.  The NaN value
mentioned above is chosen simply because it is the quiet NaN with the lowest
value when its bit pattern is interpreted as an [=/64-bit unsigned integer=].

<div id="unrestricted-double-to-js" algorithm="convert an unrestricted double to a JavaScript value">
    <span id="unrestricted-double-to-es"></span>

    The result of [=converted to a JavaScript value|converting=]
    an IDL {{unrestricted double}} value to a JavaScript
    value is a Number:

    1.  If the IDL {{unrestricted double}} value is a NaN,
        then the Number value is <emu-val>NaN</emu-val>.
    1.  Otherwise, the Number value is
        the one that represents the same numeric value as the IDL
        {{unrestricted double}} value.
</div>

<h4 id="js-bigint" oldids="es-bigint">bigint</h4>

<div id="js-to-bigint" algorithm="convert a JavaScript value to a bigint">
    <span id="es-to-bigint"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{bigint}} value by running the following algorithm:

    1.  Let |x| be [=?=] [$ToBigInt$](|V|).
    1.  Return the IDL {{bigint}} value that represents the same numeric value as |x|.
</div>

<div id="bigint-to-js" algorithm="convert a bigint to a JavaScript value">
    <span id="bigint-to-es"></span>

    The result of [=converted to a JavaScript value|converting=]
    an IDL {{bigint}} value to a JavaScript value is a BigInt:

    1.  Return the {{BigInt}} value that represents the same numeric value as the IDL {{bigint}}
        value.
</div>

<div id="js-to-bigint-or-numeric" algorithm="convert a JavaScript value to a numeric type or a bigint">
    <span id="es-to-bigint-or-numeric"></span>

    A JavaScript value |V| is <dfn lt="converted to a numeric type or bigint">converted</dfn>
    to an IDL [=numeric type=] |T| or {{bigint}} value by running the following algorithm:

    1.  Let |x| be [=?=] [$ToNumeric$](|V|).
    1.  If |x| [=is a BigInt=], then
        1.  Return the IDL {{bigint}} value that represents the same numeric value as |x|.
    1.  Assert: |x| [=is a Number=].
    1.  Return the result of [=converted to a JavaScript value|converting=] |x| to |T|.
</div>


<h4 id="js-DOMString" oldids="es-DOMString">DOMString</h4>

<div id="js-to-DOMString" algorithm="convert a JavaScript value to DOMString">
    <span id="es-to-DOMString"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{DOMString}} value by running the following algorithm:

    1.  If |V| is <emu-val>null</emu-val> and the conversion is to an IDL type
        [=extended attribute associated with|associated with=] the [{{LegacyNullToEmptyString}}] extended
        attribute, then return the {{DOMString}} value that represents the empty string.
    1.  Let |x| be [=?=] <a abstract-op>ToString</a>(|V|).
    1.  Return the IDL {{DOMString}} value that represents the same sequence of code units as the one the JavaScript String value |x| represents.
</div>

<p id="DOMString-to-js">
    <span id="DOMString-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL {{DOMString}} value to a JavaScript
    value is the String
    value that represents the same sequence of [=code units=] that the
    IDL {{DOMString}} represents.
</p>


<h4 id="js-ByteString" oldids="es-ByteString">ByteString</h4>

<div id="js-to-ByteString" algorithm="convert a JavaScript value to ByteString">
    <span id="es-to-ByteString"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{ByteString}} value by running the following algorithm:

    1.  Let |x| be [=?=] <a abstract-op>ToString</a>(|V|).
    1.  If the value of any <l spec=ecmascript>[=ECMAScript String/element=]</l>
        of |x| is greater than 255, then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Return an IDL {{ByteString}} value
        whose length is the length of |x|, and where the value of each element is
        the value of the corresponding element of |x|.
</div>

<p id="ByteString-to-js">
    <span id="ByteString-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL {{ByteString}} value to a JavaScript
    value is a String
    value whose length is the length of the {{ByteString}},
    and the value of each <l spec=ecmascript>[=ECMAScript String/element=]</l> of which is the value
    of the corresponding element of the {{ByteString}}.
</p>


<h4 id="js-USVString" oldids="es-USVString">USVString</h4>

<div id="js-to-USVString" algorithm="convert a JavaScript value to USVString">
    <span id="es-to-USVString"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{USVString}} value by running the following algorithm:

    1.  Let |string| be the result of [=converted to an IDL value|converting=] |V|
        to a {{DOMString}}.
    1.  Return an IDL {{USVString}} value that is the result of
        [=string/convert|converting=] |string| to a sequence of [=scalar values=].
</div>

<div id="USVString-to-js" algorithm="convert an USVString to a JavaScript value">
    <span id="USVString-to-es"></span>

    The result of [=converted to a JavaScript value|converting=]
    an IDL {{USVString}} value |S| to a JavaScript
    value is |S|.
</div>


<h4 id="js-object" oldids="es-object">object</h4>

IDL {{object}}
values are represented by JavaScript Object values.

<div id="js-to-object" algorithm="convert a JavaScript value to object">
    <span id="es-to-object"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{object}} value by running the following algorithm:

    1.  If |V| [=is not an Object=], then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Return the IDL {{object}} value that is a reference to the same object as |V|.
</div>

<p id="object-to-js">
    <span id="object-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL {{object}} value to a JavaScript
    value is the Object value that represents a reference to the same object that the
    IDL {{object}} represents.
</p>


<h4 id="js-symbol" oldids="es-symbol">symbol</h4>

IDL {{symbol}} values are represented by JavaScript Symbol values.

<div id="js-to-symbol" algorithm="convert a JavaScript value to a symbol">
    <span id="es-to-symbol"></span>
    A JavaScript value |V| is [=converted to an IDL value|converted=] to an IDL {{symbol}} value
    by running the following algorithm:

    1.  If |V| [=is not a Symbol=], then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Return the IDL {{symbol}} value that is a reference to the same symbol as |V|.
</div>

<p id="symbol-to-js">
    <span id="symbol-to-es"></span>
    The result of [=converted to a JavaScript value|converting=] an IDL {{symbol}} value to a
    JavaScript value is the Symbol value that represents a reference to the same
    symbol that the IDL {{symbol}} represents.
</p>


<h4 id="js-interface" oldids="es-interface">Interface types</h4>

IDL [=interface type=]
values are represented by JavaScript Object values (including [=function objects=]).

<div id="js-to-interface" algorithm="convert a JavaScript value to interface">
    <span id="es-to-interface"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL [=interface type=] value by running the following algorithm (where |I| is the [=interface=]):

    1.  If |V| [=implements=] |I|, then return the IDL [=interface type=] value that represents a reference to that platform object.
    1.  [=JavaScript/Throw=] a <l spec=ecmascript>{{TypeError}}</l>.
</div>

<p id="interface-to-js">
    <span id="interface-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL [=interface type=]
    value to a JavaScript value is the Object
    value that represents a reference to the same object that the IDL
    [=interface type=] value represents.
</p>


<h4 id="js-callback-interface" oldids="es-callback-interface">Callback interface types</h4>

IDL [=callback interface type=]
values are represented by JavaScript Object values (including [=function objects=]).

<div id="js-to-callback-interface" algorithm="convert a JavaScript value to callback interface">
    <span id="es-to-callback-interface"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL [=callback interface type=] value by running the following algorithm:

    1.  If |V| [=is not an Object=], then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Return the IDL [=callback interface type=] value that represents a reference to |V|, with
        the <a spec="HTML">incumbent settings object</a> as the [=callback context=].
</div>

<p id="callback-interface-to-js">
    <span id="callback-interface-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL [=callback interface type=]
    value to a JavaScript value is the Object
    value that represents a reference to the same object that the IDL
    [=callback interface type=] value represents.
</p>


<h4 id="js-dictionary" oldids="es-dictionary">Dictionary types</h4>

IDL [=dictionary type=] values are represented
by JavaScript Object values.  Properties on
the object (or its prototype chain) correspond to [=dictionary members=].

<div id="js-to-dictionary" algorithm="convert a JavaScript value to dictionary">
    <span id="es-to-dictionary"></span>

    A JavaScript value |jsDict| is [=converted to an IDL value|converted=]
    to an IDL [=dictionary type=] value by
    running the following algorithm (where |D| is the [=dictionary type=]):

    1.  If |jsDict| [=is not an Object=] and |jsDict| is neither <emu-val>undefined</emu-val> nor
        <emu-val>null</emu-val>, then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Let |idlDict| be an empty [=ordered map=], representing a dictionary of type |D|.
    1.  Let |dictionaries| be a list consisting of |D| and all of |D|'s [=inherited dictionaries=],
        in order from least to most derived.
    1.  For each dictionary |dictionary| in |dictionaries|, in order:
        1.  For each dictionary member |member| declared on |dictionary|, in lexicographical order:
            1.  Let |key| be the [=identifier=] of |member|.
            1.  If |jsDict| is either <emu-val>undefined</emu-val> or <emu-val>null</emu-val>, then:
                1.  Let |jsMemberValue| be <emu-val>undefined</emu-val>.
            1.  Otherwise,
                1.  Let |jsMemberValue| be [=?=] <a abstract-op>Get</a>(|jsDict|, |key|).
            1.  If |jsMemberValue| is not <emu-val>undefined</emu-val>, then:
                1.  Let |idlMemberValue| be the result of [=converted to an IDL value|converting=] |jsMemberValue| to an IDL value whose type is the type |member| is declared to be of.
                1.  [=map/Set=] |idlDict|[|key|] to |idlMemberValue|.
            1.  Otherwise, if |jsMemberValue| is <emu-val>undefined</emu-val> but |member| has a [=dictionary member/default value=], then:
                1.  Let |idlMemberValue| be |member|'s default value.
                1.  [=map/Set=] |idlDict|[|key|] to |idlMemberValue|.
            1.  Otherwise, if |jsMemberValue| is <emu-val>undefined</emu-val> and |member| is
                [=dictionary member/required=], then throw a {{TypeError}}.
    1.  Return |idlDict|.
</div>

Note: The order that [=dictionary members=] are looked
up on the JavaScript object are not necessarily the same as the object's property enumeration order.

<div id="dictionary-to-js" algorithm="convert a dictionary to a JavaScript value">
    <span id="dictionary-to-es"></span>

    An IDL dictionary value |V| is [=converted to a JavaScript value|converted=]
    to a JavaScript Object value by
    running the following algorithm (where |D| is the [=dictionary=]):

    1.  Let |O| be [$OrdinaryObjectCreate$]({{%Object.prototype%}}).
    1.  Let |dictionaries| be a list consisting of |D| and all of |D|'s [=inherited dictionaries=],
        in order from least to most derived.
    1.  For each dictionary |dictionary| in |dictionaries|, in order:
        1.  For each dictionary member |member| declared on |dictionary|, in lexicographical order:
            1.  Let |key| be the [=identifier=] of |member|.
            1.  If |V|[|key|] [=map/exists=], then:
                1.  Let |idlValue| be |V|[|key|].
                1.  Let |value| be the result of [=converted to a JavaScript value|converting=] |idlValue| to a JavaScript value.
                1.  Perform [=!=] <a abstract-op>CreateDataPropertyOrThrow</a>(|O|, |key|, |value|).

                <p class="note">Recall that if |member| has a [=dictionary member/default value=],
                then |key| will always [=map/exist=] in |V|.</p>
    1.  Return |O|.
</div>


<h4 id="js-enumeration" oldids="es-enumeration">Enumeration types</h4>

IDL [=enumeration types=] are represented by JavaScript String
values.

<div id="js-to-enumeration" algorithm="convert a JavaScript value to enumeration">
    <span id="es-to-enumeration"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL [=enumeration|enumeration type=] value as follows
    (where |E| is the [=enumeration=]):

    1.  Let |S| be the result of calling [=?=] <a abstract-op>ToString</a>(|V|).
    1.  If |S| is not one of |E|'s [=enumeration values=],
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Return the enumeration value of type |E| that is equal to |S|.
</div>

<p id="enumeration-to-js">
    <span id="enumeration-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL [=enumeration|enumeration type=] value to a JavaScript
    value is the String
    value that represents the same sequence of [=code units=] as
    the [=enumeration value=].
</p>


<h4 id="js-callback-function" oldids="es-callback-function">Callback function types</h4>

IDL [=callback function types=] are represented by JavaScript [=function objects=], except in the
[{{LegacyTreatNonObjectAsNull}}] case, when they can be any object.

<div id="js-to-callback-function" algorithm="convert a JavaScript value to callback function">
    <span id="es-to-callback-function"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL [=callback function type=] value by running the following algorithm:

    1.  If the result of calling <a abstract-op>IsCallable</a>(|V|) is <emu-val>false</emu-val>
        and the conversion to an IDL value
        is not being performed due
        to |V| being assigned to an [=attribute=]
        whose type is a [=nullable type|nullable=]
        [=callback function=]
        that is annotated with [{{LegacyTreatNonObjectAsNull}}],
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Return the IDL [=callback function type=] value
        that represents a reference to the same object that |V| represents, with the
        <a spec="HTML">incumbent settings object</a> as the [=callback context=].
</div>

<p id="callback-function-to-js">
    <span id="callback-function-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL [=callback function type=]
    value to a JavaScript value is a reference to the same object
    that the IDL [=callback function type=] value represents.
</p>


<h4 id="js-nullable-type" oldids="es-nullable-type">Nullable types — |T|?</h4>

IDL [=nullable type=] values are represented
by values of either the JavaScript type corresponding to the [=nullable types/inner type|inner IDL type=], or
the JavaScript <emu-val>null</emu-val> value.

<div id="js-to-nullable" algorithm="convert a JavaScript value to nullable">
    <span id="es-to-nullable"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL [=nullable type=] <code class="idl">|T|?</code>
    value (where |T| is the [=nullable types/inner type=]) as follows:

    1.  If |V| [=is not an Object=], and
        the conversion to an IDL value is being performed due
        to |V| being assigned to an [=attribute=]
        whose type is a [=nullable type|nullable=]
        [=callback function=]
        that is annotated with [{{LegacyTreatNonObjectAsNull}}],
        then return the IDL
        [=nullable type=] <code class="idl">|T|?</code>
        value <emu-val>null</emu-val>.
    1.  Otherwise, if |V| is <emu-val>undefined</emu-val>,
        and |T| [=includes undefined=],
        return the unique {{undefined}} value.
    1.  Otherwise, if |V| is <emu-val>null</emu-val> or <emu-val>undefined</emu-val>, then return the IDL
        [=nullable type=] <code class="idl">|T|?</code>
        value <emu-val>null</emu-val>.
    1.  Otherwise, return the result of
        [=converted to an IDL value|converting=] |V|
        using the rules for the [=nullable types/inner type|inner IDL type=] <code class="idl">T</code>.
</div>

<div id="nullable-to-js" algorithm="convert a nullable to a JavaScript value">
    <span id="nullable-to-es"></span>

    The result of [=converted to a JavaScript value|converting=]
    an IDL [=nullable type=] value to a JavaScript value is:

    1.  If the IDL [=nullable type=] <code class="idl">|T|?</code>
        value is <emu-val>null</emu-val>,
        then the JavaScript value is <emu-val>null</emu-val>.
    1.  Otherwise, the JavaScript value is the result of
        [=converted to a JavaScript value|converting=]
        the IDL [=nullable type=] value
        to the [=nullable types/inner type|inner IDL type=] <code class="idl">|T|</code>.
</div>

<h4 id="js-sequence" oldids="es-sequence">Sequences — sequence&lt;|T|&gt;</h4>

IDL <a lt="sequence type">sequence&lt;|T|&gt;</a> values are represented by
JavaScript Array values.

<div id="js-to-sequence" algorithm="convert a JavaScript value to sequence">
    <span id="es-to-sequence"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL <a lt="sequence type">sequence&lt;<var ignore>T</var>&gt;</a> value as follows:

    1.  If |V| [=is not an Object=],
        [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Let |method| be [=?=] <a abstract-op>GetMethod</a>(|V|, {{%Symbol.iterator%}}).
    1.  If |method| is <emu-val>undefined</emu-val>,
        [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Return the result of [=creating a sequence from an iterable|creating a sequence=]
        from |V| and |method|.
</div>

<div id="sequence-to-js" algorithm="convert a sequence to a JavaScript value">
    <span id="sequence-to-es"></span>

    An IDL sequence value |S| of type
    <a lt="sequence type">sequence&lt;<var ignore>T</var>&gt;</a> is
    [=converted to a JavaScript value|converted=]
    to a JavaScript Array object as follows:


    1.  Let |n| be the length of |S|.
    1.  Let |A| be a new Array object created as if by the expression <code>[]</code>.
    1.  Initialize |i| to be 0.
    1.  While |i| &lt; |n|:
        1.  Let |V| be the value in |S| at index |i|.
        1.  Let |E| be the result of [=converted to a JavaScript value|converting=]
            |V| to a JavaScript value.
        1.  Let |P| be the result of calling [=!=] <a abstract-op>ToString</a>(|i|).
        1.  Perform [=!=] <a abstract-op>CreateDataPropertyOrThrow</a>(|A|, |P|, |E|).
        1.  Set |i| to |i| + 1.
    1.  Return |A|.
</div>


<h5 id="create-sequence-from-iterable" dfn>Creating a sequence from an iterable</h5>

<div algorithm="create sequence from iterable">

    To create an IDL value of type <a lt="sequence type">sequence&lt;|T|&gt;</a>
    given an iterable |iterable| and an iterator getter |method|,
    perform the following steps:

    1.  Let |iteratorRecord| be [=?=] <a abstract-op>GetIteratorFromMethod</a>(|iterable|, |method|).
    1.  Initialize |i| to be 0.
    1.  Repeat
        1.  Let |next| be [=?=] <a abstract-op>IteratorStepValue</a>(|iteratorRecord|).
        1.  If |next| is <emu-const>done</emu-const>,
            then return an IDL sequence value of type
            <a lt="sequence type">sequence&lt;|T|&gt;</a>
            of length |i|, where the value of the element
            at index |j| is
            |S|<sub>|j|</sub>.
        1.  Initialize |S|<sub>|i|</sub> to the result of
            [=converted to an IDL value|converting=]
            |next| to an IDL value of type |T|.
        1.  Set |i| to |i| + 1.
</div>

<div class="example" id="example-8d9e263c">

    The following [=interface=] defines
    an [=attribute=] of a sequence
    type as well as an [=operation=]
    with an argument of a sequence type.

    <pre highlight="webidl">
        [Exposed=Window]
        interface Canvas {

          sequence&lt;DOMString&gt; getSupportedImageCodecs();

          undefined drawPolygon(sequence&lt;double&gt; coordinates);
          sequence&lt;double&gt; getLastDrawnPolygon();

          // ...
        };
    </pre>

    In a JavaScript implementation of this interface, an Array
    object with elements of type String is used to
    represent a <code class="idl">sequence&lt;DOMString&gt;</code>, while an
    Array with elements of type Number
    represents a <code class="idl">sequence&lt;double&gt;</code>.  The
    Array objects are effectively passed by
    value; every time the <code>getSupportedImageCodecs()</code>
    function is called a new Array is
    returned, and whenever an Array is
    passed to <code>drawPolygon</code> no reference
    will be kept after the call completes.

        <pre highlight="js">
        // Obtain an instance of Canvas.  Assume that getSupportedImageCodecs()
        // returns a sequence with two DOMString values: "image/png" and "image/svg+xml".
        var canvas = getCanvas();

        // An Array object of length 2.
        var supportedImageCodecs = canvas.getSupportedImageCodecs();

        // Evaluates to "image/png".
        supportedImageCodecs[0];

        // Each time canvas.getSupportedImageCodecs() is called, it returns a
        // new Array object.  Thus modifying the returned Array will not
        // affect the value returned from a subsequent call to the function.
        supportedImageCodecs[0] = "image/jpeg";

        // Evaluates to "image/png".
        canvas.getSupportedImageCodecs()[0];

        // This evaluates to false, since a new Array object is returned each call.
        canvas.getSupportedImageCodecs() == canvas.getSupportedImageCodecs();

        // An Array of Numbers...
        var a = [0, 0, 100, 0, 50, 62.5];

        // ...can be passed to a platform object expecting a sequence&lt;double&gt;.
        canvas.drawPolygon(a);

        // Each element will be converted to a double by first calling ToNumber().
        // So the following call is equivalent to the previous one, except that
        // "hi" will be alerted before drawPolygon() returns.
        a = [false, "",
             { valueOf: function() { alert("hi"); return 100; } }, 0,
             "50", new Number(62.5)];
        canvas.drawPolygon(a);

        // Modifying an Array that was passed to drawPolygon() is guaranteed not to
        // have an effect on the Canvas, since the Array is effectively passed by value.
        a[4] = 20;
        var b = canvas.getLastDrawnPolygon();
        alert(b[4]);    // This would alert "50".
    </pre>
</div>


<h4 id="js-async-iterable">Async iterables — async iterable&lt;|T|&gt;</h4>

In the JavaScript binding, IDL [=async iterable type|async iterable=] values are represented by
a [=struct=] with the following [=struct/items=]:

* <dfn for="JS async iterable">object</dfn>, a JavaScript value
* <dfn for="JS async iterable">method</dfn>, a JavaScript value
* <dfn for="JS async iterable">type</dfn>, either "<code>sync</code>" or "<code>async</code>"


<div id="js-to-async-iterable" algorithm="convert a JavaScript value to async iterable">
    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL <a lt="async iterable">async iterable&lt;<var ignore>T</var>&gt;</a> value as follows:

    1.  If |V| [=is not an Object=], then
        [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Let |method| be [=?=] <a abstract-op>GetMethod</a>(obj, {{%Symbol.asyncIterator%}}).
    1.  If |method| is <emu-val>undefined</emu-val>:
        1.  Set |syncMethod| to [=?=] <a abstract-op>GetMethod</a>(obj, {{%Symbol.iterator%}}).
        1.  If |syncMethod| is undefined, [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
        1.  Return an IDL [=async iterable=] value with [=JS async iterable/object=] set to |V|,
            [=JS async iterable/method=] set to |syncMethod|, and [=JS async iterable/type=] set to
            "<code>sync</code>".
    1.  Return an IDL [=async iterable=] value with [=JS async iterable/object=] set to |V|,
        [=JS async iterable/method=] set to |method|, and [=JS async iterable/type=] set to
        "<code>async</code>".
</div>

<div id="async-iterable-to-js" algorithm="convert an async iterable to a JavaScript value">
    An IDL <a lt="async iterable">async iterable&lt;<var ignore>T</var>&gt;</a> value |V| is
    [=converted to a JavaScript value|converted=] to a JavaScript object as follows:

    1.  Return |V|'s [=JS async iterable/object=].
</div>

<h5 id="js-async-iterator-iteration">Iterating async iterators</h5>

An [=async iterable=] is not directly iterated over. Instead, it is first opened to create
an [=async iterator=]. The [=async iterator=] can be asynchronously iterated over to produce values.

<dfn lt="async iterator" export>Async iterators</dfn> are [=structs=] with the following [=struct/items=]:
* <dfn for="JS async iterator">underlying record</dfn>, an [=Iterator Record=]
* <dfn for="JS async iterator">type parameter</dfn>, an IDL type representing the type of values produced by the async iterator

<div algorithm>

    To <dfn id="async-iterable-open" export lt="open an async iterable">open</dfn> an
    <code><a lt="async iterable type">async iterable&lt;<var>T</var>&gt;</a></code> |iterable|:

    1.  Let |iterator| be [=?=] <a abstract-op>GetIteratorFromMethod</a>(|iterable|'s
        [=JS async iterable/object=], |iterable|'s [=JS async iterable/method=]).
    1.  If |iterable|'s [=JS async iterable/type=] is "<code>sync</code>", set |iterator| to
        <a abstract-op>CreateAsyncFromSyncIterator</a>(|iterator|).
    1.  Return an [=async iterator=] value with [=JS async iterator/underlying record=] set to |iterator| and
        [=JS async iterator/type parameter=] set to |T|.

</div>



<div algorithm>

    To <dfn id="async-iterator-get-next-value" export lt="get an async iterator next value">get the next value</dfn> of an
    [=async iterator=] |iterator|:

    1.  Let |nextResult| be
        <a abstract-op>IteratorNext</a>(|iterator|'s [=JS async iterator/underlying record=]).
    1.  If |nextResult| is an [=abrupt completion=], return [=a promise rejected with=]
        |nextResult|.\[[Value]].
    1.  Let |nextPromise| be [=a promise resolved with=] |nextResult|.\[[Value]].
    1.  Return the result of [=reacting=] to |nextPromise| with the following fulfillment
        steps, given |iterResult|:
        1.  If |iterResult| [=is not an Object=], [=JavaScript/throw=] a
            <l spec=ecmascript>{{TypeError}}</l>.
        1.  Let |done| be [=?=] <a abstract-op>IteratorComplete</a>(|iterResult|).
        1.  If |done| is true:
            1.  Return [=end of iteration=].
        1.  Otherwise:
            1.  Let |V| be [=?=] <a abstract-op>IteratorValue</a>(|iterResult|).
            1.  Let |value| be the result of [=converted to an IDL value|converting=] |V| to an IDL
                value of type |iterator|'s [=JS async iterator/type parameter=].
            1.  Return |value|.

</div>

<div algorithm>

    To <dfn id="async-iterator-close" export lt="close an async iterator">close</dfn> an
    <code><a lt="async iterator">async iterator&lt;<var ignore>T</var>&gt;</a></code> |iterator|,
    with an ECMAScript value |reason|:

    1.  Let |iteratorRecord| be |iterator|'s [=JS async iterator/underlying record=].
    1.  Let |iteratorObj| be |iteratorRecord|.\[[Iterator]].
    1.  Let |returnMethod| be <a abstract-op>GetMethod</a>(|iteratorObj|, "<code>return</code>").
    1.  If |returnMethod| is an [=abrupt completion=], return [=a promise rejected with=]
        |returnMethod|.\[[Value]].
    1.  If |returnMethod| is <emu-val>undefined</emu-val>, return [=a promise resolved with=]
        {{undefined}}.
    1.  Let |returnResult| be <a abstract-op>Call</a>(|returnMethod|.\[[Value]], |iteratorObj|, « |reason| »).
    1.  If |returnResult| is an [=abrupt completion=], return [=a promise rejected with=]
        |returnResult|.\[[Value]].
    1.  Let |returnPromise| be [=a promise resolved with=] |returnResult|.\[[Value]].
    1.  Return the result of [=reacting=] to |returnPromise| with the following fulfillment steps,
        given |returnPromiseResult|:
        1.  If |returnPromiseResult| [=is not an Object=], [=JavaScript/throw=] a
            <l spec=ecmascript>{{TypeError}}</l>.
        1.  Return {{undefined}}.

</div>

<div class="example" id="example-js-async-iterable">

    <code>concatN</code> is an [=operation=] that returns a promise that will be fulfilled with the
    concatenation of all the strings yielded by the async iterable passed to it. It stops
    concatenating and closes the iterator once the async iterable has yielded <var ignore>maxN</var>
    strings.

    <pre>
        interface I {
          Promise&lt;DOMString> concatN(async iterable&lt;DOMString> strings, unsigned long maxN);
        };
    </pre>

<div algorithm="concatN">

    The <code>concatN(|iterable|, |maxN|)</code> method steps are:

    1.  Let |promise| be [=a new promise=].
    1.  Let |result| be the empty string.
    1.  Let |n| be 0.
    1.  Let |iterator| be the result of <a lt="open an async iterable">opening</a> |iterable|.
    1.  Let |step| be a sequence of steps that will be used to process the async iterable:
        1.  Let |next| be the result of <a lt="get an async iterator next value">getting the next value</a> of |iterator|.
        1.  [=React=] to |next|:
            -   If |next| was fulfilled with value |v|:
                1.  If |v| is [=end of iteration=], [=resolve=] |promise| with |result|.
                1.  Set |result| to the result of concatenating |result| and |v|.
                1.  Set |n| to |n| + 1.
                1.  If |n| is |maxN|, then:
                    1.  Let |finish| be the result of <a lt="close an async iterator">closing</a>
                        |iterator| with reason {{undefined}}.
                    1.  [=React=] to |finish|:
                        -   If |finish| was fulfilled, [=resolve=] |promise| with |result|.
                        -   If |finish| was rejected with reason |r|, [=reject=] |promise| with |r|.
                1.  Otherwise:
                    1.  Call |step|.
            -   If |next| was rejected with reason |r|, [=reject=] |promise| with |r|.
    1.  Call |step|.
    1.  Return |promise|.

</div>
</div>




<h4 id="js-record" oldids="es-record">Records — record&lt;|K|, |V|&gt;</h4>

IDL [=record=]&lt;|K|, |V|&gt; values are represented by
JavaScript Object values.

<div id="js-to-record" algorithm="convert a JavaScript value to record">
    <span id="es-to-record"></span>

    A JavaScript value |O| is [=converted to an IDL value|converted=]
    to an IDL <code>[=record=]&lt;|K|, |V|></code> value as follows:

    1.  If |O| [=is not an Object=],
        [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Let |result| be a new empty instance of <code>[=record=]&lt;|K|, |V|></code>.
    1.  Let |keys| be [=?=] |O|.\[[OwnPropertyKeys]]().
    1.  [=list/For each=] |key| of |keys|:
        1.  Let |desc| be [=?=] |O|.\[[GetOwnProperty]](|key|).
        1.  If |desc| is not <emu-val>undefined</emu-val>
            and |desc|.\[[Enumerable]] is <emu-val>true</emu-val>:
            1.  Let |typedKey| be |key| [=converted to an IDL value=] of type |K|.
            1.  Let |value| be [=?=] <a abstract-op>Get</a>(|O|, |key|).
            1.  Let |typedValue| be |value| [=converted to an IDL value=] of type |V|.
            1.  [=map/Set=] |result|[|typedKey|] to |typedValue|.

                Note: It's possible that |typedKey| is already in |result|,
                if |K| is {{USVString}} and |key| contains unpaired surrogates.
    1.  Return |result|.
</div>

<div id="record-to-js" algorithm="convert a record to a JavaScript value">
    <span id="record-to-es"></span>

    An IDL <code>[=record=]&lt;…></code> value |D| is
    [=converted to a JavaScript value|converted=]
    to a JavaScript value as follows:

    1.  Let |result| be [$OrdinaryObjectCreate$]({{%Object.prototype%}}).
    1.  [=map/For each=] |key| → |value| of |D|:
        1.  Let |jsKey| be |key| [=converted to a JavaScript value=].
        1.  Let |jsValue| be |value| [=converted to a JavaScript value=].
        1.  Let |created| be [=!=] <a abstract-op>CreateDataProperty</a>(|result|, |jsKey|, |jsValue|).
        1.  Assert: |created| is <emu-val>true</emu-val>.
    1.  Return |result|.
</div>

<div class="example" id="example-js-record">
    <span id="example-es-record"></span>

    Passing the JavaScript value <code>{b: 3, a: 4}</code> as a
    <code>[=record=]&lt;DOMString, double></code> argument
    would result in the IDL value «[ "<code>b</code>" → 3, "<code>a</code>" → 4 ]».

    Records only consider [=own property|own=] [=enumerable=]
    properties, so given an IDL operation
    <code>record&lt;DOMString, double>
    identity(record&lt;DOMString, double> arg)</code> which returns its
    argument, the following code passes its assertions:

    <pre highlight="js">
        let proto = {a: 3, b: 4};
        let obj = {__proto__: proto, d: 5, c: 6}
        Object.defineProperty(obj, "e", {value: 7, enumerable: false});
        let result = identity(obj);
        console.assert(result.a === undefined);
        console.assert(result.b === undefined);
        console.assert(result.e === undefined);
        let entries = Object.entries(result);
        console.assert(entries[0][0] === "d");
        console.assert(entries[0][1] === 5);
        console.assert(entries[1][0] === "c");
        console.assert(entries[1][1] === 6);
    </pre>

    Record keys and values can be constrained, although keys can only be
    constrained among the three string types.
    The following conversions have the described results:
    <table class="data">
        <thead><th>Value</th><th>Passed to type</th><th>Result</th></thead>
        <tr>
            <td><code>{"😞": 1}</code></td>
            <td><code>[=record=]&lt;ByteString, double></code></td>
            <td>{{TypeError}}</td>
        </tr>
        <tr>
            <td><code>{"\uD83D": 1}</code></td>
            <td><code>[=record=]&lt;USVString, double></code></td>
            <td>«[ "<code>\uFFFD</code>" → 1 ]»</td>
        </tr>
        <tr>
            <td><code>{"\uD83D": {hello: "world"}}</code></td>
            <td><code>[=record=]&lt;DOMString, double></code></td>
            <td>«[ "<code>\uD83D</code>" → 0 ]»</td>
        </tr>
    </table>
</div>


<h4 id="js-promise" oldids="es-promise">Promise types — Promise&lt;|T|&gt;</h4>

IDL [=promise type=] values are represented by JavaScript [=PromiseCapability=] records.

<div id="js-to-promise" algorithm="convert a JavaScript value to promise">
    <span id="es-to-promise"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=] to an IDL
    <code><a interface>Promise</a>&lt;<var ignore>T</var>></code> value as follows:

    1.  Let |promiseCapability| be [=?=] [$NewPromiseCapability$]({{%Promise%}}).
    1.  Perform [=?=] [$Call$](|promiseCapability|.\[[Resolve]], <emu-val>undefined</emu-val>,
        « |V| »).
    1.  Return |promiseCapability|.
</div>

<p id="promise-to-js">
    <span id="promise-to-es"></span>
    The result of [=converted to a JavaScript value|converting=]
    an IDL [=promise type=] value to a JavaScript
    value is the value of the \[[Promise]] field of the record that
    IDL [=promise type=] represents.
</p>

<h5 id="js-promise-manipulation" oldids="es-promise-manipulation">Creating and manipulating Promises</h5>

<div algorithm>

    To <dfn export lt="a new promise">create</dfn> a new
    <code><a interface>Promise</a>&lt;<var ignore>T</var>&gt;</code> in a [=realm=] |realm|,
    perform the following steps:

    1.  Let |constructor| be |realm|.\[[Intrinsics]].\[[{{%Promise%}}]].
    1.  Return [=?=] [$NewPromiseCapability$](|constructor|).
</div>

<div algorithm>

    To create a <dfn export lt="a promise resolved with">resolved promise</dfn> of type
    <code><a interface>Promise</a>&lt;|T|&gt;</code>, with |x| (a value of type |T|) in a [=realm=]
    |realm|, perform the following steps:

    1.  Let |value| be the result of [=converted to a JavaScript value|converting=] |x| to a
        JavaScript value.
    1.  Let |constructor| be |realm|.\[[Intrinsics]].\[[{{%Promise%}}]].
    1.  Let |promiseCapability| be [=?=] [$NewPromiseCapability$](|constructor|).
    1.  Perform [=!=] [$Call$](|promiseCapability|.\[[Resolve]], <emu-val>undefined</emu-val>,
        « |value| »).
    1.  Return |promiseCapability|.
</div>

<div algorithm>

    To create a <dfn export lt="a promise rejected with">rejected promise</dfn> of type
    <code><a interface>Promise</a>&lt;<var ignore>T</var>&gt;</code>, with reason |r| (a
    JavaScript value) in a [=realm=] |realm|, perform the following steps:

    1.  Let |constructor| be |realm|.\[[Intrinsics]].\[[{{%Promise%}}]].
    1.  Let |promiseCapability| be [=?=] [$NewPromiseCapability$](|constructor|).
    1.  Perform [=!=] [$Call$](|promiseCapability|.\[[Reject]], <emu-val>undefined</emu-val>,
        « |r| »).
    1.  Return |promiseCapability|.
</div>

<div algorithm>

    To <dfn export>resolve</dfn> a <code><a interface>Promise</a>&lt;|T|&gt;</code> |p| with |x| (a
    value of type |T|), perform the following steps:

    1.  If |x| is not given, then let it be the {{undefined}} value.
    1.  Let |value| be the result of [=converted to a JavaScript value|converting=] |x| to a
        JavaScript value.
    1.  Perform [=!=] [$Call$](|p|.\[[Resolve]], <emu-val>undefined</emu-val>, « |value| »).

    If |T| is {{undefined}}, then the |x| argument is optional, allowing a simpler "[=resolve=] p" usage.
</div>

<div algorithm>

    To <dfn export>reject</dfn> a <code><a interface>Promise</a>&lt;<var ignore>T</var>&gt;</code>
    |p| with reason |r| (a JavaScript value), perform the following steps:

    1.  Perform [=!=] [$Call$](|p|.\[[Reject]], <emu-val>undefined</emu-val>, « |r| »).
</div>

<div algorithm>

    To <dfn id="dfn-perform-steps-once-promise-is-settled" export lt="react|reacting" for="promise">react</dfn>
    to a <code><a interface>Promise</a>&lt;|T|&gt;</code> |promise|, given one or two sets of steps
    to perform, covering when the promise is fulfilled, rejected, or both, perform the following
    steps:

    1.  Let |onFulfilledSteps| be the following steps given argument |V|:
        1.  Let |value| be the result of [=converted to an IDL value|converting=] |V| to an IDL
            value of type |T|.
        1.  If there is a set of steps to be run if the promise was fulfilled, then let |result| be
            the result of performing them, given |value| if |T| is not {{undefined}}. Otherwise, let
            |result| be |value|.
        1.  Return |result|, [=converted to a JavaScript value=].
    1.  Let |onFulfilled| be [$CreateBuiltinFunction$](|onFulfilledSteps|, « »):
    1.  Let |onRejectedSteps| be the following steps given argument |R|:
        1.  Let |reason| be the result of [=converted to an IDL value|converting=]
            |R| to an IDL value of type {{any}}.
        1.  If there is a set of steps to be run if the promise was rejected, then let |result| be
            the result of performing them, given |reason|. Otherwise, let |result| be
            [=a promise rejected with=] |reason|.
        1.  Return |result|, [=converted to a JavaScript value=].
    1.  Let |onRejected| be [$CreateBuiltinFunction$](|onRejectedSteps|, « »):
    1.  Let |constructor| be |promise|.\[[Promise]].\[[Realm]].\[[Intrinsics]].\[[{{%Promise%}}]].
    1.  Let |newCapability| be [=?=] [$NewPromiseCapability$](|constructor|).

        Note: Not all callers will use the returned {{Promise}}. Implementations might wish to
        avoid creating |newCapability| in those cases.
    1.  Perform [$PerformPromiseThen$](|promise|.\[[Promise]], |onFulfilled|, |onRejected|,
        |newCapability|).
    1.  Return |newCapability|.

    Note: This algorithm will behave in a very similar way to the
    {{%Promise.prototype.then%|promise.then()}} method.
    In particular, if the steps return a value of type |U| or
    <code><a interface>Promise</a>&lt;|U|&gt;</code>, this algorithm returns a
    <code><a interface>Promise</a>&lt;|U|&gt;</code> as well.
</div>

<div algorithm>

    To perform some steps <dfn export>upon fulfillment</dfn> of a
    <code><a interface>Promise</a>&lt;|T|&gt;</code> |promise| given some steps |steps| taking a
    value of type |T|, perform the following steps:

    1.  Return the result of [=promise/reacting=] to |promise|:
        *   If |promise| was fulfilled with value |v|, then:
            1.  Perform |steps| with |v|.
</div>

<div algorithm>

    To perform some steps <dfn export>upon rejection</dfn> of a
    <code><a interface>Promise</a>&lt;<var ignore>T</var>&gt;</code> |promise| given some steps
    |steps| taking a JavaScript value, perform the following steps:

    1.  Return the result of [=promise/reacting=] to |promise|:
        *   If |promise| was rejected with reason |r|, then:
            1.  Perform |steps| with |r|.
</div>

<div algorithm>

    To <dfn export lt="wait for all|waiting for all">wait for all</dfn> with a [=list=] of
    <code><a interface>Promise</a>&lt;|T|&gt;</code> values |promises|, with success steps
    |successSteps| that take a [=list=] of |T| values and failure steps |failureSteps| that take a
    rejection reason {{any}} value, perform the following steps:

    1.  Let |fullfilledCount| be 0.
    1.  Let |rejected| be false.
    1.  Let |rejectionHandlerSteps| be the following steps given |arg|:
        1.  If |rejected| is true, abort these steps.
        1.  Set |rejected| to true.
        1.  Perform |failureSteps| given |arg|.
    1.  Let |rejectionHandler| be [$CreateBuiltinFunction$](|rejectionHandlerSteps|, « »):
    1.  Let |total| be |promises|'s [=list/size=].
    1.  If |total| is 0, then:
        1.  [=Queue a microtask=] to perform |successSteps| given « ».
        1.  Return.
    1.  Let |index| be 0.
    1.  Let |result| be a [=list=] containing |total| null values.
    1.  [=list/For each=] |promise| of |promises|:
        1.  Let |promiseIndex| be |index|.
        1.  Let |fulfillmentHandler| be the following steps given |arg|:
            1.  Set |result|[|promiseIndex|] to |arg|.
            1.  Set |fullfilledCount| to |fullfilledCount| + 1.
            1.  If |fullfilledCount| equals |total|, then perform |successSteps| given |result|.
        1.  Let |fulfillmentHandler| be [$CreateBuiltinFunction$](|fulfillmentHandler|, « »):
        1.  Perform [$PerformPromiseThen$](|promise|, |fulfillmentHandler|, |rejectionHandler|).
        1.  Set |index| to |index| + 1.
</div>

<div algorithm>

    To
    <dfn id="waiting-for-all-promise" export lt="get a promise to wait for all|getting a promise to wait for all">get a promise for waiting for all</dfn>
    with a [=list=] of <code><a interface>Promise</a>&lt;|T|&gt;</code> values |promises| and a
    [=realm=] |realm|, perform the following steps:

    1.  Let |promise| be [=a new promise=] of type
        <code><a interface>Promise</a>&lt;<a lt="sequence type">sequence</a>&lt;|T|>></code> in
        |realm|.
    1.  Let |successSteps| be the following steps, given |results|:
        1.  [=Resolve=] |promise| with |results|.
    1.  Let |failureSteps| be the following steps, given |reason|:
        1.  [=Reject=] |promise| with |reason|.
    1.  [=Wait for all=] with |promises|, given |successSteps| and |failureSteps|.
    1.  Return |promise|.

    <p class="note">This definition is useful when you wish to aggregate the results of multiple
    promises, and then produce another promise from them, in the same way that
    {{Promise/all()|Promise.all()}} functions for JavaScript code. If you do not need to produce
    another promise, then [=waiting for all=] is likely better.
</div>

<div algorithm>
    To <dfn export lt="mark a promise as handled|mark as handled">mark as handled</dfn> a
    <code><a interface>Promise</a>&lt;<var ignore>T</var>&gt;</code> |promise|, set
    |promise|.\[[Promise]].\[[PromiseIsHandled]] to true.

    <p class="note">This definition is useful for promises for which you expect rejections to often
    be ignored; it ensures such promises do not cause {{Window/unhandledrejection}} events. The most
    common use case is for promise properties, which the web developer might or might not consult.
    An example is the {{WritableStreamDefaultWriter/closed|writableStreamWriter.closed}} promise.
</div>


<h5 id="js-promise-examples" oldids="es-promise-examples">Examples</h5>

<div class="example" id="promise-example-delay">

    <code>delay</code> is an [=operation=] that returns a promise that will be fulfilled in a
    number of milliseconds.
    It illustrates how simply you can resolve a promise, with one line of prose.

    <pre highlight="webidl">
        interface I {
          Promise&lt;undefined> delay(unrestricted double ms);
        };
    </pre>

<div algorithm="delay">

    The <code>delay(|ms|)</code> method steps are:

    1.  Let |realm| be [=this=]'s [=relevant realm=].
    1.  Let |taskSource| be some appropriate [=task source=].
    1.  If |ms| is NaN, let |ms| be +0; otherwise let |ms| be the maximum of |ms| and +0.
    1.  Let |p| be [=a new promise=] in |realm|.
    1.  Run the following steps [=in parallel=]:
        1.  Wait |ms| milliseconds.
        1.  [=Queue a task=] on |taskSource| to [=resolve=] |p|.
    1.  Return |p|.
</div>
</div>

<div class="example" id="promise-example-validatedDelay">

    The <code>validatedDelay</code> [=operation=] is much like <a href="#promise-example-delay">the
    <code>delay</code> function</a>, except it will validate its arguments.
    This shows how to use rejected promises to signal immediate failure before even starting any
    asynchronous operations.

    <pre highlight="webidl">
        interface I {
          Promise&lt;undefined> validatedDelay(unrestricted double ms);
        };
    </pre>

<div algorithm="validatedDelay">

    The <code>validatedDelay(|ms|)</code> method steps are:

    1.  Let |realm| be [=this=]'s [=relevant realm=].
    1.  Let |taskSource| be some appropriate [=task source=].
    1.  If |ms| is NaN, return [=a promise rejected with=] a {{TypeError}} in |realm|.
    1.  If |ms| &lt; 0, return [=a promise rejected with=] a {{RangeError}} in |realm|.
    1.  Let |p| be [=a new promise=] in |realm|.
    1.  Run the following steps [=in parallel=]:
        1.  Wait |ms| milliseconds.
        1.  [=Queue a task=] on |taskSource| to [=resolve=] |p|.
    1.  Return |p|.
</div>
</div>

<div class="example" id="promise-example-addDelay">

    <code>addDelay</code> is an [=operation=] that adds an extra number of milliseconds of delay
    between |promise| settling and the returned promise settling.

    <pre highlight="webidl">
        interface I {
          Promise&lt;any> addDelay(Promise&lt;any> promise, unrestricted double ms);
        };
    </pre>

<div algorithm="addDelay">

    The <code>addDelay(|ms|, |promise|)</code> method steps are:

    1.  Let |realm| be [=this=]'s [=relevant realm=].
    1.  Let |taskSource| be some appropriate [=task source=].
    1.  If |ms| is NaN, let |ms| be +0; otherwise let |ms| be the maximum of |ms| and +0.
    1.  Let |p| be [=a new promise=] in |realm|.
    1.  [=promise/React=] to |promise|:
        *   If |promise| was fulfilled with value |v|, then:
            1.  Run the following steps [=in parallel=]:
                1.  Wait |ms| milliseconds.
                1.  [=Queue a task=] on |taskSource| to [=resolve=] |p| with |v|.
        *   If |promise| was rejected with reason |r|, then:
            1.  Run the following steps [=in parallel=]:
                1.  Wait |ms| milliseconds.
                1.  [=Queue a task=] on |taskSource| to [=reject=] |p| with |r|.
    1.  Return |p|.
</div>
</div>

<div class="example" id="promise-example-environment-ready" noexport>

    <code>environment.ready</code> is an [=attribute=] that signals when some part of some
    environment, e.g. a DOM document, becomes "ready".
    It illustrates how to encode environmental asynchronicity.

    <pre highlight="webidl">
        interface Environment {
          readonly attribute Promise&lt;undefined> ready;
        };
    </pre>

    Every <code>Environment</code> object must have a <dfn for="Environment">ready promise</dfn>,
    which is a <code><a interface>Promise</a>&lt;<a interface>undefined</a>></code>.

<div algorithm="Environment-ready">

    The <code>ready</code> attribute getter steps are:

    1. Return [=this=]'s [=Environment/ready promise=].
</div>

<div algorithm="Environment-create">

    To create an <code>Environment</code> object in a [=realm=] |realm|, perform the following
    steps:

    1.  Let |taskSource| be some appropriate [=task source=].
    1.  Let |environment| be [=new=] <code>Environment</code> object in |realm|.
    1.  Set |environment|'s [=Environment/ready promise=] to [=a new promise=] in |realm|.
    1.  Run the following steps [=in parallel=]:
        1.  Do some asynchronous work.
        1.  If |environment| becomes ready successfully, then [=queue a task=] on |taskSource| to
            [=resolve=] |environment|'s [=Environment/ready promise=].
        1.  If |environment| fails to become ready, then [=queue a task=] on |taskSource| to
            [=reject=] |environment|'s [=Environment/ready promise=] with a
            "{{NetworkError!!exception}}" {{DOMException}}.
    1.  Return |environment|.
</div>
</div>

<div class="example" id="promise-example-addBookmark">

    <code>addBookmark</code> is an [=operation=] that requests that the user add the current web
    page as a bookmark.
    It's drawn from <a href="https://github.com/domenic/promises-unwrapping/issues/85">some
    iterative design work</a> and illustrates a more real-world scenario of appealing to
    environmental asynchrony, as well as immediate rejections.

    <pre highlight="webidl">
        interface I {
          Promise&lt;undefined> addBookmark();
        };
    </pre>

<div algorithm="addBookmark">

    The <code>addBookmark()</code> method steps are:

    1.  Let |taskSource| be some appropriate [=task source=].
    1.  If this method was not invoked as a result of explicit user action, return
        [=a promise rejected with=] a "{{SecurityError}}" {{DOMException}}.
    1.  If the document's mode of operation is standalone, return [=a promise rejected with=] a
        "{{NotSupportedError}}" {{DOMException}}.
    1.  Let |promise| be [=a new promise=].
    1.  Let |info| be the result of getting a web application's metadata.
    1.  Run the following steps [=in parallel=]:
        1.  Using |info|, and in a manner that is user-agent specific, allow the end user to make a
            choice as to whether they want to add the bookmark.
            1.  If the end-user aborts the request to add the bookmark (e.g., they hit escape, or
                press a "cancel" button), then [=queue a task=] on |taskSource| to [=reject=]
                |promise| with an "{{AbortError}}" {{DOMException}}.
            1.  Otherwise, [=queue a task=] on |taskSource| to [=resolve=] |promise|.
    1. Return |promise|.
</div>
</div>

<div class="example" id="promise-example-batchRequest">

    Several places in [[SERVICE-WORKERS]] use [=get a promise to wait for all=].
    <code>batchRequest</code> illustrates a simplified version of one of their uses.
    It takes as input a [=sequence=] of URLs, and returns a promise for a [=sequence=] of
    {{Response}} objects created by fetching the corresponding URL.
    If any of the fetches fail, it will return [=a promise rejected with=] that failure.

    <pre highlight="webidl">
        interface I {
          Promise&lt;sequence&lt;Response>> batchRequest(sequence&lt;USVString> urls);
        };
    </pre>

<div algorithm="batchRequest">

    The <code>batchRequest(|urls|)</code> method steps are:

    1.  Let |responsePromises| be « ».
    1.  [=list/For each=] |url| of |urls|:
        1.  Let |p| be the result of calling {{WindowOrWorkerGlobalScope/fetch()}} with |url|.
        1.  [=list/Append=] |p| to |responsePromises|.
    1.  Let |p| be the result of [=getting a promise to wait for all=] with |responsePromises|.
    1.  Return |p|.
</div>
</div>


<h4 id="js-union" oldids="es-union">Union types</h4>

IDL [=union type=] values are represented by JavaScript values
that correspond to the union's [=member types=].

<div id="js-to-union" algorithm="convert a JavaScript value to union">
    <span id="es-to-union"></span>

    To [=converted to an IDL value|convert a JavaScript value=] |V| to an IDL [=union type=]
    value is done as follows:

    1.  If the [=union type=] [=includes undefined=]
        and |V| is <emu-val>undefined</emu-val>,
        then return the unique {{undefined}} value.
    1.  If the [=union type=] [=includes a nullable type=] and
        |V| is <emu-val>null</emu-val> or <emu-val>undefined</emu-val>,
        then return the IDL value <emu-val>null</emu-val>.
    1.  Let |types| be the [=flattened member types=]
        of the [=union type=].
    1.  If |V| is <emu-val>null</emu-val> or <emu-val>undefined</emu-val>, then:
        1.  If |types| includes a [=dictionary type=], then return the
            result of [=converted to an IDL value|converting=] |V| to that dictionary type.
    1.  If |V| [=is a platform object=], then:
        1.  If |types| includes an [=interface type=] that |V|
            [=implements=], then return the IDL value that is a reference to the object |V|.
        1.  If |types| includes {{object}}, then return the IDL value
            that is a reference to the object |V|.
    1.  If |V| [=is an Object=], |V| has an \[[ArrayBufferData]]
        [=/internal slot=], and <a abstract-op>IsSharedArrayBuffer</a>(|V|) is false, then:
        1.  If |types| includes {{ArrayBuffer}}, then return the
            result of [=converted to an IDL value|converting=]
            |V| to {{ArrayBuffer}}.
        1.  If |types| includes {{object}}, then return the IDL value
            that is a reference to the object |V|.
    1.  If |V| [=is an Object=], |V|, has an \[[ArrayBufferData]]
        [=/internal slot=], and <a abstract-op>IsSharedArrayBuffer</a>(|V|) is true, then:
        1.  If |types| includes {{SharedArrayBuffer}}, then return the
            result of [=converted to an IDL value|converting=]
            |V| to {{SharedArrayBuffer}}.
        1.  If |types| includes {{object}}, then return the IDL value
            that is a reference to the object |V|.
    1.  If |V| [=is an Object=] and |V| has a \[[DataView]] [=/internal slot=], then:
        1.  If |types| includes {{DataView}}, then return the
            result of [=converted to an IDL value|converting=]
            |V| to {{DataView}}.
        1.  If |types| includes {{object}}, then return the IDL value
            that is a reference to the object |V|.
    1.  If |V| [=is an Object=] and |V| has a \[[TypedArrayName]] [=/internal slot=], then:
        1.  If |types| includes a [=typed array type=]
            whose name is the value of |V|'s \[[TypedArrayName]] [=/internal slot=], then return the
            result of [=converted to an IDL value|converting=]
            |V| to that type.
        1.  If |types| includes {{object}}, then return the IDL value
            that is a reference to the object |V|.
    1.  If <a abstract-op>IsCallable</a>(|V|) is true, then:
        1.  If |types| includes a [=callback function=]
            type, then return the result of
            [=converted to an IDL value|converting=]
            |V| to that callback function type.
        1.  If |types| includes {{object}}, then return the IDL value
            that is a reference to the object |V|.
    1.  If |V| [=is an Object=], then:
        1.  If |types| includes an [=async iterable type=], then
            1. If |types| does not include a [=string type=] or |V| does not have a \[[StringData]] [=/internal slot=], then
                1.  Let |asyncMethod| be [=?=] <a abstract-op>GetMethod</a>(|V|, {{%Symbol.asyncIterator%}}).
                1.  If |asyncMethod| is not <emu-val>undefined</emu-val>,
                    return an IDL [=async iterable=] value with [=JS async iterable/object=]
                    set to |V|, [=JS async iterable/method=] set to |syncMethod|, and
                    [=JS async iterable/type=] set to "<code>async</code>".
                1.  Let |syncMethod| be [=?=] <a abstract-op>GetMethod</a>(|V|, {{%Symbol.iterator%}}).
                1.  If |syncMethod| is not <emu-val>undefined</emu-val>,
                    return an IDL [=async iterable=] value with [=JS async iterable/object=]
                    set to |V|, [=JS async iterable/method=] set to |syncMethod|, and
                    [=JS async iterable/type=] set to "<code>sync</code>".
        1.  If |types| includes a [=sequence type=], then
            1.  Let |method| be [=?=] <a abstract-op>GetMethod</a>(|V|, {{%Symbol.iterator%}}).
            1.  If |method| is not <emu-val>undefined</emu-val>,
                return the result of
                [=creating a sequence from an iterable|creating a sequence=]
                of that type from |V| and |method|.
        1.  If |types| includes a [=frozen array type=], then
            1.  Let |method| be [=?=] <a abstract-op>GetMethod</a>(|V|, {{%Symbol.iterator%}}).
            1.  If |method| is not <emu-val>undefined</emu-val>,
                return the result of
                [=Creating a frozen array from an iterable|creating a frozen array=]
                of that type from |V| and |method|.
        1.  If |types| includes a [=dictionary type=], then return the
            result of [=converted to an IDL value|converting=]
            |V| to that dictionary type.
        1.  If |types| includes a [=record type=], then return the
            result of [=converted to an IDL value|converting=]
            |V| to that record type.
        1.  If |types| includes a [=callback interface=]
            type, then return the result of
            [=converted to an IDL value|converting=]
            |V| to that [=callback interface type=].
        1.  If |types| includes {{object}}, then return the IDL value
            that is a reference to the object |V|.
    1.  If |V| [=is a Boolean=], then:
        1.  If |types| includes {{boolean}},
            then return the result of [=converted to an IDL value|converting=]
            |V| to {{boolean}}.
    1.  If |V| [=is a Number=], then:
        1.  If |types| includes a [=numeric type=],
            then return the result of [=converted to an IDL value|converting=]
            |V| to that [=numeric type=].
    1.  If |V| [=is a BigInt=], then:
        1.  If |types| includes {{bigint}},
            then return the result of [=converted to an IDL value|converting=]
            |V| to {{bigint}}
    1.  If |types| includes a [=string type=],
        then return the result of
        [=converted to an IDL value|converting=]
        |V| to that type.
    1.  If |types| includes a [=numeric type=] and {{bigint}},
        then return the result of [=converted to a numeric type or bigint|converting=]
        |V| to either that [=numeric type=] or {{bigint}}.
    1.  If |types| includes a [=numeric type=],
        then return the result of [=converted to an IDL value|converting=]
        |V| to that [=numeric type=].
    1.  If |types| includes {{boolean}},
        then return the result of [=converted to an IDL value|converting=]
        |V| to {{boolean}}.
    1.  If |types| includes {{bigint}},
        then return the result of [=converted to an IDL value|converting=]
        |V| to {{bigint}}.
    1.  [=JavaScript/Throw=] a <l spec=ecmascript>{{TypeError}}</l>.
</div>

<p id="union-to-js">
    <span id="union-to-es"></span>
    An IDL union type value is
    [=converted to a JavaScript value=]
    according to the rules for converting the [=specific type=]
    of the IDL union type value as described in this section ([[#js-type-mapping]]).
</p>


<h4 id="js-buffer-source-types" oldids="es-buffer-source-types">Buffer source types</h4>

A value of an IDL {{ArrayBuffer}} is represented by an object of the corresponding JavaScript class.
If it is not [=extended attributes associated with|associated with=] the [{{AllowResizable}}]
[=extended attribute=], it can only be backed by JavaScript <l spec=ecmascript>{{ArrayBuffer}}</l>
objects |V| for which <a abstract-op>IsResizableArrayBuffer</a>(|V|) is false.

A value of an IDL {{SharedArrayBuffer}} is represented by an object of the corresponding JavaScript
class. If it is not [=extended attributes associated with|associated with=] the [{{AllowResizable}}]
[=extended attribute=], it can only be backed by JavaScript
<l spec=ecmascript>{{SharedArrayBuffer}}</l> objects |V| for which
<a abstract-op>IsResizableArrayBuffer</a>(|V|) is false.

Values of the IDL [=buffer view types=] are represented by objects of the corresponding JavaScript
class, with the following additional restrictions on those objects.

<ul>
    <li>
        If the type is not [=extended attributes associated with|associated with=] either the
        [{{AllowResizable}}] or [{{AllowShared}}] [=extended attribute=], if applicable, they can
        only be backed by JavaScript <l spec=ecmascript>{{ArrayBuffer}}</l> objects |V| for which <a
        abstract-op>IsResizableArrayBuffer</a>(|V|) is false.
    </li>
    <li>
        If the type is [=extended attributes associated with|associated with=] the
        [{{AllowResizable}}] [=extended attribute=] but not with the [{{AllowShared}}] [=extended
        attribute=], if applicable, they can only be backed by JavaScript
        <l spec=ecmascript>{{ArrayBuffer}}</l> objects.
    </li>
    <li>
        If the type is [=extended attributes associated with|associated with=] the [{{AllowShared}}]
        [=extended attribute=] but not with the [{{AllowResizable}}] [=extended attribute=], they
        can only be backed by JavaScript <l spec=ecmascript>{{ArrayBuffer}}</l> and
        <l spec=ecmascript>{{SharedArrayBuffer}}</l> objects |V| for which
        <a abstract-op>IsResizableArrayBuffer</a>(|V|) is false.
    </li>
    <li>
        If the type is [=extended attributes associated with|associated with=] both the
        [{{AllowResizable}}] and the [{{AllowShared}}] [=extended attribute|extended attributes=],
        they can be backed by any JavaScript <l spec=ecmascript>{{ArrayBuffer}}</l> or
        <l spec=ecmascript>{{SharedArrayBuffer}}</l> object.
    </li>
</ul>

<div id="js-to-buffer-source" algorithm="convert a JavaScript value to IDL ArrayBuffer">
    <span id="es-to-buffer-source"></span>

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{ArrayBuffer}} value by running the following algorithm:

    1.  If |V| [=is not an Object=],
        or |V| does not have an \[[ArrayBufferData]] [=/internal slot=],
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  If <a abstract-op>IsSharedArrayBuffer</a>(|V|) is true, then [=JavaScript/throw=]
        a <l spec=ecmascript>{{TypeError}}</l>.
    1.  If the conversion is not to an IDL type
        [=extended attributes associated with|associated with=] the [{{AllowResizable}}]
        [=extended attribute=], and <a abstract-op>IsResizableArrayBuffer</a>(|V|) is true,
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Return the IDL {{ArrayBuffer}} value that is a reference
        to the same object as |V|.
</div>

<div algorithm="convert a JavaScript value to IDL SharedArrayBuffer">

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{SharedArrayBuffer}} value by running the following algorithm:

    1.  If |V| [=is not an Object=],
        or |V| does not have an \[[ArrayBufferData]] [=/internal slot=],
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  If <a abstract-op>IsSharedArrayBuffer</a>(|V|) is false, then [=JavaScript/throw=]
        a <l spec=ecmascript>{{TypeError}}</l>.
    1.  If the conversion is not to an IDL type
        [=extended attributes associated with|associated with=] the [{{AllowResizable}}]
        [=extended attribute=], and <a abstract-op>IsResizableArrayBuffer</a>(|V|) is true,
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Return the IDL {{SharedArrayBuffer}} value that is a reference
        to the same object as |V|.
</div>

<div algorithm="convert a JavaScript value to IDL DataView">

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL {{DataView}} value by running the following algorithm:

    1.  If |V| [=is not an Object=],
        or |V| does not have a \[[DataView]] [=/internal slot=],
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  If the conversion is not to an IDL type
        [=extended attributes associated with|associated with=] the [{{AllowShared}}]
        [=extended attribute=], and <a abstract-op>IsSharedArrayBuffer</a>(|V|.\[[ViewedArrayBuffer]]) is true,
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  If the conversion is not to an IDL type
        [=extended attributes associated with|associated with=] the [{{AllowResizable}}]
        [=extended attribute=], and <a abstract-op>IsResizableArrayBuffer</a>(|V|.\[[ViewedArrayBuffer]]) is true,
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Return the IDL {{DataView}} value that is a reference
        to the same object as |V|.
</div>

<div algorithm="convert a JavaScript value to IDL typed array">

    A JavaScript value |V| is
    [=converted to an IDL value|converted=]
    to an IDL {{Int8Array}},
    {{Int16Array}},
    {{Int32Array}},
    {{Uint8Array}},
    {{Uint16Array}},
    {{Uint32Array}},
    {{Uint8ClampedArray}},
    {{BigInt64Array}},
    {{BigUint64Array}},
    {{Float16Array}},
    {{Float32Array}}, or
    {{Float64Array}} value
    by running the following algorithm:

    1.  Let |T| be the IDL type |V| is being converted to.
    1.  If |V| [=is not an Object=],
        or |V| does not have a \[[TypedArrayName]] [=/internal slot=]
        with a value equal to |T|'s name,
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  If the conversion is not to an IDL type
        [=extended attributes associated with|associated with=] the [{{AllowShared}}]
        [=extended attribute=], and <a abstract-op>IsSharedArrayBuffer</a>(|V|.\[[ViewedArrayBuffer]]) is true,
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  If the conversion is not to an IDL type
        [=extended attributes associated with|associated with=] the [{{AllowResizable}}]
        [=extended attribute=], and <a abstract-op>IsResizableArrayBuffer</a>(|V|.\[[ViewedArrayBuffer]]) is true,
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Return the IDL value of type |T| that is a reference to the same object as |V|.
</div>

<div id="buffer-source-to-js" algorithm="convert a buffer source type to an ECMAScript value">
<span id="buffer-source-to-es"></span>
The result of [=converted to a JavaScript value|converting=]
an IDL value of any [=buffer source type=]
to a JavaScript value is the Object value that represents
a reference to the same object that the IDL value represents.
</div>

<hr>

<div algorithm>
    To <dfn export for="ArrayBuffer">create</dfn> an {{ArrayBuffer}} from a [=byte sequence=]
    |bytes| in a [=realm=] |realm|:

    1.  Let |jsArrayBuffer| be [=?=]
        [$AllocateArrayBuffer$](|realm|.\[[Intrinsics]].\[[{{%ArrayBuffer%}}]], |bytes|'s
        [=byte sequence/length=]).
    1.  Let |arrayBuffer| be the result of [=converted to an IDL value|converting=] |jsArrayBuffer|
        to an IDL value of type {{ArrayBuffer}}.
    1.  [=ArrayBuffer/Write=] |bytes| into |arrayBuffer|.
    1.  Return |arrayBuffer|.
</div>

<div algorithm>
    To <dfn export for=SharedArrayBuffer>create</dfn> a {{SharedArrayBuffer}} from a
    [=byte sequence=] |bytes| in a [=realm=] |realm|:

    1.  Let |jsSharedArrayBuffer| be [=?=]
        [$AllocateSharedArrayBuffer$](|realm|.\[[Intrinsics]].\[[{{%SharedArrayBuffer%}}]], |bytes|'s
        [=byte sequence/length=]).
    1.  Let |sharedArrayBuffer| be the result of [=converted to an IDL value|converting=]
        |jsSharedArrayBuffer| to an IDL value of type {{SharedArrayBuffer}}.
    1.  [=SharedArrayBuffer/Write=] |bytes| into |sharedArrayBuffer|.
    1.  Return |sharedArrayBuffer|.
</div>

<div algorithm>
    To <dfn export for="ArrayBufferView">create</dfn> one of the {{ArrayBufferView}} types from a
    [=byte sequence=] |bytes| in a [=realm=] |realm|:

    1.  Assert: if the type is not {{DataView}}, then |bytes|'s [=byte sequence/length=] [=modulo=]
        the [=element size=] of that type is 0.
    1.  Let |arrayBuffer| be the result of [=ArrayBuffer/creating=] an {{ArrayBuffer}} from |bytes|
        in |realm|.
    1.  Let |jsArrayBuffer| be the result of [=converted to a JavaScript value|converting=]
        |arrayBuffer| to a JavaScript value.
    1.  Let |constructor| be the appropriate constructor from |realm|.\[[Intrinsics]] for the type
        of {{ArrayBufferView}} being created.
    1.  Let |jsView| be [=!=] [$Construct$](|constructor|, « |jsArrayBuffer| »).
    1.  Return the result of [=converted to an IDL value|converting=] |jsView| into the given type.
</div>

<div algorithm>
    To <dfn id="dfn-get-buffer-source-copy" export lt="get a copy of the buffer source|get a copy of the bytes held by the buffer source">get a copy of the bytes held by the buffer source</dfn>
    given a [=buffer source type=] instance |bufferSource|:

    1.  Let |jsBufferSource| be the result of [=converted to a JavaScript value|converting=]
        |bufferSource| to a JavaScript value.
    1.  Let |jsArrayBuffer| be |jsBufferSource|.
    1.  Let |offset| be 0.
    1.  Let |length| be 0.
    1.  If |jsBufferSource| has a \[[ViewedArrayBuffer]] [=/internal slot=], then:
        1.  Set |jsArrayBuffer| to |jsBufferSource|.\[[ViewedArrayBuffer]].
        1.  Set |offset| to |jsBufferSource|.\[[ByteOffset]].
        1.  Set |length| to |jsBufferSource|.\[[ByteLength]].
    1.  Otherwise:
        1.  Assert: |jsBufferSource| is an {{ArrayBuffer}} or
            {{SharedArrayBuffer}} object.
        1.  Set |length| to |jsBufferSource|.\[[ArrayBufferByteLength]].
    1.  If [$IsDetachedBuffer$](|jsArrayBuffer|) is true, then return the empty
        [=byte sequence=].
    1.  Let |bytes| be a new [=byte sequence=] of [=byte sequence/length=] equal to |length|.
    1.  For |i| in [=the range=] |offset| to |offset| + |length| &minus; 1, inclusive, set
        |bytes|[|i| &minus; |offset|] to [$GetValueFromBuffer$](|jsArrayBuffer|, |i|, Uint8,
        true, Unordered).
    1.  Return |bytes|.
</div>

<div algorithm>
    The <dfn export for="BufferSource">byte length</dfn> of a [=buffer source type=] instance
    |bufferSource| is the value returned by the following steps:

    1.  Let |jsBufferSource| be the result of [=converted to a JavaScript value|converting=]
        |bufferSource| to a JavaScript value.
    1.  If |jsBufferSource| has a \[[ViewedArrayBuffer]] internal slot, then return
        |jsBufferSource|.\[[ByteLength]].
    1.  Return |jsBufferSource|.\[[ArrayBufferByteLength]].
</div>
<!-- TODO: should this be stricter around not being detached? -->

<div algorithm>
    The <dfn export for="BufferSource">underlying buffer</dfn> of a [=buffer source type=] instance
    |bufferSource| is the value returned by the following steps:

    1.  If |bufferSource| is a [=buffer type=] instance, then return |bufferSource|.
    1.  Let |jsBufferView| be the result of [=converted to a JavaScript value|converting=]
        |bufferSource| to a JavaScript value.
    1.  Let |jsBuffer| be |jsBufferView|.\[[ViewedArrayBuffer]].
    1.  If [$IsSharedArrayBuffer$](|jsBuffer|) is false, then return the result of
        [=converted to an IDL value|converting=] |jsBuffer| to an IDL value of type {{ArrayBuffer}}.
    1.  Return the result of [=converted to an IDL value|converting=] |jsBuffer| to an IDL value of
        type {{SharedArrayBuffer}}.
</div>

<div algorithm="ArrayBuffer/write">
    To <dfn id=arraybuffer-write export for="ArrayBuffer,SharedArrayBuffer">write</dfn> a
    [=byte sequence=] |bytes| into a [=buffer type=] instance |arrayBuffer|, optionally given a
    <dfn id=arraybuffer-write-startingoffset export for="ArrayBuffer/write,SharedArrayBuffer/write">|startingOffset|</dfn>
    (default 0):

    1.  Let |jsArrayBuffer| be the result of [=converted to a JavaScript value|converting=]
        |arrayBuffer| to a JavaScript value.
    1.  Assert: |bytes|'s [=byte sequence/length=] ≤ |jsArrayBuffer|.\[[ArrayBufferByteLength]]
        &minus; |startingOffset|.
    1.  For |i| in [=the range=] |startingOffset| to |startingOffset| + |bytes|'s [=byte
        sequence/length=] &minus; 1, inclusive, perform [$SetValueInBuffer$](|jsArrayBuffer|,
        |i|, Uint8, |bytes|[|i| - |startingOffset|], true, Unordered).
</div>

<div algorithm="ArrayBufferView/write">
    To <dfn export for="ArrayBufferView">write</dfn> a [=byte sequence=] |bytes| into an
    {{ArrayBufferView}} |view|, optionally given a
    <dfn export for="ArrayBufferView/write">|startingOffset|</dfn> (default 0):

    1.  Let |jsView| be the result of [=converted to a JavaScript value|converting=] |view| to
        a JavaScript value.
    1.  Assert: |bytes|'s [=byte sequence/length=] ≤ |jsView|.\[[ByteLength]] &minus;
        |startingOffset|.
    1.  Assert: if |view| is not a {{DataView}}, then |bytes|'s [=byte sequence/length=] [=modulo=]
        the [=element size=] of |view|'s type is 0.
    1.  Let |arrayBuffer| be the result of [=converted to an IDL value|converting=]
        |jsView|.\[[ViewedArrayBuffer]] to an IDL value of type {{ArrayBuffer}}.
    1.  [=ArrayBuffer/Write=] |bytes| into |arrayBuffer| with
        <i>[=ArrayBuffer/write/startingOffset=]</i> set to |jsView|.\[[ByteOffset]] +
        |startingOffset|.
</div>

<div class="warning">
    Extreme care must be taken when writing specification text that
    [=ArrayBuffer/writes=] into a [=buffer source type=] instance, as the underlying data
    can easily be changed by the script author or other APIs at unpredictable times. This is
    especially true if a {{SharedArrayBuffer}} object is involved.

    For the non-shared cases, a more recommended pattern is to [=ArrayBuffer/transfer=] the
    {{ArrayBuffer}} first if possible, to ensure the writes cannot overlap with other modifications,
    and then give the new {{ArrayBuffer}} instance to author code as necessary. Alternately, you can
    [=get a copy of the bytes held by the buffer source=], modify those bytes, and then use them to
    [=ArrayBuffer/create=] a new {{ArrayBuffer}} or {{ArrayBufferView}} to give back to author code.
</div>

<div algorithm>
    To <dfn id="dfn-detach" for="ArrayBuffer" export>detach</dfn> an {{ArrayBuffer}} |arrayBuffer|:

    1.  Let |jsArrayBuffer| be the result of [=converted to a JavaScript value|converting=]
        |arrayBuffer| to a JavaScript value.
    1.  Perform [=?=] [$DetachArrayBuffer$](|jsArrayBuffer|).

    <p class="note" id="note-ArrayBuffer-detach-exceptions">This will throw an exception if
    |jsArrayBuffer| has an \[[ArrayBufferDetachKey]] that is not undefined, such as is the case
    with the value of {{Memory|WebAssembly.Memory}}'s {{Memory/buffer}} attribute.
    [[WASM-JS-API-1]]

    <p class="note">Detaching a buffer that is already [=BufferSource/detached=] is a no-op.
</div>

<div algorithm>
    A [=buffer source type=] instance |bufferSource| is
    <dfn for="BufferSource" export>detached</dfn> if the following steps return true:

    1.  Let |jsArrayBuffer| be the result of [=converted to a JavaScript value|converting=]
        |bufferSource| to a JavaScript value.
    1.  If |jsArrayBuffer| has a \[[ViewedArrayBuffer]] internal slot, then set |jsArrayBuffer| to
        |jsArrayBuffer|.\[[ViewedArrayBuffer]].
    1.  Return [$IsDetachedBuffer$](|jsArrayBuffer|).
</div>

<div algorithm>
    A [=buffer source type=] instance |bufferSource| is
    <dfn for="BufferSource" export>transferable</dfn> if the following steps return true:

    1.  Let |jsArrayBuffer| be the result of [=converted to a JavaScript value|converting=]
        |bufferSource| to a JavaScript value.
    1.  If |jsArrayBuffer| has a \[[ViewedArrayBuffer]] internal slot, then set |jsArrayBuffer| to
        |jsArrayBuffer|.\[[ViewedArrayBuffer]].
    1.  If [$IsSharedArrayBuffer$](|jsArrayBuffer|) is true, then return false.
    1.  If [$IsDetachedBuffer$](|jsArrayBuffer|) is true, then return false.
    1.  If |jsArrayBuffer|.\[[ArrayBufferDetachKey]] is not <emu-val>undefined</emu-val>, then
        return false.
    1.  Return true.
</div>

<div algorithm>
    To <dfn for="ArrayBuffer" export>transfer</dfn> an {{ArrayBuffer}} |arrayBuffer|, optionally
    given a [=realm=] |targetRealm|:

    1.  Let |jsArrayBuffer| be the result of [=converted to a JavaScript value|converting=]
        |arrayBuffer| to a JavaScript value.
    1.  If [$IsDetachedBuffer$](|jsArrayBuffer|) is false, then [=JavaScript/throw=] a
        <l spec=ecmascript>{{TypeError}}</l>.
    1.  Let |arrayBufferData| be |jsArrayBuffer|.\[[ArrayBufferData]].
    1.  Let |arrayBufferByteLength| be |jsArrayBuffer|.\[[ArrayBufferByteLength]].
    1.  Perform [=?=] [$DetachArrayBuffer$](|jsArrayBuffer|).
    1.  If |targetRealm| is not given, let |targetRealm| be the [=current realm=].
    1.  Let |jsTransferred| be [=?=]
        [$AllocateArrayBuffer$](|targetRealm|.\[[Intrinsics]].\[[{{%ArrayBuffer%}}]], 0).
    1.  Set |jsTransferred|.\[[ArrayBufferData]] to |arrayBufferData|.
    1.  Set |jsTransferred|.\[[ArrayBufferByteLength]] to |arrayBufferByteLength|.
    1.  Return the result of [=converted to an IDL value|converting=] |jsTransferred| to an IDL
        value of type {{ArrayBuffer}}.

    <div class="note" id="note-ArrayBuffer-transfer-exceptions">
        This will throw an exception under any of the following circumstances:

        *   |arrayBuffer| cannot be [=BufferSource/detached=], for the reasons
            <a href="#note-ArrayBuffer-detach-exceptions">explained in that algorithm's
            definition</a>;
        *   |arrayBuffer| is already [=BufferSource/detached=];
        *   Sufficient memory cannot be allocated in |realm|. Generally this will only be the case
            if |realm| is in a different [=agent cluster=] than the one in which |arrayBuffer| was
            allocated. If they are in the same [=agent cluster=], then implementations will just
            change the backing pointers to get the same observable results with better performance
            and no allocations.
    </div>
</div>

<h4 id="js-frozen-array" oldids="es-frozen-array">Frozen arrays — FrozenArray&lt;|T|&gt;</h4>

Values of frozen array types are represented by frozen JavaScript
Array object references.

<div algorithm="convert a JavaScript value to frozen array">

    A JavaScript value |V| is [=converted to an IDL value|converted=]
    to an IDL <a interface lt="FrozenArray">FrozenArray&lt;|T|&gt;</a> value
    by running the following algorithm:

    1.  Let |values| be the result of
        [=converted to an IDL value|converting=]
        |V| to IDL type <a lt="sequence type">sequence&lt;|T|&gt;</a>.
    1.  Return the result of
        [=create a frozen array|creating a frozen array=]
        from |values|.
</div>

<div algorithm>

    To <dfn id="dfn-create-frozen-array" lt="create a frozen array|creating a frozen array" export>create a frozen array</dfn>
    from a sequence of values of type |T|, follow these steps:

    1.  Let |array| be the result of
        [=converted to a JavaScript value|converting=]
        the sequence of values of type |T| to a JavaScript value.
    1.  Perform [=!=] <a abstract-op>SetIntegrityLevel</a>(|array|, "<code>frozen</code>").
    1.  Return |array|.
</div>

The result of [=converted to a JavaScript value|converting=]
an IDL <a interface lt="FrozenArray">FrozenArray&lt;|T|&gt;</a> value to a JavaScript
value is the Object value that represents a reference
to the same object that the IDL <a interface lt="FrozenArray">FrozenArray&lt;|T|&gt;</a> represents.


<h5 id="create-frozen-array-from-iterable" dfn>Creating a frozen array from an iterable</h5>

<div algorithm="create frozen array from iterable">

    To create an IDL value of type <a interface lt="FrozenArray">FrozenArray&lt;|T|&gt;</a> given an
    iterable |iterable| and an iterator getter |method|, perform the following steps:

    1.  Let |values| be the result of [=creating a sequence from an iterable|creating a sequence=]
        of type <a lt="sequence type">sequence&lt;|T|&gt;</a> from |iterable| and |method|.
    1.  Return the result of [=create a frozen array|creating a frozen array=] from |values|.
</div>

<h4 id="js-observable-array" oldids="es-observable-array">Observable arrays — ObservableArray&lt;|T|&gt;</h4>

Values of observable array types are represented by [=observable array exotic objects=].

Instead of the usual conversion algorithms, observable array types have special handling as part of
the [=attribute getter=] and [=attribute setter=] algorithms.

In the JavaScript binding, JavaScript objects that represent [=platform objects=] have a
<dfn>backing observable array exotic object</dfn> for each [=regular attribute=] of an
[=observable array type=]. These are created and managed as part of the [=define the attributes=]
algorithm.

<div algorithm="observable array backing list">
    The [=observable array attribute/backing list=] for an observable array attribute in the
    JavaScript binding, given a [=platform object=] |obj| and an attribute |attribute|, is the
    [=list=] returned by the following algorithm:

    1.  Assert: |obj| [=implements=] an [=interface=] with the [=regular attribute=] |attribute|.
    1.  Let |oa| be |obj|'s [=backing observable array exotic object=] for |attribute|.
    1.  Return |oa|.\[[ProxyHandler]].\[[BackingList]].
</div>


<h3 id="js-extended-attributes" oldids="es-extended-attributes">Extended attributes</h3>

This section defines a number of
[=extended attributes=]
whose presence affects the JavaScript binding.


<h4 id="AllowResizable" extended-attribute lt="AllowResizable">[AllowResizable]</h4>

If the [{{AllowResizable}}] [=extended attribute=] appears on a [=buffer type=], it creates a new
IDL type that allows for the respective corresponding JavaScript <l spec=ecmascript>{{ArrayBuffer}}</l>
or <l spec=ecmascript>{{SharedArrayBuffer}}</l> object to be resizable.

If the [{{AllowResizable}}] [=extended attribute=] appears on one of the [=buffer view types=] and
the [{{AllowShared}}] [=extended attribute=] does not, it creates a new IDL type that allows the
buffer view type to be backed by a JavaScript <l spec=ecmascript>{{ArrayBuffer}}</l> that is
resizable, instead of only by a fixed-length <l spec=ecmascript>{{ArrayBuffer}}</l>.

If the [{{AllowResizable}}] [=extended attribute=] and the [{{AllowShared}}] [=extended attribute=]
both appear on one of the [=buffer view types=], it creates a new IDL type that allows the buffer
view type to be additionally backed by a JavaScript <l spec=ecmascript>{{SharedArrayBuffer}}</l>
that is growable.

The [{{AllowResizable}}] extended attribute must [=takes no arguments|take no arguments=].

A type that is not a [=buffer source type=] must not be
[=extended attributes associated with|associated with=] the [{{AllowResizable}}] extended attribute.

See the rules for converting JavaScript values to IDL [=buffer source types=] in
[[#js-buffer-source-types]] for the specific requirements that the use of [{{AllowResizable}}] entails.

See the <a href="#example-allowresizable-allowshared">example</a> in [[#AllowShared]] for example usage of both [{{AllowResizable}}] and [{{AllowShared}}].


<h4 id="AllowShared" extended-attribute lt="AllowShared">[AllowShared]</h4>

If the [{{AllowShared}}] [=extended attribute=] appears on one of the [=buffer view types=], it
creates a new IDL type that allows the object to be backed by an {{SharedArrayBuffer}} instead of
only by an {{ArrayBuffer}}.

The [{{AllowShared}}] extended attribute must [=takes no arguments|take no arguments=].

A type that is not a [=buffer view type=] must not be
[=extended attributes associated with|associated with=] the [{{AllowShared}}] extended attribute.

See the rules for converting JavaScript values to IDL [=buffer view types=] in
[[#js-buffer-source-types]] for the specific requirements that the use of [{{AllowShared}}] entails.

<div class="example" id="example-allowresizable-allowshared">
    The following [=IDL fragment=] demonstrates the possible combinations of the
    [{{AllowResizable}}] and [{{AllowShared}}] [=extended attribute=]:

    <pre highlight="webidl">
        [Exposed=Window]
        interface ExampleBufferFeature {
          undefined writeInto(ArrayBufferView dest);
          undefined writeIntoResizable([AllowResizable] ArrayBufferView dest);
          undefined writeIntoShared([AllowShared] ArrayBufferView dest);
          undefined writeIntoSharedResizable([AllowResizable, AllowShared] ArrayBufferView dest);
        };
    </pre>

    With this definition,
    <ul>
        <li>
            A call to <code>writeInto</code> with any [=buffer view type=] backed by
            either a resizable {{ArrayBuffer}} instance or a {{SharedArrayBuffer}} instance,
            will throw a {{TypeError}} exception.
       </li>
        <li>
            A call to <code>writeIntoResizable</code> with any [=buffer view type=] backed by
            a {{SharedArrayBuffer}} instance, will throw a
            {{TypeError}} exception.
        </li>
        <li>
            A call to <code>writeIntoShared</code> with any [=buffer view type=] backed by a
            resizable {{ArrayBuffer}} instance or a growable {{SharedArrayBuffer}} instance,
            will throw a {{TypeError}} exception.
        </li>
        <li>
            A call to <code>writeIntoSharedResizable</code> will accept any
            [=buffer view type=] backed by a {{ArrayBuffer}} instance or a
            {{SharedArrayBuffer}} instance.
        </li>
    </ul>
</div>


<h4 id="Clamp" extended-attribute lt="Clamp">[Clamp]</h4>

If the [{{Clamp}}] [=extended attribute=] appears on one of the [=integer types=], it creates a new
IDL type such that that when a JavaScript Number is converted to the IDL type,
out-of-range values will be clamped to the range of valid values, rather than using the operators
that use a modulo operation (<a abstract-op>ToInt32</a>, <a abstract-op>ToUint32</a>, etc.).

The [{{Clamp}}]
extended attribute must
[=takes no arguments|take no arguments=].

A type annotated with the [{{Clamp}}] extended attribute must not appear in a [=read only=]
attribute. A type must not be [=extended attributes associated with|associated with=] both the
[{{Clamp}}] and [{{EnforceRange}}] extended attributes. A type that is not an [=integer type=] must
not be [=extended attributes associated with|associated with=] the [{{Clamp}}] extended attribute.

See the rules for converting JavaScript values to the various IDL integer
types in [[#js-integer-types]]
for the specific requirements that the use of
[{{Clamp}}] entails.

<div class="example" id="example-401309f5">

    In the following [=IDL fragment=],
    two [=operations=] are declared that
    take three {{octet}} arguments; one uses
    the [{{Clamp}}] [=extended attribute=]
    on all three arguments, while the other does not:

    <pre highlight="webidl">
        [Exposed=Window]
        interface GraphicsContext {
          undefined setColor(octet red, octet green, octet blue);
          undefined setColorClamped([Clamp] octet red, [Clamp] octet green, [Clamp] octet blue);
        };
    </pre>

    A call to <code>setColorClamped</code> with
    Number values that are out of range for an
    {{octet}} are clamped to the range [0, 255].

    <pre highlight="js">
        // Get an instance of GraphicsContext.
        var context = getGraphicsContext();

        // Calling the non-[Clamp] version uses ToUint8 to coerce the Numbers to octets.
        // This is equivalent to calling setColor(255, 255, 1).
        context.setColor(-1, 255, 257);

        // Call setColorClamped with some out of range values.
        // This is equivalent to calling setColorClamped(0, 255, 255).
        context.setColorClamped(-1, 255, 257);
    </pre>
</div>


<h4 id="CrossOriginIsolated" extended-attribute lt="CrossOriginIsolated">[CrossOriginIsolated]</h4>

If the [{{CrossOriginIsolated}}] [=extended attribute=] appears on an
[=interface=],
[=partial interface=],
[=interface mixin=],
[=partial interface mixin=],
[=callback interface=],
[=namespace=],
[=partial namespace=],
[=interface member=],
[=interface mixin member=], or
[=namespace member=],
it indicates that the construct is [=exposed=] only within an environment whose
[=environment settings object/cross-origin isolated capability=] is true. The
[{{CrossOriginIsolated}}] extended attribute must not be used on any other construct.

The [{{CrossOriginIsolated}}] extended attribute must [=takes no arguments|take no arguments=].

If [{{CrossOriginIsolated}}] appears on an [=overloaded=] [=operation=],
then it must appear on all overloads.

The [{{CrossOriginIsolated}}] [=extended attribute=] must not be specified both on

* an [=interface member=] and its [=interface=] or [=partial interface=];
* an [=interface mixin member=] and its [=interface mixin=] or [=partial interface mixin=];
* a [=namespace member=] and its [=namespace=] or [=partial namespace=].

Note: This is because adding the [{{CrossOriginIsolated}}] [=extended attribute=] on a [=member=]
when its containing definition is also annotated with the [{{CrossOriginIsolated}}]
[=extended attribute=] does not further restrict the exposure of the [=member=].

An [=interface=] without the [{{CrossOriginIsolated}}] [=extended attribute=]
must not [=interface/inherit=] from another interface
that does specify [{{CrossOriginIsolated}}].

<div class="example" id="example-3d6a455d">

    The following [=IDL fragment=] defines an interface with one [=operation=] that is executable
    from all contexts, and two which are executable only from cross-origin isolated contexts.

    <pre highlight="webidl">
        [Exposed=Window]
        interface ExampleFeature {
          // This call will succeed in all contexts.
          Promise &lt;Result&gt; calculateNotSoSecretResult();

          // This operation will not be exposed to a non-isolated context. In such a context,
          // there will be no "calculateSecretResult" property on ExampleFeature.prototype.
          [CrossOriginIsolated] Promise&lt;Result&gt; calculateSecretResult();

          // The same applies here: the attribute will not be exposed to a non-isolated context,
          // and in such a context there will be no "secretBoolean" property on
          // ExampleFeature.prototype.
          [CrossOriginIsolated] readonly attribute boolean secretBoolean;
        };

        // HighResolutionTimer will not be exposed in a non-isolated context, nor will its members.
        // In such a context, there will be no "HighResolutionTimer" property on Window.
        [Exposed=Window, CrossOriginIsolated]
        interface HighResolutionTimer {
          DOMHighResTimeStamp getHighResolutionTime();
        };

        // The interface mixin members defined below will never be exposed in a non-isolated
        // context, regardless of whether the interface that includes them is. That is, in
        // non-isolated context, there will be no "snap" property on ExampleFeature.prototype.
        [CrossOriginIsolated]
        interface mixin Snapshotable {
          Promise&lt;boolean&gt; snap();
        };
        ExampleFeature includes Snapshotable;

        // On the other hand, the following interface mixin members will be exposed to a
        // non-isolated context when included by a host interface that doesn't have the
        // [CrossOriginIsolated] extended attribute. That is, in a non-isolated context, there will
        // be a "log" property on ExampleFeature.prototype.
        interface mixin Loggable {
          Promise&lt;boolean&gt; log();
        };
        ExampleFeature includes Loggable;
    </pre>
</div>


<h4 id="Default" extended-attribute lt="Default">[Default]</h4>

If the [{{Default}}] [=extended attribute=] appears on a [=regular operation=], then it indicates
that the appropriate [=default method steps=] must be carried out when the operation is invoked.

The [{{Default}}] extended attribute must
[=takes no arguments|take no arguments=].

The [{{Default}}] extended attribute must not be used on anything other than a [=regular operation=]
that [=has default method steps=] defined.

<div class="example" id="example-tojson-default">

    As an example, the [{{Default}}] extended attribute is suitable
    for use on <code>toJSON</code> [=regular operations=]:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Animal {
          attribute DOMString name;
          attribute unsigned short age;
          [Default] object toJSON();
        };

        [Exposed=Window]
        interface Human : Animal {
          attribute Dog? pet;
          [Default] object toJSON();
        };

        [Exposed=Window]
        interface Dog : Animal {
          attribute DOMString? breed;
        };

    </pre>

    In the JavaScript language binding, there would exist a <code>toJSON()</code> method on
    <code class="idl">Animal</code>, <code class="idl">Human</code>,
    and (via inheritance) <code class="idl">Dog</code> objects:

    <pre highlight="js">
        // Get an instance of Human.
        var alice = getHuman();

        // Evaluates to an object like this (notice how "pet" still holds
        // an instance of Dog at this point):
        //
        // {
        //   name: "Alice",
        //   age: 59,
        //   pet: Dog
        // }
        alice.toJSON();

        // Evaluates to an object like this (notice how "breed" is absent,
        // as the Dog interface doesn't use the default toJSON steps):
        //
        // {
        //   name: "Tramp",
        //   age: 6
        // }
        alice.pet.toJSON();

        // Evaluates to a string like this:
        // '{"name":"Alice","age":59,"pet":{"name":"Tramp","age":6}}'
        JSON.stringify(alice);
    </pre>
</div>


<h4 id="EnforceRange" extended-attribute lt="EnforceRange">[EnforceRange]</h4>

If the [{{EnforceRange}}] [=extended attribute=] appears on one of the [=integer types=], it creates
a new IDL type such that that when a JavaScript Number is converted to the IDL
type, out-of-range values will cause an exception to be thrown, rather than being converted to a
valid value using using the operators that use a modulo operation (<a abstract-op>ToInt32</a>, <a abstract-op>ToUint32</a>, etc.).
The Number will be rounded toward zero before being checked against its range.

The [{{EnforceRange}}]
extended attribute must
[=takes no arguments|take no arguments=].

A type annotated with the [{{EnforceRange}}] extended attribute must not appear in a
[=read only=] attribute. A type must not be [=extended attributes associated with|associated with=]
both the [{{Clamp}}] and [{{EnforceRange}}] extended attributes. A type that is not an
[=integer type=] must not be [=extended attributes associated with|associated with=] the
[{{EnforceRange}}] extended attribute.

See the rules for converting JavaScript values to the various IDL integer
types in [[#js-type-mapping]]
for the specific requirements that the use of
[{{EnforceRange}}] entails.

<div class="example" id="example-1a34c82a">

    In the following [=IDL fragment=],
    two [=operations=] are declared that
    take three {{octet}} arguments; one uses
    the [{{EnforceRange}}] [=extended attribute=]
    on all three arguments, while the other does not:

    <pre highlight="webidl">
        [Exposed=Window]
        interface GraphicsContext {
          undefined setColor(octet red, octet green, octet blue);
          undefined setColorEnforcedRange([EnforceRange] octet red, [EnforceRange] octet green, [EnforceRange] octet blue);
        };
    </pre>

    In a JavaScript implementation of the IDL, a call to setColorEnforcedRange with
    Number values that are out of range for an
    {{octet}} will result in an exception being
    thrown.

    <pre highlight="js">
        // Get an instance of GraphicsContext.
        var context = getGraphicsContext();

        // Calling the non-[EnforceRange] version uses ToUint8 to coerce the Numbers to octets.
        // This is equivalent to calling setColor(255, 255, 1).
        context.setColor(-1, 255, 257);

        // When setColorEnforcedRange is called, Numbers are rounded towards zero.
        // This is equivalent to calling setColor(0, 255, 255).
        context.setColorEnforcedRange(-0.9, 255, 255.2);

        // The following will cause a TypeError to be thrown, since even after
        // rounding the first and third argument values are out of range.
        context.setColorEnforcedRange(-1, 255, 256);
    </pre>
</div>


<h4 id="Exposed" extended-attribute lt="Exposed">[Exposed]</h4>

When the [{{Exposed}}] [=extended attribute=] appears on
an [=interface=],
[=partial interface=],
[=interface mixin=],
[=partial interface mixin=],
[=callback interface=],
[=namespace=],
[=partial namespace=], or
an individual [=interface member=],
[=interface mixin member=], or
[=namespace member=],
it indicates that the construct is exposed
on that particular set of global interfaces.

The [{{Exposed}}] [=extended attribute=] must either
[=takes an identifier|take an identifier=],
[=takes an identifier list|take an identifier list=] or
[=takes a wildcard|take a wildcard=].
Each of the identifiers mentioned must be a [=global name=] of some [=interface=] and be unique.

The <dfn>own exposure set</dfn> is either a [=/set=] of identifiers or the special value
<code>*</code>, defined as follows:

<dl class="switch">
     :  If the [{{Exposed}}] [=extended attribute=] [=takes an identifier=] |I|
     :: The [=own exposure set=] is the [=/set=] « |I| ».
     :  If the [{{Exposed}}] [=extended attribute=] [=takes an identifier list=] |I|
     :: The [=own exposure set=] is the [=/set=] |I|.
     :  If the [{{Exposed}}] [=extended attribute=] [=takes a wildcard=]
     :: The [=own exposure set=] is <code>*</code>.
</dl>

<p class="advisement">
    <code>[Exposed=*]</code> is to be used with care.
    It is only appropriate when an API does not expose significant new capabilities.
    If the API might be restricted or disabled in some environments,
    it is preferred to list the globals explicitly.
</p>

<div algorithm>

The <dfn>exposure set intersection</dfn> of a construct |C| and interface-or-null |H| is defined as
follows:

1.  Assert: |C| is an [=interface member=], [=interface mixin member=], [=namespace member=],
    [=partial interface=], [=partial interface mixin=], [=partial namespace=], or
    [=interface mixin=].
1.  Assert: |H| is an [=interface=] or null.
1.  If |H| is null, return |C|'s [=own exposure set=].
1.  If |C|'s [=own exposure set=] is <code>*</code>, return |H|'s [=exposure set=].
1.  If |H|'s [=exposure set=] is <code>*</code>, return |C|'s [=own exposure set=].
1.  Return the [=set/intersection=] of |C|'s [=own exposure set=] and |H|'s
    [=exposure set=].

</div>

<div algorithm>
    To get the <dfn id="dfn-exposure-set" export>exposure set</dfn> of a construct |C|,
    run the following steps:

    1.  Assert: |C| is an [=interface=], [=callback interface=], [=namespace=],
        [=interface member=], [=interface mixin member=], or [=namespace member=].
    1.  Let |H| be |C|'s [=host interface=] if |C| is an [=interface mixin member=], or null otherwise.
    1.  If |C| is an [=interface member=], [=interface mixin member=], or [=namespace member=], then:
        1.  If the [{{Exposed}}] [=extended attribute=] is specified on |C|,
            return the [=exposure set intersection=] of |C| and |H|.
        1.  Set |C| to the
            [=interface=], [=partial interface=],
            [=interface mixin=], [=partial interface mixin=],
            [=namespace=], or [=partial namespace=]
            |C| is declared on.
    1.  If |C| is a [=partial interface=], [=partial interface mixin=], or [=partial namespace=], then:
        1.  If the [{{Exposed}}] [=extended attribute=] is specified on |C|,
            return the [=exposure set intersection=] of |C| and |H|.
        1.  Set |C| to the original [=interface=], [=interface mixin=], or [=namespace=] definition
            of |C|.
    1.  If |C| is an [=interface mixin=], then:
        1.  Assert: |H| is not null.
        1.  If the [{{Exposed}}] [=extended attribute=] is specified on |C|,
            return the [=exposure set intersection=] of |C| and |H|.
        1.  Set |C| to |H|.
    1.  Assert: |C| is an [=interface=], [=callback interface=] or [=namespace=].
    1.  Assert: The [{{Exposed}}] [=extended attribute=] is specified on |C|.
    1.  Return |C|'s [=own exposure set=].
</div>

If [{{Exposed}}] appears on an [=overloaded=] [=operation=],
then it must appear identically on all overloads.

The [{{Exposed}}] extended attribute must not be specified both on
an [=interface member=], [=interface mixin member=], or [=namespace member=], and on
the [=partial interface=], [=partial interface mixin=], or [=partial namespace=] definition
the [=member=] is declared on.

Note: This is because adding an [{{Exposed}}] [=extended attribute=] on a
[=partial interface=], [=partial interface mixin=], or [=partial namespace=]
is shorthand for annotating each of its [=members=].

If [{{Exposed}}] appears on a [=partial interface=] or [=partial namespace=],
then the partial's [=own exposure set=] must be a subset of
the [=exposure set=] of the partial's original [=interface=] or [=namespace=].

If [{{Exposed}}] appears on an [=interface member|interface=] or [=namespace member=],
then the [=member=]'s [=exposure set=] must be a subset
of the [=exposure set=] of the [=interface=] or [=namespace=] it is a member of.

If [{{Exposed}}] appears both on a [=partial interface mixin=]
and its original [=interface mixin=],
then the [=partial interface mixin=]'s [=own exposure set=]
must be a subset of the [=interface mixin=]'s [=own exposure set=].

If [{{Exposed}}] appears both on an [=interface mixin member=]
and the [=interface mixin=] it is a member of,
then the [=interface mixin members=]'s [=own exposure set=]
must be a subset of the [=interface mixin=]'s [=own exposure set=].

If an interface |X| [=interface/inherits=] from another interface |Y|
then the [=exposure set=] of |X| must be a subset of the [=exposure set=] of |Y|.

Note: As an [=interface mixin=] can be [=included=] by different [=interfaces=],
the [=exposure set=] of its [=interface mixin member|members=] is a function of
the [=interface=] that [=includes=] them.
If the [=interface mixin member=], [=partial interface mixin=], or [=interface mixin=]
is annotated with an [{{Exposed}}] [=extended attribute=],
then the [=interface mixin member=]'s [=exposure set=]
is the [=set/intersection=] of the relevant construct's [=own exposure set=]
with the [=host interface=]'s [=exposure set=].
Otherwise, it is the [=host interface=]'s [=exposure set=].

<div algorithm>
    An [=interface=], [=callback interface=], [=namespace=], or [=member=] |construct| is
    <dfn id="dfn-exposed" export>exposed</dfn> in a given [=realm=] |realm| if the following steps
    return true:

    1.  If |construct|'s [=exposure set=] is not <code>*</code>, and |realm|.\[[GlobalObject]] does
        not implement an [=interface=] that is in |construct|'s [=exposure set=], then return false.
    1.  If |realm|'s [=realm/settings object=] is not a [=secure context=], and |construct| is
        [=conditionally exposed=] on [{{SecureContext}}], then return false.
    1.  If |realm|'s [=realm/settings object=]'s
        [=environment settings object/cross-origin isolated capability=] is false, and |construct|
        is [=conditionally exposed=] on [{{CrossOriginIsolated}}], then return false.
    1.  Return true.
</div>

<div algorithm>
    An [=interface=], [=callback interface=], [=namespace=], or [=member=] |construct| is
    <dfn id="dfn-conditionally-exposed" export>conditionally exposed</dfn> on a given
    [=extended attribute=] |exposure condition| if the following steps return true:

    1.  Assert: |construct| is an [=interface=], [=callback interface=], [=namespace=],
        [=interface member=], [=interface mixin member=], or [=namespace member=].
    1.  Let |H| be |construct|'s [=host interface=] if |construct| is an [=interface mixin member=],
        or null otherwise.
    1.  If |construct| is an [=interface member=], [=interface mixin member=], or
        [=namespace member=], then:
        1.  If the |exposure condition| [=extended attribute=] is specified on |construct|,
            then return true.
        1.  Otherwise, set |construct| to be the
            [=interface=], [=partial interface=],
            [=interface mixin=], [=partial interface mixin=],
            [=namespace=], or [=partial namespace=]
            |construct| is declared on.
    1.  If |construct| is a [=partial interface=], [=partial interface mixin=], or
        [=partial namespace=], then:
        1.  If the |exposure condition| [=extended attribute=] is specified on |construct|,
            then return true.
        1.  Otherwise, set |construct| to be the original [=interface=], [=interface mixin=], or
            [=namespace=] definition of |construct|.
    1.  If |construct| is an [=interface mixin=], then:
        1.  If the |exposure condition| [=extended attribute=] is specified on |construct|,
            then return true.
        1.  Otherwise, set |construct| to |H|.
    1.  Assert: |construct| is an [=interface=], [=callback interface=] or [=namespace=].
    1.  If the |exposure condition| [=extended attribute=] is specified on |construct|,
        then return true.
    1.  Otherwise, return false.
</div>

Note: Since it is not possible for the [=relevant settings object=]
for a JavaScript global object to change whether it is a
[=secure context=] or [=environment settings object/cross-origin isolated capability=] over time, an
implementation's decision to create properties for an interface or interface member can be made
once, at the time the [=initial objects=] are created.

See
[[#js-interfaces]],
[[#js-constants]],
[[#js-attributes]],
[[#js-operations]], and
for the specific requirements that the use of
[{{Exposed}}] entails.

<div class="example" id="example-d5c14f84">

    [{{Exposed}}] is intended to be used to control whether [=interfaces=],
    [=callback interfaces=], [=namespaces=], or individual [=interface member|interface=],
    [=interface mixin member|mixin=] or [=namespace members=] are available for use in workers,
    {{Worklet}}, {{Window}}, or any combination of the above.

    The following IDL fragment shows how that might be achieved:

    <pre highlight="webidl">
        [Exposed=Window, Global=Window]
        interface Window {
          // ...
        };

        // By using the same identifier Worker for both SharedWorkerGlobalScope
        // and DedicatedWorkerGlobalScope, both can be addressed in an [Exposed]
        // extended attribute at once.
        [Exposed=Worker, Global=Worker]
        interface SharedWorkerGlobalScope : WorkerGlobalScope {
          // ...
        };

        [Exposed=Worker, Global=Worker]
        interface DedicatedWorkerGlobalScope : WorkerGlobalScope {
          // ...
        };

        // Dimensions is available for use in workers and on the main thread.
        [Exposed=(Window,Worker)]
        interface Dimensions {
          constructor(double width, double height);
          readonly attribute double width;
          readonly attribute double height;
        };

        // WorkerNavigator is only available in workers.  Evaluating WorkerNavigator
        // in the global scope of a worker would give you its interface object, while
        // doing so on the main thread will give you a ReferenceError.
        [Exposed=Worker]
        interface WorkerNavigator {
          // ...
        };

        // Node is only available on the main thread.  Evaluating Node
        // in the global scope of a worker would give you a ReferenceError.
        [Exposed=Window]
        interface Node {
          // ...
        };

        // MathUtils is available for use in workers and on the main thread.
        [Exposed=(Window,Worker)]
        namespace MathUtils {
          double someComplicatedFunction(double x, double y);
        };

        // WorkerUtils is only available in workers.  Evaluating WorkerUtils
        // in the global scope of a worker would give you its namespace object, while
        // doing so on the main thread will give you a ReferenceError.
        [Exposed=Worker]
        namespace WorkerUtils {
          undefined setPriority(double x);
        };

        // NodeUtils is only available in the main thread.  Evaluating NodeUtils
        // in the global scope of a worker would give you a ReferenceError.
        [Exposed=Window]
        namespace NodeUtils {
          DOMString getAllText(Node node);
        };
    </pre>
</div>


<h4 oldids="PrimaryGlobal" id="Global" extended-attribute lt="Global">[Global]</h4>

If the [{{Global}}] [=extended attribute=] appears on an [=interface=],
it indicates that objects implementing this interface will
be used as the global object in a [=realm=].

The [{{Global}}] [=extended attribute=] also defines the
<dfn id="dfn-global-name" export>global names</dfn> for the [=interface=]:

<dl class="switch">
     :  If the [{{Global}}] [=extended attribute=] [=takes an identifier=]
     :: « the given [=identifier=] »
     :  If the [{{Global}}] [=extended attribute=] [=takes an identifier list=]
     :: the identifier list
</dl>

The [{{Global}}] extended attribute must be one of the forms given above.

Note: The [=global names=] for the [=interface=] are the [=identifiers=] that can be used to
reference it in the [{{Exposed}}] [=extended attribute=].
A single name can be shared across multiple different global interfaces,
allowing an interface to more easily use [{{Exposed}}] to expose itself to all of them at once.
For example, "<code>Worker</code>" is used to refer to several distinct types of threading-related
global interfaces.

For these global [=interfaces=], the structure of the prototype chain and how properties
corresponding to [=interface members=] will be reflected on the prototype objects will be different
from other interfaces. Specifically:

1.  Any [=named properties=]
    will be exposed on an object in the prototype chain – the
    [=named properties object=] –
    rather than on the object itself.
1.  [=Interface members=] from the
    [=interface=]
    will correspond to properties on the object itself rather than on
    [=interface prototype objects=].

All [=realms=] have an <dfn export for="realm">is global prototype chain mutable</dfn> boolean,
which can be set when the [=realm=] is created.
Its value can not change during the lifetime of the [=realm=].
By default it is set to false.

<p class="note">This allows the <code>ShadowRealm</code> global to have a mutable prototype.</p>

<div class="note">

    Placing named properties on an object in the prototype chain
    is done so that variable declarations and bareword assignments
    will shadow the named property with a property on the global
    object itself.

    Placing properties corresponding to interface members on
    the object itself will mean that common feature detection
    methods like the following will work:

    <pre highlight="js">
        var indexedDB = window.indexedDB || window.webkitIndexedDB ||
                        window.mozIndexedDB || window.msIndexedDB;

        var requestAnimationFrame = window.requestAnimationFrame ||
                                    window.mozRequestAnimationFrame || ...;
    </pre>

    Because of the way variable declarations are handled in
    JavaScript, the code above would result in the <code>window.indexedDB</code>
    and <code>window.requestAnimationFrame</code> evaluating
    to <emu-val>undefined</emu-val>, as the shadowing variable
    property would already have been created before the
    assignment is evaluated.

</div>

If the [{{Global}}] [=extended attributes=] is
used on an [=interface=], then:

*   The interface must not define a [=named property setter=].
*   The interface must not define [=indexed property getters=] or [=indexed property setter|setters=].
*   The interface must not define a [=constructor operation=].
*   The interface must not also be declared with the [{{LegacyOverrideBuiltIns}}]
    extended attribute.
*   The interface must not [=interface/inherit=] from another interface with the
    [{{LegacyOverrideBuiltIns}}] extended attribute.
*   Any other interface must not [=interface/inherit=] from it.

If [{{Global}}] is specified on
a [=partial interface=]
definition, then that partial interface definition must
be the part of the interface definition that defines
the [=named property getter=].

The [{{Global}}] [=extended attribute=] must not
be used on an [=interface=] that can have more
than one object implementing it in the same [=realm=].

Note: This is because the [=named properties object=],
which exposes the named properties, is in the prototype chain, and it would not make
sense for more than one object's named properties to be exposed on an object that
all of those objects inherit from.

If an interface is declared with the [{{Global}}] [=extended attribute=], then
there must not be more than one
[=member=] across
the interface
with the same [=identifier=].
There also must not be more than
one [=stringifier=]
or more than one [=iterable declaration=],
[=asynchronously iterable declaration=],
[=maplike declaration=] or
[=setlike declaration=]
across those interfaces.

Note: This is because all of the [=members=] of the interface
get flattened down on to the object that [=implements=] the interface.

See [[#named-properties-object]] for the specific requirements
that the use of [{{Global}}] entails for [=named properties=],
and [[#js-constants]], [[#js-attributes]] and [[#js-operations]]
for the requirements relating to the location of properties
corresponding to [=interface members=].

<div class="example" id="example-2e291568">

    The <code class="idl">Window</code> interface exposes frames as properties on the <code class="idl">Window</code>
    object.  Since the <code class="idl">Window</code> object also serves as the
    JavaScript global object, variable declarations or assignments to the named properties
    will result in them being replaced by the new value.  Variable declarations for
    attributes will not create a property that replaces the existing one.

    <pre highlight="webidl">
        [Exposed=Window, Global=Window]
        interface Window {
          getter any (DOMString name);
          attribute DOMString name;
          // ...
        };
    </pre>

    The following HTML document illustrates how the named properties on the
    <code class="idl">Window</code> object can be shadowed, and how
    the property for an attribute will not be replaced when declaring
    a variable of the same name:

    <pre highlight="html">
        &lt;!DOCTYPE html&gt;
        &lt;title&gt;Variable declarations and assignments on Window&lt;/title&gt;
        &lt;iframe name=abc&gt;&lt;/iframe&gt;
        &lt;!-- Shadowing named properties --&gt;
        &lt;script&gt;
          window.abc;    // Evaluates to the iframe's Window object.
          abc = 1;       // Shadows the named property.
          window.abc;    // Evaluates to 1.
        &lt;/script&gt;

        &lt;!-- Preserving properties for IDL attributes --&gt;
        &lt;script&gt;
          Window.prototype.def = 2;         // Places a property on the prototype.
          window.hasOwnProperty("length");  // Evaluates to true.
          length;                           // Evaluates to 1.
          def;                              // Evaluates to 2.
        &lt;/script&gt;
        &lt;script&gt;
          var length;                       // Variable declaration leaves existing property.
          length;                           // Evaluates to 1.
          var def;                          // Variable declaration creates shadowing property.
          def;                              // Evaluates to undefined.
        &lt;/script&gt;
    </pre>
</div>


<h4 id="NewObject" extended-attribute lt="NewObject">[NewObject]</h4>

If the [{{NewObject}}]
[=extended attribute=]
appears on a [=regular operation|regular=]
or [=static operations|static=]
[=operation=],
then it indicates that when calling the operation,
a reference to a newly created object
must always be returned.

The [{{NewObject}}]
extended attribute must
[=takes no arguments|take no arguments=].

The [{{NewObject}}]
extended attribute must not
be used on anything other than a [=regular operation|regular=]
or [=static operations|static=]
[=operation=]
whose [=return type=]
is an [=interface type=] or
a [=promise type=].

<div class="example" id="example-5b56e2ba">

    As an example, this extended attribute is suitable for use on
    the {{Document/createElement()}} operation on the {{Document}} interface,
    since a new object is always returned when
    it is called. [[DOM]]

    <pre highlight="webidl">
        [Exposed=Window]
        interface Document : Node {
          [NewObject] Element createElement(DOMString localName);
          // ...
        };
    </pre>
</div>


<h4 id="PutForwards" extended-attribute lt="PutForwards">[PutForwards]</h4>

If the [{{PutForwards}}]
[=extended attribute=]
appears on a [=read only=]
[=regular attribute=] declaration whose type is
an [=interface type=],
it indicates that assigning to the attribute will have specific behavior.
Namely, the assignment is “forwarded” to the attribute (specified by
the extended attribute argument) on the object that is currently
referenced by the attribute being assigned to.

The [{{PutForwards}}] extended
attribute must [=takes an identifier|take an identifier=].
Assuming that:

*   |A| is the [=attribute=]
    on which the [{{PutForwards}}]
    extended attribute appears,
*   |I| is the [=interface=]
    on which |A| is declared,
*   |J| is the [=interface type=]
    that |A| is declared to be of, and
*   |N| is the [=identifier=]
    argument of the extended attribute,

then there must be another
[=attribute=] |B|
declared on |J| whose [=identifier=]
is |N|.  Assignment of a value to the attribute |A|
on an object implementing |I| will result in that value
being assigned to attribute |B| of the object that |A|
references, instead.

Note that [{{PutForwards}}]-annotated
[=attributes=] can be
chained.  That is, an attribute with the [{{PutForwards}}]
[=extended attribute=]
can refer to an attribute that itself has that extended attribute.
There must not exist a cycle in a
chain of forwarded assignments.  A cycle exists if, when following
the chain of forwarded assignments, a particular attribute on
an [=interface=] is
encountered more than once.

An attribute with the [{{PutForwards}}]
extended attribute must not also be declared
with the [{{LegacyLenientSetter}}] or
[{{Replaceable}}] extended attributes.

The [{{PutForwards}}]
extended attribute must not be used
on an [=attribute=] that
is not [=read only=].

The [{{PutForwards}}] extended attribute
must not be used on a
[=static attribute=].

The [{{PutForwards}}] extended attribute
must not be used on an attribute declared on
a [=namespace=].

See the <a href="#js-attributes">Attributes</a> section for how
[{{PutForwards}}]
is to be implemented.

<div class="example" id="example-dc4da779">

    The following [=IDL fragment=] defines interfaces for names and people.
    The [{{PutForwards}}] extended
    attribute is used on the <code class="idl">name</code> attribute
    of the <code class="idl">Person</code> interface to indicate
    that assignments to that attribute result in assignments to the
    <code class="idl">full</code> attribute of the
    <code class="idl">Person</code> object:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Name {
          attribute DOMString full;
          attribute DOMString family;
          attribute DOMString given;
        };

        [Exposed=Window]
        interface Person {
          [PutForwards=full] readonly attribute Name name;
          attribute unsigned short age;
        };
    </pre>

    In the JavaScript binding, this would allow assignments to the
    <code class="idl">name</code> property:

    <pre highlight="js">
        var p = getPerson();           // Obtain an instance of Person.

        p.name = 'John Citizen';       // This statement...
        p.name.full = 'John Citizen';  // ...has the same behavior as this one.
    </pre>
</div>


<h4 id="Replaceable" extended-attribute lt="Replaceable">[Replaceable]</h4>

If the [{{Replaceable}}]
[=extended attribute=]
appears on a [=read only=]
[=regular attribute=],
it indicates that setting the corresponding property on the
[=platform object=] will result in
an own property with the same name being created on the object
which has the value being assigned.  This property will shadow
the accessor property corresponding to the attribute, which
exists on the [=interface prototype object=].

The [{{Replaceable}}]
extended attribute must
[=takes no arguments|take no arguments=].

An attribute with the [{{Replaceable}}]
extended attribute must not also be declared
with the [{{LegacyLenientSetter}}] or
[{{PutForwards}}] extended attributes.

The [{{Replaceable}}]
extended attribute must not be used
on an [=attribute=] that
is not [=read only=].

The [{{Replaceable}}] extended attribute
must not be used on a
[=static attribute=].

The [{{Replaceable}}] extended attribute
must not be used on an attribute declared on
a [=namespace=].

See [[#js-attributes]]
for the specific requirements that the use of
[{{Replaceable}}] entails.

<div class="example" id="example-fe2bdbf4">

    The following [=IDL fragment=]
    defines an [=interface=]
    with an [=operation=]
    that increments a counter, and an [=attribute=]
    that exposes the counter's value, which is initially 0:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Counter {
          [Replaceable] readonly attribute unsigned long value;
          undefined increment();
        };
    </pre>

    Assigning to the <code class="idl">value</code> property
    on a [=platform object=] implementing <code class="idl">Counter</code>
    will shadow the property that corresponds to the
    [=attribute=]:

    <pre highlight="js">
        var counter = getCounter();                              // Obtain an instance of Counter.
        counter.value;                                           // Evaluates to 0.

        counter.hasOwnProperty("value");                         // Evaluates to false.
        Object.getPrototypeOf(counter).hasOwnProperty("value");  // Evaluates to true.

        counter.increment();
        counter.increment();
        counter.value;                                           // Evaluates to 2.

        counter.value = 'a';                                     // Shadows the property with one that is unrelated
                                                                 // to Counter::value.

        counter.hasOwnProperty("value");                         // Evaluates to true.

        counter.increment();
        counter.value;                                           // Evaluates to 'a'.

        delete counter.value;                                    // Reveals the original property.
        counter.value;                                           // Evaluates to 3.
    </pre>
</div>


<h4 id="SameObject" extended-attribute lt="SameObject">[SameObject]</h4>

If the [{{SameObject}}]
[=extended attribute=]
appears on a [=read only=]
[=attribute=], then it
indicates that when getting the value of the attribute on a given
object, the same value must always
be returned.

The [{{SameObject}}]
extended attribute must
[=takes no arguments|take no arguments=].

The [{{SameObject}}]
extended attribute must not
be used on anything other than a [=read only=]
[=attribute=]
whose type is an [=interface type=]
or {{object}}.

<div class="example" id="example-4032028d">

    As an example, this extended attribute is suitable for use on
    the {{Document/implementation}} attribute on the {{Document}} interface
    since the same object is always returned for a given
    {{Document}} object. [[DOM]]

    <pre highlight="webidl">
        [Exposed=Window]
        interface Document : Node {
          [SameObject] readonly attribute DOMImplementation implementation;
          // ...
        };
    </pre>
</div>


<h4 id="SecureContext" extended-attribute lt="SecureContext">[SecureContext]</h4>

If the [{{SecureContext}}] [=extended attribute=] appears on an
[=interface=],
[=partial interface=],
[=interface mixin=],
[=partial interface mixin=],
[=callback interface=],
[=namespace=],
[=partial namespace=],
[=interface member=],
[=interface mixin member=], or
[=namespace member=],
it indicates that the construct is [=exposed=]
only within a [=secure context=].
The [{{SecureContext}}] extended attribute must not be used
on any other construct.

The [{{SecureContext}}] extended attribute must [=takes no arguments|take no arguments=].

If [{{SecureContext}}] appears on an [=overloaded=] [=operation=],
then it must appear on all overloads.

The [{{SecureContext}}] [=extended attribute=] must not be specified both on

* an [=interface member=] and its [=interface=] or [=partial interface=];
* an [=interface mixin member=] and its [=interface mixin=] or [=partial interface mixin=];
* a [=namespace member=] and its [=namespace=] or [=partial namespace=].

Note: This is because adding the [{{SecureContext}}] [=extended attribute=] on a [=member=] when
its containing definition is also annotated with the [{{SecureContext}}] [=extended attribute=]
does not further restrict the exposure of the [=member=].

An [=interface=] without the [{{SecureContext}}] [=extended attribute=]
must not [=interface/inherit=] from another interface
that does specify [{{SecureContext}}].

[{{SecureContext}}] must not be specified on a construct is that is [=conditionally exposed=] on
[{{CrossOriginIsolated}}]. (Doing so would be redundant, since every environment which is
[=environment settings object/cross-origin isolated capability|cross-origin isolated=] is also a
[=secure context=].)

<div class="example" id="example-9e6148d4">

    The following [=IDL fragment=] defines an interface
    with one [=operation=] that is executable from all
    contexts, and two which are executable only from secure contexts.

    <pre highlight="webidl">
        [Exposed=Window]
        interface ExampleFeature {
          // This call will succeed in all contexts.
          Promise &lt;Result&gt; calculateNotSoSecretResult();

          // This operation will not be exposed to a non-secure context. In such a context,
          // there will be no "calculateSecretResult" property on ExampleFeature.prototype.
          [SecureContext] Promise&lt;Result&gt; calculateSecretResult();

          // The same applies here: the attribute will not be exposed to a non-secure context,
          // and in a non-secure context there will be no "secretBoolean" property on
          // ExampleFeature.prototype.
          [SecureContext] readonly attribute boolean secretBoolean;
        };

        // HeartbeatSensor will not be exposed in a non-secure context, nor will its members.
        // In such a context, there will be no "HeartbeatSensor" property on Window.
        [Exposed=Window, SecureContext]
        interface HeartbeatSensor {
          Promise&lt;float&gt; getHeartbeatsPerMinute();
        };

        // The interface mixin members defined below will never be exposed in a non-secure context,
        // regardless of whether the interface that includes them is. That is, in a non-secure
        // context, there will be no "snap" property on ExampleFeature.prototype.
        [SecureContext]
        interface mixin Snapshotable {
          Promise&lt;boolean&gt; snap();
        };
        ExampleFeature includes Snapshotable;

        // On the other hand, the following interface mixin members will be exposed to a non-secure
        // context when included by a host interface that doesn't have the [SecureContext] extended
        // attribute. That is, in a non-secure context, there will be a "log" property on
        // ExampleFeature.prototype.
        interface mixin Loggable {
          Promise&lt;boolean&gt; log();
        };
        ExampleFeature includes Loggable;
    </pre>
</div>


<h4 id="Unscopable" extended-attribute lt="Unscopable">[Unscopable]</h4>

If the [{{Unscopable}}]
[=extended attribute=]
appears on a [=regular attribute=]
or [=regular operation=], it
indicates that an object that [=implements=] an interface with the given
interface member will not include its property name in any object
environment record with it as its base object.  The result of this is
that bare identifiers matching the property name will not resolve to
the property in a <code>with</code> statement.  This is achieved by
including the property name on the
[=interface prototype object=]'s
{{%Symbol.unscopables%}} property's value.

The [{{Unscopable}}]
extended attribute must
[=takes no arguments|take no arguments=].

The [{{Unscopable}}]
extended attribute must not appear on
anything other than a [=regular attribute=]
or [=regular operation=].

The [{{Unscopable}}] extended attribute must not be used on an attribute declared on a
[=namespace=].

See [[#interface-prototype-object]]
for the specific requirements that the use of
[{{Unscopable}}] entails.

<div class="note">

    For example, with the following IDL:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Thing {
          undefined f();
          [Unscopable] g();
        };
    </pre>

    the <code class="idl">f</code> property can be referenced with a bare identifier
    in a <code>with</code> statement but the <code class="idl">g</code> property cannot:

    <pre highlight="js">
        var thing = getThing();  // An instance of Thing
        with (thing) {
          f;                     // Evaluates to a Function object.
          g;                     // Throws a ReferenceError.
        }
    </pre>
</div>


<h3 id="js-legacy-extended-attributes" oldids="es-legacy-extended-attributes">Legacy extended attributes</h3>

This section defines a number of [=extended attributes=] whose presence affects the JavaScript
binding. Unlike those in [[#js-extended-attributes]], these exist only so that legacy Web platform
features can be specified. They should not be used in specifications, unless required to specify the
behavior of legacy APIs.

Editors who believe they have a good reason for using these extended attributes are strongly advised
to discuss this by
<a href="https://github.com/whatwg/webidl/issues/new?title=Intent%20to%20use%20a%20legacy%20extended%20attribute">filing an issue</a>
before proceeding.


<h4 id="LegacyFactoryFunction" extended-attribute lt="LegacyFactoryFunction" oldids="NamedConstructor">[LegacyFactoryFunction]</h4>

<p class="warning">Instead of using this feature, give your interface a [=constructor operation=].</p>

If the [{{LegacyFactoryFunction}}]
[=extended attribute=]
appears on an [=interface=],
it indicates that the JavaScript global object will have a property with the
specified name whose value is a function that can
create objects that implement the interface.
Multiple [{{LegacyFactoryFunction}}] extended
attributes may appear on a given interface.

The [{{LegacyFactoryFunction}}] extended attribute must
[=takes a named argument list|take a named argument list=].
The <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> that occurs directly after the
“<emu-t>=</emu-t>” is the [{{LegacyFactoryFunction}}]'s <dfn lt="LegacyFactoryFunction identifier">identifier</dfn>.
For each [{{LegacyFactoryFunction}}] extended attribute on the interface,
there will be a way to construct an object that
[=implements=] the interface by passing the specified arguments to the [=constructor=]
that is the value of the aforementioned property.

The [=LegacyFactoryFunction identifier|identifier=] used for the legacy factory function must not
be the same as that used by a [{{LegacyFactoryFunction}}]
extended attribute on another interface, must not
be the same as an [=LegacyWindowAlias identifier|identifier=] used by a [{{LegacyWindowAlias}}]
extended attribute on this interface or another interface,
must not be the same as an [=identifier=] of an interface
that has an [=interface object=],
and must not be one of the
[=reserved identifiers=].

The [{{LegacyFactoryFunction}}] and [{{Global}}] [=extended attributes=] must not be specified on the
same [=interface=].

See [[#legacy-factory-functions]] for details on how legacy factory functions
are to be implemented.

<div class="example" id="example-c9fe335f">

    The following IDL defines an interface that uses the
    [{{LegacyFactoryFunction}}] extended
    attribute.

    <pre highlight="webidl">
        [Exposed=Window,
         LegacyFactoryFunction=Audio(DOMString src)]
        interface HTMLAudioElement : HTMLMediaElement {
          // ...
        };
    </pre>

    A JavaScript implementation that supports this interface will
    allow the construction of <code class="idl">HTMLAudioElement</code>
    objects using the <code class="idl">Audio</code> function.

    <pre highlight="js">
        typeof Audio;                   // Evaluates to 'function'.

        var a2 = new Audio('a.flac');   // Creates an HTMLAudioElement using the
                                        // one-argument constructor.
    </pre>

    As an additional legacy quirk, these factory functions will have a <code>prototype</code>
    property equal to the <code>prototype</code> of the original interface:

    <pre highlight="js">
        console.assert(Audio.prototype === HTMLAudioElement.prototype);
    </pre>
</div>


<h4 id="LegacyLenientSetter" extended-attribute lt="LegacyLenientSetter" oldids="LenientSetter">[LegacyLenientSetter]</h4>

If the [{{LegacyLenientSetter}}]
[=extended attribute=]
appears on a [=read only=]
[=regular attribute=],
it indicates that a no-op setter will be generated for the attribute's
accessor property.  This results in erroneous assignments to the property
in strict mode to be ignored rather than causing an exception to be thrown.

<p class="note">Pages have been observed where authors have attempted to polyfill an IDL attribute
by assigning to the property, but have accidentally done so even if the property exists. In strict
mode, this would cause an exception to be thrown, potentially breaking page. Without
[{{LegacyLenientSetter}}], this could prevent a browser from shipping the feature.</p>

The [{{LegacyLenientSetter}}] extended attribute
must [=takes no arguments|take no arguments=].
It must not be used on anything other than
a [=read only=] [=regular attribute=].

An attribute with the [{{LegacyLenientSetter}}]
extended attribute must not also be declared
with the [{{PutForwards}}]
or [{{Replaceable}}] extended attributes.

The [{{LegacyLenientSetter}}] extended attribute must not be used on an attribute declared on a
[=namespace=].

See the <a href="#js-attributes">Attributes</a> section for how
[{{LegacyLenientSetter}}] is to be implemented.

<div class="example" id="example-15547457">

    The following IDL fragment defines an interface that uses the
    [{{LegacyLenientSetter}}] extended
    attribute.

    <pre highlight="webidl">
        [Exposed=Window]
        interface Example {
          [LegacyLenientSetter] readonly attribute DOMString x;
          readonly attribute DOMString y;
        };
    </pre>

    A JavaScript implementation that supports this interface will
    have a setter on the accessor property that correspond to x,
    which allows any assignment to be ignored in strict mode.

    <pre highlight="js">
        "use strict";

        var example = getExample();  // Get an instance of Example.

        // Fine; while we are in strict mode, there is a setter that is a no-op.
        example.x = 1;

        // Throws a TypeError, since we are in strict mode and there is no setter.
        example.y = 1;
    </pre>
</div>


<h4 id="LegacyLenientThis" extended-attribute lt="LegacyLenientThis" oldids="LenientThis">[LegacyLenientThis]</h4>

If the [{{LegacyLenientThis}}]
[=extended attribute=]
appears on a [=regular attribute=],
it indicates that invocations of the attribute's getter or setter
with a <emu-val>this</emu-val> value that is not an
object that [=implements=] the [=interface=]
on which the attribute appears will be ignored.

The [{{LegacyLenientThis}}] extended attribute
must
[=takes no arguments|take no arguments=].
It must not be used on a
[=static attribute=].

The [{{LegacyLenientThis}}] extended attribute must not be used on an attribute declared on a
[=namespace=].

See the <a href="#js-attributes">Attributes</a> section for how
[{{LegacyLenientThis}}]
is to be implemented.

<div class="example" id="example-b5f368f2">

    The following IDL fragment defines an interface that uses the
    [{{LegacyLenientThis}}] extended
    attribute.

    <pre highlight="webidl">
        [Exposed=Window]
        interface Example {
          [LegacyLenientThis] attribute DOMString x;
          attribute DOMString y;
        };
    </pre>

    A JavaScript implementation that supports this interface will
    allow the getter and setter of the accessor property that corresponds
    to x to be invoked with something other than an <code class="idl">Example</code>
    object.

    <pre highlight="js">
        var example = getExample();  // Get an instance of Example.
        var obj = { };

        // Fine.
        example.x;

        // Ignored, since the this value is not an Example object and [LegacyLenientThis] is used.
        Object.getOwnPropertyDescriptor(Example.prototype, "x").get.call(obj);

        // Also ignored, since Example.prototype is not an Example object and [LegacyLenientThis] is used.
        Example.prototype.x;

        // Throws a TypeError, since Example.prototype is not an Example object.
        Example.prototype.y;
    </pre>
</div>


<h4 id="LegacyNamespace" extended-attribute lt="LegacyNamespace">[LegacyNamespace]</h4>

<p class="warning">Instead of using this feature, interface names can be formed with a naming
convention of starting with a particular prefix for a set of interfaces, as part of the identifier,
without the intervening dot.</p>

If the [{{LegacyNamespace}}] [=extended attribute=] appears on an [=interface=], it indicates that
the [=interface object=] for this interface will not be created as a property of the global
object, but rather as a property of the [=namespace=] identified by the argument to the extended
attribute.

The [{{LegacyNamespace}}] extended attribute must [=take an identifier=].
This identifier must be the [=identifier=] of a [=namespace=] definition.

The [{{LegacyNamespace}}] and [{{LegacyNoInterfaceObject}}]
extended attributes must not be specified on the same interface.

See [[#namespace-object]] for details on how an interface is exposed on a namespace.

<div class="example" id="example-194971b0">
    The following [=IDL fragment=] defines a [=namespace=] and an [=interface=] which
    uses [{{LegacyNamespace}}] to be defined inside of it.

    <pre highlight="webidl">
        namespace Foo { };

        [LegacyNamespace=Foo]
        interface Bar {
          constructor();
        };
    </pre>

    In a JavaScript implementation of the above namespace and interface, the
    constructor Bar can be accessed as follows:

    <pre highlight="js">
        var instance = new Foo.Bar();
    </pre>
</div>


<h4 id="LegacyNoInterfaceObject" extended-attribute lt="LegacyNoInterfaceObject" oldids="NoInterfaceObject">[LegacyNoInterfaceObject]</h4>

If the [{{LegacyNoInterfaceObject}}] [=extended attribute=] appears on an [=interface=],
it indicates that an [=interface object=]
will not exist for the interface in the JavaScript binding.

The [{{LegacyNoInterfaceObject}}] extended attribute
must [=takes no arguments|take no arguments=].

The [{{LegacyNoInterfaceObject}}] extended attribute
must not be specified on an interface that has any
[=constructors=] or [=static operations=] defined on it.

An interface that does not have the [{{LegacyNoInterfaceObject}}] extended
attribute specified must not inherit
from an interface that has the [{{LegacyNoInterfaceObject}}] extended
attribute specified.

See [[#js-interfaces]]
for the specific requirements that the use of
[{{LegacyNoInterfaceObject}}] entails.

<div class="example" id="example-ecf33c5c">

    The following [=IDL fragment=] defines two interfaces, one whose interface object
    is exposed on the JavaScript global object, and one whose isn't:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Storage {
          undefined addEntry(unsigned long key, any value);
        };

        [Exposed=Window,
         LegacyNoInterfaceObject]
        interface Query {
          any lookupEntry(unsigned long key);
        };
    </pre>

    A JavaScript implementation of the above IDL would allow
    manipulation of <code class="idl">Storage</code>'s
    prototype, but not <code class="idl">Query</code>'s.

    <pre highlight="js">
        typeof Storage;                        // evaluates to "object"

        // Add some tracing alert() call to Storage.addEntry.
        var fn = Storage.prototype.addEntry;
        Storage.prototype.addEntry = function(key, value) {
          alert('Calling addEntry()');
          return fn.call(this, key, value);
        };

        typeof Query;                          // evaluates to "undefined"
        var fn = Query.prototype.lookupEntry;  // exception, Query isn't defined
    </pre>
</div>


<h4 id="LegacyNullToEmptyString" extended-attribute lt="LegacyNullToEmptyString" oldids="TreatNullAs">[LegacyNullToEmptyString]</h4>

If the [{{LegacyNullToEmptyString}}] [=extended attribute=] appears on the {{DOMString}} or {{USVString}} type,
it creates a new IDL type such that that when a JavaScript <emu-val>null</emu-val> is converted to the IDL type,
it will be handled differently from its default handling. Instead of being stringified to
"<code>null</code>", which is the default, it will be converted to the empty string.

The [{{LegacyNullToEmptyString}}] extended attribute must not be
[=extended attribute associated with|associated with=] a type that is not {{DOMString}} or {{USVString}}.

Note: This means that even <code class="idl">DOMString?</code> must not use [{{LegacyNullToEmptyString}}], since
<emu-val>null</emu-val> is a valid value of that type.

See [[#js-DOMString]] for the specific requirements that the use of [{{LegacyNullToEmptyString}}] entails.

<div class="example" id="example-485c9e14">
    The following [=IDL fragment=] defines an interface that has one attribute whose type has the
    extended attribute, and one operation whose argument's type has the extended attribute:

    <pre highlight="webidl">
        [Exposed=Window]
        interface Dog {
          attribute DOMString name;
          attribute [LegacyNullToEmptyString] DOMString owner;

          boolean isMemberOfBreed([LegacyNullToEmptyString] DOMString breedName);
        };
    </pre>

    A JavaScript implementation implementing the <code class="idl">Dog</code>
    interface would convert a <emu-val>null</emu-val> value
    assigned to the <code>owner</code> property or passed as the
    argument to the <code>isMemberOfBreed</code> function
    to the empty string rather than "<code>null</code>":

    <pre highlight="js">
        var d = getDog();         // Assume d is a platform object implementing the Dog
                                  // interface.

        d.name = null;            // This assigns the string "null" to the .name
                                  // property.

        d.owner = null;           // This assigns the string "" to the .owner property.

        d.isMemberOfBreed(null);  // This passes the string "" to the isMemberOfBreed
                                  // function.
    </pre>
</div>


<h4 id="LegacyOverrideBuiltIns" extended-attribute lt="LegacyOverrideBuiltIns" oldids="OverrideBuiltins">[LegacyOverrideBuiltIns]</h4>

If the [{{LegacyOverrideBuiltIns}}]
[=extended attribute=]
appears on an [=interface=],
it indicates that for a [=legacy platform object=] implementing the interface,
properties corresponding to all of
the object's [=supported property names=]
will appear to be on the object,
regardless of what other properties exist on the object or its
prototype chain.  This means that named properties will always shadow
any properties that would otherwise appear on the object.
This is in contrast to the usual behavior, which is for named properties
to be exposed only if there is no property with the
same name on the object itself or somewhere on its prototype chain.

The [{{LegacyOverrideBuiltIns}}]
extended attribute must
[=takes no arguments|take no arguments=]
and must not appear on an interface
that does not define a [=named property getter=]
or that also is declared with the [{{Global}}] [=extended attribute=].
If the extended attribute is specified on
a [=partial interface=]
definition, then that partial interface definition must
be the part of the interface definition that defines
the [=named property getter=].

If the [{{LegacyOverrideBuiltIns}}] extended attribute is specified on a
[=partial interface=] definition, it is considered to appear on the
[=interface=] itself.

See [[#js-legacy-platform-objects]]
and [[#legacy-platform-object-defineownproperty]]
for the specific requirements that the use of
[{{LegacyOverrideBuiltIns}}] entails.

<div class="example" id="example-b703da70">

    The following [=IDL fragment=]
    defines two [=interfaces=],
    one that has a [=named property getter=]
    and one that does not.

    <pre highlight="webidl">
        [Exposed=Window]
        interface StringMap {
          readonly attribute unsigned long length;
          getter DOMString lookup(DOMString key);
        };

        [Exposed=Window,
         LegacyOverrideBuiltIns]
        interface StringMap2 {
          readonly attribute unsigned long length;
          getter DOMString lookup(DOMString key);
        };
    </pre>

    In a JavaScript implementation of these two interfaces,
    getting certain properties on objects implementing
    the interfaces will result in different values:

    <pre highlight="js">
        // Obtain an instance of StringMap.  Assume that it has "abc", "length" and
        // "toString" as supported property names.
        var map1 = getStringMap();

        // This invokes the named property getter.
        map1.abc;

        // This fetches the "length" property on the object that corresponds to the
        // length attribute.
        map1.length;

        // This fetches the "toString" property from the object's prototype chain.
        map1.toString;

        // Obtain an instance of StringMap2.  Assume that it also has "abc", "length"
        // and "toString" as supported property names.
        var map2 = getStringMap2();

        // This invokes the named property getter.
        map2.abc;

        // This also invokes the named property getter, despite the fact that the "length"
        // property on the object corresponds to the length attribute.
        map2.length;

        // This too invokes the named property getter, despite the fact that "toString" is
        // a property in map2's prototype chain.
        map2.toString;
    </pre>
</div>


<h4 id="LegacyTreatNonObjectAsNull" extended-attribute lt="LegacyTreatNonObjectAsNull" oldids="TreatNonObjectAsNull">[LegacyTreatNonObjectAsNull]</h4>

If the [{{LegacyTreatNonObjectAsNull}}] [=extended attribute=] appears on a [=callback function=], then
it indicates that any value assigned to an [=attribute=] whose type is a [=nullable type|nullable=]
[=callback function=] will be converted more loosely: if the value is not an object, it will be
converted to null, and if the value is not [=ECMAScript/callable=], it will be converted to a
[=callback function=] value that does nothing when called.

See [[#js-nullable-type]], [[#js-callback-function]] and [[#js-invoking-callback-functions]]
for the specific requirements that the use of
[{{LegacyTreatNonObjectAsNull}}] entails.

<div class="example" id="example-abade5af">

    The following [=IDL fragment=] defines an interface that has one
    attribute whose type is a [{{LegacyTreatNonObjectAsNull}}]-annotated
    [=callback function=] and another whose type is a
    [=callback function=] without the [=extended attribute=]:

    <pre highlight="webidl">
        callback OccurrenceHandler = undefined (DOMString details);

        [LegacyTreatNonObjectAsNull]
        callback ErrorHandler = undefined (DOMString details);

        [Exposed=Window]
        interface Manager {
          attribute OccurrenceHandler? handler1;
          attribute ErrorHandler? handler2;
        };
    </pre>

    In a JavaScript implementation, assigning a value that is not
    an object (such as a Number value), or that is not [=ECMAScript/callable=]
    to handler1 will have different behavior from that when assigning
    to handler2:

    <pre highlight="js">
        var manager = getManager();  // Get an instance of Manager.

        manager.handler1 = function() { };
        manager.handler1;            // Evaluates to the function.

        try {
          manager.handler1 = 123;    // Throws a TypeError.
        } catch (e) {
        }

        try {
          manager.handler1 = {};     // Throws a TypeError.
        } catch (e) {
        }

        manager.handler2 = function() { };
        manager.handler2;            // Evaluates to the function.

        manager.handler2 = 123;
        manager.handler2;            // Evaluates to null.

        manager.handler2 = {};
        manager.handler2;            // Evaluates to the object.
    </pre>
</div>


<h4 id="LegacyUnenumerableNamedProperties" extended-attribute lt="LegacyUnenumerableNamedProperties">[LegacyUnenumerableNamedProperties]</h4>

If the [{{LegacyUnenumerableNamedProperties}}]
[=extended attribute=]
appears on a [=interface=]
that [=support named properties|supports named properties=],
it indicates that all the interface's named properties are unenumerable.

The [{{LegacyUnenumerableNamedProperties}}]
extended attribute must
[=takes no arguments|take no arguments=]
and must not appear on an interface
that does not define a [=named property getter=].

If the [{{LegacyUnenumerableNamedProperties}}]
extended attribute is specified on an interface, then it applies to all its derived interfaces and
must not be specified on any of them.

See [[#legacy-platform-object-getownproperty]]
for the specific requirements that the use of
[{{LegacyUnenumerableNamedProperties}}]
entails.


<h4 id="LegacyUnforgeable" extended-attribute lt="LegacyUnforgeable" oldids="Unforgeable">[LegacyUnforgeable]</h4>

If the [{{LegacyUnforgeable}}] [=extended attribute=] appears on
[=regular attributes=] or non-[=static operations|static=] [=operations=],
it indicates that the attribute or operation
will be reflected as a JavaScript property
in a way that means its behavior cannot be modified
and that performing a property lookup on the object
will always result in the attribute's property value being returned.
In particular, the property will be non-configurable
and will exist as an own property on the object itself
rather than on its prototype.

An attribute or operation is said to be
<dfn id="dfn-unforgeable-on-an-interface" export>unforgeable</dfn> on a given interface |A|
if the attribute or operation is declared on |A|,
and is annotated with the [{{LegacyUnforgeable}}] [=extended attribute=].

The [{{LegacyUnforgeable}}] extended attribute must [=takes no arguments|take no arguments=].

The [{{LegacyUnforgeable}}] [=extended attribute=] must not appear
on anything other than a [=regular attribute=]
or a non-[=static operations|static=] [=operation=].
If it does appear on an [=operation=],
then it must appear on all operations
with the same [=identifier=] on that interface.

The [{{LegacyUnforgeable}}] extended attribute must not be used
on an attribute declared on a [=namespace=].

If an attribute or operation |X| is [=unforgeable=] on an interface |A|,
and |A| is one of the [=inherited interfaces=] of another interface |B|,
then |B| must not have a [=regular attribute=]
or non-[=static operations|static=] [=operation=]
with the same [=identifier=] as |X|.

<div class="note">

    For example, the following is disallowed:

    <pre highlight="webidl">
        [Exposed=Window]
        interface A1 {
          [LegacyUnforgeable] readonly attribute DOMString x;
        };
        [Exposed=Window]
        interface B1 : A1 {
          undefined x();  // Invalid; would be shadowed by A1's x.
        };

        [Exposed=Window]
        interface B2 : A1 { };
        B2 includes M1;
        interface mixin M1 {
          undefined x();  // Invalid; B2's copy of x would be shadowed by A1's x.
        };
    </pre>
</div>

See [[#js-attributes]],
[[#js-operations]],
[[#js-platform-objects]],
[[#js-legacy-platform-objects]] and
[[#legacy-platform-object-defineownproperty]]
for the specific requirements that the use of
[{{LegacyUnforgeable}}] entails.

<div class="example" id="example-526d5162">

    The following [=IDL fragment=] defines
    an interface that has two [=attributes=],
    one of which is designated as [{{LegacyUnforgeable}}]:

    <pre highlight="webidl">
        [Exposed=Window]
        interface System {
          [LegacyUnforgeable] readonly attribute DOMString username;
          readonly attribute long long loginTime;
        };
    </pre>

    In a JavaScript implementation of the interface, the username attribute will be exposed as a non-configurable property on the
    object itself:

    <pre highlight="js">
        var system = getSystem();                      // Get an instance of System.

        system.hasOwnProperty("username");             // Evaluates to true.
        system.hasOwnProperty("loginTime");            // Evaluates to false.
        System.prototype.hasOwnProperty("username");   // Evaluates to false.
        System.prototype.hasOwnProperty("loginTime");  // Evaluates to true.

        try {
          // This call would fail, since the property is non-configurable.
          Object.defineProperty(system, "username", { value: "administrator" });
        } catch (e) { }

        // This defineProperty call would succeed, because System.prototype.loginTime
        // is configurable.
        var forgedLoginTime = 5;
        Object.defineProperty(System.prototype, "loginTime", { value: forgedLoginTime });

        system.loginTime;  // So this now evaluates to forgedLoginTime.
    </pre>
</div>


<h4 id="LegacyWindowAlias" extended-attribute lt="LegacyWindowAlias">[LegacyWindowAlias]</h4>

If the [{{LegacyWindowAlias}}] [=extended attribute=] appears on an [=interface=],
it indicates that the {{Window}} [=interface=] will have a property
for each [=identifier=] mentioned in the extended attribute,
whose value is the [=interface object=] for the interface.

The [{{LegacyWindowAlias}}] extended attribute must either
[=takes an identifier|take an identifier=] or
[=takes an identifier list|take an identifier list=].
The <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t>s that occur after the
“<emu-t>=</emu-t>” are the [{{LegacyWindowAlias}}]'s <dfn lt="LegacyWindowAlias identifier">identifiers</dfn>.

Each of the [=LegacyWindowAlias identifier|identifiers=] of [{{LegacyWindowAlias}}]
must not be the same as one used by a [{{LegacyWindowAlias}}]
extended attribute on this interface or another interface,
must not be the same as the [=LegacyFactoryFunction identifier|identifier=] used by a [{{LegacyFactoryFunction}}]
extended attribute on this interface or another interface,
must not be the same as an [=identifier=] of an interface that has an [=interface object=],
and must not be one of the [=reserved identifiers=].

The [{{LegacyWindowAlias}}] and [{{LegacyNoInterfaceObject}}]
extended attributes must not be specified on the same interface.

The [{{LegacyWindowAlias}}] and [{{LegacyNamespace}}]
extended attributes must not be specified on the same interface.

The [{{LegacyWindowAlias}}] extended attribute must not be specified
on an interface that does not include the {{Window}} [=interface=]
in its [=exposure set=].

An interface must not have more than one [{{LegacyWindowAlias}}] extended attributes specified.

See [[#js-interfaces]] for details on how legacy window aliases
are to be implemented.

<div class="example" id="example-758340c7">

    The following IDL defines an interface that uses the
    [{{LegacyWindowAlias}}] extended attribute.

    <pre highlight="webidl">
        [Exposed=Window,
         LegacyWindowAlias=WebKitCSSMatrix]
        interface DOMMatrix : DOMMatrixReadOnly {
          // ...
        };
    </pre>

    A JavaScript implementation that supports this interface will
    expose two properties on the {{Window}} object with the same value
    and the same characteristics;
    one for exposing the [=interface object=] normally,
    and one for exposing it with a legacy name.

    <pre highlight="js">
        WebKitCSSMatrix === DOMMatrix;     // Evaluates to true.

        var m = new WebKitCSSMatrix();     // Creates a new object that
                                           // implements DOMMatrix.

        m.constructor === DOMMatrix;       // Evaluates to true.
        m.constructor === WebKitCSSMatrix; // Evaluates to true.
        {}.toString.call(m);               // Evaluates to '[object DOMMatrix]'.
    </pre>
</div>


<h3 id="js-security" oldids="es-security">Security</h3>

Certain algorithms in the sections below are defined to
<dfn id="dfn-perform-a-security-check" export>perform a security check</dfn> on a given
object.  This check is used to determine whether a given
[=operation=] invocation or
[=attribute=] access should be
allowed.  The security check takes the following three inputs:

1.  the [=platform object=] on
    which the operation invocation or attribute access is being done,
1.  the [=identifier=]
    of the operation or attribute, and
1.  the type of the [=function object=] –
    "<code>method</code>" (when it corresponds to an IDL operation), or
    "<code>getter</code>" or "<code>setter</code>" (when it corresponds to the
    getter or setter function of an IDL attribute).

Note: The HTML Standard defines how a security check is performed. [[!HTML]]


<h3 id="js-overloads" oldids="es-overloads">Overload resolution algorithm</h3>

<div algorithm>

    In order to define how function invocations are resolved, the
    <dfn id="dfn-overload-resolution-algorithm" export>overload resolution algorithm</dfn>
    is defined.  Its input is an [=effective overload set=],
    |S|, and a list of JavaScript values, |args|.
    Its output is a pair consisting of the [=operation=] or
    [=extended attribute=] of one of |S|'s entries
    and a list of IDL values or the special value “missing”.  The algorithm behaves as follows:

    1.  Let |maxarg| be the length of the longest type list of the entries in |S|.
    1.  Let |n| be the [=list/size=] of |args|.
    1.  Initialize |argcount| to be min(|maxarg|, |n|).
    1.  Remove from |S| all entries whose type list is not of length |argcount|.
    1.  If |S| is empty, then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Initialize |d| to −1.
    1.  Initialize |method| to <emu-val>undefined</emu-val>.
    1.  If there is more than one entry in |S|, then set
        |d| to be the [=distinguishing argument index=]
        for the entries of |S|.
    1.  Initialize |values| to be an empty list, where each entry will be either an IDL value or the special value “missing”.
    1.  Initialize |i| to 0.
    1.  While |i| &lt; |d|:
        1.  Let |V| be |args|[|i|].
        1.  Let |type| be the type at index |i| in the type list of any entry in |S|.

            Note: All entries in |S| at this point have the same type and [=optionality value=] at index |i|.

        1.  Let |optionality| be the value at index |i| in the list of [=optionality values=] of any entry in |S|.
        1.  If |optionality| is “optional” and |V| is <emu-val>undefined</emu-val>, then:
            1.  If the argument at index |i| is declared with a [=optional argument/default value=],
                then append to |values| that default value.
            1.  Otherwise, append to |values| the special value “missing”.
        1.  Otherwise, append to |values| the result of [=converted to an IDL value|converting=]
            |V| to IDL type |type|.
        1.  Set |i| to |i| + 1.
    1.  If |i| = |d|, then:
        1.  Let |V| be |args|[|i|].

            Note: This is the argument that will be used to resolve which overload is selected.

        1.  If |V| is <emu-val>undefined</emu-val>, and there is an entry in |S|
            whose list of [=optionality values=] has “optional” at index |i|,
            then remove from |S| all other entries.

        1.  Otherwise: if |V| is <emu-val>null</emu-val> or <emu-val>undefined</emu-val>,
            and there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   a [=nullable type=]
            *   a [=dictionary type=]
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=] or [=annotated type|annotated=] union type that [=includes a nullable type=] or that
                has a [=dictionary type=] in its [=flattened member types|flattened members=]

            then remove from |S| all other entries.

        1.  Otherwise: if |V| [=is a platform object=], and
            there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   an [=interface type=] that |V| [=implements=]
            *   {{object}}
            *   a [=nullable type|nullable=] version of any of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if |V| [=is an Object=], |V| has an \[[ArrayBufferData]] [=/internal slot=], and
            there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   {{ArrayBuffer}}
            *   {{SharedArrayBuffer}}
            *   {{object}}
            *   a [=nullable type|nullable=] version of either of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if |V| [=is an Object=], |V| has a \[[DataView]] [=/internal slot=], and
            there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   {{DataView}}
            *   {{object}}
            *   a [=nullable type|nullable=] version of either of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if |V| [=is an Object=], |V| has a \[[TypedArrayName]] [=/internal slot=], and
            there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   a [=typed array type=] whose name
                is equal to the value of |V|'s \[[TypedArrayName]] [=/internal slot=]
            *   {{object}}
            *   a [=nullable type|nullable=] version of either of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if <a abstract-op>IsCallable</a>(|V|) is true,
            and there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   a [=callback function=] type
            *   {{object}}
            *   a [=nullable type|nullable=] version of any of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if |V| [=is an Object=] and
            there is an entry in |S| that has one of the
            following types at position |i| of its type list,
            *   an [=async iterable type=]
            *   a [=nullable type|nullable=] version of any of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            and the following are not all true,
            *   |V| has a \[[StringData]] [=/internal slot=]
            *   |S| has one of the following types at position |i| of its type list,
                *   a [=string type=]
                *   a [=nullable type|nullable=] version of a [=string type=]
                *   an [=annotated type=] whose [=annotated types/inner type=] is a [=string type=]
                *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                    that has one of the above types in its [=flattened member types=]

            and after performing the following steps,

            1.  Let |method| be [=?=] <a abstract-op>GetMethod</a>(|V|, {{%Symbol.asyncIterator%}}).
            1.  If |method| is <emu-val>undefined</emu-val>, then set |method| to [=?=] <a abstract-op>GetMethod</a>(|V|, {{%Symbol.iterator%}}).

            |method| is not <emu-val>undefined</emu-val>, then remove from |S| all
            other entries.

        1.  Otherwise: if |V| [=is an Object=] and
            there is an entry in |S| that has one of the
            following types at position |i| of its type list,
            *   a [=sequence type=]
            *   a [=nullable type|nullable=] version of any of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            and after performing the following steps,

            1.  Let |method| be [=?=] <a abstract-op>GetMethod</a>(|V|, {{%Symbol.iterator%}}).

            |method| is not <emu-val>undefined</emu-val>, then remove from |S| all
            other entries.

        1.  Otherwise: if |V| [=is an Object=] and
            there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   a [=callback interface type=]
            *   a [=dictionary type=]
            *   a [=record type=]
            *   {{object}}
            *   a [=nullable type|nullable=] version of any of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if |V| [=is a Boolean=]
            and there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   {{boolean}}
            *   a [=nullable type|nullable=] {{boolean}}
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if |V| [=is a Number=]
            and there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   a [=numeric type=]
            *   a [=nullable type|nullable=] [=numeric type=]
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if |V| [=is a BigInt=]
            and there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   {{bigint}}
            *   a [=nullable type|nullable=] {{bigint}}
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   a [=string type=]
            *   a [=nullable type|nullable=] version of any of the above types
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   a [=numeric type=]
            *   a [=nullable type|nullable=] [=numeric type=]
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   {{boolean}}
            *   a [=nullable type|nullable=] {{boolean}}
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if there is an entry in |S| that has one of the following types at position |i| of its type list,
            *   {{bigint}}
            *   a [=nullable type|nullable=] {{bigint}}
            *   an [=annotated type=] whose [=annotated types/inner type=] is one of the above types
            *   a [=union type=], [=nullable type|nullable=] union type, or [=annotated type|annotated=] union type
                that has one of the above types in its [=flattened member types=]

            then remove from |S| all other entries.

        1.  Otherwise: if there is an entry in |S| that has {{any}} at position |i|
            of its type list, then remove from |S| all other entries.
        1.  Otherwise: [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Let |callable| be the [=operation=] or [=extended attribute=]
        of the single entry in |S|.
    1.  If |i| = |d| and |method| is not <emu-val>undefined</emu-val>, then
        1.  Let |V| be |args|[|i|].
        1.  Let |T| be the type at index |i| in the
            type list of the remaining entry in |S|.
        1.  Assert: |T| is a [=sequence type=].
        1.  Append to |values| the result of
            [=creating a sequence from an iterable|creating a sequence=]
            of type |T| from |V| and |method|.
        1.  Set |i| to |i| + 1.
    1.  While |i| &lt; |argcount|:
        1.  Let |V| be |args|[|i|].
        1.  Let |type| be the type at index |i| in the type list of the remaining entry in |S|.
        1.  Let |optionality| be the value at index |i| in the list of [=optionality values=] of the remaining entry in |S|.
        1.  If |optionality| is “optional” and |V| is <emu-val>undefined</emu-val>, then:
            1.  If the argument at index |i| is declared with a [=optional argument/default value=],
                then append to |values| that default value.
            1.  Otherwise, append to |values| the special value “missing”.
        1.  Otherwise, append to |values| the result of
            [=converted to an IDL value|converting=] |V| to IDL type |type|.
        1.  Set |i| to |i| + 1.
    1.  While |i| is less than the number of arguments |callable| is declared to take:
        1.  If |callable|'s argument at index |i| is declared with a [=optional argument/default value=],
            then append to |values| that default value.
        1.  Otherwise, if |callable|'s argument at index |i| is not variadic, then append to |values| the special value “missing”.
        1.  Set |i| to |i| + 1.
    1.  Return the pair &lt;|callable|, |values|&gt;.
</div>

<div class="note">

    The overload resolution algorithm performs both the identification
    of which overloaded operation, constructor, etc. is being called,
    and the conversion of the JavaScript argument values to their
    corresponding IDL values.  Informally, it operates as follows.

    First, the selection of valid overloads is done by considering
    the number of JavaScript arguments that were passed in to the function:

    *   If there are more arguments passed in than the longest
        overload argument list, then they are ignored.
    *   After ignoring these trailing arguments, only overloads
        that can take this exact number of arguments are considered.
        If there are none, then a {{TypeError}} is thrown.

    Once we have a set of possible overloads with the right number
    of arguments, the JavaScript values are converted from left to right.
    The nature of the restrictions on overloading means that if we
    have multiple possible overloads at this point, then there will
    be one position in the argument list that will be used to
    distinguish which overload we will finally select; this is
    the [=distinguishing argument index=].

    We first convert the arguments to the left of the distinguishing
    argument.  (There is a requirement that an argument to the left of
    the distinguishing argument index has the same type as in the other
    overloads, at the same index.) Then we inspect the type of the
    JavaScript value that is passed in at the distinguishing argument
    index to determine which IDL type it can correspond to.
    This allows us to select the final overload that will
    be invoked.  If the value passed in is <emu-val>undefined</emu-val>
    and there is an overload with an <span class=allow-rfc2119>optional</span> argument at this
    position, then
    we will choose that overload.  If there is no valid overload for the type of
    value passed in here, then we throw a {{TypeError}}.
    Generally, the inspection of the value at the distinguishing argument index does not have any
    side effects, and the only side effects in the overload resolution algorithm are the result of
    converting the JavaScript values to IDL values.
    (An exception exists when one of the overloads has an [=async iterable type=], [=sequence type=]
    or [=frozen array type=] at the distinguishing argument index.
    In this case, we attempt to get the {{%Symbol.asyncIterator%}} / {{%Symbol.iterator%}} property
    to determine the appropriate overload, and perform the conversion of the distinguishing argument
    separately before continuing with the next step.)

    At this point, we have determined which overload to use.  We now
    convert the remaining arguments, from the distinguishing argument onwards,
    again ignoring any additional arguments that were ignored due to being passed
    after the last possible argument.

    When converting an <span class=allow-rfc2119>optional</span> argument's JavaScript value to its
    equivalent IDL value,
    <emu-val>undefined</emu-val> will be converted into the
    <a for="optional argument" lt="default value" class=allow-2119>optional argument's default value</a>,
    if it has one, or a special value “missing” otherwise.

    <span class=allow-2119>Optional</span> arguments corresponding to a final, variadic argument do
    not treat <emu-val>undefined</emu-val> as a special “missing” value, however.
    The <emu-val>undefined</emu-val> value is converted to the type
    of variadic argument as would be done for a non-<span class=allow-rfc2119>optional</span>
    argument.

</div>


<h3 id="js-interfaces" oldids="es-interfaces">Interfaces</h3>

For every [=interface=] that is [=exposed=] in
a given [=realm=] and that is not declared with
the [{{LegacyNoInterfaceObject}}] or [{{LegacyNamespace}}] [=extended attributes=],
a corresponding property exists on the [=realm=]'s [=realm/global object=].
The name of the property is the [=identifier=] of the interface,
and its value is an object called the <dfn id="dfn-interface-object" export>interface object</dfn>.
The characteristics of an interface object are described in [[#interface-object]].

If the [{{LegacyWindowAlias}}] extended attribute was specified on an [=exposed=] interface,
then for each [=LegacyWindowAlias identifier|identifier=] in [{{LegacyWindowAlias}}]'s [=LegacyWindowAlias identifier|identifiers=]
there exists a corresponding property on the {{Window}} global object.
The name of the property is the given [=LegacyWindowAlias identifier|identifier=],
and its value is a reference to the [=interface object=] for the [=interface=].

In addition, for every [{{LegacyFactoryFunction}}] extended attribute on an [=exposed=] interface,
a corresponding property exists on the JavaScript global object.
The name of the property is the [{{LegacyFactoryFunction}}]'s [=LegacyFactoryFunction identifier|identifier=],
and its value is an object called a <dfn id="dfn-legacy-factory-function" export oldids="dfn-named-constructor">legacy factory function</dfn>,
which allows creation of objects that implement the interface.
The characteristics of a legacy factory function are described in [[#legacy-factory-functions]].

<div algorithm>
    Some JavaScript methods defined in this section will perform an implementation check in their opening steps,
    to ensure they're being called on the correct kind of object
    and that the method is valid to call from the current context.

    To <dfn local-lt="implementation check|implementation-check">implementation-check an object</dfn> |jsValue|
    against the interface |interface|,
    with the identifier |name|
    and the type |type|:

    1. Let |object| to [=?=] [$ToObject$](|jsValue|).
    1. If |object| is a [=platform object=],
        then [=perform a security check=], passing:

        * the platform object |object|
        * the identifier |name|
        * the type |type|
    1. If |object| does not [=implement=] |interface|, then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1. Return |object|.

    Issue: This algo is not yet consistently used everywhere.
</div>


<h4 id="interface-object" oldids="es-interface-call,es-constructible-interfaces">Interface object</h4>

The [=interface object=] for a given [=interface=] is a [=built-in function object=].
It has properties that correspond to the [=constants=] and [=static operations=]
defined on that interface,
as described in sections [[#js-constants]] and [[#js-operations]].

If the [=interface=] is declared with a [=constructor operation=],
then the [=interface object=] can be called as a [=constructor=]
to create an object that [=implements=] that interface.
Calling that interface as a function will throw an exception.

[=Interface objects=] whose [=interfaces=] are not declared
with a [=constructor operation=] will throw when called,
both as a function and as a [=constructor=].

An [=interface object=] for an [=interface=]
has an associated object called the [=interface prototype object=].
This object has properties that correspond to
the [=regular attributes=] and [=regular operations=] defined on the interface,
and is described in more detail in [[#interface-prototype-object]].

Note: Since an [=interface object=] is a [=function object=]
the <code>typeof</code> operator will return "function" when applied to an interface object.

An interface may have <dfn export>overridden constructor steps</dfn>, which can
change the behavior of the [=interface object=] when called or constructed. By
default interfaces do not have such steps.

<p class="warning">
    In general, constructors are described by defining a [=constructor operation=] and its behavior.
    The [=overridden constructor steps=] are used only for more complicated situations.
    Editors who wish to use this feature are strongly advised to discuss this by
    <a href="https://github.com/whatwg/webidl/issues/new?title=Intent%20to%20use%20constructor%20steps">filing an issue</a> before proceeding.
</p>

<div algorithm>

    The [=interface object=] for a given [=interface=] |I|
    with [=identifier=] |id| and in [=realm=] |realm|
    is <dfn lt="create an interface object">created</dfn> as follows:

    1.  Let |steps| be |I|'s [=overridden constructor steps=] if they exist, or
        the following steps otherwise:
        1.  If |I| was not declared with a [=constructor operation=],
            then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
        1.  If {{NewTarget}} is <emu-val>undefined</emu-val>, then
            [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
        1.  Let |args| be the passed arguments.
        1.  Let |n| be the [=list/size=] of |args|.
        1.  Let |id| be the identifier of interface |I|.
        1.  [=Compute the effective overload set=] for constructors with [=identifier=] |id| on
            [=interface=] |I| and with argument count |n|, and let |S| be the result.
        1.  Let &lt;|constructor|, |values|&gt; be the result
            of passing |S| and |args| to the [=overload resolution algorithm=].
        1.  Let |object| be the result of [=internally create a new object implementing the
            interface|internally creating a new object implementing=] |I|, with |realm| and
            {{NewTarget}}.
        1.  Perform the [=constructor steps=] of |constructor|
            with |object| as [=this=] and |values| as the argument values.
        1.  Let |O| be |object|, [=converted to a JavaScript value=].
        1.  Assert: |O| is an object that [=implements=] |I|.
        1.  Assert: |O|.\[[Realm]] is |realm|.
        1.  Return |O|.
    1.  Let |constructorProto| be |realm|.\[[Intrinsics]].\[[{{%Function.prototype%}}]].
    1.  If |I| inherits from some other interface |P|,
        then set |constructorProto| to the [=interface object=] of |P| in |realm|.
    1.  Let |F| be <a abstract-op>CreateBuiltinFunction</a>(|steps|, « \[[Unforgeables]] »,
        |realm|, |constructorProto|).
    1.  Let |unforgeables| be [$OrdinaryObjectCreate$](<emu-val>null</emu-val>).
    1.  [=Define the unforgeable regular operations=] of |I| on |unforgeables|, given |realm|.
    1.  [=Define the unforgeable regular attributes=] of |I| on |unforgeables|, given |realm|.
    1.  Set |F|.\[[Unforgeables]] to |unforgeables|.

        Note: this object is never exposed to user code. It exists only to ensure all instances
        of an interface with an unforgeable member use the same JavaScript function objects for
        [=attribute getters=], [=attribute setters=] and [=creating an operation
        function|operation functions=].
    1.  Perform <a abstract-op>SetFunctionName</a>(|F|, |id|).
    1.  Let |length| be 0.
    1.  If |I| was declared with a [=constructor operation=], then
        1.  [=Compute the effective overload set=] for constructors with [=identifier=] |id| on
            [=interface=] |I| and with argument count 0, and let |S| be the result.
        1.  Set |length| to the length of the
            shortest argument list of the entries in |S|.
    1.  Perform <a abstract-op>SetFunctionLength</a>(|F|, |length|).
    1.  Let |proto| be the result of [=create an interface prototype object|creating an interface
        prototype object=] of [=interface=] |I| in |realm|.
    1.  Perform [=!=] <a abstract-op>DefinePropertyOrThrow</a>(|F|, "<code>prototype</code>",
        PropertyDescriptor{\[[Value]]: |proto|, \[[Writable]]: <emu-val>false</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>false</emu-val>}).
    1.  [=Define the constants=] of [=interface=] |I| on |F| given |realm|.
    1.  [=Define the static attributes=] of [=interface=] |I| on |F| given |realm|.
    1.  [=Define the static operations=] of [=interface=] |I| on |F| given |realm|.
    1.  Return |F|.

</div>


<h4 id="legacy-factory-functions" oldids="named-constructors">Legacy factory functions</h4>

A [=legacy factory function=] that exists due to one or more
[{{LegacyFactoryFunction}}] [=extended attributes=]
with a given [=LegacyFactoryFunction identifier|identifier=] is a [=built-in function object=].
It allows constructing objects that
implement the interface on which the
[{{LegacyFactoryFunction}}] extended attributes appear.

<div algorithm>

    The [=legacy factory function=] with [=LegacyFactoryFunction identifier|identifier=] |id|
    for a given [=interface=] |I| in [=realm=] |realm|
    is <dfn lt="create a legacy factory function">created</dfn> as follows:

    1.  Let |steps| be the following steps:
        1.  If {{NewTarget}} is <emu-val>undefined</emu-val>, then
            [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
        1.  Let |args| be the passed arguments.
        1.  Let |n| be the [=list/size=] of |args|.
        1.  [=Compute the effective overload set=] for legacy factory functions with [=identifier=] |id|
            on [=interface=] |I| and with argument count |n|, and let |S| be the result.
        1.  Let &lt;|constructor|, |values|&gt; be the result of passing |S| and
            |args| to the [=overload resolution algorithm=].
        1.  Let |object| be the result of [=internally create a new object implementing the
            interface|internally creating a new object implementing=] |I|, with |realm| and
            {{NewTarget}}.
        1.  Perform the [=constructor steps=] of |constructor|
            with |object| as [=this=] and |values| as the argument values.
        1.  Let |O| be |object|, [=converted to a JavaScript value=].
        1.  Assert: |O| is an object that [=implements=] |I|.
        1.  Assert: |O|.\[[Realm]] is |realm|.
        1.  Return |O|.
    1.  Let |F| be <a abstract-op>CreateBuiltinFunction</a>(|steps|, « », |realm|).
    1.  Perform <a abstract-op>SetFunctionName</a>(|F|, |id|).
    1.  [=Compute the effective overload set=] for legacy factory functions with [=identifier=] |id|
        on [=interface=] |I| and with argument count 0, and let |S| be the result.
    1.  Let |length| be the length of the shortest argument list of the entries in |S|.
    1.  Perform <a abstract-op>SetFunctionLength</a>(|F|, |length|).
    1.  Let |proto| be the [=interface prototype object=] of [=interface=] |I| in |realm|.
    1.  Perform [=!=] <a abstract-op>DefinePropertyOrThrow</a>(|F|, "<code>prototype</code>",
        PropertyDescriptor{\[[Value]]: |proto|, \[[Writable]]: <emu-val>false</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>false</emu-val>}).
    1.  Return |F|.
</div>


<h4 id="interface-prototype-object">Interface prototype object</h4>

There will exist an <dfn id="dfn-interface-prototype-object" export>interface prototype object</dfn>
for every [=interface=] defined,
regardless of whether the interface was declared
with the [{{LegacyNoInterfaceObject}}] [=extended attribute=].

<div algorithm>

    The [=interface prototype object=] for a given [=interface=] |interface| and [=realm=] |realm|
    is <dfn lt="create an interface prototype object">created</dfn> as follows:

    1.  Let |proto| be null.
    1.  If |interface| is declared with the [{{Global}}] [=extended attribute=],
        and |interface| [=support named properties|supports named properties=],
        then set |proto| to the result of [=create a named properties object|creating a named
        properties object=] for |interface| and |realm|.
    1.  Otherwise, if |interface| is declared to inherit from another interface,
        then set |proto| to the [=interface prototype object=] in |realm|
        of that [=inherited interface=].
    1.  Otherwise, if |interface| is the {{DOMException}} [=interface=],
        then set |proto| to |realm|.\[[Intrinsics]].\[[{{%Error.prototype%}}]].
    1.  Otherwise, set |proto| to |realm|.\[[Intrinsics]].\[[{{%Object.prototype%}}]].
    1.  Assert: |proto| [=is an Object=].
    1.  Let |interfaceProtoObj| be null.
    1.  If |realm|'s [=is global prototype chain mutable=] is true, then:
        1.  Set |interfaceProtoObj| to [$OrdinaryObjectCreate$](|proto|).
    1.  Otherwise, if |interface| is declared with the [{{Global}}] [=extended attribute=], or
        |interface| is in the set of [=inherited interfaces=] of an interface
        that is declared with the [{{Global}}] [=extended attribute=], then:
        1.  Set |interfaceProtoObj| to [$MakeBasicObject$](« \[[Prototype]], \[[Extensible]] »).
        1.  Set |interfaceProtoObj|.\[[Prototype]] to |proto|.
        1.  Set the internal methods of |interfaceProtoObj|
            which are specific to [=immutable prototype exotic objects=]
            to the definitions specified in
            [=ECMA-262 Immutable prototype exotic objects=].
    1.  Otherwise, set |interfaceProtoObj| to [$OrdinaryObjectCreate$](|proto|).
    1.  If |interface| has any [=member=] declared with the [{{Unscopable}}] [=extended attribute=],
        then:
        1.  Let |unscopableObject| be [$OrdinaryObjectCreate$](<emu-val>null</emu-val>).
        1.  [=list/For each=] [=exposed=] [=member=] |member| of |interface|
            that is declared with the [{{Unscopable}}] [=extended attribute=]:
            1.  Let |id| be |member|'s [=identifier=].
            1.  Perform [=!=] <a abstract-op>CreateDataPropertyOrThrow</a>(|unscopableObject|, |id|,
                <emu-val>true</emu-val>).
        1.  Let |desc| be the PropertyDescriptor{\[[Value]]: |unscopableObject|,
            \[[Writable]]: <emu-val>false</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>,
            \[[Configurable]]: <emu-val>true</emu-val>}.
        1.  Perform [=!=] <a abstract-op>DefinePropertyOrThrow</a>(|interfaceProtoObj|, {{%Symbol.unscopables%}}, |desc|).
    1.  If |interface| is not declared with the [{{Global}}] [=extended attribute=], then:
        1.  [=Define the regular attributes=] of |interface| on |interfaceProtoObj| given |realm|.
        1.  [=Define the regular operations=] of |interface| on |interfaceProtoObj| given |realm|.
        1.  [=Define the iteration methods=] of |interface| on |interfaceProtoObj| given |realm|.
        1.  [=Define the asynchronous iteration methods=] of |interface| on |interfaceProtoObj|
            given |realm|.
    1.  [=Define the constants=] of |interface| on |interfaceProtoObj| given |realm|.
    1.  If the [{{LegacyNoInterfaceObject}}] [=extended attribute=] was not specified on |interface|, then:
        1.  Let |constructor| be the [=interface object=] of |interface| in |realm|.
        1.  Let |desc| be the PropertyDescriptor{\[[Writable]]: <emu-val>true</emu-val>,
            \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val>,
            \[[Value]]: |constructor|}.
        1.  Perform [=!=] <a abstract-op>DefinePropertyOrThrow</a>(|interfaceProtoObj|, "<code>constructor</code>", |desc|).
    1.  Return |interfaceProtoObj|.
</div>

Additionally, [=interface prototype objects=] get properties declaratively from:

* [[#js-stringifier]],
* [[#js-maplike]], and
* [[#js-setlike]].

Issue: Define those properties imperatively instead.

<div class="note">

    The [=interface prototype object=]
    of an [=interface=] that is defined with
    the [{{LegacyNoInterfaceObject}}]
    [=extended attribute=]
    will be accessible.
    For example, with the following IDL:

    <pre highlight="webidl">
        [Exposed=Window,
         LegacyNoInterfaceObject]
        interface Foo {
        };

        partial interface Window {
          attribute Foo foo;
        };
    </pre>

    it is not possible to access the interface prototype object through
    the [=interface object=]
    (since it does not exist as <code>window.Foo</code>).  However, an instance
    of <code class="idl">Foo</code> can expose the interface prototype
    object by calling its \[[GetPrototypeOf]]
    [=/internal method=] – <code>Object.getPrototypeOf(window.foo)</code> in
    this example.

</div>

The [=class string=] of an [=interface prototype object=] is the [=interface=]'s [=qualified name=].


<h4 id="named-properties-object">Named properties object</h4>

For every [=interface=] declared with the [{{Global}}] [=extended attribute=]
that [=support named properties|supports named properties=],
there will exist an object known as the <dfn id="dfn-named-properties-object" export>named properties object</dfn>
for that interface on which named properties are exposed.

<div algorithm>
    The [=named properties object=] for a given [=interface=] |interface| and [=realm=] |realm|,
    is <dfn lt="create a named properties object">created</dfn> as follows:

    1.  Let |proto| be null.
    1.  If |interface| is declared to inherit from another interface,
        then set |proto| to the [=interface prototype object=] in |realm| for the [=inherited interface=].
    1.  Otherwise, set |proto| to |realm|.\[[Intrinsics]].\[[{{%Object.prototype%}}]].
    1.  Let |obj| be [$MakeBasicObject$](« \[[Prototype]], \[[Extensible]] »).
    1.  Set |obj|.\[[GetOwnProperty]] as specified in [[#named-properties-object-getownproperty]].
    1.  Set |obj|.\[[DefineOwnProperty]] as specified in [[#named-properties-object-defineownproperty]].
    1.  Set |obj|.\[[Delete]] as specified in [[#named-properties-object-delete]].
    1.  Set |obj|.\[[SetPrototypeOf]] as specified in [[#named-properties-object-setprototypeof]].
    1.  Set |obj|.\[[PreventExtensions]] as specified in [[#named-properties-object-preventextensions]].
    1.  Set |obj|.\[[Prototype]] to |proto|.
    1.  Return |obj|.
</div>

Note: The \[[OwnPropertyKeys]] internal method of a named properties object
continues to use <a abstract-op>OrdinaryOwnPropertyKeys</a>,
unlike the counterpart for [=legacy platform objects=].
Since named properties are not “real” own properties,
they will not be returned by this internal method.

The [=class string=] of a [=named properties object=]
is the concatenation of the [=interface=]'s
[=identifier=] and the string "<code>Properties</code>".


<h5 id="named-properties-object-getownproperty">\[[GetOwnProperty]]</h5>

<div algorithm="to invoke the internal [[GetOwnProperty]] method of named properties object">

    When the \[[GetOwnProperty]] internal method of a [=named properties object=] |O|
    is called with property key |P|, the following steps are taken:

    1.  Let |A| be the [=interface=] for the [=named properties object=] |O|.
    1.  Let |object| be |O|.\[[Realm]]'s [=realm/global object=].
    1.  Assert: |object| [=implements=] |A|.
    1.  If the result of running the [=named property visibility algorithm=] with
        property name |P| and object |object| is true, then:
        1.  Let |operation| be the operation used to declare the named property getter.
        1.  Let |value| be an uninitialized variable.
        1.  If |operation| was defined without an [=identifier=], then
            set |value| to the result of performing the steps listed in the interface description to
            [=determine the value of a named property=]
            with |P| as the name.
        1.  Otherwise, |operation| was defined with an identifier.  Set |value| to the result
            of performing the steps listed in the description of |operation| with |P| as the only argument value.
        1.  Let |desc| be a newly created [=Property Descriptor=] with no fields.
        1.  Set |desc|.\[[Value]] to the result of [=converted to a JavaScript value|converting=]
            |value| to a JavaScript value.
        1.  If |A| [=implements=] an interface with the
            [{{LegacyUnenumerableNamedProperties}}]
            [=extended attribute=],
            then set |desc|.\[[Enumerable]] to <emu-val>false</emu-val>,
            otherwise set it to <emu-val>true</emu-val>.
        1.  Set |desc|.\[[Writable]] to <emu-val>true</emu-val> and
            |desc|.\[[Configurable]] to <emu-val>true</emu-val>.
        1.  Return |desc|.
    1.  Return <a abstract-op>OrdinaryGetOwnProperty</a>(|O|, |P|).
</div>


<h5 id="named-properties-object-defineownproperty">\[[DefineOwnProperty]]</h5>

<div algorithm="to invoke the [[DefineOwnProperty]] internal method of named properties object">

    When the \[[DefineOwnProperty]] internal method of a [=named properties object=] is called,
    the following steps are taken:

    1.  Return <emu-val>false</emu-val>.
</div>

<h5 id="named-properties-object-delete">\[[Delete]]</h5>

<div algorithm="to invoke the [[Delete]] internal method of named properties object">

    When the \[[Delete]] internal method of a [=named properties object=] is called,
    the following steps are taken:

    1.  Return <emu-val>false</emu-val>.
</div>


<h5 id="named-properties-object-setprototypeof">\[[SetPrototypeOf]]</h5>

<div algorithm="to invoke the [[SetPrototypeOf]] internal method of a named properties object">

    When the \[[SetPrototypeOf]] internal method of a [=named properties object=] |O| is called with
    JavaScript language value |V|, the following step is taken:

    1.  If |O|'s [=associated realm=]'s [=is global prototype chain mutable=] is true,
        return [=?=] [$OrdinarySetPrototypeOf$](|O|, |V|).
    1.  Return [=?=] <a abstract-op>SetImmutablePrototype</a>(|O|, |V|).

</div>


<h5 id="named-properties-object-preventextensions">\[[PreventExtensions]]</h5>

<div algorithm="to invoke the [[PreventExtensions]] internal method of named properties object">

    When the \[[PreventExtensions]] internal method of a [=named properties object=] is called,
    the following steps are taken:

    1.  Return <emu-val>false</emu-val>.

    Note: this keeps [=named properties object=] extensible by
    making \[[PreventExtensions]] fail.
</div>


<h4 id="js-constants" oldids="es-constants">Constants</h4>

[=Constants=] are exposed on [=interface objects=],
[=legacy callback interface objects=],
[=interface prototype objects=], and
on the single object that [=implements=] the interface,
when an interface is declared with the [{{Global}}] [=extended attribute=].

<div algorithm>
    To <dfn>define the constants</dfn> of [=interface=], [=callback interface=], or [=namespace=]
    |definition| on |target|, given [=realm=] |realm|, run the following steps:

    1.  [=list/For each=] [=constant=] |const| that is a [=member=] of |definition|:
        1.  If |const| is not [=exposed=] in |realm|, then [=iteration/continue=].
        1.  Let |value| be the result of [=converted to a JavaScript value|converting=]
            |const|'s IDL value to a JavaScript value.
        1.  Let |desc| be the PropertyDescriptor{\[[Writable]]: <emu-val>false</emu-val>,
            \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>false</emu-val>,
            \[[Value]]: |value|}.
        1.  Let |id| be |const|'s [=identifier=].
        1.  Perform [=!=] <a abstract-op>DefinePropertyOrThrow</a>(|target|, |id|, |desc|).
</div>


<h4 id="js-attributes" oldids="es-attributes">Attributes</h4>

[=Static attributes=] are exposed on the [=interface object=].
[=Regular attributes=] are exposed on the [=interface prototype object=],
unless the attribute is [=unforgeable=] or
if the interface was declared with the [{{Global}}] [=extended attribute=],
in which case they are exposed on every object that [=implements=] the interface.

<div algorithm>
    To <dfn>define the regular attributes</dfn> of [=interface=] or [=namespace=] |definition| on |target|,
    given [=realm=] |realm|, run the following steps:

    1.  Let |attributes| be the [=list=] of [=regular attributes=] that are [=members=] of |definition|.
    1.  [=list/Remove=] from |attributes| all the [=attributes=] that are [=unforgeable=].
    1.  [=Define the attributes=] |attributes| of |definition| on |target| given |realm|.
</div>

<div algorithm>
    To <dfn>define the static attributes</dfn> of [=interface=] or [=namespace=] |definition| on |target|,
    given [=realm=] |realm|, run the following steps:

    1.  Let |attributes| be the [=list=] of [=static attributes=] that are [=members=] of |definition|.
    1.  [=Define the attributes=] |attributes| of |definition| on |target| given |realm|.
</div>

<div algorithm>
    To <dfn>define the unforgeable regular attributes</dfn> of [=interface=] or [=namespace=] |definition| on |target|,
    given [=realm=] |realm|, run the following steps:

    1.  Let |attributes| be the [=list=] of [=unforgeable=] [=regular attributes=] that are [=members=] of |definition|.
    1.  [=Define the attributes=] |attributes| of |definition| on |target| given |realm|.
</div>

<div algorithm>
    To <dfn>define the attributes</dfn> |attributes| of [=interface=] or [=namespace=] |definition| on |target|
    given [=realm=] |realm|, run the following steps:

    1.  [=list/For each=] [=attribute=] |attr| of |attributes|:
        1.  If |attr| is not [=exposed=] in |realm|, then [=iteration/continue=].
        1.  Let |getter| be the result of creating an [=attribute getter=]
            given |attr|, |definition|, and |realm|.
        1.  Let |setter| be the result of creating an [=attribute setter=]
            given |attr|, |definition|, and |realm|.

            Note: the algorithm to create an [=attribute setter=]
            returns <emu-val>undefined</emu-val> if |attr| is [=read only=].
        1.  Let |configurable| be <emu-val>false</emu-val> if |attr| is [=unforgeable=]
            and <emu-val>true</emu-val> otherwise.
        1.  Let |desc| be the PropertyDescriptor{\[[Get]]: |getter|, \[[Set]]: |setter|,
            \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: |configurable|}.
        1.  Let |id| be |attr|'s [=identifier=].
        1.  Perform [=!=] <a abstract-op>DefinePropertyOrThrow</a>(|target|, |id|, |desc|).
        1.  If |attr|'s type is an [=observable array type=] with type argument |T|, then set
            |target|'s [=backing observable array exotic object=] for |attr| to the result of
            [=creating an observable array exotic object=] in |realm|, given |T|, |attr|'s
            [=set an indexed value=] algorithm, and |attr|'s [=delete an indexed value=] algorithm.

</div>

<div algorithm>

    The <dfn id="dfn-attribute-getter" export>attribute getter</dfn> is created as follows, given an
    [=attribute=] |attribute|, a [=namespace=] or [=interface=] |target|, and a [=realm=] |realm|:

    1.  Let |steps| be the following series of steps:
        1.  Try running the following steps:
            1.  Let |idlObject| be null.
            1.  If |target| is an [=interface=], and |attribute| is a [=regular attribute=]:
                1.  Let |jsValue| be the <emu-val>this</emu-val> value, if it is not
                    <emu-val>null</emu-val> or <emu-val>undefined</emu-val>, or |realm|'s
                    [=realm/global object=] otherwise.
                    (This will subsequently cause a {{TypeError}} in a few steps, if
                    the global object does not implement |target| and [{{LegacyLenientThis}}] is not
                    specified.)
                    <!-- https://www.w3.org/Bugs/Public/show_bug.cgi?id=18547#c9 -->
                1.  If |jsValue| [=is a platform object=], then [=perform a security check=],
                    passing |jsValue|, |attribute|'s [=identifier=], and "getter".
                1.  If |jsValue| does not [=implement=] |target|, then:
                    1.  If |attribute| was specified with the [{{LegacyLenientThis}}]
                        [=extended attribute=], then return <emu-val>undefined</emu-val>.
                    1.  Otherwise, [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
                1.  If |attribute|'s type is an [=observable array type=], then return |jsValue|'s
                    [=backing observable array exotic object=] for |attribute|.
                1.  Set |idlObject| to the IDL [=interface type=] value that represents a reference
                    to |jsValue|.
            1.  Let |R| be the result of running the [=getter steps=] of |attribute| with
                |idlObject| as [=this=].
            1.  Return the result of [=converted to a JavaScript value|converting=] |R| to a
                JavaScript value of the type |attribute| is declared as.

        And then, if <a lt="an exception was thrown">an exception |E| was thrown</a>:

        1.  If |attribute|'s type is a [=promise type=], then return
            [=!=] <a abstract-op>Call</a>({{%Promise.reject%}}, {{%Promise%}}, «|E|»).
        1.  Otherwise, end these steps and allow the exception to propagate.
    1.  Let |F| be <a abstract-op>CreateBuiltinFunction</a>(|steps|, « », |realm|).
    1.  Let |name| be the string "<code>get </code>" prepended to |attribute|'s [=identifier=].
    1.  Perform <a abstract-op>SetFunctionName</a>(|F|, |name|).
    1.  Perform <a abstract-op>SetFunctionLength</a>(|F|, 0).
    1.  Return |F|.

</div>

<div algorithm>

    The <dfn id="dfn-attribute-setter" export>attribute setter</dfn> is created as follows, given an
    [=attribute=] |attribute|, a [=namespace=] or [=interface=] |target|, and a [=realm=] |realm|:

    1.  If |target| is a [=namespace=]:
        1. Assert: |attribute| is [=read only=].
        1. Return <emu-val>undefined</emu-val>.
    1.  If |attribute| is [=read only=] and does not have a
        [{{LegacyLenientSetter}}], [{{PutForwards}}] or [{{Replaceable}}] [=extended attribute=], return
        <emu-val>undefined</emu-val>; there is no [=attribute setter=] function.
    1.  Assert: |attribute|'s type is not a [=promise type=].
    1.  Let |steps| be the following series of steps:
        1.  If no arguments were passed, then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
        1.  Let |V| be the value of the first argument passed.
        1.  Let |id| be |attribute|'s [=identifier=].
        1.  Let |idlObject| be null.
        1.  If |attribute| is a [=regular attribute=]:
            1.  Let |jsValue| be the <emu-val>this</emu-val> value, if it is not
                <emu-val>null</emu-val> or <emu-val>undefined</emu-val>, or |realm|'s
                [=realm/global object=] otherwise.
                (This will subsequently cause a {{TypeError}} in a few steps, if
                the global object does not implement |target| and [{{LegacyLenientThis}}] is not
                specified.)
                <!-- https://www.w3.org/Bugs/Public/show_bug.cgi?id=18547#c9 -->
            1.  If |jsValue| [=is a platform object=], then [=perform a security check=], passing
                |jsValue|, |id|, and "setter".
            1.  Let |validThis| be true if |jsValue| [=implements=] |target|, or false otherwise.
            1.  If |validThis| is false and |attribute| was not specified with the [{{LegacyLenientThis}}]
                [=extended attribute=], then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
            1.  If |attribute| is declared with the [{{Replaceable}}] extended attribute, then:
                1.  Perform [=?=] <a abstract-op>CreateDataPropertyOrThrow</a>(|jsValue|, |id|, |V|).
                1.  Return <emu-val>undefined</emu-val>.
            1.  If |validThis| is false, then return <emu-val>undefined</emu-val>.
            1.  If |attribute| is declared with a [{{LegacyLenientSetter}}] extended attribute, then
                return <emu-val>undefined</emu-val>.
            1.  If |attribute| is declared with a [{{PutForwards}}] extended attribute, then:
                1.  Let |Q| be [=?=] <a abstract-op>Get</a>(|jsValue|, |id|).
                1.  If |Q| [=is not an Object=], then [=JavaScript/throw=] a
                    <l spec=ecmascript>{{TypeError}}</l>.
                1.  Let |forwardId| be the identifier argument of the [{{PutForwards}}] extended
                    attribute.
                1.  Perform [=?=] <a abstract-op>Set</a>(|Q|, |forwardId|, |V|, <emu-val>false</emu-val>).
                1.  Return <emu-val>undefined</emu-val>.
            1.  Set |idlObject| to the IDL [=interface type=] value that represents a reference
                to |jsValue|.
            1.  If |attribute|'s type is an [=observable array type=] with type argument |T|:
                1.  Let |newValues| be the result of [=converted to an IDL value|converting=] |V| to
                    an IDL value of type <a lt="sequence type">sequence&lt;|T|&gt;</a>.
                1.  Let |oa| be |idlObject|'s |attribute|'s [=backing observable array exotic object=].
                1.  [=observable array exotic object/Set the length=] of |oa|.\[[ProxyHandler]] to 0.
                1.  Let |i| be 0.
                1.  While |i| &lt; |newValues|'s [=list/size=]:
                    1.  Perform the algorithm steps given by
                        |oa|.\[[ProxyHandler]].\[[SetAlgorithm]], given |newValues|[|i|] and |i|.
                    1.  [=list/Append=] |newValues|[|i|] to |oa|.\[[ProxyHandler]].\[[BackingList]].
                1.  Return <emu-val>undefined</emu-val>.
        1.  Let |idlValue| be determined as follows:

            <dl class="switch">
                <dt>|attribute|'s type is an [=enumeration=]</dt>
                <dd>
                    1.  Let |S| be [=?=] <a abstract-op>ToString</a>(|V|).
                    1.  If |S| is not one of the [=enumeration's values=], then
                        return <emu-val>undefined</emu-val>.
                    1.  Otherwise, |idlValue| is the enumeration value equal to |S|.
                </dd>

                <dt>Otherwise</dt>
                <dd>
                    |idlValue| is the result of [=converted to an IDL value|converting=] |V| to an
                    IDL value of |attribute|'s type.
                </dd>
            </dl>

        1.  Perform the [=setter steps=] of |attribute|,
            with |idlObject| as [=this=] and |idlValue| as [=the given value=].
        1.  Return <emu-val>undefined</emu-val>
    1.  Let |F| be <a abstract-op>CreateBuiltinFunction</a>(|steps|, « », |realm|).
    1.  Let |name| be the string "<code>set </code>" prepended to |id|.
    1.  Perform <a abstract-op>SetFunctionName</a>(|F|, |name|).
    1.  Perform <a abstract-op>SetFunctionLength</a>(|F|, 1).
    1. Return |F|.
</div>

Note: Although there is only a single property for an IDL attribute, since
accessor property getters and setters are passed a [=this=]
value for the object on which property corresponding to the IDL attribute is
accessed, they are able to expose instance-specific data.

Note: Attempting to assign to a property corresponding to a
[=read only=] [=attribute=]
results in different behavior depending on whether the script doing so is in strict mode.
When in strict mode, such an assignment will result in a {{TypeError}}
being thrown.  When not in strict mode, the assignment attempt will be ignored.


<h4 id="js-operations" oldids="es-operations">Operations</h4>

For each unique [=identifier=] of an [=exposed=] [=operation=] defined on the [=interface=],
there exist a corresponding property.
[=Static operations=] are exposed of the [=interface object=].
[=Regular operations=] are exposed on the [=interface prototype object=],
unless the operation is [=unforgeable=] or
the interface was declared with the [{{Global}}] [=extended attribute=],
in which case they are exposed on every object that [=implements=] the interface.

<div algorithm>
    To <dfn>define the regular operations</dfn> of [=interface=] or [=namespace=] |definition| on |target|, given [=realm=] |realm|,
    run the following steps:

    1.  Let |operations| be the [=list=] of [=regular operations=] that are [=members=] of |definition|.
    1.  [=list/Remove=] from |operations| all the [=operations=] that are [=unforgeable=].
    1.  [=Define the operations=] |operations| of |definition| on |target| given |realm|.
</div>

<div algorithm>
    To <dfn>define the static operations</dfn> of [=interface=] or [=namespace=] |definition| on |target|, given [=realm=] |realm|,
    run the following steps:

    1.  Let |operations| be the [=list=] of [=static operations=] that are [=members=] of |definition|.
    1.  [=Define the operations=] |operations| of |definition| on |target| given |realm|.
</div>

<div algorithm>
    To <dfn>define the unforgeable regular operations</dfn> of [=interface=] or [=namespace=] |definition| on |target|, given [=realm=] |realm|,
    run the following steps:

    1.  Let |operations| be the [=list=] of [=unforgeable=] [=regular operations=] that are [=members=] of |definition|.
    1.  [=Define the operations=] |operations| of |definition| on |target| given |realm|.
</div>

<div algorithm>
    To <dfn>define the operations</dfn> |operations| of [=interface=] or [=namespace=] |definition| on |target|,
    given [=realm=] |realm|, run the following steps:

    1.  [=list/For each=] [=operation=] |op| of |operations|:
        1.  If |op| is not [=exposed=] in |realm|, then [=iteration/continue=].
        1.  Let |method| be the result of [=creating an operation function=]
            given |op|, |definition|, and |realm|.
        1.  Let |modifiable| be <emu-val>false</emu-val> if |op| is [=unforgeable=]
            and <emu-val>true</emu-val> otherwise.
        1.  Let |desc| be the PropertyDescriptor{\[[Value]]: |method|,
            \[[Writable]]: |modifiable|, \[[Enumerable]]: <emu-val>true</emu-val>,
            \[[Configurable]]: |modifiable|}.
        1.  Let |id| be |op|'s [=identifier=].
        1.  Perform [=!=] <a abstract-op>DefinePropertyOrThrow</a>(|target|, |id|, |desc|).
</div>

<div algorithm>
    To <dfn id="dfn-create-operation-function" lt="creating an operation function">create an operation function</dfn>,
    given an [=operation=] |op|, a [=namespace=] or [=interface=] |target|, and a [=realm=] |realm|:

    1.  Let |id| be |op|'s [=identifier=].
    1.  Let |steps| be the following series of steps, given function argument
        values |args|:
        1.  Try running the following steps:
            1.  Let |idlObject| be null.
            1.  If |target| is an [=interface=], and |op| is not a [=static operation=]:
                1.  Let |jsValue| be the <emu-val>this</emu-val> value, if it is not
                    <emu-val>null</emu-val> or <emu-val>undefined</emu-val>, or |realm|'s
                    [=realm/global object=] otherwise.
                    (This will subsequently cause a {{TypeError}} in a few steps, if
                    the global object does not implement |target| and [{{LegacyLenientThis}}] is not
                    specified.)
                    <!-- https://www.w3.org/Bugs/Public/show_bug.cgi?id=18547#c9 -->
                1.  If |jsValue| [=is a platform object=], then [=perform a security check=],
                    passing |jsValue|, |id|, and "method".
                1.  If |jsValue| does not [=implement=] the interface |target|,
                    [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
                1.  Set |idlObject| to the IDL [=interface type=] value that represents a reference
                    to |jsValue|.
            1.  Let |n| be the [=list/size=] of |args|.
            1.  [=Compute the effective overload set=]  for [=regular operations=] (if |op| is a
                regular operation) or for [=static operations=] (if |op| is a static operation)
                with [=identifier=] |id| on |target| and with argument count |n|, and let |S| be
                the result.
            1.  Let &lt;|operation|, |values|&gt; be the result of passing
                |S| and |args| to the [=overload resolution algorithm=].
            1.  Let |R| be <emu-val>null</emu-val>.
            1.  If |operation| is declared with a [{{Default}}] [=extended attribute=], then:
                1.  Assert: |operation| [=has default method steps=].
                1.  Set |R| to the result of running the [=default method steps=] for |operation|,
                    with |idlObject| as [=this=] and |values| as the argument values.
            1.  Otherwise, set |R| to the result of running the [=method steps=] of |operation|,
                with |idlObject| as [=this=] and |values| as the argument values.
            1.  Return |R|, [=converted to a JavaScript value=].

                Issue(whatwg/webidl#674): |R| is assumed to be an IDL value of the type |op| is declared to return.

        And then, if <a lt="an exception was thrown">an exception |E| was thrown</a>:

        1.  If |op| has a [=return type=]
            that is a [=promise type=], then return
            [=!=] <a abstract-op>Call</a>({{%Promise.reject%}}, {{%Promise%}}, «|E|»).
        1.  Otherwise, end these steps and allow the exception to propagate.
    1.  Let |F| be <a abstract-op>CreateBuiltinFunction</a>(|steps|, « », |realm|).
    1.  Perform <a abstract-op>SetFunctionName</a>(|F|, |id|).
    1.  [=Compute the effective overload set=]  for [=regular operations=] (if |op| is a regular
        operation) or for [=static operations=] (if |op| is a static operation) with [=identifier=]
        |id| on |target| and with argument count 0, and let |S| be the result.
    1.  Let |length| be the length of the shortest argument list in the entries in |S|.
    1.  Perform <a abstract-op>SetFunctionLength</a>(|F|, |length|).
    1.  Return |F|.
</div>


<h5 id="js-default-operations" oldids="es-default-operations">Default operations</h5>

A [=regular operation=]
<dfn lt="has default method steps|have default method steps">has default method steps</dfn>
if its [=identifier=] appears in the first column of the following table. In that case, its
<dfn>default method steps</dfn> are those given by the algorithm linked from the second column of
the table, and the operation must have the return type given in the third column of the table.

<table id="table-default-method-steps" class="data">
<thead>
    <th>[=Identifier=]
    <th>[=Default method steps=]
    <th>[=Return type=]</th>
<tbody>
    <tr>
        <td>"<code>toJSON</code>"
        <td>The [=default toJSON steps=]
        <td>{{object}}</td>
</table>

A [=regular operation=] that does not [=have default method steps=] must not be declared with a
[{{Default}}] [=extended attribute=].


<h6 id="js-default-tojson" oldids="es-default-tojson">Default toJSON operation</h6>

<div algorithm>

    The <dfn export>default toJSON steps</dfn> for an [=interface=] |I| are:

    1.  Let |map| be a new [=ordered map=].
    1.  Let |stack| be the result of [=create an inheritance stack|creating an inheritance stack=]
        for [=interface=] |I|.
    1.  Invoke [=collect attribute values of an inheritance stack=] given [=this=], |stack|, and
        |map|.
    1.  Let |result| be [$OrdinaryObjectCreate$]({{%Object.prototype%}}).
    1.  [=map/For each=] |key| → |value| of |map|,
        1.  Let |k| be |key| [=converted to a JavaScript value=].
        1.  Let |v| be |value| [=converted to a JavaScript value=].
        1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|result|, |k|, |v|).
    1.  Return |result|.
</div>

<div algorithm>

    To <dfn>collect attribute values of an inheritance stack</dfn> given a [=platform object=]
    |object|, a [=stack=] |stack|, and an [=ordered map=] |map|:

    1.  Let |I| be the result of [=stack/pop|popping=] from |stack|.
    1.  Invoke [=collect attribute values=] given |object|, |I|, and |map|.
    1.  If |stack| [=stack/is not empty=], then invoke
        [=collect attribute values of an inheritance stack=] given |object|, |stack|, and |map|.
</div>

<div algorithm>

    To <dfn>collect attribute values</dfn> given a [=platform object=] |object|, an [=interface=]
    |I|, and an [=ordered map=] |map|:

    1.  If a <code>toJSON</code> operation with a [{{Default}}] [=extended attribute=] is declared
        on |I|, then [=list/for each=] [=exposed=] [=regular attribute=] |attr| that is an
        [=interface member=] of |I|, in order:
        1.  Let |id| be the [=identifier=] of |attr|.
        1.  Let |value| be the result of running the [=getter steps=] of |attr| with |object| as
            [=this=].
        1.  If |value| is a [=JSON type=], then [=map/set=] |map|[|id|] to |value|.

</div>

<div algorithm>

    To <dfn>create an inheritance stack</dfn> for [=interface=] |I|,
    run the following steps:

    1.  Let |stack| be a new [=stack=].
    1.  [=stack/Push=] |I| onto |stack|.
    1.  [=iteration/While=] |I| [=interface/inherits=] from an [=interface=],
        1.  Let |I| be that [=interface=].
        1.  [=stack/Push=] |I| onto |stack|.
    1.  Return |stack|.
</div>

<div class=example id=example-tojson-default-inheritance-and-mixins>

    Only [=regular attributes=] of [=interfaces=] that declare a <code>toJSON</code> operation with
    a [{{Default}}] [=extended attribute=] are included, even if an [=inherited interface=] declares
    such a <code>toJSON</code> operation. For example, consider the following [=IDL fragment=]:

    <pre class=webidl>
        [Exposed=Window]
        interface A {
          [Default] object toJSON();
          attribute DOMString a;
        };

        [Exposed=Window]
        interface B : A {
          attribute DOMString b;
        };

        [Exposed=Window]
        interface C : B {
          [Default] object toJSON();
          attribute DOMString c;
        };
    </pre>

    Calling the <code>toJSON()</code> method of an object implementing interface
    <code class="idl">C</code> defined above would return the following JSON object:

    <pre highlight=json>
    {
        "a": "...",
        "c": "..."
    }
    </pre>

    Calling the <code>toJSON()</code> method of an object implementing interface
    <code class="idl">A</code> (or <code class="idl">B</code>) defined above would return:

    <pre highlight=json>
    {
        "a": "..."
    }
    </pre>

    A <code>toJSON</code> operation can also be declared on an [=interface mixin=] (or
    [=partial interface=]) and is equivalent to declaring it on the original [=interface=]. For
    example, consider the following [=IDL fragment=]:

    <pre class=webidl>
        [Exposed=Window]
        interface D {
          attribute DOMString d;
        };

        interface mixin M {
          [Default] object toJSON();
          attribute DOMString m;
        };

        D includes M;
    </pre>

    Calling the <code>toJSON()</code> method of an object implementing interface
    <code class="idl">D</code> defined above would return:

    <pre highlight=json>
    {
        "d": "...",
        "m": "..."
    }
    </pre>
</div>

<h4 id="js-stringifier" oldids="es-stringifier">Stringifiers</h4>

If the [=interface=] has an [=exposed=] [=stringifier=],
then there must exist a property with the following characteristics:

*   The name of the property is "<code>toString</code>".
*   If the [=stringifier=] is [=unforgeable=] on the interface
    or if the interface was declared with the [{{Global}}] [=extended attribute=],
    then the property exists on every object that [=implements=] the interface.
    Otherwise, the property exists on the [=interface prototype object=].
*   The property has attributes
    { \[[Writable]]: |B|, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: |B| },
    where |B| is <emu-val>false</emu-val> if the stringifier is [=unforgeable=] on the interface,
    and <emu-val>true</emu-val> otherwise.
*   <div algorithm="to invoke the toString method of interfaces">

        The value of the property is a [=built-in function object=], which behaves as follows:

        1.  Let |thisValue| be the <emu-val>this</emu-val> value.
        1.  Let |O| be [=?=] <a abstract-op>ToObject</a>(|thisValue|).
        1.  If |O| [=is a platform object=],
            then [=perform a security check=], passing:
            *   the platform object |O|,
            *   the [=identifier=] of the [=stringifier=], and
            *   the type "<code>method</code>".
        1.  If |O| does not [=implement=] the [=interface=]
            on which the stringifier was declared, then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
        1.  Let |V| be an uninitialized variable.
        1.  Depending on how <code>stringifier</code> was specified:
            <dl class="switch">
                 :  as a declaration
                 :: Set |V| to the result of performing the [=stringification behavior=]
                    of the interface.
                 :  on an [=attribute=]
                 :: Set |V| to the result of running the [=getter steps=] of the attribute
                    (or those listed in the [=getter steps=] of the inherited attribute, if this attribute is declared to
                    [=inherit its getter=]),
                    with |O| as [=this=].
            </dl>
        1.  Return the result of [=converted to a JavaScript value|converting=] |V| to a String value.
    </div>
*   The value of the [=function object=]'s <code class="idl">length</code>
    property is the Number value <emu-val>0</emu-val>.
*   The value of the [=function object=]'s <code class="idl">name</code>
    property is the String value "<code>toString</code>".


<h4 id="js-iterable" oldids="es-iterable">Iterable declarations</h4>

<div algorithm>
    To <dfn oldids="es-iterable-entries,es-iterable-keys,es-iterable-values">define the iteration methods</dfn>
    of [=interface=] |definition| on |target|, given [=realm=] |realm|, run the following steps:

    1.  If |definition| has an [=indexed property getter=], then:
        1.  Perform [$DefineMethodProperty$](|target|, {{%Symbol.iterator%}},
            {{%Array.prototype.values%}}, false).
        1.  If |definition| has a [=value iterator=], then:
            1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|target|, "<code>entries</code>",
                {{%Array.prototype.entries%}}).
            1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|target|, "<code>keys</code>",
                {{%Array.prototype.keys%}}).
            1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|target|, "<code>values</code>",
                {{%Array.prototype.values%}}).
            1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|target|, "<code>forEach</code>",
                {{%Array.prototype.forEach%}}).
    1.  Otherwise, if |definition| has a [=pair iterator=], then:
        1.  Define the {{%Symbol.iterator%}} and <code class="idl">entries</code> methods:
            1.  Let |steps| be the following series of steps:
                1.  Let |jsValue| be [=?=] [$ToObject$](<emu-val>this</emu-val> value).
                1.  If |jsValue| [=is a platform object=], then [=perform a security check=],
                    passing |jsValue|, "<code>%Symbol.iterator%</code>", and "<code>method</code>".
                1.  If |jsValue| does not [=implement=] |definition|, then [=JavaScript/throw=] a
                    <l spec=ecmascript>{{TypeError}}</l>.
                1.  Return a newly created [=default iterator object=] for |definition|, with
                    |jsValue| as its [=default iterator object/target=], "<code>key+value</code>"
                    as its [=default iterator object/kind=], and [=default iterator object/index=]
                    set to 0.
            1.  Let |F| be [$CreateBuiltinFunction$](|steps|, « », |realm|).
            1.  Perform [$SetFunctionName$](|F|, "<code>entries</code>").
            1.  Perform [$SetFunctionLength$](|F|, 0).
            1.  Perform [$DefineMethodProperty$](|target|, {{%Symbol.iterator%}}, |F|, false).
            1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|target|, "<code>entries</code>", |F|).
        1.  Define the <code class="idl">keys</code> method:
            1.  Let |steps| be the following series of steps:
                1.  Let |jsValue| be [=?=] [$ToObject$](<emu-val>this</emu-val> value).
                1.  If |jsValue| [=is a platform object=], then [=perform a security check=],
                    passing |jsValue|, "<code>keys</code>", and "<code>method</code>".
                1.  If |jsValue| does not [=implement=] |definition|, then [=JavaScript/throw=] a
                    <l spec=ecmascript>{{TypeError}}</l>.
                1.  Return a newly created [=default iterator object=] for |definition|, with
                    |jsValue| as its [=default iterator object/target=], "<code>key</code>" as its
                    [=default iterator object/kind=], and [=default iterator object/index=] set to 0.
            1.  Let |F| be [$CreateBuiltinFunction$](|steps|, « », |realm|).
            1.  Perform [$SetFunctionName$](|F|, "<code>keys</code>").
            1.  Perform [$SetFunctionLength$](|F|, 0).
            1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|target|, "<code>keys</code>", |F|).
        1.  Define the <code class="idl">values</code> method:
            1.  Let |steps| be the following series of steps:
                1.  Let |jsValue| be [=?=] [$ToObject$](<emu-val>this</emu-val> value).
                1.  If |jsValue| [=is a platform object=], then [=perform a security check=],
                    passing |jsValue|, "<code>values</code>", and "<code>method</code>".
                1.  If |jsValue| does not [=implement=] |definition|, then [=JavaScript/throw=] a
                    <l spec=ecmascript>{{TypeError}}</l>.
                1.  Return a newly created [=default iterator object=] for |definition|, with
                    |jsValue| as its [=default iterator object/target=], "<code>value</code>" as its
                    [=default iterator object/kind=], and [=default iterator object/index=] set to 0.
            1.  Let |F| be [$CreateBuiltinFunction$](|steps|, « », |realm|).
            1.  Perform [$SetFunctionName$](|F|, "<code>values</code>").
            1.  Perform [$SetFunctionLength$](|F|, 0).
            1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|target|, "<code>values</code>", |F|).
        1.  Define the <code class="idl">forEach</code> method:
            1.  Let |steps| be the following series of steps, given function argument values
                |callback| and |thisArg|:
                1.  Let |jsValue| be [=?=] [$ToObject$](<emu-val>this</emu-val> value).
                1.  If |jsValue| [=is a platform object=], then [=perform a security check=],
                    passing |jsValue|, "<code>forEach</code>", and "<code>method</code>".
                1.  If |jsValue| does not [=implement=] |definition|, then [=JavaScript/throw=] a
                    <l spec=ecmascript>{{TypeError}}</l>.
                1.  Let |idlCallback| be |callback|, [=converted to an IDL value|converted=] to a
                    {{Function}}.
                1.  Let |idlObject| be the IDL [=interface type=] value that represents a reference
                    to |jsValue|.
                1.  Let |pairs| be |idlObject|'s list of [=value pairs to iterate over=].
                1.  Let |i| be 0.
                1.  While |i| &lt; |pairs|'s [=list/size=]:
                    1.  Let |pair| be |pairs|[|i|].
                    1.  [=Invoke=] |idlCallback| with « |pair|'s [=value pair/value=], |pair|'s
                        [=value pair/key=], |idlObject| » and with |thisArg| as the
                        [=callback this value=].
                    1.  Set |pairs| to |idlObject|'s current list of
                        [=value pairs to iterate over=]. (It might have changed.)
                    1.  Set |i| to |i| + 1.
            1.  Let |F| be [$CreateBuiltinFunction$](|steps|, « », |realm|).
            1.  Perform [$SetFunctionName$](|F|, "<code>forEach</code>").
            1.  Perform [$SetFunctionLength$](|F|, 1).
            1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|target|, "<code>forEach</code>", |F|).
</div>


<h5 id="js-default-iterator-object" oldids="es-default-iterator-object">Default iterator objects</h5>

A <dfn id="dfn-default-iterator-object" export>default iterator object</dfn> for a given
[=interface=], target and iteration kind
is an object whose \[[Prototype]] [=/internal slot=] is the
[=iterator prototype object=]
for the [=interface=].

A [=default iterator object=]
has three internal values:

*   its <dfn for="default iterator object">target</dfn>, which is an object whose values are to be
    iterated,
*   its <dfn for="default iterator object">kind</dfn>, which is the iteration kind,
*   its <dfn for="default iterator object">index</dfn>, which is the current index into the values
    to be iterated.

Note: Default iterator objects are only used for [=pair iterators=];
[=value iterators=], as they are currently
restricted to iterating over an object's
[=support indexed properties|supported indexed properties=],
use standard JavaScript Array iterator objects.

Note: [=Default iterator objects=] do not have [=class strings=]; when <code
class="idl">Object.prototype.toString()</code> is called on a [=default
iterator object=] of a given [=interface=], the [=class string=] of the
[=iterator prototype object=] of that [=interface=] is used.


<h5 id="js-iterator-prototype-object" oldids="es-iterator-prototype-object">Iterator prototype object</h5>

The <dfn id="dfn-iterator-prototype-object" export>iterator prototype object</dfn>
for a given [=interface=]
is an object that exists for every interface that has a
[=pair iterator=].  It serves as the
prototype for [=default iterator objects=]
for the interface.

The \[[Prototype]] [=/internal slot=] of an [=iterator prototype object=]
must be {{%Iterator.prototype%}}.

<div algorithm>
  The <dfn>iterator result</dfn> for a [=value pair=] |pair| and a kind |kind| is given by the
  following steps:

    1.  Let |result| be a value determined by the value of |kind|:
        <dl class="switch">
             :  "<code>key</code>"
             :: 1.  Let |idlKey| be |pair|'s [=value pair/key=].
                1.  Let |key| be the result of [=converted to a JavaScript value|converting=] |idlKey| to a JavaScript value.
                1.  |result| is |key|.
             :  "<code>value</code>"
             :: 1.  Let |idlValue| be |pair|'s [=value pair/value=].
                1.  Let |value| be the result of [=converted to a JavaScript value|converting=] |idlValue| to a JavaScript value.
                1.  |result| is |value|.
             :  "<code>key+value</code>"
             :: 1.  Let |idlKey| be |pair|'s [=value pair/key=].
                1.  Let |idlValue| be |pair|'s [=value pair/value=].
                1.  Let |key| be the result of [=converted to a JavaScript value|converting=] |idlKey| to a JavaScript value.
                1.  Let |value| be the result of [=converted to a JavaScript value|converting=] |idlValue| to a JavaScript value.
                1.  Let |array| be [=!=] [$ArrayCreate$](2).
                1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|array|, "<code>0</code>", |key|).
                1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|array|, "<code>1</code>", |value|).
                1.  |result| is |array|.
        </dl>
    1.  Return [$CreateIteratorResultObject$](|result|, <emu-val>false</emu-val>).
</div>

<div algorithm="to invoke the next property of iterators">

    An [=iterator prototype object=] must have a <code class="idl">next</code> data property with attributes
    { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
    and whose value is a [=built-in function object=] that behaves as follows:

    1.  Let |interface| be the [=interface=] for which the
        [=iterator prototype object=] exists.
    1.  Let |thisValue| be the <emu-val>this</emu-val> value.
    1.  Let |object| be [=?=] <a abstract-op>ToObject</a>(|thisValue|).
    1.  If |object| [=is a platform object=],
        then [=perform a security check=], passing:
        *   the platform object |object|,
        *   the identifier "<code>next</code>", and
        *   the type "<code>method</code>".
    1.  If |object| is not a [=default iterator object=] for |interface|,
        then [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Let |index| be |object|'s [=default iterator object/index=].
    1.  Let |kind| be |object|'s [=default iterator object/kind=].
    1.  Let |values| be |object|'s [=default iterator object/target=]'s [=value pairs to iterate over=].
    1.  Let |len| be the length of |values|.
    1.  If |index| is greater than or equal to |len|, then
        return <a abstract-op>CreateIteratorResultObject</a>(<emu-val>undefined</emu-val>, <emu-val>true</emu-val>).
    1.  Let |pair| be the entry in |values| at index |index|.
    1.  Set |object|'s index to |index| + 1.
    1.  Return the [=iterator result=] for |pair| and |kind|.
</div>

The [=class string=] of an [=iterator prototype object=] for a given [=interface=]
is the result of concatenating the [=identifier=] of the [=interface=]
and the string "<code> Iterator</code>".

<h4 id="js-asynchronous-iterable" oldids="es-asynchronous-iterable">Asynchronous iterable declarations</h4>

<div algorithm>
    To <dfn>define the asynchronous iteration methods</dfn> of [=interface=] |definition| on
    |target|, given [=realm=] |realm|, run the following steps:

    1.  If |definition| does not have an an [=asynchronously iterable declaration=] (of either
        sort), then return.
    1.  Assert: |definition| does not have an [=indexed property getter=] or an
        [=iterable declaration=].
    1.  If |definition| has a [=pair asynchronously iterable declaration=], then define the
        {{%Symbol.asyncIterator%}} and <code class="idl">entries</code> methods:
        1.  Let |steps| be the following series of steps, given function argument values |args|:
            1.  Let |jsValue| be [=?=] [$ToObject$](<emu-val>this</emu-val> value).
            1.  If |jsValue| [=is a platform object=], then [=perform a security check=], passing
                |jsValue|, "<code>%Symbol.asyncIterator%</code>", and "<code>method</code>".
            1.  If |jsValue| does not [=implement=] |definition|, then [=JavaScript/throw=] a
                <l spec=ecmascript>{{TypeError}}</l>.
            1.  Let |idlObject| be the IDL [=interface type=] value that represents a reference to
                |jsValue|.
            1.  Let |idlArgs| be the result of
                [=converting arguments for an asynchronous iterator method=] given |args|.
            1.  Let |iterator| be a newly created [=default asynchronous iterator object=] for
                |definition| with |idlObject| as its
                [=default asynchronous iterator object/target=], "<code>key+value</code>" as its
                [=default asynchronous iterator object/kind=], and
                [=default asynchronous iterator object/is finished=] set to false.
            1.  Run the [=asynchronous iterator initialization steps=] for |definition| with
                |idlObject|, |iterator|, and |idlArgs|, if any such steps exist.
            1.  Return |iterator|.
        1.  Let |F| be [$CreateBuiltinFunction$](|steps|, « », |realm|).
        1.  Perform [$SetFunctionName$](|F|, "<code>entries</code>").
        1.  Perform [$SetFunctionLength$](|F|, 0).
        1.  Perform [$DefineMethodProperty$](|target|, {{%Symbol.asyncIterator%}}, |F|, false).
        1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|target|, "<code>entries</code>", |F|).
    1.  If |definition| has a [=pair asynchronously iterable declaration=], then define the
        <code class="idl">keys</code> method:
        1.  Let |steps| be the following series of steps, given function argument values |args|:
            1.  Let |jsValue| be [=?=] [$ToObject$](<emu-val>this</emu-val> value).
            1.  If |jsValue| [=is a platform object=], then [=perform a security check=], passing
                |jsValue|, "<code>keys</code>", and "<code>method</code>".
            1.  If |jsValue| does not [=implement=] |definition|, then [=JavaScript/throw=] a
                <l spec=ecmascript>{{TypeError}}</l>.
            1.  Let |idlObject| be the IDL [=interface type=] value that represents a reference to
                |jsValue|.
            1.  Let |idlArgs| be the result of
                [=converting arguments for an asynchronous iterator method=] given |args|.
            1.  Let |iterator| be a newly created [=default asynchronous iterator object=] for
                |definition| with |idlObject| as its
                [=default asynchronous iterator object/target=], "<code>key</code>" as its
                [=default asynchronous iterator object/kind=], and
                [=default asynchronous iterator object/is finished=] set to false.
            1.  Run the [=asynchronous iterator initialization steps=] for |definition| with
                |idlObject|, |iterator|, and |idlArgs|, if any such steps exist.
            1.  Return |iterator|.
        1.  Let |F| be [$CreateBuiltinFunction$](|steps|, « », |realm|).
        1.  Perform [$SetFunctionName$](|F|, "<code>keys</code>").
        1.  Perform [$SetFunctionLength$](|F|, 0).
        1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|target|, "<code>keys</code>", |F|).
    1.  Define the <code class="idl">values</code>, and possibly {{%Symbol.asyncIterator%}}, methods:
        1.  Let |steps| be the following series of steps, given function argument values |args|:
            1.  Let |jsValue| be [=?=] [$ToObject$](<emu-val>this</emu-val> value).
            1.  If |jsValue| [=is a platform object=], then [=perform a security check=], passing
                |jsValue|, "<code>values</code>", and "<code>method</code>".
            1.  If |jsValue| does not [=implement=] |definition|, then [=JavaScript/throw=] a
                <l spec=ecmascript>{{TypeError}}</l>.
            1.  Let |idlObject| be the IDL [=interface type=] value that represents a reference to
                |jsValue|.
            1.  Let |idlArgs| be the result of
                [=converting arguments for an asynchronous iterator method=] given |args|.
            1.  Let |iterator| be a newly created [=default asynchronous iterator object=] for
                |definition| with |idlObject| as its
                [=default asynchronous iterator object/target=], "<code>value</code>" as its
                [=default asynchronous iterator object/kind=], and
                [=default asynchronous iterator object/is finished=] set to false.
            1.  Run the [=asynchronous iterator initialization steps=] for |definition| with
                |idlObject|, |iterator|, and |idlArgs|, if any such steps exist.
            1.  Return |iterator|.
        1.  Let |F| be [$CreateBuiltinFunction$](|steps|, « », |realm|).
        1.  Perform [$SetFunctionName$](|F|, "<code>values</code>").
        1.  Perform [$SetFunctionLength$](|F|, 0).
        1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|target|, "<code>values</code>", |F|).
        1.  If |definition| has a [=value asynchronously iterable declaration=], then perform [=!=]
            [$DefineMethodProperty$](|target|, {{%Symbol.asyncIterator%}}, |F|, false).
</div>

<div algorithm>
    To <dfn lt="converting arguments for an asynchronous iterator method">convert arguments for an asynchronous iterator method</dfn>,
    given an [=interface=] |definition| that has an [=asynchronously iterable declaration=] and a
    [=list=] of JavaScript values |args|:

    1.  Let |idlArgs| be an empty list.
    1.  Let |argCount| be the number of arguments of |definition|'s
        [=asynchronously iterable declaration=], or 0 if the [=asynchronously iterable declaration=]
        does not have an argument list.
    1.  Let |i| be 0.
    1.  While |i| &lt; |argCount|:
        1.  If |i| ≥ |args|'s [=list/size=], or if |args|[|i|] is <emu-val>undefined</emu-val>,
            then:
            1.  If the argument to the [=asynchronously iterable declaration=] at index |i| is
                declared with a [=optional argument/default value=], then [=list/append=] that
                default value to |idlArgs|.
            1.  Otherwise, [=list/append=] to |idlArgs| the special value "missing".
        1.  Otherwise, [=list/append=] to |idlArgs| the result of
            [=converted to an IDL value|converting=] |args|[|i|] to the IDL type given in the
            [=asynchronously iterable declaration=]'s argument list at index |i|.
        1.  Set |i| to |i| + 1.
    1.  Return |idlArgs|.

    <p class="note">This is essentially a hyper-specialization of the
    [=overload resolution algorithm=] for the case where no overloads are allowed and all arguments
    are optional.</p>
</div>

<h5 id="js-default-asynchronous-iterator-object" oldids="es-default-asynchronous-iterator-object">Default asynchronous iterator objects</h5>

A <dfn id="dfn-default-asynchronous-iterator-object" export>default asynchronous iterator
object</dfn> for a given [=interface=], target and iteration kind is an object whose \[[Prototype]]
[=/internal slot=] is the [=asynchronous iterator prototype object=] for the [=interface=].

A [=default asynchronous iterator object=] has internal values:

*   its <dfn for="default asynchronous iterator object">target</dfn>, which is an object whose
    values are to be iterated,
*   its <dfn for="default asynchronous iterator object">kind</dfn>, which is the iteration kind,
*   its <dfn for="default asynchronous iterator object">ongoing promise</dfn>, which is a
    {{Promise}} or null,
*   its <dfn for="default asynchronous iterator object">is finished</dfn>, which is a boolean.

Note: [=Default asynchronous iterator objects=] do not have [=class strings=]; when
<code class="idl">Object.prototype.toString()</code> is called on a
[=default asynchronous iterator object=] of a given [=interface=], the [=class string=] of the
[=asynchronous iterator prototype object=] of that [=interface=] is used.


<h5 id="js-asynchronous-iterator-prototype-object" oldids="es-asynchronous-iterator-prototype-object">Asynchronous iterator prototype object</h5>

The
<dfn id="dfn-asynchronous-iterator-prototype-object" export>asynchronous iterator prototype object</dfn>
for a given [=interface=] is an object that exists for every interface that has an
[=asynchronously iterable declaration=].
It serves as the prototype for [=default asynchronous iterator objects=] for the interface.

The \[[Prototype]] [=/internal slot=] of an [=asynchronous iterator prototype object=] must be
{{%AsyncIteratorPrototype%}}.

<div algorithm="to invoke the next property of asynchronous iterators">

    An [=asynchronous iterator prototype object=] must have a <code class="idl">next</code> data
    property with attributes { \[[Writable]]: <emu-val>true</emu-val>,
    \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
    and whose value is a [=built-in function object=] that behaves as follows:

    1.  Let |interface| be the [=interface=] for which the
        [=asynchronous iterator prototype object=] exists.

    1.  Let |thisValidationPromiseCapability| be [=!=] [$NewPromiseCapability$]({{%Promise%}}).

    1.  Let |thisValue| be the <emu-val>this</emu-val> value.
    1.  Let |object| be <a abstract-op>Completion</a>(<a abstract-op>ToObject</a>(|thisValue|)).

    1.  [$IfAbruptRejectPromise$](|object|, |thisValidationPromiseCapability|).

    1.  If |object| [=is a platform object=], then [=perform a security check=], passing:
        *   the platform object |object|,
        *   the identifier "<code>next</code>", and
        *   the type "<code>method</code>".

        If this threw an exception |e|, then:
        1.  Perform [=!=] [$Call$](|thisValidationPromiseCapability|.\[[Reject]],
            <emu-val>undefined</emu-val>, « |e| »).
        1.  Return |thisValidationPromiseCapability|.\[[Promise]].

    1.  If |object| is not a [=default asynchronous iterator object=] for |interface|, then:
        1.  Let |error| be a new <l spec=ecmascript>{{TypeError}}</l>.
        1.  Perform [=!=] [$Call$](|thisValidationPromiseCapability|.\[[Reject]],
            <emu-val>undefined</emu-val>, « |error| »).
        1.  Return |thisValidationPromiseCapability|.\[[Promise]].

    1.  Let |nextSteps| be the following steps:
        1.  Let |nextPromiseCapability| be [=!=] [$NewPromiseCapability$]({{%Promise%}}).
        1.  If |object|'s [=default asynchronous iterator object/is finished=] is true, then:
            1.  Let |result| be [$CreateIteratorResultObject$](<emu-val>undefined</emu-val>,
                <emu-val>true</emu-val>).
            1.  Perform [=!=] [$Call$](|nextPromiseCapability|.\[[Resolve]],
                <emu-val>undefined</emu-val>, « |result| »).
            1.  Return |nextPromiseCapability|.\[[Promise]].
        1.  Let |kind| be |object|'s [=default asynchronous iterator object/kind=].
        1.  Let |nextPromise| be the result of
            [=get the next iteration result|getting the next iteration result=] with |object|'s
            [=default asynchronous iterator object/target=] and |object|.
        1.  Let |fulfillSteps| be the following steps, given |next|:
            1.  Set |object|'s [=default asynchronous iterator object/ongoing promise=] to
                null.
            1.  If |next| is [=end of iteration=], then:
                1.  Set |object|'s [=default asynchronous iterator object/is finished=] to true.
                1.  Return [$CreateIteratorResultObject$](<emu-val>undefined</emu-val>,
                    <emu-val>true</emu-val>).
            1.  Otherwise, if |interface| has a [=pair asynchronously iterable declaration=]:
                1.  Assert: |next| is a [=value pair=].
                1.  Return the [=iterator result=] for |next| and |kind|.
            1.  Otherwise:
                1.  Assert: |interface| has a [=value asynchronously iterable declaration=].
                1.  Assert: |next| is a value of the type that appears in the declaration.
                1.  Let |value| be |next|, [=converted to a JavaScript value=].
                1.  Return [$CreateIteratorResultObject$](|value|, <emu-val>false</emu-val>).
        1.  Let |onFulfilled| be [$CreateBuiltinFunction$](|fulfillSteps|, « »).
        1.  Let |rejectSteps| be the following steps, given |reason|:
            1.  Set |object|'s [=default asynchronous iterator object/ongoing promise=] to
                null.
            1.  Set |object|'s [=default asynchronous iterator object/is finished=] to true.
            1.  [=JavaScript/Throw=] |reason|.
        1.  Let |onRejected| be [$CreateBuiltinFunction$](|rejectSteps|, « »).
        1.  Perform [$PerformPromiseThen$](|nextPromise|, |onFulfilled|, |onRejected|,
            |nextPromiseCapability|).
        1.  Return |nextPromiseCapability|.\[[Promise]].

    1.  Let |ongoingPromise| be |object|'s [=default asynchronous iterator object/ongoing promise=].

    1.  If |ongoingPromise| is not null, then:
        1.  Let |afterOngoingPromiseCapability| be [=!=] [$NewPromiseCapability$]({{%Promise%}}).
        1.  Let |onSettled| be [$CreateBuiltinFunction$](|nextSteps|, « »).
        1.  Perform [$PerformPromiseThen$](|ongoingPromise|, |onSettled|, |onSettled|,
            |afterOngoingPromiseCapability|).
        1.  Set |object|'s [=default asynchronous iterator object/ongoing promise=] to
            |afterOngoingPromiseCapability|.\[[Promise]].

    1.  Otherwise:
        1.  Set |object|'s [=default asynchronous iterator object/ongoing promise=] to the result of
            running |nextSteps|.

    1.  Return |object|'s [=default asynchronous iterator object/ongoing promise=].
</div>

<div algorithm="to invoke the return property of asynchronous iterators">

    If an [=asynchronous iterator return=] algorithm is defined for the [=interface=], then the
    [=asynchronous iterator prototype object=] must have a <code class="idl">return</code> data
    property with attributes { \[[Writable]]: <emu-val>true</emu-val>,
    \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
    and whose value is a [=built-in function object=], taking one argument |value|, that behaves as
    follows:

    1.  Let |interface| be the [=interface=] for which the
        [=asynchronous iterator prototype object=] exists.

    1.  Let |returnPromiseCapability| be [=!=] [$NewPromiseCapability$]({{%Promise%}}).

    1.  Let |thisValue| be the <emu-val>this</emu-val> value.
    1.  Let |object| be <a abstract-op>Completion</a>(<a abstract-op>ToObject</a>(|thisValue|)).

    1.  [$IfAbruptRejectPromise$](|object|, |returnPromiseCapability|).

    1.  If |object| [=is a platform object=], then [=perform a security check=], passing:
        *   the platform object |object|,
        *   the identifier "<code>return</code>", and
        *   the type "<code>method</code>".

        If this threw an exception |e|, then:
        1.  Perform [=!=] [$Call$](|returnPromiseCapability|.\[[Reject]],
            <emu-val>undefined</emu-val>, « |e| »).
        1.  Return |returnPromiseCapability|.\[[Promise]].

    1.  If |object| is not a [=default asynchronous iterator object=] for |interface|, then:
        1.  Let |error| be a new <l spec=ecmascript>{{TypeError}}</l>.
        1.  Perform [=!=] [$Call$](|returnPromiseCapability|.\[[Reject]],
            <emu-val>undefined</emu-val>, « |error| »).
        1.  Return |returnPromiseCapability|.\[[Promise]].

    1.  Let |returnSteps| be the following steps:
        1.  Let |returnPromiseCapability| be [=!=] [$NewPromiseCapability$]({{%Promise%}}).
        1.  If |object|'s [=default asynchronous iterator object/is finished=] is true, then:
            1.  Let |result| be [$CreateIteratorResultObject$](|value|, <emu-val>true</emu-val>).
            1.  Perform [=!=] [$Call$](|returnPromiseCapability|.\[[Resolve]],
                <emu-val>undefined</emu-val>, « |result| »).
            1.  Return |returnPromiseCapability|.\[[Promise]].
        1.  Set |object|'s [=default asynchronous iterator object/is finished=] to true.
        1.  Return the result of running the [=asynchronous iterator return=] algorithm for
            |interface|, given |object|'s [=default asynchronous iterator object/target=], |object|,
            and |value|.

    1.  Let |ongoingPromise| be |object|'s [=default asynchronous iterator object/ongoing promise=].

    1.  If |ongoingPromise| is not null, then:
        1.  Let |afterOngoingPromiseCapability| be [=!=] [$NewPromiseCapability$]({{%Promise%}}).
        1.  Let |onSettled| be [$CreateBuiltinFunction$](|returnSteps|, « »).
        1.  Perform [$PerformPromiseThen$](|ongoingPromise|, |onSettled|, |onSettled|,
            |afterOngoingPromiseCapability|).
        1.  Set |object|'s [=default asynchronous iterator object/ongoing promise=] to
            |afterOngoingPromiseCapability|.\[[Promise]].

    1.  Otherwise:
        1.  Set |object|'s [=default asynchronous iterator object/ongoing promise=] to the result of
            running |returnSteps|.

    1.  Let |fulfillSteps| be the following steps:
        1.  Return [$CreateIteratorResultObject$](|value|, <emu-val>true</emu-val>).

    1.  Let |onFulfilled| be [$CreateBuiltinFunction$](|fulfillSteps|, « »).

    1.  Perform [$PerformPromiseThen$](|object|'s [=default asynchronous iterator object/ongoing
        promise=], |onFulfilled|, <emu-val>undefined</emu-val>, |returnPromiseCapability|).

    1.  Return |returnPromiseCapability|.\[[Promise]].
</div>

The [=class string=] of an [=asynchronous iterator prototype object=] for a given [=interface=] is
the result of concatenating the [=identifier=] of the [=interface=] and the string
"<code> AsyncIterator</code>".


<h4 id="js-maplike" oldids="es-maplike">Maplike declarations</h4>

If an [=interface=] |A| is declared with
a [=maplike declaration=], then
there exists a number of additional properties on |A|'s
[=interface prototype object=].
These additional properties are described in the sub-sections below.

<h5 id="js-map-size" oldids="es-map-size">size</h5>

There must exist a <code class="idl">size</code> property on
|A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes
    { \[[Get]]: |G|, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> },
    where |G| is the interface's <dfn id="dfn-map-size-getter" export>map size getter</dfn>,
    defined below.
*   <div algorithm="to invoke the size method of Maps">

        The [=map size getter=] is a [=built-in function object=]
        whose behavior when invoked is as follows:

        1.  Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>size</code>" and type "<code>getter</code>".
        1.  Let |map| be the [=map entries=] of the IDL value
            that represents a reference to |O|.
        1.  Return |map|'s [=map/size=], [=converted to a JavaScript value=].
    </div>

    The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>0</emu-val>.

    The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>get size</code>".


<h5 id="js-map-iterator" oldids="es-map-iterator,es-iterator, es-iterators">%Symbol.iterator%</h5>

There must exist a data property whose name is the {{%Symbol.iterator%}} symbol on
|A|'s [=interface prototype object=]
with attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
and whose value is the [=function object=] that is the value of
the <code>entries</code> property.

<div algorithm>
    To <dfn>create a map iterator</dfn>
    from a [=/map=] |map|
    and a |kind| which is either "<code>key+value</code>", "<code>key</code>", or "<code>value</code>":

    1. Let |closure| be a new [=/Abstract Closure=] with no parameters
        that captures |map| and |kind| and performs the following steps when called:
        1. [=map/For each=] |key| → |value| of |map|:
            1. Set |key| and |value| to each [=converted to a JavaScript value=].
            1. If |kind| is "<code>key</code>", let |result| be |key|.
            1. Else if |kind| is "<code>value</code>", let |result| be |value|.
            1. Else, let |result| be [$CreateArrayFromList$](« |key|, |value| »).
            1. Perform [=?=] [$GeneratorYield$]([$CreateIteratorResultObject$](|result|, <emu-val>false</emu-val>)).

            Note: The [=map/size=] of |map|, and the order of its entries,
            might have changed while execution of this abstract operation
            was paused by [$Yield$].
        1. Return <emu-val>undefined</emu-val>.
    1. Return [$CreateIteratorFromClosure$](|closure|, "<code>%MapIteratorPrototype%</code>", {{%MapIteratorPrototype%}}).
</div>


<h5 id="js-map-entries" oldids="es-map-entries">entries</h5>

There must exist an <code class="idl">entries</code> data property on
|A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    whose behavior when invoked is as follows:

    <div algorithm="to invoke the entries method of Maps">
        1. Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>entries</code>" and type "<code>method</code>".
        1.  Let |map| be the [=map entries=] of the IDL value
            that represents a reference to |O|.
        1. Return the result of [=creating a map iterator=] from |map| with kind "<code>key+value</code>".
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>0</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>entries</code>".

<h5 id="js-map-keys" oldids="es-map-keys,es-map-keys-values">keys</h5>

There must exist a <code class="idl">keys</code> data property on
|A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    whose behavior when invoked is as follows:

    <div algorithm="to invoke the keys method of Maps">
        1. Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>keys</code>" and type "<code>method</code>".
        1.  Let |map| be the [=map entries=] of the IDL value
            that represents a reference to |O|.
        1. Return the result of [=creating a map iterator=] from |map| with kind "<code>key</code>".
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>0</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>keys</code>".


<h5 id="js-map-values" oldids="es-map-values">values</h5>

There must exist a <code class="idl">values</code> data property on
|A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    whose behavior when invoked is as follows:

    <div algorithm="to invoke the values method of Maps">
        1. Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>values</code>" and type "<code>method</code>".
        1.  Let |map| be the [=map entries=] of the IDL value
            that represents a reference to |O|.
        1. Return the result of [=creating a map iterator=] from |map| with kind "<code>value</code>".
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>0</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>values</code>".


<h5 id="js-map-forEach" oldids="es-map-forEach,es-forEach">forEach</h5>

There must exist a <code class="idl">forEach</code> data property on
|A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    whose behavior when invoked is as follows:

    <div algorithm="to invoke the forEach method of Maps">
        1. Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>forEach</code>" and type "<code>method</code>".
        1.  Let |map| be the [=map entries=] of the IDL value
            that represents a reference to |O|.
        1.  Let |callbackFn| be the first argument passed to the function, or <emu-val>undefined</emu-val> if not supplied.
        1.  If [$IsCallable$](|callbackFn|) is <emu-val>false</emu-val>, [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
        1.  Let |thisArg| be the second argument passed to the function, or <emu-val>undefined</emu-val> if not supplied.
        1. [=map/For each=] |key| → |value| of |map|:
            1. Let |jsKey| and |jsValue| be |key| and |value| [=converted to a JavaScript value=].
            1. Perform [=?=] [$Call$](|callbackFn|, |thisArg|, « |jsValue|, |jsKey|, |O| »).
        1.  Return <emu-val>undefined</emu-val>.
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>1</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>forEach</code>".


<h5 id="js-map-get" oldids="es-map-get,es-map-get-has">get</h5>

There must exist a <code class="idl">get</code> data property on
|A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    that behaves as follows when invoked:

    <div algorithm="to invoke the get method of Maps">
        1.  Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>get</code>" and type "<code>method</code>".
        1.  Let |map| be the [=map entries=] of the IDL value
            that represents a reference to |O|.
        1.  Let |keyType| be the key type specified in the [=maplike declaration=].
        1.  Let |keyArg| be the first argument passed to this function, or <emu-val>undefined</emu-val> if not supplied.
        1.  Let |key| be |keyArg| [=converted to an IDL value=] of type |keyType|.
        1.  If |key| is -0, set |key| to +0.
        1.  If |map|[|key|] [=map/exists=], then return |map|[|key|],
            [=converted to a JavaScript value=].
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>1</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>get</code>".


<h5 id="js-map-has" oldids="es-map-has">has</h5>

There must exist a <code class="idl">has</code> data property on
|A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    that behaves as follows when invoked:

    <div algorithm="to invoke the has method of Maps">
        1.  Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>has</code>" and type "<code>method</code>".
        1.  Let |map| be the [=map entries=] of the IDL value
            that represents a reference to |O|.
        1.  Let |keyType| be the key type specified in the [=maplike declaration=].
        1.  Let |keyArg| be the first argument passed to this function, or <emu-val>undefined</emu-val> if not supplied.
        1.  Let |key| be |keyArg| [=converted to an IDL value=] of type |keyType|.
        1.  If |key| is -0, set |key| to +0.
        1.  If |map|[|key|] [=map/exists=], then return <emu-val>true</emu-val>;
            otherwise return <emu-val>false</emu-val>.
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>1</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>has</code>".


<h5 id="js-map-set" oldids="es-map-set">set</h5>

If |A| does not declare a [=member=] with identifier "<code>set</code>",
and |A| was declared with a read–write maplike declaration,
then there must exist a <code class="idl">set</code> data property
on |A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    that behaves as follows when invoked:

    <div algorithm="to invoke the set method of Maps">
        1.  Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>set</code>" and type "<code>method</code>".
        1.  Let |map| be the [=map entries=] of the IDL value
            that represents a reference to |O|.
        1.  Let |keyType| be the key type specified in the [=maplike declaration=], and |valueType| be the value type.
        1.  Let |keyArg| be the first argument passed to this function, or <emu-val>undefined</emu-val> if not supplied.
        1.  Let |key| be |keyArg| [=converted to an IDL value=] of type |keyType|.
        1.  If |key| is -0, set |key| to +0.
        1.  Let |valueArg| be the second argument passed to this function, or <emu-val>undefined</emu-val> if not supplied.
        1.  Let |value| be |valueArg| [=converted to an IDL value=] of type |valueType|.
        1.  [=map/Set=] |map|[|key|] to |value|.
        1.  Return |O|.
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>2</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>set</code>".

If the interface does declare a <code class=idl>set</code> method,
it should similarly map a -0 key to +0,
and must return [=this=].


<h5 id="js-map-delete" oldids="es-map-delete">delete</h5>

If |A| does not declare a [=member=] with identifier "<code>delete</code>",
and |A| was declared with a read–write maplike declaration,
then there must exist a <code class="idl">delete</code> data property
on |A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    that behaves as follows when invoked:

    <div algorithm="to invoke the delete method of Maps">
        1.  Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>delete</code>" and type "<code>method</code>".
        1.  Let |map| be the [=map entries=] of the IDL value
            that represents a reference to |O|.
        1.  Let |keyType| be the key type specified in the [=maplike declaration=].
        1.  Let |keyArg| be the first argument passed to this function, or <emu-val>undefined</emu-val> if not supplied.
        1.  Let |key| be |keyArg| [=converted to an IDL value=] of type |keyType|.
        1.  If |key| is -0, set |key| to +0.
        1.  Let |retVal| be <emu-val>true</emu-val> if |map|[|key|] exists,
            or else <emu-val>false</emu-val>.
        1.  [=map/Remove=] |map|[|key|].
        1.  Return |retVal|.
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>1</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>delete</code>".

If the interface does declare a <code class=idl>delete</code> method,
it should similarly map a -0 key to +0,
and must return a {{boolean}} indicating whether the key was present or not.


<h5 id="js-map-clear" oldids="es-map-clear">clear</h5>

If |A| does not declare a [=member=] with identifier "<code>clear</code>",
and |A| was declared with a read–write maplike declaration,
then there must exist a <code class="idl">clear</code> data property
on |A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    that behaves as follows when invoked:

    <div algorithm="to invoke the clear method of Maps">
        1.  Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>clear</code>" and type "<code>method</code>".
        1.  Let |map| be the [=map entries=] of the IDL value
            that represents a reference to |O|.
        1.  [=map/Clear=] |map|.

            Note: The [=/map=] is preserved because there may be existing
            iterators, currently suspended, iterating over it.
        1.  Return <emu-val>undefined</emu-val>.
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>0</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>clear</code>".

If the interface does declare a <code class=idl>clear</code> method,
it must preserve the [=map entries=] object (rather than generating a new one)
and must return {{undefined}}.


<h4 id="js-setlike" oldids="es-setlike">Setlike declarations</h4>

If an [=interface=] |A| is declared with a [=setlike declaration=],
then there exists a number of additional properties on |A|'s [=interface prototype object=].
These additional properties are described in the sub-sections below.

<h5 id="js-set-size" oldids="es-set-size">size</h5>

A <code class="idl">size</code> property must exist on
|A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Get]]: |G|, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> },
    where |G| is the interface's <dfn id="dfn-set-size-getter" export>set size getter</dfn>,
    defined below.
*   <div algorithm="to invoke the size method of Sets">

        The [=set size getter=] is a [=built-in function object=]
        whose behavior when invoked is as follows:

        1.  Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>size</code>" and type "<code>getter</code>".
        1.  Let |set| be the [=set entries=] of the IDL value
            that represents a reference to |O|.
        1.  Return |set|'s [=set/size=], [=converted to a JavaScript value=].
    </div>

    The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>0</emu-val>.

    The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>get size</code>".


<h5 id="js-set-iterator" oldids="es-set-iterator">%Symbol.iterator%</h5>

There must exist a data property whose name is the {{%Symbol.iterator%}} symbol on
|A|'s [=interface prototype object=]
with attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>false</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
and whose value is the [=function object=] that is the value of
the <code class="idl">values</code> property.

<div algorithm>
    To <dfn>create a set iterator</dfn>
    from a [=/set=] |set|
    and a |kind| which is either "<code>key+value</code>" or "<code>value</code>":

    1. Let |closure| be a new [=/Abstract Closure=] with no parameters
        that captures |set| and |kind| and performs the following steps when called:
        1. [=set/For each=] |entry| of |set|:
            1. Set |entry| to be |entry| [=converted to a JavaScript value=].
            1. If |kind| is "<code>value</code>", let |result| be |entry|.
            1. Else, let |result| be [$CreateArrayFromList$](« |entry|, |entry| »).
            1. Perform [=?=] [$GeneratorYield$]([$CreateIteratorResultObject$](|result|, <emu-val>false</emu-val>)).

            Note: The [=set/size=] of |set|, and the order of its entries,
            might have changed while execution of this abstract operation
            was paused by [$Yield$].
        1. Return <emu-val>undefined</emu-val>.
    1. Return [$CreateIteratorFromClosure$](|closure|, "<code>%SetIteratorPrototype%</code>", {{%SetIteratorPrototype%}}).
</div>


<h5 id="js-set-entries" oldids="es-set-entries,es-set-entries-keys">entries</h5>

There must exist an <code class="idl">entries</code> data property on
|A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    whose behavior when invoked is as follows:

    <div algorithm="to invoke the entries method of Sets">
        1. Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>entries</code>" and type "<code>method</code>".
        1.  Let |set| be the [=set entries=] of the IDL value
            that represents a reference to |O|.
        1. Return the result of [=creating a set iterator=] from |set| with kind "<code>key+value</code>".
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is
the Number value <emu-val>0</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is
the String value "<code>entries</code>".


<h5 id="js-set-keys" oldids="es-set-keys">keys</h5>

A <code class="idl">keys</code> data property must exist
on |A|'s [=interface prototype object=]
with attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }
and whose value is the [=function object=] that is the value of
the <code class="idl">values</code> property.


<h5 id="js-set-values" oldids="es-set-values">values</h5>

There must exist a <code class="idl">values</code> data property on
|A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    whose behavior when invoked is as follows:

    <div algorithm="to invoke the values method of Sets">
        1. Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>values</code>" and type "<code>method</code>".
        1.  Let |set| be the [=set entries=] of the IDL value
            that represents a reference to |O|.
        1. Return the result of [=creating a set iterator=] from |set| with kind "<code>value</code>".
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is
the Number value <emu-val>0</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is
the String value "<code>values</code>".


<h5 id="js-set-forEach" oldids="es-set-forEach">forEach</h5>

There must exist a <code class="idl">forEach</code> data property on
|A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    whose behavior when invoked is as follows:

    <div algorithm="to invoke the forEach method of Sets">
        1.  Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>forEach</code>" and type "<code>method</code>".
        1.  Let |set| be the [=set entries=] of the IDL value
            that represents a reference to |O|.
        1.  Let |callbackFn| be the first argument passed to the function, or <emu-val>undefined</emu-val> if not supplied.
        1.  If [$IsCallable$](|callbackFn|) is <emu-val>false</emu-val>, [=JavaScript/throw=] a <l spec=ecmascript>{{TypeError}}</l>.
        1.  Let |thisArg| be the second argument passed to the function, or <emu-val>undefined</emu-val> if not supplied.
        1. [=map/For each=] |value| of |set|:
            1. Let |jsValue| be |value| [=converted to a JavaScript value=].
            1. Perform [=?=] [$Call$](|callbackFn|, |thisArg|, « |jsValue|, |jsValue|, |O|»).
        1.  Return <emu-val>undefined</emu-val>.
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>1</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>forEach</code>".


<h5 id="js-set-has" oldids="es-set-has">has</h5>

There must exist a <code class="idl">has</code> data property on
|A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    that behaves as follows when invoked:

    <div algorithm="to invoke the has method of Sets">
        1.  Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>has</code>" and type "<code>method</code>".
        1.  Let |set| be the [=set entries=] of the IDL value
            that represents a reference to |O|.
        1.  Let |valueType| be the value type specified in the [=setlike declaration=].
        1.  Let |valueArg| be the first argument passed to this function, or <emu-val>undefined</emu-val> if not supplied.
        1.  Let |value| be |valueArg| [=converted to an IDL value=] of type |valueType|.
        1.  If |value| is -0, set |value| to +0.
        1.  If |set| [=set/contains=] |value|, then return <emu-val>true</emu-val>,
            otherwise return <emu-val>false</emu-val>.
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is a Number value <emu-val>1</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>has</code>".


<h5 id="js-set-add" oldids="es-set-add,es-add-delete">add</h5>

If |A| does not declare a [=member=] with identifier "<code>add</code>",
and |A| was declared with a read–write setlike declaration,
then there must exist an <code class="idl">add</code> data property
on |A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    that behaves as follows when invoked:

    <div algorithm="to invoke the add method of Sets">
        1.  Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>add</code>" and type "<code>method</code>".
        1.  Let |set| be the [=set entries=] of the IDL value
            that represents a reference to |O|.
        1.  Let |valueType| be the value type specified in the [=setlike declaration=].
        1.  Let |valueArg| be the first argument passed to this function, or <emu-val>undefined</emu-val> if not supplied.
        1.  Let |value| be |valueArg| [=converted to an IDL value=] of type |valueType|.
        1.  If |value| is -0, set |value| to +0.
        1.  [=set/Append=] |value| to |set|.
        1.  Return |O|.
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>1</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>add</code>".

If the interface does declare an <code class=idl>add</code> method,
it should similarly map a -0 value to +0,
and must return the value that was set.


<h5 id="js-set-delete" oldids="es-set-delete">delete</h5>

If |A| does not declare a [=member=] with identifier "<code>delete</code>",
and |A| was declared with a read–write setlike declaration,
then there must exist a <code class="idl">delete</code> data property
on |A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    that behaves as follows when invoked:

    <div algorithm="to invoke the delete method of Sets">
        1.  Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>delete</code>" and type "<code>method</code>".
        1.  Let |set| be |O|'s [=set entries=].
        1.  Let |valueType| be the value type specified in the [=setlike declaration=].
        1.  Let |valueArg| be the first argument passed to this function, or <emu-val>undefined</emu-val> if not supplied.
        1.  Let |value| be |valueArg| [=converted to an IDL value=] of type |valueType|.
        1.  If |value| is -0, set |value| to +0.
        1.  Let |retVal| be <emu-val>true</emu-val> if |set| [=set/contains=] |value|, or else <emu-val>false</emu-val>.
        1.  [=list/Remove=] |value| from |set|.
        1.  Return |retVal|.
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>1</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>delete</code>".

If the interface does declare a <code class=idl>delete</code> method,
it should similarly map a -0 value to +0,
and must return a {{boolean}} indicating whether the value was present or not.


<h5 id="js-set-clear" oldids="es-set-clear">clear</h5>

If |A| does not declare a [=member=] with identifier "<code>clear</code>",
and |A| was declared with a read–write setlike declaration,
then there must exist a <code class="idl">clear</code> data property
on |A|'s [=interface prototype object=]
with the following characteristics:

*   The property has attributes { \[[Writable]]: <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Configurable]]: <emu-val>true</emu-val> }.
*   The value of the property is a [=built-in function object=]
    that behaves as follows when invoked:

    <div algorithm="to invoke the clear method of Sets">
        1.  Let |O| be the <emu-val>this</emu-val> value, [=implementation-checked=] against <var ignore>A</var> with identifier "<code>clear</code>" and type "<code>method</code>".
        1.  Let |set| be the [=set entries=] of the IDL value
            that represents a reference to |O|.
        1.  [=set/Empty=] |set|.

            Note: The [=/set=] is preserved because there may be existing
            iterators, currently suspended, iterating over it.
        1.  Return <emu-val>undefined</emu-val>.
    </div>

The value of the [=function object=]'s <code class="idl">length</code> property is the Number value <emu-val>0</emu-val>.

The value of the [=function object=]'s <code class="idl">name</code> property is the String value "<code>clear</code>".

If the interface does declare a <code class=idl>clear</code> method,
it must preserve the [=set entries=] object (rather than generating a new one)
and must return {{undefined}}.


<h3 id="js-platform-objects" oldids="es-platform-objects">Platform objects implementing interfaces</h3>

<div algorithm>
    A JavaScript value |value| <dfn>is a platform object</dfn> if |value| [=is an Object=] and
    if |value| has a \[[PrimaryInterface]] internal slot.
</div>

<div algorithm>
    A JavaScript value |value| <dfn export>implements</dfn> an [=interface=] |interface|
    if |value| [=is a platform object=] and the [=inclusive inherited interfaces=] of
    |value|.\[[PrimaryInterface]] [=list/contains=] |interface|.

    Specifications may reference the concept "|object| implements |interface|"
    in various ways, including "|object| is an |interface| object".
</div>

Every [=platform object=] is associated with a [=realm=], just
as the [=initial objects=] are.
This realm is stored in the [=platform object=]'s \[[Realm]] slot.
It is the responsibility of specifications using Web IDL to state
which realm (or, by proxy, which global object) each platform
object is associated with.
In particular, the algorithms below associate the new [=platform object=] with
the realm given as an argument.

<div algorithm>
  To <dfn export lt=new>create a new object implementing the interface</dfn> |interface|, with a
  [=realm=] |realm|, perform the following steps:

    1.  Return the result of [=internally create a new object implementing the
        interface|internally creating a new object implementing=] |interface|, with |realm| and
        <emu-val>undefined</emu-val>.
</div>

<div algorithm>
  To <dfn>internally create a new object implementing the interface</dfn> |interface|, with a
  [=realm=] |realm| and a JavaScript value |newTarget|, perform the following steps:

    1.  Assert: |interface| is [=exposed=] in |realm|.
    1.  If |newTarget| is <emu-val>undefined</emu-val>, then:
        1.  Let |prototype| be the [=interface prototype object=] for |interface| in
            |realm|.
    1.  Otherwise:
        1.  Assert: [$IsCallable$](|newTarget|) is true.
        1.  Let |prototype| be [=?=] [$Get$](|newTarget|, "prototype").
        1.  If |prototype| [=is not an Object=], then:
            1.  Let |targetRealm| be [=?=] [$GetFunctionRealm$](|newTarget|).
            1.  Set |prototype| to the [=interface prototype object=] for |interface| in
                |targetRealm|.
    1.  Let |slots| be « \[[Prototype]], \[[Extensible]], \[[Realm]], \[[PrimaryInterface]] ».
    1.  If |interface| is {{DOMException}}, append \[[ErrorData]] to |slots|.
    1.  Let |instance| be [$MakeBasicObject$](|slots|).
    1.  Set |instance|.\[[Realm]] to |realm|.
    1.  Set |instance|.\[[PrimaryInterface]] to |interface|.
    1.  Set |instance|.\[[Prototype]] to |prototype|.
    1.  Let |interfaces| be the [=inclusive inherited interfaces=] of |interface|.
    1.  [=list/iterate|For every=] [=interface=] |ancestor interface| in |interfaces|:
        1.  Let |unforgeables| be the value of the \[[Unforgeables]] slot of the [=interface
            object=] of |ancestor interface| in |realm|.
        1.  Let |keys| be [=!=] |unforgeables|.\[[OwnPropertyKeys]]().
        1.  [=list|For each=] element |key| of |keys|:
            1.  Let |descriptor| be [=!=] |unforgeables|.\[[GetOwnProperty]](|key|).
            1.  Perform [=!=] [$DefinePropertyOrThrow$](|instance|, |key|, |descriptor|).
    1.  If |interface| is declared with the [{{Global}}] [=extended attribute=], then:
        1.  [=Define the regular operations=] of |interface| on |instance|, given |realm|.
        1.  [=Define the regular attributes=] of |interface| on |instance|, given |realm|.
        1.  [=Define the iteration methods=] of |interface| on |instance| given |realm|.
        1.  [=Define the asynchronous iteration methods=] of |interface| on |instance| given |realm|.
        1.  [=Define the global property references=] on |instance|, given |realm|.
        1.  Set |instance|.\[[SetPrototypeOf]] as defined in [[#platform-object-setprototypeof]].
    1.  Otherwise, if |interfaces| contains an [=interface=] which
        [=support indexed properties|supports indexed properties=],
        [=support named properties|named properties=], or both:
        1.  Set |instance|.\[[GetOwnProperty]] as defined in
            [[#legacy-platform-object-getownproperty]].
        1.  Set |instance|.\[[Set]] as defined in
            [[#legacy-platform-object-set]].
        1.  Set |instance|.\[[DefineOwnProperty]] as defined in
            [[#legacy-platform-object-defineownproperty]].
        1.  Set |instance|.\[[Delete]] as defined in
            [[#legacy-platform-object-delete]].
        1.  Set |instance|.\[[PreventExtensions]] as defined in
            [[#legacy-platform-object-preventextensions]].
        1.  Set |instance|.\[[OwnPropertyKeys]] as defined in
            [[#legacy-platform-object-ownpropertykeys]].
    1.  Return |instance|.
</div>

<div algorithm>
  To <dfn>define the global property references</dfn> on |target|, given [=realm=] |realm|,
  perform the following steps:

    1.  Let |interfaces| be a [=list=] that contains every [=interface=] that is [=exposed=] in
        |realm|.
    1.  Sort |interfaces| in such a way that if |A| and |B| are [=list/items=] of |interfaces|,
        and |A| [=interface/inherits=] from |B|, |A| has a higher index in |interfaces| than |B|.
    1.  [=list/iterate|For every=] |interface| of |interfaces|:
        1.  If |interface| is not declared with the [{{LegacyNoInterfaceObject}}] or
            [{{LegacyNamespace}}] [=extended attributes=], then:
            1.  Let |id| be |interface|'s [=identifier=].
            1.  Let |interfaceObject| be the result of [=create an interface object|creating
                an interface object=] for |interface| with |id| in |realm|.
            1.  Perform [$DefineMethodProperty$](|target|, |id|, |interfaceObject|, false).
            1.  If the |interface| is declared with a [{{LegacyWindowAlias}}] [=extended attribute=],
                and |target| implements the {{Window}} [=interface=], then:
                1.  [=list/iterate|For every=] [=LegacyWindowAlias identifier|identifier=] |id| in
                    [{{LegacyWindowAlias}}]'s [=LegacyWindowAlias identifier|identifiers=]:
                    1.  Perform [$DefineMethodProperty$](|target|, |id|, |interfaceObject|, false).
        1.  If the |interface| is declared with a [{{LegacyFactoryFunction}}] [=extended attribute=],
            then:
            1.  [=list/iterate|For every=] [=LegacyFactoryFunction identifier|identifier=] |id| in
                [{{LegacyFactoryFunction}}]'s [=LegacyFactoryFunction identifier|identifiers=]:
                1.  Let |legacyFactoryFunction| be the result of
                    [=create a legacy factory function|creating a legacy factory function=] with
                    |id| for |interface| in |realm|.
                1.  Perform [$DefineMethodProperty$](|target|, |id|, |legacyFactoryFunction|, false).
    1.  [=list/iterate|For every=] [=callback interface=] |interface| that is [=exposed=] in
        |realm| and on which [=constants=] are defined:
        1.  Let |id| be |interface|'s [=identifier=].
        1.  Let |interfaceObject| be the result of [=create a legacy callback interface
            object|creating a legacy callback interface object=] for |interface| with |id| in |realm|.
        1.  Perform [$DefineMethodProperty$](|target|, |id|, |interfaceObject|, false).
    1.  [=list/iterate|For every=] [=namespace=] |namespace| that is [=exposed=] in
        |realm|:
        1.  Let |id| be |namespace|'s [=identifier=].
        1.  Let |namespaceObject| be the result of [=create a namespace object|creating a namespace object=] for |namespace| in |realm|.
        1.  Perform [$DefineMethodProperty$](|target|, |id|, |namespaceObject|, false).
</div>

<div class="note">
  The set of interfaces that a [=platform object=] [=implements=] does not change over
  the lifetime of the object.

  Multiple [=platform objects=] with different [=realm/global objects=] will share
  a reference to the same [=interface=] in their \[[PrimaryInterface]] internal
  slots. For example, a page could contain a same-origin iframe, with the iframe's
  method being called on the main page's element of the same kind, with no exception
  thrown.

  [=Interface mixins=] do not participate directly in the evaluation of the [=implements=]
  algorithm. Instead, each [=interface=] that the [=interface mixin=] is [=included=] in
  has its own "copy" of each [=member=] of the [=interface mixin=], and the corresponding
  [=creating an operation function|operation function=] checks that the receiver [=implements=]
  the particular [=interface=] which [=includes=] the [=interface mixin=].
</div>

<div algorithm>
  The <dfn id="dfn-primary-interface" export>primary interface</dfn> of a [=platform object=] is
  the value of the object's \[[PrimaryInterface]] internal slot, which is the most-derived
  [=interface=] that it [=implements=].
</div>

The [=realm=] that a given [=platform object=]
is associated with can <dfn id="dfn-change-global-environment" for="realm" export>change</dfn> after it has been created.  When
the [=realm=] associated with a platform object is changed, its
\[[Prototype]] [=/internal slot=] must be immediately
updated to be the [=interface prototype object=]
of the [=primary interface=]
from the [=platform object=]'s newly associated [=realm=].

Additionally, [=platform objects=] which implement an [=interface=]
which has a [{{Global}}] [=extended attribute=]
get properties declaratively from:

* [[#js-stringifier]],
* [[#js-maplike]], and
* [[#js-setlike]].

Issue: Define those properties imperatively instead.

<h4 id="platform-object-setprototypeof" oldids="platformobjectsetprototypeof">\[[SetPrototypeOf]]</h4>

<div algorithm="to invoke the internal [[SetPrototypeOf]] method of a platform object that implements an interface with [Global] extended attribute">

    When the \[[SetPrototypeOf]] internal method of a [=platform object=] |O| that implements an
    [=interface=] with the [{{Global}}] [=extended attribute=] is called with
    JavaScript language value |V|, the following step is taken:

    1.  If |O|'s [=associated realm=]'s [=is global prototype chain mutable=] is true,
        return [=?=] [$OrdinarySetPrototypeOf$](|O|, |V|).
    1.  Return [=?=] <a abstract-op>SetImmutablePrototype</a>(|O|, |V|).

</div>

Note: For {{Window}} objects, it is unobservable whether this is implemented, since the presence of
the {{WindowProxy}} object ensures that \[[SetPrototypeOf]] is never called on a {{Window}} object
directly. For other global objects, however, this is necessary.


<h3 id="js-legacy-platform-objects" oldids="es-legacy-platform-objects,indexed-and-named-properties">Legacy platform objects</h3>

[=Legacy platform objects=] will appear to have additional properties that correspond to their
[=indexed properties|indexed=] and [=named properties=].  These properties are not “real” own
properties on the object, but are made to look like they are by being exposed
by the <a href="#legacy-platform-object-getownproperty">\[[GetOwnProperty]] internal method</a> .

It is permissible for an object to implement multiple interfaces that support indexed properties.
However, if so, and there are conflicting definitions as to the object's
[=supported property indices=],
then it is undefined what additional properties the object will appear to
have, or what its exact behavior will be with regard to its indexed properties.
The same applies for named properties.

The [=indexed property getter=]
that is defined on the derived-most interface that the
legacy platform object implements is the one that defines the behavior
when indexing the object with an [=array index=].  Similarly for
[=indexed property setters=].
This way, the definitions of these special operations from
ancestor interfaces can be overridden.

A property name is an <dfn id="dfn-unforgeable-property-name" export>unforgeable property name</dfn> on a
given platform object |O| if the object implements an [=interface=] that
has an [=interface member=] with that identifier
and that interface member is [=unforgeable=] on any of
the interfaces that |O| implements.

Support for [=getters=] is handled in [[#legacy-platform-object-getownproperty]],
and for [=setters=] in [[#legacy-platform-object-defineownproperty]]
and [[#legacy-platform-object-set]].

Additionally, [=legacy platform objects=] have internal methods as defined in:

* [[#legacy-platform-object-delete]],
* [[#legacy-platform-object-preventextensions]], and
* [[#legacy-platform-object-ownpropertykeys]].


<h4 id="legacy-platform-object-getownproperty" dfn oldids="getownproperty" lt=GetOwnProperty for="legacy platform object">\[[GetOwnProperty]]</h4>

<div algorithm="to invoke the [[GetOwnProperty]] internal method of legacy platform objects">

    The \[[GetOwnProperty]] internal method of every [=legacy platform object=] |O|
    must behave as follows when called with property name |P|:

    1. Return [=?=] <a abstract-op>LegacyPlatformObjectGetOwnProperty</a>(|O|, |P|, <emu-val>false</emu-val>).
</div>


<h4 id="legacy-platform-object-set" oldids="platformobjectset">\[[Set]]</h4>

<div algorithm="to invoke the [[Set]] internal method of legacy platform objects">

    The \[[Set]] internal method of every [=legacy platform object=] |O|
    must behave as follows when called with
    property name |P|, value |V|, and JavaScript language value |Receiver|:

    1.  If |O| and |Receiver| are the same object, then:
        1.  If |O| [=implements=] an interface with an [=indexed property setter=]
            and |P| [=is an array index=], then:
            1.  [=Invoke the indexed property setter=] on |O| with |P| and |V|.
            1.  Return <emu-val>true</emu-val>.
        1.  If |O| [=implements=] an interface with a [=named property setter=]
            and |P| [=is a String=], then:
            1.  [=Invoke the named property setter=] on |O| with |P| and |V|.
            1.  Return <emu-val>true</emu-val>.
    1.  Let |ownDesc| be [=?=] <a abstract-op>LegacyPlatformObjectGetOwnProperty</a>(|O|, |P|, <emu-val>true</emu-val>).
    1.  Perform [=?=] <a abstract-op>OrdinarySetWithOwnDescriptor</a>(|O|, |P|, |V|, |Receiver|, |ownDesc|).
</div>


<h4 id="legacy-platform-object-defineownproperty" oldids="defineownproperty">\[[DefineOwnProperty]]</h4>

<div algorithm="to invoke the [[DefineOwnProperty]] internal method of legacy platform objects">

    When the \[[DefineOwnProperty]] internal method of a [=legacy platform object=] |O|
    is called with property key |P| and [=Property Descriptor=] |Desc|,
    the following steps must be taken:

    1.  If |O| [=support indexed properties|supports indexed properties=] and
        |P| [=is an array index=], then:
        1.  If the result of calling <a abstract-op>IsDataDescriptor</a>(|Desc|) is
            <emu-val>false</emu-val>, then return
            <emu-val>false</emu-val>.
        1.  If |O| does not implement an interface with an
            [=indexed property setter=], then return <emu-val>false</emu-val>.
        1.  [=Invoke the indexed property setter=] on |O| with |P| and |Desc|.\[[Value]].
        1.  Return <emu-val>true</emu-val>.
    1.  If |O| [=support named properties|supports named properties=],
        |O| does not implement an [=interface=] with the [{{Global}}] [=extended attribute=],
        |P| [=is a String=],
        and |P| is not an [=unforgeable property name=]
        of |O|, then:
        1.  Let |creating| be true if |P| is not a [=supported property name=], and false otherwise.
        1.  If |O| [=implements=] an interface with the [{{LegacyOverrideBuiltIns}}]
            [=extended attribute=] or |O| does not have an own property
            named |P|, then:
            1.  If |creating| is false and |O| does not implement an
                interface with a [=named property setter=], then return <emu-val>false</emu-val>.
            1.  If |O| [=implements=] an interface with a
                [=named property setter=], then:
                1.  If the result of calling <a abstract-op>IsDataDescriptor</a>(|Desc|) is
                    <emu-val>false</emu-val>, then return
                    <emu-val>false</emu-val>.
                1.  [=Invoke the named property setter=] on |O| with |P| and |Desc|.\[[Value]].
                1.  Return <emu-val>true</emu-val>.
    1.  Return [=!=] <a abstract-op>OrdinaryDefineOwnProperty</a>(|O|, |P|, |Desc|).
</div>


<h4 id="legacy-platform-object-delete" oldids="delete">\[[Delete]]</h4>

<div algorithm="to invoke the [[Delete]] internal method of legacy platform objects">

    The \[[Delete]] internal method of every [=legacy platform object=] |O|
    must behave as follows when called with property name |P|.

    1.  If |O| [=support indexed properties|supports indexed properties=] and
        |P| [=is an array index=], then:
        1.  Let |index| be the result of calling [=!=] <a abstract-op>ToUint32</a>(|P|).
        1.  If |index| is not a [=supported property indices|supported property index=], then return <emu-val>true</emu-val>.
        1.  Return <emu-val>false</emu-val>.
    1.  If |O| [=support named properties|supports named properties=],
        |O| does not implement an [=interface=] with the [{{Global}}] [=extended attribute=]
        and the result of calling the [=named property visibility algorithm=]
        with property name |P| and object |O| is true, then:
        1.  If |O| does not implement an interface with a [=named property deleter=], then return <emu-val>false</emu-val>.
        1.  Let |operation| be the operation used to declare the named property deleter.
        1.  If |operation| was defined without an [=identifier=], then:
            1.  Perform the steps listed in the interface description to
                [=delete an existing named property=]
                with |P| as the name.
            1.  If the steps indicated that the deletion failed, then return <emu-val>false</emu-val>.
        1.  Otherwise, |operation| was defined with an identifier:
            1.  Perform [=method steps=] of |operation| with |O| as [=this=] and « |P| » as the
                argument values.
            1.  If |operation| was declared with a [=return type=] of {{boolean}}
                and the steps returned <emu-val>false</emu-val>, then return <emu-val>false</emu-val>.
        1.  Return <emu-val>true</emu-val>.
    1.  If |O| has an own property with name |P|, then:
        1.  If the property is not configurable, then return <emu-val>false</emu-val>.
        1.  Otherwise, remove the property from |O|.
    1.  Return <emu-val>true</emu-val>.
</div>


<h4 id="legacy-platform-object-preventextensions" oldids="preventextensions">\[[PreventExtensions]]</h4>

<div algorithm="to invoke the internal [[PreventExtensions]] method of legacy platform objects">

    When the \[[PreventExtensions]] internal method of a [=legacy platform object=] is called,
    the following steps are taken:

    1.  Return <emu-val>false</emu-val>.

    Note: this keeps [=legacy platform objects=] extensible by
    making \[[PreventExtensions]] fail for them.
</div>


<h4 id="legacy-platform-object-ownpropertykeys" oldids="property-enumeration,legacy-platform-object-property-enumeration">\[[OwnPropertyKeys]]</h4>

This document does not define a complete property enumeration order
for [=platform objects=] implementing [=interfaces=]
(or for <a href="#js-exception-objects">platform objects representing exceptions</a>).
However, it does for [=legacy platform objects=] by defining the \[[OwnPropertyKeys]]
internal method as follows.

<div algorithm="to invoke the internal [[OwnPropertyKeys]] method of legacy platform objects">

    When the \[[OwnPropertyKeys]] internal method of a [=legacy platform object=] |O| is called,
    the following steps are taken:

    1.  Let |keys| be a new empty [=list=] of JavaScript String and Symbol values.
    1.  If |O| [=support indexed properties|supports indexed properties=], then [=list|for each=] |index| of |O|'s
        [=supported property indices=], in ascending numerical order, [=list|append=] [=!=] <a abstract-op>ToString</a>(|index|) to
        |keys|.
    1.  If |O| [=support named properties|supports named properties=], then [=list|for each=] |P| of |O|'s
        [=supported property names=] that is visible according to the [=named property visibility algorithm=],
        [=list|append=] |P| to |keys|.
    1.  [=list|For each=] |P| of |O|'s own property keys that is a String, in ascending chronological order of
        property creation, [=list|append=] |P| to |keys|.
    1.  [=list|For each=] |P| of |O|'s own property keys that is a Symbol, in ascending chronological order of
        property creation, [=list|append=] |P| to |keys|.
    1.  Assert: |keys| has no duplicate items.
    1.  Return |keys|.

</div>

<h4 id="legacy-platform-object-abstract-ops">Abstract operations</h4>

<div algorithm="to determine if a property name is an array index">

    To determine if a property name |P| <dfn lt="is an array index|is not an array index"
    oldids="dfn-array-index-property-name">is an [=array index=]</dfn>, the following algorithm is
    applied:

    1.  If |P| [=is not a String=], then return <emu-val>false</emu-val>.
    1.  Let |index| be <a abstract-op>CanonicalNumericIndexString</a>(|P|).
    1.  If |index| is <emu-val>undefined</emu-val>, then return <emu-val>false</emu-val>.
    1.  If <a abstract-op>IsInteger</a>(|index|) is <emu-val>false</emu-val>,
        then return <emu-val>false</emu-val>.
    1.  If |index| is −0, then return <emu-val>false</emu-val>.
    1.  If |index| &lt; 0, then return <emu-val>false</emu-val>.
    1.  If |index| ≥ 2<sup>32</sup> − 1, then return <emu-val>false</emu-val>.

        Note: 2<sup>32</sup> − 1 is the maximum array length allowed by JavaScript.
    1.  Return <emu-val>true</emu-val>.

</div>

<div algorithm>

    The <dfn id="dfn-named-property-visibility" export>named property visibility algorithm</dfn>
    is used to determine if a given named property is exposed on an object.
    Some named properties are not exposed on an object depending on whether
    the [{{LegacyOverrideBuiltIns}}] [=extended attribute=] was used.
    The algorithm operates as follows, with property name |P| and object |O|:

    1.  If |P| is not a [=supported property name=] of |O|, then return false.
    1.  If |O| has an own property named |P|, then return false.

          Note: This will include cases in which |O| has unforgeable properties,
          because in practice those are always set up before objects have any supported property names,
          and once set up will make the corresponding named properties invisible.

    1.  If |O| [=implements=] an interface that has the [{{LegacyOverrideBuiltIns}}]
        [=extended attribute=], then return true.
    1.  Let |prototype| be |O|.\[[GetPrototypeOf]]().
    1.  While |prototype| is not null:
        1.  If |prototype| is not a [=named properties object=],
            and |prototype| has an own property named |P|, then return false.
        1.  Set |prototype| to |prototype|.\[[GetPrototypeOf]]().
    1.  Return true.
</div>

<div class="note">

    This ensures that for objects with named properties, property resolution is done in the following order:

    1.  Indexed properties.
    1.  Own properties, including unforgeable attributes and operations.
    1.  Then, if [{{LegacyOverrideBuiltIns}}]:
        1.  Named properties.
        1.  Properties from the prototype chain.
    1.  Otherwise, if not [{{LegacyOverrideBuiltIns}}]:
        1.  Properties from the prototype chain.
        1.  Named properties.
</div>

<div algorithm>

    To <dfn id="invoke-indexed-setter" oldids="invoking-indexed-setter" export lt="invoke the indexed property setter">invoke an indexed property setter</dfn>
    on a [=platform object=] |O| with property name |P| and JavaScript value |V|, the following steps must be performed:

    1.  Let |index| be the result of calling [=?=] <a abstract-op>ToUint32</a>(|P|).
    1.  Let |creating| be true if |index| is not a [=supported property indices|supported property index=],
        and false otherwise.
    1.  Let |operation| be the operation used to declare the indexed property setter.
    1.  Let |T| be the type of the second argument of |operation|.
    1.  Let |value| be the result of [=converted to an IDL value|converting=] |V| to an IDL value of type |T|.
    1.  If |operation| was defined without an [=identifier=], then:
        1.  If |creating| is true, then perform the steps listed in the interface description to
            [=set the value of a new indexed property=]
            with |index| as the index and |value| as the value.
        1.  Otherwise, |creating| is false.  Perform the steps listed in the interface description to
            [=set the value of an existing indexed property=]
            with |index| as the index and |value| as the value.
    1.  Otherwise, |operation| was defined with an identifier.  Perform the [=method steps=] of
        |operation| with |O| as [=this=] and « |index|, |value| » as the argument values.
</div>

<div algorithm>

    To <dfn id="invoke-named-setter" oldids="invoking-named-setter" export lt="invoke the named property setter">invoke a named property setter</dfn>
    on a [=platform object=] |O| with property name |P| and JavaScript value |V|, the following steps must be performed:

    1.  Let |creating| be true if |P| is not a [=supported property name=], and false otherwise.
    1.  Let |operation| be the operation used to declare the named property setter.
    1.  Let |T| be the type of the second argument of |operation|.
    1.  Let |value| be the result of [=converted to an IDL value|converting=] |V| to an IDL value of type |T|.
    1.  If |operation| was defined without an [=identifier=], then:
        1.  If |creating| is true, then perform the steps listed in the interface description to
            [=set the value of a new named property=]
            with |P| as the name and |value| as the value.
        1.  Otherwise, |creating| is false.  Perform the steps listed in the interface description to
            [=set the value of an existing named property=]
            with |P| as the name and |value| as the value.
    1.  Otherwise, |operation| was defined with an identifier.  Perform the [=method steps=] of
        |operation| with |O| as [=this=] and « |P|, |value| » as the argument values.
</div>

<div algorithm>

    The <dfn id="LegacyPlatformObjectGetOwnProperty" oldids="getownproperty-guts" abstract-op>LegacyPlatformObjectGetOwnProperty</dfn>
    abstract operation performs the following steps when called with
    an object |O|, a property name |P|, and a boolean |ignoreNamedProps| value:

    1.  If |O| [=support indexed properties|supports indexed properties=]
        and |P| [=is an array index=], then:
        1.  Let |index| be the result of calling [=!=] <a abstract-op>ToUint32</a>(|P|).
        1.  If |index| is a [=supported property indices|supported property index=], then:
            1.  Let |operation| be the operation used to declare the indexed property getter.
            1.  Let |value| be an uninitialized variable.
            1.  If |operation| was defined without an [=identifier=], then
                set |value| to the result of performing the steps listed in the interface description to
                [=determine the value of an indexed property=]
                with |index| as the index.
            1.  Otherwise, |operation| was defined with an identifier.  Set |value| to the result
                of performing the [=method steps=] of |operation| with |O| as [=this=] and «
                |index| » as the argument values.
            1.  Let |desc| be a newly created [=Property Descriptor=] with no fields.
            1.  Set |desc|.\[[Value]] to the result of [=converted to a JavaScript value|converting=]
                |value| to a JavaScript value.
            1.  If |O| [=implements=] an interface with an [=indexed property setter=], then set
                |desc|.\[[Writable]] to <emu-val>true</emu-val>, otherwise set it to
                <emu-val>false</emu-val>.
            1.  Set |desc|.\[[Enumerable]] and |desc|.\[[Configurable]] to <emu-val>true</emu-val>.
            1.  Return |desc|.
        1.  Set |ignoreNamedProps| to true.
    1.  If |O| [=support named properties|supports named properties=] and
        |ignoreNamedProps| is false, then:
        1.  If the result of running the [=named property visibility algorithm=] with
            property name |P| and object |O| is true, then:
            1.  Let |operation| be the operation used to declare the named property getter.
            1.  Let |value| be an uninitialized variable.
            1.  If |operation| was defined without an [=identifier=], then
                set |value| to the result of performing the steps listed in the interface description to
                [=determine the value of a named property=]
                with |P| as the name.
            1.  Otherwise, |operation| was defined with an identifier.  Set |value| to the result
                of performing the [=method steps=] of |operation| with |O| as [=this=] and « |P| »
                as the argument values.
            1.  Let |desc| be a newly created [=Property Descriptor=] with no fields.
            1.  Set |desc|.\[[Value]] to the result of [=converted to a JavaScript value|converting=]
                |value| to a JavaScript value.
            1.  If |O| [=implements=] an interface with a [=named property setter=], then set
                |desc|.\[[Writable]] to <emu-val>true</emu-val>, otherwise set it to
                <emu-val>false</emu-val>.
            1.  If |O| [=implements=] an interface with the
                [{{LegacyUnenumerableNamedProperties}}]
                [=extended attribute=],
                then set |desc|.\[[Enumerable]] to <emu-val>false</emu-val>,
                otherwise set it to <emu-val>true</emu-val>.
            1.  Set |desc|.\[[Configurable]] to <emu-val>true</emu-val>.
            1.  Return |desc|.
    1.  Return <a abstract-op>OrdinaryGetOwnProperty</a>(|O|, |P|).
</div>

<h3 id="js-observable-arrays" oldids="es-observable-arrays">Observable array exotic objects</h3>

An <dfn>observable array exotic object</dfn> is a specific type of JavaScript
[=Proxy exotic object=] which is created using the proxy traps defined in this section. They are
defined in this manner because the JavaScript specification includes special treatment for
[=Proxy exotic objects=] that have <code>Array</code> instances as their proxy target, and we want
to ensure that [=observable array types=] are exposed to JavaScript code with this special treatment
intact.

The proxy traps used by observable array exotic objects work to ensure a number of invariants beyond
those of normal <code>Array</code> instances:

*   The arrays have no holes, i.e. every property in the inclusive range 0 through
    <code>observableArray.length</code> &minus; 1 will be filled with a value compatible with the
    specified Web IDL type, and no [=array index=] properties will exist outside that range.
*   The property descriptors for important properties cannot be changed from their default
    configuration; indexed properties always remain as configurable, enumerable, and writable data
    properties, while the <code>length</code> property remains as a non-configurable,
    non-enumerable, and writable data property.
*   Adding additional properties to the array cannot be prevented using, for example,
    <code>Object.preventExtensions()</code>.

<div algorithm>
    To <dfn lt="creating an observable array exotic object">create an observable array exotic object</dfn>
    in a [=realm=] |realm|, given Web IDL type |T| and algorithms |setAlgorithm| and |deleteAlgorithm|:

    1.  Let |innerArray| be [=!=] [$ArrayCreate$](0).
    1.  Let |handler| be [$OrdinaryObjectCreate$](<emu-val>null</emu-val>,
        « \[[Type]], \[[SetAlgorithm]], \[[DeleteAlgorithm]], \[[BackingList]] »).
    1.  Set |handler|.\[[Type]] to |T|.
    1.  Set |handler|.\[[SetAlgorithm]] to |setAlgorithm|.
    1.  Set |handler|.\[[DeleteAlgorithm]] to |deleteAlgorithm|.
    1.  Let |defineProperty| be [$CreateBuiltinFunction$](the steps from [[#js-observable-array-defineProperty]], « », |realm|).
    1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|handler|, "<code>defineProperty</code>", |defineProperty|).
    1.  Let |deleteProperty| be [$CreateBuiltinFunction$](the steps from [[#js-observable-array-deleteProperty]], « », |realm|).
    1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|handler|, "<code>deleteProperty</code>", |deleteProperty|).
    1.  Let |get| be [$CreateBuiltinFunction$](the steps from [[#js-observable-array-get]], « », |realm|).
    1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|handler|, "<code>get</code>", |get|).
    1.  Let |getOwnPropertyDescriptor| be [$CreateBuiltinFunction$](the steps from [[#js-observable-array-getOwnPropertyDescriptor]], « », |realm|).
    1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|handler|, "<code>getOwnPropertyDescriptor</code>", |getOwnPropertyDescriptor|).
    1.  Let |has| be [$CreateBuiltinFunction$](the steps from [[#js-observable-array-has]], « », |realm|).
    1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|handler|, "<code>has</code>", |has|).
    1.  Let |ownKeys| be [$CreateBuiltinFunction$](the steps from [[#js-observable-array-ownKeys]], « », |realm|).
    1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|handler|, "<code>ownKeys</code>", |ownKeys|).
    1.  Let |preventExtensions| be [$CreateBuiltinFunction$](the steps from [[#js-observable-array-preventExtensions]], « », |realm|).
    1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|handler|, "<code>preventExtensions</code>", |preventExtensions|).
    1.  Let |set| be [$CreateBuiltinFunction$](the steps from [[#js-observable-array-set]], « », |realm|).
    1.  Perform [=!=] [$CreateDataPropertyOrThrow$](|handler|, "<code>set</code>", |set|).
    1.  Return [=!=] [$ProxyCreate$](|innerArray|, |handler|).
</div>

<h4 id="js-observable-array-defineProperty" oldids="es-observable-array-defineProperty"><code>defineProperty</code></h4>

<div algorithm="observable array exotic object defineProperty trap">
    The steps for the <code>defineProperty</code> proxy trap for
    [=observable array exotic objects=], given |O|, |P|, and |descriptorObj| are as follows:

    1.  Let |handler| be the <emu-val>this</emu-val> value.
    1.  Let |descriptor| be [=!=] [$ToPropertyDescriptor$](|descriptorObj|).
    1.  If |P| is "length", then:
        1.  If [$IsAccessorDescriptor$](|descriptor|) is <emu-val>true</emu-val>, then return
            <emu-val>false</emu-val>.
        1.  If |descriptor|.\[[Configurable]] is present and has the value <emu-val>true</emu-val>,
            then return <emu-val>false</emu-val>.
        1.  If |descriptor|.\[[Enumerable]] is present and has the value <emu-val>true</emu-val>,
            then return <emu-val>false</emu-val>.
        1.  If |descriptor|.\[[Writable]] is present and has the value <emu-val>false</emu-val>,
            then return <emu-val>false</emu-val>.
        1.  If |descriptor|.\[[Value]] is present, then return the result of
            [=observable array exotic object/setting the length=] given |handler| and
            |descriptor|.\[[Value]].
        1.  Return <emu-val>true</emu-val>.
    1. If |P| [=is an array index=], then:
        1.  If [$IsAccessorDescriptor$](|descriptor|) is <emu-val>true</emu-val>, then return
            <emu-val>false</emu-val>.
        1.  If |descriptor|.\[[Configurable]] is present and has the value <emu-val>false</emu-val>,
            then return <emu-val>false</emu-val>.
        1.  If |descriptor|.\[[Enumerable]] is present and has the value <emu-val>false</emu-val>,
            then return <emu-val>false</emu-val>.
        1.  If |descriptor|.\[[Writable]] is present and has the value <emu-val>false</emu-val>,
            then return <emu-val>false</emu-val>.
        1.  If |descriptor|.\[[Value]] is present, then return the result of
            [=observable array exotic object/setting the indexed value=] given |handler|, |P|, and
            |descriptor|.\[[Value]].
        1.  Return <emu-val>true</emu-val>.
    1. Return [=?=] |O|.\[[DefineOwnProperty]](|P|, |descriptor|).
</div>

<h4 id="js-observable-array-deleteProperty" oldids="es-observable-array-deleteProperty"><code>deleteProperty</code></h4>

<div algorithm="observable array exotic object deleteProperty trap">
    The steps for the <code>deleteProperty</code> proxy trap for
    [=observable array exotic objects=], given |O| and |P|, are as follows:

    1.  Let |handler| be the <emu-val>this</emu-val> value.
    1.  If |P| is "length", then return <emu-val>false</emu-val>.
    1.  If |P| [=is an array index=], then:
        1.  Let |oldLen| be |handler|.\[[BackingList]]'s [=list/size=].
        1.  Let |index| be [=!=] [$ToUint32$](|P|).
        1.  If |index| ≠ |oldLen| &minus; 1, then return
            <emu-val>false</emu-val>.
        1.  Perform the algorithm steps given by |handler|.\[[DeleteAlgorithm]], given
            |handler|.\[[BackingList]][|index|] and |index|.
        1.  [=list/Remove=] the last item from |handler|.\[[BackingList]].
        1.  Return <emu-val>true</emu-val>.
    1.  Return [=?=] |O|.\[[Delete]](|P|).
</div>

<h4 id="js-observable-array-get" oldids="es-observable-array-get"><code>get</code></h4>

<div algorithm="observable array exotic object get trap">
    The steps for the <code>get</code> proxy trap for
    [=observable array exotic objects=], given |O|, |P|, and |Receiver|, are as follows:

    1.  Let |handler| be the <emu-val>this</emu-val> value.
    1.  Let |length| be |handler|.\[[BackingList]]'s [=list/size=].
    1.  If |P| is "length", then return |length|.
    1.  If |P| [=is an array index=], then:
        1.  Let |index| be [=!=] [$ToUint32$](|P|).
        1.  If |index| ≥ |length|, then return <emu-val>undefined</emu-val>.
        1.  Let |jsValue| be the result of [=converted to a JavaScript value|converting=]
            |handler|.\[[BackingList]][|index|] to a JavaScript value.
        1.  Assert: the above step never throws an exception.
        1.  Return |jsValue|.
    1.  Return [=?=] |O|.\[[Get]](|P|, |Receiver|).
</div>

<h4 id="js-observable-array-getOwnPropertyDescriptor" oldids="es-observable-array-getOwnPropertyDescriptor"><code>getOwnPropertyDescriptor</code></h4>

<div algorithm="observable array exotic object getOwnPropertyDescriptor trap">
    The steps for the <code>getOwnPropertyDescriptor</code> proxy trap for
    [=observable array exotic objects=], given |O| and |P|, are as follows:

    1.  Let |handler| be the <emu-val>this</emu-val> value.
    1.  Let |length| be |handler|.\[[BackingList]]'s [=list/size=].
    1.  If |P| is "length", then return [=!=]
        [$FromPropertyDescriptor$](PropertyDescriptor{\[[Configurable]]: <emu-val>false</emu-val>,
        \[[Enumerable]]: <emu-val>false</emu-val>, \[[Writable]]: <emu-val>true</emu-val>,
        \[[Value]]: |length| }).
    1.  If |P| [=is an array index=], then
        1.  Let |index| be [=!=] [$ToUint32$](|P|).
        1.  If |index| ≥ |length|, then return <emu-val>undefined</emu-val>.
        1.  Let |jsValue| be the result of [=converted to a JavaScript value|converting=]
            |handler|.\[[BackingList]][|index|] to a JavaScript value.
        1.  Assert: the above step never throws an exception.
        1.  Return [$FromPropertyDescriptor$](PropertyDescriptor{\[[Configurable]]:
            <emu-val>true</emu-val>, \[[Enumerable]]: <emu-val>true</emu-val>, \[[Writable]]:
            <emu-val>true</emu-val>, \[[Value]]: |jsValue| }).
    1.  Return [$FromPropertyDescriptor$]([=?=] |O|.\[[GetOwnProperty]](|P|)).
</div>

<h4 id="js-observable-array-has" oldids="es-observable-array-has"><code>has</code></h4>

<div algorithm="observable array exotic object has trap">
    The steps for the <code>has</code> proxy trap for
    [=observable array exotic objects=], given |O| and |P|, are as follows:

    1.  Let |handler| be the <emu-val>this</emu-val> value.
    1.  If |P| is "length", then return <emu-val>true</emu-val>.
    1.  If |P| [=is an array index=], then:
        1.  Let |index| be [=!=] [$ToUint32$](|P|).
        1.  If |index| &lt; |handler|.\[[BackingList]]'s [=list/size=], then return
            <emu-val>true</emu-val>.
        1.  Return <emu-val>false</emu-val>.
    1.  Return [=?=] |O|.\[[HasProperty]](|P|).
</div>

<h4 id="js-observable-array-ownKeys" oldids="es-observable-array-ownKeys"><code>ownKeys</code></h4>

<div algorithm="observable array exotic object ownKeys trap">
    The steps for the <code>ownKeys</code> proxy trap for
    [=observable array exotic objects=], given |O|, are as follows:

    1.  Let |handler| be the <emu-val>this</emu-val> value.
    1.  Let |length| be |handler|.\[[BackingList]]'s [=list/size=].
    1.  Let |keys| be an empty [=list=].
    1.  Let |i| be 0.
    1.  [=While=] |i| &lt; |length|:
        1.  [=list/Append=] [=!=] [$ToString$](|i|) to |keys|.
        1.  Set |i| to |i| + 1.
    1.  [=list/Extend=] |keys| with [=!=] |O|.\[[OwnPropertyKeys]]().
    1.  Return [$CreateArrayFromList$](|keys|).
</div>

<h4 id="js-observable-array-preventExtensions" oldids="es-observable-array-preventExtensions"><code>preventExtensions</code></h4>

<div algorithm="observable array exotic object preventExtensions trap">
    The steps for the <code>preventExtensions</code> proxy trap for
    [=observable array exotic objects=] are as follows:

    1.  Return <emu-val>false</emu-val>.
</div>

<h4 id="js-observable-array-set" oldids="es-observable-array-set"><code>set</code></h4>

<div algorithm="observable array exotic object set trap">
    The steps for the <code>set</code> proxy trap for
    [=observable array exotic objects=], given |O|, |P|, |V|, and |Receiver|, are as follows:

    1.  Let |handler| be the <emu-val>this</emu-val> value.
    1.  If |P| is "length", then return the result of
        [=observable array exotic object/setting the length=] given |handler| and |V|.
    1.  If |P| [=is an array index=], then return the result of
        [=observable array exotic object/setting the indexed value=] given |handler|, |P|, and |V|.
    1.  Return [=?=] |O|.\[[Set]](|P|, |V|, |Receiver|).
</div>

<h4 id="js-observable-array-abstract-operations" oldids="es-observable-array-abstract-operations">Abstract operations</h4>

<div algorithm>
    To <dfn for="observable array exotic object" lt="set the length|setting the length">set the length</dfn>
    of an observable array exotic object given |handler| and |newLen|:

    1.  Let |uint32Len| be [=?=] [$ToUint32$](|newLen|).
    1.  Let |numberLen| be [=?=] [$ToNumber$](|newLen|).
    1.  If |uint32Len| ≠ |numberLen|, then throw a {{RangeError}} exception.
    1.  Let |oldLen| be |handler|.\[[BackingList]]'s [=list/size=].
    1.  If |uint32Len| > |oldLen|, then return <emu-val>false</emu-val>.
    1.  Let |indexToDelete| be |oldLen| &minus; 1.
    1.  [=While=] |indexToDelete| ≥ |uint32Len|:
        1.  Perform the algorithm steps given by |handler|.\[[DeleteAlgorithm]], given
            |handler|.\[[BackingList]][|indexToDelete|] and |indexToDelete|.
        1.  [=list/Remove=] the last item from |handler|.\[[BackingList]].
        1.  Set |indexToDelete| to |indexToDelete| &minus; 1.
    1.  Return <emu-val>true</emu-val>.
</div>

<div algorithm>
    To <dfn for="observable array exotic object" lt="set the indexed value|setting the indexed value">set the indexed value</dfn>
    of an observable array exotic object given |handler|, |P|, and |V|:

    1.  Let |oldLen| be |handler|.\[[BackingList]]'s [=list/size=].
    1.  Let |index| be [=!=] [$ToUint32$](|P|).
    1.  If |index| > |oldLen|, return <emu-val>false</emu-val>.
    1.  Let |idlValue| be the result of [=converted to an IDL value|converting=]
        |V| to the type given by |handler|.\[[Type]].
    1.  If |index| &lt; |oldLen|, then:
        1.  Perform the algorithm steps given by |handler|.\[[DeleteAlgorithm]], given
            |handler|.\[[BackingList]][|index|] and |index|.
    1.  Perform the algorithm steps given by |handler|.\[[SetAlgorithm]], given |idlValue| and
        |index|.
    1.  If |index| = |oldLen|, then [=list/append=] |idlValue| to |handler|.\[[BackingList]].
    1.  Otherwise, set |handler|.\[[BackingList]][|index|] to |idlValue|.
    1.  Return <emu-val>true</emu-val>.
</div>

<h3 id="js-user-objects" oldids="es-user-objects">Callback interfaces</h3>

As described in [[#idl-objects]],
[=callback interfaces=] can be
implemented in script by any JavaScript object.
The following cases explain how a [=callback interface=]'s [=operation=] is invoked on a given
object:

*   If the object is [=ECMAScript/callable=], then the implementation of the operation is the
    callable object itself.
*   Otherwise, the implementation of the operation is calling the result of invoking the
    internal \[[Get]] method on the object with a property name that is the [=identifier=] of
    the operation.

Note that JavaScript objects need not have
properties corresponding to [=constants=]
on them to be considered as
implementing [=callback interfaces=] that happen
to have constants declared on them.

A <dfn>Web IDL arguments list</dfn> is a [=list=] of values each of which is either an IDL value or
the special value “missing”, which represents a missing optional argument.

<div algorithm>
    To <dfn lt="converting" for="Web IDL arguments list">convert a Web IDL arguments list to a
    JavaScript arguments list</dfn>, given a [=Web IDL arguments list=] |args|, perform the
    following steps:

    1.  Let |jsArgs| be an empty [=list=].
    1.  Let |i| be 0.
    1.  Let |count| be 0.
    1.  While |i| &lt; |args|'s [=list/size=]:
        1.  If |args|[|i|] is the special value “missing”, then [=list/append=]
            <emu-val>undefined</emu-val> to |jsArgs|.
        1.  Otherwise, |args|[|i|] is an IDL value:
            1.  Let |convertResult| be the result of [=converted to a JavaScript value|converting=]
                |args|[|i|] to a JavaScript value. Rethrow any exceptions.
            1.  [=list/Append=] |convertResult| to |jsArgs|.
            1.  Set |count| to |i| + 1.
        1.  Set |i| to |i| + 1.
    1.  Truncate |jsArgs| to contain |count| items.
    1.  Return |jsArgs|.
</div>

<div algorithm="to call a user object's operation">

    To <dfn id="call-a-user-objects-operation" export>call a user object's operation</dfn>,
    given a [=callback interface type=] value |value|,
    operation name |opName|, [=Web IDL arguments list=] |args|, and optional
    <dfn id="dfn-callback-this-value" export>callback this value</dfn> |thisArg|,
    perform the following steps.
    These steps will either return an IDL value or throw an exception.

    1.  Let |completion| be an uninitialized variable.
    1.  If |thisArg| was not given, let |thisArg| be <emu-val>undefined</emu-val>.
    1.  Let |O| be the JavaScript object corresponding to |value|.
    1.  Let |realm| be |O|'s [=associated realm=].
    1.  Let |relevant settings| be |realm|'s [=realm/settings object=].
    1.  Let |stored settings| be |value|'s [=callback context=].
    1.  [=Prepare to run script=] with |relevant settings|.
    1.  [=Prepare to run a callback=] with |stored settings|.
    1.  Let |X| be |O|.
    1.  If <a abstract-op>IsCallable</a>(|O|) is false, then:
        1.  Let |getResult| be <a abstract-op>Completion</a>(<a abstract-op>Get</a>(|O|, |opName|)).
        1.  If |getResult| is an [=abrupt completion=], set |completion|
            to |getResult| and jump to the step labeled <a href="#call-user-object-operation-return"><i>return</i></a>.
        1.  Set |X| to |getResult|.\[[Value]].
        1.  If <a abstract-op>IsCallable</a>(|X|) is <emu-val>false</emu-val>,
            then set |completion| to [=Completion Record=] { \[[Type]]: throw, \[[Value]]: a
            newly created <l spec=ecmascript>{{TypeError}}</l> object, \[[Target]]: empty }, and jump
            to the step labeled <a href="#call-user-object-operation-return"><i>return</i></a>.
        1.  Set |thisArg| to |O| (overriding the provided value).
    1.  Let |jsArgs| be the result of [=Web IDL arguments list/converting=] |args| to a JavaScript
        arguments list. If this throws an exception, set |completion| to the completion value
        representing the thrown exception and jump to the step labeled
        <a href="#call-user-object-operation-return"><i>return</i></a>.
    1.  Let |callResult| be <a abstract-op>Completion</a>(<a abstract-op>Call</a>(|X|, |thisArg|, |jsArgs|)).
    1.  If |callResult| is an [=abrupt completion=], set |completion| to
        |callResult| and jump to the step labeled <a href="#call-user-object-operation-return"><i>return</i></a>.
    1.  Set |completion| to the result of [=converted to an IDL value|converting=]
        |callResult|.\[[Value]] to an IDL value of the same type as the operation's
        return type. If this throws an exception, set |completion| to the completion value
        representing the thrown exception.
    1.  <i id="call-user-object-operation-return">Return:</i> at this
        point |completion| will be set to an IDL value or an [=abrupt completion=].
        1.  [=Clean up after running a callback=] with |stored settings|.
        1.  [=Clean up after running script=] with |relevant settings|.
        1.  If |completion| is an IDL value, return |completion|.
        1.  If |completion| is an [=abrupt completion=] and the operation has a [=return type=]
            that is <em>not</em> a [=promise type=], throw |completion|.\[[Value]].
        1.  Let |rejectedPromise| be [=!=] <a abstract-op>Call</a>({{%Promise.reject%}},
            {{%Promise%}}, «|completion|.\[[Value]]»).
        1.  Return the result of [=converted to an IDL value|converting=]
            |rejectedPromise| to the operation's return type.
</div>


<h4 id="legacy-callback-interface-object">Legacy callback interface object</h4>

For every [=callback interface=] that is [=exposed=] in
a given [=realm=]
and on which [=constants=] are defined,
a corresponding property exists on the [=realm=]'s [=realm/global object=].
The name of the property is the [=identifier=] of the [=callback interface=],
and its value is an object called the
<dfn id="dfn-legacy-callback-interface-object" export>legacy callback interface object</dfn>.

The [=legacy callback interface object=] for a given [=callback interface=]
is a [=built-in function object=].
It has properties that correspond to the [=constants=] defined on that interface,
as described in sections [[#js-constants]].

Note: Since a [=legacy callback interface object=] is a [=function object=]
the <code>typeof</code> operator will return "function"
when applied to a [=legacy callback interface object=].

<div algorithm>

    The [=legacy callback interface object=] for a given [=callback interface=] |interface|
    with [=identifier=] |id| and in [=realm=] |realm|
    is <dfn lt="create a legacy callback interface object">created</dfn> as follows:

    1.  Let |steps| be the following steps:
        1.  [=JavaScript/Throw=] a <l spec=ecmascript>{{TypeError}}</l>.
    1.  Let |F| be <a abstract-op>CreateBuiltinFunction</a>(|steps|, « », |realm|).
    1.  Perform <a abstract-op>SetFunctionName</a>(|F|, |id|).
    1.  Perform <a abstract-op>SetFunctionLength</a>(|F|, 0).
    1.  [=Define the constants=] of |interface| on |F| given |realm|.
    1.  Return |F|.
</div>


<h3 id="js-invoking-callback-functions" oldids="es-invoking-callback-functions">Invoking callback functions</h3>

A JavaScript [=ECMAScript/callable=] object that is being
used as a [=callback function=] value is
called in a manner similar to how [=operations=]
on [=callback interface=] values are called (as
described in the previous section).

<div algorithm>

    To <dfn id="invoke-a-callback-function" export>invoke</dfn> a
    [=callback function type=] value |callable| with a [=Web IDL arguments list=] |args|,
    exception behavior |exceptionBehavior| (either "<code>report</code>" or "<code>rethrow</code>"),
    and an optional [=callback this value|callback this value=] |thisArg|,
    perform the following steps.
    These steps will either return an IDL value or throw an exception.

    The |exceptionBehavior| argument must be supplied if, and only if, |callable|'s
    [=return type=] is not a [=promise type=]. If |callable|'s return type is neither
    {{undefined}} nor {{any}}, it must be "<code>rethrow</code>".

    <div class="XXX">
        Until call sites are updated to respect this, specifications which fail to
        provide a value here when it would be mandatory should be understood as
        supplying "<code>rethrow</code>".
    </div>

    1.  Let |completion| be an uninitialized variable.
    1.  If |thisArg| was not given, let |thisArg| be <emu-val>undefined</emu-val>.
    1.  Let |F| be the JavaScript object corresponding to |callable|.
    1.  If <a abstract-op>IsCallable</a>(|F|) is <emu-val>false</emu-val>:
        1.  Note: This is only possible when the [=callback function=] came from an attribute
            marked with [{{LegacyTreatNonObjectAsNull}}].
        1.  Return the result of [=converted to an IDL value|converting=]
            <emu-val>undefined</emu-val> to the callback function's return type.
    1.  Let |realm| be |F|'s [=associated realm=].
    1.  Let |relevant settings| be |realm|'s [=realm/settings object=].
    1.  Let |stored settings| be |callable|'s [=callback context=].
    1.  [=Prepare to run script=] with |relevant settings|.
    1.  [=Prepare to run a callback=] with |stored settings|.
    1.  Let |jsArgs| be the result of [=Web IDL arguments list/converting=] |args| to a JavaScript
        arguments list. If this throws an exception, set |completion| to the completion value
        representing the thrown exception and jump to the step labeled
        <a href="#invoke-return"><i>return</i></a>.
    1.  Let |callResult| be <a abstract-op>Completion</a>(<a abstract-op>Call</a>(|F|, |thisArg|, |jsArgs|)).
    1.  If |callResult| is an [=abrupt completion=], set |completion| to
        |callResult| and jump to the step labeled <a href="#invoke-return"><i>return</i></a>.
    1.  Set |completion| to the result of [=converted to an IDL value|converting=]
        |callResult|.\[[Value]] to an IDL value of the same type as |callable|'s
        return type. If this throws an exception, set |completion| to the completion value
        representing the thrown exception.
    1.  <i id="invoke-return">Return:</i> at this
        point |completion| will be set to an IDL value or an [=abrupt completion=].
        1.  [=Clean up after running a callback=] with |stored settings|.
        1.  [=Clean up after running script=] with |relevant settings|.
        1.  If |completion| is an IDL value, return |completion|.
        1.  [=Assert=]: |completion| is an [=abrupt completion=].
        1.  If |exceptionBehavior| is "<code>rethrow</code>", throw |completion|.\[[Value]].
        1.  Otherwise, if |exceptionBehavior| is "<code>report</code>":
            1.  [=Assert=]: |callable|'s [=return type=] is {{undefined}} or {{any}}.
            1.  [=Report an exception=] |completion|.\[[Value]] for |realm|'s [=realm/global object=].
            1.  Return the unique {{undefined}} IDL value.
        1.  [=Assert=]: |callable|'s [=return type=] is a [=promise type=].
        1.  Let |rejectedPromise| be [=!=] <a abstract-op>Call</a>({{%Promise.reject%}},
            {{%Promise%}}, «|completion|.\[[Value]]»).
        1.  Return the result of [=converted to an IDL value|converting=]
            |rejectedPromise| to the callback function's return type.
</div>

Some callback functions are instead used as [=constructors=]. Such callback functions must not have
a return type that is a [=promise type=].

<div algorithm>

    To <dfn id="construct-a-callback-function" export>construct</dfn> a
    [=callback function type=] value |callable| with a [=Web IDL arguments list=] |args|,
    perform the following steps.
    These steps will either return an IDL value or throw an exception.

    1.  Let |completion| be an uninitialized variable.
    1.  Let |F| be the JavaScript object corresponding to |callable|.
    1.  If <a abstract-op>IsConstructor</a>(|F|) is <emu-val>false</emu-val>, throw a
        <l spec=ecmascript>{{TypeError}}</l> exception.
    1.  Let |realm| be |F|'s [=associated realm=].
    1.  Let |relevant settings| be |realm|'s [=realm/settings object=].
    1.  Let |stored settings| be |callable|'s [=callback context=].
    1.  [=Prepare to run script=] with |relevant settings|.
    1.  [=Prepare to run a callback=] with |stored settings|.
    1.  Let |jsArgs| be the result of [=Web IDL arguments list/converting=] |args| to a JavaScript
        arguments list. If this throws an exception, set |completion| to the completion value
        representing the thrown exception and jump to the step labeled
        <a href="#construct-return"><i>return</i></a>.
    1.  Let |callResult| be <a abstract-op>Completion</a>(<a abstract-op>Construct</a>(|F|, |jsArgs|)).
    1.  If |callResult| is an [=abrupt completion=], set |completion| to
        |callResult| and jump to the step labeled <a href="#construct-return"><i>return</i></a>.
    1.  Set |completion| to the result of [=converted to an IDL value|converting=]
        |callResult|.\[[Value]] to an IDL value of the same type as |callable|'s
        return type. If this throws an exception, set |completion| to the completion value
        representing the thrown exception.
    1.  <i id="construct-return">Return:</i> at this
        point |completion| will be set to an IDL value or an [=abrupt completion=].
        1.  [=Clean up after running a callback=] with |stored settings|.
        1.  [=Clean up after running script=] with |relevant settings|.
        1.  If |completion| is an [=abrupt completion=], throw |completion|.\[[Value]].
        1.  Return |completion|.
</div>


<h3 id="js-namespaces" oldids="es-namespaces">Namespaces</h3>

For every [=namespace=] that is [=exposed=] in a given [=realm=],
a corresponding property exists on the [=realm=]'s [=realm/global object=].
The name of the property is the [=identifier=] of the namespace, and its value is an object
called the <dfn id="dfn-namespace-object" export>namespace object</dfn>.

The characteristics of a namespace object are described in [[#namespace-object]].


<h4 id="namespace-object">Namespace object</h4>

<div algorithm>

    The namespace object for a given [=namespace=] |namespace| and [=realm=] |realm|
    is <dfn lt="create a namespace object">created</dfn> as follows:

    1.  Let |namespaceObject| be [$OrdinaryObjectCreate$](|realm|.\[[Intrinsics]].\[[{{%Object.prototype%}}]]).
    1.  [=Define the regular attributes=] of |namespace| on |namespaceObject| given |realm|.
    1.  [=Define the regular operations=] of |namespace| on |namespaceObject| given |realm|.
    1.  [=Define the constants=] of |namespace| on |namespaceObject| given |realm|.
    1.  For each [=exposed=] [=interface=] |interface| which has the [{{LegacyNamespace}}] extended
        attribute with the identifier of |namespace| as its argument,
        1.  Let |id| be |interface|'s [=identifier=].
        1.  Let |interfaceObject| be the result of [=create an interface object|creating an
            interface object=] for |interface| with |id| in |realm|.
        1.  Perform [$DefineMethodProperty$](|namespaceObject|, |id|, |interfaceObject|, false).
    1.  Return |namespaceObject|.
</div>

The [=class string=] of a [=namespace object=] is the [=namespace=]'s [=identifier=].


<h3 id="js-exceptions" oldids="es-exceptions">Exceptions</h3>

<h4 id="js-DOMException-specialness" oldids="es-DOMException-specialness,es-DOMException-constructor-object, es-DOMException-prototype-object">{{DOMException}} custom bindings</h4>

In the JavaScript binding, the [=interface prototype object=] for {{DOMException}}
has its \[[Prototype]] [=/internal slot=] set to the intrinsic object {{%Error.prototype%}},
as defined in the [=create an interface prototype object=] abstract operation.
It also has an \[[ErrorData]] slot, like all built-in exceptions.

Additionally, if an implementation gives native {{Error}} objects special powers or
nonstandard properties (such as a <code>stack</code> property),
it should also expose those on {{DOMException}} objects.

<h4 id="js-exception-objects" oldids="es-exception-objects" dfn>Exception objects</h4>

[=Simple exceptions=] are represented
by native JavaScript objects of the corresponding type.

A {{DOMException}} is represented by a
[=platform object=] that implements the {{DOMException}} interface.


<h4 id="js-creating-throwing-exceptions" oldids="es-creating-throwing-exceptions">Creating and throwing exceptions</h4>


<div algorithm="to create a simple exception">
    To [=exception/create=] a [=simple exception=] of type |T|:

    1.  Let |message| be 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.  Let |args| be « |message| ».

    1.  Let |constructor| be [=current realm=].\[[Intrinsics]].\[[%|T|%]].

    1. Return [=!=] [$Construct$](|constructor|, |args|).
</div>

<div algorithm="to create a DOMException">
    To [=exception/create=] a {{DOMException}} given a string |name|:

    1.  Assert: |name| appears in the <a><code>DOMException</code> names table</a>.

    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|.
</div>

<div algorithm="to create a DOMException derived interface">
    To [=exception/create=] a {{DOMException}} derived interface given the [=interface=]
    [=identifier=] |type| and additional initialization instructions:

    1.  Let |ex| be a [=new=] instance of the [=interface=] identified by |type|, created in the
        [=current realm=].

    1.  Set |ex|'s [=DOMException/name=] to |type|.

    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.  Perform any additional initialization on |ex| as described by the caller.

    1.  Return |ex|.
</div>

<div algorithm="throw an exception">
    To [=exception/throw=] an [=exception=]:

    1.  Let |O| be the result of [=exception/create|creating an exception=] with the same
        arguments.
    1.  Throw |O|.
</div>

<div class="note">

    The above algorithms restrict [=Exception objects|objects representing exceptions=] propagating
    out of a [=function object=] to be ones that are associated with the [=realm=] of that
    [=function object=] (i.e., the [=current realm=] at the time the function
    executes). For example, consider the IDL:

    <pre highlight="webidl">
        [Exposed=Window]
        interface MathUtils {
          // If x is negative, throws a "<a href="#notsupportederror">NotSupportedError</a>" <a href="dfn-DOMException">DOMException</a>.
          double computeSquareRoot(double x);
        };
    </pre>

    If we apply <code class="idl">computeSquareRoot</code> to a <code class="idl">MathUtils</code>
    object from a different [=realm=], then the exception thrown will be from the [=realm=] of the
    method, not the object it is applied to:

    <pre highlight="js">
        const myMU = window.getMathUtils();          // A MathUtils object from this realm
        const otherMU = otherWindow.getMathUtils();  // A MathUtils object from a different realm

        myMU instanceof Object;                      // Evaluates to true.
        otherMU instanceof Object;                   // Evaluates to false.
        otherMU instanceof otherWindow.Object;       // Evaluates to true.

        try {
          otherMU.doComputation.call(myMU, -1);
        } catch (e) {
          console.assert(!(e instanceof DOMException));
          console.assert(e instanceof otherWindow.DOMException);
        }
    </pre>
</div>


<h4 id="js-handling-exceptions" oldids="es-handling-exceptions">Handling exceptions</h4>

Unless specified otherwise,
whenever JavaScript runtime semantics are invoked due
to requirements in this document and
end due to an exception being thrown, that exception
must propagate to the caller, and if
not caught there, to its caller, and so on.

Per [[#conventions]], an algorithm specified in this document may intercept thrown exceptions, either by specifying
the exact steps to take if <dfn>an exception was thrown</dfn>, or by explicitly handling [=abrupt completions=].

<div class="example" id="example-17059fd2">

    The following [=IDL fragment=]
    defines two [=interfaces=]
    and an [=exception=].
    The <code>valueOf</code> attribute on <code class="idl">ExceptionThrower</code>
    is defined to throw an exception whenever an attempt is made
    to get its value.

    <pre highlight="webidl">
        [Exposed=Window]
        interface Dahut {
          attribute DOMString type;
        };

        [Exposed=Window]
        interface ExceptionThrower {
          // This attribute always throws a NotSupportedError and never returns a value.
          attribute long valueOf;
        };
    </pre>

    Assuming a JavaScript implementation supporting this interface,
    the following code demonstrates how exceptions are handled:

    <pre highlight="js">
        var d = getDahut();              // Obtain an instance of Dahut.
        var et = getExceptionThrower();  // Obtain an instance of ExceptionThrower.

        try {
          d.type = { toString: function() { throw "abc"; } };
        } catch (e) {
          // The string "abc" is caught here, since as part of the conversion
          // from the native object to a string, the anonymous function
          // was invoked, and none of the [[DefaultValue]], ToPrimitive or
          // ToString algorithms are defined to catch the exception.
        }

        try {
          d.type = { toString: { } };
        } catch (e) {
          // An exception is caught here, since an attempt is made to invoke
          // [[Call]] on the native object that is the value of toString
          // property.
        }

        try {
          d.type = Symbol();
        } catch (e) {
          // An exception is caught here, since an attempt is made to invoke
          // the JavaScript ToString abstract operation on a Symbol value.
        }

        d.type = et;
        // An uncaught "NotSupportedError" DOMException is thrown here, since the
        // [[DefaultValue]] algorithm attempts to get the value of the
        // "valueOf" property on the ExceptionThrower object.  The exception
        // propagates out of this block of code.
    </pre>
</div>


<h2 id="common">Common definitions</h2>

This section specifies some common definitions that all
[=conforming implementations=]
must support.


<h3 id="ArrayBufferView" typedef oldids="common-ArrayBufferView">ArrayBufferView</h3>

<pre class="idl">
    typedef (Int8Array or Int16Array or Int32Array or
             Uint8Array or Uint16Array or Uint32Array or Uint8ClampedArray or
             BigInt64Array or BigUint64Array or
             Float16Array or Float32Array or Float64Array or DataView) ArrayBufferView;
</pre>

The {{ArrayBufferView}} typedef is used to represent
objects that provide a view on to an {{ArrayBuffer}} or
{{SharedArrayBuffer}} (when [{{AllowShared}}] is used).


<h3 id="BufferSource" typedef oldids="common-BufferSource">BufferSource</h3>

<pre class="idl">typedef (ArrayBufferView or ArrayBuffer) BufferSource;</pre>

The {{BufferSource}} typedef is used to represent objects
that are either themselves an {{ArrayBuffer}} or which
provide a view on to an {{ArrayBuffer}}.

Note: [{{AllowShared}}] cannot be used with {{BufferSource}} as {{ArrayBuffer}} does not support it.
Use {{AllowSharedBufferSource}} instead.


<h3 id="AllowSharedBufferSource" typedef>AllowSharedBufferSource</h3>

<pre class="idl">typedef (ArrayBuffer or SharedArrayBuffer or [AllowShared] ArrayBufferView) AllowSharedBufferSource;</pre>

The {{AllowSharedBufferSource}} typedef is used to represent objects
that are either themselves an {{ArrayBuffer}} or {{SharedArrayBuffer}} or which
provide a view on to an {{ArrayBuffer}} or {{SharedArrayBuffer}}.


<h3 id="idl-DOMException" interface oldids="dfn-DOMException">DOMException</h3>

The {{DOMException}} type is an [=interface type=] defined by the following IDL
fragment:

<pre class="idl">
[Exposed=*,
 Serializable]
interface DOMException { // but see below note about JavaScript binding
  constructor(optional DOMString message = "", optional DOMString name = "Error");
  readonly attribute DOMString name;
  readonly attribute DOMString message;
  readonly attribute unsigned short code;

  const unsigned short INDEX_SIZE_ERR = 1;
  const unsigned short DOMSTRING_SIZE_ERR = 2;
  const unsigned short HIERARCHY_REQUEST_ERR = 3;
  const unsigned short WRONG_DOCUMENT_ERR = 4;
  const unsigned short INVALID_CHARACTER_ERR = 5;
  const unsigned short NO_DATA_ALLOWED_ERR = 6;
  const unsigned short NO_MODIFICATION_ALLOWED_ERR = 7;
  const unsigned short NOT_FOUND_ERR = 8;
  const unsigned short NOT_SUPPORTED_ERR = 9;
  const unsigned short INUSE_ATTRIBUTE_ERR = 10;
  const unsigned short INVALID_STATE_ERR = 11;
  const unsigned short SYNTAX_ERR = 12;
  const unsigned short INVALID_MODIFICATION_ERR = 13;
  const unsigned short NAMESPACE_ERR = 14;
  const unsigned short INVALID_ACCESS_ERR = 15;
  const unsigned short VALIDATION_ERR = 16;
  const unsigned short TYPE_MISMATCH_ERR = 17;
  const unsigned short SECURITY_ERR = 18;
  const unsigned short NETWORK_ERR = 19;
  const unsigned short ABORT_ERR = 20;
  const unsigned short URL_MISMATCH_ERR = 21;
  const unsigned short QUOTA_EXCEEDED_ERR = 22;
  const unsigned short TIMEOUT_ERR = 23;
  const unsigned short INVALID_NODE_TYPE_ERR = 24;
  const unsigned short DATA_CLONE_ERR = 25;
};
</pre>

Note: as discussed in [[#js-DOMException-specialness]], the JavaScript binding imposes additional
requirements beyond the normal ones for [=interface types=].

Each {{DOMException}} object has an associated <dfn export for="DOMException">name</dfn> and
<dfn export for="DOMException">message</dfn>, both [=strings=].

The
<dfn constructor for="DOMException" lt="DOMException(message, name)"><code>new DOMException(|message|, |name|)</code></dfn>
constructor steps are:

1. Set [=this=]'s [=DOMException/name=] to |name|.
1. Set [=this=]'s [=DOMException/message=] to |message|.

The <dfn attribute for="DOMException"><code>name</code></dfn> getter steps are to return
[=this=]'s [=DOMException/name=].

The <dfn attribute for="DOMException"><code>message</code></dfn> getter steps are to
return [=this=]'s [=DOMException/message=].

The <dfn attribute for="DOMException"><code>code</code></dfn> getter steps are to return the legacy
code indicated in the <a><code>DOMException</code> names table</a> for [=this=]'s
[=DOMException/name=], or 0 if no such entry exists in the table.

{{DOMException}} objects are [=serializable objects=].

Their [=serialization steps=], given <var>value</var> and <var>serialized</var>, are:

<ol>
    <li>Set <var>serialized</var>.\[[Name]] to <var>value</var>'s [=DOMException/name=].</li>
    <li>Set <var>serialized</var>.\[[Message]] to <var>value</var>'s [=DOMException/message=].</li>
    <li>User agents should attach a serialized representation of any interesting accompanying data
    which are not yet specified, notably the <code>stack</code> property, to
    <var>serialized</var>.</li>
</ol>

Their [=deserialization steps=], given <var>value</var> and <var>serialized</var>, are:

<ol>
    <li>Set <var>value</var>'s [=DOMException/name=] to <var>serialized</var>.\[[Name]].</li>
    <li>Set <var>value</var>'s [=DOMException/message=] to <var>serialized</var>.\[[Message]].</li>
    <li>If any other data is attached to <var>serialized</var>, then deserialize and attach it to
    <var>value</var>.</li>
</ol>

<h3 id="Function" callback oldids="common-Function">Function</h3>

<pre class="idl">callback Function = any (any... arguments);</pre>

The {{Function}} [=callback function=]
type is used for representing function values with no restriction on what arguments
are passed to it or what kind of value is returned from it.


<h3 id="VoidFunction" callback>VoidFunction</h3>

<pre class="idl">callback VoidFunction = undefined ();</pre>

The {{VoidFunction}} [=callback function=]
type is used for representing function values that take no arguments and do not
return any value.


<h2 id="extensibility">Extensibility</h2>

<i>This section is informative.</i>

Extensions to language binding requirements can be specified
using [=extended attributes=]
that do not conflict with those defined in this document.  Extensions for
private, project-specific use ought not be included in
[=IDL fragments=]
appearing in other specifications.  It is recommended that extensions
that are required for use in other specifications be coordinated
with the group responsible for work on <cite>Web IDL</cite>, which
at the time of writing is the
<a href="http://www.w3.org/WebPlatform/WG/">W3C Web Platform Working Group</a>,
for possible inclusion in a future version of this document.

Extensions to any other aspect of the IDL language are
strongly discouraged.


<h2 id="legacy-constructs">Legacy constructs</h2>

<i>This section is informative.</i>

Legacy Web IDL constructs exist only so that
legacy Web platform features can be specified.
They are generally prefixed with the "<code>Legacy</code>" string.
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 <a href="https://github.com/whatwg/webidl/issues/new?title=Intent%20to%20use%20a%20legacy%20Web%20IDL%20construct">filing an issue</a>
before proceeding.

Marking a construct as legacy does not, in itself,
imply that it is about to be removed from this specification.
It does suggest however, that it is a good candidate
for future removal from this specification,
whenever various heuristics indicate that
the Web platform features it helps specify can be removed altogether
or can be modified to rely on non-legacy Web IDL constructs instead.


<h2 id="referencing">Referencing this specification</h2>

<i>This section is informative.</i>

It is expected that other specifications that define Web platform interfaces
using one or more [=IDL fragments=]
will reference this specification.  It is suggested
that those specifications include a sentence such as the following,
to indicate that the IDL is to be interpreted as described in this
specification:

<blockquote>

    The IDL fragment in Appendix A <!--grammar-check-override-->of this specification must, in
    conjunction with the IDL fragments defined in this specification's normative references,
    be interpreted as required for <em>conforming sets of IDL fragments</em>, as described in the
    “Web IDL” specification. \[WEBIDL]

</blockquote>

In addition, it is suggested that the conformance class for user
agents in referencing specifications be linked to the
[=conforming implementation=] class from this specification:

<blockquote>

    A conforming FooML user agent must also be a
    <em>conforming implementation</em> of the IDL fragment in Appendix A
    <!--grammar-check-override-->of this specification, as described in the
    “Web IDL” specification. \[WEBIDL]

</blockquote>


<h2 id="priv-sec">Privacy and Security Considerations</h2>

This specification defines a conversion layer between JavaScript and IDL values. An incorrect
implementation of this layer can lead to security issues.

This specification also provides the ability to use JavaScript values directly, through the
{{any}} and {{object}} IDL types. These values need to be handled carefully to avoid security
issues. In particular, user script can run in response to nearly any manipulation of these values,
and invalidate the expectations of specifications or implementations using them.

This specification makes it possible to interact with {{SharedArrayBuffer}} objects, which can be
used to build timing attacks. Specifications that use these objects need to consider such attacks.


<h2 class=no-num id=acknowledgements>Acknowledgments</h2>

<i>This section is informative.</i>

The editors would like to thank the following people for contributing
to this specification:
Glenn Adams,
David Andersson,
Jake Archibald,
Tab Atkins-Bittner,
L. David Baron,
Art Barstow,
Nils Barth,
Robin Berjon,
David Bruant,
Jan-Ivar Bruaroey,
Marcos Cáceres,
Giovanni Campagna,
François Daoust,
Domenic Denicola,
Chris Dumez,
Michael Dyck,
Daniel Ehrenberg,
Brendan Eich,
João Eiras,
Gorm Haug Eriksen,
Sigbjorn Finne,
David Flanagan,
Aryeh Gregor,
Dimitry Golubovsky,
James Graham,
Aryeh Gregor,
Tiancheng “Timothy” Gu,
Kartikaya Gupta,
Marcin Hanclik,
Jed Hartman,
Stefan Haustein,
Dominique Hazaël-Massieux,
Ian Hickson,
Björn Höhrmann,
Kyle Huey,
Lachlan Hunt,
Oliver Hunt,
Jim Jewett,
Wolfgang Keller,
Anne van Kesteren,
Olav Junker Kjær,
Takayoshi Kochi,
Magnus Kristiansen,
Raphael Kubo da Costa,
Takeshi Kurosawa,
Yves Lafon,
Travis Leithead,
Jim Ley,
Kevin Lindsey,
Jens Lindström,
Peter Linss,
呂康豪 (Kang-Hao Lu),
Kyle Machulis,
Darien Maillet Valentine,
Mark Miller,
Ms2ger,
Andrew Oakley,
岡坂 史紀 (Shiki Okasaka),
Jason Orendorff,
Olli Pettay,
Simon Pieters,
Andrei Popescu,
François Remy,
Tim Renouf,
Jeremy Roman,
Tim Ruffles,
Alex Russell,
Takashi Sakamoto,
Doug Schepers,
Jonas Sicking,
Garrett Smith,
Sam Sneddon,
Jungkee Song,
Josh Soref,
Maciej Stachowiak,
Austin Sullivan,
Anton Tayanovskyy,
triple-underscore,
Peter Van der Beken,
Jeff Walden,
Allen Wirfs-Brock,
Jeffrey Yasskin and,
Collin Xu.

Special thanks also go to Sam Weinig for maintaining this document
while the editor was unavailable to do so.

This standard is written by Edgar Chen (<a href=https://www.mozilla.org/>Mozilla</a>,
<a href=mailto:echen@mozilla.com>echen@mozilla.com</a>) and Tiancheng "Timothy" Gu
(<a href=mailto:timothygu99@gmail.com>timothygu99@gmail.com</a>) with substantial contributions from
Boris Zbarsky (<a href=mailto:bzbarsky@mit.edu>bzbarsky@mit.edu</a>),
<a href=https://mcc.id.au/>Cameron McCormack</a> (<a href=mailto:cam@mcc.id.au>cam@mcc.id.au</a>),
and <a href=https://www.tobie.me/>Tobie Langel</a>
(<a href=mailto:tobie@unlockopen.com>tobie@unlockopen.com</a>).


<h2 id="idl-grammar" class="no-num">IDL grammar</h2>

This section defines an LL(1) grammar whose start symbol,
<emu-nt><a href="#prod-Definitions">Definitions</a></emu-nt>, matches an entire [=IDL fragment=].

Each production in the grammar has on its right hand side either a
non-zero sequence of terminal and non-terminal symbols, or an
epsilon (ε) which indicates no symbols.
Symbols that begin with an uppercase letter are non-terminal symbols.
Symbols in monospaced fonts are terminal symbols.
Symbols in sans-serif font that begin with a lowercase letter are terminal
symbols that are matched by the regular expressions (using Perl 5 regular
expression syntax [[!PERLRE]]) as follows:

<table class="grammar data">
    <tr>
        <td id="prod-integer"><emu-t class="regex">integer</emu-t></td>
        <td><code>=</code></td>
        <td><code class="regex"><span class="mute">/</span>-?([1-9][0-9]*|0[Xx][0-9A-Fa-f]+|0[0-7]*)<span class="mute">/</span></code></td>
    </tr>
    <tr>
        <td id="prod-decimal"><emu-t class="regex">decimal</emu-t></td>
        <td><code>=</code></td>
        <td><code class="regex"><span class="mute">/</span>-?(([0-9]+\.[0-9]*|[0-9]*\.[0-9]+)([Ee][+-]?[0-9]+)?|[0-9]+[Ee][+-]?[0-9]+)<span class="mute">/</span></code></td>
    </tr>
    <tr>
        <td id="prod-identifier"><emu-t class="regex">identifier</emu-t></td>
        <td><code>=</code></td>
        <td><code class="regex"><span class="mute">/</span>[_-]?[A-Za-z][0-9A-Z_a-z-]*<span class="mute">/</span></code></td>
    </tr>
    <tr>
        <td id="prod-string"><emu-t class="regex">string</emu-t></td>
        <td><code>=</code></td>
        <td><code class="regex"><span class="mute">/</span>"[^"]*"<span class="mute">/</span></code></td>
    </tr>
    <tr>
        <td id="prod-whitespace"><emu-t class="regex">whitespace</emu-t></td>
        <td><code>=</code></td>
        <td><code class="regex"><span class="mute">/</span>[\t\n\r ]+<span class="mute">/</span></code></td>
    </tr>
    <tr>
        <td id="prod-comment"><emu-t class="regex">comment</emu-t></td>
        <td><code>=</code></td>
        <td><code class="regex"><span class="mute">/</span><span class="mute">\</span>/<span class="mute">\</span>/.*|<span class="mute">\</span>/\*(.|\n)*?\*<span class="mute">\</span>/<span class="mute">/</span></code></td>
    </tr>
    <tr>
        <td id="prod-other"><emu-t class="regex">other</emu-t></td>
        <td><code>=</code></td>
        <td><code class="regex"><span class="mute">/</span>[^\t\n\r 0-9A-Za-z]<span class="mute">/</span></code></td>
    </tr>
</table>

The tokenizer operates on a sequence of [=scalar values=].
When tokenizing, the longest possible match must be used.  For example, if the input
text is “<span class="input">a1</span>”, it is tokenized as a single <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t>,
and not as a separate <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> and <emu-t class="regex"><a href="#prod-integer">integer</a></emu-t>.
If the longest possible match could match one of the above named terminal symbols or
one of the other terminal symbols from the grammar, it must be tokenized as the latter.
Thus, the input text “<span class="input">long</span>” is tokenized as the terminal symbol
<emu-t>long</emu-t> rather than an <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> called "<code>long</code>",
and “<span class="input">.</span>” is tokenized as the terminal symbol
<emu-t>.</emu-t> rather than an <emu-t class="regex"><a href="#prod-other">other</a></emu-t>.

The IDL syntax is case sensitive, both for the monospaced terminal symbols
used in the grammar and the values used for
<emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> terminals.  Thus, for
example, the input text “<span class="input">Const</span>” is tokenized as
an <emu-t class="regex"><a href="#prod-identifier">identifier</a></emu-t> rather than the
terminal symbol <emu-t>const</emu-t>, an
[=interface=] with
[=identifier=]
"<code>A</code>" is distinct from one named "<code>a</code>", and an
[=extended attribute=]
[<code class="idl">legacyfactoryfunction</code>] will not be recognized as
the [{{LegacyFactoryFunction}}]
extended attribute.

Implicitly, any number of <emu-t class="regex"><a href="#prod-whitespace">whitespace</a></emu-t> and
<emu-t class="regex"><a href="#prod-comment">comment</a></emu-t> terminals are allowed between every other terminal
in the input text being parsed.  Such <emu-t class="regex"><a href="#prod-whitespace">whitespace</a></emu-t> and
<emu-t class="regex"><a href="#prod-comment">comment</a></emu-t> terminals are ignored while parsing.

The following LL(1) grammar, starting with <emu-nt><a href="#prod-Definitions">Definitions</a></emu-nt>,
matches an [=IDL fragment=]:

<div grammar-fill-with="index"></div>

Note: The <emu-nt><a href="#prod-Other">Other</a></emu-nt>
non-terminal matches any single terminal symbol except for
<emu-t>(</emu-t>, <emu-t>)</emu-t>,
<emu-t>[</emu-t>, <emu-t>]</emu-t>,
<emu-t>{</emu-t>, <emu-t>}</emu-t>
and <emu-t>,</emu-t>.

While the <emu-nt><a href="#prod-ExtendedAttribute">ExtendedAttribute</a></emu-nt>
non-terminal matches any non-empty sequence of terminal symbols (as long as any
parentheses, square brackets or braces are balanced, and the
<emu-t>,</emu-t> token appears only within those balanced brackets),
only a subset of those
possible sequences are used by the [=extended attributes=]
defined in this specification — see
[[#idl-extended-attributes]]
for the syntaxes that are used by these extended attributes.


<h2 id="conventions" class="no-num">Document conventions</h2>

The following typographic conventions are used in this document:

*   Defining instances of terms: <dfn id="dfn-example-term">example term</dfn>
*   Links to terms defined in this document or elsewhere: [=example term=]
*   Grammar terminals: <emu-t>sometoken</emu-t>
*   Grammar non-terminals: <emu-nt>ExampleGrammarNonTerminal</emu-nt>
*   Grammar symbols: <emu-t class="regex">identifier</emu-t>
*   IDL types: {{unsigned long}}
*   JavaScript classes: {{Map}}
*   JavaScript language types: Object
*   Code snippets: <code>a = b + obj.f()</code>
*   Scalar values: U+0030 (0)
*   Extended attributes: [<code class="idl">ExampleExtendedAttribute</code>]
*   Variable names in prose and algorithms: <var ignore>exampleVariableName</var>.
*   IDL informal syntax examples:
    <pre highlight="webidl" class="syntax">
        [extended_attributes]
        interface identifier {
          <mark>/* interface_members... */</mark>
        };
    </pre>

    (Specific parts of the syntax discussed in surrounding prose are <mark>highlighted</mark>.)
*   IDL grammar snippets:
    <pre class="grammar no-index">
        ExampleGrammarNonTerminal :
            OtherNonTerminal "sometoken"
            other AnotherNonTerminal
            ε  // nothing
    </pre>
*   Non-normative notes:

    Note: This is a note.

*   Non-normative examples:
    <div class="example" id="example-263fb1aa">
        This is an example.
    </div>
*   Normative warnings:
    <p class="warning">
        This is a warning.
    </p>
*   Code blocks:
    <pre highlight="webidl">
        // This is an IDL code block.
        [Exposed=Window]
        interface Example {
          attribute long something;
        };
    </pre>
    <pre highlight="js">
        // This is a JavaScript code block.
        window.onload = function() { window.alert("loaded"); };
    </pre>

The following conventions are used in the algorithms in this document:

*   Algorithms use the [=ECMAScript/conventions=] of the JavaScript specification,
    including the [=!=] and [=?=] notation for unwrapping [=Completion Records=].
*   Algorithms sometimes treat returning/throwing values and returning [=Completion Records=]
    interchangeably. That is, an algorithm that uses return/throw terminology may be treated as
    returning a [=Completion Record=], while one that returns a [=Completion Record=] may be treated as
    returning a value or throwing an exception. Similarly, to catch exceptions, defining the
    behavior to adopt when [=an exception was thrown=] and checking if the [=Completion Record=]'s
    \[[Type]] field is “throw” are equivalent.
*   [=Completion Records=] are extended by allowing them to contain values that are not JavaScript
    values, such as Web IDL values.


<h2 id="conformance" class="no-num" oldids="conformant-algorithms">Conformance</h2>

Everything in this specification is normative except for diagrams,
examples, notes and sections marked as being informative.

This specification depends on the Infra Standard. [[!INFRA]]

The following conformance classes are defined by this specification:

 :  <dfn id="dfn-conforming-set-of-idl-fragments" export>conforming set of IDL fragments</dfn>
 :: A set of [=IDL fragments=] is considered
    to be a [=conforming set of IDL fragments=] if, taken together, they satisfy all of the
    must-,
    required- and shall-level
    criteria in this specification that apply to IDL fragments.
 :  <dfn id="dfn-conforming-implementation" export>conforming implementation</dfn>
 :: A user agent is considered to be a
    [=conforming implementation=]
    relative to a [=conforming set of IDL fragments=] if it satisfies all of the must-,
    required- and shall-level
    criteria in this specification that apply to implementations for all language
    bindings that the user agent supports.
 :  <dfn id="dfn-conforming-javascript-implementation" oldids="dfn-conforming-ecmascript-implementation" export>conforming JavaScript implementation</dfn>
 :: A user agent is considered to be a
    [=conforming JavaScript implementation=]
    relative to a [=conforming set of IDL fragments=] if it satisfies all of the must-,
    required- and shall-level
    criteria in this specification that apply to implementations for the JavaScript
    language binding.


<p boilerplate=ipr>This Living Standard includes material copied from W3C's
<a href=https://www.w3.org/TR/2016/REC-WebIDL-1-20161215/><cite>WebIDL [sic] Level 1</cite></a>,
which is available under the
<a href=https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document>W3C Software and Document License</a>.


<script type="module" class="remove">
// This is a copy of the script from webidl-grammar-post-processor. It will fill in the various
// `grammar-fill-with=""` parts of the document at runtime, allowing local development to just use
// `bikeshed` instead of the whole `make` process. In fully-built versions, it is removed by
// webidl-grammar-post-processor.

let output = "";
for (const pre of document.querySelectorAll("pre.grammar")) {
    const html = pre.textContent.replace(/("[^"]+")|([a-zA-Z]+)|(:)/g, m => {
        if (/^"/.test(m)) {
            return `<emu-t>${m.replace(/^"|"$/g, "")}</emu-t>`;
        }
        if (/^(integer|decimal|identifier|string|whitespace|comment|other)$/.test(m)) {
          return `<emu-t class="regex"><a href="#prod-${m}">${m}</a></emu-t>`;
        }
        if (m == ":") {
            return "::";
        }
        if (document.querySelector(`#prod-${m}`)) {
          return `<emu-nt><a href="#prod-${m}">${m}</a></emu-nt>`;
        }
        return `<emu-nt>${m}</emu-nt>`;
    });

    pre.innerHTML = html;

    const fillWith = document.querySelectorAll(`div[grammar-fill-with="${pre.id.replace("prod-", "")}"]`);
    for (const div of fillWith) {
        div.innerHTML = wrap(html);
    }

    if (!pre.classList.contains("no-index")) {
      output += html
        .replace(/<emu-nt>/, `<emu-nt id="${pre.id.replace("prod-", "index-prod-")}">`)
        .replace(/#prod-([^a-z])/g, "#index-prod-$1") + "\n";
    }
}

document.querySelector("div[grammar-fill-with=\"index\"]").innerHTML = wrap(output);

for (const el of document.querySelectorAll("[grammar-fill-with]")) {
  el.removeAttribute("grammar-fill-with");
}

function wrap(s) {
    return `<pre class=grammar>${s}</pre>`;
}
</script>