feat(query): placeholder

Author: ElisePatrikainen

src/query-options.ts

@@ -1,7 +1,7 @@
-import { type InjectionKey, type MaybeRefOrGetter, inject } from 'vue'
 import type { EntryKey } from './entry-options'
-import type { ErrorDefault } from './types-extension'
 import type { PiniaColadaOptions } from './pinia-colada'
+import type { ErrorDefault } from './types-extension'
+import { inject, type InjectionKey, type MaybeRefOrGetter } from 'vue'
 
 /**
  * `true` refetch if data is stale (refresh()), `false` never refetch, 'always' always refetch.
@@ -79,6 +79,8 @@ export interface UseQueryOptions<TResult = unknown, TError = ErrorDefault> {
   // TODO: this might be just sugar syntax to do `setQueryData()` on creation
   initialData?: () => TResult
 
+  placeholderData?: TResult | ((previousData: TResult) => TResult)
+
   /**
    * Function to type and ensure the `error` property is always an instance of `TError`.
    *

src/query-store.ts

@@ -1,27 +1,27 @@
+import type {
+  AsyncStatus,
+  DataState,
+  DataState_Success,
+  DataStateStatus,
+} from './data-state'
+import type { defineQuery } from './define-query'
+import type { EntryKey } from './entry-options'
+import type { UseQueryOptionsWithDefaults } from './query-options'
+import type { ErrorDefault } from './types-extension'
 import { defineStore } from 'pinia'
 import {
   type ComponentInternalInstance,
   type EffectScope,
-  type ShallowRef,
   getCurrentInstance,
   getCurrentScope,
   markRaw,
   shallowReactive,
+  type ShallowRef,
   shallowRef,
   toValue,
 } from 'vue'
-import { stringifyFlatObject, toValueWithArgs } from './utils'
 import { type EntryNodeKey, TreeMapNode } from './tree-map'
-import type { EntryKey } from './entry-options'
-import type { UseQueryOptionsWithDefaults } from './query-options'
-import type { ErrorDefault } from './types-extension'
-import type { defineQuery } from './define-query'
-import type {
-  AsyncStatus,
-  DataState,
-  DataStateStatus,
-  DataState_Success,
-} from './data-state'
+import { stringifyFlatObject, toValueWithArgs } from './utils'
 
 /**
  * NOTE: Entries could be classes but the point of having all functions within the store is to allow plugins to hook
@@ -501,9 +501,10 @@ export const useQueryCache = defineStore(QUERY_STORE_ID, ({ action }) => {
     <TResult, TError>(
       entry: UseQueryEntry<TResult, TError>,
       state: DataState<TResult, TError>,
+      resetWhen?: boolean,
     ) => {
       entry.state.value = state
-      entry.when = Date.now()
+      if (resetWhen) entry.when = Date.now()
     },
   )
 

src/use-query.spec.ts

@@ -1,17 +1,17 @@
 import type { MockInstance } from 'vitest'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { GlobalMountOptions } from '../test/utils'
+import type { UseQueryOptions } from './query-options'
+import type { UseQueryEntry } from './query-store'
 import { enableAutoUnmount, flushPromises, mount } from '@vue/test-utils'
 import { createPinia } from 'pinia'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { defineComponent, nextTick, ref, shallowReactive } from 'vue'
 import { mockWarn } from '../test/mock-warn'
-import type { GlobalMountOptions } from '../test/utils'
 import { isSpy } from '../test/utils'
-import { useQuery } from './use-query'
-import type { UseQueryEntry } from './query-store'
-import { QUERY_STORE_ID, createQueryEntry, useQueryCache } from './query-store'
-import { TreeMapNode, entryNodeSize } from './tree-map'
-import type { UseQueryOptions } from './query-options'
 import { PiniaColada } from './pinia-colada'
+import { createQueryEntry, QUERY_STORE_ID, useQueryCache } from './query-store'
+import { entryNodeSize, TreeMapNode } from './tree-map'
+import { useQuery } from './use-query'
 
 describe('useQuery', () => {
   beforeEach(() => {
@@ -456,6 +456,48 @@ describe('useQuery', () => {
       expect(query).toHaveBeenCalledTimes(1)
     })
 
+    it('uses the placeholder data if configured while refetching', async () => {
+      const { wrapper, query } = mountDynamicKey({
+        query: async () => {
+          await new Promise((res) => setTimeout(res, 100))
+          return { when: Date.now() }
+        },
+        staleTime: 1000,
+        placeholderData: (data) => data,
+      })
+
+      vi.advanceTimersByTime(100)
+      await flushPromises()
+      expect(query).toHaveBeenCalledTimes(1)
+      const dataId0 = wrapper.vm.data
+
+      await wrapper.vm.setId(1)
+      // Placeholder data is used
+      expect(wrapper.vm.data).toBe(dataId0)
+
+      vi.advanceTimersByTime(100)
+      await flushPromises()
+      const dataId1 = wrapper.vm.data
+      // Refetch data is used
+      expect(dataId1).not.toBe(dataId0)
+
+      await wrapper.vm.setId(0)
+      // Data is not stale: placeholder data is not used, catched data is used
+      expect(wrapper.vm.data).toBe(dataId0)
+
+      vi.advanceTimersByTime(1001)
+
+      await wrapper.vm.setId(1)
+      // Data is stale: placeholder data is used
+      expect(wrapper.vm.data).toBe(dataId0)
+
+      vi.advanceTimersByTime(100)
+      await flushPromises()
+      // Refetch data is used
+      expect(dataId1).not.toBe(dataId0)
+      expect(query).toHaveBeenCalledTimes(3)
+    })
+
     it('refreshes the data if mounted and the key changes', async () => {
       const { wrapper, query } = mountDynamicKey({
         initialId: 0,

src/use-query.ts

@@ -1,4 +1,12 @@
 import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from 'vue'
+import type { AsyncStatus, DataState, DataStateStatus } from './data-state'
+import type { EntryKey } from './entry-options'
+import type {
+  UseQueryOptions,
+  UseQueryOptionsWithDefaults,
+} from './query-options'
+import type { UseQueryEntry } from './query-store'
+import type { ErrorDefault } from './types-extension'
 import {
   computed,
   getCurrentInstance,
@@ -10,22 +18,14 @@ import {
   toValue,
   watch,
 } from 'vue'
-import { IS_CLIENT, useEventListener } from './utils'
-import type { UseQueryEntry } from './query-store'
+import { getCurrentDefineQueryEffect } from './define-query'
+import { useQueryOptions } from './query-options'
 import {
   queryEntry_addDep,
   queryEntry_removeDep,
   useQueryCache,
 } from './query-store'
-import { useQueryOptions } from './query-options'
-import type { EntryKey } from './entry-options'
-import type {
-  UseQueryOptions,
-  UseQueryOptionsWithDefaults,
-} from './query-options'
-import type { ErrorDefault } from './types-extension'
-import { getCurrentDefineQueryEffect } from './define-query'
-import type { AsyncStatus, DataState, DataStateStatus } from './data-state'
+import { IS_CLIENT, useEventListener } from './utils'
 
 /**
  * Return type of `useQuery()`.
@@ -200,6 +200,15 @@ export function useQuery<TResult, TError = ErrorDefault>(
     entry,
     (entry, previousEntry) => {
       if (!isActive) return
+      if (entry.stale && entry.options?.placeholderData && previousEntry?.state.value.status === 'success') {
+        cacheEntries.setEntryState(entry, {
+          // TODO: pending?
+          status: 'success',
+          // @ts-expect-error: TODO: fix this
+          data: (typeof entry.options.placeholderData === 'function') ? entry.options.placeholderData(previousEntry.state.value.data) : previousEntry.state.value.data,
+          error: null,
+        }, false)
+      }
       if (previousEntry) {
         queryEntry_removeDep(previousEntry, hasCurrentInstance, cacheEntries)
         queryEntry_removeDep(previousEntry, currentEffect, cacheEntries)