Skip to content

Aborting: clarify usage for non-promise APIs #1040

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 6, 2021
Merged

Aborting: clarify usage for non-promise APIs #1040

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions dom.bs
View file
Open in desktop
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