JavaScript - Promises study notes- 2019-11-30

Promises/A+
upstream from spec
● state
○ pending
○ fulfilled
○ rejected
● value
○ when
fulfilled
● reason
○ When
rejected
ECMAScript 2020 (draft)
‘the spec’
● [[PromiseState]]
○ pending
○ fulfilled
○ rejected
● [[PromiseResult]]
○ when
fulfilled
○ when
rejected
FireFox
downstream from spec
● <state>
○ pending
○ fulfilled
○ rejected
● <value>
○ when
fulfilled
● <reason>
○ When
rejected
Item
● [object Promise]
properties
Chrome
downstream from spec
● [[PromiseStatus]]
○ pending
○ resolved
○ rejected
● [[PromiseValue]]
○ when
resolved
○ when
rejected
THIS IS THE ONLY SLIDE WHICH IS
BOTH SUCCINCT AND INTERESTING

Deciphering: ‘Promise state’ and ‘Promise status’ across Implementations
● SPEC: TC39 (2019-11 https://tc39.es/ecma262/#sec-properties-of-promise-instances )
○ Refers to [ ‘pending’, ‘fulfilled’, ‘rejected’ ] as possible values of a (new Promise).[[PromiseState]]
○ Makes no reference to ‘status’ of a Promise
● Both:
○ (downstream) MDN (2019-11 https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise )
○ (upstream) Promises/A+ (2019-11 https://promisesaplus.com/)
■ Refer to [ ‘pending’, ‘fulfilled’, ‘rejected’ ] as ‘states’ of a Promise
■ Makes no reference to ‘status’ of a Promise
■ (At this time Firefox follows this implementation, implementing (new Promise).<state> )
● (downstream) Chrome (2019-11 Version 78.0.3904.108 (Official Build) (64-bit) )
○ Does not implement (new Promise).[[PromiseState]]
○ Instead, it implements (new Promise).[[PromiseStatus]], synonymously.
○ Refers to [ ‘pending’, ‘resolved’, ‘rejected’ ] as possible values of a (new Promise).[[PromiseStatus]]
APPENDICE,
SKIPPABLE

Deciphering: ‘Promise result’, ‘Promise value’, and ‘Promise reason’ across Implementations
● SPEC: TC39 (2019-11 https://tc39.es/ecma262/#sec-properties-of-promise-instances )
○ If [[PromiseState]] is ‘fulfilled’ or ‘rejected’, then the Promise’s value (informal) may be found in (new
Promise).[[PromiseResult]]
● Both:
○ (downstream) MDN (2019-11 https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise )
○ (upstream) Promises/A+ (2019-11 https://promisesaplus.com/)
■ Refers to Promises ‘fulfilled’ with a ‘value’
■ Refers to Promises ‘rejected’ with a ‘reason’
■ Refers to both of the above, informally, as ‘results’ of a Promise
■ (At this time Firefox follows this implementation, implementing (new Promise).<value> and (new Promise).<reason>.)
● (downstream) Chrome (2019-11 Version 78.0.3904.108 (Official Build) (64-bit) )
○ Does not implement [[PromiseResult]]
○ Instead, it implements (new Promise).[[PromiseValue]], synonymously.
APPENDICE,
SKIPPABLE

new Promise ( executor_fn )
When the Promise constructor is called:
1. It creates two built-in
functions (BIFs) via a
subroutine.
2. Then, it calls ‘executor_fn’,
passing the BIFs as arguments.
The BIFs are often documented as
‘resolve_fn’ and ‘reject_fn’. But to
reduce ambiguity, I recommend that you
call them ‘fulfill_fn’ and ‘reject_fn’
instead. This makes their names more
consistent with the names of underlying
clauses in the ECMA specification. It
also reduces the ambiguity of
‘resolution’, which should refer to both
‘fulfillment’ and ‘rejection’.
executor_fn
( fulfill_fn@resolve_fn
, reject_fn )
CreateResolvingFunctions ( promise )calls
calls
fulfill_fn@resolve_fn
, reject_fn
returns [object Promise]
RejectPromise ( promise, reason )
referencing
steps from
FulfillPromise ( promise, value )
referencing
steps from
TriggerPromiseReactions
( promiseRejectionReactions, argument )
referencing
steps from
returns

Deciphering: ‘Promise resolution’ and ‘Promise rejection’ across Implementations
● SPEC: TC39 (2019-11 https://tc39.es/ecma262/# )
○ 25.6.3.1 Promise ( executor ), the (new Promise) construction makes a call to…
■ 25.6.1.3 CreateResolvingFunctions ( promise )
● … containing the first use of the base word ‘resolve’…
● … returning ‘resolve’ and ‘reject’ as two new built-in functions
● … and is defined in terms of:
○ … the steps: 25.6.1.3.1 Promise Reject Functions, which runs 25.6.1.7 RejectPromise ( promise, reason )
which runs 25.6.1.8 TriggerPromiseReactions ( reactions, argument ) which ingests the list…
■ promise.[[PromiseRejectReactions]] (which was built by 25.6.5.4.1 PerformPromiseThen)
■ (These two clauses are consistent in their nomenclature - ‘reject, reject’.)
○ … the steps: 25.6.1.3.2 Promise Resolve Functions, which runs 25.6.1.4 FulfillPromise ( promise, value )
which runs, 25.6.1.8 TriggerPromiseReactions ( reactions, argument ) which ingests the list…
■ promise.[[PromiseFulfillReactions]] (which was built by 25.6.5.4.1 PerformPromiseThen)
■ (These two clauses are inconsistent1
in their nomenclature - ‘resolve, fulfill’.)
● So here we see another inconsistency2
, where
○ 25.6.1.3 refers to both of the following as ‘resolving functions’:
■ 25.6.1.3.1, which is itself not called ‘resolving’, and
■ 25.6.1.3.2, which is itself called ‘resolving’
● (Comment: 25.6.1.3.2 should be called Promise Fulfill Functions, which would avoid both inconsistencies1&2
.)
■ ( … continued below … )
APPENDICE,
SKIPPABLE

p = new Promise
(executor_fn)
/* returns a
[object Promise]
*/
/* Since the Promise constructor calls
executor_fn, fulfill_fn and reject_fn are defined,
and passed to executor_fn, by the constructor (not
user); yet they are called by the user. The user
defines executor_fn, and it is called before (new
Promise) returns [object Promise]. Example: */
executor_fn = function ( fulfill_fn, reject_fn ) {
/* State of the returned [object Promise]:
1. So long as neither fulfill_fn nor reject_fn
are called: pending
2. If resolve_fn is called here: fulfilled
3. If rejected_fn is called here: rejected */
}
/* There are two key
methods of p which we
can call:
1. p.then(
onFulfilled_fn,
onRejected_fn )
2. p.catch(
onRejected_fn )
*/
NEXT PAGE

NEXT PAGE
/* The user defines onFulfilled_fn and
onRejected_fn, but these are called by
then or catch. Both parameters are
optional, and each takes a single
parameter.
onFulfilled_fn defaults to the
identity function, returning the
received argument; otherwise it can be
defined by the user as
(fulfilmentValue => {
// do something
})
onRejected_fn defaults to a function,
which throws the received reason;
otherwise it can be defined by the
user as (rejectionReason => {
// do something;
// rejectionReason is often but
// not always an error
})
*/
q = p.then(
onFulfilled_fn,
onRejected_fn )
/* returns a
[object
Promise] */
r = p.catch(
onRejected_fn )
/* Internally calls
p.then(undefined,
onRejected_fn);
returns a [object
Promise] */
PREVIOUS PAGE

/* If any handler ( onFulfilled_fn or onRejected_fn ) …
● … does not return any value, then q’s returned state will be resolved, and q’s returned value will be undefined
● … returns a value, v, then q’s returned state will be resolved, and q’s returned value will be v
● … throws an error, e, then q’s returned state will be rejected, and q’s returned value will be e
● … returns a Promise, s, where
○ s is fulfilled, and s’s value is v, then q’s returned state will be fulfilled, and q’s returned value will be v
○ s is rejected, and s’s value is v, then q’s returned state will be rejected, and q’s returned value will be v
○ s is pending, then q return s
*/
PREVIOUS PAGE

If [object Promise]’s state is PENDING, then
● pushes fulfillReactionPromiseReactionRecord
onto the
list [object Promise]. PromiseFulfillReactions
● pushes rejectReactionPromiseReactionRecord
onto the
list [object Promise]. PromiseRejectReactions
Promise.prototype.then
( onFufill_fn, onReject_fn )
referencing
steps from
resultCapabilityPromiseCapabilityRecord
or ‘undefined’returns
If [object Promise]’s state is FULFILLED, then
● enqueues a PromiseReactionJob based on
fulfillReactionPromiseReactionRecord
If [object Promise]’s state is REJECTED, then
● enqueues a PromiseReactionJob based on
rejectReactionPromiseReactionRecord
PerformPromiseThen (promise, onFulfilled, onRejected,
)
● Creates fulfillReactionPromiseReactionRecord
and
rejectReactionPromiseReactionRecord
calls
returns
NewPromiseCapability
( SpeciesConstructor(promise, %Promise%) )
● … which makes a (new Promise), but lets you modify the
fulfill_fn and reject_fn which are passed into the new
object’s executor_fn

Promise.resolve ( value )
● This has a special role. If ‘value’ is a Promise
or thenable, it will not be wrapped in a new
Promise.
referencing
steps from
● If ‘value’s is an Object, and a Promise,
then return ‘value’, without
modification;
● elseif ‘value’s is an Object, and a
thenable, but not a Promise, then attempt
to coerce/convert the thenable to a
Promise, and then return that Promise
without modification;
● otherwise return :
new Promise ( (ff,rj) => { ff (value) } )
returns
PromiseResolve ( let’s not get into this)
Promise.reject ( reason )
● Returns :
new Promise ( (ff,rj) => { rj (reason) } )
● This always wraps ‘reason’ in a new rejected
Promise.

Deciphering: ‘perform promise then’, ‘promise reaction records’
○ 25.6.5.4 Promise.prototype.then ( onFulfilled, onRejected )
■ … sets resultCapability = 25.6.1.5 NewPromiseCapability ( C )
■ … returns 25.6.5.4.1 PerformPromiseThen ( promise, onFulfilled, onRejected [ , resultCapability ] ) …
● … is called by
○ 6.2.3.1 Await
○ 25.1.4.4 AsyncFromSyncIteratorContinuation ( result, promiseCapability )
○ 25.5.3.5 AsyncGeneratorResumeNext ( generator )
○ 25.6.5.4 Promise.prototype.then ( onFulfilled, onRejected )
● … and (each time it is called, on the same promise) creates 25.6.1.2 PromiseReaction Records
○ … and pushes them onto
■ promise.[[PromiseFulfillReactions]], and
■ promise.[[PromiseRejectReactions]]
○ … from where they are later consumed in the next step…
● … and calls 8.4.1 EnqueueJob ( queueName, job, arguments )…
○ … which puts a 25.6.2.1 PromiseReactionJob ( reaction, argument ) into the ‘PromiseJobs’ queue
APPENDICE,
SKIPPABLE

Deciphering: ‘promise capability records’ and ‘result capability’
○ 25.6.1.5 NewPromiseCapability ( C ) …
■ … creates 25.6.1.1 PromiseCapability Records …
● … sometimes playing the role of i.e. used as ‘result capabilities’
■ … which are ingested by (for example)…
● 12.3.7 Import Calls , Async { Function Definitions - 14.7.11 Runtime Semantics: EvaluateBody , Arrow Function Definitions - 14.8.15 Runtime
Semantics: EvaluateBody }, 25.1.4.2 The %AsyncFromSyncIteratorPrototype% Object - next(), return(), throw(), 25.5.3.6 AsyncGeneratorEnqueue
( generator, completion ), 25.6.4.1 Promise.all ( iterable ) , 25.6.4.2 Promise.allSettled ( iterable ) , 25.6.4.4 Promise.race ( iterable )
, 25.6.4.5 Promise.reject ( r ) , 25.6.4.6.1 PromiseResolve ( C, x ) , 25.6.5.4 Promise.prototype.then ( onFulfilled, onRejected )
○ Distinct from the built-in functions ‘resolve’ and ‘reject’ created by 25.6.1.3 CreateResolvingFunctions ( promise ),
■ there also exist two UNRELATED functions
● 25.6.4.6 Promise.resolve ( x ),
○ which returns 25.6.4.6.1 PromiseResolve ( C, x ), which has a ‘flattening’ role
● 25.6.4.5 Promise.reject ( r ) ,
■ both of which call NewPromiseCapability
APPENDICE,
SKIPPABLE

Readings
● Promises/A+
○ An open standard for sound, interoperable JavaScript promises.
○ This is the standard implemented below.
● Draft ECMA-262 / (November) ECMAScript® 2020 Language Specification
○ This document is the abstract specification, independent of any specific language implementation.
○ 25.6 Promise Objects
■ This is a high-level introduction to the usage of this object.
■ 25.6.3.1 Promise ( executor )
● This is a good place to start reading, because it is generally the first call that people make to this
object/class. The downstream MDN documentation introduces the reader to Promises from here.
■ 25.6.6 Properties of Promise Instances
● This is also a good place to start reading, as it addresses fundamental definitions.
● Community
○ https://stackoverflow.com/questions/29268569/what-is-the-correct-terminology-for-javascript-promises
APPENDICE,
SKIPPABLE

JavaScript - Promises study notes- 2019-11-30

More Related Content

Similar to JavaScript - Promises study notes- 2019-11-30 (20)

More from YangJerng Hwa (19)

Recently uploaded (20)

JavaScript - Promises study notes- 2019-11-30