Announcement: Join 1000+ engineers at GraphQL Summit 2025 by Apollo for talks, workshops, and office hours. Oct 6-8, 2025 in San Francisco. Get your pass here ->

Apollo Client is a fully-featured caching GraphQL client with integrations for React, Angular, and more. It allows you to easily build UI components that fetch data via GraphQL.

Apollo Client aims to comply with the Working Draft of the GraphQL specification.

Documentation

All Apollo Client documentation, including React integration articles and helpful recipes, can be found at:
https://www.apollographql.com/docs/react/

The Apollo Client API reference can be found at:
https://www.apollographql.com/docs/react/api/apollo-client/

Learn how to use Apollo Client with self-paced hands-on training on Odyssey, Apollo's official learning platform:
https://odyssey.apollographql.com/

Maintainers

Who is Apollo?

Apollo builds open-source tools and commercial services to make application development easier, better, and accessible to more people. We help you ship faster with:

• GraphOS - The platform for building, managing, and scaling a supergraph: a unified network of your organization's microservices and their data sources—all composed into a single distributed API.
• Apollo Federation – The industry-standard open architecture for building a distributed graph. Use Apollo’s gateway to compose a unified graph from multiple subgraphs, determine a query plan, and route requests across your services.
• Apollo Client – The most popular GraphQL client for the web. Apollo also builds and maintains Apollo iOS and Apollo Kotlin.
• Apollo Server – A production-ready JavaScript GraphQL server that connects to any microservice, API, or database. Compatible with all popular JavaScript frameworks and deployable in serverless environments.

Learn how to build with Apollo

Check out the Odyssey learning platform, the perfect place to start your GraphQL journey with videos and interactive code challenges. Join the Apollo Community to interact with and get technical help from the GraphQL community.

@apollo/client

3.13.8

Patch Changes

• #12567 c19d415 Thanks @thearchitector! - Fix in-flight multipart urql subscription cancellation

3.13.7

Patch Changes

• #12540 0098932 Thanks @phryneas! - Refactor: Move notification scheduling logic from QueryInfo to ObservableQuery

• #12540 0098932 Thanks @phryneas! - Refactored cache emit logic for ObservableQuery. This should be an invisible change.

3.13.6

Patch Changes

• #12285 cdc55ff Thanks @phryneas! - keep ObservableQuery created by useQuery non-active before it is first subscribed

3.13.5

Patch Changes

• #12461 12c8d06 Thanks @jerelmiller! - Fix an issue where a cache-first query would return the result for previous variables when a cache update is issued after simultaneously changing variables and skipping the query.

3.13.4

Patch Changes

• #12420 fee9368 Thanks @jorenbroekema! - Use import star from rehackt to prevent issues with importing named exports from external CJS modules.

3.13.3

Patch Changes

• #12362 f6d387c Thanks @jerelmiller! - Fixes an issue where calling observableQuery.getCurrentResult() when the errorPolicy was set to all would return the networkStatus as NetworkStatus.ready when there were errors returned in the result. This has been corrected to report NetworkStatus.error.

  This bug also affected the useQuery and useLazyQuery hooks and may affect you if you check for networkStatus in your component.

3.13.2

Patch Changes

• #12409 6aa2f3e Thanks @phryneas! - To mitigate problems when Apollo Client ends up more than once in the bundle, some unique symbols were converted into Symbol.for calls.

• #12392 644bb26 Thanks @Joja81! - Fixes an issue where the DeepOmit type would turn optional properties into required properties. This should only affect you if you were using the omitDeep or stripTypename utilities exported by Apollo Client.

• #12404 4332b88 Thanks @jerelmiller! - Show NaN rather than converting to null in debug messages from MockLink for unmatched variables values.

3.13.1

Patch Changes

• #12369 bdfc5b2 Thanks @phryneas! - ObervableQuery.refetch: don't refetch with cache-and-network, swich to network-only instead

• #12375 d3f8f13 Thanks @jerelmiller! - Export the UseSuspenseFragmentOptions type.

3.13.0

Minor Changes

• #12066 c01da5d Thanks @jerelmiller! - Adds a new useSuspenseFragment hook.

  useSuspenseFragment suspends until data is complete. It is a drop-in replacement for useFragment when you prefer to use Suspense to control the loading state of a fragment. See the documentation for more details.

• #12174 ba5cc33 Thanks @jerelmiller! - Ensure errors thrown in the onCompleted callback from useMutation don't call onError.

• #12340 716d02e Thanks @phryneas! - Deprecate the onCompleted and onError callbacks of useQuery and useLazyQuery. For more context, please see the related issue on GitHub.

• #12276 670f112 Thanks @Cellule! - Provide a more type-safe option for the previous data value passed to observableQuery.updateQuery. Using it could result in crashes at runtime as this callback could be called with partial data even though its type reported the value as a complete result.

  The updateQuery callback function is now called with a new type-safe previousData property and a new complete property in the 2nd argument that determines whether previousData is a complete or partial result.

  As a result of this change, it is recommended to use the previousData property passed to the 2nd argument of the callback rather than using the previous data value from the first argument since that value is not type-safe. The first argument is now deprecated and will be removed in a future version of Apollo Client.

  observableQuery.updateQuery(
    (unsafePreviousData, { previousData, complete }) => {
      previousData;
      // ^? TData | DeepPartial<TData> | undefined
  
      if (complete) {
        previousData;
        // ^? TData
      } else {
        previousData;
        // ^? DeepPartial<TData> | undefined
      }
    }
  );

• #12174 ba5cc33 Thanks @jerelmiller! - Reject the mutation promise if errors are thrown in the onCompleted callback of useMutation.

Patch Changes

• #12276 670f112 Thanks @Cellule! - Fix the return type of the updateQuery function to allow for undefined. updateQuery had the ability to bail out of the update by returning a falsey value, but the return type enforced a query value.

  observableQuery.updateQuery(
    (unsafePreviousData, { previousData, complete }) => {
      if (!complete) {
        // Bail out of the update by returning early
        return;
      }
  
      // ...
    }
  );

• #12296 2422df2 Thanks @Cellule! - Deprecate option ignoreResults in useMutation. Once this option is removed, existing code still using it might see increase in re-renders. If you don't want to synchronize your component state with the mutation, please use useApolloClient to get your ApolloClient instance and call client.mutate directly.

• #12338 67c16c9 Thanks @phryneas! - In case of a multipart response (e.g. with @defer), query deduplication will now keep going until the final chunk has been received.

• #12276 670f112 Thanks @Cellule! - Fix the type of the variables property passed as the 2nd argument to the subscribeToMore callback. This was previously reported as the variables type for the subscription itself, but is now properly typed as the query variables.

3.13.0-rc.0

Minor Changes

• #12066 c01da5d Thanks @jerelmiller! - Adds a new useSuspenseFragment hook.

  useSuspenseFragment suspends until data is complete. It is a drop-in replacement for useFragment when you prefer to use Suspense to control the loading state of a fragment.

• #12174 ba5cc33 Thanks @jerelmiller! - Ensure errors thrown in the onCompleted callback from useMutation don't call onError.

• #12340 716d02e Thanks @phryneas! - Deprecate the onCompleted and onError callbacks of useQuery and useLazyQuery. For more context, please see the related issue on GitHub.

• #12276 670f112 Thanks @Cellule! - Provide a more type-safe option for the previous data value passed to observableQuery.updateQuery. Using it could result in crashes at runtime as this callback could be called with partial data even though its type reported the value as a complete result.

  The updateQuery callback function is now called with a new type-safe previousData property and a new complete property in the 2nd argument that determines whether previousData is a complete or partial result.

  As a result of this change, it is recommended to use the previousData property passed to the 2nd argument of the callback rather than using the previous data value from the first argument since that value is not type-safe. The first argument is now deprecated and will be removed in a future version of Apollo Client.

  observableQuery.updateQuery(
    (unsafePreviousData, { previousData, complete }) => {
      previousData;
      // ^? TData | DeepPartial<TData> | undefined
  
      if (complete) {
        previousData;
        // ^? TData
      } else {
        previousData;
        // ^? DeepPartial<TData> | undefined
      }
    }
  );

• #12174 ba5cc33 Thanks @jerelmiller! - Reject the mutation promise if errors are thrown in the onCompleted callback of useMutation.

Patch Changes

• #12276 670f112 Thanks @Cellule! - Fix the return type of the updateQuery function to allow for undefined. updateQuery had the ability to bail out of the update by returning a falsey value, but the return type enforced a query value.

  observableQuery.updateQuery(
    (unsafePreviousData, { previousData, complete }) => {
      if (!complete) {
        // Bail out of the update by returning early
        return;
      }
  
      // ...
    }
  );

• #12296 2422df2 Thanks @Cellule! - Deprecate option ignoreResults in useMutation. Once this option is removed, existing code still using it might see increase in re-renders. If you don't want to synchronize your component state with the mutation, please use useApolloClient to get your ApolloClient instance and call client.mutate directly.

• #12338 67c16c9 Thanks @phryneas! - In case of a multipart response (e.g. with @defer), query deduplication will now keep going until the final chunk has been received.

• #12276 670f112 Thanks @Cellule! - Fix the type of the variables property passed as the 2nd argument to the subscribeToMore updateQuery callback. This was previously reported as the variables type for the subscription itself, but is now properly typed as the query variables.

3.12.11

Patch Changes

• #12351 3da908b Thanks @jerelmiller! - Fixes an issue where the wrong networkStatus and loading value was emitted from observableQuery when calling fetchMore with a no-cache fetch policy. The networkStatus now properly reports as ready and loading as false after the result is returned.

• #12354 a24ef94 Thanks @phryneas! - Fix missing main.d.cts file

3.12.10

Patch Changes

• #12341 f2bb0b9 Thanks @phryneas! - useReadQuery/useQueryRefHandlers: Fix a "hook order" warning that might be emitted in React 19 dev mode.

• #12342 219b26b Thanks @phryneas! - Add graphql-ws ^6.0.3 as a valid peerDependency

3.12.9

Patch Changes

• #12321 daa4f33 Thanks @jerelmiller! - Fix type of extensions in protocolErrors for ApolloError and the onError link. According to the multipart HTTP subscription protocol, fatal tranport errors follow the GraphQL error format which require extensions to be a map as its value instead of an array.

• #12318 b17968b Thanks @jerelmiller! - Allow RetryLink to retry an operation when fatal transport-level errors are emitted from multipart subscriptions.

  const retryLink = new RetryLink({
    attempts: (count, operation, error) => {
      if (error instanceof ApolloError) {
        // errors available on the `protocolErrors` field in `ApolloError`
        console.log(error.protocolErrors);
      }
  
      return true;
    },
  });

3.12.8

Patch Changes

• #12292 3abd944 Thanks @phryneas! - Remove unused dependency response-iterator

• #12287 bf313a3 Thanks @phryneas! - Fixes an issue where client.watchFragment/useFragment with @includes crashes when a separate cache update writes to the conditionally included fields.

3.12.7

Patch Changes

• #12281 d638ec3 Thanks @jerelmiller! - Make fatal tranport-level errors from multipart subscriptions available to the error link with the protocolErrors property.

  const errorLink = onError(({ protocolErrors }) => {
    if (protocolErrors) {
      console.log(protocolErrors);
    }
  });

• #12281 d638ec3 Thanks @jerelmiller! - Fix the array type for the errors field on the ApolloPayloadResult type. This type was always in the shape of the GraphQL error format, per the multipart subscriptions protocol and never a plain string or a JavaScript error object.

3.12.6

Patch Changes

• #12267 d57429d Thanks @jerelmiller! - Maintain the TData type when used with Unmasked when TData is not a masked type generated from GraphQL Codegen.

• #12270 3601246 Thanks @jerelmiller! - Fix handling of tagged/branded primitive types when used as scalar values with Unmasked.

3.12.5

Patch Changes

• #12252 cb9cd4e Thanks @jerelmiller! - Changes the default behavior of the MaybeMasked type to preserve types unless otherwise specified. This change makes it easier to upgrade from older versions of the client where types could have unexpectedly changed in the application due to the default of trying to unwrap types into unmasked types. This change also fixes the compilation performance regression experienced when simply upgrading the client since types are now preserved by default.

  A new mode option has now been introduced to allow for the old behavior. See the next section on migrating if you wish to maintain the old default behavior after upgrading to this version.

  Migrating from <= v3.12.4

  If you've adopted data masking and have opted in to using masked types by setting the enabled property to true, you can remove this configuration entirely:

  -declare module "@apollo/client" {
  -  interface DataMasking {
  -    mode: "unmask"
  -  }
  -}

  If you prefer to specify the behavior explicitly, change the property from enabled: true, to mode: "preserveTypes":

  declare module "@apollo/client" {
    interface DataMasking {
  -    enabled: true
  +    mode: "preserveTypes"
    }
  }

  If you rely on the default behavior in 3.12.4 or below and would like to continue to use unmasked types by default, set the mode to unmask:

  declare module "@apollo/client" {
    interface DataMasking {
      mode: "unmask";
    }
  }

3.12.4

Patch Changes

• #12236 4334d30 Thanks @charpeni! - Fix an issue with refetchQueries where comparing DocumentNodes internally by references could lead to an unknown query, even though the DocumentNode was indeed an active query—with a different reference.

3.12.3

Patch Changes

• #12214 8bfee88 Thanks @phryneas! - Data masking: prevent infinite recursion of ContainsFragmentsRefs type

• #12204 851deb0 Thanks @jerelmiller! - Fix Unmasked unwrapping tuple types into an array of their subtypes.

• #12204 851deb0 Thanks @jerelmiller! - Ensure MaybeMasked does not try and unwrap types that contain index signatures.

• #12204 851deb0 Thanks @jerelmiller! - Ensure MaybeMasked does not try to unwrap the type as Unmasked if the type contains any.

3.12.2

Patch Changes

• #12175 84af347 Thanks @jerelmiller! - Update peer deps to allow for React 19 stable release.

3.12.1

Patch Changes

• #12171 e1efe74 Thanks @phryneas! - Fix import extension in masking entry point.

3.12.0

Minor Changes

Data masking 🎭

• #12042 1c0ecbf Thanks @jerelmiller! - Introduces data masking in Apollo Client.

  Data masking enforces that only the fields requested by the query or fragment is available to that component. Data masking is best paired with colocated fragments.

  To enable data masking in Apollo Client, set the dataMasking option to true.

  new ApolloClient({
    dataMasking: true,
    // ... other options
  });

  For detailed information on data masking, including how to incrementally adopt it in an existing applications, see the data masking documentation.

• #12131 21c3f08 Thanks @jerelmiller! - Allow null as a valid from value in useFragment.

3.12.0-rc.4

Patch Changes

• #12154 d933def Thanks @phryneas! - Data masking types: handle overlapping nested array types and fragments on interface types.

3.12.0-rc.3

Patch Changes

• #12150 9ed1e1e Thanks @jerelmiller! - Fix issue when using Unmasked with older versions of TypeScript when used with array fields.

• #12152 78137ec Thanks @phryneas! - Add a helper that will skip the TS unmasking alorithm when no fragments are present on type level

3.12.0-rc.2

Patch Changes

• #12139 5a53e15 Thanks @phryneas! - Fix issue where masked data would sometimes get returned when the field was part of a child fragment from a fragment unmasked by the parent query.

• #12139 5a53e15 Thanks @phryneas! - Fix issue where the warning emitted by @unmask(mode: "migrate") would trigger unnecessarily when the fragment was used alongside a masked fragment inside an inline fragment.

• #12139 5a53e15 Thanks @phryneas! - Fix issue that threw errors when masking partial data with @unmask(mode: "migrate").

3.12.0-rc.1

Minor Changes

• #12131 21c3f08 Thanks @jerelmiller! - Allow null as a valid from value in useFragment.

Patch Changes

• #12126 d10d702 Thanks @jerelmiller! - Maintain the existing document if its unchanged by the codemod and move to more naive whitespace formatting

• #12134 cfaf4ef Thanks @jerelmiller! - Fix issue where data went missing when an unmasked fragment in migrate mode selected fields that the parent did not.

• #12130 1e7d009 Thanks @jerelmiller! - Fix error thrown when applying unmask migrate mode warnings on interface types with selection sets that contain inline fragment conditions.

• #12126 d10d702 Thanks @jerelmiller! - Ensure documents unchanged by the codemod are left untouched.

• #12133 a6ece37 Thanks @jerelmiller! - Ensure null is retained in nullable types when unmasking a type with the Unmasked helper type.

3.12.0-rc.0

Patch Changes

• #12116 8ae6e4e Thanks @jerelmiller! - Prevent field accessor warnings when using @unmask(mode: "migrate") on objects that are passed into cache.identify.

• #12120 6a98e76 Thanks @jerelmiller! - Provide a codemod that applies @unmask to all named fragments for all operations and fragments. To use the codemod, run the following command:

  npx jscodeshift -t node_modules/@apollo/client/scripts/codemods/data-masking/unmask.ts --extensions tsx --parser tsx path/to/app/

  To customize the tag used to search for GraphQL operations, use the --tag option. By default the codemod looks for gql and graphql tags.

  To apply the directive in migrate mode in order to receive runtime warnings on potentially masked fields, use the --mode migrate option.

  For more information on the options that can be used with jscodeshift, check out the jscodeshift documentation.

• #12121 1085a95 Thanks @jerelmiller! - Warn when using data masking with "no-cache" operations.

• #12114 1d4ce00 Thanks @jerelmiller! - Fix error when combining @unmask and @defer directives on a fragment spread when data masking is enabled.

3.12.0-alpha.0

Minor Changes

• #12042 1c0ecbf Thanks @jerelmiller! - Introduces data masking into Apollo Client. Data masking allows components to access only the data they asked for through GraphQL fragments. This prevents coupling between components that might otherwise implicitly rely on fields not requested by the component. Data masking also provides the benefit that masked fields only rerender components that ask for the field.

  To enable data masking in Apollo Client, set the dataMasking option to true.

  new ApolloClient({
    dataMasking: true,
    // ... other options
  });

  You can selectively disable data masking using the @unmask directive. Apply this to any named fragment to receive all fields requested by the fragment.

  query {
    user {
      id
      ...UserFields @unmask
    }
  }

  To help with migration, use the @unmask migrate mode which will add warnings when accessing fields that would otherwise be masked.

  query {
    user {
      id
      ...UserFields @unmask(mode: "migrate")
    }
  }

