`useInifiniteQuery()` for infinite scrolling

[posva]

I'm trying to figure out a flexible API for useInfiniteQuery(). Goals are:

• Allow to integrate with common practices (Elastic Search, GraphQL, others?)
• Handle page based navigation
• Handle cursor based navigation

Currently, I have a very simple version that lacks many features:

useInfiniteQuery() (click to expand source code)

export interface UseInfiniteQueryOptions<
  TResult,
  TError,
  TDataInitial extends TResult | undefined = TResult | undefined,
  TPages = unknown,
> extends Omit<UseQueryOptions<TResult, TError, TDataInitial>, 'query'> {
  /**
   * The function that will be called to fetch the data. It **must** be async.
   */
  query: (pages: NoInfer<TPages>, context: UseQueryFnContext) => Promise<TResult>
  initialPage: TPages | (() => TPages)
  merge: (result: NoInfer<TPages>, current: NoInfer<TResult>) => NoInfer<TPages>
}

export function useInfiniteQuery<TResult, TError = ErrorDefault, TPage = unknown>(
  options: UseInfiniteQueryOptions<TResult, TError, never, TPage>,
) {
  let pages: TPage = toValue(options.initialPage)

  const { refetch, refresh, ...query } = useQuery<TPage, TError, never>({
    ...options,
    // since we hijack the query function and augment the data, we cannot refetch the data
    // like usual
    staleTime: Infinity,
    async query(context) {
      const data: TResult = await options.query(pages, context)
      return (pages = options.merge(pages, data))
    },
  })

  return {
    ...query,
    loadMore: () => refetch(),
  }
}

It's lacking:

• per page caching: this means no invalidation per page, no way to refetch everything again)
• bi directional navigation: this version only has a loadMore() that works with infinite scrolling

By allowing a low level merge function, we can fully control the format of the data and we can end up with just a collection that we iterate on the client. We need initialPage to make types inferrable in merge since it's both the parameter and return type. Here is full example of it's usage with scroll:

<script setup lang="ts">
// import { factsApi, type CatFacts } from '@/composables/infinite-query'
import { useInfiniteQuery } from '@pinia/colada'
import { onWatcherCleanup, useTemplateRef, watch } from 'vue'
import { mande } from 'mande'

export interface CatFacts {
  current_page: number
  data: Array<{ fact: string, length: number }>
  first_page_url: string
  from: number
  last_page: number
  last_page_url: string
  links: Array<{
    url: string | null
    label: string
    active: boolean
  }>
  next_page_url: string | null
  path: string
  per_page: number
  prev_page_url: string | null
  to: number
  total: number
}

const factsApi = mande('https://catfact.ninja/facts')

const {
  state: facts,
  loadMore,
  asyncStatus,
  isDelaying,
} = useInfiniteQuery({
  key: ['feed'],
  query: async ({ nextPage }) =>
    nextPage != null ? factsApi.get<CatFacts>({ query: { page: nextPage, limit: 10 } }) : null,
  initialPage: {
    data: new Set<string>(),
    // null for no more pages
    nextPage: 1 as number | null,
  },
  merge(pages, newFacts) {
    // no more pages
    if (!newFacts) return pages
    // ensure we have unique entries even during HMR
    const data = new Set([...pages.data, ...newFacts.data.map((d) => d.fact)])
    return {
      data,
      nextPage: newFacts.next_page_url ? newFacts.current_page + 1 : null,
    }
  },
  // plugins
  retry: 0,
  delay: 0,
})

const loadMoreEl = useTemplateRef('load-more')

watch(loadMoreEl, (el) => {
  if (el) {
    const observer = new IntersectionObserver(
      (entries) => {
        if (entries[0]?.isIntersecting) {
          loadMore()
        }
      },
      {
        rootMargin: '300px',
        threshold: [0],
      },
    )
    observer.observe(el)
    onWatcherCleanup(() => {
      observer.disconnect()
    })
  }
})
</script>

<template>
  <div>
    <button :disabled="asyncStatus === 'loading' || isDelaying" @click="loadMore()">
      Load more (or scroll down)
    </button>
    <template v-if="facts?.data">
      <p>We have loaded {{ facts.data.data.size }} facts</p>
      <details>
        <summary>Show raw</summary>
        <pre>{{ facts }}</pre>
      </details>

      <blockquote v-for="fact in facts.data.data">
        {{ fact }}
      </blockquote>

      <p v-if="facts.data.nextPage" ref="load-more">Loading more...</p>
    </template>
  </div>
</template>

You can run this example locally with pnpm run play and visiting http://localhost:5173/cat-facts

---

I'm looking for feedback of existing needs in terms of caching and data access to implement a more feature-complete useInfiniteQuery()

[unnoq]

I’m trying to add support for useInfiniteQuery in oRPC, and I have a few questions after reviewing your useInfiniteQuery code:

