Merge pull request #388 from feathersjs-ecosystem/3.0

Feathers-Vuex 3.0

Author: marshallswain

docs/.vuepress/config.js

@@ -9,16 +9,18 @@ module.exports = {
     editLinks: true,
     sidebar: [
       '/api-overview.md',
+      '/3.0-major-release.md',
       '/vue-plugin.md',
       '/service-plugin.md',
       '/auth-plugin.md',
       '/model-classes.md',
       '/common-patterns.md',
+      '/composition-api.md',
       '/mixins.md',
       '/data-components.md',
       '/feathers-vuex-form-wrapper.md',
       '/nuxt.md',
-      '/2.0-major-release.md'
+      '/2.0-major-release.md',
     ],
     serviceWorker: {
       updatePopup: true

docs/2.0-major-release.md

@@ -1,3 +1,8 @@
+---
+title: 2.0 Breaking Changes
+sidebarDepth: 3
+---
+
 # 2.0 Breaking Changes
 
 The biggest change in Feathers-Vuex 2.0 is that it has been refactored with TypeScript!  (It's mostly ES6, still)
@@ -104,189 +109,7 @@ const store = new Vuex.Store({
 })
 ```
 
-## Setting up a project
-
-There are four steps to setting up the entirety of `feathers-vuex`:
-
-1. Setup the FeathersJS Client.
-2. Setup each Service plugin
-3. Setup the Auth plugin
-4. Register all plugins with Vuex
-
-### Setup the FeathersJS Client
-
-It's now recommended that the FeathersJS and client live together in the same file.  This cleans up imports when setting up services.  So let's start with the `feathers-client.js` file.  I usually put this in `src/feathers-client.js`, but you can put it in the store folder if you want.
-
-```js
-// src/feathers-client.js
-import feathers from '@feathersjs/feathers'
-import socketio from '@feathersjs/socketio-client'
-import authClient from '@feathersjs/authentication-client'
-import io from 'socket.io-client'
-import feathersVuex from 'feathers-vuex' // or '@/libs/feathers-vuex' if you're copying feathers-vuex as mentioned earlier.
-
-// Setup the Feathers client
-const host = process.env.VUE_APP_API_URL // or set a string here, directly
-const socket = io(host, { transports: ['websocket'] })
-const feathersClient = feathers()
-  .configure(socketio(socket))
-  .configure(authClient({ storage: window.localStorage }))
-
-export default feathersClient
-
-// Setup feathers-vuex
-const {
-  makeServicePlugin,
-  makeAuthPlugin,
-  BaseModel,
-  models,
-  clients,
-  FeathersVuex
-} = feathersVuex(feathersClient, {
-  serverAlias: 'api', // or whatever that makes sense for your project
-  idField: '_id' // `id` and `_id` are both supported, so this is only necessary if you're using something else.
-})
-
-export {
-  makeAuthPlugin,
-  makeServicePlugin,
-  BaseModel,
-  models,
-  clients,
-  FeathersVuex
-}
-
-```
-
-Now that we have setup the client, we can use the configured exports in each of our services.
-
-### Setup the Services Plugins
-
-Now let's setup a Vuex plugin for each service. I use Webpack's `require.context` to automatically import all of the services instead of explicitly typing them all.  So, I'll put the services in the `src/store/services` folder.
-
-```js
-// Bring in the imports from the feathers-client.js file.
-import feathersClient, {
-  makeServicePlugin,
-  BaseModel
-} from '../../feathers-client'
-
-// Extend the base class
-class User extends BaseModel {
-  constructor(data, options) {
-    super(data, options)
-  }
-  static modelName = 'User'
-  static instanceDefaults() {
-    return {
-      firstName: '',
-      lastName: '',
-      email: '',
-      password: ''
-    }
-  }
-  get fullName() {
-    return `${this.firstName} ${this.lastName}`
-  }
-}
-const servicePath = 'users'
-const servicePlugin = makeServicePlugin({
-  Model: User,
-  service: feathersClient.service(servicePath),
-  servicePath
-})
-
-// Optionally add service-level hooks, here:
-feathersClient.service(servicePath).hooks({
-  before: {
-    all: [],
-    find: [],
-    get: [],
-    create: [],
-    update: [],
-    patch: [],
-    remove: []
-  },
-  after: {
-    all: [],
-    find: [],
-    get: [],
-    create: [],
-    update: [],
-    patch: [],
-    remove: []
-  },
-  error: {
-    all: [],
-    find: [],
-    get: [],
-    create: [],
-    update: [],
-    patch: [],
-    remove: []
-  }
-})
-
-export default servicePlugin
-
-```
-
-Once the service plugin is exported, we can register it with Vuex, but first let's setup the auth plugin.
-
-### Setup the Auth Plugin
-
-We'll use the `makeAuthPlugin` method to tell the auth plugin where to find our `/users` service:
-
-```js
-// src/store/store.auth.js
-import feathersClient, { makeAuthPlugin } from '../feathers-client'
-
-export default makeAuthPlugin({ userService: 'users' })
-
-```
-
-Once you've added the export, we're finally ready to setup the store.
-
-### Register all plugins with Vuex
-
-The final step is to add all of the plugins to the Vuex store.
-
-```js
-// src/store/store.js
-import Vue from 'vue'
-import Vuex from 'vuex'
-import { FeathersVuex } from 'feathers-vuex'
-import auth from './store.auth'
-
-Vue.use(Vuex)
-Vue.use(FeathersVuex)
-
-// Require the entire folder of service plugins with Webpack
-const requireModule = require.context( './services', false, /.js$/ )
-const servicePlugins = requireModule
-  .keys()
-  .map(modulePath => requireModule(modulePath).default)
-
-// Or you can import them manually for Rollup, etc.
-import users from './services/users'
-
-export default new Vuex.Store({
-  state: {},
-  getters: {},
-  mutations: {},
-  actions: {},
-  plugins: [
-    ...servicePlugins, // if you're using require.context, spread the plugins into the array.
-    users, // if you're manually importing, just add the plugins into the array, like this
-    auth
-  ]
-})
-
-```
-
-With the above four steps accomplished, the base of most any application using `feathers-vuex` is ready to build something awesome!
-
-## FeathersVuex Vue plugin changes
+## Feathers-Vuex Vue plugin changes
 
 The Vue plugin is registered in exactly the same way.  The difference comes when you try to find the Model classes in the `$FeathersVuex` object.  Instead of finding models directly on the `$FeathersVuex` object, they are namespaced by the `serverAlias` you provided.  This allows cleaner support for multiple APIs.  Supposing you had this code in a component, previously...
 
@@ -320,7 +143,7 @@ Because of the new ability to handle temporary records, a message is only logged
 
 ## Getters Work with Temporary Records
 
-The `find` getter has been updated to include records from `state.tempsById`, by default.  You can pass `temps: false` in the params to only search `state.keyedById`: `find({ query: {}, temps: false })`
+The `find` getter has been updated to include records from `state.tempsById` when you pass `temps: true` in the params.
 
 The `get` getter has also been updated to work with temp ids.  Pass the tempId the way you normally would pass the id:  `get(tempId)`
 
@@ -804,21 +627,21 @@ The above code will override the `responseHandler` auth action to work with the
 
 Don't try to perform a query from within a getter like the example, below.  It will result in an infinite loop:
 
-```
+```js
 get user () {
-            if (this.userId) {
-              const user = Models.User.getFromStore(this.userId)
+  if (this.userId) {
+    const user = Models.User.getFromStore(this.userId)
 
-              // Fetch the User record if we don't already have it
-              if (!user) {
-                Models.User.get(this.userId)
-              }
+    // Fetch the User record if we don't already have it
+    if (!user) {
+      Models.User.get(this.userId)
+    }
 
-              return user
-            } else {
-              return null
-            }
-          }
+    return user
+  } else {
+    return null
+  }
+}
 ```
 
 ### Using custom query parameters
@@ -829,13 +652,3 @@ There are two places where the query operators have to be allowed.
 - Inside feathers-vuex (for the getters): Check out the `paramsForServer` and  `whitelist` options for `feathers-vuex`. Both accept an array of strings representing prop names, but now I can't remember why I determined that I needed both. :)
 
 For the Feathers Client, follow the FeathersJS docs for your database adapter.
-
-### Access `$FeathersVuex` models in Nuxt `asyncData`
-
-In `feathers-vuex@2.x`, you can get access to the `$FeathersVuex` object by importing the `models` object from the main export:
-
-```
-import { models } from 'feathers-vuex'
-```
-
-`models` and `$FeathersVuex` are the same object.

docs/3.0-major-release.md

@@ -0,0 +1,52 @@
+---
+title: What's New in 3.0
+sidebarDepth: 3
+---
+
+# What's new in Feathers-Vuex 3.0
+
+## Vue Composition API Support
+
+Version 3.0 of Feathers-Vuex is the Vue Composition API release!  There were quite a few disappointed (and misinformed:) developers in 2019 when the Vue.js team announced what is now called the Vue Composition API.  From my perspective:
+
+- It is the most powerful feature added to Vue since its first release.
+- It improves the ability to create dynamic functionality in components.
+- It greatly enhances organization of code in components.
+- It encourages code re-use. Check out the [vue-use-web](https://logaretm.github.io/vue-use-web/) collection for some great examples.
+
+And now it has become the best way to perform queries with Feathers-Vuex.  To find out how to take advantage of the new functionality in your apps, read the [Feather-Vuex Composition API docs](./composition-api.md).
+
+## A Single Breaking Change
+
+Since Feathers-Vuex follows semantic versioning, a single, small breaking change is the reason for the major version bump. Feathers-Vuex 3.0 has only one breaking change:
+
+The `makeFindMixin` (and the new `useFind` utility) now have server-side pagination support turned off, by default.  Real-time arrays of results are now the default setting.  This really improves the development experience, especially for new users.
+
+To migrate your app to version 3.0, you need to update any `params` where you are using server-side pagination.  It will work as it has been in version 2.0 once you explicitly set `paginate: true` in the params, like this:
+
+```js
+import { makeFindMixin } from 'feathers-vuex'
+
+export default {
+  name: 'MyComponent',
+  mixins: [ makeFindMixin({ service: 'users', watch: true })],
+  computed: {
+    usersParams() {
+      return {
+        query: {},
+        paginate: true // explicitly enable pagination, now.
+      }
+    }
+  }
+}
+```
+
+That's the only breaking change in this release.  This behavior exactly matches the new `useFind` utility.
+
+## One Deprecation
+
+The `keepCopiesInStore` option is now deprecated.  This was a part of the "clone and commit" API which basically disabled the reason for creating the "clone and commit" API in the first place.
+
+If you're not familiar with the Feathers-Vuex "clone and commit" API, you can learn more about the [built-in data modeling](./model-classes.md) API and the section about [Working with Forms](./feathers-vuex-form-wrapper.md#the-clone-and-commit-pattern).
+
+The `keepCopiesInStore` feature is set to be removed in Feathers-Vuex 4.0.

docs/api-overview.md

@@ -38,11 +38,11 @@ These docs are for version 2.x.  For [email protected], please go to [https://fe
 - [Renderless Data Components](./data-components.md)
 - [Renderless Form Component](./feathers-vuex-form-wrapper.md#feathersvuexformwrapper) for Simplified Vuex Forms
 - [Temporary (Local-only) Record Support](./2.0-major-release.md#support-for-temporary-records) *
+- New `useFind` and `useGet` Vue Composition API super powers! <Badge text="3.0.0+" />
 - [Server-Powered Pagination Support](./service-plugin.md#pagination-and-the-find-action) *
 - [VuePress Dark Mode Support](https://tolking.github.io/vuepress-theme-default-prefers-color-scheme/) for the Docs
 
-`* Improved in v2.0.0`<br />
-`** New in v2.0.0`
+`** Improved in v3.0.0`
 
 ## Installation
 
@@ -112,6 +112,8 @@ build: {
 }
 ```
 
+Be sure to read the section of the docs dedicated to [Working With Nuxt](./nuxt.md).
+
 ## Vue DevTools
 
 Since Feathers-Vuex extensively uses Vuex under the hood, you'll want to make sure your VueJS developer tools are up to date AND setup properly.  Specifically, the "New Vuex Backend" needs to be enabled.  To setup the devtools
@@ -185,7 +187,7 @@ The following example creates a User class and registers it with the new `makeSe
 
 ```js
 // src/store/services/users.js
-import feathersClient, { makeServicePlugin, BaseModel } from '../feathers-client'
+import feathersClient, { makeServicePlugin, BaseModel } from '../../feathers-client'
 
 class User extends BaseModel {
   constructor(data, options) {