2023/05/10 時点の英語版に同期

mdn · Sep 22, 2023 · 2db0b85 · 2db0b85
1 parent 672c74c
commit 2db0b85
Show file tree

Hide file tree

Showing 5 changed files with 172 additions and 61 deletions.
diff --git a/files/ja/web/api/readablebytestreamcontroller/byobrequest/index.md b/files/ja/web/api/readablebytestreamcontroller/byobrequest/index.md
@@ -1,30 +1,51 @@
 ---
-title: ReadableByteStreamController.byobRequest
+title: "ReadableByteStreamController: byobRequest プロパティ"
+short-title: byobRequest
 slug: Web/API/ReadableByteStreamController/byobRequest
+l10n:
+  sourceCommit: d41c5446d4ef257280fae9b78e2298ced8954a95
 ---
 
-{{SeeCompatTable}}{{APIRef("Streams")}}
+{{APIRef("Streams")}}
 
-{{domxref("ReadableByteStreamController")}} インターフェイスの **`byobRequest`** 読み取り専用プロパティは、現在の BYOB プルリクエストを返します。 保留中のリクエストがない場合は `undefined` を返します。
+**`byobRequest`** は {{domxref("ReadableByteStreamController")}} インターフェイスの読み取り専用プロパティで、現在の BYOB リクエストを返します。保留中のリクエストがない場合は `null` を返します。
 
-## 構文
-
-```
-var request = readableByteStreamController.byobRequest;
-```
+基盤となるバイトソースはこのプロパティを調べ、存在する場合はそれを使用してストリームにデータを書き込む必要があります（{{domxref("ReadableByteStreamController.enqueue()")}}を使用するのではなく）。
+こうすることで、コンシューマーへのデータの効率的なゼロバイト移譲が実現します。
 
 ### 値
 
-{{domxref("ReadableStreamBYOBRequest")}} オブジェクトのインスタンス、または `undefined`。
+{{domxref("ReadableStreamBYOBRequest")}} オブジェクトのインスタンス、または `null`。
 
 ## 例
 