3.11.10

Patch Changes

• #12093 1765668 Thanks @mgmolisani! - Fixed a bug when evaluating the devtools flag with the new syntax devtools.enabled that could result to true when explicitly set to false.

3.11.9

Patch Changes

• #12110 a3f95c6 Thanks @jerelmiller! - Fix an issue where errors returned from a fetchMore call from a Suspense hook would cause a Suspense boundary to be shown indefinitely.

3.11.8

Patch Changes

• #12054 35cf186 Thanks @phryneas! - Fixed a bug where incorrect object access in some Safari extensions could cause a crash.

3.11.7

Patch Changes

• #12052 e471cef Thanks @jerelmiller! - Fixes a regression from where passing an invalid identifier to from in useFragment would result in the warning TypeError: Cannot read properties of undefined (reading '__typename').

3.11.6

Patch Changes

• #12049 9c26892 Thanks @phryneas and @maciesielka! - Fix a bug where useFragment did not re-render as expected

• #12044 04462a2 Thanks @DoctorJohn! - Cache the useSubscription hook's restart function definition between re-renders.

3.11.5

Patch Changes

• #12027 eb3e21b Thanks @JavaScriptBach! - Type MutationResult.reset as an arrow function

• #12020 82d8cb4 Thanks @jerelmiller! - Better conform to Rules of React by avoiding write of ref in render for useFragment.

3.11.4

Patch Changes

• #11994 41b17e5 Thanks @jerelmiller! - Update the Modifier function type to allow cache.modify to return deeply partial data.

• #11989 e609156 Thanks @phryneas! - Fix a potential crash when calling clearStore while a query was running.

  Previously, calling client.clearStore() while a query was running had one of these results:

  • useQuery would stay in a loading: true state.
  • useLazyQuery would stay in a loading: true state, but also crash with a "Cannot read property 'data' of undefined" error.

  Now, in both cases, the hook will enter an error state with a networkError, and the promise returned by the useLazyQuery execute function will return a result in an error state.

• #11994 41b17e5 Thanks @jerelmiller! - Prevent accidental distribution on cache.modify field modifiers when a field is a union type array.

3.11.3

Patch Changes

• #11984 5db1659 Thanks @jerelmiller! - Fix an issue where multiple fetches with results that returned errors would sometimes set the data property with an errorPolicy of none.

• #11974 c95848e Thanks @jerelmiller! - Fix an issue where fetchMore would write its result data to the cache when using it with a no-cache fetch policy.

• #11974 c95848e Thanks @jerelmiller! - Fix an issue where executing fetchMore with a no-cache fetch policy could sometimes result in multiple network requests.

• #11974 c95848e Thanks @jerelmiller! -

  Potentially disruptive change

  When calling fetchMore with a query that has a no-cache fetch policy, fetchMore will now throw if an updateQuery function is not provided. This provides a mechanism to merge the results from the fetchMore call with the query's previous result.

3.11.2

Patch Changes

• #11980 38c0a2c Thanks @jerelmiller! - Fix missing getServerSnapshot error when using useSubscription on the server.

3.11.1

Patch Changes

• #11969 061cab6 Thanks @jerelmiller! - Remove check for window.__APOLLO_CLIENT__ when determining whether to connect to Apollo Client Devtools when connectToDevtools or devtools.enabled is not specified. This now simply checks to see if the application is in development mode.

• #11971 ecf77f6 Thanks @jerelmiller! - Prevent the setTimeout for suggesting devtools from running in non-browser environments.

3.11.0

Potentially Breaking Fixes

• #11789 5793301 Thanks @phryneas! - Changes usages of the GraphQLError type to GraphQLFormattedError.

  This was a type bug - these errors were never GraphQLError instances to begin with, and the GraphQLError class has additional properties that can never be correctly rehydrated from a GraphQL result. The correct type to use here is GraphQLFormattedError.

  Similarly, please ensure to use the type FormattedExecutionResult instead of ExecutionResult - the non-"Formatted" versions of these types are for use on the server only, but don't get transported over the network.

