Using The Response

Requests return a subclass of Promise we call a Future.

Special Powers

Futures expose a number of crucial features for working with requests.

• lid which gives access to the identity of the request
• getStream() which will resolve to the response stream once it is available
• abort() which will attempt to abort the request.

Return Values

Futures both resolve and reject with an object ({ request, response, content }) representing the original RequestInfo, the Response set by the handler chain (if any), and the processed content.

Errors

If the Future rejects, it throws either an Error an AggregateError or a DOMException that maintains the { request, response, content } shape but is also an Error instance itself.

If using the error originates from the Fetch Handler the error will be a FetchError

Consuming The Response

On their own, Futures may appear to have an overly verbose return shape and the value of the features they enhance promises with may not be immediately clear. But this is because in the general case it is expected that you won't resolve the future yourself with await, but instead will pass it around your app as a value.

Maintaining access to the Future's reference allows you to use it with declarative reactive paradigms using utilities such as getRequestState or components like <Request />.

We call this Reactive Control Flow, you may want to watch the talk where we introduced this feature.

Response Content

The content property contains whatever the request handler pipeline resolves with. For requests that do not use the cache, this will be whatever the last handler to process the response returns.

For requests that do use the cache (most requests), the content property will be a ReactiveDocument.

💡 TIP

Whether a request uses the cache (or doesn't) is not governed by whether the request is cacheable (has a RequestKey) but by whether the request should interact with the Cache. See the caching guide for more info.