Add auto-abortion on timeout

[webJose]

Another potentially useful trigger for automatically aborting an HTTP request is a timeout value: If the call takes too long, let's bale out of it and inform the user.

Sample usage:

import { abortableRootFetcher, AbortReason } from './root-fetchers.js';

const response = await abortableRootFetcher
  .for<200, ...>()
  .get('/some/url', { autoAbort: { key: 'abc', timeout: 3_000 }});

if (response.aborted) {
  if (response.error.cause === AbortReason.timeout) {
    // Show the user a specialized message/UI.
  }
}

Here, AbortReason is an enumeration that developers can use to know the exact reason of the abortion.

[webJose]

I dislike the nested IF's syntax, which is required so TypeScript can properly type-narrow things.

Maybe getting rid of the aborted property is best, in favor of a new abortStatus property of type AbortReason:

export const AbortReason = Object.freeze({
  notAborted: 0,
  timeout: 1,
  newVersion: 2
});

Then user code would be:

if (response.abortStatus === AbortReason.notAborted) {
  // Normal code.
}
else if (response.abortStatus === AbortReason.timeout) {
  // Timeout code
}
... // etc.

[webJose]

Evolution

While I thought some more about this, maybe I can tackle the re-throw situation that currently goes on since abortable fetchers became a thing.

Maybe replacing aborted with failedStatus:

export const FailedStatus = Object.freeze({
  succeeded: 0x0,
  failed: 0x1_0000,
  aborted: 0x1_1000,
  timeout: 0x1_1001,
  superseeded: 0x1_1002,
});

Then we should be able to do:

const response = await abortableFetcher
  .for<200, MyData[]>()
  .get('/my/url');

// Aborted can be tested generally:
if (response.failedStatus & FailedStatus.aborted) { ... }
// Or I can test abort reasons directly:
if (response.failedStatus & FailedStatus.superseeded) { ... }
// Or I can test failure regardless of nature:
if (response.failedStatus) { ... }
if (response.failedStatus & FailedStatus.failed) { ... }

Inside all those if blocks, the error property is guaranteed, and the else blocks will have the HTTP response data, guaranteed. So no nested if statements, which I like better.