Partial results with graphcache

[jacob-indieocean]

As I understand it, if you provide graphcache with a schema, it is capable of returning partial data from the cache while fetching the complete data from the server.

A few questions regarding this:

1. It is possible to prevent graphcache from doing this (while still providing the schema) and always wait for complete results?
2. Is it possible to detect when the results are partial? The documentation indicates that the stale flag on the result object will be true if it is partial, but also for other reasons like out-of-date (I would love to get an example for the out-of-date situation actually). Is there any way to detect when stale is true because of partial and not for other reasons?
3. Will fetching be set to true while the partial results are returned and the complete results are being fetched?
4. Is there a documented way for how the missing fields in partial data represented? Are the undefined, or null?
5. I'm using @graphql-codegen/typescript-urql to generate types for Urql. It seems like the types for the data will be inaccurate for partial results since some of the fields might be optional. Is there a clean way to resolve this?

Thanks for this great library btw. I'm new to it, so pardon my limited understanding.

[kitten]

It is possible to prevent graphcache from doing this (while still providing the schema) and always wait for complete results?

It's not, because the UI / bindings can see all future results too, so if you're interested in the full result you can check for stale: true or the data you need to make sure that the partial results match your requirements. At least for the React and Preact bindings, we plan on making a useFragment hook that automatically attempts to match partial results against fragments to ensure that parts of your app can easily specify their minimal requirements #1408

Is it possible to detect when the results are partial?

The stale: true flag is set whenever you can expect a future result, which will either be more complete or more up-to-date. This is typically sufficient for detecting partial results too, since the other circumstance will only apply if an explicit network request is triggered somewhere else (in which case it's safe to wait) or when you use cache-and-network. So as you can tell, either conditions, outside of partial results, are very predictable.

Will fetching be set to true while the partial results are returned

No, fetching: false is always set when a result has completed. That's because this is purely a "UI / bindings flag", meaning that it's not the internals that are generating this flag but it's the bindings themselves saying "I don't have a result for this operation yet".

I'm using @graphql-codegen/typescript-urql to generate types for Urql

They shouldn't be. Only optional fields from your schema can be left out, meaning that your types will remain accurate. This is similar to how fields are left out when your schema partially errors out. It will set the next highest optional field to null when a resolver errors out. The same logic applies to Graphcache's partial results, which is why it's only enabled when you pass a schema.

[jacob-indieocean]

From my perspective, I have provided a specific use case that URLQ cannot support. To reiterate and further clarify, I want to distinguish between a cache backed response where a user has no blog posts (user.posts === null && stale is true in this situation), and a cache backed response where a user does have blob posts, but it is not in the cache and is a partial result (user.posts === null && stale is also true in this situation). If you can tell me how to distinguish between these situations, I will happily withdraw my objection.

From what I understand from your response, you believe the UI should be designed so as not to distinguish between these states and I think I have explained why I don't find that satisfactory, but I will reiterate. I do not think that is a reasonable restriction on the UI because it is imposing an identical response for two semantically different situations.

If the UI is to display "no posts" when user.posts === null && stale, then this is unsatisfactory in the situation where the user does have blog posts but the results were partial, because the user is going to think, for some time at least, that we lost their data.

The other option is to go with the lowest common denominator approach and just display the loading indicator when user.posts === null && stale. This is semantically safe, but it defeats the purpose of the cache in the situation where the cache is complete for that query and the user does not actually have blog posts. The point of the cache is to avoid loading indicators. I assume I don't have to argue for the importance of not defeating the purpose of the cache, because this is a caching library after all.

You say:

but your UI is at most going to be different based on some data being null and stale === true in a subset of your page.

This is going to happen a lot! This happens for every null field, every time a result is from the cache and before the network responds and clears the stale flag, which is every time a query is made with cache-and-network and is cached! If I have to display "loading" for each of these I have completely lost the benefits of the cache on the null fields, and there may be a lot of null fields!

Also:

your UI shouldn't display stale data.

I don't quite follow. The whole point of the cache is to display stale data and update it when the network responds.

It might be worthwhile to consider that the competing library (Relay) has explicitly engineered first class support for distinguishing these scenarios (the suspense fallback is triggered exactly on missing data and not on staleness and null) if it lends support that this is not an isolated edge-case concern.

[RIP21]

BTW @jacob-indieocean unrelated to the question, but just part of it.
You should use https://www.graphql-code-generator.com/docs/plugins/typescript-document-nodes
Instead of @graphql-codegen/typescript-urql .
And then just pass a typed document node to the useQuery({ query: Document }) and get a data and other stuff properly typed.
More on it here.
https://the-guild.dev/blog/typed-document-node

In the end you need typescript, typescript-operations, and typed-document-node generators to rule it all :)
I also use @graphql-codegen/near-operation-file-preset but this is more for tree-shaking and modularization concerns.
Config then is smth similar to that:

      ./src/packlets/generated/graphql-types.generated.ts:
        - typescript
        - add:
            content: 'import type { UUID, DateTime, Time, JSON, Timestamp, Email, PhoneNumber, URL, Any, GraphQLDate } from "packlets/graphql/scalars"'
      src/:
        preset: near-operation-file
        presetConfig:
          extension: .generated.ts
          baseTypesPath: packlets/generated/graphql-types.generated.ts
        plugins:
          - typescript-operations
          - typed-document-node
          - add:
              content: 'import type { UUID, DateTime, Time, JSON, Timestamp, Email, PhoneNumber, URL, Any, GraphQLDate } from "packlets/graphql/scalars"'

