WindowOrWorkerGlobalScope
mixin
Various mechanisms can cause author-provided executable code to run in the context of a document. These mechanisms include, but are probably not limited to:
script
elements.
javascript:
URLs
.
addEventListener()
,
by
explicit
event
handler
content
attributes
,
by
event
handler
IDL
attributes
,
or
otherwise.
Scripting is enabled in a browsing context when all of the following conditions are true:
Scripting is disabled in a browsing context when any of the above conditions are false (i.e. when scripting is not enabled ).
Scripting is enabled for a node if the node's node document has a browsing context , and scripting is enabled in that browsing context .
Scripting is disabled for a node if there is no such browsing context , or if scripting is disabled in that browsing context .
A script is one of two possible structs . All scripts have:
An environment settings object , containing various settings that are shared with other scripts in the same context.
Either a Script Record , for classic scripts ; a Source Text Module Record , for module scripts ; or null. In the former two cases, it represents a parsed script; null represents a failure parsing.
A JavaScript value, which has meaning only if the record is null, indicating that the corresponding script source text could not be parsed.
A JavaScript value representing an error that will prevent evaluation from succeeding. It will be re-thrown by any attempts to run the script.
Since this exception value is provided by the JavaScript specification, we know that it is never null, so we use null to signal that no error has occurred.
A base URL used for resolving module specifiers . This will either be the URL from which the script was obtained, for external scripts, or the document base URL of the containing document, for inline scripts.
A classic script is a type of script that has the following additional item :
A boolean which, if true, means that error information will not be provided for errors in this script. This is used to mute errors for cross-origin scripts, since that can leak private information.
A module script is another type of script . It has no additional items .
The active script is determined by the following algorithm:
Let record be GetActiveScriptOrModule ().
If record is null, return null.
Return record .[[HostDefined]].
An environment is an object that identifies the settings of a current or potential execution environment. An environment has the following fields:
An opaque string that uniquely identifies the environment .
A URL record that represents the location of the resource with which the environment is associated.
In
the
case
of
an
environment
settings
object
,
this
URL
might
be
distinct
from
the
environment
settings
object
's
responsible
document
's
URL
,
due
to
mechanisms
such
as
history.pushState()
.
Null or a target browsing context for a navigation request .
Null or a service worker that controls the environment .
A flag that indicates whether the environment setup is done. It is initially unset.
An environment settings object is an environment that additionally specifies algorithms for:
A JavaScript execution context shared by all scripts that use this settings object, i.e. all scripts in a given JavaScript realm . When we run a classic script or run a module script , this execution context becomes the top of the JavaScript execution context stack , on top of which another execution context specific to the script in question is pushed. (This setup ensures ParseScript and Source Text Module Record 's Evaluate know which Realm to use.)
A module map that is used when importing JavaScript modules.
A browsing context that is assigned responsibility for actions taken by the scripts that use this environment settings object .
When
a
script
creates
and
navigates
a
new
top-level
browsing
context
,
the
opener
attribute
of
the
new
browsing
context
's
Window
object
will
be
set
to
the
responsible
browsing
context
's
WindowProxy
object.
An event loop that is used when it would not be immediately clear what event loop to use.
A
Document
that
is
assigned
responsibility
for
actions
taken
by
the
scripts
that
use
this
environment
settings
object
.
For
example,
the
URL
of
the
responsible
document
is
used
to
set
the
URL
of
the
Document
after
it
has
been
reset
using
document.open()
.
If the responsible event loop is not a browsing context event loop , then the environment settings object has no responsible document .
A character encoding used to encode URLs by APIs called by scripts that use this environment settings object .
A URL used by APIs called by scripts that use this environment settings object to parse URLs .
An origin used in security checks.
An HTTPS state value representing the security properties of the network channel used to deliver the resource with which the environment settings object is associated.
The default referrer policy for fetches performed using this environment settings object as a request client . [REFERRERPOLICY]
An environment settings object also has an outstanding rejected promises weak set and an about-to-be-notified rejected promises list , used to track unhandled promise rejections . The outstanding rejected promises weak set must not create strong references to any of its members, and implementations are free to limit its size, e.g. by removing old entries from it when new ones are added.
This section introduces a number of algorithms for fetching scripts, taking various necessary inputs and resulting in classic or module scripts .
Script fetch options is a struct with the following items :
The cryptographic nonce metadata used for the initial fetch and for fetching any imported modules
The integrity metadata used for the initial fetch
The parser metadata used for the initial fetch and for fetching any imported modules
The credentials mode used for the initial fetch (for module scripts ) and for fetching any imported modules (for both module scripts and classic scripts )
The referrer policy used for the initial fetch and for fetching any imported modules
Recall
that
via
the
import()
feature,
classic
scripts
can
import
module
scripts
.
The
default
classic
script
fetch
options
are
a
script
fetch
options
whose
cryptographic
nonce
is
the
empty
string,
integrity
metadata
is
the
empty
string,
parser
metadata
is
"
not-parser-inserted
",
credentials
mode
is
"
omit
",
and
referrer
policy
is
the
empty
string.
Given a request request and a script fetch options options , we define:
Set request 's cryptographic nonce metadata to options 's cryptographic nonce , its integrity metadata to options 's integrity metadata , its parser metadata to options 's parser metadata , and its referrer policy to options 's referrer policy .
Set request 's cryptographic nonce metadata to options 's cryptographic nonce , its integrity metadata to options 's integrity metadata , its parser metadata to options 's parser metadata , its credentials mode to options 's credentials mode , and its referrer policy to options 's referrer policy .
For any given script fetch options options , the descendant script fetch options are a new script fetch options whose items all have the same values, except for the integrity metadata , which is instead the empty string.
The
algorithms
below
can
be
customized
by
optionally
supplying
a
custom
perform
the
fetch
hook,
which
takes
a
request
and
an
is
top-level
flag.
The
algorithm
must
complete
with
a
response
(which
may
be
a
network
error
),
either
synchronously
(when
using
fetch
a
classic
worker-imported
script
)
or
asynchronously
(otherwise).
The
is
top-level
flag
will
be
set
for
all
classic
script
fetches,
and
for
the
initial
fetch
when
fetching
a
module
script
graph
or
fetching
a
module
worker
script
graph
,
but
not
for
the
fetches
resulting
from
import
statements
encountered
throughout
the
graph.
By default, not supplying the perform the fetch will cause the below algorithms to simply fetch the given request , with algorithm-specific customizations to the request and validations of the resulting response .
To layer your own customizations on top of these algorithm-specific ones, supply a perform the fetch hook that modifies the given request , fetches it, and then performs specific validations of the resulting response (completing with a network error if the validations fail).
The hook can also be used to perform more subtle customizations, such as keeping a cache of responses and avoiding performing a fetch at all.
Service Workers is an example of a specification that runs these algorithms with its own options for the hook. [SW]
Now for the algorithms themselves.
To fetch a classic script given a url , a settings object , some options , a CORS setting , and a character encoding , run these steps. The algorithm will asynchronously complete with either null (on failure) or a new classic script (on success).
Let
request
be
the
result
of
creating
a
potential-CORS
request
given
url
,
"
script
",
and
CORS
setting
.
Set request 's client to settings object .
Set up the classic script request given request and options .
If the caller specified custom steps to perform the fetch , perform them on request , with the is top-level flag set. Return from this algorithm, and when the custom perform the fetch steps complete with response response , run the remaining steps.
Otherwise, fetch request . Return from this algorithm, and run the remaining steps as part of the fetch's process response for the response response .
response can be either CORS-same-origin or CORS-cross-origin . This only affects how error reporting happens.
Let response be response 's unsafe response .
If
response
's
type
is
"
error
",
or
response
's
status
is
not
an
ok
status
,
asynchronously
complete
this
algorithm
with
null,
and
abort
these
steps.
If response 's Content Type metadata , if any, specifies a character encoding, and the user agent supports that encoding, then set character encoding to that encoding (ignoring the passed-in value).
Let source text be the result of decoding response 's body to Unicode, using character encoding as the fallback encoding.
The decode algorithm overrides character encoding if the file contains a BOM.
Let muted errors be true if response was CORS-cross-origin , and false otherwise.
Let script be the result of creating a classic script given source text , settings object , response 's url , options , and muted errors .
To fetch a classic worker script given a url , a fetch client settings object , a destination , and a script settings object , run these steps. The algorithm will asynchronously complete with either null (on failure) or a new classic script (on success).
Let
request
be
a
new
request
whose
url
is
url
,
client
is
fetch
client
settings
object
,
destination
is
destination
,
mode
is
"
same-origin
",
credentials
mode
is
"
same-origin
",
parser
metadata
is
"
not
parser-inserted
",
and
whose
use-URL-credentials
flag
is
set.
If the caller specified custom steps to perform the fetch , perform them on request , with the is top-level flag set. Return from this algorithm, and when the custom perform the fetch steps complete with response response , run the remaining steps.
Otherwise, fetch request . Return from this algorithm, and run the remaining steps as part of the fetch's process response for the response response .
Let response be response 's unsafe response .
If
response
's
type
is
"
error
",
or
response
's
status
is
not
an
ok
status
,
asynchronously
complete
this
algorithm
with
null,
and
abort
these
steps.
Let source text be the result of UTF-8 decoding response 's body .
Let script be the result of creating a classic script using source text , script settings object , response 's url , and the default classic script fetch options .
To fetch a classic worker-imported script given a url and a settings object , run these steps. The algorithm will synchronously complete with a classic script on success, or throw an exception on failure.
Let
request
be
a
new
request
whose
url
is
url
,
client
is
settings
object
,
destination
is
"
script
",
parser
metadata
is
"
not
parser-inserted
",
synchronous
flag
is
set,
and
whose
use-URL-credentials
flag
is
set.
If the caller specified custom steps to perform the fetch , perform them on request , with the is top-level flag set. Let response be the result.
Otherwise, fetch request , and let response be the result.
Unlike other algorithms in this section, the fetching process is synchronous here. Thus any perform the fetch steps will also finish their work synchronously.
Let response be response 's unsafe response .
If
response
's
type
is
"
error
",
or
response
's
status
is
not
an
ok
status
,
throw
a
"
NetworkError
"
DOMException
.
Let source text be the result of UTF-8 decoding response 's body .
Let muted errors be true if response was CORS-cross-origin , and false otherwise.
Let script be the result of creating a classic script given source text , settings object , response 's url , the default classic script fetch options , and muted errors .
Return script .
To fetch a module script graph given a url , a settings object , a destination , and some options , run these steps. The algorithm will asynchronously complete with either null (on failure) or a module script (on success).
Let visited set be « url ».
Perform
the
internal
module
script
graph
fetching
procedure
given
url
,
settings
object
,
destination
,
options
,
settings
object
,
visited
set
,
"
client
",
and
with
the
top-level
module
fetch
flag
set.
If
the
caller
of
this
algorithm
specified
custom
perform
the
fetch
steps,
pass
those
along
as
well.
When the internal module script graph fetching procedure asynchronously completes with result , asynchronously complete this algorithm with result .
To fetch a module worker script graph given a url , a fetch client settings object , a destination , a credentials mode , and a module map settings object , run these steps. The algorithm will asynchronously complete with either null (on failure) or a module script (on success).
Let visited set be « url ».
Let
options
be
a
script
fetch
options
whose
cryptographic
nonce
is
the
empty
string,
integrity
metadata
is
the
empty
string,
parser
metadata
is
"
not-parser-inserted
",
credentials
mode
is
credentials
mode
,
and
referrer
policy
is
the
empty
string.
Perform
the
internal
module
script
graph
fetching
procedure
given
url
,
fetch
client
settings
object
,
destination
,
options
,
module
map
settings
object
,
visited
set
,
"
client
",
and
with
the
top-level
module
fetch
flag
set.
If
the
caller
of
this
algorithm
specified
custom
perform
the
fetch
steps,
pass
those
along
as
well.
When the internal module script graph fetching procedure asynchronously completes with result , asynchronously complete this algorithm with result .
The following algorithms are meant for internal use by this specification only as part of fetching a module script graph or preparing a script , and should not be used directly by other specifications.
To perform the internal module script graph fetching procedure given a url , a fetch client settings object , a destination , a some options , a module map settings object , a visited set , a referrer , and a top-level module fetch flag, perform these steps. The algorithm will asynchronously complete with either null (on failure) or a module script (on success).
Assert: visited set contains url .
Fetch a single module script given url , fetch client settings object , destination , options , module map settings object , referrer , and the top-level module fetch flag. If the caller of this algorithm specified custom perform the fetch steps, pass those along while fetching a single module script .
Return from this algorithm, and run the following steps when fetching a single module script asynchronously completes with result :
If result is null, asynchronously complete this algorithm with null, and abort these steps.
If the top-level module fetch flag is set, fetch the descendants of and instantiate result given destination and visited set . Otherwise, fetch the descendants of result given the same arguments.
When the appropriate algorithm asynchronously completes with final result , asynchronously complete this algorithm with final result .
To fetch a single module script , given a url , a fetch client settings object , a destination , some options , a module map settings object , a referrer , and a top-level module fetch flag, run these steps. The algorithm will asynchronously complete with either null (on failure) or a module script (on success).
Let moduleMap be module map settings object 's module map .
If
moduleMap
[
url
]
is
"
fetching
",
wait
in
parallel
until
that
entry's
value
changes,
then
queue
a
task
on
the
networking
task
source
to
proceed
with
running
the
following
steps.
If moduleMap [ url ] exists , asynchronously complete this algorithm with moduleMap [ url ], and abort these steps.
Set
moduleMap
[
url
]
to
"
fetching
".
Let
request
be
a
new
request
whose
url
is
url
,
destination
is
destination
,
mode
is
"
cors
",
referrer
is
referrer
,
and
client
is
fetch
client
settings
object
.
Set up the module script request given request and options .
If the caller specified custom steps to perform the fetch , perform them on request , setting the is top-level flag if the top-level module fetch flag is set. Return from this algorithm, and when the custom perform the fetch steps complete with response response , run the remaining steps.
Otherwise, fetch request . Return from this algorithm, and run the remaining steps as part of the fetch's process response for the response response .
response is always CORS-same-origin .
If any of the following conditions are met, set moduleMap [ url ] to null, asynchronously complete this algorithm with null, and abort these steps:
response
's
type
is
"
error
"
The
result
of
extracting
a
MIME
type
from
response
's
header
list
(ignoring
parameters)
is
not
a
JavaScript
MIME
type
For historical reasons, fetching a classic script does not include MIME type checking. In contrast, module scripts will fail to load if they are not of a correct MIME type.
Let source text be the result of UTF-8 decoding response 's body .
Let module script be the result of creating a module script given source text , module map settings object , response 's url , and options .
Set moduleMap [ url ] to module script , and asynchronously complete this algorithm with module script .
It is intentional that the module map is keyed by the request URL , whereas the base URL for the module script is set to the response URL . The former is used to deduplicate fetches, while the latter is used for URL resolution.
To fetch the descendants of a module script module script , given a destination and a visited set , run these steps. The algorithm will asynchronously complete with either null (on failure) or with module script (on success).
If module script 's record is null, then asynchronously complete this algorithm with module script and abort these steps.
Let record be module script 's record .
If record .[[RequestedModules]] is empty , asynchronously complete this algorithm with module script .
Let urls be a new empty list .
For each string requested of record .[[RequestedModules]],
Let url be the result of resolving a module specifier given module script and requested .
Assert: url is never failure, because resolving a module specifier must have been previously successful with these same two arguments.
If visited set does not contain url , then:
Let options be the descendant script fetch options for module script 's fetch options .
For each url in urls , perform the internal module script graph fetching procedure given url , options , destination , module script 's settings object , module script 's settings object , visited set , module script 's base URL , and with the top-level module fetch flag unset. If the caller of this algorithm specified custom perform the fetch steps, pass those along while performing the internal module script graph fetching procedure .
These invocations of the internal module script graph fetching procedure should be performed in parallel to each other.
If any of the invocations of the internal module script graph fetching procedure asynchronously complete with null, asynchronously complete this algorithm with null, aborting these steps.
Otherwise, wait until all of the internal module script graph fetching procedure invocations have asynchronously completed. Asynchronously complete this algorithm with module script .
To fetch the descendants of and instantiate a module script module script , given a destination and an optional visited set , run these steps. The algorithm will asynchronously complete with either null (on failure) or with module script (on success).
If visited set was not given, let it be an empty set .
Fetch the descendants of module script , given destination and visited set .
Return from this algorithm, and run the following steps when fetching the descendants of a module script asynchronously completes with result .
If result is null, then asynchronously complete this algorithm with result .
In this case, there was an error fetching one or more of the descendants. We will not attempt to instantiate.
Let parse error be the result of finding the first parse error given result .
If parse error is null, then:
Let record be result 's record .
Perform record . Instantiate ().
This step will recursively call Instantiate on all of the module's uninstantiated dependencies.
If this throws an exception, set result 's error to rethrow to that exception.
Otherwise, set result 's error to rethrow to parse error .
Asynchronously complete this algorithm with result .
To find the first parse error given a root moduleScript and an optional discoveredSet :
Let moduleMap be moduleScript 's settings object 's module map .
If discoveredSet was not given, let it be an empty set .
Append moduleScript to discoveredSet .
If moduleScript 's record is null, then return moduleScript 's parse error .
Let childSpecifiers be the value of moduleScript 's record 's [[RequestedModules]] internal slot.
Let childURLs be the list obtained by calling resolve a module specifier once for each item of childSpecifiers , given moduleScript and that item. (None of these will ever fail, as otherwise moduleScript would have been marked as itself having a parse error.)
Let childModules be the list obtained by getting each value in moduleMap whose key is given by an item of childURLs .
For each childModule of childModules :
Assert:
childModule
is
a
module
script
(i.e.,
it
is
not
"
fetching
"
or
null);
by
now
all
module
scripts
in
the
graph
rooted
at
moduleScript
will
have
successfully
been
fetched.
Let childParseError be the result of finding the first parse error given childModule and discoveredSet .
If childParseError is not null, return childParseError .
Return null.
To create a classic script , given a JavaScript string source , an environment settings object settings , a URL baseURL , some script fetch options options , and an optional muted errors boolean:
If muted errors was not provided, let it be false.
If scripting is disabled for settings 's responsible browsing context , then set source to the empty string.
Let script be a new classic script that this algorithm will subsequently initialize.
Set script 's settings object to settings .
Set script 's base URL to baseURL .
Set script 's fetch options to options .
Set script 's muted errors to muted errors .
Set script 's parse error and error to rethrow to null.
Let result be ParseScript ( source , settings 's Realm , script ).
Passing script as the last parameter here ensures result .[[HostDefined]] will be script .
If result is a list of errors, then:
Set script 's parse error and its error to rethrow to result [0].
Return script .
Set script 's record to result .
Return script .
To create a module script , given a JavaScript string source , an environment settings object settings , a URL baseURL , and some script fetch options options :
If scripting is disabled for settings 's responsible browsing context , then set source to the empty string.
Let script be a new module script that this algorithm will subsequently initialize.
Set script 's settings object to settings .
Set script 's base URL to baseURL .
Set script 's fetch options to options .
Set script 's parse error and error to rethrow to null.
Let result be ParseModule ( source , settings 's Realm , script ).
Passing script as the last parameter here ensures result .[[HostDefined]] will be script .
If result is a list of errors, then:
Set script 's parse error to result [0].
Return script .
For each string requested of result .[[RequestedModules]]:
Let url be the result of resolving a module specifier given script and requested .
If url is failure, then:
Let
error
be
a
new
TypeError
exception.
Set script 's parse error to error .
Return script .
This step is essentially validating all of the requested module specifiers. We treat a module with unresolvable module specifiers the same as one that cannot be parsed; in both cases, a syntactic issue makes it impossible to ever contemplate instantiating the module later.
Set script 's record to result .
Return script .
To run a classic script given a classic script script and an optional rethrow errors boolean:
If rethrow errors is not given, let it be false.
Let settings be the settings object of script .
Check if we can run script with settings . If this returns "do not run" then return.
Prepare to run script given settings .
Let evaluationStatus be null.
If script 's error to rethrow is not null, then set evaluationStatus to Completion { [[Type]]: throw, [[Value]]: script 's error to rethrow , [[Target]]: empty }.
Otherwise, set evaluationStatus to ScriptEvaluation ( script 's record ).
If ScriptEvaluation does not complete because the user agent has aborted the running script , leave evaluationStatus as null.
If evaluationStatus is an abrupt completion, then:
If rethrow errors is true and script 's muted errors is false, then:
Clean up after running script with settings .
Rethrow evaluationStatus .[[Value]].
If rethrow errors is true and script 's muted errors is true, then:
Clean up after running script with settings .
Throw
a
"
NetworkError
"
DOMException
.
Otherwise, rethrow errors is false. Perform the following steps:
Report the exception given by evaluationStatus .[[Value]] for script .
Clean up after running script with settings .
Return undefined.
Clean up after running script with settings .
If evaluationStatus is a normal completion, return evaluationStatus .[[Value]].
This
value
is
only
ever
used
by
the
javascript:
URL
steps
.
If we've reached this point, evaluationStatus was left as null because the script was aborted prematurely during evaluation. Return undefined.
To run a module script given a module script script , with an optional rethrow errors boolean:
If rethrow errors is not given, let it be false.
Let settings be the settings object of script .
Check if we can run script with settings . If this returns "do not run" then return.
Prepare to run script given settings .
Let evaluationStatus be null.
If script 's error to rethrow is not null, then set evaluationStatus to Completion { [[Type]]: throw, [[Value]]: script 's error to rethrow , [[Target]]: empty }.
Otherwise:
Let record be script 's record .
Set evaluationStatus to record . Evaluate ().
This step will recursively evaluate all of the module's dependencies.
If
Evaluate
fails
to
complete
as
a
result
of
the
user
agent
aborting
the
running
script
,
then
set
evaluationStatus
to
Completion
{
[[Type]]:
throw,
[[Value]]:
a
new
"
QuotaExceededError
"
DOMException
,
[[Target]]:
empty
}.
If evaluationStatus is an abrupt completion, then:
If rethrow errors is true, rethrow the exception given by evaluationStatus .[[Value]].
Otherwise, report the exception given by evaluationStatus .[[Value]] for script .
Clean up after running script with settings .
The steps to check if we can run script with an environment settings object settings are as follows. They return either "run" or "do not run".
If
the
global
object
specified
by
settings
is
a
Window
object
whose
Document
object
is
not
fully
active
,
then
return
"do
not
run".
If scripting is disabled for the responsible browsing context specified by settings , then return "do not run".
Return "run".
The steps to prepare to run script with an environment settings object settings are as follows:
Push settings 's realm execution context onto the JavaScript execution context stack ; it is now the running JavaScript execution context .
The steps to clean up after running script with an environment settings object settings are as follows:
Assert: settings 's realm execution context is the running JavaScript execution context .
Remove settings 's realm execution context from the JavaScript execution context stack .
If the JavaScript execution context stack is now empty, perform a microtask checkpoint . (If this runs scripts, these algorithms will be invoked reentrantly.)
These algorithms are not invoked by one script directly calling another, but they can be invoked reentrantly in an indirect manner, e.g. if a script dispatches an event which has event listeners registered.
The running script is the script in the [[HostDefined]] field in the ScriptOrModule component of the running JavaScript execution context .
A global object is a JavaScript object that is the [[GlobalObject]] field of a JavaScript realm .
In
this
specification,
all
JavaScript
realms
are
initialized
with
global
objects
that
are
either
Window
or
WorkerGlobalScope
objects.
There is always a 1-to-1-to-1 mapping between JavaScript realms , global objects , and environment settings objects :
A JavaScript realm has a [[HostDefined]] field, which contains the Realm's settings object .
A JavaScript realm has a [[GlobalObject]] field, which contains the Realm's global object .
Each global object in this specification is created during the initialization of a corresponding JavaScript realm , known as the global object's Realm .
Each global object in this specification is created alongside a corresponding environment settings object , known as its relevant settings object .
An environment settings object 's realm execution context 's Realm component is the environment settings object's Realm .
An environment settings object 's Realm then has a [[GlobalObject]] field, which contains the environment settings object's global object .
When defining algorithm steps throughout this specification, it is often important to indicate what JavaScript realm is to be used—or, equivalently, what global object or environment settings object is to be used. In general, there are at least four possibilities:
Note how the entry , incumbent , and current concepts are usable without qualification, whereas the relevant concept must be applied to a particular platform object .
Consider
the
following
pages,
with
a.html
being
loaded
in
a
browser
window,
b.html
being
loaded
in
an
iframe
as
shown,
and
c.html
and
d.html
omitted
(they
can
simply
be
empty
documents):
<!-- a.html --> <!DOCTYPE html> <html lang="en"> <title>Entry page</title> <iframe src="b.html"></iframe> <button onclick="frames[0].hello()">Hello</button> <!--b.html --> <!DOCTYPE html> <html lang="en"> <title>Incumbent page</title> <iframe src="c.html" id="c"></iframe> <iframe src="d.html" id="d"></iframe> <script> const c = document.querySelector("#c").contentWindow; const d = document.querySelector("#d").contentWindow; window.hello = () => { c.print.call(d); }; </script>
Each page has its own browsing context , and thus its own JavaScript realm , global object , and environment settings object .
When
the
print()
method
is
called
in
response
to
pressing
the
button
in
a.html
,
then:
The
entry
Realm
is
that
of
a.html
.
The
incumbent
Realm
is
that
of
b.html
.
The
current
Realm
is
that
of
c.html
(since
it
is
the
print()
method
from
c.html
whose
code
is
running).
The
relevant
Realm
of
the
object
on
which
the
print()
method
is
being
called
is
that
of
d.html
.
The incumbent and entry concepts should not be used by new specifications, as they are excessively complicated and unintuitive to work with. We are working to remove almost all existing uses from the platform: see issue #1430 for incumbent , and issue #1431 for entry .
In
general,
web
platform
specifications
should
use
the
relevant
concept,
applied
to
the
object
being
operated
on
(usually
the
this
value
of
the
current
method).
This
mismatches
the
JavaScript
specification,
where
current
is
generally
used
as
the
default
(e.g.
in
determining
the
JavaScript
realm
whose
Array
constructor
should
be
used
to
construct
the
result
in
Array.prototype.map
).
But
this
inconsistency
is
so
embedded
in
the
platform
that
we
have
to
accept
it
going
forward.
Note that in constructors, where there is no this value yet, the current concept is the appropriate default.
One
reason
why
the
relevant
concept
is
generally
a
better
default
choice
than
the
current
concept
is
that
it
is
more
suitable
for
creating
an
object
that
is
to
be
persisted
and
returned
multiple
times.
For
example,
the
navigator.getBattery()
method
creates
promises
in
the
relevant
Realm
for
the
Navigator
object
on
which
it
is
invoked.
This
has
the
following
impact:
[BATTERY]
<!-- outer.html --> <!DOCTYPE html> <html lang="en"> <title>Relevant Realm demo: outer page</title> <script> function doTest() { const promise = navigator.getBattery.call(frames[0].navigator); console.log(promise instanceof Promise); // logs false console.log(promise instanceof frames[0].Promise); // logs true frames[0].hello(); } </script> <iframe src="inner.html" onload="doTest()"></iframe> <!-- inner.html --> <!DOCTYPE html> <html lang="en"> <title>Relevant Realm demo: inner page</title> <script> function hello() { const promise = navigator.getBattery(); console.log(promise instanceof Promise); // logs true console.log(promise instanceof parent.Promise); // logs false } </script>
If
the
algorithm
for
the
getBattery()
method
had
instead
used
the
current
Realm
,
all
the
results
would
be
reversed.
That
is,
after
the
first
call
to
getBattery()
in
outer.html
,
the
Navigator
object
in
inner.html
would
be
permanently
storing
a
Promise
object
created
in
outer.html
's
JavaScript
realm
,
and
calls
like
that
inside
the
hello()
function
would
thus
return
a
promise
from
the
"wrong"
realm.
Since
this
is
undesirable,
the
algorithm
instead
uses
the
relevant
Realm
,
giving
the
sensible
results
indicated
in
the
comments
above.
The rest of this section deals with formally defining the entry , incumbent , current , and relevant concepts.
The process of calling scripts will push or pop realm execution contexts onto the JavaScript execution context stack , interspersed with other execution contexts .
With this in hand, we define the entry execution context to be the most recently pushed item in the JavaScript execution context stack that is a realm execution context . The entry Realm is the entry execution context 's Realm component.
Then, the entry settings object is the environment settings object of the entry Realm .
Similarly, the entry global object is the global object of the entry Realm .
All JavaScript execution contexts must contain, as part of their code evaluation state, a skip-when-determining-incumbent counter value, which is initially zero. In the process of preparing to run a callback and cleaning up after running a callback , this value will be incremented and decremented.
Every event loop has an associated backup incumbent settings object stack , initially empty. Roughly speaking, it is used to determine the incumbent settings object when no author code is on the stack, but author code is responsible for the current algorithm having been run in some way. The process of preparing to run a callback and cleaning up after running a callback manipulate this stack. [WEBIDL]
When Web IDL is used to invoke author code, or when EnqueueJob invokes a promise job, they use the following algorithms to track relevant data for determining the incumbent settings object :
To prepare to run a callback with an environment settings object settings :
Push settings onto the backup incumbent settings object stack .
Let context be the topmost script-having execution context .
If context is not null, increment context 's skip-when-determining-incumbent counter .
To clean up after running a callback with an environment settings object settings :
Let context be the topmost script-having execution context .
This will be the same as the topmost script-having execution context inside the corresponding invocation of prepare to run a callback .
If context is not null, decrement context 's skip-when-determining-incumbent counter .
Assert: the topmost entry of the backup incumbent settings object stack is settings .
Remove settings from the backup incumbent settings object stack .
Here, the topmost script-having execution context is the topmost entry of the JavaScript execution context stack that has a non-null ScriptOrModule component, or null if there is no such entry in the JavaScript execution context stack .
With all this in place, the incumbent settings object is determined as follows:
Let context be the topmost script-having execution context .
If context is null, or if context 's skip-when-determining-incumbent counter is greater than zero, then:
Assert: the backup incumbent settings object stack is not empty.
This assert would fail if you try to obtain the incumbent settings object from inside an algorithm that was triggered neither by calling scripts nor by Web IDL invoking a callback. For example, it would trigger if you tried to obtain the incumbent settings object inside an algorithm that ran periodically as part of the event loop , with no involvement of author code. In such cases the incumbent concept cannot be used.
Return the topmost entry of the backup incumbent settings object stack .
Return context 's Realm component's settings object .
Then, the incumbent Realm is the Realm of the incumbent settings object .
Similarly, the incumbent global object is the global object of the incumbent settings object .
The following series of examples is intended to make it clear how all of the different mechanisms contribute to the definition of the incumbent concept:
Consider the following very simple example:
<!DOCTYPE html> <iframe></iframe> <script> new frames[0].MessageChannel(); </script>
When
the
MessageChannel()
constructor
looks
up
the
incumbent
settings
object
to
use
as
the
owner
of
the
new
MessagePort
objects,
the
topmost
script-having
execution
context
will
be
that
corresponding
to
the
script
element:
it
was
pushed
onto
the
JavaScript
execution
context
stack
as
part
of
ScriptEvaluation
during
the
run
a
classic
script
algorithm.
Since
there
are
no
Web
IDL
callback
invocations
involved,
the
context's
skip-when-determining-incumbent
counter
is
zero,
so
it
is
used
to
determine
the
incumbent
settings
object
;
the
result
is
the
environment
settings
object
of
window
.
(In
this
example,
the
environment
settings
object
of
frames[0]
is
not
involved
at
all.
It
is
the
current
settings
object
,
but
the
MessageChannel()
constructor
cares
only
about
the
incumbent,
not
current.)
Consider the following more complicated example:
<!DOCTYPE html> <iframe></iframe> <script> const bound = frames[0].postMessage.bind(frames[0], "some data", "*"); window.setTimeout(bound); </script>
There
are
two
interesting
environment
settings
objects
here:
that
of
window
,
and
that
of
frames[0]
.
Our
concern
is:
what
is
the
incumbent
settings
object
at
the
time
that
the
algorithm
for
postMessage()
executes?
It
should
be
that
of
window
,
to
capture
the
intuitive
notion
that
the
author
script
responsible
for
causing
the
algorithm
to
happen
is
executing
in
window
,
not
frames[0]
.
Another
way
of
capturing
the
intuition
here
is
that
invoking
algorithms
asynchronously
(in
this
case
via
setTimeout()
)
should
not
change
the
incumbent
concept.
Let
us
now
explain
how
the
steps
given
above
give
us
our
intuitively-desired
result
of
window
's
relevant
settings
object
.
When
bound
is
converted
to
a
Web
IDL
callback
type,
the
incumbent
settings
object
is
that
corresponding
to
window
(in
the
same
manner
as
in
our
simple
example
above).
Web
IDL
stores
this
as
the
resulting
callback
value's
callback
context
.
When
the
task
posted
by
setTimeout()
executes,
the
algorithm
for
that
task
uses
Web
IDL
to
invoke
the
stored
callback
value.
Web
IDL
in
turn
calls
the
above
prepare
to
run
a
callback
algorithm.
This
pushes
the
stored
callback
context
onto
the
backup
incumbent
settings
object
stack
.
At
this
time
(inside
the
timer
task)
there
is
no
author
code
on
the
stack,
so
the
topmost
script-having
execution
context
is
null,
and
nothing
gets
its
skip-when-determining-incumbent
counter
incremented.
Invoking
the
callback
then
calls
bound
,
which
in
turn
calls
the
postMessage()
method
of
frames[0]
.
When
the
postMessage()
algorithm
looks
up
the
incumbent
settings
object
,
there
is
still
no
author
code
on
the
stack,
since
the
bound
function
just
directly
calls
the
built-in
method.
So
the
topmost
script-having
execution
context
will
be
null:
the
JavaScript
execution
context
stack
only
contains
an
execution
context
corresponding
to
postMessage()
,
with
no
ScriptEvaluation
context
or
similar
below
it.
This
is
where
we
fall
back
to
the
backup
incumbent
settings
object
stack
.
As
noted
above,
it
will
contain
as
its
topmost
entry
the
relevant
settings
object
of
window
.
So
that
is
what
is
used
as
the
incumbent
settings
object
while
executing
the
postMessage()
algorithm.
Consider this final, even more convoluted example:
<!-- a.html --> <!DOCTYPE html> <button>click me</button> <iframe></iframe> <script> const bound = frames[0].location.assign.bind(frames[0].location, "https://example.com/"); document.querySelector("button").addEventListener("click", bound); </script> <!-- b.html --> <!DOCTYPE html> <iframe src="a.html"></iframe> <script> const iframe = document.querySelector("iframe"); iframe.onload = function onLoad() { iframe.contentWindow.document.querySelector("button").click(); }; </script>
Again
there
are
two
interesting
environment
settings
objects
in
play:
that
of
a.html
,
and
that
of
b.html
.
When
the
location.assign()
method
triggers
the
Location
-object
navigate
algorithm,
what
will
be
the
incumbent
settings
object
?
As
before,
it
should
intuitively
be
that
of
a.html
:
the
click
listener
was
originally
scheduled
by
a.html
,
so
even
if
something
involving
b.html
causes
the
listener
to
fire,
the
incumbent
responsible
is
that
of
a.html
.
The
callback
setup
is
similar
to
the
previous
example:
when
bound
is
converted
to
a
Web
IDL
callback
type,
the
incumbent
settings
object
is
that
corresponding
to
a.html
,
which
is
stored
as
the
callback's
callback
context
.
When
the
click()
method
is
called
inside
b.html
,
it
dispatches
a
click
event
on
the
button
that
is
inside
a.html
.
This
time,
when
the
prepare
to
run
a
callback
algorithm
executes
as
part
of
event
dispatch,
there
is
author
code
on
the
stack;
the
topmost
script-having
execution
context
is
that
of
the
onLoad
function,
whose
skip-when-determining-incumbent
counter
gets
incremented.
Additionally,
a.html
's
environment
settings
object
(stored
as
the
EventHandler
's
callback
context
)
is
pushed
onto
the
backup
incumbent
settings
object
stack
.
Now,
when
the
Location
-object
navigate
algorithm
looks
up
the
incumbent
settings
object
,
the
topmost
script-having
execution
context
is
still
that
of
the
onLoad
function
(due
to
the
fact
we
are
using
a
bound
function
as
the
callback).
Its
skip-when-determining-incumbent
counter
value
is
one,
however,
so
we
fall
back
to
the
backup
incumbent
settings
object
stack
.
This
gives
us
the
environment
settings
object
of
a.html
,
as
expected.
Note
that
this
means
that
even
though
it
is
the
iframe
inside
a.html
that
navigates,
it
is
a.html
itself
that
is
used
as
the
source
browsing
context
,
which
determines
among
other
things
the
request
client
.
This
is
perhaps
the
only
justifiable
use
of
the
incumbent
concept
on
the
web
platform
;
in
all
other
cases
the
consequences
of
using
it
are
simply
confusing
and
we
hope
to
one
day
switch
them
to
use
current
or
relevant
as
appropriate.
The JavaScript specification defines the current Realm Record , sometimes abbreviated to the "current Realm". [JAVASCRIPT]
Then, the current settings object is the environment settings object of the current Realm Record .
Similarly, the current global object is the global object of the current Realm Record .
The relevant settings object for a platform object is defined as follows:
The relevant settings object for a non-global platform object o is the environment settings object whose global object is the global object of the global environment associated with o .
The " global environment associated with " concept is from the olden days, before the modern JavaScript specification and its concept of realms . We expect that as the Web IDL specification gets updated, every platform object will have a Realm associated with it, and this definition can be re-cast in those terms. [JAVASCRIPT] [WEBIDL]
Then, the relevant Realm for a platform object is the Realm of its relevant settings object .
Similarly, the relevant global object for a platform object is the global object of its relevant settings object .
Although
the
JavaScript
specification
does
not
account
for
this
possibility,
it's
sometimes
necessary
to
abort
a
running
script
.
This
causes
any
ScriptEvaluation
or
Source
Text
Module
Record
Evaluate
invocations
to
cease
immediately,
emptying
the
JavaScript
execution
context
stack
without
triggering
any
of
the
normal
mechanisms
like
finally
blocks.
[JAVASCRIPT]
User
agents
may
impose
resource
limitations
on
scripts,
for
example
CPU
quotas,
memory
limits,
total
execution
time
limits,
or
bandwidth
limitations.
When
a
script
exceeds
a
limit,
the
user
agent
may
either
throw
a
"
QuotaExceededError
"
DOMException
,
abort
the
script
without
an
exception,
prompt
the
user,
or
throttle
script
execution.
For example, the following script never terminates. A user agent could, after waiting for a few seconds, prompt the user to either terminate the script or let it continue.
<script> while (true) { /* loop */ } </script>
User
agents
are
encouraged
to
allow
users
to
disable
scripting
whenever
the
user
is
prompted
either
by
a
script
(e.g.
using
the
window.alert()
API)
or
because
of
a
script's
actions
(e.g.
because
it
has
exceeded
a
time
limit).
If scripting is disabled while a script is executing, the script should be terminated immediately.
User agents may allow users to specifically disable scripts just for the purposes of closing a browsing context .
For
example,
the
prompt
mentioned
in
the
example
above
could
also
offer
the
user
with
a
mechanism
to
just
close
the
page
entirely,
without
running
any
unload
event
handlers.
The JavaScript specification defines the JavaScript job and job queue abstractions in order to specify certain invariants about how promise operations execute with a clean JavaScript execution context stack and in a certain order. However, as of the time of this writing the definition of EnqueueJob in that specification is not sufficiently flexible to integrate with HTML as a host environment. [JAVASCRIPT]
This is not strictly true. It is in fact possible, by taking liberal advantage of the many "implementation defined" sections of the algorithm, to contort it to our purposes. However, the end result is a mass of messy indirection and workarounds that essentially bypasses the job queue infrastructure entirely, albeit in a way that is technically sanctioned within the bounds of implementation-defined behavior. We do not take this path, and instead introduce the following willful violation .
As such, user agents must instead use the following definition in place of that in the JavaScript specification. These ensure that the promise jobs enqueued by the JavaScript specification are properly integrated into the user agent's event loops .
The RunJobs abstract operation from the JavaScript specification must not be used by user agents.
When the JavaScript specification says to call the EnqueueJob abstract operation, the following algorithm must be used in place of JavaScript's EnqueueJob :
Assert:
queueName
is
"PromiseJobs"
.
(
"ScriptJobs"
must
not
be
used
by
user
agents.)
Let job settings be some appropriate environment settings object .
It is not yet clear how to specify the environment settings object that should be used here. In practice, this means that the entry concept is not correctly specified while executing a job. See discussion in issue #1189 .
Let incumbent settings be the incumbent settings object .
Let active script be the active script .
Assert: active script is not null, as jobs are only enqueued by the JavaScript specification while a script is active.
Let script execution context be a new JavaScript execution context , with its Function field set to null, its Realm field set to active script 's settings object 's Realm , and its ScriptOrModule set to active script 's record .
Queue a microtask , on job settings 's responsible event loop , to perform the following steps:
Check if we can run script with job settings . If this returns "do not run" then return.
Prepare to run script with job settings .
This affects the entry concept while the job runs.
Prepare to run a callback with incumbent settings .
This affects the incumbent concept while the job runs.
Push script execution context onto the JavaScript execution context stack .
This
affects
the
active
script
while
the
job
runs,
in
cases
like
Promise.resolve("...").then(eval)
where
there
would
otherwise
be
no
active
script
since
eval()
is
a
built-in
function
that
does
not
originate
from
any
particular
script
.
Let result be the result of performing the abstract operation specified by job , using the elements of arguments as its arguments.
Pop script execution context from the JavaScript execution context stack .
Clean up after running a callback with incumbent settings .
Clean up after running script with job settings .
If result is an abrupt completion, report the exception given by result .[[Value]].
The
JavaScript
specification
defines
a
syntax
for
modules,
as
well
as
some
host-agnostic
parts
of
their
processing
model.
This
specification
defines
the
rest
of
their
processing
model:
how
the
module
system
is
bootstrapped,
via
the
script
element
with
type
attribute
set
to
"
module
",
and
how
modules
are
fetched,
resolved,
and
executed.
[JAVASCRIPT]
Although
the
JavaScript
specification
speaks
in
terms
of
"scripts"
versus
"modules",
in
general
this
specification
speaks
in
terms
of
classic
scripts
versus
module
scripts
,
since
both
of
them
use
the
script
element.
A
module
map
is
a
map
of
URL
records
to
values
that
are
either
a
module
script
,
null
(used
to
represent
failed
fetches),
or
a
placeholder
value
"
fetching
".
Module
maps
are
used
to
ensure
that
imported
JavaScript
modules
are
only
fetched,
parsed,
and
evaluated
once
per
Document
or
worker
.
Since module maps are keyed by URL, the following code will create three separate entries in the module map , since it results in three different URLs:
import "https://example.com/module.js"; import "https://example.com/module.js#map-buster"; import "https://example.com/module.js?debug=true";
That is, URL queries and fragments can be varied to create distinct entries in the module map ; they are not ignored. Thus, three separate fetches and three separate module evaluations will be performed.
In contrast, the following code would only create a single entry in the module map , since after applying the URL parser to these inputs, the resulting URL records are equal:
import "https://example.com/module2.js"; import "https:example.com/module2.js"; import "https://///example.com\\module2.js"; import "https://example.com/foo/../module2.js";
So in this second example, only one fetch and one module evaluation will occur.
Note that this behavior is the same as how shared workers are keyed by their parsed constructor url .
To resolve a module specifier given a script script and a JavaScript string specifier , perform the following steps. It will return either a URL record or failure.
Apply the URL parser to specifier . If the result is not failure, return the result.
If
specifier
does
not
start
with
the
character
U+002F
SOLIDUS
(
/
),
the
two-character
sequence
U+002E
FULL
STOP,
U+002F
SOLIDUS
(
./
),
or
the
three-character
sequence
U+002E
FULL
STOP,
U+002E
FULL
STOP,
U+002F
SOLIDUS
(
../
),
return
failure.
This
restriction
is
in
place
so
that
in
the
future
we
can
allow
custom
module
loaders
to
give
special
meaning
to
"bare"
import
specifiers,
like
import
"jquery"
or
import
"web/crypto"
.
For
now
any
such
imports
will
fail,
instead
of
being
treated
as
relative
URLs.
Return the result of applying the URL parser to specifier with script 's base URL as the base URL.
The following are valid module specifiers according to the above algorithm:
https://example.com/apples.js
http:example.com\pears.mjs
(becomes
http://example.com/pears.mjs
as
step
1
parses
with
no
base
URL)
//example.com/bananas
./strawberries.js.cgi
../lychees
/limes.jsx
data:text/javascript,export
default
'grapes';
blob:https://whatwg.org/d0360e2f-caee-469f-9a2f-87d5b0456f6f
The following are valid module specifiers according to the above algorithm, but will invariably cause failures when they are fetched :
javascript:export
default
'artichokes';
data:text/plain,export
default
'kale';
about:legumes
wss://example.com/celery
The following are not valid module specifiers according to the above algorithm:
https://eggplant:b/c
pumpkins.js
.tomato
..zucchini.js
.\yam.es
JavaScript contains an implementation-defined HostResolveImportedModule abstract operation, very slightly updated by the import() proposal. User agents must use the following implementation: [JAVASCRIPT] [JSIMPORT]
Let referencing script be referencingScriptOrModule .[[HostDefined]].
Let moduleMap be referencing script 's settings object 's module map .
Let url be the result of resolving a module specifier given referencing script and specifier .
Assert: url is never failure, because resolving a module specifier must have been previously successful with these same two arguments.
Let resolved module script be moduleMap [ url ]. (This entry must exist for us to have gotten to this point.)
Assert:
resolved
module
script
is
a
module
script
(i.e.,
is
not
null
or
"
fetching
").
Assert: resolved module script 's record is not null.
Return resolved module script 's record .
The import() proposal contains an implementation-defined HostImportModuleDynamically abstract operation. User agents must use the following implementation: [JSIMPORT]
Let referencing script be referencingScriptOrModule .[[HostDefined]].
Run the following steps in parallel :
Let url be the result of resolving a module specifier given referencing script and specifier .
If url is failure, then:
Let
completion
be
Completion
{
[[Type]]:
throw,
[[Value]]:
a
new
TypeError
,
[[Target]]:
empty
}.
Perform FinishDynamicImport ( referencingScriptOrModule , specifier , promiseCapability , completion ).
Return.
Let options be the descendant script fetch options for referencing script 's fetch options .
Fetch
a
module
script
graph
given
url
,
settings
object
,
"
script
",
and
options
.
Wait
until
the
algorithm
asynchronously
completes
with
result
.
If result is null, then:
Let
completion
be
Completion
{
[[Type]]:
throw,
[[Value]]:
a
new
TypeError
,
[[Target]]:
empty
}.
Perform FinishDynamicImport ( referencingScriptOrModule , specifier , promiseCapability , completion ).
Return.
Run the module script result , with the rethrow errors boolean set to true.
If running the module script throws an exception, then perform FinishDynamicImport ( referencingScriptOrModule , specifier , promiseCapability , the thrown exception completion).
Otherwise, perform FinishDynamicImport ( referencingScriptOrModule , specifier , promiseCapability , NormalCompletion (undefined)).
Return undefined.
The import.meta proposal contains an implementation-defined HostGetImportMetaProperties abstract operation. User agents must use the following implementation: [JSIMPORTMETA]
Let module script be moduleRecord .[[HostDefined]].
Let urlString be module script 's base URL , serialized .
Return « Record { [[Key]]: "url", [[Value]]: urlString } ».
JavaScript defines the concept of an agent . Until such a time that this standard has a better handle on lifetimes, we define five types of agents that user agents must allocate at the appropriate time.
In the future, when this specification has a better handle on lifetimes, we hope to define exactly when agents and agent clusters are created.
JavaScript is expected to define agents in more detail; in particular that they hold a set of realms : tc39/ecma262 issue #882 .
An
agent
whose
[[CanBlock]]
is
false
and
whose
set
of
realms
consists
of
all
realms
of
Window
objects
whose
relevant
settings
object
's
responsible
browsing
context
is
in
the
same
unit
of
related
similar-origin
browsing
contexts
.
Two
Window
objects
that
are
same
origin
can
be
in
different
similar-origin
window
agents
,
for
instance
if
they
are
each
in
their
own
unit
of
related
similar-origin
browsing
contexts
.
An
agent
whose
[[CanBlock]]
is
true
and
whose
set
of
realms
consists
of
a
single
DedicatedWorkerGlobalScope
object's
Realm
.
An
agent
whose
[[CanBlock]]
is
true
and
whose
set
of
realms
consists
a
single
SharedWorkerGlobalScope
object's
Realm
.
An
agent
whose
[[CanBlock]]
is
false
and
whose
set
of
realms
consists
of
a
single
ServiceWorkerGlobalScope
object's
Realm
.
An
agent
whose
[[CanBlock]]
is
false
and
whose
set
of
realms
consists
of
a
single
WorkletGlobalScope
object's
Realm
.
While conceptually it might be cleaner for worklets that end up with multiple realms to put all those in the same agent, it is not observable in practice.
Can share memory with defines an equivalence relation. An agent cluster consists of all agents in the same equivalence class with respect to the can share memory with equivalence relation.
A similar-origin window agent , dedicated worker agent , shared worker agent , or service worker agent , agent , can share memory with any dedicated worker agent whose single realm 's global object 's owner set contains an item whose relevant Realm belongs to agent .
We
use
item
above
as
an
owner
set
can
contain
Document
objects.
A worklet agent … currently worklets have no clearly defined owner, see: w3c/css-houdini-drafts issue #224 .
In addition, any agent A can share memory with :
The
agent
cluster
concept
is
crucial
for
defining
the
JavaScript
memory
model,
and
in
particular
among
which
agents
the
backing
data
of
SharedArrayBuffer
objects
can
be
shared.
The
following
pairs
of
global
objects
are
each
within
the
same
agent
cluster
,
and
thus
can
use
SharedArrayBuffer
instances
to
share
memory
with
each
other:
Window
object
and
a
dedicated
worker
that
it
created.
Window
object
A
and
the
Window
object
of
an
iframe
element
that
A
created
that
could
be
same
origin-domain
with
A
.
Window
object
and
a
same
origin-domain
Window
object
that
opened
it.
The following pairs of global objects are not within the same agent cluster , and thus cannot share memory:
When the user agent is required to report an error for a particular script script with a particular position line : col , using a particular target target , it must run these steps, after which the error is either handled or not handled :
If target is in error reporting mode , then return; the error is not handled .
Let target be in error reporting mode .
Let message be a user-agent-defined string describing the error in a helpful manner.
Let
errorValue
be
the
value
that
represents
the
error:
in
the
case
of
an
uncaught
exception,
that
would
be
the
value
that
was
thrown;
in
the
case
of
a
JavaScript
error
that
would
be
an
Error
object.
If
there
is
no
corresponding
value,
then
the
null
value
must
be
used
instead.
Let urlString be the result of applying the URL serializer to the URL record that corresponds to the resource from which script was obtained.
The
resource
containing
the
script
will
typically
be
the
file
from
which
the
Document
was
parsed,
e.g.
for
inline
script
elements
or
event
handler
content
attributes
;
or
the
JavaScript
file
that
the
script
was
in,
for
external
scripts.
Even
for
dynamically-generated
scripts,
user
agents
are
strongly
encouraged
to
attempt
to
keep
track
of
the
original
source
of
a
script.
For
example,
if
an
external
script
uses
the
document.write()
API
to
insert
an
inline
script
element
during
parsing,
the
URL
of
the
resource
containing
the
script
would
ideally
be
reported
as
being
the
external
script,
and
the
line
number
might
ideally
be
reported
as
the
line
with
the
document.write()
call
or
where
the
string
passed
to
that
call
was
first
constructed.
Naturally,
implementing
this
can
be
somewhat
non-trivial.
User
agents
are
similarly
encouraged
to
keep
careful
track
of
the
original
line
numbers,
even
in
the
face
of
document.write()
calls
mutating
the
document
as
it
is
parsed,
or
event
handler
content
attributes
spanning
multiple
lines.
If
script
's
muted
errors
is
true,
then
set
message
to
"
Script
error.
",
urlString
to
the
empty
string,
line
and
col
to
0,
and
errorValue
to
null.
Let
notHandled
be
the
result
of
firing
an
event
named
error
at
target
,
using
ErrorEvent
,
with
the
cancelable
attribute
initialized
to
true,
the
message
attribute
initialized
to
message
,
the
filename
attribute
initialized
to
urlString
,
the
lineno
attribute
initialized
to
line
,
the
colno
attribute
initialized
to
col
,
and
the
error
attribute
initialized
to
errorValue
.
Let target no longer be in error reporting mode .
If notHandled is false, then the error is handled . Otherwise, the error is not handled .
Returning true in an event handler cancels the event per the event handler processing algorithm .
When the user agent is to report an exception E , the user agent must report the error for the relevant script , with the problematic position (line number and column number) in the resource containing the script, using the global object specified by the script's settings object as the target. If the error is still not handled after this, then the error may be reported to a developer console.
ErrorEvent
interface
[Constructor(DOMString type, optional ErrorEventInit eventInitDict), Exposed=(Window,Worker)] interface ErrorEvent : Event { readonly attribute DOMString message; readonly attribute USVString filename; readonly attribute unsigned long lineno; readonly attribute unsigned long colno; readonly attribute any error; }; dictionary ErrorEventInit : EventInit { DOMString message = ""; USVString filename = ""; unsigned long lineno = 0; unsigned long colno = 0; any error = null; };
The
message
attribute
must
return
the
value
it
was
initialized
to.
It
represents
the
error
message.
The
filename
attribute
must
return
the
value
it
was
initialized
to.
It
represents
the
URL
of
the
script
in
which
the
error
originally
occurred.
The
lineno
attribute
must
return
the
value
it
was
initialized
to.
It
represents
the
line
number
where
the
error
occurred
in
the
script.
The
colno
attribute
must
return
the
value
it
was
initialized
to.
It
represents
the
column
number
where
the
error
occurred
in
the
script.
The
error
attribute
must
return
the
value
it
was
initialized
to.
Where
appropriate,
it
is
set
to
the
object
representing
the
error
(e.g.,
the
exception
object
in
the
case
of
an
uncaught
DOM
exception).
In
addition
to
synchronous
runtime
script
errors
,
scripts
may
experience
asynchronous
promise
rejections,
tracked
via
the
unhandledrejection
and
rejectionhandled
events.
Support: unhandledrejection Chrome for Android 64+ Chrome 49+ iOS Safari None UC Browser for Android 11.8+ Firefox None IE None Samsung Internet 5+ Opera Mini None Safari 11+ Edge None Android Browser 62+ Opera 36+
Source: caniuse.com
When the user agent is to notify about rejected promises on a given environment settings object settings object , it must run these steps:
Let list be a copy of settings object 's about-to-be-notified rejected promises list .
If list is empty, return.
Clear settings object 's about-to-be-notified rejected promises list .
Queue a task to run the following substep:
For each promise p in list :
If p 's [[PromiseIsHandled]] internal slot is true, continue to the next iteration of the loop.
Let
notHandled
be
the
result
of
firing
an
event
named
unhandledrejection
at
settings
object
's
global
object
,
using
PromiseRejectionEvent
,
with
the
cancelable
attribute
initialized
to
true,
the
promise
attribute
initialized
to
p
,
and
the
reason
attribute
initialized
to
the
value
of
p
's
[[PromiseResult]]
internal
slot.
If notHandled is false, then the promise rejection is handled . Otherwise, the promise rejection is not handled .
If p 's [[PromiseIsHandled]] internal slot is false, add p to settings object 's outstanding rejected promises weak set .
This algorithm results in promise rejections being marked as handled or not handled . These concepts parallel handled and not handled script errors. If a rejection is still not handled after this, then the rejection may be reported to a developer console.
JavaScript contains an implementation-defined HostPromiseRejectionTracker ( promise , operation ) abstract operation. User agents must use the following implementation: [JAVASCRIPT]
Let script be the running script .
If script 's muted errors is true, terminate these steps.
Let settings object be script 's settings object .
If
operation
is
"reject"
,
Add promise to settings object 's about-to-be-notified rejected promises list .
If
operation
is
"handle"
,
If settings object 's about-to-be-notified rejected promises list contains promise , then remove promise from that list and return.
If settings object 's outstanding rejected promises weak set does not contain promise , then return.
Remove promise from settings object 's outstanding rejected promises weak set .
Queue
a
task
to
fire
an
event
named
rejectionhandled
at
settings
object
's
global
object
,
using
PromiseRejectionEvent
,
with
the
promise
attribute
initialized
to
promise
,
and
the
reason
attribute
initialized
to
the
value
of
promise
's
[[PromiseResult]]
internal
slot.
PromiseRejectionEvent
interface
[Constructor(DOMString type, PromiseRejectionEventInit eventInitDict), Exposed=(Window,Worker)] interface PromiseRejectionEvent : Event { readonly attribute Promise<any> promise; readonly attribute any reason; }; dictionary PromiseRejectionEventInit : EventInit { required Promise<any> promise; any reason; };
The
promise
attribute
must
return
the
value
it
was
initialized
to.
It
represents
the
promise
which
this
notification
is
about.
The
reason
attribute
must
return
the
value
it
was
initialized
to.
It
represents
the
rejection
reason
for
the
promise.
JavaScript contains an implementation-defined HostEnsureCanCompileStrings ( callerRealm , calleeRealm ) abstract operation. User agents must use the following implementation: [JAVASCRIPT]
Perform ? EnsureCSPDoesNotBlockStringCompilation ( callerRealm , calleeRealm ). [CSP]
To coordinate events, user interaction, scripts, rendering, networking, and so forth, user agents must use event loops as described in this section. There are two kinds of event loops: those for browsing contexts , and those for workers .
There must be at least one browsing context event loop per user agent, and at most one per unit of related similar-origin browsing contexts .
When there is more than one event loop for a unit of related browsing contexts , complications arise when a browsing context in that group is navigated such that it switches from one unit of related similar-origin browsing contexts to another. This specification does not currently describe how to handle these complications.
A browsing context event loop always has at least one browsing context . If such an event loop 's browsing contexts all go away, then the event loop goes away as well. A browsing context always has an event loop coordinating its activities.
Worker event loops are simpler: each worker has one event loop , and the worker processing model manages the event loop 's lifetime.
An event loop has one or more task queues . A task queue is an ordered list of tasks , which are algorithms that are responsible for such work as:
Dispatching
an
Event
object
at
a
particular
EventTarget
object
is
often
done
by
a
dedicated
task.
Not all events are dispatched using the task queue , many are dispatched during other tasks.
The HTML parser tokenizing one or more bytes, and then processing any resulting tokens, is typically a task.
Calling a callback is often done by a dedicated task.
When an algorithm fetches a resource, if the fetching occurs in a non-blocking fashion then the processing of the resource once some or all of the resource is available is performed by a task.
Some elements have tasks that trigger in response to DOM manipulation, e.g. when that element is inserted into the document .
Each
task
in
a
browsing
context
event
loop
is
associated
with
a
Document
;
if
the
task
was
queued
in
the
context
of
an
element,
then
it
is
the
element's
node
document
;
if
the
task
was
queued
in
the
context
of
a
browsing
context
,
then
it
is
the
browsing
context
's
active
document
at
the
time
the
task
was
queued;
if
the
task
was
queued
by
or
for
a
script
then
the
document
is
the
responsible
document
specified
by
the
script's
settings
object
.
A
task
is
intended
for
a
specific
event
loop
:
the
event
loop
that
is
handling
tasks
for
the
task
's
associated
Document
or
worker
.
When a user agent is to queue a task , it must add the given task to one of the task queues of the relevant event loop .
Each
task
is
defined
as
coming
from
a
specific
task
source
.
All
the
tasks
from
one
particular
task
source
and
destined
to
a
particular
event
loop
(e.g.
the
callbacks
generated
by
timers
of
a
Document
,
the
events
fired
for
mouse
movements
over
that
Document
,
the
tasks
queued
for
the
parser
of
that
Document
)
must
always
be
added
to
the
same
task
queue
,
but
tasks
from
different
task
sources
may
be
placed
in
different
task
queues
.
For example, a user agent could have one task queue for mouse and key events (the user interaction task source ), and another for everything else. The user agent could then give keyboard and mouse events preference over other tasks three quarters of the time, keeping the interface responsive but not starving other task queues, and never processing events from any one task source out of order.
Each event loop has a currently running task . Initially, this is null. It is used to handle reentrancy. Each event loop also has a performing a microtask checkpoint flag, which must initially be false. It is used to prevent reentrant invocation of the perform a microtask checkpoint algorithm.
An event loop must continually run through the following steps for as long as it exists:
Let
oldestTask
be
the
oldest
task
on
one
of
the
event
loop
's
task
queues
,
if
any,
ignoring,
in
the
case
of
a
browsing
context
event
loop
,
tasks
whose
associated
Document
s
are
not
fully
active
.
The
user
agent
may
pick
any
task
queue
.
If
there
is
no
task
to
select,
then
jump
to
the
microtasks
step
below.
Set the event loop 's currently running task to oldestTask .
Run oldestTask .
Set the event loop 's currently running task back to null.
Remove oldestTask from its task queue .
Microtasks : Perform a microtask checkpoint .
Update the rendering : If this event loop is a browsing context event loop (as opposed to a worker event loop ), then run the following substeps.
Let
now
be
the
value
that
would
be
returned
by
the
Performance
object's
now()
method.
[HRT]
Let
docs
be
the
list
of
Document
objects
associated
with
the
event
loop
in
question,
sorted
arbitrarily
except
that
the
following
conditions
must
be
met:
Any
Document
B
that
is
nested
through
a
Document
A
must
be
listed
after
A
in
the
list.
If
there
are
two
documents
A
and
B
whose
browsing
contexts
are
both
nested
browsing
contexts
and
their
browsing
context
containers
are
both
elements
in
the
same
Document
C
,
then
the
order
of
A
and
B
in
the
list
must
match
the
relative
tree
order
of
their
respective
browsing
context
containers
in
C
.
In
the
steps
below
that
iterate
over
docs
,
each
Document
must
be
processed
in
the
order
it
is
found
in
the
list.
If
there
are
top-level
browsing
contexts
B
that
the
user
agent
believes
would
not
benefit
from
having
their
rendering
updated
at
this
time,
then
remove
from
docs
all
Document
objects
whose
browsing
context
's
top-level
browsing
context
is
in
B
.
Whether
a
top-level
browsing
context
would
benefit
from
having
its
rendering
updated
depends
on
various
factors,
such
as
the
update
frequency.
For
example,
if
the
browser
is
attempting
to
achieve
a
60Hz
refresh
rate,
then
these
steps
are
only
necessary
every
60th
of
a
second
(about
16.7ms).
If
the
browser
finds
that
a
top-level
browsing
context
is
not
able
to
sustain
this
rate,
it
might
drop
to
a
more
sustainable
30Hz
for
that
set
of
Document
s,
rather
than
occasionally
dropping
frames.
(This
specification
does
not
mandate
any
particular
model
for
when
to
update
the
rendering.)
Similarly,
if
a
top-level
browsing
context
is
in
the
background,
the
user
agent
might
decide
to
drop
that
page
to
a
much
slower
4Hz,
or
even
less.
Another example of why a browser might skip updating the rendering is to ensure certain tasks are executed immediately after each other, with only microtask checkpoints interleaved (and without, e.g., animation frame callbacks interleaved). For example, a user agent might wish to coalesce timer callbacks together, with no intermediate rendering updates.
If
there
are
a
nested
browsing
contexts
B
that
the
user
agent
believes
would
not
benefit
from
having
their
rendering
updated
at
this
time,
then
remove
from
docs
all
Document
objects
whose
browsing
context
is
in
B
.
As with top-level browsing contexts , a variety of factors can influence whether it is profitable for a browser to update the rendering of nested browsing contexts . For example, a user agent might wish to spend less resources rendering third-party content, especially if it is not currently visible to the user or if resources are constrained. In such cases, the browser could decide to update the rendering for such content infrequently or never.
For
each
fully
active
Document
in
docs
,
run
the
resize
steps
for
that
Document
,
passing
in
now
as
the
timestamp.
[CSSOMVIEW]
For
each
fully
active
Document
in
docs
,
run
the
scroll
steps
for
that
Document
,
passing
in
now
as
the
timestamp.
[CSSOMVIEW]
For
each
fully
active
Document
in
docs
,
evaluate
media
queries
and
report
changes
for
that
Document
,
passing
in
now
as
the
timestamp.
[CSSOMVIEW]
For
each
fully
active
Document
in
docs
,
update
animations
and
send
events
for
that
Document
,
passing
in
now
as
the
timestamp.
[WEBANIMATIONS]
For
each
fully
active
Document
in
docs
,
run
the
fullscreen
steps
for
that
Document
,
passing
in
now
as
the
timestamp.
[FULLSCREEN]
For
each
fully
active
Document
in
docs
,
run
the
animation
frame
callbacks
for
that
Document
,
passing
in
now
as
the
timestamp.
For
each
fully
active
Document
in
docs
,
run
the
update
intersection
observations
steps
for
that
Document
,
passing
in
now
as
the
timestamp.
[INTERSECTIONOBSERVER]
For
each
fully
active
Document
in
docs
,
update
the
rendering
or
user
interface
of
that
Document
and
its
browsing
context
to
reflect
the
current
state.
If
this
is
a
worker
event
loop
(i.e.
one
running
for
a
WorkerGlobalScope
),
but
there
are
no
tasks
in
the
event
loop
's
task
queues
and
the
WorkerGlobalScope
object's
closing
flag
is
true,
then
destroy
the
event
loop
,
aborting
these
steps,
resuming
the
run
a
worker
steps
described
in
the
Web
workers
section
below.
Each event loop has a microtask queue . A microtask is a task that is originally to be queued on the microtask queue rather than a task queue . There are two kinds of microtasks : solitary callback microtasks , and compound microtasks .
This specification only has solitary callback microtasks . Specifications that use compound microtasks have to take extra care to wrap callbacks to handle spinning the event loop .
When an algorithm requires a microtask to be queued , it must be appended to the relevant event loop 's microtask queue ; the task source of such a microtask is the microtask task source .
It is possible for a microtask to be moved to a regular task queue , if, during its initial execution, it spins the event loop . In that case, the microtask task source is the task source used. Normally, the task source of a microtask is irrelevant.
When a user agent is to perform a microtask checkpoint , if the performing a microtask checkpoint flag is false, then the user agent must run the following steps:
Set the performing a microtask checkpoint flag to true.
While the event loop 's microtask queue is not empty:
Let oldestMicrotask be the oldest microtask on the event loop 's microtask queue .
Set the event loop 's currently running task to oldestMicrotask .
Run oldestMicrotask .
This might involve invoking scripted callbacks, which eventually calls the clean up after running script steps, which call this perform a microtask checkpoint algorithm again, which is why we use the performing a microtask checkpoint flag to avoid reentrancy.
Set the event loop 's currently running task back to null.
Remove oldestMicrotask from the microtask queue .
For each environment settings object whose responsible event loop is this event loop , notify about rejected promises on that environment settings object .
Set the performing a microtask checkpoint flag to false.
If, while a compound microtask is running, the user agent is required to execute a compound microtask subtask to run a series of steps, the user agent must run the following steps:
Let parent be the event loop 's currently running task (the currently running compound microtask ).
Let subtask be a new task that consists of running the given series of steps. The task source of such a microtask is the microtask task source . This is a compound microtask subtask .
Set the event loop 's currently running task to subtask .
Run subtask .
Set the event loop 's currently running task back to parent .
When an algorithm running in parallel is to await a stable state , the user agent must queue a microtask that runs the following steps, and must then stop executing (execution of the algorithm resumes when the microtask is run, as described in the following steps):
Run the algorithm's synchronous section .
Resumes execution of the algorithm in parallel , if appropriate, as described in the algorithm's steps.
Steps in synchronous sections are marked with ⌛.
When an algorithm says to spin the event loop until a condition goal is met, the user agent must run the following steps:
Let task be the event loop 's currently running task .
This might be a microtask , in which case it is a solitary callback microtask . It could also be a compound microtask subtask , or a regular task that is not a microtask . It will not be a compound microtask .
Let task source be task 's task source .
Let old stack be a copy of the JavaScript execution context stack .
Empty the JavaScript execution context stack .
Stop task , allowing whatever algorithm that invoked it to resume, but continue these steps in parallel .
This causes one of the following algorithms to continue: the event loop 's main set of steps, the perform a microtask checkpoint algorithm, or the execute a compound microtask subtask algorithm.
Wait until the condition goal is met.
Queue a task to continue running these steps, using the task source task source . Wait until this new task runs before continuing these steps.
Replace the JavaScript execution context stack with the old stack .
Return to the caller.
Some of the algorithms in this specification, for historical reasons, require the user agent to pause while running a task until a condition goal is met. This means running the following steps:
If
necessary,
update
the
rendering
or
user
interface
of
any
Document
or
browsing
context
to
reflect
the
current
state.
Wait until the condition goal is met. While a user agent has a paused task , the corresponding event loop must not run further tasks , and any script in the currently running task must block. User agents should remain responsive to user input while paused, however, albeit in a reduced capacity since the event loop will not be doing anything.
Pausing is highly detrimental to the user experience, especially in scenarios where a single event loop is shared among multiple documents. User agents are encouraged to experiment with alternatives to pausing , such as spinning the event loop or even simply proceeding without any kind of suspended execution at all, insofar as it is possible to do so while preserving compatibility with existing content. This specification will happily change if a less-drastic alternative is discovered to be web-compatible.
In the interim, implementers should be aware that the variety of alternatives that user agents might experiment with can change subtle aspects of event loop behavior, including task and microtask timing. Implementations should continue experimenting even if doing so causes them to violate the exact semantics implied by the pause operation.
The following task sources are used by a number of mostly unrelated features in this and other specifications.
This task source is used for features that react to DOM manipulations, such as things that happen in a non-blocking fashion when an element is inserted into the document .
This task source is used for features that react to user interaction, for example keyboard or mouse input.
Events
sent
in
response
to
user
input
(e.g.
click
events)
must
be
fired
using
tasks
queued
with
the
user
interaction
task
source
.
[UIEVENTS]
This task source is used for features that trigger in response to network activity.
This
task
source
is
used
to
queue
calls
to
history.back()
and
similar
APIs.
Writing specifications that correctly interact with the event loop can be tricky. This is compounded by how this specification uses concurrency-model-independent terminology, so we say things like " event loop " and " in parallel " instead of using more familiar model-specific terms like "main thread" or "on a background thread".
By default, specification text generally runs on the event loop . This falls out from the formal event loop processing model , in that you can eventually trace most algorithms back to a task queued there.
The
algorithm
steps
for
any
JavaScript
method
will
be
invoked
by
author
code
calling
that
method.
And
author
code
can
only
be
run
via
queued
tasks,
usually
originating
somewhere
in
the
script
processing
model
.
From this starting point, the overriding guideline is that any work a specification needs to perform that would otherwise block the event loop must instead be performed in parallel with it. This includes (but is not limited to):
performing heavy computation;
displaying a user-facing prompt;
performing operations which could require involving outside systems (i.e. "going out of process").
The next complication is that, in algorithm sections that are in parallel , you must not create or manipulate objects associated to a specific JavaScript realm , global , or environment settings object . (Stated in more familiar terms, you must not directly access main-thread artifacts from a background thread.) Doing so would create data races observable to JavaScript code, since after all, your algorithm steps are running in parallel to the JavaScript code.
You can, however, manipulate specification-level data structures and values from the WHATWG Infra Standard, as those are realm-agnostic. They are never directly exposed to JavaScript without a specific conversion taking place (often via Web IDL ). [INFRA] [WEBIDL]
To affect the world of observable JavaScript objects, then, you must queue a task to perform any such manipulations. This ensures your steps are properly interleaved with respect to other things happening on the event loop . Furthermore, you must choose a task source when queueing a task ; this governs the relative order of your steps versus others. If you are unsure which task source to use, pick one of the generic task sources that sounds most applicable.
Most invocations of queue a task implicitly use "the relevant event loop ", i.e., the one that is obvious from context. That is because it is very rare for algorithms to be invoked in contexts involving multiple event loops. (Unlike contexts involving multiple global objects, which happen all the time!) So unless you are writing a specification which, e.g., deals with manipulating workers , you can omit this argument when queueing a task .
Putting this all together, we can provide a template for a typical algorithm that needs to do work asynchronously:
Do any synchronous setup work, while still on the event loop . This may include converting realm -specific JavaScript values into realm-agnostic specification-level values.
Perform a set of potentially-expensive steps in parallel , operating entirely on realm-agnostic values, and producing a realm-agnostic result.
Queue a task , on a specified task source , to convert the realm-agnostic result back into observable effects on the observable world of JavaScript objects on the event loop .
The following is an algorithm that "encrypts" a passed-in list of scalar value strings input , after parsing them as URLs:
Let urls be an empty list .
For each string of input :
Let parsed be the result of parsing string relative to the current settings object .
If
parsed
is
failure,
return
a
promise
rejected
with
a
"
SyntaxError
"
DOMException
.
Let serialized be the result of applying the URL serializer to parsed .
Append serialized to urls .
Let realm be the current Realm Record .
Let p be a new promise.
Run the following steps in parallel :
Let encryptedURLs be an empty list .
For each url of urls :
Wait 100 milliseconds, so that people think we're doing heavy-duty encryption.
Let encrypted be a new JavaScript string derived from url , whose n th code unit is equal to url 's n th code unit plus 13.
Append encrypted to encryptedURLs .
Queue a task , on the networking task source , to perform the following steps:
Let array be the result of converting encryptedURLs to a JavaScript array, in realm .
Resolve p with array .
Return p .
Here are several things to notice about this algorithm:
It does its URL parsing up front, on the event loop , before going to the in parallel steps. This is necessary, since parsing depends on the current settings object , which would no longer be current after going in parallel .
Alternately, it could have saved a reference to the current settings object 's API base URL and used it during the in parallel steps; that would have been equivalent. However, we recommend instead doing as much work as possible up front, as this example does. Attempting to save the correct values can be error prone; for example, if we'd saved just the current settings object , instead of its API base URL , there would have been a potential race.
It implicitly passes a list of JavaScript strings from the initial steps to the in parallel steps. This is OK, as both lists and JavaScript strings are realm -agnostic.
It performs "expensive computation" (waiting for 100 milliseconds per input URL) during the in parallel steps, thus not blocking the main event loop .
Promises, as observable JavaScript objects, are never created and manipulated during the in parallel steps. p is created before entering those steps, and then is manipulated during a task that is queued specifically for that purpose.
The creation of a JavaScript array object also happens during the queued task, and is careful to specify which realm it creates the array in since that is no longer obvious from context.
(On these last two points, see also w3ctag/promises-guide#52 , heycam/webidl#135 , and heycam/webidl#371 , where we are still mulling over the subtleties of the above promise-resolution pattern.)
Another
thing
to
note
is
that,
in
the
event
this
algorithm
was
called
from
a
Web
IDL-specified
operation
taking
a
sequence
<
USVString
>,
there
was
an
automatic
conversion
from
realm
-specific
JavaScript
objects
provided
by
the
author
as
input,
into
the
realm-agnostic
sequence
<
USVString
>
Web
IDL
type,
which
we
then
treat
as
a
list
of
scalar
value
strings
.
So
depending
on
how
your
specification
is
structured,
there
may
be
other
implicit
steps
happening
on
the
main
event
loop
that
play
a
part
in
this
whole
process
of
getting
you
ready
to
go
in
parallel
.
Many objects can have event handlers specified. These act as non-capture event listeners for the object on which they are specified. [DOM]
An
event
handler
has
a
name,
which
always
starts
with
"
on
"
and
is
followed
by
the
name
of
the
event
for
which
it
is
intended.
An
event
handler
has
a
value,
which
is
either
null,
or
is
a
callback
object,
or
is
an
internal
raw
uncompiled
handler
.
The
EventHandler
callback
function
type
describes
how
this
is
exposed
to
scripts.
Initially,
an
event
handler
's
value
must
be
set
to
null.
Event handlers are exposed in one of two ways.
The first way, common to all event handlers, is as an event handler IDL attribute .
The
second
way
is
as
an
event
handler
content
attribute
.
Event
handlers
on
HTML
elements
and
some
of
the
event
handlers
on
Window
objects
are
exposed
in
this
way.
An event handler IDL attribute is an IDL attribute for a specific event handler . The name of the IDL attribute is the same as the name of the event handler .
Event handler IDL attributes , on setting, must set the corresponding event handler to their new value, and on getting, must return the result of getting the current value of the event handler in question.
If an event handler IDL attribute exposes an event handler of an object that doesn't exist, it must always return null on getting and must do nothing on setting.
This
can
happen
in
particular
for
event
handler
IDL
attribute
on
body
elements
that
do
not
have
corresponding
Window
objects.
Certain
event
handler
IDL
attributes
have
additional
requirements,
in
particular
the
onmessage
attribute
of
MessagePort
objects.
An event handler content attribute is a content attribute for a specific event handler . The name of the content attribute is the same as the name of the event handler .
Event handler content attributes , when specified, must contain valid JavaScript code which, when parsed, would match the FunctionBody production after automatic semicolon insertion .
When an event handler content attribute is set, execute the following steps:
If
the
Should
element's
inline
behavior
be
blocked
by
Content
Security
Policy?
algorithm
returns
"
Blocked
"
when
executed
upon
the
attribute's
element
,
"
script
attribute
",
and
the
attribute's
value,
then
return.
[CSP]
Set the corresponding event handler to an internal raw uncompiled handler consisting of the attribute's new value and the script location where the attribute was set to this value
When an event handler content attribute is removed, the user agent must set the corresponding event handler to null.
When
an
event
handler
H
of
an
element
or
object
T
implementing
the
EventTarget
interface
is
first
set
to
a
non-null
value,
the
user
agent
must
append
an
event
listener
to
the
list
of
event
listeners
associated
with
T
with
type
set
to
the
event
handler
event
type
corresponding
to
H
and
callback
set
to
the
result
of
creating
a
Web
IDL
EventListener
instance
representing
a
reference
to
a
function
of
one
argument
that
executes
the
steps
of
the
event
handler
processing
algorithm
,
given
H
and
its
argument.
The
EventListener
's
callback
context
can
be
arbitrary;
it
does
not
impact
the
steps
of
the
event
handler
processing
algorithm
.
[DOM]
The callback is emphatically not the event handler itself. Every event handler ends up registering the same callback , the algorithm defined below, which takes care of invoking the right callback, and processing the callback's return value.
This
only
happens
the
first
time
the
event
handler
's
value
is
set.
Since
listeners
are
called
in
the
order
they
were
registered,
the
order
of
event
listeners
for
a
particular
event
type
will
always
be
first
the
event
listeners
registered
with
addEventListener()
before
the
first
time
the
event
handler
was
set
to
a
non-null
value,
then
the
callback
to
which
it
is
currently
set,
if
any,
and
finally
the
event
listeners
registered
with
addEventListener()
after
the
first
time
the
event
handler
was
set
to
a
non-null
value.
This example demonstrates the order in which event listeners are invoked. If the button in this example is clicked by the user, the page will show four alerts, with the text "ONE", "TWO", "THREE", and "FOUR" respectively.
<button id="test">Start Demo</button> <script> var button = document.getElementById('test'); button.addEventListener('click', function () { alert('ONE') }, false); button.setAttribute('onclick', "alert('NOT CALLED')"); // event handler listener is registered here button.addEventListener('click', function () { alert('THREE') }, false); button.onclick = function () { alert('TWO'); }; button.addEventListener('click', function () { alert('FOUR') }, false); </script>
The interfaces implemented by the event object do not influence whether an event handler is triggered or not.
The
event
handler
processing
algorithm
for
an
event
handler
H
and
an
Event
object
E
is
as
follows:
Let callback be the result of getting the current value of the event handler H .
If callback is null, then return.
Let
special
error
event
handling
be
true
if
E
is
an
ErrorEvent
object,
E
's
type
is
error
,
and
E
's
currentTarget
implements
the
WindowOrWorkerGlobalScope
mixin.
Otherwise,
let
special
error
event
handling
be
false.
Process
the
Event
object
E
as
follows:
Invoke
callback
with
five
arguments,
the
first
one
having
the
value
of
E
's
message
attribute,
the
second
having
the
value
of
E
's
filename
attribute,
the
third
having
the
value
of
E
's
lineno
attribute,
the
fourth
having
the
value
of
E
's
colno
attribute,
the
fifth
having
the
value
of
E
's
error
attribute,
and
with
the
callback
this
value
set
to
E
's
currentTarget
.
Let
return
value
be
the
callback's
return
value.
[WEBIDL]
Invoke
callback
with
one
argument,
the
value
of
which
is
the
Event
object
E
,
with
the
callback
this
value
set
to
E
's
currentTarget
.
Let
return
value
be
the
callback's
return
value.
[WEBIDL]
If an exception gets thrown by the callback, end these steps and allow the exception to propagate. (It will propagate to the DOM event dispatch logic , which will then report the exception .)
Process return value as follows:
BeforeUnloadEvent
object
and
E
's
type
is
beforeunload
In
this
case,
the
event
handler
IDL
attribute
's
type
will
be
OnBeforeUnloadEventHandler
,
so
return
value
will
have
been
coerced
into
either
null
or
a
DOMString
.
If return value is not null, then:
Set E 's canceled flag .
If
E
's
returnValue
attribute's
value
is
the
empty
string,
then
set
E
's
returnValue
attribute's
value
to
return
value
.
If return value is true, then set E 's canceled flag .
If return value is false, then set E 's canceled flag .
If
we've
gotten
to
this
"Otherwise"
clause
because
E
's
type
is
beforeunload
but
E
is
not
a
BeforeUnloadEvent
object,
then
return
value
will
never
be
false,
since
in
such
cases
return
value
will
have
been
coerced
into
either
null
or
a
DOMString
.
The
EventHandler
callback
function
type
represents
a
callback
used
for
event
handlers.
It
is
represented
in
Web
IDL
as
follows:
[TreatNonObjectAsNull] callback EventHandlerNonNull = any (Event event); typedef EventHandlerNonNull? EventHandler;
In
JavaScript,
any
Function
object
implements
this
interface.
For example, the following document fragment:
<body onload="alert(this)" onclick="alert(this)">
...leads
to
an
alert
saying
"
[object Window]
"
when
the
document
is
loaded,
and
an
alert
saying
"
[object HTMLBodyElement]
"
whenever
the
user
clicks
something
in
the
page.
The return value of the function affects whether the event is canceled or not: as described above, if the return value is false, the event is canceled.
There are two exceptions in the platform, for historical reasons:
The
onerror
handlers
on
global
objects,
where
returning
true
cancels
the
event
The
onbeforeunload
handler,
where
returning
any
non-null
and
non-undefined
value
will
cancel
the
event.
For
historical
reasons,
the
onerror
handler
has
different
arguments:
[TreatNonObjectAsNull] callback OnErrorEventHandlerNonNull = any ((Event or DOMString) event, optional DOMString source, optional unsigned long lineno, optional unsigned long colno, optional any error); typedef OnErrorEventHandlerNonNull? OnErrorEventHandler;
window.onerror = (message, source, lineno, colno, error) => { … };
Similarly,
the
onbeforeunload
handler
has
a
different
return
value:
[TreatNonObjectAsNull] callback OnBeforeUnloadEventHandlerNonNull = DOMString? (Event event); typedef OnBeforeUnloadEventHandlerNonNull? OnBeforeUnloadEventHandler;
An internal raw uncompiled handler is a tuple with the following information:
When the user agent is to get the current value of the event handler H , it must run these steps:
If H 's value is an internal raw uncompiled handler , run these substeps:
If H is an element's event handler , then let element be the element, and document be the element's node document .
Otherwise,
H
is
a
Window
object's
event
handler
:
let
element
be
null,
and
let
document
be
H
's
associated
Document
.
If scripting is disabled for document , then return null.
Let body be the uncompiled script body in the internal raw uncompiled handler .
Let location be the location where the script body originated, as given by the internal raw uncompiled handler .
If element is not null and element has a form owner , let form owner be that form owner . Otherwise, let form owner be null.
Let settings object be the relevant settings object of document .
If body is not parsable as FunctionBody or if parsing detects an early error , then follow these substeps:
Set H 's value to null.
Report the error for the appropriate script and with the appropriate position (line number and column number) given by location , using settings object 's global object . If the error is still not handled after this, then the error may be reported to a developer console.
Return null.
If body begins with a Directive Prologue that contains a Use Strict Directive then let strict be true, otherwise let strict be false.
Push settings object 's realm execution context onto the JavaScript execution context stack ; it is now the running JavaScript execution context .
This is necessary so the subsequent invocation of FunctionCreate takes place in the correct JavaScript Realm .
Let function be the result of calling FunctionCreate , with arguments:
onerror
event
handler
of
a
Window
object
event
,
source
,
lineno
,
colno
,
and
error
.
event
.
If H is an element's event handler , then let Scope be NewObjectEnvironment ( document , the global environment ).
Otherwise,
H
is
a
Window
object's
event
handler
:
let
Scope
be
the
global
environment
.
If form owner is not null, let Scope be NewObjectEnvironment ( form owner , Scope ).
If element is not null, let Scope be NewObjectEnvironment ( element , Scope ).
Remove settings object 's realm execution context from the JavaScript execution context stack .
Set H 's value to the result of creating a Web IDL callback function whose object reference is function and whose callback context is settings object .
Return H 's value.
Document
objects,
and
Window
objects
The
following
are
the
event
handlers
(and
their
corresponding
event
handler
event
types
)
that
must
be
supported
by
all
HTML
elements
,
as
both
event
handler
content
attributes
and
event
handler
IDL
attributes
;
and
that
must
be
supported
by
all
Document
and
Window
objects,
as
event
handler
IDL
attributes
:
Event handler | Event handler event type |
---|---|
onabort
|
abort
|
onauxclick
|
auxclick
|
oncancel
|
cancel
|
oncanplay
|
canplay
|
oncanplaythrough
|
canplaythrough
|
onchange
|
change
|
onclick
|
click
|
onclose
|
close
|
oncontextmenu
|
contextmenu
|
oncuechange
|
cuechange
|
ondblclick
|
dblclick
|
ondrag
|
drag
|
ondragend
|
dragend
|
ondragenter
|
dragenter
|
ondragexit
|
dragexit
|
ondragleave
|
dragleave
|
ondragover
|
dragover
|
ondragstart
|
dragstart
|
ondrop
|
drop
|
ondurationchange
|
durationchange
|
onemptied
|
emptied
|
onended
|
ended
|
oninput
|
input
|
oninvalid
|
invalid
|
onkeydown
|
keydown
|
onkeypress
|
keypress
|
onkeyup
|
keyup
|
onloadeddata
|
loadeddata
|
onloadedmetadata
|
loadedmetadata
|
onloadend
|
loadend
|
onloadstart
|
loadstart
|
onmousedown
|
mousedown
|
onmouseenter
|
mouseenter
|
onmouseleave
|
mouseleave
|
onmousemove
|
mousemove
|
onmouseout
|
mouseout
|
onmouseover
|
mouseover
|
onmouseup
|
mouseup
|
onwheel
|
wheel
|
onpause
|
pause
|
onplay
|
play
|
onplaying
|
playing
|
onprogress
|
progress
|
onratechange
|
ratechange
|
onreset
|
reset
|
onsecuritypolicyviolation
|
securitypolicyviolation
|
onseeked
|
seeked
|
onseeking
|
seeking
|
onselect
|
select
|
onstalled
|
stalled
|
onsubmit
|
submit
|
onsuspend
|
suspend
|
ontimeupdate
|
timeupdate
|
ontoggle
|
toggle
|
onvolumechange
|
volumechange
|
onwaiting
|
waiting
|
The
following
are
the
event
handlers
(and
their
corresponding
event
handler
event
types
)
that
must
be
supported
by
all
HTML
elements
other
than
body
and
frameset
elements,
as
both
event
handler
content
attributes
and
event
handler
IDL
attributes
;
that
must
be
supported
by
all
Document
objects,
as
event
handler
IDL
attributes
;
and
that
must
be
supported
by
all
Window
objects,
as
event
handler
IDL
attributes
on
the
Window
objects
themselves,
and
with
corresponding
event
handler
content
attributes
and
event
handler
IDL
attributes
exposed
on
all
body
and
frameset
elements
that
are
owned
by
that
Window
object's
associated
Document
:
Event handler | Event handler event type |
---|---|
onblur
|
blur
|
onerror
|
error
|
onfocus
|
focus
|
onload
|
load
|
onresize
|
resize
|
onscroll
|
scroll
|
The
following
are
the
event
handlers
(and
their
corresponding
event
handler
event
types
)
that
must
be
supported
by
Window
objects,
as
event
handler
IDL
attributes
on
the
Window
objects
themselves,
and
with
corresponding
event
handler
content
attributes
and
event
handler
IDL
attributes
exposed
on
all
body
and
frameset
elements
that
are
owned
by
that
Window
object's
associated
Document
:
Event handler | Event handler event type |
---|---|
onafterprint
|
afterprint
|
onbeforeprint
|
beforeprint
|
onbeforeunload
|
beforeunload
|
onhashchange
|
hashchange
|
onlanguagechange
|
languagechange
|
onmessage
|
message
|
onmessageerror
|
messageerror
|
onoffline
|
offline
|
ononline
|
online
|
onpagehide
|
pagehide
|
onpageshow
|
pageshow
|
onpopstate
|
popstate
|
onrejectionhandled
|
rejectionhandled
|
onstorage
|
storage
|
onunhandledrejection
|
unhandledrejection
|
onunload
|
unload
|
The
following
are
the
event
handlers
(and
their
corresponding
event
handler
event
types
)
that
must
be
supported
by
all
HTML
elements
,
as
both
event
handler
content
attributes
and
event
handler
IDL
attributes
;
and
that
must
be
supported
by
all
Document
objects,
as
event
handler
IDL
attributes
:
Event handler | Event handler event type |
---|---|
oncut
|
cut
|
oncopy
|
copy
|
onpaste
|
paste
|
The
following
are
the
event
handlers
(and
their
corresponding
event
handler
event
types
)
that
must
be
supported
on
Document
objects
as
event
handler
IDL
attributes
:
Event handler | Event handler event type |
---|---|
onreadystatechange
|
readystatechange
|
interface mixin GlobalEventHandlers { attribute EventHandler onabort; attribute EventHandler onauxclick; attribute EventHandler onblur; attribute EventHandler oncancel; attribute EventHandler oncanplay; attribute EventHandler oncanplaythrough; attribute EventHandler onchange; attribute EventHandler onclick; attribute EventHandler onclose; attribute EventHandler oncontextmenu; attribute EventHandler oncuechange; attribute EventHandler ondblclick; attribute EventHandler ondrag; attribute EventHandler ondragend; attribute EventHandler ondragenter; attribute EventHandler ondragexit; attribute EventHandler ondragleave; attribute EventHandler ondragover; attribute EventHandler ondragstart; attribute EventHandler ondrop; attribute EventHandler ondurationchange; attribute EventHandler onemptied; attribute EventHandler onended; attribute OnErrorEventHandler onerror; attribute EventHandler onfocus; attribute EventHandler oninput; attribute EventHandler oninvalid; attribute EventHandler onkeydown; attribute EventHandler onkeypress; attribute EventHandler onkeyup; attribute EventHandler onload; attribute EventHandler onloadeddata; attribute EventHandler onloadedmetadata; attribute EventHandler onloadend; attribute EventHandler onloadstart; attribute EventHandler onmousedown; [LenientThis] attribute EventHandler onmouseenter; [LenientThis] attribute EventHandler onmouseleave; attribute EventHandler onmousemove; attribute EventHandler onmouseout; attribute EventHandler onmouseover; attribute EventHandler onmouseup; attribute EventHandler onwheel; attribute EventHandler onpause; attribute EventHandler onplay; attribute EventHandler onplaying; attribute EventHandler onprogress; attribute EventHandler onratechange; attribute EventHandler onreset; attribute EventHandler onresize; attribute EventHandler onscroll; attribute EventHandler onsecuritypolicyviolation; attribute EventHandler onseeked; attribute EventHandler onseeking; attribute EventHandler onselect; attribute EventHandler onstalled; attribute EventHandler onsubmit; attribute EventHandler onsuspend; attribute EventHandler ontimeupdate; attribute EventHandler ontoggle; attribute EventHandler onvolumechange; attribute EventHandler onwaiting; }; interface mixin WindowEventHandlers { attribute EventHandler onafterprint; attribute EventHandler onbeforeprint; attribute OnBeforeUnloadEventHandler onbeforeunload; attribute EventHandler onhashchange; attribute EventHandler onlanguagechange; attribute EventHandler onmessage; attribute EventHandler onmessageerror; attribute EventHandler onoffline; attribute EventHandler ononline; attribute EventHandler onpagehide; attribute EventHandler onpageshow; attribute EventHandler onpopstate; attribute EventHandler onrejectionhandled; attribute EventHandler onstorage; attribute EventHandler onunhandledrejection; attribute EventHandler onunload; }; interface mixin DocumentAndElementEventHandlers { attribute EventHandler oncopy; attribute EventHandler oncut; attribute EventHandler onpaste; };
Certain
operations
and
methods
are
defined
as
firing
events
on
elements.
For
example,
the
click()
method
on
the
HTMLElement
interface
is
defined
as
firing
a
click
event
on
the
element.
[UIEVENTS]
Firing a synthetic mouse event named e at target , with an optional not trusted flag , means running these steps:
Let
event
be
the
result
of
creating
an
event
using
MouseEvent
.
Initialize
event
's
type
attribute
to
e
.
Initialize
event
's
bubbles
and
cancelable
attributes
to
true.
Set event 's composed flag .
If
the
not
trusted
flag
is
set,
initialize
event
's
isTrusted
attribute
to
false.
Initialize
event
's
ctrlKey
,
shiftKey
,
altKey
,
and
metaKey
attributes
according
to
the
current
state
of
the
key
input
device,
if
any
(false
for
any
keys
that
are
not
available).
Initialize
event
's
view
attribute
to
target
's
node
document
's
Window
object,
if
any,
and
null
otherwise.
event
's
getModifierState()
method
is
to
return
values
appropriately
describing
the
current
state
of
the
key
input
device.
Return the result of dispatching event at target .
Firing
a
click
event
at
target
means
firing
a
synthetic
mouse
event
named
click
at
target
.
WindowOrWorkerGlobalScope
mixin
The
WindowOrWorkerGlobalScope
mixin
is
for
use
of
APIs
that
are
to
be
exposed
on
Window
and
WorkerGlobalScope
objects.
Other
standards
are
encouraged
to
further
extend
it
using
partial
interface
WindowOrWorkerGlobalScope
{
…
};
along
with
an
appropriate
reference.
typedef (DOMString or Function) TimerHandler; interface mixin WindowOrWorkerGlobalScope { [Replaceable] readonly attribute USVString origin; // base64 utility methods DOMString btoa(DOMString data); ByteString atob(DOMString data); // timers long setTimeout(TimerHandler handler, optional long timeout = 0, any... arguments); void clearTimeout(optional long handle = 0); long setInterval(TimerHandler handler, optional long timeout = 0, any... arguments); void clearInterval(optional long handle = 0); // ImageBitmap Promise<ImageBitmap> createImageBitmap(ImageBitmapSource image, optional ImageBitmapOptions options); Promise<ImageBitmap> createImageBitmap(ImageBitmapSource image, long sx, long sy, long sw, long sh, optional ImageBitmapOptions options); }; Window includes WindowOrWorkerGlobalScope; WorkerGlobalScope includes WindowOrWorkerGlobalScope;
origin
Returns the global object's origin , serialized as string.
Developers
are
strongly
encouraged
to
use
self.origin
over
location.origin
.
The
former
returns
the
origin
of
the
environment,
the
latter
of
the
URL
of
the
environment.
Imagine
the
following
script
executing
in
a
document
on
https://stargate.example/
:
var frame = document.createElement("iframe") frame.onload = function() { var frameWin = frame.contentWindow console.log(frameWin.location.origin) // "null" console.log(frameWin.origin) // "https://stargate.example" } document.body.appendChild(frame)
self.origin
is
a
more
reliable
security
indicator.
The
origin
attribute's
getter
must
return
this
object's
relevant
settings
object
's
origin
,
serialized
.
Support: atob-btoa Chrome for Android 64+ Chrome 4+ iOS Safari 3.2+ UC Browser for Android 11.8+ Firefox 2+ IE 10+ Samsung Internet 4+ Opera Mini all+ Safari 3.1+ Edge 12+ Android Browser 2.1+ Opera 10.6+
Source: caniuse.com
The
atob()
and
btoa()
methods
allow
developers
to
transform
content
to
and
from
the
base64
encoding.
In these APIs, for mnemonic purposes, the "b" can be considered to stand for "binary", and the "a" for "ASCII". In practice, though, for primarily historical reasons, both the input and output of these functions are Unicode strings.
btoa
(
data
)
Takes the input data, in the form of a Unicode string containing only characters in the range U+0000 to U+00FF, each representing a binary byte with values 0x00 to 0xFF respectively, and converts it to its base64 representation, which it returns.
Throws
an
"
InvalidCharacterError
"
DOMException
exception
if
the
input
string
contains
any
out-of-range
characters.
atob
(
data
)
Takes the input data, in the form of a Unicode string containing base64-encoded binary data, decodes it, and returns a string consisting of characters in the range U+0000 to U+00FF, each representing a binary byte with values 0x00 to 0xFF respectively, corresponding to that binary data.
Throws
an
"
InvalidCharacterError
"
DOMException
if
the
input
string
is
not
valid
base64
data.
The
btoa(
data
)
method
must
throw
an
"
InvalidCharacterError
"
DOMException
if
data
contains
any
character
whose
code
point
is
greater
than
U+00FF.
Otherwise,
the
user
agent
must
convert
data
to
a
byte
sequence
whose
n
th
byte
is
the
eight-bit
representation
of
the
n
th
code
point
of
data
,
and
then
must
apply
forgiving-base64
encode
to
that
byte
sequence
and
return
the
result.
The
atob(
data
)
method,
when
invoked,
must
run
the
following
steps:
Let decodedData be the result of running forgiving-base64 decode on data .
If
decodedData
is
failure,
then
throw
an
"
InvalidCharacterError
"
DOMException
.
Return decodedData .