promise.md

   1 ---
   2 title: Promises
   3 category: JavaScript
   4 layout: 2017/sheet
   5 ---
   6
   7 ## Reference
   8 {:.-three-column}
   9
  10 ### Introduction
  11 {: .-intro}
  12
  13 intro: A quick reference to the JavaScript [Promise API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
  14
  15 - [Using Promises guide](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) _(developer.mozilla.org)_
  16 - [Promise documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) _(developer.mozilla.org)_
  17
  18 ### Creating promises
  19
  20 ```js
  21 new Promise((resolve, reject) => {
  22   doStuff(() => {
  23     if (success) {
  24       resolve('good')
  25     } else {
  26       reject(new Error('oops'))
  27     }
  28   })
  29 })
  30 ```
  31
  32 Use [new Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#Contstructor) to create new promises.
  33
  34 ### Consuming promises
  35
  36 ```js
  37 promise
  38   .then((result) => {
  39     /* success */
  40   })
  41   .catch((error) => {
  42     /* failure */
  43   })
  44 ```
  45
  46 [then()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then) runs a function when a promise resolves. [catch()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch) runs when a promise fails.
  47
  48 ### Multiple promises
  49
  50 ```js
  51 const promises = [promise1(), promise2() /* ... */]
  52 ```
  53
  54 ```js
  55 // Succeeds when all succeed
  56 Promise.all(promises).then((results) => {
  57   /* ... */
  58 })
  59 ```
  60
  61 ```js
  62 // Succeeds when one finishes first
  63 Promise.race(promises).then((result) => {
  64   /* ... */
  65 })
  66 ```
  67
  68 ### Converting other promises
  69
  70 ```js
  71 return Promise.resolve('result')
  72 return Promise.resolve(promise)
  73 return Promise.resolve(thenable)
  74
  75 return Promise.reject('reason')
  76
  77 Promise.resolve(result).then(() => {
  78   /* ... */
  79 })
  80 ```
  81
  82 `Promise.resolve(val)` will return a promise that resolves to the value given to it.