resultTransformer and resultComparator

CHANGELOG.md

@@ -5,6 +5,7 @@ Expect active development and potentially significant breaking changes in the `0
 ### vNEXT
 - Fixed an issue with named fragments in batched queries. [PR #509](https://github.com/apollostack/apollo-client/pull/509) and [Issue #501](https://github.com/apollostack/apollo-client/issues/501).
 - Fixed an issue with unused variables in queries after diffing queries against information available in the store. [PR #518](https://github.com/apollostack/apollo-client/pull/518) and [Issue #496](https://github.com/apollostack/apollo-client/issues/496).
+- Added `resultTransformer` and `resultComparator` to `ApolloClient`/`QueryManager`, which afford the ability to transform result objects immediately before they are returned to the application. [PR #446](https://github.com/apollostack/apollo-client/pull/446)
 
 ### v0.4.11
 

src/ObservableQuery.ts

@@ -104,7 +104,8 @@ export class ObservableQuery extends Observable<ApolloQueryResult> {
       return this.queryManager.fetchQuery(this.queryId, assign(this.options, {
         forceFetch: true,
         variables,
-      }) as WatchQueryOptions);
+      }) as WatchQueryOptions)
+      .then(result => this.queryManager.transformResult(result));
     };
 
     this.fetchMore = (fetchMoreOptions: WatchQueryOptions & FetchMoreOptions) => {

src/QueryManager.ts

@@ -95,6 +95,22 @@ import { ObservableQuery } from './ObservableQuery';
 
 export type QueryListener = (queryStoreValue: QueryStoreValue) => void;
 
+// A result transformer is given the data that is to be returned from the store from a query or
+// mutation, and can modify or observe it before the value is provided to your application.
+//
+// For watched queries, the transformer is only called when the data retrieved from the server is
+// different from previous.
+//
+// If the transformer wants to mutate results (say, by setting the prototype of result data), it
+// will likely need to be paired with a custom resultComparator.  By default, Apollo performs a
+// deep equality comparsion on results, and skips those that are considered equal - reducing
+// re-renders.
+export type ResultTransformer = (resultData: ApolloQueryResult) => ApolloQueryResult;
+
+// Controls how Apollo compares two query results and considers their equality.  Two equal results
+// will not trigger re-renders.
+export type ResultComparator = (result1: ApolloQueryResult, result2: ApolloQueryResult) => boolean;
+
 export class QueryManager {
   public pollingTimers: {[queryId: string]: NodeJS.Timer | any}; //oddity in Typescript
   public scheduler: QueryScheduler;
@@ -103,6 +119,8 @@ export class QueryManager {
   private networkInterface: NetworkInterface;
   private reduxRootKey: string;
   private queryTransformer: QueryTransformer;
+  private resultTransformer: ResultTransformer;
+  private resultComparator: ResultComparator;
   private queryListeners: { [queryId: string]: QueryListener };
 
   // A map going from queryId to the last result/state that the queryListener was told about.
@@ -140,13 +158,17 @@ export class QueryManager {
     store,
     reduxRootKey,
     queryTransformer,
+    resultTransformer,
+    resultComparator,
     shouldBatch = false,
     batchInterval = 10,
   }: {
     networkInterface: NetworkInterface,
     store: ApolloStore,
     reduxRootKey: string,
     queryTransformer?: QueryTransformer,
+    resultTransformer?: ResultTransformer,
+    resultComparator?: ResultComparator,
     shouldBatch?: Boolean,
     batchInterval?: number,
   }) {
@@ -156,6 +178,8 @@ export class QueryManager {
     this.store = store;
     this.reduxRootKey = reduxRootKey;
     this.queryTransformer = queryTransformer;
+    this.resultTransformer = resultTransformer;
+    this.resultComparator = resultComparator;
     this.pollingTimers = {};
     this.batchInterval = batchInterval;
     this.queryListeners = {};
@@ -275,7 +299,7 @@ export class QueryManager {
           });
 
           refetchQueries.forEach((name) => { this.refetchQueryByName(name); });
-          resolve(result);
+          resolve(this.transformResult(<ApolloQueryResult>result));
         })
         .catch((err) => {
           this.store.dispatch({
@@ -338,7 +362,7 @@ export class QueryManager {
             if (observer.next) {
               if (this.isDifferentResult(queryId, resultFromStore )) {
                 this.queryResults[queryId] = resultFromStore;
-                observer.next(resultFromStore);
+                observer.next(this.transformResult(resultFromStore));
               }
             }
           } catch (error) {
@@ -577,6 +601,15 @@ export class QueryManager {
     };
   }
 
+  // Give the result transformer a chance to observe or modify result data before it is passed on.
+  public transformResult(result: ApolloQueryResult): ApolloQueryResult {
+    if (!this.resultTransformer) {
+      return result;
+    } else {
+      return this.resultTransformer(result);
+    }
+  }
+
   private collectResultBehaviorsFromUpdateQueries(
     updateQueries: MutationQueryReducersMap,
     mutationResult: Object,
@@ -908,7 +941,8 @@ export class QueryManager {
   // Given a query id and a new result, this checks if the old result is
   // the same as the last result for that particular query id.
   private isDifferentResult(queryId: string, result: ApolloQueryResult): boolean {
-    return !isEqual(this.queryResults[queryId], result);
+    const comparator = this.resultComparator || isEqual;
+    return !comparator(this.queryResults[queryId], result);
   }
 
   private broadcastQueries() {

src/index.ts

@@ -30,6 +30,8 @@ import {
 
 import {
   QueryManager,
+  ResultComparator,
+  ResultTransformer,
 } from './QueryManager';
 
 import {
@@ -167,6 +169,8 @@ export default class ApolloClient {
   public queryManager: QueryManager;
   public reducerConfig: ApolloReducerConfig;
   public queryTransformer: QueryTransformer;
+  public resultTransformer: ResultTransformer;
+  public resultComparator: ResultComparator;
   public shouldBatch: boolean;
   public shouldForceFetch: boolean;
   public dataId: IdGetter;
@@ -179,6 +183,8 @@ export default class ApolloClient {
     initialState,
     dataIdFromObject,
     queryTransformer,
+    resultTransformer,
+    resultComparator,
     shouldBatch = false,
     ssrMode = false,
     ssrForceFetchDelay = 0,
@@ -190,6 +196,8 @@ export default class ApolloClient {
     initialState?: any,
     dataIdFromObject?: IdGetter,
     queryTransformer?: QueryTransformer,
+    resultTransformer?: ResultTransformer,
+    resultComparator?: ResultComparator,
     shouldBatch?: boolean,
     ssrMode?: boolean,
     ssrForceFetchDelay?: number
@@ -201,6 +209,8 @@ export default class ApolloClient {
     this.networkInterface = networkInterface ? networkInterface :
       createNetworkInterface('/graphql');
     this.queryTransformer = queryTransformer;
+    this.resultTransformer = resultTransformer;
+    this.resultComparator = resultComparator;
     this.shouldBatch = shouldBatch;
     this.shouldForceFetch = !(ssrMode || ssrForceFetchDelay > 0);
     this.dataId = dataIdFromObject;
@@ -307,6 +317,8 @@ export default class ApolloClient {
       reduxRootKey: this.reduxRootKey,
       store,
       queryTransformer: this.queryTransformer,
+      resultTransformer: this.resultTransformer,
+      resultComparator: this.resultComparator,
       shouldBatch: this.shouldBatch,
       batchInterval: this.batchInterval,
     });

test/QueryManager.ts

@@ -3067,6 +3067,161 @@ describe('QueryManager', () => {
       });
     });
   });
+
+  describe('result transformation', () => {
+
+    let client: ApolloClient, response, transformCount;
+    beforeEach(() => {
+      transformCount = 0;
+
+      const networkInterface: NetworkInterface = {
+        query(request: Request): Promise<GraphQLResult> {
+          return Promise.resolve(response);
+        },
+      };
+
+      client = new ApolloClient({
+        networkInterface,
+        resultTransformer(result) {
+          transformCount++;
+          return {
+            data: assign({}, result.data, {transformCount}),
+            loading: false,
+          };
+        },
+      });
+    });
+
+    it('transforms query() results', () => {
+      response = {data: {foo: 123}};
+      return client.query({query: gql`{ foo }`})
+        .then((result) => {
+          assert.deepEqual(result.data, {foo: 123, transformCount: 1});
+        });
+    });
+
+    it('transforms watchQuery() results', (done) => {
+      response = {data: {foo: 123}};
+      const handle = client.watchQuery({query: gql`{ foo }`});
+
+      let callCount = 0;
+      handle.subscribe({
+        error: done,
+        next(result) {
+          try {
+            callCount++;
+            if (callCount === 1) {
+              assert.deepEqual(result.data, {foo: 123, transformCount: 1});
+              response = {data: {foo: 456}};
+              handle.refetch();
+            } else {
+              assert.deepEqual(result.data, {foo: 456, transformCount: 2});
+              done();
+            }
+          } catch (error) {
+            done(error);
+          }
+        },
+      });
+    });
+
+    it('does not transform identical watchQuery() results', (done) => {
+      response = {data: {foo: 123}};
+      const handle = client.watchQuery({query: gql`{ foo }`});
+
+      let callCount = 0;
+      handle.subscribe({
+        error: done,
+        next(result) {
+          callCount++;
+          try {
+            assert.equal(callCount, 1, 'observer should only fire once');
+            assert.deepEqual(result.data, {foo: 123, transformCount: 1});
+          } catch (error) {
+            done(error);
+            return;
+          }
+
+          response = {data: {foo: 123}}; // Ensure we have new response objects.
+          handle.refetch().then(() => {
+            // Skip done() on subsequent calls, because that means we've already failed.  This gives
+            // us better test failure output.
+            if (callCount === 1) {
+              done();
+            }
+          }).catch(done);
+        },
+      });
+    });
+
+    it('transforms mutate() results', () => {
+      response = {data: {foo: 123}};
+      return client.mutate({mutation: gql`mutation makeChanges { foo }`})
+        .then((result) => {
+          assert.deepEqual(result.data, {foo: 123, transformCount: 1});
+        });
+    });
+
+  });
+
+  describe('result transformation with custom equality', () => {
+
+    class Model {}
+
+    let client: ApolloClient, response;
+    beforeEach(() => {
+      const networkInterface: NetworkInterface = {
+        query(request: Request): Promise<GraphQLResult> {
+          return Promise.resolve(response);
+        },
+      };
+
+      client = new ApolloClient({
+        networkInterface,
+        resultTransformer(result) {
+          result.data.__proto__ = Model.prototype;
+          return result;
+        },
+        resultComparator(result1, result2) {
+          // A real example would, say, deep compare the two while ignoring prototypes.
+          const foo1 = result1 && result1.data && result1.data.foo;
+          const foo2 = result2 && result2.data && result2.data.foo;
+          return foo1 === foo2;
+        },
+      });
+    });
+
+    it('does not transform identical watchQuery() results, according to the comparator', (done) => {
+      response = {data: {foo: 123}};
+      const handle = client.watchQuery({query: gql`{ foo }`});
+
+      let callCount = 0;
+      handle.subscribe({
+        error: done,
+        next(result) {
+          callCount++;
+          try {
+            assert.equal(callCount, 1, 'observer should only fire once');
+            assert.instanceOf(result.data, Model);
+          } catch (error) {
+            done(error);
+            return;
+          }
+
+          response = {data: {foo: 123}}; // Ensure we have new response objects.
+          handle.refetch().then(() => {
+            // Skip done() on subsequent calls, because that means we've already failed.  This gives
+            // us better test failure output.
+            if (callCount === 1) {
+              done();
+            }
+          }).catch(done);
+        },
+      });
+    });
+
+  });
+
 });
 
 function testDiffing(

typings/main/globals/node/index.d.ts

@@ -2298,4 +2298,4 @@ declare module "constants" {
     export var W_OK: number;
     export var X_OK: number;
     export var UV_UDP_REUSEADDR: number;
-}
+}