feat(useSubscription): add skip option (#98)

README.md

@@ -275,6 +275,9 @@ const { data, error, loading } = useSubscription(MY_SUBSCRIPTION, {
 });
 ```
 
+In some cases you might want to subscribe only after you have all the information available, eg. only when user has selected necessary filters. Since hooks cannot be used conditionally, it would lead to unnecessary complicated patterns.
+
+Instead, you can use the `skip` option which turns the subsciption dormant until toggled again. It will also unsubscribe if there was any previous subscription active and throw away previous result.
 
 ## useApolloClient
 

src/__tests__/useSubscription-test.tsx

@@ -3,7 +3,7 @@ import { Operation } from 'apollo-link';
 import { MockSubscriptionLink } from 'apollo-link-mock';
 import gql from 'graphql-tag';
 import React from 'react';
-import { cleanup, render } from 'react-testing-library';
+import { act, cleanup, render } from 'react-testing-library';
 
 import { ApolloProvider, useSubscription } from '..';
 import createClient from '../__testutils__/createClient';
@@ -327,3 +327,39 @@ it('should re-subscription if variables have changed', async () => {
 
   expect(count).toBe(5);
 });
+
+it('should not subscribe if skip option is enabled', async () => {
+  const variables = { completed: true };
+
+  class MockSubscriptionLinkOverride extends MockSubscriptionLink {
+    request(req: Operation) {
+      expect(req.variables).toEqual(variables);
+      return super.request(req);
+    }
+  }
+
+  const link = new MockSubscriptionLinkOverride();
+
+  const client = createClient({ link });
+
+  const Component = () => {
+    const { data, loading, error } = useSubscription(
+      FILTERED_TASKS_SUBSCRIPTION,
+      { variables, skip: true }
+    );
+    expect(loading).toBe(true);
+    expect(error).toBeUndefined();
+    expect(data).toBeUndefined();
+    return null;
+  };
+
+  render(
+    <ApolloProvider client={client}>
+      <Component />
+    </ApolloProvider>
+  );
+
+  act(() => {
+    link.simulateResult(complitedResults[0]);
+  });
+});

src/useSubscription.ts

@@ -22,6 +22,7 @@ export interface OnSubscriptionDataOptions<TData> {
 
 export interface SubscriptionHookOptions<TData, TVariables>
   extends Omit<SubscriptionOptions<TVariables>, 'query'> {
+  skip?: boolean;
   onSubscriptionData?: OnSubscriptionData<TData>;
 }
 
@@ -57,6 +58,9 @@ export function useSubscription<TData = any, TVariables = OperationVariables>(
 
   useEffect(
     () => {
+      if (options.skip === true) {
+        return;
+      }
       const subscription = client
         .subscribe({
           ...options,