Promise

Promise オブジェクトは非同期処理の最終的な完了処理（もしくは失敗）およびその結果の値を表現します。

このデモのソースファイルは GitHub リポジトリに格納されています。デモプロジェクトに協力したい場合は、 https://github.com/mdn/interactive-examples をクローンしてプルリクエストを送信してください。

構文

new Promise(executor);

引数

executor

2 つの引数 resolve と reject を取る関数。executor 関数は resolve 関数と reject 関数が渡されて Promise が実装されるとすぐに実行されます (Promise コンストラクターがオブジェクトを返すよりも前に executor は実行されます)。 resolve 関数と reject 関数は呼び出されると Promise に対してそれぞれ resolve (解決) もしくは reject (拒否) を行います。executor は通常、非同期の作業を開始して、完了した際に resolve 関数 (成功した場合) もしくは reject 関数 (エラーが発生した場合) のいずれか一方を呼び出します。 executor 関数でエラーが投げられた場合、 Promise は reject されます。 executor の返値は無視されます。

解説

Promise インターフェイスは作成時点では分からなくてもよい値へのプロキシです。 Promise を用いることで、非同期アクションの成功や失敗に対するハンドラーを関連付けることができます。これにより、非同期メソッドは、最終的な値を返すのではなく、未来のある時点で値を持つ Promise を返すことで、同期メソッドと同じように値を返すことができるようになります。

Promise の状態は以下のいずれかとなります。

• pending: 初期状態。成功も失敗もしていません。
• fulfilled: 処理が成功して完了したことを意味します。
• rejected: 処理が失敗したことを意味します。

pending 状態の Promise は、何らかの値を持つ fulfilled 状態、もしくは何らかの理由 (エラー) を持つ rejected 状態のいずれかに変わります。そのどちらとなっても、then メソッドによって関連付けられたハンドラーが呼ばれます。 (対応するハンドラーがアタッチされたとき、既に Promise が成功または失敗していても、そのハンドラーは呼ばれます。よって、非同期処理とその関連付けられたハンドラーとの競合は発生しません。)

Promise.prototype.then() メソッドと Promise.prototype.catch() メソッドもまた Promise を返すので、これらをチェーン (連鎖) させることができます。

プロパティ

Promise.length

長さを表し、常に 1 (コンストラクターの引数の数)。

Promise.prototype

Promise コンストラクターのプロトタイプを表す。

メソッド

Promise.all(iterable)

すべての Promise が解決されるか、拒否されるかするまで待ちます。

返却された Promise が解決された場合、解決された Promise が、複数の Promise が含まれる iterable で定義された通りの順番で入った集合配列の値によって解決されます。拒否された場合は、 iterable の中で拒否された最初の Promise の理由によって拒否されます。

Promise.allSettled(iterable)

すべての Promise が完了する (それぞれが解決するか、拒否される) まで待ちます。

Promise を返し、これはすべての与えられた Promise が解決または拒否された後で、それぞれの Promise の結果を記述するオブジェクトの配列で解決されます。

Promise.race(iterable)

Promise のうちの1つが解決または拒否されるまで待ちます。

返された Promise が解決された場合、 iterable の中で最初に解決された Promise の値によって解決されます。拒否された場合、最初に拒否された Promise の理由によって拒否されます。

Promise.reject(reason)

与えられた理由で拒否された新しい Promise オブジェクトを返します。

Promise.resolve(value)

与えられた値で解決された新しい Promise オブジェクトを返します。もし値が thenable (つまり then メソッドを持っているオブジェクト) ならば、返される Promise はその thenable をたどり、その結果を採用します。そうでなければ、返される Promise は与えられた値で解決されます。一般に、ある値が Promise かどうかがわからない場合は、Promise.resolve(value) を使って Promise にして扱います。

Promise プロトタイプ

プロパティ

Promise.prototype.constructor

インスタンスのプロトタイプを生成した関数を返します。デフォルトで、Promise関数です。

メソッド

Promise.prototype.catch(onRejected)

プロミスに失敗ハンドラコールバックを付加します。呼ばれるとコールバックの戻り値、または、オリジナルのプロミスが成功しているなら、その成功値によって完了している新しいプロミスを返します。

Promise.prototype.then(onFulfilled, onRejected)

プロミスに成功ハンドラと失敗ハンドラを付加します。呼ばれたハンドラの戻り値によって解決している新しいプロミスを返します。または、プロミスが扱われなかった場合 (つまり onFulfilled や onRejected が関数でない場合) には、元の完了した値に解決しているプロミスを返します。

Promise.prototype.finally()

プロミスにハンドラを付加し、元のプロミスが解決されたときに解決される新しいプロミスを返します。このハンドラは、成功か失敗かに関わらず、元のプロミスが完了したときに呼ばれます。

Promise を作成する

Promise オブジェクトは new キーワードとコンストラクターで作成されます。コンストラクターは executor 関数と呼ばれる引数を取ります。 executor 関数は 2 つの関数を引数として取ります。1 つめの関数 (resolve) は非同期タスクが成功して完了した場合に呼び出され、タスクの結果を値として返します。2 つめの関数 (reject) はタスクが失敗した場合に呼び出され、失敗した理由 (典型的には error オブジェクト) を返します。

