Change API for custom mutations and queries

phortx · phortx · commit 72c27efb5f66 · 2018-06-10T11:37:29.000+02:00
and added multiple field
diff --git a/dist/vuex-orm-apollo.esm.js b/dist/vuex-orm-apollo.esm.js
@@ -10551,22 +10551,32 @@ var Mutate = /** @class */ (function (_super) {
     /**
      * @param {any} state The Vuex state
      * @param {DispatchFunction} dispatch Vuex Dispatch method for the model
+     * @param {string} name Name of the query
+     * @param {boolean} multiple Fetch one or multiple?
      * @param {Arguments} args Arguments for the mutation. Must contain a 'mutation' field.
      * @returns {Promise<Data>} The new record if any
      */
-    Mutate.call = function (_a, args) {
+    Mutate.call = function (_a, _b) {
         var state = _a.state, dispatch = _a.dispatch;
+        var args = _b.args, multiple = _b.multiple, name = _b.name;
         return __awaiter$5(this, void 0, void 0, function () {
-            var model, mutationName;
-            return __generator$5(this, function (_b) {
-                model = this.getModelFromState(state);
-                mutationName = args['mutation'];
-                delete args['mutation'];
-                // There could be anything in the args, but we have to be sure that all records are gone through
-                // transformOutgoingData()
-                this.transformArgs(args);
-                // Send the mutation
-                return [2 /*return*/, Action.mutation(mutationName, args, dispatch, model, !args['id'])];
+            var model;
+            return __generator$5(this, function (_c) {
+                if (name) {
+                    model = this.getModelFromState(state);
+                    args = this.prepareArgs(args);
+                    // There could be anything in the args, but we have to be sure that all records are gone through
+                    // transformOutgoingData()
+                    this.transformArgs(args);
+                    if (multiple === undefined)
+                        multiple = !args['id'];
+                    // Send the mutation
+                    return [2 /*return*/, Action.mutation(name, args, dispatch, model, multiple)];
+                }
+                else {
+                    throw new Error("The mutate action requires the mutation name ('mutation') to be set");
+                }
+                return [2 /*return*/];
             });
         });
     };
@@ -10824,30 +10834,34 @@ var Query = /** @class */ (function (_super) {
     /**
      * @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
+     * @param {string} name Name of the query
+     * @param {boolean} multiple Fetch one or multiple?
+     * @param {object} filter Filter object (arguments)
+     * @param {boolean} bypassCache Whether to bypass the cache
      * @returns {Promise<Data>} The fetched records as hash
      */
-    Query.call = function (_a, params) {
+    Query.call = function (_a, _b) {
         var state = _a.state, dispatch = _a.dispatch;
+        var name = _b.name, multiple = _b.multiple, filter = _b.filter, bypassCache = _b.bypassCache;
         return __awaiter$8(this, void 0, void 0, function () {
-            var context, model, filter, bypassCache, multiple, name_1, query, data;
-            return __generator$8(this, function (_b) {
-                switch (_b.label) {
+            var context, model, query, data;
+            return __generator$8(this, function (_c) {
+                switch (_c.label) {
                     case 0:
-                        if (!(params && params.query)) return [3 /*break*/, 2];
+                        if (!name) return [3 /*break*/, 2];
                         context = Context.getInstance();
                         model = this.getModelFromState(state);
-                        filter = params && params.filter ? Transformer.transformOutgoingData(model, params.filter) : {};
-                        bypassCache = params && params.bypassCache;
-                        multiple = !filter['id'];
-                        name_1 = params.query;
-                        query = QueryBuilder.buildQuery('query', model, name_1, filter, multiple, false);
+                        // Filter
+                        filter = filter ? Transformer.transformOutgoingData(model, filter) : {};
+                        if (multiple === undefined)
+                            multiple = !filter['id'];
+                        query = QueryBuilder.buildQuery('query', model, name, filter, multiple, false);
                         return [4 /*yield*/, context.apollo.request(model, query, filter, false, bypassCache)];
                     case 1:
-                        data = _b.sent();
+                        data = _c.sent();
                         // Insert incoming data into the store
                         return [2 /*return*/, Store.insertData(data, dispatch)];
-                    case 2: throw new Error("The customQuery action requires the query name ('query') to be set");
+                    case 2: throw new Error("The customQuery action requires the query name ('name') to be set");
                 }
             });
         });
@@ -11107,32 +11121,35 @@ var VuexORMApollo = /** @class */ (function () {
                 });
             });
         };
-        context.components.Model.customQuery = function (query, filter, bypassCache) {
-            if (bypassCache === void 0) { bypassCache = false; }
+        context.components.Model.customQuery = function (_a) {
+            var name = _a.name, filter = _a.filter, multiple = _a.multiple, bypassCache = _a.bypassCache;
             return __awaiter$11(this, void 0, void 0, function () {
-                return __generator$11(this, function (_a) {
-                    return [2 /*return*/, this.dispatch('query', { query: query, filter: filter, bypassCache: bypassCache })];
+                return __generator$11(this, function (_b) {
+                    return [2 /*return*/, this.dispatch('query', { name: name, filter: filter, multiple: multiple, bypassCache: bypassCache })];
                 });
             });
         };
         // Register model convenience methods
         var model = context.components.Model.prototype;
-        model.$mutate = function (params) {
+        model.$mutate = function (_a) {
+            var name = _a.name, args = _a.args, multiple = _a.multiple;
             return __awaiter$11(this, void 0, void 0, function () {
-                return __generator$11(this, function (_a) {
-                    if (!params['id'])
-                        params['id'] = this.id;
-                    return [2 /*return*/, this.$dispatch('mutate', params)];
+                return __generator$11(this, function (_b) {
+                    args = args || {};
+                    if (!args['id'])
+                        args['id'] = this.id;
+                    return [2 /*return*/, this.$dispatch('mutate', { name: name, args: args, multiple: multiple })];
                 });
             });
         };
-        model.$customQuery = function (query, filter, bypassCache) {
-            if (bypassCache === void 0) { bypassCache = false; }
+        model.$customQuery = function (_a) {
+            var name = _a.name, filter = _a.filter, multiple = _a.multiple, bypassCache = _a.bypassCache;
             return __awaiter$11(this, void 0, void 0, function () {
-                return __generator$11(this, function (_a) {
+                return __generator$11(this, function (_b) {
+                    filter = filter || {};
                     if (!filter['id'])
                         filter['id'] = this.id;
-                    return [2 /*return*/, this.$dispatch('query', { query: query, filter: filter, bypassCache: bypassCache })];
+                    return [2 /*return*/, this.$dispatch('query', { name: name, filter: filter, multiple: multiple, bypassCache: bypassCache })];
                 });
             });
         };
diff --git a/docs/guide/custom-queries/README.md b/docs/guide/custom-queries/README.md
@@ -26,13 +26,13 @@ method Vuex-ORM.
 
 ```javascript
 const post = Post.query().first();
-await post.$customQuery({ query: 'example' });
+await post.$customQuery({ name: 'example' });
 
 // is the same as
-await Post.customQuery({ query: 'example', id: post.id });
+await Post.customQuery({ name: 'example', filter: { id: post.id } });
 
 // or
-await Post.dispatch('query', { query: 'example', id: post.id });
+await Post.dispatch('query', { name: 'example', filter: { 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
@@ -73,6 +73,13 @@ Variables:
 Like for all other operations, all records which are returned replace the respective existing records in the Vuex-ORM
 database.
 
+Following fields are allowed:
+
+- `name`: Required. The name of the query.
+- `multiple`: Whether the query is of a connection type (multiple records are returned) or not (single record is returned).
+- `filter`: Hash map with filters. These are passed as a filter typed variable like in fetch.
+- `bypassCache`: Whether to bypass the caching.
+
 
 ## Model unrelated simple query
 
@@ -104,20 +111,26 @@ The result contains a hash which is shaped like the request:
 
 Nothing is inserted in the Vuex store.
 
+Following fields are allowed:
+
+- `query`: Required. The GraphQL query.
+- `variables`: Variables to pass
+- `bypassCache`: Whether to bypass the caching.
+
 
 ## Model related custom mutation
 
 Along with the CRUD mutations you may want to send custom GraphQL mutations. We support this via the `mutate` action:
 
 ```javascript
 const post = Post.query().first();
-await post.$mutate({ mutation: 'upvotePost' });
+await post.$mutate({ name: 'upvotePost' });
 
 // is the same as
-await Post.mutate({ mutation: 'upvotePost', id: post.id });
+await Post.mutate({ name: 'upvotePost', args: { id: post.id } });
 
 // or
-await Post.dispatch('mutate', { mutation: 'upvotePost', id: post.id });
+await Post.dispatch('mutate', { name: 'upvotePost', args: { id: post.id } });
 ```
 
 As you can see you have to provide the mutation name and any further arguments you want to pass. In this case we send
@@ -160,6 +173,13 @@ Like for all other operations, all records which are returned replace the respec
 database.
 
 
+Following fields are allowed:
+
+- `name`: Required. The name of the mutation.
+- `multiple`: Whether the mutation is of a connection type (multiple records are returned) or not (single record is returned).
+- `args`: Hash map with arguments (variables).
+
+
 ## Model unrelated simple mutation
 
 Like simple custom queries, you can also send simple custom mutations. The action (`simpleQuery`) stays the same.
@@ -191,3 +211,23 @@ The result contains a hash which is shaped like the request:
 ```
 
 Nothing is inserted in the Vuex store.
+
+Following fields are allowed:
+
+- `query`: Required. The GraphQL mutation query.
+- `variables`: Hash map with variables to pass.
+
+
+## Multiple or single record
+
+Vuex-ORM-Apollo tries to determine automatically if a  single record or a connection (multiple records) is returned by
+a query/mutation via checking if a `id` field is set in the filter/args/variables. But sometimes you have a
+query/mutation without ID but it still returns a single record or vice versa. For this case you can manually set the
+`multiple` field to tell the plugin how the result is shaped:
+
+```javascript
+await Post.customQuery({ name: 'example', multiple: true, filter: { id: post.id } });
+```
+
+In future versions of this project this might be obsolete because it could consume and analyze the schema to know
+how the queries and mutations are shaped.
diff --git a/src/actions/mutate.ts b/src/actions/mutate.ts
@@ -8,19 +8,26 @@ export default class Mutate extends Action {
   /**
    * @param {any} state The Vuex state
    * @param {DispatchFunction} dispatch Vuex Dispatch method for the model
+   * @param {string} name Name of the query
+   * @param {boolean} multiple Fetch one or multiple?
    * @param {Arguments} args Arguments for the mutation. Must contain a 'mutation' field.
    * @returns {Promise<Data>} The new record if any
    */
-  public static async call ({ state, dispatch }: ActionParams, args: Arguments): Promise<Data> {
-    const model = this.getModelFromState(state);
-    const mutationName: string = args['mutation'];
-    delete args['mutation'];
+  public static async call ({ state, dispatch }: ActionParams, { args, multiple, name }: ActionParams): Promise<Data> {
+    if (name) {
+      const model = this.getModelFromState(state);
+      args = this.prepareArgs(args);
 
-    // There could be anything in the args, but we have to be sure that all records are gone through
-    // transformOutgoingData()
-    this.transformArgs(args);
+      // There could be anything in the args, but we have to be sure that all records are gone through
+      // transformOutgoingData()
+      this.transformArgs(args);
 
-    // Send the mutation
-    return Action.mutation(mutationName, args, dispatch, model, !args['id']);
+      if (multiple === undefined) multiple = !args['id'];
+
+      // Send the mutation
+      return Action.mutation(name, args, dispatch, model, multiple);
+    } else {
+      throw new Error("The mutate action requires the mutation name ('mutation') to be set");
+    }
   }
 }
diff --git a/src/actions/query.ts b/src/actions/query.ts
@@ -13,30 +13,33 @@ 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
+   * @param {string} name Name of the query
+   * @param {boolean} multiple Fetch one or multiple?
+   * @param {object} filter Filter object (arguments)
+   * @param {boolean} bypassCache Whether to bypass the cache
    * @returns {Promise<Data>} The fetched records as hash
    */
-  public static async call ({ state, dispatch }: ActionParams, params?: ActionParams): Promise<Data> {
-    if (params && params.query) {
+  public static async call ({ state, dispatch }: ActionParams,
+                            { name, multiple, filter, bypassCache }: ActionParams): Promise<Data> {
+    if (name) {
       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;
+      filter = filter ? Transformer.transformOutgoingData(model, filter) : {};
 
-      // 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);
+      if (multiple === undefined) multiple = !filter['id'];
+
+      // Build 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");
+      throw new Error("The customQuery action requires the query name ('name') to be set");
     }
   }
 }
diff --git a/src/support/interfaces.ts b/src/support/interfaces.ts
@@ -27,6 +27,8 @@ export interface ActionParams {
   variables?: Arguments;
   bypassCache?: boolean;
   query?: string;
+  multiple?: boolean;
+  name?: string;
 }
 
 export interface Data {
@@ -50,6 +52,6 @@ export interface Field {
 
 export class PatchedModel extends ORMModel {
   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; }
+  static async mutate (params: ActionParams): Promise<any> { return undefined; }
+  static async customQuery (params: ActionParams): Promise<any> { return undefined; }
 }
diff --git a/src/vuex-orm-apollo.ts b/src/vuex-orm-apollo.ts
@@ -1,4 +1,4 @@
-import { PatchedModel, Options } from './support/interfaces';
+import {PatchedModel, Options, ActionParams} 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';
@@ -52,26 +52,27 @@ export default class VuexORMApollo {
       return this.dispatch('fetch', { filter: filterObj, bypassCache });
     };
 
-    (context.components.Model as (typeof PatchedModel)).mutate = async function (params: any) {
+    (context.components.Model as (typeof PatchedModel)).mutate = async function (params: ActionParams) {
       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 });
+    (context.components.Model as (typeof PatchedModel)).customQuery = async function ({ name, filter, multiple, bypassCache }: ActionParams) {
+      return this.dispatch('query', { name, filter, multiple, bypassCache });
     };
 
     // Register model convenience methods
     const model = context.components.Model.prototype;
 
-    model.$mutate = async function (params: any) {
-      if (!params['id']) params['id'] = this.id;
-      return this.$dispatch('mutate', params);
+    model.$mutate = async function ({ name, args, multiple }: ActionParams) {
+      args = args || {};
+      if (!args['id']) args['id'] = this.id;
+      return this.$dispatch('mutate', { name, args, multiple });
     };
 
-    model.$customQuery = async function (query: string, filter: any, bypassCache: boolean = false) {
+    model.$customQuery = async function ({ name, filter, multiple, bypassCache }: ActionParams) {
+      filter = filter || {};
       if (!filter['id']) filter['id'] = this.id;
-      return this.$dispatch('query', { query, filter, bypassCache });
+      return this.$dispatch('query', { name, filter, multiple, bypassCache });
     };
 
     model.$persist = async function (args: any) {
diff --git a/test/integration/VuexORMApollo.spec.js b/test/integration/VuexORMApollo.spec.js
