apollographql · helfer · Mar 1, 2017 · Feb 9, 2017 · Feb 9, 2017 · Feb 10, 2017
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,7 @@ Expect active development and potentially significant breaking changes in the `0
 
 ### vNEXT
 - Prefer stale data over partial data in cases where a user would previously get an error. [PR #1306](https://github.com/apollographql/apollo-client/pull/1306)
+- Add direct cache manipulation read and write methods to provide the user the power to interact with Apollo’s GraphQL data representation outside of mutations. [PR #1310](https://github.com/apollographql/apollo-client/pull/1310)
 - Update TypeScript `MutationOptions` definition with the new object type available in `refetchQueries`. [PR #1315](https://github.com/apollographql/apollo-client/pull/1315)
 - Add `fetchMore` network status to enable loading information for `fetchMore` queries. [PR #1305](https://github.com/apollographql/apollo-client/pull/1305)
 - ...

diff --git a/src/ApolloClient.ts b/src/ApolloClient.ts
@@ -11,6 +11,8 @@ import {
   SelectionSetNode,
   /* tslint:enable */
 
+  DocumentNode,
+  FragmentDefinitionNode,
 } from 'graphql';
 
 import {
@@ -58,6 +60,16 @@ import {
   storeKeyNameFromFieldNameAndArgs,
 } from './data/storeUtils';
 
+import {
+  getFragmentQueryDocument,
+} from './queries/getFromAST';
+
+import {
+  DataProxy,
+  ReduxDataProxy,
+  TransactionDataProxy,
+} from './data/proxy';
+
 import {
   version,
 } from './version';
@@ -100,6 +112,8 @@ export default class ApolloClient {
   public queryDeduplication: boolean;
 
   private devToolsHookCb: Function;
+  private optimisticWriteId: number;
+  private proxy: DataProxy | undefined;
 
   /**
    * Constructs an instance of {@link ApolloClient}.
@@ -232,6 +246,8 @@ export default class ApolloClient {
     }
 
     this.version = version;
+
+    this.optimisticWriteId = 1;
   }
 
   /**
@@ -336,6 +352,219 @@ export default class ApolloClient {
     return this.queryManager.startGraphQLSubscription(realOptions);
   }
 
+  /**
+   * Tries to read some data from the store in the shape of the provided
+   * GraphQL query without making a network request. This method will start at
+   * the root query. To start at a specific id returned by `dataIdFromObject`
+   * use `readFragment`.
+   *
+   * @param query The GraphQL query shape to be used.
+   *
+   * @param variables Any variables that the GraphQL query may depend on.
+   */
+  public readQuery<QueryType>(
+    query: DocumentNode,
+    variables?: Object,
+  ): QueryType {
+    return this.initProxy().readQuery<QueryType>(query, variables);
+  }
+
+  /**
+   * Tries to read some data from the store in the shape of the provided
+   * GraphQL fragment without making a network request. This method will read a
+   * GraphQL fragment from any arbitrary id that is currently cached, unlike
+   * `readQuery` which will only read from the root query.
+   *
+   * You must pass in a GraphQL document with a single fragment or a document
+   * with multiple fragments that represent what you are reading. If you pass
+   * in a document with multiple fragments then you must also specify a
+   * `fragmentName`.
+   *
+   * @param id The root id to be used. This id should take the same form as the
+   * value returned by your `dataIdFromObject` function. If a value with your
+   * id does not exist in the store, `null` will be returned.
+   *
+   * @param fragment A GraphQL document with one or more fragments the shape of
+   * which will be used. If you provide more then one fragments then you must
+   * also specify the next argument, `fragmentName`, to select a single
+   * fragment to use when reading.
+   *
+   * @param fragmentName The name of the fragment in your GraphQL document to
+   * be used. Pass `undefined` if there is only one fragment and you want to
+   * use that.
+   *
+   * @param variables Any variables that your GraphQL fragments depend on.
+   */
+  public readFragment<FragmentType>(
+    id: string,
+    fragment: DocumentNode,
+    fragmentName?: string,
+    variables?: Object,
+  ): FragmentType | null {
+    return this.initProxy().readFragment<FragmentType>(id, fragment, fragmentName, variables);
+  }
+
+  /**
+   * Writes some data in the shape of the provided GraphQL query directly to
+   * the store. This method will start at the root query. To start at a a
+   * specific id returned by `dataIdFromObject` then use `writeFragment`.
+   *
+   * @param data The data you will be writing to the store.
+   *
+   * @param query The GraphQL query shape to be used.
+   *
+   * @param variables Any variables that the GraphQL query may depend on.
+   */
+  public writeQuery(
+    data: any,
+    query: DocumentNode,
+    variables?: Object,
+  ): void {
+    return this.initProxy().writeQuery(data, query, variables);
+  }
+
+  /**
+   * Writes some data in the shape of the provided GraphQL fragment directly to
+   * the store. This method will write to a GraphQL fragment from any arbitrary
+   * id that is currently cached, unlike `writeQuery` which will only write
+   * from the root query.
+   *
+   * You must pass in a GraphQL document with a single fragment or a document
+   * with multiple fragments that represent what you are writing. If you pass
+   * in a document with multiple fragments then you must also specify a
+   * `fragmentName`.
+   *
+   * @param data The data you will be writing to the store.
+   *
+   * @param id The root id to be used. This id should take the same form as the
+   * value returned by your `dataIdFromObject` function.
+   *
+   * @param fragment A GraphQL document with one or more fragments the shape of
+   * which will be used. If you provide more then one fragments then you must
+   * also specify the next argument, `fragmentName`, to select a single
+   * fragment to use when reading.
+   *
+   * @param fragmentName The name of the fragment in your GraphQL document to
+   * be used. Pass `undefined` if there is only one fragment and you want to
+   * use that.
+   *
+   * @param variables Any variables that your GraphQL fragments depend on.
+   */
+  public writeFragment(
+    data: any,
+    id: string,
+    fragment: DocumentNode,
+    fragmentName?: string,
+    variables?: Object,
+  ): void {
+    return this.initProxy().writeFragment(data, id, fragment, fragmentName, variables);
+  }
+
+  /**
+   * Writes some data in the shape of the provided GraphQL query directly to
+   * the store. This method will start at the root query. To start at a
+   * specific id returned by `dataIdFromObject` then use
+   * `writeFragmentOptimistically`.
+   *
+   * Unlike `writeQuery`, the data written with this method will be stored in
+   * the optimistic portion of the cache and so will not be persisted. This
+   * optimistic write may also be rolled back with the `rollback` function that
+   * was returned.
+   *
+   * @param data The data you will be writing to the store.
+   *
+   * @param query The GraphQL query shape to be used.
+   *
+   * @param variables Any variables that the GraphQL query may depend on.
+   */
+  public writeQueryOptimistically(
+    data: any,
+    query: DocumentNode,
+    variables?: Object,
+  ): {
+    rollback: () => void,
+  } {
+    const optimisticWriteId = (this.optimisticWriteId++).toString();
+    this.initStore();
+    this.store.dispatch({
+      type: 'APOLLO_WRITE_OPTIMISTIC',
+      optimisticWriteId,
+      writes: [{
+        rootId: 'ROOT_QUERY',
+        result: data,
+        document: query,
+        variables: variables || {},
+      }],
+    });
+    return {
+      rollback: () => this.store.dispatch({
+        type: 'APOLLO_WRITE_OPTIMISTIC_ROLLBACK',
+        optimisticWriteId,
+      }),
+    };
+  }
+
+  /**
+   * Writes some data in the shape of the provided GraphQL fragment directly to
+   * the store. This method will write to a GraphQL fragment from any
+   * arbitrary id that is currently cached, unlike `writeQueryOptimistically`
+   * which will only write from the root query.
+   *
+   * You must pass in a GraphQL document with a single fragment or a document
+   * with multiple fragments that represent what you are writing. If you pass
+   * in a document with multiple fragments then you must also specify a
+   * `fragmentName`.
+   *
+   * Unlike `writeFragment`, the data written with this method will be stored in
+   * the optimistic portion of the cache and so will not be persisted. This
+   * optimistic write may also be rolled back with the `rollback` function that
+   * was returned.
+   *
+   * @param data The data you will be writing to the store.
+   *
+   * @param id The root id to be used. This id should take the same form as the
+   * value returned by your `dataIdFromObject` function.
+   *
+   * @param fragment A GraphQL document with one or more fragments the shape of
+   * which will be used. If you provide more then one fragments then you must
+   * also specify the next argument, `fragmentName`, to select a single
+   * fragment to use when reading.
+   *
+   * @param fragmentName The name of the fragment in your GraphQL document to
+   * be used. Pass `undefined` if there is only one fragment and you want to
+   * use that.
+   *
+   * @param variables Any variables that your GraphQL fragments depend on.
+   */
+  public writeFragmentOptimistically(
+    data: any,
+    id: string,
+    fragment: DocumentNode,
+    fragmentName?: string,
+    variables?: Object,
+  ): {
+    rollback: () => void,
+  } {
+    const optimisticWriteId = (this.optimisticWriteId++).toString();
+    this.initStore();
+    this.store.dispatch({
+      type: 'APOLLO_WRITE_OPTIMISTIC',
+      optimisticWriteId,
+      writes: [{
+        rootId: id,
+        result: data,
+        document: getFragmentQueryDocument(fragment, fragmentName),
+        variables: variables || {},
+      }],
+    });
+    return {
+      rollback: () => this.store.dispatch({
+        type: 'APOLLO_WRITE_OPTIMISTIC_ROLLBACK',
+        optimisticWriteId,
+      }),
+    };
+  }
+
   /**
    * Returns a reducer function configured according to the `reducerConfig` instance variable.
    */
@@ -457,4 +686,20 @@ export default class ApolloClient {
       queryDeduplication: this.queryDeduplication,
     });
   };
+
+  /**
+   * Initializes a data proxy for this client instance if one does not already
+   * exist and returns either a previously initialized proxy instance or the
+   * newly initialized instance.
+   */
+  private initProxy(): DataProxy {
+    if (!this.proxy) {
+      this.initStore();
+      this.proxy = new ReduxDataProxy(
+        this.store,
+        this.reduxRootSelector || defaultReduxRootSelector,
+      );
+    }
+    return this.proxy;
+  }
 }
diff --git a/src/actions.ts b/src/actions.ts
@@ -7,6 +7,10 @@ import {
   MutationQueryReducer,
 } from './data/mutationResults';
 
+import {
+  DataProxy,
+} from './data/proxy';
+
 import {
   ApolloReducer,
 } from './store';
@@ -89,6 +93,7 @@ export interface MutationInitAction {
   optimisticResponse: Object | undefined;
   extraReducers?: ApolloReducer[];
   updateQueries?: { [queryId: string]: MutationQueryReducer };
+  update?: (proxy: DataProxy, mutationResult: Object) => void;
 }
 
 export function isMutationInitAction(action: ApolloAction): action is MutationInitAction {
@@ -105,6 +110,7 @@ export interface MutationResultAction {
   mutationId: string;
   extraReducers?: ApolloReducer[];
   updateQueries?: { [queryId: string]: MutationQueryReducer };
+  update?: (proxy: DataProxy, mutationResult: Object) => void;
 }
 
 export function isMutationResultAction(action: ApolloAction): action is MutationResultAction {
@@ -141,20 +147,55 @@ export function isStoreResetAction(action: ApolloAction): action is StoreResetAc
   return action.type === 'APOLLO_STORE_RESET';
 }
 
-export type SubscriptionResultAction = {
+export interface SubscriptionResultAction {
   type: 'APOLLO_SUBSCRIPTION_RESULT';
   result: ExecutionResult;
   subscriptionId: number;
   variables: Object;
   document: DocumentNode;
   operationName: string;
   extraReducers?: ApolloReducer[];
-};
+}
 
 export function isSubscriptionResultAction(action: ApolloAction): action is SubscriptionResultAction {
   return action.type === 'APOLLO_SUBSCRIPTION_RESULT';
 }
 
+export interface DataWrite {
+  rootId: string;
+  result: any;
+  document: DocumentNode;
+  variables: Object;
+}
+
+export interface WriteAction {
+  type: 'APOLLO_WRITE';
+  writes: Array<DataWrite>;
+}
+
+export function isWriteAction(action: ApolloAction): action is WriteAction {
+  return action.type === 'APOLLO_WRITE';
+}
+
+export interface WriteActionOptimistic {
+  type: 'APOLLO_WRITE_OPTIMISTIC';
+  optimisticWriteId: string;
+  writes: Array<DataWrite>;
+}
+
+export function isWriteOptimisticAction(action: ApolloAction): action is WriteActionOptimistic {
+  return action.type === 'APOLLO_WRITE_OPTIMISTIC';
+}
+
+export interface WriteActionOptimisticRollback {
+  type: 'APOLLO_WRITE_OPTIMISTIC_ROLLBACK';
+  optimisticWriteId: string;
+}
+
+export function isWriteOptimisticRollbackAction(action: ApolloAction): action is WriteActionOptimisticRollback {
+  return action.type === 'APOLLO_WRITE_OPTIMISTIC_ROLLBACK';
+}
+
 export type ApolloAction =
   QueryResultAction |
   QueryErrorAction |
@@ -166,4 +207,7 @@ export type ApolloAction =
   MutationErrorAction |
   UpdateQueryResultAction |
   StoreResetAction |
-  SubscriptionResultAction;
+  SubscriptionResultAction |
+  WriteAction |
+  WriteActionOptimistic |
+  WriteActionOptimisticRollback;