@apollo/client 4.2.0-alpha.0 → 4.2.0-alpha.2

package/CHANGELOG.md

@@ -1,11 +1,181 @@
 # @apollo/client
 
+## 4.2.0-alpha.2
+
+### Minor Changes
+
+- [#13132](https://github.com/apollographql/apollo-client/pull/13132) [`f3ce805`](https://github.com/apollographql/apollo-client/commit/f3ce805425d10a9666218a8e109288a2d46dcab1) Thanks [@phryneas](https://github.com/phryneas)! - Introduce "classic" and "modern" method and hook signatures.
+
+  Apollo Client 4.2 introduces two signature styles for methods and hooks. All signatures previously present are now "classic" signatures, and a new set of "modern" signatures are added alongside them.
+
+  **Classic signatures** are the default and are identical to the signatures before Apollo Client 4.2, preserving backward compatibility. Classic signatures still work with manually specified TypeScript generics (e.g., `useSuspenseQuery<MyData>(...)`). However, manually specifying generics has been discouraged for a long time—instead, we recommend using `TypedDocumentNode` to automatically infer types, which provides more accurate results without any manual annotations.
+
+  **Modern signatures** automatically incorporate your declared `defaultOptions` into return types, providing more accurate types. Modern signatures infer types from the document node and do not support manually passing generic type arguments; TypeScript will produce a type error if you attempt to do so.
+
+  Methods and hooks automatically switch to modern signatures the moment any non-optional property is declared in `DeclareDefaultOptions`. The switch happens across all methods and hooks globally:
+
+  ```ts
+  // apollo.d.ts
+  import "@apollo/client";
+  declare module "@apollo/client" {
+    namespace ApolloClient {
+      namespace DeclareDefaultOptions {
+        interface WatchQuery {
+          errorPolicy: "all"; // non-optional → modern signatures activated automatically
+        }
+      }
+    }
+  }
+  ```
+
+  Users can also manually switch to modern signatures without declaring any `defaultOptions`, for example when wanting accurate type inference without relying on global `defaultOptions`:
+
+  ```ts
+  // apollo.d.ts
+  import "@apollo/client";
+  declare module "@apollo/client" {
+    export interface TypeOverrides {
+      signatureStyle: "modern";
+    }
+  }
+  ```
+
+  Users can do a global `DeclareDefaultOptions` type augmentation and then manually switch back to "classic" for migration purposes:
+
+  ```ts
+  // apollo.d.ts
+  import "@apollo/client";
+  declare module "@apollo/client" {
+    export interface TypeOverrides {
+      signatureStyle: "classic";
+    }
+  }
+  ```
+
+  Note that this is **not recommended for long-term use**. When combined with `DeclareDefaultOptions`, switching back to classic results in the same incorrect types as before Apollo Client 4.2—methods and hooks will not reflect the `defaultOptions` you've declared.
+
+- [#13132](https://github.com/apollographql/apollo-client/pull/13132) [`f3ce805`](https://github.com/apollographql/apollo-client/commit/f3ce805425d10a9666218a8e109288a2d46dcab1) Thanks [@phryneas](https://github.com/phryneas)! - Synchronize method and hook return types with `defaultOptions`.
+
+  Prior to this change, the following code snippet would always apply:
+
+  ```ts
+  declare const MY_QUERY: TypedDocumentNode<TData, TVariables>;
+  const result1 = useSuspenseQuery(MY_QUERY);
+  result1.data;
+  //      ^? TData
+  const result2 = useSuspenseQuery(MY_QUERY, { errorPolicy: "all" });
+  result2.data;
+  //      ^? TData | undefined
+  ```
+
+  While these types are generally correct, if you were to set `errorPolicy: 'all'` as a default option, the type of `result.data` for the first query would remain `TData` instead of changing to `TData | undefined` to match the runtime behavior.
+
+  We are now enforcing that certain `defaultOptions` types need to be registered globally. This means that if you want to use `errorPolicy: 'all'` as a default option for a query, you will need to register its type like this:
+
+  ```ts
+  // apollo.d.ts
+  import "@apollo/client";
+
+  declare module "@apollo/client" {
+    namespace ApolloClient {
+      namespace DeclareDefaultOptions {
+        interface WatchQuery {
+          // possible global-registered values:
+          // * `errorPolicy`
+          // * `returnPartialData`
+          errorPolicy: "all";
+        }
+        interface Query {
+          // possible global-registered values:
+          // * `errorPolicy`
+        }
+        interface Mutate {
+          // possible global-registered values:
+          // * `errorPolicy`
+        }
+      }
+    }
+  }
+  ```
+
+  Once this type declaration is in place, the type of `result.data` in the above example will correctly be changed to `TData | undefined`, reflecting the possibility that if an error occurs, `data` might be `undefined`. Manually specifying `useSuspenseQuery(MY_QUERY, { errorPolicy: "none" });` changes `result.data` to `TData` to reflect the local override.
+
+  This change means that you will need to declare your default options types in order to use `defaultOptions` with `ApolloClient`, otherwise you will see a TypeScript error.
+
+  Without the type declaration, the following (previously valid) code will now error:
+
+  ```ts
+  new ApolloClient({
+    link: ApolloLink.empty(),
+    cache: new InMemoryCache(),
+    defaultOptions: {
+      watchQuery: {
+        // results in a type error:
+        // Type '"all"' is not assignable to type '"A default option for watchQuery.errorPolicy must be declared in ApolloClient.DeclareDefaultOptions before usage. See https://www.apollographql.com/docs/react/data/typescript#declaring-default-options-for-type-safety."'.
+        errorPolicy: "all",
+      },
+    },
+  });
+  ```
+
+  If you are creating multiple instances of Apollo Client with conflicting default options and you cannot register a single `defaultOptions` value as a result, you can relax the constraints by declaring those options as union types covering all values used by all clients. The properties can be required (to enforce them in `defaultOptions`) or optional (if some constructor calls won't pass a value):
+
+  ```ts
+  // apollo.d.ts
+  import "@apollo/client";
+
+  declare module "@apollo/client" {
+    export namespace ApolloClient {
+      export namespace DeclareDefaultOptions {
+        interface WatchQuery {
+          errorPolicy?: "none" | "all" | "ignore";
+          returnPartialData?: boolean;
+        }
+        interface Query {
+          errorPolicy?: "none" | "all" | "ignore";
+        }
+        interface Mutate {
+          errorPolicy?: "none" | "all" | "ignore";
+        }
+      }
+    }
+  }
+  ```
+
+  With this declaration, the `ApolloClient` constructor accepts any of those values in `defaultOptions`. The tradeoff is that hook and method return types become more generic. For example, calling `useSuspenseQuery` without an explicit `errorPolicy` will return a result typed as if all error policies are possible, since TypeScript can't know which specific value your instance uses at runtime.
+
+  Note that making a property optional (`errorPolicy?:`) is equivalent to adding the TypeScript default value (`"none"`) to the union. So `errorPolicy?: "all" | "ignore"` has the same effect on return types as `errorPolicy: "none" | "all" | "ignore"`, because TypeScript assumes the option could also be absent (i.e., `"none"`).
+
+  You can also use a **partial union** that only lists the values you actually use. For example, if you only ever use `"all"` or `"ignore"`, declare `errorPolicy: "all" | "ignore"` (required) to keep the union narrow and avoid unused values broadening your signatures unnecessarily.
+
+## 4.2.0-alpha.1
+
+### Patch Changes
+
+- [#13166](https://github.com/apollographql/apollo-client/pull/13166) [`0537d97`](https://github.com/apollographql/apollo-client/commit/0537d97161a51479141a182d869458912e1b8e1d) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Release changes in 4.1.5 and 4.1.6.
+
 ## 4.2.0-alpha.0
 
 ### Minor Changes
 
 - [#13130](https://github.com/apollographql/apollo-client/pull/13130) [`dd12231`](https://github.com/apollographql/apollo-client/commit/dd122316028b55307de4a40335512307c8fa916a) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Improve the accuracy of `client.query` return type to better detect the current `errorPolicy`. The `data` property is no longer nullable when the `errorPolicy` is `none`. This makes it possible to remove the `undefined` checks or optional chaining in most cases.
 
+## 4.1.6
+
+### Patch Changes
+
+- [#13128](https://github.com/apollographql/apollo-client/pull/13128) [`6c0b8e4`](https://github.com/apollographql/apollo-client/commit/6c0b8e4301609b62ed599340589c978e4f51f020) Thanks [@pavelivanov](https://github.com/pavelivanov)! - Fix `useQuery` hydration mismatch when `ssr: false` and `skip: true` are used together
+
+  When both options were combined, the server would return `loading: false` (because `useSSRQuery` checks `skip` first), but the client's `getServerSnapshot` was returning `ssrDisabledResult` with `loading: true`, causing a hydration mismatch.
+
+## 4.1.5
+
+### Patch Changes
+
+- [#13155](https://github.com/apollographql/apollo-client/pull/13155) [`3ba1583`](https://github.com/apollographql/apollo-client/commit/3ba1583f93c40343501acd9d598ce506537d1c9b) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Fix an issue where `useQuery` would poll with `pollInterval` when `skip` was initialized to `true`.
+
+- [#13135](https://github.com/apollographql/apollo-client/pull/13135) [`fd42142`](https://github.com/apollographql/apollo-client/commit/fd42142495d24859a9bc7145a85bc8f8d857ec88) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Fix issue where `client.query` would apply options from `defaultOptions.watchQuery`.
+
 ## 4.1.4
 
 ### Patch Changes

package/__cjs/core/ApolloClient.cjs

@@ -84,7 +84,11 @@ class ApolloClient {
         this.link = link;
         this.cache = cache;
         this.queryDeduplication = queryDeduplication;
-        this.defaultOptions = defaultOptions || {};
+        // `DefaultOptions.Input` and `DefaultOptions` are inherently incompatible,
+        // as the `.Input` type restricts certain values from being passed in if not
+        // configured globally.
+        // Without those, it's compatible though so it is fine to cast.
+        this.defaultOptions = (defaultOptions || {});
         this.devtoolsConfig = {
             ...devtools,
             enabled: devtools?.enabled ?? environment_1.__DEV__,
@@ -225,7 +229,16 @@ class ApolloClient {
         }
         return this.queryManager.watchQuery(options);
     }
-    query(options) {
+    /**
+    * This resolves a single query according to the options specified and
+    * returns a `Promise` which is either resolved with the resulting data
+    * or rejected with an error.
+    * 
+    * @param options - An object of type `QueryOptions` that allows us to
+    * describe how this query should be treated e.g. whether it should hit the
+    * server at all or just resolve from the cache, etc.
+    */
+    query = (options) => {
         if (this.defaultOptions.query) {
             options = (0, internal_1.mergeOptions)(this.defaultOptions.query, options);
         }
@@ -239,7 +252,7 @@ class ApolloClient {
             (0, invariant_1.invariant)(!options.notifyOnNetworkStatusChange, 76);
         }
         return this.queryManager.query(options);
-    }
+    };
     /**
      * This resolves a single mutation according to the options specified and returns a
      * Promise which is either resolved with the resulting data or rejected with an