Feature 87: Adapters (#89)

Author: phortx

dist/vuex-orm-graphql.es5.js

@@ -30,7 +30,6 @@ module.exports = {
         collapsable: false,
         children: [
           '/guide/setup',
-          '/guide/graphql',
           '/guide/fetch',
           '/guide/persist',
           '/guide/push',
@@ -43,6 +42,7 @@ module.exports = {
         title: 'Advanced Topics',
         collapsable: false,
         children: [
+          '/guide/adapters',
           '/guide/connection-mode',
           '/guide/custom-queries',
           '/guide/eager-loading',

dist/vuex-orm-graphql.es5.js.map

@@ -1,12 +1,12 @@
 # Introduction
 
-Vuex-ORM-GraphQL is a plugin for the amazing [Vuex-ORM](https://github.com/vuex-orm/vuex-orm), which brings
+Vuex-ORM/Plugin-GraphQL is a plugin for the amazing [Vuex-ORM](https://github.com/vuex-orm/vuex-orm), which brings
 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 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
+The plugin will automatically generate GraphQL queries and mutations on the fly based on your model definitions and by
+reading the 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.
 
@@ -91,16 +91,18 @@ After [installing](setup.md) this plugin you can load data in your component:
 ```
 
 ::: tip
-Vuex-ORM-GraphQL works with the [Apollo Dev Tools](https://chrome.google.com/webstore/detail/apollo-client-developer-t/jdkknkkbebbapilgoeccciglkfbmbnfm)!
+This plugin works with the [Apollo Dev Tools](https://chrome.google.com/webstore/detail/apollo-client-developer-t/jdkknkkbebbapilgoeccciglkfbmbnfm)!
 :::
 
 
-## Connection Mode
+## Adapters
 
-It seems that there are several standards within the GraphQL community how connections (fields that returns multiple
-records) are designed. Some do this via a `nodes` field, some via a `edges { nodes }` query and some do neither of them.
-Vuex-ORM-GraphQL tries to be flexible and supports all of them, but the example queries in the documentation work with
-the `nodes` query, don't be irritated. You'll find [more details here](connection-mode.md).
+It seems that there are several standards within the GraphQL community how the schema is designed.
+Some do connections via a `nodes` field, some via a `edges { nodes }` query and some do neither of them.
+Some work with Input Types and some with plain parameter lists. This plugin supports all of them via
+a adapter pattern. There is a default adapter and all example queries in this documentation are
+generated by the DefaultAdapter but that doesn't mean the queries are tied to this format.
+When you have to customize it, you'll find how to do so in the [respective chapter](adapters.md).
 
 
 ## License

dist/vuex-orm-graphql.umd.js

@@ -0,0 +1,146 @@
+# Adapters
+
+[[toc]]
+
+There is not single true way to design a GraphQL schema and thus there are 
+some small differences between the implementations, however this plugin has to automatically
+generate GraphQL queries, has to parse the schema and de-/serialize the data. Thus we needed a way
+to customize how this plugin should behave and communicate with the API. For this we implemented an
+adapter pattern, which allows you to setup your own adapter and customize it.
+
+
+## Basics
+
+Every adapter has to implement the `Adapter` interface (when your're working with TypeScript).
+However it's easier to just inherit from the DefaultAdapter:
+
+`data/custom-adapter.js`:
+```javascript
+import DefaultAdapter from '@vuex-orm/plugin-graphql';
+
+export default class CustomAdapter extends DefaultAdapter {
+  // Your code here
+}
+``` 
+
+Then register this adapter when setting up the plugin:
+
+`data/store.js`:
+```javascript
+import CustomAdapter from './custom-adapter.ts'; 
+
+// ...
+
+VuexORM.use(VuexORMGraphQL, {
+  database,
+  adapter: CustomAdapter,
+});
+```
+
+
+That's it. In the next sections you can read what and how you can customize the adapter.
+
+
+## Methods
+
+Each Adapter has to implement a bunch of methods. Here is the list of the currently supported
+method signatures and their value in the default adapter:
+
+- `getRootQueryName(): string;`
+    - Returns the name of the type all query types inherit.
+    - Default adapter value: `Query`
+
+- `getRootMutationName(): string;`
+    - Returns the name of the type all mutation types inherit.
+    - Default adapter value: `Mutation`
+
+- `getNameForPersist(model: Model): string;`
+    - Returns the mutation name for persisting (creating) a record.
+    - Default adapter value example: `createPost`
+    - `model` is a instance of [Model](https://github.com/vuex-orm/plugin-graphql/blob/master/src/orm/model.ts)
+    
+- `getNameForPush(model: Model): string;`
+    - Returns the mutation name for pushing (updating) a record.
+    - Default adapter value example: `updatePost`
+    - `model` is a instance of [Model](https://github.com/vuex-orm/plugin-graphql/blob/master/src/orm/model.ts)
+   
+- `getNameForDestroy(model: Model): string;`
+    - Returns the mutation name for destroying a record.
+    - Default adapter value example: `deletePost`
+    - `model` is a instance of [Model](https://github.com/vuex-orm/plugin-graphql/blob/master/src/orm/model.ts)
+   
+- `getNameForFetch(model: Model, plural: boolean): string;`
+    - Returns the query field for fetching a record.
+    - Default adapter value example: `posts` or `post`
+    - `model` is a instance of [Model](https://github.com/vuex-orm/plugin-graphql/blob/master/src/orm/model.ts)
+    - `plural` tells if one or multiple records (connection) are fetched.
+
+- `getConnectionMode(): ConnectionMode;`
+    - Returns the [ConnectionMode](connection-mode.md).
+    - Default adapter value: `AUTO`
+
+- `getArgumentMode(): ArgumentMode;`
+    - Returns the ArgumentMode for filtering and inputs (push, persist).
+    - Default adapter value: `TYPE`
+
+- `getFilterTypeName(model: Model): string;`
+    - Returns the name of the filter type for a model.
+    - `model` is a instance of [Model](https://github.com/vuex-orm/plugin-graphql/blob/master/src/orm/model.ts)
+    - Default adapter value example: `PostFilter`
+    
+- `getInputTypeName(model: Model, action?: string): string;`
+    - Returns the name of the input type for a model.
+    - `model` is a instance of [Model](https://github.com/vuex-orm/plugin-graphql/blob/master/src/orm/model.ts)
+    - Default adapter value example: `PostInput`
+
+
+## ArgumentMode
+
+The `getArgumentMode()` methods determines the ArgumentMode, which knows to options: `LIST` and `TYPE`.
+It tells the plugin how arguments should be passed to queries and mutations.
+
+
+### `TYPE`
+
+`TYPE` is the value in the default adapter and causes the plugin to use a `Input` or `Filter` type:
+
+For `$persist()`:
+```
+mutation CreatePost($post: PostInput!) {
+  createPost(post: $post) {
+    ...
+  }
+}
+```
+
+For `fetch()`:
+```
+query Posts($title: String!) {
+  posts(filter: {title: $title}) {
+    ...
+  }
+}
+```
+
+
+### `LIST`
+
+`LIST` causes the plugin to use plain lists:
+
+For `$persist()`:
+```
+mutation CreatePost($id: ID!, $authorId: ID!, $title: String!, $content: String!) {
+  createPost(id: $id, authorId: $authorId, title: $title, content: $content) {
+    ...
+  }
+}
+```
+
+For `fetch()`:
+```
+query Posts($title: String!) {
+  posts(title: $title) {
+    ...
+  }
+}
+```

dist/vuex-orm-graphql.umd.js.map

@@ -4,20 +4,22 @@
 
 It seems that there are several standards within the GraphQL community how connections (fields that returns multiple
 records) are designed. Some do this via a `nodes` field, some via a `edges { nodes }` query and some do neither of them.
-Vuex-ORM-GraphQL tries to be flexible and supports all of them, but the example queries in the documentation work with
-the `nodes` query, don't be irritated.
+Vuex-ORM-GraphQL tries to be flexible and supports all of them.
+
+There are four possible modes: `AUTO`, `NODES`, `EDGES`, `PLAIN`. The Adapter you use will tell the
+plugin which ConnectionMode to use. In the DefaultAdapter this is `AUTO`.
 
 
 ## Automatic detection
 
-The plugin will try to detect automatically which mode should be used by analyzing the GraphQL Schema. In the best
-case you don't have to bother with this at all.
+The plugin will try to detect automatically which mode should be used by analyzing the GraphQL
+Schema. In the best case you don't have to bother with this at all.
 
 
 ## Manual setting
 
-In rare cases the automatic detection might fail or report the wrong mode. In this case, you can manually set the
-`connectionQueryMode` config param to either `auto` (default), `nodes`, `edges`, `plain`. The modes and the resulting
+In rare cases the automatic detection might fail or report the wrong mode. In this case, you can
+manually set the connection mode via a custom adapter. The modes and the resulting
 queries are explained in the next sections.
 
 

docs/.vuepress/config.js

@@ -65,3 +65,9 @@ Like when pushing, all records which are returned replace the respective existin
 
 You can pass a object like this: `$perist({ captchaToken: 'asdfasdf' })`. All fields in the object will be passed as
 variables to the mutation.
+
+
+## Relationships
+
+When persisting a record, all `belongsTo` relations are sent to the server too. `hasMany`/`hasOne`
+relations on the other hand are filtered out and have to be persisted on their own.