Re: [whatwg/streams] Add explainer for WritableStreamDefaultController's AbortSignal (#1162)

@domenic approved this pull request.

LGTM with mostly typographical nits. One substantial issue in the example code, `abortReason()` should be `abortReason`.

> @@ -0,0 +1,120 @@
+# WritableStream controller AbortSignal Explainer

```suggestion
# `WritableStream` controller `AbortSignal` Explainer
```

> +*   [abortReason](https://streams.spec.whatwg.org/#writablestreamdefaultcontroller-abortreason)
+    *   The argument passed to `writable.abort()` or `writer.abort()`. Undefined if no argument was passed or `abort()`
+    hasn't been called.
+*   [signal](https://streams.spec.whatwg.org/#writablestreamdefaultcontroller-signal)
+    *   An AbortSignal. By using `signal.addEventListener('abort', …)` an underlying sink can abort the pending write
+    or close operation when the stream is aborted.

```suggestion
*   [`abortReason`](https://streams.spec.whatwg.org/#writablestreamdefaultcontroller-abortreason): The argument passed to `writable.abort()` or `writer.abort()`. Undefined if no argument was passed or `abort()`
    hasn't been called.
*   [`signal`](https://streams.spec.whatwg.org/#writablestreamdefaultcontroller-signal): An `AbortSignal`. By using `signal.addEventListener('abort', …)` an underlying sink can abort the pending write
    or close operation when the stream is aborted.
```

> +streams such as [WebTransport](https://w3c.github.io/webtransport/).
+
+
+## API Proposed
+
+On [WritableStreamDefaultController](https://streams.spec.whatwg.org/#writablestreamdefaultcontroller)
+(the controller argument that is passed to underlying sinks):
+
+*   [abortReason](https://streams.spec.whatwg.org/#writablestreamdefaultcontroller-abortreason)
+    *   The argument passed to `writable.abort()` or `writer.abort()`. Undefined if no argument was passed or `abort()`
+    hasn't been called.
+*   [signal](https://streams.spec.whatwg.org/#writablestreamdefaultcontroller-signal)
+    *   An AbortSignal. By using `signal.addEventListener('abort', …)` an underlying sink can abort the pending write
+    or close operation when the stream is aborted.
+
+The WritableStream API does not change. Instead, the existing `abort()` operation will now signal abort.

```suggestion
The `WritableStream` API does not change. Instead, the existing `abort()` operation will now signal abort.
```

> +On [WritableStreamDefaultController](https://streams.spec.whatwg.org/#writablestreamdefaultcontroller)
+(the controller argument that is passed to underlying sinks):
+
+*   [abortReason](https://streams.spec.whatwg.org/#writablestreamdefaultcontroller-abortreason)
+    *   The argument passed to `writable.abort()` or `writer.abort()`. Undefined if no argument was passed or `abort()`
+    hasn't been called.
+*   [signal](https://streams.spec.whatwg.org/#writablestreamdefaultcontroller-signal)
+    *   An AbortSignal. By using `signal.addEventListener('abort', …)` an underlying sink can abort the pending write
+    or close operation when the stream is aborted.
+
+The WritableStream API does not change. Instead, the existing `abort()` operation will now signal abort.
+
+
+## Examples
+
+These are some examples of Javascript which can be used for writable streams once this is implemented:

```suggestion
These are some examples of JavaScript which can be used for writable streams once this is implemented:
```

> +
+## Examples
+
+These are some examples of Javascript which can be used for writable streams once this is implemented:
+
+In this example, the underlying sink write waits 1 second to simulate a long-running operation. However, if abort() is
+called it stops immediately.
+
+
+```javascript
+const ws = new WritableStream({
+  write(controller) {
+    return new Promise((resolve, reject) => {
+      setTimeout(resolve, 1000);
+      controller.signal.addEventListener('abort',
+        () => reject(controller.abortReason()));

```suggestion
        () => reject(controller.abortReason));
```

> +  write(controller) {
+    return new Promise((resolve, reject) => {
+      setTimeout(resolve, 1000);
+      controller.signal.addEventListener('abort',
+        () => reject(controller.abortReason()));
+    });
+  }
+});
+const writer = ws.getWriter();
+
+writer.write(99);
+await writer.abort();
+```
+
+
+This example shows integration with an existing API that uses AbortSignal. In this case, each write() triggers a POST

```suggestion
This example shows integration with an existing API that uses `AbortSignal`. In this case, each `write()` triggers a POST
```

> +// `ws` is a WritableStream.
+
+const reallyBigArrayBuffer = …;
+writer.write(reallyBigArrayBuffer);
+// Send RESET_STREAM to the server without waiting for `reallyBigArrayBuffer` to
+// be transmitted.
+await writer.abort();
+```
+
+
+
+## Goals
+
+*   Allow writes to be aborted more quickly and efficiently.
+*   WebTransport will be able to use WritableStreamDefaultController.signal to make
+[SendStream's write](https://w3c.github.io/webtransport/#sendstream-write) and

```suggestion
[`SendStream`'s `write()`](https://w3c.github.io/webtransport/#sendstream-write) and
```

> +
+const reallyBigArrayBuffer = …;
+writer.write(reallyBigArrayBuffer);
+// Send RESET_STREAM to the server without waiting for `reallyBigArrayBuffer` to
+// be transmitted.
+await writer.abort();
+```
+
+
+
+## Goals
+
+*   Allow writes to be aborted more quickly and efficiently.
+*   WebTransport will be able to use WritableStreamDefaultController.signal to make
+[SendStream's write](https://w3c.github.io/webtransport/#sendstream-write) and
+[close](https://w3c.github.io/webtransport/#sendstream-close) abortable.

```suggestion
[`close()`](https://w3c.github.io/webtransport/#sendstream-close) abortable.
```

> +
+*   Allow writes to be aborted more quickly and efficiently.
+*   WebTransport will be able to use WritableStreamDefaultController.signal to make
+[SendStream's write](https://w3c.github.io/webtransport/#sendstream-write) and
+[close](https://w3c.github.io/webtransport/#sendstream-close) abortable.
+
+
+## Non-Goals
+
+*   Exposing a method to abort individual operations without aborting the stream as a whole. The semantics of this
+would be unclear and confusing.
+
+
+## User Benefits
+
+*   Allows `abort` operation to complete more quickly, which avoids wasted resources for sites that take advantage of it.

```suggestion
*   Allows the abort operation to complete more quickly, which avoids wasted resources for sites that take advantage of it.
```

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/streams/pull/1162#pullrequestreview-741816787