Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Update cache-configuration keyFields docs #11778

Open
wants to merge 11 commits into
base: main
Choose a base branch
from
19 changes: 19 additions & 0 deletions docs/source/caching/cache-configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,22 @@ const cache = new InMemoryCache({
// array for their keyFields.
keyFields: [],
},
Store: {
// If you need to disable normalization, set the keyFields to false
// and the object will be embedded in the parent
keyFields: false
},
Location: {
// You can also use a function to determine any of the values above.
// The first argument is the reference to the record to be written, and the second is the runtime context
keyFields: (location, context) => {
if (location.state) {
return ["city, "state", "country"];
} else {
return ["city, "country"];
}
}

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on this comment, I believe this should be context.readField("location") or context.storeObject.location and we should steer folks away from using the first arg altogether since it represents the raw server response which includes aliased fields and won't follow refs (aka instead of refs to other nested cache objects you'll only get the fields selected).

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see you mention this in a later bullet point, but my worry is that folks will read the code example and not the following notes and be surprised.

}
},
});
```
Expand All @@ -195,6 +211,9 @@ This example shows a variety of `typePolicies` with different `keyFields`:
Book:{"title":"Fahrenheit 451","author":{"name":"Ray Bradbury"}}
```
* The `AllProducts` type illustrates a special strategy for a **singleton** type. If the cache will only ever contain one `AllProducts` object and that object has _no_ identifying fields, you can provide an empty array for its `keyFields`.
* The `Store` type provides an example of how you can [disable normalization](https://www.apollographql.com/docs/react/caching/cache-configuration/#disabling-normalization) by setting the keyFields to `false`
* The `Location` type provides an example of using custom fuction given object and runtime context to calculate what fields should be used for the key field selection.
* Keep in mind that the first argument here is a reference to the record that will be written. As such, it does NOT include subselected fields, only scalar fields, and it contains aliases from the operation. If you need to read the real type you can use `context.storeObject`. To read even more indepth about how this function can work the best source will be our own [test cases for the cache policies](https://github.com/apollographql/apollo-client/blob/8bc7d4d406402962bf5151cdd2c5c75c9398d10c/src/cache/inmemory/__tests__/policies.ts#L5543-L5622)

If an object has multiple `keyFields`, the cache ID always lists those fields in the same order to ensure uniqueness.

Expand Down
Loading