New pagination API & service getters tested

Author: marshallswain

README.md

@@ -261,6 +261,8 @@ let params = {query: {completed: true}}
 store.dispatch('todos/find', params)
 ```
 
+See the section about pagination, below, for more information that is applicable to the `find` action.
+
 #### `get(id)` or `get([id, params])`
 Query a single record from the server & add to Vuex store
 - `id {Number|String}` - the `id` of the record being requested from the API server.
@@ -318,6 +320,66 @@ Remove/delete the record with the given `id`.
 store.dispatch('todos/remove', 1)
 ```
 
+## Querying with Find & Pagination
+Both the `find` action and the `find` getter support pagination.  There are differences in how they work.
+
+### The `find` action
+
+The `find` action queries data from the remote server.  It returns a promise that resolves to the response from the server.  The presence of pagination data will be determined by the server.
+
+`[email protected]` can store pagination data on a per-query basis.  The `pagination` store attribute maps queries to their most-recent pagination data.  It's an empty object by default, but after performing a single query (with pagination in the response), it will have a `default` property.  This property stores pagination information for the query.  Here's what it will look like:
+
+**`params = { query: {} }`**
+```js
+{
+  pagination: {
+    default: {
+      query: {}, // Same as params.query
+      ids: [0, 1, 2], // the ids in the store for the records that were returned from the server
+      limit: 0, // the response.limit
+      skip: 0, // the response.skip
+      total: 3 // the response.total
+    }
+  }
+}
+```
+
+It's possible that you'll want to store pagination information for more than one query.  This might be for different components making queries against the same service, for example.  You can use the `params.qid` (query identifier) property to assign a name to the query.  If you set a `qid` of `mainListView`, for example, the pagination for this query will show up under `pagination.mainListView`.  The `pagination.default` property will be used any time a `params.qid` is not provided.  Here's an example of what this might look like:
+
+**`params = { query: { $limit: 1 }, qid: 'mainListView' }`**
+```js
+// Data in the store
+{
+  pagination: {
+    mainListView: {
+      query: { $limit: 1 }, // Same as params.query
+      ids: [0], // the ids in the store for the records that were returned from the server
+      limit: 1, // the response.limit
+      skip: 0, // the response.skip
+      total: 3 // the response.total
+    }
+  }
+}
+```
+
+### The `find` getter
+
+The `find` getter queries data from the local store using the same Feathers query syntax as on the server.  It is synchronous and directly returns the results of the query.  Pagination is **always** enabled and cannot be disabled.  It accepts a params object with a `query` attribute.  It does not use any other special attributes.  The returned object looks just like a paginated result that you would receive from the server:
+
+**`params = { query: {} }`**
+```js
+// The returned results object
+{
+  data: [{ _id: 1, ...etc }, ...etc],
+  limit: 0,
+  skip: 0,
+  total: 3
+}
+```
+
+
+###
+
 ## Customizing a Service's Default Store
 
 As shown in the first example, the service module allows you to customize its store:
@@ -384,6 +446,6 @@ You can provide a `userService` in the auth plugin's options to automatically po
 
 ## License
 
-Copyright (c) 2016
+Copyright (c) Forever and Ever, or at least the current year.
 
 Licensed under the [MIT license](LICENSE).

src/service-module/actions.js

@@ -1,11 +1,20 @@
 export default function makeServiceActions (service) {
   const serviceActions = {
-    find ({ commit, dispatch, getters }, params) {
+    find ({ commit, dispatch, getters }, params = {}) {
       commit('setFindPending')
+
       const handleResponse = response => {
+        const { qid = 'default', query } = params
+
         dispatch('addOrUpdateList', response)
         commit('unsetFindPending')
-        return getters.find(params)
+
+        // The pagination data will be under `pagination.default` or whatever qid is passed.
+        if (response.data) {
+          commit('updatePaginationForQuery', { qid, response, query })
+        }
+
+        return response
       }
       const handleError = error => {
         commit('setFindError', Object.assign({}, error))

src/service-module/getters.js

@@ -28,16 +28,11 @@ export default function makeServiceGetters (servicePath) {
         values = values.map(value => _.pick(value, ...filters.$select))
       }
 
-      const shouldPaginate = state.paginate && params.paginate !== false
-      if (shouldPaginate) {
-        return {
-          total,
-          limit: filters.$limit,
-          skip: filters.$skip || 0,
-          data: values
-        }
-      } else {
-        return values
+      return {
+        total,
+        limit: filters.$limit || 0,
+        skip: filters.$skip || 0,
+        data: values
       }
     },
     get: ({ keyedById, idField }) => (id, params = {}) => {

src/service-module/mutations.js

@@ -151,6 +151,17 @@ export default function makeServiceMutations (servicePath) {
       _merge(current, state.copy)
     },
 
+    // Stores pagination data on state.pagination based on the query identifier (qid)
+    // The qid must be manually assigned to `params.qid`
+    updatePaginationForQuery (state, { qid, response, query }) {
+      const { data, limit, skip, total } = response
+      const { idField } = state
+      const ids = data.map(item => {
+        return item[idField]
+      })
+      state.pagination = { ...state.pagination, [qid]: { limit, skip, total, ids, query } }
+    },
+
     setFindPending (state) {
       state.isFindPending = true
     },

src/service-module/state.js

@@ -7,7 +7,7 @@ export default function makeDefaultState (servicePath, { idField, autoRemove, pa
     idField,
     servicePath,
     autoRemove,
-    paginate,
+    pagination: {},
 
     isFindPending: false,
     isGetPending: false,

test/index.test.js

@@ -1,6 +1,7 @@
 import './service-module/service-module.test.js'
 import './service-module/misconfigured-client.test.js'
 import './service-module/actions.test.js'
+import './service-module/getters.test.js'
 import './service-module/mutations.test.js'
 import './auth-module/auth-module.test.js'
 import './auth-module/actions.test.js'