support AbortSignal.reason

[gomain]

In enviroments that implement it.

When an AbortSignal#reason has a value, i.e. in nodejs >= v17.2.0, it is added on the returned AbortError. AbortError#reason would be undefined otherwise.

Contrary to the specification, when AbortController#abort is called, with or without a reason, fetch does not throw the AbortSignal#reason. This is to allow more fine grained error handling. Had the reason was thrown, the general information that an abort happened is lost and it becomes sole responsibility of the reason provider.

Purpose

Allow detecting the reason fetch was aborted.

Changes

• Extend AbortError to have field reason. It's constructor takes this additional argument.
• The AbortSignal#reason is given when constructing AbortError instance. Could possibly be undefined in environments/libraries/polyfills that do not support it.

Additional information

The actual value (even existence) of AbortSignal#reason is external to this library. We make no assumptions about it. We simply forward it.

This goes against #1519. There is no inherent reason to follow the specifications to the dot. node-fetch is for node, specifically, not the web. TBD.

---

• I updated readme
• I added unit test(s)

---

• fix AbortController abort reason Parameter #1462

[LinusU]

Is this a breaking change?

AbortError is exported publicly from the package...

[gomain]

Yeah, wasn't aware the constructor was actually exported. It just seemed odd that the type would be explicitly given, i.e. what else could it be.

We basically need to thread the reason into the thrown AbortError. To not break its constructor, the only sane option would be to extend it:

  // no change to existing `AbortError`
  class AbortWithReasonError extends AbortError {
    constructor(message, reason) {
      super(message);
      this.reason = reason;
    }
  }