-未定。
+[読み取り可能なバイトストリームの使用 > 読み取り可能なソケットプッシュバイトストリームの作成](/ja/docs/Web/API/Streams_API/Using_readable_byte_streams#読み取り可能なソケットプッシュバイトストリームの作成)の例では、 `byobRequest` を使用して（データが存在する場合は）データを移譲するか、 {{domxref("ReadableByteStreamController.enqueue()")}} を使用してストリーム内部のキューにデータをコピーする方法を示しています。
+
+関連するコードを下記に示します。
+`byobRequest` が存在すれば、 {{domxref("ReadableStreamBYOBRequest.view","controller.byobRequest.view")}} にデータが読み込まれ、 {{domxref("ReadableStreamBYOBRequest.respond()")}} が呼び出されて、移譲可能なデータ量を指示します。
+
+```js
+if (controller.byobRequest) {
+  const v = controller.byobRequest.view;
+  bytesRead = socket.readInto(v.buffer, v.byteOffset, v.byteLength);
+  if (bytesRead === 0) {
+    controller.close();
+  }
+  controller.byobRequest.respond(bytesRead);
+} else {
+  // Write to data using enqueue().
+}
+```
 
-## 仕様
+## 仕様書
 
 {{Specifications}}
 
 ## ブラウザーの互換性
 
-{{Compat("api.ReadableByteStreamController.byobRequest")}}
+{{Compat}}
+
+## 関連情報
+
+- [読み取り可能なバイトストリームの使用](/ja/docs/Web/API/Streams_API/Using_readable_byte_streams)
+- {{domxref("ReadableByteStreamController")}}
diff --git a/files/ja/web/api/readablebytestreamcontroller/close/index.md b/files/ja/web/api/readablebytestreamcontroller/close/index.md
@@ -1,41 +1,65 @@
 ---
-title: ReadableByteStreamController.close()
+title: "ReadableByteStreamController: close() メソッド"
+short-title: close()
 slug: Web/API/ReadableByteStreamController/close
+l10n:
+  sourceCommit: dcce943de1c2fa0f6a82de3c90bc98285f27ed6f
 ---
 
-{{SeeCompatTable}}{{APIRef("Streams")}}
+{{APIRef("Streams")}}
 
-{{domxref("ReadableByteStreamController")}} インターフェイスの **`close()`** メソッドは、関連するストリームを閉じます。
+**`close()`** は {{domxref("ReadableByteStreamController")}} インターフェイスのメソッドで、関連するストリームを閉じます。
 
-> **メモ:** リーダーは、以前にキューに入れられたチャンクをストリームから読み取ることができますが、それらを読み取とってしまうとストリームは閉じられます。
+これは、そのデータソースが使い果たされたとき/完全に完了したときに、基盤ソースによって呼び出される可能性があります。
+
+> **メモ:** リーダーは、以前にキューに入れられたチャンクをストリームから読み取ることができますが、それらを読み取ってしまうとストリームは閉じられます。
+> しかし、 `close()` が呼び出されたときに、未処理で部分的に書き込まれた {{domxref("ReadableByteStreamController.byobRequest","byobRequest")}} がある場合、ストリームはエラーになります。
 
 ## 構文
 
-```
-readableByteStreamController.close();
+```js-nolint
+close()
 ```
 
-### パラメーター
+### 引数
 
 なし。
 
-### 戻り値
+### 返値
 
-`undefined`。
+なし ({{jsxref("undefined")}})。
 
 ### 例外
 
-- TypeError
+- {{jsxref("TypeError")}}
   - : ソースオブジェクトが `ReadableByteStreamController` ではないか、何らかの理由でストリームが読み取り可能ではありません。
 
 ## 例
 
-未定。
+[読み取り可能なバイトストリームの使用 > 読み取り可能なソケットプッシュバイトストリームの作成](/ja/docs/Web/API/Streams_API/Using_readable_byte_streams#読み取り可能なソケットプッシュバイトストリームの作成)の例で、データがなくなったときにストリームを閉じています。
+
+関連するコードを下記に示します。
+これは `readInto()` メソッドがデータがまだないときだけ 0 バイトを返すと仮定しています。
+
+```js
+bytesRead = socket.readInto(v.buffer, v.byteOffset, v.byteLength);
+if (bytesRead === 0) {
+  controller.close();
+}
+```
+
+closeを呼び出すと、ストリームは閉じられ、コンシューマーがあれば通知されます。
+例えば {{domxref("ReadableStreamBYOBReader")}} を使用している場合、 {{domxref("ReadableStreamBYOBReader.read()","read()")}} リクエストは `done: true` で解決され、 {{domxref("ReadableStreamBYOBReader.closed")}} からのプロミスも解決されます。
 
-## 仕様
+## 仕様書
 
 {{Specifications}}
 
 ## ブラウザーの互換性
 
-{{Compat("api.ReadableByteStreamController.close")}}
+{{Compat}}
+
+## 関連情報
+
+- [読み取り可能なバイトストリームの使用](/ja/docs/Web/API/Streams_API/Using_readable_byte_streams)
+- {{domxref("ReadableByteStreamController")}}
diff --git a/files/ja/web/api/readablebytestreamcontroller/desiredsize/index.md b/files/ja/web/api/readablebytestreamcontroller/desiredsize/index.md
@@ -1,30 +1,41 @@
 ---
-title: ReadableByteStreamController.desiredSize
+title: "ReadableByteStreamController: desiredSize プロパティ"
+short-title: desiredSize
 slug: Web/API/ReadableByteStreamController/desiredSize
+l10n:
+  sourceCommit: dcce943de1c2fa0f6a82de3c90bc98285f27ed6f
 ---
 
-{{SeeCompatTable}}{{APIRef("Streams")}}
+{{APIRef("Streams")}}
 
-{{domxref("ReadableByteStreamController")}} インターフェイスの **`desiredSize`** 読み取り専用プロパティは、ストリームの内部キューを満たすために必要な希望サイズを返します。
+**`desiredSize`** は {{domxref("ReadableByteStreamController")}} インターフェイスの読み取り専用プロパティで、ストリームの内部キューを満たすために必要な「希望サイズ」を返します。
 
-## 構文
+この値は、ストリームが、基盤となるソースへの推奨する流量を示すために使用します。
+データ流入のスロットリングや一時停止に対応しているソース（すべてではありません）は、ストリームバッファの `desiredSize` が正の値で、使用可能な限りゼロに近づくように流入を制御する必要があります。
 
-```
-var desiredSize = readableByteStreamController.desiredSize;
-```
+`desiredSize` は下流コンシューマーの[背圧](/ja/docs/Web/API/Streams_API/Concepts#背圧)を適用するために使用します。
 
-### 値
+## 値
 
-整数。 キューがいっぱいになった場合、これは負になる可能性があることに注意してください。
+整数です。キューがいっぱいになった場合、これは負になる可能性があることに注意してください。
+
+ストリームがエラーになったときは `null`、閉じられていたときは `0` になる可能性があります。
 
 ## 例
 
-未定。
+仕様書の [A readable stream with an underlying push source and backpressure support](https://streams.spec.whatwg.org/#example-rs-push-backpressure) の例には、ストリームが一杯になったことを手動で検出して背圧をかけるために `desiredSize` を使用する良い例が示されています。
+
+この例では既定のソースを使用していますが、概念は読み取り可能なバイトソースとまったく同じです。
 
-## 仕様
+## 仕様書
 
 {{Specifications}}
 
 ## ブラウザーの互換性
 
-{{Compat("api.ReadableByteStreamController.desiredSize")}}
+{{Compat}}
+
+## 関連情報
+
+- [読み取り可能なバイトストリームの使用](/ja/docs/Web/API/Streams_API/Using_readable_byte_streams)
+- {{domxref("ReadableByteStreamController")}}
diff --git a/files/ja/web/api/readablebytestreamcontroller/enqueue/index.md b/files/ja/web/api/readablebytestreamcontroller/enqueue/index.md
@@ -1,40 +1,64 @@
 ---
-title: ReadableByteStreamController.enqueue()
+title: "ReadableByteStreamController: enqueue() メソッド"
+short-title: enqueue()
 slug: Web/API/ReadableByteStreamController/enqueue
+l10n:
+  sourceCommit: d41c5446d4ef257280fae9b78e2298ced8954a95
 ---
 
-{{SeeCompatTable}}{{APIRef("Streams")}}
+{{APIRef("Streams")}}
 
-{{domxref("ReadableByteStreamController")}} インターフェイスの **`enqueue()`** メソッドは、所与のチャンクを関連するストリームのキューに入れます。
+**`enqueue()`** は {{domxref("ReadableByteStreamController")}} で、指定された塊を、関連する読み取り可能なバイトストリームのキューに入れます（塊はストリーム内部のキューにコピーされます）。
+
+これは、 {{domxref("ReadableByteStreamController.byobRequest","byobRequest")}} が `null` である場合にのみ、キューへのデータ移譲に使用しましょう。
 
 ## 構文
 
-```
-readableByteStreamController.enqueue(chunk);
+```js-nolint
+enqueue(chunk)
 ```
 
-### パラメーター
+### 引数
 
-- _chunk_
+- `chunk`
   - : キューに入れるチャンク。
 
-### 戻り値
+### 返値
 
-`undefined`。
+なし ({{jsxref("undefined")}})。
 
 ### 例外
 
-- TypeError
+- {{jsxref("TypeError")}}
   - : ソースオブジェクトが `ReadableByteStreamController` ではないか、何らかの理由でストリームを読み取れないか、チャンクがオブジェクトではないか、チャンクの内部配列バッファーが存在しないか、切り離されています。
+    ストリームが既に閉じられていたときにも発生します。
 
 ## 例
 
-未定。
+[読み取り可能なバイトストリームの使用 > 読み取り可能なソケットプッシュバイトストリームの作成](/ja/docs/Web/API/Streams_API/Using_readable_byte_streams#読み取り可能なソケットプッシュバイトストリームの作成) の例では、未処理の {{domxref("ReadableByteStreamController.byobRequest","byobRequest")}} がない場合に `enqueue()` を使用してデータをストリームにコピーする方法を示します。
+もし `byobRequest` があれば、それを使用しましょう。
 
-## 仕様
+下記のコードでは、「仮定の」 `socket.readInto()` メソッドを使用してデータを `ArrayBuffer` に読み込ませ、その後キューに入れています（ただし、実際にデータがコピーされた場合のみ）。
+
+```js
+const buffer = new ArrayBuffer(DEFAULT_CHUNK_SIZE);
+bytesRead = socket.readInto(buffer, 0, DEFAULT_CHUNK_SIZE);
+if (bytesRead === 0) {
+  controller.close();
+} else {
+  controller.enqueue(new Uint8Array(buffer, 0, bytesRead));
+}
+```
+
+## 仕様書
 
 {{Specifications}}
 
 ## ブラウザーの互換性
 
-{{Compat("api.ReadableByteStreamController.enqueue")}}
+{{Compat}}
+
+## 関連情報
+
+- [読み取り可能なバイトストリームの使用](/ja/docs/Web/API/Streams_API/Using_readable_byte_streams)
+- {{domxref("ReadableByteStreamController")}}
diff --git a/files/ja/web/api/readablebytestreamcontroller/index.md b/files/ja/web/api/readablebytestreamcontroller/index.md
@@ -1,24 +1,45 @@
 ---
 title: ReadableByteStreamController
 slug: Web/API/ReadableByteStreamController
+l10n:
+  sourceCommit: d41c5446d4ef257280fae9b78e2298ced8954a95
 ---
 
-{{APIRef("Streams")}}{{SeeCompatTable}}
+{{APIRef("Streams")}}
 
-[Streams API](/ja/docs/Web/API/Streams_API) の **`ReadableByteStreamController`** インターフェイスは、{{domxref("ReadableStream")}} の状態と内部キューを制御できるコントローラーを表します。 バイトストリームコントローラーは、バイトストリーム用です。
+**`ReadableByteStreamController`** は[ストリーム API](/ja/docs/Web/API/Streams_API) のインターフェイスで、[読み取り可能なバイトストリーム](/ja/docs/Web/API/Streams_API/Using_readable_byte_streams)コントローラーを表します。
+これは、基礎となるバイトソースを持つ {{domxref("ReadableStream")}} の状態と内部キューを制御し、ストリームの内部キューが空の場合に、基礎となるソースからコンシューマーへの効率的なゼロコピーデータ移譲を可能にします。
+
+このコントローラ型のインスタンスは、 `underlyingSource` オブジェクトに `type="bytes"` プロパティを設定して [`ReadableStream()` コンストラクター](/ja/docs/Web/API/ReadableStream/ReadableStream#type)の引数として渡された場合に作成されます。
+`underlyingSource` オブジェクトは [`start()`](/ja/docs/Web/API/ReadableStream/ReadableStream#start) および [`pull()`](/ja/docs/Web/API/ReadableStream/ReadableStream#pull) コールバック関数を定義することもできます。
+これらは、コントローラーを引数として呼び出され、 基盤となるソースを設定し、必要に応じてデータをリクエストします。
+
+基盤となるソースは、コントローラーを使用して [`byobRequest`](#readablebytestreamcontroller.byobrequest) プロパティまたは [`enqueue()`](#readablebytestreamcontroller.enqueue) メソッドでストリームにデータを供給します。
+[`byobRequest`](#readablebytestreamcontroller.byobrequest) は {{domxref("ReadableStreamBYOBRequest")}} オブジェクトで、コンシューマーから直接コンシューマーにゼロコピーでデータを移譲するための待機リクエストを表します。
+データが存在する場合は、`byobRequest` を使用してデータをコピーする必要があります（この場合は `enqueue()` を使用しないでください）。
+基盤となるソースがストリームにデータを渡す必要があり、 `byobRequest` が `null` の場合、ソースは [`enqueue()`](#readablebytestreamcontroller.enqueue) を呼び出して、ストリーム内部のキューにデータを追加することができます。
+
+[`byobRequest`](#readablebytestreamcontroller.byobrequest) は、リーダーからのリクエストがあり、ストリームの内部キューが空の場合にのみ、「BYOB モード」で作成されることに注意してください。
+「BYOB モード」は、 {{domxref("ReadableStreamBYOBReader")}} （通常、 {{domxref("ReadableStream.getReader()")}} を引数 `{ mode: 'byob' }` で呼び出すことで構築されます）を使用している場合に有効になります。
+既定値でリーダーを使用し、 [`autoAllocateChunkSize`](/ja/docs/Web/API/ReadableStream/ReadableStream#autoallocatechunksize) が [`ReadableController()` コンストラクター](/ja/docs/Web/API/ReadableStream/ReadableStream#autoallocatechunksize) で指定されている場合にも有効になります。
+
+基盤となるバイトソースは、コントローラーを使用して、すべてのデータが送信されたときにストリームを閉じたり ([`close()`](#readablebytestreamcontroller.close))、 [`error()`](#readablebytestreamcontroller.error) を使用して基盤となるソースからエラーを報告したりすることもできます。
+コントローラーの [`desiredSize`](#readablebytestreamcontroller.desiredsize) プロパティを使用して「背圧」をかけ、基盤となるソースに内部キューのサイズを通知します（値が小さいと、キューがいっぱいになっていることを示し、基盤となるソースに流入を一時停止またはスロットルすることが望ましいことを示唆します）。
+
+たとえコントローラーが主に基盤となるバイトソースによって使用されるとしても、ストリームの指示のためにシステムの他の部分によって格納することができない理由はないことに注意してください。
 
 ## コンストラクター
 
-なし。 `ReadableByteStreamController` インスタンスは、`ReadableStream` の構築中に自動的に作成されます。
+なし。 `ReadableByteStreamController` インスタンスは、 `underlyingSource` に `type="bytes"` プロパティが設定されたものが [`ReadableStream()` コンストラクター](/ja/docs/Web/API/ReadableStream/ReadableStream#type)に渡された場合、自動的に作成されます。
 
-## プロパティ
+## インスタンスプロパティ
 
-- {{domxref("ReadableByteStreamController.byobRequest")}} {{readonlyInline}}
-  - : 現在の BYOB プルリクエストを返します。
-- {{domxref("ReadableByteStreamController.desiredSize")}} {{readonlyInline}}
+- {{domxref("ReadableByteStreamController.byobRequest")}} {{ReadOnlyInline}}
+  - : 現在の BYOB プルリクエストを返します。未処理のリクエストがない場合は `null` となります。
+- {{domxref("ReadableByteStreamController.desiredSize")}} {{ReadOnlyInline}}
   - : ストリームの内部キューを満たすために必要な希望サイズを返します。
 
-## メソッド
+## インスタンスメソッド
 
 - {{domxref("ReadableByteStreamController.close()")}}
   - : 関連するストリームを閉じます。
@@ -29,12 +50,22 @@ slug: Web/API/ReadableByteStreamController
 
 ## 例
 
-未定。
+コントローラーは、データを移譲またはエンキューしたり、ストリームにデータがない（閉じられた）またはエラーとされていたことを指示するために、基盤となるソースによって使用されます。また、 {{domxref("ReadableByteStreamController.desiredSize","desiredSize")}} を使用して、希望するデータレートの「上流」から基盤ソースに指示するためにも使用します。
+
+[読み取り可能なバイトストリームの使用](/ja/docs/Web/API/Streams_API/Using_readable_byte_streams)の例、特に[読み取り可能なソケットプッシュバイトストリームの作成](/ja/docs/Web/API/Streams_API/Using_readable_byte_streams#読み取り可能なソケットプッシュバイトストリームの作成)がこれらのほとんどの場合を示します。
 
-## 仕様
+## 仕様書
 
 {{Specifications}}
 
 ## ブラウザーの互換性
 
-{{Compat("api.ReadableByteStreamController")}}
+{{Compat}}
+
+## 関連情報
+
+- [ストリーム API の概念](/ja/docs/Web/API/Streams_API)
+- [読み取り可能なバイトストリームの使用](/ja/docs/Web/API/Streams_API/Using_readable_byte_streams)
+- {{domxref("ReadableStream")}}
+- [WHATWG Stream Visualizer](https://whatwg-stream-visualizer.glitch.me/), for a basic visualization of readable, writable, and transform streams.
+- [Web-streams-polyfill](https://github.com/MattiasBuelens/web-streams-polyfill) or [sd-streams](https://github.com/stardazed/sd-streams) - polyfills