fix: abort timed-out requests with TimeoutError

[manwithacat]

Description

Request timeouts called AbortController.abort() with no reason, so a timeout and an hx-sync replace were both AbortError. Pass TimeoutError ("Request timed out") as the abort reason so apps can tell them apart via ctx.request.signal.reason.

Corresponding issue: #4021

Demo: https://manwithacat.github.io/htmx/demos/timeout-error-reason/

Testing

Existing timeout test now asserts signal.reason.name === 'TimeoutError'. Added a replace-abort case that is not TimeoutError. Documented the discriminator on htmx:error.

Local npm test (Chromium, same as CI htmx_tests): 87 files, 1739 passed, 0 failed, 5 skipped.

Checklist

• I have read the contribution guidelines
• I have targeted this PR against four-dev
• This is a bugfix
• Full browser suite — CI; __issueRequest unit tests cover timeout vs replace

[salomvary]

Would it make sense to name the DOMException something htmx specific so that it is not going to get confused with a "native" TimeoutError? https://developer.mozilla.org/en-US/docs/Web/API/DOMException#timeouterror

Something like signal.reason.name === 'htmx.TimeoutError'?

[manwithacat]

Good question. I used the standard TimeoutError name on purpose so this matches AbortSignal.timeout() and the usual reason.name === 'TimeoutError' check.

The distinction between an htmx timeout and a “native” timeout is empty: they are the same kind of event. The request ran out of time. Colliding with the platform TimeoutError is the goal, not something to avoid.

A custom htmx.TimeoutError would only help if we needed to tell htmx’s timer apart from another timeout on the same signal, which isn’t the #4021 case.

[salomvary]

A custom htmx.TimeoutError would only help if we needed to tell htmx’s timer apart from another timeout on the same signal, which isn’t the #4021 case.

I'm not sure that's true. My use case, which I think is the same problem as outlined in #4021 is the following: as a lazy solution to handling all sorts of network errors and unexpected server responses, we show a generic "something went wrong" error notification in the UI whenever an htmx:error event is triggered.

And the problem we are seeing with htmx 4 is the very specific hx-sync="this:replace" case, where htmx itself aborts "obsolete" pending requests, in which case we don't want to show an error notification, because this is "business as usual".

But I might as well be misreading what/how this fix achieves :)

[manwithacat]

With the patch:

• an hx-sync="this:replace" cancellation still has signal.reason.name === "AbortError"
• an actual request timeout has signal.reason.name === "TimeoutError"

So in your generic htmx:error handler you can treat AbortError as the expected “obsolete request was replaced” case and ignore it, while still treating TimeoutError as a genuine failure.

The reason I used the standard TimeoutError name rather than htmx.TimeoutError is that there doesn’t seem to be any additional htmx-specific distinction to encode here. A timeout produced by htmx’s timer has the same semantics as AbortSignal.timeout(): the operation exceeded its allotted time.

I do think your separate point about this being a behavioural change from htmx 2 is worth documenting. If htmx:error now includes expected cancellations such as hx-sync replacement, applications with a generic error handler need to know that they should discriminate on the abort reason.

[MichaelWest22]

Yeah in the ideal world we would actually use AbortSignal.timeout and not use our own custom setTimeout. But for this to work we need to wrap it in AbortSignal.any() so we can keep the manual abort as an option as well and these two features are too newly released to be used yet in htmx without expensive fallback code.

to keep the code change minimal we should just be returning a text error reason directly like:

ctx.requestTimeout = setTimeout(() => ctx.request?.abort?.('timeout'), timeout);

or maybe 'RequestTimeout'
This makes it clear it is just a custom timeout being reported by htmx and not trying to fake a standard abort signal error.

but aborts via hx-sync or manual htmx:abort events are not errors but are thrown as errors to be caught by the abort controller we use. so we should probably also do:

            } catch (error) {
                ctx.status = "error: " + error;
                if (error?.name !== 'AbortError') this.__trigger(elt, "htmx:error", {ctx, error})
            } finally {

to swallow this expected thrown error ideally

[salomvary]

This might deserve to be documented as a breaking change when upgrading htmx 2 to 4...