Custom queries

Author: phortx

docs/.vuepress/config.yml

@@ -25,6 +25,7 @@ themeConfig:
     - /guide/persist/
     - /guide/push/
     - /guide/destroy/
+    - /guide/custom-queries/
     - /guide/custom-mutations/
     - /guide/relationships/
     - /guide/eager-loading/

docs/guide/custom-mutations/README.md

@@ -16,8 +16,15 @@ await Post.mutate({ mutation: 'upvotePost', id: post.id });
 await Post.dispatch('mutate', { mutation: 'upvotePost', id: post.id });
 ```
 
-As you can see you have to privide the mutation name and any further arguments you want to pass. In this case we send
-the post id, but this could be anything. This generates the following query:
+As you can see you have to provide the mutation name and any further arguments you want to pass. In this case we send
+the post id, but this could be anything else. Please also notice that `record.$mutate` automatically adds the id
+of the record into the arguments list. The plugin automatically determines if there are multiple records or a single
+record is requests by looking in the arguments hash if there is a `id` field and respectively setups the query.
+
+A custom mutation is always tied to the model, so the plugin expects the return value of the custom query is of the
+model type. In this example that means, that Vuex-ORM-Apollo expects that the `upvotePost` mutation is of type `Post`.
+
+This generates the following query:
 
 
 ```graphql

docs/guide/custom-queries/README.md

@@ -0,0 +1,57 @@
+# Custom Queries
+
+[[toc]]
+
+
+You may sometimes want to send custom GraphQL query. We support this via the `query` action. However please notice that
+the convenienceMethods here are named `customMutation` and `$customMutation` due to a name conflict with the `query()`
+method Vuex-ORM.
+
+```javascript
+const post = Post.query().first();
+await post.$customQuery({ query: 'example' });
+
+// is the same as
+await Post.customQuery({ query: 'example', id: post.id });
+
+// or
+await Post.dispatch('query', { query: 'example', id: post.id });
+```
+
+As you can see you have to provide the query name and any further arguments you want to pass. In this case we send
+the post id, but this could be anything else. Please also notice that `record.$customQuery` automatically adds the id
+of the record into the arguments list. The plugin automatically determines if there are multiple records or a single
+record is requests by looking in the arguments hash if there is a `id` field and respectively setups the query.
+
+A custom query is always tied to the model, so the plugin expects the return value of the custom query is of the model
+type. In this example that means, that Vuex-ORM-Apollo expects that the `example` query is of type `Post`. 
+
+This generates the following query:
+
+
+```graphql
+mutation Example($id: ID!) {
+  example(post: $id) {
+    id
+    userId
+    content
+    title
+
+    user {
+      id
+      email
+    }
+  }
+}
+```
+
+Variables:
+
+```json
+{
+  "id": 42
+}
+```
+
+Like for all other operations, all records which are returned replace the respective existing records in the Vuex-ORM
+database.

src/actions/fetch.ts

