Feature: add onSubscriptionData callback to <Subscription>

Changelog.md

@@ -4,6 +4,12 @@
 
 - Added an example app that shows how to test mutations. <br/>
   [@excitement-engineer](https://github.com/excitement-engineer) in [#1998](https://github.com/apollographql/react-apollo/pull/1998)
+- The `<Subscription />` component now allows the registration of a callback
+  function, that will be triggered each time the component receives data. The
+  callback `options` object param consists of the current Apollo Client
+  instance in `client`, and the received subscription data in
+  `subscriptionData`. <br/>
+  [@jedwards1211](https://github.com/jedwards1211) in [#1966](https://github.com/apollographql/react-apollo/pull/1966)
 
 ## 2.1.11 (August 9, 2018)
 

src/Subscriptions.tsx

@@ -16,11 +16,17 @@ export interface SubscriptionResult<TData = any> {
   error?: ApolloError;
 }
 
+export interface OnSubscriptionDataOptions<TData = any> {
+  client: ApolloClient<Object>;
+  subscriptionData: SubscriptionResult<TData>;
+}
+
 export interface SubscriptionProps<TData = any, TVariables = OperationVariables> {
   subscription: DocumentNode;
   variables?: TVariables;
   shouldResubscribe?: any;
-  children: (result: SubscriptionResult<TData>) => React.ReactNode;
+  onSubscriptionData?: (options: OnSubscriptionDataOptions<TData>) => any;
+  children?: (result: SubscriptionResult<TData>) => React.ReactNode;
 }
 
 export interface SubscriptionState<TData = any> {
@@ -44,7 +50,8 @@ class Subscription<TData = any, TVariables = any> extends React.Component<
   static propTypes = {
     subscription: PropTypes.object.isRequired,
     variables: PropTypes.object,
-    children: PropTypes.func.isRequired,
+    children: PropTypes.func,
+    onSubscriptionData: PropTypes.func,
     shouldResubscribe: PropTypes.oneOfType([PropTypes.func, PropTypes.bool]),
   };
 
@@ -106,10 +113,12 @@ class Subscription<TData = any, TVariables = any> extends React.Component<
   }
 
   render() {
+    const renderFn: any = this.props.children;
+    if (!renderFn) return null;
     const result = Object.assign({}, this.state, {
       variables: this.props.variables,
     });
-    return this.props.children(result);
+    return renderFn(result);
   }
 
   private initialize = (props: SubscriptionProps<TData, TVariables>) => {
@@ -135,6 +144,8 @@ class Subscription<TData = any, TVariables = any> extends React.Component<
   });
 
   private updateCurrentData = (result: SubscriptionResult<TData>) => {
+    const {client, props: {onSubscriptionData}} = this;
+    if (onSubscriptionData) onSubscriptionData({client, subscriptionData: result});
     this.setState({
       data: result.data,
       loading: false,

test/client/Subscription.test.tsx

@@ -98,6 +98,39 @@ it('executes the subscription', done => {
   jest.runTimersToTime(40);
 });
 
+
+it('calls onSubscriptionData if given', done => {
+  jest.useFakeTimers();
+
+  let count = 0;
+
+  const Component = () => (
+    <Subscription
+      subscription={subscription}
+      onSubscriptionData={opts => {
+        expect(opts.client).toBeInstanceOf(ApolloClient);
+        const {data} = opts.subscriptionData;
+        expect(data).toEqual(results[count].result.data);
+        if (count === 3) done();
+        count++;
+      }}
+    />
+  );
+
+  wrapper = mount(
+    <ApolloProvider client={client}>
+      <Component />
+    </ApolloProvider>,
+  );
+
+  const interval = setInterval(() => {
+    link.simulateResult(results[count]);
+    if (count >= 3) clearInterval(interval);
+  }, 10);
+
+  jest.runTimersToTime(40);
+});
+
 it('executes subscription for the variables passed in the props', done => {
   expect.assertions(4);
   const subscriptionWithVariables = gql`