Query components + loading + provider improvements

Author: Guillaume Chau

README.md

@@ -2,14 +2,16 @@
 
 [![npm](https://img.shields.io/npm/v/vue-apollo/next.svg) ![npm](https://img.shields.io/npm/dm/vue-apollo.svg)](https://www.npmjs.com/package/vue-apollo)
 [![vue1](https://img.shields.io/badge/apollo-2.x-blue.svg)](https://www.apollographql.com/)
-[![vue1](https://img.shields.io/badge/vue-1.x-brightgreen.svg) ![vue2](https://img.shields.io/badge/vue-2.x-brightgreen.svg)](https://vuejs.org/)
+[![vue1](https://img.shields.io/badge/vue-1.x-brightgreen.svg) ![vue2](https://img.shields.io/badge/vue-2.2+-brightgreen.svg)](https://vuejs.org/)
 
 ![schema](https://cdn-images-1.medium.com/max/800/1*H9AANoofLqjS10Xd5TwRYw.png)
 
 **Warning! This README is related to the next version of vue-apollo (that supports Apollo 2.x). For the old release (supporting only Apollo 1.x), see [here](https://github.com/Akryum/vue-apollo/tree/master).**
 
 Integrates [apollo](https://www.apollographql.com/) in your [Vue](http://vuejs.org) components with declarative queries. Compatible with Vue 1.0+ and 2.0+. [Live demo](https://jsfiddle.net/Akryum/oyejk2qL/)
 
+[<img src="https://assets-cdn.github.com/favicon.ico" alt="icon" width="16" height="16"/> Vue-cli plugin](https://github.com/Akryum/vue-cli-plugin-apollo)
+
 [<img src="https://assets-cdn.github.com/favicon.ico" alt="icon" width="16" height="16"/> More vue-apollo examples](https://github.com/Akryum/vue-apollo-example)
 
 [<img src="https://assets-cdn.github.com/favicon.ico" alt="icon" width="16" height="16"/> Apollo graphql server example](https://github.com/Akryum/apollo-server-example)
@@ -28,6 +30,7 @@ Integrates [apollo](https://www.apollographql.com/) in your [Vue](http://vuejs.o
 - [Queries](#queries)
   - [Simple query](#simple-query)
   - [Query with parameters](#query-with-parameters)
+  - [Loading state](#loading-state)
   - [Option function](#option-function)
   - [Reactive query definition](#reactive-query-definition)
   - [Reactive parameters](#reactive-parameters)
@@ -46,14 +49,17 @@ Integrates [apollo](https://www.apollographql.com/) in your [Vue](http://vuejs.o
 - [Skip all](#skip-all)
 - [Multiple clients](#multiple-clients)
 - [Server-Side Rendering](#server-side-rendering)
+- [Query Components](#query-components)
 - [Migration](#migration)
 - [API Reference](#api-reference)
 
 ## Installation
 
+**If you are using vue-cli 3.x, you can [use this vue-cli plugin](https://github.com/Akryum/vue-cli-plugin-apollo) to get started in a few minutes!**
+
 Try and install these packages before server side set (of packages), add apollo to meteor.js before then, too.
 
-    npm install --save vue-apollo@next graphql apollo-client apollo-link apollo-link-http apollo-cache-inmemory graphql-tag
+    npm install --save vue-apollo graphql apollo-client apollo-link apollo-link-http apollo-cache-inmemory graphql-tag
 
 In your app, create an `ApolloClient` instance and install the `VueApollo` plugin:
 
@@ -91,7 +97,7 @@ const apolloProvider = new VueApollo({
 
 new Vue({
   el: '#app',
-  apolloProvider,
+  provide: apolloProvider.provide(),
   render: h => h(App),
 })
 ```
@@ -267,12 +273,26 @@ And then use it in your vue component:
   <div class="apollo">
     <h3>Ping</h3>
     <p>
-      {{ping}}
+      {{ ping }}
     </p>
   </div>
 </template>
 ```
 
+### Loading state
+
+You can display a loading state thanks to the `$apollo.loading` prop:
+
+```html
+<div v-if="$apollo.loading">Loading...</div>
+```
+
+Or for this specific `ping` query:
+
+```html
+<div v-if="$apollo.queries.ping.loading">Loading...</div>
+```
+
 ### Option function
 
 You can use a function to initialize the key:
@@ -1260,6 +1280,14 @@ export default willPrefetch({
 })
 ```
 
+The second parameter is optional: it's a callback that gets the context and should return a boolean indicating if the component should be prefetched:
+
+```js
+willPrefetch({
+  // Component definition...
+}, context => context.url === '/foo')
+```
+
 ### On the server
 
 To prefetch all the apollo queries you marked, use the `apolloProvider.prefetchAll` method. The first argument is the context object passed to the `prefetch` hooks (see above). It is recommended to pass the vue-router `currentRoute` object. The second argument is the array of component definition to include (e.g. from `router.getMatchedComponents` method). The third argument is an optional `options` object. It returns a promise resolved when all the apollo queries are loaded.
@@ -1492,6 +1520,89 @@ router.onReady(() => {
 })
 ```
 
+## Query components
+
+(WIP) You can use the `ApolloQuery` (or `apollo-query`) component to make watched Apollo queries directly in your template:
+
+```html
+<ApolloQuery
+  :query="require('../graphql/HelloWorld.gql')"
+  :variables="{ name }"
+>
+  <template slot-scope="{ result: { loading, error, data } }">
+    <!-- Loading -->
+    <div v-if="loading" class="loading apollo">Loading...</div>
+
+    <!-- Error -->
+    <div v-else-if="error" class="error apollo">An error occured</div>
+
+    <!-- Result -->
+    <div v-else-if="data" class="result apollo">{{ data.hello }}</div>
+
+    <!-- No result -->
+    <div v-else class="no-result apollo">No result :(</div>
+  </template>
+</ApolloQuery>
+```
+
+Props:
+
+- `query`: GraphQL query (transformed by `graphql-tag`)
+- `variables`: Object of GraphQL variables
+- `fetchPolicy`: See [apollo fetchPolicy](https://www.apollographql.com/docs/react/basics/queries.html#graphql-config-options-fetchPolicy)
+- `pollInterval`: See [apollo pollInterval](https://www.apollographql.com/docs/react/basics/queries.html#graphql-config-options-pollInterval)
+- `notifyOnNetworkStatusChange`: See [apollo notifyOnNetworkStatusChange](https://www.apollographql.com/docs/react/basics/queries.html#graphql-config-options-notifyOnNetworkStatusChange)
+- `context`: See [apollo context](https://www.apollographql.com/docs/react/basics/queries.html#graphql-config-options-context)
+- `skip`: Boolean disabling query fetching
+- `clienId`: Used to resolve the Apollo Client used (defined in ApolloProvider)
+- `tag`: String HTML tag name (default: `div`)
+
+Scoped slot props:
+- `result`: Apollo Query result
+  - `result.data`: Data returned by the query
+  - `result.loading`: Boolean indicating that a request is in flight
+  - `result.error`: Eventual error for the current result
+  - `result.networkStatus`: See [apollo networkStatus](https://www.apollographql.com/docs/react/basics/queries.html#graphql-query-data-networkStatus)
+- `query`: Smart Query associated with the component
+
+(WIP) You can subscribe to mode data with the `ApolloSubscribeToMore` (or `apollo-subscribe-to-more`) component:
+
+```html
+<template>
+  <ApolloQuery>
+    <ApolloSubscribeToMore
+      :document="require('../gql/MessageAdded.gql')"
+      :variables="{ channel }"
+      :updateQuery="onMessageAdded"
+    />
+  </ApolloQuery>
+</template>
+
+<script>
+export default {
+  data () {
+    return {
+      channel: 'general',
+    }
+  },
+
+  methods: {
+    onMessageAdded (previousResult, { subscriptionData }) {
+      // The previous result is immutable
+      const newResult = {
+        messages: [...previousResult.messages],
+      }
+      // Add the question to the list
+      newResult.messages.push(subscriptionData.data.messageAdded)
+      return newResult
+    },
+  },
+}
+</script>
+```
+
+*You can put as many of those as you want inside a `<ApolloQuery>` component.*
+
 ---
 
 # Migration

build/rollup.config.base.js

@@ -7,7 +7,6 @@ const config = require('../package.json')
 
 export default {
   input: 'src/index.js',
-  name: 'vue-apollo',
   plugins: [
     resolve({
       jsnext: true,

build/rollup.config.browser.js

@@ -6,8 +6,8 @@ const config = Object.assign({}, base, {
   output: {
     file: 'dist/vue-apollo.min.js',
     format: 'iife',
+    name: 'VueApollo',
   },
-  name: 'VueApollo',
 })
 
 config.plugins.push(uglify({}, minify))

build/rollup.config.es.js

@@ -4,6 +4,7 @@ const config = Object.assign({}, base, {
   output: {
     file: 'dist/vue-apollo.esm.js',
     format: 'es',
+    name: 'vue-apollo',
   },
 })
 

build/rollup.config.umd.js

@@ -4,6 +4,7 @@ const config = Object.assign({}, base, {
   output: {
     file: 'dist/vue-apollo.umd.js',
     format: 'umd',
+    name: 'vue-apollo',
   },
 })
 

package.json

@@ -12,13 +12,11 @@
     "build:es": "rollup --config build/rollup.config.es.js",
     "build:umd": "rollup --config build/rollup.config.umd.js",
     "prepublishOnly": "npm run test && npm run build",
-    "dev": "npm-watch",
-    "test": "npm run test:types",
+    "dev": "nodemon --exec 'npm run build' --watch src",
+    "test": "npm run test:eslint && npm run test:types",
+    "test:eslint": "eslint --ext .js src",
     "test:types": "tsc -p types/test"
   },
-  "watch": {
-    "build": "src/*.js"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Akryum/vue-apollo.git"
@@ -61,7 +59,7 @@
     "eslint-plugin-standard": "^3.0.1",
     "graphql": "^0.12.3",
     "graphql-tag": "^2.5.0",
-    "npm-watch": "^0.3.0",
+    "nodemon": "^1.14.12",
     "rimraf": "^2.6.1",
     "rollup": "^0.55.3",
     "rollup-plugin-babel": "^3.0.2",

src/apollo-provider.js

@@ -16,14 +16,20 @@ export class ApolloProvider {
     this.prefetchQueries = []
   }
 
-  willPrefetchQuery (queryOptions, client) {
+  provide (key = '$apolloProvider') {
+    return {
+      [key]: this,
+    }
+  }
+
+  addQueryToPrefetch (queryOptions, client) {
     this.prefetchQueries.push({
       queryOptions,
       client,
     })
   }
 
-  willPrefetch (component) {
+  prefetchComponent (component, context) {
     component = getMergedDefinition(component)
     const apolloOptions = component.apollo
 
@@ -42,14 +48,14 @@ export class ApolloProvider {
           )
         )
       ) {
-        this.willPrefetchQuery(options, options.client || componentClient)
+        this.addQueryToPrefetch(options, options.client || componentClient)
       }
     }
   }
 
-  willPrefetchComponents (definitions) {
+  prefetchComponents (definitions) {
     for (const def of definitions) {
-      this.willPrefetch(def)
+      this.prefetchComponent(def)
     }
   }
 
@@ -65,11 +71,21 @@ export class ApolloProvider {
     }, options)
 
     if (components) {
-      this.willPrefetchComponents(components)
+      this.prefetchComponents(components)
     }
 
     if (finalOptions.includeGlobal) {
-      this.willPrefetchComponents(globalPrefetchs)
+      this.prefetchComponents(globalPrefetchs.filter(
+        ({ component, contextCallback }) => {
+          let result = true
+          if (typeof contextCallback === 'function') {
+            result = !!contextCallback(context)
+          }
+          return result
+        }
+      ).map(
+        ({ component }) => component
+      ), context)
     }
 
     return Promise.all(this.prefetchQueries.map(
@@ -166,7 +182,14 @@ export class ApolloProvider {
 
 const globalPrefetchs = []
 
-export function willPrefetch (component) {
-  globalPrefetchs.push(component)
+export function willPrefetch (component, contextCallback = null) {
+  globalPrefetchs.push({ component, contextCallback })
   return component
 }
+
+// Global access for libraries
+if (typeof window !== 'undefined') {
+  window.vueApolloWillPrefetch = willPrefetch
+} else if (typeof global !== 'undefined') {
+  global.vueApolloWillPrefetch = willPrefetch
+}