Allow read functions to return undefined array items#13056
Allow read functions to return undefined array items#13056jerelmiller merged 2 commits intorelease-4.1from
read functions to return undefined array items#13056Conversation
🦋 Changeset detectedLatest commit: 956b2e4 The changes in this PR will be included in the next version bump. Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
commit: |
✅ Docs preview readyThe preview is ready to be viewed. View the preview File Changes 0 new, 2 changed, 0 removedBuild ID: 2b7c9363d614ac5c6121f678 |
| if (field.selectionSet) { | ||
| array = array.filter(context.store.canRead); | ||
| array = array.filter( | ||
| (item) => item === undefined || context.store.canRead(item) |
There was a problem hiding this comment.
I'm not 100% sure if undefined is the right value to use here.
undefined is already a valid return value (although not perfectly valid by TS types, we'll have to look at those either way) with a - by now - defined behavior.
What are your thoughts about adding a modifier to ReadFieldOptions, like DELETE in other places?
export interface ReadFieldOptions extends FieldSpecifier {
from?: StoreObject | Reference;
+ PARTIAL_MISSING: PartialMissingModifier
}usage would be like
const cache = new InMemoryCache({
typePolicies: {
Query: {
fields: {
- books: (existing: Reference[] = [], { canRead }) => {
- return existing.map((book) => (canRead(book) ? book : undefined));
+ books: (existing: Reference[] = [], { canRead, PARTIAL_MISSING }) => {
+ return existing.map((book) => (canRead(book) ? book : PARTIAL_MISSING));
},
},
},
},
});There was a problem hiding this comment.
I would disagree, simply because we use undefined as the directive already for telling the cache that we have a missing value and that the query should be fetched. Reading through #6454 (where this behavior originated), the original motivation centered around filtering out dangling references, that way a cache.evict works more seamlessly without the need to find every list that reference belongs to and clean it yourself. Additionally, I changed no existing tests and I can find no reference in the documentation that specifies that undefined is automatically filtered out, so at best this is undocumented behavior. The closest I found in the docs is from the garbage collection guide (which only mentions dangling references):
Filtering dangling references out of a cached list field (like the
Deity.offspringexample above) is so common that the defaultreadfunction for a list field performs this filtering automatically. You can define a customreadfunction to override this behavior.
The only scenario this changes is existing custom read functions that return undefined items in array fields where previously those records were filtered out and now they are fetched. If you don't define a read function, the only time you'd ever see this occur is if you merge an undefined value in the array (unlikely). Cache evictions don't remove those refs in the array so the default read function still continues to work as it does today.
If we weren't already using undefined as the means to signal a missing value, I would agree here. I'd like to avoid 2 values meaning the same thing if we can avoid it. This is why I'm targeting this change for a minor though, I think it deserves a bit more callout.
This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and publish to npm yourself or [setup this action to publish automatically](https://github.com/changesets/action#with-publishing). If you're not ready to do a release yet, that's fine, whenever you add more changesets to release-4.1, this PR will be updated.⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ `release-4.1` is currently in **pre mode** so this branch has prereleases rather than normal releases. If you want to exit prereleases, run `changeset pre exit` on `release-4.1`.⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ # Releases ## @apollo/[email protected] ### Minor Changes - [#13056](#13056) [`b224efc`](b224efc) Thanks [@jerelmiller](https://github.com/jerelmiller)! - `InMemoryCache` no longer filters out explicitly returned `undefined` items from `read` functions for array fields. This now makes it possible to create `read` functions on array fields that return partial data and trigger a fetch for the full list. Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to release-4.1, this PR will be updated.⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ `release-4.1` is currently in **pre mode** so this branch has prereleases rather than normal releases. If you want to exit prereleases, run `changeset pre exit` on `release-4.1`.⚠️ ⚠️ ⚠️ ⚠️ ⚠️ ⚠️ # Releases ## @apollo/[email protected] ### Minor Changes - [#13056](#13056) [`b224efc`](b224efc) Thanks [@jerelmiller](https://github.com/jerelmiller)! - `InMemoryCache` no longer filters out explicitly returned `undefined` items from `read` functions for array fields. This now makes it possible to create `read` functions on array fields that return partial data and trigger a fetch for the full list. - [#13058](#13058) [`121a2cb`](121a2cb) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add an `extensions` option to `cache.write`, `cache.writeQuery`, and `client.writeQuery`. This makes `extensions` available in cache `merge` functions which can be accessed with the other merge function options. As a result of this change, any `extensions` returned in GraphQL operations are now available in `merge` in the cache writes for these operations. ### Patch Changes - [#13053](#13053) [`23ca0ba`](23ca0ba) Thanks [@phryneas](https://github.com/phryneas)! - Use memoized observable mapping when using `watchFragment`, `useFragment` or `useSuspenseFragment`. --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: apollogithubactionsbot[bot] <159198662+apollogithubactionsbot[bot]@users.noreply.github.com>
This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated. # Releases ## @apollo/[email protected] ### Minor Changes - [#13043](#13043) [`65e66ca`](65e66ca) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Support `headers` transport for enhanced client awareness. - [#12927](#12927) [`785e223`](785e223) Thanks [@jerelmiller](https://github.com/jerelmiller)! - You can now provide a callback function as the `context` option on the `mutate` function returned by `useMutation`. The callback function is called with the value of the `context` option provided to the `useMutation` hook. This is useful if you'd like to merge the context object provided to the `useMutation` hook with a value provided to the `mutate` function. ```ts function MyComponent() { const [mutate, result] = useMutation(MUTATION, { context: { foo: true }, }); async function runMutation() { await mutate({ // sends context as { foo: true, bar: true } context: (hookContext) => ({ ...hookContext, bar: true }), }); } // ... } ``` - [#12923](#12923) [`94ea3e3`](94ea3e3) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Fix an issue where deferred payloads that returned arrays with fewer items than the original cached array would retain items from the cached array. This change includes `@stream` arrays where stream arrays replace the cached arrays. - [#12927](#12927) [`96b531f`](96b531f) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Don't set the fallback value of a `@client` field to `null` when a `read` function is defined. Instead the `read` function will be called with an `existing` value of `undefined` to allow default arguments to be used to set the returned value. When a `read` function is not defined nor is there a defined resolver for the field, warn and set the value to `null` only in that instance. - [#12927](#12927) [`45ebb52`](45ebb52) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add support for `from: null` in `client.watchFragment` and `cache.watchFragment`. When `from` is `null`, the emitted result is: ```ts { data: null, dataState: "complete", complete: true, } ``` - [#12926](#12926) [`2b7f2c1`](2b7f2c1) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Support the newer incremental delivery format for the `@defer` directive implemented in `[email protected]`. Import the `GraphQL17Alpha9Handler` to use the newer incremental delivery format with `@defer`. ```ts import { GraphQL17Alpha9Handler } from "@apollo/client/incremental"; const client = new ApolloClient({ // ... incrementalHandler: new GraphQL17Alpha9Handler(), }); ``` > [!NOTE] > In order to use the `GraphQL17Alpha9Handler`, the GraphQL server MUST implement the newer incremental delivery format. You may see errors or unusual behavior if you use the wrong handler. If you are using Apollo Router, continue to use the `Defer20220824Handler` because Apollo Router does not yet support the newer incremental delivery format. - [#12927](#12927) [`45ebb52`](45ebb52) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add support for arrays with `useFragment`, `useSuspenseFragment`, and `client.watchFragment`. This allows the ability to use a fragment to watch multiple entities in the cache. Passing an array to `from` will return `data` as an array where each array index corresponds to the index in the `from` array. ```ts function MyComponent() { const result = useFragment({ fragment, from: [item1, item2, item3], }); // `data` is an array with 3 items console.log(result); // { data: [{...}, {...}, {...}], dataState: "complete", complete: true } } ``` - [#12927](#12927) [`45ebb52`](45ebb52) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add a `getCurrentResult` function to the observable returned by `client.watchFragment` and `cache.watchFragment` that returns the current value for the watched fragment. ```ts const observable = client.watchFragment({ fragment, from: { __typename: "Item", id: 1 }, }); console.log(observable.getCurrentResult()); // { // data: {...}, // dataState: "complete", // complete: true, // } ``` - [#13038](#13038) [`109efe7`](109efe7) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add the `from` option to `readFragment`, `watchFragment`, and `updateFragment`. - [#12918](#12918) [`2e224b9`](2e224b9) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add support for the `@stream` directive on both the `Defer20220824Handler` and the `GraphQL17Alpha2Handler`. > [!NOTE] > The implementations of `@stream` differ in the delivery of incremental results between the different GraphQL spec versions. If you upgrading from the older format to the newer format, expect the timing of some incremental results to change. - [#13056](#13056) [`b224efc`](b224efc) Thanks [@jerelmiller](https://github.com/jerelmiller)! - `InMemoryCache` no longer filters out explicitly returned `undefined` items from `read` functions for array fields. This now makes it possible to create `read` functions on array fields that return partial data and trigger a fetch for the full list. - [#13058](#13058) [`121a2cb`](121a2cb) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add an `extensions` option to `cache.write`, `cache.writeQuery`, and `client.writeQuery`. This makes `extensions` available in cache `merge` functions which can be accessed with the other merge function options. As a result of this change, any `extensions` returned in GraphQL operations are now available in `merge` in the cache writes for these operations. - [#12927](#12927) [`96b531f`](96b531f) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add an abstract `resolvesClientField` function to `ApolloCache` that can be used by caches to tell `LocalState` if it can resolve a `@client` field when a local resolver is not defined. `LocalState` will emit a warning and set a fallback value of `null` when no local resolver is defined and `resolvesClientField` returns `false`, or isn't defined. Returning `true` from `resolvesClientField` signals that a mechanism in the cache will set the field value. In this case, `LocalState` won't set the field value. - [#13078](#13078) [`bf1e0dc`](bf1e0dc) Thanks [@phryneas](https://github.com/phryneas)! - Use the default stream merge function for `@stream` fields only if stream info is present. This change means that using the older `Defer20220824Handler` will not use the default stream merge function and will instead truncate the streamed array on the first chunk. ### Patch Changes - [#12884](#12884) [`d329790`](d329790) Thanks [@phryneas](https://github.com/phryneas)! - Ensure that `PreloadedQueryRef` instances are unsubscribed when garbage collected - [#13086](#13086) [`1a1d408`](1a1d408) Thanks [@phryneas](https://github.com/phryneas)! - Change the returned value from `null` to `{}` when all fields in a query were skipped. This also fixes a bug where `useSuspenseQuery` would suspend indefinitely when all fields were skipped. - [#13010](#13010) [`7627000`](7627000) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Fix an issue where errors parsed from incremental chunks in `ErrorLink` might throw when using the `GraphQL17Alpha9Handler`. - [#12927](#12927) [`45ebb52`](45ebb52) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Deduplicate watches created by `useFragment`, `client.watchFragment`, and `cache.watchFragment` that contain the same fragment, variables, and identifier. This should improve performance in situations where a `useFragment` or a `client.watchFragment` is used to watch the same object in multiple places of an application. - [#12927](#12927) [`259ae9b`](259ae9b) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Allow `FragmentType` not only to be called as `FragmentType<TData>`, but also as `FragmentType<TypedDocumentNode>`. - [#12925](#12925) [`5851800`](5851800) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Fix an issue where calling `fetchMore` with `@defer` or `@stream` would not rerender incremental results as they were streamed. - [#12927](#12927) [`9e55188`](9e55188) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Truncate `@stream` arrays only on last chunk by default. - [#13083](#13083) [`f3c2be1`](f3c2be1) Thanks [@phryneas](https://github.com/phryneas)! - Expose the `ExtensionsWithStreamInfo` type for `extensions` in `Cache.writeQuery`, `Cache.write` and `Cache.update` so other cache implementations also can correctly access them. - [#12923](#12923) [`94ea3e3`](94ea3e3) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Improve the cache data loss warning message when `existing` or `incoming` is an array. - [#12927](#12927) [`4631175`](4631175) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Ignore top-level `data` values on subsequent chunks in incremental responses. - [#12927](#12927) [`2be8de2`](2be8de2) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Create mechanism to add experimental features to Apollo Client - [#12927](#12927) [`96b531f`](96b531f) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Ensure `LocalState` doesn't try to read from the cache when using a `no-cache` fetch policy. - [#12927](#12927) [`bb8ed7b`](bb8ed7b) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Ensure an error is thrown when `@stream` is detected and an `incrementalDelivery` handler is not configured. - [#13053](#13053) [`23ca0ba`](23ca0ba) Thanks [@phryneas](https://github.com/phryneas)! - Use memoized observable mapping when using `watchFragment`, `useFragment` or `useSuspenseFragment`. - [#12927](#12927) [`44706a2`](44706a2) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add helper type `QueryRef.ForQuery<TypedDocumentNode>` - [#13082](#13082) [`c257418`](c257418) Thanks [@phryneas](https://github.com/phryneas)! - Pass `streamInfo` through result extensions as a `WeakRef`. - [#12927](#12927) [`4631175`](4631175) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Fix the `Defer20220824Handler.SubsequentResult` type to match the `FormattedSubsequentIncrementalExecutionResult` type in `[email protected]`. - [#12927](#12927) [`96b531f`](96b531f) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Warn when using a `no-cache` fetch policy without a local resolver defined. `no-cache` queries do not read or write to the cache which meant `no-cache` queries are silently incomplete when the `@client` field value was handled by a cache `read` function. - [#12927](#12927) [`5776ea0`](5776ea0) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Update the `accept` header used with the `GraphQL17Alpha9Handler` to `multipart/mixed;incrementalSpec=v0.2` to ensure the newest incremental delivery format is requested. - [#12927](#12927) [`45ebb52`](45ebb52) Thanks [@jerelmiller](https://github.com/jerelmiller)! - `DeepPartial<Array<TData>>` now returns `Array<DeepPartial<TData>>` instead of `Array<DeepPartial<TData | undefined>>`. - [#13071](#13071) [`99ffe9a`](99ffe9a) Thanks [@phryneas](https://github.com/phryneas)! - `prerenderStatic`: Expose return value of `renderFunction` to userland, fix `aborted` property. This enables usage of `resumeAndPrerender` with React 19.2. - [#13026](#13026) [`05eee67`](05eee67) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Reduce the number of observables created by `watchFragment` by reusing existing observables as much as possible. This should improve performance when watching the same item in the cache multiple times after a cache update occurs. - [#13010](#13010) [`7627000`](7627000) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Handle `@stream` payloads that send multiple items in the same chunk when using the `Defer20220824Handler`. - [#13010](#13010) [`7627000`](7627000) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Handle an edge case with the `Defer20220824Handler` where an error for a `@stream` item that bubbles to the `@stream` boundary (such as an item returning `null` for a non-null array item) would write items from future chunks to the wrong array index. In these cases, the `@stream` field is no longer processed and future updates to the field are ignored. This prevents runtime errors that TypeScript would otherwise not be able to catch. - [#13081](#13081) [`1e06ad7`](1e06ad7) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Avoid calling `merge` functions more than once for the same incremental chunk. Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Fixes #9063
Fixes #13042
#6454 added functionality to filter out array items that can't be read via the
canReadutility function in order to filter out dangling references that might be left over from a cache evict. This behavior is reasonable and eases the burden on cleaning up arrays after cache evicts, however it makes it more difficult to return partial data on fields that return arrays when using thereturnPartialDataoption. With the existing behavior, you get an all-or-nothing behavior where you either have to returnundefinedfor the field to trigger a fetch (which means you can't return any items in the array that are actually present), or you get back a list with only items that are present in the cache (as determined bycanRead(item)).This PR makes it possible to return an explicit
undefinedas an array item from a customreadfunction.undefineditems are no longer automatically filtered out which makes it possible to return a partial list and trigger a fetch.