add ignoreResults option to useSubscription (#11921)

* add `ignoreResults` option to `useSubscription`

* more tests

* changeset

* restore type, add deprecation, tweak tag

* Update src/react/hooks/useSubscription.ts

* reflect code change in comment

* review feedback

* Update src/react/types/types.documentation.ts

Co-authored-by: Jerel Miller <jerelmiller@gmail.com>

* add clarification about resetting the return value when switching on `ignoreResults` later

* test fixup

---------

Co-authored-by: Jerel Miller <jerelmiller@gmail.com>

.api-reports/api-report-react.api.md

@@ -388,6 +388,7 @@ export interface BaseSubscriptionOptions<TData = any, TVariables extends Operati
  context?: Context;
  // Warning: (ae-forgotten-export) The symbol "FetchPolicy" needs to be exported by the entry point index.d.ts
  fetchPolicy?: FetchPolicy;
+ ignoreResults?: boolean;
  onComplete?: () => void;
  onData?: (options: OnDataOptions<TData>) => any;
  onError?: (error: ApolloError) => void;
@@ -1919,7 +1920,7 @@ export interface SubscriptionCurrentObservable {
  subscription?: Subscription;
 }
 
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export interface SubscriptionDataOptions<TData = any, TVariables extends OperationVariables = OperationVariables> extends BaseSubscriptionOptions<TData, TVariables> {
  // (undocumented)
  children?: null | ((result: SubscriptionResult<TData>) => ReactTypes.ReactNode);

.api-reports/api-report-react_components.api.md

@@ -336,6 +336,7 @@ interface BaseSubscriptionOptions<TData = any, TVariables extends OperationVaria
  context?: DefaultContext;
  // Warning: (ae-forgotten-export) The symbol "FetchPolicy" needs to be exported by the entry point index.d.ts
  fetchPolicy?: FetchPolicy;
+ ignoreResults?: boolean;
  onComplete?: () => void;
  // Warning: (ae-forgotten-export) The symbol "OnDataOptions" needs to be exported by the entry point index.d.ts
  onData?: (options: OnDataOptions<TData>) => any;

.api-reports/api-report-react_hooks.api.md

@@ -359,6 +359,7 @@ interface BaseSubscriptionOptions<TData = any, TVariables extends OperationVaria
  context?: DefaultContext;
  // Warning: (ae-forgotten-export) The symbol "FetchPolicy" needs to be exported by the entry point index.d.ts
  fetchPolicy?: FetchPolicy;
+ ignoreResults?: boolean;
  onComplete?: () => void;
  // Warning: (ae-forgotten-export) The symbol "OnDataOptions" needs to be exported by the entry point index.d.ts
  onData?: (options: OnDataOptions<TData>) => any;

.api-reports/api-report.api.md

@@ -359,6 +359,7 @@ export interface BaseSubscriptionOptions<TData = any, TVariables extends Operati
  client?: ApolloClient<object>;
  context?: DefaultContext;
  fetchPolicy?: FetchPolicy;
+ ignoreResults?: boolean;
  onComplete?: () => void;
  onData?: (options: OnDataOptions<TData>) => any;
  onError?: (error: ApolloError) => void;
@@ -2551,7 +2552,7 @@ export interface SubscriptionCurrentObservable {
  subscription?: ObservableSubscription;
 }
 
-// @public (undocumented)
+// @public @deprecated (undocumented)
 export interface SubscriptionDataOptions<TData = any, TVariables extends OperationVariables = OperationVariables> extends BaseSubscriptionOptions<TData, TVariables> {
  // (undocumented)
  children?: null | ((result: SubscriptionResult<TData>) => ReactTypes.ReactNode);

.changeset/unlucky-birds-press.md

@@ -0,0 +1,5 @@
+---
+"@apollo/client": patch
+---
+
+add `ignoreResults` option to `useSubscription`

.size-limits.json

@@ -1,4 +1,4 @@
 {
- "dist/apollo-client.min.cjs": 39971,
+ "dist/apollo-client.min.cjs": 40015,
  "import { ApolloClient, InMemoryCache, HttpLink } from \"dist/index.js\" (production)": 32903
 }

src/react/hooks/__tests__/useSubscription.test.tsx

@@ -1455,6 +1455,297 @@ describe("`restart` callback", () => {
  });
 });
 
+describe("ignoreResults", () => {
+ const subscription = gql`
+ subscription {
+ car {
+ make
+ }
+ }
+ `;
+
+ const results = ["Audi", "BMW"].map((make) => ({
+ result: { data: { car: { make } } },
+ }));
+
+ it("should not rerender when ignoreResults is true, but will call `onData` and `onComplete`", async () => {
+ const link = new MockSubscriptionLink();
+ const client = new ApolloClient({
+ link,
+ cache: new Cache({ addTypename: false }),
+ });
+
+ const onData = jest.fn((() => {}) as SubscriptionHookOptions["onData"]);
+ const onError = jest.fn((() => {}) as SubscriptionHookOptions["onError"]);
+ const onComplete = jest.fn(
+ (() => {}) as SubscriptionHookOptions["onComplete"]
+ );
+ const ProfiledHook = profileHook(() =>
+ useSubscription(subscription, {
+ ignoreResults: true,
+ onData,
+ onError,
+ onComplete,
+ })
+ );
+ render(<ProfiledHook />, {
+ wrapper: ({ children }) => (
+ <ApolloProvider client={client}>{children}</ApolloProvider>
+ ),
+ });
+
+ const snapshot = await ProfiledHook.takeSnapshot();
+ expect(snapshot).toStrictEqual({
+ loading: false,
+ error: undefined,
+ data: undefined,
+ variables: undefined,
+ restart: expect.any(Function),
+ });
+ link.simulateResult(results[0]);
+
+ await waitFor(() => {
+ expect(onData).toHaveBeenCalledTimes(1);
+ expect(onData).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ data: {
+ data: results[0].result.data,
+ error: undefined,
+ loading: false,
+ variables: undefined,
+ },
+ })
+ );
+ expect(onError).toHaveBeenCalledTimes(0);
+ expect(onComplete).toHaveBeenCalledTimes(0);
+ });
+
+ link.simulateResult(results[1], true);
+ await waitFor(() => {
+ expect(onData).toHaveBeenCalledTimes(2);
+ expect(onData).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ data: {
+ data: results[1].result.data,
+ error: undefined,
+ loading: false,
+ variables: undefined,
+ },
+ })
+ );
+ expect(onError).toHaveBeenCalledTimes(0);
+ expect(onComplete).toHaveBeenCalledTimes(1);
+ });
+
+ await expect(ProfiledHook).not.toRerender();
+ });
+
+ it("should not rerender when ignoreResults is true and an error occurs", async () => {
+ const link = new MockSubscriptionLink();
+ const client = new ApolloClient({
+ link,
+ cache: new Cache({ addTypename: false }),
+ });
+
+ const onData = jest.fn((() => {}) as SubscriptionHookOptions["onData"]);
+ const onError = jest.fn((() => {}) as SubscriptionHookOptions["onError"]);
+ const onComplete = jest.fn(
+ (() => {}) as SubscriptionHookOptions["onComplete"]
+ );
+ const ProfiledHook = profileHook(() =>
+ useSubscription(subscription, {
+ ignoreResults: true,
+ onData,
+ onError,
+ onComplete,
+ })
+ );
+ render(<ProfiledHook />, {
+ wrapper: ({ children }) => (
+ <ApolloProvider client={client}>{children}</ApolloProvider>
+ ),
+ });
+
+ const snapshot = await ProfiledHook.takeSnapshot();
+ expect(snapshot).toStrictEqual({
+ loading: false,
+ error: undefined,
+ data: undefined,
+ variables: undefined,
+ restart: expect.any(Function),
+ });
+ link.simulateResult(results[0]);
+
+ await waitFor(() => {
+ expect(onData).toHaveBeenCalledTimes(1);
+ expect(onData).toHaveBeenLastCalledWith(
+ expect.objectContaining({
+ data: {
+ data: results[0].result.data,
+ error: undefined,
+ loading: false,
+ variables: undefined,
+ },
+ })
+ );
+ expect(onError).toHaveBeenCalledTimes(0);
+ expect(onComplete).toHaveBeenCalledTimes(0);
+ });
+
+ const error = new Error("test");
+ link.simulateResult({ error });
+ await waitFor(() => {
+ expect(onData).toHaveBeenCalledTimes(1);
+ expect(onError).toHaveBeenCalledTimes(1);
+ expect(onError).toHaveBeenLastCalledWith(error);
+ expect(onComplete).toHaveBeenCalledTimes(0);
+ });
+
+ await expect(ProfiledHook).not.toRerender();
+ });
+
+ it("can switch from `ignoreResults: true` to `ignoreResults: false` and will start rerendering, without creating a new subscription", async () => {
+ const subscriptionCreated = jest.fn();
+ const link = new MockSubscriptionLink();
+ link.onSetup(subscriptionCreated);
+ const client = new ApolloClient({
+ link,
+ cache: new Cache({ addTypename: false }),
+ });
+
+ const onData = jest.fn((() => {}) as SubscriptionHookOptions["onData"]);
+ const ProfiledHook = profileHook(
+ ({ ignoreResults }: { ignoreResults: boolean }) =>
+ useSubscription(subscription, {
+ ignoreResults,
+ onData,
+ })
+ );
+ const { rerender } = render(<ProfiledHook ignoreResults={true} />, {
+ wrapper: ({ children }) => (
+ <ApolloProvider client={client}>{children}</ApolloProvider>
+ ),
+ });
+ expect(subscriptionCreated).toHaveBeenCalledTimes(1);
+
+ {
+ const snapshot = await ProfiledHook.takeSnapshot();
+ expect(snapshot).toStrictEqual({
+ loading: false,
+ error: undefined,
+ data: undefined,
+ variables: undefined,
+ restart: expect.any(Function),
+ });
+ expect(onData).toHaveBeenCalledTimes(0);
+ }
+ link.simulateResult(results[0]);
+ await expect(ProfiledHook).not.toRerender({ timeout: 20 });
+ expect(onData).toHaveBeenCalledTimes(1);
+
+ rerender(<ProfiledHook ignoreResults={false} />);
+ {
+ const snapshot = await ProfiledHook.takeSnapshot();
+ expect(snapshot).toStrictEqual({
+ loading: false,
+ error: undefined,
+ // `data` appears immediately after changing to `ignoreResults: false`
+ data: results[0].result.data,
+ variables: undefined,
+ restart: expect.any(Function),
+ });
+ // `onData` should not be called again for the same result
+ expect(onData).toHaveBeenCalledTimes(1);
+ }
+
+ link.simulateResult(results[1]);
+ {
+ const snapshot = await ProfiledHook.takeSnapshot();
+ expect(snapshot).toStrictEqual({
+ loading: false,
+ error: undefined,
+ data: results[1].result.data,
+ variables: undefined,
+ restart: expect.any(Function),
+ });
+ expect(onData).toHaveBeenCalledTimes(2);
+ }
+ // a second subscription should not have been started
+ expect(subscriptionCreated).toHaveBeenCalledTimes(1);
+ });
+ it("can switch from `ignoreResults: false` to `ignoreResults: true` and will stop rerendering, without creating a new subscription", async () => {
+ const subscriptionCreated = jest.fn();
+ const link = new MockSubscriptionLink();
+ link.onSetup(subscriptionCreated);
+ const client = new ApolloClient({
+ link,
+ cache: new Cache({ addTypename: false }),
+ });
+
+ const onData = jest.fn((() => {}) as SubscriptionHookOptions["onData"]);
+ const ProfiledHook = profileHook(
+ ({ ignoreResults }: { ignoreResults: boolean }) =>
+ useSubscription(subscription, {
+ ignoreResults,
+ onData,
+ })
+ );
+ const { rerender } = render(<ProfiledHook ignoreResults={false} />, {
+ wrapper: ({ children }) => (
+ <ApolloProvider client={client}>{children}</ApolloProvider>
+ ),
+ });
+ expect(subscriptionCreated).toHaveBeenCalledTimes(1);
+
+ {
+ const snapshot = await ProfiledHook.takeSnapshot();
+ expect(snapshot).toStrictEqual({
+ loading: true,
+ error: undefined,
+ data: undefined,
+ variables: undefined,
+ restart: expect.any(Function),
+ });
+ expect(onData).toHaveBeenCalledTimes(0);
+ }
+ link.simulateResult(results[0]);
+ {
+ const snapshot = await ProfiledHook.takeSnapshot();
+ expect(snapshot).toStrictEqual({
+ loading: false,
+ error: undefined,
+ data: results[0].result.data,
+ variables: undefined,
+ restart: expect.any(Function),
+ });
+ expect(onData).toHaveBeenCalledTimes(1);
+ }
+ await expect(ProfiledHook).not.toRerender({ timeout: 20 });
+
+ rerender(<ProfiledHook ignoreResults={true} />);
+ {
+ const snapshot = await ProfiledHook.takeSnapshot();
+ expect(snapshot).toStrictEqual({
+ loading: false,
+ error: undefined,
+ // switching back to the default `ignoreResults: true` return value
+ data: undefined,
+ variables: undefined,
+ restart: expect.any(Function),
+ });
+ // `onData` should not be called again
+ expect(onData).toHaveBeenCalledTimes(1);
+ }
+
+ link.simulateResult(results[1]);
+ await expect(ProfiledHook).not.toRerender({ timeout: 20 });
+ expect(onData).toHaveBeenCalledTimes(2);
+
+ // a second subscription should not have been started
+ expect(subscriptionCreated).toHaveBeenCalledTimes(1);
+ });
+});
+
 describe.skip("Type Tests", () => {
  test("NoInfer prevents adding arbitrary additional variables", () => {
  const typedNode = {} as TypedDocumentNode<{ foo: string }, { bar: number }>;