@apollo/client 4.2.0-alpha.1 → 4.2.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,195 @@
 # @apollo/client
 
+## 4.2.0-alpha.3
+
+### Minor Changes
+
+- [#13206](https://github.com/apollographql/apollo-client/pull/13206) [`08fccab`](https://github.com/apollographql/apollo-client/commit/08fccab68822e99c6edd539cb4162d1a3df4f4c9) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Extend the `defaultOptions` type-safety work to `client.mutate` and `useMutation`.
+
+  The `errorPolicy` option now flows through to the result types for mutations in the same way it already does for queries:
+
+  - `ApolloClient.MutateResult<TData, TErrorPolicy>` maps `errorPolicy` to the concrete shape of `data` and `error`:
+    - `"none"` → `{ data: TData; error?: never }`
+    - `"all"` → `{ data: TData | undefined; error?: ErrorLike }`
+    - `"ignore"` → `{ data: TData | undefined; error?: never }`
+  - `client.mutate` and `useMutation` pick up the declared `defaultOptions.mutate.errorPolicy` and the explicit `errorPolicy` on each call to narrow return types accordingly.
+  - `useMutation.Result.error` is narrowed to `undefined` when `errorPolicy` is `"ignore"`, since `client.mutate` never resolves with an error in that case.
+
+  `DeclareDefaultOptions.Mutate` already accepted `errorPolicy`; the new behavior is that once you declare it, hook and method return types reflect it:
+
+  ```ts
+  // apollo.d.ts
+  import "@apollo/client";
+
+  declare module "@apollo/client" {
+    namespace ApolloClient {
+      namespace DeclareDefaultOptions {
+        interface Mutate {
+          errorPolicy: "all";
+        }
+      }
+    }
+  }
+  ```
+
+  ```ts
+  const result = await client.mutate({ mutation: MUTATION });
+  result.data;
+  //     ^? TData | undefined
+  result.error;
+  //     ^? ErrorLike | undefined
+  ```
+
+  Setting `errorPolicy` on an individual call overrides the default for that call's return type.
+
+## 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
@@ -12,6 +202,25 @@
 
 - [#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.9
+
+### Patch Changes
+
+- [#13203](https://github.com/apollographql/apollo-client/pull/13203) [`099954b`](https://github.com/apollographql/apollo-client/commit/099954b9905c0f80b57563eb64157386f4493e84) Thanks [@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)! - Remove the `workspaces` field from the published `package.json` in `dist` to avoid Yarn v1 warnings about workspaces requiring private packages.
+
+## 4.1.8
+
+### Patch Changes
+
+- [#13202](https://github.com/apollographql/apollo-client/pull/13202) [`8a51ea6`](https://github.com/apollographql/apollo-client/commit/8a51ea636600dbe4b48477d32f30469b7d36b152) Thanks [@phryneas](https://github.com/phryneas)! - Ship agent skill for usage with @tanstack/intent — the skill is now bundled in the npm package under `skills/apollo-client/` and discoverable by `intent list`.
+  For more context, see the [TanStack Intent QuickStart](https://tanstack.com/intent/latest/docs/getting-started/quick-start-consumers).
+
+## 4.1.7
+
+### Patch Changes
+
+- [#13187](https://github.com/apollographql/apollo-client/pull/13187) [`bb3fd9b`](https://github.com/apollographql/apollo-client/commit/bb3fd9b3d40a2505add673a6ee89d85b8b4c8984) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Fix RxJS interop issue with the observable returned by `WebSocketLink`.
+
 ## 4.1.6
 
 ### 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,16 +252,16 @@ 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
-     * error. In some cases both `data` and `errors` might be undefined, for example
-     * when `errorPolicy` is set to `'ignore'`.
-     *
-     * It takes options as an object with the following keys and values:
-     */
-    mutate(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
+    * error. In some cases both `data` and `errors` might be undefined, for example
+    * when `errorPolicy` is set to `'ignore'`.
+    * 
+    * It takes options as an object with the following keys and values:
+    */
+    mutate = (options) => {
         const optionsWithDefaults = (0, internal_1.mergeOptions)((0, internal_1.compact)({
             fetchPolicy: "network-only",
             errorPolicy: "none",
@@ -260,7 +273,7 @@ class ApolloClient {
         }
         (0, internal_1.checkDocument)(optionsWithDefaults.mutation, graphql_1.OperationTypeNode.MUTATION);
         return this.queryManager.mutate(optionsWithDefaults);
-    }
+    };
     /**
      * This subscribes to a graphql subscription according to the options specified and returns an
      * `Observable` which either emits received data or an error.