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

- [#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

- [#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.

- [#13082](#13082)
[`c257418`](c257418)
Thanks [@phryneas](https://github.com/phryneas)! - Pass `streamInfo`
through result extensions as a `WeakRef`.

- [#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>

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>