diff options
| -rw-r--r-- | files/ja/web/javascript/reference/global_objects/promise/any/index.html | 152 | ||||
| -rw-r--r-- | files/ja/web/javascript/reference/global_objects/promise/any/index.md | 136 |
2 files changed, 136 insertions, 152 deletions
diff --git a/files/ja/web/javascript/reference/global_objects/promise/any/index.html b/files/ja/web/javascript/reference/global_objects/promise/any/index.html deleted file mode 100644 index bca62a9a74..0000000000 --- a/files/ja/web/javascript/reference/global_objects/promise/any/index.html +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: Promise.any() -slug: Web/JavaScript/Reference/Global_Objects/Promise/any -tags: - - Experimental - - JavaScript - - Method - - NeedsCompatTable - - Promise - - Reference - - プロミス - - メソッド - - 実験的 -translation_of: Web/JavaScript/Reference/Global_Objects/Promise/any ---- -<div>{{JSRef}}</div> - -<p><code>Promise.any()</code> は {{JSxRef("Promise")}} オブジェクトの反復可能オブジェクトを受け取り、反復可能オブジェクトの中にあるプロミスの一つが満足するとすぐに、そのプロミスの値で解決される単一のプロミスを返します。反復可能オブジェクトの中に満足可能なプロミスがない場合 (与えられたプロミスがすべて拒否された場合)、返されたプロミスは {{JSxRef("AggregateError")}} という、個々のエラーをグループ化した {{JSxRef("Error")}} の新しいサブクラスで拒否されます。本質的には、このメソッドは {{JSxRef("Promise.all()")}} の反対です。</p> - -<div class="blockIndicator warning"> -<p><strong>警告!</strong> <code>Promise.any()</code> メソッドは実験的であり、すべてのブラウザーが対応しているわけではありません。現在は <a href="https://github.com/tc39/proposal-promise-any" rel="external">TC39 Candidate stage (Stage 4)</a> にあります。</p> -</div> - -<h2 id="Syntax" name="Syntax">構文</h2> - -<pre class="notranslate">Promise.any(<var>iterable</var>);</pre> - -<h3 id="Parameters" name="Parameters">引数</h3> - -<dl> - <dt><code><var>iterable</var></code></dt> - <dd><a href="/ja/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol">反復可能</a>オブジェクト、例えば {{JSxRef("Array")}} です。</dd> -</dl> - -<h3 id="Return_value" name="Return_value">返値</h3> - -<ul> - <li>渡された <var>iterable</var> が空の場合は、<strong>解決済みの</strong> {{JSxRef("Promise")}}。</li> - <li>渡された <var>iterable</var> がプロミスを含んでいない場合は、<strong>非同期に解決される</strong> {{JSxRef("Promise")}}。</li> - <li>それ以外の場合は<strong>待ち状態の</strong> {{JSxRef("Promise")}}。ここで返されたプロミスは、与えられた反復可能オブジェクト内のいずれかのプロミスが満足したとき、またはすべてのプロミスが拒否されたときに、非同期的に (スタックが空になるとすぐに) 解決または拒否されます。</li> -</ul> - -<h2 id="Description" name="Description">解説</h2> - -<p>このメソッドは、最初に満足するプロミスを返すのに便利です。1つのプロミスが満足した後に短絡するので、1つのプロミスが見つかったら他のプロミスが満足するのを待つことはありません。 {{JSxRef("Promise.all()")}} が満足した値の<em>配列</em>を返すのとは異なり、 (少なくとも1つのプロミスが満足したと仮定すると) 満足した値は 1 つしか得られません。これは、1つのプロミスが満足する必要があるが、どちらのプロミスが満足するかは関係ないときに有益な場合があります。また {{JSxRef("Promise.race()")}} が最初に<em>完了した</em>値 (満足または拒否のいずれか) を返すのとは異なり、このメソッドは最初に<em>満足した</em>値を返します。このメソッドは、最初のプロミスが満足するまでは、すべての拒否されたプロミスを無視します。</p> - -<h3 id="Fulfilment" name="Fulfilment">満足</h3> - -<p>渡されたプロミスのうちのいずれかが満足した場合、返却されるプロミスは他のプロミスが満足または拒否されているかどうかにかかわらず、満足したプロミスの値で非同期に満足します。</p> - -<ul> - <li>空の <var>iterable</var> が渡された場合は、このメソッドはすでに解決済みのプロミスを (同期的に) 返します。</li> - <li>渡されたプロミスのいずれかが満足するか、プロミスがない場合は、 <code>Promise.any</code> で返されるプロミスは非同期で満足します。</li> -</ul> - -<h3 id="Rejection" name="Rejection">拒否</h3> - -<p>渡されたすべてのプロミスが拒否された場合、 <code>Promise.any</code> は {{JSxRef("AggregateError")}} オブジェクトで非同期に拒否され、これは{{JSxRef("Error")}} を継承しており、拒否された値の配列を持つ <code>errors</code> プロパティを含みます。</p> - -<h2 id="Examples" name="Examples">例</h2> - -<h3 id="First_to_fulfil" name="First_to_fulfil">最初に満足するもの</h3> - -<p><code>Promise.any()</code> は、先に拒否されたプロミスがあったとしても、最初に満足したプロミスで解決されます。これは {{jsxref("Promise.race()")}} が最初に決定したプロミスで解決または拒否されるのとは対照的です。</p> - -<pre class="brush: js notranslate">const pErr = new Promise((resolve, reject) => { - reject("Always fails"); -}); - -const pSlow = new Promise((resolve, reject) => { - setTimeout(resolve, 500, "Done eventually"); -}); - -const pFast = new Promise((resolve, reject) => { - setTimeout(resolve, 100, "Done quick"); -}); - -Promise.any([pErr, pSlow, pFast]).then((value) => { - console.log(value); - // pFast fulfils first -}) -// 期待される出力: "Done quick" -</pre> - -<h3 id="Rejections_with_AggregateError" name="Rejections_with_AggregateError">AggregateError での拒否</h3> - -<p><code>Promise.any()</code> は満足したプロミスがないと {{jsxref("AggregateError")}} で拒否されます。</p> - -<pre class="brush: js notranslate">const pErr = new Promise((resolve, reject) => { - reject('Always fails'); -}); - -Promise.any([pErr]).catch((err) => { - console.log(err); -}) -// 期待される出力: "AggregateError: No Promise in Promise.any was resolved" -</pre> - -<h3 id="Displaying_the_first_image_loaded" name="Displaying_the_first_image_loaded">最初に読み込まれた画像の表示</h3> - -<p>この例では、画像を読み込んで blob を返す関数があります。 <code>Promise.any()</code> を使用して二つの画像を読み込み、先に利用可能になった方 (つまり、プロミスが解決された方) を表示します。</p> - -<pre class="brush: js notranslate">function fetchAndDecode(url) { - return fetch(url).then(response => { - if(!response.ok) { - throw new Error(`HTTP error! status: ${response.status}`); - } else { - return response.blob(); - } - }) -} - -let coffee = fetchAndDecode('coffee.jpg'); -let tea = fetchAndDecode('tea.jpg'); - -Promise.any([coffee, tea]).then(value => { - let objectURL = URL.createObjectURL(value); - let image = document.createElement('img'); - image.src = objectURL; - document.body.appendChild(image); -}) -.catch(e => { - console.log(e.message); -});</pre> - -<h2 id="Specifications" name="Specifications">仕様書</h2> - -<table class="standard-table"> - <thead> - <tr> - <th scope="col">仕様書</th> - </tr> - </thead> - <tbody> - <tr> - <td>{{SpecName('Promise.any')}}</td> - </tr> - </tbody> -</table> - -<h2 id="Browser_compatibility" name="Browser_compatibility">ブラウザーの互換性</h2> - -<p>{{Compat("javascript.builtins.Promise.any")}}</p> - -<h2 id="See_also" name="See_also">関連情報</h2> - -<ul> - <li>{{JSxRef("Promise")}}</li> - <li>{{JSxRef("Promise.allSettled()")}}</li> - <li>{{JSxRef("Promise.all()")}}</li> - <li>{{JSxRef("Promise.race()")}}</li> -</ul> diff --git a/files/ja/web/javascript/reference/global_objects/promise/any/index.md b/files/ja/web/javascript/reference/global_objects/promise/any/index.md new file mode 100644 index 0000000000..e68101da41 --- /dev/null +++ b/files/ja/web/javascript/reference/global_objects/promise/any/index.md @@ -0,0 +1,136 @@ +--- +title: Promise.any() +slug: Web/JavaScript/Reference/Global_Objects/Promise/any +tags: + - JavaScript + - メソッド + - プロミス + - Reference + - Polyfill +browser-compat: javascript.builtins.Promise.any +translation_of: Web/JavaScript/Reference/Global_Objects/Promise/any +--- +{{JSRef}} + +`Promise.any()` は {{JSxRef("Promise")}} オブジェクトの集合の反復可能オブジェクトを受け取り、反復可能オブジェクトの中にあるプロミスの一つが履行されるとすぐに、そのプロミスの値で解決される単一のプロミスを返します。反復可能オブジェクトの中に履行されたプロミスがない場合 (与えられたプロミスがすべて拒否された場合)、返されたプロミスは {{JSxRef("AggregateError")}} という、個々のエラーをグループ化した {{JSxRef("Error")}} の新しいサブクラスで拒否されます。 + +{{EmbedInteractiveExample("pages/js/promise-any.html")}} + +## 構文 + + Promise.any(iterable); + +### 引数 + +- `iterable` + - : [反復可能](/ja/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol)オブジェクト、例えば {{JSxRef("Array")}} です。 + +### 返値 + +- 渡された*反復可能*オブジェクトが空の場合は、**拒否済みの** {{JSxRef("Promise")}} です。 +- 渡された*反復可能*オブジェクトにプロミスがなかった場合は、**非同期に解決**される {{JSxRef("Promise")}} です。 +- それ以外の場合は**待ち状態**の {{JSxRef("Promise")}} です。ここで返されたプロミスは、与えられた反復可能オブジェクト内のいずれかのプロミスが解決されたとき、またはすべてのプロミスが拒否されたとき、**非同期的に** (スタックが空になるとすぐに) 解決または拒否されます。 + +## 解説 + +このメソッドは、最初に履行されたプロミスを返すのに便利です。 1 つのプロミスが履行した後に短絡するので、 1 つのプロミスが見つかったら他のプロミスが履行されるのを待つことはありません。 {{JSxRef("Promise.all()")}} が履行値の*配列*を返すのとは異なり、 (少なくとも 1 つのプロミスが履行したと仮定すると) 履行値は 1 つしか得られません。これは、 1 つのプロミスが履行される必要があるが、どのプロミスが履行されるかは関係ないときに有益な場合があります。なお、もう一つの違いとして、このメソッドは*空の反復可能*オブジェクトを受け取ったときには拒否されます。 + +また、 {{JSxRef("Promise.race()")}} が最初に*決定*された値 (履行されたか拒否されたか) を返すのとは異なり、このメソッドは最初に*履行*された値を返します。このメソッドは、最初にプロミスが履行されるまで、すべての拒否されたプロミスを無視します。 + +### 履行の場合 + +返却されたプロミスは、引数として渡された*反復可能*オブジェクトの中で**最初に**解決された値 (またはプロミスではない値) で解決します。 + +- 空でない*反復可能*オブジェクトが渡され、**いずれか**のプロミスが履行されたか、プロミスではなかった場合、このメソッドから返却されるプロミスは非同期に履行されます。 + +### 拒否の場合 + +渡されたすべてのプロミスが拒否された場合、 `Promise.any` は {{JSxRef("AggregateError")}} オブジェクトで非同期に拒否されます。これはを継承しており、拒否された値の配列を持つ errors` プロパティを含みます。 + +- 空の*反復可能*オブジェクトが渡された場合、このメソッドから返却されたプロミスは同期的に拒否されます。拒否の理由は `AggregateError` オブジェクトであり、その `errors` プロパティは空の配列になります。 + +## 例 + +### 最初に履行されるもの + +`Promise.any()` は、先に拒否されたプロミスがあったとしても、最初に履行されたプロミスで解決されます。これは {{jsxref("Promise.race()")}} が、最初に決定されたプロミスで解決または拒否されるのとは対照的です。 + +```js +const pErr = new Promise((resolve, reject) => { + reject("Always fails"); +}); + +const pSlow = new Promise((resolve, reject) => { + setTimeout(resolve, 500, "Done eventually"); +}); + +const pFast = new Promise((resolve, reject) => { + setTimeout(resolve, 100, "Done quick"); +}); + +Promise.any([pErr, pSlow, pFast]).then((value) => { + console.log(value); + // pFast fulfils first +}) +// 期待される出力: "Done quick" +``` + +### AggregateError での拒否 + +`Promise.any()` は履行されたプロミスがないと {{jsxref("AggregateError")}} で拒否されます。 + +```js +const pErr = new Promise((resolve, reject) => { + reject('Always fails'); +}); + +Promise.any([pErr]).catch((err) => { + console.log(err); +}) +// 期待される出力: "AggregateError: No Promise in Promise.any was resolved" +``` + +### 最初に読み込まれた画像の表示 + +この例では、画像を読み込んで blob を返す関数があります。 `Promise.any()` を使用して二つの画像を読み込み、先に利用可能になった方 (つまり、プロミスが解決された方) を表示します。 + +```js +function fetchAndDecode(url) { + return fetch(url).then(response => { + if(!response.ok) { + throw new Error(`HTTP error! status: ${response.status}`); + } else { + return response.blob(); + } + }) +} + +let coffee = fetchAndDecode('coffee.jpg'); +let tea = fetchAndDecode('tea.jpg'); + +Promise.any([coffee, tea]).then(value => { + let objectURL = URL.createObjectURL(value); + let image = document.createElement('img'); + image.src = objectURL; + document.body.appendChild(image); +}) +.catch(e => { + console.log(e.message); +}); +``` + +## 仕様書 + +{{Specifications}} + +## ブラウザーの互換性 + +{{Compat}} + +## 関連情報 + +- `Promise.any` のポリフィルは [`core-js`](https://github.com/zloirock/core-js#ecmascript-promise) で利用できます +- {{JSxRef("Promise")}} +- {{JSxRef("Promise.allSettled()")}} +- {{JSxRef("Promise.all()")}} +- {{JSxRef("Promise.race()")}} |