Merge pull request #26 from vuex-orm/feature/24-schema

Feature/24 schema

Author: phortx

dist/vuex-orm-graphql.esm.js

@@ -4,15 +4,16 @@ Vuex-ORM-GraphQL is a plugin for the amazing [Vuex-ORM](https://github.com/vuex-
 Object-Relational Mapping access to the Vuex Store. Vuex-ORM-GraphQL enhances Vuex-ORM to let you sync your Vuex state
 via the Vuex-ORM models with your server via a [GraphQL API](http://graphql.org/).
 
-The plugin will automatically generate GraphQL queries and mutations based on your model definitions and thus hides
-the specifics of Network Communication, GraphQL, Caching, De- and Serialization of your Data and so on from the
-developer. Getting a record of a model from the server is as easy as calling `Product.fetch()`. This allows you to write
-sophisticated Single-Page Applications fast and efficient without worrying about GraphQL.
+The plugin will automatically generate GraphQL queries and mutations based on your model definitions and by
+reading your and GraphQL schema from your server. Thus it hides the specifics of Network Communication, GraphQL,
+Caching, De- and Serialization of your Data and so on from the developer. Getting a record of a model from the server
+is as easy as calling `Product.fetch()`. This allows you to write sophisticated Single-Page Applications fast and
+efficient without worrying about GraphQL.
 
 
 ::: warning
-You should have basic knowledge of [Vue](https://vuejs.org/), [Vuex](https://vuex.vuejs.org/) and
-[Vuex-ORM](https://vuex-orm.github.io/vuex-orm/) before reading this documentation.
+You should have basic knowledge of [GraphQL](http://graphql.org/), [Vue](https://vuejs.org/),
+[Vuex](https://vuex.vuejs.org/) and [Vuex-ORM](https://vuex-orm.github.io/vuex-orm/) before reading this documentation.
 :::
 
 

docs/guide/README.md

@@ -38,10 +38,11 @@ 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
 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.
+record is returned by looking in the arguments hash if there is a `id` field and respectively setups the query.
 
 A model related 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-GraphQL expects that the `example` query is of type `Post`. 
+is of the model type. In this example that means, that Vuex-ORM-GraphQL expects that the `example` query is of type
+`Post`.
 
 This generates the following query:
 
@@ -76,7 +77,6 @@ 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.
 
@@ -176,7 +176,6 @@ 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).
 
 
@@ -220,14 +219,5 @@ Following fields are allowed:
 
 ## Multiple or single record
 
-Vuex-ORM-GraphQL 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.
+Vuex-ORM-GraphQL will determine automatically if a single record or a connection (multiple records) is returned by a
+query/mutation via checking your GraphQL Schema. How smart is this?

docs/guide/custom-queries/README.md

@@ -23,6 +23,13 @@ the following GraphQL query is generated:
 mutation DeletePost($id: ID!) {
   deletePost(id: $id) {
     id
+    title
+    content
+    
+    user {
+      id
+      email
+    }
   }
 }
 ```

docs/guide/destroy/README.md

@@ -2,6 +2,23 @@
 
 [[toc]]
 
+## WTF?
+
+Good question, glad you asked! Maybe [this article](https://dev.to/phortx/vue-3-graphql-kj6) helps you. If not, feel
+free to join us on our [Slack Channel](https://join.slack.com/t/vuex-orm/shared_invite/enQtMzY5MzczMzI2OTgyLTAwOWEwOGRjOTFmMzZlYzdmZTJhZGU2NGFiY2U2NzBjOWE4Y2FiMWJkMjYxMTAzZDk0ZjAxNTgzZjZhY2VkZDQ) 
+for any questions and discussions.
+
+
+## Does Vuex-ORM-GraphQL know my GraphQL Schema?
+
+Yes, it does! Before the first query is sent, the plugin loads the schema from the GraphQL server and extracts different
+information like the types of the fields to use, which fields to ignore, because they're not in the schema and whether
+custom queries and mutations return a connection or a record.
+
+Further it detects differences between the Vuex-ORM model definitions and the schema.
+
+In the future there will probably be more smart consulting of your GraphQL schema, we're open for suggestions. 
+
 
 ## Is this plugin nativescript-vue compatible?
 

docs/guide/faq/README.md

@@ -5,16 +5,14 @@
 It may happen that you want fields in your Vuex-ORM model, which are not in the respective GraphQL Type.
 We call these "virtual fields" because they are only known to the Vuex-ORM and not to your backend or database.
 
-This plugin will automatically query all fields of the model, but when your GraphQL API doesn't know a field, it returns
-an error. So we have to prevent the querying of our virtual fields. For that we have the `skipFields` field in our model:
+This plugin will automatically detect which fields are not included in the schema and will not query them at all.
 
+Let's assume we have a product model with the field `parsedMarkdownContent` which is not known to our GraphQL server:
 
 ```javascript{4}
 export default class Product extends Model {
     static entity = 'products';
 
-    static skipFields = ['parsedMarkdownContent'];
-
     static fields () {
         return {
             id: this.increment(),
@@ -40,4 +38,4 @@ query Posts() {
 }
 ```
 
-As you see the `parsedMarkdownContent` field is not queried.
+As you see the `parsedMarkdownContent` field is not queried due to the fact that it's not in the GraphQL Schema.

docs/guide/virtual-fields/README.md

@@ -6,6 +6,7 @@ import Model from '../orm/model';
 import State from '@vuex-orm/core/lib/modules/State';
 import Transformer from '../graphql/transformer';
 import NameGenerator from '../graphql/name-generator';
+import Schema from '../graphql/schema';
 
 const inflection = require('inflection');
 
@@ -24,8 +25,12 @@ export default class Action {
    * @returns {Promise<any>}
    */
   protected static async mutation (name: string, variables: Data | undefined, dispatch: DispatchFunction,
-                                   model: Model, multiple: boolean = false): Promise<any> {
+                                   model: Model): Promise<any> {
     if (variables) {
+      const context: Context = Context.getInstance();
+      const schema: Schema = await context.loadSchema();
+
+      const multiple: boolean = schema.returnsConnection(schema.getMutation(name));
       const query = QueryBuilder.buildQuery('mutation', model, name, variables, multiple);
 
       // Send GraphQL Mutation

src/actions/action.ts

@@ -18,6 +18,8 @@ export default class Fetch extends Action {
    */
   public static async call ({ state, dispatch }: ActionParams, params?: ActionParams): Promise<Data> {
     const context = Context.getInstance();
+    await context.loadSchema();
+
     const model = this.getModelFromState(state);
 
     // Filter

src/actions/fetch.ts

@@ -1,5 +1,7 @@
 import { ActionParams, Arguments, Data } from '../support/interfaces';
 import Action from './action';
+import Context from '../common/context';
+import Schema from '../graphql/schema';
 
 /**
  * Mutate action for sending a custom mutation. Will be used for Model.mutate() and record.$mutate().
@@ -13,19 +15,19 @@ export default class Mutate extends Action {
    * @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, multiple, name }: ActionParams): Promise<Data> {
+  public static async call ({ state, dispatch }: ActionParams, { args, name }: ActionParams): Promise<Data> {
     if (name) {
+      const context: Context = Context.getInstance();
+      const schema: Schema = await context.loadSchema();
       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);
 
-      if (multiple === undefined) multiple = !args['id'];
-
       // Send the mutation
-      return Action.mutation(name, args, dispatch, model, multiple);
+      return Action.mutation(name, args, dispatch, model);
     } else {
       throw new Error("The mutate action requires the mutation name ('mutation') to be set");
     }

src/actions/mutate.ts

@@ -5,6 +5,7 @@ import Transformer from '../graphql/transformer';
 import { ActionParams, Data } from '../support/interfaces';
 import Action from './action';
 import NameGenerator from '../graphql/name-generator';
+import Schema from '../graphql/schema';
 
 /**
  * Query action for sending a custom query. Will be used for Model.customQuery() and record.$customQuery.
@@ -20,15 +21,17 @@ export default class Query extends Action {
    * @returns {Promise<Data>} The fetched records as hash
    */
   public static async call ({ state, dispatch }: ActionParams,
-                            { name, multiple, filter, bypassCache }: ActionParams): Promise<Data> {
+                            { name, filter, bypassCache }: ActionParams): Promise<Data> {
     if (name) {
-      const context = Context.getInstance();
+      const context: Context = Context.getInstance();
+      const schema: Schema = await context.loadSchema();
       const model = this.getModelFromState(state);
 
       // Filter
       filter = filter ? Transformer.transformOutgoingData(model, filter) : {};
 
-      if (multiple === undefined) multiple = !filter['id'];
+      // Multiple?
+      const multiple: boolean = schema.returnsConnection(schema.getQuery(name));
 
       // Build query
       const query = QueryBuilder.buildQuery('query', model, name, filter, multiple, false);