Add a way to identify Abort errors originating from controllers

[benjamingr]

Hey,

I recently realized that it's now impossible (since .reason and .abort(reason)) to identify AbortErrors, it would be really useful if there was some way to identify them as originating from cancellation (timeout is cancellation in that it's not an exceptional case that should warrant monitoring probably).

It would be useful either to have a property on DOMExceptions that signal cancellation/timeout users can check or a branding check AbortSignal.isAbortError or similar.

This would enhance the ergonomics of using AbortSignals while allowing the flexibility of passing reason.

[kanongil]

Won't it always be safer to check signal.aborted / signal.reason when handling rejection errors? Even if you brand the errors, it could have originated from a different signal.

async function a({ signal }) {
  await b();
}

async function b() {
  const ab = new AbortController();
  ab.abort();
  throw ab.signal.reason;
}

try {
  const ac = new AbortController();
  await a({ signal: ac.signal });
}
catch (err) {
  console.log(err); // 'AbortError' DOMException
  console.log(ac.signal.aborted); // false
}

[benjamingr]

If you have a direct reference to the signal you might. You often do not have a reference to the signal which means you can't check err === signal.reason or signal.aborted.

Think "I'm instrumentation that needs to decide if an error is really exceptional and I need to wake up someone in the middle of the night or I'm just cancellation which I will happily ignore".

[kanongil]

You often do not have a reference to the signal.

I don't agree with this claim – especially the "often" part.

Do you have any concrete examples where you need to handle abort errors without access to the signal? Instrumentation could also access it, eg. fetch(…, { signal }) provides it as a parameter, which the instrumentation could extract. Also, I'm not sure it makes sense for instrumentation to determine the difference – it seems like something that should be handled at the app level.

[kanongil]

Hmm, it's not actually possible to brand all reason values, as any non-undefined value is a valid reason. ac.abort(false) is expected to reject with false.

[benjamingr]

@kanongil In this case "instrumentation" is something like APM (that presumably doesn't override fetch)

We have spent time talking to API consumers about this and have plenty of examples and use cases. Here is a common one (I'll use the web terminology since this is whatwg/dom but there are plenty of others).

• I have a framework over my web components / React.
• Components can "cancel rendering" because the user navigated away or the time allotment for rendering is up or an API request timed out.
• I have a high order component above those that needs to catch the timeout/cancellation and abort it (componentDidCatch in React speak).
• That component presumably does not have access to the signal (coming from a hook in the framework React speak).

This is just an example, it can be worked around (by for example making the signal global, injecting the signal to all components) but that would create pretty ugly code from what I recall.

I am happy to loop in library/sdk authors we have talked to about this in the past if that'd help.

[benjamingr]

Hmm, it's not actually possible to brand all reason values, as any non-undefined value is a valid reason. ac.abort(false) is expected to reject with false.

It would be great if we could prohibit non DOMExceptions as reasons even if it means a lot more work for Node.js in the future because I am a lot more worried about the "API surface increased and cancellation is hard to determine" problem than the "Node will have portability issues with it" problem.

[domenic]

I think the premise here is wrong. If the controller wants to send an "AbortError" DOMException, knowing some consumers will discriminate based on that, it can do so. But if it wants to send a TypeError, knowing some consumers are not specifically watching for that, it can. You should generally not write code that assumes all controller-caused errors are "third state" abort errors. The signal is telling you about an error, but that error has the usual semantics based on its type: some are "third state" abort errors, some are fatal failures of a different sort, some are timeouts, etc.

Perhaps it would have been better if AbortSignal were named ExceptionSignal, but the historical naming here shouldn't cause people to assume all controller-initiated exceptions are treated the same way (e.g. ignored).

[benjamingr]

But if it wants to send a TypeError, knowing some consumers are not specifically watching for that, it can.

Why is that capability good/useful?

You should generally not write code that assumes all controller-caused errors are "third state" abort errors.

Are there any non-third-state errors that are aborted with?

[domenic]

That capability is useful in the same way that exceptions in general are useful.

A signal-accepting API is one which gives its caller some amount of control over what exceptions it throws/rejections it returns/etc. Those exceptions can communicate anything: sometimes an abort, sometimes a timeout, sometimes a TypeError, sometimes a HTTP error (in a Node server), etc. The caller could use its controller to control the function and have it give a TypeError in exactly the situations a TypeError would normally be appropriate. (E.g., the caller has done some further async validation work and realized that the inputs are bad.)

Are there any non-third-state errors that are aborted with?

Any error can be the rejection reason. That's the point. When you accept a controlled signal, you are just giving the caller the ability to participate in your function's control flow.

[domenic]

Stated another way, the fact that a function accepts a signal should not change how you handle its errors. If you expect a function to return error types {X, Y, ...other stuff you don't care about}, and you want special handling for X and Y, then just add special handling for those, and rethrow the rest. It doesn't matter which among X/Y/other stuff come from logic provided by the controller, vs. the function body.

[Jamesernator]

Just to point out another example, accepting an AbortSignal that can signal any error is not significantly different from accepting a function that can throw an arbitrary error. In either case if you don't know where the signal/function is coming from, then you can't reasonably expect to handle any error it could throw.

i.e. Like this could throw any error:

async function someTask(transformResult=(result) => result) {
    const data = await loadDataSomehow();
    const transformed = await transformResult(data);
    return transformed;
}

If you're not in control of the transformResult function, then you can't really expect to be able to distinguish errors thrown from transformResult vs from within loadDataSomehow. In this way AbortSignal works the same, if you don't have the signal/controller you can't do anything to control how it behaves, or even know how the errors were generated.

[benjamingr]

@Jamesernator that's a good analogy but you'll find few (if at all) places in the DOM that have this behaviour. Event listeners for example "wrap" error handling internally and call the host error handler rather than "throw it back" to the dispatchEvent call.

@domenic I think I was confused about how this works?

If a user does

const ac = new AbortController();
const fetchResult = fetch('.../', { signal: ac.signal });
ac.abort(new TypeError());

Is fetchResult rejected with an ERR_ABORT DOMException and the user can access ac.signal.reason for metadata or is the goal (eventually) for promise APIs to reject with ac.signal.reason?

[annevk]

The goal is to reject with the reason. #1030 tracks this.