• #11626 228429a Thanks @phryneas! - Call nextFetchPolicy with "variables-changed" even if there is a fetchPolicy specified.

  Previously this would only be called when the current fetchPolicy was equal to the fetchPolicy option or the option was not specified. If you use nextFetchPolicy as a function, expect to see this function called more often.

  Due to this bug, this also meant that the fetchPolicy might be reset to the initial fetchPolicy, even when you specified a nextFetchPolicy function. If you previously relied on this behavior, you will need to update your nextFetchPolicy callback function to implement this resetting behavior.

  As an example, if your code looked like the following:

  useQuery(QUERY, {
    nextFetchPolicy(currentFetchPolicy, info) {
      // your logic here
    }
  );

  Update your function to the following to reimplement the resetting behavior:

  useQuery(QUERY, {
    nextFetchPolicy(currentFetchPolicy, info) {
      if (info.reason === 'variables-changed') {
        return info.initialFetchPolicy;
      }
      // your logic here
    }
  );

Minor Changes

• #11923 d88c7f8 Thanks @jerelmiller! - Add support for subscribeToMore function to useQueryRefHandlers.

• #11854 3812800 Thanks @jcostello-atlassian! - Support extensions in useSubscription

• #11923 d88c7f8 Thanks @jerelmiller! - Add support for subscribeToMore function to useLoadableQuery.

• #11863 98e44f7 Thanks @phryneas! - Reimplement useSubscription to fix rules of React violations.

• #11869 a69327c Thanks @phryneas! - Rewrite big parts of useQuery and useLazyQuery to be more compliant with the Rules of React and React Compiler

• #11936 1b23337 Thanks @jerelmiller! - Add the ability to specify a name for the client instance for use with Apollo Client Devtools. This is useful when instantiating multiple clients to identify the client instance more easily. This deprecates the connectToDevtools option in favor of a new devtools configuration.

  new ApolloClient({
    devtools: {
      enabled: true,
      name: "Test Client",
    },
  });

  This option is backwards-compatible with connectToDevtools and will be used in the absense of a devtools option.

• #11923 d88c7f8 Thanks @jerelmiller! - Add support for subscribeToMore function to useBackgroundQuery.

• #11930 a768575 Thanks @jerelmiller! - Deprecates experimental schema testing utilities introduced in 3.10 in favor of recommending @apollo/graphql-testing-library.

Patch Changes

• #11951 0de03af Thanks @phryneas! - add React 19 RC to peerDependencies

• #11927 2941824 Thanks @phryneas! - Add restart function to useSubscription.

• #11949 4528918 Thanks @alessbell! - Remove deprecated watchFragment option, canonizeResults

• #11937 78332be Thanks @phryneas! - createSchemaFetch: simulate serialized errors instead of an ApolloError instance

• #11902 96422ce Thanks @phryneas! - Add cause field to ApolloError.

• #11806 8df6013 Thanks @phryneas! - MockLink: add query default variables if not specified in mock request

• #11926 3dd6432 Thanks @phryneas! - watchFragment: forward additional options to diffOptions

• #11946 7d833b8 Thanks @jerelmiller! - Fix issue where mutations were not accessible by Apollo Client Devtools in 3.11.0-rc.0.

• #11944 8f3d7eb Thanks @sneyderdev! - Allow IgnoreModifier to be returned from a optimisticResponse function when inferring from a TypedDocumentNode when used with a generic argument.

• #11954 4a6e86a Thanks @phryneas! - Document (and deprecate) the previously undocumented errors property on the useQuery QueryResult type.

• #11719 09a6677 Thanks @phryneas! - Allow wrapping createQueryPreloader

• #11921 70406bf Thanks @phryneas! - add ignoreResults option to useSubscription

3.11.0-rc.2

Patch Changes

• #11951 0de03af Thanks @phryneas! - add React 19 RC to peerDependencies

• #11937 78332be Thanks @phryneas! - createSchemaFetch: simulate serialized errors instead of an ApolloError instance

• #11944 8f3d7eb Thanks @sneyderdev! - Allow IgnoreModifier to be returned from a optimisticResponse function when inferring from a TypedDocumentNode when used with a generic argument.

• #11954 4a6e86a Thanks @phryneas! - Document (and deprecate) the previously undocumented errors property on the useQuery QueryResult type.

3.11.0-rc.1

Patch Changes

• #11949 4528918 Thanks @alessbell! - Remove deprecated watchFragment option, canonizeResults

• #11926 3dd6432 Thanks @phryneas! - watchFragment: forward additional options to diffOptions

• #11946 7d833b8 Thanks @jerelmiller! - Fix issue where mutations were not accessible by Apollo Client Devtools in 3.11.0-rc.0.

3.11.0-rc.0

Minor Changes

• #11923 d88c7f8 Thanks @jerelmiller! - Add support for subscribeToMore function to useQueryRefHandlers.

• #11854 3812800 Thanks @jcostello-atlassian! - Support extensions in useSubscription

• #11923 d88c7f8 Thanks @jerelmiller! - Add support for subscribeToMore function to useLoadableQuery.

• #11863 98e44f7 Thanks @phryneas! - Reimplement useSubscription to fix rules of React violations.

• #11869 a69327c Thanks @phryneas! - Rewrite big parts of useQuery and useLazyQuery to be more compliant with the Rules of React and React Compiler

• #11936 1b23337 Thanks @jerelmiller! - Add the ability to specify a name for the client instance for use with Apollo Client Devtools. This is useful when instantiating multiple clients to identify the client instance more easily. This deprecates the connectToDevtools option in favor of a new devtools configuration.

  new ApolloClient({
    devtools: {
      enabled: true,
      name: "Test Client",
    },
  });

  This option is backwards-compatible with connectToDevtools and will be used in the absense of a devtools option.

• #11923 d88c7f8 Thanks @jerelmiller! - Add support for subscribeToMore function to useBackgroundQuery.

• #11789 5793301 Thanks @phryneas! - Changes usages of the GraphQLError type to GraphQLFormattedError.

  This was a type bug - these errors were never GraphQLError instances to begin with, and the GraphQLError class has additional properties that can never be correctly rehydrated from a GraphQL result. The correct type to use here is GraphQLFormattedError.

  Similarly, please ensure to use the type FormattedExecutionResult instead of ExecutionResult - the non-"Formatted" versions of these types are for use on the server only, but don't get transported over the network.

• #11930 a768575 Thanks @jerelmiller! - Deprecates experimental schema testing utilities introduced in 3.10 in favor of recommending @apollo/graphql-testing-library.

Patch Changes

• #11927 2941824 Thanks @phryneas! - Add restart function to useSubscription.

• #11902 96422ce Thanks @phryneas! - Add cause field to ApolloError.

• #11806 8df6013 Thanks @phryneas! - MockLink: add query default variables if not specified in mock request

• #11626 228429a Thanks @phryneas! - Call nextFetchPolicy with "variables-changed" even if there is a fetchPolicy specified. (fixes #11365)

• #11719 09a6677 Thanks @phryneas! - Allow wrapping createQueryPreloader

• #11921 70406bf Thanks @phryneas! - add ignoreResults option to useSubscription

3.10.8

Patch Changes

• #11911 1f0460a Thanks @jerelmiller! - Allow undefined to be returned from a cache.modify modifier function when a generic type argument is used.

3.10.7

Patch Changes

• #11901 10a8c0a Thanks @phryneas! - update canUseLayoutEffect check to also allow for layout effects in React Native

• #11861 1aed0e8 Thanks @henryqdineen! - Defend against non-serializable params in invariantWrappers

• #11905 29755da Thanks @phryneas! - Add .d.cts files for cjs bundles

• #11906 d104759 Thanks @phryneas! - chore: update TypeScript to 5.5

3.10.6

Patch Changes

• #11900 f745558 Thanks @phryneas! - useMutation: use useIsomorphicLayoutEffect instead of useLayoutEffect

3.10.5

Patch Changes

• #11888 7fb7939 Thanks @phryneas! - switch useRenderGuard to an approach not accessing React's internals

• #11511 6536369 Thanks @phryneas! - useLoadableQuery: ensure that loadQuery is updated if the ApolloClient instance changes

• #11860 8740f19 Thanks @alessbell! - Fixes #11849 by reevaluating window.fetch each time BatchHttpLink uses it, if not configured via options.fetch. Takes the same approach as PR #8603 which fixed the same issue in HttpLink.

• #11852 d502a69 Thanks @phryneas! - Fix a bug where calling the useMutation reset function would point the hook to an outdated client reference.

• #11329 3d164ea Thanks @PaLy! - Fix graphQLErrors in Error Link if networkError.result is an empty string

• #11852 d502a69 Thanks @phryneas! - Prevent writing to a ref in render in useMutation. As a result, you might encounter problems in the future if you call the mutation's execute function during render. Please note that this was never supported behavior, and we strongly recommend against it.

• #11848 ad63924 Thanks @phryneas! - Ensure covariant behavior: MockedResponse<X,Y> should be assignable to MockedResponse

• #11851 45c47be Thanks @phryneas! - Avoid usage of useRef in useInternalState to prevent ref access in render.

• #11877 634d91a Thanks @phryneas! - Add missing name to tuple member (fix TS5084)

• #11851 45c47be Thanks @phryneas! - Fix a bug where useLazyQuery would not pick up a client change.

3.10.4

Patch Changes

• #11838 8475346 Thanks @alex-kinokon! - Don’t prompt for DevTools installation for browser extension page

• #11839 6481fe1 Thanks @jerelmiller! - Fix a regression in 3.9.5 where a merge function that returned an incomplete result would not allow the client to refetch in order to fulfill the query.

• #11844 86984f2 Thanks @jerelmiller! - Honor the @nonreactive directive when using cache.watchFragment or the useFragment hook to avoid rerendering when using these directives.

• #11824 47ad806 Thanks @phryneas! - Create branded QueryRef type without exposed properties.

  This change deprecates QueryReference in favor of a QueryRef type that doesn't expose any properties. This change also updates preloadQuery to return a new PreloadedQueryRef type, which exposes the toPromise function as it does today. This means that query refs produced by useBackgroundQuery and useLoadableQuery now return QueryRef types that do not have access to a toPromise function, which was never meant to be used in combination with these hooks.

  While we tend to avoid any types of breaking changes in patch releases as this, this change was necessary to support an upcoming version of the React Server Component integration, which needed to omit the toPromise function that would otherwise have broken at runtime. Note that this is a TypeScript-only change. At runtime, toPromise is still present on all queryRefs currently created by this package - but we strongly want to discourage you from accessing it in all cases except for the PreloadedQueryRef use case.

  Migration is as simple as replacing all references to QueryReference with QueryRef, so it should be possible to do this with a search & replace in most code bases:

  -import { QueryReference } from '@apollo/client'
  +import { QueryRef } from '@apollo/client'
  
  - function Component({ queryRef }: { queryRef: QueryReference<TData> }) {
  + function Component({ queryRef }: { queryRef: QueryRef<TData> }) {
    // ...
  }

• #11845 4c5c820 Thanks @jerelmiller! - Remove @nonreactive directives from queries passed to MockLink to ensure they are properly matched.

• #11837 dff15b1 Thanks @jerelmiller! - Fix an issue where a polled query created in React strict mode may not stop polling after the component unmounts while using the cache-and-network fetch policy.

3.10.3

Patch Changes

• #11811 d67d7f9 Thanks @phryneas! - Adjust some types for React 19 compat

• #11834 7d8aad4 Thanks @psamim! - Fix error "Cannot convert object to primitive value"

3.10.2

Patch Changes

• #11821 2675d3c Thanks @jerelmiller! - Fix a regression where rerendering a component with useBackgroundQuery would recreate the queryRef instance when used with React's strict mode.

• #11821 2675d3c Thanks @jerelmiller! - Revert the change introduced in 3.9.10 via #11738 that disposed of queryRefs synchronously. This change caused too many issues with strict mode.

3.10.1

Patch Changes

• #11792 5876c35 Thanks @phryneas! - AutoCleanedCache: only schedule batched cache cleanup if the cache is full (fixes #11790)

• #11799 1aca7ed Thanks @phryneas! - RenderPromises: use canonicalStringify to serialize variables to ensure query deduplication is properly applied even when variables are specified in a different order.

• #11803 bf9dd17 Thanks @phryneas! - Update the rehackt dependency to ^0.1.0

• #11756 60592e9 Thanks @henryqdineen! - Fix operation.setContext() type

3.10.0

Minor Changes

• #11605 e2dd4c9 Thanks @alessbell! - Adds createMockFetch utility for integration testing that includes the link chain

• #11760 acd1982 Thanks @alessbell! - createTestSchema now uses graphql-tools mergeResolvers to merge resolvers instead of a shallow merge.

• #11764 f046aa9 Thanks @alessbell! - Rename createProxiedSchema to createTestSchema and createMockFetch to createSchemaFetch.

• #11777 5dfc79f Thanks @alessbell! - Call createMockSchema inside createTestSchema.

• #11774 2583488 Thanks @alessbell! - Add ability to set min and max delay in createSchemaFetch

• #11605 e2dd4c9 Thanks @alessbell! - Adds proxiedSchema and createMockSchema testing utilities

• #11465 7623da7 Thanks @alessbell! - Add watchFragment method to the cache and expose it on ApolloClient, refactor useFragment using watchFragment.

• #11743 78891f9 Thanks @jerelmiller! - Remove alpha designation for queryRef.toPromise() to stabilize the API.

• #11743 78891f9 Thanks @jerelmiller! - Remove alpha designation for createQueryPreloader to stabilize the API.

• #11783 440563a Thanks @alessbell! - Moves new testing utilities to their own entrypoint, testing/experimental

Patch Changes

• #11757 9825295 Thanks @phryneas! - Adjust useReadQuery wrapper logic to work with transported objects.

• #11771 e72cbba Thanks @phryneas! - Wrap useQueryRefHandlers in wrapHook.

• #11754 80d2ba5 Thanks @alessbell! - Export WatchFragmentOptions and WatchFragmentResult from main entrypoint and fix bug where this wasn't bound to the watchFragment method on ApolloClient.

3.10.0-rc.1

Minor Changes

• #11760 acd1982 Thanks @alessbell! - createTestSchema now uses graphql-tools mergeResolvers to merge resolvers instead of a shallow merge.

• #11764 f046aa9 Thanks @alessbell! - Rename createProxiedSchema to createTestSchema and createMockFetch to createSchemaFetch.

• #11777 5dfc79f Thanks @alessbell! - Call createMockSchema inside createTestSchema.

• #11774 2583488 Thanks @alessbell! - Add ability to set min and max delay in createSchemaFetch

• #11783 440563a Thanks @alessbell! - Moves new testing utilities to their own entrypoint, testing/experimental

Patch Changes

• #11757 9825295 Thanks @phryneas! - Adjust useReadQuery wrapper logic to work with transported objects.

• #11771 e72cbba Thanks @phryneas! - Wrap useQueryRefHandlers in wrapHook.

• #11754 80d2ba5 Thanks @alessbell! - Export WatchFragmentOptions and WatchFragmentResult from main entrypoint and fix bug where this wasn't bound to the watchFragment method on ApolloClient.

3.10.0-rc.0

Minor Changes

• #11605 e2dd4c9 Thanks @alessbell! - Adds createMockFetch utility for integration testing that includes the link chain

• #11605 e2dd4c9 Thanks @alessbell! - Adds proxiedSchema and createMockSchema testing utilities

• #11743 78891f9 Thanks @jerelmiller! - Remove alpha designation for queryRef.toPromise() to stabilize the API.

• #11743 78891f9 Thanks @jerelmiller! - Remove alpha designation for createQueryPreloader to stabilize the API.

3.10.0-alpha.0

Minor Changes

• #11465 7623da7 Thanks @alessbell! - Add watchFragment method to the cache and expose it on ApolloClient, refactor useFragment using watchFragment.

3.9.11

Patch Changes

• #11769 04132af Thanks @jerelmiller! - Fix an issue where using skipToken or the skip option with useSuspenseQuery in React's strict mode would perform a network request.

3.9.10

Patch Changes

• #11738 b1a5eb8 Thanks @jerelmiller! - Fix an issue where rerendering useBackgroundQuery after the queryRef had been disposed, either via the auto dispose timeout or by unmounting useReadQuery, would cause the queryRef to be recreated potentially resulting in another network request.

• #11738 b1a5eb8 Thanks @jerelmiller! - Allow queryRefs to be disposed of synchronously when a suspense hook unmounts. This prevents some situations where using a suspense hook with the same query/variables as the disposed queryRef accidentally used the disposed queryRef rather than creating a new instance.

• #11670 cc5c03b Thanks @phryneas! - Bail out of executeSubSelectedArray calls if the array has 0 elements.

3.9.9

Patch Changes

• #11696 466ef82 Thanks @PiR1! - Immediately dispose of the queryRef if useBackgroundQuery unmounts before the auto dispose timeout kicks in.

3.9.8

Patch Changes

• #11706 8619bc7 Thanks @jerelmiller! - Fix issue in all suspense hooks where returning an empty array after calling fetchMore would rerender the component with an empty list.

• #11694 835d5f3 Thanks @phryneas! - Expose setErrorMessageHandler from @apollo/client/dev entrypoint.

• #11689 cb8ffe5 Thanks @jerelmiller! - Fix issue where passing a new from option to useFragment would first render with the previous value before rerendering with the correct value.

• #11713 642092c Thanks @jerelmiller! - Fix issue where setting a default watchQuery option in the ApolloClient constructor could break startTransition when used with suspense hooks.

3.9.7

Patch Changes

• #11659 652a61e Thanks @phryneas! - Make useRenderGuard more resilient to changes in React internals.

• #11594 50b1097 Thanks @alessbell! - Adds a fix for multipart subscriptions that terminate with payload: null

3.9.6

Patch Changes

• #11617 f1d8bc4 Thanks @phryneas! - Allow Apollo Client instance to intercept hook functionality

• #11638 bf93ada Thanks @jerelmiller! - Fix issue where calling fetchMore from a suspense-enabled hook inside startTransition caused an unnecessary rerender.

3.9.5

Patch Changes

• #11595 8c20955 Thanks @phryneas! - Bumps the dependency rehackt to 0.0.5

• #11592 1133469 Thanks @Stephen2! - Strengthen MockedResponse.newData type

• #11579 1ba2fd9 Thanks @jerelmiller! - Fix issue where partial data is reported to useQuery when using notifyOnNetworkStatusChange after it errors while another overlapping query succeeds.

• #11579 1ba2fd9 Thanks @jerelmiller! - Fix an issue where a partial cache write for an errored query would result in automatically refetching that query.

• #11562 65ab695 Thanks @mspiess! - Mocks with an infinite delay no longer require result or error

3.9.4

Patch Changes

• #11403 b0c4f3a Thanks @jerelmiller! - Fix issue in useLazyQuery that results in a double network call when calling the execute function with no arguments after having called it previously with another set of arguments.

• #11576 e855d00 Thanks @alessbell! - Revert PR #11202 to fix caching bug reported in #11560

3.9.3

Patch Changes

• #11525 dce923a Thanks @vezaynk! - Allows passing in client via options to useFragment

• #11558 8cba16f Thanks @alessbell! - Fix unbound-method linter error on ObservableQuery methods exposed on useQuery's QueryResult object.

3.9.2

Patch Changes

• #11552 6ac2b0c Thanks @jerelmiller! - Fix import in useLazyRef causing import issues in the nextjs package.

3.9.1

Patch Changes

• #11516 8390fea Thanks @phryneas! - Fix an incorrect string substitution in a warning message.

• #11515 c9bf93b Thanks @vladar! - Avoid redundant refetchQueries call for mutation with no-cache policy (fixes #10238)

• #11545 84a6bea Thanks @alessbell! - Remove error thrown by inFlightLinkObservables intended to be removed before 3.9 release.

3.9.0

Minor Changes

Memory optimizations

• #11424 62f3b6d Thanks @phryneas! - Simplify RetryLink, fix potential memory leak

  Historically, RetryLink would keep a values array of all previous values, in case the operation would get an additional subscriber at a later point in time.

  In practice, this could lead to a memory leak (#11393) and did not serve any further purpose, as the resulting observable would only be subscribed to by Apollo Client itself, and only once - it would be wrapped in a Concast before being exposed to the user, and that Concast would handle subscribers on its own.

• #11435 5cce53e Thanks @phryneas! - Deprecates canonizeResults.

  Using canonizeResults can result in memory leaks so we generally do not recommend using this option anymore. A future version of Apollo Client will contain a similar feature without the risk of memory leaks.

• #11254 d08970d Thanks @benjamn! - Decouple canonicalStringify from ObjectCanon for better time and memory performance.

• #11356 cc4ac7e Thanks @phryneas! - Fix a potential memory leak in FragmentRegistry.transform and FragmentRegistry.findFragmentSpreads that would hold on to passed-in DocumentNodes for too long.

• #11370 25e2cb4 Thanks @phryneas! - parse function: improve memory management

  • use LRU WeakCache instead of Map to keep a limited number of parsed results
  • cache is initiated lazily, only when needed
  • expose parse.resetCache() method

• #11389 139acd1 Thanks @phryneas! - documentTransform: use optimism and WeakCache instead of directly storing data on the Trie

• #11358 7d939f8 Thanks @phryneas! - Fixes a potential memory leak in Concast that might have been triggered when Concast was used outside of Apollo Client.

• #11344 bd26676 Thanks @phryneas! - Add a resetCache method to DocumentTransform and hook InMemoryCache.addTypenameTransform up to InMemoryCache.gc

• #11367 30d17bf Thanks @phryneas! - print: use WeakCache instead of WeakMap

• #11387 4dce867 Thanks @phryneas! - QueryManager.transformCache: use WeakCache instead of WeakMap

• #11369 2a47164 Thanks @phryneas! - Persisted Query Link: improve memory management

  • use LRU WeakCache instead of WeakMap to keep a limited number of hash results
  • hash cache is initiated lazily, only when needed
  • expose persistedLink.resetHashCache() method
  • reset hash cache if the upstream server reports it doesn't accept persisted queries

• #10804 221dd99 Thanks @phryneas! - use WeakMap in React Native with Hermes

• #11355 7d8e184 Thanks @phryneas! - InMemoryCache.gc now also triggers FragmentRegistry.resetCaches (if there is a FragmentRegistry)

• #11409 2e7203b Thanks @phryneas! - Adds an experimental ApolloClient.getMemoryInternals helper

• #11343 776631d Thanks @phryneas! - Add reset method to print, hook up to InMemoryCache.gc

Suspense-enabled data fetching on user interaction with useLoadableQuery

• #11300 a815873 Thanks @jerelmiller! - Introduces a new useLoadableQuery hook. This hook works similarly to useBackgroundQuery in that it returns a queryRef that can be used to suspend a component via the useReadQuery hook. It provides a more ergonomic way to load the query during a user interaction (for example when wanting to preload some data) that would otherwise be clunky with useBackgroundQuery.

  function App() {
    const [loadQuery, queryRef, { refetch, fetchMore, reset }] =
      useLoadableQuery(query, options);
  
    return (
      <>
        <button onClick={() => loadQuery(variables)}>Load query</button>
        <Suspense fallback={<SuspenseFallback />}>
          {queryRef && <Child queryRef={queryRef} />}
        </Suspense>
      </>
    );
  }
  
  function Child({ queryRef }) {
    const { data } = useReadQuery(queryRef);
  
    // ...
  }

Begin preloading outside of React with createQueryPreloader

• #11412 58db5c3 Thanks @jerelmiller! - Add the ability to start preloading a query outside React to begin fetching as early as possible. Call createQueryPreloader to create a preloadQuery function which can be called to start fetching a query. This returns a queryRef which is passed to useReadQuery and suspended until the query is done fetching.

  const preloadQuery = createQueryPreloader(client);
  const queryRef = preloadQuery(QUERY, { variables, ...otherOptions });
  
  function App() {
    return {
      <Suspense fallback={<div>Loading</div>}>
        <MyQuery />
      </Suspense>
    }
  }
  
  function MyQuery() {
    const { data } = useReadQuery(queryRef);
  
    // do something with data
  }

Testing utility improvements

• #11178 4d64a6f Thanks @sebakerckhof! - Support re-using of mocks in the MockedProvider

• #6701 8d2b4e1 Thanks @prowe! - Ability to dynamically match mocks

  Adds support for a new property MockedResponse.variableMatcher: a predicate function that accepts a variables param. If true, the variables will be passed into the ResultFunction to help dynamically build a response.

New useQueryRefHandlers hook

• #11412 58db5c3 Thanks @jerelmiller! - Create a new useQueryRefHandlers hook that returns refetch and fetchMore functions for a given queryRef. This is useful to get access to handlers for a queryRef that was created by createQueryPreloader or when the handlers for a queryRef produced by a different component are inaccessible.

  const MyComponent({ queryRef }) {
    const { refetch, fetchMore } = useQueryRefHandlers(queryRef);
  
    // ...
  }

Bail out of optimisticResponse updates with the IGNORE sentinel object

• #11410 07fcf6a Thanks @sf-twingate! - Allow returning IGNORE sentinel object from optimisticResponse functions to bail-out from the optimistic update.

  Consider this example:

  const UPDATE_COMMENT = gql`
    mutation UpdateComment($commentId: ID!, $commentContent: String!) {
      updateComment(commentId: $commentId, content: $commentContent) {
        id
        __typename
        content
      }
    }
  `;
  
  function CommentPageWithData() {
    const [mutate] = useMutation(UPDATE_COMMENT);
    return (
      <Comment
        updateComment={({ commentId, commentContent }) =>
          mutate({
            variables: { commentId, commentContent },
            optimisticResponse: (vars, { IGNORE }) => {
              if (commentContent === "foo") {
                // conditionally bail out of optimistic updates
                return IGNORE;
              }
              return {
                updateComment: {
                  id: commentId,
                  __typename: "Comment",
                  content: commentContent,
                },
              };
            },
          })
        }
      />
    );
  }

  The IGNORE sentinel can be destructured from the second parameter in the callback function signature passed to optimisticResponse.

Network adapters for multipart subscriptions usage with Relay and urql

• #11301 46ab032 Thanks @alessbell! - Add multipart subscription network adapters for Relay and urql

  Relay

  import { createFetchMultipartSubscription } from "@apollo/client/utilities/subscriptions/relay";
  import { Environment, Network, RecordSource, Store } from "relay-runtime";
  
  const fetchMultipartSubs = createFetchMultipartSubscription(
    "http://localhost:4000"
  );
  
  const network = Network.create(fetchQuery, fetchMultipartSubs);
  
  export const RelayEnvironment = new Environment({
    network,
    store: new Store(new RecordSource()),
  });

  Urql

  import { createFetchMultipartSubscription } from "@apollo/client/utilities/subscriptions/urql";
  import { Client, fetchExchange, subscriptionExchange } from "@urql/core";
  
  const url = "http://localhost:4000";
  
  const multipartSubscriptionForwarder = createFetchMultipartSubscription(url);
  
  const client = new Client({
    url,
    exchanges: [
      fetchExchange,
      subscriptionExchange({
        forwardSubscription: multipartSubscriptionForwarder,
      }),
    ],
  });

skipPollAttempt callback function

• #11397 3f7eecb Thanks @aditya-kumawat! - Adds a new skipPollAttempt callback function that's called whenever a refetch attempt occurs while polling. If the function returns true, the refetch is skipped and not reattempted until the next poll interval. This will solve the frequent use-case of disabling polling when the window is inactive.

  useQuery(QUERY, {
    pollInterval: 1000,
    skipPollAttempt: () => document.hidden, // or !document.hasFocus()
  });
  // or define it globally
  new ApolloClient({
    defaultOptions: {
      watchQuery: {
        skipPollAttempt: () => document.hidden, // or !document.hasFocus()
      },
    },
  });

QueryManager.inFlightLinkObservables now uses a strong Trie as an internal data structure

• #11345 1759066 Thanks @phryneas!

  Warning: requires @apollo/experimental-nextjs-app-support update

  If you are using @apollo/experimental-nextjs-app-support, you will need to update that to at least 0.5.2, as it accesses this internal data structure.

3.8.10

Patch Changes

• #11489 abfd02a Thanks @gronxb! - Fix networkStatus with useSuspenseQuery not properly updating to ready state when using a cache-and-network fetch policy that returns data equal to what is already in the cache.

• #11483 6394dda Thanks @pipopotamasu! - Fix cache override warning output

3.8.9

Patch Changes

• #11472 afc844d Thanks @alessbell! - Fix delay: Infinity when set on a MockResponse passed to Mocked Provider so it indefinitely enters loading state.

• #11464 aac12b2 Thanks @jerelmiller! - Prevent useFragment from excessively unsubscribing and resubscribing the fragment with the cache on every render.

• #11449 f40cda4 Thanks @phryneas! - Removes refences to the typescript "dom" lib.

• #11470 e293bc9 Thanks @phryneas! - Remove an unnecessary check from parseAndCheckHttpResponse.

3.8.8

Patch Changes

• #11200 ae5091a21 Thanks @jerelmiller! - Enable strict in tsconfig for the entire project.

• #11332 291aea56b Thanks @asvishnyakov! - Add missed reexports of MutationFetchPolicy and RefetchWritePolicy to @apollo/client/core

• #10931 e5acf910e Thanks @phryneas! - useMutation: also reset internal state on reset

3.8.7

Patch Changes

• #11297 c8c76a522 Thanks @jerelmiller! - Add an explicit return type for the useReadQuery hook called UseReadQueryResult. Previously the return type of this hook was inferred from the return value.

• #11337 bb1da8349 Thanks @phryneas! - #11206 used the TypeScript syntax infer X extends Y that was introduced in TS 4.8. This caused some problems for some users, so we are rolling back to a more backwars-compatible (albeit slightly less performant) type.

3.8.6

Patch Changes

• #11291 2be7eafe3 Thanks @ArioA! - Fix a bug that allows to only call loadErrorMessages without also calling loadDevErrorMessages.

• #11274 b29f000f3 Thanks @jerelmiller! - Start the query ref auto dispose timeout after the initial promise has settled. This prevents requests that run longer than the timeout duration from keeping the component suspended indefinitely.

• #11289 b5894dbf0 Thanks @phryneas! - MockedProvider: default connectToDevTools to false in created ApolloClient instance.

  This will prevent the mocked ApolloClient instance from trying to connect to the DevTools, which would start a setTimeout that might keep running after a test has finished.

• #11206 dd2ce7687 Thanks @phryneas! - cache.modify: Less strict types & new dev runtime warnings.

3.8.5

Patch Changes

• #11266 5192cf6e1 Thanks @phryneas! - Fixes argument handling for invariant log messages.

• #11235 6cddaaf65 Thanks @phryneas! - Fix nextFetchPolicy behaviour with transformed documents by keeping options reference stable when passing it through QueryManager.

• #11252 327a2abbd Thanks @phryneas! - Fixes a race condition in asyncMap that caused issues in React Native when errors were returned in the response payload along with a data property that was null.

• #11229 c372bad4e Thanks @phryneas! - Remove (already throwing) SuspenseCache export that should have been removed in 3.8.

• #11267 bc055e068 Thanks @phryneas! - Remove some dead code.

3.8.4

Patch Changes

• #11195 9e59b251d Thanks @phryneas! - For invariant.log etc., error arguments are now serialized correctly in the link to the error page.

3.8.3

Patch Changes

• #11193 fd2a4cf0c Thanks @phryneas! - Call devtools registration after ApolloClient is fully set up.

3.8.2

Patch Changes

• #10072 51045c336 Thanks @Huulivoide! - Fixes race conditions in useReactiveVar that may prevent updates to the reactive variable from propagating through the hook.

• #11162 d9685f53c Thanks @jerelmiller! - Ensures GraphQL errors returned in subscription payloads adhere to the errorPolicy set in client.subscribe(...) calls.

• #11134 96492e142 Thanks @alessbell! - Use separate type imports in useSuspenseQuery and useBackgroundQuery to workaround SWC compiler issue.

• #11117 6b8198109 Thanks @phryneas! - Adds a new devtools registration mechanism and tweaks the mechanism behind the "devtools not found" mechanic.

• #11186 f1d429f32 Thanks @jerelmiller! - Fix an issue where race conditions when rapidly switching between variables would sometimes result in the wrong data returned from the query. Specifically this occurs when a query is triggered with an initial set of variables (VariablesA), then triggers the same query with another set of variables (VariablesB) but switches back to the VariablesA before the response for VariablesB is returned. Previously this would result in the data for VariablesB to be displayed while VariablesA was active. The data is for VariablesA is now properly returned.

• #11163 a8a9e11e9 Thanks @bignimbus! - Fix typo in error message: "occured" -> "occurred"

• #11180 7d9c481e5 Thanks @jerelmiller! - Fixes an issue where refetching from useBackgroundQuery via refetch with an error after an error was already fetched would get stuck in a loading state.

3.8.1

Patch Changes

• #11141 c469b1616 Thanks @jerelmiller! - Remove newly exported response iterator helpers that caused problems on some installs where @types/node was not available.

  IMPORTANT

  The following exports were added in version 3.8.0 that are removed with this patch.

  • isAsyncIterableIterator
  • isBlob
  • isNodeReadableStream
  • isNodeResponse
  • isReadableStream
  • isStreamableBlob

3.8.0

Minor Changes

Fetching with Suspense 🎉

• #10323 64cb88a4b Thanks @jerelmiller! - Add support for React suspense with a new useSuspenseQuery hook.

  useSuspenseQuery initiates a network request and causes the component calling it to suspend while the request is in flight. It can be thought of as a drop-in replacement for useQuery that allows you to take advantage of React's concurrent features while fetching during render.

  Consider a Dog component that fetches and renders some information about a dog named Mozzarella:

  <summary>View code 🐶</summary>

  import { Suspense } from "react";
  import { gql, TypedDocumentNode, useSuspenseQuery } from "@apollo/client";
  
  interface Data {
    dog: {
      id: string;
      name: string;
    };
  }
  
  interface Variables {
    name: string;
  }
  
  const GET_DOG_QUERY: TypedDocumentNode<Data, Variables> = gql`
    query GetDog($name: String) {
      dog(name: $name) {
        id
        name
      }
    }
  `;
  
  function App() {
    return (
      <Suspense fallback={<div>Loading...</div>}>
        <Dog name="Mozzarella" />
      </Suspense>
    );
  }
  
  function Dog({ name }: { name: string }) {
    const { data } = useSuspenseQuery(GET_DOG_QUERY, {
      variables: { name },
    });
  
    return <>Name: {data.dog.name}</>;
  }

  For a detailed explanation of useSuspenseQuery, see our fetching with Suspense reference.

• #10755 e3c676deb Thanks @alessbell! - Feature: adds useBackgroundQuery and useReadQuery hooks

  useBackgroundQuery initiates a request for data in a parent component and returns a QueryReference which is used to read the data in a child component via useReadQuery. If the child component attempts to render before the data can be found in the cache, the child component will suspend until the data is available. On cache updates to watched data, the child component calling useReadQuery will re-render with new data but the parent component will not re-render (as it would, for example, if it were using useQuery to issue the request).

  Consider an App component that fetches a list of breeds in the background while also fetching and rendering some information about an individual dog, Mozzarella:

  <summary>View code 🐶</summary>

  function App() {
    const [queryRef] = useBackgroundQuery(GET_BREEDS_QUERY);
    return (
      <Suspense fallback={<div>Loading...</div>}>
        <Dog name="Mozzarella" queryRef={queryRef} />
      </Suspense>
    );
  }
  
  function Dog({
    name,
    queryRef,
  }: {
    name: string;
    queryRef: QueryReference<BreedData>;
  }) {
    const { data } = useSuspenseQuery(GET_DOG_QUERY, {
      variables: { name },
    });
    return (
      <>
        Name: {data.dog.name}
        <Suspense fallback={<div>Loading breeds...</div>}>
          <Breeds queryRef={queryRef} />
        </Suspense>
      </>
    );
  }
  
  function Breeds({ queryRef }: { queryRef: QueryReference<BreedData> }) {
    const { data } = useReadQuery(queryRef);
    return data.breeds.map(({ characteristics }) =>
      characteristics.map((characteristic) => (
        <div key={characteristic}>{characteristic}</div>
      ))
    );
  }

  For a detailed explanation of useBackgroundQuery and useReadQuery, see our fetching with Suspense reference.

Document transforms 📑

• #10509 79df2c7ba Thanks @jerelmiller! - Add the ability to specify custom GraphQL document transforms. These transforms are run before reading data from the cache, before local state is resolved, and before the query document is sent through the link chain.

  To register a custom document transform, create a transform using the DocumentTransform class and pass it to the documentTransform option on ApolloClient.

  import { DocumentTransform } from "@apollo/client";
  
  const documentTransform = new DocumentTransform((document) => {
    // do something with `document`
    return transformedDocument;
  });
  
  const client = new ApolloClient({ documentTransform: documentTransform });

  For more information on the behavior and API of DocumentTransform, see its reference page in our documentation.

New removeTypenameFromVariables link 🔗

• #10853 300957960 Thanks @jerelmiller! - Introduce the new removeTypenameFromVariables link. This link will automatically remove __typename fields from variables for all operations. This link can be configured to exclude JSON-scalars for scalars that utilize __typename.

  This change undoes some work from #10724 where __typename was automatically stripped for all operations with no configuration. This was determined to be a breaking change and therefore moved into this link.

  For a detailed explanation of removeTypenameFromVariables, see its API reference.

New skipToken sentinel ⏭️

• #11112 b4aefcfe9 Thanks @jerelmiller! - Adds support for a skipToken sentinel that can be used as options in useSuspenseQuery and useBackgroundQuery to skip execution of a query. This works identically to the skip option but is more type-safe and as such, becomes the recommended way to skip query execution. As such, the skip option has been deprecated in favor of skipToken.

  We are considering the removal of the skip option from useSuspenseQuery and useBackgroundQuery in the next major. We are releasing with it now to make migration from useQuery easier and make skipToken more discoverable.

  useSuspenseQuery

  import { skipToken, useSuspenseQuery } from "@apollo/client";
  
  const id: number | undefined;
  
  const { data } = useSuspenseQuery(
    query,
    id ? { variables: { id } } : skipToken
  );

  useBackgroundQuery

  import { skipToken, useBackgroundQuery } from "@apollo/client";
  
  function Parent() {
    const [queryRef] = useBackgroundQuery(
      query,
      id ? { variables: { id } } : skipToken
    );
  
    return queryRef ? <Child queryRef={queryRef} /> : null;
  }
  
  function Child({ queryRef }: { queryRef: QueryReference<TData> }) {
    const { data } = useReadQuery(queryRef);
  }

  For a detailed explanation of skipToken, see its API reference.

New error extraction mechanism, smaller bundles 📉

• #10887 f8c0b965d Thanks @phryneas! - Add a new mechanism for Error Extraction to reduce bundle size by including error message texts on an opt-in basis.

  By default, errors will link to an error page with the entire error message. This replaces "development" and "production" errors and works without additional bundler configuration.

  Bundling the text of error messages and development warnings can be enabled as follows:

  import { loadErrorMessages, loadDevMessages } from "@apollo/client/dev";
  if (process.env.NODE_ENV !== "production") {
    loadErrorMessages();
    loadDevMessages();
  }

  For a detailed explanation, see our reference on reducing bundle size.

New @nonreactive directive 🎬

• #10722 c7e60f83d Thanks @benjamn! - Implement a @nonreactive directive for selectively skipping reactive comparisons of query result subtrees.

  The @nonreactive directive can be used to mark query fields or fragment spreads and is used to indicate that changes to the data contained within the subtrees marked @nonreactive should not trigger re-rendering. This allows parent components to fetch data to be rendered by their children without re-rendering themselves when the data corresponding with fields marked as @nonreactive change.

  Consider an App component that fetches and renders a list of ski trails:

  <summary>View code 🎿</summary>

  const TrailFragment = gql`
    fragment TrailFragment on Trail {
      name
      status
    }
  `;
  
  const ALL_TRAILS = gql`
    query allTrails {
      allTrails {
        id
        ...TrailFragment @nonreactive
      }
    }
    ${TrailFragment}
  `;
  
  function App() {
    const { data, loading } = useQuery(ALL_TRAILS);
    return (
      <main>
        <h2>Ski Trails</h2>
        <ul>
          {data?.trails.map((trail) => (
            <Trail key={trail.id} id={trail.id} />
          ))}
        </ul>
      </main>
    );
  }

  The Trail component renders a trail's name and status and allows the user to execute a mutation to toggle the status of the trail between "OPEN" and "CLOSED":

  <summary>View code 🎿</summary>

  const Trail = ({ id }) => {
    const [updateTrail] = useMutation(UPDATE_TRAIL);
    const { data } = useFragment({
      fragment: TrailFragment,
      from: {
        __typename: "Trail",
        id,
      },
    });
    return (
      <li key={id}>
        {data.name} - {data.status}
        <input
          checked={data.status === "OPEN" ? true : false}
          type="checkbox"
          onChange={(e) => {
            updateTrail({
              variables: {
                trailId: id,
                status: e.target.checked ? "OPEN" : "CLOSED",
              },
            });
          }}
        />
      </li>
    );
  };

  Notice that the Trail component isn't receiving the entire trail object via props, only the id which is used along with the fragment document to create a live binding for each trail item in the cache. This allows each Trail component to react to the cache updates for a single trail independently. Updates to a trail's status will not cause the parent App component to rerender since the @nonreactive directive is applied to the TrailFragment spread, a fragment that includes the status field.

  For a detailed explanation, see our @nonreactive reference and @alessbell's post on the Apollo blog about using @nonreactive with useFragment.

Abort the AbortController signal more granularly 🛑

• #11040 125ef5b2a Thanks @phryneas! - HttpLink/BatchHttpLink: Abort the AbortController signal more granularly.

  Before this change, when HttpLink/BatchHttpLink created an AbortController internally, the signal would always be .aborted after the request was completed. This could cause issues with Sentry Session Replay and Next.js App Router Cache invalidations, which just replayed the fetch with the same options - including the cancelled AbortSignal.

  With this change, the AbortController will only be .abort()ed by outside events, not as a consequence of the request completing.

useFragment drops its experimental label 🎓

• #10916 ea75e18de Thanks @alessbell! - Remove experimental labels.

  useFragment, introduced in 3.7.0 as useFragment_experimental, is no longer an experimental API 🎉 We've removed the _experimental suffix from its named export and have made a number of improvements.

  For a detailed explanation, see our useFragment reference and @alessbell's post on the Apollo blog about using useFragment with @nonreactive for improved performance when rendering lists.

  <summary>

  useFragment improvements

  </summary>

  • #10765 35f36c5aa Thanks @phryneas! - More robust types for the data property on UseFragmentResult. When a partial result is given, the type is now correctly set to Partial<TData>.

  • #11083 f766e8305 Thanks @phryneas! - Adjust the rerender timing of useQuery to more closely align with useFragment. This means that cache updates delivered to both hooks should trigger renders at relatively the same time. Previously, the useFragment might rerender much faster leading to some confusion.

  • #10836 6794893c2 Thanks @phryneas! - Remove the deprecated returnPartialData option from useFragment hook.

3.7.17

Patch Changes

• #10631 b93388d75 Thanks @phryneas! - ObservableQuery.getCurrentResult: skip the cache if the running query should not access the cache

3.7.16

Patch Changes

• #10806 cb1540504 Thanks @phryneas! - Fix a bug in PersistedQueryLink that would cause it to permanently skip persisted queries after a 400 or 500 status code.

• #10807 b32369592 Thanks @phryneas! - PersistedQueryLink will now also check for error codes in extensions.

• #10982 b9be7a814 Thanks @sdeleur-sc! - Update relayStylePagination to avoid populating startCursor when only a single cursor is present under the edges field. Use that cursor only as the endCursor.

• #10962 772cfa3cb Thanks @jerelmiller! - Remove useGETForQueries option in BatchHttpLink.Options type since it is not supported.

3.7.15

Patch Changes

• #10891 ab42a5c08 Thanks @laverdet! - Fixes a bug in how multipart responses are read when using @defer. When reading a multipart body, HttpLink no longer attempts to parse the boundary (e.g. "---" or other boundary string) within the response data itself, only when reading the beginning of each mulitpart chunked message.

• #10789 23a4e1578 Thanks @phryneas! - Fix a bug where other fields could be aliased to __typename or id, in which case an incoming result would be merged into the wrong cache entry.

3.7.14

Patch Changes

• #10764 1b0a61fe5 Thanks @phryneas! - Deprecate useFragment returnPartialData option

• #10810 a6252774f Thanks @dleavitt! - Fix type signature of ServerError.

  In <3.7 HttpLink and BatchHttpLink would return a ServerError.message of e.g. "Unexpected token 'E', \"Error! Foo bar\" is not valid JSON" and a ServerError.result of undefined in the case where a server returned a >= 300 response code with a response body containing a string that could not be parsed as JSON.

  In >=3.7, message became e.g. Response not successful: Received status code 302 and result became the string from the response body, however the type in ServerError.result was not updated to include the string type, which is now properly reflected.

3.7.13

Patch Changes

• #10805 a5503666c Thanks @phryneas! - Fix a potential memory leak in SSR scenarios when many persistedQuery instances were created over time.

• #10718 577c68bdd Thanks @Hsifnus! - Delay Concast subscription teardown slightly in useSubscription to prevent unexpected Concast teardown when one useSubscription hook tears down its in-flight Concast subscription immediately followed by another useSubscription hook reusing and subscribing to that same Concast

3.7.12

Patch Changes

• #10735 895bcdcff Thanks @alessbell! - If a multipart chunk contains only hasNext: false, immediately complete the observable.

3.7.11

Patch Changes

• #10586 4175af594 Thanks @alessbell! - Improve WebSocket error handling for generic Event received on error. For more information see https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/error_event.

• #10411 152baac34 Thanks @lovasoa! - Simplify error message generation and make 'undefined' an impossible message string.

• #10592 cdb98ae08 Thanks @alessbell! - Adds support for multipart subscriptions in HttpLink.

• #10698 38508a251 Thanks @jerelmiller! - Changes the behavior of useLazyQuery introduced in #10427 where unmounting a component before a query was resolved would reject the promise with an abort error. Instead, the promise will now resolve naturally with the result from the request.

  Other notable fixes:

  • Kicking off multiple requests in parallel with the execution function will now ensure each returned promise is resolved with the data from its request. Previously, each promise was resolved with data from the last execution.
  • Re-rendering useLazyQuery with a different query document will now ensure the execution function uses the updated query document. Previously, only the query document rendered the first time would be used for the request.

• #10660 364bee98f Thanks @alessbell! - Upgrades TypeScript to v5. This change is fully backward-compatible and transparent to users.

• #10597 8fb9d190d Thanks @phryneas! - Fix a bug where an incoming cache update could prevent future updates from the active link.

• #10629 02605bb3c Thanks @phryneas! - useQuery: delay unsubscribe to fix race conditions

3.7.10

Patch Changes

• #9438 52a9c8ea1 Thanks @dciesielkiewicz! - Ensure the client option passed to useMutation's execute function is used when provided. Previously this option was ignored.

• #9124 975b923c0 Thanks @andrebrantom! - Make ApolloClient.writeQuery and ApolloClient.writeFragment behave more like cache.writeQuery and cache.writeFragment by returning the reference returned by the cache.

3.7.9

Patch Changes

• #10560 a561ecf43 Thanks @benjamn! - Keep __typename fragment when it does not contain @client directive and strip out inline fragments which use a @client directive. Thanks @Gazler and @mtsmfm!

• #10560 251a12806 Thanks @benjamn! - Refactor removeDirectivesFromDocument to fix AST ordering sensitivities and avoid 1/3 AST traversals, potentially improving performance for large queries

3.7.8

Patch Changes

• #7555 45562d6fa Thanks @TheCeloReis! - Adds TVariables generic to GraphQLRequest and MockedResponse interfaces.

• #10526 1d13de4f1 Thanks @benjamn! - Tolerate undefined concast.sources if complete called earlier than concast.start

• #10497 8a883d8a1 Thanks @nevir! - Update SingleExecutionResult and IncrementalPayload's data types such that they no longer include undefined, which was not a valid runtime value, to fix errors when TypeScript's exactOptionalPropertyTypes is enabled.

3.7.7

Patch Changes

• #10502 315faf9ca Thanks @jerelmiller! - Log a warning to the console when a mock passed to MockedProvider or MockLink cannot be matched to a query during a test. This makes it easier to debug user errors in the mock setup, such as typos, especially if the query under test is using an errorPolicy set to ignore, which makes it difficult to know that a match did not occur.

• #10499 9e54f5dfa Thanks @phryneas! - Allow the execution function returned by useLazyQuery to change the query.

• #10362 14a56b105 Thanks @mccraveiro! - Fix error when server returns an error and we are also querying for a local field

3.7.6

Patch Changes

• #10470 47435e879 Thanks @alessbell! - Bumps TypeScript to 4.9.4 (previously 4.7.4) and updates types to account for changes in TypeScript 4.8 by propagating contstraints on generic types. Technically this makes some types stricter as attempting to pass null|undefined into certain functions is now disallowed by TypeScript, but these were never expected runtime values in the first place. This should only affect you if you are wrapping functions provided by Apollo Client with your own abstractions that pass in their generics as type arguments, in which case you might get an error like error TS2344: Type 'YourGenericType' does not satisfy the constraint 'OperationVariables'. In that case, make sure that YourGenericType is restricted to a type that only accepts objects via extends, like Record<string, any> or @apollo/client's OperationVariables:

  import {
    QueryHookOptions,
    QueryResult,
    useQuery,
  + OperationVariables,
  } from '@apollo/client';
  - export function useWrappedQuery<T, TVariables>(
  + export function useWrappedQuery<T, TVariables extends OperationVariables>(
      query: DocumentNode,
      queryOptions: QueryHookOptions<T, TVariables>
    ): QueryResult<T, TVariables> {
      const [execute, result] = useQuery<T, TVariables>(query);
    }

• #10408 55ffafc58 Thanks @zlrlo! - fix: modify BatchHttpLink to have a separate timer for each different batch key

• #9573 4a4f48dda Thanks @vladar! - Improve performance of local resolvers by only executing selection sets that contain an @client directive. Previously, local resolvers were executed even when the field did not contain @client. While the result was properly discarded, the unncessary work could negatively affect query performance, sometimes signficantly.

3.7.5

Patch Changes

• #10458 b5ccef229 Thanks @lennyburdette! - Passes getServerSnapshot to useSyncExternalStore so that it doesn't trigger a Missing getServerSnapshot error when using useFragment_experimental on the server.

• #10471 895ddcb54 Thanks @alessbell! - More robust type definition for headers property passed to createHttpLink

• #10321 bbaa3ef2d Thanks @alessbell! - Refetch should not return partial data with errorPolicy: none and notifyOnNetworkStatusChange: true.

• #10402 0b07aa955 Thanks @Hugodby! - Improve context types

• #10469 328c58f90 Thanks @jerelmiller! - Add generic type defaults when using useFragment to allow passing TData directly to the function without needing to specify TVars.

3.7.4

Patch Changes

• #10427 28d909cff Thanks @jerelmiller! - Ensure in-flight promises executed by useLazyQuery are rejected when useLazyQuery unmounts.

• #10383 5c5ca9b01 Thanks @jerelmiller! - Ensure the onError callback is called when the errorPolicy is set to "all" and partial data is returned.

• #10425 86e35a6d2 Thanks @jerelmiller! - Prefer the onError and onCompleted callback functions passed to the execute function returned from useMutation instead of calling both callback handlers.

3.7.3

Patch Changes

• #10334 7d923939d Thanks @jerelmiller! - Better handle deferred queries that have cached or partial cached data for them

• #10368 46b58e976 Thanks @alessbell! - Fix: unblocks support for defer in mutations

  If the @defer directive is present in the document passed to mutate, the Promise will resolve with the final merged data after the last multipart chunk has arrived in the response.

3.7.2

Patch Changes

• Only show dev tools suggestion in the console when connectToDevTools is true.
  @chris110408 in #10258

• Pass TCache generic to MutationHookOptions for better type support in useMutation.
  @igrlk in #10223

• Add name property to ApolloError to ensure better type safety and help error reporting tools better identify the error.
  @aaronadamsCA in #9323

• Export a ModifierDetails type for the details parameter of a Modifier function.
  @KeithGillette in #7133

• Revert use of cloneDeep to clone options when fetching queries.
  @MrDoomBringer in #10215

3.7.1

Patch Changes

• Fix issue where loading remains true after observer.refetch is called repeatedly with different variables when the same data are returned.
  @alessbell in #10143

• Fix race condition where useFragment_experimental could receive cache updates before initially calling cache.watch in useEffect.
  @benjamn in #10212

3.7.0

Minor Changes

• Implement preview support for the @defer directive.
  @alessbell and @benjamn in #10018

• Implement useFragment_experimental hook, which represents a lightweight live binding into the ApolloCache, and never triggers network requests of its own.
  @benjamn in #8782

• Allow registering named fragments with InMemoryCache to support using ...NamedFragment in queries without redeclaring NamedFragment repeatedly in every query that uses it.
  @benjamn in #9764

• Support onError callback for useSubscription hook.
  @jeroenvisser101 in #9495

• Implement preserveHeaderCase option for http context object, enabling preserved header capitalization for non-http-spec-compliant servers.
  @mrdoombringer in #9891

Patch Changes

• Delay calling onCompleted and onError callbacks passed to useQuery using Promise.resolve().then(() => ...) to fix issue #9794.
  @dylanwulf in #9823

• Replace concast.cleanup method with simpler concast.beforeNext API, which promises to call the given callback function just before the next result/error is delivered. In addition, concast.removeObserver no longer takes a quietly?: boolean parameter, since that parameter was partly responsible for cleanup callbacks sometimes not getting called.
  @benjamn in #9718

• Allow preserving header name capitalization when creating an HttpLink with createHttpLink({ uri, preserveHeaderCase: true }). Otherwise, header names are converted to lowercase to prevent case-sensitivity bugs.
  @MrDoomBringer in #9891

• Make queries with a pollInterval respect the no-cache fetch policy, instead of writing polled results into the cache.
  @MrDoomBringer in #10020

• Deprecate the onSubscriptionData callback in favor of a new onData callback for the useSubscription hook. Deprecate the onSubscriptionComplete callback in favor of a new onComplete callback for the useSubscription hook.
  @jerelmiller in #10134

Potentially disruptive

• The optional subscribeAndCount testing utility exported from @apollo/client/testing/core now takes a single generic TResult type parameter, instead of TData. This type will typically be inferred from the observable argument type, but if you have any explicit calls to subscribeAndCount<TData>(...) in your own codebase, you may need to adjust those calls accordingly.
  @benjamn in #9718

Apollo Client 3.6.10 (2022-09-29)

Improvements

• The client options (variables, context, etc.) used for mutation calls are now available as the second argument to the onCompleted and onError callback functions.
  @MrDoomBringer in #10052

Apollo Client 3.6.9 (2022-06-21)

Bug Fixes

• Leave fetchPolicy unchanged when skip: true (or in standby) and nextFetchPolicy is available, even if variables change.
  @benjamn in #9823

Apollo Client 3.6.8 (2022-06-10)

Bug Fixes

• Fix incorrect variables passed in FieldFunctionOptions for nested readField calls in read and merge functions.
  @stardustxx in #9808

• Improve repository build scripts to work better on Windows.
  @dylanwulf in #9805

• Ensure useQuery(query, { skip: true }).called === false rather than always returning called as true.
  @KucharskiPiotr in #9798

• Allow abandoned reobserve requests to unsubscribe from their underlying Observable.
  @javier-garcia-meteologica in #9791

Apollo Client 3.6.7 (2022-06-10)

Bug Fixes

• Fix regression (introduced in v3.6.0) that caused BatchHttpLink to discard pending batched queries on early completion of the underlying Observable.
  @benjamn in #9793

Apollo Client 3.6.6 (2022-05-26)

Bug Fixes

• Allow useLazyQuery(query, { defaultOptions }) to benefit from defaultOptions.variables and client.defaultOptions.watchQuery.variables merging.
  @benjamn in #9762

Apollo Client 3.6.5 (2022-05-23)

Bug Fixes

• Restore pre-v3.6 variables replacement behavior of ObservableQuery#reobserve method, fixing a regression that prevented removal of variables.
  @benjamn in #9741

• Preserve previousData even when different query or client provided to useQuery, instead of resetting previousData to undefined in those cases, matching behavior prior to v3.6.0.
  @benjamn in #9734

• Fix bug where onCompleted() and onError() are stale for useMutation().
  @charle692 in #9740

• Limit scope of DeepMerger object reuse, and avoid using Object.isFrozen, which can introduce differences between development and production if objects that were frozen using Object.freeze in development are left unfrozen in production.
  @benjamn in #9742

• Properly merge variables from original useLazyQuery(query, { variables }) with variables passed to execution function.
  @benjamn in #9758

Apollo Client 3.6.4 (2022-05-16)

Bug Fixes

• Guarantee Concast cleanup without Observable cancelled prematurely rejection, potentially solving long-standing issues involving that error.
  @benjamn in #9701

• Ensure useSubscription subscriptions are properly restarted after unmounting/remounting by React 18 in <StrictMode>.
  @kazekyo in #9707

Improvements

• Internalize useSyncExternalStore shim, for more control than use-sync-external-store provides, fixing some React Native issues.
  @benjamn in #9675 and #9709

• Provide @apollo/client/**/*.cjs.native.js versions of every @apollo/client/**/*.cjs bundle (including dependencies ts-invariant and zen-observable-ts) to help React Native's Metro bundler automatically resolve CommonJS entry point modules. These changes should render unnecessary the advice we gave in the v3.5.4 section below about metro.config.js.
  @benjamn in #9716

• Handle falsy incoming data more gracefully in offetLimitPagination().merge function.
  @shobhitsharma in #9705

Apollo Client 3.6.3 (2022-05-05, only tagged next on npm)

Bug Fixes

• Simplify useQuery(query, { defaultOptions }) default options processing in order to fix bug where skip: true queries failed to execute upon switching to skip: false.
  @benjamn in #9665

• Add tests of skipping/unskipping and useLazyQuery with defaultOptions, and fix a bug causing duplicate requests.
  @benjamn in #9666

• Update ts-invariant to version 0.10.2 to fix source map warnings.
  @benjamn in #9672

• Test that useQuery queries with skip: true do not stall server-side rendering.
  @nathanmarks and @benjamn in #9677

• Prevent useLazyQuery from making duplicate requests when its execution function is first called, and stop rejecting the Promise it returns when result.error is defined.
  @benjamn in #9684

• Fix issue with useQuery returning loading: true state during server-side rendering with skip: true.
  @nathanmarks in #9679

Apollo Client 3.6.2 (2022-05-02)

Bug Fixes

• Pass getServerSnapshot function to useSyncExternalStore in addition to getSnapshot, though the two functions behave identically. This change should fix/unbreak React 18 server rendering.
  @hungphongbk in #9652

Improvements

• Consider networkError.result.errors in addition to result.errors in PersistedQueryLink.
  @redaid113 and @benjamn in #9410

Apollo Client 3.6.1 (2022-04-28)

Bug Fixes

• Remove recently-added, internal fetchBlockingPromise option from the WatchQueryOptions interface, due to regressions.
  @benjamn in #9504

Apollo Client 3.6.0 (2022-04-26)

Potentially disruptive changes

• Calling fetchMore for queries using the cache-and-network or network-only fetch policies will no longer trigger additional network requests when cache results are complete. Instead, those complete cache results will be delivered as if using the cache-first fetch policy.
  @benjamn in #9504

• Reimplement useQuery and useLazyQuery to use the proposed useSyncExternalStore API from React 18.
  @brainkim and @benjamn in #8785 and #9596

• Fixed bug where the useLazyQuery execution function would always use the refetch method of ObservableQuery, instead of properly reapplying the current fetchPolicy using the reobserve method.
  @benjamn in #9564

  Since this reobserve method is useful and used internally, we have now exposed it as use[Lazy]Query(...).reobserve (which optionally takes a Partial<WatchQueryOptions> of new options), to supplement the existing refetch method. Note that reobserve permanently updates the variables and other options of the ObservableQuery, unlike refetch({ ...variables }), which does not save those variables.

• The internal use of options.fetchBlockingPromise by useQuery and useLazyQuery may slightly delay the delivery of network results, compared to previous versions of Apollo Client. Since network results are already delivered asynchronously, these timing differences should not be disruptive in most cases. Nevertheless, please open an issue if the timing differences are a problem for you (and you have no easy workaround).
  @benjamn in #9599

React 18

In both its peerDependencies and its internal implementation, Apollo Client v3.6 should no longer prevent you from updating to React 18 in your applications.

Internally, we have refactored useQuery and useLazyQuery to be implemented in terms of React's new (shimmable) useSyncExternalStore hook, demonstrating Apollo Client can serve as an external store with a referentially stable, synchronous API, as needed by React.

As part of this refactoring, we also improved the behavior of useQuery and useLazyQuery when used in <React.StrictMode>, which double-renders components in development. While this double-rendering always results in calling useQuery twice, forcing Apollo Client to create and then discard an unnecessary ObservableQuery object, we now have multiple defenses in place against executing any network queries for the unused ObservableQuery objects.

In upcoming v3.6.x and v3.7 (beta) releases, we will be completely overhauling our server-side rendering utilities (getDataFromTree et al.), and introducing suspenseful versions of our hooks, to take full advantage of the new patterns React 18+ enables for data management libraries like Apollo Client.

Improvements

• Allow BatchLink to cancel queued and in-flight operations.
  @PowerKiKi and @benjamn in #9248

• Add GraphQLWsLink in @apollo/client/link/subscriptions. This link is similar to the existing WebSocketLink in @apollo/client/link/ws, but uses the newer graphql-ws package and protocol instead of the older subscriptions-transport-ws implementation. This functionality was technically first released in @apollo/client@3.5.10, but semantically belongs in the 3.6.0 minor version. @glasser in #9369

• Allow passing defaultOptions to useQuery to avoid clobbering/resetting existing options when useQuery is called repeatedly.
  @benjamn in #9563, superseding #9223

• Provide additional context to nextFetchPolicy functions to assist with fetchPolicy transitions. More details can be found in the nextFetchPolicy documentation.
  @benjamn in #9222

• Remove nagging deprecation warning about passing an options.updateQuery function to fetchMore.
  @benjamn in #9504

• Let addTypenameToDocument take any ASTNode (including DocumentNode, as before).
  @benjamn in #9595

• Set useMutation internal isMounted variable to true again when component remounted.
  @devpeerapong in #9561

Apollo Client 3.5.10 (2022-02-24)

Improvements

• Add GraphQLWsLink in @apollo/client/link/subscriptions. This link is similar to the existing WebSocketLink in @apollo/client/link/ws, but uses the newer graphql-ws package and protocol instead of the older subscriptions-transport-ws implementation.
  @glasser in #9369

  Note from @benjamn: since GraphQLWsLink is new functionality, we would normally wait for the next minor version (v3.6), but we were asked to expedite this release. These changes are strictly additive/opt-in/backwards-compatible, so shipping them in a patch release (3.5.10) seems safe, if unusual.

Apollo Client 3.5.9 (2022-02-15)

Improvements

• Interpret keyFields: [...] and keyArgs: [...] configurations in InMemoryCache type/field policies as ReadonlyArrays, since they are never mutated internally.
  @julienfouilhe in #9339

• Avoid declaring a global type for the __DEV__ constant, to avoid conflict with other such global declarations.
  @benjamn in #9386

Bug Fixes

• Fix useSubscription executing skipped subscription when input changes.
  @levrik in #9299

• Fix partial data appearing in useQuery().data when notifyOnNetworkStatusChange: true.
  @brainkim in #9367

• Prevent Promises returned by useLazyQuery execute functions from causing unhandled Promise rejection errors if uncaught.
  @brainkim in #9380

Apollo Client 3.5.8 (2022-01-24)

Bug Fixes

• Fix the type of the called property returned by useQuery() and useLazyQuery().
  @sztadii in #9304

Bug Fixes (by @brainkim in #9328)

• Fix refetch() not being called when skip is true.
• Fix the promise returned from the useLazyQuery() execution function having stale variables.
• Fix the promise returned from the useLazyQuery() execution function not rejecting when a query errors.

Apollo Client 3.5.7 (2022-01-10)

Bug Fixes

• Fix regression that prevented calling onError or onCompleted in some cases when using useQuery.
  @mmahalwy in #9226

• Make useQuery respect defaultOptions.watchQuery.fetchPolicy.
  @yasharzolmajdi in #9210

Apollo Client 3.5.6 (2021-12-07)

Bug Fixes (by @brainkim in #9144)

• Restores old behavior where the callback passed to useMutation() is constant.
• Fix useMutation() callbacks having stale closures.
• Fix useQuery() variables being out of date.

Apollo Client 3.5.5 (2021-11-23)

Bug Fixes

• Remove printer: Printer positional parameter from publicly-exported selectHttpOptionsAndBody function, whose addition in #8699 was a breaking change (starting in Apollo Client 3.5.0) for direct consumers of selectHttpOptionsAndBody.
  @benjamn in #9103

Apollo Client 3.5.4 (2021-11-19)

Notices

⚠️ The following advice about metro.config.js should no longer be necessary, as of Apollo Client v3.6.4.

• [Relevant if you use Apollo Client with React Native] Since Apollo Client v3.5.0, CommonJS bundles provided by @apollo/client use a .cjs file extension rather than .cjs.js, so Node.js won't interpret them as ECMAScript modules. While this change should be an implementation detail, it may cause problems for the Metro bundler used by React Native, whose resolver.sourceExts configuration does not include the cjs extension by default.

  As a workaround until this issue is resolved, you can configure Metro to understand the .cjs file extension by creating a metro.config.js file in the root of your React Native project:

  // NOTE: No longer necessary in @apollo/client@3.6.4!
  const { getDefaultConfig } = require("metro-config");
  const { resolver: defaultResolver } = getDefaultConfig.getDefaultValues();
  exports.resolver = {
    ...defaultResolver,
    sourceExts: [...defaultResolver.sourceExts, "cjs"],
  };

Improvements

• Restore the ability to pass onError() and onCompleted() to the mutation execution function.
  @brainkim in #9076

• Work around webpack 5 errors of the form

  The request 'ts-invariant/process' failed to resolve only because it was resolved as fully specified

  by ensuring import ... from 'ts-invariant/process' is internally written to import ... from 'ts-invariant/process/index.js'.
  @benjamn in #9083

Apollo Client 3.5.3 (2021-11-17)

• Avoid rewriting non-relative imported module specifiers in config/rewriteModuleIds.ts script, thereby allowing bundlers to resolve those imports as they see fit.
  @benjamn in #9073

• Ensure only current file is matched when running VSCode debugger.
  @eps1lon in #9050

Apollo Client 3.5.2 (2021-11-10)

• Fix useMutation execute function returning non-identical execution functions when passing similar options.
  @brainkim in #9037

Apollo Client 3.5.1 (2021-11-09)

• Remove npm from dependencies, and avoid referencing graphql-js enum value.
  @brainkim in #9030

Apollo Client 3.5.0 (2021-11-08)

Improvements

• Add updateQuery and updateFragment methods to ApolloCache, simplifying common readQuery/writeQuery cache update patterns.
  @wassim-k in #8382

• Field directives and their arguments can now be included along with field argument names when using field policy keyArgs: [...] notation. For example, if you have a Query.feed field that takes an argument called type and uses a @connection(key:...) directive to keep feed data from different queries separate within the cache, you might configure both using the following InMemoryCache field policy:

  new InMemoryCache({
    typePolicies: {
      Query: {
        fields: {
          feed: {
            keyArgs: ["type", "@connection", ["key"]],
          },
        },
      },
    },
  });

  @benjamn in #8678

• Report single MissingFieldError instead of a potentially very large MissingFieldError[] array for incomplete cache reads, improving performance and memory usage.
  @benjamn in #8734

• When writing results into InMemoryCache, each written object is now identified using policies.identify after traversing the fields of the object (rather than before), simplifying identification and reducing duplicate work. If you have custom keyFields functions, they still receive the raw result object as their first parameter, but the KeyFieldsContext parameter now provides context.storeObject (the StoreObject just processed by processSelectionSet) and context.readField (a helper function for reading fields from context.storeObject and any References it might contain, similar to readField for read, merge, and cache.modify functions).
  @benjamn in #8996

• Ensure cache.identify never throws when primary key fields are missing, and include the source object in the error message when keyFields processing fails.
  @benjamn in #8679

• The HttpLink constructor now accepts an optional print function that can be used to customize how GraphQL DocumentNode objects are transformed back into strings before they are sent over the network.
  @sarahgp in #8699

• Make @apollo/client/testing a fully-fledged, independent entry point, instead of re-exporting @apollo/client/utilities/testing (which was never an entry point and no longer exists).
  @benjamn in #8769

• A new nested entry point called @apollo/client/testing/core has been created. Importing from this entry point instead of @apollo/client/testing excludes any React-related dependencies.
  @wassim-k in #8687

• Make cache.batch return the result of calling the options.update function.
  @benjamn in #8696

• The NetworkError and ErrorResponse types have been changed to align more closely.
  @korywka in #8424

• Include graphql@16 in peer deps.
  @brainkim in #8997

• Update zen-observable-ts to eliminate transitive dependency on @types/zen-observable.
  @benjamn in #8695

React Refactoring

Improvements (due to @brainkim in #8875):

• The useLazyQuery function now returns a promise with the result.
• The useMutation result now exposes a method which can be reset.

Bug Fixes (due to @brainkim in #8596):

• The useQuery and useLazyQuery hooks will now have ObservableQuery methods defined consistently.
• Calling useLazyQuery methods like startPolling will start the query.
• Calling the useLazyQuery execution function will now behave more like refetch. previousData will be preserved.
• standby fetchPolicies will now act like skip: true more consistently.
• Calling refetch on a skipped query will have no effect (issue #8270).
• Prevent onError and onCompleted functions from firing continuously, and improving their polling behavior.

Apollo Client 3.4.17 (2021-11-08)

Improvements

• Allow TOptions extends FieldFunctionOptions to be passed as final (optional) type parameter of FieldPolicy type.
  @VictorGaiva in #9000

Apollo Client 3.4.16

Improvements

• Prevent webpack from misresolving the graphql package as the local @apollo/client/utilities/globals/graphql.js module when module.exports.resolve.preferRelative is enabled in webpack.config.js.

  Note: if you encounter strange module resolution errors like export 'isType' (imported as 'isType') was not found in 'graphql' (possible exports: removeTemporaryGlobals) please try removing preferRelative: true from your webpack.config.js file, or find a way to disable that resolution behavior for packages within node_modules.

  @benjamn in #8862

• Avoid importing isType from the graphql package internally, to prevent bundlers from including as much as 3.4kB of unnecessary code.
  @benjamn in #8891

• Make client.resetStore and client.clearStore pass appropriate discardWatches option to cache.reset.
  @benjamn in #8873

Apollo Client 3.4.15

Bug Fixes

• Require calling cache.reset({ discardWatches: true }) to make cache.reset discard cache.watches, restoring behavior broken in v3.4.14 by #8826.
  @benjamn in #8852

Apollo Client 3.4.14

Bug Fixes

• Disable InMemoryCache result object canonization by default, to prevent unexpected memory growth and/or reuse of object references, with multiple ways to reenable it (per-cache, per-query, or a mixture of both).
  @benjamn in #8822

• Clear InMemoryCache watches set when cache.reset() called.
  @benjamn in #8826

• Stop excluding observerless queries from refetchQueries: [...] selection.
  @benjamn in #8825

• Prevent optimistic cache evictions from evicting non-optimistic data.
  @benjamn in #8829

• Ensure cache.broadcastWatch passes all relevant WatchOptions to cache.diff as DiffOptions.
  @benjamn in #8832

Apollo Client 3.4.13

Bug Fixes

• Fix componentDidUpate typo in withSubscription higher-order component.
  @YarBez in #7506

• Fix internal canUseSymbol import within @apollo/client/utilities to avoid breaking bundlers/builds.
  @benjamn in #8817

• Tolerate unfreezable objects like Uint8Array and Buffer in maybeDeepFreeze.
  @geekuillaume and @benjamn in #8813

Apollo Client 3.4.12

Bug Fixes

• Improve handling of falsy existing and/or incoming parameters in relayStylePagination field policy helper function.
  @bubba and @benjamn in #8733

• Associate Apollo context with React.createContext (instead of using a local WeakMap) again, so multiple copies of @apollo/client (uncommon) can share the same context.
  @benjamn in #8798

Apollo Client 3.4.11

Bug Fixes

• Fix Vite tree-shaking by calling the checkDEV() function (at least once) in the module that exports it, @apollo/client/utilities/globals/index.ts.
  @benjamn in #8767

Improvements

• Export PersistedQueryLink namespace from @apollo/client/link/persisted-queries.
  @vedrani in #8761

Documentation

• Upgrade docs theme for new Algolia-powered search experience.
  @trevorblades in #8768

Apollo Client 3.4.10

Improvements

• Warn when calling refetch({ variables }) instead of refetch(variables), except for queries that declare a variable named $variables (uncommon).
  @benjamn in #8702

Bug Fixes

• Fix ObservableQuery.getCurrentResult() returning cached data with certain fetch policies.
  @brainkim in #8718

• Prevent ssrMode/ssrForceFetchDelay from causing queries to hang.
  @brainkim in #8709

• Import @apollo/client/utilities/globals internally wherever __DEV__ is used, not just in @apollo/client/**/index.js entry points.
  @benjamn in #8720

Apollo Client 3.4.9

Bug Fixes

• Fix unhandled Promise rejection warnings/errors whose message is Observable cancelled prematurely.
  @benjamn in #8676

• Enforce that __DEV__ is polyfilled by every @apollo/client/* entry point that uses it. This build step considers not only explicit __DEV__ usage but also __DEV__ references injected near invariant(...) and new InvariantError(...) expressions.
  @benjamn in #8689

Apollo Client 3.4.8

Bug Fixes

• Fix error thrown by nested keyFields: ["a", ["b", "c"], "d"] type policies when writing results into the cache where any of the key fields (.a, .a.b, .a.c, or .d) have been renamed by query field alias syntax.
  @benjamn in #8643

• Fix regression from PR #8422 (first released in @apollo/client@3.4.0-rc.15) that caused result.data to be set to undefined in some cases after ObservableQuery#getCurrentResult reads an incomplete result from the cache.
  @benjamn in #8642

Apollo Client 3.4.7

Bug Fixes

• Fix accidental reuse of recycled MergeTree objects in StoreWriter class used by InMemoryCache.
  @benjamn in #8618

Apollo Client 3.4.6

Improvements

• Reevaluate window.fetch each time HttpLink uses it, if not configured using options.fetch. This change enables a variety of strategies for instrumenting window.fetch, without requiring those strategies to run before @apollo/client/link/http is first imported.
  @benjamn in #8603

• Clarify mutation fetchPolicy options ("network-only" or "no-cache") using MutationFetchPolicy union type.
  @benjamn in #8602

Bug Fixes

• Restore full @apollo/client/apollo-client.cjs.js CommonJS bundle for older bundlers.

  Note that Node.js and CommonJS bundlers typically use the bundles specified by "main" fields in our generated package.json files, which are all independent and non-overlapping CommonJS modules. However, apollo-client.cjs.js is just one big bundle, so mixing imports of apollo-client.cjs.js with the other CommonJS bundles is discouraged, as it could trigger the dual package hazard. In other words, please don't start using apollo-client.cjs.js if you're not already.
  

  @benjamn in #8592

• Log MissingFieldErrors in ObservableQuery#getCurrentResult using invariant.debug, rather than reporting them via result.error.
  @benjamn in #8604

Apollo Client 3.4.5

Bug Fixes

• Fix double registration bug for mutation refetchQueries specified using legacy one-time refetchQueries: [{ query, variables }] style. Though the bug is fixed, we recommend using refetchQueries: [query] instead (when possible) to refetch an existing query using its DocumentNode, rather than creating, executing, and then deleting a new query, as the legacy { query, variables } style unfortunately does.
  @benjamn in #8586

• Fix useQuery/useLazyQuery stalling when clients or queries change.
  @brainkim in #8589

Apollo Client 3.4.4

Bug Fixes

• Revert accidental addition of engines.npm section to published version of @apollo/client/package.json.
  @benjamn in #8578

Apollo Client 3.4.3

Bug Fixes

• Fix { ssr: false } causing queries to hang on the client.
  @brainkim in #8574

Apollo Client 3.4.2

Bug Fixes

• Use more default type parameters for mutation-related types in react/types/types.ts, to provide smoother backwards compatibility for code using those types explicitly.
  @benjamn in #8573

Apollo Client 3.4.1

Bug Fixes

• Initialize stringifyCanon lazily, when canonicalStringify is first called, fixing Uncaught ReferenceError: __DEV__ is not defined errors due to usage of __DEV__ before declaration.
  @benjamn in #8557

Apollo Client 3.4.0

New documentation

• Refetching queries with client.refetchQueries.
  @StephenBarlow and @benjamn in #8265

Improvements

• InMemoryCache now guarantees that any two result objects returned by the cache (from readQuery, readFragment, etc.) will be referentially equal (===) if they are deeply equal. Previously, === equality was often achievable for results for the same query, on a best-effort basis. Now, equivalent result objects will be automatically shared among the result trees of completely different queries. This guarantee is important for taking full advantage of optimistic updates that correctly guess the final data, and for "pure" UI components that can skip re-rendering when their input data are unchanged.
  @benjamn in #7439

• Mutations now accept an optional callback function called onQueryUpdated, which will be passed the ObservableQuery and Cache.DiffResult objects for any queries invalidated by cache writes performed by the mutation's final update function. Using onQueryUpdated, you can override the default FetchPolicy of the query, by (for example) calling ObservableQuery methods like refetch to force a network request. This automatic detection of invalidated queries provides an alternative to manually enumerating queries using the refetchQueries mutation option. Also, if you return a Promise from onQueryUpdated, the mutation will automatically await that Promise, rendering the awaitRefetchQueries option unnecessary.
  @benjamn in #7827

• Support client.refetchQueries as an imperative way to refetch queries, without having to pass options.refetchQueries to client.mutate.
  @dannycochran in #7431

• Improve standalone client.refetchQueries method to support automatic detection of queries needing to be refetched.
  @benjamn in #8000

• Fix remaining barriers to loading @apollo/client/core as native ECMAScript modules from a CDN like esm.run. Importing @apollo/client from a CDN will become possible once we move all React-related dependencies into @apollo/client/react in Apollo Client 4.
  @benjamn in #8266

• InMemoryCache supports a new method called batch, which is similar to performTransaction but takes named options rather than positional parameters. One of these named options is an onDirty(watch, diff) callback, which can be used to determine which watched queries were invalidated by the batch operation.
  @benjamn in #7819

• Allow merge: true field policy to merge Reference objects with non-normalized objects, and vice-versa.
  @benjamn in #7778

• Allow identical subscriptions to be deduplicated by default, like queries.
  @jkossis in #6910

• Always use POST request when falling back to sending full query with @apollo/client/link/persisted-queries.
  @rieset in #7456

• The FetchMoreQueryOptions type now takes two instead of three type parameters (<TVariables, TData>), thanks to using Partial<TVariables> instead of K extends typeof TVariables and Pick<TVariables, K>.
  @ArnaudBarre in #7476

• Pass variables and context to a mutation's update function. Note: The type of the update function is now named MutationUpdaterFunction rather than MutationUpdaterFn, since the older type was broken beyond repair. If you are using MutationUpdaterFn in your own code, please use MutationUpdaterFunction instead.
  @jcreighton in #7902

• A resultCacheMaxSize option may be passed to the InMemoryCache constructor to limit the number of result objects that will be retained in memory (to speed up repeated reads), and calling cache.reset() now releases all such memory.
  @SofianHn in #8107

• Fully remove result cache entries from LRU dependency system when the corresponding entities are removed from InMemoryCache by eviction, or by any other means.
  @sofianhn and @benjamn in #8147

• Expose missing field errors in results.
  @brainkim in #8262

• Add expected/received variables to No more mocked responses... error messages generated by MockLink.
  @markneub in #8340

• The InMemoryCache version of the cache.gc method now supports additional options for removing non-essential (recomputable) result caching data.
  @benjamn in #8421

• Suppress noisy Missing cache result fields... warnings by default unless setLogVerbosity("debug") called.
  @benjamn in #8489

• Improve interaction between React hooks and React Fast Refresh in development.
  @andreialecu in #7952

Potentially disruptive changes

• To avoid retaining sensitive information from mutation root field arguments, Apollo Client v3.4 automatically clears any ROOT_MUTATION fields from the cache after each mutation finishes. If you need this information to remain in the cache, you can prevent the removal by passing the keepRootFields: true option to client.mutate. ROOT_MUTATION result data are also passed to the mutation update function, so we recommend obtaining the results that way, rather than using keepRootFields: true, if possible.
  @benjamn in #8280

• Internally, Apollo Client now controls the execution of development-only code using the __DEV__ global variable, rather than process.env.NODE_ENV. While this change should not cause any visible differences in behavior, it will increase your minified+gzip bundle size by more than 3.5kB, unless you configure your minifier to replace __DEV__ with a true or false constant, the same way you already replace process.env.NODE_ENV with a string literal like "development" or "production". For an example of configuring a Create React App project without ejecting, see this pull request for our React Apollo reproduction template.
  @benjamn in #8347

• Internally, Apollo Client now uses namespace syntax (e.g. import * as React from "react") for imports whose types are re-exported (and thus may appear in .d.ts files). This change should remove any need to configure esModuleInterop or allowSyntheticDefaultImports in tsconfig.json, but might require updating bundler configurations that specify named exports of the react and prop-types packages, to include exports like createContext and createElement (example).
  @devrelm in #7742

• Respect no-cache fetch policy (by not reading any data from the cache) for loading: true results triggered by notifyOnNetworkStatusChange: true.
  @jcreighton in #7761

• The TypeScript return types of the getLastResult and getLastError methods of ObservableQuery now correctly include the possibility of returning undefined. If you happen to be calling either of these methods directly, you may need to adjust how the calling code handles the methods' possibly-undefined results.
  @benjamn in #8394

• Log non-fatal invariant.error message when fields are missing from result objects written into InMemoryCache, rather than throwing an exception. While this change relaxes an exception to be merely an error message, which is usually a backwards-compatible change, the error messages are logged in more cases now than the exception was previously thrown, and those new error messages may be worth investigating to discover potential problems in your application. The errors are not displayed for @client-only fields, so adding @client is one way to handle/hide the errors for local-only fields. Another general strategy is to use a more precise query to write specific subsets of data into the cache, rather than reusing a larger query that contains fields not present in the written data.
  @benjamn in #8416

• The nextFetchPolicy option for client.watchQuery and useQuery will no longer be removed from the options object after it has been applied, and instead will continue to be applied any time options.fetchPolicy is reset to another value, until/unless the options.nextFetchPolicy property is removed from options.
  @benjamn in #8465

• The fetchMore, subscribeToMore, and updateQuery functions returned from the useQuery hook may now return undefined in edge cases where the functions are called when the component is unmounted
  @noghartt in #7980.

Bug fixes

• In Apollo Client 2.x, a refetch operation would always replace existing data in the cache. With the introduction of field policy merge functions in Apollo Client 3, existing field values could be inappropriately combined with incoming field values by a custom merge function that does not realize a refetch has happened.

  To give you more control over this behavior, we have introduced an overwrite?: boolean = false option for cache.writeQuery and cache.writeFragment, and an option called refetchWritePolicy?: "merge" | "overwrite" for client.watchQuery, useQuery, and other functions that accept WatchQueryOptions. You can use these options to make sure any merge functions involved in cache writes for refetch operations get invoked with undefined as their first argument, which simulates the absence of any existing data, while still giving the merge function a chance to determine the internal representation of the incoming data.

  The default behaviors are overwrite: true and refetchWritePolicy: "overwrite", which restores the Apollo Client 2.x behavior, but (if this change causes any problems for your application) you can easily recover the previous merging behavior by setting a default value for refetchWritePolicy in defaultOptions.watchQuery:

  new ApolloClient({
    defaultOptions: {
      watchQuery: {
        refetchWritePolicy: "merge",
      },
    },
  });

  @benjamn in #7810

• Make sure the MockedResponse ResultFunction type is re-exported.
  @hwillson in #8315

• Fix polling when used with skip.
  @brainkim in #8346

• InMemoryCache now coalesces EntityStore updates to guarantee only one store.merge(id, fields) call per id per cache write.
  @benjamn in #8372

• Fix polling when used with <React.StrictMode>.
  @brainkim in #8414

• Fix the React integration logging Warning: Can't perform a React state update on an unmounted component.
  @wuarmin in #7745

• Make ObservableQuery#getCurrentResult always call queryInfo.getDiff().
  @benjamn in #8422

• Make readField default to reading from current object only when the from option/argument is actually omitted, not when from is passed to readField with an undefined value. A warning will be printed when this situation occurs.
  @benjamn in #8508

• The fetchMore, subscribeToMore, and updateQuery functions no longer throw undefined errors
  @noghartt in #7980.

Apollo Client 3.3.21

Bug fixes

• Fix race condition in @apollo/client/link/context that could leak subscriptions if the subscription is cancelled before operation.setContext is called.
  @sofianhn in #8399

• Prefer existing.pageInfo.startCursor and endCursor (if defined) in read function of relayStylePagination policies.
  @benjamn in #8438

Improvements

• Normalize user-provided HttpLink headers by lower-casing their names.
  @benjamn in #8449

Apollo Client 3.3.20

Bug fixes

• Fix policy merging bug when calling cache.policies.addTypePolicies multiple times for the same type policy.
  @Banou26 in #8361

Apollo Client 3.3.19

Bug fixes

• Use export ... from syntax to re-export graphql-tag named exports, making tree-shaking easier for some bundlers.
  @benjamn in #8221

Documentation

• Replace Spectrum references with community.apollographql.com.
  @hwillson in #8238

Apollo Client 3.3.18

Bug fixes

• Add "sideEffects": false to all generated/published package.json files, to improve dead code elimination for nested entry points like @apollo/client/cache.
  @benjamn in #8213

Apollo Client 3.3.17

Bug fixes

• Make useReactiveVar(rv) recheck the latest rv() value in its useEffect callback, and immediately update state if the value has already changed, rather than calling rv.onNextChange(setValue) to listen for future changes.
  @benjamn in #8135

Apollo Client 3.3.16

Bug fixes

• Prevent undefined mutation result in useMutation.
  @jcreighton in #8018

• Fix useReactiveVar not rerendering for successive synchronous calls.
  @brainkim in #8022

• Support batchDebounce option for BatchLink and BatchHttpLink.
  @dannycochran in #8024

Apollo Client 3.3.15

• Increment queryInfo.lastRequestId only when making a network request through the ApolloLink chain, rather than every time fetchQueryByPolicy is called.
  @dannycochran in #7956

• During server-side rendering, allow initial useQuery calls to return final { loading: false, data } results when the cache already contains the necessary data.
  @benjamn in #7983

Apollo Client 3.3.14

Improvements

• Adjust TypeScript types to allow keyFields and keyArgs functions to return false.
  @CarsonF and @benjamn in #7900

Bug fixes

• Prevent RenderPromises memory leak by calling renderPromises.clear() after getMarkupFromTree finishes.
  @benjamn in #7943

• Cancel pending notify timeout when stopping a QueryInfo object.
  @hollandThomas in #7935

• Fix infinite rendering bug related to useSubscription.
  @brainkim in #7917

Apollo Client 3.3.13

Improvements

• Add missing context option to useSubscription.
  @jcreighton in #7860

• Remove unnecessary TypeScript global Observable<T>["@@observable"] method declaration.
  @benjamn in #7888

• Prevent skipped/observerless ObservableQuerys from being refetched by refetchQueries.
  @dannycochran in #7877

Apollo Client 3.3.12

Bug fixes

• Maintain serial ordering of asyncMap mapping function calls, and prevent potential unhandled Promise rejection errors.
  @benjamn in #7818

• Relax incompatible children?: React.ReactElement field type in MockedProviderProps interface.
  @kevinperaza in #7833

Apollo Client 3.3.11

Bug fixes

• Fix useLazyQuery forceUpdate loop regression introduced by #7655 in version 3.3.10.
  @benjamn in #7715

Apollo Client 3.3.10

Bug fixes

• Revert PR #7276, but test that garbage collection reclaims torn-down ObservableQuery objects.
  @benjamn in #7695

• Reset QueryInfo.diff and QueryInfo.dirty after canceling notify timeout in QueryInfo.markResult and QueryInfo.markError.
  @jcreighton in #7696

Improvements

• Avoid calling forceUpdate when component is unmounted.
  @DylanVann in #7655

• The codemods/ top-level directory has been moved into the scripts/ directory.
  @benjamn in #7675

Apollo Client 3.3.9

Bug Fixes

• Prevent reactive variables from retaining otherwise unreachable InMemoryCache objects.
  @benjamn in #7661

Improvements

• The graphql-tag dependency has been updated to version 2.12.0, after converting its repository to use TypeScript and ECMAScript module syntax. There should be no visible changes in behavior, though the internal changes seemed significant enough to mention here.
  @abdonrd in graphql-tag#273 and @PowerKiKi in graphql-tag#325

Apollo Client 3.3.8

Bug Fixes

• Catch updates in useReactiveVar with an additional check.
  @jcreighton in #7652

• Reactivate forgotten reactive variables whenever InMemoryCache acquires its first watcher.
  @benjamn in #7657

• Backport Symbol.species fix for Concast and ObservableQuery from release-3.4, fixing subscriptions in React Native Android when the Hermes JavaScript engine is enabled (among other benefits).
  @benjamn in #7403 and #7660

Apollo Client 3.3.7

Bug Fixes

• Fix a regression due to #7310 that caused loading always to be true for skip: true results during server-side rendering.
  @rgrove in #7567

• Avoid duplicate useReactiveVar listeners when rendering in React.StrictMode.
  @jcreighton in #7581

Improvements

• Set displayName on ApolloContext objects for easier debugging.
  @dulmandakh in #7550

Apollo Client 3.3.6

Bug Fixes

• Immediately apply queryType: true, mutationType: true, and subscriptionType: true type policies, rather than waiting for the first time the policy is used, fixing a regression introduced by #7065.
  @benjamn in #7463

• Check that window is defined even when connectToDevTools is true.
  @yasupeke in #7434

Improvements

• Replace stray console.debug (undefined in React Native) with invariant.log.
  @benjamn in #7454

• Suggest Firefox Apollo DevTools as well as the Chrome extension.
  @benjamn in #7461

Apollo Client 3.3.5

Improvements

• Restore client.version property, reflecting the current @apollo/client version from package.json.
  @benjamn in #7448

Apollo Client 3.3.4

Improvements

• Update ts-invariant to avoid potential Content Security Policy-violating Function fallback, thanks to a clever new globalThis polyfill technique.
  @benjamn in #7414

Apollo Client 3.3.3

Bug fixes

• Make the observer parameter of ApolloLink#onError optional, fixing an unnecessary breaking change for any code that called onError directly.
  @benjamn in #7407

Apollo Client 3.3.2

⚠️ Note: This version of @apollo/client contains no behavioral changes since version 3.3.1

Documentation

• The Pagination article has been completely rewritten (and split into multiple pages) to cover Apollo Client 3 field policies.
  @benjamn and @StephenBarlow in #7175

• Revamp local state tutorial chapter for Apollo Client 3, including reactive variables.
  @StephenBarlow in apollographql@apollo#1050

• Add examples of using ApolloLink to modify response data asynchronously.
  @alichry in #7332

• Consolidate separate v2.4, v2.5, and v2.6 documentation versions into one v2 version.
  @jgarrow in #7378

Apollo Client 3.3.1

Bug Fixes

• Revert back to default-importing React internally, rather than using a namespace import.
  @benjamn in 113475b1

Apollo Client 3.3.0

Bug Fixes

• Update @wry/equality to consider undefined properties equivalent to missing properties.
  @benjamn in #7108

• Prevent memory leaks involving unused onBroadcast function closure created in ApolloClient constructor.
  @kamilkisiela in #7161

• Provide default empty cache object for root IDs like ROOT_QUERY, to avoid differences in behavior before/after ROOT_QUERY data has been written into InMemoryCache.
  @benjamn in #7100

• Cancel queryInfo.notifyTimeout in QueryInfo#markResult to prevent unnecessary network requests when using a FetchPolicy of cache-and-network or network-only in a React component with multiple useQuery calls.
  @benjamn in #7347

Potentially breaking changes

• Ensure cache.readQuery and cache.readFragment always return TData | null, instead of throwing MissingFieldError exceptions when missing fields are encountered.
  @benjamn in #7098

  Since this change converts prior exceptions to null returns, and since null was already a possible return value according to the TData | null return type, we are confident this change will be backwards compatible (as long as null was properly handled before).

• HttpLink will now automatically strip any unused variables before sending queries to the GraphQL server, since those queries are very likely to fail validation, according to the All Variables Used rule in the GraphQL specification. If you depend on the preservation of unused variables, you can restore the previous behavior by passing includeUnusedVariables: true to the HttpLink constructor (which is typically passed as options.link to the ApolloClient constructor).
  @benjamn in #7127

• Ensure MockLink (used by MockedProvider) returns mock configuration errors (e.g. No more mocked responses for the query ...) through the Link's Observable, instead of throwing them. These errors are now available through the error property of a result.
  @hwillson in #7110

  Returning mock configuration errors through the Link's Observable was the default behavior in Apollo Client 2.x. We changed it for 3, but the change has been problematic for those looking to migrate from 2.x to 3. We've decided to change this back with the understanding that not many people want or are relying on MockLink's throwing exception approach. If you want to change this functionality, you can define custom error handling through MockLink.setOnError.

• Unsubscribing the last observer from an ObservableQuery will once again unsubscribe from the underlying network Observable in all cases, as in Apollo Client 2.x, allowing network requests to be cancelled by unsubscribing.
  @javier-garcia-meteologica in #7165 and #7170.

• The independent QueryBaseOptions and ModifiableWatchQueryOptions interface supertypes have been eliminated, and their fields are now defined by QueryOptions.
  @DCtheTall in #7136

• Internally, Apollo Client now avoids nested imports from the graphql package, importing everything from the top-level package instead. For example,

  import { visit } from "graphql/language/visitor";

  is now just

  import { visit } from "graphql";

  Since the graphql package uses .mjs modules, your bundler may need to be configured to recognize .mjs files as ECMAScript modules rather than CommonJS modules.
  @benjamn in #7185

Improvements

• Support inheritance of type and field policies, according to possibleTypes.
  @benjamn in #7065

• Allow configuring custom merge functions, including the merge: true and merge: false shorthands, in type policies as well as field policies.
  @benjamn in #7070

• The verbosity of Apollo Client console messages can be globally adjusted using the setLogVerbosity function:

  import { setLogVerbosity } from "@apollo/client";
  setLogVerbosity("log"); // display all messages
  setLogVerbosity("warn"); // display only warnings and errors (default)
  setLogVerbosity("error"); // display only errors
  setLogVerbosity("silent"); // hide all console messages

  Remember that all logs, warnings, and errors are hidden in production.
  @benjamn in #7226

• Modifying InMemoryCache fields that have keyArgs configured will now invalidate only the field value with matching key arguments, rather than invalidating all field values that share the same field name. If keyArgs has not been configured, the cache must err on the side of invalidating by field name, as before.
  @benjamn in #7351

• Shallow-merge options.variables when combining existing or default options with newly-provided options, so new variables do not completely overwrite existing variables.
  @amannn in #6927

• Avoid displaying Cache data may be lost... warnings for scalar field values that happen to be objects, such as JSON data.
  @benjamn in #7075

• In addition to the result.data property, useQuery and useLazyQuery will now provide a result.previousData property, which can be useful when a network request is pending and result.data is undefined, since result.previousData can be rendered instead of rendering an empty/loading state.
  @hwillson in #7082

• Passing validate: true to the SchemaLink constructor will enable validation of incoming queries against the local schema before execution, returning validation errors in result.errors, just like a non-local GraphQL endpoint typically would.
  @amannn in #7094

• Allow optional arguments in keyArgs: [...] arrays for InMemoryCache field policies.
  @benjamn in #7109

• Avoid registering QueryPromise when skip is true during server-side rendering.
  @izumin5210 in #7310

• ApolloCache objects (including InMemoryCache) may now be associated with or disassociated from individual reactive variables by calling reactiveVar.attachCache(cache) and/or reactiveVar.forgetCache(cache).
  @benjamn in #7350

Apollo Client 3.2.9

Bug Fixes

• Revert back to default-importing React internally, rather than using a namespace import.
  @benjamn in 113475b1

Apollo Client 3.2.8

Bug Fixes

• Ensure sourcesContent array is properly defined in .js.map files generated by tsc.
  @benjamn in #7371

• Avoid relying on global Symbol properties in ApolloContext.ts.
  @benjamn in #7371

Apollo Client 3.2.7

Bug Fixes

• Revert updating symbol-observable from version 2.x to version 3, which caused TypeScript errors with some @types/node versions, especially in Angular applications.
  @benjamn in #7340

Apollo Client 3.2.6

Bug Fixes

• Always consider singleton IDs like ROOT_QUERY and ROOT_MUTATION to be root IDs during cache.gc garbage collection, regardless of whether they have been retained or released.
  @benjamn in #7333

• Use optional chaining syntax (this.currentObservable?.refetch) in React refetch wrapper function to avoid crashing when an unmounted component is accidentally refetched.
  @tm1000 in #6314 and @linmic in #7186

Improvements

• Handle older react-apollo package in codemods/ac2-to-ac3/imports.js migration script.
  @tm1000 in #7216

• Ensure relayStylePagination preserves pageInfo.{start,end}Cursor if edges is missing or empty.
  @beaucollins in #7224

Apollo Client 3.2.5

Improvements

• Move terser dependency from dependencies to devDependencies.
  @SimenB in #7188

• Avoid all sub-package imports from the graphql npm package.
  @stoically in #7185

Apollo Client 3.2.4

Improvements

• Update the optimism npm dependency to version 0.13.0 in order to use the new optimistic.forget method to fix a potential cache.watch memory leak.
  @benjamn in #7157

• Consider cache.reset a destructive method, like cache.evict and cache.modify.
  @joshjg in #7150

• Avoid refetching observerless queries with reFetchObservableQueries.
  @joshjg in #7146

Apollo Client 3.2.3

Improvements

• Default args.offset to zero in offsetLimitPagination.
  @benjamn in #7141

Apollo Client 3.2.2

Bug Fixes

• Undo TEdgeWrapper approach for relayStylePagination, introduced by f41e9efc in #7023, since it was an unintended breaking change for existing code that used cache.modify to interact with field data managed by relayStylePagination.
  @benjamn in #7103

Apollo Client 3.2.1

Bug Fixes

• Fix relayStylePagination to handle the possibility that edges might be normalized Reference objects (uncommon).
  @anark and @benjamn in #7023

• Disable "Missing cache result fields" warnings when returnPartialData is true.
  @hwillson in #7055

Improvements

• Mark subscriptions-transport-ws peerDependency as optional.
  @MasterOdin in #7047

Apollo Client 3.2.0

Bug Fixes

• Use options.nextFetchPolicy internally to restore original FetchPolicy after polling with fetchPolicy: "network-only", so that polling does not interfere with normal query watching.
  @benjamn in #6893

• Initialize ObservableQuery in updateObservableQuery even if skip is true.
  @mu29 in #6999

• Prevent full reobservation of queries affected by optimistic mutation updates, while still delivering results from the cache.
  @benjamn in #6854

Improvements

• In TypeScript, all APIs that take DocumentNode parameters now may alternatively take TypeDocumentNode<Data, Variables>. This type has the same JavaScript representation but allows the APIs to infer the data and variable types instead of requiring you to specify types explicitly at the call site.
  @dotansimha in #6720

• Bring back an improved form of heuristic fragment matching, by allowing possibleTypes to specify subtype regular expression strings, which count as matches if the written result object has all the fields expected for the fragment.
  @benjamn in #6901

• Allow options.nextFetchPolicy to be a function that takes the current FetchPolicy and returns a new (or the same) FetchPolicy, making nextFetchPolicy more suitable for global use in defaultOptions.watchQuery.
  @benjamn in #6893

• Implement useReactiveVar hook for consuming reactive variables in React components.
  @benjamn in #6867

• Move apollo-link-persisted-queries implementation to @apollo/client/link/persisted-queries. Try running our automated imports transform to handle this conversion, if you're using apollo-link-persisted-queries.
  @hwillson in #6837

• Disable feud-stopping logic after any cache.evict or cache.modify operation.
  @benjamn in #6817 and #6898

• Throw if writeFragment cannot identify options.data when no options.id provided.
  @jcreighton in #6859

• Provide options.storage object to cache.modify functions, as provided to read and merge functions.
  @benjamn in #6991

• Allow cache.modify functions to return details.INVALIDATE (similar to details.DELETE) to invalidate the current field, causing affected queries to rerun, even if the field's value is unchanged.
  @benjamn in #6991

• Support non-default ErrorPolicy values (that is, "ignore" and "all", in addition to the default value "none") for mutations and subscriptions, like we do for queries.
  @benjamn in #7003

• Remove invariant forbidding a FetchPolicy of cache-only in ObservableQuery#refetch.
  @benjamn in ccb0a79a, fixing #6702

Apollo Client 3.1.5

Bug Fixes

• Make ApolloQueryResult.data field non-optional again.
  @benjamn in #6997

Improvements

• Allow querying Connection metadata without args in relayStylePagination.
  @anark in #6935

Apollo Client 3.1.4

Bug Fixes

• Restrict root object identification to ROOT_QUERY (the ID corresponding to the root Query object), allowing Mutation and Subscription as user-defined types.
  @benjamn in #6914

• Prevent crash when pageInfo and empty edges are received by relayStylePagination.
  @fracmak in #6918

Apollo Client 3.1.3

Bug Fixes

• Consider only result.data (rather than all properties of result) when settling cache feuds.
  @danReynolds in #6777

Improvements

• Provide jscodeshift transform for automatically converting Apollo Client 2.x import declarations to use Apollo Client 3.x packages. Instructions.
  @dminkovsky and @jcreighton in #6486

Apollo Client 3.1.2

Bug Fixes

• Avoid making network requests when skip is true.
  @hwillson in #6752

Improvements

• Allow SchemaLink.Options.context function to be async (or return a Promise).
  @benjamn in #6735

Apollo Client 3.1.1

Bug Fixes

• Re-export cache types from @apollo/client/core (and thus also @apollo/client), again.
  @benjamn in #6725

Apollo Client 3.1.0

Bug Fixes

• Rework interdependencies between @apollo/client/* entry points, so that CommonJS and ESM modules are supported equally well, without any duplication of shared code.
  @benjamn in #6656 and #6657

• Tolerate !== callback functions (like onCompleted and onError) in useQuery options, since those functions are almost always freshly evaluated each time useQuery is called.
  @hwillson and @benjamn in #6588

• Respect context.queryDeduplication if provided, and otherwise fall back to client.deduplication (as before).
  @igaloly in #6261 and @Kujawadl in #6526

• Refactor ObservableQuery#getCurrentResult to reenable immediate delivery of warm cache results. As part of this refactoring, the ApolloCurrentQueryResult type was eliminated in favor of ApolloQueryResult.
  @benjamn in #6710

• Avoid clobbering defaultOptions with undefined values.
  @benjamn in #6715

Improvements

• Apollo Client will no longer modify options.fetchPolicy unless you pass options.nextFetchPolicy to request an explicit change in FetchPolicy after the current request. Although this is technically a breaking change, options.nextFieldPolicy makes it easy to restore the old behavior (by passing cache-first).
  @benjamn in #6712, reverting #6353

• Errors of the form Invariant Violation: 42 thrown in production can now be looked up much more easily, by consulting the auto-generated @apollo/client/invariantErrorCodes.js file specific to your @apollo/client version.
  @benjamn in #6665

• Make the client field of the MutationResult type non-optional, since it is always provided.
  @glasser in #6617

• Allow passing an asynchronous options.renderFunction to getMarkupFromTree.
  @richardscarrott in #6576

• Ergonomic improvements for merge and keyArgs functions in cache field policies.
  @benjamn in #6714

Apollo Client 3.0.2

Bug Fixes

• Avoid duplicating graphql/execution/execute dependency in CommonJS bundle for @apollo/client/link/schema, fixing instanceof errors reported in #6621 and #6614.
  @benjamn in #6624

Apollo Client 3.0.1

Bug Fixes

• Make sure useQuery onCompleted is not fired when skip is true.
  @hwillson in #6589

• Revert changes to peerDependencies in package.json (#6594), which would have allowed using incompatible future versions of graphql and/or react due to overly-permissive >= version constraints.
  @hwillson in #6605

Apollo Client 3.0.0

Improvements

⚠️ Note: As of 3.0.0, Apollo Client uses a new package name: @apollo/client

ApolloClient

• [BREAKING] ApolloClient is now only available as a named export. The default ApolloClient export has been removed.
  @hwillson in #5425

• [BREAKING] The queryManager property of ApolloClient instances is now marked as private, paving the way for a more aggressive redesign of its API.

• [BREAKING] Apollo Client will no longer deliver "stale" results to ObservableQuery consumers, but will instead log more helpful errors about which cache fields were missing.
  @benjamn in #6058

• [BREAKING] ApolloError's thrown by Apollo Client no longer prefix error messages with GraphQL error: or Network error:. To differentiate between GraphQL/network errors, refer to ApolloError's public graphQLErrors and networkError properties.
  @lorensr in #3892

• [BREAKING] Support for the @live directive has been removed, but might be restored in the future if a more thorough implementation is proposed.
  @benjamn in #6221

• [BREAKING] Apollo Client 2.x allowed @client fields to be passed into the link chain if resolvers were not set in the constructor. This allowed @client fields to be passed into Links like apollo-link-state. Apollo Client 3 enforces that @client fields are local only, meaning they are no longer passed into the link chain, under any circumstances.
  @hwillson in #5982

• [BREAKING?] Refactor QueryManager to make better use of observables and enforce fetchPolicy more reliably.
  @benjamn in #6221

• The updateQuery function previously required by fetchMore has been deprecated with a warning, and will be removed in the next major version of Apollo Client. Please consider using a merge function to handle incoming data instead of relying on updateQuery.
  @benjamn in #6464

  • Helper functions for generating common pagination-related field policies may be imported from @apollo/client/utilities. The most basic helper is concatPagination, which emulates the concatenation behavior of typical updateQuery functions. A more sophisticated helper is offsetLimitPagination, which implements offset/limit-based pagination. If you are consuming paginated data from a Relay-friendly API, use relayStylePagination. Feel free to use these helper functions as inspiration for your own field policies, and/or modify them to suit your needs.
    @benjamn in #6465

• Updated to work with graphql@15.
  @durchanek in #6194 and #6279
  @hagmic in #6328

• Apollo Link core and HTTP related functionality has been merged into @apollo/client. Functionality that was previously available through the apollo-link, apollo-link-http-common and apollo-link-http packages is now directly available from @apollo/client (e.g. import { HttpLink } from '@apollo/client'). The ApolloClient constructor has also been updated to accept new uri, headers and credentials options. If uri is specified, Apollo Client will take care of creating the necessary HttpLink behind the scenes.
  @hwillson in #5412

• The gql template tag should now be imported from the @apollo/client package, rather than the graphql-tag package. Although the graphql-tag package still works for now, future versions of @apollo/client may change the implementation details of gql without a major version bump.
  @hwillson in #5451

• @apollo/client/core can be used to import the Apollo Client core, which includes everything the main @apollo/client package does, except for all React related functionality.
  @kamilkisiela in #5541

• Several deprecated methods have been fully removed:

  • ApolloClient#initQueryManager
  • QueryManager#startQuery
  • ObservableQuery#currentResult

• Apollo Client now supports setting a new ApolloLink (or link chain) after new ApolloClient() has been called, using the ApolloClient#setLink method.
  @hwillson in #6193

• The final time a mutation update function is called, it can no longer accidentally read optimistic data from other concurrent mutations, which ensures the use of optimistic updates has no lasting impact on the state of the cache after mutations have finished.
  @benjamn in #6551

• Apollo links that were previously maintained in https://github.com/apollographql/apollo-link have been merged into the Apollo Client project. They should be accessed using the new entry points listed in the migration guide.
  @hwillson in #

InMemoryCache

⚠️ Note: InMemoryCache has been significantly redesigned and rewritten in Apollo Client 3.0. Please consult the migration guide and read the new documentation to understand everything that has been improved.

• The InMemoryCache constructor should now be imported directly from @apollo/client, rather than from a separate package. The apollo-cache-inmemory package is no longer supported.

  The @apollo/client/cache entry point can be used to import InMemoryCache without importing other parts of the Apollo Client codebase.
  > @hwillson in #5577

• [BREAKING] FragmentMatcher, HeuristicFragmentMatcher, and IntrospectionFragmentMatcher have all been removed. We now recommend using InMemoryCache’s possibleTypes option instead. For more information see the Defining possibleTypes manually section of the docs.
  @benjamn in #5073

• [BREAKING] As promised in the Apollo Client 2.6 blog post, all cache results are now frozen/immutable.
  @benjamn in #5153

• [BREAKING] Eliminate "generated" cache IDs to avoid normalizing objects with no meaningful ID, significantly reducing cache memory usage. This might be a backwards-incompatible change if your code depends on the precise internal representation of normalized data in the cache.
  @benjamn in #5146

• [BREAKING] InMemoryCache will no longer merge the fields of written objects unless the objects are known to have the same identity, and the values of fields with the same name will not be recursively merged unless a custom merge function is defined by a field policy for that field, within a type policy associated with the __typename of the parent object.
  @benjamn in #5603

• [BREAKING] InMemoryCache now throws when data with missing or undefined query fields is written into the cache, rather than just warning in development.
  @benjamn in #6055

• [BREAKING] client|cache.writeData have been fully removed. writeData usage is one of the easiest ways to turn faulty assumptions about how the cache represents data internally, into cache inconsistency and corruption. client|cache.writeQuery, client|cache.writeFragment, and/or cache.modify can be used to update the cache.
  @benjamn in #5923

• InMemoryCache now supports tracing garbage collection and eviction. Note that the signature of the evict method has been simplified in a potentially backwards-incompatible way.
  @benjamn in #5310

  • [beta-BREAKING] Please note that the cache.evict method now requires Cache.EvictOptions, though it previously supported positional arguments as well.
    @danReynolds in #6141 @benjamn in #6364

  • Removing an entity object using the cache.evict method does not automatically remove dangling references to that entity elsewhere in the cache, but dangling references will be automatically filtered from lists whenever those lists are read from the cache. You can define a custom field read function to customize this behavior. See #6412, #6425, and #6454 for further explanation.

• Cache methods that would normally trigger a broadcast, like cache.evict, cache.writeQuery, and cache.writeFragment, can now be called with a named options object, which supports a broadcast: boolean property that can be used to silence the broadcast, for situations where you want to update the cache multiple times without triggering a broadcast each time.
  @benjamn in #6288

• InMemoryCache now console.warns in development whenever non-normalized data is dangerously overwritten, with helpful links to documentation about normalization and custom merge functions.
  @benjamn in #6372

• The result caching system (introduced in #3394) now tracks dependencies at the field level, rather than at the level of whole entity objects, allowing the cache to return identical (===) results much more often than before.
  @benjamn in #5617

• InMemoryCache now has a method called modify which can be used to update the value of a specific field within a specific entity object:

  cache.modify({
    id: cache.identify(post),
    fields: {
      comments(comments: Reference[], { readField }) {
        return comments.filter(
          (comment) => idToRemove !== readField("id", comment)
        );
      },
    },
  });

  This API gracefully handles cases where multiple field values are associated with a single field name, and also removes the need for updating the cache by reading a query or fragment, modifying the result, and writing the modified result back into the cache. Behind the scenes, the cache.evict method is now implemented in terms of cache.modify.
  @benjamn in #5909 and #6178

• InMemoryCache provides a new API for storing client state that can be updated from anywhere:

  import { makeVar } from "@apollo/client";
  const v = makeVar(123);
  console.log(v()); // 123
  console.log(v(v() + 1)); // 124
  console.log(v()); // 124
  v("asdf"); // TS type error

  These variables are reactive in the sense that updating their values invalidates any previously cached query results that depended on the old values.
  @benjamn in #5799, #5976, and #6512

• Various cache read and write performance optimizations, cutting read and write times by more than 50% in larger benchmarks.
  @benjamn in #5948

• The cache.readQuery and cache.writeQuery methods now accept an options.id string, which eliminates most use cases for cache.readFragment and cache.writeFragment, and skips the implicit conversion of fragment documents to query documents performed by cache.{read,write}Fragment.
  @benjamn in #5930

• Support cache.identify(entity) for easily computing entity ID strings.
  @benjamn in #5642

• Support eviction of specific entity fields using cache.evict(id, fieldName).
  @benjamn in #5643

• Make InMemoryCache#evict remove data from all EntityStore layers.
  @benjamn in #5773

• Stop paying attention to previousResult in InMemoryCache.
  @benjamn in #5644

• Improve optimistic update performance by limiting cache key diversity.
  @benjamn in #5648

• Custom field read functions can read from neighboring fields using the readField(fieldName) helper, and may also read fields from other entities by calling readField(fieldName, objectOrReference).
  @benjamn in #5651

• Expose cache modify and identify to the mutate update function.
  @hwillson in #5956

• Add a default gc implementation to ApolloCache.
  @justinwaite in #5974

React

• [BREAKING] The QueryOptions, MutationOptions, and SubscriptionOptions React Apollo interfaces have been renamed to QueryDataOptions, MutationDataOptions, and SubscriptionDataOptions (to avoid conflicting with similarly named and exported Apollo Client interfaces).

• [BREAKING] Results with loading: true will no longer redeliver previous data, though they may provide partial data from the cache, when available.
  @benjamn in #6566

• [BREAKING?] Remove fixPolyfills.ts, except when bundling for React Native. If you have trouble with Map or Set operations due to frozen key objects in React Native, either update React Native to version 0.59.0 (or 0.61.x, if possible) or investigate why fixPolyfills.native.js is not included in your bundle.
  @benjamn in #5962

• The contents of the @apollo/react-hooks package have been merged into @apollo/client, enabling the following all-in-one import:

  import { ApolloClient, ApolloProvider, useQuery } from "@apollo/client";

  @hwillson in #5357

• React SSR features (previously accessed via @apollo/react-ssr) can now be accessed from the separate Apollo Client entry point of @apollo/client/react/ssr. These features are not included in the default @apollo/client bundle.
  @hwillson in #6499

General

• [BREAKING] Removed graphql-anywhere since it's no longer used by Apollo Client.
  @hwillson in #5159

• [BREAKING] Removed apollo-boost since Apollo Client 3.0 provides a boost like getting started experience out of the box.
  @hwillson in #5217

• [BREAKING] We are no longer exporting certain (intended to be) internal utilities. If you are depending on some of the lesser known exports from apollo-cache, apollo-cache-inmemory, or apollo-utilities, they may no longer be available from @apollo/client.
  @hwillson in #5437 and #5514

  Utilities that were previously externally available through the apollo-utilities package are now only available by importing from @apollo/client/utilities.
  > @hwillson in #5683

• Make sure all graphql-tag public exports are re-exported.
  @hwillson in #5861

• Fully removed prettier. The Apollo Client team has decided to no longer automatically enforce code formatting across the codebase. In most cases existing code styles should be followed as much as possible, but this is not a hard and fast rule.
  @hwillson in #5227

• Make sure ApolloContext plays nicely with IE11 when storing the shared context.
  @ms in #5840

• Migrated React Apollo HOC and Components functionality into Apollo Client, making it accessible from @apollo/client/react/components and @apollo/client/react/hoc entry points.
  @hwillson in #6558

• Support passing a context object through the link execution chain when using subscriptions.
  @sgtpepper43 in #4925

• MockSubscriptionLink now supports multiple subscriptions.
  @dfrankland in #6081

Bug Fixes

• useMutation adjustments to help avoid an infinite loop / too many renders issue, caused by unintentionally modifying the useState based mutation result directly.
  @hwillson in #5770

• Missing __typename fields no longer cause the InMemoryCache#diff result to be marked complete: false, if those fields were added by InMemoryCache#transformDocument (which calls addTypenameToDocument).
  @benjamn in #5787

• Fixed an issue that allowed @client @export based queries to lead to extra unnecessary network requests being fired.
  @hwillson in #5946

• Refined useLazyQuery types to help prevent runtime errors.
  @benmosher in #5935

• Make sure @client @export variables used in watched queries are updated each time the query receives new data that changes the value of the @export variable.
  @hwillson in #5986

• Ensure useMutation passes a defined errorPolicy option into its underlying ApolloClient.mutate() call.
  @jamesreggio in #5863

• useQuery: Prevent new data re-render attempts during an existing render. This helps avoid React 16.13.0's "Cannot update a component from inside the function body of a different component" warning (https://github.com/facebook/react/pull/17099).
  @hwillson in #6107

• Expand ApolloError typings to include ServerError and ServerParseError.
  @dmarkow in #6319

• Fast responses received over the link chain will no longer conflict with skip settings.
  @hwillson in #6587

Apollo Client 2.6.8

Apollo Client (2.6.8)

• Update the fetchMore type signature to accept context.
  @koenpunt in #5147

• Fix type for Resolver and use it in the definition of Resolvers.
  @peoplenarthax in #4943

• Local state resolver functions now receive a fragmentMap: FragmentMap object, in addition to the field: FieldNode object, via the info parameter.
  @mjlyons in #5388

• Documentation updates.
  @tomquirk in #5645
  @Sequoia in #5641
  @phryneas in #5628
  @AryanJ-NYC in #5560

GraphQL Anywhere (4.2.6)

• Fix filter edge case involving null.
  @lifeiscontent in #5110

Apollo Boost (0.4.7)

• Replace GlobalFetch reference with WindowOrWorkerGlobalScope.
  @abdonrd in #5373

• Add assumeImmutableResults typing to apollo boost PresetConfig interface.
  @bencoullie in #5571

Apollo Client (2.6.4)

Apollo Client (2.6.4)

• Modify ObservableQuery to allow queries with notifyOnNetworkStatusChange to be notified when loading after an error occurs.
  @jasonpaulos in #4992

• Add graphql as a peerDependency of apollo-cache and graphql-anywhere.
  @ssalbdivad in #5081

• Documentation updates.
  @raibima in #5132
  @hwillson in #5141

Apollo Client (2.6.3)

Apollo Client (2.6.3)

• A new ObservableQuery.resetQueryStoreErrors() method is now available that can be used to clear out ObservableQuery query store errors.
  @hwillson in #4941
• Documentation updates.
  @michael-watson in #4940
  @hwillson in #4969

Apollo Client (2.6.1)

Apollo Utilities 1.3.2

• Reimplement isEqual without pulling in massive lodash.isequal.
  @benjamn in #4924

Apollo Client (2.6.1)

• In all Apollo Client packages, the compilation of lib/bundle.esm.js to lib/bundle.cjs.js and lib/bundle.umd.js now uses Babel instead of Rollup, since Babel correctly compiles some edge cases that neither Rollup nor TypeScript compile correctly.
  @benjamn in #4911

Apollo Cache In-Memory 1.6.1

• Pretend that __typename exists on the root Query when matching fragments.
  @benjamn in #4853

Apollo Utilities 1.3.1

• The isEqual function has been reimplemented using the lodash.isequal npm package, to better support circular references. Since the lodash.isequal package is already used by react-apollo, this change is likely to decrease total bundle size.
  @capaj in #4915

Apollo Client (2.6.0)

• In production, invariant(condition, message) failures will now include a unique error code that can be used to trace the error back to the point of failure.
  @benjamn in #4521

Apollo Client 2.6.0

• If you can be sure your application code does not modify cache result objects (see freezeResults note below), you can unlock substantial performance improvements by communicating this assumption via

  new ApolloClient({ assumeImmutableResults: true });

  which allows the client to avoid taking defensive snapshots of past results using cloneDeep, as explained by @benjamn in #4543.

• Identical overlapping queries are now deduplicated internally by apollo-client, rather than using the apollo-link-dedup package.
  @benjamn in commit 7cd8479f

• The FetchPolicy type has been split into two types, so that passing cache-and-network to ApolloClient#query is now forbidden at the type level, whereas previously it was forbidden by a runtime invariant assertion:

  export type FetchPolicy =
    | "cache-first"
    | "network-only"
    | "cache-only"
    | "no-cache"
    | "standby";
  
  export type WatchQueryFetchPolicy = FetchPolicy | "cache-and-network";

  The exception thrown if you ignore the type error has also been improved to explain the motivation behind this restriction.
  Issue #3130 (comment) and commit cf069bc7

• Avoid updating (and later invalidating) cache watches when fetchPolicy is 'no-cache'.
  @bradleyayers in PR #4573, part of issue #3452

• Remove temporary queryId after fetchMore completes.
  @doomsower in #4440

• Call clearStore callbacks after clearing store.
  @ds8k in #4695

• Perform all DocumentNode transforms once, and cache the results.
  @benjamn in #4601

• Accommodate @client @export variable changes in ObservableQuery.
  @hwillson in #4604

• Support the returnPartialData option for watched queries again.
  @benjamn in #4743

• Preserve networkStatus for incomplete cache-and-network queries.
  @benjamn in #4765

• Preserve cache-and-network fetchPolicy when refetching.
  @benjamn in #4840

• Update the React Native docs to remove the request for external example apps that we can link to. We're no longer going to manage a list of external example apps.
  @hwillson in #4531

• Polling queries are no longer batched together, so their scheduling should be more predictable.
  @benjamn in #4800

Apollo Cache In-Memory 1.6.0

• Support new InMemoryCache({ freezeResults: true }) to help enforce immutability.
  @benjamn in #4514

• Allow IntrospectionFragmentMatcher to match fragments against the root Query, as HeuristicFragmentMatcher does.
  @rynobax in #4620

• Rerential identity (===) of arrays in cache results will now be preserved for unchanged data.
  @benjamn in commit f3091d6a

• Avoid adding __typename field to @client selection sets that have been @exported as input variables.
  @benjamn in #4784

GraphQL Anywhere 4.2.2

• The graphql function can now be configured to ignore @include and @skip directives (useful when walking a fragment to generate prop types or filter result data).
  @GreenGremlin in #4373

Apollo Client 2.5.1

apollo-client 2.5.1

• Fixes A tuple type element list cannot be empty issue.
  @benjamn in #4502

graphql-anywhere 4.2.1

• Adds back the missing graphql-anywhere/lib/async entry point.
  @benjamn in #4503

Apollo Client (2.5.0)