[jacob-indieocean]

@RIP21 Wow, I totally did not know about that! Thank you, that sounds awesome!

[kitten]

The thing is that specifically with lists you can still differentiate between the two, but what I left out to say was that it'll depend on your schema. If you need to differentiate between two states (the absence and the presence of data that is not partial) then I'd always recommend to make these states unambiguous to partial data.

Meaning, it shouldn't be possible to have a shared null state on something nullable meaning both "absence of data" and "partial / errored data". So for instance for a list, it'd make sense to return an empty list rather than null; for Relay pagination you'd have no connection for partial data or an empty connection for empty lists, and so on.

For single items this gets trickier but the same principle applies: edge types are useful for that and can help to make these differences unambiguous

[jacob-indieocean]

I think we are on the same page wrt the statement of the problem at least, so that is great. I was not so sure of that before.

Agreed, lists have a naturally distinguishable values for empty vs missing (null vs []) and that can help, but it is impractically tedious to do the same that for non-list values and it is just as important in those cases (for example, does the user have a bank account user.bank === null).

But, beyond that, this is punting the issue upstream to API design. And it is an invasive (and unnecessary) requirement. The API has to decide in advance where the boundaries for partial data can be and reserve null for that use case, and remap null to another value (probably by introducing an otherwise unnecessary union type) at those points. This is a non-starter.

I'm in favor of solving this purely on the client side if possible, and I believe it is. graphcache has all the data it needs, it knows what the partial results are, it just needs to surface that to the user and we would avoid the downstream problems and proposed upstream solutions. URQL needs separate concepts for staleness and partial data. They are just not the same thing and there is material difference in how the UI should respond (I will die on this hill!) .

Granted, this may be a challenge to do without useFragment because there are so many places that might be missing data (every null value) that is hard to communicate that to the user, but JSON paths, boolean objects, even just a simple global partial flag similar to stale would go a long way. But I hope that with useFragment we can specify (and limit) the boundary for partial data to the fragment boundary and the response will clearly indicate if it is state or partial and not have it tied to whether it is null or not. (Partial data should be at user defined boundaries - it is too hard to reason about them in arbitrary locations.)

Note, that partial results in its current implementation has leaked its semantics into all stale results because of the inability to differentiate. Whenever any value is null and stale === true, we can never be sure if that is missing data or really null. And it is not just a specific points that we allow to contain partial responses that we can reason about specially, it is at all nullable values. All null values are untrustable now, and I really don't know to design the UI sensibly for this other than to turn of partial results (by not providing the schema, it would be great to have a flag for this so we can get the other benefits of providing the schema but not introduce partial results.)

This is unlike errors btw, because we know when an error has happened - there is an error object. For example, the Apollo client by default discards the response on an error. So if we get a result and it is null, we know it is not due to an error. There is no identical option for partial results.

Finally, as I said before, URQL is a great library, and I appreciate most parts of it. That sentiment might get lost in focusing on a single issue, so I want to emphasis that again. Thanks for the great work!