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

package/CHANGELOG.md

@@ -1,5 +1,226 @@
 # @apollo/client
 
+## 4.2.0-alpha.4
+
+### Minor Changes
+
+- [#13210](https://github.com/apollographql/apollo-client/pull/13210) [`1f9a428`](https://github.com/apollographql/apollo-client/commit/1f9a4287eb1eeef2cc08c81c92961f1cecd0dbca) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add support for automatic event-based refetching, such as window focus.
+
+  The `RefetchEventManager` class handles automatic refetches in response to events. Apollo Client provides built-in sources for window focus and network reconnect as `windowFocusSource` and `onlineSource`.
+
+  Event refetching is fully opt-in. Create and pass a `RefetchEventManager` instance to the `ApolloClient` constructor to activate the event listeners.
+
+  ```ts
+  import {
+    ApolloClient,
+    InMemoryCache,
+    RefetchEventManager,
+    windowFocusSource,
+    onlineSource,
+  } from "@apollo/client";
+
+  const client = new ApolloClient({
+    link,
+    cache: new InMemoryCache(),
+    refetchEventManager: new RefetchEventManager({
+      sources: {
+        // Refetch when window is focused
+        windowFocus: windowFocusSource,
+
+        // Refetch when the user comes back online
+        online: onlineSource,
+      },
+    }),
+  });
+  ```
+
+  By default, all active queries refetch when the events fire. Queries can opt out per-event or disable all event refetches:
+
+  ```ts
+  // Skip refetch on window focus for this query, but keep `online`
+  useQuery(QUERY, {
+    refetchOn: { windowFocus: false },
+  });
+
+  // Disable all event-driven refetches for this query
+  useQuery(OTHER_QUERY, {
+    refetchOn: false,
+  });
+
+  // Enable every event for this query, regardless of defaultOptions
+  useQuery(LIVE_DASHBOARD, {
+    refetchOn: true,
+  });
+
+  // Dynamically enable or disable a refetch when the event fires
+  useQuery(LIVE_DASHBOARD, {
+    refetchOn: ({ source, payload }) => {
+      if (source === "windowFocus") {
+        // payload is the data associated with the event
+        return someCondition(payload);
+      }
+
+      return true;
+    },
+  });
+
+  // Dynamically enable or disable a refetch for a specific event
+  useQuery(LIVE_DASHBOARD, {
+    refetchOn: {
+      windowFocus: ({ payload }) => {
+        // payload is the data associated with the event
+        return someCondition(payload);
+      },
+    },
+  });
+  ```
+
+  To enable per-query opt-in rather than opt-out, set `defaultOptions.watchQuery.refetchOn` to `false` and enable it per-query instead.
+
+  ```ts
+  const client = new ApolloClient({
+    link,
+    cache,
+    refetchEventManager: new RefetchEventManager({
+      sources: { windowFocus: windowFocusSource },
+    }),
+    defaultOptions: {
+      watchQuery: { refetchOn: false },
+    },
+  });
+
+  // Only this query refetches on window focus
+  useQuery(DASHBOARD_QUERY, { refetchOn: { windowFocus: true } });
+  ```
+
+  When `defaultOptions.watchQuery.refetchOn` and per-query `refetchOn` options are provided, the objects are merged together.
+
+  ### Custom events
+
+  You can also add your own custom events that trigger refetches. Register your event name and payload type using TypeScript module augmentation, then provide a source function that returns an Observable. The source's emitted value becomes the event's `payload`.
+
+  ```ts
+  import { Observable } from "@apollo/client";
+  import { filter } from "rxjs";
+  import { AppState, AppStateStatus, Platform } from "react-native";
+
+  declare module "@apollo/client" {
+    interface RefetchEvents {
+      reactNativeAppStatus: AppStateStatus;
+    }
+  }
+
+  const refetchEventManager = new RefetchEventManager({
+    sources: {
+      reactNativeAppStatus: () => {
+        return new Observable((observer) => {
+          const subscription = AppState.addEventListener("change", (status) => {
+            observer.next(status);
+          });
+          return () => subscription.remove();
+        }).pipe(
+          filter((status) => Platform.OS !== "web" && status === "active")
+        );
+      },
+    },
+  });
+
+  // Disable per-query by setting the event to false
+  useQuery(QUERY, { refetchOn: { reactNativeAppStatus: false } });
+  ```
+
+  ### Manually trigger an event refetch
+
+  Refetches can be triggered imperatively by calling `emit` with the event name and its payload (if any).
+
+  ```ts
+  refetchEventManager.emit("reactNativeAppStatus", "active");
+  ```
+
+  #### Sourceless events
+
+  A source that has no automatic detection logic but still wants imperative `emit` support can be declared as `true`. Type the event as `void` to omit the payload argument.
+
+  ```ts
+  declare module "@apollo/client" {
+    interface RefetchEvents {
+      userTriggered: void;
+    }
+  }
+
+  const refetchEventManager = new RefetchEventManager({
+    sources: { userTriggered: true },
+  });
+
+  refetchEventManager.emit("userTriggered");
+  ```
+
+  Note: Calling `emit` on an event without a registered source will log a warning and result in a no-op.
+
+  ### Custom handlers
+
+  When an event fires, the default handler calls `client.refetchQueries({ include: "active" })` filtered by each query's `refetchOn` setting. You can override the handler for an event to add your own custom filtering. For example, to refetch all queries, including `standby` queries, define a handler for the event:
+
+  ```ts
+  const refetchEventManager = new RefetchEventManager({
+    // ...
+    handlers: {
+      userTriggered: ({ client, source, payload, matchesRefetchOn }) => {
+        return client.refetchQueries({
+          include: "all",
+          onQueryUpdated: (observableQuery) => {
+            return matchesRefetchOn(observableQuery);
+          },
+        });
+      },
+    },
+  });
+  ```
+
+  Handlers must return either a `RefetchQueriesResult` or `void`. Returning `void` skips refetching for the event.
+
+## 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
@@ -160,6 +381,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/cache/core/cache.cjs

@@ -140,7 +140,7 @@ class ApolloCache {
             if (environment_1.__DEV__) {
                 const actualFragmentName = fragmentName || (0, internal_1.getFragmentDefinition)(fragment).name.value;
                 if (id === undefined) {
-                    __DEV__ && invariant_1.invariant.warn(113, actualFragmentName);
+                    __DEV__ && invariant_1.invariant.warn(118, actualFragmentName);
                 }
             }
             return id;

package/__cjs/cache/inmemory/entityStore.cjs

@@ -82,7 +82,7 @@ class EntityStore {
         // then there are no fields to be merged, so we're done.
         if (!incoming)
             return;
-        (0, invariant_1.invariant)(typeof dataId === "string", 99);
+        (0, invariant_1.invariant)(typeof dataId === "string", 104);
         const merged = new internal_1.DeepMerger({
             reconciler: storeObjectReconciler,
         }).merge(existing, incoming);
@@ -184,7 +184,7 @@ class EntityStore {
                             if (environment_1.__DEV__) {
                                 const checkReference = (ref) => {
                                     if (this.lookup(ref.__ref) === undefined) {
-                                        __DEV__ && invariant_1.invariant.warn(100, ref);
+                                        __DEV__ && invariant_1.invariant.warn(105, ref);
                                         return true;
                                     }
                                 };
@@ -213,7 +213,7 @@ class EntityStore {
                                             }
                                         }
                                         if (seenReference && someNonReference !== undefined) {
-                                            __DEV__ && invariant_1.invariant.warn(101, someNonReference);
+                                            __DEV__ && invariant_1.invariant.warn(106, someNonReference);
                                             break;
                                         }
                                     }