AbortSignal.timeout()

[shaseley]

Braw mornin' TAG!

I'm requesting a TAG review of AbortSignal.timeout(milliseconds).

This introduces a new static method, AbortSignal.timeout(milliseconds), which returns a newly-created AbortSignal that, after milliseconds milliseconds, becomes automatically aborted. The AbortSignal's reason property will be a "TimeoutError" DOMException. The main motivating use case for this is helping web developers easily time out async operations, such as fetch().

• Explainer¹ (minimally containing user needs and example code): Introduce AbortSignal.timeout() whatwg/dom#1032 (comment)
• Specification URL: [spec url] DOM PR: Introduce AbortSignal.timeout() whatwg/dom#1032
• Tests: [wpt folder(s), if available] To be added to https://github.com/web-platform-tests/wpt/tree/master/dom/abort
• User research: None
• Security and Privacy self-review²: https://gist.github.com/shaseley/2d3e76d98151811f1517f4380a12fe2b
• GitHub repo (if you prefer feedback filed there): Introduce AbortSignal.timeout() whatwg/dom#1032
• Primary contacts (and their relationship to the specification):
  • Domenic Denicola (@domenic, Google, specifier)
  • Scott Haseley (@shaseley, Google, Chromium implementer)
• Organization(s)/project(s) driving the specification: WHATWG github issues (see below)
• Key pieces of existing multi-stakeholder review or discussion of this specification:
  • Issue: Add AbortSignal.timeout(ms) whatwg/dom#951
  • PR: Introduce AbortSignal.timeout() whatwg/dom#1032
  • Related issue, for fetch(): Add a timeout option, to prevent hanging whatwg/fetch#951
• External status/issue trackers for this specification (publicly visible, e.g. Chrome Status):
  • https://chromestatus.com/feature/5768400507764736

Further details:

• I have reviewed the TAG's Web Platform Design Principles
• Relevant time constraints or deadlines: No deadline, but the spec PR has been approved and has support from multiple implementers, so I'd expect the first implementation and PR will both land soon.
• The group where the work on this specification is currently being done: WHATWG
• The group where standardization of this work is intended to be done (if current group is a community group or other incubation venue): N/A
• Major unresolved issues with or opposition to this specification: None known
• This work is being funded by: Google

We'd prefer the TAG provide feedback as (please delete all but the desired option):

💬 leave review feedback as a comment in this issue and @-notify [@domenic, @shaseley ]

[LeaVerou]

We looked at this today, and had a question about the design of this API. Why is this a new factory method (especially on a non constructible class, AbortSignal) instead of a parameter in the AbortController constructor, that would also allow combining with regular signal functionality?

Also, we wondered if there are any plans for extending or cancelling the timeout.

[domenic]

We looked at this today, and had a question about the design of this API. Why is this a new factory method (especially on a non constructible class, AbortSignal) instead of a parameter in the AbortController constructor

The idea is that there is no web-developer-visible AbortController for this AbortSignal; the browser holds onto the ability to control the signal, instead of the web developer. (In particular, the browser uses that ability to signal after the timeout.)

instead of a parameter in the AbortController constructor, that would also allow combining with regular signal functionality?

I'm not sure what you mean by this? In general combining works at the level of signals, not controllers.

Also, we wondered if there are any plans for extending or cancelling the timeout.

This was proposed in whatwg/dom#1039 but the use cases were rather esoteric. My current opinion is that it is not necessary to give such full control; if a developer wants that they can just use setTimeout + AbortController themselves. This is a simple factory method to make the 95% case easier, e.g. by not having the developer need to care about controllers, just getting a signal in a single line of code.