Async cheatsheet

👋 FYI, this note is over 6 months old. Some of the content may be out of date.
On this page

Pending promises can become either…

  • value: Fulfilled with a value, or…
  • error: Rejected with an error.
  • outcome: Either way, they are settled with an outcome.

Combining promises Jump to heading

Use all() to turn an array of promises into a promise to an array.

Promise.all([value1, value2, value3])[
// ->

(value1, value2, value3)

If any promise is rejected, the error will be passed through.

Promise.all([?, ?, error])

// -> error

Use race() instead to pass through the first settled promise.

Promise.race([?, ?, value])

// -> value
promise.then(onFulfilled, onRejected)

Combining promises Jump to heading

Calls onFulfilled once the promise is fulfilled. Jump to heading

value.then(value => nextValue, ...) -> nextValue value.then(value => outcome, ...) -> outcome value.then(value => throw error, ...) -> error

Calls onRejected if the promise is rejected.

error.then(..., error => value) -> value error.then(..., error => outcome) -> outcome error.then(..., error => throw nextError) -> nextError

Passes errors through if onRejected is undefined.

error.then(...) -> error

promise.catch( onRejected ) Jump to heading

Behaves identically to then when onFulfilled is omitted.

error.catch(onRejected) <=> error.then(..., onRejected)

Passes fulfilled values through.

value.catch(...) -> value

promise.finally( onFinally ) Jump to heading

Calls onFinally with no arguments once any outcome is available. Passes through input promise.

outcome.finally(() => ...) -> outcome

The onFulfilled, onRejected and onFinally functions will not be executed until at least the next tick, even for promises that already have an outcome.

Making promises Jump to heading

The function passed to new Promise will be executed synchronously.

new Promise((resolve, reject) => {
doImportantStuff((error, value) => {
if (error) {
} else {

Use resolve() or reject() to create promises from values.

Promise.resolve(value) -> value Promise.reject(error) -> error

If you put a fulfilled promise into a fulfilled promise, they’ll collapse into one.

Promise.resolve(value) -> value

Sometimes you might not need reject, or might not resolve to a value.

function delay(milliseconds) {
return new Promise((resolve) => setTimeout(resolve, milliseconds))

async/await Jump to heading

Calling an async function always results in a promise.

(async () => value)() -> value (async () => outcome)() -> outcome (async () => throw error)() -> error

await waits for a promise to be fulfilled, then returns its value.

async function() {
try {
let value = await outcome
// ...
catch (error) {
// ...

You can pass non-promise values to await

const fn = async () => {
let value = await value
// ...

await may only be used within async functions.

await will wait until at least the next tick before returning, even when awaiting already-fulfilled promises or non-promise values.

← Back home