@@ -27,7 +27,7 @@ export default class Fetch extends Action {
     // When the filter contains an id, we query in singular mode
     const multiple: boolean = !filter['id'];
     const name: string = NameGenerator.getNameForFetch(model, multiple);
-    const query = QueryBuilder.buildQuery('query', model, name, filter, multiple);
+    const query = QueryBuilder.buildQuery('query', model, name, filter, multiple, multiple);
 
     // Send the request to the GraphQL API
     const data = await context.apollo.request(model, query, filter, false, bypassCache as boolean);

src/actions/query.ts

@@ -0,0 +1,42 @@
+import QueryBuilder from '../graphql/query-builder';
+import Context from '../common/context';
+import { Store } from '../orm/store';
+import Transformer from '../graphql/transformer';
+import { ActionParams, Data } from '../support/interfaces';
+import Action from './action';
+import NameGenerator from '../graphql/name-generator';
+
+/**
+ * Query action for sending a custom query. Will be used for Model.customQuery() and record.$customQuery.
+ */
+export default class Query extends Action {
+  /**
+   * @param {any} state The Vuex state
+   * @param {DispatchFunction} dispatch Vuex Dispatch method for the model
+   * @param {ActionParams} params Optional params to send with the query
+   * @returns {Promise<Data>} The fetched records as hash
+   */
+  public static async call ({ state, dispatch }: ActionParams, params?: ActionParams): Promise<Data> {
+    if (params && params.query) {
+      const context = Context.getInstance();
+      const model = this.getModelFromState(state);
+
+      // Filter
+      const filter = params && params.filter ? Transformer.transformOutgoingData(model, params.filter) : {};
+      const bypassCache = params && params.bypassCache;
+
+      // When the filter contains an id, we query in singular mode
+      const multiple: boolean = !filter['id'];
+      const name: string = params.query;
+      const query = QueryBuilder.buildQuery('query', model, name, filter, multiple, false);
+
+      // Send the request to the GraphQL API
+      const data = await context.apollo.request(model, query, filter, false, bypassCache as boolean);
+
+      // Insert incoming data into the store
+      return Store.insertData(data, dispatch);
+    } else {
+      throw new Error("The customQuery action requires the query name ('query') to be set");
+    }
+  }
+}

src/graphql/query-builder.ts

@@ -28,13 +28,14 @@ export default class QueryBuilder {
                      args?: Arguments,
                      ignoreModels: Array<Model> = [],
                      name?: string,
+                     filter: boolean = false,
                      allowIdFields: boolean = false): string {
 
     const context = Context.getInstance();
     model = context.getModel(model);
     ignoreModels.push(model);
 
-    let params: string = this.buildArguments(model, args, false, multiple, allowIdFields);
+    let params: string = this.buildArguments(model, args, false, filter, allowIdFields);
 
     const fields = `
       ${model.getQueryFields().join(' ')}
@@ -66,9 +67,11 @@ export default class QueryBuilder {
    * @param {string} name Optional name of the query/mutation. Will overwrite the name from the model.
    * @param {Arguments} args Arguments for the query
    * @param {boolean} multiple Determines if the root query field is a connection or not (will be passed to buildField)
+   * @param {boolean} filter When true the query arguments are passed via a filter object.
    * @returns {any} Whatever gql() returns
    */
-  public static buildQuery (type: string, model: Model | string, name?: string, args?: Arguments, multiple?: boolean) {
+  public static buildQuery (type: string, model: Model | string, name?: string, args?: Arguments, multiple?: boolean,
+                            filter?: boolean) {
     const context = Context.getInstance();
 
     // model
@@ -94,7 +97,7 @@ export default class QueryBuilder {
     // build query
     const query: string =
       `${type} ${upcaseFirstLetter(name)}${this.buildArguments(model, args, true, false)} {\n` +
-      `  ${this.buildField(model, multiple, args, [], name, true)}\n` +
+      `  ${this.buildField(model, multiple, args, [], name, filter, true)}\n` +
       `}`;
 
     return gql(query);
@@ -234,7 +237,7 @@ export default class QueryBuilder {
         const multiple: boolean = !(field instanceof context.components.BelongsTo ||
           field instanceof context.components.HasOne);
 
-        relationQueries.push(this.buildField(relatedModel, multiple, undefined, ignoreModels, name));
+        relationQueries.push(this.buildField(relatedModel, multiple, undefined, ignoreModels, name, false));
       }
     });
 

src/support/interfaces.ts

@@ -25,6 +25,7 @@ export interface ActionParams {
   data?: Data;
   args?: Arguments;
   bypassCache?: boolean;
+  query?: string;
 }
 
 export interface Data {
@@ -47,6 +48,7 @@ export interface Field {
 }
 
 export class PatchedModel extends ORMModel {
-  static async fetch (filter: any, bypassCache = false): Promise<any> { return undefined; }
+  static async fetch (filter: any, bypassCache: boolean = false): Promise<any> { return undefined; }
   static async mutate (params: any): Promise<any> { return undefined; }
+  static async customQuery (query: string, params: any, bypassCache: boolean = false): Promise<any> { return undefined; }
 }

src/vuex-orm-apollo.ts

@@ -2,6 +2,7 @@ import { PatchedModel, Options } from './support/interfaces';
 import Context from './common/context';
 import { Components } from '@vuex-orm/core/lib/plugins/use';
 import { Destroy, Fetch, Mutate, Persist, Push } from './actions';
+import Query from './actions/query';
 
 /**
  * Main class of the plugin. Setups the internal context, Vuex actions and model methods
@@ -29,11 +30,12 @@ export default class VuexORMApollo {
     context.components.subActions.push = Push.call.bind(Push);
     context.components.subActions.destroy = Destroy.call.bind(Destroy);
     context.components.subActions.mutate = Mutate.call.bind(Mutate);
+    context.components.subActions.query = Query.call.bind(Query);
   }
 
   /**
-   * This method will setup following model methods: Model.fetch, Model.mutate, record.$mutate, record.$persist,
-   * record.$push, record.$destroy and record.$deleteAndDestroy
+   * This method will setup following model methods: Model.fetch, Model.mutate, Model.customQuery, record.$mutate,
+   * record.$persist, record.$push, record.$destroy and record.$deleteAndDestroy, record.$customQuery
    */
   private static setupModelMethods () {
     const context = Context.getInstance();
@@ -49,6 +51,11 @@ export default class VuexORMApollo {
       return this.dispatch('mutate', params);
     };
 
+    (context.components.Model as (typeof PatchedModel)).customQuery = async function (query: string, filter: any,
+                                                                                      bypassCache = false) {
+      return this.dispatch('query', { query, filter, bypassCache });
+    };
+
     // Register model convenience methods
     const model = context.components.Model.prototype;
 
@@ -57,6 +64,11 @@ export default class VuexORMApollo {
       return this.$dispatch('mutate', params);
     };
 
+    model.$customQuery = async function (query: string, filter: any, bypassCache: boolean = false) {
+      if (!filter['id']) filter['id'] = this.id;
+      return this.$dispatch('query', { query, filter, bypassCache });
+    };
+
     model.$persist = async function (args: any) {
       return this.$dispatch('persist', { id: this.id, args });
     };

test/integration/VuexORMApollo.spec.js

@@ -357,6 +357,133 @@ mutation DeleteUser($id: ID!) {
   });
 
 
+  describe('custom query', () => {
+    it('via Model method sends the correct query to the API', async () => {
+      const response = {
+        data: {
+          unpublishedPosts: {
+            nodes: [
+              {
+                __typename: 'post',
+                id: 1,
+                otherId: 13548,
+                published: false,
+                title: 'Example Post 1',
+                content: 'Foo',
+                comments: {
+                  __typename: 'comment',
+                  nodes: []
+                },
+                user: {
+                  __typename: 'user',
+                  id: 2,
+                  name: 'Johnny Imba',
+                }
+              }
+            ],
+            __typename: 'post'
+          }
+        }
+      };
+
+      const request = await sendWithMockFetch(response, async () => {
+        await Post.customQuery('unpublishedPosts', { userId: 2 });
+      });
+
+      expect(request.variables.userId).toEqual(2);
+      expect(request.query).toEqual(`
+query UnpublishedPosts($userId: ID!) {
+  unpublishedPosts(userId: $userId) {
+    nodes {
+      id
+      content
+      title
+      otherId
+      published
+      user {
+        id
+        name
+        __typename
+      }
+      comments {
+        nodes {
+          id
+          content
+          subjectId
+          subjectType
+          __typename
+        }
+        __typename
+      }
+      __typename
+    }
+    __typename
+  }
+}
+      `.trim() + "\n");
+    });
+
+    it('via record method sends the correct query to the API', async () => {
+      const post = Post.find(1);
+      const response = {
+        data: {
+          example: {
+            __typename: 'post',
+            id: 1,
+            otherId: 13548,
+            published: false,
+            title: 'Example Post 1',
+            content: 'Foo',
+            comments: {
+              __typename: 'comment',
+              nodes: []
+            },
+            user: {
+              __typename: 'user',
+              id: 2,
+              name: 'Johnny Imba',
+            }
+          }
+        }
+      };
+
+      const request = await sendWithMockFetch(response, async () => {
+        await post.$customQuery('example', { userId: 2 });
+      });
+
+      expect(request.variables.userId).toEqual(2);
+      expect(request.variables.id).toEqual(1);
+      expect(request.query).toEqual(`
+query Example($userId: ID!, $id: ID!) {
+  example(userId: $userId, id: $id) {
+    id
+    content
+    title
+    otherId
+    published
+    user {
+      id
+      name
+      __typename
+    }
+    comments {
+      nodes {
+        id
+        content
+        subjectId
+        subjectType
+        __typename
+      }
+      __typename
+    }
+    __typename
+  }
+}
+      `.trim() + "\n");
+    });
+  });
+
+
   describe('custom mutation', () => {
     it('sends the correct query to the API', async () => {
       const post = Post.find(1);

test/unit/QueryBuilder.spec.js

@@ -84,7 +84,7 @@ query test {
 
   describe('.buildField', () => {
     it('generates query fields for all model fields and relations', () => {
-      let query = QueryBuilder.buildField(context.getModel('user'), true, { age: 32 });
+      let query = QueryBuilder.buildField(context.getModel('user'), true, { age: 32 }, undefined, undefined, true);
       query = prettify(`query users { ${query} }`).trim();
 
       expect(query).toEqual(`
@@ -106,7 +106,7 @@ query users {
     it('generates a complete query for a model', () => {
       const args = { title: 'Example Post 1' };
 
-      let query = QueryBuilder.buildQuery('query', context.getModel('post'), null, args, true);
+      let query = QueryBuilder.buildQuery('query', context.getModel('post'), null, args, true, true);
       query = prettify(query.loc.source.body);
 
       expect(query).toEqual(`