const myFirstPromise = new Promise((resolve, reject) => {
  // do something asynchronous which eventually calls either:
  //
  //   resolve(someValue); // fulfilled
  // or
  //   reject("failure reason"); // rejected
});

Promise 機能を持つ関数を作るには、単純に Promise オブジェクトを返すようにします。

function myAsyncFunction(url) {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.open("GET", url);
    xhr.onload = () => resolve(xhr.responseText);
    xhr.onerror = () => reject(xhr.statusText);
    xhr.send();
  });
}

例

基本的な使用例

let myFirstPromise = new Promise((resolve, reject) => {
  // We call resolve(...) when what we were doing asynchronously was successful, and reject(...) when it failed.
  // In this example, we use setTimeout(...) to simulate async code. 
  // In reality, you will probably be using something like XHR or an HTML5 API.
  setTimeout(function(){
    resolve("Success!"); // Yay! Everything went well!
  }, 250);
});

myFirstPromise.then((successMessage) => {
  // successMessage is whatever we passed in the resolve(...) function above.
  // It doesn't have to be a string, but if it is only a succeed message, it probably will be.
  console.log("Yay! " + successMessage);
});

応用例

<button id="btn">Make a promise!</button>
<div id="log"></div>

以下の例は Promise の仕組みを示したものです。 testPromise() メソッドは <button> をクリックする度に呼び出されます。testPromise() メソッドは、 window.setTimeout() を用いて、1秒から 3秒のランダムな時間の後、メソッドがこれまでに呼ばれた回数で成功する Promise を作成します。 Promise() コンストラクターは Promise を作成するために使用されます。

Promise の成功は、 p1.then() で設定されたコールバックによって記録されます。この記録から、メソッドの同期処理部分が、 Promise による非同期処理からどのように分離されているかがわかります。

'use strict';
var promiseCount = 0;

function testPromise() {
    let thisPromiseCount = ++promiseCount;

    let log = document.getElementById('log');
    log.insertAdjacentHTML('beforeend', thisPromiseCount +
        ') 開始 (<small>同期処理開始</small>)<br/>');

    // 新しい Promise を作成: 1～3秒後に結果を返すことを約束します
    let p1 = new Promise(
        // executor 関数は Promise の成功または失敗に応じて呼ばれます
       (resolve, reject) => {
            log.insertAdjacentHTML('beforeend', thisPromiseCount +
                ') Promise 開始 (<small>非同期処理開始</small>)<br/>');
            // 非同期を作成するための一例です
            window.setTimeout(
                function() {
                    // 約束を果たしました!
                    resolve(thisPromiseCount);
                }, Math.random() * 2000 + 1000);
        }
    );

    // Promise が成功した時に何をするかを定めます then() で成功した時
    // catch() で失敗した時
    p1.then(
        // メッセージと値を記録します
        function(val) {
            log.insertAdjacentHTML('beforeend', val +
                ') Promise 成功 (<small>非同期処理終了</small>)<br/>');
        }).catch(
        // 失敗した理由を記録します
       (reason) => {
            console.log('Handle rejected promise ('+reason+') here.');
        });

    log.insertAdjacentHTML('beforeend', thisPromiseCount +
        ') Promise は作成されました (<small>同期処理終了</small>)<br/>');
}

if ("Promise" in window) {
  let btn = document.getElementById("btn");
  btn.addEventListener("click",testPromise);
} else {
  log = document.getElementById('log');
  log.innerHTML = "Live example not available as your browser doesn't support the <code>Promise<code> interface.";
}

この例はボタンをクリックすると実行されます。あなたのブラウザーが Promise に対応している必要があります。短い時間の間に何度かボタンをクリックすると、それぞれの promise が次々と成功するのがわかります。

XHR による画像の読み込み

Promise と XMLHttpRequest で画像を読み込む別の例は、 MDN GitHub js-examples リポジトリにあり、動作を確認することができます。それぞれの行のコメントで Promise と XHR の構造がよくわかるはずです。

仕様書

ブラウザーの互換性

互換性データに協力していただけるのであれば、 https://github.com/mdn/browser-compat-data に対してプルリクエストを書いてください。

関連情報

• Promise の使用
• Promises/A+ specification
• Venkatraman.R - JS Promise (Part 1, Basics)
• Venkatraman.R - JS Promise (Part 2 - Using Q.js, When.js and RSVP.js)
• Venkatraman.R - Tools for Promises Unit Testing
• Jake Archibald: JavaScript Promises: There and Back Again
• Domenic Denicola: Callbacks, Promises, and Coroutines – Asynchronous Programming Patterns in JavaScript
• Matt Greer: JavaScript Promises ... In Wicked Detail
• Forbes Lindesay: promisejs.org
• Speed-polyfill to polyfill both promise availability and promise performance.
• Promise polyfill
• Udacity: JavaScript Promises