JavaScript Promise のメソッド

then() Promise が Settled 状態になると呼ばれる

Promise のインスタンスメソッド then(onFulfilled, [onRejected]) メソッドは、基本的に Promise が Settled となったときに呼ばれます。

Promise が Fulfilled となったときは第一引数の onFulfilled ハンドラ関数が呼ばれます。このとき Promise の resolve() ハンドラ関数に渡した値が渡されます。

Promise が Rejected となったときには、第二引数の onRejected ハンドラ関数が渡されている場合には、onRejected ハンドラ関数が呼ばれます。 このとき Promise の reject() ハンドラ関数に渡した値あるいは throw したエラー等が渡されます。

onRejected ハンドラ関数が省略された場合、 Rejected となると then() ではなく Promise の catch() メソッドが呼ばれます。

catch() Promise が Rejected 状態になると呼ばれる

Promise が Rejected 状態になった場合に呼ばれます。ただし、 then() メソッドの onRejected ハンドラ関数が実行された場合は呼ばれません。

なお、Promise は例外が投げられ捕捉されない場合にも Rejected になります。このため、 Promise のハンドラ関数に対する例外の catch プロック catch() メソッドが呼ばれます。

finally() Promise が Settled 状態になると呼ばれる

Promise のインスタンスメソッド finally() メソッドは Promise が Settled 状態 (Fulfilled または Rejected) となったときに、 Fulfilled または Rejected のハンドラ関数がコールバックされた後に呼ばれます。

Promise.all() 全ての Promise が Fulfilled 状態で Fulfilled になる

Promise のスタティックメソッド Promise.all(promises) は Promise のイテラブル (配列など) を受け取り Promise を返します。

Promise.all() に渡した全ての Promise が Fulfilled となったときに、戻り値の Promise は Fulfilled になります。ひとつでも Rejected になると、戻り値の Promise は Rejected になります。

then() メソッドのハンドラ関数には、それぞれの Promise が Fulfilled となったときの値が配列として渡されます。

const delays = [1000, 2000, 5000]
const promises = delays.map((delay) => {
  return new Promise((resolve) => {
    setTimeout(() => resolve(`Fulfilled after ${delay}ms`), delay)
  })
})

Promise.all(promises)
  .then((value) => {
    console.log(value)
    // [
    //  'Fulfilled after 1000ms',
    //  'Fulfilled after 2000ms',
    //  'Fulfilled after 5000ms'
    // ]
  })
  .catch((reason) => {
    console.log(reason)
  })

Promise.all() に渡した一つ以上の Promise のうち、はじめに Rejected となった Promise の reason が catch() (または onRejected ハンドラ関数) に渡されます。

const delays = [1000, 2000, 5000]
const promises = delays.map((delay) => {
  if (delay === 2000) {
    return Promise.reject('Rejected!')
  } else {
    return new Promise((resolve) => {
      setTimeout(() => resolve(`Fulfilled after ${delay}ms`), delay)
    })
  }
})

Promise.all(promises)
  .then((value) => {
    console.log(value)
  })
  .catch((reason) => {
    console.log(reason)
    // Rejected!
  })

Promise.allSettled() 全ての Promise が Settled 状態で Fulfilled になる

Promise のスタティックメソッド Promise.allSettled(promises) は Promise のイテラブル (配列など) を受け取り Promise を返します。

Promise.allSettled() に渡した全ての Promise が Settled となったときに、戻り値の Promise は Fulfilled になります。

then() メソッドのハンドラ関数には、 Promise.allSettled() に渡した全ての Promise の status 及び value (fulfilled のとき) または reason (rejected のとき) を示すオブジェクトの配列が渡されます。

次の例では Promise.allSettled() に 3個の Promise を渡し、そのうちの二つが fulfilled、ひとつが rejected ステータスになっています。 then() にはそれらの状態を表す配列が渡されています。

const delays = [1000, 2000, 5000]
const promises = delays.map((delay) => {
  if (delay === 2000) {
    return Promise.reject('Rejected!')
  } else {
    return new Promise((resolve) => {
      setTimeout(() => resolve(`Fulfilled after ${delay}ms`), delay)
    })
  }
})

Promise.allSettled(promises)
  .then((value) => {
    console.log(value)
    //[
    //  { status: 'fulfilled', value: 'Fulfilled after 1000ms' },
    //  { status: 'rejected', reason: 'Rejected!' },
    //  { status: 'fulfilled', value: 'Fulfilled after 5000ms' }
    //]
  })
  .catch((reason) => {
    console.log(reason)
  })

Promise.any() ひとつでも Fulfilled 状態になると Fulfilled

Promise のスタティックメソッド Promise.any(promises) は Promise のイテラブル (配列など) を受け取り、 Promise を返します。

Promise.any() に渡したひとつ以上の Promise のうちの一つが Fulfilled となったときに、戻り値の Promise は Fulfilled になります。

const delays = [1000, 2000, 5000]
const promises = delays.map((delay) => {
  if (delay < 5000) {
    return Promise.reject('Rejected!')
  } else {
    return new Promise((resolve) => {
      setTimeout(() => resolve(`Fulfilled after ${delay}ms`), delay)
    })
  }
})

Promise.any(promises)
  .then((value) => {
    console.log(value)
    // Fulfilled after 5000ms
  })
  .catch((reason) => {
    console.log(reason)
  })

Promise.any() に渡した全ての Promise が rejected 状態になった場合には、戻り値の Promise は Rejected となります。 reason には AggregateError "All promises were rejected" がセットされます。

Promise.race() 最初に Settled となった Promise の状態と値をとる

Promise のスタティックメソッド Promise.race(promises) は Promise のイテラブル (配列など) を受け取り、Promise を返します。

戻り値の Promise は、Promise.race() に渡された一つ以上の Promise のうち最初に Settled となった Promise の状態と同じ状態になります。

例えば、次の例では、ひとつの Promise はあらかじめ Promise.reject('ABC') として、Rejected として作成されています。 このため Promise.race() が返す Promise も直ちに Rejected となり、reason として ABC がセットされます。

const sleep = (ms) => new Promise((resolve) => setTimeout(() => resolve, ms))
const promises = [sleep(300), Promise.reject('ABC'), sleep(100)]

Promise.race(promises)
  .then((value) => {
    console.log('.then')
    console.log(value)
  })
  .catch((reason) => {
    console.log('.catch')
    console.log(reason)
    // .then
    // ABC
  })

Promise.reject() Rejected 状態で Promise を作成

Promise のスタティックメソッド Promise.reject(reason) は、 reason を受け取り、渡された reason がセットされた Rejected 状態の Promise を作成します。

Promise.resolve() Fulfilled 状態で Promise を作成

Promise のスタティックメソッド Promise.resolve(value) は、 value を受け取り、渡された value がセットされた Fulfilled 状態の Promise を作成します。