An interface is a set of property keys whose associated values match a specific specification. Any object that provides all the properties as described by an interface's specification conforms to that interface. An interface is not represented by a distinct object. There may be many separately implemented objects that conform to any interface. An individual object may conform to multiple interfaces.
The Iterable interface includes the property described in Table 52:
Property | Value | Requirements |
---|---|---|
@@iterator |
A function that returns an Iterator object. | The returned object must conform to the Iterator interface. |
An object that implements the Iterator interface must include the property in Table 53. Such objects may also implement the properties in Table 54.
Property | Value | Requirements |
---|---|---|
next |
A function that returns an IteratorResult object. | The returned object must conform to the IteratorResult interface. If a previous call to the next method of an Iterator has returned an IteratorResult object whose done property is true, then all subsequent calls to the next method of that object should also return an IteratorResult object whose done property is true. However, this requirement is not enforced. |
NOTE 1 Arguments may be passed to the next function but their interpretation and validity is dependent upon the target Iterator. The for-of statement and other common users of Iterators do not pass any arguments, so Iterator objects that expect to be used in such a manner must be prepared to deal with being called with no arguments.
Property | Value | Requirements |
---|---|---|
return |
A function that returns an IteratorResult object. | The returned object must conform to the IteratorResult interface. Invoking this method notifies the Iterator object that the caller does not intend to make any more next method calls to the Iterator. The returned IteratorResult object will typically have a done property whose value is true, and a value property with the value passed as the argument of the return method. However, this requirement is not enforced. |
throw |
A function that returns an IteratorResult object. | The returned object must conform to the IteratorResult interface. Invoking this method notifies the Iterator object that the caller has detected an error condition. The argument may be used to identify the error condition and typically will be an exception object. A typical response is to throw the value passed as the argument. If the method does not throw , the returned IteratorResult object will typically have a done property whose value is true. |
NOTE 2 Typically callers of these methods should check for their existence before invoking
them. Certain ECMAScript language features including for
-of
, yield*
, and array
destructuring call these methods after performing an existence check. Most ECMAScript library functions that accept
Iterable objects as arguments also conditionally call them.
The IteratorResult interface includes the properties listed in Table 55:
Property | Value | Requirements |
---|---|---|
done |
Either true or false. | This is the result status of an iterator next method call. If the end of the iterator was reached done is true. If the end was not reached done is false and a value is available. If a done property (either own or inherited) does not exist, it is consider to have the value false. |
value |
Any ECMAScript language value. | If done is false, this is the current iteration element value. If done is true, this is the return value of the iterator, if it supplied one. If the iterator does not have a return value, value is undefined. In that case, the value property may be absent from the conforming object if it does not inherit an explicit value property. |
The value of the [[Prototype]] internal slot of the %IteratorPrototype% object is the intrinsic object %ObjectPrototype% (19.1.3). The %IteratorPrototype% object is an ordinary object. The initial value of the [[Extensible]] internal slot of the %IteratorPrototype% object is true.
NOTE All objects defined in this specification that implement the Iterator interface also inherit from %IteratorPrototype%. ECMAScript code may also define objects that inherit from %IteratorPrototype%.The %IteratorPrototype% object provides a place where additional methods that are applicable to all iterator objects may be added.
The following expression is one way that ECMAScript code can access the %IteratorPrototype% object:
Object.getPrototypeOf(Object.getPrototypeOf([][Symbol.iterator]()))
The following steps are taken:
The value of the name
property of this function is "[Symbol.iterator]"
.
Generator Function objects are constructor functions that are usually created by evaluating GeneratorDeclaration, GeneratorExpression, and GeneratorMethod syntactic productions. They may also be created by calling the %GeneratorFunction% intrinsic.
The GeneratorFunction
constructor is the %GeneratorFunction% intrinsic. When
GeneratorFunction
is called as a function rather than as a constructor, it creates and initializes a new
GeneratorFunction object. Thus the function call GeneratorFunction
(…)
is
equivalent to the object creation expression new GeneratorFunction
(…)
with
the same arguments.
GeneratorFunction
is designed to be subclassable. It may be used as the value of an extends
clause of a class definition. Subclass constructors that intend to inherit the specified GeneratorFunction
behaviour must include a super
call to the GeneratorFunction
constructor to create and
initialize subclass instances with the internal slots necessary for built-in GeneratorFunction behaviour. All ECMAScript
syntactic forms for defining generator function objects create direct instances of GeneratorFunction
. There
is no syntactic means to create instances of GeneratorFunction
subclasses.
The last argument specifies the body (executable code) of a generator function; any preceding arguments specify formal parameters.
When the GeneratorFunction
function is called with some arguments p1,
p2, … , pn, body (where n might be 0, that is, there are no “p” arguments, and where body might also not be
provided), the following steps are taken:
"generator"
,
args).NOTE See NOTE for 19.2.1.1.
The GeneratorFunction
constructor is a standard built-in function object that inherits from the
Function
constructor. The value of the [[Prototype]] internal slot of the GeneratorFunction
constructor
is the intrinsic object %Function%.
The value of the [[Extensible]] internal slot of the GeneratorFunction constructor is true.
The value of the name
property of the GeneratorFunction is "GeneratorFunction"
.
The GeneratorFunction
constructor has the following properties:
This is a data property with a value of 1. This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
The initial value of GeneratorFunction.prototype
is the intrinsic object %Generator%.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
The GeneratorFunction prototype object is an ordinary object. It is not a function object and does not have an [[ECMAScriptCode]] internal slot or any other of the internal slots listed in Table 27 or Table 56. In addition to being the value of the prototype property of the %GeneratorFunction% intrinsic, it is the %Generator% intrinsic (see Figure 2).
The value of the [[Prototype]] internal slot of the GeneratorFunction prototype object is the %FunctionPrototype% intrinsic object. The initial value of the [[Extensible]] internal slot of the GeneratorFunction prototype object is true.
The initial value of GeneratorFunction.prototype.constructor
is the intrinsic object
%GeneratorFunction%.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
The value of GeneratorFunction.prototype.prototype
is the %GeneratorPrototype% intrinsic object.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
The initial value of the @@toStringTag property is the String value "GeneratorFunction"
.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
Every GeneratorFunction instance is an ECMAScript function object and
has the internal slots listed in Table 27. The value of the [[FunctionKind]] internal slot for all such instances is
"generator"
.
Each GeneratorFunction instance has the following own properties:
The value of the length
property is an integer that indicates the typical number of arguments expected by
the GeneratorFunction. However, the language permits the function to be invoked with some other number of arguments. The
behaviour of a GeneratorFunction when invoked on a number of arguments other than the number specified by its
length
property depends on the function.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
The specification for the name
property of Function instances given in 19.2.4.2 also applies to GeneratorFunction instances.
Whenever a GeneratorFunction instance is created another ordinary object is also created and is the initial value of
the generator function's prototype
property. The value of the prototype property is used to initialize
the [[Prototype]] internal slot of a newly created Generator
object when the generator function object is invoked using either [[Call]] or [[Construct]].
This property has the attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: false }.
NOTE Unlike function instances, the object that is the value of the a
GeneratorFunction's prototype
property does not have a constructor
property whose value
is the GeneratorFunction instance.
A Generator object is an instance of a generator function and conforms to both the Iterator and Iterable interfaces.
Generator instances directly inherit properties from the object that is the value of the prototype
property
of the Generator function that created the instance. Generator instances indirectly inherit properties from the Generator
Prototype intrinsic, %GeneratorPrototype%.
The Generator prototype object is the %GeneratorPrototype% intrinsic. It is also the initial value of the
prototype
property of the %Generator% intrinsic (the GeneratorFunction.prototype).
The Generator prototype is an ordinary object. It is not a Generator instance and does not have a [[GeneratorState]] internal slot.
The value of the [[Prototype]] internal slot of the Generator prototype object is the intrinsic object %IteratorPrototype% (25.1.2). The initial value of the [[Extensible]] internal slot of the Generator prototype object is true.
All Generator instances indirectly inherit properties of the Generator prototype object.
The initial value of Generator.prototype.constructor
is the intrinsic object %Generator%.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
The next
method performs the following steps:
The return
method performs the following steps:
The throw
method performs the following steps:
The initial value of the @@toStringTag property is the String value "Generator"
.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
Generator instances are initially created with the internal slots described in Table 56.
Internal Slot | Description |
---|---|
[[GeneratorState]] | The current execution state of the generator. The possible values are: undefined, "suspendedStart" , "suspendedYield" , "executing" , and "completed" . |
[[GeneratorContext]] | The execution context that is used when executing the code of this generator. |
The abstract operation GeneratorStart with arguments generator and generatorBody performs the following steps:
"completed"
."completed"
state it never leaves it and its associated execution context is never resumed. Any execution state associated with
generator can be discarded at this point."suspendedStart"
.The abstract operation GeneratorValidate with argument generator performs the following steps:
"executing"
, throw a TypeError exception.The abstract operation GeneratorResume with arguments generator and value performs the following steps:
"completed"
, return CreateIterResultObject(undefined, true)."suspendedStart"
or
"suspendedYield"
."executing"
.The abstract operation GeneratorResumeAbrupt with arguments generator and abruptCompletion performs the following steps:
"suspendedStart"
, then
"completed"
."completed"
state it never leaves it and its associated execution context is never resumed. Any execution state associated with
generator can be discarded at this point."completed"
."completed"
, then
"suspendedYield"
."executing"
.The abstract operation GeneratorYield with argument iterNextObj performs the following steps:
"suspendedYield"
.A Promise is an object that is used as a placeholder for the eventual results of a deferred (and possibly asynchronous) computation.
Any Promise object is in one of three mutually exclusive states: fulfilled, rejected, and pending:
A promise p
is fulfilled if p.then(f, r)
will immediately enqueue a Job to call the
function f
.
A promise p
is rejected if p.then(f, r)
will immediately enqueue a Job to call the function
r
.
A promise is pending if it is neither fulfilled nor rejected.
A promise is said to be settled if it is not pending, i.e. if it is either fulfilled or rejected.
A promise is resolved if it is settled or if it has been “locked in” to match the state of another promise. Attempting to resolve or reject a resolved promise has no effect. A promise is unresolved if it is not resolved. An unresolved promise is always in the pending state. A resolved promise may be pending, fulfilled or rejected.
A PromiseCapability is a Record value used to encapsulate a promise object along with the functions that are capable of resolving or rejecting that promise object. PromiseCapability records are produced by the NewPromiseCapability abstract operation.
PromiseCapability Records have the fields listed in Table 57.
Field Name | Value | Meaning |
---|---|---|
[[Promise]] | An object | An object that is usable as a promise. |
[[Resolve]] | A function object | The function that is used to resolve the given promise object. |
[[Reject]] | A function object | The function that is used to reject the given promise object. |
IfAbruptRejectPromise is a short hand for a sequence of algorithm steps that use a PromiseCapability record. An algorithm step of the form:
means the same thing as:
The PromiseReaction is a Record value used to store information about how a promise should react when it becomes
resolved or rejected with a given value. PromiseReaction records are created by the then
method of the
Promise prototype, and are used by a PromiseReactionJob.
PromiseReaction records have the fields listed in Table 58.
Field Name | Value | Meaning |
---|---|---|
[[Capabilities]] | A PromiseCapability record | The capabilities of the promise for which this record provides a reaction handler. |
[[Handler]] | A function object or a String | The function that should be applied to the incoming value, and whose return value will govern what happens to the derived promise. If [[Handler]] is "Identity" it is equivalent to a function that simply returns its first argument. If [[Handler]] is "Thrower" it is equivalent to a function that throws its first argument as an exception. |
When CreateResolvingFunctions is performed with argument promise, the following steps are taken:
A promise reject function is an anonymous built-in function that has [[Promise]] and [[AlreadyResolved]] internal slots.
When a promise reject function F is called with argument reason, the following steps are taken:
The length
property of a promise reject function is 1.
A promise resolve function is an anonymous built-in function that has [[Promise]] and [[AlreadyResolved]] internal slots.
When a promise resolve function F is called with argument resolution, the following steps are taken:
"then"
)."PromiseJobs"
, PromiseResolveThenableJob, «promise,
resolution, thenAction»)The length
property of a promise resolve function is 1.
When the FulfillPromise abstract operation is called with arguments promise and value the following steps are taken:
"pending"
."fulfilled"
.The abstract operation NewPromiseCapability takes a constructor function, and attempts to use
that constructor function in the fashion of the built-in Promise
constructor to create a Promise object and
extract its resolve and reject functions. The promise plus the resolve and reject functions are used to initialize a new
PromiseCapability record which is returned as the value of this abstract operation.
Promise
constructor (see
25.4.3.1).NOTE This abstract operation supports Promise subclassing, as it is generic on any constructor that calls a passed executor function argument in the same way as the Promise constructor. It is used to generalize static methods of the Promise constructor to any subclass.
A GetCapabilitiesExecutor function is an anonymous built-in function that has a [[Capability]] internal slot.
When a GetCapabilitiesExecutor function F is called with arguments resolve and reject the following steps are taken:
The length
property of a GetCapabilitiesExecutor function is 2.
The abstract operation IsPromise checks for the promise brand on an object.
When the RejectPromise abstract operation is called with arguments promise and reason the following steps are taken:
"pending"
."rejected"
.The abstract operation TriggerPromiseReactions takes a collection of PromiseReactionRecords and enqueues a new Job for each record. Each such Job processes the [[Handler]] of the PromiseReactionRecord, and if the [[Handler]] is a function calls it passing the given argument.
"PromiseJobs"
, PromiseReactionJob, «reaction,
argument»).The job PromiseReactionJob with parameters reaction and argument applies the appropriate handler to the incoming value, and uses the handler's return value to resolve or reject the derived promise associated with that handler.
"Identity"
, let handlerResult be NormalCompletion(argument)."Thrower"
, let handlerResult be Completion{[[type]]: throw, [[value]]: argument, [[target]]: empty}.The job PromiseResolveThenableJob with parameters promiseToResolve, thenable, and then performs the following steps:
NOTE This Job uses the supplied thenable and its then
method to resolve the
given promise. This process must take place as a Job to ensure that the evaluation of the then
method
occurs after evaluation of any surrounding code has completed.
The Promise constructor is the %Promise% intrinsic object and the initial value of the Promise
property of
the global object. When called as a constructor it creates and initializes a new Promise object. Promise
is
not intended to be called as a function and will throw an exception when called in that manner.
The Promise
constructor is designed to be subclassable. It may be used as the value in an
extends
clause of a class definition. Subclass constructors that intend to inherit the specified
Promise
behaviour must include a super
call to the Promise
constructor to create
and initialize the subclass instance with the internal state necessary to support the Promise
and
Promise.prototype
built-in methods.
When the Promise
function is called with argument executor the following
steps are taken:
"%PromisePrototype%"
, «[[PromiseState]], [[PromiseResult]], [[PromiseFulfillReactions]],
[[PromiseRejectReactions]]» )."pending"
.NOTE The executor argument must be a function object. It is called for initiating and reporting completion of the possibly deferred action represented by this Promise object. The executor is called with two arguments: resolve and reject. These are functions that may be used by the executor function to report eventual completion or failure of the deferred computation. Returning from the executor function does not mean that the deferred action has been completed but only that the request to eventually perform the deferred action has been accepted.
The resolve function that is passed to an executor function accepts a single argument. The executor code may eventually call the resolve function to indicate that it wishes to resolve the associated Promise object. The argument passed to the resolve function represents the eventual value of the deferred action and can be either the actual fulfillment value or another Promise object which will provide the value if it is fulfilled.
The reject function that is passed to an executor function accepts a single argument. The
executor code may eventually call the reject function to indicate that the associated Promise is
rejected and will never be fulfilled. The argument passed to the reject function is used as the rejection
value of the promise. Typically it will be an Error
object.
The resolve and reject functions passed to an executor function by the Promise constructor have the capability to actually resolve and reject the associated promise. Subclasses may have different constructor behaviour that passes in customized values for resolve and reject.
The value of the [[Prototype]] internal slot of the
Promise
constructor is the intrinsic object %FunctionPrototype% (19.2.3).
Besides the length
property (whose value is 1), the Promise constructor has the following properties:
The all
function returns a new promise which is fulfilled with an array of
fulfillment values for the passed promises, or rejects with the reason of the first passed promise that rejects. It
resolves all elements of the passed iterable to promises as it runs this algorithm.
NOTE The all
function requires its this value to be a constructor
function that supports the parameter conventions of the Promise
constructor.
When the PerformPromiseAll abstract operation is called with arguments iteratorRecord, constructor, and resultCapability the following steps are taken:
"resolve"
,
«nextValue»)."then"
,
«resolveElement, resultCapability.[[Reject]]»).A Promise.all resolve element function is an anonymous built-in function that is used to resolve a specific Promise.all element. Each Promise.all resolve element function has [[Index]], [[Values]], [[Capabilities]], [[RemainingElements]], and [[AlreadyCalled]] internal slots.
When a Promise.all resolve element function F is called with argument x, the following steps are taken:
The length
property of a Promise.all resolve element function is
1.
The initial value of Promise.prototype
is the intrinsic object %PromisePrototype% (25.4.5).
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
The race
function returns a new promise which is settled in the same way as the
first passed promise to settle. It resolves all elements of the passed iterable to promises as it runs this algorithm.
NOTE 1 If the iterable argument is empty or if none of the promises in iterable ever settle then the pending promise returned by this method will never be settled
NOTE 2 The race
function expects its this value to be a constructor
function that supports the parameter conventions of the Promise
constructor. It also expects that its
this value provides a resolve
method.
When the PerformPromiseRace abstract operation is called with arguments iteratorRecord, promiseCapability, and C the following steps are taken:
"resolve"
,
«nextValue»)."then"
,
«promiseCapability.[[Resolve]], promiseCapability.[[Reject]]»).The reject
function returns a new promise rejected with the passed argument.
NOTE The reject
function expects its this value to be a constructor
function that supports the parameter conventions of the Promise
constructor.
The resolve
function returns either a new promise resolved with the passed argument,
or the argument itself if the argument is a promise produced by this constructor.
"constructor"
).NOTE The resolve
function expects its this value to be a constructor
function that supports the parameter conventions of the Promise
constructor.
Promise[@@species]
is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:
The value of the name
property of this function is "get [Symbol.species]"
.
NOTE Promise prototype methods normally use their this
object’s
constructor to create a derived object. However, a subclass constructor may over-ride that default behaviour by
redefining its @@species property.
The Promise prototype object is the intrinsic object %PromisePrototype%. The value of the [[Prototype]] internal slot of the Promise prototype object is the intrinsic object %ObjectPrototype% (19.1.3). The Promise prototype object is an ordinary object. It does not have a [[PromiseState]] internal slot or any of the other internal slots of Promise instances.
When the catch
method is called with argument onRejected the following
steps are taken:
"then"
, «undefined,
onRejected»).The initial value of Promise.prototype.constructor
is the intrinsic object %Promise%.
When the then
method is called with arguments onFulfilled and
onRejected the following steps are taken:
The abstract operation PerformPromiseThen performs the “then” operation on promise using onFulfilled and onRejected as its settlement actions. The result is resultCapability's promise.
"Identity"
."Thrower"
."pending"
,
"fulfilled"
,
"PromiseJobs"
, PromiseReactionJob, «fulfillReaction,
value»)."rejected"
,
"PromiseJobs"
, PromiseReactionJob, «rejectReaction,
reason»).The initial value of the @@toStringTag property is the String value "Promise"
.
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
Promise instances are ordinary objects that inherit properties from the Promise prototype object (the intrinsic, %PromisePrototype%). Promise instances are initially created with the internal slots described in Table 59.
Internal Slot | Description |
---|---|
[[PromiseState]] | A String value that governs how a promise will react to incoming calls to its then method. The possible values are: "pending" , "fulfilled" , and "rejected" . |
[[PromiseResult]] | The value with which the promise has been fulfilled or rejected, if any. Only meaningful if [[PromiseState]] is not "pending" . |
[[PromiseFulfillReactions]] | A List of PromiseReaction records to be processed when/if the promise transitions from the "pending" state to the "fulfilled" state. |
[[PromiseRejectReactions]] | A List of PromiseReaction records to be processed when/if the promise transitions from the "pending" state to the "rejected" state. |