Web IDL Standard

Web IDL Standard
Web IDL
Living Standard — Last Updated
27 March 2026
Participate:
GitHub whatwg/webidl
new issue
open issues
Chat on Matrix
Commits:
GitHub whatwg/webidl/commits
Snapshot as of this commit
@webidl
Tests:
web-platform-tests webidl/
ongoing work
Translations
(non-normative)
简体中文
한국어
Abstract
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.
1.
Introduction
This section is informative.
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.
The term "JavaScript" is used to refer to ECMA-262, rather than the official term ECMAScript, since the term JavaScript is more widely known.
2.
Interface definition language
This section describes a language,
Web IDL
, which can be used to define
interfaces for APIs in the Web platform. A specification that defines Web APIs
can include one or more
IDL fragments
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
Definitions
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
definitions
that can appear in an
IDL fragment
are:
interfaces
partial interface definitions
interface mixins
partial mixin definitions
callback functions
callback interfaces
namespaces
partial namespace definitions
dictionaries
partial dictionary definitions
typedefs
and
includes statements
These are all defined in the following sections.
Each
definition
(matching
Definition
can be preceded by a list of
extended attributes
(matching
ExtendedAttributeList
),
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
§ 2.14 Extended attributes
while those specific to the JavaScript language binding are discussed
in
§ 3.3 Extended attributes
extended_attributes
interface
identifier
/* interface_members... */
};
Definitions
::
ExtendedAttributeList
Definition
Definitions
Definition
::
CallbackOrInterfaceOrMixin
Namespace
Partial
Dictionary
Enum
Typedef
IncludesStatement
The following is an example of an
IDL fragment
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
double
double
width
double
height
);
undefined
drawText
double
double
DOMString
text
);
};
Here, four
interfaces
are being defined.
The
GraphicalWindow
interface has two
read only
attributes
one writable attribute, and two
operations
defined on it. Objects that implement the
GraphicalWindow
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
GraphicalWindow
objects; each JavaScript object that implements
GraphicalWindow
will have that prototype object in its prototype chain.
The
constructor operation
that appears on
GraphicalWindow
causes a
constructor
to exist in JavaScript implementations,
so that calling
new GraphicalWindow()
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
global object
is a
Window
object.
2.1.
Names
Every
interface
partial interface definition
namespace
partial namespace definition
dictionary
partial dictionary definition
enumeration
callback function
callback interface
and
typedef
(together called
named definitions
and every
constant
attribute
and
dictionary member
has an
identifier
, as do some
operations
The identifier is determined by an
identifier
token somewhere
in the declaration:
For
named definitions
the
identifier
token that appears
directly after the
interface
namespace
dictionary
enum
or
callback
keyword
determines the identifier of that definition.
interface
interface_identifier
{ /* interface_members... */ };
partial
interface
interface_identifier
{ /* interface_members... */ };
namespace
namespace_identifier
{ /* namespace_members... */ };
partial
namespace
namespace_identifier
{ /* namespace_members... */ };
dictionary
dictionary_identifier
{ /* dictionary_members... */ };
partial
dictionary
dictionary_identifier
{ /* dictionary_members... */ };
enum
enumeration_identifier
"enum"
"values"
/* , ... */ };
callback
callback_identifier
return_type
(/* arguments... */);
callback
interface
callback_interface_identifier
{ /* interface_members... */ };
For
attributes
typedefs
and
dictionary members
the final
identifier
token before the
semicolon at the end of the declaration determines the identifier.
extended_attributes
interface
identifier
attribute
type
attribute_identifier
};
typedef
type
typedef_identifier
dictionary
identifier
type
dictionary_member_identifier
};
For
constants
the
identifier
token before the
equals sign determines the identifier.
const
type
constant_identifier
= 42;
For
operations
, the
identifier
token that appears
after the return type but before the opening parenthesis (that is,
one that is matched as part of the
OptionalOperationName
grammar symbol in an
OperationRest
) determines the identifier of the operation. If
there is no such
identifier
token,
then the operation does not have an identifier.
interface
interface_identifier
return_type
operation_identifier
(/* arguments... */);
};
Note:
Operations can have no identifier when they are being used to declare a
special kind of operation
, such as a getter or setter.
For all of these constructs, the
identifier
is the value of the
identifier
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 "
interface
" 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
identifier
token or by one of the keywords that match the
ArgumentNameKeyword
symbol. If one of these keywords is used, it need not be escaped with a leading
underscore.
interface
interface_identifier
return_type
operation_identifier
argument_type
argument_identifier
/* , ... */);
};
ArgumentNameKeyword
::
attribute
callback
const
constructor
deleter
dictionary
enum
getter
includes
inherit
interface
iterable
maplike
mixin
namespace
partial
readonly
required
setlike
setter
static
stringifier
typedef
unrestricted
If an
identifier
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
ArgumentNameKeyword
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 "
constructor
",
toString
",
or begin with a U+005F (_). These
are known as
reserved identifiers
Although the "
toJSON
identifier
is not a
reserved identifier
it must only be used for
regular operations
that convert objects to
JSON types
as described in
§ 2.5.3.1 toJSON
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
Therefore, the following
IDL fragment
is valid:
Exposed
Window
interface
undefined
SequenceOfLongs
);
};

Exposed
Window
interface
};
typedef
sequence
long
SequenceOfLongs
The following
IDL fragment
demonstrates how
identifiers
are given to definitions and
interface members
// 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
object
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
};
Note that while the second
attribute
on the
TextField
interface
need not have been escaped with an underscore (because "
value
" is
not a keyword in the IDL grammar), it is still unescaped
to obtain the attribute’s
identifier
2.2.
Interfaces
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
interface
is a definition (matching
interface
InterfaceRest
) that declares some
state and behavior that an object implementing that interface will expose.
extended_attributes
interface
identifier
/* interface_members... */
};
An interface is a specification of a set of
interface members
(matching
InterfaceMembers
).
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
inherit
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.
interface
identifier
identifier_of_inherited_interface
/* interface_members... */
};
The order that members appear in has significance for property enumeration in the
JavaScript binding
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.
Consider the following two interfaces.
Exposed
Window
interface
undefined
();
undefined
();
};

Exposed
Window
interface
undefined
();
undefined
DOMString
);
};
In the JavaScript language binding, an instance of
will have a prototype chain that looks like the following:
[Object.prototype: the Object prototype object]
[A.prototype: interface prototype object for A]
[B.prototype: interface prototype object for B]
[instanceOfB]
Calling
instanceOfB.f()
in JavaScript will invoke the f defined
on
. However, the f from
can still be invoked on an object that implements
by
calling
A.prototype.f.call(instanceOfB)
The
inherited interfaces
of
a given interface
is the set of all interfaces that
inherits from, directly or indirectly. If
does not
inherit
from another interface, then the set is empty. Otherwise, the set
includes the interface
that
inherits
from and all of
’s
inherited interfaces
An interface must not be declared such that
its inheritance hierarchy has a cycle. That is, an interface
cannot inherit from itself, nor can it inherit from another
interface
that inherits from
, and so on.
The
list
of
inclusive inherited interfaces
of an
interface
is defined as follows:
Let
result
be « ».
Let
interface
be
While
interface
is not null:
Append
interface
to
result
Set
interface
to the
interface
that
inherits
from, if any, and
null otherwise.
Return
result
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
which means that it also implements all of
’s
inherited interfaces
In addition, an
includes statement
can be used
to define that objects implementing an
interface
will always also include the
members
of the
interface mixins
includes
Each interface member can be preceded by a list of
extended attributes
(matching
ExtendedAttributeList
),
which can control how the interface member will be handled in language bindings.
extended_attributes
interface
identifier

extended_attributes
const
type
constant_identifier
= 42;

extended_attributes
attribute
type
identifier

extended_attributes
return_type
identifier
(/* arguments... */);
};
The IDL for interfaces can be split into multiple parts by using
partial interface
definitions
(matching
partial
interface
PartialInterfaceRest
).
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.
interface
SomeInterface
/* interface_members... */
};
partial
interface
SomeInterface
/* interface_members... */
};
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
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
The
qualified name
of an
interface
interface
is defined as follows:
Let
identifier
be the
identifier
of
interface
If
interface
has a [
LegacyNamespace
extended attribute
, then:
Let
namespace
be the identifier argument of the [
LegacyNamespace
extended attribute
Return the
concatenation
of «
namespace
identifier
» with
separator U+002E (.).
Return
identifier
CallbackOrInterfaceOrMixin
::
callback
CallbackRestOrInterface
interface
InterfaceOrMixin
InterfaceOrMixin
::
InterfaceRest
MixinRest
InterfaceRest
::
identifier
Inheritance
InterfaceMembers
Partial
::
partial
PartialDefinition
PartialDefinition
::
interface
PartialInterfaceOrPartialMixin
PartialDictionary
Namespace
PartialInterfaceOrPartialMixin
::
PartialInterfaceRest
MixinRest
PartialInterfaceRest
::
identifier
PartialInterfaceMembers
InterfaceMembers
::
ExtendedAttributeList
InterfaceMember
InterfaceMembers
InterfaceMember
::
PartialInterfaceMember
Constructor
PartialInterfaceMembers
::
ExtendedAttributeList
PartialInterfaceMember
PartialInterfaceMembers
PartialInterfaceMember
::
Const
Operation
Stringifier
StaticMember
Iterable
AsyncIterable
ReadOnlyMember
ReadWriteAttribute
ReadWriteMaplike
ReadWriteSetlike
InheritAttribute
Inheritance
::
identifier
The following
IDL fragment
demonstrates the definition of two mutually referential
interfaces
Both
Human
and
Dog
inherit from
Animal
. Objects that implement
either of those two interfaces will thus have a
name
attribute.
Exposed
Window
interface
Animal
attribute
DOMString
name
};

Exposed
Window
interface
Human
Animal
attribute
Dog
pet
};

Exposed
Window
interface
Dog
Animal
attribute
Human
owner
};
The following
IDL fragment
defines
simplified versions of a DOM
interfaces
and a
callback interface
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
);
};
Plain objects can implement a
callback interface
like
EventListener
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.
It is not possible for such an object to implement an
interface
like
Node
, however:
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.
2.3.
Interface mixins
An
interface mixin
is a definition (matching
interface
MixinRest
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
interface
mixin
identifier
/* mixin_members... */
};
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
§ 2.3.1 Using mixins and partials
An
interface mixin
is a specification of a set of
interface mixin members
(matching
MixinMembers
),
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
asynchronously iterable
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
partial interface mixin
definitions
(matching
partial
interface
MixinRest
).
The
identifier
of a
partial interface mixin
definition
must
be the same as the
identifier
of an
interface mixin
definition
All of the
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
interface
mixin
SomeMixin
/* mixin_members... */
};
partial
interface
mixin
SomeMixin
/* mixin_members... */
};
The order that members appear in has significance for property enumeration
in the
JavaScript binding
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
includes statement
is a definition
(matching
IncludesStatement
used to declare that all objects implementing an
interface
(identified by the first
identifier
must additionally include the
members
of
interface mixin
(identified by the second identifier).
Interface
is said to
include
interface mixin
interface_identifier
includes
mixin_identifier
The first
identifier
must reference a
interface
The second identifier must reference an
interface mixin
Each
member
of
is considered to be
member
of each
interface
, … that
includes
as if a copy of each
member
had been made.
So for a given member
of
interface
is considered to have a
member
interface
is considered to have a
member
interface
is considered to have a
member
, and so on.
The
host interfaces
of
and
, are
, and
respectively.
Note:
In JavaScript, this implies that each
regular operation
declared as a
member
of
interface mixin
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
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
Member
order isn’t clearly specified,
in particular when
interface mixins
are defined in separate documents.
It is discussed in
issue #432
No
extended attributes
defined in this specification are applicable to
includes statements
The following
IDL fragment
defines an
interface
Entry
and an
interface mixin
Observable
The
includes statement
specifies that
Observable
’s
members
are always included on objects implementing
Entry
interface
Entry
readonly
attribute
unsigned
short
entryType
// ...
};
interface
mixin
Observable
undefined
addEventListener
DOMString
type
EventListener
listener
boolean
useCapture
);
// ...
};
Entry
includes
Observable
A JavaScript implementation would thus have an
addEventListener
property in the prototype chain of every
Entry
var
getEntry
();
// Obtain an instance of Entry.
typeof
addEventListener
// Evaluates to "function".
CallbackOrInterfaceOrMixin
::
callback
CallbackRestOrInterface
interface
InterfaceOrMixin
InterfaceOrMixin
::
InterfaceRest
MixinRest
Partial
::
partial
PartialDefinition
PartialDefinition
::
interface
PartialInterfaceOrPartialMixin
PartialDictionary
Namespace
MixinRest
::
mixin
identifier
MixinMembers
MixinMembers
::
ExtendedAttributeList
MixinMember
MixinMembers
MixinMember
::
Const
RegularOperation
Stringifier
OptionalReadOnly
AttributeRest
IncludesStatement
::
identifier
includes
identifier
2.3.1.
Using mixins and partials
This section is informative.
Interface mixins
allow the sharing of
attributes
constants
, and
operations
across
multiple
interfaces
If you’re only planning to extend a single interface,
you might consider using a
partial interface
instead.
For example, instead of:
interface
mixin
WindowSessionStorage
readonly
attribute
Storage
sessionStorage
};
Window
includes
WindowSessionStorage
do:
partial
interface
Window
readonly
attribute
Storage
sessionStorage
};
Additionally, you can rely on extending
interface mixins
exposed by other specifications
to target common use cases, such as
exposing
a set of
attributes
constants
, or
operations
across both window and worker contexts.
For example, instead of the common but verbose:
interface
mixin
GlobalCrypto
readonly
attribute
Crypto
crypto
};
Window
includes
GlobalCrypto
WorkerGlobalScope
includes
GlobalCrypto
you can extend the
WindowOrWorkerGlobalScope
interface mixin
using a
partial interface mixin
partial
interface
mixin
WindowOrWorkerGlobalScope
readonly
attribute
Crypto
crypto
};
2.4.
Callback interfaces
callback interface
is a
definition
matching
callback
interface
identifier
CallbackInterfaceMembers
It can be implemented by any object, as described in
§ 2.12 Objects implementing interfaces
Note:
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.
callback interface
is a specification of a set of
callback interface members
(matching
CallbackInterfaceMembers
).
These are the
members
that appear between the braces in the interface declaration.
callback
interface
identifier
/* interface_members... */
};
Note:
See also the similarly named
callback function
definition.
Callback interfaces
must define exactly one
regular operation
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
handleEvent
) 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).
Callback interfaces
which declare
constants
must be annotated with an [
Exposed
extended attribute
CallbackRestOrInterface
::
CallbackRest
interface
identifier
CallbackInterfaceMembers
CallbackInterfaceMembers
::
ExtendedAttributeList
CallbackInterfaceMember
CallbackInterfaceMembers
CallbackInterfaceMember
::
Const
RegularOperation
2.5.
Members
Interfaces
interface mixins
, and
namespaces
are specifications of a set of
members
(respectively matching
InterfaceMembers
MixinMembers
, and
NamespaceMembers
),
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.
When an
interface
includes
an
interface mixin
, each
member
of the interface mixin is also considered a member of the interface. In contrast,
inherited
interface members are not considered members
of the interface.
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
this
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
the given value
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
§ 2.2 Interfaces
§ 2.3 Interface mixins
§ 2.4 Callback interfaces
, and
§ 2.6 Namespaces
and summarized in the following informative table:
Interfaces
Callback interfaces
Interface mixins
Namespaces
Constants
Regular attributes
Only
read only
attributes
Static attributes
Regular Operations
Stringifiers
Special Operations
Static Operations
Iterable declarations
Asynchronously iterable declarations
Maplike declarations
Setlike declarations
2.5.1.
Constants
constant
is a declaration (matching
Const
) used to bind a constant value to a name.
Constants can appear on
interfaces
and
callback interfaces
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
filing an issue
before proceeding.
const
type
constant_identifier
= 42;
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 "
length
", "
name
" or "
prototype
".
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
ConstType
must not be any type other than
primitive type
If an
identifier
is used,
it must reference a
typedef
whose type is a primitive type.
The
ConstValue
part of a
constant declaration gives the value of the constant, which can be
one of the two boolean literal tokens (
true
and
false
), an
integer
token,
decimal
token,
or one of the three special floating point constant values
-Infinity
Infinity
and
NaN
).
Note:
These values – in addition to strings and the empty sequence – can also be used to specify the
default value of a dictionary member
or
of an optional argument
Note that strings, the
empty sequence
[]
, and the default dictionary
{}
cannot be used as the value of a
constant
The value of the boolean literal tokens
true
and
false
are the IDL
boolean
values
true
and
false
The value of an
integer
token
is an integer whose value is determined as follows:
Let
be the sequence of
scalar values
matched by the
integer
token.
Let
sign
be −1 if
begins with U+002D (-), and 1 otherwise.
Let
base
be the base of the number based on the
scalar values
that follow the optional leading U+002D (-):
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.
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
Return
sign
number
The type of an
integer
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
integer
token must not
lie outside the valid range of values for its type, as given in
§ 2.13 Types
The value of a
decimal
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:
Let
be the sequence of
scalar values
matched by the
decimal
token.
Let
result
be the Mathematical Value that would be obtained if
were parsed as a JavaScript
NumericLiteral
If the
decimal
token is being
used as the value for a
float
or
unrestricted float
, then
the value of the
decimal
token
is the IEEE 754 single-precision floating point number closest to
result
Otherwise, the
decimal
token is being
used as the value for a
double
or
unrestricted double
, and
the value of the
decimal
token
is the IEEE 754 double-precision floating point number closest to
result
[IEEE-754]
The value of a constant value specified as
Infinity
-Infinity
, or
NaN
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:
Type
unrestricted float
, constant value
Infinity
The value is the IEEE 754 single-precision positive infinity value.
Type
unrestricted double
, constant value
Infinity
The value is the IEEE 754 double-precision positive infinity value.
Type
unrestricted float
, constant value
-Infinity
The value is the IEEE 754 single-precision negative infinity value.
Type
unrestricted double
, constant value
-Infinity
The value is the IEEE 754 double-precision negative infinity value.
Type
unrestricted float
, constant value
NaN
The value is the IEEE 754 single-precision NaN value with the bit pattern 0x7fc00000.
Type
unrestricted double
, constant value
NaN
The value is the IEEE 754 double-precision NaN value with the bit pattern 0x7ff8000000000000.
The type of a
decimal
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
decimal
token must not
lie outside the valid range of values for its type, as given in
§ 2.13 Types
Also,
Infinity
-Infinity
and
NaN
must not
be used as the value of a
float
or
double
The value of the
null
token is the special
null
value that is a member of the
nullable types
. The type of
the
null
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
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.
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:
Exposed
Window
interface
const
short
rambaldi
= 47;
};
the constant value can be accessed in JavaScript either as
A.rambaldi
or
instanceOfA.rambaldi
The following extended attributes are applicable to constants:
CrossOriginIsolated
],
Exposed
], and
SecureContext
].
Const
::
const
ConstType
identifier
ConstValue
ConstValue
::
BooleanLiteral
FloatLiteral
integer
BooleanLiteral
::
true
false
FloatLiteral
::
decimal
-Infinity
Infinity
NaN
ConstType
::
PrimitiveType
identifier
The following
IDL fragment
demonstrates how
constants
of the above types can be defined.
Exposed
Window
interface
Util
const
boolean
DEBUG
false
const
octet
LF
= 10;
const
unsigned
long
BIT_MASK
= 0x0000fc00;
const
double
AVOGADRO
= 6.022e23;
};
2.5.2.
Attributes
An
attribute
is an
interface member
or
namespace member
(matching
inherit
AttributeRest
static
OptionalReadOnly
AttributeRest
stringifier
OptionalReadOnly
AttributeRest
OptionalReadOnly
AttributeRest
or
AttributeRest
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:
regular attributes
, which are those
used to declare that objects implementing the
interface
will have a data field member with the given
identifier
interface
interface_identifier
attribute
type
identifier
};
static attributes
, which are used
to declare attributes that are not associated with a particular object implementing the interface
interface
interface_identifier
static
attribute
type
identifier
};
If an attribute has no
static
keyword, then it declares a
regular attribute
. 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
getter steps
of an attribute
attr
should be introduced using text of the form “The
attr
getter steps are:” followed by a list, or “The
attr
getter steps
are to” followed by an inline description.
The
setter steps
of an attribute
attr
should be introduced using text of the form “The
attr
setter steps are:” followed by a list, or “The
attr
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 "
prototype
".
The type of the attribute is given by the type (matching
Type
that appears after the
attribute
keyword.
If the
Type
is an
identifier
or an identifier followed by
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
or non-nullable version of any of the following types:
sequence type
an
async sequence type
dictionary type
record type
union type
that has a nullable or non-nullable sequence type, dictionary,
or record
as one of its
flattened member types
The attribute is
read only
if the
readonly
keyword is used before the
attribute
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.
interface
interface_identifier
readonly
attribute
type
identifier
};
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
].
regular attribute
that is not
read only
can be declared to
inherit its getter
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
inherits its getter
if
its declaration includes
inherit
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
inherit
does not appear on a
read only
attribute
or a
static attribute
Exposed
Window
interface
Ancestor
readonly
attribute
TheType
theIdentifier
};

Exposed
Window
interface
Derived
Ancestor
inherit
attribute
TheType
theIdentifier
};
When the
stringifier
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
§ 2.5.5 Stringifiers
for details.
interface
interface_identifier
stringifier
attribute
DOMString
identifier
};
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
].
ReadOnlyMember
::
readonly
ReadOnlyMemberRest
ReadOnlyMemberRest
::
AttributeRest
MaplikeRest
SetlikeRest
ReadWriteAttribute
::
AttributeRest
InheritAttribute
::
inherit
AttributeRest
AttributeRest
::
attribute
TypeWithExtendedAttributes
AttributeName
AttributeName
::
AttributeNameKeyword
identifier
AttributeNameKeyword
::
required
OptionalReadOnly
::
readonly
The following
IDL fragment
demonstrates how
attributes
can be declared on an
interface
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
};
2.5.3.
Operations
An
operation
is an
interface member
callback interface member
or
namespace member
(matching
static
RegularOperation
stringifier
RegularOperation
or
SpecialOperation
that defines a behavior that can be invoked on objects implementing the interface.
There are three kinds of operation:
regular operations
, which
are those used to declare that objects implementing the
interface
will have a method with
the given
identifier
interface
interface_identifier
return_type
identifier
(/* arguments... */);
};
special operations
which are used to declare special behavior on objects
implementing the interface, such as object indexing and stringification
interface
interface_identifier
/* special_keyword */
return_type
identifier
(/* arguments... */);
/* special_keyword */
return_type
(/* arguments... */);
};
static operations
which are used to declare operations that are not associated with
a particular object implementing the interface
interface
interface_identifier
static
return_type
identifier
(/* arguments... */);
};
If an operation has an identifier but no
static
keyword, then it declares a
regular operation
If the operation has a
special keyword
used in its declaration (that is, any keyword matching
Special
, or
the
stringifier
keyword),
then it declares a special operation. A single operation can declare
both a regular operation and a special operation;
see
§ 2.5.6 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 "
prototype
".
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
return type
of the operation is given
by the type (matching
Type
that appears before the operation’s optional
identifier
If the return type is an
identifier
followed by
then the identifier must
identify an
interface
dictionary
enumeration
callback function
callback interface
or
typedef
An operation’s arguments (matching
ArgumentList
are given between the parentheses in the declaration. Each individual argument is specified
as a type (matching
Type
) followed by an
identifier
(matching
ArgumentName
).
Note:
For expressiveness, the identifier of an operation argument can also be specified
as one of the keywords matching the
ArgumentNameKeyword
symbol without needing to escape it.
If the
Type
of an operation argument is an identifier
followed by
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
, 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
inner type
must not be a
dictionary type
interface
interface_identifier
return_type
identifier
type
identifier
type
identifier
/* , ... */);
};
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
ExtendedAttributeList
),
which can control how a value passed as the argument will be handled in
language bindings.
interface
interface_identifier
return_type
identifier
([
extended_attributes
type
identifier
, [
extended_attributes
type
identifier
/* , ... */);
};
The following
IDL fragment
demonstrates how
regular operations
can be declared on an
interface
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
);
};
An operation or
constructor operation
is considered to be
variadic
if the final argument uses the
...
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
...
token unless it
is the final argument in the operation’s argument list.
interface
interface_identifier
return_type
identifier
type
...
identifier
);
return_type
identifier
type
identifier
type
...
identifier
);
};
Extended attributes
that
take an argument list
([
LegacyFactoryFunction
], of those
defined in this specification) and
callback functions
are also considered to be
variadic
when the
...
token is used in their argument lists.
The following
IDL fragment
defines an interface that has
two variadic operations:
Exposed
Window
interface
IntegerSet
readonly
attribute
unsigned
long
cardinality
undefined
union
long
...
ints
);
undefined
intersection
long
...
ints
);
};
In the JavaScript binding, variadic operations are implemented by
functions that can accept the subsequent arguments:
var
getIntegerSet
();
// Obtain an instance of IntegerSet.
union
();
// Passing no arguments corresponding to 'ints'.
union
);
// Passing three arguments corresponding to 'ints'.
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.
An argument is considered to be an
optional argument
if it is declared with the
optional
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
interface
interface_identifier
return_type
identifier
type
identifier
optional
type
identifier
);
};
Optional arguments can also have a
default value
specified. If the argument’s identifier is followed by a U+003D (=)
and a value (matching
DefaultValue
),
then that gives the optional argument its
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.
interface
interface_identifier
return_type
identifier
type
identifier
optional
type
identifier
= "value");
};
It is strongly suggested not to use a
default value
of
true
for
boolean
-typed arguments,
as this can be confusing for authors who might otherwise expect the default
conversion of
undefined
to be used (i.e.,
false
).
[API-DESIGN-PRINCIPLES]
If the type of an argument is a
dictionary type
or a
union type
that has
dictionary type
as one
of its
flattened member types
, and that dictionary type and its ancestors have no
required
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.
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
{}
, 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.
When a boolean literal token (
true
or
false
),
the
null
token,
an
integer
token, a
decimal
token or one of
the three special floating point literal values (
Infinity
-Infinity
or
NaN
) is used as the
default value
it is interpreted in the same way as for a
constant
When the
undefined
token is used as the
default value
the value is the IDL
undefined
value.
Optional argument default values can also be specified using a
string
token, whose
value
is a
string type
determined as follows:
Let
be the sequence of
scalar values
matched by
the
string
token
with its leading and trailing U+0022 (")
scalar values
removed.
Depending on the type of the argument:
DOMString
USVString
an
enumeration
type
The value of the
string
token
is
ByteString
Assert:
doesn’t contain any
code points
higher than U+00FF.
The value of the
string
token
is the
isomorphic encoding
of
If the type of the
optional argument
is an
enumeration
, then its
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
[]
, 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
inner type
is a
sequence type
or a
union type
or
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
{}
, which represents a default-initialized (as if from ES
null
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
The following
IDL fragment
defines an
interface
with a single
operation
that can be invoked with two different argument list lengths:
Exposed
Window
interface
ColorCreator
object
createColor
double
v1
double
v2
double
v3
optional
double
alpha
);
};
It is equivalent to an
interface
that has two
overloaded
operations
Exposed
Window
interface
ColorCreator
object
createColor
double
v1
double
v2
double
v3
);
object
createColor
double
v1
double
v2
double
v3
double
alpha
);
};
The following
IDL fragment
defines an
interface
with an operation that takes a dictionary argument:
dictionary
LookupOptions
boolean
caseSensitive
false
};

Exposed
Window
interface
AddressBook
boolean
hasAddressForName
USVString
name
optional
LookupOptions
options
= {});
};
If
hasAddressForName
is called with only one argument, the
second argument will be a default-initialized
LookupOptions
dictionary, which will cause
caseSensitive
to be set to
false
The following extended attributes are applicable to operations:
CrossOriginIsolated
],
Default
],
Exposed
],
LegacyUnforgeable
],
NewObject
], and
SecureContext
].
The
method steps
of an operation
operation
should be introduced using text of the form
“The
operation
arg1
arg2
, ...)
method
steps are:” followed by a list, or “The
operation
arg1
arg2
, ...)
method steps are to” followed by an inline description.
Note:
When defining
method steps
, you implicitly have access to
this
DefaultValue
::
ConstValue
string
null
undefined
Operation
::
RegularOperation
SpecialOperation
RegularOperation
::
Type
OperationRest
SpecialOperation
::
Special
RegularOperation
Special
::
getter
setter
deleter
OperationRest
::
OptionalOperationName
ArgumentList
OptionalOperationName
::
OperationName
OperationName
::
OperationNameKeyword
identifier
OperationNameKeyword
::
includes
ArgumentList
::
Argument
Arguments
Arguments
::
Argument
Arguments
Argument
::
ExtendedAttributeList
ArgumentRest
ArgumentRest
::
optional
TypeWithExtendedAttributes
ArgumentName
Default
Type
Ellipsis
ArgumentName
ArgumentName
::
ArgumentNameKeyword
identifier
Ellipsis
::
...
ArgumentNameKeyword
::
attribute
callback
const
constructor
deleter
dictionary
enum
getter
includes
inherit
interface
iterable
maplike
mixin
namespace
partial
readonly
required
setlike
setter
static
stringifier
typedef
unrestricted
2.5.3.1.
toJSON
By declaring a
toJSON
regular operation
an
interface
specifies how to convert the objects that implement it to
JSON types
The
toJSON
regular operation
is reserved for this usage.
It must take zero arguments and return a
JSON type
The
JSON types
are:
numeric types
boolean
string types
nullable types
whose
inner type
is a
JSON type
annotated types
whose
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
members
declared on the dictionary and all its
inherited dictionaries
are
JSON types
records
where all of their
values
are
JSON types
object
interface types
that have a
toJSON
operation declared on themselves or
one of their
inherited interfaces
How the
toJSON
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
toJSON
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
toJSON
operation can take a [
Default
extended attribute
in which case the
default toJSON steps
are exposed instead.
The following
IDL fragment
defines an interface
Transaction
that has a
toJSON
method defined in prose:
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
};
The
toJSON
regular operation
of
Transaction
interface
could be defined as follows:
The
toJSON()
method steps are:
Let
json
be a new
map
For each
attribute
identifier
attr
in « "from", "to", "amount", "description" »:
Let
value
be the result of running the
getter steps
of
attr
on
this
Set
json
attr
] to
value
Return
json
In the JavaScript language binding, there would exist a
toJSON()
method on
Transaction
objects:
// 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
);
2.5.4.
Constructor operations
If an
interface
has a
constructor operation
member (matching
Constructor
), 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
constructor steps
of a
constructor operation
that is a member of an interface
named
interface
should be introduced using text of the form “The
new
interface
arg1
arg2
, ...)
constructor steps
are:” followed by a list, or “The
new
interface
arg1
arg2
, ...)
constructor steps
are to” followed by an inline description.
The
constructor steps
must do nothing, initialize the value passed as
this
, or throw an
exception.
If the constructor does not initialize
this
, one can write “The
new Example(
init
constructor
steps are to do nothing.”
See
§ 3.7.1 Interface object
for details on how a
constructor operation
is to be implemented.
The following IDL defines two interfaces. The second has
constructor operations
, while the
first does not.
Exposed
Window
interface
NodeList
Node
item
unsigned
long
index
);
readonly
attribute
unsigned
long
length
};

Exposed
Window
interface
Circle
constructor
();
constructor
double
radius
);
attribute
double
attribute
double
cx
attribute
double
cy
readonly
attribute
double
circumference
};
A JavaScript implementation supporting these interfaces would implement a [[Construct]]
internal method on the
Circle
interface object which would return a
new object that
implements
the interface.
It would take either zero or one argument.
It is unclear whether the
NodeList
interface
object would implement a [[Construct]] internal method. In any case, trying to use it as a
constructor will cause a
TypeError
to be thrown.
[whatwg/webidl Issue #698]
var
new
Circle
();
// This uses the zero-argument constructor to create a
// reference to a platform object that implements the
// Circle interface.
var
new
Circle
1.25
);
// This also creates a Circle object, this time using
// the one-argument constructor.
var
new
NodeList
();
// This would throw a TypeError, since no
// constructor is declared.
Constructor
::
constructor
ArgumentList
ArgumentList
::
Argument
Arguments
Arguments
::
Argument
Arguments
Argument
::
ExtendedAttributeList
ArgumentRest
ArgumentRest
::
optional
TypeWithExtendedAttributes
ArgumentName
Default
Type
Ellipsis
ArgumentName
ArgumentName
::
ArgumentNameKeyword
identifier
Ellipsis
::
...
ArgumentNameKeyword
::
attribute
callback
const
constructor
deleter
dictionary
enum
getter
includes
inherit
interface
iterable
maplike
mixin
namespace
partial
readonly
required
setlike
setter
static
stringifier
typedef
unrestricted
2.5.5.
Stringifiers
When an
interface
has a
stringifier
, it indicates that objects
that implement the interface have a non-default conversion to a string. Stringifiers can be
specified using a
stringifier
keyword, which creates a stringifier operation when
used alone.
interface
interface_identifier
stringifier
};
Prose accompanying the interface must define
the
stringification behavior
of the interface.
The
stringifier
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
stringifier
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
static attribute
interface
interface_identifier
stringifier
attribute
DOMString
identifier
};
On a given
interface
, there must exist at most one stringifier.
Stringifier
::
stringifier
StringifierRest
StringifierRest
::
OptionalReadOnly
AttributeRest
The following
IDL fragment
defines an interface that will stringify to the value of its
name
attribute:
Exposed
Window
interface
Student
constructor
();
attribute
unsigned
long
id
stringifier
attribute
DOMString
name
};
In the JavaScript binding, using a
Student
object in a context where a string is expected will result in the
value of the object’s
name
property being
used:
var
new
Student
();
id
12345678
name
'周杰倫'
var
greeting
'Hello, '
'!'
// Now greeting == 'Hello, 周杰倫!'.
The following
IDL fragment
defines an interface that has custom stringification behavior that is
not specified in the IDL itself.
Exposed
Window
interface
Student
constructor
();
attribute
unsigned
long
id
attribute
DOMString
familyName
attribute
DOMString
givenName
stringifier
};
Thus, there needs to be prose to explain the stringification behavior.
We assume that the
familyName
and
givenName
attributes are backed by
family name and given name concepts, respectively.
The
stringification behavior
steps are:
If
this
’s family name is null, then return
this
’s given name.
Return the concatenation of
this
’s given name, followed by U+0020 SPACE, followed by
this
’s family name.
A JavaScript implementation of the IDL would behave as follows:
var
new
Student
();
id
12345679
familyName
'Smithee'
givenName
'Alan'
var
greeting
'Hi '
// Now greeting == 'Hi Alan Smithee'.
2.5.6.
Special operations
special operation
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
special keyword
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:
Special operation
Keyword
Purpose
Getters
getter
Defines behavior for when an object is indexed for property retrieval.
Setters
setter
Defines behavior for when an object is indexed for property
assignment or creation.
Deleters
deleter
Defines behavior for when an object is indexed for property deletion.
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.
The following IDL fragment defines an interface with a getter and a setter:
Exposed
Window
interface
Dictionary
readonly
attribute
unsigned
long
propertyCount
getter
double
DOMString
propertyName
);
setter
undefined
DOMString
propertyName
double
propertyValue
);
};
In language bindings that do not support property getters and setters,
objects implementing
Dictionary
will not
have that special behavior.
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.
The following two interfaces are equivalent:
Exposed
Window
interface
Dictionary
readonly
attribute
unsigned
long
propertyCount
getter
double
getProperty
DOMString
propertyName
);
setter
undefined
setProperty
DOMString
propertyName
double
propertyValue
);
};
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
);
};
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
named property getters
and
named property setters
and ones that take an
unsigned long
as a property index, known as
indexed property getters
and
indexed property setters
There is only one variety of deleter:
named property deleters
See
§ 2.5.6.1 Indexed properties
and
§ 2.5.6.2 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.
2.5.6.1.
Indexed properties
An
interface
that defines an
indexed property getter
is said to
support indexed properties
By extension, a
platform object
is said to
support indexed properties
if
it implements an
interface
that itself does.
If an interface
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
supported property indices
Interfaces that
support indexed properties
must define
an
integer-typed
attribute
named "
length
".
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
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
);
};
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 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
determine the value of an indexed property
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
set the value of an existing indexed property
and how to
set the value of a new indexed property
for a given property index and value.
Note that if an
indexed property getter
or
setter
is specified using an
operation
with an
identifier
then indexing an object with an integer that is not a
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:
Exposed
Window
interface
getter
DOMString
toWord
unsigned
long
index
);
};
Assume that an object implementing
has
supported property indices
in the range 0 ≤
index
< 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:
var
getA
();
toWord
);
// Evalautes to "zero".
];
// Also evaluates to "zero".
toWord
);
// Evaluates to "five".
];
// Evaluates to undefined, since there is no property "5".
The following
IDL fragment
defines an interface
OrderedMap
which allows
retrieving and setting values by name or by index number:
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
);
};
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
get()
operation is
defined to return
null
if an
attempt is made to look up a non-existing entry in the
OrderedMap
, then the following
two sentences would suffice:
An object
map
implementing
OrderedMap
supports indexed properties with indices in the range
0 ≤
index
map.size
Such objects also support a named property for every name that,
if passed to
get()
, would return a non-null value.
As described in
§ 3.9 Legacy platform objects
a JavaScript implementation would create
properties on a
legacy platform object
implementing
OrderedMap
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:
// Assume map is a legacy platform object implementing the OrderedMap interface.
var
map
getOrderedMap
();
var
map
];
// If map.length > 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
false
// This will do the equivalent of:
//
// map.setByIndex(1, false)
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")
2.5.6.2.
Named properties
An
interface
that defines a
named property getter
is said to
support named properties
By extension, a
platform object
is said to
support named properties
if
it implements an
interface
that itself does.
If an interface
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
supported property names
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
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
);
};
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
determine the value of a named property
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
set the value of an existing named property
and how to
set the value of a new named property
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
delete an existing named property
for a given property name.
Note:
As with
indexed properties
if an
named property getter
setter
or
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.
2.5.7.
Static attributes and operations
Static attributes
and
static operations
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
static
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.
StaticMember
::
static
StaticMemberRest
StaticMemberRest
::
OptionalReadOnly
AttributeRest
RegularOperation
The following
IDL fragment
defines an interface
Circle
that has a static
operation declared on it:
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
);
};
In the JavaScript language binding, the
function object
for
triangulate
and the accessor property for
triangulationCount
will exist on the
interface object
for
Circle
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
].
triangulate
// As does this
circles
].
triangulationCount
// And this
// Call the static operation
var
triangulationPoint
Circle
triangulate
circles
],
circles
],
circles
]);
// Find out how many triangulations we have done
window
alert
Circle
triangulationCount
);
2.5.8.
Overloading
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
overloaded
. 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
effective overload set
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.
For example, the overloads for both
and
are disallowed:
Exposed
Window
interface
undefined
();
};
partial
interface
undefined
double
);
undefined
();
};
partial
interface
undefined
DOMString
);
};
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.
An
effective overload set
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
items
of an
effective overload set
are
tuples
of the form
callable
type list
optionality list
whose
items
are described below:
callable
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
type list
is a
list
of IDL types.
An
optionality list
is a
list
of
three possible
optionality values
– "required", "optional" or "variadic" –
indicating whether the argument at a given index was
declared as being
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.
The algorithm below describes how to
compute the effective overload set
The following input variables are used, if they are required:
the identifier of the operation or legacy factory function is
the argument count is
the interface is
Whenever an argument of an extended attribute is mentioned,
it is referring to an argument of the extended attribute’s
named argument list
Let
be an
ordered set
Let
be an
ordered set
with
items
as follows,
according to the kind of
effective overload set
For regular operations
The elements of
are the
regular operations
with
identifier
defined on interface
For static operations
The elements of
are the
static operations
with
identifier
defined on interface
For constructors
The elements of
are the
constructor operations
on interface
For legacy factory functions
The elements of
are the
LegacyFactoryFunction
extended attributes
on interface
whose
named argument lists'
identifiers are
Let
maxarg
be the maximum number of arguments the operations,
legacy factory functions, or callback functions in
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
undefined f(long x, long... y);
is considered to be declared to take two arguments.
Let
max
be
max
maxarg
).
For each
operation or extended attribute
in
Let
arguments
be the
list
of arguments
is declared to take.
Let
be the
size
of
arguments
Let
types
be a
type list
Let
optionalityValues
be an
optionality list
For each
argument
in
arguments
Append
the type of
argument
to
types
Append
"variadic" to
optionalityValues
if
argument
is a final, variadic argument,
"optional" if
argument
is
optional
and "required" otherwise.
Append
the
tuple
types
optionalityValues
) to
If
is declared to be
variadic
, then:
For each
in
the range
to
max
− 1, inclusive:
Let
be a
type list
Let
be an
optionality list
For each
in
the range
0 to
− 1, inclusive:
Append
types
] to
Append
optionalityValues
] to
For each
in
the range
to
, inclusive:
Append
types
− 1] to
Append
"variadic" to
Append
the
tuple
) to
Let
be
− 1.
While
≥ 0:
If
arguments
] is not
optional
(i.e., it is not marked as "optional" and is not
a final, variadic argument), then
break
Let
be a
type list
Let
be an
optionality list
For each
in
the range
0 to
− 1, inclusive:
Append
types
] to
Append
optionalityValues
] to
Append
the
tuple
) to
Note:
if
is 0, this means to add to
the tuple (
, « », « »);
(where "« »" represents an
empty list
).
Set
to
− 1.
Return
For the following interface:
Exposed
Window
interface
/* f1 */
undefined
DOMString
);
/* f2 */
undefined
Node
DOMString
double
...
);
/* f3 */
undefined
();
/* f4 */
undefined
Event
DOMString
optional
DOMString
double
...
);
};
assuming
Node
and
Event
are two other interfaces of which no object can implement both,
the
effective overload set
for
regular operations
with
identifier
and argument count 4 is:
(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 »)
Two types are
distinguishable
if
the following algorithm returns
true
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
false
None of the following pairs are distinguishable:
double
and
Dictionary1
(Interface1 or
long
)?
and
(Interface2 or
DOMString
)?
(Interface1 or
long
?)
and
(Interface2 or
DOMString
)?
(Interface1 or
long
?)
and
(Interface2 or
DOMString
?)
(Dictionary1 or
long
and
(Interface2 or
DOMString
)?
(Dictionary1 or
long
and
(Interface2 or
DOMString
?)
If both types are either a
union type
or
nullable
union type
return
true
if each member type of the one
is distinguishable with each member type of the other,
or
false
otherwise.
If one type is a
union type
or nullable union type,
return
true
if each
member type
of the union type is distinguishable
with the non-union type,
or
false
otherwise.
Consider the two "innermost" types derived by taking each type’s
inner type
if it is an
annotated type
, and then taking its
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
true
Otherwise return
false
Categories:
interface-like
interface types
buffer source types
dictionary-like
dictionary types
record types
callback interface types
sequence-like
sequence types
frozen array types
undefined
boolean
numeric types
bigint
string types
object
symbol
interface-like
callback function
dictionary-like
async sequence
sequence-like
undefined
boolean
numeric types
(b)
bigint
string types
(d)
object
symbol
interface-like
(a)
callback function
(c)
dictionary-like
async sequence
sequence-like
The two identified interface-like types are
not the same, and no single
platform object
implements both
interface-like types.
The types are distinguishable, but there is
a separate restriction on their use in
overloading
below. Please also note
the
advice about using unions of these types
callback function
that does not have
LegacyTreatNonObjectAsNull
] extended attribute is
distinguishable from a type in the dictionary-like category.
For example, when converting an ECMAScript value to
union type
which includes a
callback function
and a
dictionary-like type, if the value is
callable
then it is converted to a
callback function
. Otherwise, it is
converted to a dictionary-like type.
The types are distinguishable, but when converting from an ECMAScript value,
string object
is never converted to an
async sequence type
(even if it has a
%Symbol.iterator%
method), if a
string type
is also in the overload set or union.
double
and
DOMString
are distinguishable because
there is a ● at the intersection of
numeric types
with
string types
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
Given:
callback
interface
CBIface
undefined
handle
();
};

Exposed
Window
interface
Iface
attribute
DOMString
attr2
};
dictionary
Dict
DOMString
field1
};
CBIface
is distinguishable from
Iface
because there’s a ● at the intersection of dictionary-like and interface-like,
but it is not distinguishable from
Dict
because there’s no ● at the intersection of dictionary-like and itself.
Promise types
do not appear in the above table, and as a consequence are
not distinguishable with any other type.
If there is more than one
item
in an
effective overload set
that has a given
type list
size
then for those items there must be an index
such that
for each pair of items the types at index
are
distinguishable
The lowest such index is termed the
distinguishing argument index
for the items of the
effective overload set
with the given type list size.
An
effective overload set
must not contain more than
one
item
with the same
type list
size
, where one
item
has a
bigint
argument at the
distinguishing argument index
and another has a
numeric type
argument at the
distinguishing argument index
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
Node
and
Event
are
distinguishable
The following use of overloading however is invalid:
Exposed
Window
interface
undefined
DOMString
);
undefined
USVString
);
};
since
DOMString
and
USVString
are not distinguishable.
In addition, for each index
, where
is less than the
distinguishing argument index
for a given type list size, the types at index
in
all of the items' type lists must be the same,
and the
optionality values
at index
in all of the items' optionality lists must
be the same.
The following is invalid:
Exposed
Window
interface
/* f1 */
undefined
DOMString
);
/* f2 */
undefined
long
double
Node
Node
);
/* f3 */
undefined
double
double
DOMString
Node
);
};
For argument count 4, the
effective overload set
is:
(f1, « DOMString », « required »),
(f2, « long, double, Node, Node », « required, required, required, required »),
(f3, « double, double, DOMString, Node », « required, required, required, required »)
Looking at items with type list size 4, the
distinguishing argument index
is 2, since
Node
and
DOMString
are
distinguishable
However, since the arguments in these two overloads at index 0 are different,
the overloading is invalid.
2.5.8.1.
Overloading vs. union types
This section is informative.
For specifications defining IDL
operations
, it might seem that
overloads
and a
combination of
union types
and
optional arguments
have some feature overlap.
It is first important to note that
overloads
have different behaviors than
union types
or
optional arguments
, and one
cannot
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
stroke()
operations defined on the
CanvasDrawPath
interface
[HTML]
interface
CanvasDrawPathExcerpt
undefined
stroke
();
undefined
stroke
Path2D
path
);
};
Per the JavaScript language binding, calling
stroke(undefined)
on an object
implementing
CanvasDrawPathExcerpt
would attempt to call the second
overload, yielding a
TypeError
since
undefined
cannot be
converted
to a
Path2D
. However, if the operations were instead
defined with
optional arguments
and merged into one,
interface
CanvasDrawPathExcerptOptional
undefined
stroke
optional
Path2D
path
);
};
the
overload resolution algorithm
would treat the
path
argument as missing
given the same call
stroke(undefined)
, 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
stroke()
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,
overloading
will result in more expressive IDL fragments.
This is almost never appropriate API design, and separate operations with distinct
names usually are a better choice for such cases.
Suppose there is an operation
calculate()
that accepts a
long
DOMString
, or
CalculatableInterface
(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
interface
long
calculate
long
input
);
DOMString
calculate
DOMString
input
);
CalculatableInterface
calculate
CalculatableInterface
input
);
};
than using a
union type
with a
typedef
as
typedef
long
or
DOMString
or
CalculatableInterface
Calculatable
interface
Calculatable
calculate
Calculatable
input
);
};
which does not convey the fact that the return value is always of the same type as
input
If the specified
calculate()
is a new API and does not have any
compatibility concerns, it is suggested to use different names for the overloaded operations,
perhaps as
interface
long
calculateNumber
long
input
);
DOMString
calculateString
DOMString
input
);
CalculatableInterface
calculateCalculatableInterface
CalculatableInterface
input
);
};
which allows Web developers to write explicit and unambiguous code.
When the operation has significantly different semantics for different argument types or
lengths,
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
supports(property, value)
and
supports(conditionText)
operations of the
CSS
interface are defined as the
following IDL fragment
[CSS3-CONDITIONAL]
[CSSOM]
partial
interface
CSS
static
boolean
supports
CSSOMString
property
CSSOMString
value
);
static
boolean
supports
CSSOMString
conditionText
);
};
Using
optional arguments
one can rewrite the IDL fragment as follows:
partial
interface
CSSExcerptOptional
static
boolean
supports
CSSOMString
propertyOrConditionText
optional
CSSOMString
value
);
};
Even though the IDL is shorter in the second version, two distinctively different concepts are
conflated in the first argument. Without
overloads
, the question "is
property
or
conditionText
paired with
value
?"
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:
The
supports(
property
value
method steps are:
The
supports(
conditionText
method steps are:
Yet using
value
as an
optional argument
, the specification author has to
use more boilerplate-style text to effectively replicate the
overload resolution algorithm
The
supports(
propertyOrConditionText
value
method steps are:
If
value
is given, then:
Let
property
be
propertyOrConditionText
Otherwise:
Let
conditionText
be
propertyOrConditionText
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.
typedef
long
long
or
DOMString
or
CalculatableInterface
SupportedArgument
interface
undefined
add
SupportedArgument
operand1
SupportedArgument
operand2
);
};
For the
add()
operation above, to specify it using
overloads
would require
interface
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
);
};
and nine times the corresponding prose!
Specification authors are encouraged to treat missing argument and
undefined
argument the same way in the JavaScript language binding.
Given the following IDL fragment:
interface
undefined
foo
();
undefined
foo
Node
arg
);
};
Using the JavaScript language binding, calling
foo(undefined)
and
foo(null)
would both run the steps corresponding to the
foo(
arg
operation, with
arg
set to null, while
foo()
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
foo()
and
foo(undefined)
as "
arg
is missing".
interface
undefined
foo
optional
Node
arg
);
};
In general, optionality is best expressed using the
optional
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
conversion algorithms
of
union types
and
optional arguments
are simpler to implement and reason about than
those
of
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.
2.5.9.
Iterable declarations
An
interface
can be declared to be
iterable
by using an
iterable declaration
(matching
Iterable
) in the body of the interface.
interface
interface_identifier
iterable
value_type
>;
iterable
key_type
value_type
>;
};
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
entries
forEach
keys
values
, and
%Symbol.iterator%
properties on its
interface prototype object
If a single type parameter is given, then the interface has a
value iterator
and provides
values of the specified type.
If two type parameters are given, then the interface has a
pair iterator
and provides
value pairs
with the given types.
value pair
, given a key type and a value type, is a
struct
with two
items
an
item
whose
name
is "key", which is referred to as the
value pair
’s
key
, and whose value is an IDL value of the key type;
an
item
whose
name
is "value", which is referred to as the
value pair
’s
value
, and whose value is an IDL value of the
value type.
value iterator
must only be declared on an interface
that
supports indexed properties
The value-type of the
value iterator
must be the same as the type returned by
the
indexed property getter
value iterator
is implicitly
defined to iterate over the object’s indexed properties.
pair iterator
must not be declared on an interface
that
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
value pairs to iterate over
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
file an issue
Note:
This is how
array iterator objects
work.
For interfaces that
support indexed properties
the iterator objects returned by
entries
keys
values
, and
%Symbol.iterator%
are
actual
array iterator objects
Interfaces
with an
iterable declaration
must not have any
attributes
constants
, or
regular operations
named "
entries
", "
forEach
", "
keys
", or
values
", or have any
inherited interfaces
that have
attributes
constants
or
regular operations
with these names.
Consider the following interface
SessionManager
, which allows access to
a number of
Session
objects keyed by username:
Exposed
Window
interface
SessionManager
Session
getSessionForUser
DOMString
username
);
iterable
DOMString
Session
>;
};

Exposed
Window
interface
Session
readonly
attribute
DOMString
username
// ...
};
The behavior of the iterator could be defined like so:
The
value pairs to iterate over
are the list of
value pairs
with the
key
being the username and the
value
being the open
Session
object on the
SessionManager
object corresponding to that username, sorted by username.
In the JavaScript language binding, the
interface prototype object
for the
SessionManager
interface
has a
values
method that is a function, which, when invoked,
returns an iterator object that itself has a
next
method that returns the
next value to be iterated over. It has
keys
and
entries
methods that iterate over the usernames of session objects
and username/
Session
object pairs, respectively. It also has
%Symbol.iterator%
method that allows a
SessionManager
to be used in a
for..of
loop that has the same value as the
entries
method:
// 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
);
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
].
Iterable
::
iterable
TypeWithExtendedAttributes
OptionalType
OptionalType
::
TypeWithExtendedAttributes
2.5.10.
Asynchronously iterable declarations
An
interface
can be declared to be asynchronously iterable by using an
asynchronously iterable declaration
(matching
AsyncIterable
) in the body of the
interface
interface
interface_identifier
async_iterable
value_type
>;
async_iterable
value_type
>(/* arguments... */);
async_iterable
key_type
value_type
>;
async_iterable
key_type
value_type
>(/* arguments... */);
};
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
value asynchronously iterable declaration
and asynchronously provides values of the
specified type. If two type parameters are given, then the interface has a
pair asynchronously iterable declaration
and asynchronously provides
value pairs
with the given types.
If given, an
asynchronously iterable declaration
’s arguments (matching
ArgumentList
) must all be
optional arguments
In the JavaScript language binding, an interface that is asynchronously iterable will have
%Symbol.asyncIterator%
and
values
properties on its
interface prototype object
. If the interface has a
pair asynchronously iterable declaration
, it will additionally have
entries
and
keys
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,
for
await
of
can work directly on
instances of the interface, since
for
await
of
calls the
%Symbol.asyncIterator%
method with no arguments.
Prose accompanying an
interface
with an
asynchronously iterable declaration
must define a
get the next iteration result
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
end of
iteration
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
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
asynchronous iterator return
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.
In the JavaScript binding, this algorithm allows customizing the behavior when the
async iterator’s
return()
method is invoked. This most commonly occurs when a
break
or
return
statement causes an exit from a
for
await
of
loop.
We could add a similar hook for
throw()
. So far there has been no need,
but if you are creating an API that needs such capabilities, please
file an issue
The prose may also define
asynchronous iterator initialization steps
. These
receive the instance of the
interface
being iterated, the newly-created iterator object, and a
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 "
entries
", "
keys
", or
values
", or have any
inherited interfaces
that have
attributes
constants
or
regular operations
with these names.
Consider the following interface
SessionManager
, which allows access
to a number of
Session
objects keyed by username:
Exposed
Window
interface
SessionManager
Session
getSessionForUser
DOMString
username
);
async_iterable
DOMString
Session
>;
};

Exposed
Window
interface
Session
readonly
attribute
DOMString
username
// ...
};
The behavior of the iterator could be defined like so:
The
asynchronous iterator initialization steps
for a
SessionManager
async iterator
iterator
are:
Set
iterator
’s
current state
to "not
yet started".
To
get the next iteration result
for a
SessionManager
manager
and its async iterator
iterator
Let
promise
be a new promise.
Let
key
be the following value, if it exists, or null otherwise:
If
iterator
’s
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
Note:
iterator
’s
current state
might no longer be
present in the open sessions.
If
key
is null, then:
Resolve
promise
with
end of iteration
Otherwise:
Let
session
be the
Session
object corresponding to
key
Resolve
promise
with (
username
session
).
Set
iterator
’s
current state
to
username
Return
promise
In the JavaScript language binding, the
interface prototype object
for the
SessionManager
interface
has a
values
method that is a
function, which, when invoked, returns an asynchronous iterator object that itself has a
next
method that returns the next value to be iterated over.
It has
keys
and
entries
methods that iterate over the usernames of
session objects and (username,
Session
) object pairs, respectively.
It also has a
%Symbol.asyncIterator%
method that allows a
SessionManager
to be used in a
for await..of
loop that has the same value as the
entries
method:
// 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
);
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
].
these
extended attributes
are not currently taken into account.
When they are, the effect will be as you would expect.
AsyncIterable
::
async_iterable
TypeWithExtendedAttributes
OptionalType
OptionalArgumentList
OptionalArgumentList
::
ArgumentList
2.5.11.
Maplike declarations
An
interface
can be declared to be
maplike
by using a
maplike declaration
(matching
ReadWriteMaplike
or
readonly
MaplikeRest
) in the body of the interface.
interface
interface_identifier
readonly
maplike
key_type
value_type
>;
maplike
key_type
value_type
>;
};
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
map entries
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
readonly
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
readonly
keyword is used, this includes
entries
forEach
get
has
keys
values
%Symbol.iterator%
methods, and a
size
getter.
For read–write maplikes, it also includes
clear
delete
, and
set
methods.
Maplike interfaces must not have any
attributes
constants
, or
regular operations
named
entries
", "
forEach
", "
get
", "
has
",
keys
", "
size
", or "
values
", 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
clear
", "
delete
",
or "
set
", or have any
inherited interfaces
that have
attributes
or
constants
with these names.
Note:
Read-write maplike interfaces
can
have
regular operations
named
clear
", "
delete
", or "
set
", which will override the default
implementation of those methods (defined in
§ 3.7.11 Maplike declarations
). 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
setlike declaration
, or
an
indexed property getter
ReadOnlyMember
::
readonly
ReadOnlyMemberRest
ReadOnlyMemberRest
::
AttributeRest
MaplikeRest
SetlikeRest
ReadWriteMaplike
::
MaplikeRest
MaplikeRest
::
maplike
TypeWithExtendedAttributes
TypeWithExtendedAttributes
No
extended attributes
defined in this specification are applicable to
maplike declarations
Add example.
2.5.12.
Setlike declarations
An
interface
can be declared to be
setlike
by using a
setlike declaration
(matching
ReadWriteSetlike
or
readonly
SetlikeRest
) in the body of the interface.
interface
interface_identifier
readonly
setlike
type
>;
setlike
type
>;
};
Objects implementing an interface that is declared to be setlike
represent an
ordered set
of values, initially empty,
known as that object’s
set entries
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
readonly
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
readonly
keyword is used, this includes
entries
forEach
has
keys
values
%Symbol.iterator%
methods, and a
size
getter.
For read–write setlikes, it also includes
add
clear
, and
delete
methods.
Setlike interfaces must not have any
attributes
constants
, or
regular operations
named
entries
", "
forEach
", "
has
", "
keys
",
size
", or "
values
", 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
add
", "
clear
",
or "
delete
", or have any
inherited interfaces
that have
attributes
or
constants
with these names.
Note:
Read-write setlike interfaces
can
have
regular operations
named
add
", "
clear
", or "
delete
", which will override the default
implementation of those methods (defined in
§ 3.7.12 Setlike declarations
). 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
maplike declaration
, or
an
indexed property getter
ReadOnlyMember
::
readonly
ReadOnlyMemberRest
ReadOnlyMemberRest
::
AttributeRest
MaplikeRest
SetlikeRest
ReadWriteSetlike
::
SetlikeRest
SetlikeRest
::
setlike
TypeWithExtendedAttributes
No
extended attributes
defined in this specification are applicable to
setlike declarations
Add example.
2.6.
Namespaces
namespace
is a definition (matching
Namespace
) that declares a global singleton with
associated behaviors.
namespace
identifier
/* namespace_members... */
};
A namespace is a specification of a set of
namespace members
(matching
NamespaceMembers
), 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
partial namespace
definitions
(matching
partial
Namespace
). 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.
namespace
SomeNamespace
/* namespace_members... */
};
partial
namespace
SomeNamespace
/* namespace_members... */
};
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
JavaScript binding
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
Partial
::
partial
PartialDefinition
PartialDefinition
::
interface
PartialInterfaceOrPartialMixin
PartialDictionary
Namespace
Namespace
::
namespace
identifier
NamespaceMembers
NamespaceMembers
::
ExtendedAttributeList
NamespaceMember
NamespaceMembers
NamespaceMember
::
RegularOperation
readonly
AttributeRest
Const
The following
IDL fragment
defines a
namespace
namespace
VectorUtils
readonly
attribute
Vector
unit
double
dotProduct
Vector
Vector
);
Vector
crossProduct
Vector
Vector
);
};
A JavaScript implementation would then expose a global
VectorUtils
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:
Object
getPrototypeOf
VectorUtils
);
// Evaluates to Object.prototype.
Object
keys
VectorUtils
);
// Evaluates to ["dotProduct", "crossProduct"].
Object
getOwnPropertyDescriptor
VectorUtils
"dotProduct"
);
// Evaluates to { value: , enumerable: true, configurable: true, writable: true }.
Object
getOwnPropertyDescriptor
VectorUtils
"unit"
);
// Evaluates to { get: , enumerable: true, configurable: true }.
2.7.
Dictionaries
dictionary
is a definition (matching
Dictionary
used to define an
ordered map
data type with a fixed, ordered set of
entries
termed
dictionary members
where
keys
are strings and
values
are of a particular type specified in the definition.
dictionary
identifier
/* dictionary_members... */
};
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
inherit
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
cannot inherit from itself, nor can it inherit from another
dictionary
that inherits from
, and so on.
dictionary
Base
/* dictionary_members... */
};
dictionary
Derived
Base
/* dictionary_members... */
};
The
inherited dictionaries
of
a given dictionary
is the set of all dictionaries that
inherits from, directly or indirectly. If
does not
inherit
from another dictionary, then the set is empty. Otherwise, the set
includes the dictionary
that
inherits
from and all of
’s
inherited dictionaries
Dictionary members
can be specified as
required
, meaning that
converting a language-specific value to a dictionary requires providing a value for that member. Any
dictionary member that is not
required
is
optional
Note that specifying
dictionary members
as
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
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
can have
entries
for each of the dictionary members
defined on
and on any of
’s
inherited dictionaries
. Dictionary members that are specified
as
required
, or that are specified as having a
default value
, will always have such corresponding
entries
. Other
members' entries might or might not
exist
in the dictionary value.
In the JavaScript binding, a value of
undefined
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
required
, or will trigger the
default value
if one is present, or will result in no
entry
existing in the dictionary value otherwise.
As with
operation argument default values
, it is strongly
encouraged not to use
true
as the
default value
for
boolean
-typed
dictionary members
, as this can be confusing for authors who might
otherwise expect the default conversion of
undefined
to be used (i.e.,
false
).
[API-DESIGN-PRINCIPLES]
An
ordered map
with string
keys
can be implicitly treated as a dictionary value of a
specific dictionary
if all of its
entries
correspond to
dictionary members
, as long
as those entries have the correct types, and there are
entries
present for any
required
or
defaulted
dictionary members.
dictionary
Descriptor
DOMString
name
sequence
unsigned
long
serviceIdentifiers
};
Descriptor
dictionary could be created as in the following steps:
Let
identifiers
be « 1, 3, 7 ».
Return «[ "name" → "test", "serviceIdentifiers" →
identifiers
]».
Each
dictionary member
(matching
DictionaryMember
) is specified
as a type (matching
Type
) followed by an
identifier
(given by an
identifier
token following
the type). The identifier is the key name of the key–value pair.
If the
Type
is an
identifier
followed by
, 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
, 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
inner type
must not be a
dictionary type
dictionary
identifier
type
identifier
};
If the identifier for an
optional
dictionary member
is followed by a
U+003D (=) and a value (matching
DefaultValue
), then that gives the dictionary member its
default value
, which
is the value used by default when author code or specification text does not provide a value for
that member.
dictionary
identifier
type
identifier
= "value";
};
When a boolean literal token (
true
or
false
),
the
null
token,
an
integer
token, a
decimal
token,
one of the three special floating point literal values (
Infinity
-Infinity
or
NaN
),
string
token, the two
token sequence
[]
, or the two token sequence
{}
is
used as the
default value
it is interpreted in the same way as for an
operation
’s
optional argument default value
If the type of the
dictionary member
is an
enumeration
, then its
default value
if specified must
be one of the
enumeration’s values
If the type of the dictionary member is preceded by the
required
keyword, the member is considered a
required
dictionary member
dictionary
identifier
required
type
identifier
};
The type of a dictionary member must not include
the dictionary it appears on. A type includes a dictionary
if at least one of the following is true:
the type is
the type is a dictionary that
inherits
from
the type is a
nullable type
whose
inner type
includes
the type is a
sequence type
or
frozen array
whose element type includes
the type is a
union type
one of whose
member types
includes
the type is a dictionary, one of whose members or inherited members has
a type that includes
the type is
record
where
includes
As with interfaces, the IDL for dictionaries can be split into multiple parts
by using
partial dictionary
definitions
(matching
partial
Dictionary
).
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.
dictionary
SomeDictionary
/* dictionary_members... */
};
partial
dictionary
SomeDictionary
/* dictionary_members... */
};
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.
For example, with the following definitions:
dictionary
long
long
};
dictionary
long
long
};
dictionary
long
long
};
partial
dictionary
long
long
};
the order of the
dictionary members
of a dictionary value of type
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:
Exposed
Window
interface
Something
undefined
);
};
and this JavaScript code:
var
something
getSomething
();
// Get an instance of Something.
var
var
dict
};
Object
defineProperty
dict
"d"
get
function
()
return
++
});
Object
defineProperty
dict
"c"
get
function
()
return
++
});
something
dict
);
The order that the dictionary members are fetched in determines
what values they will be taken to have. Since the order for
is defined to be c then d,
the value for c will be 1 and the value for d will be 2.
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.
Partial
::
partial
PartialDefinition
PartialDefinition
::
interface
PartialInterfaceOrPartialMixin
PartialDictionary
Namespace
Dictionary
::
dictionary
identifier
Inheritance
DictionaryMembers
DictionaryMembers
::
DictionaryMember
DictionaryMembers
DictionaryMember
::
ExtendedAttributeList
DictionaryMemberRest
DictionaryMemberRest
::
required
TypeWithExtendedAttributes
identifier
Type
identifier
Default
PartialDictionary
::
dictionary
identifier
DictionaryMembers
Default
::
DefaultValue
DefaultValue
::
ConstValue
string
null
undefined
Inheritance
::
identifier
One use of dictionary types is to allow a number of
optional
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
Exposed
Window
interface
Point
constructor
();
attribute
double
attribute
double
};
dictionary
PaintOptions
DOMString
fillPattern
= "black";
DOMString
strokePattern
Point
position
};

Exposed
Window
interface
GraphicsContext
undefined
drawRectangle
double
width
double
height
optional
PaintOptions
options
);
};
In a JavaScript implementation of the IDL, an Object
can be passed in for the
optional
PaintOptions
dictionary:
// Get an instance of GraphicsContext.
var
ctx
getGraphicsContext
();
// Draw a rectangle.
ctx
drawRectangle
300
200
fillPattern
"red"
position
new
Point
10
10
});
The members of
PaintOptions
are
optional
If
fillPattern
is omitted, the definition of
drawRectangle
can assume that it has the given default values
and not include explicit wording to handle its omission.
drawRectangle
needs to explicitly handle the case where
strokePattern
and
position
are omitted.
2.8.
Exceptions
An
exception
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
inherit
from
DOMException
simple exception
is identified by one of the
following types:
EvalError
RangeError
ReferenceError
TypeError
URIError
These correspond to all of the JavaScript
error objects
(apart from
SyntaxError
and
Error
, 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
name
Such
names
are drawn from the
DOMException
names table
below.
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
§ 2.8.2 DOMException derived interfaces
Simple exceptions
can be
created
by providing their
type name. A
DOMException
can be
created
by providing its
name
followed by
DOMException
. Exceptions can also be
thrown
, by providing the same details
required to
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.
Here is are some examples of wording to use to create and throw exceptions.
To throw a new
simple exception
whose type is
TypeError
Throw
TypeError
To throw a new
DOMException
with
name
NotAllowedError
":
Throw
a "
NotAllowedError
DOMException
To create a new
DOMException
with
name
SyntaxError
":
Let
object
be a newly
created
SyntaxError
DOMException
To
reject
a promise with a new
DOMException
with
name
OperationError
":
Reject
with an "
OperationError
DOMException
An example of including additional information used to construct the exception message would
be:
Throw
a "
SyntaxError
DOMException
indicating that the given value
had disallowed trailing spaces.
Such additional context is most helpful to implementers when it is not immediately obvious
why the exception is being thrown, e.g., because there are many different steps in the algorithm
which throw a "
SyntaxError
DOMException
. In contrast, if your specification throws a
NotAllowedError
DOMException
immediately after checking if the user has provided
permission to use a given feature, it’s fairly obvious what sort of message the implementation
ought to construct, and so specifying it is not necessary.
The resulting behavior from creating and throwing an exception is language binding specific.
See
§ 3.14.3 Creating and throwing exceptions
for details on what creating and throwing an
exception entails in the JavaScript language binding.
2.8.1.
Base
DOMException
error names
The
DOMException
names table
below lists all the
allowed
names
for instances of the base
DOMException
interface, along with a
description of what such names mean, and legacy numeric error code values.
Interfaces
inheriting
from
DOMException
, in the manner described
in
§ 2.8.2 DOMException derived interfaces
, will have their own names, not listed in this table.
When
creating
or
throwing
DOMException
, specifications must use
one of these names. If a specification author believes none of these names are a good fit for their
case, they must
file an issue
to discuss adding a new name to the shared namespace, so that the community can coordinate such
efforts. Note that adding new use-case-specific names is only important if you believe web
developers will discriminate multiple error conditions arising from a single API.
The
DOMException
names marked as deprecated are kept for legacy purposes, but
their usage is discouraged.
Note:
Don’t confuse the "
SyntaxError
DOMException
defined here
with JavaScript’s
SyntaxError
SyntaxError
DOMException
is used to report parsing errors in web APIs,
for example when parsing selectors,
while the JavaScript
SyntaxError
is reserved for the JavaScript parser.
To help disambiguate this further,
always favor the "
SyntaxError
DOMException
notation
over just using
SyntaxError
to refer to the
DOMException
[DOM]
Name
Description
Legacy code name and value
IndexSizeError
Deprecated.
Use
RangeError
instead.
INDEX_SIZE_ERR
(1)
HierarchyRequestError
The operation would yield an incorrect
node tree
[DOM]
HIERARCHY_REQUEST_ERR
(3)
WrongDocumentError
The object is in the wrong
document
[DOM]
WRONG_DOCUMENT_ERR
(4)
InvalidCharacterError
The string contains invalid characters.
INVALID_CHARACTER_ERR
(5)
NoModificationAllowedError
The object can not be modified.
NO_MODIFICATION_ALLOWED_ERR
(7)
NotFoundError
The object can not be found here.
NOT_FOUND_ERR
(8)
NotSupportedError
The operation is not supported.
NOT_SUPPORTED_ERR
(9)
InUseAttributeError
The attribute is in use by another
element
[DOM]
INUSE_ATTRIBUTE_ERR
(10)
InvalidStateError
The object is in an invalid state.
INVALID_STATE_ERR
(11)
SyntaxError
The string did not match the expected pattern.
SYNTAX_ERR
(12)
InvalidModificationError
The object can not be modified in this way.
INVALID_MODIFICATION_ERR
(13)
NamespaceError
The operation is not allowed by
Namespaces in XML
[XML-NAMES]
NAMESPACE_ERR
(14)
InvalidAccessError
Deprecated.
Use
TypeError
for invalid arguments,
NotSupportedError
DOMException
for unsupported operations, and
NotAllowedError
DOMException
for denied requests instead.
INVALID_ACCESS_ERR
(15)
TypeMismatchError
Deprecated.
Use
TypeError
instead.
TYPE_MISMATCH_ERR
(17)
SecurityError
The operation is insecure.
SECURITY_ERR
(18)
NetworkError
A network error occurred.
NETWORK_ERR
(19)
AbortError
The operation was aborted.
ABORT_ERR
(20)
URLMismatchError
Deprecated.
URL_MISMATCH_ERR
(21)
QuotaExceededError
Deprecated.
Use the
QuotaExceededError
DOMException
-derived interface instead.
QUOTA_EXCEEDED_ERR
(22)
TimeoutError
The operation timed out.
TIMEOUT_ERR
(23)
InvalidNodeTypeError
The supplied
node
is incorrect or has an incorrect ancestor for this operation.
[DOM]
INVALID_NODE_TYPE_ERR
(24)
DataCloneError
The object can not be cloned.
DATA_CLONE_ERR
(25)
EncodingError
The encoding operation (either encoded or decoding) failed.
NotReadableError
The I/O read operation failed.
UnknownError
The operation failed for an unknown transient reason (e.g. out of memory).
ConstraintError
A mutation operation in a transaction failed because a constraint was not satisfied.
[INDEXEDDB]
DataError
Provided data is inadequate.
TransactionInactiveError
A request was placed against a transaction which is currently not active, or which is finished.
[INDEXEDDB]
ReadOnlyError
The mutating operation was attempted in a "readonly" transaction.
[INDEXEDDB]
VersionError
An attempt was made to open a database using a lower version than the existing version.
[INDEXEDDB]
OperationError
The operation failed for an operation-specific reason.
NotAllowedError
The request is not allowed by the user agent or the platform in the current context, possibly because the user denied permission.
OptOutError
The user opted out of the process.
2.8.2.
DOMException
derived interfaces
When an exception needs to carry additional programmatically-introspectable information, beyond what
can be provided with a
DOMException
’s
name
, specification authors can create an
interface
which
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
Error
, and must not be any
of the names in the
DOMException
names table
The
interface
must have a
constructor operation
which sets the instance’s
name
to the interface’s
identifier
Their
constructor operation
must take as its first parameter an
optional
DOMString
named
message
defaulting to the empty string, and must set the instance’s
message
to
message
Their
constructor operation
should take as its second parameter a
dictionary
containing
the additional information that needs to be exposed.
They should have
read only
attributes
, whose names are the same as the members of the
constructor dictionary, which return the values accepted by the constructor operation.
They should be
serializable objects
, whose
serialization steps
and
deserialization steps
preserve the additional information.
These requirements mean that the inherited
code
property of these
interfaces will always return 0.
To
create
or
throw
DOMException
derived interface, supply its
interface
identifier
as well as the additional information needed to construct it.
To throw an instance of
QuotaExceededError
Throw
QuotaExceededError
whose
quota
is 42 and
requested
is 50.
2.8.3.
Predefined
DOMException
derived interfaces
This standard so far defines one predefined
DOMException
derived interface:
[Exposed=*,
Serializable
interface
QuotaExceededError
DOMException
constructor
optional
DOMString
message
= "",
optional
QuotaExceededErrorOptions
options
= {});
readonly
attribute
double
quota
readonly
attribute
double
requested
};
dictionary
QuotaExceededErrorOptions
double
quota
double
requested
};
The
QuotaExceededError
exception can be thrown when a quota is exceeded. It has two properties
that are optionally present, to give more information to the web developer about their request
compared to the quota value.
Previous versions of this standard defined "
QuotaExceededError
" as one
of the
base
DOMException
error names
. It
has been upgraded to a full interface to support including such information.
Every
QuotaExceededError
instance has a
requested
and
quota
, both numbers or null. They are both initially
null.
The
new QuotaExceededError(
message
options
constructor steps are:
Set
this
’s
name
to "
QuotaExceededError
".
Set
this
’s
message
to
message
If
options
["
quota
"] is present:
If
options
["
quota
"] is less than 0, then throw a
RangeError
Set
this
’s
quota
to
options
["
quota
"].
If
options
["
requested
"] is present:
If
options
["
requested
"] is less than 0, then throw a
RangeError
Set
this
’s
requested
to
options
["
requested
"].
If
this
’s
quota
is not null,
this
’s
requested
is not null,
and
this
’s
requested
is less than
this
’s
quota
, then
throw a
RangeError
The
quota
getter steps are to return
this
’s
quota
The
requested
getter steps are to return
this
’s
requested
The
QuotaExceededError
interface inherits the
DOMException
interface’s
code
getter, which will always return 22. However, relying on this value is discouraged (for both
QuotaExceededError
and
DOMException
); it is better to use the
name
getter.
QuotaExceededError
objects are
serializable objects
Their
serialization steps
, given
value
and
serialized
, are:
Run the
DOMException
serialization steps
given
value
and
serialized
Set
serialized
.[[Quota]] to
value
’s
quota
Set
serialized
.[[Requested]] to
value
’s
requested
Their
deserialization steps
, given
serialized
and
value
, are:
Run the
DOMException
deserialization steps
given
serialized
and
value
Set
value
’s
quota
to
serialized
.[[Quota]].
Set
value
’s
requested
to
serialized
.[[Requested]].
Specifications that
create
or
throw
QuotaExceededError
must not
provide a
requested
and
quota
that are both non-null
and where
requested
is less than
quota
2.9.
Enumerations
An
enumeration
is a definition (matching
Enum
) 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
enum
identifier
"enum"
"values"
/* , ... */ };
The
enumeration values
are specified
as a comma-separated list of
string
literals.
The list of
enumeration values
must not include duplicates.
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
createobject
" or "
create-object
".
Consider related uses of enumeration values when deciding whether
to dash-separate or not separate enumeration value words so that
similar APIs are consistent.
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
Enum
::
enum
identifier
EnumValueList
EnumValueList
::
string
EnumValueListComma
EnumValueListComma
::
EnumValueListString
EnumValueListString
::
string
EnumValueListComma
The following
IDL fragment
defines an
enumeration
that is used as the type of an
attribute
and an
operation
argument:
enum
MealType
"rice"
"noodles"
"other"
};

Exposed
Window
interface
Meal
attribute
MealType
type
attribute
double
size
; // in grams
undefined
initialize
MealType
type
double
size
);
};
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
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
meal
type
"noodles"
// Attribute assigned as normal.
meal
type
"dumplings"
// Attribute assignment ignored.
meal
type
==
"noodles"
// Evaluates to true.
2.10.
Callback functions
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?
callback function
is a definition (matching
callback
CallbackRest
) used to declare a function type.
callback
identifier
return_type
(/* arguments... */);
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
Type
and
ArgumentList
) 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
].
CallbackOrInterfaceOrMixin
::
callback
CallbackRestOrInterface
interface
InterfaceOrMixin
CallbackRest
::
identifier
Type
ArgumentList
The following
IDL fragment
defines
callback function
used for an API that
invokes a user-defined function when an operation is complete.
callback
AsyncOperationCallback
undefined
DOMString
status
);

Exposed
Window
interface
AsyncOperations
undefined
performOperation
AsyncOperationCallback
whenFinished
);
};
In the JavaScript language binding, a
function object
is
passed as the operation argument.
var
ops
getAsyncOperations
();
// Get an instance of AsyncOperations.
ops
performOperation
function
status
window
alert
"Operation finished, status is "
status
"."
);
});
2.11.
Typedefs
typedef
is a definition (matching
Typedef
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.
typedef
type
identifier
The
type being given a new name
is specified after the
typedef
keyword (matching
TypeWithExtendedAttributes
), and the
identifier
token following the
type gives the name.
The
Type
must not
be the identifier of the same or another
typedef
No
extended attributes
defined in this specification are applicable to
typedefs
Typedef
::
typedef
TypeWithExtendedAttributes
identifier
The following
IDL fragment
demonstrates the use of
typedefs
to allow the use of a short
identifier
instead of a long
sequence type
Exposed
Window
interface
Point
attribute
double
attribute
double
};
typedef
sequence
Point
Points

Exposed
Window
interface
Widget
boolean
pointWithinBounds
Point
);
boolean
allPointsWithinBounds
Points
ps
);
};
2.12.
Objects implementing interfaces
In a given implementation of a set of
IDL fragments
an object can be described as being a
platform object
Platform objects
are objects
that implement an
interface
Legacy platform objects
are
platform objects
that implement an
interface
which
does not have a [
Global
extended attribute
, and which
supports indexed properties
named properties
, or both.
In a browser, for example,
the browser-implemented DOM objects (implementing interfaces such as
Node
and
Document
) 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
Node
interface
will not be treated as platform objects that implement
Node
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.
2.13.
Types
This section lists the types supported by Web IDL,
the set of values or
Infra
type
corresponding to each type, and how
constants
of that type are represented.
The following types are known as
integer types
byte
octet
short
unsigned short
long
unsigned long
long long
and
unsigned long long
The following types are known as
numeric types
the
integer types
float
unrestricted float
double
and
unrestricted double
The
primitive types
are
bigint
boolean
and the
numeric types
The
string types
are
DOMString
, all
enumeration types
ByteString
and
USVString
The
buffer types
are
ArrayBuffer
and
SharedArrayBuffer
The
typed array types
are
Int8Array
Int16Array
Int32Array
Uint8Array
Uint16Array
Uint32Array
Uint8ClampedArray
BigInt64Array
BigUint64Array
Float16Array
Float32Array
, and
Float64Array
The
buffer view types
are
DataView
and the
typed array types
The
buffer source types
are the
buffer types
and the
buffer view types
The
object
type,
all
interface types
, and
all
callback interface types
are known as
object types
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.
Type
::
SingleType
UnionType
Null
TypeWithExtendedAttributes
::
ExtendedAttributeList
Type
SingleType
::
DistinguishableType
any
PromiseType
UnionType
::
UnionMemberType
or
UnionMemberType
UnionMemberTypes
UnionMemberType
::
ExtendedAttributeList
DistinguishableType
UnionType
Null
UnionMemberTypes
::
or
UnionMemberType
UnionMemberTypes
DistinguishableType
::
PrimitiveType
Null
StringType
Null
identifier
Null
sequence
TypeWithExtendedAttributes
Null
async_sequence
TypeWithExtendedAttributes
Null
object
Null
symbol
Null
BufferRelatedType
Null
FrozenArray
TypeWithExtendedAttributes
Null
ObservableArray
TypeWithExtendedAttributes
Null
RecordType
Null
undefined
Null
ConstType
::
PrimitiveType
identifier
PrimitiveType
::
UnsignedIntegerType
UnrestrictedFloatType
boolean
byte
octet
bigint
UnrestrictedFloatType
::
unrestricted
FloatType
FloatType
FloatType
::
float
double
UnsignedIntegerType
::
unsigned
IntegerType
IntegerType
IntegerType
::
short
long
OptionalLong
OptionalLong
::
long
StringType
::
ByteString
DOMString
USVString
PromiseType
::
Promise
Type
RecordType
::
record
StringType
TypeWithExtendedAttributes
Null
::
2.13.1.
any
The
any
type is the union of all other possible
non-
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
specific type
(Values of
union types
also have
specific types
.)
2.13.2.
undefined
The
undefined
type has a unique value.
undefined
constant values in IDL
are represented with the
undefined
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-
required
dictionary member
Note:
This value was previously spelled
void
and more limited in how it was allowed to be used.
2.13.3.
boolean
The
boolean
type corresponds to
booleans
boolean
constant values in IDL are
represented with the
true
and
false
tokens.
2.13.4.
byte
The
byte
type corresponds to
8-bit signed integers
byte
constant values in IDL are
represented with
integer
tokens.
2.13.5.
octet
The
octet
type corresponds to
8-bit unsigned integers
octet
constant values in IDL are
represented with
integer
tokens.
2.13.6.
short
The
short
type corresponds to
16-bit signed integers
short
constant values in IDL are
represented with
integer
tokens.
2.13.7.
unsigned short
The
unsigned short
type corresponds to
16-bit unsigned integers
unsigned short
constant values in IDL are
represented with
integer
tokens.
2.13.8.
long
The
long
type corresponds to
32-bit signed integers
long
constant values in IDL are
represented with
integer
tokens.
2.13.9.
unsigned long
The
unsigned long
type corresponds to
32-bit unsigned integers
unsigned long
constant values in IDL are
represented with
integer
tokens.
2.13.10.
long long
The
long long
type corresponds to
64-bit signed integers
long long
constant values in IDL are
represented with
integer
tokens.
2.13.11.
unsigned long long
The
unsigned long long
type corresponds to
64-bit unsigned integers
unsigned long long
constant values in IDL are
represented with
integer
tokens.
2.13.12.
float
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
decimal
tokens.
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.
2.13.13.
unrestricted float
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
decimal
tokens.
2.13.14.
double
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
decimal
tokens.
2.13.15.
unrestricted double
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
decimal
tokens.
2.13.16.
bigint
The
bigint
type is an arbitrary integer type, unrestricted in range.
bigint
constant values in IDL are represented with
integer
tokens.
2.13.17.
DOMString
The
DOMString
type corresponds to
strings
Note:
null
is not a value of type
DOMString
. To allow
null
, a
nullable
DOMString
, written as
DOMString?
in IDL, needs to be used.
Note:
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
default values
and
operation optional argument
default values
can be set to
the value
of a
string
literal.
2.13.18.
ByteString
The
ByteString
type corresponds to
byte sequences
There is no way to represent a constant
ByteString
value in IDL, although
ByteString
dictionary member
default values
and
operation optional argument
default values
can be set to
the value
of a
string
literal.
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.
Sequences
or
frozen arrays
with
octet
or
byte
elements,
Uint8Array
, or
Int8Array
should be used for holding
8-bit data rather than
ByteString
2.13.19.
USVString
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
default values
and
operation optional argument
default values
can be set to
the value
of a
string
literal.
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
2.13.20.
object
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
null
value, use the
nullable type
object?
2.13.21.
symbol
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.
2.13.22.
Interface types
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
null
value,
use a
nullable type
2.13.23.
Callback interface types
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
callback context
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
incumbent settings object
at the time the Object value is converted to an IDL
callback interface type value. See
§ 3.2.16 Callback interface types
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
null
value, use a
nullable type
2.13.24.
Dictionary types
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.
2.13.25.
Enumeration types
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
default values
and
operation optional argument
default values
can be set to
the value
of a
string
literal.
2.13.26.
Callback function types
An
identifier
that identifies
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
incumbent settings object
at
the time a JavaScript Object value is converted to an IDL
callback function type value. See
§ 3.2.19 Callback function types
There is no way to represent a constant
callback function
value in IDL.
2.13.27.
Nullable types —
nullable type
is an IDL type constructed
from an existing type (called the
inner type
),
which just allows the additional value
null
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
inner type
must not be:
any
promise type
an
observable array type
another nullable type, or
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
inner type
would be represented, or with the
null
token.
For example, a type that allows the values
true
false
and
null
is written as
boolean?
Exposed
Window
interface
NetworkFetcher
undefined
get
optional
boolean
areWeThereYet
false
);
};
The following
interface
has two
attributes
: one whose value can
be a
DOMString
or the
null
value, and another whose value can be a reference to a
Node
object or the
null
value:
Exposed
Window
interface
Node
readonly
attribute
DOMString
namespaceURI
readonly
attribute
Node
parentNode
// ...
};
2.13.28.
Sequence types — sequence<
The
sequence<
type is a parameterized type whose values are (possibly zero-length)
lists
of
values of type
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
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
sequence<
, as long as it contains
only
items
that are of type
2.13.29.
Async sequence types — async_sequence<
An
async sequence type
is a parameterized
type whose values are references to objects that can produce an asynchronously iterable, possibly infinite,
sequence of values of type
Unlike
sequences
, which are fixed-length lists where all values are known in advance, the asynchronously
iterable sequences created by async sequences 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
sequence is created.
Async sequences are passed by reference in language bindings where they are represented by an object.
This means that passing an async sequence to a
platform object
will result in a reference to the
async sequence being kept by that object. Similarly, any async sequence 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 sequences cannot be constructed from IDL. If returned from an operation, or used as the
type of a dictionary member, the async sequence will have originated from the host environment and
have been turned into an IDL type via a language binding. Instead of returning an async sequence
from an IDL operation, the operation might want to return an
interface
that has an
asynchronously iterable declaration
Async sequences must not be used as the type of an
attribute
or
constant
There is no way to represent an async sequence value in IDL.
2.13.30.
Record types — record<
record type
is a parameterized type whose values are
ordered maps
with
keys
that are instances of
and
values
that are instances of
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
record<
, as long as
it contains only
entries
whose
keys
are all of of type
and whose
values
are all of type
2.13.31.
Promise types — Promise<
promise type
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
section 25.4
of the JavaScript specification for details on the semantics of promise objects.
Promise types are non-nullable, but
may be nullable.
There is no way to represent a promise value in IDL.
2.13.32.
Union types
union type
is a type whose set of values
is the union of those in two or more other types. Union types (matching
UnionType
are written as a series of types separated by the
or
keyword
with a set of surrounding parentheses.
The types which comprise the union type are known as the
union’s
member types
For example, you might write
(Node or DOMString)
or
(double or sequence)
. When applying a
suffix to a
union type
as a whole, it is placed after the closing parenthesis,
as in
(Node or DOMString)?
Note that the
member types
of a union type do not descend into nested union types. So for
(double or (sequence or Event) or (Node or DOMString)?)
the member types
are
double
(sequence or Event)
and
(Node or DOMString)?
Like the
any
type, values of
union types have a
specific type
which is the particular
member type
that matches the value.
The
flattened member types
of a
union type
, possibly
annotated
, is a set of types determined as
follows:
Let
be the
union type
Initialize
to ∅.
For each
member type
of
If
is an
annotated type
, then
set
to be the
inner type
of
If
is a
nullable type
, then
set
to be the
inner type
of
If
is a
union type
, then
add to
the
flattened member types
of
Otherwise,
is not a
union type
Add
to
Return
Note:
For example, the
flattened member types
of the
union type
(Node or (sequence or Event) or (XMLHttpRequest or DOMString)? or sequence<(sequence or NodeList)>)
are the six types
Node
sequence
Event
XMLHttpRequest
DOMString
and
sequence<(sequence or NodeList)>
The
number of nullable member types
of a
union type
is an integer
determined as follows:
Let
be the
union type
Initialize
to 0.
For each
member type
of
If
is a
nullable type
, then:
Set
to
+ 1.
Set
to be the
inner type
of
If
is a
union type
, then:
Let
be the
number of nullable member types
of
Set
to
Return
The
any
type must not
be used as a
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
dictionary type
in its
flattened member types
A type
includes a nullable type
if:
the type is a
nullable type
, or
the type is an
annotated type
and its
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
and
must be
distinguishable
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
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
file an issue
before using this feature.
A type
includes undefined
if:
the type is
undefined
, or
the type is a
nullable type
and its
inner type
includes undefined
, or
the type is an
annotated type
and its
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.
UnionType
::
UnionMemberType
or
UnionMemberType
UnionMemberTypes
UnionMemberType
::
ExtendedAttributeList
DistinguishableType
UnionType
Null
UnionMemberTypes
::
or
UnionMemberType
UnionMemberTypes
DistinguishableType
::
PrimitiveType
Null
StringType
Null
identifier
Null
sequence
TypeWithExtendedAttributes
Null
async_sequence
TypeWithExtendedAttributes
Null
object
Null
symbol
Null
BufferRelatedType
Null
FrozenArray
TypeWithExtendedAttributes
Null
ObservableArray
TypeWithExtendedAttributes
Null
RecordType
Null
undefined
Null
2.13.33.
Annotated types
Additional types can be created from existing ones by specifying certain
extended attributes
on
the existing types. Such types are called
annotated types
, and the types they
annotate are called
inner types
[Clamp] long
defines a new
annotated type
, whose behavior is based on that of
the
inner type
long
, but modified as specified by the [
Clamp
extended attribute.
The following extended attributes are
applicable to types
AllowResizable
],
AllowShared
],
Clamp
],
EnforceRange
], and
LegacyNullToEmptyString
].
The
extended attributes associated with
an IDL type
type
are determined as follows:
Let
extended attributes
be a new empty
set
If
type
appears as part of a
TypeWithExtendedAttributes
production,
append
each of the
extended attributes
present in the production’s
ExtendedAttributeList
to
extended attributes
Exposed
Window
interface
attribute
XAttr
long
attrib
undefined
f1
sequence
<[
XAttr
long
arg
);
undefined
f2
optional
XAttr
long
arg
);
maplike
<[
XAttr2
DOMString
, [
XAttr3
long
>;
};
dictionary
required
XAttr
long
member
};
If
type
is a
member type
of a
union type
append
each of the
extended attributes associated with
to
extended attributes
Exposed
Window
interface
attribute
XAttr
] (
long
or
Node
attrib
};
If
type
appears as part of a
Type
production
directly within an
Argument
production,
append
to
extended attributes
all of the
extended attributes
present in the
production’s
ExtendedAttributeList
that are
applicable to types
Exposed
Window
interface
undefined
([
XAttr
long
attrib
);
};
Note that this is an example of this step only if [
XAttr
] is
applicable to types
; otherwise [
XAttr
] applies to the argument, and not
the argument’s type.
If
type
appears as part of a
Type
production
directly within a
DictionaryMember
production,
append
to
extended attributes
all of the
extended attributes
present in the production’s
ExtendedAttributeList
that are
applicable to types
dictionary
XAttr
long
member
};
Note that this is an example of this step only if [
XAttr
] is
applicable to types
; otherwise [
XAttr
] applies to the dictionary
member, and not the member’s type.
If
type
is a
typedef
append
the
extended attributes associated with
the
type being given a new name
to
extended attributes
typedef
XAttr
long
xlong
Return
extended attributes
For any type, the
extended attributes associated with
it must only contain
extended attributes
that are
applicable to types
2.13.34.
Buffer source types
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.
Type
Kind of buffer
ArrayBuffer
An object that holds a pointer (which can be null) to a buffer of a fixed number of bytes
SharedArrayBuffer
An object that holds a pointer (which cannot be null) to a shared buffer of a fixed number of bytes
DataView
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
Int8Array
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
Int16Array
Int32Array
BigInt64Array
Uint8Array
A view on to a
buffer type
instance that exposes it as an array of unsigned integers of the given size in bits
Uint16Array
Uint32Array
BigUint64Array
Uint8ClampedArray
A view on to a
buffer type
instance that exposes it as an array of
8-bit unsigned integers
with clamped conversions
Float16Array
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]
Float32Array
Float64Array
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
§ 3.2.26 Buffer source types
BufferRelatedType
::
ArrayBuffer
SharedArrayBuffer
DataView
Int8Array
Int16Array
Int32Array
Uint8Array
Uint16Array
Uint32Array
Uint8ClampedArray
BigInt64Array
BigUint64Array
Float16Array
Float32Array
Float64Array
2.13.35.
Frozen array types — FrozenArray<
frozen array type
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
Frozen array types must only be used as the type of
regular attributes
or
static attributes
defined on an
interface
The following
IDL fragment
defines an
interface
with two frozen array attributes, one
read only
and one not.
Exposed
Window
interface
PersonalPreferences
readonly
attribute
FrozenArray
DOMString
favoriteColors
attribute
FrozenArray
DOMString
favoriteFoods
undefined
randomizeFavoriteColors
();
};
The behavior of these attributes could be defined like so:
Each
PersonalPreferences
has associated
favorite colors
, a
FrozenArray
DOMString
>, initially equal to the result of
creating a frozen array
from « "
purple
", "
aquamarine
" ».
Each
PersonalPreferences
has an associated
favorite foods
, a
FrozenArray
DOMString
>, initially equal to the result of
creating a frozen array
from the empty list.
The
favoriteColors
getter steps
are to return
this
’s favorite colors.
The
favoriteFoods
getter steps
are to return
this
’s favorite foods.
The
favoriteFoods
setter steps
are to set
this
’s favorite foods to
the given value
The
randomizeFavoriteColors()
method steps
are:
Let
newFavoriteColors
be a list of two strings representing colors, chosen randomly.
Set
this
’s favorite colors to the result of
creating a frozen array
from
newFavoriteColors
Since
FrozenArray<
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.
2.13.36.
Observable array types — ObservableArray<
An
observable array type
is a parameterized type
whose values are references to a combination of a mutable list of objects of type
, as well as
behavior to perform when author code modifies the contents of the list.
The parameterized type
must not be a
dictionary type
sequence type
record type
or
observable array type
. However,
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:
set an indexed value
, which accepts an IDL
value that is about to be set in the observable array, and the index at which it is being set;
delete an indexed value
, 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
delete an indexed value
algorithm to remove the existing value, and
then the
set an indexed value
algorithm with the new value.
Every
regular attribute
whose type is an
observable array type
has a
backing list
, 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
set an indexed value
and
delete an indexed value
algorithms.
There is no way to represent a constant observable array value in IDL.
The following
IDL fragment
defines an
interface
with an observable array attribute:
Exposed
Window
interface
Building
attribute
ObservableArray
Employee
employees
};
The behavior of the attribute could be defined like so:
The
set an indexed value
algorithm for
Building
’s
employees
attribute, given
employee
and
index
, is:
If
employee
is not allowed to enter the building today, then throw a
NotAllowedError
DOMException
If
index
is greater than or equal to 200, then throw a
QuotaExceededError
whose
quota
is 200 and
requested
is
index
Put
employee
to work!
The
delete an indexed value
algorithm for
Building
’s
employees
attribute, given
employee
and
index
, is:
Alert security that
employee
has left the building.
Then, JavaScript code could manipulate the
employees
property in
various ways:
// 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
);
const
employeeB
building
employees
pop
();
building
employees
new
Employee
"D"
),
employeeB
new
Employee
"C"
)];
building
employees
length
// Will throw:
building
employees
push
"not an Employee; a string instead"
);
All of these manipulations would pass through the above-defined
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
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
Array
instance:
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
===
`[{}]`
);
2.14.
Extended attributes
An
extended attribute
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
ExtendedAttributeList
which is a square bracket enclosed, comma separated list of
ExtendedAttribute
s.
The
ExtendedAttribute
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 grammar symbols to determine
which form (or forms) it is in:
Grammar symbol
Form
Example
ExtendedAttributeNoArgs
takes no arguments
[Replaceable]
ExtendedAttributeArgList
takes an argument list
Not currently used; previously used by
[Constructor(double x, double y)]
ExtendedAttributeNamedArgList
takes a named argument list
[LegacyFactoryFunction=Image(DOMString src)]
ExtendedAttributeIdent
takes an identifier
[PutForwards=name]
ExtendedAttributeString
takes a string
[Reflect="popover"]
ExtendedAttributeInteger
takes an integer
[ReflectDefault=2]
ExtendedAttributeDecimal
takes a decimal
[ReflectDefault=2.0]
ExtendedAttributeIntegerList
takes an integer list
[ReflectRange=(2, 600)]
ExtendedAttributeIdentList
takes an identifier list
[Exposed=(Window,Worker)]
ExtendedAttributeWildcard
takes a wildcard
[Exposed=*]
This specification defines a number of extended attributes that
are applicable to the JavaScript language binding, which are described in
§ 3.3 Extended attributes
Each extended attribute definition will state which of the above
five forms are allowed.
ExtendedAttributeList
::
ExtendedAttribute
ExtendedAttributes
ExtendedAttributes
::
ExtendedAttribute
ExtendedAttributes
ExtendedAttribute
::
ExtendedAttributeInner
ExtendedAttributeRest
ExtendedAttributeInner
ExtendedAttributeRest
ExtendedAttributeInner
ExtendedAttributeRest
Other
ExtendedAttributeRest
ExtendedAttributeRest
::
ExtendedAttribute
ExtendedAttributeInner
::
ExtendedAttributeInner
ExtendedAttributeInner
ExtendedAttributeInner
ExtendedAttributeInner
ExtendedAttributeInner
ExtendedAttributeInner
OtherOrComma
ExtendedAttributeInner
Other
::
integer
decimal
identifier
string
other
-Infinity
...
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
OtherOrComma
::
Other
IdentifierList
::
identifier
Identifiers
Identifiers
::
identifier
Identifiers
IntegerList
::
integer
Integers
Integers
::
integer
Integers
ExtendedAttributeNoArgs
::
identifier
ExtendedAttributeArgList
::
identifier
ArgumentList
ExtendedAttributeIdent
::
identifier
identifier
ExtendedAttributeString
::
identifier
string
ExtendedAttributeInteger
::
identifier
integer
ExtendedAttributeDecimal
::
identifier
decimal
ExtendedAttributeWildcard
::
identifier
ExtendedAttributeIdentList
::
identifier
IdentifierList
ExtendedAttributeIntegerList
::
identifier
IntegerList
ExtendedAttributeNamedArgList
::
identifier
identifier
ArgumentList
3.
JavaScript binding
This section describes how definitions written with the IDL defined in
§ 2 Interface definition language
correspond to particular constructs
in JavaScript, as defined by the
ECMAScript Language Specification
[ECMA-262]
Unless otherwise specified, objects defined in this section are ordinary objects as described in
ECMAScript
§ 10.1 Ordinary Object Internal Methods and Internal Slots
, and if the
object is a
function object
ECMAScript
§ 10.3 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.
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.
This is currently used to define the
HTMLAllCollection
and
Location
interfaces.
[HTML]
Unless otherwise specified, exotic objects defined in this section and other specifications have the
same
internal slots
as ordinary objects, and all of the internal methods for
which alternative definitions are not given are the same as
those
of ordinary objects.
Unless otherwise specified, the [[Extensible]] internal slot
of objects defined in this section has the value
true
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
class string
which is the string to include in the string returned from
Object.prototype.toString
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]]:
false
[[Enumerable]]:
false
, [[Configurable]]:
true
[[Value]]:
classString
}.
Algorithms in this section use the conventions described in
ECMAScript
§ 5.2 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.
When an algorithm says to
throw
Something
Error
then this means to construct a new JavaScript
Something
Error
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.
Consider the following algorithm:
Let
be the JavaScript value passed in to this algorithm.
Let
be the result of calling
ToString
).
Return
Since
ToString
can throw an exception (for example if passed the object
({ toString: function() { throw 1 } })
), 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.
3.1.
JavaScript environment
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
initial objects
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
the function objects that correspond to operations
the function objects that correspond to stringifiers
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
global object
for that realm is created. The [[Prototype]]s
of all initial objects in a given
realm
must come from
that same
realm
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:

title
Different Realms
title
iframe
id
>iframe
script
var
iframe
document
getElementById
"a"
);
var
iframe
contentWindow
// The global object in the frame
Object
==
Object
// Evaluates to false, per ECMA-262
Node
==
Node
// Evaluates to false
iframe
instanceof
Node
// Evaluates to false
iframe
instanceof
Object
// Evaluates to false
iframe
appendChild
instanceof
Function
// Evaluates to true
iframe
appendChild
instanceof
Function
// Evaluates to false
script
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
associated
realm
. 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
callable
proxies, and not bound functions)
the associated realm is equal to the value of the
function object
’s [[Realm]] internal
slot.
3.2.
JavaScript type mapping
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
converted to an IDL value
when passed to a
platform object
expecting that type, and how IDL values
of that type are
converted to JavaScript values
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.
3.2.1.
any
Since the IDL
any
type
is the union of all other IDL types, it can correspond to any
JavaScript value type.
A JavaScript value
is
converted
to an IDL
any
value by running the following algorithm:
If
is
undefined
, then
return the unique
undefined
IDL value.
If
is
null
, then
return the
null
object?
reference.
If
is a Boolean
, then
return the
boolean
value that represents the same truth value.
If
is a Number
, then
return the result of
converting
to an
unrestricted double
If
is a BigInt
, then
return the result of
converting
to a
bigint
If
is a String
, then
return the result of
converting
to a
DOMString
If
is a Symbol
, then
return the result of
converting
to a
symbol
If
is an Object
, then
return an IDL
object
value that references
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.
3.2.2.
undefined
A JavaScript value
is
converted
to an IDL
undefined
value by
returning the unique
undefined
value, ignoring
The unique IDL
undefined
value is
converted
to the
JavaScript
undefined
value.
3.2.3.
boolean
A JavaScript value
is
converted
to an IDL
boolean
value by running the following algorithm:
Let
be the result of computing
ToBoolean
).
Return the IDL
boolean
value that is the one that
represents the same truth value as the
JavaScript Boolean value
The IDL
boolean
value
true
is
converted
to
the JavaScript
true
value and the IDL
boolean
value
false
is converted to the JavaScript
false
value.
3.2.4.
Integer types
Mathematical operations used in this section,
including those defined in
ECMAScript
§ 5.2 Algorithm Conventions
are to be understood as computing exact mathematical results
on mathematical real numbers.
In effect, where
is a Number value,
“operating on
” is shorthand for
“operating on the mathematical real number that represents the same numeric value as
”.
3.2.4.1.
byte
A JavaScript value
is
converted
to an IDL
byte
value by running the following algorithm:
Let
be
ConvertToInt
, 8, "
signed
").
Return the IDL
byte
value that represents the same numeric value as
The result of
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].
3.2.4.2.
octet
A JavaScript value
is
converted
to an IDL
octet
value by running the following algorithm:
Let
be
ConvertToInt
, 8, "
unsigned
").
Return the IDL
octet
value that represents the same numeric value as
The result of
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].
3.2.4.3.
short
A JavaScript value
is
converted
to an IDL
short
value by running the following algorithm:
Let
be
ConvertToInt
, 16, "
signed
").
Return the IDL
short
value that represents the same numeric value as
The result of
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].
3.2.4.4.
unsigned short
A JavaScript value
is
converted
to an IDL
unsigned short
value by running the following algorithm:
Let
be
ConvertToInt
, 16, "
unsigned
").
Return the IDL
unsigned short
value that represents the same numeric value as
The result of
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].
3.2.4.5.
long
A JavaScript value
is
converted
to an IDL
long
value by running the following algorithm:
Let
be
ConvertToInt
, 32, "
signed
").
Return the IDL
long
value that represents the same numeric value as
The result of
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].
3.2.4.6.
unsigned long
A JavaScript value
is
converted
to an IDL
unsigned long
value by running the following algorithm:
Let
be
ConvertToInt
, 32, "
unsigned
").
Return the IDL
unsigned long
value that represents the same numeric value as
The result of
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].
3.2.4.7.
long long
A JavaScript value
is
converted
to an IDL
long long
value by running the following algorithm:
Let
be
ConvertToInt
, 64, "
signed
").
Return the IDL
long long
value that represents the same numeric value as
The result of
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
even significand
if there are
two
equally close values
If the
long long
is in the range
[−2
53
+ 1, 2
53
− 1], then the Number
will be able to represent exactly the same value as the
long long
3.2.4.8.
unsigned long long
A JavaScript value
is
converted
to an IDL
unsigned long long
value by running the following algorithm:
Let
be
ConvertToInt
, 64, "
unsigned
").
Return the IDL
unsigned long long
value that represents the same numeric value as
The result of
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
even significand
if there are
two
equally close values
If the
unsigned long long
is less than or equal to 2
53
− 1,
then the Number will be able to
represent exactly the same value as the
unsigned long long
3.2.4.9.
Abstract operations
IntegerPart(
Let
be
floor
abs
)).
If
< 0, then return -1 ×
Otherwise, return
ConvertToInt(
bitLength
signedness
If
bitLength
is 64, then:
Let
upperBound
be 2
53
− 1.
If
signedness
is "
unsigned
", then let
lowerBound
be 0.
Otherwise let
lowerBound
be −2
53
+ 1.
Note:
this ensures
long long
types
associated with
EnforceRange
] or
Clamp
extended attributes
are representable in JavaScript’s
Number type
as unambiguous integers.
Otherwise, if
signedness
is "
unsigned
", then:
Let
lowerBound
be 0.
Let
upperBound
be 2
bitLength
− 1.
Otherwise:
Let
lowerBound
be -2
bitLength
− 1
Let
upperBound
be 2
bitLength
− 1
− 1.
Let
be
ToNumber
).
If
is −0, then set
to +0.
If the conversion is to an IDL type
associated with
the [
EnforceRange
extended attribute
, then:
If
is
NaN
, +∞, or −∞,
then
throw
TypeError
Set
to
IntegerPart
).
If
lowerBound
or
upperBound
then
throw
TypeError
Return
If
is not
NaN
and the conversion is to an IDL type
associated with
the [
Clamp
] extended attribute,
then:
Set
to
min
max
lowerBound
),
upperBound
).
Round
to the nearest integer, choosing the even integer if it lies halfway between two,
and choosing +0 rather than −0.
Return
If
is
NaN
, +0, +∞, or −∞,
then return +0.
Set
to
IntegerPart
).
Set
to
modulo
bitLength
If
signedness
is "
signed
" and
≥ 2
bitLength
− 1
then return
− 2
bitLength
Otherwise, return
3.2.5.
float
A JavaScript value
is
converted
to an IDL
float
value by running the following algorithm:
Let
be
ToNumber
).
If
is
NaN
, +∞, or −∞,
then
throw
TypeError
Let
be the set of finite IEEE 754 single-precision floating
point values except −0, but with two special values added: 2
128
and
−2
128
Let
be the number in
that is closest
to
, selecting the number with an
even significand
if there are two
equally close values
(The two special values 2
128
and −2
128
are considered to have even significands for this purpose.)
If
is 2
128
or −2
128
, then
throw
TypeError
If
is +0 and
is negative, return −0.
Return
The result of
converting
an IDL
float
value to a JavaScript
value is the Number value that represents the same numeric value as the IDL
float
value.
3.2.6.
unrestricted float
A JavaScript value
is
converted
to an IDL
unrestricted float
value by running the following algorithm:
Let
be
ToNumber
).
If
is
NaN
, then return the IDL
unrestricted float
value that represents the IEEE 754 NaN value with the bit pattern 0x7fc00000
[IEEE-754]
Let
be the set of finite IEEE 754 single-precision floating
point values except −0, but with two special values added: 2
128
and
−2
128
Let
be the number in
that is closest
to
, selecting the number with an
even significand
if there are two
equally close values
(The two special values 2
128
and −2
128
are considered to have even significands for this purpose.)
If
is 2
128
, return +∞.
If
is −2
128
, return −∞.
If
is +0 and
is negative, return −0.
Return
Note:
Since there is only a single JavaScript
NaN
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
The result of
converting
an IDL
unrestricted float
value to a JavaScript
value is a Number:
If the IDL
unrestricted float
value is a NaN,
then the Number value is
NaN
Otherwise, the Number value is
the one that represents the same numeric value as the IDL
unrestricted float
value.
3.2.7.
double
A JavaScript value
is
converted
to an IDL
double
value by running the following algorithm:
Let
be
ToNumber
).
If
is
NaN
, +∞, or −∞,
then
throw
TypeError
Return the IDL
double
value
that represents the same numeric value as
The result of
converting
an IDL
double
value to a JavaScript
value is the Number value that represents the
same numeric value as the IDL
double
value.
3.2.8.
unrestricted double
A JavaScript value
is
converted
to an IDL
unrestricted double
value by running the following algorithm:
Let
be
ToNumber
).
If
is
NaN
, then
return the IDL
unrestricted double
value that represents
the IEEE 754 NaN value with the bit pattern 0x7ff8000000000000
[IEEE-754]
Return the IDL
unrestricted double
value
that represents the same numeric value as
Note:
Since there is only a single JavaScript
NaN
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
The result of
converting
an IDL
unrestricted double
value to a JavaScript
value is a Number:
If the IDL
unrestricted double
value is a NaN,
then the Number value is
NaN
Otherwise, the Number value is
the one that represents the same numeric value as the IDL
unrestricted double
value.
3.2.9.
bigint
A JavaScript value
is
converted
to an IDL
bigint
value by running the following algorithm:
Let
be
ToBigInt
).
Return the IDL
bigint
value that represents the same numeric value as
The result of
converting
an IDL
bigint
value to a JavaScript value is a BigInt:
Return the
BigInt
value that represents the same numeric value as the IDL
bigint
value.
A JavaScript value
is
converted
to an IDL
numeric type
or
bigint
value by running the following algorithm:
Let
be
ToNumeric
).
If
is a BigInt
, then
Return the IDL
bigint
value that represents the same numeric value as
Assert:
is a Number
Return the result of
converting
to
3.2.10.
DOMString
A JavaScript value
is
converted
to an IDL
DOMString
value by running the following algorithm:
If
is
null
and the conversion is to an IDL type
associated with
the [
LegacyNullToEmptyString
] extended
attribute, then return the
DOMString
value that represents the empty string.
Let
be
ToString
).
Return the IDL
DOMString
value that represents the same sequence of code units as the one the JavaScript String value
represents.
The result of
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.
3.2.11.
ByteString
A JavaScript value
is
converted
to an IDL
ByteString
value by running the following algorithm:
Let
be
ToString
).
If the value of any
element
of
is greater than 255, then
throw
TypeError
Return an IDL
ByteString
value
whose length is the length of
, and where the value of each element is
the value of the corresponding element of
The result of
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
element
of which is the value
of the corresponding element of the
ByteString
3.2.12.
USVString
A JavaScript value
is
converted
to an IDL
USVString
value by running the following algorithm:
Let
string
be the result of
converting
to a
DOMString
Return an IDL
USVString
value that is the result of
converting
string
to a sequence of
scalar values
The result of
converting
an IDL
USVString
value
to a JavaScript
value is
3.2.13.
object
IDL
object
values are represented by JavaScript Object values.
A JavaScript value
is
converted
to an IDL
object
value by running the following algorithm:
If
is not an Object
, then
throw
TypeError
Return the IDL
object
value that is a reference to the same object as
The result of
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.
3.2.14.
symbol
IDL
symbol
values are represented by JavaScript Symbol values.
A JavaScript value
is
converted
to an IDL
symbol
value
by running the following algorithm:
If
is not a Symbol
, then
throw
TypeError
Return the IDL
symbol
value that is a reference to the same symbol as
The result of
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.
3.2.15.
Interface types
IDL
interface type
values are represented by JavaScript Object values (including
function objects
).
A JavaScript value
is
converted
to an IDL
interface type
value by running the following algorithm (where
is the
interface
):
If
implements
, then return the IDL
interface type
value that represents a reference to that platform object.
Throw
TypeError
The result of
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.
3.2.16.
Callback interface types
IDL
callback interface type
values are represented by JavaScript Object values (including
function objects
).
A JavaScript value
is
converted
to an IDL
callback interface type
value by running the following algorithm:
If
is not an Object
, then
throw
TypeError
Return the IDL
callback interface type
value that represents a reference to
, with
the
incumbent settings object
as the
callback context
The result of
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.
3.2.17.
Dictionary types
IDL
dictionary type
values are represented
by JavaScript Object values. Properties on
the object (or its prototype chain) correspond to
dictionary members
A JavaScript value
jsDict
is
converted
to an IDL
dictionary type
value by
running the following algorithm (where
is the
dictionary type
):
If
jsDict
is not an Object
and
jsDict
is neither
undefined
nor
null
, then
throw
TypeError
Let
idlDict
be an empty
ordered map
, representing a dictionary of type
Let
dictionaries
be a list consisting of
and all of
’s
inherited dictionaries
in order from least to most derived.
For each dictionary
dictionary
in
dictionaries
, in order:
For each dictionary member
member
declared on
dictionary
, in lexicographical order:
Let
key
be the
identifier
of
member
If
jsDict
is either
undefined
or
null
, then:
Let
jsMemberValue
be
undefined
Otherwise,
Let
jsMemberValue
be
Get
jsDict
key
).
If
jsMemberValue
is not
undefined
, then:
Let
idlMemberValue
be the result of
converting
jsMemberValue
to an IDL value whose type is the type
member
is declared to be of.
Set
idlDict
key
] to
idlMemberValue
Otherwise, if
jsMemberValue
is
undefined
but
member
has a
default value
, then:
Let
idlMemberValue
be
member
’s default value.
Set
idlDict
key
] to
idlMemberValue
Otherwise, if
jsMemberValue
is
undefined
and
member
is
required
, then throw a
TypeError
Return
idlDict
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.
An IDL dictionary value
is
converted
to a JavaScript Object value by
running the following algorithm (where
is the
dictionary
):
Let
be
OrdinaryObjectCreate
%Object.prototype%
).
Let
dictionaries
be a list consisting of
and all of
’s
inherited dictionaries
in order from least to most derived.
For each dictionary
dictionary
in
dictionaries
, in order:
For each dictionary member
member
declared on
dictionary
, in lexicographical order:
Let
key
be the
identifier
of
member
If
key
exists
, then:
Let
idlValue
be
key
].
Let
value
be the result of
converting
idlValue
to a JavaScript value.
Perform
CreateDataPropertyOrThrow
key
value
).
Recall that if
member
has a
default value
then
key
will always
exist
in
Return
3.2.18.
Enumeration types
IDL
enumeration types
are represented by JavaScript String
values.
A JavaScript value
is
converted
to an IDL
enumeration type
value as follows
(where
is the
enumeration
):
Let
be the result of calling
ToString
).
If
is not one of
’s
enumeration values
then
throw
TypeError
Return the enumeration value of type
that is equal to
The result of
converting
an IDL
enumeration type
value to a JavaScript
value is the String
value that represents the same sequence of
code units
as
the
enumeration value
3.2.19.
Callback function types
IDL
callback function types
are represented by JavaScript
function objects
, except in the
LegacyTreatNonObjectAsNull
] case, when they can be any object.
A JavaScript value
is
converted
to an IDL
callback function type
value by running the following algorithm:
If the result of calling
IsCallable
) is
false
and the conversion to an IDL value
is not being performed due
to
being assigned to an
attribute
whose type is a
nullable
callback function
that is annotated with [
LegacyTreatNonObjectAsNull
],
then
throw
TypeError
Return the IDL
callback function type
value
that represents a reference to the same object that
represents, with the
incumbent settings object
as the
callback context
The result of
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.
3.2.20.
Nullable types —
IDL
nullable type
values are represented
by values of either the JavaScript type corresponding to the
inner IDL type
, or
the JavaScript
null
value.
A JavaScript value
is
converted
to an IDL
nullable type
value (where
is the
inner type
) as follows:
If
is not an Object
, and
the conversion to an IDL value is being performed due
to
being assigned to an
attribute
whose type is a
nullable
callback function
that is annotated with [
LegacyTreatNonObjectAsNull
],
then return the IDL
nullable type
value
null
Otherwise, if
is
undefined
and
includes undefined
return the unique
undefined
value.
Otherwise, if
is
null
or
undefined
, then return the IDL
nullable type
value
null
Otherwise, return the result of
converting
using the rules for the
inner IDL type
The result of
converting
an IDL
nullable type
value to a JavaScript value is:
If the IDL
nullable type
value is
null
then the JavaScript value is
null
Otherwise, the JavaScript value is the result of
converting
the IDL
nullable type
value
to the
inner IDL type
3.2.21.
Sequences — sequence<
IDL
sequence<
values are represented by
JavaScript Array values.
A JavaScript value
is
converted
to an IDL
sequence<
value as follows:
If
is not an Object
throw
TypeError
Let
method
be
GetMethod
%Symbol.iterator%
).
If
method
is
undefined
throw
TypeError
Return the result of
creating a sequence
from
and
method
An IDL sequence value
of type
sequence<
is
converted
to a JavaScript Array object as follows:
Let
be the length of
Let
be a new Array object created as if by the expression
[]
Initialize
to be 0.
While
Let
be the value in
at index
Let
be the result of
converting
to a JavaScript value.
Let
be the result of calling
ToString
).
Perform
CreateDataPropertyOrThrow
).
Set
to
+ 1.
Return
3.2.21.1.
Creating a sequence from an iterable
To create an IDL value of type
sequence<
given an iterable
iterable
and an iterator getter
method
perform the following steps:
Let
iteratorRecord
be
GetIteratorFromMethod
iterable
method
).
Initialize
to be 0.
Repeat
Let
next
be
IteratorStepValue
iteratorRecord
).
If
next
is
done
then return an IDL sequence value of type
sequence<
of length
, where the value of the element
at index
is
Initialize
to the result of
converting
next
to an IDL value of type
Set
to
+ 1.
The following
interface
defines
an
attribute
of a sequence
type as well as an
operation
with an argument of a sequence type.
Exposed
Window
interface
Canvas
sequence
DOMString
getSupportedImageCodecs
();
undefined
drawPolygon
sequence
double
coordinates
);
sequence
double
getLastDrawnPolygon
();

// ...
};
In a JavaScript implementation of this interface, an Array
object with elements of type String is used to
represent a
sequence
, while an
Array with elements of type Number
represents a
sequence
. The
Array objects are effectively passed by
value; every time the
getSupportedImageCodecs()
function is called a new Array is
returned, and whenever an Array is
passed to
drawPolygon
no reference
will be kept after the call completes.
// 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
];
// 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
"image/jpeg"
// Evaluates to "image/png".
canvas
getSupportedImageCodecs
()[
];
// This evaluates to false, since a new Array object is returned each call.
canvas
getSupportedImageCodecs
()
==
canvas
getSupportedImageCodecs
();
// An Array of Numbers...
var
100
50
62.5
];
// ...can be passed to a platform object expecting a sequence.
canvas
drawPolygon
);
// 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.
false
""
valueOf
function
()
alert
"hi"
);
return
100
},
"50"
new
Number
62.5
)];
canvas
drawPolygon
);
// 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.
20
var
canvas
getLastDrawnPolygon
();
alert
]);
// This would alert "50".
3.2.22.
Async sequences — async_sequence<
In the JavaScript binding, IDL
async sequence
values are represented by
struct
with the following
items
object
, a JavaScript value
method
, a JavaScript value
type
, either "
sync
" or "
async
A JavaScript value
is
converted
to an IDL
async_sequence<
value as follows:
If
is not an Object
, then
throw
TypeError
Let
method
be
GetMethod
(obj,
%Symbol.asyncIterator%
).
If
method
is
undefined
Set
syncMethod
to
GetMethod
(obj,
%Symbol.iterator%
).
If
syncMethod
is undefined,
throw
TypeError
Return an IDL
async sequence
value with
object
set to
method
set to
syncMethod
, and
type
set to
sync
".
Return an IDL
async sequence
value with
object
set to
method
set to
method
, and
type
set to
async
".
An IDL
async_sequence<
value
is
converted
to a JavaScript object as follows:
Return
’s
object
3.2.22.1.
Iterating async sequences
An
async sequence
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.
Async iterators
are
structs
with the following
items
underlying record
, an
Iterator Record
type parameter
, an IDL type representing the type of values produced by the async iterator
To
open
an
async_sequence<
sequence
Let
iterator
be
GetIteratorFromMethod
sequence
’s
object
sequence
’s
method
).
If
sequence
’s
type
is "
sync
", set
iterator
to
CreateAsyncFromSyncIterator
iterator
).
Return an
async iterator
value with
underlying record
set to
iterator
and
type parameter
set to
To
get the next value
of an
async iterator
iterator
Let
nextResult
be
IteratorNext
iterator
’s
underlying record
).
If
nextResult
is an
abrupt completion
, return
a promise rejected with
nextResult
.[[Value]].
Let
nextPromise
be
a promise resolved with
nextResult
.[[Value]].
Return the result of
reacting
to
nextPromise
with the following fulfillment
steps, given
iterResult
If
iterResult
is not an Object
throw
TypeError
Let
done
be
IteratorComplete
iterResult
).
If
done
is true:
Return
end of iteration
Otherwise:
Let
be
IteratorValue
iterResult
).
Let
value
be the result of
converting
to an IDL
value of type
iterator
’s
type parameter
Return
value
To
close
an
async iterator<
iterator
with an ECMAScript value
reason
Let
iteratorRecord
be
iterator
’s
underlying record
Let
iteratorObj
be
iteratorRecord
.[[Iterator]].
Let
returnMethod
be
GetMethod
iteratorObj
, "
return
").
If
returnMethod
is an
abrupt completion
, return
a promise rejected with
returnMethod
.[[Value]].
If
returnMethod
is
undefined
, return
a promise resolved with
undefined
Let
returnResult
be
Call
returnMethod
.[[Value]],
iteratorObj
, «
reason
»).
If
returnResult
is an
abrupt completion
, return
a promise rejected with
returnResult
.[[Value]].
Let
returnPromise
be
a promise resolved with
returnResult
.[[Value]].
Return the result of
reacting
to
returnPromise
with the following fulfillment steps,
given
returnPromiseResult
If
returnPromiseResult
is not an Object
throw
TypeError
Return
undefined
concatN
is an
operation
that returns a promise that will be fulfilled with the
concatenation of all the strings yielded by the async sequence passed to it. It stops
concatenating and closes the iterator once the async sequence has yielded
maxN
strings.
interface I {
Promise concatN(async_sequence strings, unsigned long maxN);
};
The
concatN(
sequence
maxN
method steps are:
Let
promise
be
a new promise
Let
result
be the empty string.
Let
be 0.
Let
iterator
be the result of
opening
sequence
Let
step
be a sequence of steps that will be used to process the async sequence:
Let
next
be the result of
getting the next value
of
iterator
React
to
next
If
next
was fulfilled with value
If
is
end of iteration
resolve
promise
with
result
Set
result
to the result of concatenating
result
and
Set
to
+ 1.
If
is
maxN
, then:
Let
finish
be the result of
closing
iterator
with reason
undefined
React
to
finish
If
finish
was fulfilled,
resolve
promise
with
result
If
finish
was rejected with reason
reject
promise
with
Otherwise:
Call
step
If
next
was rejected with reason
reject
promise
with
Call
step
Return
promise
3.2.23.
Records — record<
IDL
record
> values are represented by
JavaScript Object values.
A JavaScript value
is
converted
to an IDL
record
value as follows:
If
is not an Object
throw
TypeError
Let
result
be a new empty instance of
record
Let
keys
be
.[[OwnPropertyKeys]]().
For each
key
of
keys
Let
desc
be
.[[GetOwnProperty]](
key
).
If
desc
is not
undefined
and
desc
.[[Enumerable]] is
true
Let
typedKey
be
key
converted to an IDL value
of type
Let
value
be
Get
key
).
Let
typedValue
be
value
converted to an IDL value
of type
Set
result
typedKey
] to
typedValue
Note:
It’s possible that
typedKey
is already in
result
if
is
USVString
and
key
contains unpaired surrogates.
Return
result
An IDL
record
<…>
value
is
converted
to a JavaScript value as follows:
Let
result
be
OrdinaryObjectCreate
%Object.prototype%
).
For each
key
value
of
Let
jsKey
be
key
converted to a JavaScript value
Let
jsValue
be
value
converted to a JavaScript value
Let
created
be
CreateDataProperty
result
jsKey
jsValue
).
Assert:
created
is
true
Return
result
Passing the JavaScript value
{b: 3, a: 4}
as a
record

argument
would result in the IDL value «[ "
" → 3, "
" → 4 ]».
Records only consider
own
enumerable
properties, so given an IDL operation
record
identity(record arg)
which returns its
argument, the following code passes its assertions:
let
proto
};
let
obj
__proto__
proto
Object
defineProperty
obj
"e"
value
enumerable
false
});
let
result
identity
obj
);
console
assert
result
===
undefined
);
console
assert
result
===
undefined
);
console
assert
result
===
undefined
);
let
entries
Object
entries
result
);
console
assert
entries
][
===
"d"
);
console
assert
entries
][
===
);
console
assert
entries
][
===
"c"
);
console
assert
entries
][
===
);
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:
Value
Passed to type
Result
{"😞": 1}
record

TypeError
{"\uD83D": 1}
record

«[ "
\uFFFD
" → 1 ]»
{"\uD83D": {hello: "world"}}
record

«[ "
\uD83D
" → 0 ]»
3.2.24.
Promise types — Promise<
IDL
promise type
values are represented by JavaScript
PromiseCapability
records.
A JavaScript value
is
converted
to an IDL
Promise
value as follows:
Let
promiseCapability
be
NewPromiseCapability
%Promise%
).
Perform
Call
promiseCapability
.[[Resolve]],
undefined
»).
Return
promiseCapability
The result of
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.
When converting a JS value to a
Promise
IDL value,
first the value is wrapped in an (IDL) Promise,
then later machinery ensures the promise correctly resolves
to a value of type
This means that, for example,
a method defined to take a
Promise
argument
will automatically accept both
Promise
objects
(which must eventually resolve to a
object)
and
objects themselves.
(It will also, initially, accept
any other
type of object,
but will eventually auto-reject the promise
for resolving to the wrong type.)
3.2.24.1.
Creating and manipulating Promises
To
create
a new
Promise
in a
realm
realm
perform the following steps:
Let
constructor
be
realm
.[[Intrinsics]].[[
%Promise%
]].
Return
NewPromiseCapability
constructor
).
To create a
resolved promise
of type
Promise
, with
(a value of type
) in a
realm
realm
, perform the following steps:
Let
value
be the result of
converting
to a
JavaScript value.
Let
constructor
be
realm
.[[Intrinsics]].[[
%Promise%
]].
Let
promiseCapability
be
NewPromiseCapability
constructor
).
Perform
Call
promiseCapability
.[[Resolve]],
undefined
value
»).
Return
promiseCapability
To create a
rejected promise
of type
Promise
, with reason
(a
JavaScript value) in a
realm
realm
, perform the following steps:
Let
constructor
be
realm
.[[Intrinsics]].[[
%Promise%
]].
Let
promiseCapability
be
NewPromiseCapability
constructor
).
Perform
Call
promiseCapability
.[[Reject]],
undefined
»).
Return
promiseCapability
To
resolve
Promise
with
(a
value of type
), perform the following steps:
If
is not given, then let it be the
undefined
value.
Let
value
be the result of
converting
to a
JavaScript value.
Perform
Call
.[[Resolve]],
undefined
, «
value
»).
If
is
undefined
, then the
argument is optional, allowing a simpler "
resolve
p" usage.
To
reject
Promise
with reason
(a JavaScript value), perform the following steps:
Perform
Call
.[[Reject]],
undefined
, «
»).
To
react
to a
Promise
promise
, given one or two sets of steps
to perform, covering when the promise is fulfilled, rejected, or both, perform the following
steps:
Let
onFulfilledSteps
be the following steps given argument
Let
value
be the result of
converting
to an IDL
value of type
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
is not
undefined
. Otherwise, let
result
be
value
Return
result
converted to a JavaScript value
Let
onFulfilled
be
CreateBuiltinFunction
onFulfilledSteps
, 1, "", « »):
Let
onRejectedSteps
be the following steps given argument
Let
reason
be the result of
converting
to an IDL value of type
any
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
Return
result
converted to a JavaScript value
Let
onRejected
be
CreateBuiltinFunction
onRejectedSteps
, 1, "", « »):
Let
constructor
be
promise
.[[Promise]].[[Realm]].[[Intrinsics]].[[
%Promise%
]].
Let
newCapability
be
NewPromiseCapability
constructor
).
Note:
Not all callers will use the returned
Promise
. Implementations might wish to
avoid creating
newCapability
in those cases.
Perform
PerformPromiseThen
promise
.[[Promise]],
onFulfilled
onRejected
newCapability
).
Return
newCapability
Note:
This algorithm will behave in a very similar way to the
promise.then()
method.
In particular, if the steps return a value of type
or
Promise
, this algorithm returns a
Promise
as well.
To perform some steps
upon fulfillment
of a
Promise
promise
given some steps
steps
taking a
value of type
, perform the following steps:
Return the result of
reacting
to
promise
If
promise
was fulfilled with value
, then:
Perform
steps
with
To perform some steps
upon rejection
of a
Promise
promise
given some steps
steps
taking a JavaScript value, perform the following steps:
Return the result of
reacting
to
promise
If
promise
was rejected with reason
, then:
Perform
steps
with
To
wait for all
with a
list
of
Promise
values
promises
, with success steps
successSteps
that take a
list
of
values and failure steps
failureSteps
that take a
rejection reason
any
value, perform the following steps:
Let
fullfilledCount
be 0.
Let
rejected
be false.
Let
rejectionHandlerSteps
be the following steps given
arg
If
rejected
is true, abort these steps.
Set
rejected
to true.
Perform
failureSteps
given
arg
Let
rejectionHandler
be
CreateBuiltinFunction
rejectionHandlerSteps
, 1, "", « »):
Let
total
be
promises
’s
size
If
total
is 0, then:
Queue a microtask
to perform
successSteps
given « ».
Return.
Let
index
be 0.
Let
result
be a
list
containing
total
null values.
For each
promise
of
promises
Let
promiseIndex
be
index
Let
fulfillmentHandler
be the following steps given
arg
Set
result
promiseIndex
] to
arg
Set
fullfilledCount
to
fullfilledCount
+ 1.
If
fullfilledCount
equals
total
, then perform
successSteps
given
result
Let
fulfillmentHandler
be
CreateBuiltinFunction
fulfillmentHandler
, 1, "", « »):
Perform
PerformPromiseThen
promise
fulfillmentHandler
rejectionHandler
).
Set
index
to
index
+ 1.
To
get a promise for waiting for all
with a
list
of
Promise
values
promises
and a
realm
realm
, perform the following steps:
Let
promise
be
a new promise
of type
Promise
sequence
>>
in
realm
Let
successSteps
be the following steps, given
results
Resolve
promise
with
results
Let
failureSteps
be the following steps, given
reason
Reject
promise
with
reason
Wait for all
with
promises
, given
successSteps
and
failureSteps
Return
promise
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()
functions for JavaScript code. If you do not need to produce
another promise, then
waiting for all
is likely better.
To
mark as handled
Promise
promise
, set
promise
.[[Promise]].[[PromiseIsHandled]] to true.
This definition is useful for promises for which you expect rejections to often
be ignored; it ensures such promises do not cause
unhandledrejection
events. The most
common use case is for promise properties, which the web developer might or might not consult.
An example is the
writableStreamWriter.closed
promise.
3.2.24.2.
Examples
delay
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.
interface
Promise
undefined
delay
unrestricted
double
ms
);
};
The
delay(
ms
method steps are:
Let
realm
be
this
’s
relevant realm
Let
taskSource
be some appropriate
task source
If
ms
is NaN, let
ms
be +0; otherwise let
ms
be the maximum of
ms
and +0.
Let
be
a new promise
in
realm
Run the following steps
in parallel
Wait
ms
milliseconds.
Queue a task
on
taskSource
to
resolve
Return
The
validatedDelay
operation
is much like
the
delay
function
, except it will validate its arguments.
This shows how to use rejected promises to signal immediate failure before even starting any
asynchronous operations.
interface
Promise
undefined
validatedDelay
unrestricted
double
ms
);
};
The
validatedDelay(
ms
method steps are:
Let
realm
be
this
’s
relevant realm
Let
taskSource
be some appropriate
task source
If
ms
is NaN, return
a promise rejected with
TypeError
in
realm
If
ms
< 0, return
a promise rejected with
RangeError
in
realm
Let
be
a new promise
in
realm
Run the following steps
in parallel
Wait
ms
milliseconds.
Queue a task
on
taskSource
to
resolve
Return
addDelay
is an
operation
that adds an extra number of milliseconds of delay
between
promise
settling and the returned promise settling.
interface
Promise
any
addDelay
Promise
any
promise
unrestricted
double
ms
);
};
The
addDelay(
ms
promise
method steps are:
Let
realm
be
this
’s
relevant realm
Let
taskSource
be some appropriate
task source
If
ms
is NaN, let
ms
be +0; otherwise let
ms
be the maximum of
ms
and +0.
Let
be
a new promise
in
realm
React
to
promise
If
promise
was fulfilled with value
, then:
Run the following steps
in parallel
Wait
ms
milliseconds.
Queue a task
on
taskSource
to
resolve
with
If
promise
was rejected with reason
, then:
Run the following steps
in parallel
Wait
ms
milliseconds.
Queue a task
on
taskSource
to
reject
with
Return
environment.ready
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.
interface
Environment
readonly
attribute
Promise
undefined
ready
};
Every
Environment
object must have a
ready promise
which is a
Promise
undefined
The
ready
attribute getter steps are:
Return
this
’s
ready promise
To create an
Environment
object in a
realm
realm
, perform the following
steps:
Let
taskSource
be some appropriate
task source
Let
environment
be
new
Environment
object in
realm
Set
environment
’s
ready promise
to
a new promise
in
realm
Run the following steps
in parallel
Do some asynchronous work.
If
environment
becomes ready successfully, then
queue a task
on
taskSource
to
resolve
environment
’s
ready promise
If
environment
fails to become ready, then
queue a task
on
taskSource
to
reject
environment
’s
ready promise
with a
NetworkError
DOMException
Return
environment
addBookmark
is an
operation
that requests that the user add the current web
page as a bookmark.
It’s drawn from
some
iterative design work
and illustrates a more real-world scenario of appealing to
environmental asynchrony, as well as immediate rejections.
interface
Promise
undefined
addBookmark
();
};
The
addBookmark()
method steps are:
Let
taskSource
be some appropriate
task source
If this method was not invoked as a result of explicit user action, return
a promise rejected with
a "
SecurityError
DOMException
If the document’s mode of operation is standalone, return
a promise rejected with
NotSupportedError
DOMException
Let
promise
be
a new promise
Let
info
be the result of getting a web application’s metadata.
Run the following steps
in parallel
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.
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
Otherwise,
queue a task
on
taskSource
to
resolve
promise
Return
promise
Several places in
[SERVICE-WORKERS]
use
get a promise to wait for all
batchRequest
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.
interface
Promise
sequence
Response
>>
batchRequest
sequence
USVString
urls
);
};
The
batchRequest(
urls
method steps are:
Let
responsePromises
be « ».
For each
url
of
urls
Let
be the result of calling
fetch()
with
url
Append
to
responsePromises
Let
be the result of
getting a promise to wait for all
with
responsePromises
Return
3.2.25.
Union types
IDL
union type
values are represented by JavaScript values
that correspond to the union’s
member types
To
convert a JavaScript value
to an IDL
union type
value is done as follows:
If the
union type
includes undefined
and
is
undefined
then return the unique
undefined
value.
If the
union type
includes a nullable type
and
is
null
or
undefined
then return the IDL value
null
Let
types
be the
flattened member types
of the
union type
If
is
null
or
undefined
, then:
If
types
includes a
dictionary type
, then return the
result of
converting
to that dictionary type.
If
is a platform object
, then:
If
types
includes an
interface type
that
implements
, then return the IDL value that is a reference to the object
If
types
includes
object
, then return the IDL value
that is a reference to the object
If
is an Object
has an [[ArrayBufferData]]
internal slot
, and
IsSharedArrayBuffer
) is false, then:
If
types
includes
ArrayBuffer
, then return the
result of
converting
to
ArrayBuffer
If
types
includes
object
, then return the IDL value
that is a reference to the object
If
is an Object
, has an [[ArrayBufferData]]
internal slot
, and
IsSharedArrayBuffer
) is true, then:
If
types
includes
SharedArrayBuffer
, then return the
result of
converting
to
SharedArrayBuffer
If
types
includes
object
, then return the IDL value
that is a reference to the object
If
is an Object
and
has a [[DataView]]
internal slot
, then:
If
types
includes
DataView
, then return the
result of
converting
to
DataView
If
types
includes
object
, then return the IDL value
that is a reference to the object
If
is an Object
and
has a [[TypedArrayName]]
internal slot
, then:
If
types
includes a
typed array type
whose name is the value of
’s [[TypedArrayName]]
internal slot
, then return the
result of
converting
to that type.
If
types
includes
object
, then return the IDL value
that is a reference to the object
If
IsCallable
) is true, then:
If
types
includes a
callback function
type, then return the result of
converting
to that callback function type.
If
types
includes
object
, then return the IDL value
that is a reference to the object
If
is an Object
, then:
If
types
includes an
async sequence type
, then
If
types
does not include a
string type
or
does not have a [[StringData]]
internal slot
, then
Let
asyncMethod
be
GetMethod
%Symbol.asyncIterator%
).
If
asyncMethod
is not
undefined
return an IDL
async sequence
value with
object
set to
method
set to
syncMethod
, and
type
set to "
async
".
Let
syncMethod
be
GetMethod
%Symbol.iterator%
).
If
syncMethod
is not
undefined
return an IDL
async sequence
value with
object
set to
method
set to
syncMethod
, and
type
set to "
sync
".
If
types
includes a
sequence type
, then
Let
method
be
GetMethod
%Symbol.iterator%
).
If
method
is not
undefined
return the result of
creating a sequence
of that type from
and
method
If
types
includes a
frozen array type
, then
Let
method
be
GetMethod
%Symbol.iterator%
).
If
method
is not
undefined
return the result of
creating a frozen array
of that type from
and
method
If
types
includes a
dictionary type
, then return the
result of
converting
to that dictionary type.
If
types
includes a
record type
, then return the
result of
converting
to that record type.
If
types
includes a
callback interface
type, then return the result of
converting
to that
callback interface type
If
types
includes
object
, then return the IDL value
that is a reference to the object
If
is a Boolean
, then:
If
types
includes
boolean
then return the result of
converting
to
boolean
If
is a Number
, then:
If
types
includes a
numeric type
then return the result of
converting
to that
numeric type
If
is a BigInt
, then:
If
types
includes
bigint
then return the result of
converting
to
bigint
If
types
includes a
string type
then return the result of
converting
to that type.
If
types
includes a
numeric type
and
bigint
then return the result of
converting
to either that
numeric type
or
bigint
If
types
includes a
numeric type
then return the result of
converting
to that
numeric type
If
types
includes
boolean
then return the result of
converting
to
boolean
If
types
includes
bigint
then return the result of
converting
to
bigint
Throw
TypeError
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 (
§ 3.2 JavaScript type mapping
).
3.2.26.
Buffer source types
A value of an IDL
ArrayBuffer
is represented by an object of the corresponding JavaScript class.
If it is not
associated with
the [
AllowResizable
extended attribute
, it can only be backed by JavaScript
ArrayBuffer
objects
for which
IsFixedLengthArrayBuffer
) is true.
A value of an IDL
SharedArrayBuffer
is represented by an object of the corresponding JavaScript
class. If it is not
associated with
the [
AllowResizable
extended attribute
, it can only be backed by JavaScript
SharedArrayBuffer
objects
for which
IsFixedLengthArrayBuffer
) is true.
Values of the IDL
buffer view types
are represented by objects of the corresponding JavaScript
class, with the following additional restrictions on those objects.
If the type is not
associated with
either the
AllowResizable
] or [
AllowShared
extended attribute
, if applicable, they can
only be backed by JavaScript
ArrayBuffer
objects
for which
IsFixedLengthArrayBuffer
) is true.
If the type is
associated with
the
AllowResizable
extended attribute
but not with the [
AllowShared
extended attribute
, if applicable, they can only be backed by JavaScript
ArrayBuffer
objects.
If the type is
associated with
the [
AllowShared
extended attribute
but not with the [
AllowResizable
extended attribute
, they
can only be backed by JavaScript
ArrayBuffer
and
SharedArrayBuffer
objects
for which
IsFixedLengthArrayBuffer
) is true.
If the type is
associated with
both the
AllowResizable
] and the [
AllowShared
extended attributes
they can be backed by any JavaScript
ArrayBuffer
or
SharedArrayBuffer
object.
A JavaScript value
is
converted
to an IDL
ArrayBuffer
value by running the following algorithm:
If
is not an Object
or
does not have an [[ArrayBufferData]]
internal slot
then
throw
TypeError
If
IsSharedArrayBuffer
) is true, then
throw
TypeError
If the conversion is not to an IDL type
associated with
the [
AllowResizable
extended attribute
, and
IsFixedLengthArrayBuffer
) is false,
then
throw
TypeError
Return the IDL
ArrayBuffer
value that is a reference
to the same object as
A JavaScript value
is
converted
to an IDL
SharedArrayBuffer
value by running the following algorithm:
If
is not an Object
or
does not have an [[ArrayBufferData]]
internal slot
then
throw
TypeError
If
IsSharedArrayBuffer
) is false, then
throw
TypeError
If the conversion is not to an IDL type
associated with
the [
AllowResizable
extended attribute
, and
IsFixedLengthArrayBuffer
) is false,
then
throw
TypeError
Return the IDL
SharedArrayBuffer
value that is a reference
to the same object as
A JavaScript value
is
converted
to an IDL
DataView
value by running the following algorithm:
If
is not an Object
or
does not have a [[DataView]]
internal slot
then
throw
TypeError
If the conversion is not to an IDL type
associated with
the [
AllowShared
extended attribute
, and
IsSharedArrayBuffer
.[[ViewedArrayBuffer]]) is true,
then
throw
TypeError
If the conversion is not to an IDL type
associated with
the [
AllowResizable
extended attribute
, and
IsFixedLengthArrayBuffer
.[[ViewedArrayBuffer]]) is false,
then
throw
TypeError
Return the IDL
DataView
value that is a reference
to the same object as
A JavaScript value
is
converted
to an IDL
Int8Array
Int16Array
Int32Array
Uint8Array
Uint16Array
Uint32Array
Uint8ClampedArray
BigInt64Array
BigUint64Array
Float16Array
Float32Array
, or
Float64Array
value
by running the following algorithm:
Let
be the IDL type
is being converted to.
If
is not an Object
or
does not have a [[TypedArrayName]]
internal slot
with a value equal to
’s name,
then
throw
TypeError
If the conversion is not to an IDL type
associated with
the [
AllowShared
extended attribute
, and
IsSharedArrayBuffer
.[[ViewedArrayBuffer]]) is true,
then
throw
TypeError
If the conversion is not to an IDL type
associated with
the [
AllowResizable
extended attribute
, and
IsFixedLengthArrayBuffer
.[[ViewedArrayBuffer]]) is false,
then
throw
TypeError
Return the IDL value of type
that is a reference to the same object as
The result of
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.
To
create
an
ArrayBuffer
from a
byte sequence
bytes
in a
realm
realm
Let
jsArrayBuffer
be
AllocateArrayBuffer
realm
.[[Intrinsics]].[[
%ArrayBuffer%
]],
bytes
’s
length
).
Let
arrayBuffer
be the result of
converting
jsArrayBuffer
to an IDL value of type
ArrayBuffer
Write
bytes
into
arrayBuffer
Return
arrayBuffer
To
create
SharedArrayBuffer
from a
byte sequence
bytes
in a
realm
realm
Let
jsSharedArrayBuffer
be
AllocateSharedArrayBuffer
realm
.[[Intrinsics]].[[
%SharedArrayBuffer%
]],
bytes
’s
length
).
Let
sharedArrayBuffer
be the result of
converting
jsSharedArrayBuffer
to an IDL value of type
SharedArrayBuffer
Write
bytes
into
sharedArrayBuffer
Return
sharedArrayBuffer
To
create
one of the
ArrayBufferView
types from a
byte sequence
bytes
in a
realm
realm
Assert: if the type is not
DataView
, then
bytes
’s
length
modulo
the
element size
of that type is 0.
Let
arrayBuffer
be the result of
creating
an
ArrayBuffer
from
bytes
in
realm
Let
jsArrayBuffer
be the result of
converting
arrayBuffer
to a JavaScript value.
Let
constructor
be the appropriate constructor from
realm
.[[Intrinsics]] for the type
of
ArrayBufferView
being created.
Let
jsView
be
Construct
constructor
, «
jsArrayBuffer
»).
Return the result of
converting
jsView
into the given type.
To
get a copy of the bytes held by the buffer source
given a
buffer source type
instance
bufferSource
Let
jsBufferSource
be the result of
converting
bufferSource
to a JavaScript value.
Let
jsArrayBuffer
be
jsBufferSource
Let
offset
be 0.
Let
length
be 0.
If
jsBufferSource
has a [[ViewedArrayBuffer]]
internal slot
, then:
Set
jsArrayBuffer
to
jsBufferSource
.[[ViewedArrayBuffer]].
Set
offset
to
jsBufferSource
.[[ByteOffset]].
Set
length
to
jsBufferSource
.[[ByteLength]].
Otherwise:
Assert:
jsBufferSource
is an
ArrayBuffer
or
SharedArrayBuffer
object.
Set
length
to
jsBufferSource
.[[ArrayBufferByteLength]].
If
IsDetachedBuffer
jsArrayBuffer
) is true, then return the empty
byte sequence
Let
bytes
be a new
byte sequence
of
length
equal to
length
For
in
the range
offset
to
offset
length
− 1, inclusive, set
bytes
offset
] to
GetValueFromBuffer
jsArrayBuffer
, Uint8,
true, Unordered).
Return
bytes
The
byte length
of a
buffer source type
instance
bufferSource
is the value returned by the following steps:
Let
jsBufferSource
be the result of
converting
bufferSource
to a JavaScript value.
If
jsBufferSource
has a [[ViewedArrayBuffer]] internal slot, then return
jsBufferSource
.[[ByteLength]].
Return
jsBufferSource
.[[ArrayBufferByteLength]].
The
underlying buffer
of a
buffer source type
instance
bufferSource
is the value returned by the following steps:
If
bufferSource
is a
buffer type
instance, then return
bufferSource
Let
jsBufferView
be the result of
converting
bufferSource
to a JavaScript value.
Let
jsBuffer
be
jsBufferView
.[[ViewedArrayBuffer]].
If
IsSharedArrayBuffer
jsBuffer
) is false, then return the result of
converting
jsBuffer
to an IDL value of type
ArrayBuffer
Return the result of
converting
jsBuffer
to an IDL value of
type
SharedArrayBuffer
To
write
byte sequence
bytes
into a
buffer type
instance
arrayBuffer
, optionally given a
startingOffset
(default 0):
Let
jsArrayBuffer
be the result of
converting
arrayBuffer
to a JavaScript value.
Assert:
bytes
’s
length
jsArrayBuffer
.[[ArrayBufferByteLength]]
startingOffset
For
in
the range
startingOffset
to
startingOffset
bytes
’s
length
− 1, inclusive, perform
SetValueInBuffer
jsArrayBuffer
, Uint8,
bytes
startingOffset
], true, Unordered).
To
write
byte sequence
bytes
into an
ArrayBufferView
view
, optionally given a
startingOffset
(default 0):
Let
jsView
be the result of
converting
view
to
a JavaScript value.
Assert:
bytes
’s
length
jsView
.[[ByteLength]] −
startingOffset
Assert: if
view
is not a
DataView
, then
bytes
’s
length
modulo
the
element size
of
view
’s type is 0.
Let
arrayBuffer
be the result of
converting
jsView
.[[ViewedArrayBuffer]] to an IDL value of type
ArrayBuffer
Write
bytes
into
arrayBuffer
with
startingOffset
set to
jsView
.[[ByteOffset]] +
startingOffset
Extreme care must be taken when writing specification text that
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
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
create
a new
ArrayBuffer
or
ArrayBufferView
to give back to author code.
To
detach
an
ArrayBuffer
arrayBuffer
Let
jsArrayBuffer
be the result of
converting
arrayBuffer
to a JavaScript value.
Perform
DetachArrayBuffer
jsArrayBuffer
).
This will throw an exception if
jsArrayBuffer
has an [[ArrayBufferDetachKey]] that is not undefined, such as is the case
with the value of
WebAssembly.Memory
’s
buffer
attribute.
[WASM-JS-API-1]
Detaching a buffer that is already
detached
is a no-op.
buffer source type
instance
bufferSource
is
detached
if the following steps return true:
Let
jsArrayBuffer
be the result of
converting
bufferSource
to a JavaScript value.
If
jsArrayBuffer
has a [[ViewedArrayBuffer]] internal slot, then set
jsArrayBuffer
to
jsArrayBuffer
.[[ViewedArrayBuffer]].
Return
IsDetachedBuffer
jsArrayBuffer
).
buffer source type
instance
bufferSource
is
transferable
if the following steps return true:
Let
jsArrayBuffer
be the result of
converting
bufferSource
to a JavaScript value.
If
jsArrayBuffer
has a [[ViewedArrayBuffer]] internal slot, then set
jsArrayBuffer
to
jsArrayBuffer
.[[ViewedArrayBuffer]].
If
IsSharedArrayBuffer
jsArrayBuffer
) is true, then return false.
If
IsDetachedBuffer
jsArrayBuffer
) is true, then return false.
If
jsArrayBuffer
.[[ArrayBufferDetachKey]] is not
undefined
, then
return false.
Return true.
To
transfer
an
ArrayBuffer
arrayBuffer
, optionally
given a
realm
targetRealm
Let
jsArrayBuffer
be the result of
converting
arrayBuffer
to a JavaScript value.
If
IsDetachedBuffer
jsArrayBuffer
) is false, then
throw
TypeError
Let
arrayBufferData
be
jsArrayBuffer
.[[ArrayBufferData]].
Let
arrayBufferByteLength
be
jsArrayBuffer
.[[ArrayBufferByteLength]].
Perform
DetachArrayBuffer
jsArrayBuffer
).
If
targetRealm
is not given, let
targetRealm
be the
current realm
Let
jsTransferred
be
AllocateArrayBuffer
targetRealm
.[[Intrinsics]].[[
%ArrayBuffer%
]], 0).
Set
jsTransferred
.[[ArrayBufferData]] to
arrayBufferData
Set
jsTransferred
.[[ArrayBufferByteLength]] to
arrayBufferByteLength
Return the result of
converting
jsTransferred
to an IDL
value of type
ArrayBuffer
This will throw an exception under any of the following circumstances:
arrayBuffer
cannot be
detached
, for the reasons
explained in that algorithm’s
definition
arrayBuffer
is already
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.
3.2.27.
Frozen arrays — FrozenArray<
Values of frozen array types are represented by frozen JavaScript
Array object references.
A JavaScript value
is
converted
to an IDL
FrozenArray<
value
by running the following algorithm:
Let
values
be the result of
converting
to IDL type
sequence<
Return the result of
creating a frozen array
from
values
To
create a frozen array
from a sequence of values of type
, follow these steps:
Let
array
be the result of
converting
the sequence of values of type
to a JavaScript value.
Perform
SetIntegrityLevel
array
, "
frozen
").
Return
array
The result of
converting
an IDL
FrozenArray<
value to a JavaScript
value is the Object value that represents a reference
to the same object that the IDL
FrozenArray<
represents.
3.2.27.1.
Creating a frozen array from an iterable
To create an IDL value of type
FrozenArray<
given an
iterable
iterable
and an iterator getter
method
, perform the following steps:
Let
values
be the result of
creating a sequence
of type
sequence<
from
iterable
and
method
Return the result of
creating a frozen array
from
values
3.2.28.
Observable arrays — ObservableArray<
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
backing observable array exotic object
for each
regular attribute
of an
observable array type
. These are created and managed as part of the
define the attributes
algorithm.
The
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:
Assert:
obj
implements
an
interface
with the
regular attribute
attribute
Let
oa
be
obj
’s
backing observable array exotic object
for
attribute
Return
oa
.[[ProxyHandler]].[[BackingList]].
3.3.
Extended attributes
This section defines a number of
extended attributes
whose presence affects the JavaScript binding.
3.3.1.
[AllowResizable]
If the [
AllowResizable
extended attribute
appears on a
buffer type
, it creates a new
IDL type that allows for the respective corresponding JavaScript
ArrayBuffer
or
SharedArrayBuffer
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
ArrayBuffer
that is
resizable, instead of only by a fixed-length
ArrayBuffer
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
SharedArrayBuffer
that is growable.
The [
AllowResizable
] extended attribute must
take no arguments
A type that is not a
buffer source type
must not be
associated with
the [
AllowResizable
] extended attribute.
See the rules for converting JavaScript values to IDL
buffer source types
in
§ 3.2.26 Buffer source types
for the specific requirements that the use of [
AllowResizable
] entails.
See the
example
in
§ 3.3.2 [AllowShared]
for example usage of both [
AllowResizable
] and [
AllowShared
].
3.3.2.
[AllowShared]
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
take no arguments
A type that is not a
buffer view type
must not be
associated with
the [
AllowShared
] extended attribute.
See the rules for converting JavaScript values to IDL
buffer view types
in
§ 3.2.26 Buffer source types
for the specific requirements that the use of [
AllowShared
] entails.
The following
IDL fragment
demonstrates the possible combinations of the
AllowResizable
] and [
AllowShared
extended attribute
Exposed
Window
interface
ExampleBufferFeature
undefined
writeInto
ArrayBufferView
dest
);
undefined
writeIntoResizable
([
AllowResizable
ArrayBufferView
dest
);
undefined
writeIntoShared
([
AllowShared
ArrayBufferView
dest
);
undefined
writeIntoSharedResizable
([
AllowResizable
AllowShared
ArrayBufferView
dest
);
};
With this definition,
A call to
writeInto
with any
buffer view type
backed by
either a resizable
ArrayBuffer
instance or a
SharedArrayBuffer
instance,
will throw a
TypeError
exception.
A call to
writeIntoResizable
with any
buffer view type
backed by
SharedArrayBuffer
instance, will throw a
TypeError
exception.
A call to
writeIntoShared
with any
buffer view type
backed by a
resizable
ArrayBuffer
instance or a growable
SharedArrayBuffer
instance,
will throw a
TypeError
exception.
A call to
writeIntoSharedResizable
will accept any
buffer view type
backed by a
ArrayBuffer
instance or a
SharedArrayBuffer
instance.
3.3.3.
[Clamp]
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 (
ToInt32
ToUint32
, etc.).
The [
Clamp
extended attribute must
take no arguments
A type annotated with the [
Clamp
] extended attribute must not appear in a
read only
attribute. A type must not be
associated with
both the
Clamp
] and [
EnforceRange
] extended attributes. A type that is not an
integer type
must
not be
associated with
the [
Clamp
] extended attribute.
See the rules for converting JavaScript values to the various IDL integer
types in
§ 3.2.4 Integer types
for the specific requirements that the use of
Clamp
] entails.
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:
Exposed
Window
interface
GraphicsContext
undefined
setColor
octet
red
octet
green
octet
blue
);
undefined
setColorClamped
([
Clamp
octet
red
, [
Clamp
octet
green
, [
Clamp
octet
blue
);
};
A call to
setColorClamped
with
Number values that are out of range for an
octet
are clamped to the range [0, 255].
// 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
255
257
);
// Call setColorClamped with some out of range values.
// This is equivalent to calling setColorClamped(0, 255, 255).
context
setColorClamped
255
257
);
3.3.4.
[CrossOriginIsolated]
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
cross-origin isolated capability
is true. The
CrossOriginIsolated
] extended attribute must not be used on any other construct.
The [
CrossOriginIsolated
] extended attribute must
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
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
inherit
from another interface
that does specify [
CrossOriginIsolated
].
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.
Exposed
Window
interface
ExampleFeature
// This call will succeed in all contexts.
Promise
Result
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
Result
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
boolean
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
boolean
log
();
};
ExampleFeature
includes
Loggable
3.3.5.
[Default]
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
take no arguments
The [
Default
] extended attribute must not be used on anything other than a
regular operation
that
has default method steps
defined.
As an example, the [
Default
] extended attribute is suitable
for use on
toJSON
regular operations
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
};
In the JavaScript language binding, there would exist a
toJSON()
method on
Animal
Human
and (via inheritance)
Dog
objects:
// 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
);
3.3.6.
[EnforceRange]
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 (
ToInt32
ToUint32
, etc.).
The Number will be rounded toward zero before being checked against its range.
The [
EnforceRange
extended attribute must
take no arguments
A type annotated with the [
EnforceRange
] extended attribute must not appear in a
read only
attribute. A type must not be
associated with
both the [
Clamp
] and [
EnforceRange
] extended attributes. A type that is not an
integer type
must not be
associated with
the
EnforceRange
] extended attribute.
See the rules for converting JavaScript values to the various IDL integer
types in
§ 3.2 JavaScript type mapping
for the specific requirements that the use of
EnforceRange
] entails.
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:
Exposed
Window
interface
GraphicsContext
undefined
setColor
octet
red
octet
green
octet
blue
);
undefined
setColorEnforcedRange
([
EnforceRange
octet
red
, [
EnforceRange
octet
green
, [
EnforceRange
octet
blue
);
};
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.
// 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
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
255
256
);
3.3.7.
[Exposed]
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
take an identifier
take an identifier list
or
take a wildcard
Each of the identifiers mentioned must be a
global name
of some
interface
and be unique.
The
own exposure set
is either a
set
of identifiers or the special value
, defined as follows:
If the [
Exposed
extended attribute
takes an identifier
The
own exposure set
is the
set
».
If the [
Exposed
extended attribute
takes an identifier list
The
own exposure set
is the
set
If the [
Exposed
extended attribute
takes a wildcard
The
own exposure set
is
[Exposed=*]
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.
The
exposure set intersection
of a construct
and interface-or-null
is defined as
follows:
Assert:
is an
interface member
interface mixin member
namespace member
partial interface
partial interface mixin
partial namespace
, or
interface mixin
Assert:
is an
interface
or null.
If
is null, return
’s
own exposure set
If
’s
own exposure set
is
, return
’s
exposure set
If
’s
exposure set
is
, return
’s
own exposure set
Return the
intersection
of
’s
own exposure set
and
’s
exposure set
To get the
exposure set
of a construct
run the following steps:
Assert:
is an
interface
callback interface
namespace
interface member
interface mixin member
, or
namespace member
Let
be
’s
host interface
if
is an
interface mixin member
, or null otherwise.
If
is an
interface member
interface mixin member
, or
namespace member
, then:
If the [
Exposed
extended attribute
is specified on
return the
exposure set intersection
of
and
Set
to the
interface
partial interface
interface mixin
partial interface mixin
namespace
, or
partial namespace
is declared on.
If
is a
partial interface
partial interface mixin
, or
partial namespace
, then:
If the [
Exposed
extended attribute
is specified on
return the
exposure set intersection
of
and
Set
to the original
interface
interface mixin
, or
namespace
definition
of
If
is an
interface mixin
, then:
Assert:
is not null.
If the [
Exposed
extended attribute
is specified on
return the
exposure set intersection
of
and
Set
to
Assert:
is an
interface
callback interface
or
namespace
Assert: The [
Exposed
extended attribute
is specified on
Return
’s
own exposure set
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
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
inherits
from another interface
then the
exposure set
of
must be a subset of the
exposure set
of
Note:
As an
interface mixin
can be
included
by different
interfaces
the
exposure set
of its
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
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
An
interface
callback interface
namespace
, or
member
construct
is
exposed
in a given
realm
realm
if the following steps
return true:
If
construct
’s
exposure set
is not
, and
realm
.[[GlobalObject]] does
not implement an
interface
that is in
construct
’s
exposure set
, then return false.
If
realm
’s
settings object
is not a
secure context
, and
construct
is
conditionally exposed
on [
SecureContext
], then return false.
If
realm
’s
settings object
’s
cross-origin isolated capability
is false, and
construct
is
conditionally exposed
on [
CrossOriginIsolated
], then return false.
Return true.
An
interface
callback interface
namespace
, or
member
construct
is
conditionally exposed
on a given
extended attribute
exposure condition
if the following steps return true:
Assert:
construct
is an
interface
callback interface
namespace
interface member
interface mixin member
, or
namespace member
Let
be
construct
’s
host interface
if
construct
is an
interface mixin member
or null otherwise.
If
construct
is an
interface member
interface mixin member
, or
namespace member
, then:
If the
exposure condition
extended attribute
is specified on
construct
then return true.
Otherwise, set
construct
to be the
interface
partial interface
interface mixin
partial interface mixin
namespace
, or
partial namespace
construct
is declared on.
If
construct
is a
partial interface
partial interface mixin
, or
partial namespace
, then:
If the
exposure condition
extended attribute
is specified on
construct
then return true.
Otherwise, set
construct
to be the original
interface
interface mixin
, or
namespace
definition of
construct
If
construct
is an
interface mixin
, then:
If the
exposure condition
extended attribute
is specified on
construct
then return true.
Otherwise, set
construct
to
Assert:
construct
is an
interface
callback interface
or
namespace
If the
exposure condition
extended attribute
is specified on
construct
then return true.
Otherwise, return false.
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
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
§ 3.7 Interfaces
§ 3.7.5 Constants
§ 3.7.6 Attributes
§ 3.7.7 Operations
, and
for the specific requirements that the use of
Exposed
] entails.
Exposed
] is intended to be used to control whether
interfaces
callback interfaces
namespaces
, or individual
interface
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:
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
double
);
};

// 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
);
};

// 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
);
};
3.3.8.
[Global]
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
global names
for the
interface
If the [
Global
extended attribute
takes an identifier
« the given
identifier
If the [
Global
extended attribute
takes an identifier list
the identifier list
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, "
Worker
" 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:
Any
named properties
will be exposed on an object in the prototype chain – the
named properties object
rather than on the object itself.
Interface members
from the
interface
will correspond to properties on the object itself rather than on
interface prototype objects
All
realms
have an
is global prototype chain mutable
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.
This allows the
ShadowRealm
global to have a mutable prototype.
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:
var
indexedDB
window
indexedDB
||
window
webkitIndexedDB
||
window
mozIndexedDB
||
window
msIndexedDB
var
requestAnimationFrame
window
requestAnimationFrame
||
window
mozRequestAnimationFrame
||
...;
Because of the way variable declarations are handled in
JavaScript, the code above would result in the
window.indexedDB
and
window.requestAnimationFrame
evaluating
to
undefined
, as the shadowing variable
property would already have been created before the
assignment is evaluated.
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
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
inherit
from another interface with the
LegacyOverrideBuiltIns
] extended attribute.
Any other interface must not
inherit
from it.
If [
Global
] is specified on
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
§ 3.7.4 Named properties object
for the specific requirements
that the use of [
Global
] entails for
named properties
and
§ 3.7.5 Constants
§ 3.7.6 Attributes
and
§ 3.7.7 Operations
for the requirements relating to the location of properties
corresponding to
interface members
The
Window
interface exposes frames as properties on the
Window
object. Since the
Window
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.
Exposed
Window
Global
Window
interface
Window
getter
any
DOMString
name
);
attribute
DOMString
name
// ...
};
The following HTML document illustrates how the named properties on the
Window
object can be shadowed, and how
the property for an attribute will not be replaced when declaring
a variable of the same name:

title
Variable declarations and assignments on Window
title
iframe
name
abc
>iframe

script
window
abc
// Evaluates to the iframe's Window object.
abc
// Shadows the named property.
window
abc
// Evaluates to 1.
script

script
Window
prototype
def
// Places a property on the prototype.
window
hasOwnProperty
"length"
);
// Evaluates to true.
length
// Evaluates to 1.
def
// Evaluates to 2.
script
script
var
length
// Variable declaration leaves existing property.
length
// Evaluates to 1.
var
def
// Variable declaration creates shadowing property.
def
// Evaluates to undefined.
script
3.3.9.
[NewObject]
If the [
NewObject
extended attribute
appears on a
regular
or
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
take no arguments
The [
NewObject
extended attribute must not
be used on anything other than a
regular
or
static
operation
whose
return type
is an
interface type
or
promise type
As an example, this extended attribute is suitable for use on
the
createElement()
operation on the
Document
interface,
since a new object is always returned when
it is called.
[DOM]
Exposed
Window
interface
Document
Node
NewObject
Element
createElement
DOMString
localName
);
// ...
};
3.3.10.
[PutForwards]
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
take an identifier
Assuming that:
is the
attribute
on which the [
PutForwards
extended attribute appears,
is the
interface
on which
is declared,
is the
interface type
that
is declared to be of, and
is the
identifier
argument of the extended attribute,
then there must be another
attribute
declared on
whose
identifier
is
. Assignment of a value to the attribute
on an object implementing
will result in that value
being assigned to attribute
of the object that
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
namespace
See the
Attributes
section for how
PutForwards
is to be implemented.
The following
IDL fragment
defines interfaces for names and people.
The [
PutForwards
] extended
attribute is used on the
name
attribute
of the
Person
interface to indicate
that assignments to that attribute result in assignments to the
full
attribute of the
Person
object:
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
};
In the JavaScript binding, this would allow assignments to the
name
property:
var
getPerson
();
// Obtain an instance of Person.
name
'John Citizen'
// This statement...
name
full
'John Citizen'
// ...has the same behavior as this one.
3.3.11.
[Replaceable]
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
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
namespace
See
§ 3.7.6 Attributes
for the specific requirements that the use of
Replaceable
] entails.
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:
Exposed
Window
interface
Counter
Replaceable
readonly
attribute
unsigned
long
value
undefined
increment
();
};
Assigning to the
value
property
on a
platform object
implementing
Counter
will shadow the property that corresponds to the
attribute
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.
3.3.12.
[SameObject]
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
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
As an example, this extended attribute is suitable for use on
the
implementation
attribute on the
Document
interface
since the same object is always returned for a given
Document
object.
[DOM]
Exposed
Window
interface
Document
Node
SameObject
readonly
attribute
DOMImplementation
implementation
// ...
};
3.3.13.
[SecureContext]
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
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
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
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
cross-origin isolated
is also a
secure context
.)
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.
Exposed
Window
interface
ExampleFeature
// This call will succeed in all contexts.
Promise
Result
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
Result
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
float
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
boolean
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
boolean
log
();
};
ExampleFeature
includes
Loggable
3.3.14.
[Unscopable]
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
with
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
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
§ 3.7.3 Interface prototype object
for the specific requirements that the use of
Unscopable
] entails.
For example, with the following IDL:
Exposed
Window
interface
Thing
undefined
();
Unscopable
();
};
the
property can be referenced with a bare identifier
in a
with
statement but the
property cannot:
var
thing
getThing
();
// An instance of Thing
with
thing
// Evaluates to a Function object.
// Throws a ReferenceError.
3.4.
Legacy extended attributes
This section defines a number of
extended attributes
whose presence affects the JavaScript
binding. Unlike those in
§ 3.3 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
filing an issue
before proceeding.
3.4.1.
[LegacyFactoryFunction]
Instead of using this feature, give your interface a
constructor operation
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
take a named argument list
The
identifier
that occurs directly after the
” is the [
LegacyFactoryFunction
]'s
identifier
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
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
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
§ 3.7.2 Legacy factory functions
for details on how legacy factory functions
are to be implemented.
The following IDL defines an interface that uses the
LegacyFactoryFunction
] extended
attribute.
Exposed
Window
LegacyFactoryFunction
Audio
DOMString
src
)]
interface
HTMLAudioElement
HTMLMediaElement
// ...
};
A JavaScript implementation that supports this interface will
allow the construction of
HTMLAudioElement
objects using the
Audio
function.
typeof
Audio
// Evaluates to 'function'.
var
a2
new
Audio
'a.flac'
);
// Creates an HTMLAudioElement using the
// one-argument constructor.
As an additional legacy quirk, these factory functions will have a
prototype
property equal to the
prototype
of the original interface:
console
assert
Audio
prototype
===
HTMLAudioElement
prototype
);
3.4.2.
[LegacyLenientSetter]
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.
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.
The [
LegacyLenientSetter
] extended attribute
must
take no arguments
It must not be used on anything other than
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
Attributes
section for how
LegacyLenientSetter
] is to be implemented.
The following IDL fragment defines an interface that uses the
LegacyLenientSetter
] extended
attribute.
Exposed
Window
interface
Example
LegacyLenientSetter
readonly
attribute
DOMString
readonly
attribute
DOMString
};
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.
"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
// Throws a TypeError, since we are in strict mode and there is no setter.
example
3.4.3.
[LegacyLenientThis]
If the [
LegacyLenientThis
extended attribute
appears on a
regular attribute
it indicates that invocations of the attribute’s getter or setter
with a
this
value that is not an
object that
implements
the
interface
on which the attribute appears will be ignored.
The [
LegacyLenientThis
] extended attribute
must
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
Attributes
section for how
LegacyLenientThis
is to be implemented.
The following IDL fragment defines an interface that uses the
LegacyLenientThis
] extended
attribute.
Exposed
Window
interface
Example
LegacyLenientThis
attribute
DOMString
attribute
DOMString
};
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
Example
object.
var
example
getExample
();
// Get an instance of Example.
var
obj
};
// Fine.
example
// 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
// Throws a TypeError, since Example.prototype is not an Example object.
Example
prototype
3.4.4.
[LegacyNamespace]
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.
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
§ 3.13.1 Namespace object
for details on how an interface is exposed on a namespace.
The following
IDL fragment
defines a
namespace
and an
interface
which
uses [
LegacyNamespace
] to be defined inside of it.
namespace
Foo
{ };

LegacyNamespace
Foo
interface
Bar
constructor
();
};
In a JavaScript implementation of the above namespace and interface, the
constructor Bar can be accessed as follows:
var
instance
new
Foo
Bar
();
3.4.5.
[LegacyNoInterfaceObject]
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
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
§ 3.7 Interfaces
for the specific requirements that the use of
LegacyNoInterfaceObject
] entails.
The following
IDL fragment
defines two interfaces, one whose interface object
is exposed on the JavaScript global object, and one whose isn’t:
Exposed
Window
interface
Storage
undefined
addEntry
unsigned
long
key
any
value
);
};

Exposed
Window
LegacyNoInterfaceObject
interface
Query
any
lookupEntry
unsigned
long
key
);
};
A JavaScript implementation of the above IDL would allow
manipulation of
Storage
’s
prototype, but not
Query
’s.
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
3.4.6.
[LegacyNullToEmptyString]
If the [
LegacyNullToEmptyString
extended attribute
appears on the
DOMString
or
USVString
type,
it creates a new IDL type such that that when a JavaScript
null
is converted to the IDL type,
it will be handled differently from its default handling. Instead of being stringified to
null
", which is the default, it will be converted to the empty string.
The [
LegacyNullToEmptyString
] extended attribute must not be
associated with
a type that is not
DOMString
or
USVString
Note:
This means that even
DOMString?
must not use [
LegacyNullToEmptyString
], since
null
is a valid value of that type.
See
§ 3.2.10 DOMString
for the specific requirements that the use of [
LegacyNullToEmptyString
] entails.
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:
Exposed
Window
interface
Dog
attribute
DOMString
name
attribute
LegacyNullToEmptyString
DOMString
owner
boolean
isMemberOfBreed
([
LegacyNullToEmptyString
DOMString
breedName
);
};
A JavaScript implementation implementing the
Dog
interface would convert a
null
value
assigned to the
owner
property or passed as the
argument to the
isMemberOfBreed
function
to the empty string rather than "
null
":
var
getDog
();
// Assume d is a platform object implementing the Dog
// interface.
name
null
// This assigns the string "null" to the .name
// property.
owner
null
// This assigns the string "" to the .owner property.
isMemberOfBreed
null
);
// This passes the string "" to the isMemberOfBreed
// function.
3.4.7.
[LegacyOverrideBuiltIns]
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
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
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
§ 3.9 Legacy platform objects
and
§ 3.9.3 [[DefineOwnProperty]]
for the specific requirements that the use of
LegacyOverrideBuiltIns
] entails.
The following
IDL fragment
defines two
interfaces
one that has a
named property getter
and one that does not.
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
);
};
In a JavaScript implementation of these two interfaces,
getting certain properties on objects implementing
the interfaces will result in different values:
// 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
3.4.8.
[LegacyTreatNonObjectAsNull]
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
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
callable
, it will be converted to a
callback function
value that does nothing when called.
See
§ 3.2.20 Nullable types — T?
§ 3.2.19 Callback function types
and
§ 3.12 Invoking callback functions
for the specific requirements that the use of
LegacyTreatNonObjectAsNull
] entails.
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
callback
OccurrenceHandler
undefined
DOMString
details
);

LegacyTreatNonObjectAsNull
callback
ErrorHandler
undefined
DOMString
details
);

Exposed
Window
interface
Manager
attribute
OccurrenceHandler
handler1
attribute
ErrorHandler
handler2
};
In a JavaScript implementation, assigning a value that is not
an object (such as a Number value), or that is not
callable
to handler1 will have different behavior from that when assigning
to handler2:
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
try
manager
handler1
{};
// Throws a TypeError.
catch
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.
3.4.9.
[LegacyUnenumerableNamedProperties]
If the [
LegacyUnenumerableNamedProperties
extended attribute
appears on a
interface
that
supports named properties
it indicates that all the interface’s named properties are unenumerable.
The [
LegacyUnenumerableNamedProperties
extended attribute must
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
§ 3.9.1 [[GetOwnProperty]]
for the specific requirements that the use of
LegacyUnenumerableNamedProperties
entails.
3.4.10.
[LegacyUnforgeable]
If the [
LegacyUnforgeable
extended attribute
appears on
regular attributes
or non-
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
unforgeable
on a given interface
if the attribute or operation is declared on
and is annotated with the [
LegacyUnforgeable
extended attribute
The [
LegacyUnforgeable
] extended attribute must
take no arguments
The [
LegacyUnforgeable
extended attribute
must not appear
on anything other than a
regular attribute
or a non-
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
is
unforgeable
on an interface
and
is one of the
inherited interfaces
of another interface
then
must not have a
regular attribute
or non-
static
operation
with the same
identifier
as
For example, the following is disallowed:
Exposed
Window
interface
A1
LegacyUnforgeable
readonly
attribute
DOMString
};
Exposed
Window
interface
B1
A1
undefined
(); // Invalid; would be shadowed by A1's x.
};

Exposed
Window
interface
B2
A1
{ };
B2
includes
M1
interface
mixin
M1
undefined
(); // Invalid; B2's copy of x would be shadowed by A1's x.
};
See
§ 3.7.6 Attributes
§ 3.7.7 Operations
§ 3.8 Platform objects implementing interfaces
§ 3.9 Legacy platform objects
and
§ 3.9.3 [[DefineOwnProperty]]
for the specific requirements that the use of
LegacyUnforgeable
] entails.
The following
IDL fragment
defines
an interface that has two
attributes
one of which is designated as [
LegacyUnforgeable
]:
Exposed
Window
interface
System
LegacyUnforgeable
readonly
attribute
DOMString
username
readonly
attribute
long
long
loginTime
};
In a JavaScript implementation of the interface, the username attribute will be exposed as a non-configurable property on the
object itself:
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
// This defineProperty call would succeed, because System.prototype.loginTime
// is configurable.
var
forgedLoginTime
Object
defineProperty
System
prototype
"loginTime"
value
forgedLoginTime
});
system
loginTime
// So this now evaluates to forgedLoginTime.
3.4.11.
[LegacyWindowAlias]
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
take an identifier
or
take an identifier list
The
identifier
s that occur after the
” are the [
LegacyWindowAlias
]'s
identifiers
Each of the
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
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
§ 3.7 Interfaces
for details on how legacy window aliases
are to be implemented.
The following IDL defines an interface that uses the
LegacyWindowAlias
] extended attribute.
Exposed
Window
LegacyWindowAlias
WebKitCSSMatrix
interface
DOMMatrix
DOMMatrixReadOnly
// ...
};
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.
WebKitCSSMatrix
===
DOMMatrix
// Evaluates to true.
var
new
WebKitCSSMatrix
();
// Creates a new object that
// implements DOMMatrix.
constructor
===
DOMMatrix
// Evaluates to true.
constructor
===
WebKitCSSMatrix
// Evaluates to true.
{}.
toString
call
);
// Evaluates to '[object DOMMatrix]'.
3.5.
Security
Certain algorithms in the sections below are defined to
perform a security check
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:
the
platform object
on
which the operation invocation or attribute access is being done,
the
identifier
of the operation or attribute, and
the type of the
function object
method
" (when it corresponds to an IDL operation), or
getter
" or "
setter
" (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]
3.6.
Overload resolution algorithm
In order to define how function invocations are resolved, the
overload resolution algorithm
is defined. Its input is an
effective overload set
, and a list of JavaScript values,
args
Its output is a pair consisting of the
operation
or
extended attribute
of one of
’s entries
and a list of IDL values or the special value “missing”. The algorithm behaves as follows:
Let
maxarg
be the length of the longest type list of the entries in
Let
be the
size
of
args
Initialize
argcount
to be min(
maxarg
).
Remove from
all entries whose type list is not of length
argcount
If
is empty, then
throw
TypeError
Initialize
to −1.
Initialize
method
to
undefined
If there is more than one entry in
, then set
to be the
distinguishing argument index
for the entries of
Initialize
values
to be an empty list, where each entry will be either an IDL value or the special value “missing”.
Initialize
to 0.
While
Let
be
args
].
Let
type
be the type at index
in the type list of any entry in
Note:
All entries in
at this point have the same type and
optionality value
at index
Let
optionality
be the value at index
in the list of
optionality values
of any entry in
If
optionality
is “optional” and
is
undefined
, then:
If the argument at index
is declared with a
default value
then append to
values
that default value.
Otherwise, append to
values
the special value “missing”.
Otherwise, append to
values
the result of
converting
to IDL type
type
Set
to
+ 1.
If
, then:
Let
be
args
].
Note:
This is the argument that will be used to resolve which overload is selected.
If
is
undefined
, and there is an entry in
whose list of
optionality values
has “optional” at index
then remove from
all other entries.
Otherwise: if
is
null
or
undefined
and there is an entry in
that has one of the following types at position
of its type list,
nullable type
dictionary type
an
annotated type
whose
inner type
is one of the above types
union type
or
annotated
union type that
includes a nullable type
or that
has a
dictionary type
in its
flattened members
then remove from
all other entries.
Otherwise: if
is a platform object
, and
there is an entry in
that has one of the following types at position
of its type list,
an
interface type
that
implements
object
nullable
version of any of the above types
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
then remove from
all other entries.
Otherwise: if
is an Object
has an [[ArrayBufferData]]
internal slot
, and
there is an entry in
that has one of the following types at position
of its type list,
ArrayBuffer
SharedArrayBuffer
object
nullable
version of either of the above types
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
then remove from
all other entries.
Otherwise: if
is an Object
has a [[DataView]]
internal slot
, and
there is an entry in
that has one of the following types at position
of its type list,
DataView
object
nullable
version of either of the above types
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
then remove from
all other entries.
Otherwise: if
is an Object
has a [[TypedArrayName]]
internal slot
, and
there is an entry in
that has one of the following types at position
of its type list,
typed array type
whose name
is equal to the value of
’s [[TypedArrayName]]
internal slot
object
nullable
version of either of the above types
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
then remove from
all other entries.
Otherwise: if
IsCallable
) is true,
and there is an entry in
that has one of the following types at position
of its type list,
callback function
type
object
nullable
version of any of the above types
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
then remove from
all other entries.
Otherwise: if
is an Object
and
there is an entry in
that has one of the
following types at position
of its type list,
an
async sequence type
nullable
version of any of the above types
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
and the following are not all true,
has a [[StringData]]
internal slot
has one of the following types at position
of its type list,
string type
nullable
version of a
string type
an
annotated type
whose
inner type
is a
string type
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
and after performing the following steps,
Let
method
be
GetMethod
%Symbol.asyncIterator%
).
If
method
is
undefined
, then set
method
to
GetMethod
%Symbol.iterator%
).
method
is not
undefined
, then remove from
all
other entries.
Otherwise: if
is an Object
and
there is an entry in
that has one of the
following types at position
of its type list,
sequence type
nullable
version of any of the above types
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
and after performing the following steps,
Let
method
be
GetMethod
%Symbol.iterator%
).
method
is not
undefined
, then remove from
all
other entries.
Otherwise: if
is an Object
and
there is an entry in
that has one of the following types at position
of its type list,
callback interface type
dictionary type
record type
object
nullable
version of any of the above types
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
then remove from
all other entries.
Otherwise: if
is a Boolean
and there is an entry in
that has one of the following types at position
of its type list,
boolean
nullable
boolean
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
then remove from
all other entries.
Otherwise: if
is a Number
and there is an entry in
that has one of the following types at position
of its type list,
numeric type
nullable
numeric type
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
then remove from
all other entries.
Otherwise: if
is a BigInt
and there is an entry in
that has one of the following types at position
of its type list,
bigint
nullable
bigint
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
then remove from
all other entries.
Otherwise: if there is an entry in
that has one of the following types at position
of its type list,
string type
nullable
version of any of the above types
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
then remove from
all other entries.
Otherwise: if there is an entry in
that has one of the following types at position
of its type list,
numeric type
nullable
numeric type
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
then remove from
all other entries.
Otherwise: if there is an entry in
that has one of the following types at position
of its type list,
boolean
nullable
boolean
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
then remove from
all other entries.
Otherwise: if there is an entry in
that has one of the following types at position
of its type list,
bigint
nullable
bigint
an
annotated type
whose
inner type
is one of the above types
union type
nullable
union type, or
annotated
union type
that has one of the above types in its
flattened member types
then remove from
all other entries.
Otherwise: if there is an entry in
that has
any
at position
of its type list, then remove from
all other entries.
Otherwise:
throw
TypeError
Let
callable
be the
operation
or
extended attribute
of the single entry in
If
and
method
is not
undefined
, then
Let
be
args
].
Let
be the type at index
in the
type list of the remaining entry in
Assert:
is a
sequence type
Append to
values
the result of
creating a sequence
of type
from
and
method
Set
to
+ 1.
While
argcount
Let
be
args
].
Let
type
be the type at index
in the type list of the remaining entry in
Let
optionality
be the value at index
in the list of
optionality values
of the remaining entry in
If
optionality
is “optional” and
is
undefined
, then:
If the argument at index
is declared with a
default value
then append to
values
that default value.
Otherwise, append to
values
the special value “missing”.
Otherwise, append to
values
the result of
converting
to IDL type
type
Set
to
+ 1.
While
is less than the number of arguments
callable
is declared to take:
If
callable
’s argument at index
is declared with a
default value
then append to
values
that default value.
Otherwise, if
callable
’s argument at index
is not variadic, then append to
values
the special value “missing”.
Set
to
+ 1.
Return the pair <
callable
values
>.
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
undefined
and there is an overload with an
optional
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 sequence 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
optional
argument’s JavaScript value to its
equivalent IDL value,
undefined
will be converted into the
optional argument’s default value
if it has one, or a special value “missing” otherwise.
Optional
arguments corresponding to a final, variadic argument do
not treat
undefined
as a special “missing” value, however.
The
undefined
value is converted to the type
of variadic argument as would be done for a non-
optional
argument.
3.7.
Interfaces
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
global object
The name of the property is the
identifier
of the interface,
and its value is an object called the
interface object
The characteristics of an interface object are described in
§ 3.7.1 Interface object
If the [
LegacyWindowAlias
] extended attribute was specified on an
exposed
interface,
then for each
identifier
in [
LegacyWindowAlias
]'s
identifiers
there exists a corresponding property on the
Window
global object.
The name of the property is the given
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
identifier
and its value is an object called a
legacy factory function
which allows creation of objects that implement the interface.
The characteristics of a legacy factory function are described in
§ 3.7.2 Legacy factory functions
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
implementation-check an object
jsValue
against the interface
interface
with the identifier
name
and the type
type
Let
object
to
ToObject
jsValue
).
If
object
is a
platform object
then
perform a security check
, passing:
the platform object
object
the identifier
name
the type
type
If
object
does not
implement
interface
, then
throw
TypeError
Return
object
This algo is not yet consistently used everywhere.
3.7.1.
Interface object
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
§ 3.7.5 Constants
and
§ 3.7.7 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
§ 3.7.3 Interface prototype object
Note:
Since an
interface object
is a
function object
the
typeof
operator will return "function" when applied to an interface object.
An interface may have
overridden constructor steps
, which can
change the behavior of the
interface object
when called or constructed. By
default interfaces do not have such steps.
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
filing an issue
before proceeding.
The
interface object
for a given
interface
with
identifier
id
and in
realm
realm
is
created
as follows:
Let
steps
be
’s
overridden constructor steps
if they exist, or
the following steps otherwise:
If
was not declared with a
constructor operation
then
throw
TypeError
If
NewTarget
is
undefined
, then
throw
TypeError
Let
args
be the passed arguments.
Let
be the
size
of
args
Let
id
be the identifier of interface
Compute the effective overload set
for constructors with
identifier
id
on
interface
and with argument count
, and let
be the result.
Let <
constructor
values
> be the result
of passing
and
args
to the
overload resolution algorithm
Let
object
be the result of
internally creating a new object implementing
, with
realm
and
NewTarget
Perform the
constructor steps
of
constructor
with
object
as
this
and
values
as the argument values.
Let
be
object
converted to a JavaScript value
Assert:
is an object that
implements
Assert:
.[[Realm]] is
realm
Return
Let
constructorProto
be
realm
.[[Intrinsics]].[[
%Function.prototype%
]].
If
inherits from some other interface
then set
constructorProto
to the
interface object
of
in
realm
Let
unforgeables
be
OrdinaryObjectCreate
null
).
Define the unforgeable regular operations
of
on
unforgeables
, given
realm
Define the unforgeable regular attributes
of
on
unforgeables
, given
realm
Set
.[[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
operation functions
Let
length
be 0.
If
was declared with a
constructor operation
, then
Compute the effective overload set
for constructors with
identifier
id
on
interface
and with argument count 0, and let
be the result.
Set
length
to the length of the
shortest argument list of the entries in
Let
be
CreateBuiltinFunction
steps
length
id
, « [[Unforgeables]] »,
realm
constructorProto
).
Let
proto
be the result of
creating an interface
prototype object
of
interface
in
realm
Perform
DefinePropertyOrThrow
, "
prototype
",
PropertyDescriptor{[[Value]]:
proto
, [[Writable]]:
false
, [[Enumerable]]:
false
, [[Configurable]]:
false
}).
Define the constants
of
interface
on
given
realm
Define the static attributes
of
interface
on
given
realm
Define the static operations
of
interface
on
given
realm
Return
3.7.2.
Legacy factory functions
legacy factory function
that exists due to one or more
LegacyFactoryFunction
extended attributes
with a given
identifier
is a
built-in function object
It allows constructing objects that
implement the interface on which the
LegacyFactoryFunction
] extended attributes appear.
The
legacy factory function
with
identifier
id
for a given
interface
in
realm
realm
is
created
as follows:
Let
steps
be the following steps:
If
NewTarget
is
undefined
, then
throw
TypeError
Let
args
be the passed arguments.
Let
be the
size
of
args
Compute the effective overload set
for legacy factory functions with
identifier
id
on
interface
and with argument count
, and let
be the result.
Let <
constructor
values
> be the result of passing
and
args
to the
overload resolution algorithm
Let
object
be the result of
internally creating a new object implementing
, with
realm
and
NewTarget
Perform the
constructor steps
of
constructor
with
object
as
this
and
values
as the argument values.
Let
be
object
converted to a JavaScript value
Assert:
is an object that
implements
Assert:
.[[Realm]] is
realm
Return
Compute the effective overload set
for legacy factory functions with
identifier
id
on
interface
and with argument count 0, and let
be the result.
Let
length
be the length of the shortest argument list of the entries in
Let
be
CreateBuiltinFunction
steps
length
id
, « »,
realm
).
Let
proto
be the
interface prototype object
of
interface
in
realm
Perform
DefinePropertyOrThrow
, "
prototype
",
PropertyDescriptor{[[Value]]:
proto
, [[Writable]]:
false
, [[Enumerable]]:
false
, [[Configurable]]:
false
}).
Return
3.7.3.
Interface prototype object
There will exist an
interface prototype object
for every
interface
defined,
regardless of whether the interface was declared
with the [
LegacyNoInterfaceObject
extended attribute
The
interface prototype object
for a given
interface
interface
and
realm
realm
is
created
as follows:
Let
proto
be null.
If
interface
is declared with the [
Global
extended attribute
and
interface
supports named properties
then set
proto
to the result of
creating a named
properties object
for
interface
and
realm
Otherwise, if
interface
is declared to inherit from another interface,
then set
proto
to the
interface prototype object
in
realm
of that
inherited interface
Otherwise, if
interface
is the
DOMException
interface
then set
proto
to
realm
.[[Intrinsics]].[[
%Error.prototype%
]].
Otherwise, set
proto
to
realm
.[[Intrinsics]].[[
%Object.prototype%
]].
Assert:
proto
is an Object
Let
interfaceProtoObj
be null.
If
realm
’s
is global prototype chain mutable
is true, then:
Set
interfaceProtoObj
to
OrdinaryObjectCreate
proto
).
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:
Set
interfaceProtoObj
to
MakeBasicObject
(« [[Prototype]], [[Extensible]] »).
Set
interfaceProtoObj
.[[Prototype]] to
proto
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
Otherwise, set
interfaceProtoObj
to
OrdinaryObjectCreate
proto
).
If
interface
has any
member
declared with the [
Unscopable
extended attribute
then:
Let
unscopableObject
be
OrdinaryObjectCreate
null
).
For each
exposed
member
member
of
interface
that is declared with the [
Unscopable
extended attribute
Let
id
be
member
’s
identifier
Perform
CreateDataPropertyOrThrow
unscopableObject
id
true
).
Let
desc
be the PropertyDescriptor{[[Value]]:
unscopableObject
[[Writable]]:
false
, [[Enumerable]]:
false
[[Configurable]]:
true
}.
Perform
DefinePropertyOrThrow
interfaceProtoObj
%Symbol.unscopables%
desc
).
If
interface
is not declared with the [
Global
extended attribute
, then:
Define the regular attributes
of
interface
on
interfaceProtoObj
given
realm
Define the regular operations
of
interface
on
interfaceProtoObj
given
realm
Define the iteration methods
of
interface
on
interfaceProtoObj
given
realm
Define the asynchronous iteration methods
of
interface
on
interfaceProtoObj
given
realm
Define the constants
of
interface
on
interfaceProtoObj
given
realm
If the [
LegacyNoInterfaceObject
extended attribute
was not specified on
interface
, then:
Let
constructor
be the
interface object
of
interface
in
realm
Let
desc
be the PropertyDescriptor{[[Writable]]:
true
[[Enumerable]]:
false
, [[Configurable]]:
true
[[Value]]:
constructor
}.
Perform
DefinePropertyOrThrow
interfaceProtoObj
, "
constructor
",
desc
).
Return
interfaceProtoObj
Additionally,
interface prototype objects
get properties declaratively from:
§ 3.7.8 Stringifiers
§ 3.7.11 Maplike declarations
, and
§ 3.7.12 Setlike declarations
Define those properties imperatively instead.
The
interface prototype object
of an
interface
that is defined with
the [
LegacyNoInterfaceObject
extended attribute
will be accessible.
For example, with the following IDL:
Exposed
Window
LegacyNoInterfaceObject
interface
Foo
};
partial
interface
Window
attribute
Foo
foo
};
it is not possible to access the interface prototype object through
the
interface object
(since it does not exist as
window.Foo
). However, an instance
of
Foo
can expose the interface prototype
object by calling its [[GetPrototypeOf]]
internal method
Object.getPrototypeOf(window.foo)
in
this example.
The
class string
of an
interface prototype object
is the
interface
’s
qualified name
3.7.4.
Named properties object
For every
interface
declared with the [
Global
extended attribute
that
supports named properties
there will exist an object known as the
named properties object
for that interface on which named properties are exposed.
The
named properties object
for a given
interface
interface
and
realm
realm
is
created
as follows:
Let
proto
be null.
If
interface
is declared to inherit from another interface,
then set
proto
to the
interface prototype object
in
realm
for the
inherited interface
Otherwise, set
proto
to
realm
.[[Intrinsics]].[[
%Object.prototype%
]].
Let
obj
be
MakeBasicObject
(« [[Prototype]], [[Extensible]] »).
Set
obj
.[[GetOwnProperty]] as specified in
§ 3.7.4.1 [[GetOwnProperty]]
Set
obj
.[[DefineOwnProperty]] as specified in
§ 3.7.4.2 [[DefineOwnProperty]]
Set
obj
.[[Delete]] as specified in
§ 3.7.4.3 [[Delete]]
Set
obj
.[[SetPrototypeOf]] as specified in
§ 3.7.4.4 [[SetPrototypeOf]]
Set
obj
.[[PreventExtensions]] as specified in
§ 3.7.4.5 [[PreventExtensions]]
Set
obj
.[[Prototype]] to
proto
Return
obj
Note:
The [[OwnPropertyKeys]] internal method of a named properties object
continues to use
OrdinaryOwnPropertyKeys
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 "
Properties
".
3.7.4.1.
[[GetOwnProperty]]
When the [[GetOwnProperty]] internal method of a
named properties object
is called with property key
, the following steps are taken:
Let
be the
interface
for the
named properties object
Let
object
be
.[[Realm]]'s
global object
Assert:
object
implements
If the result of running the
named property visibility algorithm
with
property name
and object
object
is true, then:
Let
operation
be the operation used to declare the named property getter.
Let
value
be an uninitialized variable.
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
as the name.
Otherwise,
operation
was defined with an identifier. Set
value
to the result
of performing the steps listed in the description of
operation
with
as the only argument value.
Let
desc
be a newly created
Property Descriptor
with no fields.
Set
desc
.[[Value]] to the result of
converting
value
to a JavaScript value.
If
implements
an interface with the
LegacyUnenumerableNamedProperties
extended attribute
then set
desc
.[[Enumerable]] to
false
otherwise set it to
true
Set
desc
.[[Writable]] to
true
and
desc
.[[Configurable]] to
true
Return
desc
Return
OrdinaryGetOwnProperty
).
3.7.4.2.
[[DefineOwnProperty]]
When the [[DefineOwnProperty]] internal method of a
named properties object
is called,
the following steps are taken:
Return
false
3.7.4.3.
[[Delete]]
When the [[Delete]] internal method of a
named properties object
is called,
the following steps are taken:
Return
false
3.7.4.4.
[[SetPrototypeOf]]
When the [[SetPrototypeOf]] internal method of a
named properties object
is called with
JavaScript language value
, the following step is taken:
If
’s
associated realm
’s
is global prototype chain mutable
is true,
return
OrdinarySetPrototypeOf
).
Return
SetImmutablePrototype
).
3.7.4.5.
[[PreventExtensions]]
When the [[PreventExtensions]] internal method of a
named properties object
is called,
the following steps are taken:
Return
false
Note:
this keeps
named properties object
extensible by
making [[PreventExtensions]] fail.
3.7.5.
Constants
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
To
define the constants
of
interface
callback interface
, or
namespace
definition
on
target
, given
realm
realm
, run the following steps:
For each
constant
const
that is a
member
of
definition
If
const
is not
exposed
in
realm
, then
continue
Let
value
be the result of
converting
const
’s IDL value to a JavaScript value.
Let
desc
be the PropertyDescriptor{[[Writable]]:
false
[[Enumerable]]:
true
, [[Configurable]]:
false
[[Value]]:
value
}.
Let
id
be
const
’s
identifier
Perform
DefinePropertyOrThrow
target
id
desc
).
3.7.6.
Attributes
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.
To
define the regular attributes
of
interface
or
namespace
definition
on
target
given
realm
realm
, run the following steps:
Let
attributes
be the
list
of
regular attributes
that are
members
of
definition
Remove
from
attributes
all the
attributes
that are
unforgeable
Define the attributes
attributes
of
definition
on
target
given
realm
To
define the static attributes
of
interface
or
namespace
definition
on
target
given
realm
realm
, run the following steps:
Let
attributes
be the
list
of
static attributes
that are
members
of
definition
Define the attributes
attributes
of
definition
on
target
given
realm
To
define the unforgeable regular attributes
of
interface
or
namespace
definition
on
target
given
realm
realm
, run the following steps:
Let
attributes
be the
list
of
unforgeable
regular attributes
that are
members
of
definition
Define the attributes
attributes
of
definition
on
target
given
realm
To
define the attributes
attributes
of
interface
or
namespace
definition
on
target
given
realm
realm
, run the following steps:
For each
attribute
attr
of
attributes
If
attr
is not
exposed
in
realm
, then
continue
Let
getter
be the result of creating an
attribute getter
given
attr
definition
, and
realm
Let
setter
be the result of creating an
attribute setter
given
attr
definition
, and
realm
Note:
the algorithm to create an
attribute setter
returns
undefined
if
attr
is
read only
Let
configurable
be
false
if
attr
is
unforgeable
and
true
otherwise.
Let
desc
be the PropertyDescriptor{[[Get]]:
getter
, [[Set]]:
setter
[[Enumerable]]:
true
, [[Configurable]]:
configurable
}.
Let
id
be
attr
’s
identifier
Perform
DefinePropertyOrThrow
target
id
desc
).
If
attr
’s type is an
observable array type
with type argument
, then set
target
’s
backing observable array exotic object
for
attr
to the result of
creating an observable array exotic object
in
realm
, given
attr
’s
set an indexed value
algorithm, and
attr
’s
delete an indexed value
algorithm.
The
attribute getter
is created as follows, given an
attribute
attribute
, a
namespace
or
interface
target
, and a
realm
realm
Let
steps
be the following series of steps:
Try running the following steps:
Let
idlObject
be null.
If
target
is an
interface
, and
attribute
is a
regular attribute
Let
jsValue
be the
this
value, if it is not
null
or
undefined
, or
realm
’s
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.)
If
jsValue
is a platform object
, then
perform a security check
passing
jsValue
attribute
’s
identifier
, and "getter".
If
jsValue
does not
implement
target
, then:
If
attribute
was specified with the [
LegacyLenientThis
extended attribute
, then return
undefined
Otherwise,
throw
TypeError
If
attribute
’s type is an
observable array type
, then return
jsValue
’s
backing observable array exotic object
for
attribute
Set
idlObject
to the IDL
interface type
value that represents a reference
to
jsValue
Let
be the result of running the
getter steps
of
attribute
with
idlObject
as
this
Return the result of
converting
to a
JavaScript value of the type
attribute
is declared as.
And then, if
an exception
was thrown
If
attribute
’s type is a
promise type
, then return
Call
%Promise.reject%
%Promise%
, «
»).
Otherwise, end these steps and allow the exception to propagate.
Let
name
be the string "
get
" prepended to
attribute
’s
identifier
Let
be
CreateBuiltinFunction
steps
, 0,
name
, « »,
realm
).
Return
The
attribute setter
is created as follows, given an
attribute
attribute
, a
namespace
or
interface
target
, and a
realm
realm
If
target
is a
namespace
Assert:
attribute
is
read only
Return
undefined
If
attribute
is
read only
and does not have a
LegacyLenientSetter
], [
PutForwards
] or [
Replaceable
extended attribute
, return
undefined
; there is no
attribute setter
function.
Assert:
attribute
’s type is not a
promise type
Let
steps
be the following series of steps:
Let
be
undefined
If any arguments were passed, then set
to the value of the first argument passed.
Let
id
be
attribute
’s
identifier
Let
idlObject
be null.
If
attribute
is a
regular attribute
Let
jsValue
be the
this
value, if it is not
null
or
undefined
, or
realm
’s
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.)
If
jsValue
is a platform object
, then
perform a security check
, passing
jsValue
id
, and "setter".
Let
validThis
be true if
jsValue
implements
target
, or false otherwise.
If
validThis
is false and
attribute
was not specified with the [
LegacyLenientThis
extended attribute
, then
throw
TypeError
If
attribute
is declared with the [
Replaceable
] extended attribute, then:
Perform
CreateDataPropertyOrThrow
jsValue
id
).
Return
undefined
If
validThis
is false, then return
undefined
If
attribute
is declared with a [
LegacyLenientSetter
] extended attribute, then
return
undefined
If
attribute
is declared with a [
PutForwards
] extended attribute, then:
Let
be
Get
jsValue
id
).
If
is not an Object
, then
throw
TypeError
Let
forwardId
be the identifier argument of the [
PutForwards
] extended
attribute.
Perform
Set
forwardId
false
).
Return
undefined
Set
idlObject
to the IDL
interface type
value that represents a reference
to
jsValue
If
attribute
’s type is an
observable array type
with type argument
Let
newValues
be the result of
converting
to
an IDL value of type
sequence<
Let
oa
be
idlObject
’s
attribute
’s
backing observable array exotic object
Set the length
of
oa
.[[ProxyHandler]] to 0.
Let
be 0.
While
newValues
’s
size
Perform the algorithm steps given by
oa
.[[ProxyHandler]].[[SetAlgorithm]], given
newValues
] and
Append
newValues
] to
oa
.[[ProxyHandler]].[[BackingList]].
Return
undefined
Let
idlValue
be determined as follows:
attribute
’s type is an
enumeration
Let
be
ToString
).
If
is not one of the
enumeration’s values
, then
return
undefined
Otherwise,
idlValue
is the enumeration value equal to
Otherwise
idlValue
is the result of
converting
to an
IDL value of
attribute
’s type.
Perform the
setter steps
of
attribute
with
idlObject
as
this
and
idlValue
as
the given value
Return
undefined
Let
name
be the string "
set
" prepended to
id
Let
be
CreateBuiltinFunction
steps
, 1,
name
, « »,
realm
).
Return
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.
3.7.7.
Operations
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.
To
define the regular operations
of
interface
or
namespace
definition
on
target
, given
realm
realm
run the following steps:
Let
operations
be the
list
of
regular operations
that are
members
of
definition
Remove
from
operations
all the
operations
that are
unforgeable
Define the operations
operations
of
definition
on
target
given
realm
To
define the static operations
of
interface
or
namespace
definition
on
target
, given
realm
realm
run the following steps:
Let
operations
be the
list
of
static operations
that are
members
of
definition
Define the operations
operations
of
definition
on
target
given
realm
To
define the unforgeable regular operations
of
interface
or
namespace
definition
on
target
, given
realm
realm
run the following steps:
Let
operations
be the
list
of
unforgeable
regular operations
that are
members
of
definition
Define the operations
operations
of
definition
on
target
given
realm
To
define the operations
operations
of
interface
or
namespace
definition
on
target
given
realm
realm
, run the following steps:
For each
operation
op
of
operations
If
op
is not
exposed
in
realm
, then
continue
Let
method
be the result of
creating an operation function
given
op
definition
, and
realm
Let
modifiable
be
false
if
op
is
unforgeable
and
true
otherwise.
Let
desc
be the PropertyDescriptor{[[Value]]:
method
[[Writable]]:
modifiable
, [[Enumerable]]:
true
[[Configurable]]:
modifiable
}.
Let
id
be
op
’s
identifier
Perform
DefinePropertyOrThrow
target
id
desc
).
To
create an operation function
given an
operation
op
, a
namespace
or
interface
target
, and a
realm
realm
Let
id
be
op
’s
identifier
Let
steps
be the following series of steps, given function argument
values
args
Try running the following steps:
Let
idlObject
be null.
If
target
is an
interface
, and
op
is not a
static operation
Let
jsValue
be the
this
value, if it is not
null
or
undefined
, or
realm
’s
global object
otherwise.
(This will subsequently cause a
TypeError
in a few steps, if
the global object does not implement
target
.)
If
jsValue
is a platform object
, then
perform a security check
passing
jsValue
id
, and "method".
If
jsValue
does not
implement
the interface
target
throw
TypeError
Set
idlObject
to the IDL
interface type
value that represents a reference
to
jsValue
Let
be the
size
of
args
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
, and let
be
the result.
Let <
operation
values
> be the result of passing
and
args
to the
overload resolution algorithm
Let
be
null
If
operation
is declared with a [
Default
extended attribute
, then:
Assert:
operation
has default method steps
Set
to the result of running the
default method steps
for
operation
with
idlObject
as
this
and
values
as the argument values.
Otherwise, set
to the result of running the
method steps
of
operation
with
idlObject
as
this
and
values
as the argument values.
Return
converted to a JavaScript value
is assumed to be an IDL value of the type
op
is declared to return.
[whatwg/webidl Issue #674]
And then, if
an exception
was thrown
If
op
has a
return type
that is a
promise type
, then return
Call
%Promise.reject%
%Promise%
, «
»).
Otherwise, end these steps and allow the exception to propagate.
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
be the result.
Let
length
be the length of the shortest argument list in the entries in
Let
be
CreateBuiltinFunction
steps
length
id
, « »,
realm
).
Return
3.7.7.1.
Default operations
regular operation
has default method steps
if its
identifier
appears in the first column of the following table. In that case, its
default method steps
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.
Identifier
Default method steps
Return type
toJSON
The
default toJSON steps
object
regular operation
that does not
have default method steps
must not be declared with a
Default
extended attribute
3.7.7.1.1.
Default toJSON operation
The
default toJSON steps
for an
interface
are:
Let
map
be a new
ordered map
Let
stack
be the result of
creating an inheritance stack
for
interface
Invoke
collect attribute values of an inheritance stack
given
this
stack
, and
map
Let
result
be
OrdinaryObjectCreate
%Object.prototype%
).
For each
key
value
of
map
Let
be
key
converted to a JavaScript value
Let
be
value
converted to a JavaScript value
Perform
CreateDataPropertyOrThrow
result
).
Return
result
To
collect attribute values of an inheritance stack
given a
platform object
object
, a
stack
stack
, and an
ordered map
map
Let
be the result of
popping
from
stack
Invoke
collect attribute values
given
object
, and
map
If
stack
is not empty
, then invoke
collect attribute values of an inheritance stack
given
object
stack
, and
map
To
collect attribute values
given a
platform object
object
, an
interface
, and an
ordered map
map
If a
toJSON
operation with a [
Default
extended attribute
is declared
on
, then
for each
exposed
regular attribute
attr
that is an
interface member
of
, in order:
Let
id
be the
identifier
of
attr
Let
value
be the result of running the
getter steps
of
attr
with
object
as
this
If
value
is a
JSON type
, then
set
map
id
] to
value
To
create an inheritance stack
for
interface
run the following steps:
Let
stack
be a new
stack
Push
onto
stack
While
inherits
from an
interface
Let
be that
interface
Push
onto
stack
Return
stack
Only
regular attributes
of
interfaces
that declare a
toJSON
operation with
a [
Default
extended attribute
are included, even if an
inherited interface
declares
such a
toJSON
operation. For example, consider the following
IDL fragment
[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;
};
Calling the
toJSON()
method of an object implementing interface
defined above would return the following JSON object:
"a"
"..."
"c"
"..."
Calling the
toJSON()
method of an object implementing interface
(or
) defined above would return:
"a"
"..."
toJSON
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
[Exposed=Window]
interface D {
attribute DOMString d;
};

interface mixin M {
[Default] object toJSON();
attribute DOMString m;
};

D includes M;
Calling the
toJSON()
method of an object implementing interface
defined above would return:
"d"
"..."
"m"
"..."
3.7.8.
Stringifiers
If the
interface
has an
exposed
stringifier
then there must exist a property with the following characteristics:
The name of the property is "
toString
".
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]]:
, [[Enumerable]]:
true
, [[Configurable]]:
},
where
is
false
if the stringifier is
unforgeable
on the interface,
and
true
otherwise.
The value of the property is a
built-in function object
, which behaves as follows:
Let
thisValue
be the
this
value.
Let
be
ToObject
thisValue
).
If
is a platform object
then
perform a security check
, passing:
the platform object
the
identifier
of the
stringifier
, and
the type "
method
".
If
does not
implement
the
interface
on which the stringifier was declared, then
throw
TypeError
Let
be an uninitialized variable.
Depending on how
stringifier
was specified:
as a declaration
Set
to the result of performing the
stringification behavior
of the interface.
on an
attribute
Set
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
as
this
Return the result of
converting
to a String value.
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
toString
".
3.7.9.
Iterable declarations
To
define the iteration methods
of
interface
definition
on
target
, given
realm
realm
, run the following steps:
If
definition
has an
indexed property getter
, then:
Perform
DefineMethodProperty
target
%Symbol.iterator%
%Array.prototype.values%
, false).
If
definition
has a
value iterator
, then:
Perform
CreateDataPropertyOrThrow
target
, "
entries
",
%Array.prototype.entries%
).
Perform
CreateDataPropertyOrThrow
target
, "
keys
",
%Array.prototype.keys%
).
Perform
CreateDataPropertyOrThrow
target
, "
values
",
%Array.prototype.values%
).
Perform
CreateDataPropertyOrThrow
target
, "
forEach
",
%Array.prototype.forEach%
).
Otherwise, if
definition
has a
pair iterator
, then:
Define the
%Symbol.iterator%
and
entries
methods:
Let
steps
be the following series of steps:
Let
jsValue
be
ToObject
this
value).
If
jsValue
is a platform object
, then
perform a security check
passing
jsValue
, "
%Symbol.iterator%
", and "
method
".
If
jsValue
does not
implement
definition
, then
throw
TypeError
Return a newly created
default iterator object
for
definition
, with
jsValue
as its
target
, "
key+value
as its
kind
, and
index
set to 0.
Let
be
CreateBuiltinFunction
steps
, 0, "
entries
", « »,
realm
).
Perform
DefineMethodProperty
target
%Symbol.iterator%
, false).
Perform
CreateDataPropertyOrThrow
target
, "
entries
",
).
Define the
keys
method:
Let
steps
be the following series of steps:
Let
jsValue
be
ToObject
this
value).
If
jsValue
is a platform object
, then
perform a security check
passing
jsValue
, "
keys
", and "
method
".
If
jsValue
does not
implement
definition
, then
throw
TypeError
Return a newly created
default iterator object
for
definition
, with
jsValue
as its
target
, "
key
" as its
kind
, and
index
set to 0.
Let
be
CreateBuiltinFunction
steps
, 0, "
keys
", « »,
realm
).
Perform
CreateDataPropertyOrThrow
target
, "
keys
",
).
Define the
values
method:
Let
steps
be the following series of steps:
Let
jsValue
be
ToObject
this
value).
If
jsValue
is a platform object
, then
perform a security check
passing
jsValue
, "
values
", and "
method
".
If
jsValue
does not
implement
definition
, then
throw
TypeError
Return a newly created
default iterator object
for
definition
, with
jsValue
as its
target
, "
value
" as its
kind
, and
index
set to 0.
Let
be
CreateBuiltinFunction
steps
, 0, "
values
", « »,
realm
).
Perform
CreateDataPropertyOrThrow
target
, "
values
",
).
Define the
forEach
method:
Let
steps
be the following series of steps, given function argument values
callback
and
thisArg
Let
jsValue
be
ToObject
this
value).
If
jsValue
is a platform object
, then
perform a security check
passing
jsValue
, "
forEach
", and "
method
".
If
jsValue
does not
implement
definition
, then
throw
TypeError
Let
idlCallback
be
callback
converted
to a
Function
Let
idlObject
be the IDL
interface type
value that represents a reference
to
jsValue
Let
pairs
be
idlObject
’s list of
value pairs to iterate over
Let
be 0.
While
pairs
’s
size
Let
pair
be
pairs
].
Invoke
idlCallback
with «
pair
’s
value
pair
’s
key
idlObject
» and with
thisArg
as the
callback this value
Set
pairs
to
idlObject
’s current list of
value pairs to iterate over
. (It might have changed.)
Set
to
+ 1.
Let
be
CreateBuiltinFunction
steps
, 1, "
forEach
", « »,
realm
).
Perform
CreateDataPropertyOrThrow
target
, "
forEach
",
).
3.7.9.1.
Default iterator objects
default iterator object
for a given
interface
, target and iteration kind
is an object whose [[Prototype]]
internal slot
is the
iterator prototype object
for the
interface
default iterator object
has three internal values:
its
target
, which is an object whose values are to be
iterated,
its
kind
, which is the iteration kind,
its
index
, 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
supported indexed properties
use standard JavaScript Array iterator objects.
Note:
Default iterator objects
do not have
class strings
; when
Object.prototype.toString()
is called on a
default iterator object
of a given
interface
, the
class string
of the
iterator prototype object
of that
interface
is used.
3.7.9.2.
Iterator prototype object
The
iterator prototype object
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%
The
iterator result
for a
value pair
pair
and a kind
kind
is given by the
following steps:
Let
result
be a value determined by the value of
kind
key
Let
idlKey
be
pair
’s
key
Let
key
be the result of
converting
idlKey
to a JavaScript value.
result
is
key
value
Let
idlValue
be
pair
’s
value
Let
value
be the result of
converting
idlValue
to a JavaScript value.
result
is
value
key+value
Let
idlKey
be
pair
’s
key
Let
idlValue
be
pair
’s
value
Let
key
be the result of
converting
idlKey
to a JavaScript value.
Let
value
be the result of
converting
idlValue
to a JavaScript value.
Let
array
be
ArrayCreate
(2).
Perform
CreateDataPropertyOrThrow
array
, "
",
key
).
Perform
CreateDataPropertyOrThrow
array
, "
",
value
).
result
is
array
Return
CreateIteratorResultObject
result
false
).
An
iterator prototype object
must have a
next
data property with attributes
{ [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
and whose value is a
built-in function object
that behaves as follows:
Let
interface
be the
interface
for which the
iterator prototype object
exists.
Let
thisValue
be the
this
value.
Let
object
be
ToObject
thisValue
).
If
object
is a platform object
then
perform a security check
, passing:
the platform object
object
the identifier "
next
", and
the type "
method
".
If
object
is not a
default iterator object
for
interface
then
throw
TypeError
Let
index
be
object
’s
index
Let
kind
be
object
’s
kind
Let
values
be
object
’s
target
’s
value pairs to iterate over
Let
len
be the length of
values
If
index
is greater than or equal to
len
, then
return
CreateIteratorResultObject
undefined
true
).
Let
pair
be the entry in
values
at index
index
Set
object
’s index to
index
+ 1.
Return the
iterator result
for
pair
and
kind
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 "
Iterator
".
3.7.10.
Asynchronous iterable declarations
To
define the asynchronous iteration methods
of
interface
definition
on
target
, given
realm
realm
, run the following steps:
If
definition
does not have an an
asynchronously iterable declaration
(of either
sort), then return.
Assert:
definition
does not have an
indexed property getter
or an
iterable declaration
If
definition
has a
pair asynchronously iterable declaration
, then define the
%Symbol.asyncIterator%
and
entries
methods:
Let
steps
be the following series of steps, given function argument values
args
Let
jsValue
be
ToObject
this
value).
If
jsValue
is a platform object
, then
perform a security check
, passing
jsValue
, "
%Symbol.asyncIterator%
", and "
method
".
If
jsValue
does not
implement
definition
, then
throw
TypeError
Let
idlObject
be the IDL
interface type
value that represents a reference to
jsValue
Let
idlArgs
be the result of
converting arguments for an asynchronous iterator method
given
args
Let
iterator
be a newly created
default asynchronous iterator object
for
definition
with
idlObject
as its
target
, "
key+value
" as its
kind
, and
is finished
set to false.
Run the
asynchronous iterator initialization steps
for
definition
with
idlObject
iterator
, and
idlArgs
, if any such steps exist.
Return
iterator
Let
be
CreateBuiltinFunction
steps
, 0, "
entries
", « »,
realm
).
Perform
DefineMethodProperty
target
%Symbol.asyncIterator%
, false).
Perform
CreateDataPropertyOrThrow
target
, "
entries
",
).
If
definition
has a
pair asynchronously iterable declaration
, then define the
keys
method:
Let
steps
be the following series of steps, given function argument values
args
Let
jsValue
be
ToObject
this
value).
If
jsValue
is a platform object
, then
perform a security check
, passing
jsValue
, "
keys
", and "
method
".
If
jsValue
does not
implement
definition
, then
throw
TypeError
Let
idlObject
be the IDL
interface type
value that represents a reference to
jsValue
Let
idlArgs
be the result of
converting arguments for an asynchronous iterator method
given
args
Let
iterator
be a newly created
default asynchronous iterator object
for
definition
with
idlObject
as its
target
, "
key
" as its
kind
, and
is finished
set to false.
Run the
asynchronous iterator initialization steps
for
definition
with
idlObject
iterator
, and
idlArgs
, if any such steps exist.
Return
iterator
Let
be
CreateBuiltinFunction
steps
, 0, "
keys
, « »,
realm
).
Perform
CreateDataPropertyOrThrow
target
, "
keys
",
).
Define the
values
, and possibly
%Symbol.asyncIterator%
, methods:
Let
steps
be the following series of steps, given function argument values
args
Let
jsValue
be
ToObject
this
value).
If
jsValue
is a platform object
, then
perform a security check
, passing
jsValue
, "
values
", and "
method
".
If
jsValue
does not
implement
definition
, then
throw
TypeError
Let
idlObject
be the IDL
interface type
value that represents a reference to
jsValue
Let
idlArgs
be the result of
converting arguments for an asynchronous iterator method
given
args
Let
iterator
be a newly created
default asynchronous iterator object
for
definition
with
idlObject
as its
target
, "
value
" as its
kind
, and
is finished
set to false.
Run the
asynchronous iterator initialization steps
for
definition
with
idlObject
iterator
, and
idlArgs
, if any such steps exist.
Return
iterator
Let
be
CreateBuiltinFunction
steps
, 0, "
values
", « »,
realm
).
Perform
CreateDataPropertyOrThrow
target
, "
values
",
).
If
definition
has a
value asynchronously iterable declaration
, then perform
DefineMethodProperty
target
%Symbol.asyncIterator%
, false).
To
convert arguments for an asynchronous iterator method
given an
interface
definition
that has an
asynchronously iterable declaration
and a
list
of JavaScript values
args
Let
idlArgs
be an empty list.
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.
Let
be 0.
While
argCount
If
args
’s
size
, or if
args
] is
undefined
then:
If the argument to the
asynchronously iterable declaration
at index
is
declared with a
default value
, then
append
that
default value to
idlArgs
Otherwise,
append
to
idlArgs
the special value "missing".
Otherwise,
append
to
idlArgs
the result of
converting
args
] to the IDL type given in the
asynchronously iterable declaration
’s argument list at index
Set
to
+ 1.
Return
idlArgs
This is essentially a hyper-specialization of the
overload resolution algorithm
for the case where no overloads are allowed and all arguments
are optional.
3.7.10.1.
Default asynchronous iterator objects
default asynchronous iterator
object
for a given
interface
, target and iteration kind is an object whose [[Prototype]]
internal slot
is the
asynchronous iterator prototype object
for the
interface
default asynchronous iterator object
has internal values:
its
target
, which is an object whose
values are to be iterated,
its
kind
, which is the iteration kind,
its
ongoing promise
, which is a
Promise
or null,
its
is finished
, which is a boolean.
Note:
Default asynchronous iterator objects
do not have
class strings
; when
Object.prototype.toString()
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.
3.7.10.2.
Asynchronous iterator prototype object
The
asynchronous iterator prototype object
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%
An
asynchronous iterator prototype object
must have a
next
data
property with attributes { [[Writable]]:
true
[[Enumerable]]:
true
, [[Configurable]]:
true
and whose value is a
built-in function object
that behaves as follows:
Let
interface
be the
interface
for which the
asynchronous iterator prototype object
exists.
Let
thisValidationPromiseCapability
be
NewPromiseCapability
%Promise%
).
Let
thisValue
be the
this
value.
Let
object
be
Completion
ToObject
thisValue
)).
IfAbruptRejectPromise
object
thisValidationPromiseCapability
).
If
object
is a platform object
, then
perform a security check
, passing:
the platform object
object
the identifier "
next
", and
the type "
method
".
If this threw an exception
, then:
Perform
Call
thisValidationPromiseCapability
.[[Reject]],
undefined
, «
»).
Return
thisValidationPromiseCapability
.[[Promise]].
If
object
is not a
default asynchronous iterator object
for
interface
, then:
Let
error
be a new
TypeError
Perform
Call
thisValidationPromiseCapability
.[[Reject]],
undefined
, «
error
»).
Return
thisValidationPromiseCapability
.[[Promise]].
Let
nextSteps
be the following steps:
Let
nextPromiseCapability
be
NewPromiseCapability
%Promise%
).
If
object
’s
is finished
is true, then:
Let
result
be
CreateIteratorResultObject
undefined
true
).
Perform
Call
nextPromiseCapability
.[[Resolve]],
undefined
, «
result
»).
Return
nextPromiseCapability
.[[Promise]].
Let
kind
be
object
’s
kind
Let
nextPromise
be the result of
getting the next iteration result
with
object
’s
target
and
object
Let
fulfillSteps
be the following steps, given
next
Set
object
’s
ongoing promise
to
null.
If
next
is
end of iteration
, then:
Set
object
’s
is finished
to true.
Return
CreateIteratorResultObject
undefined
true
).
Otherwise, if
interface
has a
pair asynchronously iterable declaration
Assert:
next
is a
value pair
Return the
iterator result
for
next
and
kind
Otherwise:
Assert:
interface
has a
value asynchronously iterable declaration
Assert:
next
is a value of the type that appears in the declaration.
Let
value
be
next
converted to a JavaScript value
Return
CreateIteratorResultObject
value
false
).
Let
onFulfilled
be
CreateBuiltinFunction
fulfillSteps
, 1, "", « »).
Let
rejectSteps
be the following steps, given
reason
Set
object
’s
ongoing promise
to
null.
Set
object
’s
is finished
to true.
Throw
reason
Let
onRejected
be
CreateBuiltinFunction
rejectSteps
, 1, "", « »).
Perform
PerformPromiseThen
nextPromise
onFulfilled
onRejected
nextPromiseCapability
).
Return
nextPromiseCapability
.[[Promise]].
Let
ongoingPromise
be
object
’s
ongoing promise
If
ongoingPromise
is not null, then:
Let
afterOngoingPromiseCapability
be
NewPromiseCapability
%Promise%
).
Let
onSettled
be
CreateBuiltinFunction
nextSteps
, 0, "", « »).
Perform
PerformPromiseThen
ongoingPromise
onSettled
onSettled
afterOngoingPromiseCapability
).
Set
object
’s
ongoing promise
to
afterOngoingPromiseCapability
.[[Promise]].
Otherwise:
Set
object
’s
ongoing promise
to the result of
running
nextSteps
Return
object
’s
ongoing promise
If an
asynchronous iterator return
algorithm is defined for the
interface
, then the
asynchronous iterator prototype object
must have a
return
data
property with attributes { [[Writable]]:
true
[[Enumerable]]:
true
, [[Configurable]]:
true
and whose value is a
built-in function object
, taking one argument
value
, that behaves as
follows:
Let
interface
be the
interface
for which the
asynchronous iterator prototype object
exists.
Let
returnPromiseCapability
be
NewPromiseCapability
%Promise%
).
Let
thisValue
be the
this
value.
Let
object
be
Completion
ToObject
thisValue
)).
IfAbruptRejectPromise
object
returnPromiseCapability
).
If
object
is a platform object
, then
perform a security check
, passing:
the platform object
object
the identifier "
return
", and
the type "
method
".
If this threw an exception
, then:
Perform
Call
returnPromiseCapability
.[[Reject]],
undefined
, «
»).
Return
returnPromiseCapability
.[[Promise]].
If
object
is not a
default asynchronous iterator object
for
interface
, then:
Let
error
be a new
TypeError
Perform
Call
returnPromiseCapability
.[[Reject]],
undefined
, «
error
»).
Return
returnPromiseCapability
.[[Promise]].
Let
returnSteps
be the following steps:
Let
returnPromiseCapability
be
NewPromiseCapability
%Promise%
).
If
object
’s
is finished
is true, then:
Let
result
be
CreateIteratorResultObject
value
true
).
Perform
Call
returnPromiseCapability
.[[Resolve]],
undefined
, «
result
»).
Return
returnPromiseCapability
.[[Promise]].
Set
object
’s
is finished
to true.
Return the result of running the
asynchronous iterator return
algorithm for
interface
, given
object
’s
target
object
and
value
Let
ongoingPromise
be
object
’s
ongoing promise
If
ongoingPromise
is not null, then:
Let
afterOngoingPromiseCapability
be
NewPromiseCapability
%Promise%
).
Let
onSettled
be
CreateBuiltinFunction
returnSteps
, 0, "", « »).
Perform
PerformPromiseThen
ongoingPromise
onSettled
onSettled
afterOngoingPromiseCapability
).
Set
object
’s
ongoing promise
to
afterOngoingPromiseCapability
.[[Promise]].
Otherwise:
Set
object
’s
ongoing promise
to the result of
running
returnSteps
Let
fulfillSteps
be the following steps:
Return
CreateIteratorResultObject
value
true
).
Let
onFulfilled
be
CreateBuiltinFunction
fulfillSteps
, 1, "", « »).
Perform
PerformPromiseThen
object
’s
ongoing promise
onFulfilled
undefined
returnPromiseCapability
).
Return
returnPromiseCapability
.[[Promise]].
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
AsyncIterator
".
3.7.11.
Maplike declarations
If an
interface
is declared with
maplike declaration
, then
there exists a number of additional properties on
’s
interface prototype object
These additional properties are described in the sub-sections below.
3.7.11.1.
size
There must exist a
size
property on
’s
interface prototype object
with the following characteristics:
The property has attributes
{ [[Get]]:
, [[Enumerable]]:
true
, [[Configurable]]:
true
},
where
is the interface’s
map size getter
defined below.
The
map size getter
is a
built-in function object
whose behavior when invoked is as follows:
Let
be the
this
value,
implementation-checked
against
with identifier "
size
" and type "
getter
".
Let
map
be the
map entries
of the IDL value
that represents a reference to
Return
map
’s
size
converted to a JavaScript value
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
get size
".
3.7.11.2.
%Symbol.iterator%
There must exist a data property whose name is the
%Symbol.iterator%
symbol on
’s
interface prototype object
with attributes { [[Writable]]:
true
, [[Enumerable]]:
false
, [[Configurable]]:
true
and whose value is the
function object
that is the value of
the
entries
property.
To
create a map iterator
from a
map
map
and a
kind
which is either "
key+value
", "
key
", or "
value
":
Let
closure
be a new
Abstract Closure
with no parameters
that captures
map
and
kind
and performs the following steps when called:
For each
key
value
of
map
Set
key
and
value
to each
converted to a JavaScript value
If
kind
is "
key
", let
result
be
key
Else if
kind
is "
value
", let
result
be
value
Else, let
result
be
CreateArrayFromList
(«
key
value
»).
Perform
GeneratorYield
CreateIteratorResultObject
result
false
)).
Note:
The
size
of
map
, and the order of its entries,
might have changed while execution of this abstract operation
was paused by
Yield
Return
undefined
Return
CreateIteratorFromClosure
closure
, "
%MapIteratorPrototype%
",
%MapIteratorPrototype%
).
3.7.11.3.
entries
There must exist an
entries
data property on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
whose behavior when invoked is as follows:
Let
be the
this
value,
implementation-checked
against
with identifier "
entries
" and type "
method
".
Let
map
be the
map entries
of the IDL value
that represents a reference to
Return the result of
creating a map iterator
from
map
with kind "
key+value
".
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
entries
".
3.7.11.4.
keys
There must exist a
keys
data property on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
whose behavior when invoked is as follows:
Let
be the
this
value,
implementation-checked
against
with identifier "
keys
" and type "
method
".
Let
map
be the
map entries
of the IDL value
that represents a reference to
Return the result of
creating a map iterator
from
map
with kind "
key
".
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
keys
".
3.7.11.5.
values
There must exist a
values
data property on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
whose behavior when invoked is as follows:
Let
be the
this
value,
implementation-checked
against
with identifier "
values
" and type "
method
".
Let
map
be the
map entries
of the IDL value
that represents a reference to
Return the result of
creating a map iterator
from
map
with kind "
value
".
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
values
".
3.7.11.6.
forEach
There must exist a
forEach
data property on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
whose behavior when invoked is as follows:
Let
be the
this
value,
implementation-checked
against
with identifier "
forEach
" and type "
method
".
Let
map
be the
map entries
of the IDL value
that represents a reference to
Let
callbackFn
be the first argument passed to the function, or
undefined
if not supplied.
If
IsCallable
callbackFn
) is
false
throw
TypeError
Let
thisArg
be the second argument passed to the function, or
undefined
if not supplied.
For each
key
value
of
map
Let
jsKey
and
jsValue
be
key
and
value
converted to a JavaScript value
Perform
Call
callbackFn
thisArg
, «
jsValue
jsKey
»).
Return
undefined
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
forEach
".
3.7.11.7.
get
There must exist a
get
data property on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
that behaves as follows when invoked:
Let
be the
this
value,
implementation-checked
against
with identifier "
get
" and type "
method
".
Let
map
be the
map entries
of the IDL value
that represents a reference to
Let
keyType
be the key type specified in the
maplike declaration
Let
keyArg
be the first argument passed to this function, or
undefined
if not supplied.
Let
key
be
keyArg
converted to an IDL value
of type
keyType
If
key
is -0, set
key
to +0.
If
map
key
exists
, then return
map
key
],
converted to a JavaScript value
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
get
".
3.7.11.8.
has
There must exist a
has
data property on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
that behaves as follows when invoked:
Let
be the
this
value,
implementation-checked
against
with identifier "
has
" and type "
method
".
Let
map
be the
map entries
of the IDL value
that represents a reference to
Let
keyType
be the key type specified in the
maplike declaration
Let
keyArg
be the first argument passed to this function, or
undefined
if not supplied.
Let
key
be
keyArg
converted to an IDL value
of type
keyType
If
key
is -0, set
key
to +0.
If
map
key
exists
, then return
true
otherwise return
false
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
has
".
3.7.11.9.
set
If
does not declare a
member
with identifier "
set
",
and
was declared with a read–write maplike declaration,
then there must exist a
set
data property
on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
that behaves as follows when invoked:
Let
be the
this
value,
implementation-checked
against
with identifier "
set
" and type "
method
".
Let
map
be the
map entries
of the IDL value
that represents a reference to
Let
keyType
be the key type specified in the
maplike declaration
, and
valueType
be the value type.
Let
keyArg
be the first argument passed to this function, or
undefined
if not supplied.
Let
key
be
keyArg
converted to an IDL value
of type
keyType
If
key
is -0, set
key
to +0.
Let
valueArg
be the second argument passed to this function, or
undefined
if not supplied.
Let
value
be
valueArg
converted to an IDL value
of type
valueType
Set
map
key
] to
value
Return
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
set
".
If the interface does declare a
set
method,
it should similarly map a -0 key to +0,
and must return
this
3.7.11.10.
delete
If
does not declare a
member
with identifier "
delete
",
and
was declared with a read–write maplike declaration,
then there must exist a
delete
data property
on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
that behaves as follows when invoked:
Let
be the
this
value,
implementation-checked
against
with identifier "
delete
" and type "
method
".
Let
map
be the
map entries
of the IDL value
that represents a reference to
Let
keyType
be the key type specified in the
maplike declaration
Let
keyArg
be the first argument passed to this function, or
undefined
if not supplied.
Let
key
be
keyArg
converted to an IDL value
of type
keyType
If
key
is -0, set
key
to +0.
Let
retVal
be
true
if
map
key
] exists,
or else
false
Remove
map
key
].
Return
retVal
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
delete
".
If the interface does declare a
delete
method,
it should similarly map a -0 key to +0,
and must return a
boolean
indicating whether the key was present or not.
3.7.11.11.
clear
If
does not declare a
member
with identifier "
clear
",
and
was declared with a read–write maplike declaration,
then there must exist a
clear
data property
on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
that behaves as follows when invoked:
Let
be the
this
value,
implementation-checked
against
with identifier "
clear
" and type "
method
".
Let
map
be the
map entries
of the IDL value
that represents a reference to
Clear
map
Note:
The
map
is preserved because there may be existing
iterators, currently suspended, iterating over it.
Return
undefined
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
clear
".
If the interface does declare a
clear
method,
it must preserve the
map entries
object (rather than generating a new one)
and must return
undefined
3.7.12.
Setlike declarations
If an
interface
is declared with a
setlike declaration
then there exists a number of additional properties on
’s
interface prototype object
These additional properties are described in the sub-sections below.
3.7.12.1.
size
size
property must exist on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Get]]:
, [[Enumerable]]:
true
, [[Configurable]]:
true
},
where
is the interface’s
set size getter
defined below.
The
set size getter
is a
built-in function object
whose behavior when invoked is as follows:
Let
be the
this
value,
implementation-checked
against
with identifier "
size
" and type "
getter
".
Let
set
be the
set entries
of the IDL value
that represents a reference to
Return
set
’s
size
converted to a JavaScript value
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
get size
".
3.7.12.2.
%Symbol.iterator%
There must exist a data property whose name is the
%Symbol.iterator%
symbol on
’s
interface prototype object
with attributes { [[Writable]]:
true
, [[Enumerable]]:
false
, [[Configurable]]:
true
and whose value is the
function object
that is the value of
the
values
property.
To
create a set iterator
from a
set
set
and a
kind
which is either "
key+value
" or "
value
":
Let
closure
be a new
Abstract Closure
with no parameters
that captures
set
and
kind
and performs the following steps when called:
For each
entry
of
set
Set
entry
to be
entry
converted to a JavaScript value
If
kind
is "
value
", let
result
be
entry
Else, let
result
be
CreateArrayFromList
(«
entry
entry
»).
Perform
GeneratorYield
CreateIteratorResultObject
result
false
)).
Note:
The
size
of
set
, and the order of its entries,
might have changed while execution of this abstract operation
was paused by
Yield
Return
undefined
Return
CreateIteratorFromClosure
closure
, "
%SetIteratorPrototype%
",
%SetIteratorPrototype%
).
3.7.12.3.
entries
There must exist an
entries
data property on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
whose behavior when invoked is as follows:
Let
be the
this
value,
implementation-checked
against
with identifier "
entries
" and type "
method
".
Let
set
be the
set entries
of the IDL value
that represents a reference to
Return the result of
creating a set iterator
from
set
with kind "
key+value
".
The value of the
function object
’s
length
property is
the Number value
The value of the
function object
’s
name
property is
the String value "
entries
".
3.7.12.4.
keys
keys
data property must exist
on
’s
interface prototype object
with attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
and whose value is the
function object
that is the value of
the
values
property.
3.7.12.5.
values
There must exist a
values
data property on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
whose behavior when invoked is as follows:
Let
be the
this
value,
implementation-checked
against
with identifier "
values
" and type "
method
".
Let
set
be the
set entries
of the IDL value
that represents a reference to
Return the result of
creating a set iterator
from
set
with kind "
value
".
The value of the
function object
’s
length
property is
the Number value
The value of the
function object
’s
name
property is
the String value "
values
".
3.7.12.6.
forEach
There must exist a
forEach
data property on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
whose behavior when invoked is as follows:
Let
be the
this
value,
implementation-checked
against
with identifier "
forEach
" and type "
method
".
Let
set
be the
set entries
of the IDL value
that represents a reference to
Let
callbackFn
be the first argument passed to the function, or
undefined
if not supplied.
If
IsCallable
callbackFn
) is
false
throw
TypeError
Let
thisArg
be the second argument passed to the function, or
undefined
if not supplied.
For each
value
of
set
Let
jsValue
be
value
converted to a JavaScript value
Perform
Call
callbackFn
thisArg
, «
jsValue
jsValue
»).
Return
undefined
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
forEach
".
3.7.12.7.
has
There must exist a
has
data property on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
that behaves as follows when invoked:
Let
be the
this
value,
implementation-checked
against
with identifier "
has
" and type "
method
".
Let
set
be the
set entries
of the IDL value
that represents a reference to
Let
valueType
be the value type specified in the
setlike declaration
Let
valueArg
be the first argument passed to this function, or
undefined
if not supplied.
Let
value
be
valueArg
converted to an IDL value
of type
valueType
If
value
is -0, set
value
to +0.
If
set
contains
value
, then return
true
otherwise return
false
The value of the
function object
’s
length
property is a Number value
The value of the
function object
’s
name
property is the String value "
has
".
3.7.12.8.
add
If
does not declare a
member
with identifier "
add
",
and
was declared with a read–write setlike declaration,
then there must exist an
add
data property
on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
that behaves as follows when invoked:
Let
be the
this
value,
implementation-checked
against
with identifier "
add
" and type "
method
".
Let
set
be the
set entries
of the IDL value
that represents a reference to
Let
valueType
be the value type specified in the
setlike declaration
Let
valueArg
be the first argument passed to this function, or
undefined
if not supplied.
Let
value
be
valueArg
converted to an IDL value
of type
valueType
If
value
is -0, set
value
to +0.
Append
value
to
set
Return
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
add
".
If the interface does declare an
add
method,
it should similarly map a -0 value to +0,
and must return the value that was set.
3.7.12.9.
delete
If
does not declare a
member
with identifier "
delete
",
and
was declared with a read–write setlike declaration,
then there must exist a
delete
data property
on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
that behaves as follows when invoked:
Let
be the
this
value,
implementation-checked
against
with identifier "
delete
" and type "
method
".
Let
set
be
’s
set entries
Let
valueType
be the value type specified in the
setlike declaration
Let
valueArg
be the first argument passed to this function, or
undefined
if not supplied.
Let
value
be
valueArg
converted to an IDL value
of type
valueType
If
value
is -0, set
value
to +0.
Let
retVal
be
true
if
set
contains
value
, or else
false
Remove
value
from
set
Return
retVal
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
delete
".
If the interface does declare a
delete
method,
it should similarly map a -0 value to +0,
and must return a
boolean
indicating whether the value was present or not.
3.7.12.10.
clear
If
does not declare a
member
with identifier "
clear
",
and
was declared with a read–write setlike declaration,
then there must exist a
clear
data property
on
’s
interface prototype object
with the following characteristics:
The property has attributes { [[Writable]]:
true
, [[Enumerable]]:
true
, [[Configurable]]:
true
}.
The value of the property is a
built-in function object
that behaves as follows when invoked:
Let
be the
this
value,
implementation-checked
against
with identifier "
clear
" and type "
method
".
Let
set
be the
set entries
of the IDL value
that represents a reference to
Empty
set
Note:
The
set
is preserved because there may be existing
iterators, currently suspended, iterating over it.
Return
undefined
The value of the
function object
’s
length
property is the Number value
The value of the
function object
’s
name
property is the String value "
clear
".
If the interface does declare a
clear
method,
it must preserve the
set entries
object (rather than generating a new one)
and must return
undefined
3.8.
Platform objects implementing interfaces
A JavaScript value
value
is a platform object
if
value
is an Object
and
if
value
has a [[PrimaryInterface]] internal slot.
A JavaScript value
value
implements
an
interface
interface
if
value
is a platform object
and the
inclusive inherited interfaces
of
value
.[[PrimaryInterface]]
contains
interface
Specifications may reference the concept "
object
implements
interface
in various ways, including "
object
is an
interface
object".
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.
To
create a new object implementing the interface
interface
, with a
realm
realm
, perform the following steps:
Return the result of
internally creating a new object implementing
interface
, with
realm
and
undefined
To
internally create a new object implementing the interface
interface
, with a
realm
realm
and a JavaScript value
newTarget
, perform the following steps:
Assert:
interface
is
exposed
in
realm
If
newTarget
is
undefined
, then:
Let
prototype
be the
interface prototype object
for
interface
in
realm
Otherwise:
Assert:
IsCallable
newTarget
) is true.
Let
prototype
be
Get
newTarget
, "prototype").
If
prototype
is not an Object
, then:
Let
targetRealm
be
GetFunctionRealm
newTarget
).
Set
prototype
to the
interface prototype object
for
interface
in
targetRealm
Let
slots
be « [[Prototype]], [[Extensible]], [[Realm]], [[PrimaryInterface]] ».
If
interface
is
DOMException
, append [[ErrorData]] to
slots
Let
instance
be
MakeBasicObject
slots
).
Set
instance
.[[Realm]] to
realm
Set
instance
.[[PrimaryInterface]] to
interface
Set
instance
.[[Prototype]] to
prototype
Let
interfaces
be the
inclusive inherited interfaces
of
interface
For every
interface
ancestor interface
in
interfaces
Let
unforgeables
be the value of the [[Unforgeables]] slot of the
interface object
of
ancestor interface
in
realm
Let
keys
be
unforgeables
.[[OwnPropertyKeys]]().
For each
element
key
of
keys
Let
descriptor
be
unforgeables
.[[GetOwnProperty]](
key
).
Perform
DefinePropertyOrThrow
instance
key
descriptor
).
If
interface
is declared with the [
Global
extended attribute
, then:
Define the regular operations
of
interface
on
instance
, given
realm
Define the regular attributes
of
interface
on
instance
, given
realm
Define the iteration methods
of
interface
on
instance
given
realm
Define the asynchronous iteration methods
of
interface
on
instance
given
realm
Define the global property references
on
instance
, given
realm
Set
instance
.[[SetPrototypeOf]] as defined in
§ 3.8.1 [[SetPrototypeOf]]
Otherwise, if
interfaces
contains an
interface
which
supports indexed properties
named properties
, or both:
Set
instance
.[[GetOwnProperty]] as defined in
§ 3.9.1 [[GetOwnProperty]]
Set
instance
.[[Set]] as defined in
§ 3.9.2 [[Set]]
Set
instance
.[[DefineOwnProperty]] as defined in
§ 3.9.3 [[DefineOwnProperty]]
Set
instance
.[[Delete]] as defined in
§ 3.9.4 [[Delete]]
Set
instance
.[[PreventExtensions]] as defined in
§ 3.9.5 [[PreventExtensions]]
Set
instance
.[[OwnPropertyKeys]] as defined in
§ 3.9.6 [[OwnPropertyKeys]]
Return
instance
To
define the global property references
on
target
, given
realm
realm
perform the following steps:
Let
interfaces
be a
list
that contains every
interface
that is
exposed
in
realm
Sort
interfaces
in such a way that if
and
are
items
of
interfaces
and
inherits
from
has a higher index in
interfaces
than
For every
interface
of
interfaces
If
interface
is not declared with the [
LegacyNoInterfaceObject
] or
LegacyNamespace
extended attributes
, then:
Let
id
be
interface
’s
identifier
Let
interfaceObject
be the result of
creating
an interface object
for
interface
with
id
in
realm
Perform
DefineMethodProperty
target
id
interfaceObject
, false).
If the
interface
is declared with a [
LegacyWindowAlias
extended attribute
and
target
implements the
Window
interface
, then:
For every
identifier
id
in
LegacyWindowAlias
]'s
identifiers
Perform
DefineMethodProperty
target
id
interfaceObject
, false).
If the
interface
is declared with a [
LegacyFactoryFunction
extended attribute
then:
For every
identifier
id
in
LegacyFactoryFunction
]'s
identifiers
Let
legacyFactoryFunction
be the result of
creating a legacy factory function
with
id
for
interface
in
realm
Perform
DefineMethodProperty
target
id
legacyFactoryFunction
, false).
For every
callback interface
interface
that is
exposed
in
realm
and on which
constants
are defined:
Let
id
be
interface
’s
identifier
Let
interfaceObject
be the result of
creating a legacy callback interface object
for
interface
with
id
in
realm
Perform
DefineMethodProperty
target
id
interfaceObject
, false).
For every
namespace
namespace
that is
exposed
in
realm
Let
id
be
namespace
’s
identifier
Let
namespaceObject
be the result of
creating a namespace object
for
namespace
in
realm
Perform
DefineMethodProperty
target
id
namespaceObject
, false).
The set of interfaces that a
platform object
implements
does not change over
the lifetime of the object.
Multiple
platform objects
with different
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
operation function
checks that the receiver
implements
the particular
interface
which
includes
the
interface mixin
The
primary interface
of a
platform object
is
the value of the object’s [[PrimaryInterface]] internal slot, which is the most-derived
interface
that it
implements
The
realm
that a given
platform object
is associated with can
change
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:
§ 3.7.8 Stringifiers
§ 3.7.11 Maplike declarations
, and
§ 3.7.12 Setlike declarations
Define those properties imperatively instead.
3.8.1.
[[SetPrototypeOf]]
When the [[SetPrototypeOf]] internal method of a
platform object
that implements an
interface
with the [
Global
extended attribute
is called with
JavaScript language value
, the following step is taken:
If
’s
associated realm
’s
is global prototype chain mutable
is true,
return
OrdinarySetPrototypeOf
).
Return
SetImmutablePrototype
).
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.
3.9.
Legacy platform objects
Legacy platform objects
will appear to have additional properties that correspond to their
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
[[GetOwnProperty]] internal method
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
unforgeable property name
on a
given platform object
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
implements.
Support for
getters
is handled in
§ 3.9.1 [[GetOwnProperty]]
and for
setters
in
§ 3.9.3 [[DefineOwnProperty]]
and
§ 3.9.2 [[Set]]
Additionally,
legacy platform objects
have internal methods as defined in:
§ 3.9.4 [[Delete]]
§ 3.9.5 [[PreventExtensions]]
, and
§ 3.9.6 [[OwnPropertyKeys]]
3.9.1.
[[GetOwnProperty]]
The [[GetOwnProperty]] internal method of every
legacy platform object
must behave as follows when called with property name
Return
LegacyPlatformObjectGetOwnProperty
false
).
3.9.2.
[[Set]]
The [[Set]] internal method of every
legacy platform object
must behave as follows when called with
property name
, value
, and JavaScript language value
Receiver
If
and
Receiver
are the same object, then:
If
implements
an interface with an
indexed property setter
and
is an array index
, then:
Invoke the indexed property setter
on
with
and
Return
true
If
implements
an interface with a
named property setter
and
is a String
, then:
Invoke the named property setter
on
with
and
Return
true
Let
ownDesc
be
LegacyPlatformObjectGetOwnProperty
true
).
Perform
OrdinarySetWithOwnDescriptor
Receiver
ownDesc
).
3.9.3.
[[DefineOwnProperty]]
When the [[DefineOwnProperty]] internal method of a
legacy platform object
is called with property key
and
Property Descriptor
Desc
the following steps must be taken:
If
supports indexed properties
and
is an array index
, then:
If the result of calling
IsDataDescriptor
Desc
) is
false
, then return
false
If
does not implement an interface with an
indexed property setter
, then return
false
Invoke the indexed property setter
on
with
and
Desc
.[[Value]].
Return
true
If
supports named properties
does not implement an
interface
with the [
Global
extended attribute
is a String
and
is not an
unforgeable property name
of
, then:
Let
creating
be true if
is not a
supported property name
, and false otherwise.
If
implements
an interface with the [
LegacyOverrideBuiltIns
extended attribute
or
does not have an own property
named
, then:
If
creating
is false and
does not implement an
interface with a
named property setter
, then return
false
If
implements
an interface with a
named property setter
, then:
If the result of calling
IsDataDescriptor
Desc
) is
false
, then return
false
Invoke the named property setter
on
with
and
Desc
.[[Value]].
Return
true
Return
OrdinaryDefineOwnProperty
Desc
).
3.9.4.
[[Delete]]
The [[Delete]] internal method of every
legacy platform object
must behave as follows when called with property name
If
supports indexed properties
and
is an array index
, then:
Let
index
be the result of calling
ToUint32
).
If
index
is not a
supported property index
, then return
true
Return
false
If
supports named properties
does not implement an
interface
with the [
Global
extended attribute
and the result of calling the
named property visibility algorithm
with property name
and object
is true, then:
If
does not implement an interface with a
named property deleter
, then return
false
Let
operation
be the operation used to declare the named property deleter.
If
operation
was defined without an
identifier
, then:
Perform the steps listed in the interface description to
delete an existing named property
with
as the name.
If the steps indicated that the deletion failed, then return
false
Otherwise,
operation
was defined with an identifier:
Perform
method steps
of
operation
with
as
this
and «
» as the
argument values.
If
operation
was declared with a
return type
of
boolean
and the steps returned
false
, then return
false
Return
true
If
has an own property with name
, then:
If the property is not configurable, then return
false
Otherwise, remove the property from
Return
true
3.9.5.
[[PreventExtensions]]
When the [[PreventExtensions]] internal method of a
legacy platform object
is called,
the following steps are taken:
Return
false
Note:
this keeps
legacy platform objects
extensible by
making [[PreventExtensions]] fail for them.
3.9.6.
[[OwnPropertyKeys]]
This document does not define a complete property enumeration order
for
platform objects
implementing
interfaces
(or for
platform objects representing exceptions
).
However, it does for
legacy platform objects
by defining the [[OwnPropertyKeys]]
internal method as follows.
When the [[OwnPropertyKeys]] internal method of a
legacy platform object
is called,
the following steps are taken:
Let
keys
be a new empty
list
of JavaScript String and Symbol values.
If
supports indexed properties
, then
for each
index
of
’s
supported property indices
, in ascending numerical order,
append
ToString
index
) to
keys
If
supports named properties
, then
for each
of
’s
supported property names
that is visible according to the
named property visibility algorithm
append
to
keys
For each
of
’s own property keys that is a String, in ascending chronological order of
property creation,
append
to
keys
For each
of
’s own property keys that is a Symbol, in ascending chronological order of
property creation,
append
to
keys
Assert:
keys
has no duplicate items.
Return
keys
3.9.7.
Abstract operations
To determine if a property name
is an
array index
, the following algorithm is
applied:
If
is not a String
, then return
false
Let
index
be
CanonicalNumericIndexString
).
If
index
is
undefined
, then return
false
If
IsInteger
index
) is
false
then return
false
If
index
is −0, then return
false
If
index
< 0, then return
false
If
index
≥ 2
32
− 1, then return
false
Note:
32
− 1 is the maximum array length allowed by JavaScript.
Return
true
The
named property visibility algorithm
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
and object
If
is not a
supported property name
of
, then return false.
If
has an own property named
, then return false.
Note:
This will include cases in which
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.
If
implements
an interface that has the [
LegacyOverrideBuiltIns
extended attribute
, then return true.
Let
prototype
be
.[[GetPrototypeOf]]().
While
prototype
is not null:
If
prototype
is not a
named properties object
and
prototype
has an own property named
, then return false.
Set
prototype
to
prototype
.[[GetPrototypeOf]]().
Return true.
This ensures that for objects with named properties, property resolution is done in the following order:
Indexed properties.
Own properties, including unforgeable attributes and operations.
Then, if [
LegacyOverrideBuiltIns
]:
Named properties.
Properties from the prototype chain.
Otherwise, if not [
LegacyOverrideBuiltIns
]:
Properties from the prototype chain.
Named properties.
To
invoke an indexed property setter
on a
platform object
with property name
and JavaScript value
, the following steps must be performed:
Let
index
be the result of calling
ToUint32
).
Let
creating
be true if
index
is not a
supported property index
and false otherwise.
Let
operation
be the operation used to declare the indexed property setter.
Let
be the type of the second argument of
operation
Let
value
be the result of
converting
to an IDL value of type
If
operation
was defined without an
identifier
, then:
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.
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.
Otherwise,
operation
was defined with an identifier. Perform the
method steps
of
operation
with
as
this
and «
index
value
» as the argument values.
To
invoke a named property setter
on a
platform object
with property name
and JavaScript value
, the following steps must be performed:
Let
creating
be true if
is not a
supported property name
, and false otherwise.
Let
operation
be the operation used to declare the named property setter.
Let
be the type of the second argument of
operation
Let
value
be the result of
converting
to an IDL value of type
If
operation
was defined without an
identifier
, then:
If
creating
is true, then perform the steps listed in the interface description to
set the value of a new named property
with
as the name and
value
as the value.
Otherwise,
creating
is false. Perform the steps listed in the interface description to
set the value of an existing named property
with
as the name and
value
as the value.
Otherwise,
operation
was defined with an identifier. Perform the
method steps
of
operation
with
as
this
and «
value
» as the argument values.
The
LegacyPlatformObjectGetOwnProperty
abstract operation performs the following steps when called with
an object
, a property name
, and a boolean
ignoreNamedProps
value:
If
supports indexed properties
and
is an array index
, then:
Let
index
be the result of calling
ToUint32
).
If
index
is a
supported property index
, then:
Let
operation
be the operation used to declare the indexed property getter.
Let
value
be an uninitialized variable.
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.
Otherwise,
operation
was defined with an identifier. Set
value
to the result
of performing the
method steps
of
operation
with
as
this
and «
index
» as the argument values.
Let
desc
be a newly created
Property Descriptor
with no fields.
Set
desc
.[[Value]] to the result of
converting
value
to a JavaScript value.
If
implements
an interface with an
indexed property setter
, then set
desc
.[[Writable]] to
true
, otherwise set it to
false
Set
desc
.[[Enumerable]] and
desc
.[[Configurable]] to
true
Return
desc
Set
ignoreNamedProps
to true.
If
supports named properties
and
ignoreNamedProps
is false, then:
If the result of running the
named property visibility algorithm
with
property name
and object
is true, then:
Let
operation
be the operation used to declare the named property getter.
Let
value
be an uninitialized variable.
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
as the name.
Otherwise,
operation
was defined with an identifier. Set
value
to the result
of performing the
method steps
of
operation
with
as
this
and «
as the argument values.
Let
desc
be a newly created
Property Descriptor
with no fields.
Set
desc
.[[Value]] to the result of
converting
value
to a JavaScript value.
If
implements
an interface with a
named property setter
, then set
desc
.[[Writable]] to
true
, otherwise set it to
false
If
implements
an interface with the
LegacyUnenumerableNamedProperties
extended attribute
then set
desc
.[[Enumerable]] to
false
otherwise set it to
true
Set
desc
.[[Configurable]] to
true
Return
desc
Return
OrdinaryGetOwnProperty
).
3.10.
Observable array exotic objects
An
observable array exotic object
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
Array
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
Array
instances:
The arrays have no holes, i.e. every property in the inclusive range 0 through
observableArray.length
− 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
length
property remains as a non-configurable,
non-enumerable, and writable data property.
Adding additional properties to the array cannot be prevented using, for example,
Object.preventExtensions()
To
create an observable array exotic object
in a
realm
realm
, given Web IDL type
and algorithms
setAlgorithm
and
deleteAlgorithm
Let
innerArray
be
ArrayCreate
(0).
Let
handler
be
OrdinaryObjectCreate
null
« [[Type]], [[SetAlgorithm]], [[DeleteAlgorithm]], [[BackingList]] »).
Set
handler
.[[Type]] to
Set
handler
.[[SetAlgorithm]] to
setAlgorithm
Set
handler
.[[DeleteAlgorithm]] to
deleteAlgorithm
Let
defineProperty
be
CreateBuiltinFunction
(the steps from
§ 3.10.1 defineProperty
, 3, "", « »,
realm
).
Perform
CreateDataPropertyOrThrow
handler
, "
defineProperty
",
defineProperty
).
Let
deleteProperty
be
CreateBuiltinFunction
(the steps from
§ 3.10.2 deleteProperty
, 2, "", « »,
realm
).
Perform
CreateDataPropertyOrThrow
handler
, "
deleteProperty
",
deleteProperty
).
Let
get
be
CreateBuiltinFunction
(the steps from
§ 3.10.3 get
, 3, "", « »,
realm
).
Perform
CreateDataPropertyOrThrow
handler
, "
get
",
get
).
Let
getOwnPropertyDescriptor
be
CreateBuiltinFunction
(the steps from
§ 3.10.4 getOwnPropertyDescriptor
, 2, "", « »,
realm
).
Perform
CreateDataPropertyOrThrow
handler
, "
getOwnPropertyDescriptor
",
getOwnPropertyDescriptor
).
Let
has
be
CreateBuiltinFunction
(the steps from
§ 3.10.5 has
, 2, "", « »,
realm
).
Perform
CreateDataPropertyOrThrow
handler
, "
has
",
has
).
Let
ownKeys
be
CreateBuiltinFunction
(the steps from
§ 3.10.6 ownKeys
, 1, "", « »,
realm
).
Perform
CreateDataPropertyOrThrow
handler
, "
ownKeys
",
ownKeys
).
Let
preventExtensions
be
CreateBuiltinFunction
(the steps from
§ 3.10.7 preventExtensions
, « », 0, "",
realm
).
Perform
CreateDataPropertyOrThrow
handler
, "
preventExtensions
",
preventExtensions
).
Let
set
be
CreateBuiltinFunction
(the steps from
§ 3.10.8 set
, « », 4, "",
realm
).
Perform
CreateDataPropertyOrThrow
handler
, "
set
",
set
).
Return
ProxyCreate
innerArray
handler
).
3.10.1.
defineProperty
The steps for the
defineProperty
proxy trap for
observable array exotic objects
, given
, and
descriptorObj
are as follows:
Let
handler
be the
this
value.
Let
descriptor
be
ToPropertyDescriptor
descriptorObj
).
If
is "length", then:
If
IsAccessorDescriptor
descriptor
) is
true
, then return
false
If
descriptor
.[[Configurable]] is present and has the value
true
then return
false
If
descriptor
.[[Enumerable]] is present and has the value
true
then return
false
If
descriptor
.[[Writable]] is present and has the value
false
then return
false
If
descriptor
.[[Value]] is present, then return the result of
setting the length
given
handler
and
descriptor
.[[Value]].
Return
true
If
is an array index
, then:
If
IsAccessorDescriptor
descriptor
) is
true
, then return
false
If
descriptor
.[[Configurable]] is present and has the value
false
then return
false
If
descriptor
.[[Enumerable]] is present and has the value
false
then return
false
If
descriptor
.[[Writable]] is present and has the value
false
then return
false
If
descriptor
.[[Value]] is present, then return the result of
setting the indexed value
given
handler
, and
descriptor
.[[Value]].
Return
true
Return
.[[DefineOwnProperty]](
descriptor
).
3.10.2.
deleteProperty
The steps for the
deleteProperty
proxy trap for
observable array exotic objects
, given
and
, are as follows:
Let
handler
be the
this
value.
If
is "length", then return
false
If
is an array index
, then:
Let
oldLen
be
handler
.[[BackingList]]'s
size
Let
index
be
ToUint32
).
If
index
oldLen
− 1, then return
false
Perform the algorithm steps given by
handler
.[[DeleteAlgorithm]], given
handler
.[[BackingList]][
index
] and
index
Remove
the last item from
handler
.[[BackingList]].
Return
true
Return
.[[Delete]](
).
3.10.3.
get
The steps for the
get
proxy trap for
observable array exotic objects
, given
, and
Receiver
, are as follows:
Let
handler
be the
this
value.
Let
length
be
handler
.[[BackingList]]'s
size
If
is "length", then return
length
If
is an array index
, then:
Let
index
be
ToUint32
).
If
index
length
, then return
undefined
Let
jsValue
be the result of
converting
handler
.[[BackingList]][
index
] to a JavaScript value.
Assert: the above step never throws an exception.
Return
jsValue
Return
.[[Get]](
Receiver
).
3.10.4.
getOwnPropertyDescriptor
The steps for the
getOwnPropertyDescriptor
proxy trap for
observable array exotic objects
, given
and
, are as follows:
Let
handler
be the
this
value.
Let
length
be
handler
.[[BackingList]]'s
size
If
is "length", then return
FromPropertyDescriptor
(PropertyDescriptor{[[Configurable]]:
false
[[Enumerable]]:
false
, [[Writable]]:
true
[[Value]]:
length
}).
If
is an array index
, then
Let
index
be
ToUint32
).
If
index
length
, then return
undefined
Let
jsValue
be the result of
converting
handler
.[[BackingList]][
index
] to a JavaScript value.
Assert: the above step never throws an exception.
Return
FromPropertyDescriptor
(PropertyDescriptor{[[Configurable]]:
true
, [[Enumerable]]:
true
, [[Writable]]:
true
, [[Value]]:
jsValue
}).
Return
FromPropertyDescriptor
.[[GetOwnProperty]](
)).
3.10.5.
has
The steps for the
has
proxy trap for
observable array exotic objects
, given
and
, are as follows:
Let
handler
be the
this
value.
If
is "length", then return
true
If
is an array index
, then:
Let
index
be
ToUint32
).
If
index
handler
.[[BackingList]]'s
size
, then return
true
Return
false
Return
.[[HasProperty]](
).
3.10.6.
ownKeys
The steps for the
ownKeys
proxy trap for
observable array exotic objects
, given
, are as follows:
Let
handler
be the
this
value.
Let
length
be
handler
.[[BackingList]]'s
size
Let
keys
be an empty
list
Let
be 0.
While
length
Append
ToString
) to
keys
Set
to
+ 1.
Extend
keys
with
.[[OwnPropertyKeys]]().
Return
CreateArrayFromList
keys
).
3.10.7.
preventExtensions
The steps for the
preventExtensions
proxy trap for
observable array exotic objects
are as follows:
Return
false
3.10.8.
set
The steps for the
set
proxy trap for
observable array exotic objects
, given
, and
Receiver
, are as follows:
Let
handler
be the
this
value.
If
is "length", then return the result of
setting the length
given
handler
and
If
is an array index
, then return the result of
setting the indexed value
given
handler
, and
Return
.[[Set]](
Receiver
).
3.10.9.
Abstract operations
To
set the length
of an observable array exotic object given
handler
and
newLen
Let
uint32Len
be
ToUint32
newLen
).
Let
numberLen
be
ToNumber
newLen
).
If
uint32Len
numberLen
, then throw a
RangeError
exception.
Let
oldLen
be
handler
.[[BackingList]]'s
size
If
uint32Len
oldLen
, then return
false
Let
indexToDelete
be
oldLen
− 1.
While
indexToDelete
uint32Len
Perform the algorithm steps given by
handler
.[[DeleteAlgorithm]], given
handler
.[[BackingList]][
indexToDelete
] and
indexToDelete
Remove
the last item from
handler
.[[BackingList]].
Set
indexToDelete
to
indexToDelete
− 1.
Return
true
To
set the indexed value
of an observable array exotic object given
handler
, and
Let
oldLen
be
handler
.[[BackingList]]'s
size
Let
index
be
ToUint32
).
If
index
oldLen
, return
false
Let
idlValue
be the result of
converting
to the type given by
handler
.[[Type]].
If
index
oldLen
, then:
Perform the algorithm steps given by
handler
.[[DeleteAlgorithm]], given
handler
.[[BackingList]][
index
] and
index
Perform the algorithm steps given by
handler
.[[SetAlgorithm]], given
idlValue
and
index
If
index
oldLen
, then
append
idlValue
to
handler
.[[BackingList]].
Otherwise, set
handler
.[[BackingList]][
index
] to
idlValue
Return
true
3.11.
Callback interfaces
As described in
§ 2.12 Objects implementing interfaces
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
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.
Web IDL arguments list
is a
list
of values each of which is either an IDL value or
the special value “missing”, which represents a missing optional argument.
To
convert a Web IDL arguments list to a
JavaScript arguments list
, given a
Web IDL arguments list
args
, perform the
following steps:
Let
jsArgs
be an empty
list
Let
be 0.
Let
count
be 0.
While
args
’s
size
If
args
] is the special value “missing”, then
append
undefined
to
jsArgs
Otherwise,
args
] is an IDL value:
Let
convertResult
be the result of
converting
args
] to a JavaScript value. Rethrow any exceptions.
Append
convertResult
to
jsArgs
Set
count
to
+ 1.
Set
to
+ 1.
Truncate
jsArgs
to contain
count
items.
Return
jsArgs
To
call a user object’s operation
given a
callback interface type
value
value
operation name
opName
Web IDL arguments list
args
, and optional
callback this value
thisArg
perform the following steps.
These steps will either return an IDL value or throw an exception.
Let
completion
be an uninitialized variable.
If
thisArg
was not given, let
thisArg
be
undefined
Let
be the JavaScript object corresponding to
value
Let
realm
be
’s
associated realm
Let
relevant settings
be
realm
’s
settings object
Let
stored settings
be
value
’s
callback context
Prepare to run script
with
relevant settings
Prepare to run a callback
with
stored settings
Let
be
If
IsCallable
) is false, then:
Let
getResult
be
Completion
Get
opName
)).
If
getResult
is an
abrupt completion
, set
completion
to
getResult
and jump to the step labeled
return
Set
to
getResult
.[[Value]].
If
IsCallable
) is
false
then set
completion
to
Completion Record
{ [[Type]]: throw, [[Value]]: a
newly created
TypeError
object, [[Target]]: empty }, and jump
to the step labeled
return
Set
thisArg
to
(overriding the provided value).
Let
jsArgs
be the result of
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
return
Let
callResult
be
Completion
Call
thisArg
jsArgs
)).
If
callResult
is an
abrupt completion
, set
completion
to
callResult
and jump to the step labeled
return
Set
completion
to the result of
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.
Return:
at this
point
completion
will be set to an IDL value or an
abrupt completion
Clean up after running a callback
with
stored settings
Clean up after running script
with
relevant settings
If
completion
is an IDL value, return
completion
If
completion
is an
abrupt completion
and the operation has a
return type
that is
not
promise type
, throw
completion
.[[Value]].
Let
rejectedPromise
be
Call
%Promise.reject%
%Promise%
, «
completion
.[[Value]]»).
Return the result of
converting
rejectedPromise
to the operation’s return type.
3.11.1.
Legacy callback interface object
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
global object
The name of the property is the
identifier
of the
callback interface
and its value is an object called the
legacy callback interface object
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
§ 3.7.5 Constants
Note:
Since a
legacy callback interface object
is a
function object
the
typeof
operator will return "function"
when applied to a
legacy callback interface object
The
legacy callback interface object
for a given
callback interface
interface
with
identifier
id
and in
realm
realm
is
created
as follows:
Let
steps
be the following steps:
Throw
TypeError
Let
be
CreateBuiltinFunction
steps
, 0,
id
, « »,
realm
).
Define the constants
of
interface
on
given
realm
Return
3.12.
Invoking callback functions
A JavaScript
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).
To
invoke
callback function type
value
callable
with a
Web IDL arguments list
args
exception behavior
exceptionBehavior
(either "
report
" or "
rethrow
"),
and an optional
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 "
rethrow
".
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 "
rethrow
".
Let
completion
be an uninitialized variable.
If
thisArg
was not given, let
thisArg
be
undefined
Let
be the JavaScript object corresponding to
callable
If
IsCallable
) is
false
Note:
This is only possible when the
callback function
came from an attribute
marked with [
LegacyTreatNonObjectAsNull
].
Return the result of
converting
undefined
to the callback function’s return type.
Let
realm
be
’s
associated realm
Let
relevant settings
be
realm
’s
settings object
Let
stored settings
be
callable
’s
callback context
Prepare to run script
with
relevant settings
Prepare to run a callback
with
stored settings
Let
jsArgs
be the result of
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
return
Let
callResult
be
Completion
Call
thisArg
jsArgs
)).
If
callResult
is an
abrupt completion
, set
completion
to
callResult
and jump to the step labeled
return
Set
completion
to the result of
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.
Return:
at this
point
completion
will be set to an IDL value or an
abrupt completion
Clean up after running a callback
with
stored settings
Clean up after running script
with
relevant settings
If
completion
is an IDL value, return
completion
Assert
completion
is an
abrupt completion
If
exceptionBehavior
is "
rethrow
", throw
completion
.[[Value]].
Otherwise, if
exceptionBehavior
is "
report
":
Assert
callable
’s
return type
is
undefined
or
any
Report an exception
completion
.[[Value]] for
realm
’s
global object
Return the unique
undefined
IDL value.
Assert
callable
’s
return type
is a
promise type
Let
rejectedPromise
be
Call
%Promise.reject%
%Promise%
, «
completion
.[[Value]]»).
Return the result of
converting
rejectedPromise
to the callback function’s return type.
Some callback functions are instead used as
constructors
. Such callback functions must not have
a return type that is a
promise type
To
construct
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.
Let
completion
be an uninitialized variable.
Let
be the JavaScript object corresponding to
callable
If
IsConstructor
) is
false
, throw a
TypeError
exception.
Let
realm
be
’s
associated realm
Let
relevant settings
be
realm
’s
settings object
Let
stored settings
be
callable
’s
callback context
Prepare to run script
with
relevant settings
Prepare to run a callback
with
stored settings
Let
jsArgs
be the result of
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
return
Let
callResult
be
Completion
Construct
jsArgs
)).
If
callResult
is an
abrupt completion
, set
completion
to
callResult
and jump to the step labeled
return
Set
completion
to the result of
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.
Return:
at this
point
completion
will be set to an IDL value or an
abrupt completion
Clean up after running a callback
with
stored settings
Clean up after running script
with
relevant settings
If
completion
is an
abrupt completion
, throw
completion
.[[Value]].
Return
completion
3.13.
Namespaces
For every
namespace
that is
exposed
in a given
realm
a corresponding property exists on the
realm
’s
global object
The name of the property is the
identifier
of the namespace, and its value is an object
called the
namespace object
The characteristics of a namespace object are described in
§ 3.13.1 Namespace object
3.13.1.
Namespace object
The namespace object for a given
namespace
namespace
and
realm
realm
is
created
as follows:
Let
namespaceObject
be
OrdinaryObjectCreate
realm
.[[Intrinsics]].[[
%Object.prototype%
]]).
Define the regular attributes
of
namespace
on
namespaceObject
given
realm
Define the regular operations
of
namespace
on
namespaceObject
given
realm
Define the constants
of
namespace
on
namespaceObject
given
realm
For each
exposed
interface
interface
which has the [
LegacyNamespace
] extended
attribute with the identifier of
namespace
as its argument,
Let
id
be
interface
’s
identifier
Let
interfaceObject
be the result of
creating an
interface object
for
interface
with
id
in
realm
Perform
DefineMethodProperty
namespaceObject
id
interfaceObject
, false).
Return
namespaceObject
The
class string
of a
namespace object
is the
namespace
’s
identifier
3.14.
Exceptions
3.14.1.
DOMException
custom bindings
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
stack
property),
it should also expose those on
DOMException
objects.
3.14.2.
Exception objects
Simple exceptions
are represented
by native JavaScript objects of the corresponding type.
DOMException
is represented by a
platform object
that implements the
DOMException
interface.
3.14.3.
Creating and throwing exceptions
To
create
simple exception
of type
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.
Let
args
be «
message
».
Let
constructor
be
current realm
.[[Intrinsics]].[[%
%]].
Return
Construct
constructor
args
).
To
create
DOMException
given a string
name
Assert:
name
appears in the
DOMException
names table
Let
ex
be a
new
DOMException
created in the
current realm
Set
ex
’s
name
to
name
Set
ex
’s
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.
Return
ex
To
create
DOMException
derived interface given the
interface
identifier
type
and additional initialization instructions:
Let
ex
be a
new
instance of the
interface
identified by
type
, created in the
current realm
Set
ex
’s
name
to
type
Set
ex
’s
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.
Perform any additional initialization on
ex
as described by the caller.
Return
ex
To
throw
an
exception
Let
be the result of
creating an exception
with the same
arguments.
Throw
The above algorithms restrict
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:
Exposed
Window
interface
MathUtils
// If x is negative, throws a "
NotSupportedError
DOMException
double
computeSquareRoot
double
);
};
If we apply
computeSquareRoot
to a
MathUtils
object from a different
realm
, then the exception thrown will be from the
realm
of the
method, not the object it is applied to:
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
);
catch
console
assert
instanceof
DOMException
));
console
assert
instanceof
otherWindow
DOMException
);
3.14.4.
Handling exceptions
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
Document conventions
, an algorithm specified in this document may intercept thrown exceptions, either by specifying
the exact steps to take if
an exception was thrown
, or by explicitly handling
abrupt completions
The following
IDL fragment
defines two
interfaces
and an
exception
The
valueOf
attribute on
ExceptionThrower
is defined to throw an exception whenever an attempt is made
to get its value.
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
};
Assuming a JavaScript implementation supporting this interface,
the following code demonstrates how exceptions are handled:
var
getDahut
();
// Obtain an instance of Dahut.
var
et
getExceptionThrower
();
// Obtain an instance of ExceptionThrower.
try
type
toString
function
()
throw
"abc"
};
catch
// 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
type
toString
};
catch
// 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
type
Symbol
();
catch
// An exception is caught here, since an attempt is made to invoke
// the JavaScript ToString abstract operation on a Symbol value.
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.
4.
Common definitions
This section specifies some common definitions that all
conforming implementations
must support.
4.1.
ArrayBufferView
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
The
ArrayBufferView
typedef is used to represent
objects that provide a view on to an
ArrayBuffer
or
SharedArrayBuffer
(when [
AllowShared
] is used).
4.2.
BufferSource
typedef
ArrayBufferView
or
ArrayBuffer
BufferSource
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.
4.3.
AllowSharedBufferSource
typedef
ArrayBuffer
or
SharedArrayBuffer
or
AllowShared
ArrayBufferView
AllowSharedBufferSource
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
4.4.
DOMException
The
DOMException
type is an
interface type
defined by the following IDL
fragment:
[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;
};
Note:
as discussed in
§ 3.14.1 DOMException custom bindings
, the JavaScript binding imposes additional
requirements beyond the normal ones for
interface types
Each
DOMException
object has an associated
name
and
message
, both
strings
The
new DOMException(
message
name
constructor steps are:
Set
this
’s
name
to
name
Set
this
’s
message
to
message
The
name
getter steps are to return
this
’s
name
The
message
getter steps are to
return
this
’s
message
The
code
getter steps are to return the legacy
code indicated in the
DOMException
names table
for
this
’s
name
, or 0 if no such entry exists in the table.
DOMException
objects are
serializable objects
Their
serialization steps
, given
value
and
serialized
, are:
Set
serialized
.[[Name]] to
value
’s
name
Set
serialized
.[[Message]] to
value
’s
message
User agents should attach a serialized representation of any interesting accompanying data
which are not yet specified, notably the
stack
property, to
serialized
Their
deserialization steps
, given
value
and
serialized
, are:
Set
value
’s
name
to
serialized
.[[Name]].
Set
value
’s
message
to
serialized
.[[Message]].
If any other data is attached to
serialized
, then deserialize and attach it to
value
4.5.
Function
callback
Function
any
any
...
arguments
);
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.
4.6.
VoidFunction
callback
VoidFunction
undefined
();
The
VoidFunction
callback function
type is used for representing function values that take no arguments and do not
return any value.
5.
Extensibility
This section is informative.
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
Web IDL
, which
at the time of writing is the
W3C Web Platform Working Group
for possible inclusion in a future version of this document.
Extensions to any other aspect of the IDL language are
strongly discouraged.
6.
Legacy constructs
This section is informative.
Legacy Web IDL constructs exist only so that
legacy Web platform features can be specified.
They are generally prefixed with the "
Legacy
" 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
filing an issue
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.
7.
Referencing this specification
This section is informative.
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:
The IDL fragment in Appendix A of this specification must, in
conjunction with the IDL fragments defined in this specification’s normative references,
be interpreted as required for
conforming sets of IDL fragments
, as described in the
“Web IDL” specification. [WEBIDL]
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:
A conforming FooML user agent must also be a
conforming implementation
of the IDL fragment in Appendix A
of this specification, as described in the
“Web IDL” specification. [WEBIDL]
8.
Privacy and Security Considerations
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.
Acknowledgments
This section is informative.
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 (
Mozilla
echen@mozilla.com
) and Tiancheng "Timothy" Gu
timothygu99@gmail.com
) with substantial contributions from
Boris Zbarsky (
bzbarsky@mit.edu
),
Cameron McCormack
cam@mcc.id.au
),
and
Tobie Langel
tobie@unlockopen.com
).
IDL grammar
This section defines an LL(1) grammar whose start symbol,
Definitions
, 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:
integer
-?([1-9][0-9]*|0[Xx][0-9A-Fa-f]+|0[0-7]*)
decimal
-?(([0-9]+\.[0-9]*|[0-9]*\.[0-9]+)([Ee][+-]?[0-9]+)?|[0-9]+[Ee][+-]?[0-9]+)
identifier
[_-]?[A-Za-z][0-9A-Z_a-z-]*
string
"[^"]*"
whitespace
[\t\n\r ]+
comment
/.*|
/\*(.|\n)*?\*
other
[^\t\n\r 0-9A-Za-z]
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 “
a1
”, it is tokenized as a single
identifier
and not as a separate
identifier
and
integer
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 “
long
” is tokenized as the terminal symbol
long
rather than an
identifier
called "
long
",
and “
” is tokenized as the terminal symbol
rather than an
other
The IDL syntax is case sensitive, both for the monospaced terminal symbols
used in the grammar and the values used for
identifier
terminals. Thus, for
example, the input text “
Const
” is tokenized as
an
identifier
rather than the
terminal symbol
const
, an
interface
with
identifier
" is distinct from one named "
", and an
extended attribute
legacyfactoryfunction
] will not be recognized as
the [
LegacyFactoryFunction
extended attribute.
Implicitly, any number of
whitespace
and
comment
terminals are allowed between every other terminal
in the input text being parsed. Such
whitespace
and
comment
terminals are ignored while parsing.
The following LL(1) grammar, starting with
Definitions
matches an
IDL fragment
Definitions
::
ExtendedAttributeList
Definition
Definitions
Definition
::
CallbackOrInterfaceOrMixin
Namespace
Partial
Dictionary
Enum
Typedef
IncludesStatement
ArgumentNameKeyword
::
attribute
callback
const
constructor
deleter
dictionary
enum
getter
includes
inherit
interface
iterable
maplike
mixin
namespace
partial
readonly
required
setlike
setter
static
stringifier
typedef
unrestricted
CallbackOrInterfaceOrMixin
::
callback
CallbackRestOrInterface
interface
InterfaceOrMixin
InterfaceOrMixin
::
InterfaceRest
MixinRest
InterfaceRest
::
identifier
Inheritance
InterfaceMembers
Partial
::
partial
PartialDefinition
PartialDefinition
::
interface
PartialInterfaceOrPartialMixin
PartialDictionary
Namespace
PartialInterfaceOrPartialMixin
::
PartialInterfaceRest
MixinRest
PartialInterfaceRest
::
identifier
PartialInterfaceMembers
InterfaceMembers
::
ExtendedAttributeList
InterfaceMember
InterfaceMembers
InterfaceMember
::
PartialInterfaceMember
Constructor
PartialInterfaceMembers
::
ExtendedAttributeList
PartialInterfaceMember
PartialInterfaceMembers
PartialInterfaceMember
::
Const
Operation
Stringifier
StaticMember
Iterable
AsyncIterable
ReadOnlyMember
ReadWriteAttribute
ReadWriteMaplike
ReadWriteSetlike
InheritAttribute
Inheritance
::
identifier
MixinRest
::
mixin
identifier
MixinMembers
MixinMembers
::
ExtendedAttributeList
MixinMember
MixinMembers
MixinMember
::
Const
RegularOperation
Stringifier
OptionalReadOnly
AttributeRest
IncludesStatement
::
identifier
includes
identifier
CallbackRestOrInterface
::
CallbackRest
interface
identifier
CallbackInterfaceMembers
CallbackInterfaceMembers
::
ExtendedAttributeList
CallbackInterfaceMember
CallbackInterfaceMembers
CallbackInterfaceMember
::
Const
RegularOperation
Const
::
const
ConstType
identifier
ConstValue
ConstValue
::
BooleanLiteral
FloatLiteral
integer
BooleanLiteral
::
true
false
FloatLiteral
::
decimal
-Infinity
Infinity
NaN
ConstType
::
PrimitiveType
identifier
ReadOnlyMember
::
readonly
ReadOnlyMemberRest
ReadOnlyMemberRest
::
AttributeRest
MaplikeRest
SetlikeRest
ReadWriteAttribute
::
AttributeRest
InheritAttribute
::
inherit
AttributeRest
AttributeRest
::
attribute
TypeWithExtendedAttributes
AttributeName
AttributeName
::
AttributeNameKeyword
identifier
AttributeNameKeyword
::
required
OptionalReadOnly
::
readonly
DefaultValue
::
ConstValue
string
null
undefined
Operation
::
RegularOperation
SpecialOperation
RegularOperation
::
Type
OperationRest
SpecialOperation
::
Special
RegularOperation
Special
::
getter
setter
deleter
OperationRest
::
OptionalOperationName
ArgumentList
OptionalOperationName
::
OperationName
OperationName
::
OperationNameKeyword
identifier
OperationNameKeyword
::
includes
ArgumentList
::
Argument
Arguments
Arguments
::
Argument
Arguments
Argument
::
ExtendedAttributeList
ArgumentRest
ArgumentRest
::
optional
TypeWithExtendedAttributes
ArgumentName
Default
Type
Ellipsis
ArgumentName
ArgumentName
::
ArgumentNameKeyword
identifier
Ellipsis
::
...
Constructor
::
constructor
ArgumentList
Stringifier
::
stringifier
StringifierRest
StringifierRest
::
OptionalReadOnly
AttributeRest
StaticMember
::
static
StaticMemberRest
StaticMemberRest
::
OptionalReadOnly
AttributeRest
RegularOperation
Iterable
::
iterable
TypeWithExtendedAttributes
OptionalType
OptionalType
::
TypeWithExtendedAttributes
AsyncIterable
::
async_iterable
TypeWithExtendedAttributes
OptionalType
OptionalArgumentList
OptionalArgumentList
::
ArgumentList
ReadWriteMaplike
::
MaplikeRest
MaplikeRest
::
maplike
TypeWithExtendedAttributes
TypeWithExtendedAttributes
ReadWriteSetlike
::
SetlikeRest
SetlikeRest
::
setlike
TypeWithExtendedAttributes
Namespace
::
namespace
identifier
NamespaceMembers
NamespaceMembers
::
ExtendedAttributeList
NamespaceMember
NamespaceMembers
NamespaceMember
::
RegularOperation
readonly
AttributeRest
Const
Dictionary
::
dictionary
identifier
Inheritance
DictionaryMembers
DictionaryMembers
::
DictionaryMember
DictionaryMembers
DictionaryMember
::
ExtendedAttributeList
DictionaryMemberRest
DictionaryMemberRest
::
required
TypeWithExtendedAttributes
identifier
Type
identifier
Default
PartialDictionary
::
dictionary
identifier
DictionaryMembers
Default
::
DefaultValue
Enum
::
enum
identifier
EnumValueList
EnumValueList
::
string
EnumValueListComma
EnumValueListComma
::
EnumValueListString
EnumValueListString
::
string
EnumValueListComma
CallbackRest
::
identifier
Type
ArgumentList
Typedef
::
typedef
TypeWithExtendedAttributes
identifier
Type
::
SingleType
UnionType
Null
TypeWithExtendedAttributes
::
ExtendedAttributeList
Type
SingleType
::
DistinguishableType
any
PromiseType
UnionType
::
UnionMemberType
or
UnionMemberType
UnionMemberTypes
UnionMemberType
::
ExtendedAttributeList
DistinguishableType
UnionType
Null
UnionMemberTypes
::
or
UnionMemberType
UnionMemberTypes
DistinguishableType
::
PrimitiveType
Null
StringType
Null
identifier
Null
sequence
TypeWithExtendedAttributes
Null
async_sequence
TypeWithExtendedAttributes
Null
object
Null
symbol
Null
BufferRelatedType
Null
FrozenArray
TypeWithExtendedAttributes
Null
ObservableArray
TypeWithExtendedAttributes
Null
RecordType
Null
undefined
Null
PrimitiveType
::
UnsignedIntegerType
UnrestrictedFloatType
boolean
byte
octet
bigint
UnrestrictedFloatType
::
unrestricted
FloatType
FloatType
FloatType
::
float
double
UnsignedIntegerType
::
unsigned
IntegerType
IntegerType
IntegerType
::
short
long
OptionalLong
OptionalLong
::
long
StringType
::
ByteString
DOMString
USVString
PromiseType
::
Promise
Type
RecordType
::
record
StringType
TypeWithExtendedAttributes
Null
::
BufferRelatedType
::
ArrayBuffer
SharedArrayBuffer
DataView
Int8Array
Int16Array
Int32Array
Uint8Array
Uint16Array
Uint32Array
Uint8ClampedArray
BigInt64Array
BigUint64Array
Float16Array
Float32Array
Float64Array
ExtendedAttributeList
::
ExtendedAttribute
ExtendedAttributes
ExtendedAttributes
::
ExtendedAttribute
ExtendedAttributes
ExtendedAttribute
::
ExtendedAttributeInner
ExtendedAttributeRest
ExtendedAttributeInner
ExtendedAttributeRest
ExtendedAttributeInner
ExtendedAttributeRest
Other
ExtendedAttributeRest
ExtendedAttributeRest
::
ExtendedAttribute
ExtendedAttributeInner
::
ExtendedAttributeInner
ExtendedAttributeInner
ExtendedAttributeInner
ExtendedAttributeInner
ExtendedAttributeInner
ExtendedAttributeInner
OtherOrComma
ExtendedAttributeInner
Other
::
integer
decimal
identifier
string
other
-Infinity
...
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
OtherOrComma
::
Other
IdentifierList
::
identifier
Identifiers
Identifiers
::
identifier
Identifiers
IntegerList
::
integer
Integers
Integers
::
integer
Integers
ExtendedAttributeNoArgs
::
identifier
ExtendedAttributeArgList
::
identifier
ArgumentList
ExtendedAttributeIdent
::
identifier
identifier
ExtendedAttributeString
::
identifier
string
ExtendedAttributeInteger
::
identifier
integer
ExtendedAttributeDecimal
::
identifier
decimal
ExtendedAttributeWildcard
::
identifier
ExtendedAttributeIdentList
::
identifier
IdentifierList
ExtendedAttributeIntegerList
::
identifier
IntegerList
ExtendedAttributeNamedArgList
::
identifier
identifier
ArgumentList
Note:
The
Other
non-terminal matches any single terminal symbol except for
and
While the
ExtendedAttribute
non-terminal matches any non-empty sequence of terminal symbols (as long as any
parentheses, square brackets or braces are balanced, and the
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
§ 2.14 Extended attributes
for the syntaxes that are used by these extended attributes.
Document conventions
The following typographic conventions are used in this document:
Defining instances of terms:
example term
Links to terms defined in this document or elsewhere:
example term
Grammar terminals:
sometoken
Grammar non-terminals:
ExampleGrammarNonTerminal
Grammar symbols:
identifier
IDL types:
unsigned long
JavaScript classes:
Map
JavaScript language types: Object
Code snippets:
a = b + obj.f()
Scalar values: U+0030 (0)
Extended attributes: [
ExampleExtendedAttribute
Variable names in prose and algorithms:
exampleVariableName
IDL informal syntax examples:
extended_attributes
interface
identifier
/* interface_members... */
};
(Specific parts of the syntax discussed in surrounding prose are
highlighted
.)
IDL grammar snippets:
ExampleGrammarNonTerminal
::
OtherNonTerminal
sometoken
other
AnotherNonTerminal
ε //
nothing
Non-normative notes:
Note:
This is a note.
Non-normative examples:
This is an example.
Normative warnings:
This is a warning.
Code blocks:
// This is an IDL code block.
Exposed
Window
interface
Example
attribute
long
something
};
// This is a JavaScript code block.
window
onload
function
()
window
alert
"loaded"
);
};
The following conventions are used in the algorithms in this document:
Algorithms use the
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.
Conformance
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:
conforming set of IDL fragments
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.
conforming implementation
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.
conforming JavaScript implementation
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.
Intellectual property rights
This Living Standard includes material copied from W3C’s
WebIDL [sic] Level 1
which is available under the
W3C Software and Document License
Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a
Creative Commons Attribution 4.0
International License
. To the extent portions of it are incorporated into source code, such
portions in the source code are licensed under the
BSD 3-Clause License
instead.
This is the Living Standard. Those
interested in the patent-review version should view the
Living Standard Review Draft
Index
Terms defined by this specification
ABORT_ERR
, in § 2.8.1
AbortError
, in § 2.8.1
AllowResizable
, in § 3.3
AllowShared
, in § 3.3.1
AllowSharedBufferSource
, in § 4.2
a new promise
, in § 3.2.24.1
an exception was thrown
, in § 3.14.4
annotated types
, in § 2.13.33
any
, in § 2.13
applicable to types
, in § 2.13.33
a promise rejected with
, in § 3.2.24.1
a promise resolved with
, in § 3.2.24.1
ArrayBuffer
, in § 2.13.34
ArrayBufferView
, in § 4
associated realm
, in § 3.1
asynchronous iterator initialization steps
, in § 2.5.10
asynchronous iterator prototype object
, in § 3.7.10.2
asynchronous iterator return
, in § 2.5.10
asynchronously iterable declaration
, in § 2.5.10
async_iterable
, in § 2.5.10
async iterator
, in § 3.2.22.1
async sequence
, in § 2.13.28
async_sequence
, in § 2.13.28
async sequence type
, in § 2.13.29
attribute
, in § 2.5.2
attribute getter
, in § 3.7.6
attribute setter
, in § 3.7.6
backing list
, in § 2.13.36
backing observable array exotic object
, in § 3.2.28
bigint
, in § 2.13.15
BigInt64Array
, in § 2.13.34
BigUint64Array
, in § 2.13.34
boolean
, in § 2.13.2
BufferSource
, in § 4.1
buffer source types
, in § 2.13
buffer types
, in § 2.13
buffer view types
, in § 2.13
byte
, in § 2.13.3
byte length
, in § 3.2.26
ByteString
, in § 2.13.17
callable
, in § 2.5.8
call a user object’s operation
, in § 3.11
callback context
, in § 2.13.23
callback function
, in § 2.10
Callback function types
, in § 2.13.25
callback interface
, in § 2.4
callback interface member
, in § 2.4
Callback interface types
, in § 2.13.22
callback this value
, in § 3.11
change
, in § 3.8
Clamp
, in § 3.3.2
class string
, in § 3
close an async iterator
, in § 3.2.22.1
code
, in § 4.4
collect attribute values
, in § 3.7.7.1.1
collect attribute values of an inheritance stack
, in § 3.7.7.1.1
compute the effective overload set
, in § 2.5.8
conditionally exposed
, in § 3.3.7
conforming implementation
, in § Unnumbered section
conforming JavaScript implementation
, in § Unnumbered section
conforming set of IDL fragments
, in § Unnumbered section
constant
, in § 2.5.1
ConstraintError
, in § 2.8.1
construct
, in § 3.12
constructor()
constructor for DOMException
, in § 4.4
constructor for QuotaExceededError
, in § 2.8.3
constructor(message)
constructor for DOMException
, in § 4.4
constructor for QuotaExceededError
, in § 2.8.3
constructor(message, name)
, in § 4.4
constructor(message, options)
, in § 2.8.3
Constructor operations
, in § 2.5.3.1
constructor steps
, in § 2.5.4
converted to a JavaScript value
, in § 3.2
converted to an ECMAScript value
, in § 3.2
converted to an IDL value
, in § 3.2
converted to a numeric type or bigint
, in § 3.2.9
converted to ECMAScript values
, in § 3.2
converted to IDL values
, in § 3.2
converted to JavaScript values
, in § 3.2
converting
, in § 3.11
converting arguments for an asynchronous iterator method
, in § 3.7.10
ConvertToInt
, in § 3.2.4.9
create
dfn for ArrayBuffer
, in § 3.2.26
dfn for ArrayBufferView
, in § 3.2.26
dfn for SharedArrayBuffer
, in § 3.2.26
dfn for exception
, in § 2.8
create a frozen array
, in § 3.2.27
create a legacy callback interface object
, in § 3.11.1
create a legacy factory function
, in § 3.7.2
create a map iterator
, in § 3.7.11.2
create a named properties object
, in § 3.7.4
create a namespace object
, in § 3.13.1
create an inheritance stack
, in § 3.7.7.1.1
create an interface object
, in § 3.7.1
create an interface prototype object
, in § 3.7.3
create a set iterator
, in § 3.7.12.2
creating a frozen array
, in § 3.2.27
Creating a frozen array from an iterable
, in § 3.2.27
creating an observable array exotic object
, in § 3.10
creating an operation function
, in § 3.7.7
Creating a sequence from an iterable
, in § 3.2.21
CrossOriginIsolated
, in § 3.3.3
current state
, in § 2.5.10
DATA_CLONE_ERR
, in § 2.8.1
DataCloneError
, in § 2.8.1
DataError
, in § 2.8.1
DataView
, in § 2.13.34
Default
, in § 3.3.4
default asynchronous iterator object
, in § 3.7.10.1
default iterator object
, in § 3.7.9.1
default method steps
, in § 3.7.7.1
default toJSON steps
, in § 3.7.7.1.1
default value
dfn for dictionary member
, in § 2.7
dfn for optional argument
, in § 2.5.3
define the asynchronous iteration methods
, in § 3.7.10
define the attributes
, in § 3.7.6
define the constants
, in § 3.7.5
define the global property references
, in § 3.8
define the iteration methods
, in § 3.7.9
define the operations
, in § 3.7.7
define the regular attributes
, in § 3.7.6
define the regular operations
, in § 3.7.7
define the static attributes
, in § 3.7.6
define the static operations
, in § 3.7.7
define the unforgeable regular attributes
, in § 3.7.6
define the unforgeable regular operations
, in § 3.7.7
definitions
, in § 2
delete an existing named property
, in § 2.5.6.2
delete an indexed value
, in § 2.13.36
deleter
, in § 2.5.6
detach
, in § 3.2.26
detached
, in § 3.2.26
determine the value of a named property
, in § 2.5.6.2
determine the value of an indexed property
, in § 2.5.6.1
dictionary
, in § 2.7
dictionary members
, in § 2.7
Dictionary types
, in § 2.13.23
distinguishable
, in § 2.5.8
distinguishing argument index
, in § 2.5.8
DOMException
, in § 4.3
DOMException()
, in § 4.4
DOMException(message)
, in § 4.4
DOMException(message, name)
, in § 4.4
DOMException names table
, in § 2.8.1
DOMString
, in § 2.13.16
DOMSTRING_SIZE_ERR
, in § 4.4
double
, in § 2.13.13
ECMAScript throw
, in § 3
effective overload set
, in § 2.5.8
EncodingError
, in § 2.8.1
end of iteration
, in § 2.5.10
EnforceRange
, in § 3.3.5
enumeration
, in § 2.9
enumeration’s values
, in § 2.9
Enumeration types
, in § 2.13.24
enumeration value
, in § 2.9
EvalError
, in § 2.8
example term
, in § Unnumbered section
exception
, in § 2.8
Exception objects
, in § 3.14.1
Exposed
, in § 3.3.6
exposed
, in § 3.3.7
exposure set
, in § 3.3.7
exposure set intersection
, in § 3.3.7
extended attribute
, in § 2.14
extended attribute associated with
, in § 2.13.33
extended attributes associated with
, in § 2.13.33
flattened member types
, in § 2.13.32
float
, in § 2.13.11
Float16Array
, in § 2.13.34
Float32Array
, in § 2.13.34
Float64Array
, in § 2.13.34
FrozenArray
, in § 2.13.34
FrozenArray
, in § 2.13.34
frozen array type
, in § 2.13.35
Function
, in § 4.4
get a copy of the buffer source
, in § 3.2.26
get a copy of the bytes held by the buffer source
, in § 3.2.26
get an async iterator next value
, in § 3.2.22.1
get a promise to wait for all
, in § 3.2.24.1
GetOwnProperty
, in § 3.9
getter
, in § 2.5.6
getter steps
, in § 2.5.2
get the next iteration result
, in § 2.5.10
getting a promise to wait for all
, in § 3.2.24.1
Global
, in § 3.3.7
global names
, in § 3.3.8
has default method steps
, in § 3.7.7.1
have default method steps
, in § 3.7.7.1
HIERARCHY_REQUEST_ERR
, in § 2.8.1
HierarchyRequestError
, in § 2.8.1
host interfaces
, in § 2.3
identifier
, in § 2.1
IDL fragment
, in § 2
implementation check
, in § 3.7
implementation-check
, in § 3.7
implementation-check an object
, in § 3.7
implements
, in § 3.8
include
, in § 2.3
includes a nullable type
, in § 2.13.32
includes statement
, in § 2.3
includes undefined
, in § 2.13.32
inclusive inherited interfaces
, in § 2.2
index
, in § 3.7.9.1
Indexed properties
, in § 2.5.6
indexed property getter
, in § 2.5.6
indexed property setter
, in § 2.5.6
INDEX_SIZE_ERR
, in § 2.8.1
IndexSizeError
, in § 2.8.1
inherit
dfn for dictionary
, in § 2.7
dfn for interface
, in § 2.2
inherited dictionaries
, in § 2.7
inherited interfaces
, in § 2.2
inherit its getter
, in § 2.5.2
initial objects
, in § 3.1
inner type
dfn for annotated types
, in § 2.13.33
dfn for nullable types
, in § 2.13.27
Int16Array
, in § 2.13.34
Int32Array
, in § 2.13.34
Int8Array
, in § 2.13.34
IntegerPart
, in § 3.2.4.9
integer types
, in § 2.13
interface
, in § 2.2
interface member
, in § 2.2
interface mixin
, in § 2.3
interface mixin member
, in § 2.3
interface object
, in § 3.7
interface prototype object
, in § 3.7.3
Interface types
, in § 2.13.21
internally create a new object implementing the interface
, in § 3.8
INUSE_ATTRIBUTE_ERR
, in § 2.8.1
InUseAttributeError
, in § 2.8.1
INVALID_ACCESS_ERR
, in § 2.8.1
InvalidAccessError
, in § 2.8.1
INVALID_CHARACTER_ERR
, in § 2.8.1
InvalidCharacterError
, in § 2.8.1
INVALID_MODIFICATION_ERR
, in § 2.8.1
InvalidModificationError
, in § 2.8.1
INVALID_NODE_TYPE_ERR
, in § 2.8.1
InvalidNodeTypeError
, in § 2.8.1
INVALID_STATE_ERR
, in § 2.8.1
InvalidStateError
, in § 2.8.1
invoke
, in § 3.12
invoke the indexed property setter
, in § 3.9.7
invoke the named property setter
, in § 3.9.7
is an array index
, in § 3.9.7
is a platform object
, in § 3.8
is finished
, in § 3.7.10.1
is global prototype chain mutable
, in § 3.3.8
is not an array index
, in § 3.9.7
iterable
, in § 2.5.9
iterable declaration
, in § 2.5.9
iterator prototype object
, in § 3.7.9.2
iterator result
, in § 3.7.9.2
JavaScript throw
, in § 3
JSON type
, in § 2.5.3.1
key
, in § 2.5.9
kind
dfn for default asynchronous iterator object
, in § 3.7.10.1
dfn for default iterator object
, in § 3.7.9.1
legacy callback interface object
, in § 3.11.1
legacy factory function
, in § 3.7
LegacyFactoryFunction
, in § 3.4
LegacyFactoryFunction identifier
, in § 3.4.1
LegacyLenientSetter
, in § 3.4.1
LegacyLenientThis
, in § 3.4.2
LegacyNamespace
, in § 3.4.3
LegacyNoInterfaceObject
, in § 3.4.4
LegacyNullToEmptyString
, in § 3.4.5
LegacyOverrideBuiltIns
, in § 3.4.6
LegacyPlatformObjectGetOwnProperty
, in § 3.9.7
Legacy platform objects
, in § 2.12
LegacyTreatNonObjectAsNull
, in § 3.4.7
LegacyUnenumerableNamedProperties
, in § 3.4.8
LegacyUnforgeable
, in § 3.4.9
LegacyWindowAlias
, in § 3.4.10
LegacyWindowAlias identifier
, in § 3.4.11
long
, in § 2.13.7
long long
, in § 2.13.9
map entries
, in § 2.5.11
maplike
, in § 2.5.11
maplike declaration
, in § 2.5.11
map size getter
, in § 3.7.11.1
mark a promise as handled
, in § 3.2.24.1
mark as handled
, in § 3.2.24.1
members
, in § 2.5
member types
, in § 2.13.32
message
attribute for DOMException
, in § 4.4
dfn for DOMException
, in § 4.4
method
, in § 3.2.22
method steps
, in § 2.5.3
name
attribute for DOMException
, in § 4.4
dfn for DOMException
, in § 4.4
named definition
, in § 2.1
Named properties
, in § 2.5.6.1
named properties object
, in § 3.7.4
named property deleter
, in § 2.5.6
named property getter
, in § 2.5.6
named property setter
, in § 2.5.6
named property visibility algorithm
, in § 3.9.7
namespace
, in § 2.6
NAMESPACE_ERR
, in § 2.8.1
NamespaceError
, in § 2.8.1
namespace member
, in § 2.6
namespace object
, in § 3.13
NETWORK_ERR
, in § 2.8.1
NetworkError
, in § 2.8.1
new
, in § 3.8
NewObject
, in § 3.3.8
NO_DATA_ALLOWED_ERR
, in § 4.4
NO_MODIFICATION_ALLOWED_ERR
, in § 2.8.1
NoModificationAllowedError
, in § 2.8.1
NotAllowedError
, in § 2.8.1
NOT_FOUND_ERR
, in § 2.8.1
NotFoundError
, in § 2.8.1
NotReadableError
, in § 2.8.1
NOT_SUPPORTED_ERR
, in § 2.8.1
NotSupportedError
, in § 2.8.1
nullable type
, in § 2.13.27
number of nullable member types
, in § 2.13.32
numeric types
, in § 2.13
object
(interface)
, in § 2.13.19
dfn for JS async sequence
, in § 3.2.22
object types
, in § 2.13
ObservableArray
, in § 2.13.35
observable array exotic object
, in § 3.10
ObservableArray
, in § 2.13.35
observable array type
, in § 2.13.36
octet
, in § 2.13.4
ongoing promise
, in § 3.7.10.1
open an async sequence
, in § 3.2.22.1
operation
, in § 2.5.3
OperationError
, in § 2.8.1
optional
, in § 2.7
optional argument
, in § 2.5.3
optionality list
, in § 2.5.8
optionality values
, in § 2.5.8
OptOutError
, in § 2.8.1
overloaded
, in § 2.5.8
overload resolution algorithm
, in § 3.6
overridden constructor steps
, in § 3.7.1
own exposure set
, in § 3.3.7
pair asynchronously iterable declaration
, in § 2.5.10
pair iterator
, in § 2.5.9
partial dictionary
, in § 2.7
partial interface
, in § 2.2
partial interface mixin
, in § 2.3
partial namespace
, in § 2.6
perform a security check
, in § 3.5
platform object
, in § 2.12
primary interface
, in § 3.8
primitive types
, in § 2.13
Promise
, in § 2.13.30
Promise
, in § 2.13.30
promise type
, in § 2.13.31
PutForwards
, in § 3.3.9
qualified name
, in § 2.2
quota
attribute for QuotaExceededError
, in § 2.8.3
dfn for QuotaExceededError
, in § 2.8.3
dict-member for QuotaExceededErrorOptions
, in § 2.8.3
QUOTA_EXCEEDED_ERR
, in § 2.8.1
QuotaExceededError
, in § 2.8.3
QuotaExceededError()
, in § 2.8.3
QuotaExceededError(message)
, in § 2.8.3
QuotaExceededError(message, options)
, in § 2.8.3
QuotaExceededErrorOptions
, in § 2.8.3
RangeError
, in § 2.8
react
, in § 3.2.24.1
reacting
, in § 3.2.24.1
read only
, in § 2.5.2
ReadOnlyError
, in § 2.8.1
ready promise
, in § 3.2.24.2
record
, in § 2.13.29
record type
, in § 2.13.30
ReferenceError
, in § 2.8
regular attribute
, in § 2.5.2
regular operation
, in § 2.5.3
reject
, in § 3.2.24.1
Replaceable
, in § 3.3.10
requested
attribute for QuotaExceededError
, in § 2.8.3
dfn for QuotaExceededError
, in § 2.8.3
dict-member for QuotaExceededErrorOptions
, in § 2.8.3
required
, in § 2.7
reserved identifiers
, in § 2.1
resolve
, in § 3.2.24.1
return type
, in § 2.5.3
SameObject
, in § 3.3.11
SecureContext
, in § 3.3.12
SECURITY_ERR
, in § 2.8.1
SecurityError
, in § 2.8.1
sequence
, in § 2.13.27
sequence type
, in § 2.13.28
set an indexed value
, in § 2.13.36
set entries
, in § 2.5.12
setlike
, in § 2.5.12
setlike declaration
, in § 2.5.12
set size getter
, in § 3.7.12.1
setter
, in § 2.5.6
setter steps
, in § 2.5.2
set the indexed value
, in § 3.10.9
set the length
, in § 3.10.9
set the value of a new indexed property
, in § 2.5.6.1
set the value of a new named property
, in § 2.5.6.2
set the value of an existing indexed property
, in § 2.5.6.1
set the value of an existing named property
, in § 2.5.6.2
setting the indexed value
, in § 3.10.9
setting the length
, in § 3.10.9
SharedArrayBuffer
, in § 2.13.34
short
, in § 2.13.5
simple exception
, in § 2.8
special keyword
, in § 2.5.6
special operation
, in § 2.5.6
specific type
, in § 2.13.1
startingOffset
dfn for ArrayBuffer/write, SharedArrayBuffer/write
, in § 3.2.26
dfn for ArrayBufferView/write
, in § 3.2.26
Static attributes
, in § 2.5.7
static operations
, in § 2.5.7
stringification behavior
, in § 2.5.5
stringifier
, in § 2.5.5
string types
, in § 2.13
supported property indices
, in § 2.5.6.1
supported property names
, in § 2.5.6.2
support indexed properties
, in § 2.5.6.1
support named properties
, in § 2.5.6.2
symbol
, in § 2.13.20
SYNTAX_ERR
, in § 2.8.1
SyntaxError
, in § 2.8.1
takes a decimal
, in § 2.14
takes a named argument list
, in § 2.14
takes an argument list
, in § 2.14
takes an identifier
, in § 2.14
takes an identifier list
, in § 2.14
takes an integer
, in § 2.14
takes an integer list
, in § 2.14
takes a string
, in § 2.14
takes a wildcard
, in § 2.14
takes no arguments
, in § 2.14
target
dfn for default asynchronous iterator object
, in § 3.7.10.1
dfn for default iterator object
, in § 3.7.9.1
the given value
, in § 2.5
this
, in § 2.5
throw
dfn for JavaScript
, in § 3
dfn for exception
, in § 2.8
TIMEOUT_ERR
, in § 2.8.1
TimeoutError
, in § 2.8.1
TransactionInactiveError
, in § 2.8.1
transfer
, in § 3.2.26
transferable
, in § 3.2.26
type
, in § 3.2.22
type being given a new name
, in § 2.11
typed array types
, in § 2.13
typedef
, in § 2.11
TypeError
, in § 2.8
type list
, in § 2.5.8
TYPE_MISMATCH_ERR
, in § 2.8.1
TypeMismatchError
, in § 2.8.1
type parameter
, in § 3.2.22.1
Uint16Array
, in § 2.13.34
Uint32Array
, in § 2.13.34
Uint8Array
, in § 2.13.34
Uint8ClampedArray
, in § 2.13.34
undefined
, in § 2.13.1
underlying buffer
, in § 3.2.26
underlying record
, in § 3.2.22.1
unforgeable
, in § 3.4.10
unforgeable property name
, in § 3.9
union type
, in § 2.13.32
UnknownError
, in § 2.8.1
unrestricted double
, in § 2.13.14
unrestricted float
, in § 2.13.12
Unscopable
, in § 3.3.13
unsigned long
, in § 2.13.8
unsigned long long
, in § 2.13.10
unsigned short
, in § 2.13.6
upon fulfillment
, in § 3.2.24.1
upon rejection
, in § 3.2.24.1
URIError
, in § 2.8
URL_MISMATCH_ERR
, in § 2.8.1
URLMismatchError
, in § 2.8.1
USVString
, in § 2.13.18
VALIDATION_ERR
, in § 4.4
value
, in § 2.5.9
value asynchronously iterable declaration
, in § 2.5.10
value iterator
, in § 2.5.9
value of string literal tokens
, in § 2.5.3
value pair
, in § 2.5.9
value pairs to iterate over
, in § 2.5.9
variadic
, in § 2.5.3
VersionError
, in § 2.8.1
VoidFunction
, in § 4.5
wait for all
, in § 3.2.24.1
waiting for all
, in § 3.2.24.1
Web IDL arguments list
, in § 3.11
write
dfn for ArrayBuffer, SharedArrayBuffer
, in § 3.2.26
dfn for ArrayBufferView
, in § 3.2.26
WRONG_DOCUMENT_ERR
, in § 2.8.1
WrongDocumentError
, in § 2.8.1
Terms defined by reference
[CSS3-CONDITIONAL]
defines the following terms:
supports(conditionText)
supports(property, value)
[CSSOM]
defines the following terms:
CSS
[DOM]
defines the following terms:
Document
EventListener
createElement(localName)
document
element
implementation
node
node tree
[ECMA-262]
defines the following terms:
%Array.prototype%
%Array.prototype.entries%
%Array.prototype.forEach%
%Array.prototype.keys%
%Array.prototype.values%
%ArrayBuffer%
%AsyncIteratorPrototype%
%Error.prototype%
%Function.prototype%
%Iterator.prototype%
%MapIteratorPrototype%
%Object.prototype%
%Promise%
%Promise.prototype.then%
%Promise.reject%
%SetIteratorPrototype%
%SharedArrayBuffer%
%Symbol.asyncIterator%
%Symbol.iterator%
%Symbol.toStringTag%
%Symbol.unscopables%
AllocateArrayBuffer
AllocateSharedArrayBuffer
ArrayBuffer
ArrayCreate
BigInt
Call
CanonicalNumericIndexString
Completion
Construct
CreateArrayFromList
CreateAsyncFromSyncIterator
CreateBuiltinFunction
CreateDataProperty
CreateDataPropertyOrThrow
CreateIteratorFromClosure
CreateIteratorResultObject
DefineMethodProperty
DefinePropertyOrThrow
DetachArrayBuffer
Error
FromPropertyDescriptor
GeneratorYield
Get
GetFunctionRealm
GetIteratorFromMethod
GetMethod
GetValueFromBuffer
IfAbruptRejectPromise
IsAccessorDescriptor
IsCallable
IsConstructor
IsDataDescriptor
IsDetachedBuffer
IsFixedLengthArrayBuffer
IsInteger
IsSharedArrayBuffer
IteratorComplete
IteratorNext
IteratorStepValue
IteratorValue
JSON.stringify()
MakeBasicObject
Map
NewPromiseCapability
NewTarget
OrdinaryDefineOwnProperty
OrdinaryGetOwnProperty
OrdinaryObjectCreate
OrdinaryOwnPropertyKeys
OrdinarySetPrototypeOf
OrdinarySetWithOwnDescriptor
PerformPromiseThen
ProxyCreate
Set
SetImmutablePrototype
SetIntegrityLevel
SetValueInBuffer
SharedArrayBuffer
SyntaxError
ToBigInt
ToBoolean
ToInt32
ToNumber
ToNumeric
ToObject
ToPropertyDescriptor
ToString
ToUint32
TypeError
Yield
abrupt completion
abs
Abstract Closure
agent cluster
all(iterable)
array index
array iterator object
built-in function object
callable
Completion Record
constructor
constructors
conventions
current realm
ECMA-262 Immutable Prototype Exotic Objects
element
element size
enumerable
equally close values
error objects
floor
function object
function objects
immutable prototype exotic objects
internal method
internal method
(for ordinary object)
internal slot
internal slot
(for ordinary object)
is a BigInt
is a Boolean
is a Number
is a String
is a Symbol
is an Object
is not a String
is not a Symbol
is not an Object
Iterator Record
max
min
modulo
number type
NumericLiteral
own property
PromiseCapability
Property Descriptor
proxy exotic object
proxy exotic objects
realm
realms
string object
[FETCH]
defines the following terms:
Response
fetch(input)
[HTML]
defines the following terms:
CanvasDrawPath
HTMLAllCollection
Location
Path2D
Serializable
Window
WindowOrWorkerGlobalScope
WindowProxy
Worklet
clean up after running a callback
clean up after running script
cross-origin isolated capability
deserialization steps
global object
in parallel
incumbent settings object
prepare to run a callback
prepare to run script
queue a microtask
queue a task
relevant realm
relevant settings object
report an exception
secure context
serializable object
serialization steps
settings object
stroke()
task source
unhandledrejection
[Infra]
defines the following terms:
16-bit signed integer
16-bit unsigned integer
32-bit signed integer
32-bit unsigned integer
64-bit signed integer
64-bit unsigned integer
8-bit signed integer
8-bit unsigned integer
append
(for list)
append
(for set)
assert
boolean
break
byte sequence
clear
code point
code unit
concatenation
contain
continue
convert
empty
entry
exist
extend
for each
(for list)
for each
(for map)
implementation-defined
intersection
is empty
is not empty
isomorphic encode
item
(for list)
item
(for struct)
iterate
keys
length
list
map
name
ordered map
ordered set
pop
push
remove
(for list)
remove
(for map)
scalar value
scalar value string
set
set
(for map)
size
(for list)
size
(for map)
stack
string
struct
surrogate
the range
tuple
values
while
[STREAMS]
defines the following terms:
closed
[WASM-JS-API-2]
defines the following terms:
Memory
buffer
[WEBIDL]
defines the following terms:
any
References
Normative References
[DOM]
Anne van Kesteren.
DOM Standard
. Living Standard. URL:
[ECMA-262]
ECMAScript Language Specification
. URL:
[ECMA-402]
ECMAScript Internationalization API Specification
. URL:
[HTML]
Anne van Kesteren; et al.
HTML Standard
. Living Standard. URL:
[IEEE-754]
IEEE Standard for Floating-Point Arithmetic
. 22 July 2019. URL:
[Infra]
Anne van Kesteren; Domenic Denicola.
Infra Standard
. Living Standard. URL:
[PERLRE]
Perl regular expressions (Perl 5.8.8)
. February 2006. URL:
[WEBIDL]
Edgar Chen; Timothy Gu.
Web IDL Standard
. Living Standard. URL:
Informative References
[API-DESIGN-PRINCIPLES]
Martin Thomson; Jeffrey Yasskin.
Web Platform Design Principles
. URL:
[CSS3-CONDITIONAL]
Chris Lilley; David Baron; Elika Etemad.
CSS Conditional Rules Module Level 3
. URL:
[CSSOM]
Daniel Glazman; Emilio Cobos Álvarez.
CSS Object Model (CSSOM)
. URL:
[FETCH]
Anne van Kesteren.
Fetch Standard
. Living Standard. URL:
[INDEXEDDB]
Nikunj Mehta; et al.
Indexed Database API
. URL:
[PROPOSAL-FLOAT16ARRAY]
Proposal to add float16 TypedArrays to JavaScript
. URL:
[SERVICE-WORKERS]
Monica CHINTALA; Yoshisato Yanagisawa.
Service Workers Nightly
. URL:
[STREAMS]
Adam Rice; et al.
Streams Standard
. Living Standard. URL:
[WASM-JS-API-1]
Daniel Ehrenberg.
WebAssembly JavaScript Interface
. URL:
[WASM-JS-API-2]
. Ms2ger; Ryan Hunt.
WebAssembly JavaScript Interface
. URL:
[XML-NAMES]
Tim Bray; et al.
Namespaces in XML 1.0 (Third Edition)
. 8 December 2009. REC. URL:
IDL Index
[Exposed=*,
Serializable
interface
QuotaExceededError
DOMException
constructor
optional
DOMString
message
= "",
optional
QuotaExceededErrorOptions
options
= {});
readonly
attribute
double
quota
readonly
attribute
double
requested
};
dictionary
QuotaExceededErrorOptions
double
quota
double
requested
};
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
typedef
ArrayBufferView
or
ArrayBuffer
BufferSource
typedef
ArrayBuffer
or
SharedArrayBuffer
or
AllowShared
ArrayBufferView
AllowSharedBufferSource
[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;
};
callback
Function
any
any
...
arguments
);
callback
VoidFunction
undefined
();
MDN
DOMException/DOMException
In all current engines.
Firefox
37+
Safari
10.1+
Chrome
46+
Opera
Edge
79+
Edge (Legacy)
IE
None
Firefox for Android
iOS Safari
Chrome for Android
Android WebView
Samsung Internet
Opera Mobile
MDN
DOMException/message
In all current engines.
Firefox
1+
Safari
1+
Chrome
1+
Opera
12.1+
Edge
79+
Edge (Legacy)
12+
IE
9+
Firefox for Android
iOS Safari
Chrome for Android
Android WebView
Samsung Internet
Opera Mobile
12.1+
MDN
DOMException/name
In all current engines.
Firefox
1+
Safari
1+
Chrome
1+
Opera
12.1+
Edge
79+
Edge (Legacy)
12+
IE
10+
Firefox for Android
iOS Safari
Chrome for Android
Android WebView
Samsung Internet
Opera Mobile
12.1+
MDN
DOMException
In all current engines.
Firefox
1+
Safari
1+
Chrome
1+
Opera
12.1+
Edge
79+
Edge (Legacy)
12+
IE
9+
Firefox for Android
iOS Safari
Chrome for Android
Android WebView
Samsung Internet
Opera Mobile
12.1+
Node.js
17.0.0+