readme.adoc

Promises API Reference

Promise#then

promise.then(onFulfilled, onRejected);

thenコード例

const promise = new Promise((resolve, reject) => {
    resolve("thenに渡す値");
});
promise.then((value) => {
    console.log(value);
}, (error) => {
    console.error(error);
});

promiseオブジェクトに対してonFulfilledとonRejectedのハンドラを定義し、 新たなpromiseオブジェクトを作成して返す。

このハンドラはpromiseがresolve または rejectされた時にそれぞれ呼ばれる。

• 定義されたハンドラ内で返した値は、新たなpromiseオブジェクトのonFulfilledに対して渡される。

• 定義されたハンドラ内で例外が発生した場合は、新たなpromiseオブジェクトのonRejectedに対して渡される。

Promise#catch

promise.catch(onRejected);

catchのコード例

const promise = new Promise((resolve, reject) => {
    resolve("thenに渡す値");
});
promise.then((value) => {
    console.log(value);
}).catch((error) => {
    console.error(error);
});

promise.then(undefined, onRejected) と同等の意味をもつシンタックスシュガー。

Promise#finally

promise.finally(onFinally);

finallyのコード例

let isLoading = true;

fetch("https://httpbin.org/get").then((response) => {
    if (response.ok) {
        return response.json();
    }
    throw new TypeError("正しくデータを取得できなかった");
  })
  .then((json) => {
      console.log("リクエストが成功した", json);
   })
  .catch((error) => {
      console.error("リクエストが失敗した", error);
   })
  .finally(() => {
      // 成功、失敗どちらの場合も必ず呼ばれる処理
      isLoading = false;
  });

Promise chainが成功、失敗どちらの場合でも呼ばれるハンドラを登録し、新しいpromiseオブジェクトを作成して返す。 返したpromiseオブジェクトは、finallyの呼び出し元となったpromiseオブジェクトの状態を引き継ぐ。

Promise.resolve

Promise.resolve(promise);
Promise.resolve(thenable);
Promise.resolve(object);

Promise.resolveのコード例

const taskName = "task 1";
asyncTask(taskName).then((value) => {
    console.log(value);
}).catch((error) => {
    console.error(error);
});
function asyncTask(name) {
    return Promise.resolve(name).then((value) => {
        return "Done! " + value;
    });
}

受け取った値に応じたpromiseオブジェクトを返す。

どの場合でもpromiseオブジェクトを返すが、大きく分けて以下の3種類となる。

promiseオブジェクトを受け取った場合

受け取ったpromiseオブジェクトをそのまま返す

thenableなオブジェクトを受け取った場合

then をもつオブジェクトを新たなpromiseオブジェクトにして返す

その他の値(オブジェクトやnull等も含む)を受け取った場合

その値でresolveされる新たなpromiseオブジェクトを作り返す

Promise.reject

Promise.reject(object);

Promise.rejectのコード例

const failureStub = sinon.stub(xhr, "request").returns(Promise.reject(new Error("bad!")));

受け取った値でrejectされた新たなpromiseオブジェクトを返す。

Promise.rejectに渡す値は Error オブジェクトとすべきである。

また、Promise.resolveとは異なり、promiseオブジェクトを渡した場合も常に新たなpromiseオブジェクトを作成する。

const r = Promise.reject(new Error("error"));
console.log(r === Promise.reject(r));// false

Promise.all

Promise.all(promiseArray);

Promise.allのコード例

const p1 = Promise.resolve(1);
const p2 = Promise.resolve(2);
const p3 = Promise.resolve(3);
Promise.all([p1, p2, p3]).then((results) => {
    console.log(results);  // [1, 2, 3]
});

新たなpromiseオブジェクトを作成して返す。

渡されたpromiseオブジェクトの配列が全てresolveされた時に、 新たなpromiseオブジェクトはその値でresolveされる。

どれかの値がrejectされた場合は、その時点で新たなpromiseオブジェクトはrejectされる。

渡された配列の値はそれぞれ Promise.resolve にラップされるため、 promiseオブジェクト以外が混在している場合も扱える。

Promise.race

Promise.race(promiseArray);

Promise.raceのコード例

const p1 = Promise.resolve(1);
const p2 = Promise.resolve(2);
const p3 = Promise.resolve(3);
Promise.race([p1, p2, p3]).then((value) => {
    console.log(value);  // 1
});

新たなpromiseオブジェクトを作成して返す。

渡されたpromiseオブジェクトの配列のうち、 一番最初にresolve または rejectされたpromiseにより、 新たなpromiseオブジェクトはその値でresolve または rejectされる。