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

package/CHANGELOG.md

@@ -1,5 +1,190 @@
 # @apollo/client
 
+## 4.2.0-alpha.5
+
+### Patch Changes
+
+- [#13215](https://github.com/apollographql/apollo-client/pull/13215) [`54c9eb7`](https://github.com/apollographql/apollo-client/commit/54c9eb7f95d3cd12dc5d12ec27090f1f23b0c471) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Ensure the options object for the `useQuery`, `useSuspenseQuery`, and `useBackgroundQuery` hooks provide proper IntelliSense suggestions.
+
+## 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

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;
                                         }
                                     }