1. Why does the async query function return pages instead of data?
2. Why is the merge function's return type NoInfer<TPages> instead of NoInfer<TResult>?
3. How do I control fetching the next page?

Looking forward to your insights!

[posva]

I'm still collecting feedback on this method. I'm sure it will change a lot in the near future so I would recommend not to support it yet.

Currently the approach is to let the user merge the data, but I realized it might be better to still keep an internal representation of the pages, that's why you see different types. loadMare() loads the next page

[lewebsimple]

Could it be done with a middleware like transformData(newState, prevState) that would be applied after the query resolves a new state, in which we could do something like:

transformData: (newState, prevState) => {
  const { items, page, ...rest } = newState;
  if (page === 1) return newState;
  return {
    items: [ ...prevState.items, ...items ],
    page,
    ...rest,
  };
}

Although a specific API for infinite scrolling with helpers like loadMore and canLoadMore is really nice.

[posva]

@lewebsimple Isn't that exactly what the current useInfiniteQuery() does? To me it still feels a bit limited, so I exposed it as experimental to get more feedback on it 😄

[lewebsimple]

@lewebsimple Isn't that exactly what the current useInfiniteQuery() does? To me it still feels a bit limited, so I exposed it as experimental to get more feedback on it 😄

I meant adding this middleware to useQuery itself without the need for a separate useInfiniteQuery. I guess there are some complexities with handling the cache that could be encapsulated in a specialized function.

Nonetheless, as @unnoq stated, I think the concepts of TResult and TPages deserve better documentation. From what I understand, your approach decouples the result of query from the page data it needs to handle the infinite scroll, whereas my original comment implied the query would need to return the page data in the result itself, which in turn would be made available in the middleware for merging based on prevResult / newResult. It's a bit more general my way, but the users are responsible of handling the load more stuff themselves.

[posva]

Oh I see what you mean! You could indeed transform the data before returning it in query but it would lack the other methods (as you noted)

[Butch78]

I'm loving the implementation of this so far, but do you think it could be extendable to include query parameters, E.g catBreed, catAge?

<script setup lang="ts">
import { useInfiniteQuery } from '@pinia/colada'
import { onWatcherCleanup, useTemplateRef, watch, reactive } from 'vue'
import { mande } from 'mande'

export interface CatFacts {
  current_page: number
  data: Array<{ fact: string, length: number }>
  first_page_url: string
  from: number
  last_page: number
  last_page_url: string
  links: Array<{
    url: string | null
    label: string
    active: boolean
  }>
  next_page_url: string | null
  path: string
  per_page: number
  prev_page_url: string | null
  to: number
  total: number
}

const factsApi = mande('https://catfact.ninja/facts')

const queryParams = reactive({
  catBreed: 'Aegean', // Default value, modify as needed
  catAge: 5
  limit: 10,
})

const {
  state: facts,
  loadMore,
  asyncStatus,
  isDelaying,
} = useInfiniteQuery({
  key: ['feed', queryParams],
  query: async ({ nextPage }) =>
    nextPage != null
      ? factsApi.get<CatFacts>({ query: { ...queryParams, page: nextPage } })
      : null,
  initialPage: {
    data: new Set<string>(),
    nextPage: 1 as number | null,
  },
  merge(pages, newFacts) {
    if (!newFacts) return pages
    const data = new Set([...pages.data, ...newFacts.data.map((d) => d.fact)])
    return {
      data,
      nextPage: newFacts.next_page_url ? newFacts.current_page + 1 : null,
    }
  },
  retry: 0,
  delay: 0,
})

const loadMoreEl = useTemplateRef('load-more')

watch(loadMoreEl, (el) => {
  if (el) {
    const observer = new IntersectionObserver(
      (entries) => {
        if (entries[0]?.isIntersecting) {
          loadMore()
        }
      },
      {
        rootMargin: '300px',
        threshold: [0],
      },
    )
    observer.observe(el)
    onWatcherCleanup(() => {
      observer.disconnect()
    })
  }
})
</script>

<template>
  <div>
    <label>
      Cat Breed:
      <input v-model="queryParams.catBreed" placeholder="Enter breed" />
    </label>
    <button :disabled="asyncStatus === 'loading' || isDelaying" @click="loadMore()">
      Load more (or scroll down)
    </button>
    <template v-if="facts?.data">
      <p>We have loaded {{ facts.data.data.size }} facts</p>
      <details>
        <summary>Show raw</summary>
        <pre>{{ facts }}</pre>
      </details>
      <blockquote v-for="fact in facts.data.data">
        {{ fact }}
      </blockquote>
      <p v-if="facts.data.nextPage" ref="load-more">Loading more...</p>
    </template>
  </div>
</template>

I'm working on creating a Nuxt project that is a Job board and this would make searching through all my JobPosting so much easier :)

[posva]

@Butch78 doesn't that work already if you pass a function to key: key: () => ['feed', queryParams]?

[Butch78]

Good point, I like your logic much more! And thanks for everything you do for the Vue ecosystem!