No cache outcome in operation context

[RaikoM]

Hello,

How can I know if data response was from cached result or new fetched result?

I looked at this Stackoverlfow thread but this is maybe outdated?

my client setup looks like this:

const client = new Client({
  url: MY_API_URL,
  exchanges: [
    cacheExchange,
    mapExchange,
    fetchExchange
  ]
});

[probablykabari]

Are you referring to the response from your own server being from cache? Or the data shown by urql if you have a cache-first or cache-then-network? The default for urql is cache-first so it will not make the network request in the data is cached already, given your above configuration.

https://formidable.com/open-source/urql/docs/basics/document-caching/#request-policies

[RaikoM]

Data shown by urql useQuery when I have cache-first.

Example:
Query 1 - No urql cache exists, network call is made.
Query 2 - Cache exists, no network call.

From stackoverflow, there should be or was at some point, in response operation object, a key that would tell if urql response is from urql cache "hit" or network call "miss".

I would like to know, if from useQuery response (under operation or something else maybe) it is possible to tell if response was from urql document cache or network call. Maybe I simply forgot to configure something.

[kitten]

tl;dr:

• If you're trying to keep data fresh while using Graphcache, requestPolicyExchange, or a custom approach, that sets cache-and-network to update data when it's getting “old” works
• If you're refetching data explicitly (via a reexecute binding mechanism) or are using partial results in Graphcache (via schema awareness or @_optional) then in the former fetching: true will be set, and in the latter stale: true will be set

In short stale: true tells you whether a fresh background request for new data is ongoing.

It's a common mistake to assume that we care about whether a single result or field is “cached”. But in practice, this doesn't match UI/user expectations.

For a longer explanation read the long explanation of how this works in urql below...

---

Generally, bindings in urql aren't designed to disclose this information, because, usually it's not actionable for the UI unless there's a datapoint that's embedded in the data indicating freshness of data.

The cacheOutcome property, by the way, is for debugging purposes and stripped in production, as it was mostly used in the urql-devtools, but our cacheExchanges only add it when NODE_ENV !== 'production'.

To take a step back, lacking a use-case here, let me quickly outline how the cache approach works today. Especially since we don't have a single cache offering, but it's configurable.
I'll assume that I won't have to repeat what's basically explained here to keep this as short as possible 😅 https://formidable.com/open-source/urql/docs/architecture/

Basically, the execution in exchanges are split into two group:

asynchronous exchanges (e.g. fetchExchange)
When asynchronous exchanges receive an operation, generally, they will take that operation and eventually deliver a response. This could be because they're executing the operation by delivering to an API, but we also have other asynchronous exchanges, e.g. the authExchange. So, they could also be retrieving other data and manage asynchronous state.
I'd generally consider this part of the “execution” stage.

synchronous exchanges (e.g. cacheExchange)
When synchronous exchanges receive an operation, they can either update that operation before forwarding it (mapExchange without promises, requestPolicyExchange) or they can intercept the operation and deliver a response themselves, i.e. read an operation from a cache.

Hence, the difference here is timing.

To simplify this then,
if an operation receives a result immediately (i.e. synchronously), we consider this a cached result.
if an operation has to wait for a result (i.e. asynchronously/loading/fetching), we consider this an uncached result.

First, before moving on, this means that you can in theory create your own cacheOutcome property in an exchange by checking for the timing of results. Not that I'd recommend that, but basically, this is a reliable signal for whether something has come from a cache or not.

This is reflected in the bindings and Client, and comes from the requirement that a rendering UI library needs a result to be present to not switch to a loading state. Of course, it's sometimes a bit more complicated than that, but that's basically it.

The result of this, while ignoring the bindings is that we can look at three separate APIs on the Client for sending a GraphQL query:

client.query(...).toPromise();

client.query(...).subscribe(result => { /*...*/ });

client.readQuery(...);

The first API, toPromise, converts a result source to a promise, i.e. you'll always have a microtick delay to resolve it. But in essence, promises don't reflect all of urql since they can only deliver a single result.

The second API, subscribe, uses the internal sources in urql directly, and hence can deliver multiple results and match the internal timing. A first result may arrive synchronously. Updates may arrive later.
This matches what bindings see and what goes on internally more closely.

The third API, readQuery simplifies what I talked about to a single API. Since we can tell whether something is cached by just seeing if we have a synchronous result, this API just does that. If it receives a synchronous (cached) result, it returns it.

Now, what does that mean for bindings?

In the UI, saying whether something is cached is actually not very useful, because UI semantics don't match caches. A render can be repeated and if we assumed that we wanted to display it, the next time we display data it's always cached since every request to the API documents the cache.
So, this where cache semantics and what many developers intuitively mean by "data is cached" doesn't match reality — or at least doesn't match how UI frameworks operate.
(There's more to say here to support this point but I'll skip it)

What we found is that bindings (i.e. the UI) care about only two states: fetching and stale.

The UI may want to display a loading indicator when it's fetching data it doesn't have, i.e. a loading state.
Furthermore, a UI may want to indicate that data is stale when the data is being refreshed in the background.

The stale property actually closely matches the intuitive concept that we have around what the UI needs to often display when it has cached data. Despite having cached data, we want to somehow indicate to the user that they should expect data in the UI to change because we're fetching a new API result.

This actually leads nicely into the requestPolicyExchange, because we can combine this idea with our request policies. The cache-and-network policy will cause a cache result to be delivered while fetching a new result in the background. stale: true will be set on the cached result to indicate this. The requestPolicyExchange has a naïve approach of doing this based on a time-to-live (TTL time) per query operation.

This also extends to Graphcache. If we for instance use @_optional or schema awareness, we may be able to display part of the UI with the cached data we already have while missing other parts of our data. But we can tell the user that this is the case by looking at whether stale: true is set.

In short, urql has many cases where requests can happen in the background. When that happens to bindings they try to preserve state and set fetching: true. When this happens in exchanges or the Client, it sets stale: true on results to tell you that the current result will be updated.

This more closely hence matches our expectations for what the UI will show,
i.e. rather than saying that something is cached (and tl;dr there's always some caching going on, even without a cacheExchange), we have an indicator that tells you whether something is stale which is conceptually a huge difference, but gives you what you and your user actually expects