Promises. The basics, from Promises/A+

Promises

Luke Smith

@ls_n

SmugMug

promise

A promise represents a valuethat may not be available yet

var promise = async();

promise

A promise represents a valuethat may not be available yet

var promise = async();

var value = sync();

Synchronous code analogy

function async() {

function getMessage(resolve, reject) { setTimeout(function () {

resolve(“Promise fulfilled”);

}, 1000); }

return new Y.Promise(getMessage);

}

promise

new Y.Promise(workFn)

resolve

resolve

reject

then() method to get value when availableor catch errors during value computation

promise .then(

)

onFulfilled(value)

onRejected(reason)

var promise = async();

promise.then(onFulfilled, onRejected);

then() method to get value when availableor catch errors during value computation

promise .then(

)

onFulfilled(value)

onRejected(reason)

var value, error;try { value = sync();} catch (reason) { error = reason;}

if (error) { onRejected(reason);} else { onFulfilled(value);}

Synchronous code analogy

promise .then(

)

onFulfilled( )

onRejected(reason)

fulfill

valuevalue

Promise Resolution

promise .then(

)

onFulfilled(value)

onRejected( )

reject

reason

reason

Fulfillment Rejection

promiseA .then(

)

onFulfilled(value)

onRejected(reason)

promiseB

then() returns a promise

var promiseA = async();

var promiseB = promiseA.then(onFulfilled, onRejected);

promiseA .then(

)

onFulfilled(value)

onRejected(reason)

promiseB

then() returns a promise

var valueA, valueB, error;try { valueA = sync();} catch (reason) { error = reason;}

if (error) { onRejected(reason);} else { valueB = onFulfilled(valueA);}

Synchronous code analogy

.then(

)

onFulfilled(value)

promise

callback return values fulfill their promises

value

.then(

)

onRejected(reason)

promise

fulfill

value

return

valuefulfill

value

return

.then(

)

onFulfilled(value)

promise

callback errors reject their promises

.then(

)

onRejected(reason)

promise

throwthrow

reject

error

reason reason reject

error

promiseA .then(

)

onFulfilledA(value)

onRejectedA(reason)

promiseB .then(

)

onFulfilledB(value)

onRejectedB(reason)

promiseC

Promise Chaining

var promiseC = async()

.then(onFulfilledA, onRejectedA)

.then(onFulfilledB, onRejectedB);

and so on...

promise1 .then(

)

onFulfilled(value)

onRejected(reason)

promise2

.then(

)

onFulfilled(value)

onRejected(reason)

promise3

callback resolution through the chain

fulfill

value A value A

value B

value C

value B

fulfill

returnvalue B

fulfill

returnvalue C

var valueA, valueB, valueC, error = false;

try { valueA = sync();} catch (reasonA) { error = true; valueA = reasonA;}

if (error) { try { valueB = onRejectedA(valueA); error = false; } catch (reasonB) { valueB = reasonB; }} else { try { valueB = onFulfilledA(valueA); } catch (reasonB) { error = true; valueB = reasonB; }}

if (error) {

Synchronous code analogy

var valueA, valueB, valueC, error = false;

try { valueA = sync();} catch (reasonA) { error = true; valueA = reasonA;}

if (error) { try { valueB = onRejectedA(valueA); error = false; } catch (reasonB) { valueB = reasonB; }} else { try { valueB = onFulfilledA(valueA); } catch (reasonB) { error = true; valueB = reasonB; }}

if (error) {

Synchronous code analogy

initial promise generation

valueA = sync();} catch (reasonA) { error = true; valueA = reasonA;}

if (error) { try { valueB = onRejectedA(valueA); error = false; } catch (reasonB) { valueB = reasonB; }} else { try { valueB = onFulfilledA(valueA); } catch (reasonB) { error = true; valueB = reasonB; }}

if (error) { valueC = onRejectedB(valueB);} else { valueC = onFulfilledB(valueB);}

Synchronous code analogy

for each intermediate promise...

final promise callbacks

promise1 .then(

)

onFulfilled(value)

onRejected(reason)

promise2 .then(

) onRejected(reason)

promise3 .then(

)

onFulfilled(value)

onRejected(reason)

value/reason pass thru if callback missing

fulfill

value A value A

value B

value B value B

return

pass thrunull

value B

.then(

)

onFulfilled(value)

promise

return

callbacks can return promises

.then(

)

onRejected(reason)

promise

return

returned promise

returned promise

.then(

)

onFulfilled(value)

promise

return

callbacks can return promises

.then(

)

onRejected(reason)

promise

return

returned promise

returned promise

Not a value (yet)

Not a value (yet)

.then(

)

onFulfilled(value)

promise

returned promises postpone continuation

returned promise

return

.then(

)

onFulfilled(value)

onRejected(reason)

.then(

)

onFulfilled(value)

promise

returned promises postpone continuation

returned promise

inserted

.then(

)

onFulfilled(value)

onRejected(reason)

“wait for me”

.then(

)

onFulfilled(value)

onRejected(reason)

.then(

)

onFulfilled(value)

promise

returned promises postpone continuation

returned promise

value

fulfill

inserted

.then(

)

onFulfilled(value)

onRejected(reason)

“wait for me”

.then(

)

onFulfilled(value)

onRejected(reason)

.then(

)

onFulfilled( )

onRejected(reason)

.then(

)

onFulfilled(value)

promise

returned promises postpone continuation

returned promise

value

fulfill

value

.then(

)

onFulfilled(value)

onRejected(reason)

.then(

)

onFulfilled( )

onRejected(reason)

.then(

)

onFulfilled(value)

promise

returned promises postpone continuation

returned promise

value

fulfill

value

fulfillment value resolves original promise...

.then(

)

onFulfilled(value)

onRejected(reason)

value

.then(

)

onFulfilled( )

onRejected(reason)

.then(

)

onFulfilled(value)

promise

returned promises postpone continuation

returned promise

.then(

)

onFulfilled( )

onRejected(reason)

value

fulfill

value

valuefulfillment value resolves original promise...

...then chain continues

value

Promises/A+ spec

http://promises-aplus.github.com/promises-spec/

https://github.com/promises-aplus/promises-spec