Promise.reject()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Promise.reject() は静的メソッドで、引数で与えられた理由で拒否された Promise オブジェクトを返します。

試してみましょう

構文

js
Promise.reject(reason)

引数

reason

この Promise が拒否された理由です。

返値

与えられた理由で拒否された Promise です。

解説

静的な Promise.reject 関数は拒否された Promise を返します。デバッグのために捕捉するエラーを選別したい場合は、 reasoninstanceof Error にかけると良いでしょう。

Promise.reject() は汎用的であり、サブクラス化に対応しています。つまり、 Promise のサブクラスで呼び出すことができ、その結果はサブクラスの種類のプロミスになります。これを行うには、サブクラスのコンストラクターは Promise() コンストラクターと同じ呼び出し定義を実装する必要があります。これは、 resolvereject コールバックを引数として呼び出すことができる単一の executor 関数を引数に取ります。 Promise.reject() は、本質的に new Promise((resolve, reject) => reject(reason)) の短縮形です。

Promise.resolve() とは異なり、 Promise.reject()reason がすでに Promise であっても、常に新しい Promise オブジェクトで reason をラップします。

静的な Promise.reject() メソッドの使用

js
Promise.reject(new Error("fail")).then(
  () => {
    // not called
  },
  (error) => {
    console.error(error); // Stacktrace
  },
);

プロミスの拒否

Promise.resolve とは異なり、 Promise.reject メソッドは既存の Promise インスタンスを再利用することはありません。常に reason を包んだ新しい Promise インスタンスを返します。

js
const p = Promise.resolve(1);
const rejected = Promise.reject(p);
console.log(rejected === p); // false
rejected.catch((v) => {
  console.log(v === p); // true
});

Promise 以外のコンストラクターに対する reject() の呼び出し

Promise.reject() は汎用的なメソッドです。これは Promise() コンストラクターと同じ呼び出し定義を実装した任意のコンストラクターで呼び出すことができます。例えば、 console.logreject として渡すコンストラクターで呼び出すことができます。

js
class NotPromise {
  constructor(executor) {
    // The "resolve" and "reject" functions behave nothing like the
    // native promise's, but Promise.reject() calls them in the same way.
    executor(
      (value) => console.log("Resolved", value),
      (reason) => console.log("Rejected", reason),
    );
  }
}

Promise.reject.call(NotPromise, "foo"); // Logs "Rejected foo"

仕様書

Specification
ECMAScript Language Specification
# sec-promise.reject

ブラウザーの互換性

BCD tables only load in the browser

関連情報