Skip to content

Commit

Permalink
Aborting: clarify usage for non-promise APIs
Browse files Browse the repository at this point in the history
Also clean up some remaining instances that didn't use signal.reason.

Closes whatwg#961.
  • Loading branch information
annevk committed Dec 6, 2021
1 parent 3e51b89 commit 982c7e2
Showing 1 changed file with 10 additions and 6 deletions.
16 changes: 10 additions & 6 deletions dom.bs
Original file line number Diff line number Diff line change
Expand Up @@ -1667,7 +1667,7 @@ The API which wishes to support aborting can accept an {{AbortSignal}} object, a
determine how to proceed.

<p>APIs that rely upon {{AbortController}} are encouraged to respond to {{AbortController/abort()}}
by rejecting any unsettled promise with a new "{{AbortError!!exception}}" {{DOMException}}.
by rejecting any unsettled promise with the {{AbortSignal}}'s [=AbortSignal/abort reason=].

<div class=example id=aborting-ongoing-activities-example>
<p>A hypothetical <code>doAmazingness({ ... })</code> method could accept an {{AbortSignal}} object
Expand Down Expand Up @@ -1696,24 +1696,28 @@ controller.abort();</code></pre>
<pre><code class=lang-javascript>
function doAmazingness({signal}) {
if (signal.aborted) {
return Promise.reject(new DOMException('Aborted', 'AbortError'));
return Promise.reject(signal.reason);
}

return new Promise((resolve, reject) => {
// Begin doing amazingness, and call resolve(result) when done.
// But also, watch for signals:
signal.addEventListener('abort', () => {
// Stop doing amazingness, and:
reject(new DOMException('Aborted', 'AbortError'));
reject(signal.reason);
});
});
}
</code></pre>

<p>APIs that require more granular control could extend both {{AbortController}} and
{{AbortSignal}} objects according to their needs.
</div>

<p>APIs that do not return promises can either react in an equivalent manner or opt to not surface
the {{AbortSignal}}'s [=AbortSignal/abort reason=] at all. {{EventTarget/addEventListener()}} is an
example of an API where the latter made sense.

<p>APIs that require more granular control could extend both {{AbortController}} and
{{AbortSignal}} objects according to their needs.


<h3 id=interface-abortcontroller>Interface {{AbortController}}</h3>

Expand Down

0 comments on commit 982c7e2

Please sign in to comment.