Example showing “loading” states

Author: marshallswain

docs/composition-api.md

@@ -34,7 +34,7 @@ export default {
   name: 'UserGuide',
   setup(props, context) {
     // 1. Get a reference to the model class
-    const { Tutorial } = context.root.$FeathersVuex.spark
+    const { Tutorial } = context.root.$FeathersVuex.api
 
     // 2. Create a computed property for the params
     const tutorialsParams = computed(() => {
@@ -111,7 +111,7 @@ interface UseFindData {
   servicePath: Ref<string>
   isFindPending: Ref<boolean>
   haveBeenRequestedOnce: Ref<boolean>
-  haveLoadedOnce: Ref<boolean>
+  haveLoaded: Ref<boolean>
   isLocal: Ref<boolean>
   qid: Ref<string>
   debounceTime: Ref<number>
@@ -128,7 +128,7 @@ Let's look at the functionality that each one provides:
 - `servicePath` is the FeathersJS service path that is used by the current model. This is mostly only useful for debugging.
 - `isFindPending` is a boolean that indicates if there is an active query.  It is set to `true` just before each outgoing request.  It is set to `false` after the response returns.  Bind to it in the UI to show an activity indicator to the user.
 - `haveBeenRequestedOnce` is a boolean that is set to `true` immediately before the first query is sent out.  It remains true throughout the life of the component.  This comes in handy for first-load scenarios in the UI.
-- `haveLoadedOnce` is a boolean that is set to true after the first API response.  It remains `true` for the life of the component. This also comes in handy for first-load scenarios in the UI.
+- `haveLoaded` is a boolean that is set to true after the first API response.  It remains `true` for the life of the component. This also comes in handy for first-load scenarios in the UI.
 - `isLocal` is a boolean that is set to true if this data is local only.
 - `qid` is currently the primary `qid` provided in params.  It might become more useful in the future.
 - `debounceTime` is the current number of milliseconds used as the debounce interval.
@@ -157,7 +157,7 @@ import { useFind } from 'feathers-vuex'
 export default {
   name: 'UserGuide',
   setup(props, context) {
-    const { Todo } = context.root.$FeathersVuex.spark
+    const { Todo } = context.root.$FeathersVuex.api
 
     const todosParams = computed(() => {
       return {
@@ -196,7 +196,197 @@ The `useGet` utility is still being built.  Docs will be written when it becomes
 
 ### Returned Attributes
 
-## Pairing `useFind` with `useGet`
+## Pattens: `useFind` with `useGet`
+
+### Simultaneous Queries
+
+Let's look at an example where we have two separate tables and we want live-queried lists for both of them.  This example will show a component for a doctor's office that pulls up a patient by `id` using `useGet` then retrieves all of the patient's `appointments` using `useFind`.
+
+```html
+<template>
+  <div>
+    <div>{{ patient.name }}</div>
+
+    <li v-for="appointment in appointments" :key="appointment._id">
+      {{ appointment.date }}
+    </li>
+  </div>
+</template>
+
+<script>
+import { computed } from '@vue/composition-api'
+import { useFind, useGet } from 'feathers-vuex'
+
+export default {
+  name: 'PatientAppointments',
+  props: {
+    id: {
+      type: String,
+      required: true
+    }
+  },
+  setup(props, context) {
+    const { Patient, Appointment } = context.root.$FeathersVuex.api
+
+    // Get the patient record
+    const { item: patient } = useGet({ model: Patient, id: props.id })
+
+    // Get all of the appointments belonging to the current patient
+    const appointmentsParams = computed(() => {
+      return {
+        query: {
+          userId: props.id,
+          $sort: { date: -1 }
+        }
+      }
+    })
+    const { items: appointments } = useFind({
+      model: Appointment,
+      params: appointmentsParams
+    })
+
+    return {
+      patient,
+      appointments
+    }
+  }
+}
+```
+
+### Deferring Queries
+
+In the previous example, the requests for the `patient` and `appointments` are made at the same time because the user's `id` is available, already.  What if we were required to load `appointments` after the `patient` record finished loading?  We could change the `appointmentsParams` to return `null` until the `patient` record becomes available, as shown in the following example:
+
+```html
+<template>
+  <div>
+    <div>{{ patient.name }}</div>
+
+    <li v-for="appointment in appointments" :key="appointment._id">
+      {{ appointment.date }}
+    </li>
+
+    <div v-if="!appointments.length && haveLoaded">
+      No appointments have been scheduled for this patient.
+    </div>
+  </div>
+</template>
+
+<script>
+import { computed } from '@vue/composition-api'
+import { useFind, useGet } from 'feathers-vuex'
+
+export default {
+  name: 'PatientAppointments',
+  props: {
+    id: {
+      type: String,
+      required: true
+    }
+  },
+  setup(props, context) {
+    const { Patient, Appointment } = context.root.$FeathersVuex.api
+
+    // Get the patient record
+    const { item: patient } = useGet({ model: Patient, id: props.id })
+
+    // Get all of the appointments belonging to the current patient
+    const appointmentsParams = computed(() => {
+      // (1)
+      if (!patient.value) {
+        return null
+      }
+      // (2)
+      return {
+        query: {
+          userId: patient.value._id,
+          $sort: { date: -1 }
+        }
+      }
+    })
+    const { items: appointments, haveLoaded } = useFind({
+      model: Appointment,
+      params: appointmentsParams
+    })
+
+    return {
+      patient,
+      appointments,
+      haveLoaded
+    }
+  }
+}
+```
+
+Reviewing the above snippet, while there is no `patient` record, the `appointmentsParams` computed property returns `null` at comment `(1)`.  This will prevent any query from going out to the API server.
+
+Once the `patient` has loaded, the full params object is returned at comment `(2)`.  This allows the `useFind` utility to make the request.
+
+### Showing Loading State
+
+This next example builds on the previous one and adds loading state for both the `patient` and the `appointments`.
+
+```html
+<template>
+  <div>
+    <div v-if="isPatientLoading">Loading</div>
+    <div v-else>{{ patient.name }}</div>
+
+    <li v-for="appointment in appointments" :key="appointment._id">
+      {{ appointment.date }}
+    </li>
+
+    <div v-if="!appointments.length && haveLoaded">
+      No appointments have been scheduled for this patient.
+    </div>
+  </div>
+</template>
+
+<script>
+import { computed } from '@vue/composition-api'
+import { useFind, useGet } from 'feathers-vuex'
+
+export default {
+  name: 'PatientAppointments',
+  props: {
+    id: {
+      type: String,
+      required: true
+    }
+  },
+  setup(props, context) {
+    const { Patient, Appointment } = context.root.$FeathersVuex.api
+
+    const {
+      item: patient,
+      isPending: isPatientLoading
+    } = useGet({ model: Patient, id: props.id })
+
+    const appointmentsParams = computed(() => {
+      if (!patient.value) {
+        return null
+      }
+      return {
+        query: {
+          userId: patient.value._id,
+          $sort: { date: -1 }
+        }
+      }
+    })
+    const { items: appointments, haveLoaded } = useFind({
+      model: Appointment,
+      params: appointmentsParams
+    })
+
+    return {
+      patient,
+      isPatientLoading,
+      appointments,
+      haveLoaded
+    }
+  }
+}
+```
 
 ## Conventions for Development
 

src/useFind.ts

@@ -25,19 +25,19 @@ interface UseFindOptions {
 interface UseFindState {
   debounceTime: null | number
   qid: string
-  isFindPending: boolean
-  haveBeenRequestedOnce: boolean
-  haveLoadedOnce: boolean
+  isPending: boolean
+  haveBeenRequested: boolean
+  haveLoaded: boolean
   error: null | Error
   latestQuery: null | object
   isLocal: boolean
 }
 interface UseFindData {
   items: Ref<any>
   servicePath: Ref<string>
-  isFindPending: Ref<boolean>
-  haveBeenRequestedOnce: Ref<boolean>
-  haveLoadedOnce: Ref<boolean>
+  isPending: Ref<boolean>
+  haveBeenRequested: Ref<boolean>
+  haveLoaded: Ref<boolean>
   isLocal: Ref<boolean>
   qid: Ref<string>
   debounceTime: Ref<number>
@@ -84,9 +84,9 @@ export default function find(options: UseFindOptions): UseFindData {
 
   const state = reactive<UseFindState>({
     qid,
-    isFindPending: false,
-    haveBeenRequestedOnce: false,
-    haveLoadedOnce: false,
+    isPending: false,
+    haveBeenRequested: false,
+    haveLoaded: false,
     error: null,
     debounceTime: null,
     latestQuery: null,
@@ -128,20 +128,20 @@ export default function find(options: UseFindOptions): UseFindData {
   function find<T>(params: Params): T {
     params = isRef(params) ? params.value : params
     if (queryWhen.value && !state.isLocal) {
-      state.isFindPending = true
-      state.haveBeenRequestedOnce = true
+      state.isPending = true
+      state.haveBeenRequested = true
 
       return model.find(params).then(response => {
         // To prevent thrashing, only clear error on response, not on initial request.
         state.error = null
-        state.haveLoadedOnce = true
+        state.haveLoaded = true
 
         const queryInfo = getQueryInfo(params, response)
         queryInfo.response = response
         queryInfo.isOutdated = false
 
         state.latestQuery = queryInfo
-        state.isFindPending = false
+        state.isPending = false
         return response
       })
     }

test/use/find.test.ts

@@ -61,9 +61,9 @@ describe('use/find', function() {
     const {
       debounceTime,
       error,
-      haveBeenRequestedOnce,
-      haveLoadedOnce,
-      isFindPending,
+      haveBeenRequested,
+      haveLoaded,
+      isPending,
       isLocal,
       items,
       latestQuery,
@@ -77,14 +77,14 @@ describe('use/find', function() {
     assert(isRef(error))
     assert(error.value === null)
 
-    assert(isRef(haveBeenRequestedOnce))
-    assert(haveBeenRequestedOnce.value === true)
+    assert(isRef(haveBeenRequested))
+    assert(haveBeenRequested.value === true)
 
-    assert(isRef(haveLoadedOnce))
-    assert(haveLoadedOnce.value === false)
+    assert(isRef(haveLoaded))
+    assert(haveLoaded.value === false)
 
-    assert(isRef(isFindPending))
-    assert(isFindPending.value === true)
+    assert(isRef(isPending))
+    assert(isPending.value === true)
 
     assert(isRef(isLocal))
     assert(isLocal.value === false)
@@ -120,10 +120,10 @@ describe('use/find', function() {
       params: instrumentParams,
       lazy: true
     })
-    const { haveBeenRequestedOnce } = instrumentsData
+    const { haveBeenRequested } = instrumentsData
 
-    assert(isRef(haveBeenRequestedOnce))
-    assert(haveBeenRequestedOnce.value === false)
+    assert(isRef(haveBeenRequested))
+    assert(haveBeenRequested.value === false)
   })
 
   it('params can return null to prevent the query', function() {
@@ -137,10 +137,10 @@ describe('use/find', function() {
       params: instrumentParams,
       lazy: true
     })
-    const { haveBeenRequestedOnce } = instrumentsData
+    const { haveBeenRequested } = instrumentsData
 
-    assert(isRef(haveBeenRequestedOnce))
-    assert(haveBeenRequestedOnce.value === false)
+    assert(isRef(haveBeenRequested))
+    assert(haveBeenRequested.value === false)
   })
 
   it('allows using `local: true` to prevent API calls from being made', function() {
@@ -156,13 +156,13 @@ describe('use/find', function() {
       params: instrumentParams,
       local: true
     })
-    const { haveBeenRequestedOnce, find } = instrumentsData
+    const { haveBeenRequested, find } = instrumentsData
 
-    assert(isRef(haveBeenRequestedOnce))
-    assert(haveBeenRequestedOnce.value === false, 'no request during init')
+    assert(isRef(haveBeenRequested))
+    assert(haveBeenRequested.value === false, 'no request during init')
 
     find()
 
-    assert(haveBeenRequestedOnce.value === false, 'no request after find')
+    assert(haveBeenRequested.value === false, 'no request after find')
   })
 })